Skip to content

Parallel Agent Orchestration (the "fan-out + integrate" workflow)

URL: https://mkdocs.justinsforge.com/memory/general/reference_parallel_agent_orchestration/

How one Claude Code session shipped the whole CreatorTrack app suite in a night: spawn many isolated background workers, one per app/area/bug; the session stays the INTEGRATOR that reconciles + merges + deploys. There is no special mode , it is the Agent tool + the worktree rig + discipline. To make another Opus session work this way, tell it: "Read memory/general/reference_parallel_agent_orchestration.md and operate as the integrator."

The three ingredients

  1. Background workers = the Agent tool with run_in_background: true. Each call spawns a subagent that runs while you keep going; you get a completion notification. That is what "966 background tasks" were. Launch several in ONE message (multiple tool calls) to run them concurrently.
  2. Isolation = the Worktree Dev Agent rig (reference_creatortrack_parallel_dev). Per worker: ~/forge/scripts/forge_creatortrack_agent_bootstrap.sh <branch> <port> --no-server gives a git worktree ~/forge-suite-wt/<branch> + DB clone ct_<branch>. Workers build + npx tsc --noEmit + commit on their OWN branch + QA in a headless browser against their own temp dev server (next dev --webpack, kill after). They never touch main, never push.
  3. You are the INTEGRATOR. Workers only produce branches. The session merges them serially, reconciles conflicts, validates migrations, and deploys. That single-threaded integration is what keeps a 20-branch night coherent.

The worker prompt recipe (what to put in each Agent call)

  • Scope to ONE app/area/bug. Give exact file pointers (orient first), the acceptance criteria, and the rig rules verbatim: branch, DB, NEVER touch main/push, tsc clean at every commit, conventional commits, INTENT.md note.
  • Demand real QA: a temp `next dev --webpack