docs(governance): coordinator worktree spawn flow (#529)

.squad-templates/squad.agent.md

@@ -318,7 +318,13 @@ description: "{emoji} {Name}: {brief task summary}"
 prompt: |
   You are {Name}, the {Role} on this project.
   TEAM ROOT: {team_root}
+  WORKTREE_PATH: {worktree_path}
+  WORKTREE_MODE: {true|false}
   **Requested by:** {current user name}
+
+  {% if WORKTREE_MODE %}
+  **WORKTREE:** Working in `{WORKTREE_PATH}`. All operations relative to this path. Do NOT switch branches.
+  {% endif %}
 
   TASK: {specific task description}
   TARGET FILE(S): {exact file path(s)}
@@ -630,6 +636,39 @@ Squad and all spawned agents may be running inside a **git worktree** rather tha
 - **Not safe for concurrent sessions.** If two worktrees run sessions simultaneously, Scribe merge-and-commit steps will race on `decisions.md` and git index. Use only when a single session is active at a time.
 - Best suited for solo use when you want a single source of truth without waiting for branch merges.
 
+### Worktree Lifecycle Management
+
+When worktree mode is enabled, the coordinator creates dedicated worktrees for issue-based work. This gives each issue its own isolated branch checkout without disrupting the main repo.
+
+**Worktree mode activation:**
+- Explicit: `worktrees: true` in project config (squad.config.ts or package.json `squad` section)
+- Environment: `SQUAD_WORKTREES=1` set in environment variables
+- Default: `false` (backward compatibility — agents work in the main repo)
+
+**Creating worktrees:**
+- One worktree per issue number
+- Multiple agents on the same issue share a worktree
+- Path convention: `{repo-parent}/{repo-name}-{issue-number}`
+  - Example: Working on issue #42 in `C:\src\squad` → worktree at `C:\src\squad-42`
+- Branch: `squad/{issue-number}-{kebab-case-slug}` (created from base branch, typically `main`)
+
+**Dependency management:**
+- After creating a worktree, link `node_modules` from the main repo to avoid reinstalling
+- Windows: `cmd /c "mklink /J {worktree}\node_modules {main-repo}\node_modules"`
+- Unix: `ln -s {main-repo}/node_modules {worktree}/node_modules`
+- If linking fails (permissions, cross-device), fall back to `npm install` in the worktree
+
+**Reusing worktrees:**
+- Before creating a new worktree, check if one exists for the same issue
+- `git worktree list` shows all active worktrees
+- If found, reuse it (cd to the path, verify branch is correct, `git pull` to sync)
+- Multiple agents can work in the same worktree concurrently if they modify different files
+
+**Cleanup:**
+- After a PR is merged, the worktree should be removed
+- `git worktree remove {path}` + `git branch -d {branch}`
+- Ralph heartbeat can trigger cleanup checks for merged branches
+
 ### Orchestration Logging
 
 Orchestration log entries are written by **Scribe**, not the coordinator. This keeps the coordinator's post-work turn lean and avoids context window pressure after collecting multi-agent results.
@@ -638,6 +677,53 @@ The coordinator passes a **spawn manifest** (who ran, why, what mode, outcome) t
 
 Each entry records: agent routed, why chosen, mode (background/sync), files authorized to read, files produced, and outcome. See `.squad/templates/orchestration-log.md` for the field format.
 
+### Pre-Spawn: Worktree Setup
+
+When spawning an agent for issue-based work (user request references an issue number, or agent is working on a GitHub issue):
+
+**1. Check worktree mode:**
+- Is `SQUAD_WORKTREES=1` set in the environment?
+- Or does the project config have `worktrees: true`?
+- If neither: skip worktree setup → agent works in the main repo (existing behavior)
+
+**2. If worktrees enabled:**
+
+a. **Determine the worktree path:**
+   - Parse issue number from context (e.g., `#42`, `issue 42`, GitHub issue assignment)
+   - Calculate path: `{repo-parent}/{repo-name}-{issue-number}`
+   - Example: Main repo at `C:\src\squad`, issue #42 → `C:\src\squad-42`
+
+b. **Check if worktree already exists:**
+   - Run `git worktree list` to see all active worktrees
+   - If the worktree path already exists → **reuse it**:
+     - Verify the branch is correct (should be `squad/{issue-number}-*`)
+     - `cd` to the worktree path
+     - `git pull` to sync latest changes
+     - Skip to step (e)
+
+c. **Create the worktree:**
+   - Determine branch name: `squad/{issue-number}-{kebab-case-slug}` (derive slug from issue title if available)
+   - Determine base branch (typically `main`, check default branch if needed)
+   - Run: `git worktree add {path} -b {branch} {baseBranch}`
+   - Example: `git worktree add C:\src\squad-42 -b squad/42-fix-login main`
+
+d. **Set up dependencies:**
+   - Link `node_modules` from main repo to avoid reinstalling:
+     - Windows: `cmd /c "mklink /J {worktree}\node_modules {main-repo}\node_modules"`
+     - Unix: `ln -s {main-repo}/node_modules {worktree}/node_modules`
+   - If linking fails (error), fall back: `cd {worktree} && npm install`
+   - Verify the worktree is ready: check build tools are accessible
+
+e. **Include worktree context in spawn:**
+   - Set `WORKTREE_PATH` to the resolved worktree path
+   - Set `WORKTREE_MODE` to `true`
+   - Add worktree instructions to the spawn prompt (see template below)
+
+**3. If worktrees disabled:**
+- Set `WORKTREE_PATH` to `"n/a"`
+- Set `WORKTREE_MODE` to `false`
+- Use existing `git checkout -b` flow (no changes to current behavior)
+
 ### How to Spawn an Agent
 
 **You MUST call the `task` tool** with these parameters for every agent spawn:
@@ -683,6 +769,17 @@ prompt: |
   - Consult mode: Provide recommendations, not direct changes
   {end Ghost Protocol block}
 
+  WORKTREE_PATH: {worktree_path}
+  WORKTREE_MODE: {true|false}
+
+  {% if WORKTREE_MODE %}
+  **WORKTREE:** You are working in a dedicated worktree at `{WORKTREE_PATH}`.
+  - All file operations should be relative to this path
+  - Do NOT switch branches — the worktree IS your branch (`{branch_name}`)
+  - Build and test in the worktree, not the main repo
+  - Commit and push from the worktree
+  {% endif %}
+
   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.