Working in parallel: more agents, not more chaos.

7.1 Why parallel at all?

A single agent works sequentially: read, plan, change, test, fix. For larger initiatives that takes time, and much of it is mutually independent. The backend module for invoices and the frontend form for addresses barely touch each other. Why should they be built one after the other?

Parallelism promises three things:

• Lead time: independent parts are built at the same time.
• Focus: each agent gets a smaller, clearly scoped assignment and therefore a more manageable context. In practice, small assignments succeed more often than large ones.
• Specialisation: analysis, implementation and review can be handled by different agents, models or tools.

The catch: software is not a stack of independent sheets. Parts share interfaces, data models, build configuration and database migrations. As soon as two agents touch the same spot or rely on different assumptions about a shared interface, integration work arises. In the worst case it outweighs the time saved. The factory’s parallel roadmap names exactly this as the main risk: integration costs can exceed the gain from parallelism.

7.2 The core problem: shared state

Imagine two agents working in the same working directory. Agent A is changing a class and is halfway done. At that moment agent B runs the tests, sees a compile error in A’s half-finished code and “fixes” it. Then B commits with git add -A and takes A’s half-done work along. After that, nobody knows who caused which line. A review, a why-trace or an attestation would make statements about a state that no single agent is accountable for.

This is not an edge case but the inevitable consequence of several writers on one shared state. Human teams solve it by having each person work in their own working copy and combine changes via branches and merges. The same solution applies to agents, only more strictly, because agents don’t coordinate with each other along the way.

Single writer per workspace

At any given time, exactly one agent writes in a working directory. Parallelism comes from more working directories, not from more writers per directory.

This rule (ADR-0015 in the factory) sounds strict but simplifies everything that follows: every state is attributable to one agent, conflicts only arise between finished branches, and both sides of a conflict are internally consistent. A merge conflict between two finished branches can be analysed and formulated as a work assignment. A conflict in the middle of a shared directory cannot.

Reading agents are not affected by the rule. Reviewers and analysis agents that write nothing may look at the same state in parallel as much as they like.

Git worktrees as the tool

Technically, Git offers a fitting mechanism with worktrees: several working directories share one repository, each on its own branch. This saves space compared with full clones, and all branches are immediately visible in the shared object store, which makes merging them later easier.

Open full-size graphicOpen full-size graphic

7.3 Decomposition: the dependency graph

Before anything can run in parallel, the initiative has to be decomposed. The result is a directed acyclic graph (DAG): nodes are tasks, edges say “B can only start when A is finished”. Exactly those tasks may run in parallel that do not depend on each other in this graph and whose predecessors are finished.

Kinds of dependencies

Not every dependency is “first A, then B”. The factory’s parallel roadmap distinguishes, for example:

• Completion: B needs the result of A.
• Contract: B needs an agreed interface, not A’s implementation.
• Artifact: B needs a specific output, such as a generated file.
• Approval: B may only start after a human decision.
• Exclusive resource: A and B touch the same file, which cannot tolerate two simultaneous changes.

The distinction pays off: a contract dependency can be resolved by agreeing on the contract first. After that, provider and consumer of the interface can be built at the same time. A completion dependency cannot be resolved that easily.

Good decomposition

• Cut along write scopes, not along domain terms. Two tasks that change the same files are not parallel, no matter how different they sound in business terms.
• Shared things first: put the data model, interfaces, migrations and build changes into an early, separate task.
• Small but complete: each task should build and be testable on its own.
• Analysis before implementation: read-only analysis tasks are ideal for parallelism because they write nothing. Their results feed into the planning of the writing tasks.

How to plan in general and define acceptance criteria per task is covered in Chapter 5.

7.4 Contracts before parallel implementation

When frontend and backend are built at the same time, both need to know what the interface between them looks like. If you let each agent make its own assumption, you get two builds that are each green and don’t work together. No test of an individual change points to this problem, because the break lies between the components.

Hence the principle Contracts before Parallel Implementation: interdependent components may only be implemented in parallel once the shared contract exists in a versioned form. Contracts can be:

