singularity-forge/docs/building-coding-agents/05-parallelization-strategy.md

Parallelization Strategy

Core Principle

Parallelize across boundaries, serialize within them.

The quality of parallelization is directly determined by the quality of interface definitions.

The Diamond Pattern

    Planning (narrow, serial)
         ↓
   Fan Out (parallel execution)
         ↓
  Convergence (integration verification)
         ↓
    Fan Out (next parallel set)

Phase-by-Phase Strategy

Planning: Mostly Serial, with Parallel Spikes

• High-level decomposition must be serial (one coherent act of reasoning)
• Parallelize uncertainty resolution: Multiple spikes investigating different risks simultaneously
• Output: A dependency graph that explicitly identifies what can be parallelized

Execution: Massive Parallelization with Right Topology

Work Type	Strategy
Independent leaf tasks	Embarrassingly parallel — one agent per module
Dependent chains	Serial within chain, but chains run in parallel
Convergence points	Strictly serial — integration verification

Critical insight: The frontend doesn't need the real API — it needs the API contract. Once contracts exist, both sides build in parallel.

Testing: The Most Interesting Story

• Unit tests: Same agent, same context, atomic with code
• Cross-task tests: All parallel by definition
• Integration tests: Parallel across different boundaries
• E2E tests: Serial (exercises whole system)

Verification: Deliberate Redundancy

• Adversarial verification: Separate reviewer agent with fresh context evaluates against spec
• Red-team parallelism: Agent tries to break the implementation

Coordination Rules

• Agents communicate through the filesystem, never directly
• Each agent works on a branch — merge on success, discard on failure
• One agent per file at a time (file locking)
• Optimal concurrency: 3–8 simultaneous agents for most projects

Anti-Patterns

• ❌ Don't parallelize tasks that modify the same files
• ❌ Don't parallelize interacting decisions
• ❌ Don't skip convergence/integration verification
• ❌ Don't over-parallelize (coordination tax eats gains above ~8 agents)

---