September 12, 2026
ORCHESTRATE PARALLEL WORK WITHOUT LETTING AGENTS COLLIDE

The model hierarchy in Lesson 36.3 gave each AI a role. Once a project has several independent jobs, the CLI lets you run those roles at the same time — but only if the workspaces, branches, boundaries, and review path are deliberate. Five agents editing one folder with "make the app better" as the brief is not orchestration. It is a collision in advance.
Three definitions first
- A branch is an independent line of changes. It lets a task be built and reviewed without immediately altering the main working version of the project.
- A worktree is a separate folder on one computer checked out to a different branch. One machine can hold the main project, a frontend task, and a backend task open simultaneously without constant switching.
- Orchestration is deliberately assigning parallel workers their jobs, context, boundaries, outputs, and review order toward one outcome.
Part X teaches the command-level Git mechanics. This lesson teaches the operating model now, so branching arrives later as familiar discipline. Treat a branch as a safe named copy, and main as the version that only receives reviewed, validated work. When you want the mechanics behind pull requests and reviews, the authoritative reference is the GitHub pull requests documentation.
The central mental model:
Main working project
├─ branch/worktree A: frontend task
├─ branch/worktree B: backend or data task
├─ branch/worktree C: tests / documentation / review
└─ main branch: only reviewed, validated work returns here
Nothing returns to main without passing the review and evidence gates from Lessons 36.2 and 36.3.
Frontend and backend are not automatically separate
Frontend and backend are *often* good separate workstreams because they usually touch different files and responsibilities. They are not automatically separable just because of their names. If one feature changes the API contract and the screen that consumes it, the work has a dependency and needs an agreed interface, sequencing, or one owner.
The real rule: parallelize work with clear boundaries and minimize overlapping edits to the same files, data model, API contract, authentication rules, or infrastructure settings. Two workers editing the same component, migration, or config file will conflict no matter what the folders are called.
The dashboard example
For the research dashboard's source-date feature, three workspaces plus review stay out of each other's way:
| Workspace / branch | Job | Allowed area | Required handoff |
|---|---|---|---|
feature/source-date-ui | Show publication date beside each citation | Citation component and approved display helper | Screenshot/preview + changed-file summary |
feature/source-date-api | Expose existing source date through the approved data path | Research-record mapping and API test | Sample response + tests + interface note |
review/source-date | Inspect both changes read-only | Entire relevant diff, no edits | Compatibility, security, and regression findings |
main | Integrate only after checks pass | No experimental edits | Recorded decision and validated result |
Each row is enforceable because it names the workspace, the allowed files, and the exact handoff.
Agree the interface before parallel implementation
The backend worker must not quietly rename a field while the frontend worker guesses what arrives. Before either implements, write the exact input/output contract in Markdown or JSON: field name, type, nullable behavior, error and empty behavior, and an example payload.
For the source-date feature the contract might read:
{ "field": "source_published_at", "type": "string (ISO-8601 date) | null",
"nullable": true, "empty_behavior": "render 'Date unavailable'",
"error_behavior": "invalid dates render 'Date unavailable' and log a warning",
"example": { "source_published_at": "2026-05-12" } }
Both workers build against that note. The reviewer checks the contract against the diff. This connects directly to the Files & Context and Data lessons: the contract is project input, versioned with the task.
The five-window CLI setup
Conceptually, a builder can keep:
Window 1 — main project: run the application and integration tests
Window 2 — frontend branch/worktree: AI implements one approved UI task
Window 3 — backend branch/worktree: AI implements one approved service/data task
Window 4 — reviewer session: read-only diff, tests, architecture, and security review
Window 5 — planner/orchestrator: roadmap, task briefs, handoffs, dependency tracking
Windows are not just more chats. Each has a job, a bounded context, a branch and folder, a visible history, and one expected output. The CLI makes the state inspectable: which directory the worker is in, which branch it is changing, what command it ran, and what the output was. When something looks wrong, you know exactly which window to stop.
A contract for every parallel worker
Give each worker the same written brief:
Task: one defined outcome
Branch/worktree: exact workspace
May change: named folders/files
Must not change: named protected areas
Inputs: relevant PRD/architecture/task/interface note
Output: code + changed-file summary + evidence run
Stop/escalate when: dependency is unclear, contract changes, tests fail, or scope expands
Add context and data classification to every brief: name what may be supplied to this worker and what must stay out of its prompt, workspace, and tool permissions. The UI worker gets the component folder and the interface note — not production credentials. The reviewer gets the diff and sanitized fixtures — not the full customer export.
Pair each worker with the routing logic from Lesson 36.3: the expensive planner defines the contract and dependencies, a coding model handles each bounded branch, a cheaper model drafts copy or tests, and an independent model reviews the combined diff.
Sequence connected work
When frontend and backend share a contract, run them in this order:
1. Planner defines the product behavior and the interface contract. 2. Backend/data task builds the approved contract and tests it with sample data. 3. Frontend task builds against that contract — or against an explicit mock until the backend is ready. 4. Reviewer checks that the contract and the UI behavior match. 5. The human integrates, runs end-to-end checks, and only then marks the roadmap phase complete.
The mock in step 3 must be explicit and temporary, not a second invented contract. Name its file and who removes it before integration.
What not to parallelize casually
Some tasks need one implementation owner plus reviewers, not multiple writers: database migrations, authentication and authorization, shared configuration, environment variables, deployment settings, payment flows, and a single giant component being edited by several agents. Parallel edits here produce incompatible assumptions that surface at the worst moment — integration.
This list is not a ban. It is a sequencing rule: one writer, a stronger review and rollback plan, and no concurrent branch touching the same authority boundary.
Rollback: isolation is the point
If one branch goes off the rails, stop that worker, keep its useful notes, discard or revert that isolated branch to its last good checkpoint, and leave the other workspaces untouched. That isolation is why branches exist: a failed experiment costs one workspace, not the project.
Rollback is cheaper the moment drift is obvious. A fifteen-minute wrong turn is a small correction; three hours of cross-branch patches is an investigation. Do not let a failing worker "finish the thought" across more edits.
Exercise: write PARALLEL-WORK-PLAN.md
For one feature, create a PARALLEL-WORK-PLAN.md listing: two tasks that can run independently, one dependency that cannot, branch and worktree names, allowed and protected files for each worker, the interface contract, evidence required, and the person or agent session that reviews the final integration.
Include the stop conditions verbatim. If you cannot state when a worker must stop, the tasks are not bounded enough to parallelize.
Check your understanding
- Why is "frontend versus backend" an unreliable parallelization rule on its own?
- What five things must the interface contract specify before two workers start?
- One branch fails while two others are healthy. What do you preserve, what do you discard, and what happens to
main?
Finish line
You are done when you have a parallel-work plan where a reader can point to every worker's workspace, scope, input, output, dependency, and stop condition — and name the single integration owner.
Verify: pick any two workers and confirm they share no writable files, migration, or auth/config surface. Confirm the interface note has field, type, nullable, error/empty behavior, and an example. Confirm the reviewer is read-only.
Common failure mode: five agents on five branches with "make the app better" as the task. Result: incompatible changes and a painful merge nobody owns. Recovery: cut to fewer agents, shrink each task to one outcome, write the interface, assign one integration owner, and require the reviewer pass before anything touches main.
With parallel work under control, Class 37 asks the uncomfortable question: why does this deliberate discipline end up faster than pure speed?
ARTICLE DISCUSSION
JOIN THE
CONVERSATION.
Got a question, a take, or a better way to do this? Log in and leave a comment.
