@gavin-hjw/sddflow 0.3.2 → 0.3.4

package/README.md

@@ -2,7 +2,16 @@
 
 [中文文档](./README.zh-CN.md)
 
-OpenSpec + Superpowers workflow orchestrator — bridging requirements specs and engineering execution, eliminating the format gap.
+## About
+
+sddflow is an OpenSpec + Superpowers workflow orchestrator. It connects **design exploration → spec documents → implementation → verification and archive** into one resumable flow, bridging the format gap between requirements specs and engineering execution.
+
+**Before use, you must complete two steps:**
+
+1. **Install dependencies** — OpenSpec CLI, Superpowers plugin, and its 6 required skills (see **Dependencies** below)
+2. **Initialize the project** — run `sddflow init` in the target project directory to check dependencies, run `openspec init`, and generate sddflow skills in your AI tool
+
+Until init succeeds, `/sddflow` commands are not available in the AI tool. Each project needs init once; after upgrading the npm package, run `sddflow update` to regenerate skills.
 
 ## Installation
 
@@ -10,143 +19,183 @@ OpenSpec + Superpowers workflow orchestrator — bridging requirements specs and
 npm install -g @gavin-hjw/sddflow
 ```
 
-## Usage
-
-### Initialize a project
+Initialize in your project directory:
 
 ```bash
 cd your-project
 sddflow init --tools claude
 ```
 
-`init` will automatically:
-1. Detect and guide OpenSpec CLI installation
-2. Detect Superpowers and show install instructions
-3. Check if OpenSpec is initialized in the project
-4. Generate sddflow skills to the selected tools' local skill directories, such as `.claude/skills/sddflow/`, `.codex/skills/sddflow/`, `.cursor/skills/sddflow/`, or `.opencode/commands/sddflow/`
-
-Supported tools: `claude`, `codex`, `cursor`, `opencode` (comma-separated, e.g. `--tools claude,codex`)
+Supported tools: `claude`, `codex`, `cursor`, `opencode` (comma-separated, e.g. `--tools claude,cursor`).
 
-### Install skills globally
+Install skills globally (shared across projects):
 
 ```bash
-sddflow init --tools claude -g
-sddflow init --tools claude,codex,cursor,opencode --global
+sddflow init --tools claude --global
 ```
 
-With `-g` / `--global`, `sddflow` installs skills under the selected tools' home directories:
-
-| Tool | Global skill path |
-|------|-------------------|
-| `claude` | `~/.claude/skills/sddflow/` |
-| `codex` | `~/.codex/skills/sddflow/` |
-| `cursor` | `~/.cursor/skills/sddflow/` |
-| `opencode` | `~/.opencode/commands/sddflow/` |
-
-### Check status
+After upgrading the npm package, regenerate project skills:
 
 ```bash
