prep-major-release

name	prep-major-release
description	Prepare gitgist for a major release — refresh README.md so it stays compelling and advertises the most important features, upgrade the demo renderer (domotion-svg) to the latest version, and review the README demo modes (scripts/demo.mjs) to decide whether the screenshots should change.
allowed-tools	Read, Grep, Glob, Bash, Agent, Edit, Write

A lot has changed since the last release. Get gitgist's front door ready: the README.md (what most people read first) and the animated demo SVGs it embeds. This skill does three things — refresh the README, upgrade the demo renderer (domotion-svg) to the latest version, and review the demo modes — then hands the screenshot capture back to the maintainer.

Scope note: this is the marketing/front-door pass, not a requirements audit. Keep the deep doc-vs-code sync (FR/NFR status, AI summaries, CLAUDE.md) to /check-requirements-against-code; run that first if the docs feel stale. Here, treat docs/3-requirements.md (and its Shipped markers) as the source of truth for what exists to advertise — don't claim a feature the requirements don't back.

Step 1 — Find out what's new since the last release

Establish the gap between the last release and HEAD so you know what to advertise and what might be stale:

git describe --tags --abbrev=0          # the last released tag
git log <last-tag>..HEAD --oneline      # everything since

Also read, to ground the "what shipped" picture:

• docs/3-requirements.md — every FR/NFR and its status marker. New Shipped rows are the candidates for new README copy. (docs/ai/requirements-summary.md is a faster digest of the same.)
• CHANGELOG.md if present, and the current version in package.json.
• The provider roster: PROVIDERS + AUTO_ORDER in src/providers/index.ts, and the flag surface in src/cliArgs.ts (USAGE).

Make a short list of shipped-but-under-advertised features (in the code/docs but thin or absent in the README) and stale claims (README says something the code no longer does, or undersells it — e.g. "on the way" for a provider that has since shipped).

Step 2 — Review and update README.md

Read README.md top to bottom and bring it current. It should stay compelling and skimmable, leading with the strongest hooks. Check each region:

• Headline + one-liner (top): still the sharpest framing of what gitgist does?
• Hero diagram (assets/diagram.svg, via npm run diagram): does its alt text and message still match the pipeline? Note if it needs a re-capture.
• "Why gitgist" bullets: the most important/interesting features, in priority order. Add newly-shipped headline features; drop or merge weak ones. Every bullet must be true per the code/requirements.
• "See it" demos: the embedded SVGs and their captions/alt text — keep in sync with Step 4's decisions.
• Install / Usage / flag table: every flag in src/cliArgs.ts USAGE is in the table, and vice versa; examples reflect real, current syntax.
• AI providers section: the provider list, the auto order prose, and the "Choosing a provider" comparison table all match AUTO_ORDER and the shipped providers. Move any provider that has shipped out of the "on the way" note.
• Library + Development: exported building blocks match src/index.ts; the npm run * list matches package.json scripts.

Make the edits in place. Prefer small, targeted edits over rewrites — preserve the established voice. Don't invent features; if tempted to advertise something, confirm it against the code or a Shipped requirement first. After editing, run npm test (the tests/docs.test.ts meta-tests assert the README/docs stay in sync with the public barrel) — fix any drift the tests flag.

Step 3 — Upgrade the demo renderer (domotion-svg) to latest

Every README visual is captured by domotion-svg — scripts/demo.mjs (npm run demo, the "See it" SVGs) and scripts/diagram.mjs (npm run diagram, the hero diagram) both shell out to its domotion bin. A major release is the moment to get onto the current renderer, since a newer domotion can fix rendering bugs and change the captured output.

Check whether the pinned version is behind and, if so, upgrade it before any visuals get regenerated:

node -p "require('./package.json').devDependencies['domotion-svg']"  # what's pinned
npm view domotion-svg version                                        # latest published

If the latest is newer than the pinned range, upgrade it and refresh the lockfile:

npm install --save-dev domotion-svg@latest   # bumps package.json + package-lock.json

