feat(#525): Architecture decision: worktree vs checkout heuristic #531

Activity

1. bradygaster

   added

   squadSquad triage inbox — Lead will assign to a memberSquad triage inbox — Lead will assign to a member

   type:featureNew capabilityNew capability

   squad:flight

   on Mar 22, 2026
2. github-actions commented on Mar 22, 2026

   

   github-actionsBot

   on Mar 22, 2026 – with GitHub Actions

   Contributor

   More actions

   📋 Assigned to Flight (Lead)

   Issue: #531 — feat(#525): Architecture decision: worktree vs checkout heuristic

   Flight will pick this up in the next Copilot session.

   For Copilot coding agent: If enabled, this issue will be worked automatically.
   Otherwise, start a Copilot session and say:
   Flight, work on issue #531
3. github-actions commented on Mar 22, 2026

   

   github-actionsBot

   on Mar 22, 2026 – with GitHub Actions

   Contributor

   More actions

   🏗️ Squad Triage — Flight (Lead)

   Issue: #531 — feat(#525): Architecture decision: worktree vs checkout heuristic
   Assigned to: Flight (Lead)
   Reason: No specific domain match — assigned to Lead for further analysis

   @copilot evaluation: No strong capability match — routed to squad member.

   Team roster:

   • Flight (Lead) → label: squad:flight
   • Procedures (Prompt Engineer) → label: squad:procedures
   • EECOM (Core Dev) → label: squad:eecom
   • FIDO (Quality Owner) → label: squad:fido
   • PAO (DevRel) → label: squad:pao
   • CAPCOM (SDK Expert) → label: squad:capcom
   • CONTROL (TypeScript Engineer) → label: squad:control
   • Surgeon (Release Manager) → label: squad:surgeon
   • Booster (CI/CD Engineer) → label: squad:booster
   • GNC (Node.js Runtime) → label: squad:gnc
   • Network (Distribution) → label: squad:network
   • RETRO (Security) → label: squad:retro
   • INCO (CLI UX & Visual Design) → label: squad:inco
   • GUIDO (VS Code Extension) → label: squad:guido
   • Telemetry (Aspire & Observability) → label: squad:telemetry
   • VOX (REPL & Interactive Shell) → label: squad:vox
   • DSKY (TUI Engineer) → label: squad:dsky
   • Sims (E2E Test Engineer) → label: squad:sims
   • Handbook (SDK Usability) → label: squad:handbook
   • Ralph (Work Monitor) → label: squad:ralph
   • @copilot (Coding Agent) → label: squad:copilot

   To reassign, remove the current squad:* label and add the correct one.
4. github-actions

   added

   go:needs-researchNeeds investigationNeeds investigation

   on Mar 22, 2026
5. bradygaster commented on Mar 22, 2026

   

   bradygaster

   on Mar 22, 2026

   CollaboratorAuthor

   More actions

   Architecture Decision Complete

   📋 Decision document: .squad/decisions/inbox/flight-worktree-heuristic.md
   🔀 Branch: squad/531-worktree-heuristic

   Key Decisions

   1. Opt-in configuration (not heuristic-based)

   • Default: worktrees: false (backward compatible — all existing workflows use git checkout -b)
   • Enable via squad.config.ts: worktrees: true
   • Fallback: .squad/config.json → { "worktrees": true }
   • Override: SQUAD_WORKTREES=1 env var (highest precedence)

   Rationale: Heuristics (parallel spawn detection) are brittle and unpredictable. Configuration is explicit and user-controlled.

   2. Worktree path convention

   • Pattern: {repo-parent}/{repo-name}-{issue}
   • Example: Main repo C:\src\squad\ → Issue chore: remove internal team-docs from main #42 worktree C:\src\squad-42
   • Configurable via worktreePath pattern in config (optional)

   3. Dependency management

   • Recommended: Junction (Windows mklink /J) or symlink (Unix ln -s) for node_modules from main repo
   • Fallback: npm install in worktree if junction/symlink fails
   • Coordinator handles this automatically after git worktree add

   4. All 3 platform adapters get identical worktree support

   • GitHub, Azure DevOps, Planner all use same createWorktree / removeWorktree commands
   • createWorktree: git worktree add {path} -b {branch} {base}
   • removeWorktree: git worktree remove {path} && git worktree prune

   Implications for Sibling Issues

   #528 (ralph-commands.ts):

   • Add createWorktree? and removeWorktree? fields to RalphCommands interface (optional — only present when worktrees enabled)
   • No breaking changes to existing createBranch command

   #529 (coordinator pre-spawn):

   • Read worktrees config at session start
   • Branch on config: worktrees enabled → createWorktree, disabled → createBranch
   • Pass WORKTREE_PATH in spawn prompt when worktrees enabled
   • Handle dependency management (junction or install)

   #530 (post-merge cleanup):

   • Trigger removeWorktree after PR merge (via Ralph idle-watch or coordinator)
   • Log cleanup to orchestration log
   • Graceful failure handling (warn + defer if removal fails)

   Config Schema

   typescript export interface TeamConfig { worktrees?: boolean; // Default: false worktreePath?: string; // Default: '{repo-parent}/{repo-name}-{issue}' }

   Precedence: SQUAD_WORKTREES env var > squad.config.ts > .squad/config.json > default (false)

   Migration Path

   ✅ Zero breaking changes — all existing workflows continue using git checkout -b
   ✅ Teams opt-in by adding worktrees: true to config when ready
   ✅ New teams can enable during init if they expect parallel work

   Next Steps

   1. ✅ feat(#525): Architecture decision: worktree vs checkout heuristic #531 (this issue): Decision document complete (ready for Scribe to merge into decisions.md)
   2. ⏭️ feat(#525): Add worktree branch creation variant to ralph-commands.ts #528: EECOM implements worktree commands in ralph-commands.ts
   3. ⏭️ feat(#525): Add worktree creation to coordinator spawn flow #529: Flight or EECOM implements coordinator worktree creation + dependency management
   4. ⏭️ feat(#525): Implement post-merge worktree cleanup lifecycle #530: Flight or EECOM implements post-merge cleanup lifecycle
   5. ⏭️ Docs: PAO updates worktrees.md, parallel-work.md, squad.agent.md

   Decision approved by: Flight (as architect + owner of #531)
6. bradygaster

   added 2 commits that reference this issue on Mar 22, 2026

   feat(sdk): add worktree branch creation variant to ralph-commands (#528)

   ...

   60a4b8b

   docs(decisions): architecture decision for worktree heuristic (#531) (#…

   ...

   b0b2cd6
7. bradygaster

   closed this as completedin #532on Mar 23, 2026
8. bradygaster

   added a commit that references this issue on Mar 23, 2026

   feat(sdk): add worktree branch creation variant to ralph-commands (#528…

   ...

   08dd41f
9. chrislomonico

   added a commit that references this issue on Mar 26, 2026

   feat(observability): add OTel shell metrics — session, latency, errors (

   ...

   This issue will close once commit 770e344 is merged into the 'main' branch.

   770e344
10. bradygaster

    removed

    squad:flight

    on Sep 11, 2026