@wwkit/harness 1.0.10 → 1.0.12

package/skills/read-docs/references/superpowers/bootstrap.md

@@ -0,0 +1,107 @@
+# Bootstrap 注入机制
+
+## 安装方式
+
+在 opencode 的 `opencode.json` 中注册：
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
+}
+```
+
+或使用本地路径：
+
+```json
+{
+  "plugin": ["~/.config/opencode/node_modules/superpowers"]
+}
+```
+
+## 插件入口
+
+**文件**: `.opencode/plugins/superpowers.js`（`package.json` 的 `"main"`）
+
+插件导出 `SuperpowersPlugin`，接收 `{ client, directory }` 参数，返回两个 hook：
+
+| Hook | 作用 |
+|------|------|
+| `config` | 将 `skills/` 目录注册到 `config.skills.paths`，让 opencode 发现 superpowers 的 14 个技能 |
+| `experimental.chat.messages.transform` | 将 `using-superpowers/SKILL.md` 的内容注入到会话的第一条 user message 前面 |
+
+## Bootstrap 注入逻辑
+
+```javascript
+// .opencode/plugins/superpowers.js (简化)
+
+const getBootstrapContent = () => {
+  // 模块级缓存：SKILL.md 不变，只读一次
+  if (_bootstrapCache !== undefined) return _bootstrapCache
+
+  const skillPath = path.join(skillsDir, 'using-superpowers', 'SKILL.md')
+  const fullContent = fs.readFileSync(skillPath, 'utf8')
+  const { content } = extractAndStripFrontmatter(fullContent)  // 去掉 frontmatter
+
+  _bootstrapCache = `<EXTREMELY_IMPORTANT>
+You have superpowers.
+
+**IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the skill tool to load "using-superpowers" again - that would be redundant.**
+
+${content}
+
+${toolMapping}
+</EXTREMELY_IMPORTANT>`
+  return _bootstrapCache
+}
+
+return {
+  'experimental.chat.messages.transform': async (_input, output) => {
+    const bootstrap = getBootstrapContent()
+    if (!bootstrap || !output.messages.length) return
+
+    const firstUser = output.messages.find(m => m.info.role === 'user')
+    if (!firstUser || !firstUser.parts.length) return
+
+    // 幂等检查：已有注入则跳过
+    if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('EXTREMELY_IMPORTANT'))) return
+
+    // 注入到第一条 user message 的 parts 最前面
+    const ref = firstUser.parts[0]
+    firstUser.parts.unshift({ ...ref, type: 'text', text: bootstrap })
+  }
+}
+```
+
+## 关键设计决策
+
+1. **注入到 user message 而非 system message**：避免 system message 在每轮重复导致的 token 膨胀（#750），以及多 system message 破坏 Qwen 等模型的问题（#894）
+2. **模块级缓存**：`messages.transform` 在每个 agent step 都触发（不只是每轮），缓存避免重复磁盘 IO（#1202）
+3. **幂等检查**：通过 `EXTREMELY_IMPORTANT` 标记防止重复注入
+4. **工具映射**：为 opencode 平台生成特定的工具映射表
+
+## 工具映射（opencode 平台）
+
+| 技能中的动作 | opencode 工具 |
+|-------------|--------------|
+| Create or update todos | `todowrite` |
+| `Subagent (general-purpose):` | `task` with `subagent_type: "general"` |
+| Invoke a skill | `skill` 工具 |
+| Read files | `read` |
+| Create, edit, or delete files | `apply_patch` |
+| Run shell commands | `bash` |
+| Search files | `grep`, `glob` |
+| Fetch a URL | `webfetch` |
+
+## 跨平台注入机制
+
+| 平台 | 注入机制 | 触发时机 |
+|------|---------|---------|
+| opencode | `experimental.chat.messages.transform` hook | 每个 agent step |
+| Claude Code | `SessionStart` hook → `additionalContext` | 会话启动/clear/compact |
+| Cursor | `SessionStart` hook → `additional_context` | 会话启动 |
+| Codex | 插件系统 | 插件加载 |
+| Gemini CLI | 扩展系统 | 扩展加载 |
+| Pi | 扩展 + 原生技能 | 会话启动 + compact 后 |
+| Copilot CLI | `additionalContext` (SDK 标准) | 会话启动 |
+
+Claude Code 的 session-start hook 是一个 bash 脚本，读取 `using-superpowers/SKILL.md`，JSON 转义后输出为 `additionalContext`。

package/skills/read-docs/references/superpowers/comparison.md

@@ -0,0 +1,77 @@
+# 与 harness work agent 对比
+
+## 架构对比
+
+| 维度 | Superpowers | harness work agent |
+|------|------------|-------------------|
+| **编排者** | 宿主内置 agent + 技能 prompt | 自定义 `work` agent（`mode: primary`） |
+| **编排指令来源** | `using-superpowers` bootstrap + 技能 | agent 定义文件本身 |
+| **Worker** | 宿主内置 `general-purpose` | 宿主内置 `explore` / `general` |
+| **自定义 agent** | 无 | 7 个（work/extract/revise/query/lint/pyit/pyut） |
+| **技能系统** | 14 个技能，通过 `skill` 工具加载 | harness 自己的技能系统 |
+| **平台** | 跨平台（11+ harness） | 仅 opencode |
+
+## 调度策略对比
+
+| 维度 | Superpowers SDD | work agent |
+|------|----------------|------------|
+| **任务并行** | ❌ 串行（禁止并行实现） | ✅ 允许 ≤5 并行 |
+| **任务大小** | 2-5 分钟/任务 | ≤5 分钟/任务 |
+| **Review** | 每任务两阶段（spec + quality） | 无强制 review |
+| **Fix Loop** | ≤5 轮，含 model escalation | ≤3 轮重规划 |
+| **状态持久化** | Ledger 文件（抗 compaction） | TodoWrite + 摘要 |
+| **上下文传递** | 文件为主（brief/report/diff） | prompt 内联 |
+| **模型选择** | 精细策略（按任务类型选模型） | 不涉及 |
+| **容忍失败** | BLOCKED → 换模型/拆任务/升级 | failed 只记录不中断 |
+
+## 上下文隔离对比
+
+两者都利用 opencode 的子会话隔离（subagent 看不到父会话历史），但策略不同：
+
+| 维度 | Superpowers | work agent |
+|------|------------|------------|
+| **prompt 自包含** | ✅ 必须自包含 | ✅ 必须自包含 |
+| **上下文通过文件** | ✅ brief/report/diff 都是文件 | ❌ 上下文在 prompt 内 |
+| **返回精简** | ✅ ≤15 行摘要，详情写文件 | ✅ 摘要协议 |
+| **摘要格式** | Status + commits + test summary | status + 结论 + 变更 + 阻塞 + 建议 |
+
+## Bootstrap 注入 vs Agent 定义
+
+Superpowers 选择**不定义新 agent**，而是通过 `messages.transform` 注入 bootstrap 指令：
+
+- **优势**：跨平台（同一套技能适用于 Claude Code/Codex/opencode 等），不需要每个平台定义 agent
+- **代价**：bootstrap 内容在每次 agent step 都存在于 context 中（虽然通过注入到 user message 而非 system message 减少了重复）
+- **限制**：无法使用 agent 级别的配置（如 `temperature`、`permission`、`tools` 限制）
+
+harness 的 `work` agent 选择**定义自定义 agent**，获得更精细的控制，但绑定到 opencode 平台。
+
+## 关键设计差异
+
+### Review 策略
+
+Superpowers 的 review 机制比 work agent 更精细：
+- **每任务 review**：spec compliance + code quality 两阶段
+- **Scoped re-review**：fix 后只验证 fix，不重新审查全部
+- **Final review**：全分支审查，最强模型
+- **Adjudication**：controller 在 Round 5 后裁决，每条裁决记入 ledger
+
+### 文件传递
+
+Superpowers 的一个核心创新是**大量使用文件传递上下文**：
+- `task-brief` 脚本提取任务文本到文件
+- implementer 报告写文件
+- `review-package` 脚本生成 diff 包文件
+- Ledger 记录进度到文件
+
+这解决了两个问题：
+1. **Controller context 保护**：大段文本不经过 controller 的 context window
+2. **Compaction 恢复**：文件在 compaction 后仍然存在
+
+### 模型分层
+
+Superpowers 是少数明确实施模型分层策略的系统：
+- 机械实现用便宜模型
+- 判断任务用标准模型
+- 架构/review 用最强模型
+- Fix loop 升级模型
+- Turn count > token price 的洞察

package/skills/read-docs/references/superpowers/context.md

@@ -0,0 +1,71 @@
+# 上下文管理与模型选择
+
+## 文件作为上下文媒介
+
+Superpowers 的核心设计目标之一是**保护 controller 的 context window**：
+
+| 信息 | 传递方式 | 原因 |
+|------|---------|------|
+| 任务详情（brief） | 文件 | 避免粘贴计划全文到 prompt |
+| 实现报告（report） | 文件 | implementer 详情写文件，只返回 ≤15 行摘要 |
+| Review diff | 文件 | `review-package` 生成 diff 包文件，reviewer 一次 Read |
+| Findings | prompt 内联 | 需要精确传递给 fix implementer |
+| Ledger | 文件 | 跨 compaction 持久化 |
+| 上下文/接口 | prompt 内联 | subagent 看不到历史，必须自包含 |
+
+**反模式（被明确禁止）**：
+
+> A real session's dispatch hit 42k chars of which 99% was pasted history. A fresh subagent needs its task, the interfaces it touches, and the global constraints. Nothing else.
+
+## Ledger 机制
+
+Ledger 是 SDD 的状态持久化机制，解决 **compaction 导致上下文丢失** 的问题：
+
+```
+文件: .superpowers/sdd/<plan-name>/progress.md
+
+内容示例:
+# SDD ledger — plan: docs/superpowers/plans/feature-plan.md
+Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)
+Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)
+Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)
+Task 3: parked — magic number — ruling: plan mandates constant, deferred to final review
+Task 3: complete (commits b7c8d9e..e8f9a0b, 1 parked)
+```
+
+**为什么需要 Ledger**：
+
+> Conversation memory does not survive compaction. In real sessions, controllers that lost their place have re-dispatched entire completed task sequences — the single most expensive failure observed.
+
+Ledger 的恢复逻辑：
+- 第一行命名计划文件 → 确认归属
+- `Task <N>: complete` → 已完成，不重新派发
+- 最后一行是 fix round → 中断在 loop 中，从下一轮恢复
+- 第一行命名不同计划 → 别人的 ledger，不动它，重新开始
+
+## Model Selection 策略
+
+| 任务类型 | 模型层级 | 理由 |
+|---------|---------|------|
+| 机械实现（1-2 文件，完整 spec） | 最便宜 | 计划已包含完整代码，只是转录+测试 |
+| 集成/判断（多文件协调） | 标准 | 需要理解跨文件影响 |
+| 架构/设计 | 最强 | 需要设计判断 |
+| Task Reviewer | 按难度选择 | 小 diff 用便宜模型，并发/安全用强模型 |
+| Fix Loop Round 4-5 | 比原 implementer 强一级 | fresh eyes + capability bump |
+| Final Review | 最强 | 全分支审查，最重要 |
+| Scoped Re-review | 便宜-中档 | 只验证 fix，范围小 |
+
+**关键洞察**：
+
+> Turn count beats token price. Wall-clock and context cost scale with how many turns a subagent takes, and the cheapest models routinely take 2-3× the turns on multi-step work — costing more overall.
+
+因此：reviewer 和从 prose 描述工作的 implementer 最低用中档模型；计划文本包含完整代码时才用最便宜模型。
+
+## Subagent 类型
+
+Superpowers 只使用宿主平台的内置 agent，不定义自定义 agent：
+
+| subagent_type | 使用场景 | 来源 |
+|---------------|---------|------|
+| `general-purpose` / `general` | 实现、review、fix | opencode 内置 |
+| `explore` | 代码库探索（brainstorming 阶段） | opencode 内置 |

package/skills/read-docs/references/superpowers/index.md

@@ -0,0 +1,58 @@
+# Superpowers 概述
+
+> 基于 superpowers v6.2.0 源码分析。源码位置：`~/.config/opencode/node_modules/superpowers/`
+
+## 是什么
+
+Superpowers 是一个跨平台的 coding agent 增强插件，通过 **skills（技能）** + **bootstrap 注入** 实现 agent 行为编排。它的核心不是定义新的 agent 类型，而是通过在会话启动时注入一段"元指令"（`using-superpowers`），强制 agent 在执行任何任务前先检查并加载相关技能。
+
+## 核心架构
+
+```
+用户输入
+  │
+  ▼
+┌─────────────────────────────────────────┐
+│  Bootstrap 注入（messages.transform）     │
+│  将 using-superpowers SKILL.md 内容      │
+│  注入到第一条 user message 的 parts 前面  │
+└──────────────────┬──────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────┐
+│  Agent 看到 bootstrap 指令              │
+│  "你有 superpowers，必须先检查技能"       │
+│  │                                      │
+│  ├─ "构建功能" → 加载 brainstorming 技能 │
+│  ├─ "修 bug" → 加载 systematic-debugging│
+│  └─ "执行计划" → 加载 SDD 或 executing   │
+└──────────────────┬──────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────┐
+│  技能驱动的工作流                        │
+│  brainstorming → writing-plans →        │
+│  subagent-driven-development →          │
+│  requesting-code-review →               │
+│  finishing-a-development-branch          │
+└─────────────────────────────────────────┘
+```
+
+## 与 harness work agent 的区别
+
+| 维度 | Superpowers | harness work agent |
+|------|------------|-------------------|
+| 编排者 | 宿主内置 agent + 技能 prompt | 自定义 `work` agent（`mode: primary`） |
+| Worker | 宿主内置 `general-purpose` | 宿主内置 `explore` / `general` |
+| 自定义 agent | 无 | 7 个（work/extract/revise/query/lint/pyit/pyut） |
+| 平台 | 跨平台（11+ harness） | 仅 opencode |
+
+## 模块索引
+
+- [Bootstrap 注入](/superpowers/bootstrap) — 插件加载、messages.transform hook、跨平台注入
+- [技能体系](/superpowers/skills) — 14 个技能、自动触发、Red Flags
+- [主工作流](/superpowers/workflow) — brainstorming → plans → SDD → review → finish
+- [Subagent-Driven Development](/superpowers/sdd) — SDD 核心流程、implementer/reviewer 模板、fix loop
+- [并行派发](/superpowers/parallel) — dispatching-parallel-agents 技能
+- [上下文管理](/superpowers/context) — 文件传递、Ledger、Model Selection
+- [与 work agent 对比](/superpowers/comparison) — 架构、调度策略、上下文隔离的逐项对比

package/skills/read-docs/references/superpowers/parallel.md

@@ -0,0 +1,49 @@
+# 并行派发（dispatching-parallel-agents）
+
+## 与 SDD 的区别
+
+| 维度 | SDD | dispatching-parallel-agents |
+|------|-----|---------------------------|
+| 场景 | 执行计划中的串行任务 | 修复多个独立问题 |
+| 并行 | ❌ 禁止并行实现 | ✅ 核心就是并行 |
+| 任务来源 | 实现计划 | 多个独立失败（不同文件/子系统） |
+| Review | 每任务两阶段 review | 返回后统一验证 |
+| 模型选择 | 精细策略 | 统一用 general-purpose |
+
+## 使用条件
+
+**使用**：
+- 3+ 个独立失败（不同根因）
+- 各问题可独立理解（不需交叉上下文）
+- 无共享状态（不会编辑同一文件）
+
+**不使用**：
+- 失败相关（修一个可能修复其他）
+- 需要理解全局系统状态
+- agent 会互相干扰
+
+## 派发模式
+
+```
+# 3 个独立失败，一条消息 3 个 task 调用
+Subagent (general-purpose): "Fix agent-tool-abort.test.ts failures"
+Subagent (general-purpose): "Fix batch-completion-behavior.test.ts failures"
+Subagent (general-purpose): "Fix tool-approval-race-conditions.test.ts failures"
+# 全部并行执行
+```
+
+> Multiple dispatch calls in one response = parallel execution. One per response = sequential.
+
+## Prompt 结构要求
+
+好的并行 agent prompt：
+1. **Focused** — 一个清晰的问题域
+2. **Self-contained** — 理解问题所需的全部上下文
+3. **Specific about output** — agent 应返回什么
+
+## 返回后验证
+
+1. **Review each summary** — 理解什么变了
+2. **Check for conflicts** — agent 是否编辑了同一代码
+3. **Run full suite** — 验证所有 fix 协同工作
+4. **Spot check** — agent 可能有系统性错误

package/skills/read-docs/references/superpowers/sdd.md

@@ -0,0 +1,183 @@
+# Subagent-Driven Development (SDD)
+
+## 核心原则
+
+> **Fresh subagent per task + task review (spec + quality) + broad final review = high quality, fast iteration**
+
+## SDD 完整流程
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Setup                                                      │
+│  ├─ 确保在隔离工作区（using-git-worktrees）                  │
+│  ├─ 创建 SDD 工作区目录: .superpowers/sdd/<plan-name>/      │
+│  ├─ 检查 Ledger（progress.md）确定已完成任务                 │
+│  ├─ 读取计划，创建 todos                                     │
+│  └─ 预审计划冲突（任务矛盾、与约束冲突）                     │
+├─────────────────────────────────────────────────────────────┤
+│  Per Task Loop                                              │
+│  │                                                          │
+│  ├─ 1. 记录 BASE = git rev-parse HEAD                      │
+│  ├─ 2. 提取任务 brief: scripts/task-brief PLAN N            │
+│  │     → .superpowers/sdd/<plan>/task-N-brief.md           │
+│  ├─ 3. 派发 implementer subagent                            │
+│  │     prompt 包含: brief 路径 + report 路径 + 上下文       │
+│  │     (不粘贴计划全文，不让 subagent 读整个计划)             │
+│  │                                                          │
+│  ├─ 4. 处理 implementer 报告                                │
+│  │     DONE → 生成 review package，派发 task reviewer       │
+│  │     DONE_WITH_CONCERNS → 读顾虑，决定是否先处理           │
+│  │     NEEDS_CONTEXT → 补充上下文，重新派发                  │
+│  │     BLOCKED → 评估阻塞，换模型/拆任务/升级                │
+│  │                                                          │
+│  ├─ 5. Task Review（两阶段）                                │
+│  │     a. Spec Compliance: 对照 brief 检查实现               │
+│  │     b. Code Quality: 清洁性/DRY/边界情况                 │
+│  │     verdict: ✅ + Approved → 完成任务                     │
+│  │     verdict: ❌ 或有 Critical/Important → 进入 fix loop   │
+│  │                                                          │
+│  ├─ 6. Fix Loop（最多 5 轮）                                │
+│  │     Round 1-3: 恢复原 implementer（context 完整）         │
+│  │     Round 4-5: 新 implementer + 更强模型（fresh eyes）    │
+│  │     每轮: fix → re-test → scoped re-review               │
+│  │     Round 5 仍有 open findings → Adjudicate              │
+│  │                                                          │
+│  ├─ 7. Adjudicate（仅 Round 5 触发）                        │
+│  │     reviewer 错误/可争议 → park with ruling              │
+│  │     真问题但不 load-bearing → park with ruling            │
+│  │     真问题且 load-bearing → STOP, report BLOCKED          │
+│  │                                                          │
+│  └─ 8. 完成: 写 ledger, 标记 todo complete                  │
+│                                                             │
+│  → 下一任务（串行，不并行）                                   │
+├─────────────────────────────────────────────────────────────┤
+│  Final Review                                               │
+│  ├─ 生成全分支 review package (MERGE_BASE..HEAD)           │
+│  ├─ 派发 final reviewer（最强模型）                         │
+│  ├─ 有 findings → 一次 fix dispatch + 一次 scoped re-review │
+│  └─ 残留 load-bearing findings → 报告给用户                  │
+├─────────────────────────────────────────────────────────────┤
+│  Finish                                                     │
+│  ├─ 删除 SDD 工作区（git 历史是记录）                       │
+│  └─ 调用 finishing-a-development-branch 技能                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Implementer Subagent 派发
+
+**模板**: `implementer-prompt.md`
+
+派发 prompt 结构：
+
+```
+Subagent (general-purpose):
+  description: "Implement Task N: [task name]"
+  model: [MODEL — 必填，按 Model Selection 选择]
+  prompt: |
+    You are implementing Task N: [task name]
+
+    ## Task Description
+    Read your task brief first: [BRIEF_FILE]
+
+    ## Context
+    [场景设置：任务在项目中的位置、依赖、架构上下文]
+
+    ## Your Job
+    1. Implement exactly what the task specifies
+    2. Write tests (following TDD if task says to)
+    3. Verify implementation works
+    4. Commit your work
+    5. Self-review
+    6. Report back
+
+    ## Report Format
+    Write your full report to [REPORT_FILE].
+
+    Then report back with ONLY (under 15 lines):
+    - Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+    - Commits created
+    - One-line test summary
+    - Concerns
+    - Report file path
+```
+
+**关键设计**：
+1. **文件传递上下文**：brief 和 report 都是文件，不经过 controller 的 context window
+2. **简短返回**：implementer 只返回 ≤15 行的状态摘要，详情写文件
+3. **model 必填**：省略 model 会继承 session 最贵模型
+4. **不并行实现任务**：`Never dispatch multiple implementation subagents in parallel (conflicts)`
+
+## Task Reviewer Subagent
+
+**模板**: `task-reviewer-prompt.md`
+
+Reviewer 获取三个文件路径 + 全局约束：
+- BRIEF_FILE — 任务详情
+- REPORT_FILE — implementer 的报告
+- DIFF_FILE — review package（commits + stat + full diff with -U10 context）
+
+**两阶段 review**：
+1. **Spec Compliance**：Missing / Extra / Misunderstood
+2. **Code Quality**：Clean separation / Error handling / DRY / Edge cases / Tests verify real behavior
+
+**关键原则**：
+- **不信任 implementer 报告**：`Treat the implementer's report as unverified claims`
+- **不重新运行测试**：implementer 已运行并报告，reviewer 只在阅读代码产生具体疑虑时才跑 focused test
+- **不做全库爬取**：`Do not crawl the broader codebase`
+
+## Fix Loop 机制
+
+```
+Review 有 Critical/Important findings
+  │
+  ▼
+Round 1-3: 恢复原 implementer
+  ├─ 发送 open findings verbatim
+  ├─ implementer fix → re-test → append fix report
+  ├─ 生成 scoped review package (FIX_BASE..HEAD)
+  └─ 派发 re-reviewer (re-review-prompt.md)
+       ├─ ADDRESSED → 该 finding 关闭
+       └─ NOT ADDRESSED → 继续 open
+  │
+  ▼ (有 open findings)
+Round 4-5: 新 implementer + 更强模型
+  ├─ "A prior implementer attempted this task [N] times; you own it now."
+  ├─ 同样流程: fix → re-test → scoped re-review
+  └─ ...
+  │
+  ▼ (Round 5 仍有 open findings)
+Adjudicate (controller 自己裁决)
+  ├─ reviewer 错误 → park with ruling
+  ├─ 真但不 load-bearing → park with ruling
+  └─ 真且 load-bearing → STOP, report BLOCKED
+```
+
+**Re-review 是 scoped 的**：只验证 findings 是否解决 + 检查 fix diff 是否引入新问题。不重新审查未改动代码。out-of-scope 观察记入 ledger，不扩展 loop。
+
+## SDD 工作区
+
+每个计划有独立的工作区目录：
+
+```
+.superpowers/sdd/
+  .gitignore          # 内容: *（忽略所有）
+  <plan-name>/
+    progress.md       # Ledger
+    task-1-brief.md   # 任务 1 的完整文本
+    task-1-report.md  # 任务 1 implementer 的报告
+    review-a1b2..d4e5.diff  # 任务 1 的 review package
+    ...
+```
+
+**设计原因**：
+- `.superpowers/sdd/` 在 `.gitignore` 中，不污染 git status
+- 不在 `.git/` 下（Claude Code 禁止 agent 写 `.git/`）
+- 每计划独立目录，防止并发计划互相干扰
+
+## 辅助脚本
+
+| 脚本 | 作用 |
+|------|------|
+| `scripts/task-brief PLAN N` | 从计划文件提取第 N 个任务的完整文本到 `task-N-brief.md` |
+| `scripts/review-package PLAN BASE HEAD` | 生成 diff 包（commits + stat + full diff -U10）到文件 |
+| `scripts/sdd-workspace PLAN` | 解析并创建计划的工作区目录 |

package/skills/read-docs/references/superpowers/skills.md

@@ -0,0 +1,68 @@
+# 技能体系
+
+## 技能列表
+
+Superpowers 包含 14 个技能，覆盖完整的软件开发流程：
+
+| 技能 | 阶段 | 说明 |
+|------|------|------|
+| `using-superpowers` | 元技能 | Bootstrap：如何发现和使用技能 |
+| `brainstorming` | 需求 | 苏格拉底式设计对话，产出 spec |
+| `writing-plans` | 规划 | 将 spec 拆解为 bite-sized 任务计划 |
+| `using-git-worktrees` | 隔离 | 创建隔离工作区 |
+| `subagent-driven-development` | 执行（SDD） | 每任务一个 subagent + 两阶段 review |
+| `executing-plans` | 执行（inline） | 批量执行 + 检查点（无 subagent 时的替代） |
+| `dispatching-parallel-agents` | 执行（并行） | 并行派发独立问题的修复 |
+| `test-driven-development` | 实现 | RED-GREEN-REFACTOR |
+| `systematic-debugging` | 调试 | 4 阶段根因分析 |
+| `requesting-code-review` | 审查 | 派发 reviewer subagent |
+| `receiving-code-review` | 审查 | 响应 review 反馈 |
+| `verification-before-completion` | 验证 | 完成前验证 |
+| `finishing-a-development-branch` | 收尾 | merge/PR/keep 决策 |
+| `writing-skills` | 元技能 | 创建新技能 |
+
+## 技能自动触发
+
+`using-superpowers` 是所有技能的入口。它的核心规则：
+
+> **Invoke relevant or requested skills BEFORE any response or action** — including clarifying questions, exploring the codebase, or checking files.
+
+这意味着 agent 在回答任何问题（包括澄清问题）之前，必须先检查是否有相关技能。技能通过 `<SUBAGENT-STOP>` 标记跳过被派发为 subagent 的会话：
+
+```markdown
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, ignore this skill.
+</SUBAGENT-STOP>
+```
+
+### 验收测试
+
+> A working integration auto-triggers the `brainstorming` skill before any code is written.
+
+用户说 "Let's make a react todo list" 时，agent 应自动触发 `brainstorming` 技能。
+
+## Red Flags 表
+
+`using-superpowers` 包含一个 Red Flags 表，列出 agent 可能用来"合理化"跳过技能的借口：
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check for skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
+| "This doesn't need a formal skill" | If a skill exists, use it. |
+| "I remember this skill" | Skills evolve. Read current version. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+
+## 技能优先级
+
+> When multiple skills apply, process skills come first — they set the approach, then implementation skills carry it out.
+
+- "Let's build X" → `brainstorming` first, then implementation skills
+- "Fix this bug" → `systematic-debugging` first, then domain skills
+
+## 用户指令优先级
+
+> User instructions (CLAUDE.md, AGENTS.md, GEMINI.md, etc, direct requests) take precedence over skills, which in turn override default behavior. Only skip skill workflows or instructions when your human partner has explicitly told you to.