spec-product-demo

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

Overview

The goal of R4 is to turn {FEATURE_DIR}/requirements/prototype.md 's page list and interaction description into arunnable, interactiveDemo, used for review/verification/alignment:

• Single source of pages: can only come from prototype.md/页面/弹窗清单（P-xxx…）(inventing pages is prohibited)
• Shared project mode: by default goes to {REPO_ROOT}/demo/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/
• Skeleton first, details later: first get routing/navigation/jump paths working, then add 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 improvising new requirements in the Demo.

When to use / not use

• When to use
  • R3 has been completed, and there exists {FEATURE_DIR}/requirements/prototype.md
  • Need for higher-fidelity review (usability verification/stakeholder alignment/consistency check of R&D and QA understanding)
• Do not use when
  • spec-context fails → stop immediately
  • {FEATURE_DIR}/requirements/prototype.md is missing → stop and go back to using-aidlc(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

Input / Output (persistence conventions)

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

Gates (must be passed first, otherwise stop)

1) REQUIRED SUB-SKILL: currently executing spec-context to get context, and echo back FEATURE_DIR=...(allow (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/run a version on main first", skipping context and input files is prohibited.

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

Minimum criteria for determining a "runnable Demo project root directory":

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

Location rules (from high to low):

1. Prioritize the input: user provides DEMO_PROJECT_ROOT → use it as the standard (still must satisfy the runnable determination)
2. If not provided, automatically search：
   • {REPO_ROOT}/demo/
   • {REPO_ROOT}/prototype/ or {REPO_ROOT}/prototypes/
   • {REPO_ROOT}/apps/demo/、{REPO_ROOT}/packages/demo/
3. Stop if the search fails: If 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 process (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 located 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, common layout), but modifying the prototypes/* directory of other requirements is prohibited
• The directory name must exactly equal {SPEC_NUMBER}-{SHORT_NAME}(handwriting or using another alias is prohibited)

1) Generate a page task checklist from prototype.md (not persisted to disk)

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

• Each P-xxx has at least 1 task item (which may be further subdivided)
• Each item 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 undeclared pages in prototype.md such as login pages/settings pages/common layout pages, etc., in order to "look 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, allowed:

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

3) Then fill in details (by priority)

Complete in order of "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 required):

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

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

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

After the Demo is written to {DEMO_PROJECT_ROOT}/prototypes/{SPEC_NUMBER}-{SHORT_NAME}/ ,you 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-aidlc: pass the above ROUTER_SUMMARY as routing input to using-aidlc, and the Router determines the next step andautomatically advances(no need to wait for the user to say "continue").

   • If the Router determines that automatic continuation is possible: 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, the required input, and candidate next steps

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

Quick reference (quick lookup of high-frequency rules)

• Must
  • first execute spec-context to obtain context, and only use 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/not runnable → 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 minimal glue changes (routing/entry)
• Prohibited
  • forcing R4 on main (or a non- {num}-{short-name} branch)
  • using a "placeholder Demo first" to replace the missing prototype.md
  • when the Demo project root directory is not found, arbitrarily npm create vite@latest / npx create-next-app initializing a new project
  • inventing pages/routes and claiming they are "common in demos"

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

• without running spec-context , starting to look for/write requirements/*.md or the demo directory
• {FEATURE_DIR}/requirements/prototype.md does not exist, yet still wanting to continue
• the Demo root directory does not exist/is not runnable, yet still wanting to "first initialize a Vite project"
• adding in the Demo prototype.md pages not defined (login/settings/arbitrarily adding pages)
• the output directory is not prototypes/{SPEC_NUMBER}-{SHORT_NAME}(writing to the root directory, using the wrong spec directory name, or writing to another requirement directory)

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

Excuse (source of pressure)	Common violations	Required countermeasure actions
"The boss wants to see it in 10 minutes; first make a version on main"	skip spec-context; write the demo on main	If the gate does not pass, stop: first switch to a valid 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 first make a placeholder Demo"	inventing pages and flows, resulting in untraceability	prototype.md missing → return to using-aidlc route to R3; R4 is prohibited from replacing R3's interaction decisions
"There is no demo/ in the repository; I will first initialize a Vite/Next.js project"	creating a new project in an unknown location and polluting the repository	Stop and require DEMO_PROJECT_ROOT; continue only if a runnable demo project already exists
"By the way, add a login page/settings page; it's common in demos"	Creating custom pages deviates from the SSOT	Refuse to add pages and route back to R3: first write the pages into prototype.md 's page list (including numbering, description, AC mapping)

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

When DEMO_PROJECT_ROOT is not provided and automatic search 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)
• User must provide:DEMO_PROJECT_ROOT(for example E:\\path\\to\\demo), and specify 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