@specpow/framework 0.2.2 → 0.4.0

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

@@ -0,0 +1,295 @@
+---
+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 升级模型，避免卡死

package/.specpow/skills/execution-subagent-driven-dev/SKILL.md

@@ -1,10 +1,5 @@
 ---
 name: execution-subagent-driven-dev
-description: SpecPow execution-subagent-driven-dev skill
----
-
----
-name: execution-subagent-driven-dev-driven-dev
 description: 子代理驱动开发(SDD)。通过分发新鲜子代理执行每个任务，每个任务后进行审查，最后进行全分支审查。来自 Superpowers 的核心执行引擎。
 ---
 

package/.specpow/skills/planning-apply-change/SKILL.md

@@ -1,10 +1,5 @@
 ---
 name: planning-apply-change
-description: SpecPow planning-apply-change skill
----
-
----
-name: planning-apply-change-change
 description: 执行变更实现。融合 OpenSpec apply + Superpowers SDD 引擎。这是最关键的融合点 — 用 SDD 子代理驱动方式执行 OpenSpec 定义的任务。
 ---
 

package/.specpow/skills/planning-explore/SKILL.md

@@ -1,8 +1,3 @@
----
-name: planning-explore
-description: SpecPow planning-explore skill
----
-
 ---
 name: planning-explore
 description: 苏格拉底式需求探索。在任何编码之前激活。探索上下文、提问、提出方案、但不产生承诺。融合 Superpowers brainstorming + OpenSpec explore。

package/.specpow/skills/planning-propose/SKILL.md

@@ -1,8 +1,3 @@
----
-name: planning-propose
-description: SpecPow planning-propose skill
----
-
 ---
 name: planning-propose
 description: 创建变更提案。生成 proposal + specs + design + tasks 全套工件。融合 OpenSpec propose + brainstorming 前置验证。

