bradygaster · Mar 23, 2026 · Mar 22, 2026
@@ -26,6 +26,8 @@ Examples:
 
 ## Workflow for Issue Work
 
+### Single Issue (Standard)
+
 1. **Branch from dev:**
    ```bash
    git checkout dev
@@ -59,32 +61,30 @@ Examples:
    git push origin --delete squad/{issue-number}-{slug}
    ```
 
-## Parallel Multi-Issue Work (Worktrees)
+### Multiple Issues in Parallel (Worktrees) — Default for 2+ Issues
 
 When the coordinator routes multiple issues simultaneously (e.g., "fix bugs X, Y, and Z"), use `git worktree` to give each agent an isolated working directory. No filesystem collisions, no branch-switching overhead.
 
-### When to Use Worktrees vs Sequential
-
 | Scenario | Strategy |
 |----------|----------|
 | Single issue | Standard workflow above — no worktree needed |
-| 2+ simultaneous issues in same repo | Worktrees — one per issue |
+| 2+ simultaneous issues in same repo | **Worktrees — one per issue (default)** |
 | Work spanning multiple repos | Separate clones as siblings (see Multi-Repo below) |
 
 ### Setup
 
-From the main clone (must be on dev or any branch):
+The **coordinator** creates worktrees before spawning agents. From the main clone:
 
 ```bash
-# Ensure dev is current
+# Ensure base branch is current
 git fetch origin dev
 
-# Create a worktree per issue — siblings to the main clone
-git worktree add ../squad-195 -b squad/195-fix-stamp-bug origin/dev
-git worktree add ../squad-193 -b squad/193-refactor-loader origin/dev
+# Create a worktree per issue
+git worktree add ./worktrees/squad-195 -b squad/195-fix-stamp-bug origin/dev
+git worktree add ./worktrees/squad-193 -b squad/193-refactor-loader origin/dev
 ```
 
-**Naming convention:** `../{repo-name}-{issue-number}` (e.g., `../squad-195`, `../squad-pr-42`).
+**Naming convention:** `./worktrees/squad-{issue-number}` (e.g., `./worktrees/squad-195`).
 
 Each worktree:
 - Has its own working directory and index
@@ -93,10 +93,10 @@ Each worktree:
 
 ### Per-Worktree Agent Workflow
 
-Each agent operates inside its worktree exactly like the single-issue workflow:
+Each agent receives a `WORKTREE_PATH` in its spawn prompt and operates exclusively inside its worktree:
 
 ```bash
-cd ../squad-195
+cd ./worktrees/squad-195
 
 # Work normally — commits, tests, pushes
 git add -A && git commit -m "fix: stamp bug (#195)"
@@ -106,7 +106,7 @@ git push -u origin squad/195-fix-stamp-bug
 gh pr create --base dev --title "fix: stamp bug" --body "Closes #195" --draft
 ```
 
-All PRs target `dev` independently. Agents never interfere with each other's filesystem.
+Agents do NOT run `git checkout` to switch branches. All PRs target `dev` independently. Agents never interfere with each other's filesystem.
 
 ### .squad/ State in Worktrees
 
@@ -121,7 +121,7 @@ After a worktree's PR is merged to dev:
 
 ```bash
 # From the main clone
-git worktree remove ../squad-195
+git worktree remove ./worktrees/squad-195
 git worktree prune          # clean stale metadata
 git branch -d squad/195-fix-stamp-bug
 git push origin --delete squad/195-fix-stamp-bug

@@ -528,15 +528,44 @@ When the user gives any task, the Coordinator MUST:
 
 1. **Decompose broadly.** Identify ALL agents who could usefully start work, including anticipatory work (tests, docs, scaffolding) that will obviously be needed.
 2. **Check for hard data dependencies only.** Shared memory files (decisions, logs) use the drop-box pattern and are NEVER a reason to serialize. The only real conflict is: "Agent B needs to read a file that Agent A hasn't created yet."
-3. **Spawn all independent agents as `mode: "background"` in a single tool-calling turn.** Multiple `task` calls in one response is what enables true parallelism.
-4. **Show the user the full launch immediately:**
+3. **Create worktrees for parallel issue work.** When spawning 2+ agents on separate issues in the same repo, create a worktree per agent BEFORE spawning (see Worktree Lifecycle below). Single-agent tasks use `git checkout -b` as before.
+4. **Spawn all independent agents as `mode: "background"` in a single tool-calling turn.** Multiple `task` calls in one response is what enables true parallelism.
+5. **Show the user the full launch immediately:**
    ```
    🏗️ {Lead} analyzing project structure...
    ⚛️ {Frontend} building login form components...
    🔧 {Backend} setting up auth API endpoints...
    🧪 {Tester} writing test cases from requirements...
    ```
-5. **Chain follow-ups.** When background agents complete, immediately assess: does this unblock more work? Launch it without waiting for the user to ask.
+6. **Chain follow-ups.** When background agents complete, immediately assess: does this unblock more work? Launch it without waiting for the user to ask.
+
+### Worktree Lifecycle (Parallel Issue Work)
+
+When the coordinator needs to spawn **2+ agents on separate issues in the same repo**, use git worktrees to give each agent an isolated working directory. This prevents filesystem collisions from concurrent `git checkout` operations.
+
+**Decision logic:**
+- **Single agent / single issue** → `git checkout -b squad/{issue}-{slug}` (standard workflow)
+- **2+ agents on separate issues** → `git worktree add` per agent (worktree workflow)
+- **Ralph batch work (multiple issues)** → worktrees per issue
+
+**Pre-spawn — create worktrees:**
+```bash
+git fetch origin {baseBranch}
+git worktree add ./worktrees/squad-{issue} -b squad/{issue}-{slug} origin/{baseBranch}
+```
+
+**Spawn prompt — pass WORKTREE_PATH:**
+Include `WORKTREE_PATH: ./worktrees/squad-{issue}` in every agent spawn prompt that uses a worktree. The agent works exclusively inside that path and does NOT run `git checkout`.
+
+**Post-merge cleanup:**
+After a worktree agent's PR is merged, clean up:
+```bash
+git worktree remove ./worktrees/squad-{issue}
+git worktree prune
+git branch -d squad/{issue}-{slug}
+```
+
+If the worktree was deleted manually, `git worktree prune` recovers the state.
 
 **Example — "Team, build the login page":**
 - Turn 1: Spawn {Lead} (architecture), {Frontend} (UI), {Backend} (API), {Tester} (test cases from spec) — ALL background, ALL in one tool call
@@ -646,6 +675,12 @@ prompt: |
   TEAM ROOT: {team_root}
   All `.squad/` paths are relative to this root.
 
+  {only if agent was spawned with a worktree — omit for single-agent work:}
+  WORKTREE_PATH: {worktree_path}
+  You are already on branch {branchName} in a dedicated worktree.
+  Work ONLY inside this path. Do NOT run `git checkout` to switch branches.
+  {end worktree block}
+
   Read .squad/agents/{name}/history.md (your project knowledge).
   Read .squad/decisions.md (team decisions to respect).
   If .squad/identity/wisdom.md exists, read it before starting work.
@@ -1100,7 +1135,11 @@ Store `## Issue Source` in `team.md` with repository, connection date, and filte
 
 ### Issue → PR → Merge Lifecycle
 
-Agents create branch (`squad/{issue-number}-{slug}`), do work, commit referencing issue, push, and open PR via `gh pr create`. See `.squad/templates/issue-lifecycle.md` for the full spawn prompt ISSUE CONTEXT block, PR review handling, and merge commands.
+**On-demand reference:** Read `.squad/templates/issue-lifecycle.md` for the full worktree-aware lifecycle, spawn prompt additions, PR review handling, and merge/cleanup commands.
+
+**Single agent (standard):** Agent creates branch (`git checkout -b squad/{issue-number}-{slug}`), does work, commits referencing issue, pushes, and opens PR via `gh pr create`.
+
+**Parallel agents (worktree):** Coordinator creates a worktree per issue BEFORE spawning (`git worktree add ./worktrees/squad-{issue} -b squad/{issue}-{slug} origin/{baseBranch}`). Each agent receives `WORKTREE_PATH` in its spawn prompt and works exclusively inside its worktree. After PR merge, coordinator cleans up (`git worktree remove ./worktrees/squad-{issue} && git worktree prune`).
 
 After issue work completes, follow standard After Agent Work flow.
 

@@ -0,0 +1,127 @@
+# Issue → PR → Merge Lifecycle
+
+This template describes the full lifecycle for issue-driven work, including worktree-aware parallel execution.
+
+---
+
+## Decision Logic
+
+| Scenario | Strategy | Branch creation |
+|----------|----------|-----------------|
+| Single agent / single issue | Standard | `git checkout -b squad/{issue}-{slug}` |
+| 2+ agents on separate issues | Worktree | `git worktree add` per agent |
+| Ralph batch work (multiple issues) | Worktree | `git worktree add` per issue |
+
+---
+
+## Single-Issue Workflow (Standard)
+
+```bash
+# 1. Branch from base (dev or main, per repo convention)
+git checkout {baseBranch} && git pull origin {baseBranch}
+git checkout -b squad/{issue-number}-{slug}
+
+# 2. Do work, commit referencing issue
+git add -A && git commit -m "feat: {description} (#issue-number)"
+
+# 3. Push and open PR
+git push -u origin squad/{issue-number}-{slug}
+gh pr create --base {baseBranch} --title "{description}" --body "Closes #{issue-number}" --draft
+```
+
+---
+
+## Parallel-Issue Workflow (Worktrees)
+
+### Pre-Spawn — Coordinator Creates Worktrees
+
+Before spawning agents, the coordinator creates one worktree per issue:
+
+```bash
+git fetch origin {baseBranch}
+git worktree add ./worktrees/squad-{issue} -b squad/{issue}-{slug} origin/{baseBranch}
+```
+
+**Naming convention:** `./worktrees/squad-{issue-number}` (e.g., `./worktrees/squad-195`).
+
+Each worktree:
+- Has its own working directory and index
+- Is on its own `squad/{issue-number}-{slug}` branch
+- Shares the same `.git` object store (disk-efficient)
+
+### Spawn Prompt — ISSUE CONTEXT Block
+
+When spawning an agent for worktree-based issue work, include this block in the spawn prompt:
+
+```
+ISSUE CONTEXT:
+  Issue: #{issue-number} — {title}
+  Branch: squad/{issue-number}-{slug}
+  Base: {baseBranch}
+
+WORKTREE_PATH: ./worktrees/squad-{issue-number}
+You are already on branch squad/{issue-number}-{slug} in a dedicated worktree.
+Work ONLY inside {WORKTREE_PATH}. Do NOT run `git checkout` to switch branches.
+
+After completing work:
+1. Stage and commit: `git add -A && git commit -m "feat: {description} (#{issue-number})"`
+2. Push: `git push -u origin squad/{issue-number}-{slug}`
+3. Open PR: `gh pr create --base {baseBranch} --title "{description}" --body "Closes #{issue-number}" --draft`
+```
+
+### Per-Worktree Agent Workflow
+
+Each agent operates inside its worktree:
+
+```bash
+cd ./worktrees/squad-{issue-number}
+
+# Work normally — commits, tests, pushes
+git add -A && git commit -m "fix: {description} (#{issue-number})"
+git push -u origin squad/{issue-number}-{slug}
+
+# Create PR targeting base branch
+gh pr create --base {baseBranch} --title "{description}" --body "Closes #{issue-number}" --draft
+```
+
+All PRs target the base branch independently. Agents never interfere with each other's filesystem.
+
+### .squad/ State in Worktrees
+
+The `.squad/` directory exists in each worktree as a copy. This is safe because:
+- `.gitattributes` declares `merge=union` on append-only files (history.md, decisions.md, logs)
+- Each agent appends to its own section; union merge reconciles on PR merge
+- **Rule:** Never rewrite or reorder `.squad/` files in a worktree — append only
+
+---
+
+## PR Review Handling
+
+After PR is created:
+1. If the team has a Lead with reviewer role, spawn Lead for review (sync mode — gates further work)
+2. If reviewer rejects, apply rejection lockout protocol
+3. If reviewer approves or no reviewer configured, PR is ready for merge
+
+---
+
+## Post-Merge Cleanup
+
+After a PR is merged:
+
+### Standard (single-issue)
+```bash
+git checkout {baseBranch} && git pull origin {baseBranch}
+git branch -d squad/{issue-number}-{slug}
+git push origin --delete squad/{issue-number}-{slug}
+```
+
+### Worktree (parallel-issue)
+```bash
+# From the main clone (not from inside the worktree)
+git worktree remove ./worktrees/squad-{issue-number}
+git worktree prune
+git branch -d squad/{issue-number}-{slug}
+git push origin --delete squad/{issue-number}-{slug}
+```
+
+If a worktree was deleted manually (`rm -rf`), `git worktree prune` recovers the state.
@@ -528,15 +528,44 @@ When the user gives any task, the Coordinator MUST:
 
 1. **Decompose broadly.** Identify ALL agents who could usefully start work, including anticipatory work (tests, docs, scaffolding) that will obviously be needed.
 2. **Check for hard data dependencies only.** Shared memory files (decisions, logs) use the drop-box pattern and are NEVER a reason to serialize. The only real conflict is: "Agent B needs to read a file that Agent A hasn't created yet."
