From 83d02dbb0c0f0d45448fa0658c1ec603c3a9d396 Mon Sep 17 00:00:00 2001 From: bradygaster Date: Sun, 22 Mar 2026 15:52:48 -0700 Subject: [PATCH 1/2] chore(.squad): triage #525, backlog prioritization - Add orchestration log: 2026-03-22T22-45-flight-triage-525.md - Add session log: 2026-03-22T22-45-triage-session.md - Merge decision inbox (6 files) into decisions.md: - flight-triage-525.md (validated #525, P2 rating, sub-issue decomposition, top-5 v1 priorities) - eecom-economy-mode.md (economy mode design decision) - eecom-node-sqlite.md (Node 22.5.0+ hard-fail decision) - eecom-rate-limit-ux.md (rate limit detection and recovery) - procedures-economy-mode-governance.md (squad.agent.md governance proposal) - procedures-personal-squad-governance.md (consult mode governance proposal) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .squad/agents/flight/history.md | 8 + .squad/decisions.md | 486 ++++++++++++++++++ .squad/decisions/inbox/eecom-economy-mode.md | 37 -- .../procedures-economy-mode-governance.md | 126 ----- .../procedures-personal-squad-governance.md | 158 ------ 5 files changed, 494 insertions(+), 321 deletions(-) delete mode 100644 .squad/decisions/inbox/eecom-economy-mode.md delete mode 100644 .squad/decisions/inbox/procedures-economy-mode-governance.md delete mode 100644 .squad/decisions/inbox/procedures-personal-squad-governance.md diff --git a/.squad/agents/flight/history.md b/.squad/agents/flight/history.md index 438cba1bb..36e50127d 100644 --- a/.squad/agents/flight/history.md +++ b/.squad/agents/flight/history.md @@ -65,3 +65,11 @@ Created `.squad/skills/content-triage/SKILL.md` to codify the boundary heuristic ### Session 2 Summary (2026-03-22) Wave 1 architecture work on #329/#344: validated 20KB personal squad design doc, identified and patched 5 gaps, authored 19-task implementation plan spanning 4 future PRs. Implementation not yet started — deferred to future session. EECOM assigned Phase 1–2 (SDK + CLI), Procedures assigned Phase 3 (governance), Sims assigned Phase 4 (tests). + +### Worktree Gap Triage — #525 (2025-07-18) + +Community contributor joniba filed #525 identifying that Squad has full worktree *detection* but zero worktree *creation* in the coordinator/spawn flow. Validated all 10 claims — analysis is accurate. The reading infrastructure (resolveSquad() worktree detection, .gitattributes merge=union, boundary tests) is ~95% complete. The gap: ralph-commands.ts hardcodes `git checkout -b` in all 3 platform adapters (lines 50/71/92), coordinator never creates worktrees before spawn, no WORKTREE_PATH in prompts, and issue-lifecycle.md is referenced in squad.agent.md but doesn't exist. + +**Decision:** P2 — important but not v1-blocking. Broke into 5 sub-issues: (1) doc fix for missing issue-lifecycle.md (quick win → Procedures), (2) worktree variant in ralph-commands.ts (EECOM), (3) coordinator pre-spawn logic (Procedures + EECOM), (4) post-merge cleanup (EECOM), (5) architecture decision on heuristic (Flight). Sub-issue #1 ships immediately; #2–5 queue post-Wave-1 alongside SubSquads work where parallel execution becomes a hard requirement. + +**Backlog priority recommendation:** Top 5 for v1 = #508 (Ambient Personal Squad), #498 (remove .squad/ from VCS), #485 (Agent Spec & Validation), #481 (Typed StorageProvider), #347 (shore up init --sdk). Quick wins: #525 doc fix, #347. Deprioritize: manual verification debt (#418–421), long-term exploratory. A2A (#332–336) stays shelved per existing decision. diff --git a/.squad/decisions.md b/.squad/decisions.md index 9992fb61b..0e0469546 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -6138,3 +6138,489 @@ ESM module resolution uses dual-layer postinstall strategy: **Impact:** If users report ESM errors on Node 22/24, direct them to `squad doctor`. + +--- + +# Economy Mode Design — #500 + +**Date:** 2026-03-20 +**Author:** EECOM +**Issue:** #500 + +## Decision + +Economy mode is implemented as a modifier that shifts model selection at Layer 3 (task-aware auto) and Layer 4 (default fallback) only. Layers 0–2 (explicit user preferences) are never downgraded. + +## Model Map + +| Normal | Economy | Use case | +|--------|---------|----------| +| `claude-opus-4.6` | `claude-sonnet-4.5` | Architecture, review | +| `claude-sonnet-4.6` | `gpt-4.1` | Code writing | +| `claude-sonnet-4.5` | `gpt-4.1` | Code writing | +| `claude-haiku-4.5` | `gpt-4.1` | Docs, planning, mechanical | + +## Activation + +1. **Persistent:** `"economyMode": true` in `.squad/config.json` (survives sessions) +2. **Session:** `--economy` CLI flag (sets `SQUAD_ECONOMY_MODE=1` env var, current session only) +3. **Toggle command:** `squad economy on|off` writes to config.json + +## Hierarchy Integration + +Economy mode is a Layer 3/4 modifier — it does NOT override explicit preferences (Layers 0–2). This is intentional: if a user said "always use opus", economy mode respects that choice. + +## Implementation Points + +- `ECONOMY_MODEL_MAP` + `applyEconomyMode()` in `packages/squad-sdk/src/config/models.ts` +- `readEconomyMode()` + `writeEconomyMode()` in `packages/squad-sdk/src/config/models.ts` +- `resolveModel()` in `config/models.ts` accepts `economyMode?: boolean` option; reads from config if not provided +- `resolveModel()` in `agents/model-selector.ts` also supports `economyMode?: boolean` +- `squad economy [on|off]` command in `packages/squad-cli/src/cli/commands/economy.ts` +- `--economy` global flag in `cli-entry.ts` + +--- + +# Decision: Hard-fail on Node <22.5.0 at CLI Startup + +**Author:** EECOM +**Date:** 2026-03-21 +**Issue:** #502 (workshop blocker) + +## Context + +Workshop participants reported `ERR_UNKNOWN_BUILTIN_MODULE` when using Squad on Node <22.5.0. The `node:sqlite` built-in (used by the Copilot SDK for session storage) requires Node 22.5.0+. + +The previous approach — `try { await import('node:sqlite') } catch { warn and continue }` — let the process limp along until the SDK actually hit sqlite, producing a confusing crash deep in a stack trace. + +## Decision + +**Hard-fail at startup with a clear, actionable message.** If Node <22.5.0 is detected, Squad exits immediately (`process.exit(1)`) with: + +``` +✗ Squad requires Node.js ≥22.5.0 (you have v20.18.0). + node:sqlite (required by the Copilot SDK for session storage) was added in Node 22.5.0. + Upgrade at: https://nodejs.org/en/download +``` + +**Rationale:** +- Fail fast > fail cryptically later +- The message includes the exact version needed and where to upgrade +- `engines.node` updated to `>=22.5.0` in all package.json files — npm/npx will also warn at install time +- `squad doctor` now includes a Node version check so users can proactively diagnose + +## Alternatives Rejected + +- **Fallback to `better-sqlite3`:** Adds a native binary dependency. Complexity cost is not justified since Node 22.5.0+ is already 18+ months old. +- **Soft warn and continue:** The existing approach — proved to be a workshop blocker. + +--- + +# Rate Limit UX: Detect and Recover, Don't Hide + +**Date:** 2026-03-20 +**Author:** EECOM +**Issue:** #464 + +## Decision + +When Squad catches a rate limit error (HTTP 429, "rate limit", "quota exceeded"), surface it explicitly rather than hiding it under "Something went wrong processing your message." + +## Rationale + +Generic error messages fail the user in two ways: +1. They don't explain *why* the error happened (rate limit vs. network vs. bug) +2. They give no recovery path — the user is stuck with "run squad doctor" which previously showed nothing useful + +Rate limits are a **pivot point, not a dead end**. The user can unblock themselves immediately by switching to economy mode or a different model. + +## Implementation + +1. **`error-messages.ts`** — added `rateLimitGuidance()` and `extractRetryAfter()`. Rate limit guidance shows: + - Clear message: "Rate limit reached [for {model}]. Copilot has temporarily throttled your requests." + - Recovery: time until reset (if parseable), `squad economy on`, and config.json model override + +2. **`shell/index.ts` catch block** — detects rate limits via `instanceof RateLimitError` OR regex on the error message (`/rate.?limit|quota.*exceed|429/i`). Writes `.squad/rate-limit-status.json` on detection for doctor to read. + +3. **`doctor.ts`** — added `checkRateLimitStatus()`. Reads `.squad/rate-limit-status.json` and reports: + - `warn` if rate limit was recent (< 4h ago), with command to fix + - `pass` if stale (> 4h ago) + - Silent if no rate limit has been hit + +## Alternatives Considered + +- **Making a live API call in `squad doctor`** — rejected, adds latency and may itself be rate-limited +- **Just showing the raw error** — rejected, unhelpful wall of text +- **Writing to a separate log format** — rejected, JSON status file is simpler to read/update + +--- + +# Triage: #525 — Worktree Creation & Lifecycle Missing from Coordinator/Spawn Flow + +**Author:** Flight +**Date:** 2025-07-18 +**Status:** Triaged +**Priority:** P2 — Important, not v1-blocking +**Labels:** `squad:eecom`, `squad:procedures`, `squad:flight` + +## Validation + +Community contributor joniba's analysis is **accurate and thorough**. I validated all 10 claims: + +| Claim | Verdict | +|-------|---------| +| ralph-commands.ts hardcodes `git checkout -b` (all 3 adapters) | ✅ Confirmed — lines 50, 71, 92 | +| issue-lifecycle.md referenced but missing | ✅ Confirmed — two broken refs in squad.agent.md | +| squad.agent.md has Worktree Awareness section | ✅ Confirmed — lines 569–607 | +| git-workflow skill defaults to checkout -b | ✅ Confirmed — worktree is documented but separate path | +| resolveSquad() detects .git as file (worktree pointer) | ✅ Confirmed — resolution.ts line 66–93 | +| .gitattributes merge=union for append-only files | ✅ Confirmed — 5 entries | +| Tests for worktree boundary detection | ✅ Confirmed — 5+ tests | +| Coordinator creates worktrees before spawn | ❌ Confirmed missing | +| WORKTREE_PATH in spawn prompts | ❌ Confirmed missing | +| Post-merge worktree cleanup | ❌ Confirmed missing | + +**Summary:** The reading side (detection, path resolution, merge drivers, tests) is solid — approximately 95% of the worktree infrastructure exists. The gap is purely on the writing/orchestration side: nobody creates worktrees, and the coordinator doesn't know it should. + +## Impact Assessment + +**Who this affects:** Any user running parallel agents on the same repo. Today, two agents spawned simultaneously will both `git checkout -b` from the same working directory and clobber each other. + +**Why it's P2 not P1:** Most current Squad users run single-agent sequential workflows. Parallel multi-agent execution is the advanced case. The SubSquads/Workstreams design (#509–#511) will eventually need this, but those aren't in Wave 1. + +**Risk of deferral:** Low short-term, medium long-term. Community contributors noticing the gap means adoption is hitting this edge. If we defer past v1, it becomes tech debt that's harder to retrofit. + +## Scope Recommendation: Break Into Sub-Issues + +This is too broad for one issue. Recommended decomposition: + +1. **Doc fix: Create issue-lifecycle.md** (quick win, 1 hour) + Owner: `squad:procedures` + Fix the broken reference in squad.agent.md. Standalone — no code changes. + +2. **SDK: Add worktree branch-creation variant to ralph-commands.ts** + Owner: `squad:eecom` + Add `git worktree add` as an alternative to `git checkout -b` in all 3 platform adapters. Decision logic: single agent = checkout, parallel = worktree. + +3. **Coordinator: Pre-spawn worktree creation** + Owner: `squad:procedures`, `squad:eecom` + When coordinator detects parallel spawn, create worktree before dispatching agent. Pass WORKTREE_PATH in spawn context. + +4. **Lifecycle: Post-merge worktree cleanup** + Owner: `squad:eecom` + After PR merge, `git worktree remove` + prune. Could hook into Ralph's idle-watch. + +5. **Architecture decision: Worktree vs checkout heuristic** + Owner: `squad:flight` + Formal decision on when to use which strategy. Default: checkout-b for solo work, worktree for parallel. Write to decisions.md. + +## Priority Relative to Backlog + +**Above:** Long-term/exploratory (#357, #316, #308, #296, #260, #252), manual verification debt (#418–#421) +**Comparable to:** #457 (monorepo context), #413 (knowledge library) — all infrastructure improvements +**Below:** Wave 1 (#508, #330/#354), PRDs (#498, #485, #481), GitLab support (#465) + +**Recommendation:** Sub-issue #1 (doc fix) is a quick win — ship immediately. Sub-issues #2–#5 go into the post-Wave-1 queue, likely alongside SubSquads work where parallel execution becomes a hard requirement. + +## Top 5 Priority Recommendations for v1 Progress + +1. **#508 — Ambient Personal Squad** — Wave 1 in progress, highest user-facing value +2. **#498 — Remove .squad/ from version control** — Critical for v1 GA; repos shouldn't ship team state +3. **#485 — Agent Spec & Validation Framework** — Foundation for quality gates and onboarding +4. **#481 — Typed StorageProvider Interface** — SDK maturity; unblocks #498 +5. **#347 — Shore up squad init --sdk** — Onboarding gate; first impression for SDK users + +**Quick wins:** #525 sub-issue #1 (doc fix), #347 (scoped CLI work). +**Deprioritize:** Manual verification issues (#418–#421) are test debt, not v1-blocking. Long-term exploratory items (#357, #316, #308, #296, #260, #252) stay backlog. +**Shelved (unchanged):** A2A suite (#332–#336) per existing team decision. + +--- + +# Proposal: Economy Mode Integration in squad.agent.md + +**By:** Procedures (Prompt Engineer) +**Date:** 2026-03-22 +**Issues:** #500 +**Status:** DRAFT — for Flight review before merging to squad.agent.md + +--- + +## Summary + +Economy mode is a new session/persistent modifier that shifts Layer 3 (Task-Aware Auto-Selection) to cost-optimized alternatives. This proposal documents the governance additions needed in `squad.agent.md`. + +**Note to Flight:** Procedures owns the skill design. Squad.agent.md is governance — Flight reviews before commit. + +--- + +## 1. New Paragraph After Layer 0 (Per-Agent Model Selection section) + +Insert after the existing Layer 0 bullet points and before "**Layer 1 — Session Directive**": + +--- + +**Economy Mode — Cost Modifier (Layer 3 override):** Economy mode shifts all Layer 3 auto-selection to cost-optimized alternatives. It does NOT override Layer 0 (persistent config), Layer 1 (explicit session directive), or Layer 2 (charter preference) — user intent always wins. + +- **Activation (session):** User says "use economy mode", "save costs", "go cheap" → activate for this session only. +- **Activation (persistent):** User says "always use economy mode" OR `"economyMode": true` in `.squad/config.json` → persists across sessions. +- **Deactivation:** "turn off economy mode" or remove `economyMode` from `config.json`. +- **On session start:** Read `.squad/config.json`. If `economyMode: true`, activate economy mode before any spawns. + +--- + +## 2. Economy Model Selection Table + +Add after Layer 3 normal table: + +--- + +**Economy Mode Layer 3 Table** (active when economy mode is on): + +| Task Output | Normal Mode | Economy Mode | +|-------------|-------------|--------------| +| Writing code (implementation, refactoring, bug fixes) | `claude-sonnet-4.5` | `gpt-4.1` or `gpt-5-mini` | +| Writing prompts or agent designs | `claude-sonnet-4.5` | `gpt-4.1` or `gpt-5-mini` | +| Docs, planning, triage, changelogs, mechanical ops | `claude-haiku-4.5` | `gpt-4.1` or `gpt-5-mini` | +| Architecture, code review, security audits | `claude-opus-4.5` | `claude-sonnet-4.5` | +| Scribe / logger / mechanical file ops | `claude-haiku-4.5` | `gpt-4.1` | + +Prefer `gpt-4.1` over `gpt-5-mini` for structured output or tool use. Prefer `gpt-5-mini` for pure text generation. + +--- + +## 3. Spawn Acknowledgment Convention + +Add to the spawn acknowledgment format guidance: + +--- + +When economy mode is active, include `💰 economy` after the model name in spawn acknowledgments: + +``` +🔧 Fenster (gpt-4.1 · 💰 economy) — fixing auth bug +📋 Scribe (gpt-4.1 · 💰 economy) — logging decision +``` + +This gives the user instant visibility that cost-optimized models are in use. + +--- + +## 4. Valid Models Catalog Audit + +Current "Valid models" section lists: + +``` +Premium: claude-opus-4.6, claude-opus-4.6-fast, claude-opus-4.5 +Standard: claude-sonnet-4.5, claude-sonnet-4, gpt-5.2-codex, gpt-5.2, gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1, gpt-5, gemini-3-pro-preview +Fast/Cheap: claude-haiku-4.5, gpt-5.1-codex-mini, gpt-5-mini, gpt-4.1 +``` + +**Audit findings:** +- `claude-opus-4.6` and `claude-opus-4.6-fast` are listed but not used in the Layer 3 table (table uses `claude-opus-4.5`). The Layer 3 table should reference `claude-opus-4.6` as the premium default for consistency with the catalog. +- `claude-sonnet-4.6` appears in the model-selection SKILL.md but is absent from the valid models list in squad.agent.md. Add it under Standard. +- Economy mode introduces `gpt-4.1` and `gpt-5-mini` as primary alternatives — both are already in the Fast/Cheap catalog. No additions needed. + +**Proposed updated catalog:** + +``` +Premium: claude-opus-4.6, claude-opus-4.6-fast, claude-opus-4.5 +Standard: claude-sonnet-4.6, claude-sonnet-4.5, claude-sonnet-4, gpt-5.4, gpt-5.3-codex, gpt-5.2-codex, gpt-5.2, gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1, gpt-5, gemini-3-pro-preview +Fast/Cheap: claude-haiku-4.5, gpt-5.1-codex-mini, gpt-5-mini, gpt-4.1 +``` + +(Added `claude-sonnet-4.6`, `gpt-5.4`, `gpt-5.3-codex` which appear in the model-selection SKILL.md fallback chains but are missing from squad.agent.md's catalog.) + +--- + +## 5. Config Schema Addition + +Add `economyMode` to the config schema reference in squad.agent.md (wherever `defaultModel` is documented): + +```json +{ + "version": 1, + "defaultModel": "claude-sonnet-4.6", + "economyMode": true, + "agentModelOverrides": { + "fenster": "claude-sonnet-4.6" + } +} +``` + +--- + +## Rationale + +Economy mode solves a real user need: "I want all agents to run cheaper, but I don't want to set each one individually." It's a session-level modifier that works orthogonally to the existing hierarchy — no layer gets changed, only Layer 3's lookup table swaps. The `💰` indicator keeps it transparent. + +The skill (`economy-mode/SKILL.md`) covers the coordinator behavior in detail. This proposal is the governance side — ensuring squad.agent.md is the authoritative source for the feature. + +--- + +## References + +- Skill: `.squad/skills/economy-mode/SKILL.md` +- Issue: #500 +- Model selection skill: `.squad/skills/model-selection/SKILL.md` + +--- + +# Proposal: Personal Squad Governance Awareness in squad.agent.md + +**By:** Procedures (Prompt Engineer) +**Date:** 2026-03-22 +**Issues:** #344 +**Status:** DRAFT — for Flight review before merging to squad.agent.md + +--- + +## Summary + +Squad has a consult mode (implemented, per `prd-consult-mode.md`) and personal squad semantics (via `resolveGlobalSquadPath()`), but `squad.agent.md` doesn't tell the coordinator how to reason about either. This proposal documents the gaps and the governance additions needed. + +--- + +## Gap Analysis + +### Gap 1: Init Mode references `--global` without explaining personal squad resolution + +Current Init Mode says "run `squad init --global` for a personal squad" (implied by CLI docs) but squad.agent.md doesn't explain what a personal squad IS or how the coordinator should detect it. + +**What agents need to know:** +- Personal squad = a squad at the global path (resolved via `resolveGlobalSquadPath()`) + - Linux/macOS: `~/.config/squad/.squad` + - macOS (alt): `~/Library/Application Support/squad/.squad` + - Windows: `%APPDATA%\squad\.squad` +- If `.squad/config.json` contains `"consult": true`, the coordinator is working inside a consult session +- `sourceSquad` in `config.json` points to the original personal squad (for Scribe extraction context) + +### Gap 2: No coordinator guidance for consult mode + +`squad.agent.md` mentions nothing about consult mode. The coordinator doesn't know: +- How to recognize it's in a consult session +- That writes go to the project `.squad/` (isolated copy) — NOT the personal squad +- That Scribe's charter is patched with extraction instructions +- That `.squad/extract/` is a staging area for generic learnings + +### Gap 3: TEAM_ROOT works, but personal squad semantics are absent + +The coordinator resolves `TEAM_ROOT` correctly (Worktree Awareness section), but: +- No distinction between "project squad" vs "personal squad copy in consult mode" +- No guidance on what to tell agents about their squad context when in consult mode + +### Gap 4: Charter templates have no personal-squad-aware patterns + +Agent charters have no concept of: +- Consult mode restrictions (agents shouldn't commit to project, shouldn't pollute personal squad) +- Extraction tagging (Scribe needs to flag decisions as generic vs project-specific) + +### Gap 5: No skill for consult-mode behavior + +There is no skill for consult-mode coordinator behavior, even though consult mode has distinct patterns (invisibility, extraction, isolation). + +--- + +## Proposed squad.agent.md Additions + +### Addition 1: Consult Mode Detection (in Team Mode → On Session Start) + +After "resolve the team root" and before Issue Awareness, add: + +--- + +**Consult Mode Detection:** After resolving team root, check `.squad/config.json` for `"consult": true`. + +- If `consult: true` → **Consult mode is active.** This is a personal squad consulting on a project. + - The `.squad/` directory is an isolated copy of the user's personal squad. + - `sourceSquad` in `config.json` contains the path to the original personal squad. + - Do NOT read or write to `sourceSquad` — it's out of scope. Only operate within TEAM_ROOT. + - Scribe's charter is already patched with extraction instructions — no coordinator action needed. + - Include `🧳 consult` in your session acknowledgment: `Squad v{version} (🧳 consult — {projectName})` + - Remind agents: decisions they make here are project-isolated until explicitly extracted. +- If `consult: false` or absent → Normal mode. Team root is authoritative. + +--- + +### Addition 2: Personal Squad Path Reference + +Add a new subsection under "Worktree Awareness": + +--- + +**Personal Squad Paths:** The global squad path is resolved by `resolveGlobalSquadPath()`: + +| Platform | Path | +|----------|------| +| Linux | `~/.config/squad/.squad` | +| macOS | `~/Library/Application Support/squad/.squad` | +| Windows | `%APPDATA%\squad\.squad` | + +The coordinator should NEVER hard-code these paths. Use `squad --global` or `resolveGlobalSquadPath()` to resolve. Only relevant in consult mode (to understand the `sourceSquad` field) — the coordinator does NOT read the personal squad directly during a session. + +--- + +### Addition 3: Consult Mode Spawn Guidance + +Add to the spawn template section: + +--- + +**In consult mode:** Pass `CONSULT_MODE: true` and `PROJECT_NAME: {projectName}` in spawn prompts alongside `TEAM_ROOT`. This lets agents know: +1. Their decisions will be reviewed for extraction — keep project-specific and generic reasoning separate +2. They should NOT reference personal squad paths or personal squad agent names +3. Scribe will classify their decisions — agents should write clear, extractable decision rationale + +--- + +### Addition 4: Consult Mode Acknowledgment Format + +Add to spawn acknowledgment conventions: + +``` +🧳 consult mode active — Fenster (claude-sonnet-4.5) — refactoring auth module + ↳ decisions staged in .squad/extract/ for review before extraction +``` + +--- + +## Proposed New Skill + +**Skill needed:** `.squad/skills/consult-mode/SKILL.md` + +Should cover: +- Detecting consult mode from config.json +- Coordinator behavior changes (CONSULT_MODE in spawn prompts) +- Scribe extraction workflow (already documented in prd-consult-mode.md — condense into skill) +- Acknowledgment format conventions +- STOP: extraction is always user-driven via `squad extract` — coordinator never auto-extracts + +This skill should be authored after this governance proposal is approved, to avoid the skill getting ahead of the governance. + +--- + +## Charter Template Additions + +All agent charter templates should include a note in "How I Work": + +```markdown +**Consult Mode Awareness:** If `CONSULT_MODE: true` is in my spawn prompt, I'm working on a project outside my home squad. My decisions here are project-isolated. Write extractable rationale so Scribe can classify them for `squad extract` review. +``` + +This should be added to `.squad/templates/charter.md` (if it exists) and `.squad/agents/scribe/charter.md` (Scribe already has extraction logic, but clarifying the classification responsibility is valuable). + +--- + +## Rationale + +Consult mode is fully implemented at the SDK level (`prd-consult-mode.md`, `squad consult` command) but the coordinator has no awareness of it. The result: agents running in a consult session have no context that they're in a temporary, isolated copy of a personal squad. They might make decisions as if they're permanent, or reference the project in ways that pollute the personal squad on extraction. + +These governance additions close the loop between the implementation (CLI + SDK) and the runtime behavior (coordinator + agents). + +--- + +## References + +- Consult mode PRD: `.squad/identity/prd-consult-mode.md` +- Issue: #344 +- Flight ambient personal squad note: `.squad/decisions/inbox/flight-ambient-personal-squad.md` + diff --git a/.squad/decisions/inbox/eecom-economy-mode.md b/.squad/decisions/inbox/eecom-economy-mode.md deleted file mode 100644 index d534aa5d6..000000000 --- a/.squad/decisions/inbox/eecom-economy-mode.md +++ /dev/null @@ -1,37 +0,0 @@ -# Economy Mode Design — #500 - -**Date:** 2026-03-20 -**Author:** EECOM -**Issue:** #500 - -## Decision - -Economy mode is implemented as a modifier that shifts model selection at Layer 3 (task-aware auto) and Layer 4 (default fallback) only. Layers 0–2 (explicit user preferences) are never downgraded. - -## Model Map - -| Normal | Economy | Use case | -|--------|---------|----------| -| `claude-opus-4.6` | `claude-sonnet-4.5` | Architecture, review | -| `claude-sonnet-4.6` | `gpt-4.1` | Code writing | -| `claude-sonnet-4.5` | `gpt-4.1` | Code writing | -| `claude-haiku-4.5` | `gpt-4.1` | Docs, planning, mechanical | - -## Activation - -1. **Persistent:** `"economyMode": true` in `.squad/config.json` (survives sessions) -2. **Session:** `--economy` CLI flag (sets `SQUAD_ECONOMY_MODE=1` env var, current session only) -3. **Toggle command:** `squad economy on|off` writes to config.json - -## Hierarchy Integration - -Economy mode is a Layer 3/4 modifier — it does NOT override explicit preferences (Layers 0–2). This is intentional: if a user said "always use opus", economy mode respects that choice. - -## Implementation Points - -- `ECONOMY_MODEL_MAP` + `applyEconomyMode()` in `packages/squad-sdk/src/config/models.ts` -- `readEconomyMode()` + `writeEconomyMode()` in `packages/squad-sdk/src/config/models.ts` -- `resolveModel()` in `config/models.ts` accepts `economyMode?: boolean` option; reads from config if not provided -- `resolveModel()` in `agents/model-selector.ts` also supports `economyMode?: boolean` -- `squad economy [on|off]` command in `packages/squad-cli/src/cli/commands/economy.ts` -- `--economy` global flag in `cli-entry.ts` diff --git a/.squad/decisions/inbox/procedures-economy-mode-governance.md b/.squad/decisions/inbox/procedures-economy-mode-governance.md deleted file mode 100644 index 4561be940..000000000 --- a/.squad/decisions/inbox/procedures-economy-mode-governance.md +++ /dev/null @@ -1,126 +0,0 @@ -# Proposal: Economy Mode Integration in squad.agent.md - -**By:** Procedures (Prompt Engineer) -**Date:** 2026-03-22 -**Issues:** #500 -**Status:** DRAFT — for Flight review before merging to squad.agent.md - ---- - -## Summary - -Economy mode is a new session/persistent modifier that shifts Layer 3 (Task-Aware Auto-Selection) to cost-optimized alternatives. This proposal documents the governance additions needed in `squad.agent.md`. - -**Note to Flight:** Procedures owns the skill design. Squad.agent.md is governance — Flight reviews before commit. - ---- - -## 1. New Paragraph After Layer 0 (Per-Agent Model Selection section) - -Insert after the existing Layer 0 bullet points and before "**Layer 1 — Session Directive**": - ---- - -**Economy Mode — Cost Modifier (Layer 3 override):** Economy mode shifts all Layer 3 auto-selection to cost-optimized alternatives. It does NOT override Layer 0 (persistent config), Layer 1 (explicit session directive), or Layer 2 (charter preference) — user intent always wins. - -- **Activation (session):** User says "use economy mode", "save costs", "go cheap" → activate for this session only. -- **Activation (persistent):** User says "always use economy mode" OR `"economyMode": true` in `.squad/config.json` → persists across sessions. -- **Deactivation:** "turn off economy mode" or remove `economyMode` from `config.json`. -- **On session start:** Read `.squad/config.json`. If `economyMode: true`, activate economy mode before any spawns. - ---- - -## 2. Economy Model Selection Table - -Add after Layer 3 normal table: - ---- - -**Economy Mode Layer 3 Table** (active when economy mode is on): - -| Task Output | Normal Mode | Economy Mode | -|-------------|-------------|--------------| -| Writing code (implementation, refactoring, bug fixes) | `claude-sonnet-4.5` | `gpt-4.1` or `gpt-5-mini` | -| Writing prompts or agent designs | `claude-sonnet-4.5` | `gpt-4.1` or `gpt-5-mini` | -| Docs, planning, triage, changelogs, mechanical ops | `claude-haiku-4.5` | `gpt-4.1` or `gpt-5-mini` | -| Architecture, code review, security audits | `claude-opus-4.5` | `claude-sonnet-4.5` | -| Scribe / logger / mechanical file ops | `claude-haiku-4.5` | `gpt-4.1` | - -Prefer `gpt-4.1` over `gpt-5-mini` for structured output or tool use. Prefer `gpt-5-mini` for pure text generation. - ---- - -## 3. Spawn Acknowledgment Convention - -Add to the spawn acknowledgment format guidance: - ---- - -When economy mode is active, include `💰 economy` after the model name in spawn acknowledgments: - -``` -🔧 Fenster (gpt-4.1 · 💰 economy) — fixing auth bug -📋 Scribe (gpt-4.1 · 💰 economy) — logging decision -``` - -This gives the user instant visibility that cost-optimized models are in use. - ---- - -## 4. Valid Models Catalog Audit - -Current "Valid models" section lists: - -``` -Premium: claude-opus-4.6, claude-opus-4.6-fast, claude-opus-4.5 -Standard: claude-sonnet-4.5, claude-sonnet-4, gpt-5.2-codex, gpt-5.2, gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1, gpt-5, gemini-3-pro-preview -Fast/Cheap: claude-haiku-4.5, gpt-5.1-codex-mini, gpt-5-mini, gpt-4.1 -``` - -**Audit findings:** -- `claude-opus-4.6` and `claude-opus-4.6-fast` are listed but not used in the Layer 3 table (table uses `claude-opus-4.5`). The Layer 3 table should reference `claude-opus-4.6` as the premium default for consistency with the catalog. -- `claude-sonnet-4.6` appears in the model-selection SKILL.md but is absent from the valid models list in squad.agent.md. Add it under Standard. -- Economy mode introduces `gpt-4.1` and `gpt-5-mini` as primary alternatives — both are already in the Fast/Cheap catalog. No additions needed. - -**Proposed updated catalog:** - -``` -Premium: claude-opus-4.6, claude-opus-4.6-fast, claude-opus-4.5 -Standard: claude-sonnet-4.6, claude-sonnet-4.5, claude-sonnet-4, gpt-5.4, gpt-5.3-codex, gpt-5.2-codex, gpt-5.2, gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1, gpt-5, gemini-3-pro-preview -Fast/Cheap: claude-haiku-4.5, gpt-5.1-codex-mini, gpt-5-mini, gpt-4.1 -``` - -(Added `claude-sonnet-4.6`, `gpt-5.4`, `gpt-5.3-codex` which appear in the model-selection SKILL.md fallback chains but are missing from squad.agent.md's catalog.) - ---- - -## 5. Config Schema Addition - -Add `economyMode` to the config schema reference in squad.agent.md (wherever `defaultModel` is documented): - -```json -{ - "version": 1, - "defaultModel": "claude-sonnet-4.6", - "economyMode": true, - "agentModelOverrides": { - "fenster": "claude-sonnet-4.6" - } -} -``` - ---- - -## Rationale - -Economy mode solves a real user need: "I want all agents to run cheaper, but I don't want to set each one individually." It's a session-level modifier that works orthogonally to the existing hierarchy — no layer gets changed, only Layer 3's lookup table swaps. The `💰` indicator keeps it transparent. - -The skill (`economy-mode/SKILL.md`) covers the coordinator behavior in detail. This proposal is the governance side — ensuring squad.agent.md is the authoritative source for the feature. - ---- - -## References - -- Skill: `.squad/skills/economy-mode/SKILL.md` -- Issue: #500 -- Model selection skill: `.squad/skills/model-selection/SKILL.md` diff --git a/.squad/decisions/inbox/procedures-personal-squad-governance.md b/.squad/decisions/inbox/procedures-personal-squad-governance.md deleted file mode 100644 index b46bb17de..000000000 --- a/.squad/decisions/inbox/procedures-personal-squad-governance.md +++ /dev/null @@ -1,158 +0,0 @@ -# Proposal: Personal Squad Governance Awareness in squad.agent.md - -**By:** Procedures (Prompt Engineer) -**Date:** 2026-03-22 -**Issues:** #344 -**Status:** DRAFT — for Flight review before merging to squad.agent.md - ---- - -## Summary - -Squad has a consult mode (implemented, per `prd-consult-mode.md`) and personal squad semantics (via `resolveGlobalSquadPath()`), but `squad.agent.md` doesn't tell the coordinator how to reason about either. This proposal documents the gaps and the governance additions needed. - ---- - -## Gap Analysis - -### Gap 1: Init Mode references `--global` without explaining personal squad resolution - -Current Init Mode says "run `squad init --global` for a personal squad" (implied by CLI docs) but squad.agent.md doesn't explain what a personal squad IS or how the coordinator should detect it. - -**What agents need to know:** -- Personal squad = a squad at the global path (resolved via `resolveGlobalSquadPath()`) - - Linux/macOS: `~/.config/squad/.squad` - - macOS (alt): `~/Library/Application Support/squad/.squad` - - Windows: `%APPDATA%\squad\.squad` -- If `.squad/config.json` contains `"consult": true`, the coordinator is working inside a consult session -- `sourceSquad` in `config.json` points to the original personal squad (for Scribe extraction context) - -### Gap 2: No coordinator guidance for consult mode - -`squad.agent.md` mentions nothing about consult mode. The coordinator doesn't know: -- How to recognize it's in a consult session -- That writes go to the project `.squad/` (isolated copy) — NOT the personal squad -- That Scribe's charter is patched with extraction instructions -- That `.squad/extract/` is a staging area for generic learnings - -### Gap 3: TEAM_ROOT works, but personal squad semantics are absent - -The coordinator resolves `TEAM_ROOT` correctly (Worktree Awareness section), but: -- No distinction between "project squad" vs "personal squad copy in consult mode" -- No guidance on what to tell agents about their squad context when in consult mode - -### Gap 4: Charter templates have no personal-squad-aware patterns - -Agent charters have no concept of: -- Consult mode restrictions (agents shouldn't commit to project, shouldn't pollute personal squad) -- Extraction tagging (Scribe needs to flag decisions as generic vs project-specific) - -### Gap 5: No skill for consult-mode behavior - -There is no skill for consult-mode coordinator behavior, even though consult mode has distinct patterns (invisibility, extraction, isolation). - ---- - -## Proposed squad.agent.md Additions - -### Addition 1: Consult Mode Detection (in Team Mode → On Session Start) - -After "resolve the team root" and before Issue Awareness, add: - ---- - -**Consult Mode Detection:** After resolving team root, check `.squad/config.json` for `"consult": true`. - -- If `consult: true` → **Consult mode is active.** This is a personal squad consulting on a project. - - The `.squad/` directory is an isolated copy of the user's personal squad. - - `sourceSquad` in `config.json` contains the path to the original personal squad. - - Do NOT read or write to `sourceSquad` — it's out of scope. Only operate within TEAM_ROOT. - - Scribe's charter is already patched with extraction instructions — no coordinator action needed. - - Include `🧳 consult` in your session acknowledgment: `Squad v{version} (🧳 consult — {projectName})` - - Remind agents: decisions they make here are project-isolated until explicitly extracted. -- If `consult: false` or absent → Normal mode. Team root is authoritative. - ---- - -### Addition 2: Personal Squad Path Reference - -Add a new subsection under "Worktree Awareness": - ---- - -**Personal Squad Paths:** The global squad path is resolved by `resolveGlobalSquadPath()`: - -| Platform | Path | -|----------|------| -| Linux | `~/.config/squad/.squad` | -| macOS | `~/Library/Application Support/squad/.squad` | -| Windows | `%APPDATA%\squad\.squad` | - -The coordinator should NEVER hard-code these paths. Use `squad --global` or `resolveGlobalSquadPath()` to resolve. Only relevant in consult mode (to understand the `sourceSquad` field) — the coordinator does NOT read the personal squad directly during a session. - ---- - -### Addition 3: Consult Mode Spawn Guidance - -Add to the spawn template section: - ---- - -**In consult mode:** Pass `CONSULT_MODE: true` and `PROJECT_NAME: {projectName}` in spawn prompts alongside `TEAM_ROOT`. This lets agents know: -1. Their decisions will be reviewed for extraction — keep project-specific and generic reasoning separate -2. They should NOT reference personal squad paths or personal squad agent names -3. Scribe will classify their decisions — agents should write clear, extractable decision rationale - ---- - -### Addition 4: Consult Mode Acknowledgment Format - -Add to spawn acknowledgment conventions: - -``` -🧳 consult mode active — Fenster (claude-sonnet-4.5) — refactoring auth module - ↳ decisions staged in .squad/extract/ for review before extraction -``` - ---- - -## Proposed New Skill - -**Skill needed:** `.squad/skills/consult-mode/SKILL.md` - -Should cover: -- Detecting consult mode from config.json -- Coordinator behavior changes (CONSULT_MODE in spawn prompts) -- Scribe extraction workflow (already documented in prd-consult-mode.md — condense into skill) -- Acknowledgment format conventions -- STOP: extraction is always user-driven via `squad extract` — coordinator never auto-extracts - -This skill should be authored after this governance proposal is approved, to avoid the skill getting ahead of the governance. - ---- - -## Charter Template Additions - -All agent charter templates should include a note in "How I Work": - -```markdown -**Consult Mode Awareness:** If `CONSULT_MODE: true` is in my spawn prompt, I'm working on a project outside my home squad. My decisions here are project-isolated. Write extractable rationale so Scribe can classify them for `squad extract` review. -``` - -This should be added to `.squad/templates/charter.md` (if it exists) and `.squad/agents/scribe/charter.md` (Scribe already has extraction logic, but clarifying the classification responsibility is valuable). - ---- - -## Rationale - -Consult mode is fully implemented at the SDK level (`prd-consult-mode.md`, `squad consult` command) but the coordinator has no awareness of it. The result: agents running in a consult session have no context that they're in a temporary, isolated copy of a personal squad. They might make decisions as if they're permanent, or reference the project in ways that pollute the personal squad on extraction. - -These governance additions close the loop between the implementation (CLI + SDK) and the runtime behavior (coordinator + agents). - ---- - -## References - -- Consult mode PRD: `.squad/identity/prd-consult-mode.md` -- Issue: #344 -- Flight ambient personal squad note: `.squad/decisions/inbox/flight-ambient-personal-squad.md` From 3744d5063dddb1a2ce6bec240cf3f8e2330c9c17 Mon Sep 17 00:00:00 2001 From: bradygaster Date: Sun, 22 Mar 2026 16:12:03 -0700 Subject: [PATCH 2/2] chore(.squad): merge decisions, log #508/#525 fan-out --- .squad/decisions.md | 3 + .../inbox/flight-worktree-heuristic.md | 331 ++++++++++++++++++ .squad/orchestration-log/2026-03-22T23-10.md | 1 + 3 files changed, 335 insertions(+) create mode 100644 .squad/decisions/inbox/flight-worktree-heuristic.md create mode 100644 .squad/orchestration-log/2026-03-22T23-10.md diff --git a/.squad/decisions.md b/.squad/decisions.md index 0e0469546..21dc404e0 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -6624,3 +6624,6 @@ These governance additions close the loop between the implementation (CLI + SDK) - Issue: #344 - Flight ambient personal squad note: `.squad/decisions/inbox/flight-ambient-personal-squad.md` + + + diff --git a/.squad/decisions/inbox/flight-worktree-heuristic.md b/.squad/decisions/inbox/flight-worktree-heuristic.md new file mode 100644 index 000000000..7581c9599 --- /dev/null +++ b/.squad/decisions/inbox/flight-worktree-heuristic.md @@ -0,0 +1,331 @@ +### 2026-03-10T18:00Z: Architecture Decision — Worktree vs Checkout Heuristic +**By:** Flight (Lead / Architect) +**Status:** Approved +**Issue:** #531 (parent: #525) + +#### Decision + +Squad will support **opt-in worktree mode** for parallel agent work. The default behavior remains `git checkout -b` (backward compatible with existing workflows). When worktrees are enabled via configuration, all agent spawns use `git worktree add` instead. + +**Core principle:** Worktrees are strictly better for parallel work (no working directory conflicts, true isolation), but they require environment setup (dependency management, path conventions). Making this opt-in gives teams control over when to adopt. + +**Decision logic:** +- **Default (worktrees disabled):** All agents use `git checkout -b` — existing behavior +- **Worktrees enabled:** All agents use `git worktree add` — new parallel-safe behavior +- **No heuristic:** The decision is configuration-driven, not situation-driven. Heuristics (parallel spawn detection) are brittle and surprising. + +#### Configuration + +**Primary location:** `squad.config.ts` (team config) + +```typescript +import { defineTeam } from '@bradygaster/squad-sdk'; + +export default defineTeam({ + name: 'My Squad', + worktrees: true, // Enable worktree mode + // ... rest of team config +}); +``` + +**Fallback location:** `.squad/config.json` (for repos without TypeScript config) + +```json +{ + "name": "My Squad", + "worktrees": true +} +``` + +**Environment override:** `SQUAD_WORKTREES` (highest precedence) + +```bash +# Enable for a single session +SQUAD_WORKTREES=1 gh copilot "Flight, refactor the auth module" + +# Disable even when config says true +SQUAD_WORKTREES=0 gh copilot "Ralph, triage issues" +``` + +**Precedence order (highest to lowest):** +1. `SQUAD_WORKTREES` env var (`1` or `0`) +2. `worktrees` in `squad.config.ts` +3. `worktrees` in `.squad/config.json` +4. **Default: `false`** (backward compatible) + +#### Worktree Path Convention + +**Pattern:** `{repo-parent}/{repo-name}-{issue-number}` + +**Example:** +- Main repo: `C:\src\squad` +- Issue #42 worktree: `C:\src\squad-42` +- Issue #128 worktree: `C:\src\squad-128` + +**Rationale:** +- **Sibling directory requirement:** Git worktrees must be outside the main repo (git limitation). Sibling directories are discoverable and predictable. +- **Issue number scoping:** One worktree per issue. Multiple agents on the same issue work in the same worktree. +- **No random suffixes:** Predictable paths simplify debugging and manual intervention. + +**Configurable via `worktreePath` pattern** (optional): + +```typescript +export default defineTeam({ + worktrees: true, + worktreePath: '{repo-parent}/{repo-name}-squad-{issue}', +}); +``` + +Placeholders: +- `{repo-parent}` — parent directory of the main repo +- `{repo-name}` — name of the main repo (last segment of the path) +- `{issue}` — issue number +- `{branch}` — branch name (e.g., `squad/42-fix-auth`) + +Default pattern if not specified: `{repo-parent}/{repo-name}-{issue}` + +#### Dependency Management + +**Problem:** Each worktree is a separate working directory. Dependencies (`node_modules`, `venv`, etc.) need to be available in each worktree. + +**Recommended strategy:** Junction/symlink from main repo + +On worktree creation, create a junction (Windows) or symlink (Unix) from the worktree's `node_modules` to the main repo's `node_modules`: + +```bash +# Windows (no admin required) +mklink /J C:\src\squad-42\node_modules C:\src\squad\node_modules + +# Unix +ln -s ../squad/node_modules ./node_modules +``` + +**Fallback strategy:** `npm install` in the worktree + +If junction/symlink creation fails (permissions, filesystem limitations), fall back to running `npm install` in the worktree. This is slower and uses more disk space, but always works. + +**Detection:** Check for `package.json` in the repo root. If it exists, dependency management is required. + +**Other ecosystems:** +- **Python:** Junction/symlink `.venv` or `venv` from main repo +- **Rust:** Cargo shares `target/` automatically via `CARGO_TARGET_DIR` pointing to main repo +- **Go:** `go.mod` works out of the box (modules are path-independent) + +**Coordinator responsibility:** After `git worktree add`, attempt junction/symlink. On failure, run the install command (`npm install`, `pip install -r requirements.txt`, etc.) in the worktree. + +#### Platform Considerations + +**All 3 platform adapters (GitHub, Azure DevOps, Planner) get identical worktree support:** + +- **Worktree creation:** `git worktree add {path} -b {branch} {base}` +- **Worktree cleanup:** `git worktree remove {path} && git worktree prune` +- **Branch switching (worktrees disabled):** `git checkout -b {branch}` (existing) + +**Windows-specific:** +- Use `mklink /J` (junction) for dependency linking — no admin rights required +- Junctions work on all NTFS/ReFS filesystems +- If mklink fails, fall back to `npm install` (or equivalent) + +**Unix-specific:** +- Use `ln -s` (symlink) for dependency linking +- Symlinks require no special permissions +- If ln fails, fall back to dependency install + +**CI/containers:** +- Worktrees may not be appropriate in ephemeral environments (CI runners, containers) where parallel work doesn't apply +- Default to `worktrees: false` unless explicitly enabled +- Document this constraint in the worktrees feature guide + +#### Migration Path + +**Existing users (worktrees disabled by default):** +- No breaking changes. All existing workflows continue to use `git checkout -b`. +- Teams can opt-in by adding `worktrees: true` to their config when ready. + +**New teams:** +- Documentation can recommend worktrees for teams expecting parallel work. +- The init flow could ask: *"Will your team work on multiple issues in parallel? (enables worktrees)"* +- Still defaults to `false` — user must confirm. + +**Worktree adoption checklist** (for documentation): +1. ✅ Verify your filesystem supports junctions/symlinks (most modern filesystems do) +2. ✅ Add `worktrees: true` to `squad.config.ts` or `.squad/config.json` +3. ✅ Test with a single agent spawn: `"Flight, create issue #42 branch"` +4. ✅ Verify worktree was created in `{repo-parent}/{repo-name}-{issue}` +5. ✅ Verify dependencies are available (junction created or install ran) +6. ✅ Once confirmed, scale to parallel agent work + +#### Implementation Strategy for #528, #529, #530 + +**Issue #528: Worktree variant in ralph-commands.ts** + +Add worktree commands to all 3 adapters: + +```typescript +export interface RalphCommands { + // ... existing fields + createWorktree?: string; // Optional — only present when worktrees enabled + removeWorktree?: string; // Optional — cleanup after PR merge +} +``` + +**GitHub adapter (worktrees enabled):** +```typescript +createWorktree: 'git worktree add {path} -b {branch} {base}', +removeWorktree: 'git worktree remove {path} && git worktree prune', +``` + +**Azure DevOps adapter (same commands):** +```typescript +createWorktree: 'git worktree add {path} -b {branch} {base}', +removeWorktree: 'git worktree remove {path} && git worktree prune', +``` + +**Planner adapter (same commands):** +```typescript +createWorktree: 'git worktree add {path} -b {branch} {base}', +removeWorktree: 'git worktree remove {path} && git worktree prune', +``` + +**When worktrees are disabled:** `createWorktree` and `removeWorktree` are undefined. The coordinator falls back to `createBranch` (existing `git checkout -b` flow). + +**Issue #529: Coordinator pre-spawn worktree creation** + +Update `.squad-templates/squad.agent.md` spawn flow: + +1. **Read config:** Check `worktrees` flag from config (precedence: env var > squad.config.ts > .squad/config.json > default false) +2. **If worktrees enabled:** + - Resolve worktree path using the pattern from config (or default) + - Run `createWorktree` command from ralph-commands + - Attempt dependency junction/symlink (fall back to install on failure) + - Pass `WORKTREE_PATH: {path}` in spawn prompt + - Tell agent: *"You are in worktree {path} on branch {branch}. Do NOT run git checkout."* +3. **If worktrees disabled:** Use existing `git checkout -b` flow (no changes) + +**Issue #530: Post-merge worktree cleanup** + +After PR merge (detected by Ralph or coordinator): +1. Run `removeWorktree` command from ralph-commands +2. Log cleanup to `.squad/orchestration-log/` +3. If worktree removal fails (agent still has files open, etc.), log warning and defer cleanup to next idle cycle + +**Ralph integration:** Ralph's idle-watch could detect merged PRs and trigger cleanup asynchronously. + +#### Alternatives Considered + +**❌ Heuristic-based (parallel spawn detection):** +- Problem: Heuristics are brittle. What counts as "parallel"? Two agents? Three? What if one agent is short-lived? +- Result: Unpredictable behavior. Users can't reason about when worktrees will be used. + +**❌ Always-on worktrees:** +- Problem: Breaking change for existing users. Requires all environments to support junctions/symlinks and dependency management. +- Result: Poor migration path. Users without worktree-friendly environments (CI, containers) would be forced to opt-out. + +**❌ Per-agent worktree flag:** +- Problem: Configuration explosion. Each agent spawn would need a worktree decision. +- Result: Users have to think about worktrees on every spawn. Cognitive overhead. + +**✅ Opt-in configuration (chosen):** +- Benefit: Backward compatible. Users adopt when ready. Single configuration decision applies to all spawns. +- Tradeoff: Users must explicitly enable. But this is appropriate — worktrees are a team-level workflow decision. + +#### Tradeoffs + +**Worktrees enabled:** +- ✅ True parallel work — no working directory conflicts +- ✅ Multiple agents on different issues can work simultaneously +- ✅ Branch isolation — each agent has a clean working directory +- ❌ Requires dependency management (junctions or installs) +- ❌ More disk I/O (separate working directories) +- ❌ Users must understand worktree conventions (where is the worktree?) + +**Worktrees disabled (default):** +- ✅ Zero configuration — works everywhere +- ✅ Familiar git workflow (checkout branches in place) +- ✅ Shared dependencies — no junctions or extra installs +- ❌ Parallel work causes conflicts (agents clobber each other's working directory) +- ❌ Sequential work only (or manual worktree management by user) + +#### Implications for #528, #529, #530 + +**#528 (ralph-commands.ts):** +- Add `createWorktree` and `removeWorktree` commands to all 3 adapters +- Commands are optional (only present when worktrees enabled) +- No breaking changes to existing `createBranch` command + +**#529 (coordinator pre-spawn):** +- Read worktree config at session start (cache for duration of session) +- Branch on config: worktrees enabled → `createWorktree`, worktrees disabled → `createBranch` +- Pass `WORKTREE_PATH` in spawn prompt when worktrees enabled +- Handle dependency management (junction/symlink or install fallback) + +**#530 (post-merge cleanup):** +- Trigger `removeWorktree` after PR merge (via Ralph idle-watch or coordinator merge detection) +- Log cleanup to orchestration log +- Graceful failure handling (warn if removal fails, defer to next idle cycle) + +**Shared implementation detail:** +- All three issues share the worktree path resolution logic (pattern-based, configurable) +- All three issues share the config reading logic (precedence: env var > squad.config.ts > .squad/config.json > default) +- EECOM owns #528, but the config schema belongs in the SDK (shared across all components) + +#### Documentation Updates Required + +1. **`docs/src/content/docs/features/worktrees.md`:** + - Update to reflect opt-in configuration (not automatic) + - Add configuration examples (squad.config.ts, .squad/config.json, env var) + - Add dependency management section (junctions, install fallback) + - Add troubleshooting section (junction failures, disk space, cleanup) + +2. **`docs/src/content/docs/concepts/parallel-work.md`:** + - Mention worktrees as the recommended approach for parallel work + - Link to worktrees feature guide + - Clarify that worktrees are optional (default is sequential with checkout -b) + +3. **`.squad-templates/squad.agent.md`:** + - Add worktree configuration reading to session start + - Add worktree path resolution logic + - Add `WORKTREE_PATH` to spawn prompt template + - Update "Worktree Awareness" section to reflect coordinator-driven creation + +4. **`.squad/skills/git-workflow/SKILL.md` (if it exists):** + - Make worktree workflow the primary recommendation for parallel work + - Keep `git checkout -b` as the fallback (worktrees disabled) + +#### Config Schema (for SDK) + +Add to `packages/squad-sdk/src/types/config.ts`: + +```typescript +export interface TeamConfig { + name: string; + // ... existing fields + + /** Enable worktree mode for parallel agent work. Default: false */ + worktrees?: boolean; + + /** Worktree path pattern. Default: "{repo-parent}/{repo-name}-{issue}" */ + worktreePath?: string; +} +``` + +Validation: +- `worktrees` must be boolean or undefined (coerce truthy/falsy if needed) +- `worktreePath` must be a string containing at least `{issue}` or `{branch}` placeholder (ensure unique paths per agent) + +Env var override: +- `SQUAD_WORKTREES=1` → `worktrees: true` +- `SQUAD_WORKTREES=0` → `worktrees: false` +- Any other value → ignore, use config file + +#### Summary + +This decision establishes **opt-in worktrees** as the architecture for parallel agent work in Squad. The default remains `git checkout -b` (backward compatible), but teams can enable `worktrees: true` in their config for true parallel isolation. This unblocks #528 (SDK commands), #529 (coordinator spawn flow), and #530 (cleanup lifecycle) with a clear, unified design. + +**Next steps:** +1. EECOM implements #528 (add worktree commands to ralph-commands.ts) +2. Flight or EECOM implements #529 (coordinator reads config, creates worktrees before spawn) +3. Flight or EECOM implements #530 (post-merge cleanup via Ralph or coordinator) +4. PAO updates documentation (worktrees.md, parallel-work.md, squad.agent.md) + +**Decision approved by:** Flight (as architect + owner of #531) diff --git a/.squad/orchestration-log/2026-03-22T23-10.md b/.squad/orchestration-log/2026-03-22T23-10.md new file mode 100644 index 000000000..441c5f9d7 --- /dev/null +++ b/.squad/orchestration-log/2026-03-22T23-10.md @@ -0,0 +1 @@ +2026-03-22T23:10Z: Coordinator enabled worktrees, launched #508 fan-out (EECOM SDK + Procedures Governance), Flight authoring #525 sub-issues. Priority restack: #508 first, #525 sub-items replace #347, #498 parallel, hold #481/#347.