用户：帮我给这个 API 加个缓存
AI：马上写！✓ 已添加 cache 模块
用户：等等，这个缓存在集群环境下会怎样？
AI：呃……

用户：实现用户注册功能
AI：写完了！
用户：测试在哪？
AI：哦，补上。（写了一个 import unittest 但从未运行的测试）
用户：异常处理呢？
AI：马上加。（又产生了新的 bug）

┌─────────────────────────────────────────────────────────┐
│  步骤 1：后退一步（Step Back）                            │
│  "我想确认一下，你是想实现 XXX 吗？具体来说……"              │
├─────────────────────────────────────────────────────────┤
│  步骤 2：提炼规格（Extract Spec）                         │
│  将对话转化为结构化的 SPEC.md                              │
├─────────────────────────────────────────────────────────┤
│  步骤 3：分块展示（Chunked Presentation）                 │
│  将规格拆分为短小、可消化的段落，逐段确认                  │
├─────────────────────────────────────────────────────────┤
│  步骤 4：制定计划（Make a Plan）                          │
│  创建足够清晰的实现计划，可供"热情的初级工程师"执行        │
├─────────────────────────────────────────────────────────┤
│  步骤 5：子代理驱动开发（Subagent-Driven Development）     │
│  调度子代理处理每个工程任务，审查后继续                    │
├─────────────────────────────────────────────────────────┤
│  步骤 6：TDD 优先（Test-First）                           │
│  红→绿→重构，强调真正的测试驱动开发                        │
└─────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│  Skill 元信息（Metadata）                             │
│  - name: 技能名称                                     │
│  - trigger: 触发时机（自动激活 / 手动调用）            │
│  - description: 功能描述                             │
│  - dependencies: 依赖的其他 Skills                    │
├──────────────────────────────────────────────────────┤
│  前置条件（Pre-conditions）                           │
│  - 检查环境状态、文件状态、变量状态                    │
├──────────────────────────────────────────────────────┤
│  核心指令（Core Instructions）                         │
│  - 详细的执行步骤（通常为 5-15 个步骤）                │
│  - 每个步骤都有明确的验收标准                          │
├──────────────────────────────────────────────────────┤
│  后置验证（Post-verification）                        │
│  - 验证任务是否真正完成                                │
│  - 失败时提供具体的修复建议                            │
└──────────────────────────────────────────────────────┘

主代理（Main Agent）
  ├── 任务 1 → 子代理 A（独立 Worktree）
  │             └── 结果：审查通过 ✓ → 进入下一步
  ├── 任务 2 → 子代理 B（独立 Worktree）
  │             └── 结果：审查发现问题 → 打回重做
  └── 任务 3 → 子代理 C（独立 Worktree，可与 B 并行）
                └── 结果：审查通过 ✓ → 进入下一步

用户：我想给这个 API 加缓存
↓
brainstorming 激活：
  "让我确认一下：你想给哪个端点加缓存？缓存策略是什么？
   是本地内存缓存还是分布式缓存？
   缓存的 key 如何设计？
   缓存失效策略是什么？
   你希望缓存命中和未命中时的行为分别是什么？"
↓
用户回答后 → 想法被精炼为清晰的规格

for task in plan:
    subagent = spawn_fresh_subagent(task)
    result = subagent.execute()
    
    if verify(result):
        continue  # 进入下一步
    else:
        subagent.fix(feedback)  # 打回修复
        retry_until_pass()       # 重试直到通过

┌────────────────────────────────────────────┐
│  阶段 1：红（RED）                          │
│  写一个首先会失败的测试                      │
│  "这个功能还不存在，测试应该失败"            │
├────────────────────────────────────────────┤
│  阶段 2：绿（GREEN）                         │
│  只写通过测试所需的最少代码                  │
│  "不追求完美，只追求通过"                    │
├────────────────────────────────────────────┤
│  阶段 3：重构（REFACTOR）                    │
│  在测试保护下改进代码质量                    │
│  "删除重复、提升清晰度、保持功能不变"         │
└────────────────────────────────────────────┘

□ 所有测试通过（包括新测试和回归测试）
□ 代码符合项目编码规范
□ 文档已更新（如有必要）
□ Commit 消息符合规范（conventional commits）
□ 推送到远程仓库
□ 创建 Pull Request / Merge Request
□ 关联相关 Issue
□ 通知相关人员审查
□ 清理不再需要的 Worktree

/superpowers status
# 预期输出：Superpowers v5.0.6 ✓ 已激活

> superpowers enable
> superpowers configure

用户：帮我实现 JWT 认证中间件

Superpowers（brainstorming 激活）：
"让我确认一下需求：
1. 你想使用哪种 JWT 库？（PyJWT / python-jose / python-jwt）
2. Token 的存储位置？Header（Bearer）？Cookie？还是两者都支持？
3. Token 刷新策略？Access Token + Refresh Token 双 Token？还是单一 Token + 过期时间？
4. 错误响应格式？是返回 JSON 还是重定向？
5. 是否需要支持黑名单 / 注销功能？"

用户：PyJWT，Bearer Header，支持刷新，黑名单暂不需要。

Superpowers：明白了，开始创建规格文档。

Writing-plans 输出：

任务 1：创建 auth 配置模块（2 分钟）
  - 新建 config/auth_settings.py
  - 定义 JWTSetting 模型（Pydantic）
  - 验收：配置可被导入，字段验证生效

任务 2：实现 JWT 工具函数（3 分钟）
  - encode_jwt / decode_jwt / refresh_jwt
  - 验收：单元测试通过，覆盖率 100%

任务 3：实现认证中间件（5 分钟）
  - JWTAuthMiddleware 类
  - verify_token 依赖注入
  - 验收：集成测试通过

任务 4：实现认证路由（3 分钟）
  - POST /auth/login（生成 Token）
  - POST /auth/refresh（刷新 Token）
  - 验收：API 测试通过

任务 5：集成测试与文档（2 分钟）
  - 端到端测试
  - 更新 README

Subagent-driven-development 激活：

[任务 1] → 子代理 A（Worktree: wt-auth-1）
  → 完成：config/auth_settings.py
  → 主代理审查：✓ 通过

[任务 2] → 子代理 B（Worktree: wt-auth-2）
  → 完成：auth/jwt_utils.py + tests/test_jwt_utils.py
  → 主代理审查：发现覆盖率不足 → 打回
  → 子代理 B 修复：补充边界 case 测试
  → 主代理审查：✓ 通过

[任务 3] + [任务 4]（可并行）
  → 子代理 C + D 并行执行
  → 两个 Worktree 同时工作
  → 各自审查通过后进入任务 5

[任务 5] → 子代理 E（Worktree: wt-auth-final）
  → 完成端到端测试 + README 更新
  → TDD Skill 激活：确认覆盖率 87% > 85% ✓
  → Finishing-a-branch Skill 激活：合并到 main

Finishing-a-branch 激活：

□ 所有测试通过：✓（47 个测试，绿灯）
□ 覆盖率检查：✓（87.3%）
□ Commit 消息：✓（conventional commits 格式）
□ PR 创建：✓（PR #42: feat: add JWT authentication middleware）
□ 通知相关人员：✓（@reviewer）
□ 清理 Worktree：✓（删除了 5 个临时 worktree）

skills/
  └── my-custom-skill/
        ├── SKILL.md          # Skill 定义文件（必需）
        ├── references/        # 参考文档（可选）
        │     ├── examples.md
        │     └── templates.md
        ├── scripts/           # 辅助脚本（可选）
        │     └── validate.sh
        └── tests/             # Skill 自身测试（可选）
              └── test_skill.py

### 6.3 创建示例：documentation-check Skill

假设你经常需要在代码变更后检查文档同步情况，可以创建一个 `documentation-check` Skill：

```markdown
---
name: "documentation-check"
description: "在代码变更后检查相关文档是否同步更新"
trigger: "automatic"
---

# Documentation Check Skill

## 触发条件

当检测到以下文件变更时自动激活：
- `*.py` / `*.ts` / `*.js` → 检查 `docs/` 中是否有相关文档
- `API*.md` 变更 → 检查代码中是否有对应实现
- `CHANGELOG.md` 变更 → 检查版本号是否正确

## 执行步骤

### 步骤 1：识别变更文件

列出本次变更涉及的所有文件。

### 步骤 2：查找相关文档

对于每个代码文件，查找名称相似的 `.md` 文件或 `docs/` 目录下的相关文档。

### 步骤 3：检查同步状态

### 步骤 4：输出报告

```markdown
## 文档同步报告

| 文件 | 相关文档 | 同步状态 |
|------|----------|----------|
| auth/jwt.py | docs/auth.md | ⚠️ 过期（代码新于文档 3 天） |
| api/users.py | docs/api/users.md | ✓ 同步 |

### 6.4 Skill 的注册与分发

创建好 Skill 后，在项目的 `superpowers.json` 中注册：

```json
{
  "skills": [
    "brainstorming",
    "writing-plans",
    "subagent-driven-development/executing-plans",
    "test-driven-development",
    "my-custom-skill"
  ]
}

编码前           → brainstorming
                  → writing-plans
                  → using-git-worktrees

编码中（循环）    → subagent-driven-development/executing-plans
                  → test-driven-development（RED-GREEN-REFACTOR）
                  → requesting-code-review

编码后           → finishing-a-development-branch
                  → documentation-check（如果使用了自定义 Skill）