api-first-workflow

API-First Workflow

Note on API types: This workflow applies to all API types — the contract format and backward-compat tool differ by type. In v1, two types are implemented:

• HTTP/REST — contract = OpenAPI spec file; compat check = oasdiff; see references/http-tooling.md
• Plugin interfaces (Claude/OpenCode skills) — contract = SKILL.md frontmatter (name + description); compat check = frontmatter diff script; see references/plugin-tooling.md

When DB, queue, gRPC, or code interface skills are added (v1.1+), they each provide a {type}-tooling.md reference. The core steps remain identical.

Steps 0–6 (in order — no skipping)

Step 0 — Identify the module boundary and agent usability

Before touching any code or spec:

• Which module owns this change?
• Is data ownership respected? (each module owns its persistent state; others access via API, never direct DB)
• Is dependency direction respected? (no new cycles; no reverse dependencies)
• Agent usability check: if an AI agent is (or will become) a consumer of this API, can they call it without trial and error? The answer must be yes from the first commit — not "we will improve it later."

REQUIRED SUB-SKILL: api-first:module-boundaries SOFT REFERENCE: modularity:balanced-coupling — full three-dimensional coupling model if installed

---

Step 1 — Edit the contract

Before any implementation code:

• For HTTP: edit the OpenAPI spec (api/{service}/v1.yaml), bump info.version
• For plugin interfaces: edit the SKILL.md frontmatter (name, description) — this IS the contract; write frontmatter before writing skill body

REQUIRED SUB-SKILL: api-first:api-design (for HTTP) See references/plugin-tooling.md (for plugin interfaces)

---

Step 2 — Check backward compatibility

• For HTTP: run oasdiff against the previous spec version — see references/http-tooling.md for exact commands
• For plugin interfaces: run the frontmatter compat script — see references/plugin-tooling.md

On breaking change in a stable (v1+) API:

1. Try expand-contract first — add new alongside old
2. If unavoidable: create v2.yaml (HTTP) or bump the plugin's major version

REQUIRED SUB-SKILL: api-first:api-versioning (on breaking change or version decision)

---

Step 3 — Implement to match the contract

Apply TDD:

1. Write the failing test against the spec
2. Watch it fail
3. Write minimal implementation to make it pass

Never implement first, then write the test. The test is the spec's executable form.

---

Step 4 — Run the test pyramid

All four layers must pass (Layer 4 is conditional on the framework) plus the custom agent-friendliness suite before proceeding.

REQUIRED SUB-SKILL: api-first:api-testing

---

Step 5 — Update docs/agent-integration.md

Ships in the same commit as the API change. See references/agent-integration-format.md for the required format, the intent→endpoint table, and the token lifecycle section.

Update triggers: new endpoint, behaviour change, auth/rate-limit/error-format change, idempotency strategy change.

---

Step 6 — Commit contract + code + docs together

Verify before committing: all tests pass, no regressions, staged files include the spec change, the implementation, the docs update, and any regenerated client files.

One commit — not three.

---

Engineering boundaries

Non-negotiable:

• Contract edited before any implementation code
• Module boundaries respected
• Backward compat on v1+ APIs
• Agent-friendly design rules (x-agent-* extensions, resolvable errors, documented intent) applied from the first commit
• Steps 0–6 in order

Ask first:

• Changes to existing contracts
• Cross-module dependencies in a new direction
• Exceptions to agent-friendly design rules (must be justified in writing)

Never:

• Code before contract edit
• Direct DB access from another module
• Breaking change on minor bump
• Spec update at the end
• Designing endpoints for "documentation readers" only while ignoring agent consumers

---

Red flags — STOP

If you catch yourself thinking any of these, stop and re-read this skill:

• "The spec is obvious from the code, I'll update it at the end"
• "This is a tiny change, the contract update is overkill"
• "I'll just reach into the other module's DB, it's faster"
• "This cycle is fine, we're the only consumers"
• "I'll add x-agent-* extensions later when we have agent consumers"
• "The error message is enough — we don't need a conflicting_id"
• "Agents can figure out pagination from the spec"
• "agent-integration.md is just duplicate docs"

---

Anti-patterns

• Writing the handler first then retrofitting the spec
• Adding fields without running the compat check
• Adding a route that reads from another module's internal model
• Shipping endpoints without x-agent-* annotations because "no agents use this yet"
• Designing error responses that only make sense when a human reads logs

---

Recovery: you already wrote code before the spec

If you realize mid-task that you violated Step 1:

1. Stop. Do not commit.
2. Delete the implementation or stash it (git stash).
3. Return to Step 1: edit the spec cleanly, including all agent-friendly annotations.
4. Run Step 2 (compat check).
5. Return to Step 3: re-implement using TDD against the spec. Do not copy-paste from the stash as a shortcut — you will inherit whatever shape the implementation invented, including gaps the spec would have caught.
6. Continue Steps 4–6.

Shortcut: none. The point of the discipline is that the spec shapes the implementation, not the other way around.

---

References

• references/http-tooling.md — oasdiff, client generation, pytest, CI (HTTP/REST)
• references/plugin-tooling.md — frontmatter schema, compat script, Layer 4 validation (plugin interfaces)
• references/agent-integration-format.md — required sections for docs/agent-integration.md