sdd-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<SUBAGENT-STOP> If you were dispatched as a subagent to execute a specific task, skip this skill. </SUBAGENT-STOP> <CRITICAL-OVERRIDE> **Two superpowers skills have defaults that conflict with sdd-workflow. Both are OVERRIDDEN:**

Brainstorming says its terminal state is

writing-plans

OVERRIDDEN: After brainstorming → invoke
```
/opsx:propose "<name>"
```
, NOT
```
writing-plans
```
.

The pipeline is:

brainstorming → /opsx:propose → review → /opsx:verify → writing-plans

Writing-plans says its output path is
```
docs/superpowers/plans/YYYY-MM-DD-<name>.md
```
.
- OVERRIDDEN: Output MUST go to
```
openspec/changes/<name>/plan.md
```
  .
- ```
docs/superpowers/plans/
```
  is a legacy path — do NOT use it.

If you invoke

writing-plans

immediately after brainstorming, you skip Steps 2-4 (the entire OpenSpec specification phase). If you write

plan.md

docs/superpowers/plans/

, it lives outside the OpenSpec traceability system. </CRITICAL-OVERRIDE>

<EXTREMELY-IMPORTANT> Spec-driven development means specs live in the file system, not in chat history. OpenSpec manages specification artifacts. Superpowers enforces execution discipline. This skill routes between them.

IF A SPEC EXISTS, YOU MUST READ IT BEFORE WRITING CODE. IF NO SPEC EXISTS FOR BEHAVIOR CHANGE, YOU MUST CREATE ONE FIRST.

This is not negotiable. This is not optional. You cannot rationalize your way out of this. </EXTREMELY-IMPORTANT>

<SUBAGENT-STOP> 如果您被派作为子代理执行特定任务，请跳过此技能。 </SUBAGENT-STOP> <CRITICAL-OVERRIDE> **有两个superpowers技能的默认设置与sdd-workflow冲突，均已被覆盖：**

Brainstorming 称其终端状态为

writing-plans

。

已覆盖：头脑风暴后 → 调用
```
/opsx:propose "<name>"
```
，而非
```
writing-plans
```
。

流水线为：

brainstorming → /opsx:propose → review → /opsx:verify → writing-plans

。

Writing-plans 称其输出路径为
```
docs/superpowers/plans/YYYY-MM-DD-<name>.md
```
。
- 已覆盖：输出必须保存至
```
openspec/changes/<name>/plan.md
```
  。
- ```
docs/superpowers/plans/
```
  是旧路径——请勿使用。

如果您在头脑风暴后直接调用

writing-plans

，会跳过步骤2-4（整个OpenSpec规范阶段）。如果将

plan.md

写入

docs/superpowers/plans/

，它将处于OpenSpec可追溯系统之外。 </CRITICAL-OVERRIDE>

<EXTREMELY-IMPORTANT> 规范驱动开发意味着规范存储在文件系统中，而非聊天记录里。OpenSpec管理规范工件，Superpowers执行纪律约束。此技能负责在两者之间进行路由。

如果已有规范，编写代码前必须先阅读。如果行为变更没有对应的规范，必须先创建一个。

这没有商量余地，也不是可选步骤，您无法找借口跳过。 </EXTREMELY-IMPORTANT>

Instruction Priority

指令优先级

User's explicit instructions (CLAUDE.md, AGENTS.md, direct requests) — highest priority
OpenSpec artifacts (proposal.md, specs/, design.md, tasks.md) — the authoritative spec baseline
SDD workflow skills — route and enforce process
Default system prompt — lowest priority

If the user says "skip the spec, just write code," follow the user's instructions. The user is in control.

用户明确指令（CLAUDE.md、AGENTS.md、直接请求）——最高优先级
OpenSpec工件（proposal.md、specs/、design.md、tasks.md）——权威规范基线
SDD工作流技能——路由并执行流程
默认系统提示——最低优先级

如果用户说“跳过规范，直接写代码”，请遵循用户的指令。用户拥有控制权。

SDD Workflow — Spec-Driven Development Router

SDD工作流——规范驱动开发路由器

The Rule

规则

Before any code, human and AI agree on what to build. Specifications are files in

openspec/

. Every behavior change is traceable from proposal through archive. Run

openspec init

openspec/

doesn't exist.

Announce at start: "I'm using the sdd-workflow skill to route this development task."

编写任何代码前，人与AI需就构建内容达成共识。 规范是

openspec/

目录下的文件。每一项行为变更都可从提案追溯到归档。如果

openspec/

不存在，请运行

openspec init

。

开始时需声明： "我正在使用sdd-workflow技能来路由此开发任务。"

The 10-Step Pipeline

10步流水线

OpenSpec provides the specification skeleton (what). Superpowers enforces execution discipline (how). They connect in sequence with no overlap:

0. [Optional] superpowers:brainstorming  — Exploratory design for greenfield/fuzzy requirements.
                                           Output: design doc → feeds into Step 2.
                                           ⛔ After approval → go to Step 2, NOT writing-plans.

1. [User request]
     ↓
2. /opsx:propose <name>            — OpenSpec: Create proposal. Generate all 4 artifacts.
     ↓                               proposal.md + specs/ + design.md + tasks.md
