api-spec
API Specification
The interface contract for the system. It runs after technical-spec (the architecture, modules, and data model must already exist in docs/technical-specs/) and before task-breakdown, tech-lead-setups, and lead-review, all of which cite endpoint contracts. The technical specs decide what modules exist and what data they own; this set pins down the exact wire contract a client calls and a server must honor.
Output is a numbered file set under docs/api-specs/, not one monolith (_index.md plus NN-topic.md files), so a single resource or operation is linkable from task cards, stubs, and reviews (e.g. api-specs/03-work-orders.md -> POST /work-orders).
The protocol is already decided in technical-specs/04-tech-stack.md (API style: REST / GraphQL / gRPC / SOAP). Do not re-litigate it; read it, confirm it, and write the contract in that protocol's idiom. The document set's job is identical across protocols (references/contract-format.md); only the surface notation changes (references/contract-format.md).
Two phases: derive the surface from the technical specs, then write the set.
Running project (adopt mode). If the API already runs, document the live surface. Import an existing OpenAPI, schema, proto, or WSDL file if there is one; otherwise read the route, resolver, or service definitions in the code. Derive each operation from what the code does, not from the module definitions. Mark each place where the code and the technical spec disagree as a finding in that operation's file, and list the findings in your report. Do not change the contract here.
Phase 1: Derive the surface
Read the source of truth before writing anything. The api-specs are a projection of the technical specs, not new invention: