@wwkit/harness 1.0.9 → 1.0.11

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.

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

@@ -0,0 +1,83 @@
+# 主工作流
+
+## 完整流程
+
+```
+brainstorming → writing-plans → using-git-worktrees →
+subagent-driven-development (or executing-plans) →
+requesting-code-review → finishing-a-development-branch
+```
+
+## Brainstorming 阶段
+
+**触发**：用户说"构建 X" 或 "实现功能 Y"
+
+**流程**：
+1. 探索项目上下文（文件、文档、最近提交）
+2. 逐个提问澄清需求（一次一个问题）
+3. 提出 2-3 种方案 + 权衡 + 推荐
+4. 分段展示设计，每段后获用户确认
+5. 写设计文档到 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+6. 自审 spec（占位符扫描、一致性、范围、歧义）
+7. 用户审查 spec
+8. 调用 `writing-plans` 技能
+
+**硬门控**：在设计获批前，禁止写任何代码。
+
+## Writing Plans 阶段
+
+**输入**：已批准的 spec
+
+**产出**：实现计划文件 `docs/superpowers/plans/YYYY-MM-DD-<feature>.md`
+
+**计划格式**：
+```markdown
+# [Feature] Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
+
+**Goal:** [一句话]
+**Architecture:** [2-3 句]
+**Tech Stack:** [技术栈]
+
+## Global Constraints
+[项目级约束 — 版本、命名、平台要求等]
+
+### Task N: [Component Name]
+**Files:** Create/Modify/Test 路径
+**Interfaces:** Consumes/Produces
+- [ ] Step 1: Write the failing test
+- [ ] Step 2: Run test to verify it fails
+- [ ] Step 3: Write minimal implementation
+- [ ] Step 4: Run test to verify it passes
+- [ ] Step 5: Commit
+```
+
+**关键原则**：
+- 每步 2-5 分钟
+- 无占位符（"TBD"、"add error handling" 等是计划失败）
+- 每步包含完整代码
+- TDD：先写失败测试，再实现
+
+## 执行选择
+
+计划完成后，提供两种执行方式：
+
+| 方式 | 条件 | 特点 |
+|------|------|------|
+| Subagent-Driven Development（推荐） | 有 subagent 能力 | 每任务一个 fresh subagent + 两阶段 review |
+| Executing Plans（inline） | 无 subagent | 批量执行 + 人工检查点 |
+
+## Finishing 阶段
+
+1. 运行全量测试
+2. 检测环境（normal repo / worktree / detached HEAD）
+3. 确认 base branch
+4. 呈现选项：
+   - Merge back to base locally
+   - Push and create PR
+   - Keep as-is
+5. 执行用户选择
+6. 清理工作区（仅 Superpowers 创建的 worktree）
+
+**关键**：集成决策是用户的，agent 只呈现菜单等待回答。