njdaniel/conch / .claude/skills/schema-change
schema-change
VerifiedProcedure for changing anything in pkg/schema — version bumps, fixture regeneration, compatibility diff, migrations, and MCP tool-definition sync. Use for ANY change to a wire shape, before touching pkg/schema.
schema-change
Published schema versions are immutable (enforced by scripts/schema-compat.sh). This skill is the only sanctioned path for changing wire shapes.
Decide: compatible or breaking?
- Compatible (new optional field, new schema type, doc changes): no version bump. Existing fixtures must not change.
- Breaking (field removed/renamed/retyped, semantics changed, required field added): new version.
foo.v1stays; addfoo.v2. Requires Nick's sign-off — get it on the issue before writing code.
Procedure
- Confirm the issue covers this change and (if breaking) has Nick's sign-off recorded on it.
- Edit
pkg/schema:- Breaking: add the new versioned type alongside the old one. Never edit or delete a published type.
- Update the version registry / type dispatch if one exists.
- Regenerate golden fixtures into
pkg/schema/testdata/:- New fixtures for new versions. Existing fixture files must be byte-identical after regeneration — if one changed, you made a breaking edit to a published version; go back to step 2.
- Run
./scripts/schema-compat.shandgo test ./pkg/schema/...— both must pass. - Sync consumers in the same PR:
- MCP tool input/output definitions in
internal/serverthat reference the changed shapes. - Any REST/WS handler docs.
docs/design/approval-object.mdif approval shapes changed.
- MCP tool input/output definitions in
- If stored data is affected, ship a SQLite migration in the same PR (old rows must remain readable — the server may hold both versions live during transition).
- PR: reference the issue, label
area/schema, and addapproval-pathif approval shapes changed (Nick merges those).
Never
- Mutate a published fixture to make the diff pass.
- Bump a version "while you're in there" without an issue and sign-off.
- Let MCP tool definitions drift from
pkg/schema— same PR, always.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |