choism4/oh-my-demo

Oh My Demo

Record the real app in one take. Skip post-production.

Treat this skill as a rehearsal and setup layer around the host application, not as a mock-app generator. Prepare the starting state, operator cues, pacing, declared fixtures, and reset path so the user can press record and finish the walkthrough without cutting around failures afterward. Preserve production UI, navigation, commands, local state, and available business logic. Replace only the smallest slow, expensive, remote, flaky, or unfinished boundary required for a reliable recording.

Default flow

Resolve SKILL_ROOT to the directory containing this file, then run the bundled CLI with python3 "$SKILL_ROOT/scripts/oh_my_demo.py".

1. Inspect the repository, its test harness, existing fixtures, and the exact user-visible path to be recorded. Inspect git status and relevant diffs before changing anything.

2. Create a dedicated branch or isolated worktree. Never put demo-only fixture substitution on the production branch.

3. Initialize the project kit:

   python3 "$SKILL_ROOT/scripts/oh_my_demo.py" init . --name product-tour
   

4. Build a truth ledger in .oh-my-demo/manifest.json. Classify every claim as:

   • real: the visible app exercises its production implementation.
   • simulated: a declared boundary returns deterministic fixture data.
   • operator: recording assistance such as text fill, pacing, or reset; do not include these conveniences in the truth percentage.

5. Keep the weighted real share at or above 80%. Reduce the claim or implement more of the real path when a simulated headline feature would break the budget. Do not manipulate weights to conceal it.

6. Inventory every input, reference, fixture, result, and baseline. Copy demo resources under .oh-my-demo/ or another manifest root rather than binding to an operator's machine-specific absolute paths. For large media, choose Git LFS or a checksum-locked authenticated artifact package and materialize it locally before preflight.

7. Give visible controls stable semantic targets. Prefer accessibility IDs, test IDs, or a host registry over generated CSS selectors or coordinates.

8. Add only the smallest host adapter needed to seed state, restore a baseline, or satisfy the production boundary contract. Keep product-specific nouns out of the reusable manifest runtime.

9. Model the take as state-aware, explicitly triggered stages. Centralize typing intervals, readable loading time, staggered reveals, and viewport refits. Never advance to the next narrated stage without a human trigger.

10. Run diagnostics and fail closed before opening the app:

    python3 "$SKILL_ROOT/scripts/oh_my_demo.py" doctor .
    python3 "$SKILL_ROOT/scripts/oh_my_demo.py" status .
    python3 "$SKILL_ROOT/scripts/oh_my_demo.py" check . --record
    

11. Rehearse through the real visible application at narration speed. Verify pending states, result reveals, accumulated mutations, audio/video linkage, and viewport response before advancing.

12. Reset and repeat the identical take at least twice. Include at least one human-operated pass; automation alone cannot prove that the audience can perceive the behavior.

13. Bind evidence to the exact manifest and validate it:

    python3 "$SKILL_ROOT/scripts/oh_my_demo.py" prove .
    

14. Run a focused production-disabled check. Confirm the demo activation is off by default and normal builds do not silently resolve fixture data.

15. Report three separate lists: real behavior, simulated boundaries, and operator conveniences. File follow-up product work only for simulated product claims, not for demo controls.

Built-in surfaces

Use the CLI as the deterministic spine:

• init: create .oh-my-demo/manifest.json, evidence.json, and fixtures/.
• doctor: diagnose Python, git worktree, branch, manifest, media tooling, and explicit activation.
• status: show the weighted truth budget and simulated boundaries.
• check: preflight branch, baseline revision, assets, hashes, media duration, trailing ranges, rotation metadata, Unicode paths, and fixture linkage.
• prove: require two reset-and-replay passes, one human-visible operator pass, manifest digest binding, and production-disabled isolation.

Use the skill's reasoning to inspect and modify the host app. Do not pretend the CLI can implement framework-specific adapters by itself.

Runtime contract

Keep the reusable action vocabulary small:

focus, set-value, type-text, click, submit, navigate, wait, resolve-fixture, repeat, reset, assert, and invoke-adapter.

Map domain operations to host-owned adapters. A canvas edit, database seed, timeline insertion, mobile gesture, or TUI command remains an invoke-adapter; the host implementation owns its real types and behavior.

For text fields, resolve a declared text target or focused eligible element, reject sensitive fields, focus it, update through the framework's controlled state path when available, and submit only when explicitly requested.

Safety contract

• Require an explicit runtime activation and a dedicated demo branch.
• Require a human trigger for every recorded stage.
• Forbid live publishing, messaging, billing, charging, or other remote side effects from staged flows.
• Never bypass authentication, authorization, model policy, token accounting, signing, or release checks.
• Never fill passwords, tokens, payment data, recovery codes, or secret-like fields.
• Reset only manifest-declared state or a host-owned versioned snapshot. Never target a home directory, repository root, unresolved variable, wildcard, or path outside the declared root.
• Treat a fixture as proof of the consumer path only, never proof that its remote producer works.
• Hide debug chrome only when it is irrelevant to the product claim. Never hide a fact material to what the audience is being told.

Reference routing

Read references/distribution.md when deciding how the skill, CLI, project kit, and host adapters divide responsibility.

Read references/manifest-schema.md when creating or extending .oh-my-demo/manifest.json.

Read references/adapters-and-safety.md before implementing a host adapter, fixture boundary, reset path, or text-field integration.

Read references/rehearsal.md before the first full run, after a failed take, or when a mutation succeeds but is not perceptible.

Read references/evidence-schema.md before claiming the demo is repeatable or filling .oh-my-demo/evidence.json.

Completion gate

Do not call the setup complete until all of the following are true:

• doctor, status, and check pass on the dedicated demo branch;
• the weighted real share is at least 80%;
• every simulated claim has provenance, a narrow injection point, its production equivalent, and a visible assertion;
• reset restores the same initial state twice;
• at least one human-operated rehearsal is perceptible at narration speed;
• prove passes against the final manifest digest;
• demo mode is confirmed disabled in the production path.