3. [Manual review + iterate]       — OpenSpec: Refine specs. Review and revise each artifact.
     ↓                               Optional: /opsx:continue (step-by-step), /opsx:ff (fast-forward).
4. /opsx:verify                    — OpenSpec: Verify specs. 3-dimension validation gate.
     ↓
5. superpowers:writing-plans       — Superpowers: Generate implementation plan.
     ↓                               Output: openspec/changes/<name>/plan.md
6. /opsx:apply +                   — Superpowers: TDD execution. apply = scheduler, TDD = executor.
   @test-driven-development          RED → GREEN → REFACTOR per task.
     ↓
7. @requesting-code-review         — Superpowers: Code review.
     ↓
8. @verification-before-           — Superpowers: Pre-completion verification. Fresh test evidence.
   completion
     ↓
9. /opsx:archive <name>            — OpenSpec: Archive change. Delta merge + move to archive/.
     ↓
10. [Delivered]                    — Ship it.

OpenSpec提供规范框架（要做什么）。Superpowers执行纪律约束（怎么做）。它们按顺序衔接，互不重叠：

0. [可选] superpowers:brainstorming  — 针对全新领域/模糊需求的探索性设计。
                                           输出：设计文档 → 输入到步骤2。
                                           ⛔ 批准后 → 进入步骤2，而非writing-plans。

1. [用户请求]
     ↓
2. /opsx:propose <name>            — OpenSpec：创建提案。生成全部4个工件。
     ↓                               proposal.md + specs/ + design.md + tasks.md
3. [人工审查 + 迭代]       — OpenSpec：细化规范。审查并修订每个工件。
     ↓                               可选：/opsx:continue（分步执行）、/opsx:ff（快速推进）。
4. /opsx:verify                    — OpenSpec：验证规范。三维验证关卡。
     ↓
5. superpowers:writing-plans       — Superpowers：生成实施计划。
     ↓                               输出：openspec/changes/<name>/plan.md
6. /opsx:apply +                   — Superpowers：TDD执行。apply为调度器，TDD为执行器。
   @test-driven-development          按任务执行 RED → GREEN → REFACTOR。
     ↓
7. @requesting-code-review         — Superpowers：代码审查。
     ↓
8. @verification-before-           — Superpowers：完成前验证。提供新的测试证据。
   completion
     ↓
9. /opsx:archive <name>            — OpenSpec：归档变更。增量合并 + 移动至archive/。
     ↓
10. [交付完成]                    — 发布。

Artifact Ownership

工件归属

OpenSpec and Superpowers each produce plan-like files — they serve different roles and both belong in

openspec/changes/<name>/

Artifact	Owner	Granularity	Purpose	Example
`tasks.md`	OpenSpec ( `/opsx:propose` )	Coarse checkbox items	WHAT to implement	`- [ ] Implement Store interface`
`plan.md`	Superpowers ( `writing-plans` )	2-5min subtasks	HOW to implement	`1. Define Store interface in store/store.go (2 min)`

Rule:

plan.md

refines

tasks.md

— it does NOT replace it. Both coexist in the same change directory.

writing-plans

reads

tasks.md

as input and outputs

plan.md

with detailed steps, file paths, and test names.

openspec/changes/<name>/
├── proposal.md    ← OpenSpec: why + scope boundary
├── specs/         ← OpenSpec: behavior delta specs
├── design.md      ← OpenSpec: technical decisions
├── tasks.md       ← OpenSpec: coarse implementation checklist (WHAT)
└── plan.md        ← Superpowers: refined subtasks (HOW)

docs/superpowers/specs/

and

docs/superpowers/plans/

are legacy brainstorming output paths — they are NOT used by this workflow. All artifacts live under

openspec/changes/<name>/

OpenSpec和Superpowers都会生成类计划文件——它们承担不同角色，且都应存放在

openspec/changes/<name>/

目录下：

工件	所有者	粒度	目的	示例
`tasks.md`	OpenSpec ( `/opsx:propose` )	粗粒度复选框项	明确要实现什么	`- [ ] Implement Store interface`
`plan.md`	Superpowers ( `writing-plans` )	2-5分钟子任务	明确如何实现	`1. Define Store interface in store/store.go (2 min)`

规则：

plan.md

是对

tasks.md

的细化——而非替代。两者共存于同一变更目录中。

writing-plans

读取

tasks.md

作为输入，输出包含详细步骤、文件路径和测试名称的

plan.md

。

openspec/changes/<name>/
├── proposal.md    ← OpenSpec：原因 + 范围边界
├── specs/         ← OpenSpec：行为变更规范
├── design.md      ← OpenSpec：技术决策
├── tasks.md       ← OpenSpec：粗粒度实施检查清单（要做什么）
└── plan.md        ← Superpowers：细化子任务（怎么做）

docs/superpowers/specs/

和

docs/superpowers/plans/

是旧的头脑风暴输出路径——本工作流不使用这些路径。所有工件都存放在

openspec/changes/<name>/

下。

OpenSpec Command Reference

OpenSpec命令参考

