--- name: bump-schema-major description: Cut a new major version of a JSON Schema under `schemas/.v.schema.json` → `.v.schema.json` for a breaking change (removed required field, narrowed enum, type change). Copies the file, applies the breaking diff to v, leaves v in place during the deprecation window, and walks every consumer (skills bodies, `# yaml-language-server: $schema=...` directives, validators, sample payloads) to read both versions or migrate to v. Updates `schemas/README.md` inventory and the package SemVer (major bump). Use only for genuinely breaking changes — additive fields and optional new properties belong in v patch / minor releases. --- # Bump schema major Schema files are versioned in the filename: `.v.schema.json`. Major bumps are reserved for **breaking** changes: - Removing a required field. - Renaming a field without a migration alias. - Narrowing an enum (removing a previously valid value). - Changing a field's type (`string` → `array`). - Tightening `additionalProperties` from `true` to `false` when previously emitted YAML used unknown keys. Anything additive — new optional field, new enum value, new sub-object with `additionalProperties` permissive enough — belongs in the existing `v` and ships as a minor package release. ## Step 0 — Confirm the change is genuinely breaking Use `AskUserQuestion`: - `Yes — fits the breaking-change list above`. - `Maybe — let me describe; you decide`. - `No — it's additive` → exit; this skill doesn't apply. For `Maybe`, prompt for a one-paragraph description and apply the rules above. If the change is additive (new optional field, new enum value), refuse the bump and route the user to the additive-change flow. If clearly breaking, continue. ## Step 1 — Plan the deprecation window Use `AskUserQuestion`: - **Hard cut (no window)**: v deleted in the same release. Pick when v is unreleased or has zero known consumers. - **One-release window**: v stays, v ships, consumers migrate, v deleted next major. Default. - **Indefinite**: v + v coexist forever. Pick only when migration is genuinely impractical (rare). Hard cut + indefinite both skip the dual-read consumer logic in Step 5. The default (one-release window) requires it. ## Step 2 — Catalogue consumers Find every file that references `.v.schema.json`: ```bash grep -rn ".v.schema.json" skills schemas vinta-ai-workflows.mjs README.md CHANGELOG.md ``` Categorise hits: - **`# yaml-language-server: $schema=...`** lines — IDE directives in skill bodies + sample YAML. Update each to point at v when the producer skill writes payloads compliant with v. - **Skill bodies** (`SKILL.md`) describing the schema fields — update language to reflect new contract. - **CLI / runtime references** (`vinta-ai-workflows.mjs`, foundation-skill templates) — update reads and writes. - **CI validation snippets** in `schemas/README.md` — update version reference. Persist this list — Step 5 walks every entry. ## Step 3 — Copy v → v ```bash cp schemas/.v.schema.json schemas/.v.schema.json ``` Edit the copy: - `$id`: change `.v.schema.json` → `.v.schema.json`. - Top-level `description`: append a one-line note pointing at the breaking change. - `properties.schema_version.const`: bump to ``. Do **not** touch v yet. ## Step 4 — Apply the breaking diff to v Make the breaking changes only in v. Document each one in a short comment block at the top of the file (use `description` fields — JSON Schema doesn't support comments, but the top-level `description` field can absorb a multiline string). Validate: ```bash python3 -c "import json; json.load(open('schemas/.v.schema.json'))" ``` Should parse cleanly. If `ajv-cli` is available locally, validate a known-good v payload: ```bash ajv validate -s schemas/.v.schema.json -d /tmp/sample.yaml ``` (Sample payloads usually live next to the schema or inside the consuming skill — find one to use as a regression test.) ## Step 5 — Walk every consumer For each entry from Step 2: ### 5a. `$schema` directives in skill bodies Update to point at v: ```diff -# yaml-language-server: $schema=./node_modules/vinta-ai-workflows/schemas/.v.schema.json +# yaml-language-server: $schema=./node_modules/vinta-ai-workflows/schemas/.v.schema.json ``` Any project that has not migrated yet keeps using v; their existing local files are unaffected. New bootstraps emit v-compatible YAML. ### 5b. Producer skills The skill that writes the YAML payload (e.g. `vinta-bootstrap-ai-tools` Step 0.5 emits `.vinta-ai-workflows.yaml`) must: - Set `schema_version: ` in the emitted payload. - Update sample YAML in the SKILL.md body to v shape. - For any field renamed / removed: ensure the bootstrap interview captures the new field, not the old one. ### 5c. Reader code The CLI (`vinta-ai-workflows.mjs`) and `vinta-sync-ai-tools` skill read these payloads. Update them to: - Accept either `schema_version: ` or `schema_version: ` during the deprecation window. - Translate v payloads to the v in-memory shape (a `migrateVToV(payload)` helper, near where the payload is loaded). - Refuse `schema_version` outside `{, }` with a clear error. If hard cut: only v; refuse v. ### 5d. CI validation `schemas/README.md` documents the validation snippets. Update the example commands to reference v; keep v mentioned as deprecated until the cut. ## Step 6 — Update `schemas/README.md` inventory The README has a per-schema table. Add the v row; mark v as `(deprecated; remove in vX.0)`. ## Step 7 — CHANGELOG entry Major package bump (`X.Y.Z` → `X+1.0.0`). Use `### Changed` and `### Removed` (when hard cut) sections. ```markdown ### Changed - **Schema bump: `` v → v.** . Producers (``) emit v; readers (``) accept both v and v through this release and translate on load. v deletion scheduled for v. Migration: . ### Deprecated - **`.v.schema.json`** — superseded by v. Removal in v. ``` For hard cut: replace `### Deprecated` with `### Removed`, and the consumer-acceptance language with "v is no longer accepted". ## Step 8 — `package.json.version` major bump Hand off to [release](../release/SKILL.md) — pick `major`. Schema breaks always major. ## Verification 1. Both schema files exist + parse: `python3 -c "import json; [json.load(open(f'schemas/.v{n}.schema.json')) for n in (, )]"`. 2. `grep -rn ".v.schema.json" skills` returns only intentional dual-read sites + the deprecation note in `schemas/README.md`. 3. `grep -rn ".v.schema.json" skills` returns every producer skill's `$schema` directive + the new READMEs row. 4. A known-good v payload validated under v still parses (backward integrity). 5. A known-good v payload validated under v parses cleanly. 6. The CLI (or sync skill) loaded against a v payload still works (translation layer present). 7. CHANGELOG entry under the major-bump section, both `### Changed` and `### Deprecated` (or `### Removed`) populated. ## Pitfalls - **Bumping major for a non-breaking change.** Adds noise to consumers. Use minor for additive fields, even ones that look "big". - **Forgetting the `properties.schema_version.const` bump.** v file still claims to be v — every payload validator instantly mis-routes. - **Skipping the translation layer.** Dual-read consumers must actually translate v → v in memory, not just accept v and pass it through. Otherwise downstream code fails on missing fields. - **Updating `$schema` directives without bumping the producer's emitted `schema_version`.** YAML claims v, IDE validates against v → IDE errors on every file. Keep the two in lockstep. - **Forgetting `schemas/README.md`.** Inventory drift; future agents reading the README don't know v exists. - **Hard-cutting v on the same release as v ships.** Guarantees breakage for any project mid-bootstrap. Default is a one-release window. - **Doing this without consensus.** A schema major affects every consumer of the package. Confirm with the team before starting; an undo is itself a major bump.