package/.specpow/skills/using-specpow/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: using-specpow
+description: Bootstrap 元技能。Host-Driven 模式下会话启动时自动加载。教会宿主 Agent 使用原生工具执行 SDD 工作流。融合 Superpowers using-superpowers 模式 + SpecPow SDD 编排能力。
+version: 1.0.0
+trigger: session-start
+mode: host-driven
+---
+
+<SUBAGENT-STOP>
+如果你是被分发去执行特定任务的子代理，忽略此技能。
+</SUBAGENT-STOP>
+
+<EXTREMELY_IMPORTANT>
+如果你认为有任何 1% 的可能性某个技能适用于你正在做的事，你绝对必须调用该技能。
+如果一个技能适用于你的任务，你没有选择。你必须使用它。
+这不可协商。你不能合理化地绕过它。
+</EXTREMELY_IMPORTANT>
+
+# SpecPow Host-Driven SDD 工作流
+
+你已加载 **SpecPow** — 一个规范驱动的 AI 开发框架。
+它结合了 OpenSpec 的规范驱动规划与 Superpowers 的子代理驱动执行。
+
+**当前模式：Host-Driven** — 你将使用**原生工具**（subagent、file I/O、bash）执行整个 SDD 方法论。
+TypeScript 代码仅负责非 AI 工作（文件创建、schema 解析）。**你是编排者。**
+
+## 铁律
+
+1. **先查技能** — 任何响应或行动之前，先扫描 `.specpow/skills/` 目录查找相关技能
+2. **文件即接口** — 子代理通过文件通信（brief、report、review JSON），不通过对话上下文
+3. **Ledger 是真相** — 上下文压缩后，信任 Ledger（`.specpow/sdd/<change>/progress.md`）和 git log，不信任自己的记忆
+4. **TDD 强制** — RED → GREEN → REFACTOR，不可跳过
+5. **规范即契约** — specs 中定义的行为必须被实现遵守
+6. **审查+测试才完成** — 每个任务实施完成后，必须经过**代码审查**且**测试全部通过**，才能标记为 done。审查通过后标记完成；审查未通过则进入修复循环（最多 5 轮），每轮修复后重新审查修复部分。
+7. **发现必须验证** — 审查中发现的每个问题，必须**确认其真实存在**（读代码、跑测试、看 diff）后才能记录。禁止无中生有——不确定的发现标记为 `cannotVerify`，不标记为 finding。
+
+## 触发纪律（Trigger Discipline）
+
+| 用户说 / 场景 | 你做什么 |
+|---------------|----------|
+| `specpow apply`（默认模式） | 不干预 — TypeScript SDD 引擎接管 |
+| `specpow apply --host-driven`（计划中） | 读取任务清单，按 `execution-subagent-driven-dev` 技能逐任务执行 |
+| `specpow explore "..."` | 调用 `planning-explore` 技能 |
+| `specpow propose <name>` | 调用 `planning-propose` 技能 |
+| 任何编码任务 | 先检查 `.specpow/skills/` 是否有适用技能 |
+| 发现 SDD 工作区（`.specpow/sdd/<change>/`） | 自动读取 progress.md 并按 SDD 流程继续 |
+
+## Host-Driven 模式核心概念
+
+### 你拥有的原生工具
+
+| 工具类型 | 用途 | 示例 |
+|---------|------|------|
+| **Subagent 工具** | 派发实现者/审查者子代理 | Claude Code: Agent tool; Cursor: subagent |
+| **File I/O** | 读写 brief、report、review JSON | Read/Write 工具 |
+| **Bash** | 执行 git 操作、运行测试 | `git diff`, `npm test` |
+| **Ledger** | 记录进度、恢复状态 | 追加到 `.specpow/sdd/<change>/progress.md` |
+
+### 文件通信协议
+
+子代理之间通过文件通信，每个文件有固定位置：
+
+```
+.specpow/
+├── sdd/{change}/
+│   ├── progress.md              # 进度账本（追加写入）
+│   ├── task-{N}-brief.md        # 任务简报
+│   ├── task-{N}-report.md       # 实现报告
+│   └── task-{N}-report.md.fix-{R}  # 修复报告（第 R 轮）
+├── openspec/
+│   └── changes/{change}/
+│       ├── specs/              # 规范文件
+│       ├── design.md           # 设计文档
+│       └── .openspec.yaml      # 变更配置
+└── skills/                     # 技能目录（你正在这里）
+```
+
+### Report JSON 格式
+
+实现者子代理完成后写入 report：
+```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 轮次填写）"
+}
+```
+
+### Review JSON 格式
+
+审查者子代理完成后写入 review：
+```json
+{
+  "specCompliant": true,
+  "qualityApproved": true,
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "critical|important|minor",
+      "description": "...",
+      "file": "src/foo.ts",
+      "line": 42,
+      "isLoadBearing": false
+    }
+  ],
+  "cannotVerify": []
+}
+```
+
+## SDD 编排快速参考
+
+完整的编排流程在 `execution-sdd-orchestrator` 技能中详细描述。核心循环：
+
+```
+对每个任务：
+  1. 创建 Brief → task-{N}-brief.md
+  2. 派发实现者 → 读 brief → 写代码 → 写 report JSON → task-{N}-report.md
+  3. 检查 report（blocked? → 跳过; done? → 继续）
+  4. 派发审查者 → 读 brief + diff + specs → 写 review JSON
+  5. 运行测试
+  6. 分析结果 → 审查通过 + 测试通过? → 标记 done → 下一任务
+                → 需要修复? → 修复循环（最多 5 轮）：
+                    每轮：修复 findings → 派发重审者（只审查修复部分）→ 运行测试 → 分析
+```
+
+## 模型选择指导
+
+你可以根据任务复杂度选择子代理模型（如果宿主工具支持）：
+
+| 场景 | 条件 | 推荐级别 |
+|------|------|----------|
+| 机械实现 | ≤2 文件 + 完整 spec | cheap（默认 haiku） |
+| 集成实现 | 多文件协调 | standard（默认 sonnet） |
+| 架构设计 | 需要设计判断 | capable（默认 opus） |
+| 简单审查 | <100 行 diff | cheap（默认 haiku） |
+| 最终审查 | 全变更审查 | capable（默认 opus） |
+| 修复轮次 4-5 | 升级模型 | 比当前高一级 |
+
+**注意**：这只是指导。根据你实际可用的模型做出最佳选择。
+
+## 技能优先级
+
+当多个技能适用时，流程技能先行 — 它们设定方法，然后实施技能执行。
+- "让我们构建 X" → 先 explore/brainstorming，然后实施技能
+- "修复这个 bug" → 先 systematic-debugging，然后领域技能
+- "创建新变更" → 先 propose，然后 apply-change
+- "执行任务" → 先 subagent-driven-dev，然后相关实施技能
+
+## 可用技能清单
+
+### 规划类（先于编码）
+- `planning-explore` — 苏格拉底式需求探索（无承诺）
+- `planning-propose` — 创建变更提案（proposal + specs + design + tasks）
+- `planning-write-plans` — 将设计转化为极详细的实现计划
+- `planning-write-specs` — 编写 delta 规范
+- `planning-write-design` — 创建架构设计文档
+- `planning-apply-change` — 执行变更（SDD 引擎驱动）
+- `planning-onboard` — 项目入门引导
+- `planning-archive-change` — 归档变更
+- `planning-verify-change` — 规范合规性验证
+- `planning-update-change` — 更新变更
+
+### 执行类（编码阶段）
+- `execution-subagent-driven-dev` — **子代理驱动开发**（核心执行引擎）
+- `execution-tdd` — 测试驱动开发（RED-GREEN-REFACTOR）
+- `execution-systematic-debugging` — 4 阶段根因分析
+- `execution-parallel-agents` — 并行子代理调度
+- `execution-git-worktrees` — Git worktree 管理
+- `execution-finish-branch` — 分支完成与合并
+- `execution-requesting-review` — 请求代码审查
+- `execution-receiving-review` — 接收审查反馈
+- `execution-verification-before-completion` — 完成前验证铁律
+
+### 质量类（验证阶段）
+- `planning-verify-change` — 规范合规性验证
+
+### 业务类（领域能力）
+- `business-java-codegen` — Java 后端代码生成
+- `business-ui-codegen` — Vue2 前端代码生成
+- `business-test-gen` — 测试生成
+- `business-code-review` — 业务代码审查
+- `business-db-design` — 数据库设计
+- `business-prd-writer` — PRD 编写
+- `business-deploy-check` — 发版检查
+- `business-doc-sync` — 文档同步
+- `business-menu-register` — 菜单注册
+
+### 元技能类
+- `meta-using-skills` — 如何使用技能
+- `meta-writing-skills` — 如何编写新技能
+- `meta-create-skill` — 引导式技能创建向导
+
+## 红旗（立即停止）
+
+这些想法意味着 STOP — 你在合理化跳过技能：
+
+| 想法 | 现实 |
+|------|------|
+| "这只是个简单问题" | 问题也是任务。检查技能。 |
+| "我需要先了解更多上下文" | 技能检查在澄清问题之前。 |
+| "让我先探索代码库" | 技能告诉你如何探索。先检查。 |
+| "这不需要正式的技能" | 如果技能存在，就使用它。 |
+| "这个技能太重量级了" | 简单的事会变复杂。使用它。 |
+| "我先做这一件事" | 做任何事之前先检查技能。 |
+| "我记得这个技能" | 技能会演进。读当前版本。 |
+| "这不算一个任务" | 行动 = 任务。检查技能。 |
+| "我直接用 claude CLI 调用" | Host-Driven 模式用原生 subagent 工具，不用 CLI 子进程。 |
+| "让我直接调用 SDDController" | 不要！你是编排者，用技能指令而非 TypeScript 代码。 |
+
+## 平台适配
+
+如果你的 AI 工具在此列表中，读取其参考文件获取特殊指令（**计划中** — 文件尚未创建，当前使用通用指令）：
+
+- Claude Code: `references/claude-tools.md`（计划中）
+- Cursor: `references/cursor-tools.md`（计划中）
+- CodeBuddy: `references/codebuddy-tools.md`（计划中）
+- GitHub Copilot: `references/copilot-tools.md`（计划中）
+- Codex: `references/codex-tools.md`（计划中）
+
+## 用户指令优先级
+
+用户指令（CLAUDE.md, AGENTS.md 等直接请求）优先于技能，技能优先于默认行为。只有当你的搭档明确要求时，才跳过技能工作流。
+
+## SpecPow 特有规则
+
+1. **规划先于编码** — 任何超过 30 分钟的编码工作，必须先完成 propose 流程
+2. **规范即契约** — specs 中定义的行为必须被实现遵守，SDD 审查会验证
+3. **账本即真理** — 上下文压缩后，信任账本和 git log，而非自己的记忆
+4. **文件即接口** — Agent 之间通过文件通信，不依赖对话上下文
+5. **双模式共存** — 默认模式用 SDD Engine（TypeScript 编排）；`--host-driven` 模式用宿主 Agent 编排