feat: Worktree creation and lifecycle missing from coordinator/spawn flow #525

Summary

Squad has full worktree detection (reading .squad/ state from worktrees) but the coordinator and spawn flow never creates worktrees for parallel agent work. Every branch-creation path hardcodes git checkout -b, which breaks parallel multi-agent execution — agents clobber each other's working directory.

What exists (worktree reading — works correctly)

What's missing (worktree creation/lifecycle — the gap)

Specific locations that need changes

1. ralph-commands.ts — all 3 platform adapters hardcode checkout -b

File: packages/squad-sdk/src/platform/ralph-commands.ts

All three adapters (GitHub L71, ADO L92, Planner L50) have:

createBranch: 'git checkout main && git pull && git checkout -b {branchName}',

No worktree variant exists. When Ralph spawns parallel agents, they all run checkout -b in the same working directory, clobbering each other.

2. issue-lifecycle.md — referenced but doesn't exist

File: .squad-templates/squad.agent.md L1097 and L1103

See `.squad/templates/issue-lifecycle.md` for the full spawn prompt ISSUE CONTEXT block...

This template is referenced twice but does not exist anywhere in the repo. The coordinator has no template for the issue-to-branch-to-PR flow, so it falls back to git checkout -b from the git-workflow skill's default single-issue workflow (L33).

3. git-workflow skill defaults to checkout -b

File: .copilot/skills/git-workflow/SKILL.md L29-34

The default "Workflow for Issue Work" uses git checkout -b. The worktree path (L62-130) is documented as a separate "Parallel Multi-Issue Work" section, but nothing in the coordinator flow triggers it — the coordinator reads the default workflow.

4. No WORKTREE_PATH in spawn prompts

File: .squad-templates/squad.agent.md L592-595

TEAM_ROOT is passed to agents (for reading .squad/ state), but there's no WORKTREE_PATH mechanism to tell an agent "you are in worktree X, stay there, don't switch branches."

5. No worktree lifecycle management

Nothing in the codebase:

• Creates worktrees before spawning parallel agents
• Passes the worktree path to the spawned agent
• Cleans up worktrees after PR merge
• Decides when to use worktrees vs checkout -b (single agent = checkout, multiple = worktrees)

Proposed fix

Coordinator pre-spawn (parallel work):

# Create a worktree per agent/issue
git worktree add ./worktrees/squad-{issue} -b squad/{issue}-{slug} origin/dev

Agent spawn prompt addition:

WORKTREE_PATH: ./worktrees/squad-{issue}
"You are already on branch squad/{issue}-{slug}. Work only in {WORKTREE_PATH}."

Post-merge cleanup:

git worktree remove ./worktrees/squad-{issue}
git worktree prune

Decision logic:

• Single agent -> git checkout -b (current behavior, fine)
• Multiple agents in parallel -> git worktree add per agent (new)
• Ralph batch work -> worktrees (new)

Files to change:

1. packages/squad-sdk/src/platform/ralph-commands.ts — add createWorktree / removeWorktree commands
2. .squad-templates/squad.agent.md — update spawn flow to create worktrees for parallel work, add WORKTREE_PATH to spawn prompts
3. Create .squad-templates/issue-lifecycle.md — the missing template, with worktree-aware lifecycle
4. .copilot/skills/git-workflow/SKILL.md — make worktree the default for parallel work, not a separate section
5. test/ — add tests for worktree creation/cleanup lifecycle

Additional context

• The git-workflow skill already documents the correct git worktree add commands (L82-84) and cleanup (L120-130) — the knowledge exists, it just isn't wired into the coordinator flow.
• The merge=union .gitattributes strategy already handles the merge side correctly.
• The SDK resolution.ts + tests already handle the read side correctly.
• This is purely a coordinator/orchestration gap, not an SDK gap.