capability-bump

Topics in the source

• Change a structured-output shape
• Step 1 — Decide: does this bump?
• Step 2 — Know which responses are enveloped
• Step 3 — Move all four together
• The worked example — #254
• Step 4 — Verify
• Step 5 — Say so in the PR
• The failure this prevents

config.CapabilitiesVersion is the wire-protocol version every enveloped response carries. Consumers — loop drivers, CI scripts, ynd validate-output — read it to know what they are talking to. .claude/CLAUDE.md states the rule. This skill is how you carry it out, because the rule is a decision and the execution is four files that must move together. Bumps — a consumer must adapt: removing a field renaming a field changing a field's type narrowing a type (string → enum) tightening an enum (removing a member) making an optional field required changing the meaning of an existing value Does not bump — a tolerant consumer is unaffected: adding an optional field adding a member to an open-set enum (consumers MUST tolerate unknowns, per docs/cli-structured.md) adding a whole new schema relaxing a constraint If unsure, treat it as a bump. A needless bump costs a consumer one version check. A missed one breaks them silently. Note the asymmetry: adding an enum member does not bump, removing one does. Open-set enums put the tolerance obligation on the consumer, which only works if the set only ever grows. Most golden responses do not carry capabilities at all. Many commands return a bare array

This is an excerpt. Refer to the complete source and its current requirements.