| name | parallel-builder |
| description | Divide-and-conquer implementation from specs/plans. Decomposes a reference document into independent tasks, assigns each to a builder agent, executes in parallel waves respecting dependencies, then integrates results. Use when you have a spec, PRD, plan, or large feature to implement quickly with parallel execution. |
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:
- File path: User provides path to a spec, PRD, or plan file
- Inline description: User describes what to build
- 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:
- Independence: Can it be built without waiting for others?
- Dependencies: What must exist before this can be built?
- Outputs: What files/interfaces does this create?
- 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:
## 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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Proceed with this plan? (y/n/modify)
If user says "modify", let them adjust task boundaries or wave assignments.
Step 4: Execute Wave by Wave
For Each Wave
-
Prepare agent prompts with:
- Their specific task
- Shared contracts (from Step 2)
- Outputs from previous waves (if any)
- Files they own (and must NOT touch others)
-
Spawn agents IN PARALLEL:
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)
- Track progress:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
WAVE 1 PROGRESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
☑ builder-solver-1 - Complete (types/*.ts)
☑ builder-solver-2 - Complete (schema.prisma)
☐ builder-solver-3 - Working... (config/*.ts)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
Collect outputs when wave completes
-
Pass context to next wave - Include relevant outputs from completed waves
Step 5: Agent Prompt Template
Each builder-solver agent receives a structured prompt:
# 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.
Step 6: Integration & Verification
After all waves complete:
6.1 Apply All Changes
Agents propose changes - orchestrator applies them to the codebase.
6.2 Check for Conflicts
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CONFLICT CHECK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ No file conflicts (agents stayed in their lanes)
✅ Interface contracts honored
✅ Import paths valid
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If conflicts exist, resolve them:
- Prefer later wave's version for integration files
- Merge compatible changes
- Flag incompatible changes for user decision
6.3 Run Verification
npm run typecheck
npm run lint
npm run test
Fix any issues found.
Step 7: Report Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
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 |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Error Handling
Agent Failure
If an agent fails:
- Retry once with the same prompt
- If still fails, report to user with error details
- Ask if user wants to:
- Skip this task and continue
- Provide guidance and retry
- Abort the build
Dependency Failure
If Wave N fails and Wave N+1 depends on it:
- Block dependent waves
- Report the blocker
- Offer options: fix and continue, or abort
Configuration Options
| Option | Default | Description |
|---|
| Max parallel agents | 5 | Maximum agents running simultaneously |
| Agent timeout | 5 min | Max time per agent |
| Auto-verify | true | Run type check/lint after completion |
| Show progress | true | Display progress updates |
User can specify: parallel-builder with 3 max agents
Agents
10 builder solver agents in agents/ directory:
builder-solver-1 through builder-solver-10
All agents:
- Same instructions (focused on implementing their assigned piece)
- Lower temperature (0.4) for consistency
- Full tool access (Read, Write, Grep, Glob, LS, Shell)
- Respect file ownership boundaries
- Follow shared contracts exactly
Difference from Other Skills
| Aspect | debug-council | feature-council | parallel-builder |
|---|
| Input | Bug to fix | Feature to build | Spec/plan to implement |
| Agent task | Same problem | Same feature | Different pieces |
| Goal | Find correct fix | Diverse approaches | Fast parallel execution |
| Selection | Majority vote | Synthesis/merge | Integration |
| Speed | N agents, 1 problem | N agents, 1 feature | N pieces, ~N× speedup |
Examples
Example 1: From PRD File
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
Example 2: From Description
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)
Example 3: From Reference
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