-3. **Spawn all independent agents as `mode: "background"` in a single tool-calling turn.** Multiple `task` calls in one response is what enables true parallelism.
-4. **Show the user the full launch immediately:**
+3. **Create worktrees for parallel issue work.** When spawning 2+ agents on separate issues in the same repo, create a worktree per agent BEFORE spawning (see Worktree Lifecycle below). Single-agent tasks use `git checkout -b` as before.
+4. **Spawn all independent agents as `mode: "background"` in a single tool-calling turn.** Multiple `task` calls in one response is what enables true parallelism.
+5. **Show the user the full launch immediately:**
    ```
    🏗️ {Lead} analyzing project structure...
    ⚛️ {Frontend} building login form components...
    🔧 {Backend} setting up auth API endpoints...
    🧪 {Tester} writing test cases from requirements...
    ```
-5. **Chain follow-ups.** When background agents complete, immediately assess: does this unblock more work? Launch it without waiting for the user to ask.
+6. **Chain follow-ups.** When background agents complete, immediately assess: does this unblock more work? Launch it without waiting for the user to ask.
+
+### Worktree Lifecycle (Parallel Issue Work)
+
+When the coordinator needs to spawn **2+ agents on separate issues in the same repo**, use git worktrees to give each agent an isolated working directory. This prevents filesystem collisions from concurrent `git checkout` operations.
+
+**Decision logic:**
+- **Single agent / single issue** → `git checkout -b squad/{issue}-{slug}` (standard workflow)
+- **2+ agents on separate issues** → `git worktree add` per agent (worktree workflow)
+- **Ralph batch work (multiple issues)** → worktrees per issue
+
+**Pre-spawn — create worktrees:**
+```bash
+git fetch origin {baseBranch}
+git worktree add ./worktrees/squad-{issue} -b squad/{issue}-{slug} origin/{baseBranch}
+```
+
+**Spawn prompt — pass WORKTREE_PATH:**
+Include `WORKTREE_PATH: ./worktrees/squad-{issue}` in every agent spawn prompt that uses a worktree. The agent works exclusively inside that path and does NOT run `git checkout`.
+
+**Post-merge cleanup:**
+After a worktree agent's PR is merged, clean up:
+```bash
+git worktree remove ./worktrees/squad-{issue}
+git worktree prune
+git branch -d squad/{issue}-{slug}
+```
+
+If the worktree was deleted manually, `git worktree prune` recovers the state.
 
 **Example — "Team, build the login page":**
 - Turn 1: Spawn {Lead} (architecture), {Frontend} (UI), {Backend} (API), {Tester} (test cases from spec) — ALL background, ALL in one tool call
@@ -646,6 +675,12 @@ prompt: |
   TEAM ROOT: {team_root}
   All `.squad/` paths are relative to this root.
 
+  {only if agent was spawned with a worktree — omit for single-agent work:}
+  WORKTREE_PATH: {worktree_path}
+  You are already on branch {branchName} in a dedicated worktree.
+  Work ONLY inside this path. Do NOT run `git checkout` to switch branches.
+  {end worktree block}
+
   Read .squad/agents/{name}/history.md (your project knowledge).
   Read .squad/decisions.md (team decisions to respect).
   If .squad/identity/wisdom.md exists, read it before starting work.
@@ -1100,7 +1135,11 @@ Store `## Issue Source` in `team.md` with repository, connection date, and filte
 
 ### Issue → PR → Merge Lifecycle
 
-Agents create branch (`squad/{issue-number}-{slug}`), do work, commit referencing issue, push, and open PR via `gh pr create`. See `.squad/templates/issue-lifecycle.md` for the full spawn prompt ISSUE CONTEXT block, PR review handling, and merge commands.
+**On-demand reference:** Read `.squad/templates/issue-lifecycle.md` for the full worktree-aware lifecycle, spawn prompt additions, PR review handling, and merge/cleanup commands.
+
+**Single agent (standard):** Agent creates branch (`git checkout -b squad/{issue-number}-{slug}`), does work, commits referencing issue, pushes, and opens PR via `gh pr create`.
+
+**Parallel agents (worktree):** Coordinator creates a worktree per issue BEFORE spawning (`git worktree add ./worktrees/squad-{issue} -b squad/{issue}-{slug} origin/{baseBranch}`). Each agent receives `WORKTREE_PATH` in its spawn prompt and works exclusively inside its worktree. After PR merge, coordinator cleans up (`git worktree remove ./worktrees/squad-{issue} && git worktree prune`).
 
 After issue work completes, follow standard After Agent Work flow.