spec-product-demo

spec-product-demo (R4: generate an interactive Demo based on the prototype)

Overview

The goal of R4 is to turn the {FEATURE_DIR}/requirements/prototype.md page list and interaction notes intorunnable and interactiveDemo, used for walkthrough/verification/alignment:

• Single page source: can only come from prototype.md/页面/弹窗清单（P-xxx…）(creating pages on your own is prohibited)
• Shared project mode: by default lands in {REPO_ROOT}/demo/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/
• Skeleton first, details later: first get routing/navigation/jump paths working, then fill in fields/states/validation/error handling
• Data can be mocked: when the backend is not ready, mocking is allowed, but "real data integration" must be treated as an explicit replacement point

At the start, announce:"I am using the spec-product-demo skill to generate an interactive Demo based on prototype.md."

The core value of R4 is "turning wireframes into something clickable and runnable", not replacing design mockups, nor freely adding new requirements in the Demo.

When to use / when not to use

• When to use
  • R3 has been completed, and there is {FEATURE_DIR}/requirements/prototype.md
  • A higher-fidelity walkthrough is needed (usability verification/stakeholder alignment/consistency check of understanding between development and testing)
• Do not use it when
  • spec-context fails → stop immediately
  • {FEATURE_DIR}/requirements/prototype.md is missing → stop and return to using-aisdlc(route to R3:spec-product-prototype）
  • There is no runnable Demo project root directory in the repository, and the user did not provide DEMO_PROJECT_ROOT → stop and require a path to be provided

Inputs / outputs (disk persistence conventions)

• Hard gate input：FEATURE_DIR(must be obtained by spec-context obtained)
• Read
  • {FEATURE_DIR}/requirements/prototype.md(required, SSOT for the page list/interaction notes)
• Optional input
  • DEMO_PROJECT_ROOT: runnable Demo project root directory (has package.json and contains a start script)
• Write
  • Demo code: default {REPO_ROOT}/demo/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/(shared project mode)

Gate (must be passed first, otherwise stop)

1) REQUIRED SUB-SKILL: currently executing spec-context to obtain context, and echo FEATURE_DIR=...(allowing (reuse)）

• spec-context failure → stop
• {FEATURE_DIR}/requirements/prototype.md does not exist → stop(must not "first make a placeholder Demo")

Violating the gate = violating the spirit: no matter "the boss reviews in 10 minutes / make it first and fill it in later / first run a version on main", skipping context and input files is prohibited.

2) Locating the Demo project root directory (must be followed; if not found, stop)

The minimum criteria for determining a "runnable Demo project root directory":

• The directory exists
• contains package.json
• package.json contains at least a start script (for example, dev / start / preview one of them)

Location rules (from high to low):

1. Prefer the input: the user provides DEMO_PROJECT_ROOT → use it as the standard (still must satisfy the runnable criteria)
2. If not provided, search automatically：
   • {REPO_ROOT}/demo/
   • {REPO_ROOT}/prototype/ or {REPO_ROOT}/prototypes/
   • {REPO_ROOT}/apps/demo/、{REPO_ROOT}/packages/demo/
3. Stop if the search fails: None of the above paths exist or satisfy the runnable criteria → Stop R4 and require the user to provide DEMO_PROJECT_ROOT

Hard prohibition: When "no runnable Demo project root directory is found," arbitrarily initializing a new frontend project (Vite/Next.js/CRA, etc.) to "get it running first." This pollutes the repository and breaks process traceability.

Core flow (from prototype to runnable Demo)

0) Fixed output directory: write only to prototypes/{SPEC_NUMBER}-{SHORT_NAME}/

Under DEMO_PROJECT_ROOT create an independent namespace for the current requirement:

• OUTPUT_DIR = {DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/

Rules:

• Requirement implementation must be placed in OUTPUT_DIR: Pages/components/styles/Mock/interaction logic, etc. are all written in OUTPUT_DIR to avoid polluting other requirements
• Minimal glue changes allowed: Minimal changes may be made in the Demo root project to "mount the current requirement" (e.g., route registration, entry menu, shared layout), but modifying other requirements' prototypes/* directories is prohibited
• The directory name must exactly equal {SPEC_NUMBER}-{SHORT_NAME}(handwriting or using another alias is prohibited)

1) From prototype.md generate the page task list (not persisted to disk)

Use prototype.md/页面/弹窗清单 as the sole page source (SSOT):

• Each P-xxx has at least 1 task entry (may be further subdivided)
• Each entry must include:
  • Page route/entry, page goal
  • Main controls/fields and default values
  • Key states (normal/loading/empty/error/no permission) and key points of prompt copy
  • Mapping to task flow nodes (T-xxx) and ACs (reference prototype.md location)

Prohibited: Adding pages not declared in prototype.md such as login pages/settings pages/general layout pages for the sake of "looking more complete." If a new page is needed → return to R3 to update prototype.md before doing R4.

2) Build the skeleton first (must be runnable first)

First complete:

• Route or entry placeholders for all pages/dialogs
• Navigation entries and key jump paths (at least covering the main path of the core task flow)

At this stage it is allowed to:

• Render using only static/Mock data
• Implement only key buttons and jumps (fields/validation may be added later)

3) Then fill in details (by priority)

Fill in according to "core main path first":

• Fields and validation (including key points of error prompts)
• States and exception branches (loading/empty/failure/no permission)
• Interaction details (cancel/back/secondary confirmation/recovery path)

When data dependencies are not ready:

• Use Mock data/Mock API to make interactions runnable
• Treat "real data integration" as an explicit replacement point (avoid treating Mock as the final implementation)

4) Run and smoke test (completion check)

Minimum completion criteria (all are required):

• The Demo project can start
• Can navigate to OUTPUT_DIR page set
• Key paths can be completed (at least covering prototype.md 's core task flow main path)

After completion:Immediately call using-aisdlc route to the next step (usually entering review/return flow, or continuing to subsequent stages).

After completion, output and automatic routing (must be executed)

Demo is written to {DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/ after,mustcomplete the following actions (in order, none may be omitted):

1. output ROUTER_SUMMARY(in YAML form, for Router decision-making):

ROUTER_SUMMARY:
  stage: R4
  artifacts:
    - "{DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/"
  needs_human_review: false
  blocked: false
  block_reason: ""
  notes: "软检查点：Demo 建议走查；如不触发硬中断 Router 可继续自动推进"

1. immediately execute using-aisdlc: pass the above ROUTER_SUMMARY as routing input to using-aisdlc, and the Router will determine the next step andautomatically proceed(no need to wait for the user to say "continue").

   • If the Router determines that it can automatically continue running: continue executing the next worker skill (such as D0, I1, etc.) within the same conversation turn
   • If the Router triggers a hard interrupt: stop and output the blocking reason, required input, and candidate next steps

2. Conversation output: before calling using-aisdlc, you may briefly state "the artifacts for this stage have been written to disk; calling using-aisdlc to route the next step."

Quick reference (quick lookup of high-frequency rules)

• must
  • first execute spec-context to obtain context, and use only its output FEATURE_DIR/REPO_ROOT/SPEC_NUMBER/SHORT_NAME
  • must exist {FEATURE_DIR}/requirements/prototype.md
  • the page list comes only from prototype.md(do not add pages)
  • Demo root directory not found/unrunnable → stop immediately and require DEMO_PROJECT_ROOT
  • requirement implementation is written in {DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/; the Demo root project only makes the minimal glue changes (routing/entry)
• prohibited
  • to force R4 on main (or a non- {num}-{short-name} branch)
  • to use "make a placeholder Demo first" to replace the missing prototype.md
  • to arbitrarily npm create vite@latest / npx create-next-app initialize a new project when the Demo project root directory is not found
  • to invent pages/routes and claim they are "common in demos"

Red-flag checklist (if any one appears: stop and correct)

• without running spec-context start looking for/writing requirements/*.md or the demo directory
• {FEATURE_DIR}/requirements/prototype.md does not exist, yet still want to continue
• the Demo root directory does not exist/is unrunnable, yet still want to "initialize a Vite project first"
• add to the Demo prototype.md pages not defined (login/settings/add pages arbitrarily)
• the output directory is not prototypes/{SPEC_NUMBER}-{SHORT_NAME}(written to the root directory, wrong spec directory name, or written to another requirement directory)

Common excuses and countermeasures (high-frequency points in baseline tests)

Excuse (source of pressure)	Common violation behavior	Required countermeasure action
"The boss wants to see it in 10 minutes, so make a version on main first"	skip spec-context; write the demo on main	if the gate fails, stop: first switch to a legal spec branch and run spec-context; otherwise you may only deliver "blocking reason + required input/next step"
"the prototype has not been written/cannot be found, so just make a placeholder Demo first"	invent pages and flows, resulting in untraceability	prototype.md missing → return to using-aisdlc route to R3; R4 is prohibited from replacing R3's interaction decisions
"there is no demo/ in the repository, so I will initialize a Vite/Next.js project first"	creating a new project in an unknown location pollutes the repository	Stop and require DEMO_PROJECT_ROOT; only allow continuation if a runnable demo project already exists
“By the way, add a login page/settings page, common in demos”	Inventing pages, deviating from the SSOT	Refuse to add pages and loop back to R3: first write the pages into prototype.md 's page list (including numbering, description, AC mapping)

A good example (how to correctly stop when the Demo root directory cannot be found)

When not provided DEMO_PROJECT_ROOT and automatic lookup fails, a conclusion similar to the following should be output:

• Blocking reason: no runnable Demo project root directory was found in the current repository (missing demo/ or missing package.json/startup script)
• Needed from the user:DEMO_PROJECT_ROOT(for example E:\\path\\to\\demo), and state that it must be startable
• Next step: after obtaining DEMO_PROJECT_ROOT , generate the Demo in {DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/ Generate Demo