Skip to content

njdaniel/conch / .claude/skills/schema-change

schema-change

Verified

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

FileKindSize
SKILL.mdskill md2.1 KB
---
name: schema-change
description: Procedure 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.v1` stays; add `foo.v2`. **Requires Nick's sign-off — get it on the issue before writing code.**

## Procedure

1. Confirm the issue covers this change and (if breaking) has Nick's sign-off recorded on it.
2. 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.
3. 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.
4. Run `./scripts/schema-compat.sh` and `go test ./pkg/schema/...` — both must pass.
5. **Sync consumers in the same PR:**
   - MCP tool input/output definitions in `internal/server` that reference the changed shapes.
   - Any REST/WS handler docs.
   - `docs/design/approval-object.md` if approval shapes changed.
6. 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).
7. PR: reference the issue, label `area/schema`, and add `approval-path` if 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.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall