Title: feat: Worktree creation and lifecycle missing from coordinator/spawn flow · Issue #525 · github/squad · GitHub
Open Graph Title: feat: Worktree creation and lifecycle missing from coordinator/spawn flow · Issue #525 · github/squad
X Title: feat: Worktree creation and lifecycle missing from coordinator/spawn flow · Issue #525 · github/squad
Description: 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 paral...
Open Graph Description: 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 hardc...
X Description: 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 hardc...
Opengraph URL: https://github.com/github/squad/issues/525
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"feat: Worktree creation and lifecycle missing from coordinator/spawn flow","articleBody":"## Summary\n\nSquad 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.\n\n## What exists (worktree reading — works correctly)\n\n| Component | File | What it does |\n|-----------|------|-------------|\n| SDK resolution | `packages/squad-sdk/src/resolution.ts` L61-82 | `resolveSquad()` detects `.git` as file (worktree pointer), stops at boundary correctly |\n| Coordinator session start | `.squad-templates/squad.agent.md` L100 | Resolves team root via `git rev-parse --show-toplevel`, passes `TEAM_ROOT` to agents |\n| Worktree Awareness section | `.squad-templates/squad.agent.md` L569-601 | Documents two strategies (worktree-local vs main-checkout), `TEAM_ROOT` passing |\n| Agent charters | `packages/squad-sdk/src/roles/index.ts` L193 | All agents told to `git rev-parse --show-toplevel` — never assume CWD |\n| Merge safety | `.gitattributes` | `merge=union` on append-only `.squad/` files |\n| Consult mode | `packages/squad-sdk/src/sharing/consult.ts` L320-367 | `resolveGitExcludePath()` uses `git rev-parse` to handle worktrees/submodules |\n| Tests | `test/resolution.test.ts` L51-63 | Two tests: `.git` worktree file boundary detection + `.squad/` found in worktree |\n\n## What's missing (worktree creation/lifecycle — the gap)\n\n| What exists | What's missing |\n|-------------|----------------|\n| Worktree detection (can I read state?) | Worktree creation (do I create one per agent?) |\n| Worktree state resolution (where is `.squad/`?) | Worktree lifecycle (create before spawn, cleanup after merge) |\n| `merge=union` for clean merges | Spawn template saying \"work in your worktree, don't `checkout -b`\" |\n| git-workflow skill documents `git worktree add` | Nothing in the coordinator flow invokes it |\n\n## Specific locations that need changes\n\n### 1. `ralph-commands.ts` — all 3 platform adapters hardcode `checkout -b`\n\n**File:** `packages/squad-sdk/src/platform/ralph-commands.ts`\n\nAll three adapters (GitHub L71, ADO L92, Planner L50) have:\n\n```typescript\ncreateBranch: 'git checkout main && git pull && git checkout -b {branchName}',\n```\n\nNo worktree variant exists. When Ralph spawns parallel agents, they all run `checkout -b` in the same working directory, clobbering each other.\n\n### 2. `issue-lifecycle.md` — referenced but doesn't exist\n\n**File:** `.squad-templates/squad.agent.md` L1097 and L1103\n\n```\nSee `.squad/templates/issue-lifecycle.md` for the full spawn prompt ISSUE CONTEXT block...\n```\n\nThis 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).\n\n### 3. git-workflow skill defaults to `checkout -b`\n\n**File:** `.copilot/skills/git-workflow/SKILL.md` L29-34\n\nThe 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.\n\n### 4. No `WORKTREE_PATH` in spawn prompts\n\n**File:** `.squad-templates/squad.agent.md` L592-595\n\n`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.\"\n\n### 5. No worktree lifecycle management\n\nNothing in the codebase:\n- Creates worktrees before spawning parallel agents\n- Passes the worktree path to the spawned agent\n- Cleans up worktrees after PR merge\n- Decides when to use worktrees vs `checkout -b` (single agent = checkout, multiple = worktrees)\n\n## Proposed fix\n\n### Coordinator pre-spawn (parallel work):\n\n```bash\n# Create a worktree per agent/issue\ngit worktree add ./worktrees/squad-{issue} -b squad/{issue}-{slug} origin/dev\n```\n\n### Agent spawn prompt addition:\n\n```\nWORKTREE_PATH: ./worktrees/squad-{issue}\n\"You are already on branch squad/{issue}-{slug}. Work only in {WORKTREE_PATH}.\"\n```\n\n### Post-merge cleanup:\n\n```bash\ngit worktree remove ./worktrees/squad-{issue}\ngit worktree prune\n```\n\n### Decision logic:\n\n- **Single agent** -> `git checkout -b` (current behavior, fine)\n- **Multiple agents in parallel** -> `git worktree add` per agent (new)\n- **Ralph batch work** -> worktrees (new)\n\n### Files to change:\n\n1. `packages/squad-sdk/src/platform/ralph-commands.ts` — add `createWorktree` / `removeWorktree` commands\n2. `.squad-templates/squad.agent.md` — update spawn flow to create worktrees for parallel work, add `WORKTREE_PATH` to spawn prompts\n3. Create `.squad-templates/issue-lifecycle.md` — the missing template, with worktree-aware lifecycle\n4. `.copilot/skills/git-workflow/SKILL.md` — make worktree the default for parallel work, not a separate section\n5. `test/` — add tests for worktree creation/cleanup lifecycle\n\n## Additional context\n\n- 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.\n- The `merge=union` `.gitattributes` strategy already handles the merge side correctly.\n- The SDK `resolution.ts` + tests already handle the read side correctly.\n- This is purely a coordinator/orchestration gap, not an SDK gap.","author":{"url":"https://github.com/joniba","@type":"Person","name":"joniba"},"datePublished":"2026-03-22T22:42:16Z","url":"https://github.com/github/squad/issues/525"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:51c5cebc-1cc3-6a41-461d-3ccaad6efef1 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 83BA:B1B84:10647F9:14C7180:6B014EE1 |
| html-safe-nonce | d3fda634aa5025ebf314c5417ad190a81cf464107ca01e34472143e8618465da |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI4M0JBOkIxQjg0OjEwNjQ3Rjk6MTRDNzE4MDo2QjAxNEVFMSIsInZpc2l0b3JfaWQiOiIzNTE3MjQzODE5NjU1NTE1ODczIiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | aba8c46591c4b1f814cc2f4ef0d97a7bc0ed5297e1f6d89b8b21f29b36b0b82d |
| hovercard-subject-tag | issue:4117297159 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/github/squad/525/issue_layout |
| twitter:image | https://opengraph.githubassets.com/4fc6ab94fbcb28ed3da9aa31ccc0d9fa8b770d7f0c56d480d5aa349e5c6c4591/github/squad/issues/525 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/4fc6ab94fbcb28ed3da9aa31ccc0d9fa8b770d7f0c56d480d5aa349e5c6c4591/github/squad/issues/525 |
| og:image:alt | 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 hardc... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | joniba |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| go-import | github.com/github/squad git https://github.com/github/squad.git |
| octolytics-dimension-user_id | 9919 |
| octolytics-dimension-user_login | github |
| octolytics-dimension-repository_id | 1151205052 |
| octolytics-dimension-repository_nwo | github/squad |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 1151205052 |
| octolytics-dimension-repository_network_root_nwo | github/squad |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width