parallel-builder

What this skill does

# Parallel Builder: Divide-and-Conquer Implementation

Decomposes a plan/spec into independent tasks, spawns builder agents to implement each piece in parallel, and integrates the results. Unlike feature-council (same task, diverse approaches), this skill gives each agent a **different piece** of the work for maximum speed.

**Use this when you have a spec, PRD, or plan and want fast parallel implementation.**

## When to Use

✅ **Use parallel-builder for:**
- Implementing a PRD or spec document
- Large features that can be decomposed into parts
- When speed matters more than approach diversity
- Building from a reference file or detailed plan
- Multi-file implementations with clear boundaries

❌ **Don't use for:**
- Bugs (use debug-council)
- Features where you want diverse approaches (use feature-council)
- Tasks that can't be parallelized
- Simple single-file changes

---

## Where Parallel-Builder Shines

### 🚀 Maximum Speedup: Multi-File Specs

Parallel-builder is **fastest** when your spec produces **multiple independent files**:

```
┌─────────────────────────────────────────────────────────────┐
│  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                        │
└─────────────────────────────────────────────────────────────┘
```

**Great use cases:**
- Full-stack features (types + services + routes + UI components)
- Microservice implementations (multiple independent services)
- CRUD APIs (each resource in its own files)
- Plugin/module systems (each module independent)
- Test suites (test files for different modules)

### ⚠️ Falls Back to Sequential: Single-File Specs

When multiple tasks modify the **same file**, parallel execution would cause conflicts. The skill automatically falls back to sequential:

```
┌─────────────────────────────────────────────────────────────┐
│  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    │
└─────────────────────────────────────────────────────────────┘
```

**Still useful for:**
- Organized task breakdown and tracking
- Clear separation of concerns
- Systematic implementation of complex single-file changes

### Speedup Estimate

| Spec Type | Parallel Potential | Expected Speedup |
|-----------|-------------------|------------------|
| Multi-file, independent modules | High | 50-80% faster |
| Multi-file, some shared | Medium | 30-50% faster |
| Few files, many functions | Low | 10-20% faster |
| Single file, many changes | Minimal | ~0% (sequential) |

The skill will show you the estimated speedup in the execution plan before you confirm.

---

## Step 0: Accept Plan Input

First, get the plan from the user. Accept one of:

1. **File path**: User provides path to a spec, PRD, or plan file
2. **Inline description**: User describes what to build
3. **Reference file**: User points to existing code to replicate/extend

```
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.
```

---

## Step 1: Analyze & Decompose

Read the plan and identify work units. For each unit, determine:

1. **Independence**: Can it be built without waiting for others?
2. **Dependencies**: What must exist before this can be built?
3. **Outputs**: What files/interfaces does this create?
4. **Complexity**: Rough estimate (small/medium/large)

### Decomposition Rules

| Rule | Description |
|------|-------------|
| **File boundaries** | One agent per file or closely related file group |
| **Feature boundaries** | One agent per distinct feature/capability |
| **Layer boundaries** | Separate by layer (types, services, API, UI) |
| **Minimize coupling** | Tasks should have minimal interface dependencies |

### Create Dependency Graph

Identify three categories:

```
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
```

---

## Step 2: Define Shared Contracts

**CRITICAL**: Before spawning agents, define the contracts they share.

Create a shared context that ALL agents receive:

```markdown
## 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]
```

This prevents conflicts and ensures pieces fit together.

---

## Step 3: Present Execution Plan to User

Show the decomposition and get confirmation:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                    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

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