Then confirm the capture scripts still parse against the new version:

node --check scripts/demo.mjs
node --check scripts/diagram.mjs

Notes:

• A renderer upgrade means the visuals should be re-captured even if the demos themselves are unchanged — the SVG output can shift between domotion versions. Flag this in the Step 5 capture checklist so the maintainer re-runs npm run demo and npm run diagram, not just the demos Step 4 touched.
• If domotion's CLI flags or output shape changed in the new version, the capture scripts (scripts/demo.mjs, scripts/lib/terminal.mjs, scripts/diagram.mjs) may need small edits — check its changelog/--help and adjust, keeping the same node --check verification. If the migration is non-trivial, raise it as a FEEDBACK NEEDED note rather than guessing.
• If domotion is already current, say so and skip the upgrade.

Commit the dependency bump (build: upgrade domotion-svg to <version>) so the renderer change is captured as its own coherent unit before the demo work.

Step 4 — Review the demo modes

The README's "See it" SVGs are generated by scripts/demo.mjs (npm run demo). Each entry in its DEMOS array is one demo: a title card (eyebrow / headline / subtitle), a cmd, an optional seed, and a capture that runs the real built CLI. The seeded history lives in the COMMITS array (and seedStaged for the commit-message demo).

Review whether the current set of demos still tells the best story for this release:

• Coverage — do the demos showcase the features the README now leads with? A headline feature with no visual is a candidate for a new demo; a demo for a minor/!defunct path is a candidate to cut. Fewer, stronger demos beat many weak ones — the README currently ships three (AI release notes, commit message, offline).
• Accuracy — do the cmd, title copy, and seeded COMMITS still match how the CLI behaves and what the README claims?
• Freshness — would a different command, flag, or provider better represent the current tool (e.g. a --template demo, or one of the newer providers)?

If changes are warranted, edit scripts/demo.mjs (add/remove/adjust DEMOS entries, title copy, or the seeded commits) and update the corresponding README.md "See it" blocks (image filenames, captions, alt text) to match. Verify the script still parses: node --check scripts/demo.mjs.

Do not run npm run demo yourself to capture the SVGs — the AI demos need the maintainer's signed-in provider, and the ticket owner captures the screenshots. Leave assets/demos/*.svg untouched; your job is to get the script and README ready so a single npm run demo produces the right images.

Step 5 — Hand off for screenshot capture

Summarize for the maintainer so they can capture cleanly:

• README changes made (by region).
• Renderer upgrade: whether domotion-svg was bumped (and to what version), since that forces a full re-capture of every visual.
• Demo decisions: which demos to keep / add / change / cut, and why.
• Capture checklist: the exact commands to run to regenerate visuals — npm run demo for the "See it" SVGs (if Step 4 changed any) and npm run diagram for the hero diagram (if Step 2 flagged it). If Step 3 upgraded domotion-svg, run BOTH regardless — the new renderer can change every SVG. Note which files will change (assets/demos/*.svg, assets/diagram.svg).

If a demo decision needs the maintainer's call before they capture (e.g. "add a --template demo vs. keep three?"), raise it as a FEEDBACK NEEDED note on the ticket rather than guessing, then wait.

Report Format

• What's new since <last-tag> — the shipped features that drove the update.
• README updates — region-by-region list of edits (or "current, no change").
• Demo review — per-demo verdict (keep / add / change / cut) with rationale, and the scripts/demo.mjs / README edits made.
• Capture checklist — the exact npm run demo / npm run diagram commands the maintainer should run, and the files they'll regenerate.
• Open questions — anything raised as FEEDBACK NEEDED.

Filing follow-ups

File a Hot Sheet ticket for anything out of scope for this front-door pass: a feature worth advertising that isn't actually shipped yet (hs-feature), a doc/code discrepancy this surfaced that belongs in the requirements sync (hs-task, cross-reference /check-requirements-against-code), or a demo that needs new tooling to capture (hs-task).