using-aisdlc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

using-aisdlc（在 sdlc-dev 中使用 AI SDLC / Spec Pack 流程）

using-aisdlc (Using AI SDLC / Spec Pack Process in sdlc-dev)

概览

Overview

这是一个“导航 + 门禁”型 Skill：用于在 sdlc-dev 的 Spec Pack（

{num}-{short-name}

）流程里，由本 Skill 作为“唯一路由器（Router）”决定下一步要用的 skill，并用硬门禁防止上下文漂移与写错目录。

开始时宣布：「我正在使用 using-aisdlc 技能导航 Spec Pack 流程并执行门禁校验。」

本 Skill 现在同时覆盖两条链路：

需求链路（R0–R4）：

raw.md → solution.md → prd.md → prototype.md → demo/

设计链路（D0–D2，可整体跳过）：

D0 分流 →（可选）D1 research →（未跳过时）D2 RFC

开发链路（I1–I2 + Finish）：

solution/prd/design → implementation/plan.md → 执行实现 → finishing-development

核心原则：

先上下文，再读写：凡读写

{FEATURE_DIR}/requirements/*

、

{FEATURE_DIR}/design/*

、

{FEATURE_DIR}/implementation/*

（或 R4 写 demo）→ 先

spec-context

得到

FEATURE_DIR

（失败就停止）。

一个节点 = 一个 skill = 一个落盘产物：R0/R1/R2/R3/R4 分步执行，禁止“一次性把 PRD+原型+Demo 全做了”。
渐进式披露：先读项目级
```
memory/
```
与相关契约索引；明确处理某个 Spec 后再读写
```
{FEATURE_DIR}/requirements/*
```
。
不确定性不写“待确认问题清单”：统一进入“验证清单”（Owner/截止/信号/动作）。
回流闭环：R3/R4 的验证发现会回流更新 R1/R2/R3（必要时再做 R4）。
实现侧 SSOT：实现阶段以
```
{FEATURE_DIR}/implementation/plan.md
```
作为唯一执行清单与状态 SSOT（checkbox + 审计信息）；执行状态只回写到
```
plan.md
```
。

This is a "Navigation + Guardrail" type Skill: used in the Spec Pack (

{num}-{short-name}

) process of sdlc-dev, this Skill acts as the "only Router" to determine which skill to use next, and uses hard guardrails to prevent context drift and incorrect directory writes.

Announce at the start: "I am using the using-aisdlc skill to navigate the Spec Pack process and perform guardrail checks."

This Skill now covers two main paths:

Demand Path (R0–R4):

raw.md → solution.md → prd.md → prototype.md → demo/

Design Path (D0–D2, can be skipped entirely):

D0 Diversion → (Optional) D1 research → (If not skipped) D2 RFC

Development Path (I1–I2 + Finish):

solution/prd/design → implementation/plan.md → Execute Implementation → finishing-development

Core Principles:

Context first, read/write later: For any read/write operations on
```
{FEATURE_DIR}/requirements/*
```
,
```
{FEATURE_DIR}/design/*
```
,
```
{FEATURE_DIR}/implementation/*
```
(or writing demo in R4) → first run
```
spec-context
```
to get
```
FEATURE_DIR
```
(stop if it fails).
One node = one skill = one persisted artifact: Execute R0/R1/R2/R3/R4 step by step; prohibit "completing PRD + prototype + Demo all at once".
Progressive disclosure: First read project-level
```
memory/
```
and related contract indexes; only read/write
```
{FEATURE_DIR}/requirements/*
```
after clearly handling a specific Spec.
Do not write "to-be-confirmed issue list" for uncertainties: Uniformly enter into a "validation checklist" (Owner/Deadline/Signal/Action).
Closed-loop feedback: Verification findings from R3/R4 will flow back to update R1/R2/R3 (re-run R4 if necessary).
SSOT for implementation phase: During implementation,
```
{FEATURE_DIR}/implementation/plan.md
```
serves as the single source of truth (SSOT) for the execution checklist and status (checkbox + audit information); execution status is only written back to
```
plan.md
```
.

路由契约（唯一权威：下一步只由 using-aisdlc 判定）

Routing Contract (Only Authority: Next Step Determined Solely by using-aisdlc)

本仓库 Spec Pack 场景下，“下一步做什么/是否跳过/走哪条链路”的判断，只有 using-aisdlc 有权做出。
其它技能（R1/R2/R3/R4/D1/D2/I1/I2/Finish）是 worker skill：只负责本阶段门禁 + 产物落盘 + DoD 自检，不得：

在技能内部“自主分流到下一个技能”（例如“完成后自动进入 X”）
在技能内部决定“跳过/不跳过某阶段”的路由结论（最多做防呆校验：不满足前置则停止，并提示回到 using-aisdlc）

**重要补充：Router 允许自动推进。**using-aisdlc 作为 Router，可以在同一轮对话内按门禁串联执行：

spec-context → worker skill →（可选）再次路由

。
worker skill 仍然不得“自己决定下一步”，但可以在结尾提供结构化的产物与状态摘要，方便 Router 判断是否可继续自动推进。

**统一回环输出：**任一 worker skill 完成后，结尾统一输出（两段都要有）：

「本阶段产物已落盘。请回到
```
using-aisdlc
```
进行下一步路由（如未触发人工门禁，Router 可自动续跑）。」
```
ROUTER_SUMMARY
```
（结构化摘要，便于自动路由；建议使用 YAML 形态，字段固定，避免自由文本）：
- ```
stage
```
  : 例如
```
R1
```
  /
```
R2
```
  /
```
D2
```
  /
```
I1
```
  /
```
I2
```
  /
```
Finish
```
- ```
artifacts
```
  : 产物路径数组（可空）
- ```
needs_human_review
```
  :
```
true|false
```
- ```
blocked
```
  :
```
true|false
```
- ```
block_reason
```
  : string（无则空）
- ```
notes
```
  : string（可空）

In the Spec Pack scenario of this repository, the judgment of "what to do next/whether to skip/which path to take" can only be made by using-aisdlc.
Other skills (R1/R2/R3/R4/D1/D2/I1/I2/Finish) are worker skills: they only handle guardrails for their phase, persist artifacts, and perform DoD self-checks. They must not:

"Autonomously divert to the next skill" within the skill (e.g., "automatically proceed to X after completion")
Make routing conclusions like "skip/not skip a phase" within the skill (at most perform foolproof checks: stop if preconditions are not met, and prompt to return to using-aisdlc)

Important Supplement: Router allows auto-advance. As the Router, using-aisdlc can execute in series within the same conversation following guardrails:

spec-context → worker skill → (Optional) re-route

.
Worker skills still cannot "decide the next step on their own", but can provide structured artifact and status summaries at the end to facilitate the Router's judgment on whether to continue auto-advancing.

Unified Loop Output: After any worker skill completes, output the following uniformly (both sections are required):

"The artifact for this phase has been persisted. Please return to
```
using-aisdlc
```
for next-step routing (if no manual guardrail is triggered, the Router can continue automatically)."
```
ROUTER_SUMMARY
```
(structured summary for automatic routing; YAML format is recommended with fixed fields, avoid free text):
- ```
stage
```
  : e.g.,
```
R1
```
  /
```
R2
```
  /
```
D2
```
  /
```
I1
```
  /
```
I2
```
  /
```
Finish
```
- ```
artifacts
```
  : array of artifact paths (can be empty)
- ```
needs_human_review
```
  :
```
true|false
```
- ```
blocked
```
  :
```
true|false
```
- ```
block_reason
```
  : string (empty if none)
- ```
notes
```
  : string (can be empty)

自动推进（Auto-Advance）策略（提升体验与效率）

Auto-Advance Strategy (Improve Experience and Efficiency)

目标：在不牺牲门禁与 SSOT的前提下，把“回到 using-aisdlc”从人工操作变成默认自动行为；只有在确实需要用户介入时才停下。

Goal: Without sacrificing guardrails and SSOT, turn "return to using-aisdlc" from manual operation to default automatic behavior; only stop when user intervention is truly needed.

自动推进的触发条件（满足其一即可）

Trigger Conditions for Auto-Advance (Satisfy Any One)

用户明确表达：“继续 / 下一步 / 按推荐 / 自动推进 / 跑通最短闭环 / 直接带我走流程”
当前对话意图明确且单向：例如用户说“我要出 PRD/原型/Demo/实现计划/开始实现”，且前置产物齐全

上一步 worker skill 的

ROUTER_SUMMARY

标记：

needs_human_review=false

且

blocked=false

User explicitly states: "Continue / Next step / Follow recommendation / Auto-advance / Run through the shortest loop / Take me through the process directly"
Current conversation intent is clear and unidirectional: e.g., user says "I want to create PRD/prototype/Demo/implementation plan/start implementation", and all pre-requisite artifacts are complete

ROUTER_SUMMARY

from the previous worker skill marks:

needs_human_review=false

and

blocked=false

必须停止并交给用户的场景（人工门禁）

Scenarios That Must Stop and Hand Over to the User (Manual Guardrails)

需要用户评审与确认：产物会成为后续阶段的权威输入，且错误代价高
- 典型：
```
solution.md
```
  （尤其是
```
#impact-analysis
```
  ）、
```
prd.md
```
  、
```
prototype.md
```
  、
```
design/design.md
```
  、
```
implementation/plan.md
```
需要用户做路径选择更好：存在多条合理路线，且 Router 仅凭默认策略可能选错
- 典型分流点：是否补 R2/R3/R4；是否进入实现（I1/I2）；D0 是否跳过 design（如用户未给出倾向）
缺关键外部输入：拿不到就无法继续
- 典型：
```
spec-context
```
  失败；R4 找不到
```
DEMO_PROJECT_ROOT
```
  ；worker skill 标记
```
blocked=true
```

例外：如果用户明确要求“按最短闭环直接开发并接受默认决策”，using-aisdlc 可在 D0 依据决策表自动判定是否跳过 design，并自动进入 I1；但在进入 I2（改代码）前，仍应确认用户意图为“开始实现”而非“只产出计划”。

Requires user review and confirmation: The artifact will become the authoritative input for subsequent phases, and the cost of errors is high
- Typical examples:
```
solution.md
```
  (especially
```
#impact-analysis
```
  ),
```
prd.md
```
  ,
```
prototype.md
```
  ,
```
design/design.md
```
  ,
```
implementation/plan.md
```
Better for user to make path choices: Multiple reasonable routes exist, and the Router may choose the wrong one with default strategies alone
- Typical diversion points: Whether to supplement R2/R3/R4; whether to enter implementation (I1/I2); whether to skip design in D0 (if user has not indicated preference)
Missing critical external input: Cannot proceed without it
- Typical examples:
```
spec-context
```
  fails; R4 cannot find
```
DEMO_PROJECT_ROOT
```
  ; worker skill marks
```
blocked=true
```

Exception: If the user explicitly requests "directly develop following the shortest loop and accept default decisions", using-aisdlc can automatically determine whether to skip design in D0 based on the decision table, and automatically enter I1; however, before entering I2 (modifying code), it should still confirm the user's intent is "start implementation" rather than "only produce a plan".

默认自动推进顺序（当可自动推进时）

Default Auto-Advance Sequence (When Auto-Advance is Allowed)

先门禁：若下一步会触发读写
```
{FEATURE_DIR}/...
```
或写 demo，则先
```
spec-context
```
并回显
```
FEATURE_DIR=...
```
（失败即停）
再执行：调用路由出的唯一 worker skill 并完成落盘
再路由：读取
```
ROUTER_SUMMARY
```
，满足自动推进条件则继续；否则输出“停下原因 + 需要用户选择/评审的最小动作”

Guardrails first: If the next step triggers read/write operations on
```
{FEATURE_DIR}/...
```
or writes demo, first run
```
spec-context
```
and echo
```
FEATURE_DIR=...
```
(stop if it fails)
Then execute: Call the only routed worker skill and complete artifact persistence
Then re-route: Read
```
ROUTER_SUMMARY
```
, continue if auto-advance conditions are met; otherwise output "reason for stopping + minimal action requiring user selection/review"

路由输入/输出（对话级协议）

Routing Input/Output (Conversation-Level Protocol)

输入（路由所需最小信息）：用户意图（想产出什么/想进入哪个阶段）+ 当前 Spec 上下文（必须经
```
spec-context
```
得到
```
FEATURE_DIR/CURRENT_BRANCH/REPO_ROOT
```
）。

决策依据（只认 SSOT 文件与门禁）：

R0：
```
{FEATURE_DIR}/requirements/raw.md
```

R1：

{FEATURE_DIR}/requirements/solution.md

（必须含

## Impact Analysis

，锚点

#impact-analysis

）

R2：
```
{FEATURE_DIR}/requirements/prd.md
```
R3：
```
{FEATURE_DIR}/requirements/prototype.md
```
D1：
```
{FEATURE_DIR}/design/research.md
```
D2：
```
{FEATURE_DIR}/design/design.md
```
I1：
```
{FEATURE_DIR}/implementation/plan.md
```

输出（唯一“下一步指令”格式）：
- 你现在处于：
```
<阶段>
```
- 下一步（唯一）：
```
<skill 名称>
```
- 必须先过：
```
spec-context → FEATURE_DIR=...
```
  （以及本 skill 的硬门禁）
- 将产生：
```
<落盘产物路径>
```

Input (Minimum Information Required for Routing): User intent (what to produce/which phase to enter) + current Spec context (must obtain
```
FEATURE_DIR/CURRENT_BRANCH/REPO_ROOT
```
via
```
spec-context
```
).

Decision Basis (Only Recognize SSOT Files and Guardrails):

R0:
```
{FEATURE_DIR}/requirements/raw.md
```

R1:

{FEATURE_DIR}/requirements/solution.md

(must contain

## Impact Analysis

, anchor

#impact-analysis

)

R2:
```
{FEATURE_DIR}/requirements/prd.md
```
R3:
```
{FEATURE_DIR}/requirements/prototype.md
```
D1:
```
{FEATURE_DIR}/design/research.md
```
D2:
```
{FEATURE_DIR}/design/design.md
```
I1:
```
{FEATURE_DIR}/implementation/plan.md
```

Output (Only "Next Step Instruction" Format):
- You are currently in:
```
<Phase>
```
- Next step (only one):
```
<Skill Name>
```
- Must pass first:
```
spec-context → FEATURE_DIR=...
```
  (and hard guardrails of this Skill)
- Will produce:
```
<Persisted Artifact Path>
```

何时使用 / 不使用

When to Use / Not to Use

使用时机
- 你要开始/继续一个 Spec：生成或更新
```
raw.md / solution.md / prd.md / prototype.md / demo
```
- 你要把一个“简单需求”直接推进到开发闭环：
```
solution.md → plan.md → execute → finishing
```
- 你要决定设计阶段路线：是否跳过 design、是否需要 research、是否需要 RFC（design/design.md）
- 你不确定“现在该跑哪个 spec-product-* skill”
- 你不确定“现在该跑 spec-implementation-plan / spec-implementation-execute 还是先补需求输入”
- 用户在施压时提出：不想跑脚本、直接给你路径、要求你先写再补上下文
不要用在
- 仅讨论概念、不涉及本仓库 Spec Pack 的落盘文件与目录结构

Use Cases
- You want to start/continue a Spec: generate or update
```
raw.md / solution.md / prd.md / prototype.md / demo
```
- You want to push a "simple requirement" directly to the development loop:
```
solution.md → plan.md → execute → finishing
```
- You want to decide the design phase route: whether to skip design, whether research is needed, whether RFC (design/design.md) is needed
- You are unsure "which spec-product-* skill to run now"
- You are unsure "whether to run spec-implementation-plan / spec-implementation-execute or first supplement demand inputs"
Do Not Use
- Only discussing concepts, not involving persisted files and directory structures of the Spec Pack in this repository

唯一门禁（必须遵守）

Only Guardrails (Must Be Followed)

规则：只要任务会读写以下任意内容，就必须先跑
spec-context
并回显
FEATURE_DIR=...
：

```
{FEATURE_DIR}/requirements/raw.md
```
```
{FEATURE_DIR}/requirements/solution.md
```
```
{FEATURE_DIR}/requirements/prd.md
```
```
{FEATURE_DIR}/requirements/prototype.md
```

{FEATURE_DIR}/design/*.md

（例如

design/design.md

、

design/research.md

）

```
{FEATURE_DIR}/implementation/plan.md
```

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

（R4）

即使用户口头给了
FEATURE_DIR
也不例外。（基线压测中最常见的违规点：把“用户给的路径”当成可信上下文。）

命令书写约定：默认面向 PowerShell；同一行多命令请用
;
分隔（不要用
&&
）。

Rule: As long as the task involves reading/writing any of the following, you must first run
spec-context
and echo
FEATURE_DIR=...
:

```
{FEATURE_DIR}/requirements/raw.md
```
```
{FEATURE_DIR}/requirements/solution.md
```
```
{FEATURE_DIR}/requirements/prd.md
```
```
{FEATURE_DIR}/requirements/prototype.md
```

{FEATURE_DIR}/design/*.md

(e.g.,

design/design.md

design/research.md

)

```
{FEATURE_DIR}/implementation/plan.md
```

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

(R4)

This applies even if the user verbally provides
FEATURE_DIR
. (The most common violation in baseline testing: treating "user-provided path" as trusted context.)

Command Writing Convention: Default to PowerShell; use
;
to separate multiple commands on the same line (do not use
&&
).

你要的最短闭环（简单需求开发）：raw → solution.md → plan.md → execute → finishing-development

The Shortest Loop You Need (Simple Requirement Development): raw → solution.md → plan.md → execute → finishing-development

适用前提（满足其一即可）：

范围单一、边界清晰，风险低，不需要额外设计阶段决策文档（可按
```
design/aisdlc_spec_design.md
```
的 D0 判定跳过 design）
验收口径可追溯：至少能在
```
solution.md
```
（或更完整的
```
prd.md
```
）里写清楚验收点

最短闭环（建议先跑通）：

R0：落盘 raw（如尚未建包）
- 用什么：
```
spec-init
```
- 输出：
```
{FEATURE_DIR}/requirements/raw.md
```
门禁：定位 Spec 上下文
- 用什么：
```
spec-context
```
- 要求：对话中必须回显
```
FEATURE_DIR=...
```
  ；失败即停止
R1：raw → solution（收敛方案）
- 用什么：
```
spec-product-clarify
```
- 输出：
```
{FEATURE_DIR}/requirements/solution.md
```
- 产物门禁：
```
solution.md
```
  必须包含
```
## Impact Analysis
```
  （锚点
```
#impact-analysis
```
  ），作为后续 D2/I1 的约束输入
- 兼容说明：用户可能会说
```
solutions.md
```
  ，但本仓库需求侧 SSOT 以 solution.md
  （单数）为准；不要新建
```
solutions.md
```
  造成双 SSOT
D0：分流判定（是否需要 design 阶段）
- 用什么：
```
using-aisdlc
```
  （本 Skill 负责判定；不落盘或在后续产物中引用分流结论）
- 结论：跳过 design → I1；不跳过 →（按需）D1/D2
I1：solution/prd/design → plan（写到可执行）
- 用什么：
```
spec-implementation-plan
```
- 输出：
```
{FEATURE_DIR}/implementation/plan.md
```
  （唯一执行清单与状态 SSOT）
I2：按 plan 分批执行（实现 + 回写状态/审计）
- 用什么：
```
spec-implementation-execute
```
- 规则：执行状态只回写
```
implementation/plan.md
```
  ；遇到
```
NEEDS CLARIFICATION
```
  / 阻塞即停
Finish：开发收尾确认（仅验证，全绿才算完成）
- 用什么：
```
finishing-development
```
- 输出：一份“完成确认报告”（包含实际运行的命令与结果）

Applicable Premises (Satisfy Any One):

Single scope, clear boundaries, low risk, no need for additional design phase decision documents (can determine to skip design per D0 in
```
design/aisdlc_spec_design.md
```
)
Traceable acceptance criteria: At least can write clear acceptance points in
```
solution.md
```
(or more complete
```
prd.md
```
)

Shortest Loop (Recommended to Run First):

R0: Persist raw (if package not yet created)
- Use:
```
spec-init
```
- Output:
```
{FEATURE_DIR}/requirements/raw.md
```
Guardrail: Locate Spec Context
- Use:
```
spec-context
```
- Requirement: Must echo
```
FEATURE_DIR=...
```
  in the conversation; stop if it fails
R1: raw → solution (Converge on a Solution)
- Use:
```
spec-product-clarify
```
- Output:
```
{FEATURE_DIR}/requirements/solution.md
```
- Artifact Guardrail:
```
solution.md
```
  must contain
```
## Impact Analysis
```
  (anchor
```
#impact-analysis
```
  ), as constrained input for subsequent D2/I1
- Compatibility Note: Users may say
```
solutions.md
```
  , but the SSOT for demand side in this repository is solution.md
  (singular); do not create
```
solutions.md
```
  to avoid dual SSOT
D0: Diversion Judgment (Whether Design Phase is Needed)
- Use:
```
using-aisdlc
```
  (This Skill is responsible for judgment; no persistence or reference to diversion conclusion in subsequent artifacts)
- Conclusion: Skip design → I1; Do not skip → (As needed) D1/D2
I1: solution/prd/design → plan (Write to Executable)
- Use:
```
spec-implementation-plan
```
- Output:
```
{FEATURE_DIR}/implementation/plan.md
```
  (SSOT for execution checklist and status)
I2: Execute in Batches per Plan (Implementation + Write Back Status/Audit)
- Use:
```
spec-implementation-execute
```
- Rule: Execution status is only written back to
```
implementation/plan.md
```
  ; stop when encountering
```
NEEDS CLARIFICATION
```
  / blocked
Finish: Development Completion Confirmation (Verification Only, Complete Only When All Green)
- Use:
```
finishing-development
```
- Output: A "completion confirmation report" (including actually executed commands and results)

核心工作流（需求侧 R0 → R4；设计侧 D0 →（可选）D1 →（可选）D2；实现侧 I1 → I2 → Finish）

Core Workflows (Demand Side R0 → R4; Design Side D0 → (Optional) D1 → (Optional) D2; Implementation Side I1 → I2 → Finish)

dot

digraph aisdlc_flow {
  rankdir=LR;
  node [shape=box];
  "要处理某个需求（Spec）" -> "是否已有合法 spec 分支/Spec Pack？";
  "是否已有合法 spec 分支/Spec Pack？" [shape=diamond];
  "是否已有合法 spec 分支/Spec Pack？" -> "R0: spec-init" [label="否 / 不确定"];
  "R0: spec-init" -> "运行 spec-context" ;
  "是否已有合法 spec 分支/Spec Pack？" -> "运行 spec-context" [label="是"];
  "运行 spec-context" -> "得到 FEATURE_DIR / CURRENT_BRANCH / REPO_ROOT";
  "得到 FEATURE_DIR / CURRENT_BRANCH / REPO_ROOT" -> "选择需求链路 R1-R4（可选）";
  "得到 FEATURE_DIR / CURRENT_BRANCH / REPO_ROOT" -> "D0: 是否跳过 design？";
  "选择需求链路 R1-R4（可选）" -> "R1: raw->solution (含Impact Analysis)";
  "R1: raw->solution (含Impact Analysis)" -> "R2: solution->prd（可选）";
  "R2: solution->prd（可选）" -> "R3: prd->prototype（可选）";
  "R3: prd->prototype（可选）" -> "R4: prototype->demo（可选）";
  "D0: 是否跳过 design？" [shape=diamond];
  "D0: 是否跳过 design？" -> "I1: spec-implementation-plan" [label="是（跳过）"];
  "D0: 是否跳过 design？" -> "D1: spec-design-research（可选）" [label="否，且需要 research"];
  "D0: 是否跳过 design？" -> "D2: spec-design（RFC）" [label="否，且不需要 research"];
  "D1: spec-design-research（可选）" -> "D2: spec-design（RFC）";
  "R1: raw->solution (含Impact Analysis)" -> "D0: 是否跳过 design？";
  "R2: solution->prd（可选）" -> "D0: 是否跳过 design？";
  "R3: prd->prototype（可选）" -> "D0: 是否跳过 design？";
  "D2: spec-design（RFC）" -> "I1: spec-implementation-plan";
  "I1: spec-implementation-plan" -> "I2: spec-implementation-execute";
  "I2: spec-implementation-execute" -> "Finish: finishing-development";
}

dot

digraph aisdlc_flow {
  rankdir=LR;
  node [shape=box];
  "Need to handle a requirement (Spec)" -> "Is there a valid spec branch/Spec Pack?";
  "Is there a valid spec branch/Spec Pack?" [shape=diamond];
  "Is there a valid spec branch/Spec Pack?" -> "R0: spec-init" [label="No / Uncertain"];
  "R0: spec-init" -> "Run spec-context" ;
  "Is there a valid spec branch/Spec Pack?" -> "Run spec-context" [label="Yes"];
  "Run spec-context" -> "Obtain FEATURE_DIR / CURRENT_BRANCH / REPO_ROOT";
  "Obtain FEATURE_DIR / CURRENT_BRANCH / REPO_ROOT" -> "Select demand path R1-R4 (Optional)";
  "Obtain FEATURE_DIR / CURRENT_BRANCH / REPO_ROOT" -> "D0: Skip design?";
  "Select demand path R1-R4 (Optional)" -> "R1: raw->solution (with Impact Analysis)";
  "R1: raw->solution (with Impact Analysis)" -> "R2: solution->prd (Optional)";
  "R2: solution->prd (Optional)" -> "R3: prd->prototype (Optional)";
  "R3: prd->prototype (Optional)" -> "R4: prototype->demo (Optional)";
  "D0: Skip design?" [shape=diamond];
  "D0: Skip design?" -> "I1: spec-implementation-plan" [label="Yes (Skip)"];
  "D0: Skip design?" -> "D1: spec-design-research (Optional)" [label="No, and research needed"];
  "D0: Skip design?" -> "D2: spec-design (RFC)" [label="No, and no research needed"];
  "D1: spec-design-research (Optional)" -> "D2: spec-design (RFC)";
  "R1: raw->solution (with Impact Analysis)" -> "D0: Skip design?";
  "R2: solution->prd (Optional)" -> "D0: Skip design?";
  "R3: prd->prototype (Optional)" -> "D0: Skip design?";
  "D2: spec-design (RFC)" -> "I1: spec-implementation-plan";
  "I1: spec-implementation-plan" -> "I2: spec-implementation-execute";
  "I2: spec-implementation-execute" -> "Finish: finishing-development";
}

D0/D1/D2 路由规则（using-aisdlc 负责判定）

D0/D1/D2 Routing Rules (Determined by using-aisdlc)

设计阶段口径与细则以
design/aisdlc_spec_design.md
为准；这里仅给出可执行的路由决策表。

The caliber and details of the design phase are subject to
design/aisdlc_spec_design.md
; only the executable routing decision table is provided here.

D0：是否跳过 design 阶段（只在 using-aisdlc 判定）

D0: Whether to Skip Design Phase (Only Determined by using-aisdlc)

可考虑跳过（满足其一即可考虑）：范围单一边界清晰 / 无对外承诺变化（API/事件/权限/数据口径）且无迁移回滚 / 无关键技术不确定性 / 验收口径已足够可追溯
默认不跳过（任一命中）：对外契约/权限/口径变更、数据迁移/回滚、高风险不确定性、多系统/上下游影响面大、团队明确要求出 RFC 评审

结论：

跳过 → 路由到
```
spec-implementation-plan
```
（I1），并要求在
```
plan.md
```
补齐最小决策信息
不跳过 → 进入 D1/D2 分流

Consider skipping (satisfy any one to consider): Single scope with clear boundaries / no changes to external commitments (API/events/permissions/data caliber) and no migration rollback / no critical technical uncertainties / acceptance criteria are sufficiently traceable
Default to not skip (hit any one): Changes to external contracts/permissions/calibers, data migration/rollback, high-risk uncertainties, large impact on multiple systems/upstream and downstream, team explicitly requires RFC review

Conclusion:

Skip → Route to
```
spec-implementation-plan
```
(I1), and require supplementing minimal decision information in
```
plan.md
```
Do not skip → Enter D1/D2 diversion

D1：是否需要 research（只在 using-aisdlc 判定）

D1: Whether Research is Needed (Only Determined by using-aisdlc)

命中任一则需要 D1（路由到

spec-design-research

）：

方案正确性依赖未知事实（若 X 不成立会推倒重来）
多方案缺证据支撑取舍
对外契约/迁移/安全/性能/一致性存在高风险点需先验证

否则：直接路由到

spec-design

产出 D2（RFC）。

Route to

spec-design-research

(need D1) if any of the following are hit:

Solution correctness depends on unknown facts (if X is not true, the entire solution will be overturned)
Multiple solutions lack evidence to support trade-offs
High-risk points exist in external contracts/migration/security/performance/consistency that need to be verified first

Otherwise: Directly route to

spec-design

to produce D2 (RFC).

D2：执行 RFC（由

spec-design

作为 worker skill 落盘）

D2: Execute RFC (Worker Skill spec-design Persists Artifact)

当路由到 D2 时，

spec-design

只负责产出/更新：

```
{FEATURE_DIR}/design/design.md
```

并强制消费：

solution.md#impact-analysis

+ 受影响模块组件页全文 + 相关 ADR 全文；缺失必须显式

CONTEXT GAP

。

When routed to D2,

spec-design

is only responsible for producing/updating:

```
{FEATURE_DIR}/design/design.md
```

And must consume:

solution.md#impact-analysis

+ full text of affected module component pages + full text of related ADRs; must explicitly mark

CONTEXT GAP

if any are missing.

R0：初始化新 Spec Pack

R0: Initialize New Spec Pack

用什么：
```
spec-init
```

什么时候：还没有

{num}-{short-name}

分支与

.aisdlc/specs/{num}-{short-name}/

输出：
```
{FEATURE_DIR}/requirements/raw.md
```
（UTF-8 with BOM）
完成后：回到
```
using-aisdlc
```
路由下一步（通常先
```
spec-context
```
，再进入 R1）

Use:
```
spec-init
```

When: No

{num}-{short-name}

branch and

.aisdlc/specs/{num}-{short-name}/

directory exist yet

Output:
```
{FEATURE_DIR}/requirements/raw.md
```
(UTF-8 with BOM)
After completion: Return to
```
using-aisdlc
```
for next-step routing (usually first
```
spec-context
```
, then enter R1)

R1：澄清 + 方案决策（raw → solution）

R1: Clarification + Solution Decision (raw → solution)

用什么：
```
spec-product-clarify
```

前置输入：

spec-context

成功；

{FEATURE_DIR}/requirements/raw.md

存在且非空

关键纪律：一次一问（优先选择题）+ 增量回写
```
raw.md/## 澄清记录
```
+ 停止机制
输出：
```
{FEATURE_DIR}/requirements/solution.md
```
产物门禁：
```
solution.md
```
必须包含
```
## Impact Analysis
```
（
```
#impact-analysis
```
），且可被 D2/I1/I2 直接引用
完成后：回到
```
using-aisdlc
```
路由下一步（R2/R3/R4/D0→I1/D1/D2 等由本 Skill 统一判定）

Use:
```
spec-product-clarify
```
Pre-requisite Input:
```
spec-context
```
succeeds;
```
{FEATURE_DIR}/requirements/raw.md
```
exists and is non-empty
Key Discipline: One question at a time (prioritize multiple-choice questions) + incrementally write back to
```
raw.md/## Clarification Records
```
+ stop mechanism
Output:
```
{FEATURE_DIR}/requirements/solution.md
```
Artifact Guardrail:
```
solution.md
```
must contain
```
## Impact Analysis
```
(
```
#impact-analysis
```
), and can be directly referenced by D2/I1/I2
After completion: Return to
```
using-aisdlc
```
for next-step routing (R2/R3/R4/D0→I1/D1/D2 etc., uniformly determined by this Skill)

R2：PRD（solution → prd，可选）

R2: PRD (solution → prd, Optional)

用什么：
```
spec-product-prd
```
前置输入：
```
{FEATURE_DIR}/requirements/solution.md
```
必须存在
输出：
```
{FEATURE_DIR}/requirements/prd.md
```
完成后：回到
```
using-aisdlc
```
路由下一步

Use:
```
spec-product-prd
```
Pre-requisite Input:
```
{FEATURE_DIR}/requirements/solution.md
```
must exist
Output:
```
{FEATURE_DIR}/requirements/prd.md
```
After completion: Return to
```
using-aisdlc
```
for next-step routing

R3：原型（prd → prototype，可选）

R3: Prototype (prd → prototype, Optional)

用什么：
```
spec-product-prototype
```
前置输入：
```
{FEATURE_DIR}/requirements/prd.md
```
必须存在
输出：
```
{FEATURE_DIR}/requirements/prototype.md
```
完成后：回到
```
using-aisdlc
```
路由下一步（按需进入 R4；发现问题回流 R1/R2/R3）

Use:
```
spec-product-prototype
```
Pre-requisite Input:
```
{FEATURE_DIR}/requirements/prd.md
```
must exist
Output:
```
{FEATURE_DIR}/requirements/prototype.md
```
After completion: Return to
```
using-aisdlc
```
for next-step routing (enter R4 as needed; flow back to R1/R2/R3 if issues are found)

R4：可交互 Demo（prototype → demo，可选）

R4: Interactive Demo (prototype → demo, Optional)

用什么：
```
spec-product-demo
```
前置输入：
```
{FEATURE_DIR}/requirements/prototype.md
```
必须存在；Demo 工程根目录可定位（找不到就停止并要
```
DEMO_PROJECT_ROOT
```
）

输出：默认

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

完成后：回到
```
using-aisdlc
```
路由下一步（运行走查；发现问题按需回流更新 R1/R2/R3/R4）

Use:
```
spec-product-demo
```
Pre-requisite Input:
```
{FEATURE_DIR}/requirements/prototype.md
```
must exist; Demo project root directory can be located (stop and request
```
DEMO_PROJECT_ROOT
```
if not found)

Output: Default to

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

After completion: Return to
```
using-aisdlc
```
for next-step routing (run walkthrough; flow back to update R1/R2/R3/R4 as needed if issues are found)

D1：research（可选）

D1: Research (Optional)

用什么：
```
spec-design-research
```
前置输入：
```
requirements/solution.md
```
已存在且可追溯；（如已存在）
```
design/research.md
```
可增量更新
输出：
```
{FEATURE_DIR}/design/research.md
```
完成后：回到
```
using-aisdlc
```
路由到 D2 或回到 R1 修输入

Use:
```
spec-design-research
```
Pre-requisite Input:
```
requirements/solution.md
```
exists and is traceable;
Output:
```
{FEATURE_DIR}/design/research.md
```
After completion: Return to
```
using-aisdlc
```
to route to D2 or return to R1 to revise inputs

D2：design（RFC / 决策文档；未跳过时必做）

D2: Design (RFC / Decision Document; Mandatory if Not Skipped)

用什么：
```
spec-design
```
前置输入：必须读取
```
solution.md#impact-analysis
```
，并全文读取受影响模块组件页与相关 ADR（读不到必须写
```
CONTEXT GAP
```
）
输出：
```
{FEATURE_DIR}/design/design.md
```
完成后：回到
```
using-aisdlc
```
路由到 I1

Use:
```
spec-design
```
Pre-requisite Input: Must read
```
solution.md#impact-analysis
```
, and read full text of affected module component pages and related ADRs (must write
```
CONTEXT GAP
```
if not readable)
Output:
```
{FEATURE_DIR}/design/design.md
```
After completion: Return to
```
using-aisdlc
```
to route to I1

I1：实现计划（solution/prd/design → plan.md，必做）

I1: Implementation Plan (solution/prd/design → plan.md, Mandatory)

用什么：
```
spec-implementation-plan
```
前置输入：
```
spec-context
```
成功；
```
{FEATURE_DIR}/requirements/solution.md
```
或
```
prd.md
```
至少其一存在（否则必须在
```
plan.md
```
标注
```
NEEDS CLARIFICATION
```
并阻断进入 I2）
输出：
```
{FEATURE_DIR}/implementation/plan.md
```
（唯一执行清单与状态 SSOT）
完成后：回到
```
using-aisdlc
```
路由到 I2

Use:
```
spec-implementation-plan
```
Pre-requisite Input:
```
spec-context
```
succeeds; at least one of
```
{FEATURE_DIR}/requirements/solution.md
```
or
```
prd.md
```
exists (otherwise must mark
```
NEEDS CLARIFICATION
```
in
```
plan.md
```
and block entry to I2)
Output:
```
{FEATURE_DIR}/implementation/plan.md
```
(SSOT for execution checklist and status)
After completion: Return to
```
using-aisdlc
```
to route to I2

I2：执行（按 plan.md 分批实现并回写，必做）

I2: Execution (Batch Implementation per plan.md and Write Back, Mandatory)

用什么：
```
spec-implementation-execute
```
前置输入：
```
{FEATURE_DIR}/implementation/plan.md
```
必须存在且可执行；不存在/不可执行则回到 I1
输出：代码与配置变更 +
```
plan.md
```
checkbox/审计信息回写（唯一状态来源）
完成后：回到
```
using-aisdlc
```
路由到 Finish

Use:
```
spec-implementation-execute
```
Pre-requisite Input:
```
{FEATURE_DIR}/implementation/plan.md
```
must exist and be executable; return to I1 if it does not exist/is not executable
Output: Code and configuration changes + write back of
```
plan.md
```
checkbox/audit information (only source of status)
After completion: Return to
```
using-aisdlc
```
to route to Finish

Finish：开发收尾确认（仅验证，全绿才算完成）

Finish: Development Completion Confirmation (Verification Only, Complete Only When All Green)

用什么：
```
finishing-development
```
输出：完成确认报告（实际运行的命令与结果可复现）
完成后：回到
```
using-aisdlc
```
（或结束；本 Skill 不做合并/PR/清理）

Use:
```
finishing-development
```
Output: Completion confirmation report (executed commands and results are reproducible)
After completion: Return to
```
using-aisdlc
```
(or end; this Skill does not handle merging/PR/cleanup)

Quick reference（高频速查）

Quick Reference (High-Frequency Lookup)

你要做什么	必须先有	执行 skill	主要产物
新需求建包	原始需求（文本或文件）	`spec-init`	`requirements/raw.md`
收敛方案（含影响分析）	`raw.md`	`spec-product-clarify`	`requirements/solution.md#impact-analysis`
冻结交付规格	`solution.md`	`spec-product-prd`	`requirements/prd.md`
消除交互歧义	`prd.md`	`spec-product-prototype`	`requirements/prototype.md`
高保真走查	`prototype.md` + 可运行 demo 工程根目录	`spec-product-demo`	`demo/prototypes/{branch}/`
设计调研（可选）	`solution.md`	`spec-design-research`	`design/research.md`
产出 RFC（未跳过时）	`solution.md#impact-analysis`	`spec-design`	`design/design.md`
写可执行计划（必做）	`solution.md` 或 `prd.md`	`spec-implementation-plan`	`implementation/plan.md`
按计划实现（必做）	`implementation/plan.md`	`spec-implementation-execute`	代码变更 + `plan.md` 回写
开发收尾确认（必做）	代码已实现 + 计划任务已完成	`finishing-development`	完成确认报告

只要会读写
{FEATURE_DIR}/requirements/*
、
{FEATURE_DIR}/design/*
、
{FEATURE_DIR}/implementation/*
，或 R4 写 demo：先
spec-context
，失败就停止。

What You Want to Do	Must Have First	Execute Skill	Main Artifact
Create package for new requirement	Original requirement (text or file)	`spec-init`	`requirements/raw.md`
Converge on solution (with impact analysis)	`raw.md`	`spec-product-clarify`	`requirements/solution.md#impact-analysis`
Freeze delivery specification	`solution.md`	`spec-product-prd`	`requirements/prd.md`
Eliminate interaction ambiguity	`prd.md`	`spec-product-prototype`	`requirements/prototype.md`
High-fidelity walkthrough	`prototype.md` + runnable demo project root directory	`spec-product-demo`	`demo/prototypes/{branch}/`
Design research (Optional)	`solution.md`	`spec-design-research`	`design/research.md`
Produce RFC (if not skipped)	`solution.md#impact-analysis`	`spec-design`	`design/design.md`
Write executable plan (Mandatory)	`solution.md` or `prd.md`	`spec-implementation-plan`	`implementation/plan.md`
Implement per plan (Mandatory)	`implementation/plan.md`	`spec-implementation-execute`	Code changes + `plan.md` write back
Development completion confirmation (Mandatory)	Code implemented + plan tasks completed	`finishing-development`	Completion confirmation report

As long as you read/write
{FEATURE_DIR}/requirements/*
,
{FEATURE_DIR}/design/*
,
{FEATURE_DIR}/implementation/*
, or write demo in R4: first run
spec-context
, stop if it fails.

红旗清单（出现任一条：停止并纠正）

Red Flag List (Stop and Correct if Any Appears)

没跑

spec-context

就开始读写

{FEATURE_DIR}/requirements/*

、

{FEATURE_DIR}/design/*

、

{FEATURE_DIR}/implementation/*

（或开始 R4 写 demo）

用户口头给了
```
FEATURE_DIR
```
，你就“信了并跳过脚本”
```
spec-context
```
报错仍继续（例如 main 分支也要“先写一版”）
为了赶进度先生成文档，事后再补上下文/再回头澄清
在 R4 找不到可运行 demo 工程根目录时，自行初始化 Vite/Next.js 工程“放你觉得合适的位置”
没有
```
{FEATURE_DIR}/implementation/plan.md
```
（或 plan 不可执行）就开始“直接写代码”
执行中把状态/审计写到别处（issue/聊天记录/另一个文件），而不是回写
```
implementation/plan.md
```

Start reading/writing

{FEATURE_DIR}/requirements/*

{FEATURE_DIR}/design/*

{FEATURE_DIR}/implementation/*

(or start R4 demo writing) without running

spec-context

Accept verbal
```
FEATURE_DIR
```
from user and "trust it and skip scripts"
Continue even if
```
spec-context
```
reports an error (e.g., "write a version first" even on main branch)
Generate documents first to catch up on progress, then supplement context/clarify later
When R4 cannot find the runnable demo project root directory, initialize a Vite/Next.js project "in the location you think is appropriate" on your own
Start "directly writing code" without
```
{FEATURE_DIR}/implementation/plan.md
```
(or if the plan is not executable)
Write status/audit information elsewhere (issue/chat record/another file) during execution instead of writing back to
```
implementation/plan.md
```

常见错误（以及怎么修）

Common Errors (and How to Fix Them)

把“用户给的路径/分支名”当作上下文：仍然必须
```
spec-context
```
回显
```
FEATURE_DIR=...
```
；无法执行就停止。
先生成再回头澄清/补证据：先完成 R1 澄清循环（一次一问 + 回写），达到 DoD 后再生成产物。
越级执行：缺
```
solution.md
```
就写
```
prd.md
```
，缺
```
prd.md
```
就写
```
prototype.md
```
，缺
```
prototype.md
```
就做 demo → 一律停止并回到上一步。
越级开发：缺
```
implementation/plan.md
```
就开始实现 → 回到 I1 写到“可执行 + 可验证 + 可审计”，再进入 I2。

Treat "user-provided path/branch name" as context: Still must run
```
spec-context
```
to echo
```
FEATURE_DIR=...
```
; stop if it cannot be executed.
Generate first, then clarify/supplement evidence later: First complete the R1 clarification loop (one question at a time + write back), then generate artifacts after meeting DoD.
Skip levels: Write
```
prd.md
```
without
```
solution.md
```
, write
```
prototype.md
```
without
```
prd.md
```
, make demo without
```
prototype.md
```
→ stop and return to the previous step in all cases.
Skip levels in development: Start implementation without
```
implementation/plan.md
```
→ return to I1 to write until "executable + verifiable + auditable", then enter I2.

常见借口与反制（来自基线压测）

Common Excuses and Countermeasures (From Baseline Testing)

借口（压力来源）	常见违规行为	必须的反制动作
“我已经把 FEATURE_DIR 告诉你了，别跑脚本”	接受口头路径并直接写文件	仍然必须跑 `spec-context` ；跑不了就停止，只交付“阻断原因 + 需要的输入/下一步”
“我很急，先在 main 上写 solution.md”	跳过门禁、猜目录写入	`spec-context` 失败 → 停止；先切到合法 spec 分支或先 `spec-init`
“把 PRD/原型/Demo 一次性都做了”	节点耦合导致漂移、无法回流	拆成 R1→R2→R3→R4；每步完成给下一步与 DoD 自检
“别写 plan 了，直接改代码吧”	跳过 I1、执行不可审计、容易越界	先 `spec-implementation-plan` 产出 `implementation/plan.md` （SSOT），再 `spec-implementation-execute` 分批执行与回写

Excuse (Source of Pressure)	Common Violations	Mandatory Countermeasures
"I already told you the FEATURE_DIR, don't run the script"	Accept verbal path and write files directly	Still must run `spec-context` ; stop if it cannot be executed, only deliver "blocking reason + required input/next step"
"I'm in a hurry, write solution.md on main first"	Skip guardrails, guess directory to write	`spec-context` fails → Stop; switch to a valid spec branch first or run `spec-init` first
"Do PRD/prototype/Demo all at once"	Node coupling leads to drift, cannot flow back	Split into R1→R2→R3→R4; provide next step and DoD self-check after each step
"Don't write the plan, directly modify the code"	Skip I1, execution is not auditable, easy to go out of bounds	First use `spec-implementation-plan` to produce `implementation/plan.md` (SSOT), then use `spec-implementation-execute` for batch execution and write back

一个好例子（最短路径的正确开场）

A Good Example (Correct Opening for the Shortest Path)

用户：“我要做一个新需求，先出方案（solution.md），我不想自己找目录。”

正确做法（第一轮）：

若尚未创建 spec 分支/Spec Pack → 先
```
spec-init
```
（把原始需求落到
```
raw.md
```
）
然后执行
```
spec-context
```
并回显
```
FEATURE_DIR=...
```
进入 R1：对用户只问 1 个最高杠杆选择题；回答后增量回写
```
raw.md/## 澄清记录
```
DoD 达标或触发停止机制后生成
```
solution.md
```
，并给出下一步：
- 简单需求要开发：I1
```
spec-implementation-plan
```
  → I2
```
spec-implementation-execute
```
  →
```
finishing-development
```
- 需要更完整规格/原型：R2/R3/R4（按需）后再进入 I1/I2

User: "I want to work on a new requirement, first create a solution (solution.md), I don't want to find the directory myself."

Correct Approach (First Round):

If no spec branch/Spec Pack has been created yet → first run
```
spec-init
```
(persist the original requirement to
```
raw.md
```
)
Then execute
```
spec-context
```
and echo
```
FEATURE_DIR=...
```
Enter R1: Ask the user only 1 highest-leverage multiple-choice question; incrementally write back to
```
raw.md/## Clarification Records
```
after receiving the answer
After meeting DoD or triggering the stop mechanism, generate
```
solution.md
```
, and provide the next step:
- Simple requirement for development: I1
```
spec-implementation-plan
```
  → I2
```
spec-implementation-execute
```
  →
```
finishing-development
```
- Need more complete specification/prototype: Enter I1/I2 only after R2/R3/R4 (as needed)