demo-guide

Codex compatibility note:

• Invoke $skill-name: load the registered .agents/skills/<name>/SKILL.md and execute it with Codex tools; no separate Skill tool or Claude mode switch is needed. Author .claude/**; mirrors are generated.
• Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
• Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Preserve protocol order unless the user approves a deviation. Workflows use $start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence.

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. Inside a workflow run, $start-workflow → Workflow-step mode bounds this rule. [BLOCKING] Before each step or sub-skill call, update todo tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

Quick Summary

Goal: Investigate an in-scope feature end-to-end, then produce a stakeholder-ready, proof-carrying demo guide with real stories and profile-defined canonical identities linked to actual test/executor or approved manual-QC evidence, runnable user flows, domain storage/solution, and honest proof levels — UI-first, with technical cases in the closing appendix — so presenters can show behaviour, explain its data, and never claim unearned proof.

Summary: Read this if nothing else.

• Purpose: MUST ATTENTION investigate before scripting; prove behaviour, user path, storage, and solution with file:line; ALWAYS state blockers instead of inventing missing evidence.
• Main steps (in order): MUST ATTENTION (0) resolve scope → load output + configured spec contract → size S0–S4 → decompose → create todos; (1) clear the six-question gate + write the Understanding Brief; (2) gather five inventories; (3) map/persist canonical identities to actual carriers + classify channels; (4) trace storage/solution; (5) open guide + ledger and accumulate; (6) write four-part cases; (7) compose the task block at the top; (8) assign proof rungs + transparency; (9) validate.
• Case contract: setup + numbered flow + discriminator + domain storage/solution + proof rung/chain. UI cases lead each story; technical cases keep full rigour in the closing appendix.
• Modes and boundaries: feature-or-scope, --context, --output, --lang, --html, --stories, --estimate; only --estimate or an explicit estimation instruction names the estimate target — the demo scope never does; --lang emits a translated copy and --html follows post-approval Artifact flow; a no-front-end project names its primary demo surface; delegates gather read-only input only; secrets are redacted; deferred work is named in the header and chat summary.

Workflow:

1. Resolve Scope, Load Contract, Size & Create Todos — prompt → context → ASK; read the template and configured spec contract; size S0–S4; decompose into story groups; create todos BEFORE the first deep read.
2. Understand the Feature FIRST [BLOCKING] — clear the comprehension bar; use read-only gathering delegates only when needed; write the Understanding Brief.
3. Gather the Five Inventories — discover through docs/project-config.json; record each ladder's landing rung.
4. Map Stories → Cases + Classify the Demo Channel — preserve profile-defined canonical identities and map them to verified test/executor evidence; name gaps and tag every case 🖥️ UI or 🔧 technical; under no-front-end, UI means the declared primary surface (Step 3.1).
5. Trace Domain Storage & Solution — per case, identify persisted/changed data, owner, migration/handler, consuming rule, and file:line evidence.
6. Open the Guide + Ledger, Accumulate — write the spine first; add one block per story group; update the ledger as each lands.
7. Write Each Case — setup → numbered flow → discriminator → domain storage/solution.
8. Compose the Task Block — prepend a copy-paste-ready task at the very top: purpose, overall requirements, ALL acceptance criteria / user stories, authorization requirements, and a bottom-up estimate (effort points + man-days) per SYNC:estimation-framework, sized over the estimate target only — the current changes by default, the target the user names for estimation, or (no change set in scope) the labelled demo scope — never silently the entire feature.
9. Prove — assign the proof rung and write the test-execution transparency note.
10. Validate — pass the gate below before declaring done.