# Demo Forge

> 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.

- Skill: `manutej/demo-forge` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add manutej/demo-forge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/manutej/demo-forge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: manutej (https://skillmd.com/u/manutej)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/manutej/demo-forge

---


# 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)

1. **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.
2. **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).
3. **The buyer ACTS.** Clicks, calls, types — watching is not touching. Enacts THEIR step, not a vertical stereotype.
4. **Offline single file.** Loads with no wifi in the room; everything embedded.
5. **Plain language.** No hype, no internal machinery surfaced.
6. **One-directional flow.** Data enters only via SYNTHESIS; never copy numbers artifact-to-artifact.

## Checkable predicates (H6 — machine/eye-verifiable, all true before ship)

- [ ] Opens offline as a single file (or self-contained folder ≤2MB); zero console errors.
- [ ] Renders clean at 380px width; passes design-rigor QA ladder.
- [ ] The buyer performs an action; seconds-to-payoff ≤40s and instrumented in the plan.
- [ ] Every datum in `DEMO_DATA.md` tagged real-cited or "illustrative"; none invented-as-theirs.
- [ ] `rehearsal-log.md` shows the run-of-show executed end-to-end with stutters fixed.
- [ ] Live-channel demos embed a fallback recording (always).
- [ ] Form's acceptance checklist in `references/demo-specs.md` fully passed.

## 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).