Command	Description	When to use
`/opsx:propose`	Generate complete change artifacts in one step	Requirements are clear
`/opsx:explore`	Investigate without creating files	Fuzzy requirements, tech evaluation, approach comparison
`/opsx:apply`	Implement tasks from tasks.md item by item	Implementation phase
`/opsx:archive`	Archive and merge specs	Feature complete
`/opsx:new`	Create change skeleton only	Want fine-grained control over artifact creation
`/opsx:continue`	Generate the next artifact	Step-by-step review, confirm each artifact
`/opsx:ff`	Fast-forward: generate all remaining artifacts	Direction confirmed, accelerate
`/opsx:verify`	3-dimension validation of implementation	Pre-archive quality check
`/opsx:sync`	Sync specs without archiving	Parallel changes need reference
`/opsx:bulk-archive`	Batch archive multiple changes	Multi-feature unified wrap-up

命令	描述	使用时机
`/opsx:propose`	一步生成完整的变更工件	需求明确时
`/opsx:explore`	仅调研不创建文件	需求模糊、技术评估、方案对比时
`/opsx:apply`	逐项执行tasks.md中的任务	实施阶段
`/opsx:archive`	归档并合并规范	功能完成时
`/opsx:new`	仅创建变更框架	希望对工件创建进行细粒度控制时
`/opsx:continue`	生成下一个工件	分步审查、确认每个工件时
`/opsx:ff`	快速推进：生成所有剩余工件	方向已确认，需加速时
`/opsx:verify`	对实施进行三维验证	归档前的质量检查
`/opsx:sync`	同步规范但不归档	并行变更需要参考时
`/opsx:bulk-archive`	批量归档多个变更	多功能统一收尾时

Request Classification

请求分类

When the user brings a development request, classify FIRST. Then route.

当用户提出开发请求时，先进行分类，再路由。

Boundedness Check — BEFORE routing to Step 2

边界检查 — 路由至步骤2之前

A task is NOT "clearly bounded" (and therefore MUST route through Step 0: exploration or brainstorming) if ANY of these are true:

Signal	Example	Route to
Introduces concepts NOT in the current data model	"add users", "add sharing", "add permissions" — and the codebase has no User/Share/Permission struct	`superpowers:brainstorming`
Has multiple valid interpretations with different architectures	"add collaboration" could mean real-time sync, async assignment, or shared views	`superpowers:brainstorming`
Uses hedging or vague language	"somehow", "或者", "something like", "加点协作能力"	`superpowers:brainstorming`
Requires comparing 2+ approaches with significant trade-offs	"should we use WebSocket or polling?"	`superpowers:brainstorming`
You don't know which files would change without reading code first	Unfamiliar codebase or new feature area	`/opsx:explore` → then re-run Boundedness Check → if still fuzzy → `superpowers:brainstorming`

A task IS "clearly bounded" (can skip to Step 2) ONLY when ALL of these are true:

The data model is already defined (structs/tables exist)
There is exactly one obvious implementation approach
The request uses specific, concrete language ("add a DELETE endpoint", "add a
```
due_date
```
field to Task")
You can list the files that will change without reading any code

Signal priority: Brainstorming signals beat exploration signals. When a task matches BOTH a brainstorming signal AND the exploration signal, the flow is:

/opsx:explore

(read code, build context) → re-run Boundedness Check →

superpowers:brainstorming

(generate and compare approaches). Never skip the brainstorming step when ANY brainstorming signal is triggered.

Default rule: if you're not sure, it's not clearly bounded. Route to exploration or brainstorming.

如果满足以下任一条件，则任务不属于“明确边界”（因此必须路由至步骤0：探索或头脑风暴）：

信号	示例	路由至
引入当前数据模型中不存在的概念	"添加用户"、"添加共享功能"、"添加权限"——而代码库中没有User/Share/Permission结构体	`superpowers:brainstorming`
存在多种具有不同架构的有效解读	"添加协作功能"可能意味着实时同步、异步分配或共享视图	`superpowers:brainstorming`
使用模糊或不确定的语言	"某种方式"、"或者"、"类似这样"、"加点协作能力"	`superpowers:brainstorming`
需要比较2种及以上存在重大权衡的方案	"我们应该用WebSocket还是轮询？"	`superpowers:brainstorming`
不读取代码就不知道哪些文件会变更	不熟悉代码库或新功能领域	`/opsx:explore` → 然后重新运行边界检查 → 如果仍然模糊 → `superpowers:brainstorming`

只有同时满足以下所有条件，任务才属于“明确边界”（可跳过至步骤2）：

数据模型已定义（结构体/表已存在）
只有一种明显的实现方案
请求使用具体、明确的语言（"添加DELETE端点"、"为Task添加
```
due_date
```
字段"）
无需读取代码即可列出会变更的文件

信号优先级： 头脑风暴信号优先于探索信号。当任务同时匹配头脑风暴信号和探索信号时，流程为：

/opsx:explore

（读取代码、构建上下文）→ 重新运行边界检查 →

superpowers:brainstorming

（生成并对比方案）。只要触发任何头脑风暴信号，绝不能跳过头脑风暴步骤。

默认规则：如果不确定，则不属于明确边界。路由至探索或头脑风暴。

CRITICAL: After

/opsx:explore

— Do NOT present options

重要提示：

/opsx:explore

之后 — 不要提供选项

/opsx:explore

builds context. It does NOT authorize you to decide what to implement. After it completes:

Do NOT present a numbered list of features and ask the user to pick
Do NOT ask "你希望补充哪些功能？" or "Which features do you want?"
Do NOT merge exploration + decision into one step

You MUST instead:

Re-run the Boundedness Check against the task
If ANY "not bounded" signal still applies → invoke
```
superpowers:brainstorming
```
to generate and compare approaches
Only skip brainstorming if the exploration revealed exactly ONE obvious gap (e.g., "this CRUD API is missing a DELETE handler")

Wrong: Explore → "Here are 4 options, pick one" → implement Right: Explore → Boundedness Check → Brainstorming →

/opsx:propose

→ review → implement

dot

digraph sdd_routing {
    "User request received" [shape=doublecircle];
    "Is it a one-line fix?\n(typo, log line, comment)" [shape=diamond];
    "Make change,\nverify directly" [shape=box style=filled fillcolor="#ccffcc"];
    "Is it a bug with\nunclear cause?" [shape=diamond];
    "superpowers:systematic-debugging\n(root cause first)" [shape=box style=filled fillcolor="#ffcccc"];
    "Are there OpenSpec\nartifacts already?" [shape=diamond];
    "Read existing artifacts,\npick up where left off" [shape=box style=filled fillcolor="#ccccff"];
    "Run Boundedness Check.\nIs it clearly bounded?" [shape=diamond];
    "Unfamiliar codebase\nor uncertain approach?" [shape=diamond];
    "/opsx:propose\n(generate 4 artifacts)" [shape=box style=filled fillcolor="#ffffcc"];
    "/opsx:explore\n(build context first)" [shape=box style=filled fillcolor="#ffffcc"];
    "superpowers:brainstorming\n(Socratic design)" [shape=box style=filled fillcolor="#ffffcc"];
    "Route to 10-Step\nPipeline Step 2" [shape=doublecircle];

    "User request received" -> "Is it a one-line fix?\n(typo, log line, comment)";
    "Is it a one-line fix?\n(typo, log line, comment)" -> "Make change,\nverify directly" [label="yes"];
    "Is it a one-line fix?\n(typo, log line, comment)" -> "Is it a bug with\nunclear cause?" [label="no"];
    "Is it a bug with\nunclear cause?" -> "superpowers:systematic-debugging\n(root cause first)" [label="yes"];
    "Is it a bug with\nunclear cause?" -> "Are there OpenSpec\nartifacts already?" [label="no"];
    "Are there OpenSpec\nartifacts already?" -> "Read existing artifacts,\npick up where left off" [label="yes"];
    "Are there OpenSpec\nartifacts already?" -> "Run Boundedness Check.\nIs it clearly bounded?" [label="no"];
    "Run Boundedness Check.\nIs it clearly bounded?" -> "Unfamiliar codebase\nor uncertain approach?" [label="no — see\nBoundedness Check"];
    "Run Boundedness Check.\nIs it clearly bounded?" -> "Route to 10-Step\nPipeline Step 2" [label="yes — meets ALL\nclear-boundary criteria"];
    "Unfamiliar codebase\nor uncertain approach?" -> "/opsx:explore\n(build context first)" [label="need to read\ncode first"];
    "Unfamiliar codebase\nor uncertain approach?" -> "superpowers:brainstorming\n(Socratic design)" [label="greenfield\nor approach\ncomparison"];
    "/opsx:explore\n(build context first)" -> "Run Boundedness Check.\nIs it clearly bounded?";
    "superpowers:brainstorming\n(Socratic design)" -> "Run Boundedness Check.\nIs it clearly bounded?";
}

/opsx:explore

用于构建上下文，不授权您决定要实现什么。完成后：

请勿列出多个功能并让用户选择
请勿询问“你希望补充哪些功能？”或“Which features do you want?”
请勿将探索和决策合并为一步

您必须：

针对任务重新运行边界检查
如果仍有任何“非边界”信号适用 → 调用
```
superpowers:brainstorming
```
生成并对比方案
只有当探索揭示出唯一明显的缺口时（例如：“这个CRUD API缺少DELETE处理器”），才可跳过头脑风暴

错误流程： 探索 → “这里有4个选项，请选择一个” → 实现 正确流程： 探索 → 边界检查 → 头脑风暴 →

/opsx:propose

→ 审查 → 实现

dot

digraph sdd_routing {
    "User request received" [shape=doublecircle];
    "Is it a one-line fix?\n(typo, log line, comment)" [shape=diamond];
    "Make change,\nverify directly" [shape=box style=filled fillcolor="#ccffcc"];
    "Is it a bug with\nunclear cause?" [shape=diamond];
    "superpowers:systematic-debugging\n(root cause first)" [shape=box style=filled fillcolor="#ffcccc"];
    "Are there OpenSpec\nartifacts already?" [shape=diamond];
    "Read existing artifacts,\npick up where left off" [shape=box style=filled fillcolor="#ccccff"];
    "Run Boundedness Check.\nIs it clearly bounded?" [shape=diamond];
    "Unfamiliar codebase\nor uncertain approach?" [shape=diamond];
    "/opsx:propose\n(generate 4 artifacts)" [shape=box style=filled fillcolor="#ffffcc"];
    "/opsx:explore\n(build context first)" [shape=box style=filled fillcolor="#ffffcc"];
    "superpowers:brainstorming\n(Socratic design)" [shape=box style=filled fillcolor="#ffffcc"];
    "Route to 10-Step\nPipeline Step 2" [shape=doublecircle];

    "User request received" -> "Is it a one-line fix?\n(typo, log line, comment)";
    "Is it a one-line fix?\n(typo, log line, comment)" -> "Make change,\nverify directly" [label="yes"];
    "Is it a one-line fix?\n(typo, log line, comment)" -> "Is it a bug with\nunclear cause?" [label="no"];
    "Is it a bug with\nunclear cause?" -> "superpowers:systematic-debugging\n(root cause first)" [label="yes"];
    "Is it a bug with\nunclear cause?" -> "Are there OpenSpec\nartifacts already?" [label="no"];
    "Are there OpenSpec\nartifacts already?" -> "Read existing artifacts,\npick up where left off" [label="yes"];
    "Are there OpenSpec\nartifacts already?" -> "Run Boundedness Check.\nIs it clearly bounded?" [label="no"];
    "Run Boundedness Check.\nIs it clearly bounded?" -> "Unfamiliar codebase\nor uncertain approach?" [label="no — see\nBoundedness Check"];
    "Run Boundedness Check.\nIs it clearly bounded?" -> "Route to 10-Step\nPipeline Step 2" [label="yes — meets ALL\nclear-boundary criteria"];
    "Unfamiliar codebase\nor uncertain approach?" -> "/opsx:explore\n(build context first)" [label="need to read\ncode first"];
    "Unfamiliar codebase\nor uncertain approach?" -> "superpowers:brainstorming\n(Socratic design)" [label="greenfield\nor approach\ncomparison"];
    "/opsx:explore\n(build context first)" -> "Run Boundedness Check.\nIs it clearly bounded?";
    "superpowers:brainstorming\n(Socratic design)" -> "Run Boundedness Check.\nIs it clearly bounded?";
}

Phase Detection

阶段检测

Check the file system to determine where you are in the workflow:

What exists	Phase	Next action
No `openspec/` directory	Uninitialized	Run `openspec init` first
`openspec/` exists, no change dir	Ready for proposal	Route to Step 2: `/opsx:propose <name>` or Step 0: exploration
`openspec/changes/<name>/` with 4 artifacts, unreviewed	Specs need review	Steps 3-4: Manual review → `/opsx:verify`
`openspec/changes/<name>/` with reviewed artifacts	Ready for execution	Step 5: `superpowers:writing-plans`
`tasks.md` has unchecked items	In progress	Step 6: `/opsx:apply` + `@test-driven-development`
All tasks checked, not archived	Ready for delivery	Steps 7-8: review → verify → Step 9: `/opsx:archive`

通过检查文件系统确定当前所处的工作流阶段：

存在的内容	阶段	下一步操作
无 `openspec/` 目录	未初始化	先运行 `openspec init`
`openspec/` 存在，但无变更目录	准备提案	路由至步骤2： `/opsx:propose <name>` 或步骤0：探索
`openspec/changes/<name>/` 包含4个未审查的工件	规范需审查	步骤3-4：人工审查 → `/opsx:verify`
`openspec/changes/<name>/` 包含已审查的工件	准备执行	步骤5： `superpowers:writing-plans`
`tasks.md` 有未勾选的项目	进行中	步骤6： `/opsx:apply` + `@test-driven-development`
所有任务已勾选，未归档	准备交付	步骤7-8：审查 → 验证 → 步骤9： `/opsx:archive`

Transition Rules

过渡规则

Step 0: Explore → Brainstorming Gate

步骤0：探索 → 头脑风暴关卡

When the Boundedness Check routes to

/opsx:explore

(because you don't know which files would change),

/opsx:explore

is read-only reconnaissance — it builds context, NOT decisions. After it completes:

Re-run the Boundedness Check. The task is still "not clearly bounded" unless the codebase exploration revealed a single obvious gap.
If ANY "not bounded" signal still applies → route to
```
superpowers:brainstorming
```
. Do NOT present options to the user. Do NOT ask the user what to implement. Brainstorming is where options are generated and compared.
If the task is now clearly bounded (rare after a fuzzy request) → proceed to Step 2:
```
/opsx:propose
```
.

Why:

/opsx:explore

answers "what exists."

superpowers:brainstorming

answers "what should we build." Mixing them (explore → offer choices → implement) skips design entirely. The DOT graph shows the loop:

explore → Boundedness Check

— this must execute, not be skipped.

当边界检查路由至

/opsx:explore

（因为您不知道哪些文件会变更）时，

/opsx:explore

是只读的侦察操作——用于构建上下文，而非做决策。完成后：

重新运行边界检查。除非代码库探索揭示出唯一明显的缺口，否则任务仍属于“非明确边界”。
如果仍有任何“非边界”信号适用 → 路由至
```
superpowers:brainstorming
```
。请勿向用户提供选项，请勿询问用户要实现什么。头脑风暴是生成和对比方案的环节。
如果任务现在属于明确边界（模糊请求后这种情况很少见）→ 进入步骤2：
```
/opsx:propose
```
。

原因：

/opsx:explore

回答“现有什么”。

superpowers:brainstorming

回答“我们应该构建什么”。将两者混合（探索 → 提供选项 → 实现）会完全跳过设计环节。DOT图显示了循环：

explore → 边界检查

——必须执行此循环，不能跳过。

Step 0 → Step 2: The Critical Handoff

步骤0 → 步骤2：关键交接

Brainstorming (Step 0) is optional. When requirements are already clear, skip to Step 2.

The brainstorming skill says its terminal state is
writing-plans
. THIS IS OVERRIDDEN. When brainstorming is invoked through sdd-workflow, the pipeline is: brainstorming → /opsx:propose → review → /opsx:verify → writing-plans.

When brainstorming completes and the user approves the design:

DO NOT invoke
```
writing-plans
```
— this bypasses OpenSpec Steps 2-4
DO NOT write code — the spec isn't locked yet
DO invoke
```
/opsx:propose "<name>"
```
— feed the approved brainstorming design as context
DO verify
```
openspec/changes/<name>/
```
contains: proposal.md, specs/, design.md, tasks.md
Only then proceed to Step 3.

Why: Brainstorming produces an exploratory design (Phase 1 — Superpowers). OpenSpec locks it into auditable, mergeable artifacts (Phase 2 — OpenSpec).

docs/superpowers/specs/

is transient;

openspec/changes/<name>/

is permanent and traceable. Skipping Step 2 means specs can't be verified, archived, or traced.

头脑风暴（步骤0）是可选的。当需求已明确时，可跳过至步骤2。

头脑风暴技能称其终端状态为
writing-plans
。此设置已被覆盖。当通过sdd-workflow调用头脑风暴时，流水线为：头脑风暴 →

/opsx:propose

→ 审查 →

/opsx:verify

→ writing-plans。

头脑风暴完成且用户批准设计后：

请勿调用
```
writing-plans
```
——这会绕过OpenSpec步骤2-4
请勿编写代码——规范尚未锁定
必须调用
```
/opsx:propose "<name>"
```
——将批准的头脑风暴设计作为上下文传入
必须确认
```
openspec/changes/<name>/
```
包含：proposal.md、specs/、design.md、tasks.md
之后才能进入步骤3。

原因： 头脑风暴生成探索性设计（阶段1——Superpowers）。OpenSpec将其锁定为可审计、可合并的工件（阶段2——OpenSpec）。

docs/superpowers/specs/

是临时路径；

openspec/changes/<name>/

是永久且可追溯的路径。跳过步骤2意味着规范无法被验证、归档或追溯。

Steps 2-10: Linear Execution

步骤2-10：线性执行

Step 2: /opsx:propose <name>     → If Step 0 was done, feed its output as context.
                                    Confirm artifacts before Step 3.

Step 3: Manual review + iterate   → Review proposal/specs/design/tasks item by item.
                                    Optional: /opsx:continue (step) | /opsx:ff (fast-forward).
                                    Standard: every in-scope item has a task checkbox.

Step 4: /opsx:verify              → 3-dimension validation (complete/correct/consistent).
                                    Pass before entering execution phase.

Step 5: superpowers:writing-plans → MUST save to openspec/changes/<name>/plan.md
                                    (NOT docs/superpowers/plans/).
                                    Output: 2-5 minute granular subtasks.

Step 6: /opsx:apply +             → apply = scheduler, TDD = executor.
  @test-driven-development          RED → GREEN → REFACTOR per task.
                                    On error: @systematic-debugging → return to apply.
                                    All tasks complete → Step 7.

Step 7: @requesting-code-review   → Dispatch code-reviewer. Fix Critical/Important issues.

Step 8: @verification-before-     → Fresh go test ./... / pytest / etc.
  completion                        Evidence required BEFORE claiming completion.

Step 9: /opsx:archive <name>      → Delta merge into openspec/specs/.
                                    Change moved to openspec/changes/archive/.
                                    project.md updated.

Step 10: Done                     → Ship it.

步骤2：/opsx:propose <name>     → 如果已执行步骤0，将其输出作为上下文传入。
                                    进入步骤3前确认工件存在。

步骤3：人工审查 + 迭代   → 逐项审查提案/规范/设计/任务。
                                    可选：/opsx:continue（分步）| /opsx:ff（快速推进）。
                                    标准：所有范围内的项目都有任务复选框。

步骤4：/opsx:verify              → 三维验证（完整/正确/一致）。
                                    通过后才能进入执行阶段。

步骤5：superpowers:writing-plans → 必须保存至openspec/changes/<name>/plan.md
                                    （而非docs/superpowers/plans/）。
                                    输出：2-5分钟粒度的子任务。

步骤6：/opsx:apply +             → apply为调度器，TDD为执行器。
  @test-driven-development          按任务执行 RED → GREEN → REFACTOR。
                                    出错时：@systematic-debugging → 返回apply。
                                    所有任务完成 → 步骤7。

步骤7：@requesting-code-review   → 分派代码审查人员。修复关键/重要问题。

步骤8：@verification-before-     → 重新执行go test ./... / pytest等测试。
  completion                        声称完成前必须提供验证证据。

步骤9：/opsx:archive <name>      → 增量合并至openspec/specs/。
                                    变更移至openspec/changes/archive/。
                                    更新project.md。

步骤10：完成                     → 发布。

Tool Selection Matrix

工具选择矩阵

When both OpenSpec and Superpowers offer a tool for the same phase:

Scenario	Use This	Not That	Why
Reading existing code	`/opsx:explore`	`@brainstorming`	Explore reads code; brainstorming generates ideas
Defining new feature	`@brainstorming`	`/opsx:explore`	Brainstorming compares approaches
Generating spec artifacts	`/opsx:propose`	`@writing-plans`	Propose creates 4 artifacts; writing-plans refines
Refining task granularity	`@writing-plans`	Manual only	Writing-plans converts to 2-5min units
Executing tasks	`/opsx:apply` + `@test-driven-development`	Either alone	Apply schedules; TDD executes
Debugging failures	`@systematic-debugging`	Direct fixes	Root cause investigation first
Code review	`@requesting-code-review` + `@receiving-code-review`	"Looks good to me"	Structured independent review
Claiming completion	`@verification-before-completion`	"Should work now"	Fresh evidence required
Archiving work	`/opsx:archive`	Manual file moves	Archive does delta merge + timestamp

当OpenSpec和Superpowers针对同一阶段都提供工具时：

场景	使用此工具	不使用此工具	原因
阅读现有代码	`/opsx:explore`	`@brainstorming`	Explore用于读取代码；brainstorming用于生成想法
定义新功能	`@brainstorming`	`/opsx:explore`	Brainstorming用于对比方案
生成规范工件	`/opsx:propose`	`@writing-plans`	Propose生成4个工件；writing-plans用于细化
细化任务粒度	`@writing-plans`	仅手动操作	Writing-plans将任务转换为2-5分钟的单元
执行任务	`/opsx:apply` + `@test-driven-development`	单独使用任一工具	Apply负责调度；TDD负责执行
调试故障	`@systematic-debugging`	直接修复	先调查根因
代码审查	`@requesting-code-review` + `@receiving-code-review`	"看起来没问题"	结构化独立审查
声称完成	`@verification-before-completion`	"现在应该可以工作了"	必须提供新的验证证据
归档工作	`/opsx:archive`	手动移动文件	Archive执行增量合并 + 时间戳

Red Flags

危险信号

These thoughts mean STOP — you're rationalizing skipping the SDD process:

Thought	Reality
"This is simple, I don't need a spec"	Simple changes cause complex bugs. A 5-line proposal.md saves hours.
"I'll write the spec after the code"	Specs-after describe what you built, not what's needed.
"The spec is in the conversation history"	Conversation history evaporates. Files persist. Write it down.
"I already know what to build"	Knowing ≠ having it reviewed. Specs are the agreement.
"Specs slow me down"	Rework from misaligned expectations is slower.
"This is just a prototype"	Prototypes become production. Spec now saves pain later.
"I'll just explore the codebase first"	Use `/opsx:explore` — structured, not aimless browsing.
"I remember how this codebase works"	Code evolves. Your memory is stale. Read the specs.
"This task is clearly bounded, skip brainstorming"	⛔ STOP. Run the Boundedness Check. Does the task introduce concepts NOT in the current data model? Does it have multiple valid interpretations? If yes → brainstorming. "Add collaboration" on a single-user app is NOT clearly bounded.
"I already explored the codebase, I can just list options"	⛔ STOP. `/opsx:explore` answers "what exists," not "what to build." After explore, re-run Boundedness Check. If the task is still fuzzy → `superpowers:brainstorming` . Presenting a menu of options is NOT a substitute for Socratic design.
"The user said '完善' or 'improve' — that's clear enough"	Vague verbs imply the user trusts you to figure out WHAT to improve. That's exactly what brainstorming is for. Explore the codebase → brainstorm what should change → THEN propose.
"Brainstorming says go to writing-plans"	⛔ OVERRIDDEN. sdd-workflow pipeline: brainstorming → `/opsx:propose` → review → verify → THEN writing-plans.
"I'll write the design doc — that's the spec"	`docs/superpowers/specs/` is transient. `/opsx:propose` creates permanent `openspec/changes/<name>/` artifacts.
"The brainstorming design IS the OpenSpec design"	No. Brainstorming output is INPUT to `/opsx:propose` . It must be translated into the 4 OpenSpec artifacts.

All of these mean: follow the SDD process. No shortcuts.

出现以下想法时请停止——您在找借口跳过SDD流程：

想法	实际情况
"这个很简单，我不需要规范"	简单变更也会引发复杂bug。一份5行的proposal.md能节省数小时时间。
"我会先写代码再补规范"	事后补的规范描述的是您已构建的内容，而非需求。
"规范在聊天记录里"	聊天记录会消失，文件会留存。请写下来。
"我已经知道要构建什么了"	知道不代表已通过审查。规范是共识的体现。
"规范拖慢我的进度"	因预期不一致导致的返工更耗时。
"这只是个原型"	原型会变成生产环境代码。现在写规范能避免后续麻烦。
"我先浏览一下代码库"	使用 `/opsx:explore` ——结构化探索，而非漫无目的浏览。
"我记得这个代码库的结构"	代码会演进，您的记忆已过时。请阅读规范。
"这个任务边界明确，跳过头脑风暴"	⛔ 停止。运行边界检查。任务是否引入了当前数据模型中不存在的概念？是否有多种有效解读？如果是 → 进行头脑风暴。单用户应用中“添加协作功能”不属于边界明确的任务。
"我已经探索了代码库，可以直接列出选项"	⛔ 停止。 `/opsx:explore` 回答“现有什么”，而非“要构建什么”。探索后重新运行边界检查。如果任务仍模糊 → `superpowers:brainstorming` 。提供选项菜单不能替代苏格拉底式设计。
"用户说‘完善’或‘改进’——这足够明确了"	模糊动词意味着用户信任您来确定要改进什么。这正是头脑风暴的用途。探索代码库 → 头脑风暴确定变更内容 → 然后提出提案。
"头脑风暴说要进入writing-plans"	⛔ 已被覆盖。sdd-workflow流水线：头脑风暴 → `/opsx:propose` → 审查 → 验证 → 再进入writing-plans。
"我写设计文档——这就是规范"	`docs/superpowers/specs/` 是临时路径。 `/opsx:propose` 创建的 `openspec/changes/<name>/` 工件是永久的。
"头脑风暴的设计就是OpenSpec的设计"	不是。头脑风暴的输出是 `/opsx:propose` 的输入。必须将其转换为4个OpenSpec工件。

所有这些想法都意味着：遵循SDD流程，不要走捷径。

Skill Priority

技能优先级

When multiple tools could apply to a development task:

Classification first — Use the decision tree. One-line fix? Bug? Behavior change?
Exploration before specification —
```
/opsx:explore
```
to read code.
```
/opsx:propose
```
to generate artifacts. Never invert.
Review before execution — Steps 3-4 gate. Specs must be reviewed before any code.
Plan before implementing — Step 5:
```
writing-plans
```
refines tasks.md. Save to
```
openspec/changes/<name>/plan.md
```
.
TDD during execution — Step 6:
```
/opsx:apply
```
+
```
@test-driven-development
```
. RED → GREEN → REFACTOR.
Verify before claiming — Step 8:
```
@verification-before-completion
```
with fresh evidence. Then Step 9:
```
/opsx:archive
```
.

当多个工具可应用于同一开发任务时：

先分类——使用决策树。是单行修复？bug？行为变更？
先探索再规范——用
```
/opsx:explore
```
读取代码，用
```
/opsx:propose
```
生成工件。切勿颠倒顺序。
先审查再执行——步骤3-4是关卡。规范必须先经过审查才能编写任何代码。
先规划再实现——步骤5：
```
writing-plans
```
细化tasks.md。保存至
```
openspec/changes/<name>/plan.md
```
。
执行时采用TDD——步骤6：
```
/opsx:apply
```
+
```
@test-driven-development
```
。RED → GREEN → REFACTOR。
先验证再交付——步骤8：
```
@verification-before-completion
```
并提供新的验证证据。然后执行步骤9：
```
/opsx:archive
```
。

Skill Types

技能类型

Rigid — Follow exactly. Don't adapt away the sequence:

```
/opsx:propose
```
,
```
/opsx:apply
```
,
```
/opsx:archive
```
— CLI tools with defined behavior
```
@test-driven-development
```
— RED → GREEN → REFACTOR, no shortcuts
```
@systematic-debugging
```
— Root cause before fixes
```
@verification-before-completion
```
— Fresh evidence required
sdd-workflow
(this skill) — Follow the routing exactly

Flexible — Adapt principles to context:

```
@brainstorming
```
— Socratic design, adapt depth to complexity (but terminal routing is OVERRIDDEN by sdd-workflow)
```
@writing-plans
```
— Task granularity scales with feature complexity
```
/opsx:explore
```
— Depth of exploration matches uncertainty level

刚性技能——严格遵循。不得调整顺序：

```
/opsx:propose
```
、
```
/opsx:apply
```
、
```
/opsx:archive
```
——行为固定的CLI工具
```
@test-driven-development
```
——RED → GREEN → REFACTOR，无捷径
```
@systematic-debugging
```
——先找根因再修复
```
@verification-before-completion
```
——必须提供新的验证证据
sdd-workflow
（本技能）——严格遵循路由规则

柔性技能——可根据上下文调整原则：

```
@brainstorming
```
——苏格拉底式设计，可根据复杂度调整深度（但终端路由被sdd-workflow覆盖）
```
@writing-plans
```
——任务粒度可随功能复杂度调整
```
/opsx:explore
```
——探索深度与不确定性匹配

Related Skills

User Instructions

用户指令

Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows. The SDD process is the HOW — it exists to ensure alignment before code, not to slow you down.

If you want to bypass a step (skip review, write code directly, skip the spec), say so explicitly. The user is in control. The skill routes, the user decides.

指令说明要做什么，而非怎么做。“添加X”或“修复Y”并不意味着跳过工作流。SDD流程是实现方式——它的存在是为了确保编写代码前达成共识，而非拖慢进度。

如果您想跳过某个步骤（跳过审查、直接写代码、跳过规范），请明确说明。用户拥有控制权。本技能负责路由，用户做决定。