sanguo_vnpy_v2/.claude/skills/superpowers/SKILL.md

name, description

name	description
superpowers	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] 功能描述

内容结构：

## 项目信息
- 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，解析完成标记：

// 解析完成标记
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	包含三向检查结果

偏差报告格式

@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/