← All craftbooks

API Contract Review

Review and QAevalv1.1.0released 2026-07-19workflow: build-loop

Steps

Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.

1. Scope the contract reviewreviewerentry

   map the surface, lock an API design checklist

   Show working prompt

   Step 1: For a whole-project or recurring review, call `map_repo`, `list_file_issues`, and targeted `search_code` queries to locate every implemented API surface: HTTP routes/handlers, OpenAPI/Swagger files, GraphQL SDL/resolvers, RPC/SDK exports, event/webhook contracts, validators, error schemas, and public clients. Record indexed coverage and verify that documented operations map to implementations; for a supplied single contract, scope to it. Step 2: Inventory every endpoint/operation/type with method/path, params, request/response schema, auth, implementation, and known callers. Note whether this is a new API or a change. Step 3: Write an API checklist covering resource naming and method semantics; status codes; consistent errors; pagination/filtering/sorting; auth; versioning/backward compatibility; idempotency; schema/type rigor; and implementation/contract drift. Step 4: State pass conditions and write the surface inventory, coverage limitations, and checklist to `write_task_note` AND `notes/scope.md`. No findings yet.

2. Review the endpointsdeveloper

   check each operation + type against the rules

   Show working prompt

   Step 1: Walk EACH endpoint/operation against the checklist: verify the method matches the action, the path is a sensible resource, the status codes are correct and complete (including error codes), the request/response schemas are precise, and auth is declared. Step 2: Walk EACH type/schema: required vs optional fields are right, enums and formats constrain values, nullability is intentional, and naming is consistent. Step 3: Cross-cut the whole surface for consistency: do all errors share one schema, is pagination uniform, is casing consistent, are similar resources modeled the same way. Step 4: For a CHANGE, diff against the prior contract and flag every breaking change. Step 5: For each finding capture: the operation/type, the rule violated, the impact on a client developer, severity, and the CORRECTED snippet (the fixed YAML/SDL/schema fragment). Good looks like: a finding with a before/after contract snippet, not 'improve error handling'. Stage findings to `write_task_note`. Do not write the report yet.

3. Write the contract reportreviewer

   findings with corrected snippets + compat verdict

   Show working prompt

   Step 1: Open `api-review.md` and write a verdict: Approve / Approve-with-changes / Request-changes, and for a change an explicit Backward-compatible: yes/no. Step 2: Add a '## Breaking changes' section first if any (each with the operation and the corrected approach), then '## Blocking' and '## Non-blocking' findings, each as `operation/type — rule — impact — corrected snippet`. Step 3: Add a '## Consistency' section for cross-cutting issues (error schema, pagination, casing). Step 4: Add a '## Strengths' note on what the contract gets right. Every finding must cite the operation/type and include a concrete corrected snippet — no generic advice. On a loop-back, fix only the named gaps. `write_task_note` the report path, the compatibility verdict, and the count of blocking findings.

4. Evaluatereviewer

   Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

   Show working prompt

   Open `api-review.md` and grade it against the scope checklist. Check EACH criterion and write PASS/FAIL with a one-line reason: (1) every endpoint/operation and type was reviewed; (2) HTTP-method/status-code semantics were checked; (3) error schema, pagination, and naming consistency were assessed across the surface; (4) for a change, backward compatibility is explicitly stated and any breaking change is flagged; (5) each finding includes a concrete corrected contract snippet; (6) findings are prioritized (breaking/blocking/non-blocking); (7) the verdict matches the findings. If any criterion fails, name the exact gap and loop back.
   
   Then route — this is the whole point of the loop:
   
   - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
   - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "report" })` to loop back. The builder fixes exactly those gaps.
   
   Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.

5. Finishdeveloper

   All acceptance criteria met. Stamp a short summary and report DONE.

   Show working prompt

   Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

• api contract review
• review my openapi spec
• review this REST API
• graphql schema review
• is this api backward compatible
• api design review

Toolsets

• [object Object]

Source

View this craftbook on GitHub · MIT license