wicked-garden-demo
Skill9 starsChanged 7 months agoMITView on GitHub
Product 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.
- Installs packages
In this repository142 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- plugin-json-schemaSkill
- readme-style-guideSkill
- releaseSkill
- scaffoldSkill
- wicked-garden-agentic-agentic-patternsSkill
- wicked-garden-agentic-architectSkill
- wicked-garden-agentic-context-engineeringSkill
- wicked-garden-agentic-frameworksSkill
- wicked-garden-agentic-performance-analystSkill
- wicked-garden-agentic-review-methodologySkill
- wicked-garden-agentic-safety-reviewerSkill
- wicked-garden-agenticSkill
- wicked-garden-agentic-trust-and-safetySkill
- wicked-garden-appsSkill
- wicked-garden-archetypeSkill
- wicked-garden-build-guideSkill
- wicked-garden-classifySkill
- wicked-garden-coreSkill
- wicked-garden-data-engineerSkill
- wicked-garden-dataSkill
- wicked-garden-deliberateSkill
- wicked-garden-domain-coverageSkill
- wicked-garden-domain-extractorSkill
- wicked-garden-domain-modelerSkill
- wicked-garden-domainSkill
- wicked-garden-draftSkill
- wicked-garden-editor-scaffoldSkill
- wicked-garden-engineering-api-documentarianSkill
- wicked-garden-engineering-architectureSkill
- wicked-garden-engineering-backendSkill
- wicked-garden-engineering-debuggingSkill
- wicked-garden-engineering-docsSkill
- wicked-garden-engineering-frontendSkill
- wicked-garden-engineering-integrationSkill
- wicked-garden-engineering-large-scale-migrationSkill
- wicked-garden-engineering-migration-engineerSkill
- wicked-garden-engineering-patchSkill
- wicked-garden-engineeringSkill
- wicked-garden-engineering-solution-architectSkill
- wicked-garden-engineering-system-designSkill
- wicked-garden-engineering-unit-test-qualitySkill
- wicked-garden-governed-workerSkill
- wicked-garden-groundSkill
- wicked-garden-jam-brainstorm-facilitatorSkill
- wicked-garden-jam-councilSkill
- wicked-garden-jamSkill
- wicked-garden-learnSkill
- wicked-garden-mcp-scaffoldSkill
- wicked-garden-mcpSkill
- wicked-garden-mem-captureSkill
- wicked-garden-mem-ingestSkill
- wicked-garden-memSkill
- wicked-garden-personaSkill
- wicked-garden-platform-auditSkill
- wicked-garden-platform-compliance-officerSkill
- wicked-garden-platform-complianceSkill
- wicked-garden-platform-errorsSkill
- wicked-garden-platform-gate-benchmark-rebaselineSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 5 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 33
If none of these is available, or Python 3 is missing, skip the script-backed step, say so, and follow the manual alternative where one is …
- Very specific: line 75
Keep chapters self-contained — each starts from a known page and uses its own cases.
- Distinctive: line 80
Truth first: use scenarios whose expected outcome you know in advance (the finding it should raise, the plan it should produce).
- Distinctive: line 88
Before rehearsing, ensure the demo can be put back exactly as it was:
- Distinctive: line 96
If a reset does not exist, build or request it first — it is the difference between a demo and a one-off.
- Very specific: line 100
Run every chapter the way the UI does it against the real system and log as you go.
- Very specific: line 117
Use the templates in refs/templates.md:
- Distinctive: line 127
Keep the script in sync with rehearsal changes: after any fix lands, update the affected segment and add a
- Very specific: line 190
Write storyline.json (not storyline.mjs) and chapters.json in the plan directory your step prompt names.
- Very specific: line 197
When a governed run hands you the walkthrough_plan step, the storyline is the proof the builder's work is judged by, not a demo.
- Very specific: line 216
Before writing run() bodies, load each page without clicking to confirm every locator:
- Very specific: line 261
A failed take keeps its evidence: When a take fails (an error, or a blocked write), its timeline, a video cut from the master it has, and …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Demo
Plan a chapter-by-chapter demo story, record it chapter by chapter with captions and callouts, then review with contact sheets — three actions, one domain.
Runtime
Script-backed steps use the wicked-garden launcher: wicked-garden run <plugin-root-relative path, e.g. scripts/…> [args]. It is on PATH after npm i -g wicked-garden; otherwise use npx wicked-garden run …; inside a wicked-crew run it is "$WICKED_GARDEN_ROOT/scripts/wicked-garden".
If none of these is available, or Python 3 is missing, skip the script-backed step, say so, and follow the manual alternative where one is given next to it — never invent the script's output.
Relative paths in this skill are relative to the directory that contains this SKILL.md.
Routing
| Action | When | How |
plan | No chapter list yet; first time or after a product change | Inline — follow § plan below |
record | Chapter list and case bank exist; recording or re-recording | Script-backed — wicked-garden run scripts/demo/record.mjs |
review | A recording exists and needs QA | Script-backed — wicked-garden run scripts/demo/contact_sheet.py |
Action: plan
A good demo is a story the audience can follow, told with cases that behave the same way every time, and numbers that were actually measured. Do not write the script before the rehearsal — the script describes what the audience will actually see.
Produces: <product>-demo-script.md and a chapter list ready for the record action.
1. Frame it
Establish and write down:
- Audience: who watches, what they already know, what decision the demo should help them make.
- Pitch: one paragraph — the problem today, what the product does about it, and the guardrail.
- Use case: three sentences a listener could repeat (typical request → what the product does → outcome).
- Capabilities: a flat list of what the product can show. Each capability that matters to this audience becomes a chapter.
2. Build the story
One chapter per capability, ordered so each raises the stakes of the last:
| # | Chapter | Purpose |
| 1 | Triage / landing | "Here is my day": what needs attention, ranked |
| 2 | Core flow, end to end | One clean case from intake to done |
| 3-4 | Hard cases | Messy input, missing information, exceptions |
| 5 | Learning / governance | How the product gets smarter safely |
| 6 | Knowledge / trust | Where the rules come from, how results trace back |
| 7 | 360 view | Everything about one customer or entity |
| 8 | Wrap-up | Audit trail and measured numbers |
Keep chapters self-contained — each starts from a known page and uses its own cases.
Details and caption voice: refs/storytelling.md.
3. Choose the cases
- Truth first: use scenarios whose expected outcome you know in advance (the finding it should raise, the plan it should produce). Seeded or synthetic data with an answer key.
- One hero case per chapter plus fresh alternates (same story, different names and numbers).
- Mark state-consuming chapters (those that analyze, approve, upload, or teach). Prefer read-only.
- Record the case bank as a table: case, story, entity, what it demonstrates, fresh/used, alternates.
4. Make it repeatable
Before rehearsing, ensure the demo can be put back exactly as it was:
- A per-case reset command that rewinds only the named cases.
- A fresh/used listing so the presenter can check readiness in seconds.
- Deterministic data (seeded generation, cached model text).
- A pre-flight checklist: services and URLs, environment/dataset, business date, persona, fresh cases, files, tabs.
- Pre-bake slow steps for live sessions; say so in the script.
If a reset does not exist, build or request it first — it is the difference between a demo and a one-off.
5. Rehearse live
Run every chapter the way the UI does it against the real system and log as you go.
Full procedure: refs/rehearsal.md.
- Time every step (wall clock) and keep the raw numbers.
- Capture what the audience sees: exact labels, counts, the key sentence of each result.
- Log rough edges with the case key; triage each: fix it, script around it, or drop the chapter.
- Reset afterwards and confirm every case is fresh again.
6. Keep claims honest
- Measured means timed in a rehearsal or recording on this system; say where and when.
- Estimate means a manual-baseline guess; label it "estimate, team to validate" every time.
- Say plainly which systems are simulated and that the data is synthetic.
- Show the guardrail every time you show automation: who approved, what was refused and why.
7. Write the presenter script
Use the templates in refs/templates.md:
- The presenter-script template provides the overall document structure (pitch, setup, run of show, case bank, recovery tips, Q&A).
- The segment block template covers each chapter (case, click, say, audience sees, under the hood, speed-up, rough-edge note).
Style: skimmable. Tables and short bullets, exact UI labels in bold, quotes in italics, one idea per line.
8. Keep it in sync, then hand off to record
- Keep the script in sync with rehearsal changes: after any fix lands, update the affected segment and add a Changes since the rehearsal block at the top of the script — what changed, whether it was seen in a browser, and which timings predate it.
- Re-rehearse chapters whose behaviour changed; replace numbers only with new measurements.
For each chapter write:
- Key:
NN-slug(01-dashboard) — stable, used for files and re-recording. - Title: 2-6 words, sentence case.
- Blurb: one sentence that states what the chapter proves.
- Tags: 2-5 capability chips.
- Resets: the cases it changes.
That list becomes the segments array in the storyline file for the record action.
In a crew Demo video run (the plan step)
Your container cannot reach the app, so steps 5 and the checklist's live items change: read the probe/ page summary
(the engine loaded the app's launch page for you) instead of rehearsing live, write storyline.json (not a module)
beside script.md and chapters.json, and reset nothing (the recorder is read-only). The person approves the plan
at the gate; the engine records it. Format: refs/storyline-json.md. For a crew app, the video shows only the
app's own frame, so every target is "in": "content". Keep other chrome out with hide, never with a dismiss click.
Checklist (acceptance gate)
plan is done only when every item is checked:
- Audience, pitch, three-sentence use case written
- Capabilities listed; one chapter each, ordered as a story
- Hero case + fresh alternates per chapter; state-consuming chapters marked
- Per-case reset and fresh/used listing work; pre-flight written
- Every chapter rehearsed live; timings and audience-visible results logged; rough edges triaged
- Script written from the template; measured vs estimate labelled everywhere
- Cases reset and confirmed fresh after rehearsal
- Chapter list ready for recording (keys, titles, blurbs, tags, resets)
Action: record
Turn the chapter list into a captioned, chaptered MP4 that looks produced rather than screen-grabbed.
Requires: Node.js ≥ 20, ffmpeg and ffprobe on PATH (or FFMPEG=/path/to/ffmpeg),
and the web app running and reachable.
Install (once per machine)
wicked-garden run scripts/demo/setup.mjsConfirm: ffmpeg -version and ffprobe -version both work.
Write the storyline
Copy assets/example-storyline.mjs next to your project (e.g. demo/storyline.mjs) and
replace the segments. Keep each segment self-contained: it starts from startPath, resets its
own data in beforeSegment, and never relies on another segment's state.
Full module shape and the ctx API: refs/storyline-api.md.
Visual system (stage layout, captions, callouts, chapter slides, time-lapse): refs/stage-design.md.
Demo author (a crew Demo video run's plan step)
Inside a crew Demo video run you never record: the engine's demo_record step does, on the host, from data.
Write storyline.json (not storyline.mjs) and chapters.json in the plan directory your step prompt names; the
keys match, in order. Read the probe/ page summary first: your container cannot reach the app. Every go path
stays under the app's launch path; text is plain (no HTML). The format, every step and its limits:
refs/storyline-json.md. A take that fails comes back to you with the chapter, the cause and the time.
Walkthrough author (a crew run's walkthrough_plan step)
When a governed run hands you the walkthrough_plan step, the storyline is the proof the builder's work is
judged by, not a demo. Write exactly one file, <author dir>/storyline.mjs — the path your step prompt names
(<evidence root>/author/<your step id>/); write nothing in the worktree. The step's pinned validator lints it:
wicked-garden run scripts/demo/walkthrough.mjs lint --root <author dir> [--tree <worktree>] [--steps <plan step ids>]Exit 0 means no finding; exit 1 prints {ok, storyline, findings: [{rule, where, detail}]} — fix each and lint
again until it exits 0. The rules, in short: baseUrl: "fixture"; fixture.start is an argv starting a script
the tree declares (no -e/-c, nothing outside the tree, no secret-shaped env name); every chapter proves plan
step ids and has a locator check, a probe or artifact check, and a join of the two; the walkthrough has a
guard check; every check carries negative samples its jq_pred verifier FAILS on. The record tool
(walkthrough_review) reads the same file through WICKED_WALKTHROUGH_AUTHOR and re-runs the lint first: a
finding refuses the recording (storyline_refused). Full rules and a passing
example: refs/walkthrough-author.md.
Probe selectors (read-only)
Before writing run() bodies, load each page without clicking to confirm every locator:
wicked-garden run scripts/demo/probe.mjs <baseUrl> /page1 /page2Saves a screenshot and lists headings, sections, buttons with ARIA roles, inputs and links.
Record
wicked-garden run scripts/demo/record.mjs <storyline.mjs> # record missing segments, then stitch
wicked-garden run scripts/demo/record.mjs <storyline.mjs> 03-search # (re)record one segment, restitch
wicked-garden run scripts/demo/record.mjs <storyline.mjs> --all # re-record everything
wicked-garden run scripts/demo/record.mjs <storyline.mjs> --stitch # stitch existing segments only
wicked-garden run scripts/demo/record.mjs <storyline.mjs> --reencode # re-cut from each segment's saved master, restitch
wicked-garden run scripts/demo/record.mjs <storyline.mjs> --list # which segments are recordedOptions: --out <dir> (default demo-video/ next to the storyline), --fixture-origin <origin> (see below).
Environment: FFMPEG, DEMO_BASE_URL, DEMO_HEADFUL=1, DEMO_KEEP_FRAMES=1 (debugging only, see below).
Encoded while it records; no frame files. The screencast is fed to ffmpeg at 30 fps as the take runs and lands
as segments/<key>/capture.mp4, a near-lossless H.264 master (CRF 12, one-second fragments) whose frame k is the
picture at t0 + k/30; the segment video is a cut of that master (opening trim, time-lapsed waits, chapters, CRF 17).
A take leaves about two videos' worth of bytes, not a JPEG per frame (which was ~8 MB/s, ~5 GB per 10-minute take).
A take that is killed still leaves a master that plays up to its last complete second, and the timeline written so
far, so --reencode can cut it. DEMO_KEEP_FRAMES=1 additionally writes every screencast frame to
segments/<key>/frames/ (with timestamps in timeline.json) to look at what the screencast delivered — use it on a
short take only; the master is still what gets cut.
Read-only by default. While it records, the browser sends no writes: every request that is not
GET, HEAD or OPTIONS is aborted, and so is every WebSocket frame the page sends (frames the server pushes
still arrive). The segment fails side_effect_blocked, naming each request. Service workers are blocked
while recording. So a recording can never launch, approve, create or delete anything on the app it films.
Show a control without pressing it.
The one door: --fixture-origin. To film writes, start a disposable app for the demo (a fixture
server, a scratch database) on a loopback port and name its origin, e.g.
--fixture-origin http://127.0.0.1:4310. Writes and page WebSocket frames to exactly that origin (scheme,
host and port) pass; a write to any other origin is still aborted and listed. A non-loopback origin is
refused before recording. Never point it at a live system someone else uses. There is no environment
switch. recording.json records how each stitched segment was recorded (read-only or
fixture-writable), and each segment's guard.json names the origin.
A failed take keeps its evidence. When a take fails (an error, or a blocked write), its timeline,
a video cut from the master it has, and failure.json (the error, any blocked requests,
failed_at_sec) are kept in segments/<key>/failed-<take>/. Nothing of it is left where a stitch could
use it: the segment's old segment.mp4 is deleted, and while any segment's last take failed, --reencode
and --stitch refuse to run (failed_take, or side_effect_blocked for a blocked write). Re-record it
(or remove its directory) first.
Record one segment first, review its stills with the review action, then record the rest.
Restore the app
Reset whatever the recording consumed (run the per-case reset for every segment's resets) so the live demo
starts fresh, and confirm the cases list as fresh again.
Deliverable: <out>/<slug>.mp4 (stitched), chapters.md, timings.json, recording.json, segments/<key>/.
Hard-won failure modes and fixes: refs/gotchas.md.
Before you call it done (acceptance gate)
record is done only when every item is checked:
- Every segment probed read-only, then recorded without errors;
--listshows all recorded. - Stills reviewed: opening slides, each caption against its picture, callouts on target, joins, closing card.
- No caption claims something the video doesn't show; waits are badged; the closing card shows measured numbers.
- Simulated systems and synthetic data are labelled where the audience could mistake them for real.
- Recorded read-only (
recording.jsonsays"readOnly": true), unless the target is disposable. - The app's data is reset afterwards; services you didn't start are still running.
- The MP4 plays from start to end with chapters (
ffprobe -show_chapters <file>).
Action: review
Review a recording by looking at stills, not by watching the whole video. A few targeted contact sheets catch almost every defect in minutes and give exact timestamps to report.
Contact sheets
wicked-garden run scripts/demo/contact_sheet.py <video.mp4> --chapters # ~2 s into every chapter
wicked-garden run scripts/demo/contact_sheet.py <video.mp4> --chapters --offset 8 # first content of each chapter
wicked-garden run scripts/demo/contact_sheet.py <video.mp4> --joins # just before + after every boundary
wicked-garden run scripts/demo/contact_sheet.py <video.mp4> --end # last seconds: closing card held?
wicked-garden run scripts/demo/contact_sheet.py <video.mp4> --every 20 --cols 4 # survey
wicked-garden run scripts/demo/contact_sheet.py <video.mp4> --at 1:02,1:05 # zoom in on a moment
wicked-garden run scripts/demo/contact_sheet.py segments/05/segment.mp4 --every 8 # one segment aloneOptions: --offset (seconds into each chapter, default 2), --join-gap (seconds either side of a boundary for
--joins, default 0.6), --end-span (seconds before the end for --end, default 6), --cols (tiles per row,
default 3), --width (tile width in px, default 640), --out (output PNG; default <video>-sheet.png next to the
video). Full list: wicked-garden run scripts/demo/contact_sheet.py --help.
Also check format: ffprobe -v error -show_entries format=duration:stream=codec_name,width,height,r_frame_rate -show_chapters <video.mp4>.
Review passes (in this order)
- Structure (
--chapters, ffprobe): every chapter present, in order, titled, 1920x1080 H.264. - Joins (
--joins): plain background → next chapter slide, no setup flash. - The end (
--end): closing card present and held for its full duration. - Survey (
--every 20, then--ataround anything odd): caption sync, callouts, cursor, waits, state. - Numbers: timings on the closing card match
timings.jsonand what the app shows.
Full per-item checklist with causes and fixes: refs/review-checklist.md.
Verdicts
Classify every finding before fixing anything:
| Verdict | When | Fix |
| Re-encode | Timing, trimming, speed-up, frame rate, chapter metadata, missing end hold | Rebuild from saved raw capture — no re-recording (--reencode) |
| Re-record one segment | Wrong caption, callout, stale data, wrong persona, unannotated wait | Fix the storyline for that segment, reset its data, record only it, restitch |
| Fix the app | Errors, crashes, stale UI, wrong numbers, confusing copy | Fix and rebuild, then re-record affected segments. Report to the product owner too |
Report findings as: timestamp · chapter · what's wrong · verdict.
Re-review only the changed segments plus the joins on either side, then run --end again.
Deliverable: contact-sheet PNGs + findings table with verdicts.
Checklist (acceptance gate)
review is done only when every item is checked:
- All five review passes run, in order, on the final file.
- Every finding reported as
timestamp · chapter · what's wrong · verdict. - After fixes: changed segments and the joins on either side re-reviewed, and
--endrun again.
References
refs/storytelling.md— chapter design, ordering, metadata (keys, blurbs, tags), caption voice, honest claimsrefs/rehearsal.md— rehearsal procedure: how to drive it, what to log, rough-edge triage, post-rehearsalrefs/templates.md— presenter-script template and per-segment block templaterefs/stage-design.md— the visual system: layout, typography, captions, callouts, chapter slides, time-lapse badgerefs/storyline-api.md— storyline module shape, allctxmethods, rules of thumbrefs/walkthrough-author.md— thewalkthrough_planauthor contract: where the storyline goes, every lint rule, a passing examplerefs/gotchas.md— failure modes and fixes: capture, clicking, scrolling, timing, environmentrefs/review-checklist.md— full QA checklist with symptom → cause → fix → verdict per item
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

