Parallel Execution Strategy

Parallel Execution Strategy

Overview

Plan parallel agent execution before dispatching — so two agents never edit the same file, so integration is verified between merges, and so the merge order is fixed in advance. Output is .forge/parallel-plan.md — dependency-free task groups, file-conflict risk per group, branching strategy (one branch per task), PR sequencing, agent isolation (separate worktrees), and integration-test cadence. Pairs with planning-and-task-breakdown (the source tasks.yaml) and git-workflow (the branch and PR mechanics).

When to Use

• .forge/tasks.yaml has 3+ tasks marked ready and they appear independent
• Multiple engineers or agents are about to start work in the same week
• A prior parallel run caused merge conflicts at the end and the team wants a better plan
• A sprint is about to begin and capacity is "split N ways"

When NOT to Use

• Only one task is ready — sequential is correct
• Tasks form a strict dependency chain — sequential is correct
• The team is two people working on the same file all day — coordinate live, no plan needed

Common Rationalizations

Red Flags

• Two ready tasks in tasks.yaml that both modify the same file
• Multiple agents about to start in the same git worktree
• No integration test gate between parallel groups
• A "merge day" scheduled at the end of the sprint to resolve everything at once
• Agents dispatched without knowing what the others are touching
• No documented merge order — every PR is "ready when ready"
• A task list that lists modules but not files (file-conflict risk can't be assessed)

Core Process

Step 1: Read .forge/tasks.yaml and identify dependency-free groups

A task is dependency-free with another if both:

1. Their depends_on lists do not transitively reference each other
2. Their files lists do not intersect

Group dependency-free tasks. Sequence groups by dependency depth.

Group 1 (ready now):     T-001, T-003, T-007
Group 2 (after Group 1): T-002, T-004
Group 3 (after Group 2): T-005, T-006

Step 2: Assess file-conflict risk per group

For each group, build a matrix:

Any row with two ✏️ marks is a conflict. Resolve before dispatch:

• Split the task — extract the shared file into its own prerequisite task
• Sequence — move one task into a later group
• Designate a primary — one task owns the file; the other rebases after

Step 3: Assign branching strategy

• One branch per task: task/T-001-session-refresh
• All branches base off main (or the integration branch, if used)
• No long-lived feature branches for parallel work
• Every branch has the task ID and a one-line description in its name

Step 4: Define PR sequencing and merge order

In .forge/parallel-plan.md:

Group 1 merge order:
  1. T-001 (touches shared types — must land first)
  2. T-007 (independent UI)
  3. T-003 (rebases on T-001's type changes)

Integration test gate runs between T-001 → T-007 and T-007 → T-003.

Merge order is fixed before dispatch. Agents know their PR's position in the queue.

Step 5: Specify agent isolation

Each agent works in its own worktree (or its own clone):

~/work/main           # main worktree, integration testing
~/work/T-001          # agent A's worktree
~/work/T-003          # agent B's worktree
~/work/T-007          # agent C's worktree

git worktree add -b task/T-001-session-refresh ~/work/T-001 main

No agent ever runs in another agent's worktree. No agent ever runs in the main worktree during parallel work.

Step 6: Set the integration-test cadence

Between every PR merge in a group:

• Pull the latest main into the integration worktree
• Run the full test suite (unit + integration + e2e on critical paths)
• Run any contract-conformance tests for the modules that changed
• If green: merge the next PR
• If red: pause dispatch, root-cause, and either revert or push a fix before continuing

Between groups:

• All PRs in the previous group merged and tested green
• The next group's worktrees rebased on the new main

Step 7: Document the plan in .forge/parallel-plan.md

Sections:

• Groups and dependency order
• File-conflict matrix per group (resolved)
• Branch naming and base
• Merge order with rationale
• Worktree assignments
• Integration test cadence
• Fallback for conflicts that emerge mid-run

Prepend a forge:meta header (generated_by: parallel-execution-strategy, generated_at: <ISO 8601 UTC with Z>, content_hash: <sha256 first 8 over THIS file's body, excluding the forge:meta block>).

Transitive depends_on: parallel-plan.md builds on tasks.yaml, which itself depends on prd.md, architecture.md, and contracts/*. List the full transitive upstream set in depends_on (paths only — never hashes) AND capture each upstream's content_hash AT generation time in generated_from:

depends_on: [.forge/prd.md, .forge/architecture.md, .forge/contracts/*, .forge/tasks.yaml]
generated_from:
  .forge/prd.md: <prd.md's content_hash at this moment>
  .forge/architecture.md: <architecture.md's content_hash at this moment>
  .forge/contracts/auth-service.md: <hash>   # one entry per resolved glob match
  .forge/contracts/payment-service.md: <hash>
  .forge/tasks.yaml: <tasks.yaml's content_hash at this moment>

Listing only [.forge/tasks.yaml] is wrong — if prd.md changes but tasks.yaml hasn't been re-run yet, parallel-plan.md would appear UP_TO_DATE despite the chain being stale. See forge-dependency-graph: co-output rule.

Verification

• .forge/parallel-plan.md written
• No two parallel agents touch the same file (matrix verified)
• Every parallel task has its own branch with the task ID in the name
• Every agent has its own worktree
• Merge order is documented for every group
• Integration test gate defined between every merge
• Fallback plan exists for mid-run conflict discovery
• Plan was reviewed before dispatch — no agent starts work until the plan is signed off