spec-product-demo (R4: Generate Interactive Demo from Prototype)

Overview

The goal of R4 is to implement the page list and interaction instructions in

{FEATURE_DIR}/requirements/prototype.md

into a runnable, interactive Demo for walkthrough/validation/alignment:

Single Source of Pages: Only come from
```
prototype.md/Page/Popup List (P-xxx…)
```
(custom pages are prohibited)

Shared Project Mode: Default to

{REPO_ROOT}/demo/prototypes/{CURRENT_BRANCH}/

Skeleton First, Details Later: First get the routing/navigation/jump links working, then add fields/states/validation/error handling
Mockable Data: Mock data is allowed if the backend is not ready, but "real data integration" must be marked as a clear replacement point

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

The core value of R4 is "turn wireframes into clickable, runnable demos", not to replace design drafts, nor to freely add new requirements in the Demo.

When to Use / Not to Use

When to Use
- R3 has been completed, and
```
{FEATURE_DIR}/requirements/prototype.md
```
  exists
- Higher-fidelity walkthrough is needed (usability validation/stakeholder alignment/consistency check between R&D and testing understanding)
Do Not Use
- ```
spec-context
```
  fails → Stop immediately
- ```
{FEATURE_DIR}/requirements/prototype.md
```
  is missing → Stop and return to
  using-aisdlc
  (route to R3:
```
spec-product-prototype
```
  )
- No runnable Demo project root directory exists in the repo, and the user has not provided
```
DEMO_PROJECT_ROOT
```
  → Stop and request the path

Input / Output (Storage Convention)

Mandatory Input:
```
FEATURE_DIR
```
(must be obtained from
```
spec-context
```
)
Read
- ```
{FEATURE_DIR}/requirements/prototype.md
```
  (required, SSOT for page list/interaction instructions)
Optional Input
- ```
DEMO_PROJECT_ROOT
```
  : Runnable Demo project root directory (contains
```
package.json
```
  with at least one start script)
Write
- Demo code: Default to
```
{REPO_ROOT}/demo/prototypes/{CURRENT_BRANCH}/
```
  (shared project mode)

Gatekeepers (Must Pass First, Otherwise Stop)

1) REQUIRED SUB-SKILL: First meet the

spec-context

gatekeeper and echo

FEATURE_DIR=...

(allow

(reuse)

)

```
spec-context
```
fails → Stop
```
{FEATURE_DIR}/requirements/prototype.md
```
does not exist → Stop (do not "create a placeholder Demo first")

Violating gatekeepers = violating the spirit: Regardless of "boss review in 10 minutes / make it first then supplement / run it on main first", skipping context and input files is prohibited.

2) Demo Project Root Directory Location (Must Comply; Stop if Not Found)

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

Directory exists
```
package.json
```
exists
```
package.json
```
contains at least one start script (e.g.,
```
dev
```
/
```
start
```
/
```
preview
```
)

Location rules (from highest to lowest priority):

Prioritize User Input: If user provides
```
DEMO_PROJECT_ROOT
```
→ use it (still must meet runnability criteria)

Auto-search if Not Provided:

```
{REPO_ROOT}/demo/
```

{REPO_ROOT}/prototype/

{REPO_ROOT}/prototypes/

{REPO_ROOT}/apps/demo/

{REPO_ROOT}/packages/demo/

Stop if Search Fails: If none of the above paths exist or meet runnability criteria → Stop R4 and request the user to provide
DEMO_PROJECT_ROOT

Strictly Prohibited: When no runnable Demo project root directory is found, initialize a new frontend project (Vite/Next.js/CRA, etc.) without permission to "get it running first". This will pollute the repo and destroy process traceability.

Core Process (From Prototype to Runnable Demo)

0) Fixed Output Directory: Only write to

prototypes/{CURRENT_BRANCH}/

Create an independent namespace for the current requirement under

DEMO_PROJECT_ROOT

OUTPUT_DIR = {DEMO_PROJECT_ROOT}/prototypes/{CURRENT_BRANCH}/

