98 lines
3.1 KiB
Markdown
98 lines
3.1 KiB
Markdown
# Parallel Execution Patterns
|
||
|
||
Dispatch multiple agents simultaneously for independent tasks. Maximize throughput when tasks don't share file ownership.
|
||
|
||
## When to Parallelize
|
||
|
||
### Research Fan-Out (Most Common)
|
||
|
||
Dispatch multiple `ck-research` agents simultaneously on different topics, then aggregate into `ck-planning`:
|
||
|
||
```
|
||
ck-planning receives task
|
||
│
|
||
├──► ck-research: "authentication patterns for FastAPI"
|
||
├──► ck-research: "JWT vs session token trade-offs"
|
||
└──► ck-research: "OAuth 2.1 PKCE implementation"
|
||
│ (all complete)
|
||
▼
|
||
ck-planning aggregates reports → plan.md
|
||
```
|
||
|
||
**Max parallel research agents:** 3–5 (respects the 5-query max rule per agent)
|
||
|
||
### Scout Coverage
|
||
|
||
Divide a large codebase among multiple `ck-scout` agents by directory:
|
||
|
||
```
|
||
ck-scout agent 1: src/features/, src/components/
|
||
ck-scout agent 2: src/api/, src/hooks/
|
||
ck-scout agent 3: src/utils/, tests/
|
||
│ (all complete, timeout 3 min each)
|
||
▼
|
||
Aggregate into single scout report
|
||
```
|
||
|
||
### Independent Feature Components
|
||
|
||
When implementing a feature with truly independent parts:
|
||
|
||
```
|
||
ck-cook agent 1: phase-01-database-schema.md (owns: migrations/)
|
||
ck-cook agent 2: phase-02-api-endpoints.md (owns: api/)
|
||
ck-cook agent 3: phase-03-ui-components.md (owns: components/)
|
||
│ (all complete)
|
||
▼
|
||
Integration phase (sequential)
|
||
```
|
||
|
||
**Prerequisite:** File ownership must be explicitly divided with zero overlap.
|
||
|
||
### Cross-Platform Development
|
||
|
||
```
|
||
Developer agent 1: iOS-specific implementation
|
||
Developer agent 2: Android-specific implementation
|
||
│ (both complete)
|
||
▼
|
||
Shared interface verification (sequential)
|
||
```
|
||
|
||
## Coordination Rules
|
||
|
||
### Before Parallel Dispatch
|
||
|
||
1. **Define file ownership**: Which files does each agent exclusively own?
|
||
2. **Identify shared resources**: Are there any files both agents might write?
|
||
3. **Plan merge strategy**: How will outputs be combined?
|
||
4. **Set timeout expectations**: How long should each agent take?
|
||
|
||
### During Parallel Execution
|
||
|
||
- Agents work independently — no inter-agent communication
|
||
- Each agent writes to its own report path (different filenames)
|
||
- No agent reads files being written by another agent
|
||
|
||
### After Parallel Completion
|
||
|
||
- Wait for ALL agents to complete before proceeding
|
||
- Read all reports before synthesizing
|
||
- Resolve any conflicts manually before the next sequential step
|
||
|
||
## Parallelization Limits
|
||
|
||
| Scenario | Max Agents | Reason |
|
||
|----------|------------|--------|
|
||
| Research | 5 | Token budget per agent |
|
||
| Scout | 4 | Codebase coverage vs. overlap |
|
||
| Implementation phases | 3 | File conflict risk |
|
||
| CI/CD verification | Unlimited | Read-only bash commands |
|
||
|
||
## Anti-Patterns
|
||
|
||
- **Shared file writes**: Two agents writing the same file causes corruption — assign exclusive ownership
|
||
- **Implicit dependencies**: Agent B needs Agent A's output → must be sequential, not parallel
|
||
- **Too many agents**: Each agent consumes context window; over-parallelizing causes resource contention
|
||
- **No merge plan**: Spawning parallel agents without knowing how to combine results → wasted work
|