From 83d02dbb0c0f0d45448fa0658c1ec603c3a9d396 Mon Sep 17 00:00:00 2001 From: bradygaster Date: Sun, 22 Mar 2026 15:52:48 -0700 Subject: [PATCH 1/3] 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 c4b383da6832a507e3ad1cc0c92e78d020fca562 Mon Sep 17 00:00:00 2001 From: bradygaster Date: Sun, 22 Mar 2026 16:12:03 -0700 Subject: [PATCH 2/3] chore(.squad): merge decisions, log #508/#525 fan-out --- .squad/decisions.md | 3 +++ .squad/orchestration-log/2026-03-22T23-10.md | 1 + 2 files changed, 4 insertions(+) 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/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. From 521c03409f549e6e6e0328b271b6d7390c93f7f6 Mon Sep 17 00:00:00 2001 From: bradygaster Date: Sun, 22 Mar 2026 16:42:18 -0700 Subject: [PATCH 3/3] chore: audit .squad/ VCS references for removal prep (#498) Phase 1 preparation for removing .squad/ from version control: - Audit CI workflows that read .squad/ files - Audit source code references to .squad/ - Create migration document with risk assessment - Verify squad build regeneration capability Key findings: - 4 CI workflows need 'squad build' step before reading .squad/ - 54 source files reference .squad/ (all safe for build output mode) - squad build fully regenerates .squad/ from squad.config.ts - Preview/promote workflows already handle .squad/ exclusion correctly Part of #498 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../inbox/eecom-498-vcs-removal-prep.md | 250 ++++++++++++++++++ 1 file changed, 250 insertions(+) create mode 100644 .squad/decisions/inbox/eecom-498-vcs-removal-prep.md diff --git a/.squad/decisions/inbox/eecom-498-vcs-removal-prep.md b/.squad/decisions/inbox/eecom-498-vcs-removal-prep.md new file mode 100644 index 000000000..e4324835e --- /dev/null +++ b/.squad/decisions/inbox/eecom-498-vcs-removal-prep.md @@ -0,0 +1,250 @@ +### 2026-03-22T16:40:56Z: #498 Phase 1 Audit — .squad/ VCS Removal Preparation +**By:** EECOM (Core Dev) +**Status:** In Progress +**Issue:** #498 + +#### Executive Summary + +The `.squad/` directory is currently tracked in git. Since SDK mode (`squad.config.ts` + `squad build`) generates `.squad/` as build output, tracking it creates: +- **Merge conflicts** — developers working on different agents create conflicting `.squad/` changes +- **Dirty working trees** — `squad build` modifies tracked files, causing false positives in git status +- **CI noise** — workflows fail when `.squad/` is out of sync +- **Privacy concerns** — agent history, decisions, and orchestration logs contain sensitive project data + +This audit identifies all references to `.squad/` in CI workflows and source code to prepare for safe removal. + +--- + +#### CI Workflow Audit + +| Workflow | .squad/ Files Read | Status | Fix Needed | +|----------|-------------------|--------|------------| +| `sync-squad-labels.yml` | `.squad/team.md` | ⚠️ **BREAKS** | Add `squad build` step before reading team.md | +| `squad-heartbeat.yml` | `.squad/team.md`, `.squad/templates/ralph-triage.js` | ⚠️ **BREAKS** | Add `squad build` + ensure templates/ is installed | +| `squad-triage.yml` | `.squad/team.md`, `.squad/routing.md` | ⚠️ **BREAKS** | Add `squad build` before reading team.md/routing.md | +| `squad-issue-assign.yml` | `.squad/team.md` | ⚠️ **BREAKS** | Add `squad build` before reading team.md | +| `squad-preview.yml` | Validates absence of `.squad/` | ✅ **NO CHANGE** | Already checks that .squad/ is NOT tracked — works as-is | +| `squad-promote.yml` | Strips `.squad/` during merge | ✅ **NO CHANGE** | Already strips .squad/ from preview branch — works as-is | + +**Critical Dependencies:** +- All workflows that read `.squad/team.md` or `.squad/routing.md` MUST run `squad build` first +- `squad-heartbeat.yml` reads `.squad/templates/ralph-triage.js` — template installation needs verification +- Fallback to `.ai-team/` (legacy directory) is present in all workflows — remains safe after removal + +**Recommended CI Fix Pattern:** +```yaml +- uses: actions/checkout@v4 + +- uses: actions/setup-node@v4 + with: + node-version: 22 + +- name: Install dependencies + run: npm ci + +- name: Generate .squad/ from config + run: npx squad build + +# Now workflows can read .squad/team.md, .squad/routing.md, etc. +``` + +--- + +#### Source Code Audit + +**Total References:** 54 TypeScript files in `packages/` reference `.squad/` + +##### Category 1: Runtime Readers (Core Functionality) +These files read `.squad/` at runtime and MUST continue working after removal: + +| File | Purpose | Post-Removal Status | +|------|---------|-------------------| +| `packages/squad-cli/src/cli/core/detect-squad-dir.ts` | Detects `.squad/` vs `.ai-team/` | ✅ **WORKS** — reads from disk, doesn't assume git tracking | +| `packages/squad-cli/src/cli/commands/build.ts` | Generates `.squad/` from `squad.config.ts` | ✅ **WORKS** — writes to disk, main regeneration tool | +| `packages/squad-sdk/src/config/init.ts` | Creates initial `.squad/` structure | ✅ **WORKS** — writes new files, doesn't read git | +| `packages/squad-sdk/src/config/agent-source.ts` | Reads agent charters from `.squad/agents/` | ✅ **WORKS** — runtime file read, no git dependency | +| `packages/squad-sdk/src/platform/comms.ts` | Reads/writes orchestration logs | ✅ **WORKS** — runtime state, already gitignored | +| `packages/squad-sdk/src/runtime/config.ts` | Loads squad config from disk | ✅ **WORKS** — runtime loader | + +**Verdict:** ✅ All runtime readers work with `.squad/` as build output (not tracked). + +##### Category 2: Path References (Constants/Templates) +These files reference `.squad/` paths as strings (no actual file I/O): + +| File | Purpose | Post-Removal Status | +|------|---------|-------------------| +| `packages/squad-cli/src/cli/core/templates.ts` | Template manifest with `.squad/` destinations | ✅ **SAFE** — just path constants | +| `packages/squad-sdk/src/builders/index.ts` | Example code showing `.squad/agents/` paths | ✅ **SAFE** — documentation/examples | +| `packages/squad-sdk/src/upstream/types.ts` | Type definitions for `.squad/` structure | ✅ **SAFE** — types only | +| `packages/squad-sdk/src/streams/types.ts` | SubSquad `.squad/` path references | ✅ **SAFE** — path constants | + +**Verdict:** ✅ No action needed — these are path definitions, not file operations. + +##### Category 3: Test References (May Need Fixture Updates) +Test files that reference `.squad/`: + +| Pattern | Count | Post-Removal Status | +|---------|-------|-------------------| +| Test fixtures reading `.squad/` | ~10 files | ⚠️ **REVIEW** — tests may need `squad build` in setup or mock fixtures | +| Integration tests | ~5 files | ⚠️ **REVIEW** — may need to generate test `.squad/` dirs | + +**Verdict:** ⚠️ Test suite needs review — some tests may fail if they assume `.squad/` is tracked. + +--- + +#### .gitignore Audit + +**Current State:** +- `.gitignore` in THIS repo ignores specific `.squad/` subdirectories (logs, inbox, sessions) +- `.gitignore` does NOT ignore the entire `.squad/` directory +- `squad init` adds partial `.squad/` ignores to new projects (runtime state only) + +**Findings:** +1. **This repo (.gitignore):** Currently has partial ignores: + ```gitignore + .squad/orchestration-log/ + .squad/log/ + .squad/decisions/inbox/ + .squad/sessions/ + .squad/config.json + .squad-workstream + .squad/.first-run + ``` + **Phase 2 change:** Add `.squad/` to ignore the entire directory + +2. **`squad init` template (init.ts:975-1000):** + - Generates `.gitignore` entries for runtime state only (logs, inbox, sessions) + - Does NOT add `.squad/` to .gitignore for new projects + - **Phase 2 change:** Update `init.ts` to add `.squad/` entry for SDK mode projects + +**Recommended .gitignore template for NEW projects (SDK mode):** +```gitignore +# Squad: generated team structure (build output from squad.config.ts) +.squad/ + +# Squad: local machine state +.squad-workstream +``` + +**Recommended .gitignore template for NEW projects (markdown mode — no config file):** +```gitignore +# Squad: runtime state (logs, inbox, sessions) +.squad/orchestration-log/ +.squad/log/ +.squad/decisions/inbox/ +.squad/sessions/ + +# Squad: local machine state +.squad-workstream +``` + +--- + +#### `squad build` Regeneration Capability + +**Status:** ✅ **VERIFIED** — `squad build` fully regenerates `.squad/` from `squad.config.ts` + +**Generated Files:** +- `.squad/team.md` — team roster +- `.squad/routing.md` — routing rules +- `.squad/agents/{name}/charter.md` — agent charters +- `.squad/ceremonies.md` — ceremony definitions (or dispatch table if large) +- `.copilot/skills/ceremony-{slug}/SKILL.md` — individual ceremony skills (if dispatch mode) +- `.copilot/skills/{name}/SKILL.md` — custom skill definitions + +**Protected Files (NEVER overwritten by `squad build`):** +- `.squad/decisions.md` — user-owned decision log +- `.squad/decisions-archive.md` — archived decisions +- `.squad/orchestration-log/` — runtime logs (already gitignored) +- `.squad/history.md` — agent history (user-owned) + +**Gaps:** None identified. `squad build` is the authoritative regeneration tool. + +--- + +#### Risk Assessment + +**High Risk:** +1. **CI Workflows** — 4 workflows will break immediately if `.squad/` is removed without adding `squad build` steps +2. **Developer Onboarding** — new contributors must run `squad build` after checkout (could be automated with git hooks or README update) +3. **Legacy Projects** — projects using markdown-only mode (no `squad.config.ts`) cannot regenerate `.squad/` — need migration path + +**Medium Risk:** +1. **Test Suite** — some tests may fail if they assume `.squad/` is tracked (needs test run after removal) +2. **Documentation** — tutorials/examples may reference `.squad/` as tracked files + +**Low Risk:** +1. **Runtime Code** — all runtime readers work with `.squad/` as build output (no git dependency) +2. **Template Files** — path references are safe (no file I/O) + +--- + +#### Recommended Sequence for Safe Removal + +**Phase 1: Preparation (THIS PHASE)** +- ✅ Audit CI workflows and source code +- ✅ Document risks and migration plan +- ✅ Verify `squad build` regeneration capability +- ✅ Identify protected files + +**Phase 2: CI Workflow Updates** +1. Add `squad build` step to workflows that read `.squad/` files: + - `sync-squad-labels.yml` + - `squad-heartbeat.yml` + - `squad-triage.yml` + - `squad-issue-assign.yml` +2. Test workflows in a branch with `.squad/` removed +3. Verify workflows pass with generated `.squad/` files + +**Phase 3: Source Code Updates** +1. Update `init.ts` to add `.squad/` to `.gitignore` for SDK mode projects +2. Add `squad build` to `postinstall` scripts (optional — for auto-regeneration) +3. Update README/docs to mention `squad build` requirement +4. Run test suite and fix any tests that assume `.squad/` is tracked + +**Phase 4: Repository Removal** +1. Add `.squad/` to THIS repo's `.gitignore` +2. Remove `.squad/` from git: `git rm -r --cached .squad/` +3. Run `squad build` to regenerate `.squad/` +4. Commit: `git commit -m "chore: remove .squad/ from version control (#498)"` +5. Update `squad-preview.yml` validation (already checks for absence — no change needed) + +**Phase 5: Validation & Rollout** +1. Test on a feature branch with CI workflows +2. Verify all workflows pass +3. Merge to `dev` +4. Monitor for issues +5. Document in CHANGELOG as breaking change for v1.0 + +--- + +#### Open Questions + +1. **Template installation:** `squad-heartbeat.yml` reads `.squad/templates/ralph-triage.js` — is this file generated by `squad build` or installed by `squad upgrade`? + - **Action:** Verify template installation mechanism + +2. **Markdown-only mode:** Projects without `squad.config.ts` cannot run `squad build` — should we require migration to SDK mode before v1.0? + - **Action:** Define migration path in #498 Phase 2 + +3. **Git hooks:** Should we add a post-checkout hook to auto-run `squad build`? + - **Pros:** Seamless developer experience + - **Cons:** Slows down checkout, may surprise developers + - **Action:** Discuss with team in #498 + +4. **Preview branch:** `squad-preview.yml` validates absence of `.squad/` — does this need to change? + - **Answer:** ✅ No change needed — validation already checks for absence + +--- + +#### Next Steps (Phase 2) + +1. Create PRs to add `squad build` to CI workflows +2. Update `init.ts` to add `.squad/` to `.gitignore` for new SDK mode projects +3. Run test suite and fix failing tests +4. Update documentation (README, tutorials) to mention `squad build` requirement +5. Test removal in a feature branch +6. Merge to `dev` and validate all workflows pass + +**Estimated effort:** 2-3 days of work spread across multiple PRs + +**Target milestone:** v1.0 (blocking — `.squad/` must not ship in v1.0)