Rules:

Requirement implementation must be in
OUTPUT_DIR
: Pages/components/styles/Mock/interaction logic, etc., must be written in
```
OUTPUT_DIR
```
to avoid polluting other requirements
Allow minimal glue changes: Minimal changes can be made to the Demo root project to "mount the current requirement" (e.g., route registration, entry menu, general layout), but modifying other requirements'
```
prototypes/*
```
directories is prohibited
Directory name must exactly match
```
CURRENT_BRANCH
```
(handwriting or aliases are prohibited)

1) Generate Page Task List from

prototype.md

(No Storage)

Take

prototype.md/Page/Popup List

as the only page source (SSOT):

At least 1 task entry per
```
P-xxx
```
(can be subdivided)
Each entry must include:
- Page route/entry, page objective
- Main controls/fields and default values
- Key states (normal/loading/empty/error/no permission) and tips copy points
- Mapping to task flow nodes (T-xxx) and AC (reference location in
```
prototype.md
```
  )

Prohibited: Adding pages not declared in

prototype.md

such as login page/settings page/general layout page to "look more complete". To add pages → return to R3 to update

prototype.md

before proceeding with R4.

2) Build the Skeleton First (Must Be Runnable First)

Complete first:

Route or entry placeholders for all pages/popups
Navigation entries and key jump links (at least cover the main core task flow)

This phase allows:

Rendering only with static/Mock data
Only implementing key buttons and jumps (fields/validation can be added later)

3) Fill in Details (By Priority)

Fill in by "core main link first":

Fields and validation (including error prompt points)
States and exception branches (loading/empty/failure/no permission)
Interaction details (cancel/return/secondary confirmation/restore path)

When data dependencies are not ready:

Use Mock data/Mock API to make interactions runnable
Mark "real data integration" as a clear replacement point (avoid treating Mock as final implementation)

4) Run and Smoke Test (Completion Check)

Minimum completion criteria (all required):

Demo project can be started
Can navigate to the page set in
```
OUTPUT_DIR
```
Key links can be traversed (at least cover the main core task flow in
```
prototype.md
```
)

After completion: Return to

using-aisdlc

for next routing (usually enter walkthrough/feedback, or continue to subsequent stages).

Post-Completion Output (For

using-aisdlc

Automatic Progress Reading)

Append the following two paragraphs at the end of the answer (do not omit):

"The artifacts of this phase have been stored. Please return to
```
using-aisdlc
```
for next routing (if no manual gatekeeper is triggered, Router can automatically continue)."
```
ROUTER_SUMMARY
```
:

yaml

ROUTER_SUMMARY:
  stage: R4
  artifacts:
    - "{DEMO_PROJECT_ROOT}/prototypes/{CURRENT_BRANCH}/"
  needs_human_review: true
  blocked: false
  block_reason: ""
  notes: "Demo 建议人工走查；若发现偏差按 R1/R2/R3 回流修订"

Quick Reference (High-Frequency Rules Cheat Sheet)

Must
- Run
```
spec-context
```
  first, only use its output
```
FEATURE_DIR/CURRENT_BRANCH/REPO_ROOT
```
- ```
{FEATURE_DIR}/requirements/prototype.md
```
  must exist
- Page list only comes from
```
prototype.md
```
  (no additional pages)
- If Demo root directory is not found/not runnable → Stop immediately and request
```
DEMO_PROJECT_ROOT
```
- Requirement implementation is written in
```
{DEMO_PROJECT_ROOT}/prototypes/{CURRENT_BRANCH}/
```
  ; only minimal glue changes (route/entry) are allowed in the Demo root project
Prohibited
- Hardcode R4 on main (or non
```
{num}-{short-name}
```
  branches)
- Replace missing
```
prototype.md
```
  with "placeholder Demo first"
- Unauthorized initialization of new projects with
```
npm create vite@latest
```
  /
```
npx create-next-app
```
  when Demo project root directory is not found
