lanekeeper-contract-change
The safe process for changing a Lanekeeper contract: crates/domain, crates/ports, proto/agent.proto, api/openapi.yaml, db/migrations, docs/mcp-tools.md, perf/budgets.toml or design/handoff. Covers com
SKILL.md.claude/skills/lanekeeper-contract-change/SKILL.md
GitHubChanging a contract
Contracts let parallel agents build against each other without waiting. A change made quietly inside a feature PR breaks every other agent working from the old shape. So a contract changes only through its own PR, labelled contract-change and approved by a human.
Step 0: Is this really a contract change?
- Yes: anything under
crates/domain,crates/ports,proto/,api/openapi.yaml,db/migrations/,docs/mcp-tools.md,perf/budgets.tomlordesign/handoff/. - No: private types and modules inside your own crate. Change those freely.
- Unsure: treat it as a contract change. Splitting a PR costs little; breaking another agent costs a lot.
Step 1: Write the change down first
In your plan, write down the proposed change, why your prompt needs it, and which prompts are affected (table below). Stop and wait for approval when the change removes or renames anything.
| Contract | Prompts that consume it |
|---|---|
crates/domain |
All |
crates/ports |
02, 03a, 03b, 05, 06, 07, 14, 17 |
proto/agent.proto |
02, 03b, 05, 17 |
api/openapi.yaml |
05, 06, 08, 14, plus 03a for auth routes, problems and audit, 03b for events and refs |
db/migrations/ |
03a, 03b, 05, 06, 14, 17 |
docs/mcp-tools.md |
07, 11 |
perf/budgets.toml |
16, plus whoever owns the benchmark |
design/handoff/ |
08 |
Step 2: Make it compatible by default
- Protobuf:
- Add fields; never reuse or renumber them.
- When removing a field, mark its number and name
reserved. - New oneof variants must be ignorable by old readers.
- OpenAPI:
- Additive changes only within a version: new optional fields, new endpoints.
- Every operation keeps
x-required-role. - Afterwards, regenerate the orval client and the MSW mocks in
web/.
- Migrations:
- Always a new file; never edit a merged one.
- Expand, then contract: add the new column or table, backfill, switch readers, and drop the old one only in a later release.
- No destructive DDL in the same release as the code change.
- Keep
lanekeeper_appgrants least-privilege.audit_eventsstays INSERT and SELECT only, with its trigger intact.
- Ports:
- Prefer new methods with sensible defaults over changed signatures.
- Update the in-memory fake and
ports::conformancein the same PR, so every implementation is tested against the new behaviour.
- MCP tools:
- Add tools rather than changing their meaning.
- Every write tool keeps
confirmation: required.
- Budgets: add entries freely. Loosening a threshold needs a human decision recorded in
docs/decisions.md.
Step 3: Regenerate and verify
Run just verify-01, which covers buf lint, redocly lint, the migration and role tests, and port conformance. Then run just verify. Also run the gate of every prompt that consumes the contract and has already merged.
Step 4: Open the PR
- Title it
contract: <what>. - Label it
contract-change. - The body states what changed, why, its compatibility, and the affected prompts.
- Keep it separate from feature code. The feature PR follows, and depends on it.
- After it merges, the owners of the affected prompts need notifying. Leave a note in each of their open plans in
plans/.