CLI Forge Demo

Optimization: This skill uses on-demand loading. Heavy content lives in references/ and is loaded only when needed.

Language rule: Skill instructions are English. Detect the project's primary language (README, comments, docs, commits) and generate the demo kit in that language. If bilingual, ask the user.

Diacritics rule: When the chosen output language uses diacritics (French, Spanish, Portuguese, etc.), render them correctly — including on capitals (É, À, Ç, Ô…). Never strip accents to ASCII: write "sécurité" not "securite", "Rôle" not "Role". ASCII-flattened French is a defect, not a style.

Writing style: Favor clarity — short sentences, one idea per sentence, plain words. A metaphor only when it clarifies. Keep one consistent register (impersonal/infinitive for operational docs). Separate narrative prose, meant to make the reader understand, from telegraphic content (tables, commands, checklists) which stays terse for action.

No fabricated output: Never invent command output, console captures, API responses, metrics, or logs. When real output is needed, emit a clearly-marked placeholder (🚧 "replace with a real capture"), never plausible-but-fake text presented as real.

Demo Forge — Reproducible Live-Demo Kit

"A good production is identical every night — not because the actors are lucky, but because the show is scripted, the marks are taped to the floor, and the stage is reset between performances."

Generate everything needed to give the same demo, flawlessly, every time: a staged script, deterministic data, a one-command reset, a backup recording, and the delivery support that best fits the project.

Core Principle — The Theatre

A live demo is a staged performance, not an improvisation. Eight mappings carry the whole skill (full model in references/staging.md):

Input

$ARGUMENTS is one of:

• Project path / repo — the skill reads the project and builds a demo of its golden path.
• Feature or topic — "demo OpenBao secret rotation", "show the audit-trail feature".
• Empty — reads the current project root, detects the headline capability, and asks for intent.

Optional flags: --intent technique|fonctionnel|commercial|pédagogique, --support live|gif|cast|video|interactive (force a support instead of the recommendation).

Workflow

Step 0 — Pick the cell: intent × support

A demo lives at the intersection of who it's for and how it's delivered. Read references/tiers.md for the full matrix and how dramaturgy shifts per cell.

Axis 1 — Intent / audience (ask if not given; do not guess the audience):

Axis 2 — Support — recommend dynamically, let the user force. Detect signals, propose the best compromise, state why, then proceed unless overridden:

Announce the pick like: "CLI tool + README → I'll generate a VHS gif demo (forceable with --support live)."

Step 1 — Reconnaissance

Read the project. Find the one golden path worth demoing: the headline capability, end to end, happy path only. Use the shared reconnaissance brief — read ../shared/recon.md (same model readme and prez use, so all three tell one story). If several candidates, pick the one with the strongest "showstopper" and note the rest as out of scope.

First check the Upstream inputs table below: if cli-forge-resilience already mapped the golden path, or cli-audit-test named the nominal scenario, reuse it instead of re-deriving.

Step 2 — Detect the runner (no imposed .sh)

The demo automation lives in the project's existing tooling. Read references/tooling.md. Detect in this order and emit targets there:

Rule: meet the project where it lives. Never drop a stray demo.sh next to a Makefile.

Step 3 — Forge the script

Read references/dramaturgy.md (frameworks per intent) and references/demo-md-template.md (the skeleton). Write DEMO.md with:

• Cold-open showstopper — the wow result first, before the setup.
• Numbered beats, each with: the exact command, the expected output (so a mismatch is caught instantly), the talk-track (what to say), a timing budget, and a recovery line ("if this errors, say X and cut to the understudy").
• A reset section pointing at the runner target.
• A fallback pointer to the backup recording.

Step 4 — Wire seed + reset + support

• Seed: deterministic, with a fixed seed and fixed clock, kept separate from the app's own seed data. Idempotent.
• Reset: idempotent and fast — re-runnable back-to-back (git reset --hard && git clean -fdx for repos, DB re-seed, down && up for containers, namespace recreate for k8s).
• Support artifact per Step 0:
  • gif/video → a VHS .tape (read references/gif-video.md): sizing, Sleep/Type/Enter, Hide/Show for setup, captions/subtitles for accessibility.
  • interactive → a self-guided walkthrough (read references/interactive.md): teachme/Killercoda/CodeTour-style stepped markdown with copyable commands and a verification per step.
  • cast → asciinema record/convert instructions (agg → GIF, svg-term → SVG for README).

Step 5 — Pre-flight checklist

Always emit a short pre-flight in DEMO.md (read references/staging.md for the full list): notifications off, terminal font size up, aliases loaded, network plan + offline fallback, understudy recording rendered and tested, reset run once to confirm s0.

Step 6 — Quality gate

The 8 boxes below are this skill's post-verification gate; the 3-phase definition-of-done structure (pre → during → post) is canonical in ../shared/done-gate.md. Before delivering, verify:

• Same show every night — seed + clock pinned; two consecutive dry-runs produce identical output
• Reset is idempotent — running it twice lands on the same s0
• Showstopper first — the payoff appears before the setup
• Golden path only — no beat leaves the happy path
• No scene > 76 s — longest uninterrupted beat is under budget
• Understudy ready — a backup recording exists and was tested
• Show, don't tell — the demo shows the running thing; slides (if any) only support
• Runner-native — automation uses the project's tooling, no stray scripts
• Every beat has an expected output and a recovery line

Anti-Patterns

Read references/anti-patterns.md for the 12 named anti-patterns (Demo Gods, Feature Tour, Cold Open, The Monologue, Yak Shaving, Mystery Data, No Exit, Slideware, Cursor Ballet, Login Fumble, Director's Cut, Silent Movie) — detection + fix for each.

Dynamic Handoffs

Rule: Recommend, don't auto-execute.

Rules for the Generator

1. The demo shows; it never tells. If it could be a slide, it's not a demo beat.
2. Reproducible beats impressive. A demo that works every time beats a flashy one that works sometimes.
3. Use the project's runner. Detect make/just/task/npm/ansible/flux/chainsaw before writing any automation. A stray .sh is a smell.
4. Pin the seed and the clock. Non-deterministic data is the most common silent demo killer.
5. Always ship an understudy. Every kit includes a backup recording and an offline plan.
6. Recommend the support, let the user force it. State the pick and the reason; honour --support.
7. Gotchas — read ../gotchas.md before producing output to avoid known mistakes.

Output

Write the kit to docs/demos/<name>/:

docs/demos/<name>/
├── DEMO.md            # the staged script (lines + marks + timing + recovery)
├── PREFLIGHT.md       # the pre-flight checklist  (or a section inside DEMO.md)
├── demo.tape          # VHS tape           (if support = gif/video)
├── walkthrough.md     # self-guided steps  (if support = interactive)
└── (runner targets)   # added to Makefile / justfile / Taskfile / package.json / ansible

Standard paths, zero AI markers, output in the project's language.

Upstream inputs — what to pull into a demo

Before forging, check whether these skills have already produced material the demo should consume. Read, don't re-derive.

Integration with other cli-* skills (downstream)