- Creating custom pages/routes and claiming "common in demos"

Red Flag List (Stop and Correct if Any Appears)

Starting to look for/write
```
requirements/*.md
```
or demo directories without running
```
spec-context
```
Proceeding even though
```
{FEATURE_DIR}/requirements/prototype.md
```
does not exist
Unauthorized initialization of a Vite/Next.js project when Demo project root directory is not found
Adding pages not defined in
```
prototype.md
```
to the Demo (login/settings/random pages)
Output directory is not
```
prototypes/{CURRENT_BRANCH}
```
(written to root directory, wrong branch name, or other requirement directories)

A Good Example (How to Correctly Stop When Demo Root Directory is Not Found)

When

DEMO_PROJECT_ROOT

is not provided and auto-search fails, output a conclusion similar to:

Block reason: No runnable Demo project root directory found in the current repo (missing
```
demo/
```
or missing
```
package.json
```
/start script)
Need user to provide:
```
DEMO_PROJECT_ROOT
```
(e.g.,
```
E:\\path\\to\\demo
```
), and explain that it must be runnable

Next step: After obtaining

DEMO_PROJECT_ROOT

, generate the Demo in

{DEMO_PROJECT_ROOT}/prototypes/{CURRENT_BRANCH}/

spec-product-demo

NPX Install

Tags

SKILL.md Content (Chinese)

spec-product-demo (R4: Generate Interactive Demo from Prototype)

Overview

When to Use / Not to Use

Input / Output (Storage Convention)

Gatekeepers (Must Pass First, Otherwise Stop)

1) REQUIRED SUB-SKILL: First meet the
`spec-context`
gatekeeper and echo
`FEATURE_DIR=...`
(allow
`(reuse)`
)

2) Demo Project Root Directory Location (Must Comply; Stop if Not Found)

Core Process (From Prototype to Runnable Demo)

0) Fixed Output Directory: Only write to
`prototypes/{CURRENT_BRANCH}/`

1) Generate Page Task List from
`prototype.md`
(No Storage)

2) Build the Skeleton First (Must Be Runnable First)

3) Fill in Details (By Priority)

4) Run and Smoke Test (Completion Check)

Post-Completion Output (For
`using-aisdlc`
Automatic Progress Reading)

Quick Reference (High-Frequency Rules Cheat Sheet)

Red Flag List (Stop and Correct if Any Appears)

A Good Example (How to Correctly Stop When Demo Root Directory is Not Found)

spec-product-demo

NPX Install

Tags

SKILL.md Content (Chinese)

spec-product-demo (R4: Generate Interactive Demo from Prototype)

Overview

When to Use / Not to Use

Input / Output (Storage Convention)

Gatekeepers (Must Pass First, Otherwise Stop)

1) REQUIRED SUB-SKILL: First meet the spec-context gatekeeper and echo FEATURE_DIR=... (allow (reuse))

2) Demo Project Root Directory Location (Must Comply; Stop if Not Found)

Core Process (From Prototype to Runnable Demo)

0) Fixed Output Directory: Only write to prototypes/{CURRENT_BRANCH}/

1) Generate Page Task List from prototype.md (No Storage)

2) Build the Skeleton First (Must Be Runnable First)

3) Fill in Details (By Priority)

4) Run and Smoke Test (Completion Check)

Post-Completion Output (For using-aisdlc Automatic Progress Reading)

Quick Reference (High-Frequency Rules Cheat Sheet)

Red Flag List (Stop and Correct if Any Appears)

A Good Example (How to Correctly Stop When Demo Root Directory is Not Found)

1) REQUIRED SUB-SKILL: First meet the
`spec-context`
gatekeeper and echo
`FEATURE_DIR=...`
(allow
`(reuse)`
)

0) Fixed Output Directory: Only write to
`prototypes/{CURRENT_BRANCH}/`

1) Generate Page Task List from
`prototype.md`
(No Storage)

Post-Completion Output (For
`using-aisdlc`
Automatic Progress Reading)