---
name: agh-contract-codegen-coship
description: Contract co-ship for AGH wire changes. Use when editing public DTOs, OpenAPI, JSON-RPC extension shapes, generated clients, or handler request/response semantics. Do not use for internal Go refactors or test-only changes that leave the wire contract unchanged.
trigger: implicit
---
# Contract Codegen Co-Ship
Ship one atomic wire-contract bundle. This file owns the sequence;
`references/coship-checklist.md` owns the inventory.
## Procedures
**Step 1: Detect the Trigger**
1. Inspect the staged or about-to-be-edited files. Triggers (any one match):
- `internal/api/contract/**.go`
- `internal/api/spec/**.go`
- `openapi/agh.json`
- `openapi/compozy-daemon.json`
- `web/src/generated/**`
- a public handler's request, response, status, authentication, or error shape changes even before a contract file is edited
2. If no path or semantic trigger fires, this skill does not apply.
*Done when:* every changed wire shape and owning source is named, or the skill is explicitly ruled out with evidence.
**Step 2: Plan the Co-Ship Bundle**
1. Read `.agents/skills/agh/agh-contract-codegen-coship/references/coship-checklist.md` in full.
2. Mark every applicable source, generated, backend, Web, site, CLI, UDS, native-tool, extension, config, QA, and official-skill item before editing.
3. Record explicit no-impact evidence for checklist branches that do not apply.
*Done when:* every applicable checklist item has one owning file or verification command and no public surface is left implicit.
**Step 3: Run Codegen Locally**
1. Execute `make codegen` from the repo root. This regenerates `openapi/agh.json` and `web/src/generated/agh-openapi.d.ts`.
2. If the contract is a JSON-RPC extension shape (not REST), the Go→TS generator also runs through `make codegen` (see `internal/codegen/openapits/generate.go`).
3. Inspect the generated diff. Generated files MUST commit alongside source.
*Done when:* generated artifacts are deterministic, reviewed, and synchronized with their owning source.
**Step 4: Update Web Consumers**
1. For each affected `web/src/systems/<system>/`:
- Open `types.ts`. Remove DTOs that simply mirror the regenerated TypeScript types — import from `@/generated/agh-openapi` or the local re-export instead.
- Open `adapters/`. Update the typed wrappers if the request/response shape changed.
- Open `query-keys.ts` and `query-options.ts` if response shape affects keys.
- Open `hooks/`. Update query/mutation hook return types and rollback logic.
- Open `components/`. Update presentational props if exposed shape changed.
2. Update MSW fixtures and Storybook stories to match the new contract.
*Done when:* every affected consumer imports the canonical generated shape and its runtime/test fixtures agree.
**Step 5: Update Site Documentation**
1. CLI verb changes: regenerate `make cli-docs` so `packages/site/content/runtime/cli/` reflects the new flags / commands.
2. HTTP endpoint changes: update `packages/site/content/runtime/<area>/` MDX files and any protocol documentation.
3. Configuration key changes: update `packages/site/content/runtime/configuration/` MDX files.
4. Removed CLI verbs / endpoints / config keys: delete the doc pages in the same change (no "deprecated" markers).
*Done when:* public docs and agent-manageable surfaces describe only the shipped hard-cut contract.
**Step 6: Verify the Bundle**
1. Run `make codegen-check`. Output MUST be clean (no drift).
2. Run `make bun-lint` from the repository root.
3. Run `bunx turbo run typecheck test build --filter=./web` from the repository root when Web consumers are affected.
4. Run `bunx turbo run typecheck test build --filter=./packages/site` from the repository root when site content or generated inputs are affected.
5. Confirm every applicable co-ship checklist item passes.
6. Reserve the single full `make verify` for the completion gate after source freeze.
*Done when:* codegen has no drift, affected Turbo lanes are green, the checklist is complete, and exactly one fresh full monorepo gate is scheduled or complete for the finished task.
## Error Handling
- **`make codegen` shows large diffs unrelated to your change:** something else is out-of-date in the source tree. Investigate before committing — generated drift hides regressions.
- **`make codegen-check` fails after `make codegen`:** there's a non-deterministic generator. Inspect the generator's output ordering, file formatting, JSON normalization. Use semantic JSON comparison and run formatter before write/check (lesson `docs/_memory/analysis/analysis_local_runs.md` issue #6).
- **Web typecheck fails on imported generated type:** the consumer is mirroring instead of importing. Move it to use the generated type and delete the duplicate.
- **`packages/site` build breaks because a documented page references a removed verb:** delete the page; don't add a "see new verb" stub.
- **CI passes locally but fails on a runner:** Linux-race CI parity issue. Reproduce with `act workflow_dispatch -W .github/workflows/ci.yml -j verify --container-architecture linux/amd64`.