Skip to content

feat: add worktree creation/lifecycle to coordinator spawn flow#526

Merged
bradygaster merged 1 commit intobradygaster:devfrom
joniba:squad/525-worktree-lifecycle
Mar 23, 2026
Merged

feat: add worktree creation/lifecycle to coordinator spawn flow#526
bradygaster merged 1 commit intobradygaster:devfrom
joniba:squad/525-worktree-lifecycle

Conversation

@joniba
Copy link
Copy Markdown
Contributor

@joniba joniba commented Mar 22, 2026

Summary

Closes #525. Adds worktree creation and lifecycle management to the coordinator spawn flow. Previously, Squad could detect and read worktrees but never created them — all branch-creation paths hardcoded git checkout -b, breaking parallel multi-agent execution.

Changes

1. ralph-commands.ts — New worktree commands

Added createWorktree and removeWorktree to the RalphCommands interface and all 3 platform adapters (GitHub, ADO, Planner):

  • createWorktree: git fetch origin {baseBranch} && git worktree add {worktreePath} -b {branchName} origin/{baseBranch}
  • removeWorktree: git worktree remove {worktreePath} && git worktree prune

2. squad.agent.md — Worktree-aware spawn flow

  • Parallel Fan-Out section: Added step 3 (create worktrees for parallel issue work before spawning agents)
  • Worktree Lifecycle section: New section documenting decision logic (single agent = checkout, 2+ agents = worktrees), pre-spawn creation, and post-merge cleanup
  • Spawn template: Added WORKTREE_PATH block — tells agents they're in a dedicated worktree and must not run git checkout
  • Issue → PR → Merge Lifecycle: Updated to describe both single-agent (standard) and parallel-agent (worktree) paths; fixed reference to issue-lifecycle.md

3. issue-lifecycle.md — New template (was missing)

Created the template that was referenced twice in squad.agent.md but never existed. Contains:

  • Decision logic table (when to use checkout vs worktree)
  • Single-issue workflow (standard checkout -b)
  • Parallel-issue workflow (worktree-based) with coordinator pre-spawn, spawn prompt ISSUE CONTEXT block, per-worktree agent workflow, and post-merge cleanup
  • PR review handling and merge commands

4. git-workflow SKILL.md — Worktrees as default for parallel work

  • Restructured from flat workflow to Single Issue + Multiple Issues in Parallel subsections
  • Made worktrees the default strategy for 2+ simultaneous issues (was a separate "advanced" section)
  • Updated naming convention to ./worktrees/squad-{issue-number} (was ../{repo-name}-{issue-number})
  • Added coordinator pre-spawn responsibility (coordinator creates worktrees, not agents)
  • Updated per-worktree agent workflow to document WORKTREE_PATH and no-checkout rule

5. Tests

  • ralph-commands.test.ts: Added createWorktree and removeWorktree to COMMAND_KEYS, plus 2 new cross-platform tests verifying all platforms support worktree commands with correct placeholders
  • platform-adapter.test.ts: Added placeholder token assertions for createWorktree and removeWorktree

Test Results

All 134 tests passing (ralph-commands.test.ts + platform-adapter.test.ts).

…ygaster#525)

Add createWorktree and removeWorktree commands to RalphCommands interface
and all 3 platform adapters (GitHub, ADO, Planner). Update coordinator
spawn template in squad.agent.md to pass WORKTREE_PATH for parallel
issue work. Create the missing issue-lifecycle.md template with
worktree-aware issue-to-branch-to-PR-to-merge lifecycle. Update
git-workflow skill to make worktrees the default for parallel work.

Closes bradygaster#525

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@bradygaster bradygaster merged commit c701cad into bradygaster:dev Mar 23, 2026
chrislomonico pushed a commit to clomonico/squad that referenced this pull request Mar 26, 2026
bradygaster#545)

Adds opt-in OTel shell metrics (SQUAD_TELEMETRY=1): session_count, session_duration_ms, agent_response_latency_ms, error_count. Zero overhead when off.

Closes bradygaster#508, Closes bradygaster#520, Closes bradygaster#526, Closes bradygaster#530, Closes bradygaster#531

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

3 participants