parallel-builder

并行构建器：分而治之的实现

将计划／规格分解为独立任务，启动构建 Agent 并行实现各部分，然后整合结果。与 feature-council（同一任务、不同方案）不同，此技能会为每个 Agent 分配不同的工作部分，以实现最快速度。

当你有规格、PRD 或计划，并希望快速并行实现时，请使用此技能。

适用场景

✅ 适合使用 parallel-builder：

• 实现 PRD 或规格文档
• 可拆分为多个部分的大型功能
• 速度比方案多样性更重要时
• 基于参考文件或详细计划进行构建
• 边界清晰的多文件实现

❌ 不适合使用：

• 修复 Bug（使用 debug-council）
• 希望尝试不同方案的功能（使用 feature-council）
• 无法并行处理的任务
• 简单的单文件修改

---

Parallel-Builder 的优势场景

🚀 最大提速：多文件规格

当规格需要生成多个独立文件时，parallel-builder 的速度最快：

┌─────────────────────────────────────────────────────────────┐
│  IDEAL: Each agent owns different files                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Wave 2: TRUE PARALLEL EXECUTION                            │
│  ┌─────────────────┐ ┌─────────────────┐ ┌────────────────┐│
│  │ Agent 1         │ │ Agent 2         │ │ Agent 3        ││
│  │ userService.ts  │ │ authService.ts  │ │ apiClient.ts   ││
│  └─────────────────┘ └─────────────────┘ └────────────────┘│
│          ↓                   ↓                   ↓          │
│      [PARALLEL - All 3 run simultaneously]                  │
│                                                             │
│  Speedup: ~3× faster than sequential                        │
└─────────────────────────────────────────────────────────────┘

适用场景示例：

• 全栈功能（类型 + 服务 + 路由 + UI 组件）
• 微服务实现（多个独立服务）
• CRUD API（每种资源各用独立文件）
• 插件／模块系统（各模块彼此独立）
• 测试套件（针对不同模块的测试文件）

⚠️ 回退为顺序执行：单文件规格

当多个任务修改同一个文件时，并行执行会引发冲突。此技能会自动回退为顺序执行：

┌─────────────────────────────────────────────────────────────┐
│  LIMITED: All agents modify same file                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Wave 3: SEQUENTIAL (conflict avoidance)                    │
│  ┌─────────────────┐                                       │
│  │ Agent 1         │ → modifies BG600L.cpp                 │
│  └────────┬────────┘                                       │
│           ↓                                                 │
│  ┌─────────────────┐                                       │
│  │ Agent 2         │ → modifies BG600L.cpp                 │
│  └────────┬────────┘                                       │
│           ↓                                                 │
│  ┌─────────────────┐                                       │
│  │ Agent 3         │ → modifies BG600L.cpp                 │
│  └─────────────────┘                                       │
│                                                             │
│  No speedup, but still provides organized task breakdown    │
└─────────────────────────────────────────────────────────────┘

仍然适用于：

• 有条理地拆分和跟踪任务
• 明确划分关注点
• 系统地实现复杂的单文件修改

提速预估

规格类型	并行潜力	预期提速
多文件、模块彼此独立	高	快 50-80%
多文件、部分共享	中	快 30-50%
文件较少、函数较多	低	快 10-20%
单文件、多处修改	极低	~0%（顺序执行）

在你确认之前，此技能会在执行计划中显示预估提速。

---

步骤 0：接收计划输入

首先，向用户获取计划。接受以下任一种输入：

1. 文件路径：用户提供规格、PRD 或计划文件的路径
2. 内联描述：用户描述要构建的内容
3. 参考文件：用户指出要复刻／扩展的现有代码

What would you like me to build? You can provide:
- A file path to a spec/PRD/plan
- A description of the feature
- A reference file to work from

I'll decompose it into parallel tasks for fast implementation.

---

步骤 1：分析并拆分

阅读计划并识别工作单元。对于每个单元，确定：

1. 独立性：能否在无需等待其他任务的情况下构建？
2. 依赖项：构建此单元之前必须具备什么？
3. 输出：会创建哪些文件／接口？
4. 复杂度：粗略估算（小／中／大）

拆分规则

规则	说明
文件边界	每个 Agent 负责一个文件或一组密切相关的文件
功能边界	每个 Agent 负责一项独立功能／能力
分层边界	按层拆分（类型、服务、API、UI）
尽量减少耦合	任务应尽量减少接口依赖

创建依赖关系图

识别以下三类：

WAVE 1 (Foundation - No Dependencies):
- Shared types/interfaces
- Configuration
- Constants
- Base utilities

WAVE 2 (Core - Depends on Wave 1):
- Services
- Business logic
- Data access
- Core components

WAVE 3+ (Integration - Depends on Previous):
- API routes that use services
- UI that uses components
- Integration code
- Tests

---

步骤 2：定义共享契约

重要：启动 Agent 之前，先定义它们共享的契约。

创建一个由所有 Agent 接收的共享上下文：

## Shared Contracts

### Interfaces
[Define all shared types/interfaces that multiple agents need]

### File Ownership
[Map which agent owns which files - no overlaps]

### Naming Conventions
[Consistent naming across all agents' work]

### Import Paths
[How agents should import from each other's domains]

这样可以避免冲突，并确保各部分能够配合。

---

步骤 3：向用户展示执行计划

展示拆分结果并征求确认：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                    PARALLEL BUILD PLAN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Source: [file path or "inline description"]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                      TASK BREAKDOWN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## Wave 1: Foundation (3 agents in parallel)

| Task | Agent | Files | Complexity |
|------|-------|-------|------------|
| Create shared types | builder-solver-1 | types/*.ts | Small |
| Database schema | builder-solver-2 | schema.prisma | Medium |
| Config & constants | builder-solver-3 | config/*.ts | Small |

## Wave 2: Core (2 agents in parallel, after Wave 1)

| Task | Agent | Files | Depends On |
|------|-------|-------|------------|
| User service | builder-solver-4 | services/user.ts | Wave 1 types |
| Auth service | builder-solver-5 | services/auth.ts | Wave 1 types |

## Wave 3: Integration (1 agent, after Wave 2)

| Task | Agent | Files | Depends On |
|------|-------|-------|------------|
| API routes + wiring | builder-solver-6 | routes/*.ts, index.ts | Wave 1, 2 |

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                       SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total Tasks: 6
Total Waves: 3
Parallel Agents: Up to 3 concurrent
Estimated Speedup: ~50-60% faster than sequential

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Proceed with this plan? (y/n/modify)

如果用户说“修改”，允许他们调整任务边界或波次分配。

---

步骤 4：逐波执行

每一轮

1. 准备 Agent 提示词，包括：

   • 各自的具体任务
   • 共享约定（来自步骤 2）
   • 之前各轮的输出（如有）
   • 他们负责的文件（不得触碰其他文件）

2. 并行启动 Agent：

Task(agent: "builder-solver-1", prompt: "[TASK 1 PROMPT]")
Task(agent: "builder-solver-2", prompt: "[TASK 2 PROMPT]")
Task(agent: "builder-solver-3", prompt: "[TASK 3 PROMPT]")
... (all in the SAME batch - parallel execution)

3. 跟踪进度：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                  WAVE 1 PROGRESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
☑ builder-solver-1 - Complete (types/*.ts)
☑ builder-solver-2 - Complete (schema.prisma)
☐ builder-solver-3 - Working... (config/*.ts)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

4. 在本轮完成后收集输出

5. 将上下文传递给下一轮——包括已完成各轮的相关输出

---

步骤 5：Agent 提示词模板

每个 builder-solver Agent 都会收到结构化提示词：

# Builder Task: [TASK NAME]

## Your Assignment

[SPECIFIC DESCRIPTION OF WHAT TO BUILD]

## Files You Own

You are responsible for creating/modifying ONLY these files:
- [file1.ts]
- [file2.ts]

⚠️ DO NOT modify any other files.

## Shared Contracts

[PASTE SHARED INTERFACES/TYPES FROM STEP 2]

## Context from Previous Waves

[PASTE RELEVANT OUTPUTS FROM EARLIER WAVES, IF ANY]

## Requirements

1. [Requirement 1]
2. [Requirement 2]
3. [Requirement 3]

## Expected Output

Create the files listed above with complete, production-ready implementations.
Follow the shared contracts exactly.

---

步骤 6：集成与验证

所有轮次完成后：

6.1 应用所有更改

Agent 提出更改方案，由协调器将其应用到代码库。

6.2 检查冲突

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                  CONFLICT CHECK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ No file conflicts (agents stayed in their lanes)
✅ Interface contracts honored
✅ Import paths valid
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

如果存在冲突，请解决：

• 集成文件优先采用后续轮次的版本
• 合并兼容的更改
• 将不兼容的更改标记出来，交由用户决定

6.3 运行验证

# Type check
npm run typecheck  # or equivalent

# Lint
npm run lint

# Tests (if any)
npm run test

修复发现的所有问题。

---

步骤 7：报告结果

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                 PARALLEL BUILD COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 📊 Execution Summary

| Wave | Agents | Tasks | Status |
|------|--------|-------|--------|
| 1 | 3 | Foundation | ✅ Complete |
| 2 | 2 | Core Services | ✅ Complete |
| 3 | 1 | Integration | ✅ Complete |

Total Time: [X seconds]
Sequential Estimate: [Y seconds]  
Speedup: [Z%]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 📁 Files Created/Modified

### Wave 1 Output
| Agent | Files Created |
|-------|--------------|
| builder-solver-1 | types/user.ts, types/auth.ts |
| builder-solver-2 | prisma/schema.prisma |
| builder-solver-3 | config/index.ts, config/constants.ts |

### Wave 2 Output
| Agent | Files Created |
|-------|--------------|
| builder-solver-4 | services/user.ts |
| builder-solver-5 | services/auth.ts |

### Wave 3 Output
| Agent | Files Created |
|-------|--------------|
| builder-solver-6 | routes/user.ts, routes/auth.ts, index.ts |

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## ✅ Verification

- Type Check: ✅ Passed
- Lint: ✅ Passed  
- Tests: ✅ Passed (or N/A)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 🔍 What Each Agent Built

### builder-solver-1: Shared Types
- Created User, AuthToken, Session interfaces
- Defined validation schemas

### builder-solver-2: Database Schema
- Created User, Session, Token models
- Set up relations and indexes

... (for each agent)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 📋 Implementation from Spec

| Spec Requirement | Status | Implemented By |
|------------------|--------|----------------|
| User registration | ✅ | builder-solver-4, 6 |
| Authentication | ✅ | builder-solver-5, 6 |
| Session management | ✅ | builder-solver-5 |
| API endpoints | ✅ | builder-solver-6 |

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

错误处理

Agent 故障

如果 Agent 故障：

1. 使用相同的提示词重试一次
2. 如果仍然失败，向用户报告错误详情
3. 询问用户是否希望：
   • 跳过此任务并继续
   • 提供指导后重试
   • 中止构建

依赖项故障

如果第 N 轮失败，而第 N+1 轮依赖于该轮：

1. 阻止依赖轮次继续
2. 报告阻塞原因
3. 提供选项：修复后继续，或中止

---

配置选项

选项	默认值	说明
最大并行 Agent 数	5	同时运行的 Agent 数量上限
Agent 超时	5 min	每个 Agent 的最长运行时间
自动验证	true	完成后运行类型检查/lint
显示进度	true	显示进度更新

用户可以指定：parallel-builder with 3 max agents

---

Agent

agents/ 目录中有 10 个 builder solver Agent：

• builder-solver-1 到 builder-solver-10

所有 Agent：

• 指令相同（专注于实现分配给自己的部分）
• 使用较低的温度（0.4），以保持一致性
• 拥有完整的工具访问权限（Read、Write、Grep、Glob、LS、Shell）
• 遵守文件所有权边界
• 严格遵循共享约定

---

与其他技能的区别

方面	debug-council	feature-council	parallel-builder
输入	要修复的 Bug	要构建的功能	要实现的规范/计划
Agent 任务	同一个问题	同一项功能	不同的部分
目标	找到正确的修复方案	探索多种方法	快速并行执行
选择方式	多数表决	综合/合并	集成
速度	N 个 Agent，1 个问题	N 个 Agent，1 项功能	N 个部分，约 N 倍提速

---

示例

示例 1：来自 PRD 文件

User: parallel-builder from docs/auth-prd.md

Orchestrator:
1. Reads docs/auth-prd.md
2. Decomposes into: types, user-service, auth-service, middleware, routes
3. Creates 3 waves
4. Executes in parallel
5. Integrates and verifies

示例 2：来自描述

User: parallel-builder a full CRUD API for a blog with posts, comments, and users

Orchestrator:
1. Decomposes: types, 3 services, 3 route files, integration
2. Wave 1: types (1 agent)
3. Wave 2: 3 services in parallel (3 agents)
4. Wave 3: 3 route files in parallel (3 agents)
5. Wave 4: integration (1 agent)

示例 3：来自参考资料

User: parallel-builder something like src/features/users but for products

Orchestrator:
1. Reads src/features/users to understand pattern
2. Creates parallel tasks to replicate for products
3. Executes maintaining same architecture