mikeparcewski/wicked-garden / skills/demo
wicked-garden-demo
VerifiedProduct demo domain: plan, record and review a polished demo video. plan — frames the audience, builds the story, picks hero cases and fresh alternates, runs a live rehearsal with measured timings, and writes a presenter script with a chapter list ready for recording. record — records each chapter as its own captioned, chaptered segment via Playwright + ffmpeg (DevTools screencast encoded live to H.264, no frame files on disk, final CRF 17), then stitches them into one MP4 with chapters. review — generates labelled contact sheets of stills (at chapter slides, joins, and the end) and delivers a per-issue verdict: re-encode, re-record one segment, or fix the app. Use when: "plan a demo", "demo script", "presenter notes", "run of show", "rehearse a demo", "record a demo video", "walkthrough video", "feature tour", "re-record a segment", "stitch segments", "review the demo video", "QA the recording", "contact sheet", "demo workflow", "offline demo", "walkthrough storyline", "walkthrough lint", "walkthrough_plan".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.3 KB |
| assets/example-storyline.mjs | script | 7.8 KB |
| refs/gotchas.md | markdown | 8.4 KB |
| refs/rehearsal.md | markdown | 2.9 KB |
| refs/review-checklist.md | markdown | 6.1 KB |
| refs/stage-design.md | markdown | 6.2 KB |
| refs/storyline-api.md | markdown | 9.1 KB |
| refs/storyline-json.md | markdown | 6.1 KB |
| refs/storytelling.md | markdown | 3.3 KB |
| refs/templates.md | markdown | 4.5 KB |
| refs/walkthrough-author.md | markdown | 6.5 KB |
refs/walkthrough-author.md
View on GitHub# Walkthrough author: the `walkthrough_plan` contract
A governed run whose plan holds `walkthrough_plan` + `walkthrough_review` proves the builder's work by
recording it. The `walkthrough_plan` seat (an evaluator: it writes the checks for someone else's work)
writes the storyline; the engine-run record tool films it against a fixture started from the tree under
review and judges every check through the vault. No model judges a check.
## Where the storyline goes
- Exactly one file: `<evidence root>/author/<your step id>/storyline.mjs`. The step prompt names the full
path. The author dir is your only write root; the worktree is not yours to write.
- The step's pinned validator runs
`wicked-garden run scripts/demo/walkthrough.mjs lint --root <author dir>`. It denies the step until the
lint exits 0.
- The record step reads the same file through `WICKED_WALKTHROUGH_AUTHOR` (the author dir the engine hands
it) and re-runs the lint before it records anything: a finding refuses the recording
(`INCONCLUSIVE`, cause `storyline_refused`, the rules in `reason`). Outside a run, pass
`--storyline <path>` to `record` and `lint`.
## Lint rules
`lint` prints `{ok, storyline, chapters, checks, findings: [{rule, where, detail}]}` and exits 0 with no
finding, 1 with any, 2 on a usage error. Each rule id below is what a finding carries.
| Rule | What it requires |
|---|---|
| `storyline_missing` / `storyline_unloadable` | `<author dir>/storyline.mjs` exists and imports, default export an object |
| `base_url` | `baseUrl: "fixture"` — the tool films the fixture it starts, never a live system |
| `fixture_start` | `fixture.start` is an argv of strings; no inline code (`-e`, `-c`, `--eval`, `-p`, `--print`, `--command`); no absolute path or `..`; with `--tree <dir>`, every script-like argument exists in the tree |
| `secret_env` | no `fixture.env` name looks like a credential (`TOKEN`, `SECRET`, `PASSWORD`, `API_KEY`, `PRIVATE_KEY`, `CREDENTIAL`, `AUTH`, ...) |
| `fixture_env` | `fixture.env` does not set `PORT` or `BASE_URL`: the recorder sets both (the fixture runs on a free port) |
| `probe_port` | no probe argv hard-codes a loopback port (`127.0.0.1:<port>`, `localhost:<port>`): read `$BASE_URL` / `$PORT` instead (see Probes below) |
| `segments` | at least one chapter (a non-`intro` segment): an empty plan proves nothing |
| `segment_key` / `segment_run` | keys match `^[a-z0-9][a-z0-9-]*$` and are unique; `run(ctx)` is a function |
| `proves` | every chapter names plan step ids in `proves[]`; with `--steps a,b`, each id is one of them |
| `check_id` / `check_kind` | ids are plain and unique per chapter; `kind` is a collector: `locator`, `probe`, `artifact`, `guard`, `join` |
| `check_selector` / `check_probe` / `check_artifact` / `check_join` | a locator has a `selector`; a probe's `name` is a key of `fixture.probes`; an artifact `path` stays under `DATA_DIR`; a join names two or more earlier checks of its chapter in `sources` |
| `chapter_on_screen` / `chapter_state` / `chapter_cross_check` | each chapter has a `locator` (on_screen), a `probe` or `artifact` (saved state, events, side effects, output) and a `join` whose sources include one of each |
| `must_not_happen` | the walkthrough has at least one `guard` check (no foreign writes, no console errors) |
| `check_verify` | `verify`, when given, is `{kind: "jq_pred", params: {expr}}` and `jq` accepts the expression |
| `negative_missing` / `negative_passes` / `negative_unverified` | every check carries `negative: [...]`, capture-shaped samples its verifier must FAIL on; a verifier that passes a sample is a tautology. Without `jq` the lint fails closed |
A check without `verify` uses the record tool's default: locator `.inner_text != null`, probe
`.raw.exit_code == 0`, artifact `.sha256 != null`, guard no foreign writes and no console errors, join every
source non-null. The verifier reads the capture the tool records: a locator `{inner_text, frame}`, a probe
`{raw: {argv, exit_code, stdout, stderr}, parsed}`, an artifact `{path, sha256}`, a guard
`{foreign_writes, console_errors}`, a join `{joined: {<source id>: value}}`.
## Probes
A probe is an argv the record tool runs with `cwd` = the app (the tree under review) and this
environment on top of its own:
| Variable | Value |
|---|---|
| `DATA_DIR` | the fixture's data directory (the same one the app writes to) |
| `PORT` | the port the record tool started the fixture on — a FREE port, chosen per recording |
| `BASE_URL` | the fixture's origin, `http://127.0.0.1:$PORT` |
Never write the port into the storyline: `fixture.env.PORT` is overridden and a literal
`http://127.0.0.1:4173/...` in a probe reaches nothing (curl exit 7, the chapter FAILs while the app
is right). A probe that reads the app over HTTP expands the variable through a shell or a script:
```
probes: {
charges: ["sh", "-c", "curl -sf \"$BASE_URL/charges\""], // or ["node", "scripts/probe-charges.mjs"] reading process.env.BASE_URL
},
```
## A storyline that passes
```js
export default {
title: "Orders",
baseUrl: "fixture",
fixture: {
start: ["node", "scripts/fixture-server.mjs"], // a script the tree declares
ready: "/ready",
probes: { orders: ["sqlite3", "-json", "data/app.db", "select status, amount from orders"] },
},
segments: [
{
key: "01-pay", title: "Paying an order", proves: ["build"],
checks: [
{ id: "paid_badge", kind: "locator", selector: "#order-1 .status",
verify: { kind: "jq_pred", params: { expr: ".inner_text == \"Paid\"" } },
negative: [{ inner_text: "Pending" }] },
{ id: "paid_row", kind: "probe", name: "orders", parse: "sqlite-json",
verify: { kind: "jq_pred", params: { expr: "[.parsed[] | select(.status == \"paid\")] | length == 1" } },
negative: [{ parsed: [{ status: "paid" }, { status: "paid" }] }] },
{ id: "screen_matches_db", kind: "join", sources: ["paid_badge", "paid_row"],
negative: [{ joined: { paid_badge: "Paid", paid_row: null } }] },
{ id: "nothing_else", kind: "guard",
negative: [{ foreign_writes: ["POST https://api.example.com/charge"], console_errors: [] }] },
],
async run(ctx) {
await ctx.click(ctx.app.getByRole("button", { name: "Pay" }));
await ctx.check("paid_badge");
await ctx.check("paid_row");
await ctx.check("screen_matches_db");
await ctx.check("nothing_else");
},
},
],
};
```
Every check id must be reached by a `ctx.check(id)` in `run`: a check never reached is a FAIL at record time.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |