@specpow/framework 0.5.10 → 0.5.11

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

@@ -1,366 +0,0 @@
----
-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 轮后强制判定，避免无限循环

package/.specpow/skills/execution-subagent-dispatch/SKILL.md

@@ -1,295 +0,0 @@
----
-name: execution-subagent-dispatch
-description: 子代理派发技能。将 ai-caller.ts 的三种 prompt 模板（实现者、审查者、重审者）转化为宿主 Agent 可执行的指令。当需要派发子代理执行具体任务时使用。
-version: 1.0.0
-trigger: on-demand
----
-
-# 子代理派发技能
-
-当需要派发子代理执行实现、审查或重审任务时，按以下模板构建指令。
-
-## 核心原则
-
-1. **文件即接口** — 告诉子代理去哪里读文件，不在 prompt 中粘贴大段内容
-2. **新鲜上下文** — 每个子代理只获得它需要的文件路径，不继承历史对话
-3. **输出到文件** — 所有结果写入指定文件，不通过对话返回
-
----
-
-## 实现者子代理 Prompt 模板
-
-派发实现者时，给子代理的指令应包含以下部分：
-
-```markdown
-# 任务实现
-
-## 上下文
-你正在项目 {projectContext} 中工作。
-
-## 任务简报
-请阅读完整的任务简报文件: {briefPath}
-
-## 规范约束
-{specConstraints}
-（如无 spec，写"遵循项目现有代码风格和架构约定"）
-
-## 涉及文件
-{filesList}
-（如无指定文件，写"由你自行判断需要修改的文件"）
-
-## 铁律：测试驱动开发 (TDD)
-
-没有失败测试就不写产品代码！
-
-## 执行步骤 — RED-GREEN-REFACTOR
-
-### RED — 先写一个失败的测试
-1. 阅读任务简报，理解需求行为
-2. 为下一个要实现的 _行为_ 写一个测试
-3. 运行测试，确认它失败
-4. 失败原因必须是"功能还不存在"
-
-### GREEN — 写最少的代码让测试通过
-1. 写刚好够让测试通过的代码
-2. 不多写。YAGNI。
-3. 运行测试，确认全部通过
-
-### REFACTOR — 在测试保护下清理代码
-1. 消除重复，改善命名
-2. 运行测试，确认仍然全部通过
-
-重复 RED-GREEN-REFACTOR 直到任务完成。
-
-## 报告要求
-将详细的实现报告写入: {reportPath}
-
-报告格式（文本要点）：
-```
-报告格式：
-- 状态: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
-- 产生的 commit 列表（如果适用）
-- 测试摘要（RED 阶段写了哪些测试，GREEN 阶段全部通过）
-- 任何疑虑或未解决的问题
-```
-
-注意：`parseTaskReport` 同时接受上述文本格式和 JSON 格式。JSON 格式使用大写状态值：`"status": "DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED"`。
-```
-
-### 变量说明
-
-| 变量 | 来源 | 示例 |
-|------|------|------|
-| `{projectContext}` | 项目根目录名 | `specpow` |
-| `{briefPath}` | 任务简报路径 | `.specpow/sdd/{change}/task-{N}-brief.md` |
-| `{specConstraints}` | specs/ 目录中的规范内容 | 从 `specs/*.md` 读取 |
-| `{filesList}` | 任务涉及的文件列表 | 从任务描述中提取 |
-| `{reportPath}` | 实现报告输出路径 | `.specpow/sdd/{change}/task-{N}-report.md` |
-
-### Fix 轮次的实现者派发
-
-修复轮次复用相同的 prompt 模板，但：
-- **不修改 brief 文件** — 复用原始 brief，open findings 通过指令传递
-- **追加 open findings 列表** — 在 prompt 中列出需要修复的 findings
-- **reportPath 变更** — 写入 `task-{N}-report.md.fix-{R}`（不是覆盖原 report）
-- **模型升级** — 第 4-5 轮使用比当前高一级模型
-
----
-
-## 审查者子代理 Prompt 模板
-
-派发审查者时，给子代理的指令应包含以下部分：
-
-```markdown
-# 代码审查 — 三阶段裁决
-
-## 任务上下文
-- 任务: {taskTitle}
-- 简报: {briefPath}
-
-## 审查包
-请阅读完整的审查包: {reviewPackagePath}
-
-## 审查流程
-
-### 第一阶段: 规格合规裁决
-对照任务简报，逐项检查：
-1. 所有需求项是否已实现
-2. 是否有超出规范的实现（scope creep）
-3. 接口签名是否与设计一致
-
-### 第二阶段: 代码质量裁决
-1. 命名和结构是否清晰
-2. 错误处理是否完整
-3. 是否有安全隐患
-4. 是否有性能问题
-
-### 第三阶段: TDD 合规裁决
-1. 是否有测试覆盖新增/修改的代码
-2. 测试是否断言行为而非实现细节
-3. 测试是否在代码之前编写（检查 commit 顺序或测试结构）
-4. 关键路径和边界条件是否有测试
-
-## 输出格式
-将审查结果写入文件: {reviewResultPath}
-
-```json
-{
-  "specCompliant": true/false,
-  "qualityApproved": true/false,
-  "findings": [
-    {
-      "id": "F-001",
-      "severity": "critical|important|minor",
-      "description": "...",
-      "file": "path/to/file",
-      "line": 42,
-      "isLoadBearing": true/false
-    }
-  ],
-  "cannotVerify": ["从 diff 无法验证的项目"]
-}
-```
-```
-
-### 变量说明
-
-| 变量 | 来源 | 示例 |
-|------|------|------|
-| `{taskTitle}` | 任务标题 | 从 brief 中读取 |
-| `{briefPath}` | 任务简报路径 | `.specpow/sdd/{change}/task-{N}-brief.md` |
-| `{reviewPackagePath}` | 审查包路径（diff） | `.specpow/sdd/{change}/review-package.md` |
-| `{reviewResultPath}` | 审查结果输出路径 | `.specpow/sdd/{change}/review-result.json` |
-
-### 审查要点
-
-- **不输出 `addressed` 字段** — 初始审查不判断 addressed，该字段由重审者填充
-- **cannotVerify** — 无法从 diff 验证的项目（如运行时行为、外部依赖）放在此数组中
-- **isLoadBearing** — 标记该 finding 是否为承重墙（阻塞性），非承重墙的 finding 可以 park
-
----
-
-## 重审者子代理 Prompt 模板
-
-派发重审者时（修复循环中），给子代理的指令应包含以下部分：
-
-```markdown
-# 范围限定重新审查
-
-只审查修复 diff: {fixDiffPath}
-
-## 待验证的开放发现
-{openFindingsList}
-
-## 要求
-对每个发现做出裁决: ADDRESSED / NOT ADDRESSED
-新问题（仅限修复 diff 内的）标记为 NEW
-超出修复范围的观察 → 忽略（不记录）
-
-将结果写入: {reReviewResultPath}
-```
-
-### 变量说明
-
-| 变量 | 来源 | 示例 |
-|------|------|------|
-| `{fixDiffPath}` | 修复 diff 路径 | `.specpow/sdd/{change}/review-package.md`（复用审查包命名） |
-| `{openFindingsList}` | 开放 findings 列表 | 格式化后的 finding 列表（见下方） |
-| `{reReviewResultPath}` | 重审结果输出路径 | `.specpow/sdd/{change}/re-review-result.json` |
-
-### Open Findings 列表格式
-
-```
-  1. [critical] Description of finding 1 (src/foo.ts:42)
-  2. [important] Description of finding 2 (src/bar.ts)
-  3. [minor] Description of finding 3
-```
-
-### 重审要点
-
-- **只审查修复部分** — 不重新审查整个任务，只看 fix diff
-- **对每个 finding 裁决** — ADDRESSED 或 NOT ADDRESSED
-- **新问题限制范围** — 只有在 fix diff 内发现的新问题才标记为 NEW
-- **超出范围忽略** — 不在 fix 范围内的观察不记录
-
----
-
-## 派发流程（宿主 Agent 操作）
-
-### 1. 实现者派发
-
-```bash
-# 1. 确保 brief 文件已写入
-# （由编排技能在步骤 2a 完成）
-
-# 2. 使用宿主原生 subagent 工具派发
-# Claude Code: Agent tool
-# Cursor: subagent tool
-# 其他: 参考宿主工具文档
-
-# 3. 子代理读取 brief → 实现 → 写 report
-
-# 4. 读取 report 文件，解析 JSON
-```
-
-### 2. 审查者派发
-
-```bash
-# 1. 生成审查包（diff）
-BASE_COMMIT={recorded base commit}
-HEAD_COMMIT=$(git rev-parse HEAD)
-git diff ${BASE_COMMIT}..${HEAD_COMMIT} > .specpow/sdd/{change}/review-package.md
-
-# 2. 使用宿主原生 subagent 工具派发审查者
-# Prompt: 审查者模板（见上方）
-
-# 3. 子代理读取 brief + review package → 审查 → 写 review-result.json
-
-# 4. 读取 review-result.json，解析 JSON
-```
-
-### 3. 重审者派发（修复循环中）
-
-```bash
-# 1. 生成修复 diff（复用 generateReviewPackage 命名模式）
-FIX_BASE=$(git rev-parse HEAD)
-# 实现者修复后...
-FIX_HEAD=$(git rev-parse HEAD)
-git diff ${FIX_BASE}..${FIX_HEAD} > .specpow/sdd/{change}/review-package.md
-
-# 2. 使用宿主原生 subagent 工具派发重审者
-# Prompt: 重审者模板（见上方）+ open findings 列表
-
-# 3. 子代理读取 fix diff → 对每个 finding 裁决 → 写 re-review-result.json
-
-# 4. 读取 re-review-result.json，解析 JSON
-```
-
----
-
-## 模型选择指导
-
-根据任务复杂度选择子代理模型（如果宿主工具支持）：
-
-| 场景 | 条件 | 推荐级别 |
-|------|------|----------|
-| 机械实现 | ≤2 文件 + 完整 spec | cheap（默认 haiku） |
-| 集成实现 | 多文件协调 | standard（默认 sonnet） |
-| 架构设计 | 需要设计判断 | capable（默认 opus） |
-| 简单审查 | <100 行 diff | cheap（默认 haiku） |
-| 标准审查 | 一般变更 | standard（默认 sonnet） |
-| 复杂审查 | 复杂变更 | capable（默认 opus） |
-| 最终审查 | 全变更审查 | capable（默认 opus） |
-| 修复轮次 4-5 | 升级模型 | 比当前高一级 |
-
-**注意**：这只是指导。根据你实际可用的模型做出最佳选择。
-
----
-
-## 关键原则
-
-1. **文件即接口** — 所有产物通过文件传递，不占用上下文
-2. **范围限定** — 重审者只审查修复部分，提高效率
-3. **铁律 TDD** — 实现者必须遵循 RED-GREEN-REFACTOR
-4. **三阶段审查** — 规格合规 → 代码质量 → TDD 合规
-5. **模型升级** — 修复轮次 4-5 升级模型，避免卡死