Use with agent-api-contract and profile-api.
1. Locate the source of truth
- Prefer the repo’s existing OpenAPI/AsyncAPI (or GraphQL schema) path.
- If none exists and the API is public, add a contract artifact before coding adapters.
2. Change taxonomy
| Change | Allowed pattern | |--------|-----------------| | Additive (new optional field, new endpoint) | Ship with tests; document examples | | Compatible tighten (more enum values consumers already ignore) | Document; add consumer tests if known | | Breaking (remove/rename field, change type, stricter required) | Version bump or coordinated consumer migration; explicit notes in PR |
3. Catalog alignment
- Map each operation to slice/API tests (and XFN security rows when authz changes).
- Do not claim “documented” behavior that tests do not cover.
4. Review gates
- [ ] Diff of contract reviewed for accidental breaks
- [ ] Error envelope and auth schemes unchanged or intentionally versioned
- [ ] Idempotency documented for retried POSTs
- [ ] agent-tdd owns behavior implementation after the contract draft