Fan-Out Patterns — Parallel vs Pipeline

Choosing the Wrong Pattern Costs More Than Going Serial

Pick the right fan-out pattern and you get the throughput multiplier. Pick the wrong one and you get all the coordination overhead of parallel dispatch with none of the speed benefit.

Pure fan-out for dependent tasks: agents fail because they don't have their required inputs. Pipeline for independent tasks: you've added barrier overhead where none was needed. Either way, you've paid the dispatch setup cost without the payoff.

The decision is mechanical. The two questions on the decision tree always produce the right answer.

The Three Patterns

Pure fan-out: All tasks are independent. Dispatch them simultaneously. The classic case is cross-repo work: fix CI in academy, fix tests in memory-service, fix linting in mission-control. Three repos, three completely independent git states, three agents dispatched at the same moment. No barriers, no coordination overhead beyond the initial dispatch and the final results collection.

Pipeline with barriers: Tasks have dependencies. Later tasks need earlier outputs. The spec-implement-QA-merge sequence is the archetypal example. You cannot implement before the spec is finalized. You cannot run QA before the implementation is complete. Each wave must complete and be validated before the next wave starts.

Mixed: Real systems use both. Each stage fans out internally, but stages are sequential. Knox's /ship pattern: Feature Agent + QA Agent run in parallel (both independent within Wave 1), barrier, then the orchestrator opens the PR. The PR-opening step is sequential — it depends on both agents having passed.

The Pipeline Barrier Pattern in Detail

The barrier is not just a pause — it is a validation gate. The orchestrator does not simply wait for Wave 1 to finish; it validates Wave 1's outputs before allowing Wave 2 to start.

For a spec → implement pipeline: after the PRD agent completes Wave 1, the orchestrator reviews the PRD for ambiguity. If any requirement is vague ("add user-friendly error handling" instead of "return a 400 response with {error: 'field X is required'} when X is missing"), Wave 2 is blocked until the spec is clarified.

This is the reason pipelines exist: downstream work is worthless if upstream ambiguity propagated. The barrier enforces quality at each stage transition, not just at the end.

The cost of a barrier is the time spent in validation before Wave 2 starts — typically 5-15 minutes for a human review. The benefit is that Wave 2 agents start with complete, validated inputs and do not produce work that needs to be thrown away.

Same-Repo vs. Cross-Repo Topology

The fan-out pattern must account for isolation requirements:

Cross-repo fan-out: Different git repositories. Free parallelism. No worktrees needed. The repo boundary provides the isolation automatically.

Same-repo fan-out: Same git repository. Worktrees required for each agent. The dispatch prompt must specify each agent's worktree path and the files each agent owns.

Mixed topology (common in real sessions): Wave 1 has agents in cross-repo work (no worktrees) AND same-repo work (with worktrees). The orchestrator tracks both isolation types simultaneously. Cross-repo agents can be dispatched directly. Same-repo agents need worktree setup first.

The /ship Dispatch Topology

Knox's /ship skill implements the mixed pattern with multiple waves. The exact topology depends on the task, but the canonical /ship for this academy's track-building sessions looks like this:

Wave 1 (parallel, worktrees):
  - Content Agent (worktree A): writes lesson MDX files
  - Diagram Agent (worktree B): writes TSX components

Barrier: both agents report PASS (tsc, tests)

Wave 2 (sequential, main worktree):
  - Orchestrator: cherry-picks A+B, edits registries, runs full test suite

Barrier: tsc clean, tests green

Wave 3 (sequential):
  - Orchestrator: opens PR via gh pr create

This topology gives full parallelism in Wave 1 (the largest portion of the work), a single verification barrier in Wave 2, and a clean PR in Wave 3.

Now make the call yourself. Given three tasks — lessons, diagrams, and a registration step that imports both — pick parallel() for the independent stage and pipeline() across the barrier.

When to Add More Waves

Adding more waves adds coordination overhead. Each barrier costs 5-15 minutes of orchestrator review. Add a wave when:

• Later tasks genuinely need earlier outputs (dependency exists)
• Earlier outputs need validation before they are safe to build on (quality gate needed)

Do not add waves to "organize" the work. Parallel dispatch benefits from minimal stages. The ideal topology is the one with the fewest waves that still respects the actual dependency graph.

What's Next

The next lesson covers convergence — the process of bringing all worker branches back together, resolving any remaining conflicts, and producing a clean result. Cherry-pick mechanics, stray commit recovery, and the post-convergence verification protocol are all covered in detail.