---
name: superpowers
description: "Main Agent Orchestrator: Linus三问 → superpowers:brainstorming → Gitea Issue → Sub Agents → 三向一致性检查"
---

# /superpowers - Main Agent 任务编排

Main Agent 工作流：编排 Sub Agents 使用 Superpowers 原生技能完成任务，通过 Gitea 协作追踪。

## 使用方法

```
/superpowers                                         # 触发 Main Agent 工作流
/superpowers "完成用户登录功能"                       # 指定任务
```

## Main Agent 工作流

### Step 1: Linus 三问过滤

工程审慎决策框架，过滤伪需求和过度设计：

| 问题 | 判断标准 | 拒绝条件 |
|------|---------|----------|
| **这是现实问题还是想象问题？** | 有明确证据或用户反馈 | "可能需要"、"也许将来" |
| **这个问题真的需要解决吗？** | 影响核心功能或用户体验 | 边缘场景、伪需求 |
| **这个方案真的能解决问题吗？** | 有明确验证路径 | 理论上可行但无验证 |

**拒绝条件时**：向用户澄清或拒绝，不继续编排。

### Step 2: 调用 superpowers:brainstorming

**调用技能：** `Skill("superpowers:brainstorming")`

**探索内容**：
- 用户意图和需求边界
- 2-3 种方案及权衡
- 设计考虑和约束

**输出**：`docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`

### Step 3: 任务分析

分析任务并制定编排策略：

| 复杂度 | 特征 | 编排策略 |
|--------|------|----------|
| **简单** | 明确的 bug 修复、小改动 | Execute → Review → 验收 |
| **中等** | 单一功能实现 | Brainstorming → Execute → Review → 验收 |
| **复杂** | 多功能、跨领域 | Brainstorming → Planning → Execute → Review → Test → 验收 |
| **调试** | 问题定位和修复 | Systematic-debugging → Execute → Test → 验收 |

**确定所需 Sub Agents**：Execute、Review、Test

### Step 4: 创建 Gitea Issue

**标题格式**：`[sanguo_vnpy_v2] 功能描述`

**内容结构**：
```markdown
## 项目信息
- Spec: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
- 复杂度: 简单/中等/复杂

## 执行清单
### Execute Sub Agent
- 使用技能: superpowers:writing-plans → superpowers:subagent-driven-development
- 完成标记: @main-agent ✅ EXECUTE_DONE

### Review Sub Agent
- 使用技能: superpowers:requesting-code-review
- 完成标记: @main-agent ✅ REVIEW_DONE verdict=approved

### Test Sub Agent (可选)
- 使用技能: superpowers:test-driven-development
- 完成标记: @main-agent ✅ TEST_DONE result=passed

### Main Agent 验收
- 三向一致性检查
- 完成标记: @main-agent ✅ VERIFICATION_PASSED
```

### Step 5: 编排 Sub Agents

#### Execute Agent

```
Agent 工具 dispatch:
- spec 文档路径
- 任务范围
- 使用技能: superpowers:writing-plans → superpowers:subagent-driven-development

完成标记: @main-agent ✅ EXECUTE_DONE
```

#### Review Agent

```
Agent 工具 dispatch:
- spec 文档路径
- plan 文档路径
- Git diff
- 使用技能: superpowers:requesting-code-review

完成标记: @main-agent ✅ REVIEW_DONE verdict=approved
```

#### Test Agent (可选)

```
Agent 工具 dispatch:
- spec 文档路径
- 功能代码路径
- 使用技能: superpowers:test-driven-development

完成标记: @main-agent ✅ TEST_DONE result=passed
```

### Step 6: 等待 Sub Agent 完成标记

监控 Gitea Issue Comments，解析完成标记：

```javascript
// 解析完成标记
const executeDone = comments.some(c => c.body.includes('@main-agent ✅ EXECUTE_DONE'))
const reviewDone = comments.some(c => c.body.includes('@main-agent ✅ REVIEW_DONE'))
const testDone = comments.some(c => c.body.includes('@main-agent ✅ TEST_DONE'))

// 根据状态编排下一阶段
if (executeDone && !reviewDone) {
  // 启动 Review
  dispatchReviewAgent()
}
```

### Step 7: 三向一致性检查

对照三向检查，逐项验证：

```
┌─────────────────────────────────────────────────────────────┐
│              验收：三向一致性检查                          │
│                                                             │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐              │
│  │  需求   │ ←→ │  设计   │ ←→ │  编码   │              │
│  │ (spec)  │    │ (plan)  │    │ (code)  │              │
│  └─────────┘    └─────────┘    └─────────┘              │
│       ↑              ↑              ↑                      │
│       └──────────────┴──────────────┘                      │
│                    一致性检查                              │
└─────────────────────────────────────────────────────────────┘
```

**检查方法**：
- 需求 (spec) → 设计 (plan)：spec 是否完整覆盖需求？
- 设计 (plan) → 编码 (code)：code 是否正确实现 plan？
- 需求 (spec) → 编码 (code)：code 是否满足 spec？

**偏差处理**：
```
发现偏差 → 发布 @main-agent ❌ CONSISTENCY_ISSUE
         ↓
      通知相关 Sub Agent
         ↓
      Sub Agent 修复
         ↓
      重新发布完成标记
         ↓
      Main Agent 重新验收
```

### Step 8: 调用 superpowers:finishing-a-development-branch

**调用技能：** `Skill("superpowers:finishing-a-development-branch")`

**流程**：
1. 验证测试
2. 检测环境（normal repo / worktree / detached HEAD）
3. 呈现选项：
   - 合并到 base-branch 本地
   - 推送并创建 Pull Request
   - 保持分支原样
   - 丢弃工作
4. 执行选择
5. 清理工作区

### Step 9: 向用户汇报

**汇报内容**：
- 整合 Sub Agent 结果
- 三向一致性检查结果
- 最终完成状态

## Sub Agent 技能映射

| Main Agent 步骤 | Sub Agent 使用的技能 | 输出 |
|----------------|---------------------|------|
| 需求探索 | `superpowers:brainstorming` | spec 文档 |
| 编写计划 | `superpowers:writing-plans` | plan 文档 |
| 执行实现 | `superpowers:subagent-driven-development` 或 `superpowers:executing-plans` | 代码 + commit |
| 代码审查 | `superpowers:requesting-code-review` | 审查报告 |
| 系统调试 | `superpowers:systematic-debugging` | 根本原因 |
| 完成收尾 | `superpowers:finishing-a-development-branch` | 合并/PR/清理 |

## Gitea 协作约定

### Comment 标记格式

| Sub Agent | 完成标记格式 | 说明 |
|-----------|-------------|------|
| Execute | `@main-agent ✅ EXECUTE_DONE` | 包含交付物清单 |
| Review | `@main-agent ✅ REVIEW_DONE verdict=approved` | 包含检查结果 |
| Test | `@main-agent ✅ TEST_DONE result=passed` | 包含测试结果 |
| Main | `@main-agent ✅ VERIFICATION_PASSED` | 包含三向检查结果 |

### 偏差报告格式

```markdown
@main-agent ❌ **CONSISTENCY_ISSUE**

## 发现偏差
### 问题: 需求 (spec) → 编码 (code) 偏差
**需求**: "..."
**代码**: "..."

### 处理要求
1. ...
2. ...
3. 重新提交 review

---
**标签**: needs-consistency-fix 🔴
```

## 严格限制

- ❌ **Main Agent 不亲自编写代码**
- ❌ **不亲自执行具体实现**
- ❌ **不跳过 Linus 三问**
- ❌ **不跳过三向一致性检查**
- ✅ **只负责编排、协调、验收**

## When Invoked（调用时必须执行）

1. **确认任务**：如果用户没有指定任务，询问要完成什么
2. **Linus 三问**：对任务进行审慎过滤
3. **调用 superpowers:brainstorming**：输出 spec 文档
4. **任务分析**：评估复杂度，确定所需的 Sub Agents
5. **创建 Gitea Issue**：建立协作中心
6. **编排 Sub Agents**：通过 Agent 工具安排执行
7. **等待完成标记**：监控 Gitea Comments
8. **三向一致性检查**：验证 spec ↔ plan ↔ code
9. **调用 superpowers:finishing-a-development-branch**：完成收尾
10. **汇报结果**：向用户汇报最终结果

## 工作产物

```
.claude/workdir/
├── BRAINSTORM.md          # Linus 三问分析结果
├── SPEC_REF.md            # Spec 文档引用
├── IMPLEMENTATION_PLAN.md  # 任务分析与 Sub Agent 分配
├── GITEA_ISSUE.md         # Gitea Issue 内容备份
├── ORCHESTRATION_LOG.md   # Sub Agent 编排日志
└── COMPLETION_SUMMARY.md  # 最终完成总结

docs/superpowers/
├── specs/                 # 由 brainstorming 生成
│   └── YYYY-MM-DD-<topic>-design.md
└── plans/                 # 由 writing-plans 生成
    └── YYYY-MM-DD-<feature-name>.md
```

## 与原始 Superpowers 的关系

此技能整合：
- **Main Agent 编排模式**（Linus 三问 + 任务编排 + 三向一致性检查）
- **Superpowers 原生工作流**（brainstorming → writing-plans → executing → review → finishing）
- **Gitea 协作机制**（Issue + Comment 标记）

Main Agent 不执行实现，只编排 Sub Agents 使用 Superpowers 技能完成任务。

## 参考文档

- sanguo_moziplus_v3 设计文档 v0.6: `docs/design/07-design-v0.5-dynamic-orchestration-integrated.md`
- Superpowers 原生工作流规范: `~/.claude/skills/superpowers/`