Create API Contract
Trigger
Use when the user asks for request/response shapes, service boundaries, webhooks, events, auth requirements, pagination, errors, or integration contracts.
When To Use
- After architecture and data model are sufficiently clear.
- Before implementation planning.
- When multiple components or systems must coordinate.
Inputs Inspected
- Architecture plan, data model, PRD, and UX flow.
- Existing API routes, schemas, generated clients, webhooks, and integration docs.
Workflow
- Inspect upstream artifacts and existing route/schema/client/webhook code before defining new interface behavior.
- Identify producers, consumers, auth context, compatibility constraints, versioning expectations, and external provider facts.
- Define endpoints, messages, events, webhooks, request/response shapes, error model, pagination, rate limits, and idempotency where applicable.
- Mark breaking changes explicitly and provide compatibility or migration notes.
- Record unknown provider behavior or missing integration documentation as open questions.
- Validate generated artifacts with
python "${CLAUDE_PLUGIN_ROOT}/scripts/validate-artifact.py" <artifact paths>.
Outputs
.project/docs/engineering/<initiative-id>/api/api-contract.md.project/docs/engineering/<initiative-id>/api/openapi-fragment.yaml when applicable.
Required Sections
- Purpose
- Consumers
- Endpoints Or Messages
- Request Shape
- Response Shape
- Errors
- Auth And Permissions
- Compatibility
- Open Questions
Safety Constraints
- Do not invent external provider behavior.
- Version breaking changes explicitly.
- Include auth, error, and compatibility assumptions.
Related Agents
api-contract-reviewerbackend-engineerfrontend-engineersecurity-reviewer
1---2name: create-api-contract3description: Use to define REST, RPC, GraphQL, webhook, event, service, frontend-backend, or external integration contracts.4---56# Create API Contract78## Trigger910Use when the user asks for request/response shapes, service boundaries, webhooks, events, auth requirements, pagination, errors, or integration contracts.1112## When To Use1314- After architecture and data model are sufficiently clear.15- Before implementation planning.16- When multiple components or systems must coordinate.1718## Inputs Inspected1920- Architecture plan, data model, PRD, and UX flow.21- Existing API routes, schemas, generated clients, webhooks, and integration docs.2223## Workflow24251. Inspect upstream artifacts and existing route/schema/client/webhook code before defining new interface behavior.262. Identify producers, consumers, auth context, compatibility constraints, versioning expectations, and external provider facts.273. Define endpoints, messages, events, webhooks, request/response shapes, error model, pagination, rate limits, and idempotency where applicable.284. Mark breaking changes explicitly and provide compatibility or migration notes.295. Record unknown provider behavior or missing integration documentation as open questions.306. Validate generated artifacts with `python "${CLAUDE_PLUGIN_ROOT}/scripts/validate-artifact.py" <artifact paths>`.3132## Outputs3334- `.project/docs/engineering/<initiative-id>/api/api-contract.md`35- `.project/docs/engineering/<initiative-id>/api/openapi-fragment.yaml` when applicable.3637## Required Sections3839- Purpose40- Consumers41- Endpoints Or Messages42- Request Shape43- Response Shape44- Errors45- Auth And Permissions46- Compatibility47- Open Questions4849## Safety Constraints5051- Do not invent external provider behavior.52- Version breaking changes explicitly.53- Include auth, error, and compatibility assumptions.5455## Related Agents5657- `api-contract-reviewer`58- `backend-engineer`59- `frontend-engineer`60- `security-reviewer`
johnoconnor0