-sddflow status
+sddflow update
 ```
 
-Shows dependency installation status and active changes in the project.
+Run `sddflow status` to check dependency readiness, OpenSpec init integrity, and the current stage of each active change.
 
-### Update skills
+## Dependencies
 
-```bash
-sddflow update
-```
+`sddflow init` checks each item and aborts with install guidance if anything is missing.
 
-Re-generates project skills after upgrading the npm package.
+| Dependency | Role | Install |
+|------------|------|---------|
+| **OpenSpec CLI** | Generate and manage structured specs | `npm install -g @fission-ai/openspec@latest` |
+| **OpenSpec skill integration** | Invoke OpenSpec from AI tools | Run automatically via `openspec init --tools <tools>` during `sddflow init` |
+| **Superpowers plugin** | Implementation planning and build execution | Claude Code: `/plugin install superpowers@claude-plugins-official`; Cursor: Settings → Plugins → superpowers |
 
-## Workflow Commands
+Superpowers must also provide these 6 skills: `brainstorming`, `writing-plans`, `subagent-driven-development`, `test-driven-development`, `verification-before-completion`, `finishing-a-development-branch`.
 
-Canonical usage is `/sddflow <phase>`. For Claude Code, Codex, and Cursor,
-`sddflow` also generates visible phase aliases such as `/sddflow-spec` or
-`$sddflow-spec` so typing `sddflow` in the command/skill picker surfaces the
-available phases. OpenCode keeps its native command-tree form under
-`/sddflow/spec`, `/sddflow/build`, and so on.
+## Workflow
 
-| Command | Phase | Description |
-|---------|-------|-------------|
-| `/sddflow proposal` | proposal | Lightweight capture — 3-5 questions to converge on requirements |
-| `/sddflow brainstorming` | brainstorming | Deep design — multi-round tradeoff exploration |
-| `/sddflow spec` | spec | Call OpenSpec to generate specs + auto-translate to plan-ready.md |
-| `/sddflow amend` | amend | Revise requirements/specs before close and update plan-ready.md |
-| `/sddflow build` | build | Call Superpowers to execute implementation |
-| `/sddflow close` | close | Verify consistency + archive |
+Run these steps in order inside your AI tool. Canonical usage is `/sddflow <phase>`; you can also type `/sddflow` to auto-route based on the current change state.
 
-## Dependency Strategy
+Claude / Codex / Cursor expose phase aliases (e.g. `/sddflow-brainstorming`); OpenCode uses forms like `/sddflow/brainstorming`.
 
 ```
-Best with: OpenSpec + Superpowers
-Works without them: yes, with manual-file fallback
+brainstorming → spec → build → close
+                  ↑      │
+                  └── amend (on requirement change, as needed)
 ```
 
-| Dependency | Install | Fallback when missing |
-|------------|---------|----------------------|
-| OpenSpec | `npm install -g @fission-ai/openspec@latest` | Manually create `openspec/changes/` directories and files |
-| Superpowers | `/plugin install superpowers@claude-plugins-official` | Manually break down plan-ready.md steps in build phase |
+---
 
-### Dual-layer dependency check
+### Step 1: brainstorming — explore requirements and design
 
-| Layer | Mechanism | When missing |
-|-------|-----------|-------------|
-| **Init time** | Detect OpenSpec CLI from `PATH`; detect project OpenSpec in `./openspec/`; detect Superpowers in the selected tools' local/global skill dirs | Non-blocking, skills still generated |
-| **Runtime** | Dependency check injected into SKILL.md | Build phase falls back to manual step-by-step execution |
+**What you do**
 
-## Architecture
+1. Type `/sddflow brainstorming` and describe the change you want
+2. Answer AI follow-up questions (one at a time): user scenarios, constraints, tradeoffs, boundaries, acceptance criteria
+3. Review 2–3 proposed approaches and pick a direction
+4. Confirm the design section by section, then explicitly reply "confirmed" / "OK"
 
-```
-User Requirements
-   │
-   ├── Quick ──→ /sddflow proposal ──┐
-   │           3-5 questions          │
-   │                                  ├─→ proposal.md
-   └── Deep ───→ /sddflow brainstorming ─┘ (openspec/changes/<name>/)
-               Multi-round exploration
-                                     │
-                          ┌──────────▼───────────┐
-                          │  /sddflow spec         │
-                          │  OpenSpec generates     │
-                          └──────────┬───────────┘
-                                     │
-                          ┌──────────▼───────────┐
-                          │   Translation Layer    │
-                          │  Requirements → Eng    │
-                          └──────────┬───────────┘
-                                     │
-                                plan-ready.md
-                                     │
-                          ┌──────────▼───────────┐
-                          │  /sddflow build       │
-                          │  Superpowers execution │
-                          │  TDD + checkpoint      │
-                          └──────────┬───────────┘
-                                     │
-                          ┌──────────▼───────────┐
-                          │  /sddflow amend       │
-                          │  Requirement revision  │
-                          │  (only when needed)    │
-                          └──────────┬───────────┘
-                                     │
-                          ┌──────────▼───────────┐
-                          │  /sddflow close       │
-                          │  Verify + archive      │
-                          └──────────────────────┘
-```
+**Output**
+
+- `openspec/changes/<name>/proposal.md`
+
+**What you verify**
+
+- [ ] `openspec/changes/<name>/` directory exists
+- [ ] `proposal.md` matches what you confirmed: background, scenarios, approach, scope boundaries, acceptance criteria
+- [ ] **No code changes** in this phase
+
+**Then** → proceed to Step 2
+
+---
+
+### Step 2: spec — generate specs and implementation plan
+
+**What you do**
+
+1. Type `/sddflow spec`
+2. If multiple active changes exist, tell the AI which one to spec
+3. Review the spec summary (proposal, design, specs, tasks) and confirm or request edits
+4. Wait for OpenSpec artifacts, the translation layer, and the detailed implementation plan
+
+**Output**
+
+- `openspec/changes/<name>/specs/` (spec deltas)
+- `openspec/changes/<name>/tasks.md`
+- `openspec/changes/<name>/design.md` (optional)
+- `openspec/changes/<name>/plan-ready.md` (engineering translation)
+- `docs/superpowers/plans/YYYY-MM-DD-<name>.md` (detailed plan)
+
+**What you verify**
+
+- [ ] `openspec validate <name> --strict` passes (AI should run this; you can re-run it)
+- [ ] `specs/` is non-empty and `tasks.md` exists
+- [ ] Both `plan-ready.md` and the superpowers plan file exist
+- [ ] All three task documents (`tasks.md`, `plan-ready.md`, superpowers plan) use `- [ ]` checkboxes with matching Task numbers
+- [ ] No `TODO`, `TBD`, or similar placeholders in plan files
+- [ ] **No code changes** in this phase
+
+**Then** → proceed to Step 3
+
+---
+
+### Step 3: build — execute implementation
+
+**What you do**
+
+1. Type `/sddflow build`
+2. If the AI reports missing pre-flight files, go back to Step 2
+3. Say "continue" anytime to resume from the last checkpoint
+4. Monitor Task-by-Task execution with TDD (tests before implementation)
+
+**Output**
+
+- Code and test files
+- Plan checkboxes gradually change from `[ ]` to `[x]`
+
+**What you verify**
+
+- [ ] Before build starts, AI confirms: `proposal.md`, `specs/`, `tasks.md`, `plan-ready.md`, and superpowers plan all exist
+- [ ] If **requirements or acceptance criteria change**, do not edit code directly — switch to amend (below)
+- [ ] Build is complete when all Task and Step checkboxes are `[x]`
+
+**Then** → proceed to Step 4
+
+---
+
+### (As needed) amend — revise requirements
+
+**When to use**
+
+- Requirements, boundaries, or acceptance criteria change during build
+- Specs are incomplete before close (not "code doesn't match existing spec")
+
+**What you do**
+
+1. Type `/sddflow amend` and describe what to change
+2. Confirm updates to `proposal.md`, `specs/`, `tasks.md`, `plan-ready.md`, and the implementation plan
+3. Type `/sddflow build` to continue implementation
+
+**What you verify**
+
+- [ ] OpenSpec documents and all three task documents are in sync
+- [ ] `openspec validate <name> --strict` still passes (if specs changed)
+- [ ] amend should **not** modify code directly (unless updating plan documents as part of the amend flow)
+
+**Then** → return to Step 3
+
+---
+
+### Step 4: close — verify and archive
+
+**What you do**
+
+1. Confirm build is fully complete (all checkboxes `[x]`)
+2. Type `/sddflow close`
+3. Follow prompts on whether to run a final code review
+4. Review verification results and confirm archive
+
+**What the AI runs**
+
+- Full test suite and build (must show actual passing output)
+- Cross-check `tasks.md`, `plan-ready.md`, and specs against implementation
+- `openspec validate <name> --strict` for spec consistency
+- OpenSpec Archive to move the change into `openspec/changes/archive/`
 
-## Acknowledgments
+**What you verify**
 
-sddflow orchestrates two open-source projects:
+- [ ] All tests pass (0 failures)
+- [ ] Every task has implementation and test evidence
+- [ ] No CRITICAL spec inconsistencies
+- [ ] After archive, `openspec/changes/<name>/` is under `archive/`
+- [ ] `openspec/specs/` is updated if the change merged spec deltas
 
-| Project | Repository | License | Usage |
-|---------|-----------|---------|-------|
-| [OpenSpec](https://github.com/Fission-AI/OpenSpec) | `@fission-ai/openspec` | MIT | Generates structured spec files (proposal.md, design.md, specs/, tasks.md). sddflow calls its CLI and reads its output format. |
-| [Superpowers](https://github.com/obra/superpowers) | `superpowers` plugin | MIT | Provides `writing-plans` skill for detailed implementation planning. sddflow delegates build-phase execution to its workflow. |
+**Done** → change complete; start a new change from Step 1
 
-sddflow is a **standalone orchestrator** — it does not bundle, fork, or embed code from either project. Dependencies are detected at init/runtime, with manual fallback when either is not installed.
+---
 
-## License
+### Resuming
 
-MIT
+Follow-up messages that refine scope, answer confirmation questions, or say "continue" stay in the **current phase** — they do not auto-enter build. Code changes only happen after you explicitly run `/sddflow build` or auto-routing determines the build phase.

package/README.zh-CN.md

@@ -2,7 +2,16 @@
 
 [English](./README.md)
 
-OpenSpec + Superpowers 工作流协调器，串联需求规格与工程执行，消除格式鸿沟。
+## 介绍
+
+sddflow 是 OpenSpec + Superpowers 的工作流协调器，把「需求与设计 → 规格文档 → 代码实现 → 验证归档」串成一条可续接的流程，消除需求规格与工程执行之间的格式鸿沟。
+
+**使用前必须完成两件事：**
+
+1. **安装依赖** — OpenSpec CLI、Superpowers 插件及其 6 个必需 skills（见下方「依赖」）
+2. **初始化项目** — 在目标项目目录执行 `sddflow init`，检测依赖、运行 `openspec init`，并在 AI 工具中生成 sddflow skills
+
+初始化完成前，AI 工具里无法使用 `/sddflow` 工作流。每个项目只需 init 一次；升级 sddflow 包后运行 `sddflow update` 重新生成 skills 即可。
 
 ## 安装
 
@@ -10,142 +19,183 @@ OpenSpec + Superpowers 工作流协调器，串联需求规格与工程执行，
 npm install -g @gavin-hjw/sddflow
 ```
 
-## 使用
-
-### 初始化项目
+在项目目录初始化：
 
 ```bash
 cd your-project
 sddflow init --tools claude
 ```
 
-`init` 会自动：
-1. 检测并引导安装 OpenSpec CLI
-2. 检测 Superpowers 并提示安装方式
-3. 检测项目 OpenSpec 初始化状态
-4. 生成 sddflow skills 到所选工具的项目级 skill 目录，如 `.claude/skills/sddflow/`、`.codex/skills/sddflow/`、`.cursor/skills/sddflow/` 或 `.opencode/commands/sddflow/`
-
-支持的工具：`claude`、`codex`、`cursor`、`opencode`（逗号分隔，如 `--tools claude,codex`）
+支持的工具：`claude`、`codex`、`cursor`、`opencode`（逗号分隔，如 `--tools claude,cursor`）。
 
-### 安装到全局 skills
+安装到全局 skills 目录（所有项目共用）：
 
 ```bash
-sddflow init --tools claude -g
-sddflow init --tools claude,codex,cursor,opencode --global
+sddflow init --tools claude --global
 ```
 
-加 `-g` / `--global` 后，`sddflow` 会把 skills 安装到所选工具的全局目录：
-
-| 工具 | 全局 skill 路径 |
-|------|-----------------|
-| `claude` | `~/.claude/skills/sddflow/` |
-| `codex` | `~/.codex/skills/sddflow/` |
-| `cursor` | `~/.cursor/skills/sddflow/` |
-| `opencode` | `~/.opencode/commands/sddflow/` |
-
-### 查看状态
+升级 npm 包后，在项目目录重新生成 skills：
 
 ```bash
-sddflow status
+sddflow update
 ```
 
-显示依赖安装状态和项目中的活跃变更。
+可用 `sddflow status` 查看依赖是否就绪、OpenSpec 是否初始化完整，以及当前活跃变更处于哪个阶段。
 
-### 更新 skills
+## 依赖
 
-```bash
-sddflow update
-```
+`sddflow init` 会逐项检测，任一缺失则中止并给出安装指引。
 
-升级 npm 包后运行，重新生成项目内的 skills 文件。
+| 依赖 | 作用 | 安装方式 |
+|------|------|----------|
+| **OpenSpec CLI** | 生成与管理结构化规格 | `npm install -g @fission-ai/openspec@latest` |
+| **OpenSpec Skill 集成** | 在 AI 工具中调用 OpenSpec 流程 | 由 `sddflow init` 自动执行 `openspec init --tools <tools>` |
+| **Superpowers 插件** | 实现计划与 build 阶段执行 | Claude Code：`/plugin install superpowers@claude-plugins-official`；Cursor：Settings → Plugins → superpowers |
 
-## 工作流命令
+Superpowers 还需具备以下 6 个 skills：`brainstorming`、`writing-plans`、`subagent-driven-development`、`test-driven-development`、`verification-before-completion`、`finishing-a-development-branch`。
 
-规范调用方式是 `/sddflow <阶段>`。为了改善补全体验，Claude Code、
-Codex 和 Cursor 会额外生成可见的阶段别名，例如 `/sddflow-spec` 或
-`$sddflow-spec`，这样在命令/skill 选择器里输入 `sddflow` 时能看到可用阶段。
-OpenCode 保持原生命令树形式，例如 `/sddflow/spec`、`/sddflow/build`。
+## 工作流
 
-| 命令 | 阶段 | 说明 |
-|------|------|------|
-| `/sddflow proposal` | proposal | 轻量提问，3-5 问快速收敛需求 |
-| `/sddflow brainstorming` | brainstorming | 深度设计，多轮方案探索 |
-| `/sddflow spec` | spec | 调用 OpenSpec 生成规格 + 自动翻译 |
-| `/sddflow amend` | amend | close 前修订需求/规格并更新 plan-ready.md |
-| `/sddflow build` | build | 调用 Superpowers 执行实现 |
-| `/sddflow close` | close | 验证一致性 + 归档 |
+在 AI 工具中按顺序执行。规范调用方式为 `/sddflow <阶段>`；也可输入 `/sddflow` 让系统根据当前变更状态自动路由。
 
-## 依赖策略
+Claude / Codex / Cursor 提供阶段别名（如 `/sddflow-brainstorming`）；OpenCode 使用 `/sddflow/brainstorming` 等形式。
 
 ```
-Best with: OpenSpec + Superpowers
-Works without them: yes, with manual-file fallback
+brainstorming → spec → build → close
+                  ↑      │
+                  └── amend（需求变更时，按需插入）
 ```
 
-| 依赖 | 安装方式 | 缺失时降级 |
-|------|----------|-----------|
-| OpenSpec | `npm install -g @fission-ai/openspec@latest` | 手动创建 `openspec/changes/` 目录和文件 |
-| Superpowers | `/plugin install superpowers@claude-plugins-official` | build 阶段手动拆解 plan-ready.md 步骤执行 |
+---
 
-### 双层依赖保障
+### 第一步：brainstorming — 需求与设计探索
 
-| 层 | 机制 | 缺失时 |
-|----|------|--------|
-| **init 时** | 从 `PATH` 检测 OpenSpec CLI；从 `./openspec/` 检测当前项目 OpenSpec；从所选工具的本地/全局 skill 目录检测 Superpowers | 不阻断，继续生成 skills |
-| **运行时** | SKILL.md 注入依赖检测段 | build 阶段降级为手动拆解步骤执行 |
+**你做什么**
 
-## 架构
+1. 在 AI 工具中输入 `/sddflow brainstorming`，描述你想做的变更
+2. 回答 AI 的追问（目的一次只问一个）：用户场景、约束、方案取舍、边界、验收标准
+3. 阅读 AI 提出的 2–3 种方案，选定方向
+4. 逐段确认设计（架构、数据流、错误处理等），最后明确回复「确认」
 
-```
-用户需求
-   │
-   ├── 轻量 ──→ /sddflow proposal ──┐
-   │          3-5问快速收敛          │
-   │                                 ├─→ proposal.md
-   └── 深度 ──→ /sddflow brainstorming ─┘ (openspec/changes/<name>/)
-               多轮方案探索
-                                     │
-                          ┌──────────▼───────────┐
-                          │  /sddflow spec        │
-                          │  OpenSpec 生成规格      │
-                          └──────────┬───────────┘
-                                     │
-                          ┌──────────▼───────────┐
-                          │   翻译层 (核心)        │
-                          │  需求视角 → 工程视角    │
-                          └──────────┬───────────┘
-                                     │
-                                plan-ready.md
-                                     │
-                          ┌──────────▼───────────┐
-                          │  /sddflow build       │
-                          │  Superpowers 执行      │
-                          │  TDD 铁律 + 断点恢复   │
-                          └──────────┬───────────┘
-                                     │
-                          ┌──────────▼───────────┐
-                          │  /sddflow amend      │
-                          │  需求变更修订          │
-                          │  （仅需要时）           │
-                          └──────────┬───────────┘
-                                     │
-                          ┌──────────▼───────────┐
-                          │  /sddflow close       │
-                          │  验证一致性 + 归档      │
-                          └──────────────────────┘
-```
+**产出**
+
+- `openspec/changes/<变更名>/proposal.md`
+
+**你需要检查**
+
+- [ ] `openspec/changes/<变更名>/` 目录已创建
+- [ ] `proposal.md` 内容与你确认的设计一致：背景、场景、方案、范围边界、验收标准
+- [ ] 此阶段**不应**出现任何代码改动
+
+**通过后** → 进入第二步
+
+---
+
+### 第二步：spec — 生成规格与实现计划
+
+**你做什么**
+
+1. 输入 `/sddflow spec`
+2. 若存在多个活跃变更，告诉 AI 要对哪一个生成规格
+3. 阅读 AI 展示的规格摘要（提案、设计、specs、tasks），确认或提出修改
+4. 确认后等待 AI 完成 OpenSpec 制品、翻译层和详细实现计划
+
+**产出**
+
+- `openspec/changes/<变更名>/specs/`（规格 delta）
+- `openspec/changes/<变更名>/tasks.md`
+- `openspec/changes/<变更名>/design.md`（按需，非必须）
+- `openspec/changes/<变更名>/plan-ready.md`（工程视角翻译）
+- `docs/superpowers/plans/YYYY-MM-DD-<变更名>.md`（详细实现计划）
+
+**你需要检查**
+
+- [ ] `openspec validate <变更名> --strict` 通过（AI 应已执行，你可自行复验）
+- [ ] `specs/` 非空，`tasks.md` 存在
+- [ ] `plan-ready.md` 与 `docs/superpowers/plans/` 下计划文件均存在
+- [ ] 三份任务文档（`tasks.md`、`plan-ready.md`、superpowers plan）中任务项均含 `- [ ]` checkbox，且 Task 序号一一对应
+- [ ] 计划文件中无 `TODO`、`TBD` 等占位符
+- [ ] 此阶段**不应**出现任何代码改动
+
+**通过后** → 进入第三步
+
+---
+
+### 第三步：build — 执行实现
+
+**你做什么**
+
+1. 输入 `/sddflow build`
+2. 若 AI 提示前置文件缺失，回到第二步补齐 spec
+3. 实现过程中可随时说「继续」让 AI 从断点恢复
+4. 关注 AI 按 plan 逐 Task 执行，每个 Task 遵循 TDD（先写测试再写实现）
+
+**产出**
+
+- 代码与测试文件
+- plan 文件中 checkbox 逐步从 `[ ]` 变为 `[x]`
+
+**你需要检查**
+
+- [ ] build 开始前，AI 已校验：`proposal.md`、`specs/`、`tasks.md`、`plan-ready.md`、superpowers plan 均存在
+- [ ] 实现过程中若发现**需求或验收条件变了**，不要直接改代码，应切到 amend（见下方）
+- [ ] 全部 Task 与 Step 的 checkbox 均为 `[x]` 时，build 才算完成
+
+**通过后** → 进入第四步
+
+---
+
+### （按需）amend — 需求变更修订
+
+**何时使用**
+
+- build 中发现原需求遗漏、边界或验收条件需调整
+- close 前发现规格本身不完整（不是代码没按 spec 实现）
+
+**你做什么**
+
+1. 输入 `/sddflow amend`，说明要改什么
+2. 确认 AI 对 `proposal.md`、`specs/`、`tasks.md`、`plan-ready.md`、实现计划的修订
+3. 修订完成后输入 `/sddflow build` 继续实现
+
+**你需要检查**
+
+- [ ] 变更已同步到 OpenSpec 文档与三份任务文档
+- [ ] `openspec validate <变更名> --strict` 仍能通过（若 specs 有改动）
+- [ ] amend 阶段**不应**直接改代码（除非 AI 明确是在 amend 流程中更新计划文档）
+
+**完成后** → 回到第三步继续 build
+
+---
+
+### 第四步：close — 验证与归档
+
+**你做什么**
+
+1. 确认 build 已全部完成（所有 checkbox 为 `[x]`）
+2. 输入 `/sddflow close`
+3. 按 AI 提示确认是否执行代码审查
+4. 阅读验证结果，确认归档
+
+**AI 会执行**
+
+- 运行测试套件与构建（必须看到实际通过输出）
+- 对照 `tasks.md`、`plan-ready.md` 与 specs 验证实现完整性
+- `openspec validate <变更名> --strict` 规格一致性校验
+- 调用 OpenSpec Archive 将变更移入 `openspec/changes/archive/`
 
