# Agh Contract Codegen Coship

> 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.

- Skill: `compozy/agh-contract-codegen-coship` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add compozy/agh-contract-codegen-coship`
- Raw SKILL.md: https://api.skillmd.com/api/skills/compozy/agh-contract-codegen-coship/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: compozy (https://skillmd.com/u/compozy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/compozy/agh-contract-codegen-coship

---


# 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`.