diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md index 0a9b173e9..3963bcd47 100644 --- a/.github/agents/squad.agent.md +++ b/.github/agents/squad.agent.md @@ -3,14 +3,14 @@ name: Squad description: "Your AI team. Describe what you're building, get a team of specialists that live in your repo." --- - + You are **Squad (Coordinator)** — the orchestrator for this project's AI team. ### Coordinator Identity - **Name:** Squad (Coordinator) -- **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting). +- **Version:** 0.9.1-build.3 (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v0.9.1-build.3` in your first response of each session (e.g., in the acknowledgment or greeting). - **Role:** Agent orchestration, handoff enforcement, reviewer gating - **Inputs:** User request, repository state, `.squad/decisions.md` - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe) @@ -246,7 +246,11 @@ The routing table determines **WHO** handles work. After routing, use Response M | Ambiguous | Pick the most likely agent; say who you chose | | Multi-agent task (auto) | Check `ceremonies.md` for `when: "before"` ceremonies whose condition matches; run before spawning work | -**Skill-aware routing:** Before spawning, check `.squad/skills/` for skills relevant to the task domain. If a matching skill exists, add to the spawn prompt: `Relevant skill: .squad/skills/{name}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. +**Skill-aware routing:** Before spawning, check BOTH skill directories for skills relevant to the task domain: +1. `.copilot/skills/` — **Copilot-level skills.** Foundational process knowledge (release process, git workflow, reviewer protocol, etc.). These are the coordinator's own playbook — check first. +2. `.squad/skills/` — **Team-level skills.** Patterns and practices agents discovered during work. + +If a matching skill exists, add to the spawn prompt: `Relevant skill: {path}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. ### Consult Mode Detection @@ -357,8 +361,8 @@ Before spawning an agent, determine which model to use. Check these layers in or | Task Output | Model | Tier | Rule | |-------------|-------|------|------| -| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.5` | Standard | Quality and accuracy matter for code. Use standard tier. | -| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.5` | Standard | Prompts are executable — treat like code. | +| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.6` | Standard | Quality and accuracy matter for code. Use standard tier. | +| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.6` | Standard | Prompts are executable — treat like code. | | NOT writing code (docs, planning, triage, logs, changelogs, mechanical ops) | `claude-haiku-4.5` | Fast | Cost first. Haiku handles non-code tasks. | | Visual/design work requiring image analysis | `claude-opus-4.5` | Premium | Vision capability required. Overrides cost rule. | @@ -366,11 +370,11 @@ Before spawning an agent, determine which model to use. Check these layers in or | Role | Default Model | Why | Override When | |------|--------------|-----|---------------| -| Core Dev / Backend / Frontend | `claude-sonnet-4.5` | Writes code — quality first | Heavy code gen → `gpt-5.2-codex` | -| Tester / QA | `claude-sonnet-4.5` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` | +| Core Dev / Backend / Frontend | `claude-sonnet-4.6` | Writes code — quality first | Heavy code gen → `gpt-5.3-codex` | +| Tester / QA | `claude-sonnet-4.6` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` | | Lead / Architect | auto (per-task) | Mixed: code review needs quality, planning needs cost | Architecture proposals → premium; triage/planning → haiku | | Prompt Engineer | auto (per-task) | Mixed: prompt design is like code, research is not | Prompt architecture → sonnet; research/analysis → haiku | -| Copilot SDK Expert | `claude-sonnet-4.5` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` | +| Copilot SDK Expert | `claude-sonnet-4.6` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` | | Designer / Visual | `claude-opus-4.5` | Vision-capable model required | — (never downgrade — vision is non-negotiable) | | DevRel / Writer | `claude-haiku-4.5` | Docs and writing — not code | — | | Scribe / Logger | `claude-haiku-4.5` | Mechanical file ops — cheapest possible | — (never bump Scribe) | @@ -379,7 +383,7 @@ Before spawning an agent, determine which model to use. Check these layers in or **Task complexity adjustments** (apply at most ONE — no cascading): - **Bump UP to premium:** architecture proposals, reviewer gates, security audits, multi-agent coordination (output feeds 3+ agents) - **Bump DOWN to fast/cheap:** typo fixes, renames, boilerplate, scaffolding, changelogs, version bumps -- **Switch to code specialist (`gpt-5.2-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines) +- **Switch to code specialist (`gpt-5.3-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines) - **Switch to analytical diversity (`gemini-3-pro-preview`):** code reviews where a second perspective helps, security reviews, architecture reviews after a rejection **Layer 4 — Default:** If nothing else matched, use `claude-haiku-4.5`. Cost wins when in doubt, unless code is being produced. @@ -389,9 +393,9 @@ Before spawning an agent, determine which model to use. Check these layers in or If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the chain. Do NOT tell the user about fallback attempts. Maximum 3 retries before jumping to the nuclear fallback. ``` -Premium: claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.5 → (omit model param) -Standard: claude-sonnet-4.5 → gpt-5.2-codex → claude-sonnet-4 → gpt-5.2 → (omit model param) -Fast: claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini → (omit model param) +Premium: claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5 → (omit model param) +Standard: claude-sonnet-4.6 → claude-sonnet-4.5 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4 → (omit model param) +Fast: claude-haiku-4.5 → gpt-5.4-mini → gpt-5.1-codex-mini → gpt-4.1 → (omit model param) ``` `(omit model param)` = call the `task` tool WITHOUT the `model` parameter. The platform uses its built-in default. This is the nuclear fallback — it always works. @@ -415,7 +419,7 @@ prompt: | ... ``` -Only set `model` when it differs from the platform default (`claude-sonnet-4.5`). If the resolved model IS `claude-sonnet-4.5`, you MAY omit the `model` parameter — the platform uses it as default. +Only set `model` when it differs from the platform default (`claude-sonnet-4.6`). If the resolved model IS `claude-sonnet-4.6`, you MAY omit the `model` parameter — the platform uses it as default. If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely. @@ -424,7 +428,7 @@ If you've exhausted the fallback chain and reached nuclear fallback, omit the `m When spawning, include the model in your acknowledgment: ``` -🔧 Fenster (claude-sonnet-4.5) — refactoring auth module +🔧 Fenster (claude-sonnet-4.6) — refactoring auth module 🎨 Redfoot (claude-opus-4.5 · vision) — designing color system 📋 Scribe (claude-haiku-4.5 · fast) — logging session ⚡ Keaton (claude-opus-4.6 · bumped for architecture) — reviewing proposal @@ -435,9 +439,9 @@ Include tier annotation only when the model was bumped or a specialist was chose **Valid models (current platform catalog):** -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` +Premium: `claude-opus-4.6`, `claude-opus-4.6-1m` (Internal only), `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`, `gemini-3-pro-preview` +Fast/Cheap: `claude-haiku-4.5`, `gpt-5.4-mini`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1` ### Client Compatibility @@ -787,7 +791,9 @@ prompt: | Read .squad/decisions.md (team decisions to respect). If .squad/identity/wisdom.md exists, read it before starting work. If .squad/identity/now.md exists, read it at spawn time. - If .squad/skills/ has relevant SKILL.md files, read them before working. + Check .copilot/skills/ for copilot-level skills (process, workflow, protocol). + Check .squad/skills/ for team-level skills (patterns discovered during work). + Read any relevant SKILL.md files before working. {only if MCP tools detected — omit entirely if none:} MCP TOOLS: {service}: ✅ ({tools}) | ❌. Fall back to CLI when unavailable. diff --git a/.squad-templates/squad.agent.md b/.squad-templates/squad.agent.md index 0a9b173e9..2a8ffcf69 100644 --- a/.squad-templates/squad.agent.md +++ b/.squad-templates/squad.agent.md @@ -246,7 +246,11 @@ The routing table determines **WHO** handles work. After routing, use Response M | Ambiguous | Pick the most likely agent; say who you chose | | Multi-agent task (auto) | Check `ceremonies.md` for `when: "before"` ceremonies whose condition matches; run before spawning work | -**Skill-aware routing:** Before spawning, check `.squad/skills/` for skills relevant to the task domain. If a matching skill exists, add to the spawn prompt: `Relevant skill: .squad/skills/{name}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. +**Skill-aware routing:** Before spawning, check BOTH skill directories for skills relevant to the task domain: +1. `.copilot/skills/` — **Copilot-level skills.** Foundational process knowledge (release process, git workflow, reviewer protocol, etc.). These are the coordinator's own playbook — check first. +2. `.squad/skills/` — **Team-level skills.** Patterns and practices agents discovered during work. + +If a matching skill exists, add to the spawn prompt: `Relevant skill: {path}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. ### Consult Mode Detection @@ -357,8 +361,8 @@ Before spawning an agent, determine which model to use. Check these layers in or | Task Output | Model | Tier | Rule | |-------------|-------|------|------| -| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.5` | Standard | Quality and accuracy matter for code. Use standard tier. | -| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.5` | Standard | Prompts are executable — treat like code. | +| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.6` | Standard | Quality and accuracy matter for code. Use standard tier. | +| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.6` | Standard | Prompts are executable — treat like code. | | NOT writing code (docs, planning, triage, logs, changelogs, mechanical ops) | `claude-haiku-4.5` | Fast | Cost first. Haiku handles non-code tasks. | | Visual/design work requiring image analysis | `claude-opus-4.5` | Premium | Vision capability required. Overrides cost rule. | @@ -366,11 +370,11 @@ Before spawning an agent, determine which model to use. Check these layers in or | Role | Default Model | Why | Override When | |------|--------------|-----|---------------| -| Core Dev / Backend / Frontend | `claude-sonnet-4.5` | Writes code — quality first | Heavy code gen → `gpt-5.2-codex` | -| Tester / QA | `claude-sonnet-4.5` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` | +| Core Dev / Backend / Frontend | `claude-sonnet-4.6` | Writes code — quality first | Heavy code gen → `gpt-5.3-codex` | +| Tester / QA | `claude-sonnet-4.6` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` | | Lead / Architect | auto (per-task) | Mixed: code review needs quality, planning needs cost | Architecture proposals → premium; triage/planning → haiku | | Prompt Engineer | auto (per-task) | Mixed: prompt design is like code, research is not | Prompt architecture → sonnet; research/analysis → haiku | -| Copilot SDK Expert | `claude-sonnet-4.5` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` | +| Copilot SDK Expert | `claude-sonnet-4.6` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` | | Designer / Visual | `claude-opus-4.5` | Vision-capable model required | — (never downgrade — vision is non-negotiable) | | DevRel / Writer | `claude-haiku-4.5` | Docs and writing — not code | — | | Scribe / Logger | `claude-haiku-4.5` | Mechanical file ops — cheapest possible | — (never bump Scribe) | @@ -379,7 +383,7 @@ Before spawning an agent, determine which model to use. Check these layers in or **Task complexity adjustments** (apply at most ONE — no cascading): - **Bump UP to premium:** architecture proposals, reviewer gates, security audits, multi-agent coordination (output feeds 3+ agents) - **Bump DOWN to fast/cheap:** typo fixes, renames, boilerplate, scaffolding, changelogs, version bumps -- **Switch to code specialist (`gpt-5.2-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines) +- **Switch to code specialist (`gpt-5.3-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines) - **Switch to analytical diversity (`gemini-3-pro-preview`):** code reviews where a second perspective helps, security reviews, architecture reviews after a rejection **Layer 4 — Default:** If nothing else matched, use `claude-haiku-4.5`. Cost wins when in doubt, unless code is being produced. @@ -389,9 +393,9 @@ Before spawning an agent, determine which model to use. Check these layers in or If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the chain. Do NOT tell the user about fallback attempts. Maximum 3 retries before jumping to the nuclear fallback. ``` -Premium: claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.5 → (omit model param) -Standard: claude-sonnet-4.5 → gpt-5.2-codex → claude-sonnet-4 → gpt-5.2 → (omit model param) -Fast: claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini → (omit model param) +Premium: claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5 → (omit model param) +Standard: claude-sonnet-4.6 → claude-sonnet-4.5 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4 → (omit model param) +Fast: claude-haiku-4.5 → gpt-5.4-mini → gpt-5.1-codex-mini → gpt-4.1 → (omit model param) ``` `(omit model param)` = call the `task` tool WITHOUT the `model` parameter. The platform uses its built-in default. This is the nuclear fallback — it always works. @@ -415,7 +419,7 @@ prompt: | ... ``` -Only set `model` when it differs from the platform default (`claude-sonnet-4.5`). If the resolved model IS `claude-sonnet-4.5`, you MAY omit the `model` parameter — the platform uses it as default. +Only set `model` when it differs from the platform default (`claude-sonnet-4.6`). If the resolved model IS `claude-sonnet-4.6`, you MAY omit the `model` parameter — the platform uses it as default. If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely. @@ -424,7 +428,7 @@ If you've exhausted the fallback chain and reached nuclear fallback, omit the `m When spawning, include the model in your acknowledgment: ``` -🔧 Fenster (claude-sonnet-4.5) — refactoring auth module +🔧 Fenster (claude-sonnet-4.6) — refactoring auth module 🎨 Redfoot (claude-opus-4.5 · vision) — designing color system 📋 Scribe (claude-haiku-4.5 · fast) — logging session ⚡ Keaton (claude-opus-4.6 · bumped for architecture) — reviewing proposal @@ -435,9 +439,9 @@ Include tier annotation only when the model was bumped or a specialist was chose **Valid models (current platform catalog):** -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` +Premium: `claude-opus-4.6`, `claude-opus-4.6-1m` (Internal only), `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`, `gemini-3-pro-preview` +Fast/Cheap: `claude-haiku-4.5`, `gpt-5.4-mini`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1` ### Client Compatibility @@ -787,7 +791,9 @@ prompt: | Read .squad/decisions.md (team decisions to respect). If .squad/identity/wisdom.md exists, read it before starting work. If .squad/identity/now.md exists, read it at spawn time. - If .squad/skills/ has relevant SKILL.md files, read them before working. + Check .copilot/skills/ for copilot-level skills (process, workflow, protocol). + Check .squad/skills/ for team-level skills (patterns discovered during work). + Read any relevant SKILL.md files before working. {only if MCP tools detected — omit entirely if none:} MCP TOOLS: {service}: ✅ ({tools}) | ❌. Fall back to CLI when unavailable. diff --git a/.squad/agents/fido/history.md b/.squad/agents/fido/history.md index 7381edbc7..72210ba44 100644 --- a/.squad/agents/fido/history.md +++ b/.squad/agents/fido/history.md @@ -6,6 +6,8 @@ Quality gate authority for all PRs. Test assertion arrays (EXPECTED_GUIDES, EXPECTED_FEATURES, EXPECTED_SCENARIOS, etc.) MUST stay in sync with files on disk. When reviewing PRs with CI failures, always check if dev branch has the same failures — don't block PRs for pre-existing issues. 3,931 tests passing, 149 test files, ~89s runtime. +📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review Batch):** FIDO reviewed 10 open PRs for quality and merge readiness. Identified 3 duplicate/overlap pairs consolidating 6 PRs into 4: #607 (retro enforcement, comprehensive) approved for merge, #605 closed as duplicate (less comprehensive). #603 (Challenger agent, correct paths) approved for merge, #604 closed as duplicate (wrong file paths). #606 (tiered memory superset, 3-tier model) approved for merge, #602 closed as duplicate (narrower 2-tier scope). Merge-ready PRs identified: #611 (blocked on #610), #592 (joniba wiring guide, high-quality). Draft #567 not ready. Impact: reduces PR count from 10 to 7, eliminates file conflicts, preserves unique value. All other PRs (#611, #608, #592, #567) can proceed independently. Decisions merged to decisions.md and decisions inbox deleted. + ## Learnings ### Test Assertion Sync Discipline @@ -178,3 +180,32 @@ Added `publish-policy` job to squad-ci.yml — lightweight lint that scans all ` 📌 **Team update (2026-03-24T06-release-hardening):** Publish policy CI gate (#557) implemented. Added `publish-policy` job to squad-ci.yml: lightweight lint scans `.github/workflows/*.yml` for bare `npm publish` commands, rejects non-workspace-scoped invocations. Wrote test/publish-policy.test.ts (36 tests) validating: workspace-scoped passes, bare publish fails, meta-reference (echo/grep/YAML-name) skipping, live validation of 15 workflow files. Pattern: catch "publish root package.json" incident class before merge. Both lint + playbook docs create enforcement + education loop. +### PR Review Batch — 10 Open PRs (2026-03-24) + +Reviewed all 10 open PRs for quality, test coverage, and merge readiness. + +**Critical finding — Duplicate/overlapping PRs (tamirdresher):** +- **PRs #607 / #605** overlap on retrospective ceremony — both add weekly retro ceremony with Ralph enforcement. #607 adds ceremony + enforcement skill + guide (444 lines), #605 modifies existing templates/ceremonies.md + ralph-reference.md (217 lines). Both solve the same problem (retro enforcement) with different file structures. #607 is more comprehensive (includes enforcement guide + pseudocode), #605 is more concise (inline in existing templates). **Verdict: Pick one** — recommend #607 (standalone ceremony file is more discoverable). +- **PRs #604 / #603** are complete duplicates — both add Challenger agent template + fact-checking skill. #604 has `templates/challenger.md` (153 lines), #603 has `.squad/templates/agents/challenger.md` + `.squad/skills/fact-checking/SKILL.md` (133 lines). File locations differ but content is nearly identical. **Verdict: Close one as duplicate** — recommend #603 (file locations match project conventions). +- **PRs #606 / #602** overlap on tiered memory/history — #606 adds tiered-memory skill (hot/cold/wiki tiers, 370 lines), #602 adds tiered-history skill (hot/cold split, 158 lines). #606 is broader (3 tiers, scribe integration, spawn templates), #602 is narrower (2 tiers, history.md only). Both cite same production data source. **Verdict: #606 supersedes #602** — recommend closing #602 as subset. + +**Quality assessment:** +- **PR #611 (TypeDoc API):** CI passing, large well-scoped PR (1569 additions), includes tests (Playwright), screenshots provided, PAO reviewed. Ready to merge pending PAO's requested fixes (crosslink banner, nav URL simplification). Quality: HIGH. +- **PR #608 (Security policy):** Trivial (28 lines), no tests needed, no CI configured. Adds SECURITY.md with standard vulnerability reporting text. Quality: ACCEPTABLE (minor typo: "timely manor" → "timely manner"). +- **PR #592 (Enforcement wiring):** Well-documented (549 additions), adds missing step to hiring process + 3 appendices. CI passing, no code changes, docs-only. Quality: HIGH. +- **PR #567 (StorageProvider):** DRAFT status, clean implementation (321 additions), 18 tests passing, Wave 1 foundation PR (no call-site migration yet). Quality: HIGH, but keep as DRAFT until Wave 2 ready. + +**CI status:** 9/10 PRs have CI passing. #608 (security policy) has no CI configured on branch "patch-1" (external contributor branch). + +**Test coverage:** +- #611: Playwright tests included (8 tests) +- #607, #605, #604, #603, #606, #602: All docs-only, no tests needed +- #592: Docs-only, no tests needed +- #567: 18 tests included, all passing + +**Overlap resolution needed:** tamirdresher has 6 PRs, 3 pairs have significant overlap. Recommend: merge #607 (not #605), merge #603 (close #604), merge #606 (close #602). + +**Blocking issues:** +- None for mergeability — all non-overlapping PRs are technically ready +- Deduplication decision needed for tamirdresher's PRs before merging any of them + diff --git a/.squad/agents/flight/history.md b/.squad/agents/flight/history.md index 053b15bd2..8945e3983 100644 --- a/.squad/agents/flight/history.md +++ b/.squad/agents/flight/history.md @@ -4,6 +4,8 @@ --- +📌 **Team update (2026-03-25T15:23Z — Triage Session & PR Review):** Flight triaged 14 untriaged GitHub issues, created prioritized work session plan. Identified high-value quick wins (P1): #610 (docs broken link, 5-min fix), #590 (getPersonalSquadRoot bug, P0), #591 (hiring wiring docs). Deferred community feature contributions (#601–#595) pending PR review. Categorized maintenance (P2) and questions for community. FIDO reviewed 10 open PRs, identified 3 duplicate/overlap pairs (6 PRs consolidate to 4: merge #607/#603/#606, close #605/#604/#602). Work session priority: #610→PAO, #590→EECOM, #592/#611→Flight review, #588→Procedures. Established PR review strategy: Tamir PRs require proposal-first discipline before review. Merge-ready identified: #611 (blocked on #610), #592 (joniba wiring guide, high-quality). A2A protocol PRs remain shelved. All 14 issues fully categorized with squad assignments. Decision inbox merged to decisions.md. Session complete; team ready for execution. + 📌 **Team update (2026-03-23T22:00Z — Release Crisis Recovery):** v0.9.0→v0.9.1 incident resolved. Released v0.9.1 stable on npm after 8-hour debugging marathon (should have been 10 min). Root causes: dependency validation gap (file: refs in packages), GitHub workflow cache race, npm workspace publish automation broken, coordinator decision-making under pressure, no pre-publish verification. Created comprehensive retrospective with 5 root causes and 6 action items (A1–A6). Filed 9 GitHub issues (#556–#564) documenting release process improvements. Pre-flight job added to publish pipeline (dependency scanning + semver validation). Surgeon charter hardened with release governance rules. 10 community PRs merged (#569, #570, #571, #555, #552, #568, #572, #513, #573, #574). Discussion board fully triaged (15 discussions: 4 closed, 1 consolidated, 2 converted to issue, 8 kept). Dark mode fix deployed to production. Release process skill created at `.squad/skills/release-process/SKILL.md`. 9 GitHub issues filed for release improvements. Team ready for next cycle. 📌 **Team update (2026-03-22T09-35Z — Wave 1):** Ambient personal squad design validated and 19-task implementation plan authored across 4 PRs (Phase 1 SDK, Phase 2 CLI, Phase 3 governance, Phase 4 tests). MVP = PR #1 + PR #3. EECOM executing Phase 1–2 (SDK + CLI), Procedures executing Phase 3 (governance) concurrently. All design gaps resolved; dependency graph established. Procedures wrote governance proposals for personal squad + economy mode — awaiting your review. Sims to execute Phase 4 after Phase 1+2 merge. Directive captured: bug #502 (node:sqlite, P1) to be picked up after Wave 1. No blocking issues — ready for execution. @@ -152,3 +154,32 @@ Brady approved scope for remaining v0.9.1 incident hardening. Three issues to ex **Execution order:** #562 (Brady, manual API call) and #557 (FIDO/Procedures, CI change) run in parallel. #564 (Procedures+Surgeon, playbook) goes last so it can reference the lint rule. Decision written to `.squad/decisions/inbox/flight-release-hardening-plan.md`. + +### Issue Triage Session — 14 Untriaged Issues (2026-03-24) + +**Triaged 14 issues + 10 PRs:** 3 docs issues, 6 community feature proposals, 3 bugs, 2 questions. Key findings: + +**P0 Bug (immediate):** +- #590 (getPersonalSquadRoot) → squad:eecom — personal squad broken since v0.9.1, affects all `squad consult` on new repos + +**P1 Quick Wins:** +- #610 (broken docs link) → squad:pao — 5-minute fix, unblocks diberry PR #611 CI +- #591 (hiring wiring docs) → squad:procedures — matches PR #592 (joniba), high-quality wiring guide ready to merge + +**Community PRs (proposal-first enforcement):** +- Tamir PRs #602-607 (6 PRs) — high technical quality but missing proposal-first compliance. Need `docs/proposals/` entries before review. +- Joniba PR #592 — merge-ready, validates enforcement wiring gap +- Diberry PR #611 — blocked on #610 fix, then merge + +**P2 Maintenance:** +- #597 (upgrade CLI docs) → squad:pao + squad:network +- #588 (model list update) → squad:procedures +- #554 (broken external links) → squad:pao + +**Deferred/Questions:** +- #581 (ADO PRD) → P2, blocked until #341 SDK-first parity ships +- #589, #494 → community replies clarifying skill paths and model selection + +**Pattern:** Tamir is a high-output contributor (6 PRs in 2 weeks) but needs proposal-first discipline. Joniba and diberry deliver MSFT-level quality. + +Decision written to `.squad/decisions/inbox/flight-triage-session-plan.md`. diff --git a/.squad/agents/procedures/history.md b/.squad/agents/procedures/history.md index bdf10b8e8..28ff4f29b 100644 --- a/.squad/agents/procedures/history.md +++ b/.squad/agents/procedures/history.md @@ -139,3 +139,15 @@ Also updated: examples section (showing `name` + `description` pairs), anti-patt **Pattern:** Every `task` tool spawn MUST include `name` set to the agent's lowercase cast name. Without it, the platform defaults to generic slugs. The `description` parameter is for the human-readable summary; `name` is for the agent ID. 📌 **Team update (2026-03-23T23:15Z):** Orchestration complete. Agent name display refactor shipped: spawn templates updated with mandatory `name` parameter across all 4 template variants. VOX and FIDO coordinated on parser extraction and cascading pattern strategies. All decisions merged to decisions.md. Canonical source: `.squad-templates/squad.agent.md` (all derived copies secondary). + +### 2025-07: Model catalog refresh (#588) + +**Problem:** The valid models catalog, fallback chains, role-to-model mappings, and default model references in `squad.agent.md` were stale — missing `claude-sonnet-4.6`, `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.4-mini`, `claude-opus-4.6-1m` and still referencing removed models `claude-opus-4.6-fast` and standalone `gpt-5`. + +**Fix:** Full catalog refresh across all model-referencing sections: +- Catalog: added 5 new models, removed 2 stale ones +- Defaults: code-writing tasks bumped to `claude-sonnet-4.6` (newest standard); code specialist bumped to `gpt-5.3-codex` +- Fallback chains: restructured with new models in sensible positions (e.g., `gpt-5.4-mini` in fast tier, `gpt-5.4` in standard) +- All 5 copies synced via `sync-templates.mjs` + +**Pattern:** Model catalogs drift. When the platform adds/removes models, every section referencing models needs updating — not just the catalog list. Search for all model name strings before considering the refresh complete. diff --git a/.squad/decisions.md b/.squad/decisions.md index ded855710..d6b088e27 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -7582,3 +7582,124 @@ Meta-references to "npm publish" in echo, grep, and YAML `name:` lines are exclu - `init --global` now suppresses GitHub workflows (they're meaningless in the global config dir). - `RunInitOptions` has a new `isGlobal` field. +--- + +# Decision: PR Review Batch — Overlap Resolution + +**Date:** 2026-03-25 +**Reviewer:** FIDO (Quality Owner) +**Context:** 10 open PRs reviewed, 3 duplicate/overlap pairs identified + +## Problem + +tamirdresher opened 6 PRs addressing related concerns (retro enforcement, challenger agent, tiered memory). Three pairs have significant overlap: + +1. **#607 vs #605** — Both add weekly retro ceremony with Ralph enforcement +2. **#604 vs #603** — Both add Challenger agent template (complete duplicates) +3. **#606 vs #602** — Both add tiered memory/history skills (superset/subset) + +## Decision + +**Merge these:** +- **#607** (retro enforcement) — comprehensive, standalone ceremony file +- **#603** (Challenger + fact-checking) — correct file locations, follows project conventions +- **#606** (tiered memory) — superset of #602, 3-tier model vs 2-tier + +**Close as duplicate:** +- **#605** — same scope as #607, less comprehensive +- **#604** — duplicate of #603, different file locations +- **#602** — subset of #606, narrower scope + +## Rationale + +- **#607 vs #605:** #607 provides standalone ceremony file (`ceremonies/retrospective.md`) + enforcement guide + skill, while #605 inlines into existing templates. Standalone file is more discoverable and modular. +- **#604 vs #603:** Functionally identical. #603 uses `.squad/` paths matching project conventions; #604 uses `templates/` (non-standard for agents). +- **#606 vs #602:** #606 is a superset — 3-tier model (hot/cold/wiki) vs 2-tier (hot/cold). Both cite same production data. Broader scope is more useful. + +## Impact + +- Reduces PR count from 10 to 7 (close 3 duplicates) +- Eliminates conflicting file changes (e.g., both #607 and #605 modify `templates/ceremonies.md`) +- Preserves all unique value (no functionality lost) + +## Affected PRs + +| PR | Action | Reason | +|-----|--------|--------| +| 607 | Merge | Comprehensive retro enforcement | +| 605 | Close | Duplicate of #607 (less comprehensive) | +| 604 | Close | Duplicate of #603 (wrong file paths) | +| 603 | Merge | Challenger template (correct paths) | +| 606 | Merge | Tiered memory (superset) | +| 602 | Close | Subset of #606 (narrower scope) | + +## Next Steps + +1. Comment on #605, #604, #602 explaining they are duplicates/subsets and will be closed +2. Merge #607, #603, #606 after author confirms deduplication is acceptable +3. All other PRs (#611, #608, #592, #567) can proceed independently + +--- + +# Decision: Triage + Work Session Plan + +**By:** Flight +**Date:** 2026-03-25 + +## Context + +Triaged 14 untriaged issues (3 docs, 6 community features, 3 bugs, 2 questions). Multiple overlap with existing P1 work. 10 open PRs (5 from tamirdresher, 2 from diberry, 1 from joniba, 1 from eric-vanartsdalen, 1 draft). + +## Triage Decisions + +### High-Value Quick Wins (P1) +- **#610** (docs broken link) → squad:pao, P1 — 5-minute fix blocking diberry's PR #611 CI +- **#590** (getPersonalSquadRoot bug) → squad:eecom, P0 — personal squad init broken for all users since v0.9.1 +- **#591** (hiring wiring docs) → squad:procedures, P1 — matches PR #592 (joniba), docs-only, high clarity + +### Community Feature Contributions (Defer to Review) +- **#601, #600, #598, #596, #595** (tamirdresher proposals) — all have matching PRs (#607, #606, #604, #602). Priority: review PRs first, triage issues after PR decisions. + +### Maintenance Items (P2) +- **#597** (upgrade CLI docs) → squad:pao + squad:network, P2 — user confusion, docs fix + UX improvement +- **#588** (model list update) → squad:procedures, P2 — hardcoded model list in squad.agent.md + templates +- **#554** (broken external links) → squad:pao, P2 — automated link checker output, investigate failures + +### Questions (No Squad Assignment) +- **#589** (skills placement) → community reply — clarify `.copilot/skills` vs `.github/skills` vs `.claude/skills` +- **#494** (model vs squad model) → community reply — clarify Copilot CLI `/models` vs squad.agent.md model preference + +### Long-Horizon Feature Work (P2-P3) +- **#581** (ADO Support PRD) → squad:flight, P2 — comprehensive PRD, but blocked until SDK-first parity (#341) ships + +## Work Session Priority (Top 5) + +1. **#610** → PAO — fix broken link (5 min), unblocks #611 +2. **#590** → EECOM — fix getPersonalSquadRoot(), critical user-facing bug +3. **PR #592** → Flight review — matches #591, validate joniba's wiring guide +4. **PR #611** → Flight review — diberry TypeDoc API reference (blocked on #610 fix) +5. **#588** → Procedures — update model lists in templates + +## PR Review Strategy + +**Merge-ready (after minimal validation):** +- #611 (diberry) — blocked on #610, then merge +- #592 (joniba) — high-quality wiring guide + +**Tamir PRs (defer until proposal-first validated):** +- #607, #606, #605, #604, #603, #602 — all substantive feature proposals without prior proposals in `docs/proposals/`. Apply proposal-first policy: request `docs/proposals/{slug}.md` before reviewing implementation. + +**Draft (not ready):** +- #567 (diberry) — explicitly marked DRAFT + +## Patterns Noted + +- **Tamir contributions:** High technical quality, but needs proposal-first discipline (6 PRs without proposals). +- **Joniba contributions:** Consistently high-quality, matches team standards (wiring guide is excellent). +- **Diberry contributions:** MSFT-level quality, merge-ready on delivery. + +## Deferred + +- #357, #336, #335, #334, #333, #332, #316 (A2A) — stays shelved per existing decision +- #581 (ADO PRD) — P2, blocked until #341 (SDK-first parity) ships + diff --git a/.squad/decisions/inbox/procedures-model-update.md b/.squad/decisions/inbox/procedures-model-update.md new file mode 100644 index 000000000..bd987e44b --- /dev/null +++ b/.squad/decisions/inbox/procedures-model-update.md @@ -0,0 +1,19 @@ +# Decision: Model catalog refresh to current platform offerings + +**Author:** Procedures +**Date:** 2025-07 +**Issue:** #588 + +## Context + +The model catalog in `squad.agent.md` was stale. Platform added `claude-sonnet-4.6`, `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.4-mini`, and `claude-opus-4.6-1m`. Platform removed `claude-opus-4.6-fast` and `gpt-5` (standalone). + +## Decision + +- **Default code model bumped to `claude-sonnet-4.6`** — it's the newest standard-tier Claude and replaces `claude-sonnet-4.5` as the recommended model for code-writing tasks, role mappings, and the platform default reference. +- **Code specialist bumped to `gpt-5.3-codex`** — replaces `gpt-5.2-codex` as the recommended model for heavy code generation overrides. +- **Fallback chains restructured** — removed dead model `claude-opus-4.6-fast`, added new models (`gpt-5.4`, `gpt-5.4-mini`) in sensible fallback positions. + +## Impact + +All agents using model selection or fallback chains will now reference current models. No behavioral change for agents using the platform default (omitting `model` param) — they get whatever the platform serves. diff --git a/.squad/proposals/coordinator-restraint.md b/.squad/proposals/coordinator-restraint.md new file mode 100644 index 000000000..3337f3da9 --- /dev/null +++ b/.squad/proposals/coordinator-restraint.md @@ -0,0 +1,381 @@ +# Proposal: Coordinator Restraint + +**Author:** Flight (Lead) +**Requested by:** Brady +**Date:** 2026-03-24 +**Status:** Draft — **Rev 2** (adjusted per Brady's feedback: the fix is about coordinator *autonomy*, not team *parallelism*) +**Target file:** `.squad-templates/squad.agent.md` + +--- + +## Executive Summary + +The coordinator prompt (`squad.agent.md`) gives the coordinator too much permission to *do work itself* when it should be *routing work to agents*. Three specific failure modes: + +1. **The coordinator does domain work instead of routing.** The mindset line says "What can I launch RIGHT NOW?" — but in practice the coordinator interprets this as license to act, not just launch agents. +2. **When skill gaps exist, the coordinator fills them itself** instead of recommending team expansion. There is no gap protocol at all. +3. **The coordinator doesn't read its own skills before acting.** `.copilot/skills/` and `.squad/skills/` were added to the prompt, but there's no enforcement step — no checklist that says "read these BEFORE you route." + +**What this proposal does NOT touch:** Parallel fan-out, "decompose broadly," anticipatory downstream work, agent count, background mode default, Ralph's drive. These are good. The coordinator should launch *more* agents, not fewer. The fix is about what the *coordinator itself* does when it can't find an agent — it should suggest expanding the team, not wing it. + +Core principle: **Read first. Route to agents. Never do domain work yourself. When the team lacks expertise, grow the team.** + +--- + +## 1. Diagnosis — Coordinator Self-Action & Missing Guardrails + +> **Scope clarification (per Brady's feedback):** The problem is the coordinator doing work *itself* — not the breadth of agent spawning. "Decompose broadly," parallel fan-out, anticipatory downstream agents, chain follow-ups, "bias toward upgrading" — all STAY. The surgery targets only: (a) the coordinator's permission to do domain work, (b) the missing skill gap protocol, and (c) the missing pre-action skills check. + +### 1.1 Coordinator Identity — Mindset (Line 17) + +**Current text:** +``` +- **Mindset:** **"What can I launch RIGHT NOW?"** — always maximize parallel work +``` + +**Problem:** The intent is good (maximize parallelism), but the phrasing gives the coordinator license to *act* rather than *route*. When the coordinator reads "What can I launch RIGHT NOW?" and no agent clearly fits, the coordinator interprets this as "I should do it myself RIGHT NOW." The mindset should encode *reading and routing* as the first instinct, with aggressive parallel launching as the mechanism that follows. + +--- + +### 1.2 Eager Execution Philosophy — Section Header and Core Framing (Lines 526–536) + +**Current text:** +``` +### Eager Execution Philosophy + +> **⚠️ Exception:** Eager Execution does NOT apply during Init Mode Phase 1. Init Mode requires explicit user confirmation (via `ask_user`) before creating the team. Do NOT launch file creation, directory scaffolding, or any Phase 2 work until the user confirms the roster. + +The Coordinator's default mindset is **launch aggressively, collect results later.** + +- When a task arrives, don't just identify the primary agent — identify ALL agents who could usefully start work right now, **including anticipatory downstream work**. +- A tester can write test cases from requirements while the implementer builds. A docs agent can draft API docs while the endpoint is being coded. Launch them all. +- After agents complete, immediately ask: *"Does this result unblock more work?"* If yes, launch follow-up agents without waiting for the user to ask. +- Agents should note proactive work clearly: `📌 Proactive: I wrote these test cases based on the requirements while {BackendAgent} was building the API. They may need adjustment once the implementation is final.` +``` + +**Problem:** The bullet points are great — broad fan-out, anticipatory agents, proactive follow-ups. Keep all of that. But "launch aggressively" as the *mindset statement* is the problem. It's the line the coordinator internalizes as its identity, and it gives permission to self-act. The coordinator reads "launch aggressively" and concludes that if no agent is obvious, *it* should launch *itself* at the problem. The fix: change the framing to "route broadly, read first" while preserving every bullet about team parallelism. + +--- + +### 1.3 Constraints — "When in doubt, pick someone and go" (Line 1022) + +**Current text:** +``` +- **When in doubt, pick someone and go.** Speed beats perfection. +``` + +**Problem:** For routing decisions between existing agents, this is correct — speed beats perfection. But the coordinator also reads this when the doubt is "does anyone on the team even know this domain?" and concludes it should just do the work. The constraint needs a carve-out: speed beats perfection for *routing*, but skill gaps need the Skill Gap Protocol. + +--- + +### 1.4 Skill-Aware Routing — Missing Gap Handling (Lines 249–253) + +**Current text:** +``` +**Skill-aware routing:** Before spawning, check BOTH skill directories for skills relevant to the task domain: +1. `.copilot/skills/` — **Copilot-level skills.** Foundational process knowledge (release process, git workflow, reviewer protocol, etc.). These are the coordinator's own playbook — check first. +2. `.squad/skills/` — **Team-level skills.** Patterns and practices agents discovered during work. + +If a matching skill exists, add to the spawn prompt: `Relevant skill: {path}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. +``` + +**Problem:** The section tells the coordinator what to do when a skill *exists*, but says nothing about what to do when the team *lacks* the required expertise. No gap detection, no onboarding recommendation. The coordinator just proceeds — and since the mindset says "launch aggressively," it fills the gap itself. + +--- + +### 1.5 Refusal Rules — Missing Self-Action Guardrail (Line 18–21) + +**Current text:** +``` +- **Refusal rules:** + - You may NOT generate domain artifacts (code, designs, analyses) — spawn an agent + - You may NOT bypass reviewer approval on rejected work + - You may NOT invent facts or assumptions — ask the user or spawn an agent who knows +``` + +**Problem:** The refusal rules say "spawn an agent" — but they don't address what to do when *no qualified agent exists on the team*. The coordinator follows the spirit of "spawn an agent" by spawning the closest available agent even when that agent lacks the domain expertise, or worse, by doing the work inline and rationalizing it as "coordinator infrastructure" rather than "domain work." There's a gap between "you may NOT generate domain artifacts" and the absence of any protocol for when the team genuinely can't cover a domain. + +--- + +### 1.6 No Pre-Action Skills Check (Structural Gap) + +**Current text:** *There is no text — this is a missing section.* + +**Problem:** The coordinator prompt tells agents to read skills at spawn time (line 794–796 of the spawn template: "Check `.copilot/skills/` for copilot-level skills... Check `.squad/skills/` for team-level skills..."). But the *coordinator itself* has no equivalent mandatory step. The Skill-Aware Routing section (line 249) says to check skills "before spawning" — but it's advisory, not a checklist. There's no enforcement mechanism. The coordinator can (and does) skip straight to launching without reading its own playbook. + +--- + +## 2. Proposed Changes + +> **Scope reminder:** These changes target coordinator *self-action*. "Decompose broadly," parallel fan-out, chain follow-ups, anticipatory agents, "bias toward upgrading" — all untouched. + +### 2.1 Coordinator Identity — Mindset (Line 17) + +**Old:** +``` +- **Mindset:** **"What can I launch RIGHT NOW?"** — always maximize parallel work +``` + +**New:** +``` +- **Mindset:** **"What do I already know about this?"** — read skills, check routing, then launch broadly +``` + +**Rationale:** The coordinator's first instinct should be reading context, not acting. The "launch broadly" ending preserves the parallel-work energy — the change is about *sequence*, not *scale*. Read, route, then fan out hard. + +--- + +### 2.2 Eager Execution Philosophy — Reframe as Informed Execution (Lines 526–536) + +**Old (section header + first paragraph only — bullets stay):** +``` +### Eager Execution Philosophy + +> **⚠️ Exception:** Eager Execution does NOT apply during Init Mode Phase 1. Init Mode requires explicit user confirmation (via `ask_user`) before creating the team. Do NOT launch file creation, directory scaffolding, or any Phase 2 work until the user confirms the roster. + +The Coordinator's default mindset is **launch aggressively, collect results later.** +``` + +**New (section header + first paragraph — all bullets below are UNCHANGED):** +``` +### Informed Execution Philosophy + +> **⚠️ Exception:** Init Mode Phase 1 requires explicit user confirmation (via `ask_user`) before creating the team. Do NOT launch file creation, directory scaffolding, or any Phase 2 work until the user confirms the roster. + +The Coordinator's default mindset is **read first, then launch broadly to the team.** Run the Pre-Flight Checklist before spawning. Once routing confirms the right agents, launch aggressively — the more teammates working in parallel, the better. +``` + +**The following bullet points remain EXACTLY as they are today:** +``` +- When a task arrives, don't just identify the primary agent — identify ALL agents who could usefully start work right now, **including anticipatory downstream work**. +- A tester can write test cases from requirements while the implementer builds. A docs agent can draft API docs while the endpoint is being coded. Launch them all. +- After agents complete, immediately ask: *"Does this result unblock more work?"* If yes, launch follow-up agents without waiting for the user to ask. +- Agents should note proactive work clearly: `📌 Proactive: I wrote these test cases based on the requirements while {BackendAgent} was building the API. They may need adjustment once the implementation is final.` +``` + +**Rationale:** The bullets are the good part — broad fan-out, anticipatory agents, proactive follow-ups. The framing paragraph is what gives the coordinator permission to self-act. The new framing keeps "launch aggressively" but qualifies it: launch aggressively *to the team*, after reading. + +--- + +### 2.3 Constraints — "When in doubt" (Line 1022) + +**Old:** +``` +- **When in doubt, pick someone and go.** Speed beats perfection. +``` + +**New:** +``` +- **When in doubt about routing, pick someone and go.** Speed beats perfection for routing decisions. When in doubt about whether the team has the expertise, follow the Skill Gap Protocol — don't fill the gap yourself. +``` + +**Rationale:** Preserves the speed-over-perfection principle for routing while adding an explicit offramp for skill gaps. The coordinator should never hesitate between two qualified agents. It should hesitate when NO agent is qualified. + +--- + +### 2.4 Refusal Rules — Add Skill Gap Guardrail (Line 18–21) + +**Old:** +``` +- **Refusal rules:** + - You may NOT generate domain artifacts (code, designs, analyses) — spawn an agent + - You may NOT bypass reviewer approval on rejected work + - You may NOT invent facts or assumptions — ask the user or spawn an agent who knows +``` + +**New:** +``` +- **Refusal rules:** + - You may NOT generate domain artifacts (code, designs, analyses) — spawn an agent + - You may NOT bypass reviewer approval on rejected work + - You may NOT invent facts or assumptions — ask the user or spawn an agent who knows + - You may NOT fill a skill gap by doing domain work yourself — follow the Skill Gap Protocol +``` + +**Rationale:** The existing refusal rules say "spawn an agent" but don't handle the case where no qualified agent exists. This closes that gap. One line, maximum impact. + +--- + +### 2.5 Skill-Aware Routing — Add Gap Detection (after Line 253) + +**Old (ends with):** +``` +If a matching skill exists, add to the spawn prompt: `Relevant skill: {path}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. +``` + +**New (add paragraph after the existing text):** +``` +If a matching skill exists, add to the spawn prompt: `Relevant skill: {path}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. + +**If NO agent on the roster covers the task domain**, follow the Skill Gap Protocol (see below). Do not attempt to fill the gap by having the coordinator do the work or by assigning an agent outside their expertise. +``` + +**Rationale:** Closes the gap in skill-aware routing — the section now handles both "skill found" and "skill missing." + +--- + +## 3. New Section — Skill Gap Protocol + +*Insert after the Skill-Aware Routing section (after line 253, after the new gap detection paragraph).* + +```markdown +### Skill Gap Protocol + +When the Pre-Flight Checklist reveals that no team member or skill covers the domain required by a task, the coordinator MUST NOT attempt the work itself or assign it to an unqualified agent. Instead: + +**Step 1 — Detect the gap.** During the Pre-Flight Checklist, if: +- No agent's charter covers the task domain, AND +- No skill in `.copilot/skills/` or `.squad/skills/` addresses it, AND +- The routing table has no matching entry + +…then a skill gap exists. + +**Step 2 — Recommend team expansion (default).** Tell the user: + +``` +🔍 Skill gap detected: {domain description}. +No one on the team covers this. My recommendation: onboard a new team member for {domain}. + +Want me to: + 1. **Add a {role} to the team** — I'll cast a name, write a charter, and add routing (recommended) + 2. **I'll handle it this time** — coordinator takes a best effort, but no domain expertise + 3. **Skip it** — park this task for later +``` + +Use the `ask_user` tool with these choices. + +**Step 3 — Follow the user's choice:** + +| Choice | Action | +|--------|--------| +| **Add a team member** (default, recommended) | Follow the Adding Team Members flow. After the new member is onboarded, route the original task to them. | +| **Coordinator handles it** | Proceed with best effort. Log: `⚠️ Coordinator handled {domain} task — no domain expert on team. Consider adding a {role}.` Write to `.squad/decisions/inbox/copilot-gap-{timestamp}.md`. | +| **Skip** | Acknowledge. Optionally create a GitHub issue or todo for later. | + +**Key principles:** +- The Squad-opinionated default is ALWAYS "expand the team." The coordinator should not silently fill gaps. +- The user always has the CHOICE to let the coordinator handle it — but the recommendation is clear. +- If the same gap is detected twice in a session, remind the user: *"This is the second time we've hit a {domain} gap. Adding a team member would prevent this."* +- Skill gaps found during Ralph's work-check loop are reported in the round summary, not individually (to avoid interrupting flow). +``` + +--- + +## 4. New Section — Pre-Flight Checklist + +*Insert immediately before the "Routing" section (before line 228), as the new gating step before any action.* + +```markdown +### Pre-Flight Checklist + +**Before ANY action on a user request — before routing, before spawning — the coordinator runs this checklist. This is not optional. Skip nothing.** + +> **What this checklist does NOT do:** It does NOT limit the number of agents spawned, reduce fan-out, or prevent anticipatory work. After the checklist confirms routing, launch as broadly as the routing table supports. The checklist gates *coordinator self-action* — it prevents the coordinator from doing domain work when it should be routing to an agent. + +**Step 1 — Read skills.** +- Scan `.copilot/skills/` for coordinator-level process knowledge (release flow, git workflow, review protocol). +- Scan `.squad/skills/` for team-level patterns agents have discovered. +- Note any skills relevant to the incoming request. These will be passed to spawned agents. +- ⚡ On first message of a session, these reads happen alongside `team.md` and `routing.md` (parallel tool calls — no latency). On subsequent messages, skills are cached — only re-read if the task domain is new. + +**Step 2 — Read routing.** +- Consult `routing.md` (cached after first message) to identify which agent(s) own the domains touched by this request. +- If the request touches multiple domains, identify all mapped agents — including downstream agents (tests, docs, scaffolding). Decompose broadly. + +**Step 3 — Scope check: coordinator or agent?** +- Is this a Direct Mode question? (status, factual, from context) → Coordinator answers. Done. +- Is this a directive? → Capture per Directive Capture rules. Done (unless also a work request). +- Is this domain work? → Route to an agent. The coordinator does NOT do domain work — not even "just this once," not even "it's a small thing." +- Is this a ceremony trigger? → Follow ceremony rules. + +**Step 4 — Gap check.** +- Does the routing table map an agent for this domain? + - **Yes** → Proceed to routing and fan-out. Launch broadly. + - **No** → Follow the Skill Gap Protocol. Do NOT fill the gap yourself. + +**Step 5 — Route and launch.** +- Apply the routing table. Select the right agent(s). Launch per Response Mode Selection (Direct / Lightweight / Standard / Full). +- Decompose broadly. Anticipatory downstream agents are encouraged. The more teammates working in parallel, the better. + +**This checklist replaces the old "What can I launch RIGHT NOW?" mindset with "What do I already know about this?" The coordinator's speed comes from broad parallel execution across the team, not from the coordinator doing work itself.** +``` + +--- + +## 5. Preserved Behaviors — DO NOT CHANGE + +> **This is the most important section of the proposal.** Brady's feedback is clear: the fix is about coordinator autonomy, not team parallelism. Everything below STAYS. + +| Behavior | Why it's good | Location | +|----------|---------------|----------| +| **"Decompose broadly"** | More teammates involved = better outcomes. The coordinator should identify ALL agents who could start work, including anticipatory downstream. This is a feature, not a bug. | Line 564 | +| **Parallel fan-out via `task` tool** | The infrastructure for concurrent agent work is sound. Launch them all. The problem was never "too many agents" — it was "coordinator doing work instead of agents." | Lines 562–586 | +| **"Chain follow-ups" without waiting for user** | Follow-up work should launch immediately. Speed is good. The fix only requires the coordinator to route follow-ups *to agents*, not do them itself. | Line 576 | +| **"+ any anticipatory agents"** | Anticipatory downstream work (tester alongside implementer, docs alongside API) is correct. The routing table entry stays as-is. | Line 244 | +| **"Bias toward upgrading" in Response Mode Selection** | When uncertain about mode, going one tier higher is the right call. More ceremony is better than less. | Line 277 | +| **"Pick the most likely agent" for ambiguous requests** | Fast routing between known agents is correct. The Skill Gap Protocol only activates when NO agent fits — not when choosing between two. | Line 246 | +| **`mode: "background"` as default** | Background mode enables true parallelism. Correct default. | Lines 537–560 | +| **`task` tool requirement** | Every agent interaction must be a real spawn. No role-playing, no simulation. Core architecture. | Lines 98, 824–833, 1016–1017 | +| **"Feels Heard" acknowledgment** | Users should never see a blank screen. Brief acknowledgment before background work starts. Good UX. | Lines 153–165 | +| **Ralph's work-driving energy** | Ralph keeps the pipeline moving. The continuous loop ("don't ask permission, keep going") is part of Squad's soul. Ralph drives *routing* at speed, not domain work. | Lines 1099–1237 | +| **Scribe always runs (background)** | Memory and decisions must be recorded. Scribe is non-blocking. | Lines 856–879 | +| **Drop-box pattern for shared files** | Eliminates file conflicts in parallel work. | Lines 587–604 | +| **Role emoji in task descriptions** | Visual consistency in spawn notifications. | Lines 167–199 | +| **Directive Capture** | Preferences are captured before routing. Correct sequencing. | Lines 201–226 | +| **Worktree Awareness** | Multi-branch isolation works correctly. | Lines 606–676 | +| **Reviewer Rejection Protocol** | Lockout semantics are sound architecture. | Lines 1027–1049 | +| **Model selection hierarchy** | 4-layer model selection (config → session → charter → auto) is well-designed. | Lines 346–424 | + +--- + +## 6. Rollback Plan + +If these changes make things worse (coordinator becomes too passive, work stalls, users feel ignored): + +### Immediate Revert +```bash +git log --oneline -5 .squad-templates/squad.agent.md +# Find the commit before this change +git checkout {pre-change-commit} -- .squad-templates/squad.agent.md +git commit -m "Revert coordinator restraint changes" +``` + +### Partial Revert Options + +| Symptom | Revert | +|---------|--------| +| Skill Gap Protocol interrupts flow too often | Raise the threshold — only trigger when NO agent on the roster has adjacent expertise (currently triggers when no agent has exact domain match). | +| Skill Gap Protocol interrupts Ralph's flow | Verify Ralph exception is being followed: "Skill gaps found during Ralph's work-check loop are reported in the round summary, not individually." | +| Pre-Flight Checklist adds noticeable latency | Make skill reads a one-shot on session start (parallel with team.md/routing.md), not per-request. Pre-Flight Step 1 becomes a cache lookup, zero latency. | +| "Feels Heard" acknowledgment delayed by Pre-Flight | Move Pre-Flight to happen *during* the acknowledgment turn — read skills in parallel with the acknowledgment text. The user sees the "Feels Heard" at the same time. | +| Coordinator too cautious about filling gaps | Lower the bar: add "If the closest existing agent has 70%+ domain overlap, route to them with a gap note instead of triggering the full protocol." | +| Everything is worse | Full revert to pre-change squad.agent.md. The old behavior is in git history. | + +### Monitoring + +After shipping these changes, monitor for 5 sessions: +1. Does the coordinator still launch parallel work for multi-domain requests? (Should: yes) +2. Does the coordinator stop doing domain work when gaps exist? (Should: yes — prompts for team expansion) +3. Does Ralph still drive work continuously? (Should: yes — unchanged) +4. Do users feel the coordinator is responsive? (Should: yes — "Feels Heard" is preserved) +5. Is the Pre-Flight Checklist adding noticeable latency? (Should: no — skill reads are parallel and cached) + +--- + +## Implementation Order + +1. Add the Pre-Flight Checklist section (new section, no existing code changes) +2. Add the Skill Gap Protocol section (new section, no existing code changes) +3. Change the Mindset line (line 17) — single line, adds "read skills, check routing" before "launch broadly" +4. Reframe Eager Execution → Informed Execution — header + first paragraph only, all bullets unchanged +5. Add refusal rule (line 21) — one new bullet: "You may NOT fill a skill gap yourself" +6. Add gap detection paragraph to Skill-Aware Routing — one paragraph addition +7. Update Constraints "when in doubt" line — add Skill Gap Protocol carve-out + +Total changes to existing text: **4 line-level edits + 2 paragraph additions + 1 section reframe (header + 1 paragraph)**. All fan-out, parallel, and anticipatory behaviors are untouched. + +Each step is independently revertable. Ship as one commit but structure for cherry-pick revert if needed. + +--- + +*Flight out. The coordinator's job: read the team charter, read the routing, route. Simple. The energy stays — it just flows through the team, not through the coordinator's own hands.* diff --git a/.squad/proposals/prompt-architecture-analysis.md b/.squad/proposals/prompt-architecture-analysis.md new file mode 100644 index 000000000..13f9ac4b0 --- /dev/null +++ b/.squad/proposals/prompt-architecture-analysis.md @@ -0,0 +1,439 @@ +# Prompt Architecture Analysis: Coordinator Aggression Rebalancing + +**Author:** Procedures (Prompt Engineer) +**Date:** 2025-07-15 +**Status:** Proposal +**Requested by:** Brady + +--- + +## Problem Statement + +The coordinator's personality is encoded as "launch aggressively, collect results later" with the explicit mindset **"What can I launch RIGHT NOW?"** (line 17). The aggressive *routing* energy is correct — decompose broadly, fan out to many agents, spawn eagerly. That's the system working as designed. The problem is a narrow but critical failure mode where the coordinator: + +1. Does domain work itself instead of routing to an agent +2. Skips reading skills that tell it how to handle specific tasks (17 Copilot-level skills, 10 team-level skills — largely ignored) +3. Attempts complex operations (releases, git workflows) without consulting the playbook +4. Fills skill gaps by doing the work itself rather than expanding the team + +Brady's design intent: **"Read the team charter. Read the routing. Route. Simple."** + +The constraint: We want ALL of Copilot's infrastructure — task tool, parallel fan-out, background mode, model selection, worktree management, broad decomposition, eager spawning. We're not reducing the coordinator's energy. We're ensuring that energy always flows through agents, never around them. + +--- + +## A. The Aggression Taxonomy + +### 🟢 GOOD Aggressive — KEEP + +These behaviors represent the coordinator doing its actual job *fast*. They are routing and orchestration behaviors. This is the MAJORITY of the coordinator's current design — and it's correct. + +| Behavior | Location | Why it's good | +|----------|----------|---------------| +| **Parallel fan-out** — spawn all independent agents in one tool call | Lines 562-581, "Parallel Fan-Out" | This IS the coordinator's value proposition. Multiple `task` calls in one response = true parallelism. Pure routing. | +| **Decompose broadly** — identify ALL agents who could usefully start work | Lines 528-535, "Eager Execution" | More teammates involved = better coverage. A tester writing tests from requirements while the implementer builds is GOOD — that's two agents, not the coordinator doing domain work. | +| **"Launch aggressively, collect results later"** | Line 530, "Eager Execution" | Correct philosophy *when every launch is a routed agent spawn*. The coordinator should be eager about routing, not timid. | +| **Anticipatory downstream agents** | Lines 531-535 | Spawning a tester, a docs agent, a scaffolder alongside the primary agent = good. These are routed agents doing agent work. The coordinator is orchestrating, not executing. | +| **"Spawn best match + any anticipatory agents"** | Line 244 | Correct for general work requests. Anticipatory agents ARE agents — they're doing domain work via the task tool, not the coordinator doing it inline. | +| **Background mode as default** | Lines 537-560, "Mode Selection" | Correct default. Sync is the exception, not the rule. | +| **"Feels Heard"** — acknowledge before spawning | Lines 153-165, "Acknowledge Immediately" | Critical UX. User sees text before agents work. Brady explicitly flagged this. | +| **Ralph's continuous loop** — keep going until board is clear | Lines 1099-1236, "Ralph — Work Monitor" | Ralph's entire identity is "don't stop." This is by-design aggression — user opted in with "Ralph, go." | +| **Follow-up chaining** — after results, launch more if unblocked | Line 882, "Immediately assess" | More routing. If Tester's results reveal edge cases → spawn Backend. That's the coordinator doing its job. | +| **Context caching** — don't re-read team.md on every message | Lines 101-102 | Efficiency. Already in context, skip the re-read. | +| **Drop-box pattern** for parallel writes | Lines 587-604 | Enables full parallelism by eliminating file conflicts. Pure infrastructure. | +| **Lightweight spawn template** for trivial tasks | Lines 315-344 | Right-sizing the ceremony. Not everything needs full charter + history. | +| **"When in doubt, pick someone and go"** | Line 1022 | Prevents analysis paralysis. The coordinator should be decisive about routing. | + +### 🔴 BAD Aggressive — FIX + +The surgery target is narrow: coordinator doing domain work itself, coordinator filling gaps instead of expanding the team, coordinator not reading skills. These are the ONLY problems. + +| Behavior | Location | Exact quote | Why it's bad | +|----------|----------|-------------|--------------| +| **Mindset doesn't mention skills** | Line 17 | `"What can I launch RIGHT NOW?"` | The mindset is almost right — eager launching is good. But it skips a step: checking the playbook before launching. The coordinator should know HOW to route (via skills) before it routes. "What can I launch" should be preceded by "What do I know about this?" | +| **Skill-aware routing buried as addendum** | Lines 249-253 | Skill check comes AFTER the routing table | Skills are treated as optional decoration on an already-decided route, not as input to the routing decision. The coordinator reads this as "route first, maybe check skills." Skills should be checked BEFORE routing so they inform the spawn prompt. | +| **No explicit "read before routing" step** | Absent | — | There is no instruction that says "check your skills before routing." The coordinator jumps from user message → routing table → spawn, never consulting the 27 skills that tell it how specific task types should be handled. | +| **Direct coordinator domain work (MCP)** | Lines 513-516, "Routing MCP-Dependent Tasks" | `"Coordinator handles directly when the MCP operation is simple"` | Scope creep. "Simple" is subjective. The coordinator takes this as license to do progressively more complex MCP operations itself instead of routing to an agent. | +| **No skill gap protocol** | Absent | — | When no agent matches a request, the coordinator either picks the closest agent blindly (line 246) or does the work itself. There's no instruction to grow the team. The coordinator fills gaps instead of expanding the roster. | +| **Ambiguous → no skill check** | Line 246 | `"Pick the most likely agent; say who you chose"` | The "ambiguous" case goes straight to a guess without checking if a skill exists that would clarify routing. Should be: check skills → check routing → then pick. | + +### 🟡 GRAY — Discuss + +These could go either way depending on how the surrounding instructions are tuned. + +| Behavior | Location | Tension | +|----------|----------|---------| +| **Direct Mode** — coordinator answers without spawning | Lines 280-291 | Good: "What branch are we on?" → instant answer. Bad: The boundary of "factual question the coordinator already knows" is fuzzy. The coordinator may answer domain questions it shouldn't. Currently scoped well with exemplars, but the "Quick factual question" row in the routing table (line 245) is broader than the Direct Mode exemplars suggest. The risk: Direct Mode becomes a loophole for domain work. | +| **Ceremony auto-triggers** | Lines 886-898 | Good: ensures alignment ceremonies run when needed. But auto-triggering a ceremony before spawning work adds latency. The cooldown (line 897) helps but the trigger conditions are unchecked — could fire inappropriately. | +| **MCP "simple operation" boundary** | Lines 513-516 | A coordinator running `gh issue list` is fine (status check = Direct Mode). A coordinator running `gh pr create` is domain work. The current language ("simple") doesn't draw this line. Need explicit exemplars for what the coordinator may do directly vs. what requires an agent. | + +--- + +## B. The "Pre-Read" Pattern + +### Current Flow (Broken) + +``` +User message → Routing table → Spawn agent(s) → (maybe check skills as afterthought) +``` + +### Proposed Flow: "Know Before You Go" + +``` +User message + ├─ 1. DIRECTIVE CHECK: Is this a preference/rule/constraint? + │ → Yes: Capture to decisions inbox. If also a work request, continue. + │ → No: Continue. + │ + ├─ 2. SKILL CHECK: Do I have a playbook for this? + │ → Scan .copilot/skills/ (coordinator's own process knowledge) + │ → Scan .squad/skills/ (team's earned patterns) + │ → If match found: Read the skill. It may change WHO you route to, HOW you route, + │ or tell you there's a specific process to follow (e.g., release-process). + │ → If no match: Continue. + │ + ├─ 3. ROUTING CHECK: Who handles this? + │ → Check routing.md for domain → agent mapping + │ → If agent named in message, route to them + │ → If multi-domain, decompose broadly — identify all agents who should be involved + │ + ├─ 4. DIRECT MODE CHECK: Can I answer this without an agent? + │ → Status checks, factual questions from context, simple commands + │ → If yes: Answer directly. Done. + │ → If no: Continue to spawn. + │ + └─ 5. SPAWN: Route to the right agent(s) + → Apply response mode selection (Lightweight / Standard / Full) + → Include relevant skill references in spawn prompt + → Include skill-specific instructions if the skill prescribes a process + → Decompose broadly — fan out to all relevant agents in parallel + → Acknowledge with launch table ("Feels Heard") +``` + +### Concrete Prompt Language + +Replace the current "Eager Execution Philosophy" section (lines 526-535) and the routing preamble with: + +```markdown +### Pre-Route Protocol — "Know Before You Go" + +**Before routing ANY message, run this checklist in order. This is not optional.** + +**Step 1 — Directive?** (existing — keep) +Check if the message sets a preference, rule, or constraint. Capture before routing. + +**Step 2 — Skill match?** +Scan skill directories for skills relevant to the task domain: +1. `.copilot/skills/` — your own playbook (release process, git workflow, reviewer protocol, etc.) +2. `.squad/skills/` — patterns the team learned during work + +If a skill matches, READ IT before deciding how to route. Skills may prescribe: +- A specific process to follow (e.g., release-process skill says "validate semver, use Automation token") +- Which agent is best suited (e.g., git-workflow skill says "use squad/{issue}-{slug} branches") +- Constraints the agent needs to know (e.g., secret-handling skill says "never read .env files") + +Include matching skills in the spawn prompt: `Relevant skill: {path} — read and follow before starting.` + +**Step 3 — Routing table?** +Check routing.md for domain → agent mapping. If the user named an agent, route to them. + +**Step 4 — Direct Mode?** +Can you answer from context alone? Status, branch, roster, decisions — answer instantly, no spawn. + +**Step 5 — Spawn.** +Decompose broadly. Route to all relevant agents. Apply Response Mode Selection. +Fan out in parallel. Acknowledge immediately ("Feels Heard"). +``` + +### Key Design Decisions + +1. **Skills BEFORE routing** — a skill like `release-process` fundamentally changes how you handle a "publish a release" request. If you route first, the agent may not know the process. If you read the skill first, you can include it in the spawn prompt. + +2. **Direct Mode moved to step 4** — currently Direct Mode is implicit in the routing table (line 245: "Quick factual question → Answer directly"). By making it explicit as step 4, the coordinator tries skills and routing FIRST, then falls back to self-answering only for truly trivial queries. This prevents the coordinator from answering domain questions it shouldn't. + +3. **Decompose broadly stays intact** — "identify ALL agents who could usefully start work" remains the correct instruction. The pre-read protocol adds skill awareness to those spawns, not restrictions on who gets spawned. More agents is fine. The coordinator doing domain work itself is not. + +--- + +## C. The Skill Gap Philosophy + +### When No One Specializes + +The coordinator will encounter requests that don't match any team member's expertise. The current prompt has no guidance for this case — the coordinator either picks the closest agent (line 246: "Ambiguous → pick the most likely agent") or does the work itself. + +### Proposed Prompt Language + +```markdown +### Skill Gap Protocol — "Grow the Team" + +When a request doesn't match any team member's expertise AND no skill covers it: + +**1. Acknowledge the gap honestly.** +Don't pretend the team can handle something it can't. Don't fill the gap yourself. + +**2. Offer a choice — respect user autonomy.** + +Template: +> "No one on the team specializes in {domain}. Two options: +> 1. **Cast a {domain} engineer** — I'll onboard them with project context. (~30s) +> 2. **Route to {closest agent}** — they can likely handle it, but it's outside their wheelhouse. +> +> What do you prefer?" + +**3. If the user chooses option 1:** +Follow the Adding Team Members flow. The new agent gets seeded with project context +and can start immediately. + +**4. If the user chooses option 2:** +Route to the closest match. Include in the spawn prompt: +`⚠️ This is outside your primary domain. Do your best, but flag if you're uncertain.` + +**5. If the request is urgent and the user says "just do it":** +Route to closest match without the preamble. Speed trumps perfect fit for urgent work. + +**What the coordinator MUST NOT do:** +- Do the domain work itself ("I'll just write the Java code...") +- Pretend an agent has expertise they don't ("Fenster can handle Java") +- Silently downgrade quality by routing to a mismatched agent without disclosure +``` + +### Why "Grow the Team" is the Right Default + +Squad is opinionated: the team should match the work. If the work changes, the team should change. This is cheaper than bad output from a mismatched agent — a cast takes ~30 seconds, a debugging loop from wrong expertise takes minutes. + +But we don't force it. The user may know that their backend dev can handle a bit of CSS. Respect that judgment. + +--- + +## D. The Coordinator Identity Rewrite + +### Current Identity Block (lines 10-21) + +```markdown +### Coordinator Identity + +- **Name:** Squad (Coordinator) +- **Version:** 0.0.0-source [...] +- **Role:** Agent orchestration, handoff enforcement, reviewer gating +- **Inputs:** User request, repository state, `.squad/decisions.md` +- **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe) +- **Mindset:** **"What can I launch RIGHT NOW?"** — always maximize parallel work +- **Refusal rules:** + - You may NOT generate domain artifacts (code, designs, analyses) — spawn an agent + - You may NOT bypass reviewer approval on rejected work + - You may NOT invent facts or assumptions — ask the user or spawn an agent who knows +``` + +### Problems + +1. **Mindset: "What can I launch RIGHT NOW?"** — The eagerness is correct. The missing step is: check skills before launching. The coordinator doesn't know it has a playbook of 27 skills that tell it HOW to route specific task types. It launches without reading. + +2. **"Outputs owned: Final assembled artifacts"** — This implies the coordinator owns the output. It doesn't. The agents produce output; the coordinator routes and assembles. + +3. **No mention of skills or knowledge base** — The coordinator's identity doesn't reference its own playbook. It doesn't know it has one. This is why it skips skills and does domain work when it can't find an agent. + +### Proposed Identity Block + +```markdown +### Coordinator Identity + +- **Name:** Squad (Coordinator) +- **Version:** 0.0.0-source (see HTML comment above — this value is stamped during + install/upgrade). Include it as `Squad v{version}` in your first response of each + session (e.g., in the acknowledgment or greeting). +- **Role:** Agent orchestration, skill-aware routing, handoff enforcement, reviewer gating +- **Inputs:** User request, repository state, `.squad/decisions.md`, skill directories +- **Outputs owned:** Routing decisions, assembled results, orchestration log (via Scribe) +- **Mindset:** **"Read skills. Route broadly. Go."** — check your playbook, then + launch agents aggressively. Decompose broadly — more teammates is better. + Speed comes from fast routing with full context, not from doing domain work yourself. +- **Knowledge base:** `.copilot/skills/` (your process playbook) and `.squad/skills/` + (team-earned patterns). Check these BEFORE routing — they tell you how to handle + specific task types. Include matching skills in every spawn prompt. +- **Refusal rules:** + - You may NOT generate domain artifacts (code, designs, analyses) — spawn an agent + - You may NOT bypass reviewer approval on rejected work + - You may NOT invent facts or assumptions — ask the user or spawn an agent who knows + - You may NOT fill a skill gap by doing domain work yourself — grow the team or + route to the closest agent with disclosure +``` + +### What Changed + +| Aspect | Before | After | +|--------|--------|-------| +| Mindset | "What can I launch RIGHT NOW?" | "Read skills. Route broadly. Go." | +| Role | "Agent orchestration, handoff enforcement" | Added "skill-aware routing" | +| Inputs | No mention of skills | Explicitly lists skill directories | +| Outputs | "Final assembled artifacts" | "Routing decisions, assembled results" | +| Knowledge | Not mentioned | Explicit knowledge base reference + "check BEFORE routing" | +| Refusals | 3 rules | 4 rules — added skill gap refusal | + +The new mindset preserves ALL the eagerness (still ends with "Go.", still says "launch agents aggressively", still says "decompose broadly") but adds one step at the front: read your skills. The coordinator is just as fast and just as broad — it just knows what it knows before it routes. + +--- + +## E. The Eager Execution Rewrite + +### Current Section (lines 526-535) + +The Eager Execution Philosophy is **mostly correct**. "Launch aggressively, collect results later" — good. "Identify ALL agents who could usefully start work, including anticipatory downstream work" — good. The problem is that this philosophy has no guardrail against the coordinator doing domain work *itself* when it can't find an agent to route to. The eagerness is correct; the escape hatch is broken. + +### What Needs to Change + +The Eager Execution section needs ONE addition: a hard boundary between "eager routing" (good) and "eager domain work" (bad). The current text has: + +> When a task arrives, don't just identify the primary agent — identify ALL agents who could usefully start work right now, **including anticipatory downstream work**. + +This is correct. Keep it. But add after it: + +```markdown +**The coordinator routes eagerly. It never executes domain work eagerly.** If you +can't find an agent for a task, that's a signal to grow the team (see Skill Gap +Protocol), not to do the work yourself. Your eagerness is about ROUTING velocity +— spawning agents fast, in parallel, with full context. Not about filling gaps. +``` + +### What Stays the Same + +| Element | Status | +|---------|--------| +| "Launch aggressively, collect results later" | ✅ KEEP — this means launch AGENTS aggressively | +| "Identify ALL agents who could usefully start work" | ✅ KEEP — decompose broadly | +| "Including anticipatory downstream work" | ✅ KEEP — tester + implementer + docs in parallel = great | +| "Does this result unblock more work? If yes, launch follow-up agents" | ✅ KEEP — follow-up chaining is routing | +| Proactive work notation ("📌 Proactive: I wrote these test cases...") | ✅ KEEP — good transparency | + +### What Changes + +| Element | Change | +|---------|--------| +| No boundary between routing and domain work | ADD: explicit statement that eagerness applies to routing only | +| No skill-awareness in the eager execution flow | ADD: "Include matching skills in every spawn prompt" | +| No skill gap protocol | ADD: reference to Skill Gap Protocol when no agent matches | + +--- + +## F. Risk Assessment — Over-Correction Dangers + +### The "Too Passive" Risk + +If we over-correct, the coordinator becomes: +- A clerk that asks permission before every spawn +- Slow because it reads every skill before every task +- Annoying because it offers choices when the user wants action +- Timid about parallel fan-out, serializing work that should be concurrent + +**The line:** The coordinator should never ASK "should I spawn an agent?" for unambiguous work. If routing.md says Backend handles APIs and the user says "fix the API," spawn Backend. No questions. The pre-read protocol adds ~1 second of skill scanning, not a conversational round-trip. + +### The "Feels Heard" Risk + +Brady explicitly said "Feels Heard" is important. If the coordinator pauses to read skills before acknowledging, the user sees a blank screen. + +**Mitigation:** The pre-read protocol is internal deliberation, not visible delay. The coordinator still acknowledges immediately in the same response as the spawn. The sequence is: + +``` +[Internal: skill check — ~200ms of file reads] +[Output to user: "Fenster's on it — fixing the API endpoint."] +[Tool calls: task spawn(s)] +``` + +The user never sees the skill check. They see the acknowledgment at the same speed as before. + +### The "Skill Overload" Risk + +With 27 total skills (17 Copilot-level + 10 team-level), scanning ALL of them on every request would be wasteful. + +**Mitigation:** The coordinator doesn't read all skills — it scans skill NAMES (directory listing) and reads only matching ones. Most requests will match 0-1 skills. The release-process skill only matters for release requests. The git-workflow skill only matters for branching decisions. This is a directory listing + maybe one file read, not 27 file reads. + +### The "Ralph Exception" Risk + +Ralph's continuous loop is aggressive by design. If we apply the pre-read protocol to every Ralph cycle, we add latency to an automated loop. + +**Mitigation:** Ralph's work-check cycle already has a defined process (scan → categorize → act). The pre-read protocol applies to the INITIAL routing decision, not to Ralph's automated cycles. When Ralph is active, the coordinator is in "Ralph mode" — full anticipatory execution. The pre-read protocol governs normal interactive routing. + +### The Tension: "1-2 agents" vs. "Decompose broadly" + +The constraints section says "1-2 agents per question, not all of them" (line 1020). The Eager Execution section says "identify ALL agents who could usefully start work" (line 562). Brady's feedback is clear: decompose broadly is correct. More teammates involved = better. + +**Resolution:** The "1-2 agents" constraint should be updated to reflect the actual design intent. Proposed: **"Decompose broadly — involve every agent whose domain is touched. But every spawn must be a routed agent doing domain work, never the coordinator filling in."** The constraint isn't about agent count; it's about ensuring every agent earns its spawn through routing, not speculation. + +--- + +## G. Skills Inventory — What the Coordinator Has Been Ignoring + +### .copilot/skills/ — The Coordinator's Own Playbook (17 skills) + +These are foundational process knowledge. The coordinator should consult these BEFORE routing. + +| Skill | Critical for | Currently ignored when | +|-------|-------------|----------------------| +| `release-process` | Any publish/release request | Coordinator attempts releases without the validation checklist | +| `git-workflow` | Branch creation, PR workflow | Agents create branches without knowing the squad/{issue}-{slug} convention | +| `reviewer-protocol` | Any review/rejection cycle | Coordinator may route revision back to original author | +| `secret-handling` | Any work touching env vars or credentials | Agents may read .env files or commit secrets | +| `ci-validation-gates` | CI/CD operations, npm publishes | Skips semver validation, token type checks | +| `agent-collaboration` | Every agent spawn | Agents don't know the decisions inbox pattern | +| `agent-conduct` | Every agent spawn | Agents hardcode names in tests, skip quality checks | +| `history-hygiene` | Writing to history.md | Agents record intermediate requests instead of final outcomes | +| `squad-conventions` | Any code change in this repo | Agents don't follow zero-deps, Node test runner patterns | +| `cli-wiring` | Adding CLI commands | The recurring bug: implement without wiring | +| `model-selection` | Every spawn | Already inlined in the coordinator, but agents don't know the hierarchy | +| `init-mode` | Team creation | Already inlined, but useful as reference | +| `client-compatibility` | Cross-platform behavior | Already inlined | +| `architectural-proposals` | Design work | Agents write proposals without the standard format | +| `reskill` | Post-work optimization | Skills and charters grow without pruning | +| `github-multi-account` | Multi-account git operations | Coordinator doesn't detect account conflicts | +| `distributed-mesh` | Multi-squad coordination | Coordinator doesn't check mesh.json | + +### .squad/skills/ — Team-Earned Patterns (10 skills) + +These were discovered during work. They represent the team's institutional knowledge. + +| Skill | What it teaches | +|-------|----------------| +| `release-process` | Team-level release checklist (complements Copilot-level skill) | +| `model-selection` | 5-layer resolution with config.json (extends Copilot-level skill) | +| `session-recovery` | How to resume interrupted sessions | +| `personal-squad` | Ambient discovery of personal agents | +| `humanizer` | Tone enforcement for external communications | +| `gh-auth-isolation` | Multi-account GitHub authentication | +| `external-comms` | PAO workflow for public communications | +| `economy-mode` | Cost-saving model selection overrides | +| `cross-machine-coordination` | Ralph cross-machine task execution | +| `cross-squad` | Multi-squad delegation protocol | + +--- + +## H. Summary of Recommended Changes + +### Priority 1 — Identity Rewrite (Single biggest impact) +- Replace mindset: `"What can I launch RIGHT NOW?"` → `"Read skills. Route broadly. Go."` +- Add knowledge base reference to identity block +- Add skill-gap refusal rule +- Preserve ALL eagerness language around broad decomposition and parallel fan-out + +### Priority 2 — Pre-Read Protocol (Structural change) +- Add "Know Before You Go" checklist as the FIRST section under Team Mode routing +- Move skill-aware routing from addendum position to step 2 of the checklist +- Make skills an INPUT to routing decisions, not decoration on already-decided routes +- Step 5 explicitly says "Decompose broadly" — no reduction in agent involvement + +### Priority 3 — Eager Execution: Add the Guardrail (Surgical addition) +- KEEP "launch aggressively, collect results later" — unchanged +- KEEP "identify ALL agents who could usefully start work, including anticipatory downstream work" — unchanged +- ADD one new paragraph: "The coordinator routes eagerly. It never executes domain work eagerly." +- ADD skill references in spawn prompts so agents benefit from the playbook + +### Priority 4 — Skill Gap Protocol (New section) +- Add "Grow the Team" protocol for unmatched requests +- Offer choice: cast a specialist or route to closest match with disclosure +- Explicit refusal: coordinator may not fill gaps by doing domain work + +### Priority 5 — Constraint Reconciliation (Consistency fix) +- Update "1-2 agents per question" to match "decompose broadly" design intent +- Clarify: the constraint is on coordinator domain work, not on agent count + +--- + +*This analysis was produced by Procedures reading the full coordinator prompt (1298 lines), all 17 Copilot-level skills, and all 10 team-level skills. Every quote is cited to its source line in `.squad-templates/squad.agent.md`.* diff --git a/docs/src/content/docs/whatsnew.md b/docs/src/content/docs/whatsnew.md index 52155a152..86a899876 100644 --- a/docs/src/content/docs/whatsnew.md +++ b/docs/src/content/docs/whatsnew.md @@ -7,7 +7,58 @@ Full release history for Squad — from beta through the v1 TypeScript replatfor --- -## v0.8.2 — Current Release +## v0.9.1 — Current Release + +- **Shell agent name extraction** — Robust multi-pattern fallback for extracting agent names from shell transcripts (#577) +- **Init scaffolding** — `squad init --sdk` now scaffolds typed casting files; silences remote-lookup warnings (#579) +- **Personal squad global mode** — `squad personal init --global` auto-discovers `~/.config/squad/` (#576) +- **Release hardening** — CI playbook rewrite, publish policy linting, docs consistency checks (#564, #557) +- **Doctor improvements** — Actionable warnings and `squad.agent.md` existence checks (#565, #533) + +## v0.9.0 — Major Feature Release + +**Governance & Personal Squads** +- **Personal Squad concept** — Isolated developer workspace with own team.md, routing.md, and roster (#508) +- **Ambient discovery** — Auto-detect personal squad at `~/.squad/` via environment variables +- **Personal squad CLI** — Commands: `squad personal init`, `list`, `use`, `remove` (#508) +- **Governance isolation** — Hooks, ceremonies, telemetry scoped per personal squad (#508) + +**Worktree Spawning & Distributed Work** +- **Worktree creation** — Coordinator spawns managed worktrees for parallel agent work (#529) +- **Cross-squad orchestration** — Agents coordinate across multiple squads and worktrees (#446) +- **Persistent Ralph** — Long-running daemon with watch + heartbeat health monitoring (#443) +- **Worktree .git guard** — Regression detection for file vs directory confusion (#521) + +**Capability Discovery & Routing** +- **Machine capability inference** — Auto-detect available tools, models, hardware specs at session start (#514) +- **`needs:*` label routing** — Agents self-route based on discovered capabilities (#514) + +**Rate Limiting & Cost Control** +- **Cooperative rate limiting** — Predictive circuit breaker with token budget forecasting (#515) +- **Economy Mode** — Automatic cheaper-model selection when quality thresholds permit (#500) +- **Token usage tracking** — Per-agent cost visibility in session UI (#453) +- **Rate limit recovery** — Actionable error messages for quota pressure (#464) +- **Ralph circuit breaker** — Graceful degradation under model quota limits (#451) + +**Telemetry & Infrastructure** +- **Auto-wire telemetry** — `initSquadTelemetry()` now self-configures, no manual wiring (#281) +- **OpenTelemetry propagation** — Automatic context flow across squad sessions +- **Issue lifecycle template** — Standardized workflow (creation → triage → assignment → completion) (#527) +- **KEDA autoscaling template** — Kubernetes-based horizontal scaling for agent work (#516, #519) +- **GAP analysis verification** — After-work checklist ensures all requirements met before completion (#473) +- **Session recovery skill** — Find and resume lost sessions without restart (#442) +- **GitHub auth isolation skill** — Multi-account GitHub workflows (#470) + +**Docs, Stability & Distribution** +- **Astro site enhancements** — Search tuning, section badges, coverage indicators (#524) +- **Autonomous agents guide** — Comprehensive SDK guide for building agents (#492) +- **CLI terminal rendering** — Fixed scroll flicker, reduced re-render churn, stabilized component keys +- **Upgrade hardening** — Context-aware footers, EPERM handling, gitignore coverage (#544, #549) +- **ESM compatibility** — Node 22/24 dual-layer fix, Node 24+ hard-fail with guidance (#449, #502) +- **Signal handling** — SIGINT/SIGTERM graceful shutdown with 22+ regression tests (#486) +- **npm-only distribution** — Removed GitHub-native channel; standard npm registry install + +## v0.8.2 - **Version alignment** — CLI (0.8.1) and SDK (0.8.0) snapped to 0.8.2 across all packages - **Published to npm** — `@bradygaster/squad-sdk@0.8.2` and `@bradygaster/squad-cli@0.8.2` diff --git a/packages/squad-cli/src/cli/shell/index.ts b/packages/squad-cli/src/cli/shell/index.ts index e8be47775..5699fe4f4 100644 --- a/packages/squad-cli/src/cli/shell/index.ts +++ b/packages/squad-cli/src/cli/shell/index.ts @@ -148,7 +148,7 @@ export async function runShell(): Promise { // contexts (pipes, tests, CI) see useful guidance rather than a TTY error. const cwd = process.cwd(); const localSquad = resolveSquad(cwd); - const globalSquadDir = join(resolveGlobalSquadPath(), '.squad'); + const globalSquadDir = join(resolveGlobalSquadPath(), 'personal-squad'); const hasAnySquad = !!localSquad || existsSync(globalSquadDir); if (!hasAnySquad && !process.stdin.isTTY) { diff --git a/packages/squad-cli/templates/squad.agent.md b/packages/squad-cli/templates/squad.agent.md index f89682965..52af62b14 100644 --- a/packages/squad-cli/templates/squad.agent.md +++ b/packages/squad-cli/templates/squad.agent.md @@ -246,7 +246,11 @@ The routing table determines **WHO** handles work. After routing, use Response M | Ambiguous | Pick the most likely agent; say who you chose | | Multi-agent task (auto) | Check `ceremonies.md` for `when: "before"` ceremonies whose condition matches; run before spawning work | -**Skill-aware routing:** Before spawning, check `.squad/skills/` for skills relevant to the task domain. If a matching skill exists, add to the spawn prompt: `Relevant skill: .squad/skills/{name}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. +**Skill-aware routing:** Before spawning, check BOTH skill directories for skills relevant to the task domain: +1. `.copilot/skills/` — **Copilot-level skills.** Foundational process knowledge (release process, git workflow, reviewer protocol, etc.). These are the coordinator's own playbook — check first. +2. `.squad/skills/` — **Team-level skills.** Patterns and practices agents discovered during work. + +If a matching skill exists, add to the spawn prompt: `Relevant skill: {path}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. ### Consult Mode Detection @@ -357,8 +361,8 @@ Before spawning an agent, determine which model to use. Check these layers in or | Task Output | Model | Tier | Rule | |-------------|-------|------|------| -| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.5` | Standard | Quality and accuracy matter for code. Use standard tier. | -| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.5` | Standard | Prompts are executable — treat like code. | +| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.6` | Standard | Quality and accuracy matter for code. Use standard tier. | +| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.6` | Standard | Prompts are executable — treat like code. | | NOT writing code (docs, planning, triage, logs, changelogs, mechanical ops) | `claude-haiku-4.5` | Fast | Cost first. Haiku handles non-code tasks. | | Visual/design work requiring image analysis | `claude-opus-4.5` | Premium | Vision capability required. Overrides cost rule. | @@ -366,11 +370,11 @@ Before spawning an agent, determine which model to use. Check these layers in or | Role | Default Model | Why | Override When | |------|--------------|-----|---------------| -| Core Dev / Backend / Frontend | `claude-sonnet-4.5` | Writes code — quality first | Heavy code gen → `gpt-5.2-codex` | -| Tester / QA | `claude-sonnet-4.5` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` | +| Core Dev / Backend / Frontend | `claude-sonnet-4.6` | Writes code — quality first | Heavy code gen → `gpt-5.3-codex` | +| Tester / QA | `claude-sonnet-4.6` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` | | Lead / Architect | auto (per-task) | Mixed: code review needs quality, planning needs cost | Architecture proposals → premium; triage/planning → haiku | | Prompt Engineer | auto (per-task) | Mixed: prompt design is like code, research is not | Prompt architecture → sonnet; research/analysis → haiku | -| Copilot SDK Expert | `claude-sonnet-4.5` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` | +| Copilot SDK Expert | `claude-sonnet-4.6` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` | | Designer / Visual | `claude-opus-4.5` | Vision-capable model required | — (never downgrade — vision is non-negotiable) | | DevRel / Writer | `claude-haiku-4.5` | Docs and writing — not code | — | | Scribe / Logger | `claude-haiku-4.5` | Mechanical file ops — cheapest possible | — (never bump Scribe) | @@ -379,7 +383,7 @@ Before spawning an agent, determine which model to use. Check these layers in or **Task complexity adjustments** (apply at most ONE — no cascading): - **Bump UP to premium:** architecture proposals, reviewer gates, security audits, multi-agent coordination (output feeds 3+ agents) - **Bump DOWN to fast/cheap:** typo fixes, renames, boilerplate, scaffolding, changelogs, version bumps -- **Switch to code specialist (`gpt-5.2-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines) +- **Switch to code specialist (`gpt-5.3-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines) - **Switch to analytical diversity (`gemini-3-pro-preview`):** code reviews where a second perspective helps, security reviews, architecture reviews after a rejection **Layer 4 — Default:** If nothing else matched, use `claude-haiku-4.5`. Cost wins when in doubt, unless code is being produced. @@ -389,9 +393,9 @@ Before spawning an agent, determine which model to use. Check these layers in or If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the chain. Do NOT tell the user about fallback attempts. Maximum 3 retries before jumping to the nuclear fallback. ``` -Premium: claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.5 → (omit model param) -Standard: claude-sonnet-4.5 → gpt-5.2-codex → claude-sonnet-4 → gpt-5.2 → (omit model param) -Fast: claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini → (omit model param) +Premium: claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5 → (omit model param) +Standard: claude-sonnet-4.6 → claude-sonnet-4.5 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4 → (omit model param) +Fast: claude-haiku-4.5 → gpt-5.4-mini → gpt-5.1-codex-mini → gpt-4.1 → (omit model param) ``` `(omit model param)` = call the `task` tool WITHOUT the `model` parameter. The platform uses its built-in default. This is the nuclear fallback — it always works. @@ -415,7 +419,7 @@ prompt: | ... ``` -Only set `model` when it differs from the platform default (`claude-sonnet-4.5`). If the resolved model IS `claude-sonnet-4.5`, you MAY omit the `model` parameter — the platform uses it as default. +Only set `model` when it differs from the platform default (`claude-sonnet-4.6`). If the resolved model IS `claude-sonnet-4.6`, you MAY omit the `model` parameter — the platform uses it as default. If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely. @@ -424,7 +428,7 @@ If you've exhausted the fallback chain and reached nuclear fallback, omit the `m When spawning, include the model in your acknowledgment: ``` -🔧 Fenster (claude-sonnet-4.5) — refactoring auth module +🔧 Fenster (claude-sonnet-4.6) — refactoring auth module 🎨 Redfoot (claude-opus-4.5 · vision) — designing color system 📋 Scribe (claude-haiku-4.5 · fast) — logging session ⚡ Keaton (claude-opus-4.6 · bumped for architecture) — reviewing proposal @@ -435,9 +439,9 @@ Include tier annotation only when the model was bumped or a specialist was chose **Valid models (current platform catalog):** -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` +Premium: `claude-opus-4.6`, `claude-opus-4.6-1m` (Internal only), `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`, `gemini-3-pro-preview` +Fast/Cheap: `claude-haiku-4.5`, `gpt-5.4-mini`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1` ### Client Compatibility @@ -787,7 +791,9 @@ prompt: | Read .squad/decisions.md (team decisions to respect). If .squad/identity/wisdom.md exists, read it before starting work. If .squad/identity/now.md exists, read it at spawn time. - If .squad/skills/ has relevant SKILL.md files, read them before working. + Check .copilot/skills/ for copilot-level skills (process, workflow, protocol). + Check .squad/skills/ for team-level skills (patterns discovered during work). + Read any relevant SKILL.md files before working. {only if MCP tools detected — omit entirely if none:} MCP TOOLS: {service}: ✅ ({tools}) | ❌. Fall back to CLI when unavailable. diff --git a/packages/squad-sdk/src/sharing/consult.ts b/packages/squad-sdk/src/sharing/consult.ts index 2bd2d4fbf..f6ce8d12a 100644 --- a/packages/squad-sdk/src/sharing/consult.ts +++ b/packages/squad-sdk/src/sharing/consult.ts @@ -310,10 +310,10 @@ export interface SetupConsultModeResult { /** * Get the personal squad root path. - * Returns {globalSquadPath}/.squad/ + * Returns {globalSquadPath}/personal-squad/ */ export function getPersonalSquadRoot(): string { - return path.resolve(resolveGlobalSquadPath(), '.squad'); + return path.resolve(resolveGlobalSquadPath(), 'personal-squad'); } /** diff --git a/packages/squad-sdk/templates/squad.agent.md b/packages/squad-sdk/templates/squad.agent.md index f89682965..52af62b14 100644 --- a/packages/squad-sdk/templates/squad.agent.md +++ b/packages/squad-sdk/templates/squad.agent.md @@ -246,7 +246,11 @@ The routing table determines **WHO** handles work. After routing, use Response M | Ambiguous | Pick the most likely agent; say who you chose | | Multi-agent task (auto) | Check `ceremonies.md` for `when: "before"` ceremonies whose condition matches; run before spawning work | -**Skill-aware routing:** Before spawning, check `.squad/skills/` for skills relevant to the task domain. If a matching skill exists, add to the spawn prompt: `Relevant skill: .squad/skills/{name}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. +**Skill-aware routing:** Before spawning, check BOTH skill directories for skills relevant to the task domain: +1. `.copilot/skills/` — **Copilot-level skills.** Foundational process knowledge (release process, git workflow, reviewer protocol, etc.). These are the coordinator's own playbook — check first. +2. `.squad/skills/` — **Team-level skills.** Patterns and practices agents discovered during work. + +If a matching skill exists, add to the spawn prompt: `Relevant skill: {path}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. ### Consult Mode Detection @@ -357,8 +361,8 @@ Before spawning an agent, determine which model to use. Check these layers in or | Task Output | Model | Tier | Rule | |-------------|-------|------|------| -| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.5` | Standard | Quality and accuracy matter for code. Use standard tier. | -| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.5` | Standard | Prompts are executable — treat like code. | +| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.6` | Standard | Quality and accuracy matter for code. Use standard tier. | +| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.6` | Standard | Prompts are executable — treat like code. | | NOT writing code (docs, planning, triage, logs, changelogs, mechanical ops) | `claude-haiku-4.5` | Fast | Cost first. Haiku handles non-code tasks. | | Visual/design work requiring image analysis | `claude-opus-4.5` | Premium | Vision capability required. Overrides cost rule. | @@ -366,11 +370,11 @@ Before spawning an agent, determine which model to use. Check these layers in or | Role | Default Model | Why | Override When | |------|--------------|-----|---------------| -| Core Dev / Backend / Frontend | `claude-sonnet-4.5` | Writes code — quality first | Heavy code gen → `gpt-5.2-codex` | -| Tester / QA | `claude-sonnet-4.5` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` | +| Core Dev / Backend / Frontend | `claude-sonnet-4.6` | Writes code — quality first | Heavy code gen → `gpt-5.3-codex` | +| Tester / QA | `claude-sonnet-4.6` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` | | Lead / Architect | auto (per-task) | Mixed: code review needs quality, planning needs cost | Architecture proposals → premium; triage/planning → haiku | | Prompt Engineer | auto (per-task) | Mixed: prompt design is like code, research is not | Prompt architecture → sonnet; research/analysis → haiku | -| Copilot SDK Expert | `claude-sonnet-4.5` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` | +| Copilot SDK Expert | `claude-sonnet-4.6` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` | | Designer / Visual | `claude-opus-4.5` | Vision-capable model required | — (never downgrade — vision is non-negotiable) | | DevRel / Writer | `claude-haiku-4.5` | Docs and writing — not code | — | | Scribe / Logger | `claude-haiku-4.5` | Mechanical file ops — cheapest possible | — (never bump Scribe) | @@ -379,7 +383,7 @@ Before spawning an agent, determine which model to use. Check these layers in or **Task complexity adjustments** (apply at most ONE — no cascading): - **Bump UP to premium:** architecture proposals, reviewer gates, security audits, multi-agent coordination (output feeds 3+ agents) - **Bump DOWN to fast/cheap:** typo fixes, renames, boilerplate, scaffolding, changelogs, version bumps -- **Switch to code specialist (`gpt-5.2-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines) +- **Switch to code specialist (`gpt-5.3-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines) - **Switch to analytical diversity (`gemini-3-pro-preview`):** code reviews where a second perspective helps, security reviews, architecture reviews after a rejection **Layer 4 — Default:** If nothing else matched, use `claude-haiku-4.5`. Cost wins when in doubt, unless code is being produced. @@ -389,9 +393,9 @@ Before spawning an agent, determine which model to use. Check these layers in or If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the chain. Do NOT tell the user about fallback attempts. Maximum 3 retries before jumping to the nuclear fallback. ``` -Premium: claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.5 → (omit model param) -Standard: claude-sonnet-4.5 → gpt-5.2-codex → claude-sonnet-4 → gpt-5.2 → (omit model param) -Fast: claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini → (omit model param) +Premium: claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5 → (omit model param) +Standard: claude-sonnet-4.6 → claude-sonnet-4.5 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4 → (omit model param) +Fast: claude-haiku-4.5 → gpt-5.4-mini → gpt-5.1-codex-mini → gpt-4.1 → (omit model param) ``` `(omit model param)` = call the `task` tool WITHOUT the `model` parameter. The platform uses its built-in default. This is the nuclear fallback — it always works. @@ -415,7 +419,7 @@ prompt: | ... ``` -Only set `model` when it differs from the platform default (`claude-sonnet-4.5`). If the resolved model IS `claude-sonnet-4.5`, you MAY omit the `model` parameter — the platform uses it as default. +Only set `model` when it differs from the platform default (`claude-sonnet-4.6`). If the resolved model IS `claude-sonnet-4.6`, you MAY omit the `model` parameter — the platform uses it as default. If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely. @@ -424,7 +428,7 @@ If you've exhausted the fallback chain and reached nuclear fallback, omit the `m When spawning, include the model in your acknowledgment: ``` -🔧 Fenster (claude-sonnet-4.5) — refactoring auth module +🔧 Fenster (claude-sonnet-4.6) — refactoring auth module 🎨 Redfoot (claude-opus-4.5 · vision) — designing color system 📋 Scribe (claude-haiku-4.5 · fast) — logging session ⚡ Keaton (claude-opus-4.6 · bumped for architecture) — reviewing proposal @@ -435,9 +439,9 @@ Include tier annotation only when the model was bumped or a specialist was chose **Valid models (current platform catalog):** -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` +Premium: `claude-opus-4.6`, `claude-opus-4.6-1m` (Internal only), `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`, `gemini-3-pro-preview` +Fast/Cheap: `claude-haiku-4.5`, `gpt-5.4-mini`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1` ### Client Compatibility @@ -787,7 +791,9 @@ prompt: | Read .squad/decisions.md (team decisions to respect). If .squad/identity/wisdom.md exists, read it before starting work. If .squad/identity/now.md exists, read it at spawn time. - If .squad/skills/ has relevant SKILL.md files, read them before working. + Check .copilot/skills/ for copilot-level skills (process, workflow, protocol). + Check .squad/skills/ for team-level skills (patterns discovered during work). + Read any relevant SKILL.md files before working. {only if MCP tools detected — omit entirely if none:} MCP TOOLS: {service}: ✅ ({tools}) | ❌. Fall back to CLI when unavailable. diff --git a/templates/squad.agent.md b/templates/squad.agent.md index 0a9b173e9..2a8ffcf69 100644 --- a/templates/squad.agent.md +++ b/templates/squad.agent.md @@ -246,7 +246,11 @@ The routing table determines **WHO** handles work. After routing, use Response M | Ambiguous | Pick the most likely agent; say who you chose | | Multi-agent task (auto) | Check `ceremonies.md` for `when: "before"` ceremonies whose condition matches; run before spawning work | -**Skill-aware routing:** Before spawning, check `.squad/skills/` for skills relevant to the task domain. If a matching skill exists, add to the spawn prompt: `Relevant skill: .squad/skills/{name}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. +**Skill-aware routing:** Before spawning, check BOTH skill directories for skills relevant to the task domain: +1. `.copilot/skills/` — **Copilot-level skills.** Foundational process knowledge (release process, git workflow, reviewer protocol, etc.). These are the coordinator's own playbook — check first. +2. `.squad/skills/` — **Team-level skills.** Patterns and practices agents discovered during work. + +If a matching skill exists, add to the spawn prompt: `Relevant skill: {path}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. ### Consult Mode Detection @@ -357,8 +361,8 @@ Before spawning an agent, determine which model to use. Check these layers in or | Task Output | Model | Tier | Rule | |-------------|-------|------|------| -| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.5` | Standard | Quality and accuracy matter for code. Use standard tier. | -| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.5` | Standard | Prompts are executable — treat like code. | +| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.6` | Standard | Quality and accuracy matter for code. Use standard tier. | +| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.6` | Standard | Prompts are executable — treat like code. | | NOT writing code (docs, planning, triage, logs, changelogs, mechanical ops) | `claude-haiku-4.5` | Fast | Cost first. Haiku handles non-code tasks. | | Visual/design work requiring image analysis | `claude-opus-4.5` | Premium | Vision capability required. Overrides cost rule. | @@ -366,11 +370,11 @@ Before spawning an agent, determine which model to use. Check these layers in or | Role | Default Model | Why | Override When | |------|--------------|-----|---------------| -| Core Dev / Backend / Frontend | `claude-sonnet-4.5` | Writes code — quality first | Heavy code gen → `gpt-5.2-codex` | -| Tester / QA | `claude-sonnet-4.5` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` | +| Core Dev / Backend / Frontend | `claude-sonnet-4.6` | Writes code — quality first | Heavy code gen → `gpt-5.3-codex` | +| Tester / QA | `claude-sonnet-4.6` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` | | Lead / Architect | auto (per-task) | Mixed: code review needs quality, planning needs cost | Architecture proposals → premium; triage/planning → haiku | | Prompt Engineer | auto (per-task) | Mixed: prompt design is like code, research is not | Prompt architecture → sonnet; research/analysis → haiku | -| Copilot SDK Expert | `claude-sonnet-4.5` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` | +| Copilot SDK Expert | `claude-sonnet-4.6` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` | | Designer / Visual | `claude-opus-4.5` | Vision-capable model required | — (never downgrade — vision is non-negotiable) | | DevRel / Writer | `claude-haiku-4.5` | Docs and writing — not code | — | | Scribe / Logger | `claude-haiku-4.5` | Mechanical file ops — cheapest possible | — (never bump Scribe) | @@ -379,7 +383,7 @@ Before spawning an agent, determine which model to use. Check these layers in or **Task complexity adjustments** (apply at most ONE — no cascading): - **Bump UP to premium:** architecture proposals, reviewer gates, security audits, multi-agent coordination (output feeds 3+ agents) - **Bump DOWN to fast/cheap:** typo fixes, renames, boilerplate, scaffolding, changelogs, version bumps -- **Switch to code specialist (`gpt-5.2-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines) +- **Switch to code specialist (`gpt-5.3-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines) - **Switch to analytical diversity (`gemini-3-pro-preview`):** code reviews where a second perspective helps, security reviews, architecture reviews after a rejection **Layer 4 — Default:** If nothing else matched, use `claude-haiku-4.5`. Cost wins when in doubt, unless code is being produced. @@ -389,9 +393,9 @@ Before spawning an agent, determine which model to use. Check these layers in or If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the chain. Do NOT tell the user about fallback attempts. Maximum 3 retries before jumping to the nuclear fallback. ``` -Premium: claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.5 → (omit model param) -Standard: claude-sonnet-4.5 → gpt-5.2-codex → claude-sonnet-4 → gpt-5.2 → (omit model param) -Fast: claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini → (omit model param) +Premium: claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5 → (omit model param) +Standard: claude-sonnet-4.6 → claude-sonnet-4.5 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4 → (omit model param) +Fast: claude-haiku-4.5 → gpt-5.4-mini → gpt-5.1-codex-mini → gpt-4.1 → (omit model param) ``` `(omit model param)` = call the `task` tool WITHOUT the `model` parameter. The platform uses its built-in default. This is the nuclear fallback — it always works. @@ -415,7 +419,7 @@ prompt: | ... ``` -Only set `model` when it differs from the platform default (`claude-sonnet-4.5`). If the resolved model IS `claude-sonnet-4.5`, you MAY omit the `model` parameter — the platform uses it as default. +Only set `model` when it differs from the platform default (`claude-sonnet-4.6`). If the resolved model IS `claude-sonnet-4.6`, you MAY omit the `model` parameter — the platform uses it as default. If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely. @@ -424,7 +428,7 @@ If you've exhausted the fallback chain and reached nuclear fallback, omit the `m When spawning, include the model in your acknowledgment: ``` -🔧 Fenster (claude-sonnet-4.5) — refactoring auth module +🔧 Fenster (claude-sonnet-4.6) — refactoring auth module 🎨 Redfoot (claude-opus-4.5 · vision) — designing color system 📋 Scribe (claude-haiku-4.5 · fast) — logging session ⚡ Keaton (claude-opus-4.6 · bumped for architecture) — reviewing proposal @@ -435,9 +439,9 @@ Include tier annotation only when the model was bumped or a specialist was chose **Valid models (current platform catalog):** -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` +Premium: `claude-opus-4.6`, `claude-opus-4.6-1m` (Internal only), `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`, `gemini-3-pro-preview` +Fast/Cheap: `claude-haiku-4.5`, `gpt-5.4-mini`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1` ### Client Compatibility @@ -787,7 +791,9 @@ prompt: | Read .squad/decisions.md (team decisions to respect). If .squad/identity/wisdom.md exists, read it before starting work. If .squad/identity/now.md exists, read it at spawn time. - If .squad/skills/ has relevant SKILL.md files, read them before working. + Check .copilot/skills/ for copilot-level skills (process, workflow, protocol). + Check .squad/skills/ for team-level skills (patterns discovered during work). + Read any relevant SKILL.md files before working. {only if MCP tools detected — omit entirely if none:} MCP TOOLS: {service}: ✅ ({tools}) | ❌. Fall back to CLI when unavailable. diff --git a/test/cli-global.test.ts b/test/cli-global.test.ts index 0ecc8a553..e9d640d6b 100644 --- a/test/cli-global.test.ts +++ b/test/cli-global.test.ts @@ -48,30 +48,30 @@ describe('squad status routing logic', () => { scaffold('.git'); const repoSquad = resolveSquad(TMP); expect(repoSquad).toBeNull(); - // Without a global .squad/ dir, status shows "none" + // Without a global personal-squad/ dir, status shows "none" const globalPath = resolveGlobalSquadPath(); - const globalSquadDir = join(globalPath, '.squad'); - // When repo squad is null and global .squad doesn't exist → "none" + const globalSquadDir = join(globalPath, 'personal-squad'); + // When repo squad is null and global personal-squad doesn't exist → "none" const activeType = repoSquad ? 'repo' : existsSync(globalSquadDir) ? 'personal' : 'none'; expect(activeType).toBe(activeType === 'personal' ? 'personal' : 'none'); // At minimum, repoSquad must be null expect(repoSquad).toBeNull(); }); - it('identifies "personal" when no repo .squad/ but global .squad/ exists', () => { + it('identifies "personal" when no repo .squad/ but global personal-squad/ exists', () => { scaffold('.git'); const repoSquad = resolveSquad(TMP); expect(repoSquad).toBeNull(); const globalPath = resolveGlobalSquadPath(); - const globalSquadDir = join(globalPath, '.squad'); - // Create a .squad/ inside the global path + const globalSquadDir = join(globalPath, 'personal-squad'); + // Create a personal-squad/ inside the global path mkdirSync(globalSquadDir, { recursive: true }); const activeType = repoSquad ? 'repo' : existsSync(globalSquadDir) ? 'personal' : 'none'; expect(activeType).toBe('personal'); - // Cleanup global .squad dir we created + // Cleanup global personal-squad dir we created rmSync(globalSquadDir, { recursive: true, force: true }); }); @@ -79,7 +79,7 @@ describe('squad status routing logic', () => { scaffold('.git', '.squad'); const repoSquad = resolveSquad(TMP); const globalPath = resolveGlobalSquadPath(); - const globalSquadDir = join(globalPath, '.squad'); + const globalSquadDir = join(globalPath, 'personal-squad'); mkdirSync(globalSquadDir, { recursive: true }); // Same logic as status command — repo wins diff --git a/test/sdk/consult.test.ts b/test/sdk/consult.test.ts index f07f405de..15db12722 100644 --- a/test/sdk/consult.test.ts +++ b/test/sdk/consult.test.ts @@ -391,8 +391,26 @@ import { extractLearnings, loadSessionHistory, getPersonalSquadRoot, + resolveGlobalSquadPath, } from '@bradygaster/squad-sdk'; +// ============================================================================ +// getPersonalSquadRoot tests (#590) +// ============================================================================ + +describe('getPersonalSquadRoot', () => { + it('resolves to personal-squad subdirectory, not .squad', () => { + const root = getPersonalSquadRoot(); + const globalDir = resolveGlobalSquadPath(); + expect(root).toBe(join(globalDir, 'personal-squad')); + }); + + it('does not resolve to .squad subdirectory', () => { + const root = getPersonalSquadRoot(); + expect(root).not.toMatch(/[/\\]\.squad$/); + }); +}); + describe('setupConsultMode', () => { const SETUP_ROOT = join( process.cwd(),