| name | demo-forge |
| description | Builds the touchable sample that enacts the buyer's own workflow step — an interactive single-file prototype, a ceti-method animated explainer, or a live-channel (phone/chat) demo — so the buyer experiences the offer instead of reading about it, with buildable per-form artifact specs and a rehearsed 3-minute run-of-show. Use when the user says "demo for [prospect]", "build the sample", "prototype they can touch", "demo plan", "show don't tell", or as the 04-demo stage of a factory run. A demo the buyer can call or click beats any document; a generic vertical demo demonstrates nothing. |
Demo-forge — proof they can touch
The demo is the conversion weapon: proof of capability the buyer operates with their own hands. The dashboard proves transparency; the demo proves we can do the thing. It MUST enact the BUYER'S OWN workflow step with the improvement live — the intake that answers instantly, the quote that builds itself, the report that assembles from their categories. A demo of a generic vertical is a screensaver.
Read ../forge/references/design-rigor.md (QA ladder, hybrid palette) and ../forge/references/evidence-rules.md (real cited / sample-labeled data) before building. This skill carries three dense references — read the one your form needs before you write code:
references/form-decision-tree.md — pick the demo form from the tell + buyer context (judgment: H5).references/demo-specs.md — the buildable spec + pass/fail acceptance checklist per form (the centerpiece: H2).references/run-of-show.md — the 3-minute meeting execution template, preflight, misfire recovery, honesty block, capture.
Typed input slots (H1 — fill at intake; UNKNOWN is legal, never invent)
WORKFLOW_STEP: str|UNKNOWN # the buyer's own step to enact. UNKNOWN → use TOP_WEDGE (below).
# mislabel → you demo the wrong pain and the room stays cold.
DEMO_FORM: {workflow-enactment|animated-explainer|live-channel|hybrid}|UNKNOWN
# UNKNOWN → resolve via references/form-decision-tree.md, never default blindly.
TOP_WEDGE: str # highest-provability tell from SYNTHESIS (fallback when WORKFLOW_STEP UNKNOWN).
TOKENS_PATH: path # design/tokens.css — prospect palette leads via --sf-* vars only.
TELLS: path # via 01-research/SYNTHESIS.md (never raw dossiers; one-directional flow).
MEETING_CONTEXT: {in-room|remote|async-link} # + sponsor technical depth {technical|mixed|non-technical}.
# drives form choice AND run-of-show (who operates, fallback tier).
SPONSOR_CHOSE: bool # did the sponsor pick the step? sponsor-chosen beats agent-chosen every time.
Typed outputs (to 04-demo/):
demo.html | demo/ (self-contained, offline, ≤2MB) # the touchable artifact
demo-plan.md # chosen step + why · form rationale · run-of-show · fallback · honesty block
DEMO_DATA.md # every datum labeled: [source · date] real, or "illustrative" sample
rehearsal-log.md # the run-of-show executed end-to-end, stutters fixed, timestamp
Procedure — Frame → Do → Review → Capture (H3)
FRAME. Resolve DEMO_FORM via references/form-decision-tree.md (is the mechanism visible or experiential? is the buyer's step interactive? in-room or remote? sponsor depth?). Pick WORKFLOW_STEP: sponsor's choice if SPONSOR_CHOSE, else TOP_WEDGE. Write one sentence of what the buyer will DO and FEEL ("you send your own inquiry, watch it answered in 40 seconds"). If no real workflow step can be identified from SYNTHESIS, refuse (see H9) — do not invent a plausible-looking one.
DO. Build to the exact spec for your form in references/demo-specs.md — state machine, palette via --sf-* only, before/after framing, perf budget, seconds-to-payoff. Consume TOKENS_PATH so it feels already theirs. Prefer installed skills, degrade to hand-build at the same bar: generative-ui / frontend-design (workflow-enactment), ceti-explainer + motion-media-l2 (animated-explainer), shadcn-concept-page (React-grade). Label sample data "illustrative" as you place it, into DEMO_DATA.md.
REVIEW. Run the form's acceptance checklist in references/demo-specs.md, then the design-rigor QA ladder. Verification ladder (motion-media-l2 style): render check → single-frame/state snapshots → live browser pass. Zero console errors, offline single file, 380px mobile. Then REHEARSE: execute the run-of-show yourself end-to-end (references/run-of-show.md), fix every stutter, log to rehearsal-log.md. An unrehearsed demo does not ship.
CAPTURE. After the meeting, log what the sponsor said verbatim and which beat landed. Mint ≥1 atom to FACTORY/atoms.md (via mint-atoms): a template (a demo form that converted, a run-of-show pattern), a phrase (the landing sentence that moved them — or visibly failed), a tell-pattern the demo exposed. A run that mints no atom did not finish.
Scale-native (H4)
- Reusable demo scaffolds per vertical. The state machine + shell for a form generalizes across prospects in a vertical; only data, palette, and the wedge change. Bank scaffolds as template atoms; new instances fork the scaffold and re-skin.
- Per-client isolation. Each run's data lives in its own
04-demo/DEMO_DATA.md and palette in its own design/tokens.css. Never let one prospect's numbers, names, or palette bleed into another's build. One client's --sf-* values, one client's data — always.
- Batch builds. For a slate of prospects sharing a vertical scaffold, fan out one build subagent per prospect, each with a context-complete packet (scaffold + that client's tokens + that client's SYNTHESIS wedge). Subagents build; they never share data across clients.
Core invariants (H8 — non-negotiable)
- Real or labeled, never invented-as-theirs. Every number/name/logo is either real and cited
[source · date] per evidence-rules.md, or sample data visibly labeled "illustrative." Fabricated client data is a losing demo — refuse it.
- Their palette, tokens only. Surface color comes from
design/tokens.css --sf-* variables; no raw hex in the artifact (so it re-skins per client and stays isolated).
- The buyer ACTS. Clicks, calls, types — watching is not touching. Enacts THEIR step, not a vertical stereotype.
- Offline single file. Loads with no wifi in the room; everything embedded.
- Plain language. No hype, no internal machinery surfaced.
- One-directional flow. Data enters only via SYNTHESIS; never copy numbers artifact-to-artifact.
Checkable predicates (H6 — machine/eye-verifiable, all true before ship)
DONE predicate & refusals (H9)
DONE when: the artifact meets its form spec + acceptance checklist · all checkable predicates pass · demo-plan.md (with honesty block) + DEMO_DATA.md + rehearsal-log.md exist · ≥1 atom minted to FACTORY/atoms.md.
Refuse (state why, offer the fix):
- Generic vertical demos — if it doesn't enact THIS buyer's step, it doesn't ship. Fix: get the sponsor's step or use
TOP_WEDGE.
- Unrehearsed shipping — no
rehearsal-log.md, no ship. Fix: run the run-of-show.
- Fabricated client data — no invented numbers/logos dressed as theirs. Fix: cite it real, or label "illustrative."
Feedback tracing (H10)
On human feedback, trace the miss to its source line, not "be better" (via mint-atoms): wrong step → WORKFLOW_STEP mislabeled or SPONSOR_CHOSE ignored; demo fell flat live → run-of-show beat or form choice (form-decision-tree.md); felt generic → palette/data isolation or wrong wedge; skeptic derailed → honesty block missing. Edit the reference or slot, bump, generalize against 2–3 other instances. Refined input ⇒ regenerate, never hand-patch.
References index
references/form-decision-tree.md — decision nodes + per-leaf rationale and anti-patterns (when each form flops).references/demo-specs.md — buildable spec + acceptance checklist per form (workflow-enactment · animated-explainer · live-channel).references/run-of-show.md — 3-minute arc, roles, preflight, misfire recovery, honesty block, post-demo capture.../forge/references/design-rigor.md · ../forge/references/evidence-rules.md — shared contracts (read-only core pack).
