parallel-builder

Parallel Builder：分割統治による実装

計画／仕様を独立したタスクに分解し、ビルダーエージェントを起動して各部分を並行して実装し、その結果を統合します。feature-council（同じタスクに対して多様なアプローチを採用）とは異なり、このスキルでは作業を異なる部分に分けて各エージェントに割り当て、最大限の速度を実現します。

仕様書、PRD、または計画があり、並行実装を迅速に進めたい場合に使用してください。

使用するタイミング

✅ parallel-builder を使用するケース：

• PRD または仕様書を実装する
• パーツに分解できる大規模な機能
• アプローチの多様性よりも速度が重要な場合
• 参照ファイルまたは詳細な計画をもとに構築する
• 明確な境界がある複数ファイルの実装

❌ 使用しないケース：

• バグ（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. 複雑さ：おおよその見積もり（小／中／大）

分解ルール

ルール	説明
ファイルの境界	ファイルごと、または密接に関連するファイル群ごとに 1 つのエージェントを割り当てる
機能の境界	機能／能力ごとに 1 つのエージェントを割り当てる
レイヤーの境界	レイヤーごとに分ける（型、サービス、API、UI）
結合を最小限にする	タスク間のインターフェース依存を最小限にする

依存関係グラフを作成する

次の 3 つのカテゴリを特定します。

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：共有コントラクトを定義する

重要：エージェントを起動する前に、共有するコントラクトを定義します。

すべてのエージェントが受け取る共有コンテキストを作成します。

## 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. エージェントのプロンプトを準備する。次の項目を含めます。

   • 担当するタスク
   • 共通の契約（ステップ 2 の内容）
   • 前のウェーブからの出力（ある場合）
   • 担当するファイル（ほかのファイルには手を加えてはいけません）

2. エージェントを並行して起動する：

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：エージェントのプロンプトテンプレート

各ビルダー・ソルバーエージェントには、構造化されたプロンプトを渡します。

# 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 すべての変更を適用する

エージェントが変更案を提示し、オーケストレーターがコードベースに適用します。

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 |

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

---

エラー処理

エージェントの失敗

エージェントが失敗した場合：

1. 同じプロンプトで1 回再試行します
2. それでも失敗した場合は、エラーの詳細をユーザーに報告します
3. 次のどれを行うか、ユーザーに確認します。
   • このタスクをスキップして続行する
   • ガイダンスを提供して再試行する
   • ビルドを中止する

依存関係の失敗

ウェーブ N が失敗し、ウェーブ N+1 がそのウェーブに依存している場合：

1. 依存するウェーブをブロックする
2. ブロッカーを報告する
3. 選択肢を提示する：修正して続行する、または中止する

---

設定オプション

オプション	デフォルト	説明
最大並列エージェント数	5	同時に実行するエージェントの最大数
エージェントのタイムアウト	5 min	エージェントごとの最大実行時間
自動検証	true	完了後に型チェック／リンターを実行します
進捗を表示	true	進捗状況を表示します

ユーザーは次のように指定できます：parallel-builder with 3 max agents

---

エージェント

agents/ ディレクトリに 10 個のビルダー・ソルバーエージェントがあります。

• builder-solver-1 から builder-solver-10 まで

すべてのエージェント：

• 同じ指示に従います（割り当てられた部分の実装に集中します）
• 一貫性を保つため、低い温度（0.4）を使用します
• すべてのツールにアクセスできます（Read、Write、Grep、Glob、LS、Shell）
• ファイルの担当範囲を守ります
• 共通の契約に厳密に従います

---

ほかのスキルとの違い

項目	debug-council	feature-council	parallel-builder
入力	修正するバグ	開発する機能	実装する仕様／計画
エージェントのタスク	同じ問題	同じ機能	異なる部分
目標	正しい修正を見つける	多様なアプローチ	高速な並列実行
選定方法	多数決	統合／マージ	統合
速度	N エージェント、1 つの問題	N エージェント、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