@specpow/framework 0.2.2 → 0.4.0

package/.specpow/hooks/session-start

@@ -42,7 +42,7 @@ if [ -f "${PLUGIN_ROOT}/../openspec/specs" ] 2>/dev/null || [ -d "${PLUGIN_ROOT}
   openspec_context="\nOpenSpec structure detected in this project. Follow the spec-driven workflow:\n1. Explore → planning-explore skill\n2. Propose → planning-propose skill\n3. Write Specs/Design/Tasks → planning-write-* skills\n4. Implement → execution-* skills (SDD engine)\n5. Verify → execution-verification-before-completion\n6. Archive → specpow archive\n${active_changes}\n"
 fi
 
-session_context="<EXTREMELY_IMPORTANT>\nYou have specpow — a spec-powered AI development framework. It combines OpenSpec's spec-driven planning with Superpowers' subagent-driven execution.\n\n**Below is the full content of your 'specpow:meta-using-skills' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_skills_escaped}\n\n${openspec_context}\n\nAvailable skill categories:\n- Planning: planning-explore, planning-propose, planning-write-plans, planning-write-specs, planning-write-design\n- Execution: planning-apply-change, execution-subagent-driven-dev, execution-tdd, execution-systematic-debugging, execution-parallel-agents\n- Quality: execution-requesting-review, execution-receiving-review, execution-verification-before-completion, planning-verify-change\n- Business: business-java-codegen, business-ui-codegen, business-test-gen, business-code-review, business-db-design, business-prd-writer, business-deploy-check\n\nRemember: Check for relevant skills BEFORE any action.\n</EXTREMELY_IMPORTANT>"
+session_context="<EXTREMELY_IMPORTANT>\nYou have specpow — a spec-powered AI development framework. It combines OpenSpec's spec-driven planning with Superpowers' subagent-driven execution.\n\n**Below is the full content of your 'specpow:meta-using-skills' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_skills_escaped}\n\n${openspec_context}\n\nAvailable skill categories:\n- Planning: planning-explore, planning-propose, planning-write-plans, planning-write-specs, planning-write-design\n- Execution: planning-apply-change, execution-subagent-driven-dev, execution-tdd, execution-systematic-debugging, execution-parallel-agents\n- Quality: execution-requesting-review, execution-receiving-review, execution-verification-before-completion, planning-verify-change\n- Business: business-java-codegen, business-ui-codegen, business-test-gen, business-code-review, business-db-design, business-prd-writer, business-deploy-check\n- CLI Router: cli-router — maps user intent to SpecPow CLI commands\n\nSpecPow CLI quick reference (execute via Bash tool):\n| Command | Purpose |\n|---------|----------|\n| specpow status | View current change status |\n| specpow explore \"<topic>\" | Socratic requirement exploration (interactive, run in terminal) |\n| specpow propose <name> | Create change proposal |\n| specpow apply | Execute implementation |\n| specpow verify | Verify changes |\n| specpow archive | Archive changes |\n| specpow debug \"<desc>\" | Systematic debugging |\n| specpow doctor | Project diagnostics |\n\nUsers can also use slash commands: /specpow-explore, /specpow-propose, /specpow-apply, /specpow-verify, /specpow-archive, /specpow-status\n\nRemember: Check for relevant skills BEFORE any action.\n</EXTREMELY_IMPORTANT>"
 
 # Output context injection as JSON
 # Cursor hooks expect additional_context (snake_case)

package/.specpow/skills/cli-router/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: cli-router
+version: 1.0.0
+trigger: on-demand
+description: SpecPow CLI 命令路由 — 将用户意图映射到 CLI 命令执行
+---
+
+# SpecPow CLI 路由技能
+
+当用户请求执行 SpecPow CLI 命令时，按以下规则执行。
+
+## 铁律
+
+1. **所有 CLI 命令通过 Bash 工具执行**，不在对话中模拟输出
+2. **先检查状态**：执行任何命令前先 `specpow status`
+3. **展示完整输出**：将命令输出完整展示给用户
+4. **链式引导**：执行完一步后建议下一步
+
+## 意图 → 命令映射表
+
+| 用户说 | 执行命令 |
+|--------|---------|
+| "探索需求" / "explore" / "specpow explore" | `specpow explore "主题"` |
+| "创建提案" / "propose" / "specpow propose" | `specpow propose <name>` |
+| "执行" / "apply" / "实现" / "specpow apply" | `specpow apply` |
+| "验证" / "verify" / "检查" / "specpow verify" | `specpow verify` |
+| "归档" / "archive" / "specpow archive" | `specpow archive` |
+| "状态" / "status" / "specpow status" | `specpow status` |
+| "调试" / "debug" / "specpow debug" | `specpow debug "描述"` |
+| "doctor" / "诊断" / "specpow doctor" | `specpow doctor` |
+| "review" / "审查" / "specpow review" | `specpow review` |
+| "schemas" / "schema 列表" | `specpow schemas` |
+| "更新" / "update" / "specpow update" | `specpow update` |
+| "配置" / "config" / "specpow config" | `specpow config` |
+
+## 执行规则
+
+### 交互式命令处理
+
+`specpow explore` 是交互式命令（使用 readline），在 Claude Code 的 Bash 工具中无法交互。
+遇到此命令时：
+1. 告诉用户需要在终端中运行：`specpow explore "主题"`
+2. 或者尝试使用 `--json` 标志获取非交互式输出（如果支持）
+3. 如果用户坚持在 Claude Code 中执行，使用苏格拉底式提问手动模拟探索流程
+
+### 非交互式命令
+
+其他所有命令（propose/apply/verify/archive/status）都是非交互式的，直接通过 Bash 执行：
+
+```bash
+# 示例：执行状态检查
+specpow status
+
+# 示例：创建变更提案
+specpow propose add-login
+
+# 示例：使用特定 schema
+specpow propose fix-bug --schema bug-fix
+
+# 示例：验证变更
+specpow verify --change add-login
+
+# 示例：归档变更
+specpow archive --change add-login
+```
+
+### 错误处理
+
+命令失败时：
+1. 展示完整错误信息
+2. 分析可能的原因
+3. 建议解决方案
+4. 如果适用，运行 `specpow doctor` 进行诊断
+
+### 工作流引导
+
+根据当前阶段引导用户：
+
+```
+[无变更] → propose → [有提案] → apply → [已实现] → verify → [已验证] → archive
+```
+
+每次执行 `specpow status` 后，根据阶段推荐下一步操作：
+- 无活跃变更 → 建议 `/specpow-propose <name>`
+- 有提案但工件未完成 → 建议编辑工件文件
+- 工件已完成 → 建议 `/specpow-apply`
+- 已实现 → 建议 `/specpow-verify`
+- 已验证 → 建议 `/specpow-archive`
+
+## 合理化防御表
+
+| 你以为的 | 实际应该做的 |
+|---------|------------|
+| "我可以直接告诉用户命令是什么" | 用 Bash 工具执行命令并展示结果 |
+| "这个命令太简单了，不需要执行" | 仍然执行，展示实际输出 |
+| "用户应该自己去终端运行" | 用户要求你执行，你就执行 |
+| "explore 是交互式的，我模拟一下" | 告诉用户需要在终端运行，或手动模拟苏格拉底式提问 |
+
+## 红旗
+
+以下想法意味着 STOP：
+
+| 想法 | 现实 |
+|------|------|
+| "我可以假装执行了命令" | 必须真正用 Bash 执行并展示输出 |
+| "这个命令会改变什么，让我先确认" | 直接执行，展示结果让用户确认 |
+| "用户可能不知道这个命令" | 执行命令后解释输出含义 |

package/.specpow/skills/execution-parallel-agents/SKILL.md

@@ -1,10 +1,5 @@
 ---
 name: execution-parallel-agents
-description: SpecPow execution-parallel-agents skill
----
-
----
-name: execution-parallel-agents-agents
 description: 并行子代理调度。识别独立问题域，并行分发多个子代理同时处理。来自 Superpowers。
 ---
 

package/.specpow/skills/execution-sdd-orchestrator/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: execution-sdd-orchestrator
+description: SDD 编排技能。将 controller.ts 的 implement→review→fix 循环转化为宿主 Agent 可执行的指令。当执行 specpow apply 或用户要求实现变更时使用。
+version: 1.0.0
+trigger: on-demand
+---
+
+# SDD 编排技能
+
+当执行 `specpow apply` 或用户要求实现变更时，按以下流程执行。
+
+## 前置条件
+
+- 变更提案已完成：`.specpow/openspec/changes/{change}/` 存在
+- 任务清单已生成：`.specpow/openspec/changes/{change}/task-manifest.json`（Host-Driven 模式由 `apply.ts` 生成）
+- Ledger 位置：`.specpow/sdd/{change}/progress.md`
+
+## 执行流程
+
+### 步骤 1：初始化
+
+1. 读取 Ledger（`progress.md`），检查是否有已完成的任务（断点续跑）
+2. 读取任务清单：`.specpow/openspec/changes/{change}/task-manifest.json`（包含增强描述和 specConstraints）
+3. 记录 BASE commit：`git rev-parse HEAD`
+
+### 步骤 2：逐任务执行
+
+对每个未完成任务：
+
+#### 2a. 创建 Brief
+
+读取任务信息，创建 brief 文件：
+- **路径**：`.specpow/sdd/{change}/task-{N}-brief.md`
+- **内容**：
+  ```markdown
+  # Task {N}: {title}
+
+  ## 描述
+  {description}
+
+  ## 涉及文件
+  {files list}
+
+  ## Spec 约束
+  {spec constraints from specs/ directory}
+
+  ## 输出要求
+  完成后写 Report JSON 到：`.specpow/sdd/{change}/task-{N}-report.md`
+  ```
+
+#### 2b. 派发实现者子代理
+
+使用宿主原生 subagent 工具派发：
+- **Prompt**：读取 brief 文件 + TDD 指令 + spec 约束
+- **模型选择**（参考，可根据实际情况调整）：
+  - ≤2 文件 + 完整 spec → `cheap`（haiku）
+  - 多文件协调 → `standard`（sonnet）
+  - 需要架构判断 → `capable`（opus）
+- **指令**：
+  1. 读取 brief 文件
+  2. TDD 流程：RED → GREEN → REFACTOR
+  3. 遵守 spec 约束
+  4. 完成后写 Report JSON 到 reportPath
+
+#### 2c. 检查 Report
+
+读取 `.specpow/sdd/{change}/task-{N}-report.md`，解析 JSON：
+```json
+{
+  "status": "done|blocked|in_progress|done_with_concerns|needs_context",
+  "commits": ["sha1", "sha2"],
+  "testSummary": "X tests passed",
+  "concerns": "any issues or null",
+  "fixReport": "修复说明（仅 fix 轮次）"
+}
+```
+
+- `status === 'blocked'` → 记录到 Ledger：`Task {N}: BLOCKED — {concerns}`，跳过此任务
+- `status === 'done'` → 继续审查
+
+#### 2d. 生成审查包
+
+运行 `git diff` 生成变更摘要：
+```bash
+BASE_COMMIT={recorded base commit}
+HEAD_COMMIT=$(git rev-parse HEAD)
+git diff ${BASE_COMMIT}..${HEAD_COMMIT} > .specpow/sdd/{change}/review-package.md
+```
+
+#### 2e. 派发审查者子代理
+
+使用宿主原生 subagent 工具派发：
+- **Prompt**：brief + review package + spec 约束
+- **指令**：
+  1. 读取 brief 文件
+  2. 读取 review package（diff）
+  3. 两阶段审查：
+     - **阶段 A：Spec 合规性** — 实现是否满足 spec 要求
+     - **阶段 B：代码质量** — bug、安全问题、性能问题
+     - **阶段 C：TDD 合规** — 测试是否充分
+  4. 输出 Review JSON 到 `.specpow/sdd/{change}/review-result.json`：
+     ```json
+     {
+       "specCompliant": true/false,
+       "qualityApproved": true/false,
+       "findings": [
+         {
+           "id": "F1",
+           "severity": "critical|important|minor",
+           "description": "...",
+           "file": "src/foo.ts",
+           "line": 42,
+           "isLoadBearing": false
+         }
+       ],
+       "cannotVerify": ["..."]
+     }
+     ```
+     **注意**：初始审查不输出 `addressed` 字段（由重审者在修复循环中填充）。
+
+#### 2f. 运行测试
+
+执行项目测试：
+```bash
+# 检测包管理器并运行测试
+if [ -f pnpm-lock.yaml ]; then
+  pnpm test --silent
+elif [ -f yarn.lock ]; then
+  yarn test --silent
+else
+  npm test --silent
+fi
+```
+
+记录测试结果：通过/失败。
+
+#### 2g. 分析审查结果
+
+读取 review JSON，判定：
+- `specCompliant === true && qualityApproved === true && tests passed` → **PASS**
+  - 记录到 Ledger：`Task {N}: complete (commits {BASE}..{HEAD}, review clean)`
+  - 进入下一任务
+- `findings.length > 0 || tests failed` → **需要修复**，进入修复循环
+
+### 步骤 3：修复循环（最多 5 轮）
+
+每轮：
+
+1. **派发实现者修复（复用原始 brief）**
+   - Brief 路径不变：`.specpow/sdd/{change}/task-{N}-brief.md`（不修改 brief 文件）
+   - Open findings 通过指令传递给实现者，不写入 brief 文件
+   - **模型升级**：第 4-5 轮使用比当前高一级模型
+   - **指令**：修复 findings → 写 Report JSON 到 `task-{N}-report.md.fix-{R}`
+
+2. **生成修复 diff**
+   ```bash
+   FIX_BASE=$(git rev-parse HEAD)
+   # 实现者修复后...
+   FIX_HEAD=$(git rev-parse HEAD)
+   git diff ${FIX_BASE}..${FIX_HEAD} > .specpow/sdd/{change}/review-package.md
+   ```
+
+3. **派发重审者（范围限定）**
+   - **只审查修复部分**，不重新审查整个任务
+   - **指令**：对每个 finding 判定 `addressed: true/false`
+   - 输出更新后的 review JSON 到 `.specpow/sdd/{change}/re-review-result.json`
+
+4. **运行测试**
+
+5. **分析结果**
+   - 所有 findings addressed + tests passed → **PASS**
+   - 仍有 open findings → 继续下一轮
+
+6. **记录到 Ledger**
+   ```
+   Task {N}: fix round {R}/5 ({A} addressed, {O} open — {finding1_summary}; {finding2_summary}; commits {BASE}..{HEAD})
+   ```
+
+**断路器**：5 轮后仍未通过 → 对每个 finding 判定：
+- `isLoadBearing === false` → **park**（延后，记录到 Ledger）
+- `isLoadBearing === true` → **block**（阻塞，任务标记为 BLOCKED）
+
+### 步骤 4：完成
+
+所有任务完成后，输出总结：
+```
+✅ SDD 执行完成
+- 完成任务：X/Y
+- 阻塞任务：Z
+- 停放发现：N（已记录到 Ledger）
+```
+
+## 并行执行模式
+
+当用户指定 `--parallel` 或任务数量 ≥ 3 且无强依赖时，可启用并行执行。
+
+### 前置条件
+
+- 任务清单已读取
+- 依赖分析完成（参考 `buildParallelLayers` 逻辑）
+
+### 执行流程
+
+#### 1. 依赖分析与分层
+
+分析任务依赖关系，构建并行层：
+- **文件级依赖**：多个任务修改同一文件 → 顺序执行
+- **逻辑级依赖**：tasks.md 中显式声明的依赖
+- **分层结果**：每层内的任务彼此独立，可并行执行
+
+```
+示例：
+- 层 1: [T1, T2, T3] — 无依赖，可并行
+- 层 2: [T4] — 依赖 T1 的输出
+- 层 3: [T5, T6] — 无依赖，可并行
+```
+
+#### 2. 逐层并行执行
+
+对每一层：
+
+##### 2a. 为每个任务创建 Git Worktree
+
+```bash
+# 为每个任务创建独立 worktree
+BASE_COMMIT=$(git rev-parse HEAD)
+BRANCH_NAME="specpow-parallel-{TASK_NUM}-{TIMESTAMP}"
+WORKTREE_PATH=".specpow/sdd/{change}/.worktrees/task-{TASK_NUM}"
+
+git worktree add -b "$BRANCH_NAME" "$WORKTREE_PATH" "$BASE_COMMIT"
+```
+
+**关键**：
+- 每个任务在独立的 worktree 中工作，消除并行竞态
+- worktree 拥有独立的 HEAD 和工作目录
+- 所有文件编辑和 git 操作必须在 worktree 中执行
+
+##### 2b. 并行派发实现者子代理
+
+使用宿主原生 subagent 工具**同时**派发多个实现者：
+
+```
+对层内的每个任务：
+  派发子代理（isolation: "worktree"）：
+    - prompt: 读取 brief + TDD 指令 + spec 约束
+    - 指令：在 worktree 中工作，完成后写 report
+    - 模型选择：参考串行模式的模型选择表
+```
+
+**并行派发示例**（Claude Code）：
+```
+同时发起多个 Agent 调用：
+- Agent 1: "Task 1 in worktree .specpow/sdd/{change}/.worktrees/task-1"
+- Agent 2: "Task 2 in worktree .specpow/sdd/{change}/.worktrees/task-2"
+- Agent 3: "Task 3 in worktree .specpow/sdd/{change}/.worktrees/task-3"
+```
+
+##### 2c. 等待所有子代理完成
+
+所有子代理完成后，检查各自的 report 文件。
+
+##### 2d. 顺序合并分支
+
+```bash
+# 按任务编号顺序合并
+for TASK_NUM in 1 2 3; do
+  BRANCH="specpow-parallel-${TASK_NUM}-xxx"
+  git merge "$BRANCH" --no-edit
+  
+  # 检查冲突
+  if [ $? -ne 0 ]; then
+    echo "冲突：任务 $TASK_NUM 合并失败"
+    # 记录到 Ledger
+  fi
+done
+```
+
+##### 2e. 冲突检测
+
+检查哪些文件被多个任务修改：
+```bash
+# 对每个完成的任务，获取变更文件列表
+for TASK_NUM in 1 2 3; do
+  git diff --name-only "$BASE_COMMIT".."$HEAD_COMMIT"
+done
+
+# 如果同一文件出现在多个任务的变更列表中 → 冲突
+```
+
+##### 2f. 清理 Worktree
+
+```bash
+# 删除 worktree 和分支
+git worktree remove ".specpow/sdd/{change}/.worktrees/task-{TASK_NUM}" --force
+git branch -D "specpow-parallel-{TASK_NUM}-xxx"
+```
+
+##### 2g. 运行集成测试
+
+所有任务合并后，运行完整测试套件：
+```bash
+pnpm test --silent
+```
+
+##### 2h. 记录到 Ledger
+
+```
+Layer {L}: complete ({N} tasks merged, {C} conflicts detected)
+```
+
+#### 3. 层间串行
+
+前一层合并完成后，才开始下一层。这确保了依赖关系的正确性。
+
+### 并行执行的注意事项
+
+1. **绝不并行修改同一文件** — 依赖分析必须准确
+2. **合并后必须运行完整测试** — 并行执行可能引入集成问题
+3. **冲突是并行代价** — 显式报告冲突，而非静默丢失
+4. **Worktree 清理必须彻底** — 即使任务失败也要清理
+5. **断路器保护** — 如果一层中有 ≥ 50% 任务失败，停止后续层
+
+### 何时使用并行模式
+
+| 场景 | 推荐模式 |
+|------|----------|
+| 3+ 个独立任务，无文件重叠 | 并行 |
+| 任务间有强依赖 | 串行 |
+| CI/CD 自动化 | 并行（节省时间） |
+| 交互式开发，需要实时反馈 | 串行（更易调试） |
+| 多文件非依赖变更 | 并行 |
+
+## Ledger 记录格式
+
+每完成一个操作，**追加一行**到 `.specpow/sdd/{change}/progress.md`。
+格式为**扁平日志行**（不是结构化 markdown），ledger.ts 用正则解析这些行。
+
+首行固定为：
+```
+# SDD ledger — plan: {planFile}
+```
+
+后续追加的日志行格式：
+
+```
+Task {N}: complete (commits {BASE}..{HEAD}, review clean)
+Task {N}: complete (commits {BASE}..{HEAD}, review with parked)
+Task {N}: fix round {R}/{MAX} ({A} addressed, {O} open — {summary1}; {summary2}; commits {RANGE})
+Task {N}: BLOCKED — {reason}
+Task {N}: parked — {description} — ruling: {ruling}
+Task {N}: minor (deferred): {description}
+```
+
+**注意**：
+- 每行独立，不分组、不嵌套
+- `review clean` 表示审查通过无停放；`review with parked` 表示有停放发现
+- fix round 行中的 summaries 用分号分隔，每个 summary 对应一个 open finding 的描述
+- `{MAX}` 来自配置 `sdd.maxFixRounds`（默认 5）
+
+## 关键原则
+
+1. **文件即接口** — 所有产物通过文件传递，不占用上下文
+2. **信任 Ledger** — 断点续跑时读取 Ledger，不信任记忆
+3. **模型升级** — 修复轮次 4-5 升级模型，避免卡死
+4. **范围限定重审** — 修复后只审查修复部分，提高效率
+5. **断路器保护** — 5 轮后强制判定，避免无限循环