• API descriptions (OpenAPI for REST, AsyncAPI for events),
• data schemas (JSON Schema, DTO definitions),
• Java or TypeScript interfaces,
• domain events,
• acceptance criteria.

Three properties of a usable contract

1. Immutable versions. A change creates a new version; the old one remains. Otherwise the evidence “agent B built against version 3” refers to content that may have changed in the meantime.
2. Content checksum. A hash over the content makes versions unambiguously comparable.
3. Binding at the right moment. Which version applies is fixed when the work starts, not already at planning time. The contract can still change between planning and start.

When the contract changes

If a contract changes while tasks are working against the old version, those tasks are stale. Their result must not be accepted unchecked, even if their own build is green. The task has to be reassessed: run it again against the new version, or discard it.

7.5 Ownership and leases

Single writer per directory prevents two agents from wrecking each other’s working copy. It does not prevent two agents from changing the same file in their separate worktrees. You only notice that when merging, and by then the work is already done. It is better to detect overlaps before the start.

Declared ownership

For this, each writing task declares which areas it intends to change (write scopes), which it only reads and which it must not touch. If the write scopes of two active tasks overlap, the second one does not start. Certain files are always exclusive because two simultaneous changes there almost certainly collide: central build configuration, database migrations, shared API specifications.

Leases instead of permanent locks

An ownership claim needs an expiry date. If an agent process crashes, its lock must not block the rest of the initiative permanently. That is why ownership is granted as a lease: a claim with a duration that is renewed via heartbeat. If the heartbeat stops, the claim is considered orphaned and can be released.

A related problem arises with several executing processes: two workers could pick up the same task at the same time. The solution is an atomic claim before anything happens: only one can win it. And if a worker fails, the rule is: a task that has not run yet may go back into the queue. One that has already run has left behind a working state of unknown quality and must not be silently repeated.

7.6 Bringing it together: order, conflicts, integration

When all parallel tasks are finished, there are several branches, each built and checked on its own. Now comes the hardest part: merging them into an overall state that works as a whole.

Fixed order

You could merge branches in the order in which they finish. But then the result depends on random run times, and two runs of the same plan produce different states. It only becomes reproducible with a fixed order, such as the plan order, and a sequential queue (merge queue).

Not all conflicts are alike

To Git, every conflict looks the same: two sides that contradict each other at the same spot. In practice they call for very different responses:

• Two migrations with the same number: renumber, but carefully, because database states depend on them.
• Two added dependencies in the build file: usually solvable mechanically.
• Pure formatting differences: harmless.
• A stale branch: a rebase onto the current state may be enough.
• A genuine content contradiction: here someone has to decide what should apply.

An agent that is only told “resolve the conflict” guesses. If you classify conflicts, you can respond in a targeted way: automate mechanical cases, escalate content ones. And a rebase is not a cure-all: it resolves conflicts that exist only because a branch is old, but not content contradictions.

Checking the integration

Each task was checked on its own. That does not answer whether the changes work together. That is why, after merging, a separate check of the overall state is needed: full build, integration tests, architecture tests across the integrated state, contract compatibility. Only when this integration check passes is the initiative finished.

7.7 Replanning with a reason

No plan survives execution unchanged. A task turns out to be too large, a contract changes, a conflict shows that two tasks are really one. Replanning is therefore normal. It becomes dangerous when it happens without a trace or serves as a pretext for blind repetition.

Two rules help:

• Every plan change is versioned and justified. Not just “plan version 4”, but: what changed, why, and who triggered it? The question that comes weeks later is not “which version” but “why this one”.
• A task is only restarted with new input. This is the same rule as for correction loops in Chapter 6. A different cut or a new order rearranges work but gives the agent nothing it didn’t have on the last attempt.

7.8 When you should not parallelise

Parallelism is a tool, not a goal. Do without it when:

• the tasks change the same files, such as a central service or a shared data model. The ownership check would start them one after the other anyway.
• no contract exists yet and the interface only emerges while building. In that case, first create a task “agree on the contract”.
• the initiative is small. Planning, approval, integration and checks take time; for a change that a single run can manage in one pass, a workflow isn’t worth it.
• the requirements are unclear. Three agents interpreting a vague requirement differently produce three inconsistent parts. Clarify the spec first.
• nobody owns the integration. Conflicts and stale tasks need human decisions. Without someone who makes them, the workflow stalls.

Chapter questions

1. What does the principle “single writer per workspace” state, and which problem does it prevent?

   Model answer

   At any given time exactly one agent writes in a working directory; parallelism comes from more working directories. It prevents an agent from committing or “fixing” another agent’s half-finished work, which would make states attributable to no one and rob review, why-trace and attestation of their meaning.

2. Why may reviewers and analysis agents run in parallel as much as they like, but writing tasks may not?

   Model answer

   Reading agents don’t change any state, so they cannot disturb each other or mix up work. Writing agents produce changes that must remain attributable and be merged in a controlled way; that is why they get their own worktrees and declared write scopes.

3. Explain “Contracts before Parallel Implementation” using an example from frontend and backend.

   Model answer

   Before the frontend form and the backend endpoint are built in parallel, the interface is fixed as a versioned contract, for example as an OpenAPI document. Both agents work against the same version, bound at start. Without a contract, each would make its own assumptions; both builds would be green, but together they would not work.

4. What happens in the factory when a contract gets a new version while a task bound to it is still running?

   Model answer

   Stale detection sets the task to WAITING_FOR_REPLAN. Even if its run then finishes successfully, the result is only recorded, but the task is not promoted to PASSED. The merge block prevents integration, and the workflow moves to WAITING_FOR_APPROVAL. A human decides: run again against the new version, or discard.

5. Why does the merge queue merge branches in plan order and not in the order in which they finish?

   Model answer

   Otherwise the integrated result would depend on random run times, and two runs of the same plan could produce different states and conflicts. The fixed order makes integration reproducible and traceable.

6. An agent suggests resolving every merge conflict via rebase. What do you reply?

   Model answer

   A rebase only resolves conflicts that exist because a branch is stale. It does not resolve content contradictions and merely shifts migration number collisions. That is why the factory classifies conflicts first and only attempts the rebase when the classification rates it as promising; deliberately not for MIGRATIONSNUMMER and INHALTLICHER_WIDERSPRUCH.

7. Why do you need an integration gate when every child run has already passed its own gate?

   Model answer

   The local gate checks a change on its own. Whether several changes work together is only shown by checking the integrated overall state. In the factory, a workflow reaches COMPLETED only through the integration gate’s verdict; a discarded branch makes it FAILED, a contract break downgrades it to WARNING.

8. Someone wants to simply “run a failed task again”. Under which condition does the factory allow this, and why?

   Model answer

   Only via replanning whose reason carries new input, such as a build error, reviewer finding, merge conflict, contract change or a human instruction. The change is recorded as a PlanRevision with a description and attested as WORKFLOW_REPLANNED. The reason is AP-6: a repetition without new information costs tokens without specifically increasing the chance of success.

9. Transfer: three child runs of a workflow implement parts of the same spec. While the second is running, a maintainer approves a new spec version. Which version do the three runs work against, and why is that intended?

   Model answer

   Against the version that was bound to the task at start (WORKFLOW_TASK_SPEC_GEBUNDEN); all child runs of a workflow verifiably work against the same version. This prevents parallel parts from being built against different requirements and only falling apart at integration. The new version is deliberately adopted through new planning or a new workflow; since v0.38.0, spec drift detection moves affected tasks that are not finished to WAITING_FOR_REPLAN.

10. Name three situations in which you do without a workflow and prefer a single build run.

    Model answer

    When the subtasks change the same files, when the initiative is so small that planning and integration cost more than parallelism brings, and when requirements or interfaces are still unclear. A workflow also stalls without a person responsible for integration decisions.