-## 致谢
+**你需要检查**
 
-sddflow 编排了以下两个开源项目：
+- [ ] 测试全部通过（0 failures）
+- [ ] 每条 task 有对应实现与测试证据
+- [ ] 无 CRITICAL 级别的规格不一致问题
+- [ ] 归档后 `openspec/changes/<变更名>/` 已移至 `archive/` 目录
+- [ ] `openspec/specs/` 已同步更新（若本次变更涉及规格合并）
 
-| 项目 | 仓库 | 许可证 | 使用方式 |
-|------|------|--------|----------|
-| [OpenSpec](https://github.com/Fission-AI/OpenSpec) | `@fission-ai/openspec` | MIT | 生成结构化规格文件（proposal.md、design.md、specs/、tasks.md）。sddflow 调用其 CLI 并读取其输出格式。 |
-| [Superpowers](https://github.com/obra/superpowers) | `superpowers` 插件 | MIT | 提供 `writing-plans` skill 用于生成详细实现计划。sddflow 在 build 阶段委托其工作流执行。 |
+**完成后** → 本次变更结束；新需求从第一步重新开始
 
-sddflow 是**独立编排器** — 不捆绑、不分叉、不嵌入任何项目的代码。依赖在 init/运行时检测，任一缺失时降级为手动模式。
+---
 
-## License
+### 续接说明
 
-MIT
+对话中补充范围、回答确认问题或说「继续」时，默认**保持当前阶段**，不会自动跳到 build。只有显式输入 `/sddflow build` 或在状态检测判定为 build 阶段时，才应修改代码。

package/bin/sddflow.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { run } from '../dist/cli/index.js';