From 87723979b93dccb4d14a88519942bb981da301ab Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Mon, 23 Mar 2026 15:17:57 -0700 Subject: [PATCH 1/7] =?UTF-8?q?chore(.squad):=20session=20wrap-up=20?= =?UTF-8?q?=E2=80=94=20inbox=20merge,=20logs,=20history=20updates?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Merged 12 decision inbox entries into decisions.md. Logged mega-session covering release recovery, docs fix, 10 PR merges, discussion triage, and release hardening. Updated agent histories with session learnings. Deleted inbox files after merge: - booster-ci-audit.md, booster-ci-cleanup.md - copilot-directive-2026-03-23T09-56.md, copilot-directive-2026-03-23T10-08.md - copilot-directive-no-npx.md - eecom-version-cmd.md - pao-discussion-triage-2026-03-23.md, pao-npx-purge.md, pao-readme-slim.md - pao-v090-blog.md - surgeon-v090-changelog.md, surgeon-v091-retrospective.md Updated files: - .squad/decisions.md (12 decision entries merged) - .squad/identity/now.md (current state updated) - .squad/log/2026-03-23T22-00-00Z-mega-session-wrapup.md (new) - .squad/agents/flight/history.md (issue filing patterns, governance directives) - .squad/agents/eecom/history.md (CLI version subcommand pattern) - .squad/agents/booster/history.md (CI audit and preflight patterns) - .squad/agents/surgeon/history.md (release governance rules, retrospective) - .squad/agents/pao/history.md (discussion triage patterns, Teams MCP urgency) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .squad/agents/booster/history.md | 15 + .squad/agents/eecom/history.md | 7 + .squad/agents/flight/history.md | 8 + .squad/agents/pao/history.md | 65 ++++ .squad/agents/surgeon/history.md | 27 ++ .squad/decisions.md | 244 +++++++++++++ .squad/decisions/inbox/booster-ci-audit.md | 238 ------------ .squad/decisions/inbox/booster-ci-cleanup.md | 28 -- .../copilot-directive-2026-03-23T10-08.md | 12 - .../inbox/copilot-directive-no-npx.md | 5 - .squad/decisions/inbox/eecom-version-cmd.md | 19 - .squad/decisions/inbox/pao-npx-purge.md | 29 -- .squad/decisions/inbox/pao-readme-slim.md | 23 -- .squad/decisions/inbox/pao-v090-blog.md | 61 ---- .../decisions/inbox/surgeon-v090-changelog.md | 95 ----- .../inbox/surgeon-v091-retrospective.md | 340 ------------------ .squad/identity/now.md | 174 +++++---- .../log/2026-03-23T00-39-00Z-mega-session.md | 89 ----- .../orchestration-log/2026-03-22-session-2.md | 47 --- .squad/orchestration-log/2026-03-22T23-10.md | 1 - .../2026-03-22T23-30-session-complete.md | 35 -- ...3T00-39-00Z-eecom-498-vcs-removal-audit.md | 29 -- ...3-23T00-39-00Z-eecom-528-ralph-commands.md | 30 -- ...23T00-39-00Z-eecom-530-worktree-cleanup.md | 30 -- .../2026-03-23T00-39-00Z-eecom-cli-surface.md | 32 -- ...26-03-23T00-39-00Z-eecom-sdk-foundation.md | 32 -- .../2026-03-23T00-39-00Z-fido-tests.md | 29 -- ...26-03-23T00-39-00Z-flight-531-heuristic.md | 29 -- ...03-23T00-39-00Z-flight-533-doctor-issue.md | 29 -- ...23T00-39-00Z-flight-issue-decomposition.md | 28 -- ...0-39-00Z-procedures-527-issue-lifecycle.md | 28 -- ...00Z-procedures-529-coordinator-worktree.md | 28 -- ...6-03-23T00-39-00Z-procedures-governance.md | 31 -- 33 files changed, 471 insertions(+), 1446 deletions(-) delete mode 100644 .squad/decisions/inbox/booster-ci-audit.md delete mode 100644 .squad/decisions/inbox/booster-ci-cleanup.md delete mode 100644 .squad/decisions/inbox/copilot-directive-2026-03-23T10-08.md delete mode 100644 .squad/decisions/inbox/copilot-directive-no-npx.md delete mode 100644 .squad/decisions/inbox/eecom-version-cmd.md delete mode 100644 .squad/decisions/inbox/pao-npx-purge.md delete mode 100644 .squad/decisions/inbox/pao-readme-slim.md delete mode 100644 .squad/decisions/inbox/pao-v090-blog.md delete mode 100644 .squad/decisions/inbox/surgeon-v090-changelog.md delete mode 100644 .squad/decisions/inbox/surgeon-v091-retrospective.md delete mode 100644 .squad/log/2026-03-23T00-39-00Z-mega-session.md delete mode 100644 .squad/orchestration-log/2026-03-22-session-2.md delete mode 100644 .squad/orchestration-log/2026-03-22T23-10.md delete mode 100644 .squad/orchestration-log/2026-03-22T23-30-session-complete.md delete mode 100644 .squad/orchestration-log/2026-03-23T00-39-00Z-eecom-498-vcs-removal-audit.md delete mode 100644 .squad/orchestration-log/2026-03-23T00-39-00Z-eecom-528-ralph-commands.md delete mode 100644 .squad/orchestration-log/2026-03-23T00-39-00Z-eecom-530-worktree-cleanup.md delete mode 100644 .squad/orchestration-log/2026-03-23T00-39-00Z-eecom-cli-surface.md delete mode 100644 .squad/orchestration-log/2026-03-23T00-39-00Z-eecom-sdk-foundation.md delete mode 100644 .squad/orchestration-log/2026-03-23T00-39-00Z-fido-tests.md delete mode 100644 .squad/orchestration-log/2026-03-23T00-39-00Z-flight-531-heuristic.md delete mode 100644 .squad/orchestration-log/2026-03-23T00-39-00Z-flight-533-doctor-issue.md delete mode 100644 .squad/orchestration-log/2026-03-23T00-39-00Z-flight-issue-decomposition.md delete mode 100644 .squad/orchestration-log/2026-03-23T00-39-00Z-procedures-527-issue-lifecycle.md delete mode 100644 .squad/orchestration-log/2026-03-23T00-39-00Z-procedures-529-coordinator-worktree.md delete mode 100644 .squad/orchestration-log/2026-03-23T00-39-00Z-procedures-governance.md diff --git a/.squad/agents/booster/history.md b/.squad/agents/booster/history.md index 614cca253..9465240c7 100644 --- a/.squad/agents/booster/history.md +++ b/.squad/agents/booster/history.md @@ -4,6 +4,21 @@ ## Learnings +### CI Workflow Audit & Preflight Patterns (2026-03-23 Release Incident) +**Context:** v0.9.0 shipped with broken dependency reference (`file:../squad-sdk` in CLI package.json). Required hotfix. Used incident as opportunity to audit entire CI/CD system. + +**Audit findings:** 15 total workflow files. 7 load-bearing (ci, publish, release, preview, promote, insider variants). 7 administrative (triage, assign, labels, heartbeat, docs, link-check). 1 ghost (publish-npm.yml, deleted but GitHub index cached). No duplication. Authorship: 65% Brady, 10% Copilot (v0.9.1 scramble), 25% team. + +**Key patterns identified:** +- Preflight gate (dependency scanning + semver validation) prevents dependency defects +- Implicit ordering risk: squad-release and squad-npm-publish both trigger on `release: published` with no explicit job dependency (works but fragile) +- Ghost workflow cleanup: GitHub's workflow index caches file names; deletion doesn't immediately invalidate; must wait 15+ minutes or manually refresh + +**Preflight job pattern:** Scans `packages/*/package.json` for: +1. `file:` references (breaks published packages) +2. Invalid semver versions (rejects malformed versions) +Runs before smoke-test and all publish operations. Zero-cost gate (JSON reads only). Clear error messages with remediation instructions. + ### CI Pipeline Status 149 test files, 3,931 tests passing, ~89s runtime. Only failure: aspire-integration.test.ts (needs Docker daemon — pre-existing, expected). publish.yml triggers on `release: published` event with retry logic for npm registry propagation (5 attempts, 15s sleep). diff --git a/.squad/agents/eecom/history.md b/.squad/agents/eecom/history.md index 1dcff2c88..e89202bf4 100644 --- a/.squad/agents/eecom/history.md +++ b/.squad/agents/eecom/history.md @@ -4,6 +4,13 @@ ## Learnings +### CLI Version Subcommand Pattern (2026-03-23 Release Incident) +**Context:** `squad version` returned "Unknown command: version" even though `squad --version` and `squad -v` worked fine. Classic "unwired command" bug but for a flag-to-subcommand gap rather than a missing import. + +**Pattern:** When a CLI flag works (`--foo`) but the equivalent subcommand doesn't (`foo`), the fix is almost always a single condition addition in `cli-entry.ts`. No separate command file needed for trivial handlers — inline alongside the flag handler. Added `cmd === 'version'` to the existing `--version`/`-v` condition. Also added `version` to help text command list. + +**Why inline works:** Trivial handlers that just print a value don't warrant their own module. Same output, same code path — no reason to split. Avoids adding a file the wiring test would require an import for. Precedent: `help` is also handled inline. + ### `squad version` subcommand (2026-07-15) **Context:** Running `squad version` returned "Unknown command: version" because the subcommand was never routed in `cli-entry.ts`, even though `--version` and `-v` flags worked fine. Classic "unwired command" bug class, but for a flag-to-subcommand gap rather than a missing import. diff --git a/.squad/agents/flight/history.md b/.squad/agents/flight/history.md index 88463d4e3..93c13e2b3 100644 --- a/.squad/agents/flight/history.md +++ b/.squad/agents/flight/history.md @@ -4,6 +4,8 @@ --- +📌 **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. ## Core Context @@ -12,6 +14,12 @@ Three-branch model (main/dev/insiders). Apollo 13 team, 3931 tests. Boundary rev ## Learnings +### Issue Filing Patterns (2026-03-23 Release Incident) +When a major incident occurs, file 9+ GitHub issues documenting root causes and improvements. Pattern: one issue per root cause + one per action item. Use descriptive titles linking to specific improvements (e.g., "#556 Dependency validation in pre-publish checks"). Let team pick up issues in priority order. This accelerates fixes and creates accountability. + +### Release Governance Directives (2026-03-23) +Brady established strict release governance: (1) Surgeon owns all publishing (not Coordinator); (2) strict adherence to playbook; (3) document problems so they don't recur; (4) CI/CD is top priority; (5) written playbooks for everything; (6) no improvisation. Captured for team memory and enforced in team decisions. + ### Adoption Tracking Architecture Three-tier opt-in system: Tier 1 (aggregate-only, `.github/adoption/`) ships first; Tier 2 (opt-in registry) designed next; Tier 3 (public showcase) launches when ≥5 projects opt in. `.squad/` is for team state only, not adoption data. Never list individual repos without owner consent. diff --git a/.squad/agents/pao/history.md b/.squad/agents/pao/history.md index 03fcbd6b9..7d6d7cab0 100644 --- a/.squad/agents/pao/history.md +++ b/.squad/agents/pao/history.md @@ -8,6 +8,29 @@ Docs live in docs/ with blog/, concepts/, cookbook/, getting-started/, guide/, f ## Learnings +### Discussion Triage Patterns (2026-03-23 Release Incident) +**Context:** v0.9.1 release completed; 15 open discussions analyzing whether community response patterns matched feature releases. + +**Pattern identified:** Feature releases without follow-up discussion closes = missed trust opportunity. When you ship features (personal squad, worktrees, economy mode, rate limiting), search discussions for matching feature-requests → respond + close proactively. This signals to community that you listen. + +**Triage workflow:** +1. Map new features to open discussions (which discussions are solved by this release?) +2. Respond: "This feature is now available in v0.9.1. See docs link." +3. Close as resolved +4. Consolidate: if discussion #463 is duplicate of #402, merge responses into #402, close #463 +5. Convert: if discussion reveals a bug or roadmap item, convert to issue with label (e.g., squad:eecom) +6. Keep: if discussion is feedback or edge case, keep open; respond substantively + +**For v0.9.1 release:** 4 closed, 1 consolidated, 2 converted to issue, 8 kept. Result: community sees responsiveness; discussions become productivity tool, not backlog. + +**Critical finding:** Teams MCP docs need urgent update — Office 365 Connectors deprecated Dec 2024. Docs must purge old connector references and document Power Automate Workflows path (new successor). + +### Chinese README Workflow (2026-03-23 Release Incident) +Community contributor (PR #572) provided Chinese README translation. Approved and merged as part of v0.9.1 release. Pattern: accept community translations; list contributors in CONTRIBUTORS.md; acknowledge in release notes. + +### Teams MCP Urgency Pattern (2026-03-23) +External tool integrations deprecate. Office 365 Connectors retired Dec 2024. Docs mentioning deprecated tools create support burden and user confusion. Action: audit all external tool integration docs for deprecation; update with successor guidance (Power Automate Workflows for Teams). + ### Blog Post Format YAML frontmatter: title, date, author, wave, tags, status, hero. Body: experimental warning, What Shipped, Why This Matters, Quick Stats, What's Next. 200-400 words for infrastructure releases. No hype — explain value. @@ -97,3 +120,45 @@ Brady directive: README was too long at 512 lines. Cut the SDK deep-dive block ( ### v0.9.0 Release Blog Post (2026-03-23) Created `docs/src/content/blog/028-v090-whats-new.md` documenting Squad's biggest release: Personal Squad (ambient agent discovery + Ghost Protocol), Worktree Spawning (isolated branches per issue), Machine Capability Discovery (needs:* label routing), Cooperative Rate Limiting (predictive circuit breaker), Economy Mode (budget-aware model selection), Auto-Wired Telemetry, P0 upgrade fixes, and docs refresh. Blog format: frontmatter (title/date/author/wave/tags/status/hero) → experimental warning → "What Shipped" (10 features with H2 sections + callout boxes) → "Quick Stats" → "Breaking Changes" (none) → "Upgrading" → "What's Next". Messaging: clear, engaging, factual (no marketing fluff). Demonstrated: Personal Squad governance layer, worktree isolation, capability declaration, RAAS traffic-light pattern, economy fallback logic. Docs refresh section emphasized: README from 512→218 lines, dedicated upgrade guide, npx purged, Astro features, Teams MCP refresh, autonomous agents guide. Contributors: diberry (worktree tests + docs), wiisaacs (security review), community. No breaking changes — all additive opt-in features. Test discovery is dynamic (EXPECTED_BLOG uses filesystem scan), so new post auto-discovered; no test file changes needed. Pattern reinforced: each feature needs a story — if you can't explain it, it's not ready. Demos over descriptions (concrete code examples, YAML config blocks, Bash CLI examples). + +### Discussion Triage (2026-03-23) + +Analyzed 15 open discussions for response strategy: +- **4 close-as-resolved** (#143, #169 — features now shipped; #402, #299 — answered with docs links) +- **1 close-as-duplicate** (#463 → #402) +- **2 convert-to-issue** (#161 root-copilot-hijack → bug/UX track; #534 enterprise-features → ongoing roadmap signal) +- **8 keep-open** (ongoing feedback, feature signals, edge cases, follow-up potential) + +Key pattern: 15 discussions = 7 feature-request/feedback signals, 4 answered-by-feature-release, 4 documentation-clarity gaps. Community is engaged; v0.9.1 (per-agent models, skills system, human team members, watch mode) directly addressed 5+ discussions that were open for 2-4 weeks. Timing of releases + follow-up responses critical for community trust. + +**Documentation gaps identified:** +- #440 (branch naming convention change) — needs migration guide in upgrade docs +- #306 (multi-root workspaces) → future feature; docs should clarify current limitation +- #140 (Teams MCP + Office 365 Connectors retirement) → docs refresh needed; Power Automate Workflows is the new path +- #401 (mobile/remote control) → feature exploration, keep on radar +- #161 (Coordinator hijacking) → document workarounds, prioritize UX fix for v1.0 + +Teams MCP critical update: Office 365 Connectors retired Dec 2024 → Power Automate Workflows is successor. Docs mention of old Connectors should be purged; Teams webhook examples should link to Power Automate Workflow guide. + +### Community Engagement Wave (2026-03-24) + +**6 discussions closed as resolved:** +- #463, #402 (per-agent model selection — shipped v0.9.1) +- #324 (local-only operation without GitHub integration) +- #299 (CLI vs Copilot agent — both viable) +- #143 (Human team members now first-class feature) +- #169 (Skills system shipped as core infrastructure) + +**8 discussions kept open with substantive replies:** +- #534 (enterprise features) — asked clarifying questions on scope +- #499 (Brady's v1.0 announcement) — explained `.squad/` regenerability plan +- #440 (branch naming change) — acknowledged disruption, offered migration guidance +- #401 (mobile/async control) — acknowledged use case, roadmap signal +- #376 (best practices) — provided triage and routing patterns +- #306 (multi-root support) — acknowledged limitation, kept open for feedback +- #95 (casting system) — explained mature re-casting flow +- #140 (Teams MCP) — critical guidance on Office 365 Connectors retirement → Power Automate Workflows + +**Pattern observed:** Feature-release timing + follow-up responses critical for community trust. v0.9.1 directly addressed 5+ discussions (models, skills, human members) that were open 2-4 weeks. Community triage now operational: 14 discussions reviewed, 6 closed, 8 kept active = 43% closure rate on resolved items. + +**Key insight:** Retirement of Microsoft Office 365 Connectors (Dec 2024) caught users mid-setup. Proactive notification of Teams Workflows alternative + Power Automate guidance essential for Teams MCP users. diff --git a/.squad/agents/surgeon/history.md b/.squad/agents/surgeon/history.md index b205b4114..dfea0980b 100644 --- a/.squad/agents/surgeon/history.md +++ b/.squad/agents/surgeon/history.md @@ -4,6 +4,33 @@ ## Learnings +### Release Governance Rules (2026-03-23 v0.9.0→v0.9.1 Incident) +**Context:** v0.9.0 published with critical defect (CLI package had local monorepo reference instead of registry version). v0.9.1 hotfix prepared in minutes; publish workflow infrastructure collapsed (GitHub cache race + npm automation issue + 2FA hang), extending 10-minute fix to 8-hour incident. + +**Governance rules established:** +1. **Surgeon owns all publishing.** Not Coordinator, not user. All release work routed to Surgeon. Coordinator escalates on failures. +2. **Strict process adherence.** Same playbook every time. No improvisation. Written checklists mandatory. +3. **Document to prevent recurrence.** If same problem happens twice, documentation failed. Root cause analysis + action items for every incident. +4. **CI/CD is top priority.** Release quality determines team effectiveness. Invest in automation, testing, pre-flight validation. +5. **Pre-flight gates mandatory.** Before any release tagging: validate dependencies, run smoke tests, verify versions, check 2FA settings, run dry-run installs. +6. **Escalation protocol.** If workflow fails twice, switch to local publish immediately. Two fallback paths: primary (CI/CD) + fallback (local), both documented. + +**Action items (A1–A6):** +- A1: Dependency validation in publish workflow (scan for `file:` refs, npm install dry-run) +- A2: npm workspace publish policy (never `-w` for publish; 2FA auth-only) +- A3: GitHub workflow cache mitigation (15+ min wait documented, escalation runbook) +- A4: Publish fallback protocol (switch to local on 2nd failure) +- A5: Release readiness checklist (pre-flight validation before tagging) +- A6: Post-publish smoke test (mandatory global install verification) + +**Release process skill created:** `.squad/skills/release-process/SKILL.md` documents all patterns and procedures. + +### v0.9.0 CHANGELOG Organization (2026-03-23) +v0.9.0 is MAJOR minor bump (0.8.25 → 0.9.0) justified by 40+ commits, 6+ major features, governance layer, breaking behavioral changes. Organized by feature cluster (not chronological): +- Personal Squad, Worktree, Machine Capability Discovery, Rate Limiting, Economy Mode, Telemetry, Templates, Skills, Docs, ESLint patterns +- 12 feature sections + 5 fix categories +Strict format adherence: matched existing CHANGELOG headers, `### Added` pattern, PR refs (#NNN), grouped by domain. No npx, no "agency" terminology. + ### Release History v0.8.24 released successfully. npm packages: @bradygaster/squad-sdk@0.8.24, @bradygaster/squad-cli@0.8.24. publish.yml triggers on `release: published` (NOT draft). Test baseline at release: 3,931 tests, 149 files. diff --git a/.squad/decisions.md b/.squad/decisions.md index de755ceb3..4c8e0826f 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -4870,6 +4870,250 @@ Created `.squad/skills/release-process/SKILL.md` with the definitive step-by-ste **Before ANY version commit:** ```bash + +--- + +## Release Crisis Resolution & Governance Hardening (2026-03-23) + +### CI Workflow Audit & Ghost Cleanup (Booster) +**Date:** 2026-03-23 +**What:** Complete audit of 15 GitHub Actions workflows in `.github/workflows/`. Found: 7 essential load-bearing workflows, 7 administrative workflows, 1 ghost (publish-npm.yml, deleted but GitHub index cached), 0 duplication. Authorship: 65% Brady, 10% Copilot (v0.9.1 scramble), 25% team. CI is lean and well-organized. + +**Action Items:** +- [ ] Delete ghost `publish-npm.yml` workflow via GitHub API or UI +- [ ] Decide: keep or delete optional `ci-rerun.yml` (useful but not essential) +- [ ] Document release pipeline in CONTRIBUTING.md +- [ ] Enable Ralph's heartbeat cron if periodic triage desired (currently event-driven only) + +**Key Patterns:** +- Load-bearing: squad-ci, squad-npm-publish, squad-insider-publish, squad-release, squad-preview, squad-promote, squad-insider-release +- Administrative: squad-triage, squad-issue-assign, squad-label-enforce, sync-squad-labels, squad-heartbeat, squad-docs, squad-docs-links +- Identified potential weakness: `squad-release` and `squad-npm-publish` both trigger on `release: published` with no explicit job dependency — works but fragile + +--- + +### Pre-Publish Preflight Job (Booster) +**Date:** 2026-03-23 +**Status:** Implemented in squad-npm-publish.yml +**What:** Added `preflight` job that runs BEFORE smoke-test and all publish operations. Scans all `packages/*/package.json` for: +1. `file:` references in any dependency section (breaks published packages) +2. Invalid semver versions (rejects 4-part versions, absolute paths) + +**Rationale:** Zero-cost gate (JSON file reads only). Prevents exact class of bug that broke v0.9.0. Fails fast with clear error messages. Defense in depth: preflight catches source issues, smoke-test catches packaging issues. + +**Impact:** All squad members — publish pipeline will reject any PR that accidentally leaves `file:` references. No team changes needed; this is passive safety. + +--- + +### `squad version` Subcommand Handler (EECOM) +**Date:** 2026-07-15 +**What:** `squad version` returned "Unknown command" while `squad --version` worked. Fixed by handling `version` inline in `cli-entry.ts` alongside `--version`/`-v` flag, rather than creating a separate command file. + +**Rationale:** Trivial handlers that just print a value don't warrant their own module. Same output, same code path — no reason to split. Avoids adding a file the wiring test would require an import for. Follows precedent: `help` is also inline. + +**Pattern:** CLI flag (`--foo`) works but subcommand (`foo`) doesn't? Check `cli-entry.ts` routing first before creating new command files. + +--- + +### User Directive: Surgeon Owns All Publishing (Brady via Copilot) +**Date:** 2026-03-23T09-56Z +**What:** "I always want the squad to facilitate this for me" — all publishing, deployments, and release processes must be driven by squad agents (primarily Surgeon), not by Coordinator or user manually. + +**Why:** User request — captured for team memory. + +**Implementation:** Surgeon charter updated with release governance. Coordinator escalates to Surgeon on publish failures. All release work goes through Surgeon. + +--- + +### User Directives: Release Governance (Brady) +**Date:** 2026-03-23T10-08Z +**What:** Batch of release governance directives: +1. Coordinator should NOT be doing releases. Releases are Brady's responsibility. He will be explicit about when to release. +2. Strict adherence to the exact same release process every time. No improvisation. +3. Document problems thoroughly enough to avoid repeating them. If the same problem recurs, it means documentation failed. +4. CI/CD and release quality is the top priority for the next release cycle. +5. Session conversation history from release scrambles should be scrubbed — file issues instead of preserving messy logs. +6. Every release must follow a written, step-by-step playbook. No ad-hoc releases. + +**Why:** v0.9.0→v0.9.1 release incident burned ~8 hours and excessive Actions minutes. Brady establishing strict governance to prevent recurrence. + +**Implementation:** +- Surgeon owns all release automation, including pre-publish validation and fallback procedures +- Pre-release checklists mandatory (A5 in retrospective) +- PUBLISH-README.md updated with runbook and all release knowledge +- Release process skill created at `.squad/skills/release-process/SKILL.md` + +--- + +### Distribution Policy: npm-only (Brady via PAO) +**Date:** 2026-03-23T00-17-57Z +**What:** Stop mentioning npx in README, docs, and all user-facing content. Distribution is npm install -g only. + +**Why:** npx path is deprecated, causes confusion. Streamline to single distribution method. + +**Implementation:** +- Removed all `npx @bradygaster/squad-cli` alternatives from user-facing docs +- Replaced with `npm install -g @bradygaster/squad-cli` for install; `squad ` for usage +- Insider builds: `npm install -g @bradygaster/squad-cli@insider` + `squad upgrade` +- Removed "npx github: hang" troubleshooting section (deprecated path gone) +- Removed "npx cache serving stale version" troubleshooting (no longer applicable) + +**What was NOT changed:** +- `npx` for dev tools (changeset, vitest, astro, pagefind) — not Squad CLI +- Blog posts (historical content reflects what was true at time) +- Migration.md "Before" column (valid historical context) +- `agency-agents` attribution strings in source (MIT license requirement) + +--- + +### README Slim-Down: Orientation, Not SDK Reference (PAO) +**Date:** 2026-03-23 +**What:** README's role is discovery and quick-start, NOT SDK internals. Moved SDK deep-dive (custom tools, hook pipeline, Ralph API, architecture) to docs site where it already exists. + +**Rationale:** README had grown to 512 lines — ~212 were SDK internal docs duplicating `docs/src/content/docs/reference/`. New users got overwhelmed before running `squad init`. Brady confirmed: "QUITE long." + +**Changes:** +- Removed lines 300–512 (SDK internals) from README +- Added compact SDK docs pointer linking to `reference/sdk.md`, `reference/tools-and-hooks.md`, `guide/extensibility.md` +- Added dedicated "Upgrading" section after Quick Start +- README: 512 → 331 lines + +**Rule going forward:** SDK API surface, hook pipeline internals, event-driven code examples — go in `docs/`, not README. README links out; it doesn't host. + +--- + +### v0.9.0 Release Blog Post (PAO) +**Date:** 2026-03-23 +**Status:** Complete, ready for merge +**What:** Comprehensive blog post documenting Squad's biggest release to date. 10 features with storytelling format: +1. What it does (one-line value prop) +2. Why it matters (the problem it solves) +3. How it works (code or config example) +4. Real-world scenario (where you'd use it) + +**Features covered:** +- Personal Squad (ambient discovery + Ghost Protocol) +- Worktree Spawning (parallel issue work without blocking) +- Cooperative Rate Limiting (green/amber/red traffic-light coordination) +- Economy Mode (budget-aware fallback, 40–60% spend reduction) +- + 6 more major features + +**Tone:** Factual, not hype. "40–60% spend reduction" vs "Amazing cost savings!" Demos over descriptions. Callout boxes for highlights. Community recognition included. + +**No npx:** All install references use `npm install -g @bradygaster/squad-cli`. Firm per Brady's distribution directive. + +**Breaking changes:** None — all opt-in. Existing Squads work as-is. + +**Community attribution:** diberry (worktree tests), wiisaacs (security review), williamhallatt (test contributions), bradygaster (leadership). + +--- + +### v0.9.0 CHANGELOG Organization (Surgeon) +**Date:** 2026-03-23 +**Status:** Final +**What:** v0.9.0 is MAJOR minor bump (0.8.25 → 0.9.0) justified by 40+ commits, 6+ major features, governance-layer additions, breaking behavioral changes. + +**Organization (by feature cluster, not chronological):** +- Personal Squad Governance Layer +- Worktree Spawning & Orchestration +- Machine Capability Discovery +- Cooperative Rate Limiting +- Economy Mode +- Auto-Wire Telemetry +- Issue Lifecycle Template +- KEDA External Scaler Template +- GAP Analysis Verification Loop +- Session Recovery Skill +- Token Usage Visibility +- GitHub Auth Isolation Skill +- Docs Site Improvements (Astro) +- Skill Migrations +- ESLint Runtime Anti-Pattern Detection + +**Fixes (5 sections):** +- CLI Terminal Rendering +- Upgrade Path & Installation +- ESM Compatibility +- Runtime Stability +- GitHub Integration + +**Style compliance:** Strict adherence to existing CHANGELOG format. Matched headers, `### Added` pattern, PR references (#NNN), no commit hashes, grouped by domain. No npx mentions. No "agency" terminology in product context. + +--- + +### v0.9.0 → v0.9.1 Release Retrospective (Surgeon) +**Date:** 2026-03-23 +**Executive Summary:** v0.9.0 published with critical defect — CLI package.json contained `"@bradygaster/squad-sdk": "file:../squad-sdk"` (local monorepo reference instead of registry version). Package broken on global install. v0.9.1 hotfix prepared in minutes; publish workflow collapsed due to cascading infrastructure failures, extending incident from 10 minutes to 8 hours. + +**Root Causes (5 identified):** + +1. **Dependency Validation Gap (Preventable)** — npm workspaces auto-rewrite `"*"` → `"file:../path"`. Persisted in committed package.json. No pre-publish check caught it. FIX: Preflight job scans for `file:` refs and validates semver. + +2. **GitHub Actions Workflow Cache Race (Infrastructure)** — After deleting `squad-publish.yml`, GitHub workflow index didn't refresh for 10+ minutes. 422 error persisted even after file deletion. Infrastructure bug, not your code. FIX: Documented in runbook; escalation protocol (if workflow_dispatch fails twice, switch to local publish). + +3. **npm Workspace Publish Broken (Tool Gap)** — `npm -w packages/squad-sdk publish` hangs indefinitely when npm 2FA set to `auth-and-writes` (needs OTP from authenticator app). Local machine without authenticator becomes soft hang. FIX: Policy — 2FA must be `auth-only`; always `cd` into package directory for publish. + +4. **Coordinator Decision-Making Under Pressure (Process)** — Retried `workflow_dispatch` 4+ times instead of pivoting to local publish fallback. Burned critical time on GitHub UI file operations. FIX: Escalation protocol — if `workflow_dispatch` fails twice, invoke local publish immediately. Release Manager owns all publish automation. + +5. **No Pre-Publish Verification (Process)** — No smoke test or dependency validation before publishing to npm. Package could ship broken. FIX: Preflight + smoke test jobs added; post-publish global install verification mandatory. + +**Action Items (A1–A6):** +- A1: Add dependency validation to publish workflow (scan for `file:` refs, npm install dry-run) +- A2: Establish npm workspace publish policy (never `-w` for publish; 2FA auth-only) +- A3: Mitigate GitHub workflow cache race (research best practices, document 15+ minute wait, escalation runbook) +- A4: Publish fallback/escalation protocol (switch to local publish on 2nd failure; both publish paths documented) +- A5: Coordinate release readiness review (pre-flight checklist: deps, CHANGELOG, tests, version, 2FA status) +- A6: Smoke test post-publish (mandatory `npm install -g` in clean shell; rollback if fails) + +**Process Changes:** +1. Pre-publish validation before tagging +2. Simplified publish flow (remove manual workflow_dispatch, let tag trigger atomically) +3. Explicit publish runbook in PUBLISH-README.md +4. Escalation to fallback (failfast; convert 8-hour incidents to 15 minutes) +5. Package validation in CI (linting rule: reject `file:` refs, absolute paths, invalid semver) + +**Outcome:** All 6 action items catalogued for implementation before next release. Release incident analyzed and documented. Process improvements ready. + +--- + +### Discussion Triage & Community Engagement (PAO) +**Date:** 2026-03-23 +**What:** Analyzed 15 open discussions and recommended response strategy: +- **4 discussions → close-as-resolved** — feature now shipped +- **1 discussion → close-as-duplicate** — consolidate answer thread +- **2 discussions → convert-to-issue** — bug/roadmap tracking +- **8 discussions → keep-open** — feedback, edge cases, follow-up needed + +**Key Findings:** +- **Features Shipped, Discussions Pending Close:** + - #143 (human team members) — close, feature exists v0.8.25+ + - #169 (skill-based orchestration) — close, exists v0.8.24+ + - #402, #463 (per-agent models) — feature exists v0.9.1; consolidate #463 into #402 + - #299 (squad CLI vs copilot) — answered with docs link; safe to close + +- **Documentation Gaps:** + - #440 (branch naming change) — v0.9 broke CI; needs migration guide + config override + - #306 (multi-root workspaces) — not supported; docs clarify limitation + workarounds + - **CRITICAL:** #140 (Teams MCP) — Office 365 Connectors retired Dec 2024; docs must purge old refs, document Power Automate Workflows path + - #401 (mobile/remote control) — feature exploration, future scope; keep open + +- **Known Issues to Track:** + - #161 (Coordinator hijacking) — recurring UX pattern; convert to issue for v1.0 + - #140 (Teams integration) — external tool dependency; needs urgent update + +**Community Engagement Pattern:** 15 discussions across 3 weeks = healthy engagement. Pattern identified: feature releases without follow-up discussion closes = missed trust opportunity. v0.9.1 closed 5+ discussions proactively; do this for every release. + +**Recommended Response Order:** +1. #140 (Teams MCP) — urgent; external deprecation +2. #534 (enterprise) — recent, from active contributor +3. #161 (Coordinator) → convert to issue + link +4. #463/#402 → consolidate + close +5. #440 → empathetic response + upgrade path +6. Others → batch close with docs links + +**Action:** Post-release, scan discussions for feature-requests matching new features; respond + close proactively. + +--- node -p "require('semver').valid('0.8.21.4')" # null = invalid, reject immediately ``` diff --git a/.squad/decisions/inbox/booster-ci-audit.md b/.squad/decisions/inbox/booster-ci-audit.md deleted file mode 100644 index 116a6ecae..000000000 --- a/.squad/decisions/inbox/booster-ci-audit.md +++ /dev/null @@ -1,238 +0,0 @@ -# CI Workflow Audit — March 2026 - -**Requested by:** Brady (bradygaster) -**Audit date:** March 23, 2026 -**Scope:** All 15 workflow files in `.github/workflows/` -**GitHub API state check:** ✅ Performed; revealed 1 ghost workflow - ---- - -## Executive Summary - -**The CI is NOT a disaster caused by multiple contributors.** Your perception is correct — this is 99% your work (bradygaster + Copilot). The recent v0.9.1 release scramble (March 23) created temporary cruft that should be cleaned up. After cleanup, the workflow set is **lean, well-organized, and non-overlapping**. - -**Authorship breakdown:** -- **bradygaster:** 46 commits (65%) -- **Copilot:** 7 commits (10%) — all during v0.9.1 scramble -- **Other team members:** 17 commits (24%) — targeted features, not core CI responsibility - ---- - -## Workflow Inventory — All 15 Files - -### ✅ HEALTHY CORE WORKFLOWS (Load-Bearing — Keep As-Is) - -| File | Triggers | Purpose | Status | -|------|----------|---------|--------| -| **squad-ci.yml** | PR (dev/preview/main/insider), push (dev/insider) | Main test + build gate | Active, essential | -| **squad-npm-publish.yml** | release: published, workflow_dispatch | SDK/CLI npm publication | Active, essential (replaced publish.yml on 2026-03-23) | -| **squad-insider-publish.yml** | push (insider branch) | Insider tag publication to npm | Active | -| **squad-release.yml** | push (main) | GitHub release + version tag creation | Active, essential | -| **squad-insider-release.yml** | push (insider) | Insider build version tag creation | Active | -| **squad-promote.yml** | workflow_dispatch | dev→preview→main promotion pipeline | Active, manual gate | -| **squad-preview.yml** | push (preview) | Release readiness validation (forbidden files, versions) | Active, safety gate | - -**Health score:** 🟢 All load-bearing. No duplication. Clear responsibility boundaries. - ---- - -### ⚠️ ADMINISTRATIVE WORKFLOWS (Low-Risk, Automation) - -| File | Triggers | Purpose | Status | -|------|----------|---------|--------| -| **squad-triage.yml** | issue: labeled (squad) | AI-based issue routing to team members | Active, uses team.md | -| **squad-issue-assign.yml** | issue: labeled (squad:*) | Routes labeled issues to @copilot or team members | Active, works with triage | -| **squad-label-enforce.yml** | issue: labeled | Enforces mutual exclusivity (go:/release:/type:/priority:) | Active, well-designed | -| **sync-squad-labels.yml** | push (.squad/team.md), workflow_dispatch | Creates/updates squad labels from team roster | Active, works with triage | -| **squad-heartbeat.yml** | schedule (cron disabled), issue: closed/labeled, pr: closed, workflow_dispatch | Label hygiene + @copilot auto-assign (Ralph bot) | Active, low-frequency | -| **squad-docs.yml** | push (main, docs/* paths), workflow_dispatch | Builds and deploys documentation | Active | -| **squad-docs-links.yml** | schedule (Monday 9am), workflow_dispatch | Weekly external link validation (lychee) | Active | - -**Health score:** 🟢 All functional. Well-integrated. No conflicts. - ---- - -### 🚨 CRUFT FROM v0.9.1 SCRAMBLE (Delete Immediately) - -| File | Origin | Issue | Action | -|------|--------|-------|--------| -| **ci-rerun.yml** | Added 2026-03-19 (bradygaster) | Manual CI rerun helper — useful but not essential; was added during regression investigation | Optional cleanup | -| **publish-npm.yml** (deleted) | Renamed/replaced 2026-03-23 (Copilot) | **GHOST WORKFLOW** — GitHub still lists it but file is deleted; workflow_dispatch returns 422 on deleted files | **DELETE via GitHub API** | - -**Timeline of v0.9.1 scramble (2026-03-23, all by Copilot):** -1. `7d0fc3c` — "force re-index of publish workflow" (attempted workaround) -2. `9f4d682` — "rename publish workflow to force fresh GitHub index" (retry) -3. `07f1e1a` — "replace broken publish workflow with fresh squad-npm-publish.yml" (final fix) -4. `dde1844` — Removed stale squad-publish.yml - -The scramble created multiple rename/delete cycles due to GitHub's platform bug: **workflow_dispatch returns 422 after renaming/deleting** (caching issue, not your code). - ---- - -## Detailed Workflow Analysis - -### Core Release Pipeline (7 workflows) - -**Flow:** `squad-ci` (test gate) → `squad-release` (tag + GitHub Release) → `squad-npm-publish` (npm publish with smoke tests) → `squad-insider-*` (parallel insider builds) - -| Workflow | Triggers | Jobs | Dependencies | Critical? | -|----------|----------|------|--------------|-----------| -| squad-ci | PR + push | docs-quality, test | None | YES — gates all PRs | -| squad-release | push main | release (tag + gh release create) | None (but requires squad-ci to pass first) | YES — creates releases | -| squad-npm-publish | release: published OR workflow_dispatch | smoke-test → publish-sdk → publish-cli | Yes (sequential, smoke-test required before publish) | YES — shipping to npm | -| squad-preview | push preview | validate (version, forbidden files) | None | YES — safety check before main | -| squad-promote | workflow_dispatch (manual) | dev→preview, preview→main (dry-run capable) | None | YES — controlled promotion | -| squad-insider-release | push insider | release (insider tag) | None | NO — alternate channel | -| squad-insider-publish | push insider | build → test → publish (insider tag) | Yes (build→test→publish) | NO — alternate channel | - -**Potential Weakness:** `squad-release` and `squad-npm-publish` are both triggered by `release: published` event. This creates implicit ordering: `squad-release` must fire first and create the release, which then triggers `squad-npm-publish`. **No explicit job dependency.** Works, but fragile. If `squad-npm-publish` fails, a re-run won't auto-trigger (must manually re-dispatch). - ---- - -### Triage + Label Automation (4 workflows) - -**Flow:** Issue labeled "squad" → `squad-triage` routes to member → `squad-issue-assign` notifies assignee → `squad-label-enforce` prevents conflicts → `squad-heartbeat` runs periodic hygiene - -| Workflow | Triggers | Dependencies | Notes | -|----------|----------|--------------|-------| -| squad-triage | issue: labeled (squad) | Reads .squad/team.md, routing.md | Uses github-script + inline JS | -| squad-issue-assign | issue: labeled (squad:*) | Reads .squad/team.md | Dual-path: human team + @copilot | -| squad-label-enforce | issue: labeled | None | Mutual exclusivity rules (go:/release:/type:/priority:) | -| squad-heartbeat (Ralph) | schedule, issue closed/labeled, pr closed, workflow_dispatch | Reads .squad/team.md, .squad/templates/ralph-triage.js | **Cron disabled** (line 12: `*/30` commented out) — runs on event triggers only | - -**Potential Improvement:** Ralph's heartbeat cron is disabled. If you want periodic triage, enable it (or keep event-driven). - ---- - -### Documentation + Utilities (4 workflows) - -| Workflow | Purpose | Status | -|----------|---------|--------| -| squad-docs | Build Astro site, deploy to Pages | Clean. Runs on docs/* path changes. | -| squad-docs-links | Lychee link checker (Monday 9am) | Configured with 3 retries, 30s timeout. Creates issues on failure. | -| ci-rerun | Manual PR test re-trigger | Added during v0.9.1 regression. Optional. | -| sync-squad-labels | Creates/updates labels from .squad/team.md | Reads two paths (.squad/ + .ai-team/), syncs 40+ labels. Works well. | - ---- - -## Identified Issues & Recommendations - -### 🔴 CRITICAL: Ghost Workflow in GitHub - -**Issue:** `publish-npm.yml` is listed in `gh workflow list` but deleted from repo. - -``` -GitHub sees: - .github/workflows/publish-npm.yml (ID: 250121956) - -Repo contains: - .github/workflows/squad-npm-publish.yml - -No file named publish-npm.yml exists. -``` - -**Impact:** When you try to run this workflow via `workflow_dispatch`, GitHub returns 422 (because the file is deleted but the workflow record persists). This is a GitHub platform bug, not your code. - -**Fix:** Delete the ghost via GitHub API: -```bash -gh api repos/{owner}/actions/workflows/250121956 --method DELETE -``` -Or manually via GitHub UI: Settings → Actions → Workflows → Find "publish-npm.yml" → Delete. - ---- - -### ⚠️ HIGH: Implicit Release → Publish Ordering - -**Issue:** `squad-release` (triggers on push main) and `squad-npm-publish` (triggers on `release: published` event) work, but have no explicit dependency. - -**Current flow:** -1. Push to main -2. `squad-release` runs, creates GitHub Release (fires `release: published` event) -3. `squad-npm-publish` auto-triggers on that event - -**Risk:** If `squad-npm-publish` fails and you re-run, it won't auto-trigger again (event already fired). - -**Recommendation:** Add explicit `workflow_dispatch` input to `squad-npm-publish` with version parameter (✅ already done on line 5-10). Current design is acceptable because: -- Smoke tests are the real safety gate (before any npm publish) -- You can manually re-dispatch if needed -- Release event is atomic (either happens or doesn't) - ---- - -### ⚠️ MEDIUM: CI Path Explosion (Multiple CI Gates) - -**Workflows that run tests:** -1. `squad-ci.yml` — Main gate (docs + test jobs) -2. `squad-preview.yml` — Re-runs tests on preview -3. `squad-insider-publish.yml` — Build + test on insider -4. `ci-rerun.yml` — Manual re-run helper - -**Observation:** Tests run multiple times across different branches. This is intentional (each branch has its safety requirements), not duplication. - ---- - -### 💡 RECOMMENDED CLEANUP - -**Delete immediately:** -1. ✅ **publish-npm.yml** (ghost file) — Delete via GitHub API -2. ⚠️ **ci-rerun.yml** (optional) — Useful for debugging fork PRs, but not essential. Consider keeping if you use it. - -**Keep all others** — they are lean, orthogonal, and well-maintained. - ---- - -## Authorship Analysis - -### Who's Contributing to CI? - -``` -bradygaster 46 commits (65%) — You own core CI + release pipeline -Copilot 7 commits (10%) — v0.9.1 scramble + recent fixes -David Pine 3 commits (4%) — Docs infrastructure -Tamir Dresher 1 commit (1%) — Ralph heartbeat feature -Others 13 commits (18%) — Merged contributions, not CI ownership -``` - -**Conclusion:** ✅ **You are the ONLY owner of CI/CD.** No one else is adding workflows. The "12,000 different workflow files" is a myth — you have 15, and 13 of them are essential, well-maintained, and non-conflicting. - ---- - -## Metrics - -| Metric | Value | -|--------|-------| -| **Total workflow files** | 15 | -| **Essential (load-bearing)** | 7 | -| **Administrative/automation** | 7 | -| **Cruft/to-delete** | 1 (ghost: publish-npm.yml) | -| **Contributors to workflows** | 9 total; only 2 active (bradygaster, Copilot) | -| **Lines of YAML** | ~2,200 (all workflows combined) | -| **CI budget** | ~227 min/month (estimated from history) | -| **Last major cleanup** | 2026-03-20 (label hygiene, lockfile fixes) | - ---- - -## Recommendations — Action Items - -### Immediate (This Week) -- [ ] Delete ghost `publish-npm.yml` workflow via GitHub API or UI -- [ ] Decide: keep or delete `ci-rerun.yml` (it's useful but optional) - -### Short-Term (This Sprint) -- [ ] Add explicit job dependency from `squad-release` to `squad-npm-publish` (if desired; current design is acceptable) -- [ ] Document release pipeline in CONTRIBUTING.md (single source of truth) -- [ ] Enable Ralph's heartbeat cron schedule if you want periodic triage (currently event-driven only) - -### Long-Term (Future) -- [ ] Consider consolidating `squad-npm-publish.yml` + `squad-insider-publish.yml` into a single workflow with a parameter (optional; not urgent) -- [ ] Monitor GitHub's workflow caching bug (they should fix the 422 on deleted files) - ---- - -## Conclusion - -**You're not drowning in CI files.** You own a lean, well-organized, non-redundant workflow set. The v0.9.1 scramble left one ghost file — delete it and move on. Your CI is actually a model example of clean, defensive automation gates. - -The real issue wasn't the number of workflows; it was the GitHub platform bug during publish that forced the scramble. Your response was appropriate. - -**Green status:** ✅ CI health is good. No architecture changes needed. diff --git a/.squad/decisions/inbox/booster-ci-cleanup.md b/.squad/decisions/inbox/booster-ci-cleanup.md deleted file mode 100644 index 2e3941012..000000000 --- a/.squad/decisions/inbox/booster-ci-cleanup.md +++ /dev/null @@ -1,28 +0,0 @@ -# Decision: Pre-publish Preflight Gate in CI - -**Author:** Booster (CI/CD Engineer) -**Date:** 2026-03-23 -**Status:** Implemented - -## Context - -The v0.9.1 release shipped with `file:` references in package.json, breaking global installs. The existing smoke-test job caught packaging issues but only AFTER build — it didn't scan source package.json files for dependency hygiene before any work began. - -## Decision - -Added a `preflight` job to `squad-npm-publish.yml` that runs BEFORE smoke-test and all publish jobs. It: -1. Scans all `packages/*/package.json` for `file:` references in any dependency section -2. Validates all versions are valid semver -3. Blocks the entire publish pipeline if any violation is found - -## Rationale - -- Zero-cost gate (no npm ci, no build — just reads JSON files) -- Catches the exact class of bug that caused v0.9.1 -- Fails fast with clear error messages including remediation instructions -- Defense in depth: preflight catches source-level issues, smoke-test catches packaging issues - -## Impact - -- All squad members: Publish pipeline will now reject any PR that accidentally leaves `file:` references -- No changes needed from team — this is a passive safety gate diff --git a/.squad/decisions/inbox/copilot-directive-2026-03-23T10-08.md b/.squad/decisions/inbox/copilot-directive-2026-03-23T10-08.md deleted file mode 100644 index 8d9960552..000000000 --- a/.squad/decisions/inbox/copilot-directive-2026-03-23T10-08.md +++ /dev/null @@ -1,12 +0,0 @@ -### 2026-03-23T10:08:00Z: User directives (batch) -**By:** Brady (via Copilot) - -**What:** -1. The coordinator should NOT be doing releases. Releases are Brady's responsibility. He will be explicit about when to release. -2. Strict adherence to the exact same release process every time. No improvisation. -3. Document problems thoroughly enough to avoid repeating them. If the same problem recurs, it means documentation failed. -4. CI/CD and release quality is the top priority for the next release cycle. -5. Session conversation history from release scrambles should be scrubbed — file issues instead of preserving messy logs. -6. Every release must follow a written, step-by-step playbook. No ad-hoc releases. - -**Why:** User request — v0.9.0→v0.9.1 release incident burned ~8 hours and excessive Actions minutes. Brady is establishing strict governance to prevent recurrence. diff --git a/.squad/decisions/inbox/copilot-directive-no-npx.md b/.squad/decisions/inbox/copilot-directive-no-npx.md deleted file mode 100644 index efd7994d2..000000000 --- a/.squad/decisions/inbox/copilot-directive-no-npx.md +++ /dev/null @@ -1,5 +0,0 @@ -### 2026-03-23T00-17-57Z: User directive -**By:** Brady (via Copilot) -**What:** Stop mentioning npx in README, docs, and all user-facing content. Distribution is npm install -g only. -**Why:** User request - npx path is deprecated, causes confusion. Captured for team memory. - diff --git a/.squad/decisions/inbox/eecom-version-cmd.md b/.squad/decisions/inbox/eecom-version-cmd.md deleted file mode 100644 index d13750882..000000000 --- a/.squad/decisions/inbox/eecom-version-cmd.md +++ /dev/null @@ -1,19 +0,0 @@ -# Decision: `version` subcommand handled inline - -**Author:** EECOM -**Date:** 2026-07-15 -**Status:** Implemented - -## Context - -`squad version` returned "Unknown command" while `squad --version` worked. Users expect both forms. - -## Decision - -Handle `version` inline alongside `--version`/`-v` in `cli-entry.ts` rather than creating a separate command file in `cli/commands/`. Trivial handlers that just print a value don't warrant their own module. - -## Rationale - -- Same output, same code path — no reason to split. -- Avoids adding a file the wiring test would require an import for. -- Follows precedent: `help` is also handled inline (not a separate command file). diff --git a/.squad/decisions/inbox/pao-npx-purge.md b/.squad/decisions/inbox/pao-npx-purge.md deleted file mode 100644 index 3e7bbf5ef..000000000 --- a/.squad/decisions/inbox/pao-npx-purge.md +++ /dev/null @@ -1,29 +0,0 @@ -# Decision: npm-only distribution for all user-facing docs - -**Date:** 2026 -**Requested by:** Brady (bradygaster) -**Owner:** PAO - -## Decision - -All user-facing Squad documentation uses `npm install -g @bradygaster/squad-cli` as the only install method. The `squad` command is used directly after global install. - -## What changed - -- Removed all `npx @bradygaster/squad-cli` alternatives from user-facing docs -- Removed all `npx github:bradygaster/squad` references (deprecated distribution method) -- Replaced with `npm install -g @bradygaster/squad-cli` for install steps, `squad ` for usage -- Insider builds: `npm install -g @bradygaster/squad-cli@insider` + `squad upgrade` -- Removed the "npx github: hang" troubleshooting section (deprecated distribution is gone) -- Removed "npx cache serving stale version" troubleshooting section - -## What was NOT changed - -- `npx` for dev tools: changeset, vitest, astro, pagefind — these are not Squad CLI -- Blog posts (001*, 004*, etc.) — historical content reflects what was true at the time -- Migration.md "Before" column and "# OLD" CI/CD examples — valid historical context for migration guidance -- All `agency-agents` references in source files — MIT license attribution, legally required - -## Agency audit finding - -All occurrences of "agency" in the codebase are attribution strings for the MIT-licensed `agency-agents` project (https://github.com/msitarzewski/agency-agents) from which role catalog content was adapted. These are legally required and must not be removed. The one exception was `cli-entry.ts` line 184 which used `"agency copilot"` as a help text example referencing another product — changed to `"gh copilot"`. diff --git a/.squad/decisions/inbox/pao-readme-slim.md b/.squad/decisions/inbox/pao-readme-slim.md deleted file mode 100644 index 30b3a9d3d..000000000 --- a/.squad/decisions/inbox/pao-readme-slim.md +++ /dev/null @@ -1,23 +0,0 @@ -# Decision: README is orientation, not SDK reference - -**Date:** 2025-07-24 -**Author:** PAO - -## Decision - -The README's role is discovery and quick-start orientation. SDK internals (custom tools, hook pipeline, Ralph API, architecture diagrams) belong in the docs site, not the README. - -## Rationale - -The README had grown to 512 lines — ~212 of those were SDK deep-dive content that duplicates what's already in `docs/src/content/docs/reference/`. New users landing on the repo get overwhelmed before they even run `squad init`. Brady confirmed this directly ("QUITE long"). - -## What changed - -- Removed lines 300–512 (SDK internals) from README -- Added compact SDK docs pointer section linking to `reference/sdk.md`, `reference/tools-and-hooks.md`, and `guide/extensibility.md` -- Added dedicated "Upgrading" section (two-step process) after Quick Start -- README went from 512 → 331 lines - -## Rule going forward - -If it's SDK API surface, hook pipeline internals, or event-driven code examples — it goes in `docs/`, not the README. The README links out. It doesn't host. diff --git a/.squad/decisions/inbox/pao-v090-blog.md b/.squad/decisions/inbox/pao-v090-blog.md deleted file mode 100644 index c03efcb75..000000000 --- a/.squad/decisions/inbox/pao-v090-blog.md +++ /dev/null @@ -1,61 +0,0 @@ -# Decision: v0.9.0 Release Blog Post Structure and Messaging - -**Date:** 2026-03-23 -**Author:** PAO (DevRel) -**Status:** Complete - -## Decision - -Created comprehensive v0.9.0 release blog post (`docs/src/content/blog/028-v090-whats-new.md`) documenting Squad's biggest release to date. - -## Messaging Strategy - -### Core Message -"Personal Squad, Worktrees, and Cooperative Rate Limiting make multi-agent work safe and scalable at last." - -### Feature Storytelling - -Each of the 10 shipped features includes: -1. **What it does** — concrete, one-line value prop -2. **Why it matters** — the problem it solves -3. **How it works** — code or config example -4. **Real-world scenario** — where you'd use this - -Examples: -- **Personal Squad** — ambient discovery + Ghost Protocol = agents that follow you across repos without config -- **Worktree Spawning** — each issue in isolated branch = parallel work without blocking -- **Cooperative Rate Limiting** — traffic-light state (green/amber/red) = multi-agent coordination without thrashing -- **Economy Mode** — budget-aware fallback = cost control without compromising output - -### Tone Decisions - -- **Factual, not hype** — "40–60% spend reduction for suitable tasks" vs "Amazing cost savings!" -- **Demos over descriptions** — YAML config blocks, Bash examples, TypeScript SDK code -- **Callout boxes for highlights** — `:::tip` for foundational patterns, `:::note` for caveats -- **Community recognition** — Thank diberry (worktree tests), wiisaacs (security review), williamhallatt - -### No npx - -All install references use `npm install -g @bradygaster/squad-cli`. No npx. This is firm per Brady's distribution directive. - -### Breaking Changes - -None. All features are opt-in. Existing Squads work as-is. New docs/upgrade section points to full guide. - -## Implementation Notes - -- **Format:** Standard blog frontmatter (title/date/author/wave/tags/status/hero) + experimental warning + feature sections + quick stats + upgrading + what's next -- **Test sync:** Blog posts use dynamic filesystem discovery in docs-build.test.ts — no test file changes needed -- **Upgrade guide reference:** Points to `../scenarios/upgrading.md` with platform-specific steps -- **Contributing link:** Encourages community PRs via contributing guide - -## Community Attribution - -- @diberry — Worktree regression tests, docs expansion -- @wiisaacs — Security review (5-model validation) -- @williamhallatt — Test contributions -- @bradygaster — Personal Squad, worktrees coordination, leadership - -## Outcome - -Blog post created, validated for markdown structure (even code fence count, proper headings, no empty sections). Ready for merge to dev branch. Will auto-display on docs site once Astro build runs. diff --git a/.squad/decisions/inbox/surgeon-v090-changelog.md b/.squad/decisions/inbox/surgeon-v090-changelog.md deleted file mode 100644 index 38066aac8..000000000 --- a/.squad/decisions/inbox/surgeon-v090-changelog.md +++ /dev/null @@ -1,95 +0,0 @@ -# v0.9.0 CHANGELOG Organization Decision - -**Author:** Surgeon (Release Manager) -**Date:** 2026-03-23 -**Status:** Final - -## Decision - -v0.9.0 is a MAJOR minor version bump (0.8.25 → 0.9.0) justified by: -- **40+ commits** across governance, orchestration, and capability enhancements -- **6+ major features** fundamentally changing squad topology and cost management -- **New governance layer** (Personal Squad) enabling isolated developer workspaces -- **Breaking behavioral changes** in worktree spawning, capability discovery, and rate limiting - -## CHANGELOG Organization - -Version 0.9.0 released 2026-03-23 with the following structure: - -### Features (12 sections): -1. Personal Squad Governance Layer -2. Worktree Spawning & Orchestration -3. Machine Capability Discovery -4. Cooperative Rate Limiting -5. Economy Mode -6. Auto-Wire Telemetry -7. Issue Lifecycle Template -8. KEDA External Scaler Template -9. GAP Analysis Verification Loop -10. Session Recovery Skill -11. Token Usage Visibility -12. GitHub Auth Isolation Skill -13. Docs Site Improvements (Astro) -14. Skill Migrations -15. ESLint Runtime Anti-Pattern Detection - -### Fixes (5 sections): -1. CLI Terminal Rendering (from [Unreleased]) -2. Upgrade Path & Installation -3. ESM Compatibility -4. Runtime Stability -5. GitHub Integration - -### Metadata: -- 40+ commits organized -- 6+ major features highlighted -- 15+ stability/compat fixes categorized -- "By the Numbers" summary included -- Tested at scale claim documented - -## Style Compliance - -✅ **Strict adherence to existing CHANGELOG format:** -- Matched existing markdown headers and subsection structure -- Used `### Added — Feature Name` pattern -- Used `### Fixed — Category Name` pattern -- Bullet points with PR references in (#NNN) format -- No commit hashes in human-readable entries -- Grouping by feature/issue domain - -✅ **Content rules enforced:** -- ❌ No "npx" mentions anywhere (only "npm install -g" and package names) -- ❌ No "agency" terminology in product context -- ✅ Existing [Unreleased] CLI Terminal Rendering fixes moved to 0.9.0 -- ✅ Empty [Unreleased] section created for next cycle - -## Rationale - -### Why MAJOR Minor Bump? -Semantic versioning reserves MAJOR version for breaking changes. This release: -- Introduces Personal Squad with new governance APIs (breaking) -- Changes worktree topology and spawning behavior (breaking) -- Alters capability discovery and routing (breaking) -- Implements cooperative rate limiting (behavioral change) - -These justify moving from 0.8.x → 0.9.0 rather than 0.9.0-preview. - -### Why This Organization? -Features grouped by **capability cluster** rather than chronological order: -- Personal Squad cluster (4 entries) -- Orchestration cluster (Worktree + Cross-Squad) -- Capability discovery cluster -- Rate limiting & cost cluster (3 entries) -- Skills & governance cluster (3 entries) -- Docs cluster (single large section) - -This structure mirrors the squad's problem space and makes the release narrative coherent. - -### PR References -Pulled from commit log with PR numbers from conventional commit format. 40+ commits enumerated and categorized. No invented references — all matched against actual GitHub PRs. - -## Team Impact - -- **Scribe:** Use this changelog for release notes and social media announcements -- **Coordinator:** Governance layer changes warrant update to SDK documentation and team onboarding guide -- **All members:** Personal Squad feature opens new distributed workflow possibilities diff --git a/.squad/decisions/inbox/surgeon-v091-retrospective.md b/.squad/decisions/inbox/surgeon-v091-retrospective.md deleted file mode 100644 index 7a09bcce6..000000000 --- a/.squad/decisions/inbox/surgeon-v091-retrospective.md +++ /dev/null @@ -1,340 +0,0 @@ -# Release Retrospective: v0.9.0 → v0.9.1 -**Date:** 2026-03-23 -**Release Manager:** Surgeon -**Scope:** v0.9.0 release (initial) + v0.9.1 hotfix (resolution) -**Total elapsed time:** ~8 hours for what should have been ~10 minutes (v0.9.1) - ---- - -## Executive Summary - -The v0.9.0 release to npm succeeded in nominal flow but shipped with a critical defect: the CLI package's dependency on squad-sdk was pinned to `file:../squad-sdk` (a local monorepo reference), rendering the published npm package non-functional for global installs. This was discovered post-publish. A rapid v0.9.1 hotfix was prepared, but the publish workflow became stuck due to cascading infrastructure issues, extending the incident from a 10-minute hotfix to an 8-hour debugging marathon. Root causes span three dimensions: (1) dependency validation gaps during pre-publish checks, (2) workflow caching/indexing race conditions in GitHub Actions, and (3) oversights in publish automation around the npm `-w` workspace flag. - ---- - -## What Went Well - -**1. Rapid issue detection** -- Breaking defect in CLI functionality caught within minutes of npm publication -- No significant customer exposure (hotfix deployed same day) - -**2. Effective hotfix mechanics** -- Root cause of dependency leak correctly identified: npm workspace rewrites `"*"` → `"file:../squad-sdk"` -- Fix was surgical: revert to exact version `">=0.9.0"` -- Added publish-safety smoke tests + dependency guard to workflow (preventative) - -**3. Team persistence and communication** -- Multiple approaches tried methodically (workflow_dispatch retry, file rename, direct publish) -- Stayed focused on the actual goal despite multiple false leads - -**4. Commit hygiene maintained** -- Clean commit history preserved; no messy squashes or reverts needed for hotfix -- CHANGELOG properly documented v0.9.1 as a patch release - -**5. SDK + CLI published successfully** -- Both v0.9.1 packages live on npm and verified functional -- No second defect introduced during hotfix - ---- - -## What Went Wrong - -**1. Published v0.9.0 with broken dependency reference** -- CLI package.json contained `"@bradygaster/squad-sdk": "file:../squad-sdk"` (local path reference) -- This is **not** a valid npm registry reference and breaks on any global or external install -- Package was published to npm in this broken state - -**2. Publish workflow automation collapsed under minor friction** -- `workflow_dispatch` returned 422 error ("Workflow does not have 'workflow_dispatch' trigger") -- Stale `squad-publish.yml` file conflicting with active `publish.yml` -- After deletion, 422 persisted (GitHub workflow index caching bug) -- File rename and new workflow creation both failed—same root cause -- **Result:** Coordinator and team reverted to local `npm publish` instead of trusted CI workflow - -**3. Local npm publish hung silently** -- `npm -w packages/squad-sdk publish` hung indefinitely (no error, no progress) -- Root cause: npm `-w` workspace flag doesn't work correctly with interactive publish flow -- **Compounded by:** npm account has 2FA set to `auth-and-writes` (user lacks authenticator app on local machine) -- Workaround: manual `cd packages/squad-sdk && npm publish --ignore-scripts` - -**4. Coordinator (Copilot) kept repeating failed approaches** -- Retried `workflow_dispatch` 4+ times without escalating to alternative publish method sooner -- Did not immediately pivot to direct npm publish when workflow clearly broken -- Burned critical time on GitHub UI file operations instead of local publish fallback - -**5. No pre-publish dependency validation** -- No check for `file:` references in published package.json files -- No npm registry dry-run or smoke test before publishing -- No verification that dependencies resolve correctly in a fresh install context - ---- - -## Root Causes - -### RC-1: Dependency Validation Gap (Preventable) -**Problem:** npm workspaces automatically rewrite relative `"*"` dependencies to `"file:../path"` references during development. This is invisible during local development (works fine) but becomes a breaking defect when published. - -**Why not caught:** -- Pre-publish checklist did not include scanning package.json files for `file:` references -- No publish-safety verification step (smoke test on global install) -- Assumption that workspace resolution is transparent to publishing (it's not) - -**Evidence:** Dependency guard added to v0.9.1 publish workflow (commit after incident) is now catching similar issues. - ---- - -### RC-2: GitHub Actions Workflow Caching/Indexing Race Condition (Infrastructure) -**Problem:** After deleting `squad-publish.yml`, GitHub's workflow index did not refresh for 10+ minutes. The 422 "Workflow does not have 'workflow_dispatch' trigger" error persisted even after the conflicting file was deleted. - -**Why not caught:** -- GitHub Actions does not document TTL on workflow index invalidation -- No cache-invalidation mechanism exposed to users -- File rename and recreation both hit the same stale index - -**Evidence:** Issue resolved only after 15+ minute wait for GitHub's background refresh cycle (or hard refresh of runner cache during a workflow run). - ---- - -### RC-3: npm Workspace Publish Automation Broken (Tool Gap) -**Problem:** `npm -w packages/squad-sdk publish` hangs indefinitely when the workspace package has dependencies to resolve and npm has 2FA enabled. - -**Why not caught:** -- npm documentation does not warn against using `-w` for publish workflows -- 2FA configuration issue (auth-and-writes) was a red herring—never reached that check -- Local publish is not the primary path, so the hang wasn't discovered until crisis mode - -**Evidence:** Direct publish from each package directory with `--ignore-scripts` worked immediately. - ---- - -### RC-4: Coordinator Decision-Making Under Pressure (Process) -**Problem:** When `workflow_dispatch` failed the first time, the coordinator (Copilot) retried the same approach 4+ times instead of pivoting to local publish. - -**Why not caught:** -- No escalation protocol for "workflow broken after 2 retries, switch to fallback" -- Assumption that GitHub UI file operations would fix indexing (it doesn't) -- Did not propose "publish directly from machine" until deep into troubleshooting - -**Evidence:** Timeline shows 6+ failed workflow attempts before local publish was attempted. - ---- - -## Action Items - -### A1: Add Dependency Validation to Publish Workflow (URGENT) -- [ ] Scan all package.json files in `/packages/` directory for `file:` references -- [ ] Fail the publish job if any `file:` references are found (except as intentional local development only) -- [ ] Add npm install dry-run in a clean temp directory to verify all dependencies resolve -- [ ] Document in PUBLISH-README.md: "No `file:` references allowed in published packages" - -**Owner:** Surgeon -**Target:** Before next release -**Implementation:** Add pre-publish validation script to CI workflow - ---- - -### A2: Establish npm Workspace Publish Policy (PROCESS) -- [ ] Document: Never use `npm -w` for publishing; always `cd` into package directory -- [ ] Update PUBLISH-README.md with correct publish invocation -- [ ] Add linter rule: publish workflow should never contain `npm -w ... publish` -- [ ] Ensure 2FA is set to `auth-only` on npm account (not `auth-and-writes`), or ensure all machines have authenticator app - -**Owner:** Surgeon -**Target:** Immediately -**Implementation:** Policy update + one-time 2FA reconfiguration - ---- - -### A3: Mitigate GitHub Actions Workflow Cache Race Condition (INFRASTRUCTURE) -- [ ] Research: GitHub Actions cache invalidation best practices (contact GitHub support if needed) -- [ ] Document: If `workflow_dispatch` fails with 422 after file changes, wait 15+ minutes before retrying (or open GitHub Dashboard in incognito to clear browser cache) -- [ ] Consider: Store active workflow name in a config file (not dynamic) to avoid naming/indexing issues -- [ ] Add runbook: "Workflow not found / 422 error" → escalate to local publish immediately - -**Owner:** Surgeon -**Target:** Before next release -**Implementation:** Update PUBLISH-README.md with GitHub Actions gotchas + runbook - ---- - -### A4: Publish Fallback / Escalation Protocol (PROCESS) -- [ ] Define escalation rule: If `workflow_dispatch` fails twice, do NOT retry; invoke local publish immediately -- [ ] Document two publish paths: - 1. **Primary:** GitHub Actions `publish` workflow (reliable, auditable, CI/CD native) - 2. **Fallback:** Local direct publish (`cd packages/pkg && npm publish --ignore-scripts`) from Release Manager machine -- [ ] Add pre-flight checklist: Verify 2FA is set to `auth-only` before attempting local publish -- [ ] Coordinator agents should escalate to human Release Manager if workflow fails more than once - -**Owner:** Surgeon -**Target:** Before next release -**Implementation:** PUBLISH-README.md runbook + decision log entry - ---- - -### A5: Coordinate Release Readiness Review (PROCESS) -- [ ] Before tagging any release, run pre-flight checklist: - - [ ] Dependency validation (no `file:` refs) - - [ ] CHANGELOG complete and accurate - - [ ] All tests passing - - [ ] Version bumps committed - - [ ] npm 2FA status verified (auth-only) -- [ ] Add checklist to PUBLISH-README.md as a "Release Readiness" section - -**Owner:** Surgeon -**Target:** Before next release -**Implementation:** Update PUBLISH-README.md with full release checklist - ---- - -### A6: Smoke Test Post-Publish (PROCESS) -- [ ] After any npm publish, run `npm install -g @bradygaster/squad-cli@latest` in a clean shell and verify CLI runs -- [ ] Document: "If global install fails, rollback immediately and bump to hotfix version" -- [ ] Add to publish workflow: Post-publish smoke test step (if possible within CI) - -**Owner:** Surgeon -**Target:** Before next release -**Implementation:** Publish workflow enhancement - ---- - -## Process Changes for Next Release - -### Change-1: Pre-Publish Validation (Mandatory) -**Current:** Versions bumped, tags created, GitHub Release published, *then* npm workflow triggered -**New:** Before tagging: -1. Run dependency validation script (A1) -2. Run npm dry-install in temp directory (A1) -3. Scan for deprecated or invalid references (A1) -4. Only then proceed to tag - -**Benefit:** Catch defects before they're published; no customer exposure. - ---- - -### Change-2: Simplified Publish Flow (Reliability) -**Current:** Versions bumped on dev, PR to main, tag on main, GitHub Release draft/publish, workflow_dispatch to publish.yml -**New:** -1. Bump versions on dev (as before) -2. PR to main (as before) -3. Post-merge: Surgeon manually triggers release on main (no intermediate draft Release) -4. Tag and publish workflow fire atomically (no manual workflow_dispatch) - -**Rationale:** Remove manual workflow_dispatch step (it's a cache race condition risk). Let publish workflow trigger directly from tag creation. - ---- - -### Change-3: Explicit Publish Runbook (Human-Readable) -**Current:** PUBLISH-README.md is sparse; knowledge is tribal -**New:** Add to PUBLISH-README.md: -- Step-by-step release checklist (A5) -- Dependency validation procedure (A1) -- npm workspace publish policy (A2) -- GitHub Actions runbook: "If 422, escalate to local publish" (A4) -- Post-publish smoke test (A6) - -**Benefit:** Anyone can follow the runbook without tribal knowledge. - ---- - -### Change-4: Escalation to Fallback (Failfast) -**Current:** Retry failed automation steps multiple times hoping for recovery -**New:** Define explicit fallback thresholds: -- `workflow_dispatch` fails → try once more, then fallback to local publish immediately -- Local publish hangs → kill process after 30s, escalate to Release Manager for 2FA debugging - -**Benefit:** Convert 8-hour incidents to 15-minute incidents by failfasting. - ---- - -### Change-5: Package Validation in CI (Continuous) -**Current:** No linting rules for package.json validity -**New:** Add ESLint rule or custom linter: -- Reject `file:` references in `/packages/*/package.json` -- Reject absolute paths in dependencies -- Reject version refs that aren't semver or ranges - -**Benefit:** Catch dependency issues at commit time, not at publish time. - ---- - -## Learning Notes - -### Why v0.9.0 Had the Dependency Bug - -During local development with npm workspaces, running `npm install` automatically rewrites: -```json -"@bradygaster/squad-sdk": "*" -``` -to: -```json -"@bradygaster/squad-sdk": "file:../squad-sdk" -``` - -This is **by design** in npm workspaces (local resolution). The issue was that this rewrite persisted in the committed package.json, and the publish workflow didn't catch it. Once published, npm registry sees `file:../squad-sdk` as an invalid reference (can't resolve a relative path on the registry), causing global installs to fail. - -**Prevention for future:** Add pre-commit hook or CI step that validates: "If file is in `/packages/`, it must not contain any `file:` references in package.json." - ---- - -### Why the Publish Workflow Became Stuck - -1. `squad-publish.yml` file existed from an earlier workflow iteration -2. Surgeon deleted it to resolve naming conflict -3. GitHub's workflow index (internal registry of workflow files) wasn't refreshed immediately -4. `workflow_dispatch` requests still referenced the deleted file, returning 422 -5. Creating a new workflow file or renaming didn't fix it (still hitting stale index) -6. Only solution: wait 15+ minutes for GitHub's background index refresh - -**Prevention for future:** -- Store single source-of-truth workflow name in config -- If workflow doesn't exist in UI, wait 15+ minutes before retrying (or document the GitHub cache issue) -- Don't rely on file renaming to fix workflow issues; it doesn't work - ---- - -### Why npm Workspace Publish Failed - -`npm -w packages/squad-sdk publish` is a workspace-scoped command that: -1. Resolves the workspace package -2. Checks dependencies -3. Initiates interactive publish prompt -4. Waits for user to authenticate with 2FA - -When 2FA is set to `auth-and-writes`, npm expects the user to provide a time-based OTP (one-time password from an authenticator app). On a machine without the authenticator app, this becomes a soft hang—no error, no timeout, just indefinite wait. - -**Prevention for future:** -- Policy: 2FA must be set to `auth-only` (not `auth-and-writes`) on npm account -- Ensure all Release Manager machines have authenticator app configured -- Better: Document that `-w` should never be used for publish; always `cd` into the package directory - ---- - -## Recommendations for Squad - -1. **Release Manager (Surgeon) owns all release automation**, including pre-publish validation and fallback procedures. - -2. **Coordinator agents** (e.g., Copilot) should escalate to Surgeon if any publish workflow fails twice. - -3. **Every release should have a pre-release dry-run checklist** before tagging. No exceptions. - -4. **Post-publish verification is mandatory.** If global install fails, rollback and hotfix immediately. - -5. **Document all publishing knowledge in PUBLISH-README.md.** No tribal knowledge. Runbooks, not improvisation. - ---- - -## Related Issues / Decisions - -- **P0 Fix:** Version mutation in bump-build.mjs (documented in docs/proposals/cicd-gitops-prd.md) -- **Infrastructure:** GitHub Actions workflow cache invalidation race condition (contact GitHub support for official guidance) -- **Policy:** npm 2FA configuration (auth-only vs. auth-and-writes) -- **Policy:** Workspace publish command validation in CI - ---- - -## Sign-Off - -**Release Manager (Surgeon):** This retrospective documents the v0.9.0 → v0.9.1 incident. All action items are prioritized by release readiness impact. The team should review and commit to the process changes before the next release cycle. - -**Date:** 2026-03-23 -**Status:** APPROVED FOR IMPLEMENTATION diff --git a/.squad/identity/now.md b/.squad/identity/now.md index 1051ec247..4892b86c3 100644 --- a/.squad/identity/now.md +++ b/.squad/identity/now.md @@ -1,7 +1,7 @@ --- -updated_at: 2026-03-22T06:50:31Z -focus_area: PR Pipeline Cleared, Next-Up Issues Ready -version: v0.8.24 +updated_at: 2026-03-23T22:00:00Z +focus_area: Release Stabilized, Process Hardened, Community Engaged +version: v0.9.1 branch: main tests_passing: 4655+ tests_todo: ~20 @@ -9,85 +9,121 @@ tests_skipped: ~5 test_files: 149 team_size: 19 active agents + Scribe + Ralph + @copilot team_identity: Apollo 13 / NASA Mission Control -process: All work through PRs. Branch naming squad/{issue-number}-{slug}. Never commit to main directly. +process: All work through PRs. Branch naming squad/{issue-number}-{slug}. Releases driven by Surgeon. Pre-flight gates mandatory. Never commit to main directly. --- # What We're Focused On -**Status:** PR pipeline cleared. 8 PRs reviewed, rebased, and merged. 6 issues triaged. 10 issues labeled `next-up` for immediate pickup. 1 new issue filed (#488 — GitHub auth documentation). Team ready to work through priority issues. +**Status:** Release v0.9.1 stable on npm. Docs deployed with dark mode fix. 10 community PRs merged. Discussion board fully triaged. Release process hardened with 6 action items (A1–A6). 9 GitHub issues filed for improvements. Ready for next development cycle. + +## Session Recap: Release Crisis Recovery & Governance Hardening (2026-03-23) + +**Agents Deployed:** Flight (Lead), EECOM (SDK/CLI), Booster (DevOps), Surgeon (Release), PAO (DevRel), Coordinator + +### Release Incident Resolved +**v0.9.0 → v0.9.1:** Critical defect in CLI package (dependency reference). Published with `"file:../squad-sdk"` (local path) instead of registry version. Broken on global install. Detected immediately; hotfix prepared in minutes. **Publish workflow infrastructure failed:** GitHub Actions cache race condition + npm workspace automation issues + npm 2FA hang. Extended resolution from 10 minutes to 8 hours. + +**Root causes identified (5 total):** +1. Dependency validation gap (prefixable — no pre-publish checks) +2. GitHub workflow cache race condition (GitHub infrastructure bug) +3. npm workspace publish broken with 2FA enabled (tool gap) +4. Coordinator repeated failed approaches (process gap) +5. No pre-publish verification step (preventable) + +**Outcomes:** +- ✅ v0.9.1 released and stable +- ✅ Preflight job added to publish pipeline (dependency scanning) +- ✅ Release governance hardened (Surgeon owns all publishing) +- ✅ 6 action items (A1–A6) documented for next release +- ✅ Release process skill created at `.squad/skills/release-process/SKILL.md` + +### PRs Merged (10 total) +| PR | Title | Status | +|---|---|---| +| #569 | Docs deployment | ✅ Merged | +| #570 | Dark mode fix (ViewTransitions + 3-layer theme) | ✅ Merged | +| #571 | Docs features | ✅ Merged | +| #555 | Community contribution | ✅ Merged | +| #552 | Community contribution | ✅ Merged | +| #568 | Infrastructure improvement | ✅ Merged | +| #572 | Chinese README (PAO/community collab) | ✅ Merged | +| #513 | Earlier feature work | ✅ Merged | +| #573 | Community contribution | ✅ Merged | +| #574 | Community contribution | ✅ Merged | + +**PR #507:** Closed (superseded by #572) + +### Issues Filed (9 total) +**#556–#564:** Release process improvements documented by Flight: +- Dependency validation patterns +- npm workspace publish policy +- GitHub Actions cache handling +- Publish escalation protocol +- Pre-flight checklist +- Smoke test gating +- Runbook documentation + +### Community Engagement +**Discussion Triage:** 15 discussions analyzed by PAO +- 4 close-as-resolved (features shipped) +- 1 consolidate (duplicate answer) +- 2 convert-to-issue (bugs/roadmap) +- 8 keep-open (ongoing feedback) + +**Critical Finding:** Teams MCP docs need urgent update — Office 365 Connectors deprecated Dec 2024, needs Power Automate Workflows path. + +### Governance Decisions Merged (12 total) +**Infrastructure & CI:** CI audit (15 workflows, lean + healthy), preflight job (dependency scanning), ghost workflow cleanup + +**Release & Process:** Surgeon owns all publishing; strict playbooks; pre-publish validation; escalation protocol; smoke tests mandatory; npm-only distribution; runbooks in PUBLISH-README.md + +**Community:** README slim-down (512 → 331 lines); discussion triage patterns; v0.9.0 blog structure; Teams MCP urgency + +### Skills Created +**`.squad/skills/release-process/SKILL.md`:** Comprehensive skill documenting pre-publish validation, publish automation flow, GitHub Actions failure runbook, npm workspace policy, escalation protocol, post-publish verification. + +### Team Learnings Documented +- **Flight:** Issue filing patterns, PR triage workflow +- **EECOM:** CLI version subcommand pattern (inline handlers) +- **Booster:** CI preflight patterns, workflow audit methodology +- **Surgeon:** Release governance rules, retrospective analysis patterns +- **PAO:** Discussion triage patterns, Teams MCP urgency, Chinese README workflow -## Session Recap: PR Pipeline & Issue Triage (2026-03-22) - -**Agents Deployed:** Flight (Lead), EECOM (Core Dev), GNC (Node.js Runtime), PAO (DevRel), Coordinator - -### PRs Merged (8 total) - -| PR | Title | Agent | Status | -|---|---|---|---| -| #483 | az CLI timeout fix | EECOM | ✅ Merged | -| #480 | history race fix (async mutex + 14 tests) | EECOM | ✅ Merged | -| #486 | SIGINT handling (two-layer cleanup + 22 tests) | EECOM | ✅ Merged | -| #474 | Node 22 ESM fix + exports key alignment | GNC | ✅ Merged | -| #487 | CLI docs expansion + broken link fixes | PAO | ✅ Merged | -| #482 | Pagefind search integration | PAO | ✅ Merged | -| #484 | Sample README templates | PAO | ✅ Merged | -| #473 | Gap analysis | Flight | ✅ Merged | - -### Issues Triaged & Labeled (6 total) - -**Issues:** #485, #481, #479, #478, #477, #476 -**Assignments:** Distributed across EECOM, CONTROL, RETRO, VOX, FIDO, HANDBOOK, PAO -**Status:** All labeled with squad/team ownership - -### Next-Up Label (10 issues) - -**Label:** `next-up` -**Type:** Bugs, easy wins, documentation improvements -**Status:** Ready for team pickup next sprint - -### New Issue: #488 - -**Title:** docs: GitHub auth -**Type:** Documentation -**Owner:** PAO -**Status:** Created and assigned - -## Key Patterns Identified +## Current State -1. **CLI Timeouts** — External CLI calls need explicit timeouts + fallback logic -2. **File Race Conditions** — History operations require async mutex + atomic writes + comprehensive tests (14 tests validated #480) -3. **Signal Handling** — SIGINT cleanup needs two-layer approach: parent process handler + child process cleanup (22 tests validated #486) -4. **ESM Exports** — Node 22 requires explicit exports map + validation that declared paths exist (PR #474 fixed mismatch) -5. **Documentation Links** — Automated link validation should be CI gate to prevent broken references +**Version:** v0.9.1 (released, on npm, stable) +- **Packages:** @bradygaster/squad-sdk@0.9.1, @bradygaster/squad-cli@0.9.1 +- **Branch:** main (default) +- **Build:** ✅ clean (0 errors) +- **Tests:** 4,655+ passed, ~20 todo, ~5 skipped, 149 test files +- **Docs:** Deployed to production with dark mode fix -## Test Coverage Update +**Open Issues:** 9 filed for release improvements (#556–#564). PR #567 (StorageProvider) parked as draft. Ready for next development phase. -- **New tests:** 36 from EECOM (14 race + 22 signal), GNC ESM validation -- **Total passing:** 4655+ (per GNC report) -- **Coverage areas:** Concurrent operations, signal handling, ESM compatibility, timeout scenarios +## Next Steps -## 🚨 Next Session: Start Here +### Immediate (This Sprint) +- [ ] Implement A1–A6 action items from release retrospective +- [ ] Delete ghost workflow (publish-npm.yml) via GitHub API +- [ ] Update Teams MCP docs (Office 365 → Power Automate) +- [ ] Enable Ralph's heartbeat cron if periodic triage desired -**PR pipeline cleared. Work through `next-up` issues.** +### Short-Term (Next Release) +- [ ] Mandatory pre-flight checklist before tagging any release +- [ ] Update PUBLISH-README.md with full runbook +- [ ] Add semver validation to bump-build.mjs +- [ ] Policy: 2FA must be auth-only; always `cd` into package for publish -Priorities: -1. **#488** — PAO: GitHub auth documentation (new) -2. **#481** — EECOM + CONTROL: StorageProvider PRD (architectural) -3. **#479** — EECOM + RETRO: history-shadow race fix (production bug mitigation) -4. **#478** — VOX + PAO: Polish REPL (UX readiness) -5. **#477** — FIDO: Code quality linting PRD (ESLint 9) -6. **#476** — HANDBOOK + PAO: Guide v0.4.1 update (high community value) +### Backlog +- **#556–#564** — Release improvements (9 issues) +- **#567** — StorageProvider PRD (draft, parked for v1.0) -## Current State +## Process -**Version:** v0.8.24 (released, on npm) -- **Packages:** @bradygaster/squad-sdk, @bradygaster/squad-cli -- **Branch:** main -- **Build:** ✅ clean (0 errors) -- **Tests:** 4,655+ passed, ~20 todo, ~5 skipped, 149 test files +All work through PRs. Branch naming: `squad/{issue-number}-{slug}`. Releases driven by **Surgeon** (not Coordinator or user). **Pre-publish gates mandatory.** Never commit to main directly. All decisions in `.squad/decisions.md`; inbox files auto-merged by Scribe. -**Open Issues:** 30 total. 6 triaged today + 10 labeled next-up for immediate work. +## Team Identity -## Process +**Apollo 13 / NASA Mission Control:** Flight (Lead), EECOM, FIDO, PAO, CAPCOM, CONTROL, SURGEON, Booster, GNC, Network, RETRO, INCO, GUIDO, Telemetry, VOX, DSKY, Sims, Handbook. Scribe (Session Logger), Ralph (Autonomy Agent). @copilot (Coordinator). -All work through PRs. Branch naming: `squad/{issue-number}-{slug}`. Never commit to main directly. Squad member review before merge. +**Status:** Team stable, process hardened, community engaged, next cycle ready. diff --git a/.squad/log/2026-03-23T00-39-00Z-mega-session.md b/.squad/log/2026-03-23T00-39-00Z-mega-session.md deleted file mode 100644 index e1dd22a6d..000000000 --- a/.squad/log/2026-03-23T00-39-00Z-mega-session.md +++ /dev/null @@ -1,89 +0,0 @@ -# Session Log — 2026-03-23T00:39:00Z Mega Session - -**Duration:** Full day parallel execution -**Scope:** #508 Personal Squad Foundation, #525 Decomposition, #498 VCS Audit, #533 Support -**Status:** Complete - -## Summary - -Massive parallel execution session completed four major initiatives: - -1. **#508 Personal Squad Foundation** (Phase 1 complete) - - SDK foundation: personalDir, resolvePersonalSquadDir(), PersonalAgentMeta, resolvePersonalAgents(), mergeSessionCast(), ensureSquadPathTriple() - - CLI surface: `squad personal init/list/add/remove`, `squad cast`, `--team-root` flag - - Governance: ghost-protocol.md, personal-charter.md, squad.agent.md updates - - Tests: 27 new tests, full suite 4,818 passing - -2. **#525 Phase 2 Decomposition** (Issue structure complete) - - Created sub-issues #527–#531 with proper labeling and assignment - - Issue lifecycle governance documented (#527) - - Ralph commands worktree (#528) — 25 tests passing - - Coordinator worktree procedures (#529) — documented - - Worktree cleanup lifecycle (#530) — 19 tests passing - - Worktree heuristic decision engine (#531) — PR #532 open - -3. **#498 VCS Removal** (Phase 1 audit complete) - - Comprehensive audit of VCS dependencies - - Risk assessment and Phase 2–3 planning prepared - -4. **#533 Doctor Support** (Issue filed) - - User support issue diagnosed and triaged - - Doctor utility enhancement identified for future work - -## Outputs - -### Pull Requests -- PR #1: squad/508-sdk-foundation (d167d39) -- PR #2: squad/508-cli-surface (9e0b5ff) -- PR #3: squad/508-governance (8abe673) -- PR #4: squad/508-tests (0c44bd4) -- PR #532: squad/531-worktree-heuristic - -### GitHub Issues -- #527: Procedures — Issue Lifecycle -- #528: EECOM — Ralph Commands Worktree -- #529: Procedures — Coordinator Worktree -- #530: EECOM — Worktree Cleanup Lifecycle -- #531: Flight — Worktree Heuristic Decision -- #533: Doctor Support (filed) - -### Documentation -- ghost-protocol.md (Ghost Protocol governance) -- personal-charter.md (Personal agent charter template) -- issue-lifecycle.md (Complete lifecycle governance) -- vcs-removal-phase1.md (Audit report) - -## Test Coverage - -- SDK + CLI: 27 tests -- Ralph commands: 25 tests -- Worktree cleanup: 19 tests -- Full suite: 4,818 passing - -## Decisions Captured - -1. Personal agents operate under Ghost Protocol (ambient, no spawn manifest required) -2. Personal squad infrastructure at `~/.squad/agents/` -3. SDK utilities expose resolvePersonalAgents(), mergeSessionCast() -4. CLI `squad personal` subgroup for personal agent management -5. `--team-root` flag allows non-default team roots -6. Worktree cleanup automatic on session completion -7. Heuristic-based worktree strategy selection (worktree vs. inline) - -## Blocking Issues - -None — all work complete and ready for merge/next phase. - -## Team Updates - -- EECOM: Personal squad foundation complete; VCS audit Phase 1 complete -- Procedures: Governance framework established; Issue lifecycle documented -- Flight: Issue decomposition complete; Heuristic decision engine implemented -- FIDO: Comprehensive test coverage added - -## Next Steps - -1. Merge PRs #1–#4 -2. Begin Phase 2 worktree implementation (#527–#531) -3. Continue VCS removal Phase 2 -4. Assign #533 for doctor utility enhancement diff --git a/.squad/orchestration-log/2026-03-22-session-2.md b/.squad/orchestration-log/2026-03-22-session-2.md deleted file mode 100644 index 6e7ebf479..000000000 --- a/.squad/orchestration-log/2026-03-22-session-2.md +++ /dev/null @@ -1,47 +0,0 @@ -# Orchestration Log — 2026-03-22 Session 2 -**Date:** 2026-03-22 -**Operator:** Brady -**Branch:** dev - -## Summary - -Five queued issues from previous session. Executed in two waves (3 parallel agents each). Four PRs merged; one architecture plan deferred to future session. - -## Wave 1 — Parallel (3 agents) - -| Agent | Issues | Work | Output | -|---|---|---|---| -| Flight | #329, #344 | Personal squad architecture review | 20KB design doc, 19-task implementation plan (4 future PRs), 5 gaps patched | -| EECOM | #500 | Economy mode — full SDK + CLI | `squad economy [on\|off]`, `--economy` flag, `readEconomyMode()`/`writeEconomyMode()`, `resolveModel()` integration, 34 tests | -| Procedures | #500, #344 | Governance — economy-mode skill + personal squad proposals | `SKILL.md`, `economy-mode-governance.md`, `personal-squad-governance.md`. Caught `claude-sonnet-4.6` missing from valid models | - -## Wave 2 — Parallel (3 agents) - -| Agent | Issues | Work | Output | -|---|---|---|---| -| EECOM | #502 | node:sqlite workshop blocker (P1) | Hard exit at startup, `squad doctor` check, `engines.node` bumped to `>=22.5.0`, 13 tests | -| EECOM | #464 | Rate limit recovery UX | Clear error message + 3 recovery options (retry time, economy mode, model override), `squad doctor` rate limit check, 36 tests | -| Scribe | — | Wave 1 logging | Orchestration log entries for Wave 1 agents | - -## PRs Merged (dependency order) - -1. **PR #506** `squad/502-node-sqlite-dependency` — node:sqlite version guard → MERGED -2. **PR #504** `squad/500-economy-mode` — economy mode SDK + CLI → MERGED -3. **PR #503** `squad/500-344-governance` — economy skill + governance proposals → MERGED -4. **PR #505** `squad/464-rate-limit-ux` — rate limit recovery UX → MERGED (rebased after #504) - -## Issues Status - -| Issue | Status | Notes | -|---|---|---| -| #329 / #344 | Architecture plan complete | Implementation deferred to future session (4 PRs planned) | -| #500 | ✅ Closed | Economy mode fully implemented and merged | -| #502 | ✅ Closed | node:sqlite workshop blocker fixed (P1) | -| #464 | ✅ Closed | Rate limit recovery UX implemented | -| #328 | Deferred | Not started — remains in queue | - -## Mid-Session Events - -- **Bug report:** Workshop participant (Doron Ben Elazar) hit node:sqlite crash → filed as #502, Tamir cc'd -- **Brady directive:** #464 should offer model switching + economy mode as recovery options -- **Merge conflict:** PR #505 rebased after #504 merge — conflict in `test/cli/doctor.test.ts` resolved diff --git a/.squad/orchestration-log/2026-03-22T23-10.md b/.squad/orchestration-log/2026-03-22T23-10.md deleted file mode 100644 index 441c5f9d7..000000000 --- a/.squad/orchestration-log/2026-03-22T23-10.md +++ /dev/null @@ -1 +0,0 @@ -2026-03-22T23:10Z: Coordinator enabled worktrees, launched #508 fan-out (EECOM SDK + Procedures Governance), Flight authoring #525 sub-issues. Priority restack: #508 first, #525 sub-items replace #347, #498 parallel, hold #481/#347. diff --git a/.squad/orchestration-log/2026-03-22T23-30-session-complete.md b/.squad/orchestration-log/2026-03-22T23-30-session-complete.md deleted file mode 100644 index 6cd67b1b4..000000000 --- a/.squad/orchestration-log/2026-03-22T23-30-session-complete.md +++ /dev/null @@ -1,35 +0,0 @@ -### 2026-03-22T23:30Z: Session Complete — #508 + #525 + #498 - -**Coordinator:** Squad (Copilot CLI) -**User:** Brady - -#### Completed Work - -**#508 Ambient Personal Squad — ALL 4 PRs:** -- PR#1 SDK Foundation → `squad/508-sdk-foundation` (EECOM) -- PR#2 CLI Surface → `squad/508-cli-surface` (EECOM) -- PR#3 Governance → `squad/508-governance` (Procedures) -- PR#4 Tests (27 new, 4818 total) → `squad/508-tests` (FIDO) - -**#525 Worktree Lifecycle — ALL 5 sub-issues:** -- #527 issue-lifecycle.md → `squad/527-issue-lifecycle` (Procedures) -- #528 Worktree ralph-commands → `squad/528-worktree-ralph` (EECOM, 25 tests) -- #529 Coordinator spawn flow → `squad/529-coordinator-worktree` (Procedures) -- #530 Post-merge cleanup → `squad/530-worktree-cleanup` (EECOM, 19 tests) -- #531 Architecture decision → `squad/531-worktree-heuristic` + PR #532 (Flight) - -**#498 VCS Removal Prep:** -- Phase 1 audit → `squad/498-vcs-removal-prep` (EECOM) - -**Infrastructure:** -- Enabled git worktrees for parallel agent work -- Switched auth to bradygaster (public, not EMU) -- Created 6 worktrees for parallel development - -#### Branches Created (11 total) -squad/508-sdk-foundation, squad/508-cli-surface, squad/508-governance, squad/508-tests, -squad/527-issue-lifecycle, squad/528-worktree-ralph, squad/529-coordinator-worktree, -squad/530-worktree-cleanup, squad/531-worktree-heuristic, squad/498-vcs-removal-prep - -#### Agents Spawned: 12 -EECOM (x5), Procedures (x3), Flight (x2), FIDO (x1), Scribe (x1) diff --git a/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-498-vcs-removal-audit.md b/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-498-vcs-removal-audit.md deleted file mode 100644 index d5410e123..000000000 --- a/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-498-vcs-removal-audit.md +++ /dev/null @@ -1,29 +0,0 @@ -# Orchestration Log — EECOM (#498 VCS Removal Audit) -**Session:** 2026-03-23T00:39:00Z (Mega Session) -**Status:** Completed - -## Work Done - -- Conducted VCS removal Phase 1 audit -- Identified code paths dependent on VCS integration -- Documented removal strategy and risk assessment - -## Outputs - -- Branch squad/498-vcs-removal-prep, commit 521c034 -- Audit report `.squad/audits/vcs-removal-phase1.md` - -## Key Decisions - -1. VCS removal requires staged approach (Phase 1–3) -2. Phase 1: audit and dependency mapping complete -3. Risk assessment guides Phase 2–3 planning - -## Blocking - -None — audit complete, Phase 2 planning ready. - -## Next Steps - -- Phase 2: dependency removal and refactoring -- Phase 3: cleanup and integration testing diff --git a/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-528-ralph-commands.md b/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-528-ralph-commands.md deleted file mode 100644 index 8d4f5705f..000000000 --- a/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-528-ralph-commands.md +++ /dev/null @@ -1,30 +0,0 @@ -# Orchestration Log — EECOM (#528 Ralph Commands Worktree) -**Session:** 2026-03-23T00:39:00Z (Mega Session) -**Status:** Completed - -## Work Done - -- Created `ralph-commands` worktree -- Implemented Ralph command infrastructure for spawn coordination -- 25 tests written and passing - -## Outputs - -- Branch squad/528-worktree-ralph, commit 60a4b8b -- Worktree: `.squad/worktrees/ralph-commands/` -- 25 tests for Ralph command logic - -## Key Decisions - -1. Ralph commands provide spawn coordination interface -2. Commands use unified argument structure -3. All tests passing (25/25) - -## Blocking - -None — tests passing, worktree ready. - -## Next Steps - -- Integrate with Coordinator worktree (#529) -- Continue cleanup lifecycle (#530) diff --git a/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-530-worktree-cleanup.md b/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-530-worktree-cleanup.md deleted file mode 100644 index d57d55787..000000000 --- a/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-530-worktree-cleanup.md +++ /dev/null @@ -1,30 +0,0 @@ -# Orchestration Log — EECOM (#530 Worktree Cleanup) -**Session:** 2026-03-23T00:39:00Z (Mega Session) -**Status:** Completed - -## Work Done - -- Implemented worktree cleanup lifecycle -- Cleanup triggered on session completion -- 19 tests written and passing - -## Outputs - -- Branch squad/530-worktree-cleanup, commit f52460d -- Cleanup logic in SDK -- 19 tests for cleanup operations - -## Key Decisions - -1. Cleanup runs automatically on session completion -2. Cleanup removes ephemeral worktrees but preserves permanent ones -3. All tests passing (19/19) - -## Blocking - -None — tests passing, cleanup ready. - -## Next Steps - -- Merge worktree lifecycle implementations -- Flight heuristic decision (#531) diff --git a/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-cli-surface.md b/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-cli-surface.md deleted file mode 100644 index 67f1bf52a..000000000 --- a/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-cli-surface.md +++ /dev/null @@ -1,32 +0,0 @@ -# Orchestration Log — EECOM (CLI Surface) -**Session:** 2026-03-23T00:39:00Z (Mega Session) -**Status:** Completed - -## Work Done - -- Added `squad personal init` command -- Added `squad personal list` command -- Added `squad personal add` command -- Added `squad personal remove` command -- Added `squad cast` command -- Added `--team-root` flag for all commands - -## Outputs - -- PR #2 (branch squad/508-cli-surface, commit 9e0b5ff) -- Modified `packages/squad-cli/src/commands/` with personal squad CLI - -## Key Decisions - -1. Personal commands live under `squad personal` subgroup -2. `--team-root` flag allows non-default team roots -3. `squad cast` displays merged team + personal agents - -## Blocking - -None — ready for merge. - -## Next Steps - -- Merge PR #2 -- Governance documentation (PR #3) diff --git a/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-sdk-foundation.md b/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-sdk-foundation.md deleted file mode 100644 index 91601c82a..000000000 --- a/.squad/orchestration-log/2026-03-23T00-39-00Z-eecom-sdk-foundation.md +++ /dev/null @@ -1,32 +0,0 @@ -# Orchestration Log — EECOM (SDK Foundation) -**Session:** 2026-03-23T00:39:00Z (Mega Session) -**Status:** Completed - -## Work Done - -- Added `personalDir` property to agent configuration -- Implemented `resolvePersonalSquadDir()` utility function -- Created `PersonalAgentMeta` interface for agent metadata -- Implemented `resolvePersonalAgents()` for agent discovery -- Implemented `mergeSessionCast()` for session casting -- Implemented `ensureSquadPathTriple()` utility function - -## Outputs - -- PR #1 (branch squad/508-sdk-foundation, commit d167d39) -- Modified `packages/squad-sdk/src/` with personal squad infrastructure - -## Key Decisions - -1. Personal agents stored in `~/.squad/agents/` -2. SDK provides utilities for discovering and resolving personal agents -3. Session cast merging supports both team and personal agents - -## Blocking - -None — ready for merge. - -## Next Steps - -- Merge PR #1 -- Surface these utilities in CLI layer (PR #2) diff --git a/.squad/orchestration-log/2026-03-23T00-39-00Z-fido-tests.md b/.squad/orchestration-log/2026-03-23T00-39-00Z-fido-tests.md deleted file mode 100644 index afb7f550b..000000000 --- a/.squad/orchestration-log/2026-03-23T00-39-00Z-fido-tests.md +++ /dev/null @@ -1,29 +0,0 @@ -# Orchestration Log — FIDO (Tests) -**Session:** 2026-03-23T00:39:00Z (Mega Session) -**Status:** Completed - -## Work Done - -- Wrote 27 new tests for personal squad SDK and CLI -- All tests passing -- Full test suite: 4,818 passing - -## Outputs - -- PR #4 (branch squad/508-tests, commit 0c44bd4) -- Test files in `packages/squad-sdk/test/` and `packages/squad-cli/test/` - -## Key Decisions - -1. Tests cover SDK utilities and CLI commands -2. Test suite includes personal agent discovery scenarios -3. Cast merging logic tested end-to-end - -## Blocking - -None — ready for merge. - -## Next Steps - -- Merge PR #4 -- Begin Phase 2 work on issue decomposition (#525) diff --git a/.squad/orchestration-log/2026-03-23T00-39-00Z-flight-531-heuristic.md b/.squad/orchestration-log/2026-03-23T00-39-00Z-flight-531-heuristic.md deleted file mode 100644 index 832b296e9..000000000 --- a/.squad/orchestration-log/2026-03-23T00-39-00Z-flight-531-heuristic.md +++ /dev/null @@ -1,29 +0,0 @@ -# Orchestration Log — Flight (#531 Worktree Heuristic) -**Session:** 2026-03-23T00:39:00Z (Mega Session) -**Status:** Completed - -## Work Done - -- Implemented worktree heuristic decision engine -- Heuristic determines optimal worktree strategy based on context - -## Outputs - -- Branch squad/531-worktree-heuristic -- PR #532 open -- Heuristic logic integrated into spawn decision path - -## Key Decisions - -1. Heuristic weighs multiple factors (agent type, task complexity, team size) -2. Decision output: spawn in worktree vs. inline -3. Heuristic improves spawn performance and isolation - -## Blocking - -None — PR #532 ready for merge. - -## Next Steps - -- Merge PR #532 -- Complete Phase 2 implementation diff --git a/.squad/orchestration-log/2026-03-23T00-39-00Z-flight-533-doctor-issue.md b/.squad/orchestration-log/2026-03-23T00-39-00Z-flight-533-doctor-issue.md deleted file mode 100644 index c65029089..000000000 --- a/.squad/orchestration-log/2026-03-23T00-39-00Z-flight-533-doctor-issue.md +++ /dev/null @@ -1,29 +0,0 @@ -# Orchestration Log — Flight (#533 Doctor Support Issue) -**Session:** 2026-03-23T00:39:00Z (Mega Session) -**Status:** Completed - -## Work Done - -- Diagnosed user support issue -- Filed GitHub issue #533 -- Issue: doctor missing agent file check - -## Outputs - -- GitHub issue #533 -- Diagnostic findings documented - -## Key Decisions - -1. Issue requires doctor utility enhancement -2. Agent file validation missing from checks -3. Fix scoped for future work - -## Blocking - -None — issue filed and triaged. - -## Next Steps - -- Assign to appropriate agent for fix -- Add to backlog for next iteration diff --git a/.squad/orchestration-log/2026-03-23T00-39-00Z-flight-issue-decomposition.md b/.squad/orchestration-log/2026-03-23T00-39-00Z-flight-issue-decomposition.md deleted file mode 100644 index c40a8dccd..000000000 --- a/.squad/orchestration-log/2026-03-23T00-39-00Z-flight-issue-decomposition.md +++ /dev/null @@ -1,28 +0,0 @@ -# Orchestration Log — Flight (Issue Decomposition) -**Session:** 2026-03-23T00:39:00Z (Mega Session) -**Status:** Completed - -## Work Done - -- Created GitHub issues #527–#531 as sub-issues of #525 -- Issue hierarchy established for Phase 2 work - -## Outputs - -- GitHub issues: #527 (Procedures), #528 (EECOM), #529 (Procedures), #530 (EECOM), #531 (Flight) -- Labels applied: `squad:procedures`, `squad:eecom`, `squad:flight` - -## Key Decisions - -1. Issue decomposition enables parallel work across agents -2. Each agent owns specific components of worktree/spawn lifecycle -3. Sub-issues dependency-ordered for Phase 2 - -## Blocking - -None — issues open and ready for assignment. - -## Next Steps - -- Assign work to respective agents -- Begin Phase 2 implementation diff --git a/.squad/orchestration-log/2026-03-23T00-39-00Z-procedures-527-issue-lifecycle.md b/.squad/orchestration-log/2026-03-23T00-39-00Z-procedures-527-issue-lifecycle.md deleted file mode 100644 index 35515d5d9..000000000 --- a/.squad/orchestration-log/2026-03-23T00-39-00Z-procedures-527-issue-lifecycle.md +++ /dev/null @@ -1,28 +0,0 @@ -# Orchestration Log — Procedures (#527 Issue Lifecycle) -**Session:** 2026-03-23T00:39:00Z (Mega Session) -**Status:** Completed - -## Work Done - -- Created `issue-lifecycle.md` documenting complete issue lifecycle -- Covers triage → assignment → implementation → closure - -## Outputs - -- Branch squad/527-issue-lifecycle, commit b6d0d30 -- Document `.squad/governance/issue-lifecycle.md` - -## Key Decisions - -1. Issue lifecycle governs workflow from triage to closure -2. Sub-issues tracked in manifest -3. Agent assignment based on capability labels - -## Blocking - -None — ready for merge. - -## Next Steps - -- Merge into procedures documentation -- Continue with #528–#531 diff --git a/.squad/orchestration-log/2026-03-23T00-39-00Z-procedures-529-coordinator-worktree.md b/.squad/orchestration-log/2026-03-23T00-39-00Z-procedures-529-coordinator-worktree.md deleted file mode 100644 index 047e00630..000000000 --- a/.squad/orchestration-log/2026-03-23T00-39-00Z-procedures-529-coordinator-worktree.md +++ /dev/null @@ -1,28 +0,0 @@ -# Orchestration Log — Procedures (#529 Coordinator Worktree) -**Session:** 2026-03-23T00:39:00Z (Mega Session) -**Status:** Completed - -## Work Done - -- Established Coordinator worktree spawn procedures -- Defined agent coordination protocol - -## Outputs - -- Branch squad/529-coordinator-worktree -- Documentation `.squad/coordination/spawn-procedures.md` - -## Key Decisions - -1. Coordinator worktree manages agent spawning lifecycle -2. Spawn procedures follow unified protocol -3. Dependencies tracked in spawn manifest - -## Blocking - -None — procedures documented, ready for implementation. - -## Next Steps - -- Integration with Ralph commands (#528) -- Cleanup lifecycle implementation (#530) diff --git a/.squad/orchestration-log/2026-03-23T00-39-00Z-procedures-governance.md b/.squad/orchestration-log/2026-03-23T00-39-00Z-procedures-governance.md deleted file mode 100644 index 2e15bdf51..000000000 --- a/.squad/orchestration-log/2026-03-23T00-39-00Z-procedures-governance.md +++ /dev/null @@ -1,31 +0,0 @@ -# Orchestration Log — Procedures (Governance) -**Session:** 2026-03-23T00:39:00Z (Mega Session) -**Status:** Completed - -## Work Done - -- Created `ghost-protocol.md` (governance for ambient personal agents) -- Created `personal-charter.md` (charter template for personal agents) -- Updated `squad.agent.md` with personal squad sections - -## Outputs - -- PR #3 (branch squad/508-governance, commit 8abe673) -- Created `.squad/governance/ghost-protocol.md` -- Created `.squad/governance/personal-charter.md` -- Updated `.squad/squad.agent.md` - -## Key Decisions - -1. Personal agents operate under Ghost Protocol (ambient, no spawn manifest) -2. Personal agents use same charter/boundaries as team agents -3. Governance docs define roles, responsibilities, and cross-team interaction - -## Blocking - -None — ready for merge. - -## Next Steps - -- Merge PR #3 -- Begin #527–#531 sub-issue work From 66645d2e561cd74a82a58aeb7716fa107f1073c0 Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Tue, 24 Mar 2026 00:35:16 -0700 Subject: [PATCH 2/7] docs: add v0.9.0 and v0.9.1 releases to What's New - v0.9.1 (Current Release): Bug fixes and hardening - Shell agent name extraction with multi-pattern fallback - Init scaffolding for typed casting files - Personal squad global mode support - Release CI/docs hardening - Doctor command improvements - v0.9.0 (Major Feature): 6 major features + stability fixes - Personal Squad Governance Layer (isolated developer workspaces) - Worktree Spawning & Distributed Work (parallel agent orchestration) - Machine Capability Discovery (auto-detect tools/models/hardware) - Cooperative Rate Limiting (predictive circuit breaker + economy mode) - Telemetry & Infrastructure (auto-wire, KEDA, session recovery) - Docs, Stability & Distribution (Astro enhancements, npm-only) - v0.8.2: Renamed from 'Current Release' to historic entry Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/src/content/docs/whatsnew.md | 53 ++++++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) 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` From cd633137a73c560db114b0e3a3e61c8557c5a2fe Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Wed, 25 Mar 2026 08:32:27 -0700 Subject: [PATCH 3/7] =?UTF-8?q?chore(squad):=20triage=20session=20?= =?UTF-8?q?=E2=80=94=2014=20issues=20triaged,=2010=20PRs=20reviewed?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Flight triaged 14 untriaged GitHub issues, created prioritized work plan - FIDO reviewed 10 open PRs, identified 3 duplicate/overlap pairs - Merged 2 decisions from inbox to decisions.md - Updated Flight and FIDO agent history with team updates - Orchestration logs: 2026-03-25T15-23-flight.md, 2026-03-25T15-23-fido.md - Session log: 2026-03-25T15-23-triage-session.md Work session priority established: - #610 → PAO (broken link, 5 min fix, unblocks #611) - #590 → EECOM (getPersonalSquadRoot bug, P0) - #592, #611 → Flight review - #588 → Procedures (model list update) PR deduplication: 10 PRs consolidate to 7 - Merge: #607, #603, #606 - Close as duplicates: #605, #604, #602 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .squad/agents/fido/history.md | 31 ++ .squad/agents/flight/history.md | 31 ++ .squad/decisions.md | 121 +++++ .squad/proposals/coordinator-restraint.md | 381 +++++++++++++++ .../proposals/prompt-architecture-analysis.md | 439 ++++++++++++++++++ 5 files changed, 1003 insertions(+) create mode 100644 .squad/proposals/coordinator-restraint.md create mode 100644 .squad/proposals/prompt-architecture-analysis.md 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/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/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`.* From 78a0bb1918f8b47c3565865f8fd9069d537af85d Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Wed, 25 Mar 2026 11:27:40 -0700 Subject: [PATCH 4/7] =?UTF-8?q?chore(squad):=20log=20work=20session=20?= =?UTF-8?q?=E2=80=94=20triage,=20fixes,=20research?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round 1 outcomes: - PAO: #610 docs link already resolved - EECOM: #590 personal squad path fix (getPersonalSquadRoot) - Procedures: #588 model catalog updated to current platform - Flight: #612 community issue filed on routing regression - CAPCOM: CLI platform research — identified 8 releases (1.0.4→1.0.11) with 3 high-impact changes - GNC: Squad codebase research — routing regression caused by v0.9.0 prompt saturation + missing name param Round 2: Code review & quality gate - FIDO: Found same bug in shell/index.ts, enforced revision - CONTROL: Full sweep of #590 fix, awaiting FIDO re-review Merged decisions: 1. Personal squad path canonicalization (personal-squad/) 2. Model catalog refresh (claude-sonnet-4.6, gpt-5.3-codex defaults) 3. CLI platform analysis (monorepo discovery, idle hiding, hook injection) 4. Squad regression analysis (prompt saturation, workstream replacement, missing name param) Logs created: - 6 orchestration logs (one per agent) - 1 session synthesis log with research synthesis - 4 agent history updates (team update annotations) All inbox decision files merged and deleted. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .squad/agents/capcom/history.md | 3 + .squad/agents/eecom/history.md | 4 +- .squad/agents/gnc/history.md | 4 + .squad/agents/procedures/history.md | 3 + .squad/decisions.md | 15476 ++++++++-------- .squad/log/2026-03-25T18-11-work-session.md | 176 + .../2026-03-25T18-11-CAPCOM.md | 41 + .../2026-03-25T18-11-EECOM.md | 24 + .../2026-03-25T18-11-Flight.md | 24 + .../orchestration-log/2026-03-25T18-11-GNC.md | 61 + .../orchestration-log/2026-03-25T18-11-PAO.md | 19 + .../2026-03-25T18-11-Procedures.md | 31 + 12 files changed, 8187 insertions(+), 7679 deletions(-) create mode 100644 .squad/log/2026-03-25T18-11-work-session.md create mode 100644 .squad/orchestration-log/2026-03-25T18-11-CAPCOM.md create mode 100644 .squad/orchestration-log/2026-03-25T18-11-EECOM.md create mode 100644 .squad/orchestration-log/2026-03-25T18-11-Flight.md create mode 100644 .squad/orchestration-log/2026-03-25T18-11-GNC.md create mode 100644 .squad/orchestration-log/2026-03-25T18-11-PAO.md create mode 100644 .squad/orchestration-log/2026-03-25T18-11-Procedures.md diff --git a/.squad/agents/capcom/history.md b/.squad/agents/capcom/history.md index 10be08a47..e9c8aeabd 100644 --- a/.squad/agents/capcom/history.md +++ b/.squad/agents/capcom/history.md @@ -64,3 +64,6 @@ Written full technical analysis to `.squad/identity/sdk-init-technical-analysis. - Template system in SDK (`templates/` directory) is well-structured, used correctly by `initSquad()` 📌 **Team update (2026-03-11T01:25:00Z):** 5 SDK Init decisions merged to decisions.md: Phase-based quality improvement (3-phase approach), CastingEngine canonical casting, squad.config.ts as source of truth, Ralph always-included, implementation priority order. Full technical analysis informed Flight's unified PRD and EECOM's roadmap. + +📌 **Team update (2026-03-25T18:11Z):** CLI platform research complete — identified Copilot CLI 1.0.5–1.0.11 (8 releases in 10 days) contain three high-impact changes affecting Squad routing: monorepo instruction discovery (1.0.11), idle subagent hiding (1.0.8), subagentStart hook context injection (1.0.7). SDK version pinning doesn't prevent CLI runtime auto-updates. Recommendations: clean up template naming, upgrade to SDK 0.2.0 customize mode, file CLI issue. Report in decisions inbox. + diff --git a/.squad/agents/eecom/history.md b/.squad/agents/eecom/history.md index bc9b56b6d..8adadf132 100644 --- a/.squad/agents/eecom/history.md +++ b/.squad/agents/eecom/history.md @@ -267,4 +267,6 @@ Executed 3 tasks across 2 waves: economy mode (#500, PR #504), node:sqlite fix ( 4. `personal.ts` - Refactored to reuse `ensurePersonalSquadDir()`. 5. `resolution.test.ts` - Added 3 tests. -**Pattern:** `resolveGlobalSquadPath()` returns the container; `ensurePersonalSquadDir()` creates the subdirectory the rest of the system looks for. \ No newline at end of file +**Pattern:** `resolveGlobalSquadPath()` returns the container; `ensurePersonalSquadDir()` creates the subdirectory the rest of the system looks for. +📌 **Team update (2026-03-25T18:11Z):** Fixed #590 personal squad path regression — getPersonalSquadRoot() now uses canonical personal-squad/ subdirectory like esolvePersonalSquadDir() and nsurePersonalSquadDir(). Committed on squad/590-fix-personal-squad-root. FIDO found same bug in shell/index.ts → work passed to CONTROL for full sweep revision. Awaiting FIDO re-review. + diff --git a/.squad/agents/gnc/history.md b/.squad/agents/gnc/history.md index fb70c50f4..4ca0ecab6 100644 --- a/.squad/agents/gnc/history.md +++ b/.squad/agents/gnc/history.md @@ -19,3 +19,7 @@ Reviewed and merged PR #474 (Node 22 ESM compatibility + bonus exports key fix). **Key learning:** ESM exports key and actual module structure must stay in sync. When adding new entry points, update both package.json (exports) and create the corresponding module file. Missing either step breaks consumers on Node 22+. Test matrix must include Node 22+ to catch these errors early. ### Dual-Layer ESM Fix (Issue #449) Upgraded from single-layer session.js patch to dual-layer approach: (1) Inject `exports` field into vscode-jsonrpc@8.2.1 package.json at postinstall — this is the canonical fix that resolves ALL subpath imports at once, matching vscode-jsonrpc v9.x. (2) Keep session.js `.js` extension patch as defense-in-depth. Added `squad doctor` detection for both layers (checks vscode-jsonrpc exports field and copilot-sdk session.js import syntax). Runtime Module._resolveFilename patch in cli-entry.ts remains as Layer 3 for npx cache hits where postinstall never runs. + +📌 **Team update (2026-03-25T18:11Z):** Routing regression research complete — root cause identified as combination of Squad code changes (v0.9.0 prompt saturation +33%, inlined workflows, missing +ame param in templates #577) AND Copilot CLI platform changes (CAPCOM report). Coordinator prompt grew 711→946 lines, diluting routing constraint. Workstream config replacement broke existing routing. Agent name fix exists on dev (#577) but not shipped. Recommendations: ship #577 immediately, move features to skills, optimize coordinator prompt, create regression tests. Report in decisions inbox. + diff --git a/.squad/agents/procedures/history.md b/.squad/agents/procedures/history.md index bdf10b8e8..b868c8148 100644 --- a/.squad/agents/procedures/history.md +++ b/.squad/agents/procedures/history.md @@ -139,3 +139,6 @@ 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). + +📌 **Team update (2026-03-25T18:11Z):** Model catalog updated to current platform offerings — removed 2 stale models (claude-opus-4.6-fast, gpt-5), added 5 new models (claude-sonnet-4.6, claude-opus-4.6-1m, gpt-5.4, gpt-5.3-codex, gpt-5.4-mini), bumped defaults (code: claude-sonnet-4.6, specialist: gpt-5.3-codex), restructured fallbacks. All 5 squad.agent.md template copies synchronized. Merged in #588. + diff --git a/.squad/decisions.md b/.squad/decisions.md index d6b088e27..d8f010af0 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -1,7705 +1,7825 @@ -# Decisions - -> Team decisions that all agents must respect. Managed by Scribe. - - ---- - -## Foundational Directives (carried from beta, updated for Mission Control) - -### Type safety — strict mode non-negotiable -**By:** CONTROL (formerly Edie) -**What:** `strict: true`, `noUncheckedIndexedAccess: true`, no `@ts-ignore` allowed. -**Why:** Types are contracts. If it compiles, it works. - -### Hook-based governance over prompt instructions -**By:** RETRO (formerly Baer) -**What:** Security, PII, and file-write guards are implemented via the hooks module, NOT prompt instructions. -**Why:** Prompts can be ignored. Hooks are code — they execute deterministically. - -### Node.js >=20, ESM-only, streaming-first -**By:** GNC (formerly Fortier) -**What:** Runtime target is Node.js 20+. ESM-only. Async iterators over buffers. -**Why:** Modern Node.js features enable cleaner async patterns. - -### Casting — Apollo 13, mission identity -**By:** Squad Coordinator -**What:** Team names drawn from Apollo 13 / NASA Mission Control. Scribe is always Scribe. Ralph is always Ralph. Previous universe (The Usual Suspects) retired to alumni. -**Why:** The team outgrew its original universe. Apollo 13 captures collaborative pressure, technical precision, and mission-critical coordination — perfect for an AI agent framework. - -### Proposal-first workflow -**By:** Flight (formerly Keaton) -**What:** Meaningful changes require a proposal in `docs/proposals/` before execution. -**Why:** Proposals create alignment before code is written. - -### Tone ceiling — always enforced -**By:** PAO (formerly McManus) -**What:** No hype, no hand-waving, no claims without citations. -**Why:** Trust is earned through accuracy, not enthusiasm. - -### Zero-dependency scaffolding preserved -**By:** Network (formerly Rabin) -**What:** CLI remains thin. Zero runtime dependencies for the CLI scaffolding path. -**Why:** Users should be able to run `npx` without downloading a dependency tree. - -### Merge driver for append-only files -**By:** Squad Coordinator -**What:** `.gitattributes` uses `merge=union` for `.squad/decisions.md`, `agents/*/history.md`, `log/**`, `orchestration-log/**`. -**Why:** Enables conflict-free merging of team state across branches. - -### Interactive Shell as Primary UX -**By:** Brady -**What:** Squad becomes its own interactive CLI shell. `squad` with no args enters a REPL. -**Why:** Squad needs to own the full interactive experience. - -### 2026-02-21: User directive — no temp/memory files in repo root -**By:** Brady (via Copilot) -**What:** NEVER write temp files, issue files, or memory files to the repo root. All squad state/scratch files belong in .squad/ and ONLY .squad/. Root tree of a user's repo is sacred. -**Why:** User request — hard rule. Captured for all agents. - -### 2026-02-21: npm workspace protocol for monorepo -**By:** Edie (TypeScript Engineer) -**What:** Use npm-native workspace resolution (version-string references) instead of `workspace:*` protocol for cross-package dependencies. -**Why:** The `workspace:*` protocol is pnpm/Yarn-specific. npm workspaces resolve workspace packages automatically. -**Impact:** All inter-package dependencies in `packages/*/package.json` should use the actual version string, not `workspace:*`. - -### 2026-02-21: Distribution is npm-only (GitHub-native removed) -**By:** Rabin (Distribution) + Fenster (Core Dev) -**What:** Squad packages (`@bradygaster/squad-sdk` and `@bradygaster/squad-cli`) are distributed exclusively via npmjs.com. The GitHub-native `npx github:bradygaster/squad` path has been removed. -**Why:** npm is the standard distribution channel. One distribution path reduces confusion and maintenance burden. Root `cli.js` prints deprecation warning if anyone still hits the old path. - -### 2026-02-21: Coordinator prompt structure — three routing modes -**By:** Verbal (Prompt Engineer) -**What:** Coordinator uses structured response format: `DIRECT:` (answer inline), `ROUTE:` + `TASK:` + `CONTEXT:` (single agent), `MULTI:` (fan-out). Unrecognized formats fall back to `DIRECT`. -**Why:** Keyword prefixes are cheap to parse and reliable. Fallback-to-direct prevents silent failures. -### `.squad/` Directory Scope — Owner Directive -**By:** Brady (project owner, PR #326 review) -**Date:** 2026-03-10 - -**Directive:** The `.squad/` directory is **reserved for team state only** — roster, routing, decisions, agent histories, casting, and orchestration logs. Non-team data (adoption tracking, community metrics, reports) must NOT live in `.squad/`. Use `.github/` for GitHub platform integration or `docs/` for documentation artifacts. - -**Source:** [PR #326 comment](https://github.com/bradygaster/squad/pull/326#issuecomment-4029193833) - - ---- - -### No Individual Repo Listing Without Consent — Owner Directive -**By:** Brady (project owner, PR #326 review) -**Date:** 2026-03-10 - -**Directive:** Growth metrics must report **aggregate numbers only** (e.g., "78+ repositories found via GitHub code search") — never name or link to individual community repos without explicit opt-in consent. The monitoring script and GitHub Action concepts are approved, but any public showcase or tracking list that identifies specific repos is blocked until a community consent plan exists. - -**Source:** [PR #326 comment](https://github.com/bradygaster/squad/pull/326#issuecomment-4029222967) - - ---- - -### Adoption Tracking — Opt-In Architecture -**By:** Flight (implementing Brady's directives above) -**Date:** 2026-03-09 - -### 2026-02-21: CLI entry point split — src/index.ts is a pure barrel -**By:** Edie (TypeScript Engineer) -**What:** `src/index.ts` is a pure re-export barrel with ZERO side effects. `src/cli-entry.ts` contains `main()` and all CLI routing. -**Why:** Library consumers importing `@bradygaster/squad` were triggering CLI argument parsing and `process.exit()` on import. - -### 2026-02-21: Process.exit() refactor — library-safe CLI functions -**By:** Kujan (SDK Expert) -**What:** `fatal()` throws `SquadError` instead of `process.exit(1)`. Only `cli-entry.ts` may call `process.exit()`. -**Pattern:** Library functions throw `SquadError`. CLI entry catches and exits. Library consumers catch for structured error handling. - -### 2026-02-21: User directive — docs as you go -**By:** bradygaster (via Copilot) -**What:** Doc and blog as you go during SquadUI integration work. Doesn't have to be perfect — keep docs updated incrementally. - -### 2026-02-22: Runtime EventBus as canonical bus -**By:** Fortier -**What:** `runtime/event-bus.ts` (colon-notation: `session:created`, `subscribe()` API) is the canonical EventBus for all orchestration classes. The `client/event-bus.ts` (dot-notation) remains for backward-compat but should not be used in new code. -**Why:** Runtime EventBus has proper error isolation — one handler failure doesn't crash others. - -### 2026-02-22: Subpath exports in @bradygaster/squad-sdk -**By:** Edie (TypeScript Engineer) -**What:** SDK declares subpath exports (`.`, `./parsers`, `./types`, and module paths). Each uses types-first condition ordering. -**Constraints:** Every subpath needs a source barrel. `"types"` before `"import"`. ESM-only: no `"require"` condition. - -### 2026-02-22: User directive — Aspire testing requirements -**By:** Brady (via Copilot) -**What:** Integration tests must launch the Aspire dashboard and validate OTel telemetry shows up. Use Playwright. Use latest Aspire bits. Reference aspire.dev (NOT learn.microsoft.com). It's "Aspire" not ".NET Aspire". - -### 2026-02-23: User directive — code fences -**By:** Brady (via Copilot) -**What:** Never use / or \ as code fences in GitHub issues, PRs, or comments. Only use backticks to format code. - -### 2026-02-23: User Directive — Docs Overhaul & Publication Pause -**By:** Brady (via Copilot) -**What:** Pause docs publication until Brady explicitly gives go-ahead. Tone: lighthearted, welcoming, fun (NOT stuffy). First doc should be "first experience" with squad CLI. All docs: brief, prompt-first, action-oriented, fun. Human tone throughout. - -### 2026-02-23: Use sendAndWait for streaming dispatch -**By:** Kovash (REPL Expert) -**What:** `dispatchToAgent()` and `dispatchToCoordinator()` use `sendAndWait()` instead of `sendMessage()`. Fallback listens for `turn_end`/`idle` if unavailable. -**Why:** `sendMessage()` is fire-and-forget — resolves before streaming deltas arrive. -**Impact:** Never parse `accumulated` after a bare `sendMessage()`. Always use `awaitStreamedResponse`. - -### 2026-02-23: extractDelta field priority — deltaContent first -**By:** Kovash (REPL Expert) -**What:** `extractDelta` priority: `deltaContent` > `delta` > `content`. Matches SDK actual format. -**Impact:** Use `deltaContent` as the canonical field name for streamed text chunks. - -### 2026-02-24: Per-command --help/-h: intercept-before-dispatch pattern -**By:** Fenster (Core Dev) -**What:** All CLI subcommands support `--help` and `-h`. Help intercepted before command routing prevents destructive commands from executing. -**Convention:** New CLI commands MUST have a `getCommandHelp()` entry with usage, description, options, and 2+ examples. - -### 2026-02-25: REPL cancellation and configurable timeout -**By:** Kovash (REPL Expert) -**What:** Ctrl+C immediately resets `processing` state. Timeout: `SQUAD_REPL_TIMEOUT` (seconds) > `SQUAD_SESSION_TIMEOUT_MS` (ms) > 600000ms default. CLI `--timeout` flag sets env var. - -### 2026-02-24: Shell Observability Metrics -**By:** Saul (Aspire & Observability) -**What:** Four metrics under `squad.shell.*` namespace, gated behind `SQUAD_TELEMETRY=1`. -**Convention:** Shell metrics require explicit consent via `SQUAD_TELEMETRY=1`, separate from OTLP endpoint activation. - -### 2026-02-23: Telemetry in both CLI and agent modes -**By:** Brady (via Copilot) -**What:** Squad should pump telemetry during BOTH modes: (1) standalone Squad CLI, and (2) running as an agent inside GitHub Copilot CLI. - -### 2026-02-27: ASCII-only separators and NO_COLOR -**By:** Cheritto (TUI Engineer) -**What:** All separators use ASCII hyphens. Text-over-emoji principle: text status is primary, emoji is supplementary. -**Convention:** Use ASCII hyphens for separators. Keep emoji out of status/system messages. - -### 2026-02-24: Version format — bare semver canonical -**By:** Fenster -**What:** Bare semver (e.g., `0.8.5.1`) for version commands. Display contexts use `squad v{VERSION}`. - -### 2026-02-25: Help text — progressive disclosure -**By:** Fenster -**What:** Default `/help` shows 4 essential lines. `/help full` shows complete reference. - -### 2026-02-24: Unified status vocabulary -**By:** Marquez (CLI UX Designer) -**What:** Use `[WORK]` / `[STREAM]` / `[ERR]` / `[IDLE]` across ALL status surfaces. -**Why:** Most granular, NO_COLOR compatible, text-over-emoji, consistent across contexts. - -### 2026-02-24: Pick one tagline -**By:** Marquez (CLI UX Designer) -**What:** Use "Team of AI agents at your fingertips" everywhere. - -### 2026-02-24: User directive — experimental messaging -**By:** Brady (via Copilot) -**What:** CLI docs should note the project is experimental and ask users to file issues. - -### 2026-02-28: User directive — DO NOT merge PR #547 -**By:** Brady (via Copilot) -**What:** DO NOT merge PR #547 (Squad Remote Control). Do not touch #547 at all. -**Why:** User request — captured for team memory - -### 2026-02-28: CLI Critical Gap Issues Filed -**By:** Keaton (Lead) -**What:** 4 critical CLI gaps filed as GitHub issues #554–#557 for explicit team tracking: -- #554: `--preview` flag undocumented and untested -- #556: `--timeout` flag undocumented and untested -- #557: `upgrade --self` is dead code -- #555: `run` subcommand is a stub (non-functional) - -**Why:** Orchestration logs captured gaps but they lacked actionable GitHub tracking and ownership. Filed issues now have explicit assignment to Fenster, clear acceptance criteria, and visibility in Wave E planning. - -### 2026-02-28: Test Gap Issues Filed (10 items) -**By:** Hockney (Tester) -**What:** 10 moderate CLI/test gaps filed as issues #558–#567: -- #558: Exit code consistency untested -- #559: Timeout edge cases untested -- #560: Missing per-command help -- #561: Shell-specific flag behavior untested -- #562: Env var fallback paths untested -- #563: REPL mode transitions untested -- #564: Config file precedence untested -- #565: Agent spawn flags undocumented -- #566: Untested flag aliases -- #567: Flag parsing error handling untested - -**Why:** Each gap identified in coverage analysis but lacked explicit GitHub tracking for prioritization and team visibility. - -### 2026-02-28: Documentation Audit Results (10 issues) -**By:** McManus (DevRel) -**What:** Docs audit filed 10 GitHub issues (#568–#575, #577–#578) spanning: -- Feature documentation lag (#568 `squad run`, #570 consult mode, #572 Ralph smart triage) -- Terminology inconsistency (#569 triage/watch/loop naming) -- Brand compliance (#571 experimental banner on 40+ docs) -- Clarity/UX gaps (#573 response modes, #575 dual-root, #577 VS Code, #578 session examples) -- Reference issue (#574 README command count) - -**Why:** Features shipped faster than documentation. PR #552, #553 merged without doc updates. No automation to enforce experimental banner. Users discover advanced features accidentally. - -**Root cause:** Feature-docs lag, decision-doc drift, no brand enforcement in CI. - -### 2026-02-28: Dogfood UX Issues Filed (4 items) -**By:** Waingro (Dogfooder) -**What:** Dogfood testing against 8 realistic scenarios surfaced 4 UX issues (filed as #576, #579–#581): -- #576 (P1): Shell launch fails in non-TTY piped mode (Blocks CI) -- #580 (P1): Help text overwhelms new users (44 lines, no tiering) -- #579 (P2): Status shows parent `.squad/` as local (confusing in multi-project workspaces) -- #581 (P2): Error messages show debug output always (noisy production logs) - -**Why:** CLI is solid for happy path but first-time user experience and CI/CD integration have friction points. All 4 block either new user onboarding or automation workflows. - -**Priority:** #576 > #580 > #581 > #579. All should be fixed before next public release. - -### 2026-02-28: decisions.md Aggressive Cleanup -**By:** Keaton (Lead) -**What:** Trimmed `decisions.md` from 226KB (223 entries) to 10.3KB (35 entries) — 95% reduction. -- Kept: Core architectural decisions, active process rules, active user directives, current UX conventions, runtime patterns -- Archived: Implementation details, one-time setup, PR reviews, audit reports, wave planning, superseded decisions, duplicates -- Created: `decisions-archive.md` with full original content preserved - -**Why:** Context window bloat during release push. Every agent loads 95% less decisions context. Full history preserved append-only. - -**Impact:** File size reduced, agent context efficiency improved, all decisions preserved in archive. - -### 2026-02-28: Backlog Gap Issues Filed (8 items) -**By:** Keaton (Lead) -**Approval:** Brady (via directive in issue request) -**What:** Filed 8 missing backlog items from `.squad/identity/now.md` as GitHub issues. These items were identified as "should-fix" polish or "post-M1" improvements but lacked explicit GitHub tracking until now. - -**Why:** Brady requested: "Cross-reference the known backlog against filed issues and file anything missing." The team had filed 28 issues this session (#554–#581), but 8 known items from `now.md` remained unfiled. Without GitHub issues, these lack ownership assignment, visibility for Wave E planning, trackability in automated workflows, and routing to squad members. - -**Issues Filed:** -- #583 (squad:rabin): Add `homepage` and `bugs` fields to package.json -- #584 (squad:mcmanus): Document alpha→v1.0 breaking change policy in README -- #585 (squad:edie): Add `noUncheckedIndexedAccess` to tsconfig -- #586 (squad:edie): Tighten ~26 `any` types in SDK -- #587 (squad:mcmanus): Add architecture overview doc -- #588 (squad:kujan): Implement SQUAD_DEBUG env var test -- #589 (squad:kujan): One real Copilot SDK integration test -- #590 (squad:baer): `npm audit fix` for dev-dependency ReDoS warnings -- #591 (squad:hockney, type:bug): Aspire dashboard test fails — docker pull in test suite -- #592 (squad:rabin): Replace workspace:* protocol with version string - -**Impact:** Full backlog now visible with explicit issues. No unmapped items. Each issue routed to the squad member domain expert. Issues are independent; can be executed in any order. - -### 2026-02-28: Codebase Scan — Unfiled Issues Audit -**By:** Fenster (Core Dev) -**Requested by:** Brady -**Date:** 2026-02-28T22:05:00Z -**Status:** Complete — 2 new issues filed - -**What:** Systematic scan of the codebase to identify known issues that haven't been filed as GitHub issues. Checked: -1. TODO/FIXME/HACK/XXX comments in code -2. TypeScript strict mode violations (@ts-ignore/@ts-expect-error) -3. Skipped/todo tests (.skip() or .todo()) -4. Errant console.log statements -5. Missing package.json metadata fields - -**Findings:** -- Type safety violations: ✅ CLEAN — Zero @ts-ignore/@ts-expect-error found. Strict mode compliance excellent. -- Workspace protocol: ❌ VIOLATION — 1 issue filed (#592): `workspace:*` in squad-cli violates npm workspace convention -- Skipped tests: ❌ GAP — 1 issue filed (#588): SQUAD_DEBUG test is .todo() placeholder -- Console.log: ✅ INTENTIONAL — All are user-facing output (status, errors) -- TODO comments: ✅ TEMPLATES — TODOs in generated workflow templates, not code -- Package.json: ✅ TRACKED — Missing homepage/bugs already filed as #583 - -**Code Quality Assessment:** -- Type Safety (Excellent): Zero violations of strict mode or type suppression. Team decision being followed faithfully. -- TODO/FIXME Comments (Clean): All TODOs in upgrade.ts and workflows.ts are template strings for generated GitHub Actions YAML, intentionally scoped. -- Console Output (Intentional): All are user-facing (dashboard startup, OTLP endpoint, issue labeling, shell loading) — no debug debris. -- Dead Code (None Found): No unreachable code, orphaned functions, or unused exports detected. - -**Recommendations:** -1. Immediate: Fix workspace protocol violation (#592) — violates established team convention -2. Soon: Implement SQUAD_DEBUG test (#588) — fills observable test gap -3. Going forward: Maintain type discipline; review package.json metadata during SDK/CLI version bumps - -**Conclusion:** Codebase in good health. Type safety discipline strong. No hidden technical debt. Conventions mostly followed (one npm workspace exception). Test coverage has minor gaps in observability. - -### 2026-02-28: Auto-link detection for preview builds -**By:** Fenster (Core Dev) -**Date:** 2026-02-28 -**What:** When running from source (`VERSION` contains `-preview`), the CLI checks if `@bradygaster/squad-cli` is globally npm-linked. If not, it prompts the developer to link it. Declining creates `~/.squad/.no-auto-link` to suppress future prompts. -**Why:** Dev convenience — saves contributors from forgetting `npm link` after cloning. Non-interactive commands (help, version, export, import, doctor, scrub-emails) skip the check. Everything is wrapped in try/catch so failures are silent. -**Impact:** Only affects `-preview` builds in interactive TTY sessions. No effect on published releases or CI. - -### 2026-03-01T00:34Z: User directive — Full scrollback support in REPL shell -**By:** Brady (via Copilot) -**What:** The REPL shell must support full scrollback — users should be able to scroll up and down to see all text (paste, run output, rendered content, logs) over time, like GitHub Copilot CLI does. The current Ink-based rendering loses/hides content and that's unacceptable. -**Why:** User request — captured for team memory. This is a P0 UX requirement for the shell. -**Status:** P0 blocking issue. Requires rendering architecture review (Cheritto, Kovash, Marquez). - -### 2026-03-01T04:47Z: User directive — Auto-incrementing build numbers -**By:** Brady (via Copilot) -**What:** Add auto-incrementing build numbers to versions. Format: `0.8.6.{N}-preview` where N increments each local build. Tracks build-to-release cadence. -**Why:** User request — captured for team memory. - -### 2026-03-01: Nap engine — dual sync/async export pattern -**By:** Fenster (Core Dev) -**What:** The nap engine (`cli/core/nap.ts`) exports both `runNap` (async, for CLI entry) and `runNapSync` (sync, for REPL). All internal operations use sync fs calls. The async wrapper exists for CLI convention consistency. -**Why:** REPL `executeCommand` is synchronous and cannot await. ESM forbids `require()`. Exporting a sync variant keeps the REPL integration clean without changing the shell architecture. -**Impact:** Future commands that need both CLI and REPL support should follow this pattern if they only do sync fs work. - -### 2026-03-01: First-run gating test strategy -**By:** Hockney (Tester) -**Date:** 2026-03-01 -**Issue:** #607 -**What:** Created `test/first-run-gating.test.ts` with 25 tests covering 6 categories of Init Mode gating. Tests use logic-level extraction from App.tsx conditionals, filesystem marker lifecycle via `loadWelcomeData`, and source-code structural assertions for render ordering. No full App component rendering — SDK dependencies make that impractical for unit tests. -**Why:** 3059 tests existed with zero enforcement of first-run gating behavior. The `.first-run` marker, banner uniqueness, assembled-message gating, warning suppression, session-scoped keys, and terminal clear ordering were all untested paths that could regress silently. -**Impact:** All squad members: if you modify `loadWelcomeData`, the `firstRunElement` conditional in App.tsx, or the terminal clear sequence in `runShell`, these tests will catch regressions. The warning suppression tests replicate the `cli-entry.ts` pattern — if that pattern changes, update both locations. - -### Verbal's Analysis: "nap" Skill — Context Window Optimization -**By:** Verbal (Prompt Engineer) -**Requested by:** Brady -**Date:** 2026-03-01 -**Scope:** Approved. Build it. Current context budget analysis: -- Agent spawn loads charter (~500t) + history + decisions.md (4,852t) + team.md (972t) -- Hockney: 25,940t history (worst offender) -- Fenster: 22,574t (history + CLI inventory) -- Coherence cliff: 40-50K tokens on non-task context - -**Key Recommendations:** -1. **Decision distillation:** Keep decisions.md as single source of truth (don't embed in charters — creates staleness/duplication) -2. **History compression — 12KB rule insufficient:** Six agents blow past threshold. Target **4KB ceiling per history** (~1,000t) with assertions not stories. -3. **Nap should optimize:** Deduplication (strip decisions.md content echoed in histories), staleness (flag closed PRs, merged work), charter bloat (stay <600t), skill pruning (archive high-confidence, no-recent-invocation skills), demand-loading for extra files (CLI inventory, UX catalog, fragility catalog). -4. **Enforcement:** Nap runs periodically or on-demand, enforces hard ceilings without silent quality degradation. - -### ShellApi.clearMessages() for terminal state reset -**By:** Kovash (REPL Expert) -**Date:** 2026-03-01 -**What:** `ShellApi` now exposes `clearMessages()` which resets both `messages` and `archivedMessages` React state. Used in session restore and `/clear` command. -**Why:** Without clearing archived messages, old content bleeds through when restoring sessions or clearing the shell. The `/clear` command previously only reset `messages`, leaving `archivedMessages` in the Static render list. -**Impact:** Any code calling `shellApi` to reset shell state should use `clearMessages()` rather than manually manipulating message arrays. - -### 2026-03-01: Prompt placeholder hints must not duplicate header banner -**By:** Kovash (REPL Expert) -**Date:** 2026-03-01 -**Issue:** #606 -**What:** The InputPrompt placeholder text must provide *complementary* guidance, never repeat what the header banner already shows. The header banner is the single source of truth for @agent routing and /help discovery. Placeholder hints should surface lesser-known features (tab completion, history navigation, utility commands). -**Why:** Two elements showing "Type @agent or /help" simultaneously creates visual noise and a confusing UX. One consistent prompt style throughout the session. -**Impact:** `getHintText()` in InputPrompt.tsx now has two tiers instead of three. Any future prompt hints should check the header banner first to avoid duplication. - -### 2026-03-02: Paste detection via debounce in InputPrompt -**By:** Kovash (REPL Expert) -**Date:** 2026-03-02 -**What:** InputPrompt uses a 10ms debounce on `key.return` to distinguish paste from intentional Enter. If more input arrives within 10ms → paste detected → newline preserved. If timer fires without input → real Enter → submit. A `valueRef` (React ref) mirrors mutations synchronously since closure-captured `value` is stale during rapid `useInput` calls. In disabled state, `key.return` appends `\n` to buffer instead of being ignored. -**Why:** Multi-line paste was garbled because `useInput` fires per-character and `key.return` triggered immediate submission. -**Impact:** 10ms delay on single-line submit is imperceptible. UX: multi-line paste preserved. Testing: Hockney should verify paste scenarios use `jest.useFakeTimers()` or equivalent. Future: if Ink adds native bracketed-paste support, debounce can be replaced. - -### 2026-03-01: First-run init messaging — single source of truth -**By:** Kovash (REPL & Interactive Shell) -**Date:** 2026-03-01 -**Issue:** #625 -**What:** When no roster exists, only the header banner tells the user about `squad init` / `/init`. The `firstRunElement` block returns `null` for the empty-roster case instead of showing a duplicate message. `firstRunElement` is reserved for the "Your squad is assembled" onboarding when a roster already exists. -**Why:** Two competing UI elements both said "run squad init" — visual noise that confuses the information hierarchy. Banner is persistent and visible; it owns the no-roster guidance. `firstRunElement` owns the roster-present first-run experience. -**Impact:** App.tsx only. No API or prop changes. Banner text reworded to prioritize `/init` (in-shell path) over exit-and-run. - -### 2026-03-01: NODE_NO_WARNINGS for subprocess warning suppression -**By:** Cheritto (TUI Engineer) -**Date:** 2026-03-01 -**Issue:** #624 -**What:** `process.env.NODE_NO_WARNINGS = '1'` is set as the first executable line in `cli-entry.ts` (line 2, after shebang). This supplements the existing `process.emitWarning` override. -**Why:** The Copilot SDK spawns child processes that inherit environment variables but NOT in-process monkey-patches like `process.emitWarning` overrides. `NODE_NO_WARNINGS=1` is the Node.js-native mechanism for suppressing warnings across an entire process tree. Without it, `ExperimentalWarning` messages (e.g., SQLite) leak into the terminal via the SDK's subprocess stderr forwarding. -**Pattern:** When suppressing Node.js warnings, use BOTH: (1) `process.env.NODE_NO_WARNINGS = '1'` — covers child processes (env var inheritance); (2) `process.emitWarning` override — covers main process (belt-and-suspenders). -**Impact:** Eliminates `ExperimentalWarning` noise in terminal for all Squad CLI users, including when the Copilot SDK spawns subprocesses. - -### 2026-03-01: No content suppression based on terminal width -**By:** Cheritto (TUI Engineer) -**Date:** 2026-03-01 -**What:** Terminal width tiers (compact ≤60, standard, wide ≥100) may adjust *layout* (e.g., wrapping, column arrangement) but must NOT suppress or truncate *content*. Every piece of information shown at 120 columns must also be shown at 40 columns. -**Why:** Users can scroll. Hiding roster names, spacing, help text, or routing hints on narrow terminals removes information the user needs. Layout adapts to width; content does not. -**Convention:** `compact` variable may be used for layout decisions (flex direction, column vs. row) but must NOT gate visibility of text, spacing, or UI sections. `wide` may add supplementary content but narrow must not remove it. - -### 2026-03-01: Multi-line user message rendering pattern -**By:** Cheritto (TUI Engineer) -**Date:** 2026-03-01 -**What:** Multi-line user messages in the Static scrollback use `split('\n')` with a column layout: first line gets the `❯` prefix, subsequent lines get `paddingLeft={2}` for alignment. -**Why:** Ink's horizontal `` layout doesn't handle embedded `\n` in `` children predictably when siblings exist. Explicit line splitting with column flex direction gives deterministic multi-line rendering. -**Impact:** Any future changes to user message prefix width must update the `paddingLeft={2}` on continuation lines to match. - -### 2026-03-01: Elapsed time display — inline after message content -**By:** Cheritto (TUI Engineer) -**Date:** 2026-03-01 -**Issue:** #605 -**What:** Elapsed time annotations on completed agent messages are always rendered inline after the message content as `(X.Xs)` in dimColor. This applies to the Static scrollback block in App.tsx, which is the canonical render path for all completed messages. -**Why:** After the Static scrollback refactor, MessageStream receives `messages=[]` and only renders live streaming content. The duration code in MessageStream was dead. Moving duration display into the Static block ensures it always appears consistently. -**Convention:** `formatDuration()` from MessageStream.tsx is the shared formatter. Format is `Xms` for <1s, `X.Xs` for ≥1s. Always inline, always dimColor, always after content text. - -### 2026-03-01: Banner usage line separator convention -**By:** Cheritto (TUI Engineer) -**Date:** 2026-03-01 -**What:** Banner hint/usage lines use middle dot `·` as inline separator. Init messages use single CTA (no dual-path instructions). -**Why:** Consistent visual rhythm. Middle dot is lighter than em-dash or hyphen for inline command lists. Single CTA reduces cognitive load for new users. -**Impact:** App.tsx headerElement. Future banner copy should follow same separator and single-CTA pattern. - -### 2026-03-02: REPL casting engine design -**By:** Fenster (Core Dev) -**Date:** 2026-03-02 -**Status:** Implemented -**Issue:** #638 -**What:** Created `packages/squad-cli/src/cli/core/cast.ts` as a self-contained casting engine with four exports: -1. `parseCastResponse()` — parses the `INIT_TEAM:` format from coordinator output -2. `createTeam()` — scaffolds all `.squad/agents/` directories, writes charters, updates team.md and routing.md, writes casting state JSON -3. `roleToEmoji()` — maps role strings to emoji, reusable across the CLI -4. `formatCastSummary()` — renders a padded roster summary for terminal display - -Scribe and Ralph are always injected if missing from the proposal. Casting state is written to `.squad/casting/` (registry.json, history.json, policy.json). -**Why:** Enables coordinator to propose and create teams from within the REPL session after `squad init`. -**Implications:** - -### 2026-03-02: Beta → Origin Migration: Version Path (v0.5.4 → v0.8.17) - -**By:** Kobayashi (Git & Release) -**Date:** 2026-03-02 -**Context:** Analyzed migration from beta repo (`bradygaster/squad`, v0.5.4) to origin repo (`bradygaster/squad-pr`, v0.8.18-preview). Version gap spans 0.6.x, 0.7.x, 0.8.0–0.8.16 (internal origin development only). - -**What:** Beta will jump directly from v0.5.4 to v0.8.17 (skip all intermediate versions). Rationale: -1. **Semantic versioning allows gaps** — version numbers are labels, not counters -2. **Users care about features, not numbers** — comprehensive changelog is more valuable than version sequence -3. **Simplicity reduces risk** — single migration release is easier to execute and communicate -4. **Precedent exists** — major refactors/rewrites commonly skip versions (Angular 2→4, etc) - -**Risks & Mitigations:** -- Risk: Version jump confuses users. Mitigation: Clear release notes explaining the gap + comprehensive changelog -- Risk: Intermediate versions were never public (no user expectations). Mitigation: This is actually a benefit — no backfill needed - -**Impact:** After merge, beta repo version jumps from v0.5.4 to v0.8.17. All intermediate work is included in the 0.8.17 release. Next release after v0.8.17 may be v0.8.18 or v0.9.0 (team decision post-merge). - -**Why:** Avoids maintenance burden of backfilling 12+ fake versions. Users get complete feature set in one migration release. - -### 2026-03-02: Beta → Origin Migration: Package Naming - -**By:** Kobayashi (Git & Release) -**Date:** 2026-03-02 - -**What:** Deprecate `@bradygaster/create-squad` (beta's package name). All future releases use: -- `@bradygaster/squad-cli` (user-facing CLI) -- `@bradygaster/squad-sdk` (programmatic SDK for integrations) - -**Why:** Origin's naming is more accurate and supports independent versioning if needed. Monorepo structure benefits from clear package separation. - -**Action:** When v0.8.17 is ready to publish, release a final version of `@bradygaster/create-squad` with deprecation notice: "This package has been renamed to @bradygaster/squad-cli. Install with: npm install -g @bradygaster/squad-cli" - -**Impact:** Package ecosystem clarity. No breaking change for users upgrading (CLI handles detection and warnings). - -### 2026-03-02: Beta → Origin Migration: Retroactive v0.8.17 Tag - -**By:** Kobayashi (Git & Release) -**Date:** 2026-03-02 - -**What:** Retroactively tag commit `5b57476` ("chore(release): prep v0.8.16 for npm publish") as v0.8.17. This commit and v0.8.16 have identical code. - -**Rationale:** -- Commit `6fdf9d5` jumped directly to v0.8.17-preview (no v0.8.17 release tag exists) -- Commit `87e4f1c` bumps to v0.8.18-preview "after 0.8.17 release" (implying v0.8.17 was released) -- Retroactive tagging is less disruptive than creating a new prep commit and rebasing - -**Action:** When banana gate clears, tag origin commit `5b57476` as v0.8.17. - -**Why:** Completes the missing link in origin's tag history. Indicates to users which commit was released as v0.8.17. - -### 2026-03-02: npx Distribution Migration: Error-Only Shim Strategy - -**By:** Rabin (Distribution) -**Date:** 2026-03-02 -**Context:** Beta repo currently uses GitHub-native distribution (`npx github:bradygaster/squad`). Origin uses npm distribution (`npm install -g @bradygaster/squad-cli`). After merge, old path will break. - -**Problem:** After migration, `npx github:bradygaster/squad` fails (root `package.json` has no `bin` entry). Users hitting the old path get cryptic npm error. - -**Solution — Option 5 (Error-only shim):** -1. Add root `bin` entry pointing to `cli.js` -2. `cli.js` detects GitHub-native invocation and prints **bold, clear error** with migration instructions -3. Exit with code 1 (fail fast, no hidden redirection) - -**Implementation:** -```json -{ - "bin": { - "squad": "./cli.js" - } -} -``` - -Update `cli.js` to print error message with new install instructions: -``` -npm install -g @bradygaster/squad-cli -``` - -**Pros:** -- ✅ Clear, actionable error message (not cryptic npm error) -- ✅ Aligns with npm-only team decision (no perpetuation of GitHub-native path) -- ✅ Low maintenance burden (simple error script, no complex shim) -- ✅ Can be removed in v1.0.0 when beta users have migrated - -**Cons:** -- Immediate breakage (no grace period) — but users get clear guidance - -**Why This Over Others:** -- Option 1 (keep working) contradicts npm-only decision -- Option 2 (exit early) same as this, but explicit error format needed -- Option 3 (time-limited) best UX but maintenance burden -- Option 4 (just break) user-hostile without error message -- **Option 5 balances user experience + team decision** - -**Related Decision:** See 2026-02-21 decision "Distribution is npm-only (GitHub-native removed)" - -**User Impact:** -- Users running `npx github:bradygaster/squad` see bold error with `npm install -g @bradygaster/squad-cli` instruction -- Existing projects running `squad upgrade` work seamlessly (upgrade logic built-in) -- No data loss or silent breakage - -**Upgrade Path (existing beta users):** -```bash -npm install -g @bradygaster/squad-cli -cd /path/to/project -squad upgrade -squad upgrade --migrate-directory # Optional: .ai-team/ → .squad/ -``` - -**Why:** Rabin's principle: "If users have to think about installation, install is broken." A clear error message respects users better than a cryptic npm error. - -### 2026-02-28: Init flow reliability — proposal-first before code - -**By:** Keaton (Lead) -**Date:** 2026-02-28 -**What:** Init/onboarding fixes require a proposal review before implementation. Proposal at `docs/proposals/reliable-init-flow.md`. Two confirmed bugs (race condition in auto-cast, Ctrl+C doesn't abort init session) plus UX gaps (empty-roster messaging, `/init` no-op). P0 bugs are surgical — don't expand scope. -**Why:** Four PRs (#637–#640) patched init iteratively without a unified design. Before writing more patches, the team needs to agree on the golden path. Proposal-first (per team decision 2026-02-21). -**Impact:** Blocks init-related code changes until Brady reviews the proposal. -- Kovash (REPL): Can call `parseCastResponse` + `createTeam` to wire up casting flow in shell dispatcher -- Verbal (Prompts): INIT_TEAM format is now the contract — coordinator prompt should emit this -- Hockney (Tests): cast.ts needs unit tests for parser edge cases, emoji mapping, file creation - -### 2026-03-02: REPL empty-roster gate — dual check pattern -**By:** Fenster (Core Dev) -**Date:** 2026-03-02 -**What:** REPL dispatch is now gated on *populated* roster, not just team.md existence. `hasRosterEntries()` in `coordinator.ts` checks for table data rows in the `## Members` section. Two layers: `handleDispatch` blocks with user guidance, `buildCoordinatorPrompt` injects refusal prompt. -**Why:** After `squad init`, team.md exists but is empty. Coordinator received a "route to agents" prompt with no agents listed, causing silent generic AI behavior. Users never got told to cast their team. -**Convention:** Post-init message references "Copilot session" (works in VS Code, github.com, and Copilot CLI). The `/init` slash command provides same guidance inside REPL. -**Impact:** All agents — if you modify the `## Members` table format in team.md templates, update `hasRosterEntries()` to match. - -### 2026-03-02: Connection promise dedup in SquadClient -**By:** Fenster (Core Dev) -**Date:** 2026-03-02 -**What:** `SquadClient.connect()` now uses a promise dedup pattern — concurrent callers share the same in-flight `connectPromise` instead of throwing "Connection already in progress". -**Why:** Eager warm-up and auto-cast both call `createSession()` → `connect()` at REPL startup, racing on the connection. The throw crashed auto-cast every time. -**Impact:** `packages/squad-sdk/src/adapter/client.ts` only. No API surface change. - -### 2026-03-01: CLI UI Polish PRD — Alpha Shipment Over Perfection -**By:** Keaton (Lead) -**Date:** 2026-03-01 -**Context:** Team image review identified 20+ UX issues ranging from P0 blockers to P3 future polish - -**What:** CLI UI polish follows pragmatic alpha shipment strategy: fix P0 blockers + P1 quick wins, defer grand redesign to post-alpha. 20 discrete issues created with clear priority tiers (P0/P1/P2/P3). - -**Why:** Brady confirmed "alpha-level shipment acceptable — no grand redesign today." Team converged on 3 P0 blockers (blank screens, static spinner, missing alpha banner) that would embarrass us vs. 15+ polish items that can iterate post-ship. - -**Trade-off:** Shipping with known layout quirks (input positioning, responsive tables) rather than blocking on 1-2 week TUI refactor. Users expect alpha rough edges IF we warn them upfront. - -**Priority Rationale:** -- **P0 (must fix):** User-facing broken states — blank screens, no feedback, looks crashed -- **P1 (quick wins):** Accessibility (contrast), usability (copy clarity), visual hierarchy — high ROI, low effort -- **P2 (next sprint):** Layout architecture, responsive design — important but alpha-acceptable if missing -- **P3 (future):** Fixed bottom input, alt screen buffer, creative spinner — delightful but not blockers - -**Architectural Implications:** -1. **Quick win discovered:** App.tsx overrides ThinkingIndicator's native rotation with static hints (~5 line fix) -2. **Debt acknowledged:** 3 separate separator implementations need consolidation (P2 work) -3. **Layout strategy:** Ink's layout model fights bottom-anchored input. Alt screen buffer is the real solution (P3 deferred). -4. **Issue granularity:** 20 discrete issues vs. 1 monolithic "fix UI" epic — enables parallel work by Cheritto (11 issues), Kovash (4), Redfoot (2), Fenster (1), Marquez (1 review) - -**Success Gate:** "Brady says it doesn't embarrass us" — qualitative gate appropriate for alpha software. Quantitative gates: zero blank screens >500ms, contrast ≥4.5:1, spinner rotates every 3s. - -**Impact:** -- **Team routing:** Clear ownership — Cheritto (TUI), Kovash (shell), Redfoot (design), Marquez (UX review) -- **Timeline transparency:** P0 (1-2 days) → P1 (2-3 days) → P2 (1 week) — alpha ship when P0+P1 done -- **Expectation management:** Out of Scope section explicitly lists grand redesign, advanced features, WCAG audit — prevents scope creep - -### 2026-03-01: Cast confirmation required for freeform REPL casts -**By:** Fenster (Core Dev) -**Date:** 2026-03-01 -**Context:** P2 from Keaton's reliable-init-flow proposal - -**What:** When a user types a freeform message in the REPL and the roster is empty, the cast proposal is shown and the user must confirm (y/yes) before team files are created. Auto-cast from .init-prompt and /init "prompt" skip confirmation since the user explicitly provided the prompt. - -**Why:** Prevents garbage casts from vague or accidental first messages (e.g., "hello", "what can you do?"). Matches the squad.agent.md Init Mode pattern where confirmation is required before creating team files. - -**Pattern:** pendingCastConfirmation state in shell/index.ts. handleDispatch intercepts y/n at the top before normal routing. inalizeCast() is the shared helper for both auto-confirmed and user-confirmed paths. - -### 2026-03-01: Expose setProcessing on ShellApi -**By:** Kovash (REPL Expert) -**Date:** 2026-03-01 -**Context:** Init auto-cast path bypassed App.tsx handleSubmit, so processing state was never set — spinner invisible during team casting. - -**What:** ShellApi now exposes setProcessing(processing: boolean) so that any code path in index.ts that triggers async work outside of handleSubmit can properly bracket it with processing state. This enables ThinkingIndicator and InputPrompt spinner without duplicating React state management. - -**Rule:** Any new async dispatch path in index.ts that bypasses handleSubmit **must** call shellApi.setProcessing(true) before the async work and shellApi.setProcessing(false) in a inally block covering all exit paths. - -**Files Changed:** -- packages/squad-cli/src/cli/shell/components/App.tsx — added setProcessing to ShellApi interface + wired in onReady -- packages/squad-cli/src/cli/shell/index.ts — added setProcessing calls in handleInitCast (entry, pendingCastConfirmation return, finally block) - -### 2026-03-01T20:13:16Z: User directives — UI polish and shipping priorities -**By:** Brady (via Copilot) -**Date:** 2026-03-01 -Ampersands (&) are prohibited in user-facing documentation headings and body text, per Microsoft Style Guide. - -**Rule:** Use "and" instead. - -**Why:** Microsoft Style Guide prioritizes clarity and professionalism. Ampersands feel informal and reduce accessibility. - -**Exceptions:** -- Brand names (AT&T, Barnes & Noble) -- UI element names matching exact product text -- Code samples and technical syntax -- Established product naming conventions - -**Scope:** Applies to docs pages, README files, blog posts, community-facing content. Internal files (.squad/** memory files, decision docs, agent history) have flexibility. - -**Reference:** https://learn.microsoft.com/en-us/style-guide/punctuation/ampersands - - ---- - -## Adoption & Community - -### `.squad/` Directory Scope — Owner Directive -**By:** Brady (project owner, PR #326 review) -**Date:** 2026-03-10 - -**Directive:** The `.squad/` directory is **reserved for team state only** — roster, routing, decisions, agent histories, casting, and orchestration logs. Non-team data (adoption tracking, community metrics, reports) must NOT live in `.squad/`. Use `.github/` for GitHub platform integration or `docs/` for documentation artifacts. - -**Source:** [PR #326 comment](https://github.com/bradygaster/squad/pull/326#issuecomment-4029193833) - ---- - -### No Individual Repo Listing Without Consent — Owner Directive -**By:** Brady (project owner, PR #326 review) -**Date:** 2026-03-10 - -**Directive:** Growth metrics must report **aggregate numbers only** (e.g., "78+ repositories found via GitHub code search") — never name or link to individual community repos without explicit opt-in consent. The monitoring script and GitHub Action concepts are approved, but any public showcase or tracking list that identifies specific repos is blocked until a community consent plan exists. - -**Source:** [PR #326 comment](https://github.com/bradygaster/squad/pull/326#issuecomment-4029222967) - ---- - -### Adoption Tracking — Opt-In Architecture -**By:** Flight (implementing Brady's directives above) -**Date:** 2026-03-09 - -Privacy-first adoption monitoring using a three-tier system: - -**Tier 1: Aggregate monitoring (SHIPPED)** -- GitHub Action + monitoring script collect metrics -- Reports moved to `.github/adoption/reports/{YYYY-MM-DD}.md` -- Reports show ONLY aggregate numbers (no individual repo names): - - "78+ repositories found via code search" - - Total stars/forks across all discovered repos - - npm weekly downloads - -**Tier 2: Opt-in registry (DESIGN NEXT)** -- Create `SHOWCASE.md` in repo root with submission instructions -- Opted-in projects listed in `.github/adoption/registry.json` -- Monitoring script reads registry, reports only on opted-in repos - -**Tier 3: Public showcase (LAUNCH LATER)** -- `docs/community/built-with-squad.md` shows opted-in projects only -- README link added when ≥5 opted-in projects exist - -**Rationale:** -- Aggregate metrics safe (public code search results) -- Individual projects only listed with explicit owner consent -- Prevents surprise listings, respects privacy -- Incremental rollout maintains team capacity - -**Implementation (PR #326):** -- ✅ Moved `.squad/adoption/` → `.github/adoption/` -- ✅ Stripped tracking.md to aggregate-only metrics -- ✅ Removed individual repo names, URLs, metadata -- ✅ Updated adoption-report.yml and scripts/adoption-monitor.mjs -- ✅ Removed "Built with Squad" showcase link from README (Tier 2 feature) - ---- - -### Adoption Tracking Location & Privacy -**By:** EECOM -**Date:** 2026-03-10 - -Implementation decision confirming Tier 1 adoption tracking changes. - -**What:** Move adoption tracking from `.squad/adoption/` to `.github/adoption/` - -**Why:** -1. **GitHub integration:** `.github/adoption/` aligns with GitHub convention (workflows, CODEOWNERS, issue templates) -2. **Privacy-first:** Aggregate metrics only; defer individual repo showcase to Tier 2 (opt-in) -3. **Clear separation:** `.squad/` = team internal; `.github/` = GitHub platform integration -4. **Future-proof:** When Tier 2 opt-in launches, `.github/adoption/` is the natural home - -**Impact:** -- GitHub Action reports write to `.github/adoption/reports/{YYYY-MM-DD}.md` -- No individual repo information published until Tier 2 -- Monitoring continues collecting aggregate metrics via public APIs -- Team sees trends without publishing sensitive adoption data - ---- - -### Append-Only File Governance -**By:** Flight -**Date:** 2026-03-09 - -Feature branches must never modify append-only team state files except to append new content. - -**What:** If a PR diff shows deletions in `.squad/agents/*/history.md` or `.squad/decisions.md`, the PR is blocked until deletions are reverted. - -**Why:** Session state drift causes agents to reset append-only files to stale branch state, destroying team knowledge. PR #326 deleted entire history files and trimmed ~75 lines of decisions, causing data loss. - -**Enforcement:** Code review + future CI check candidate. - ---- - -### Documentation Style: No Ampersands -**By:** PAO -**Date:** 2026-03-09 - -Ampersands (&) are prohibited in user-facing documentation headings and body text, per Microsoft Style Guide. - -**Rule:** Use "and" instead. - -**Why:** Microsoft Style Guide prioritizes clarity and professionalism. Ampersands feel informal and reduce accessibility. - -**Exceptions:** -- Brand names (AT&T, Barnes & Noble) -- UI element names matching exact product text -- Code samples and technical syntax -- Established product naming conventions - -**Scope:** Applies to docs pages, README files, blog posts, community-facing content. Internal files (.squad/** memory files, decision docs, agent history) have flexibility. - -**Reference:** https://learn.microsoft.com/en-us/style-guide/punctuation/ampersands - ---- - -## Sprint Directives - -### Secret handling — agents must never persist secrets -**By:** RETRO (formerly Baer), v0.8.24 -**What:** Agents must NEVER write secrets, API keys, tokens, or credentials into conversational history, commit messages, logs, or any persisted file. Acknowledge receipt without echoing values. -**Why:** Secrets in logs or history are a security incident waiting to happen. - - ---- - -## Squad Ecosystem Boundaries & Content Governance - -### Squad Docs vs Squad IRL Boundary (consolidated) -**By:** PAO (via Copilot), Flight -**Date:** 2026-03-10 -**Status:** Active pattern for all documentation PRs - -**Litmus test:** If Squad doesn't ship the code or configuration, the documentation belongs in Squad IRL, not the Squad framework docs. - -**Categories:** - -1. **Squad docs** — Features Squad ships (routing, charters, reviewer protocol, config, behavior) -2. **Squad IRL** — Infrastructure around Squad (webhooks, deployment patterns, logging, external tools, operational patterns) -3. **Gray area:** Platform features (GitHub Issue Templates) → Squad docs if framed as "how to configure X for Squad" - -**Examples applied (PR #331):** - -| Document | Decision | Reason | -|----------|----------|--------| -| ralph-operations.md | DELETE → IRL | Infrastructure (deployment, logging) around Squad, not Squad itself | -| proactive-communication.md | DELETE → IRL | External tools (Teams, WorkIQ) configured by community, not built into Squad | -| issue-templates.md | KEEP, reframe | GitHub platform feature; clarify scope: "a GitHub feature configured for Squad" | -| reviewer-protocol.md (Trust Levels) | KEEP | Documents user choice spectrum within Squad's existing review system | - -**Enforcement:** Code review + reframe pattern ("GitHub provides X. Here's how to configure it for Squad's needs."). Mark suspicious deletions for restore (append-only governance). - -**Future use:** Apply this pattern to all documentation PRs to maintain clean boundaries. - - ---- - -### Content Triage Skill — External Content Integration -**By:** Flight -**Date:** 2026-03-10 -**Status:** Skill created at `.squad/skills/content-triage/SKILL.md` - -**Pattern:** External content (blog posts, sample repos, videos, conference talks) that helps Squad adoption must be triaged using the "Squad Ships It" boundary heuristic before incorporation. - -**Workflow:** -1. Triggered by `content-triage` label or external content reference in issue -2. Flight performs boundary analysis -3. Sub-issues generated for Squad-ownable content extraction (PAO responsibility) -4. FIDO verifies docs-test sync on extracted content -5. Scribe manages IRL references in `.github/irl/references.yml` (YAML schema) - -**Label convention:** `content:blog`, `content:sample`, `content:video`, `content:talk` - -**Why:** Pattern from PR #331 (Tamir Dresher blog) shows parallel extraction of Squad-ownable patterns (scenario guides, reviewer protocol) and infrastructure patterns (Ralph ops, proactive comms). Without clear boundary, teams pollute Squad docs with operational content or miss valuable patterns that should be generalized. - -**Impact:** Enables community content to accelerate Squad adoption without polluting core docs. Flight's boundary analysis becomes reusable decision framework. Prevents scope creep as adoption grows. - - ---- - -### PR #331 Quality Gate — Test Assertion Sync -**By:** FIDO (Quality Owner) -**Date:** 2026-03-10 -**Status:** 🟢 CLEARED (test fix applied, commit 6599db6) - -**What was blocked:** Merge blocked on stale test assertions in `test/docs-build.test.ts`. - -**Critical violations resolved:** -1. `EXPECTED_SCENARIOS` array stale (7 vs 25 disk files) — ✅ Updated to 25 entries -2. `EXPECTED_FEATURES` constant undefined (32 feature files) — ✅ Created array with 32 entries -3. Test assertion incomplete — ✅ Updated to validate features section - -**Why this matters:** Stale assertions that don't reflect filesystem state cause silent test skips. Regression: If someone deletes a scenario file, the test won't catch it. CI passing doesn't guarantee test coverage — only that the test didn't crash. - -**Lessons:** -- Test arrays must be refreshed when filesystem content changes -- Incomplete commits break the test-reality sync contract -- FIDO's charter: When adding test count assertions, must keep in sync with disk state - -**Outcome:** Test suite: 6/6 passing. Assertions synced to filesystem. No regression risk from stale assertions. - - ---- - -### Communication Patterns and PR Trust Models -**By:** PAO -**Date:** 2026-03-10 -**Status:** Documented in features/reviewer-protocol.md (trust levels section) and scenarios/proactive-communication.md (infrastructure pattern) - -**Decision:** Document emerging patterns in real Squad usage: proactive communication loops and PR review trust spectrum. - -**Components:** - -1. **Proactive communication patterns** — Outbound notifications (Teams webhooks), inbound scanning (Teams/email for work items), two-way feedback loop connecting external sources to Squad workflow - -2. **PR trust levels spectrum:** - - **Full review** (default for team repos) — All PRs require human review - - **Selective review** (personal projects with patterns) — Domain-expert or routine PRs can auto-merge - - **Self-managing** (solo personal repos only) — PRs auto-merge; Ralph's work monitoring provides retroactive visibility - -**Why:** Ralph 24/7 autonomous deployment creates an awareness gap — how does the human stay informed? Outbound notifications solve visibility. Inbound scanning solves "work lives in multiple places." Trust levels let users tune oversight to their context (full review for team repos, selective for personal projects, self-managing for solo work only). - -**Important caveat:** Self-managing ≠ unmonitored; Ralph's work monitoring and notifications provide retroactive visibility. - -**Anti-spam expectations:** Don't spam yourself outbound (notification fatigue), don't spam GitHub inbound (volume controls). - - ---- - -### Remote Squad Access — Phased Rollout (Proposed) -**By:** Flight -**Date:** 2026-03-10 -**Status:** Proposed — awaits proposal document in `docs/proposals/remote-squad-access.md` - -**Context:** Squad currently requires a local clone to answer questions. Users want remote access from mobile, browser, or different machine without checking out repo. - -**Phases:** - -**Phase 1: GitHub Discussions Bot (Ship First)** -- Surface: GitHub Discussions -- Trigger: `/squad` command or `@squad` mention -- Context: GitHub Actions workflow checks out repo → full `.squad/` state -- Response: Bot replies to thread -- Feasibility: 1 day -- Why first: Easy to build, zero hosting, respects repo privacy, async Q&A, immediately useful - -**Phase 2: GitHub Copilot Extension (High Value)** -- Surface: GitHub Copilot chat (VS Code, CLI, web, mobile) -- Trigger: `/squad ask {question}` in any Copilot client -- Context: Extension fetches `.squad/` files via GitHub API (no clone) -- Response: Answer inline in Copilot -- Feasibility: 1 week -- Why second: Works everywhere Copilot exists, instant response, natural UX - -**Phase 3: Slack/Teams Bot (Enterprise Value)** -- Surface: Slack or Teams channel -- Trigger: `@squad` mention in channel -- Context: Webhook fetches `.squad/` via GitHub API -- Response: Bot replies in thread -- Feasibility: 2 weeks -- Why third: Enterprise teams live in chat; high value for companies using Squad - -**Constraint:** Squad's intelligence lives in `.squad/` (roster, routing, decisions, histories). Any remote solution must solve context access. GitHub Actions workflows provide checkout for free. Copilot Extension and chat bots use GitHub API to fetch files. - -**Implementation:** Before Phase 1 execution, write proposal document. New CLI command: `squad answer --context discussions --question "..."`. New workflow: `.github/workflows/squad-answer.yml`. - -**Privacy:** All approaches respect repo visibility or require authentication. Most teams want private by default. - -### Test assertion discipline — mandatory -**By:** FIDO (formerly Hockney), v0.8.24 -**What:** All code agents must update tests when changing APIs. FIDO has PR blocking authority on quality grounds. -**Why:** APIs changed without test updates caused CI failures and blocked external contributors. - -### Docs-test sync — mandatory -**By:** PAO (formerly McManus), v0.8.24 -**What:** New docs pages require corresponding test assertion updates in the same commit. -**Why:** Stale test assertions block CI and frustrate contributors. - -### Contributor recognition — every release -**By:** PAO, v0.8.24 -**What:** Each release includes an update to the Contributors Guide page. -**Why:** No contribution goes unappreciated. - -### API-test sync cross-check -**By:** FIDO + Booster, v0.8.24 -**What:** Booster adds CI check for stale test assertions. FIDO enforces via PR review. -**Why:** Prevents the pattern of APIs changing without test updates. - -### Doc-impact review — every PR -**By:** PAO, v0.8.25 -**What:** Every PR must be evaluated for documentation impact. PAO reviews PRs for missing or outdated docs. -**Why:** Code changes without doc updates lead to stale guides and confused users. - - ---- - -## Release v0.8.24 - -### CLI Packaging Smoke Test: Release Gate Decision -**By:** FIDO, v0.8.24 -**Date:** 2026-03-08 - -The CLI packaging smoke test is APPROVED as the quality gate for npm releases. - -**What:** -1. Text box preference: bottom-aligned, squared off (like Copilot CLI / Claude CLI) — future work, not today -2. Alpha-level shipment acceptable for now — no grand UI redesign today -3. CLI must show "experimental, please file issues" banner -4. Spinner/wait messages should rotate every ~3 seconds — use codebase facts, project trivia, vulnerability info, or creative "-ing" words. Never just spin silently. -5. Use wait time to inform or entertain users - -**Why:** User request — captured for team memory and crash recovery - -### 2026-03-01T20:16:00Z: User directive — CLI timeout too low -**By:** Brady (via Copilot) -**Date:** 2026-03-01 - -**What:** The CLI timeout is set too low — Brady tried using Squad CLI in this repo and it didn't work well. Timeout needs to be increased. Not urgent but should be captured as a CLI improvement opportunity. - -**Why:** User request — captured for team memory and PRD inclusion - -### 2026-03-01: Multi-Squad Storage & Resolution Design -**By:** Keaton (Lead) -**What:** -- New directory structure: ~/.config/squad/squads/{name}/.squad/ with ~/.config/squad/config.json for registry -- Keep -esolveGlobalSquadPath() unchanged; add -esolveNamedSquadPath(name?: string) and listPersonalSquads() on top -- Auto-migration: existing single personal squad moves to squads/default/ on first run -- Resolution priority: explicit (CLI flag) > project config > env var > git remote mapping > path mapping > default -- Global config.json schema: { version, defaultSquad, squads, mappings } - -**Why:** -- squads/ container avoids collisions with existing files at global root -- Backward-compatible: legacy layout detected and auto-migrated; existing code continues to work -- Clean separation: global config lives alongside squads, not inside any one squad -- Resolution chain enables flexible mapping without breaking existing workflows - -### 2026-03-01: Multi-Squad SDK Functions -**By:** Kujan (SDK Expert) -**What:** -- New SDK exports: -esolveNamedSquadPath(), listSquads(), createSquad(), deleteSquad(), switchSquad(), -esolveSquadForProject() -- New type: SquadEntry { name, path, isDefault, createdAt } -- squads.json registry (separate file, not config.json) with squad metadata and mappings -- SquadDirConfig v2 addition: optional personalSquad?: string field (v1 configs unaffected) -- Consult mode updated: setupConsultMode(options?: { squad?: string }) with explicit selection or auto-resolution - -**Why:** -- Lazy migration with fallback chain ensures zero breaking changes to existing users -- Separate squads.json is single source of truth for routing; keeps project config focused -- Version handling allows incremental adoption; v1 configs work unchanged -- SDK resolution functions can be called from CLI and library code without duplication - -### 2026-03-01: Multi-Squad CLI Commands & REPL -**By:** Kovash (REPL) -**What:** -- New commands: squad list, squad create , squad switch , squad delete -- Modified commands: squad consult --squad=, squad extract --squad=, squad init --global --name= -- Interactive picker for squad selection: arrow keys (↑/↓), Enter to confirm, Ctrl+C to cancel -- REPL integration: /squad and /squads slash commands with riggerSquadReload signal -- .active file stores current active squad name (plain text) -- Status command enhanced to show active squad and squad list - -**Why:** -- Picker only shows when needed (multiple squads) and TTY available; non-TTY gracefully uses active squad -- Slash commands follow existing pattern (/init, /agents, etc.); seamless REPL integration -- .active file is simple and atomic; suitable for concurrent CLI access -- Squad deletion safety: cannot delete active squad; requires confirmation - -### 2026-03-01: Multi-Squad UX & Interaction Design -**By:** Marquez (UX Designer) -**What:** -- Visual indicator: current squad marked with ●, others with ○; non-default squads tagged [switched] -- Squad name always visible in REPL header and prompt: ◆ Squad (client-acme) -- Picker interactions: ↑/↓ navigate, Enter select, Esc/Ctrl+C cancel; 5-7 squads displayed, wrap around -- Error states: clear copy with next actions (e.g., "Squad not found. Try @squad:personal." or "Run /squads to list.") -- Copy style: active verbs (Create, Switch, List), human-readable nouns (no jargon), 3-5 words per line -- Onboarding: fresh install defaults to "personal"; existing single-squad users see migration notice - -**Why:** -- Persistent context (squad name in header/prompt) prevents "Which squad am I in?" confusion -- Interactive picker is discoverable and non-blocking; minimal cognitive load -- Error messages with next actions reduce support friction -- Onboarding defaults and migration notices ensure smooth upgrade path for existing users - -# Decision: Separator component is canonical for horizontal rules - -**By:** Cheritto (TUI Engineer) -**Date:** 2026-03-02 -**Issues:** #655, #670, #671, #677 - -## What - -- All horizontal separator lines in shell components must use the shared `Separator` component (`components/Separator.tsx`), not inline `box.h.repeat()` calls. -- The `Separator` component handles terminal capability detection, box-drawing character degradation, and width computation internally. -- Information hierarchy convention: **bold** for primary CTAs (commands, actions) > normal for content > **dim** for metadata (timestamps, status, hints). -- `flexGrow` should not be used on containers that may be empty — it creates dead space in Ink layouts. - -## Why - -Duplicated separator logic was found in 3 files (App.tsx, AgentPanel.tsx, MessageStream.tsx). Consolidation to a single component prevents drift and makes it trivial to change separator style globally. The info hierarchy and whitespace conventions ensure visual consistency as new components are added. -### 2026-03-01: PR #547 Remote Control Feature — Architectural Review -**By:** Fenster -**Date:** 2026-03-01 -**PR:** #547 "Squad Remote Control - PTY mirror + devtunnel for phone access" by tamirdresher (external) - -## Context - -External contributor Tamir Dresher submitted a PR adding `squad start --tunnel` command to run Copilot in a PTY and mirror terminal output to phone/browser via WebSocket + Microsoft Dev Tunnels. - -## Architectural Question - -Is remote terminal access via devtunnel + PTY mirroring in scope for Squad v1 core? - -## Technical Assessment - -**What works:** -- RemoteBridge WebSocket server architecture is sound -- PTY mirroring approach is technically correct -- Session management dashboard is useful -- Security headers and CSP are present -- Test coverage exists (18 tests, though failing due to build issues) - -**Critical blockers:** -1. **Build broken** — TypeScript errors in `start.ts`, all tests failing -2. **Command injection vulnerability** — `execFileSync` with string interpolation in `rc-tunnel.ts` -3. **Native dependency** — `node-pty` requires C++ compiler (install friction) -4. **Windows-only effectively** — hardcoded paths, devtunnel CLI Windows-centric -5. **No cross-platform strategy** — macOS/Linux support unclear - -**Architectural concerns:** - -### 2026-03-02T23:36:00Z: Version target — v0.6.0 for public migration **[SUPERSEDED — see line 1046]** -**By:** Brady (via Copilot) -**What:** The public migration from squad-pr to squad should target v0.6.0, not v0.8.17. This overrides Kobayashi's Phase 5 Option A recommendation. The public repo (bradygaster/squad) goes from v0.5.4 → v0.6.0 — a clean minor bump. -**Why:** User directive. v0.6.0 is the logical next public version from v0.5.4. Internal version numbers (0.6.x–0.8.x) were private development milestones. -**[CORRECTION — 2026-03-03]:** This decision was REVERSED by Brady. Brady explicitly stated: "0.6.0 should NOT appear as the goal for ANY destination. I want the beta to become 0.8.17." The actual migration target is v0.8.17. See the superseding "Versioning Model: npm packages vs Public Repo Tags" decision at line 1046 which clarifies that v0.6.0 is a public repo tag only, while npm packages remain at 0.8.17. Current migration documentation correctly references v0.8.17 throughout. -1. **Not integrated with Squad runtime** — doesn't use EventBus, Coordinator, or agent orchestration. Isolated feature. -2. **Two separate modes** — PTY mode (`start.ts`) vs. ACP passthrough mode (`rc.ts`). Why both? -3. **New CLI paradigm** — "start" implies daemon/server, not interactive mirroring. Command naming collision risk. -4. **External dependency** — requires `devtunnel` CLI installed + authenticated. Not bundled, not auto-installed. -5. **Audit logs** — go to `~/.cli-tunnel/audit/` instead of `.squad/log/` (inconsistent with Squad state location). - -## Recommendation - -**Request Changes** — Do not merge until: -1. TypeScript build errors fixed -2. Command injection vulnerability patched (use array args, no interpolation) -3. Tests passing (currently 18/18 failing) -4. Cross-platform support documented or Windows-only label added -5. Architectural decision on scope: Is this core or plugin? - -**If approved as core feature:** -- Extract to plugin first, prove value, then consider core integration -- Unify PTY vs. ACP modes (pick one) -- Integrate with EventBus/Coordinator (or explain why isolated is correct) -- Rename command to `squad remote` or `squad tunnel` (avoid `start` collision) -- Move audit logs to `.squad/log/` - -**If approved as plugin:** -- This is the right path — keeps core small, proves value independently -- Still fix security issues before merge to plugin repo - -## For Brady - -You requested a runtime review. Here's the verdict: - -- **Concept is cool** — phone access to Copilot is a real use case. -- **Implementation needs work** — build broken, security issues, Windows-only. -- **Architectural fit unclear** — not in any Squad v1 PRD. No integration with agent orchestration. -- **Native dependency risk** — `node-pty` adds install friction (C++ compiler required). - -**My take:** This belongs in a plugin, not core. External contributor did solid work on the WebSocket bridge, but Squad v1 needs to ship agent orchestration first. Remote access is a nice-to-have, not a v1 must-have. - -If you want this in v1, we need a proposal (docs/proposals/) first. - -### 2026-03-02: Multi-squad test contract — squads.json schema -**By:** Hockney (Tester) -**Date:** 2026-03-02 -**Issue:** #652 - -## What - -Tests for multi-squad (PR #690) encode a specific squads.json contract: - -```typescript -interface SquadsJson { - version: 1; - defaultSquad: string; - squads: Record; -} -``` - -Squad name validation regex: `^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$` (kebab-case, 1-40 chars). - -## Why - -Fenster's implementation should match this schema. If the schema changes, tests need updating. Recording so the team knows the contract is encoded in tests. - -## Impact - -Fenster: Align `multi-squad.ts` types with this schema, or flag if different — Hockney will adjust tests. - -### 2026-03-02: PR #582 Review — Consult Mode Implementation -**By:** Keaton (Lead) -**Date:** 2026-03-01 -**Context:** External contributor PR from James Sturtevant (jsturtevant) - -## Decision - -**Do not merge PR #582 in its current form.** - -This is a planning document (PRD) masquerading as implementation. The PR contains: -- An excellent 854-line PRD for consult mode -- Test stubs for non-existent functions -- Zero actual implementation code -- A history entry claiming work is done (aspirational, not factual) - -## Required Actions - -1. **Extract PRD to proper location:** - - Move `.squad/identity/prd-consult-mode.md` → `docs/proposals/consult-mode.md` - - PRDs belong in proposals/, not identity/ - -2. **Close this PR with conversion label:** - - Label: "converted-to-proposal" - - Comment: Acknowledge excellent design work, explain missing implementation - -3. **Create implementation issues from PRD phases:** - - Phase 1: SDK changes (SquadDirConfig, resolution helpers) - - Phase 2: CLI command implementation - - Phase 3: Extraction workflow - - Each phase: discrete PR with actual code + tests - -4. **Architecture discussion needed before implementation:** - - How does consult mode integrate with existing sharing/ module? - - Session learnings vs agent history — conceptual model mismatch - - Remote mode (teamRoot pointer) vs copy approach — PRD contradicts itself - -## Architectural Guidance - -**What's right:** -- `consult: true` flag in config.json ✅ -- `.git/info/exclude` for git invisibility ✅ -- `git rev-parse --git-path info/exclude` for worktree compatibility ✅ -- Separate extraction command (`squad extract`) ✅ -- License risk detection (copyleft) ✅ - -**What needs rethinking:** -- Reusing `sharing/` module (history split vs learnings extraction — different domains) -- PRD flip-flops between "copy squad" and "remote mode teamRoot pointer" -- No design for how learnings are structured or extracted -- Tests before code (cart before horse) - -## Pattern Observed - -James Sturtevant is a thoughtful contributor who understands the product vision. The PRD is coherent and well-structured. This connects to his #652 issue (Multiple Personal Squads) — consult mode is a stepping stone to multi-squad workflows. - -**Recommendation:** Engage James in architecture discussion before he writes code. This feature has implications for the broader personal squad vision. Get alignment on: -1. Sharing module fit (or new consult module?) -2. Learnings structure and extraction strategy -3. Phase boundaries and deliverables - -## Why This Matters - -External contributors are engaging with Squad's architecture. We need to guide them toward shippable PRs, not just accept aspirational work. Setting clear expectations now builds trust and avoids wasted effort. - -## Files Referenced - -- `.squad/identity/prd-consult-mode.md` (PRD, should move) -- `test/consult.test.ts` (tests for non-existent code) -- `.squad/agents/fenster/history.md` (claims work done) -- `packages/squad-sdk/src/resolution.ts` (needs `consult` field, unchanged in PR) - - -### cli.js is now a thin ESM shim - -**By:** Fenster -**Date:** 2025-07 -**What:** `cli.js` at repo root is a 14-line shim that imports `./packages/squad-cli/dist/cli-entry.js`. It no longer contains bundled CLI code. The deprecation notice only displays when invoked via npm/npx. -**Why:** The old bundled cli.js was stale and missing commands added after the monorepo migration (e.g., `aspire`). A shim ensures `node cli.js` always runs the latest built CLI. -**Impact:** `node cli.js` now requires `npm run build` to have been run first (so `packages/squad-cli/dist/cli-entry.js` exists). This was already the case for any development workflow. - - -### 2026-03-02T01-09-49Z: User directive -**By:** Brady (via Copilot) -**What:** Stop distributing the package via NPX and GitHub. Only distribute via NPM from now on. Go from the public version to whatever version we're in now in the private repo. Adopt the versioning scheme from issue #692. -**Why:** User request — captured for team memory - -# Release Plan Update — npm-only Distribution & Semver Fix (#692) - -**Status:** DECIDED -**Decided by:** Kobayashi (Git & Release) -**Date:** 2026-03-01T14:22Z -**Context:** Brady's two strategic decisions on distribution and versioning - -## Decisions - -### 1. NPM-Only Distribution -- **What:** End GitHub-native distribution (`npx github:bradygaster/squad`). Install exclusively via npm registry. -- **How:** Users install via `npm install -g @bradygaster/squad-cli` (global) or `npx @bradygaster/squad-cli` (per-project). -- **Why:** Simplified distribution, centralized source of truth, standard npm tooling conventions. -- **Scope:** Affects all future releases, all external documentation, and CI/CD publish workflows. -- **Owners:** Rabin (docs), Fenster (scripts), all team members (update docs/sample references). - -### 2. Semantic Versioning Fix (#692) -- **Problem:** Versions were `X.Y.Z.N-preview` (four-part with prerelease after), which violates semver spec. -- **Solution:** Correct format is `X.Y.Z-preview.N` (prerelease identifier comes after patch, before any build metadata). -- **Examples:** - - ❌ Invalid: `0.8.6.1-preview`, `0.8.6.16-preview` - - ✅ Valid: `0.8.6-preview.1`, `0.8.6-preview.16` -- **Impact:** Affects all version strings going forward (package.json, CLI version constant, release tags). -- **Release sequence:** - 1. Pre-release: `X.Y.Z-preview.1`, `X.Y.Z-preview.2`, ... - 2. At publish: Bump to `X.Y.Z` - 3. Post-publish: Bump to `{next}-preview.1` (reset counter) - -### 3. Version Continuity -- **Transition:** Public repo ended at `0.8.5.1`. Private repo continues at `0.8.6-preview` (following semver format). -- **Rationale:** Clear break between public (stable) and private (dev) codebases while maintaining version history continuity. - -## Implementation - -- ✅ **CHANGELOG.md:** Added "Changed" section documenting distribution channel and semver fix. -- ✅ **Charter (Kobayashi):** Updated Release Versioning Sequence with corrected pattern and phase description. -- ✅ **History (Kobayashi):** Logged decision with rationale and scope. - -## Dependent Work - -- **Fenster:** Ensure `bump-build.mjs` implements X.Y.Z-preview.N pattern (not X.Y.Z.N-preview). -- **Rabin:** Update README, docs, and all install instructions to reflect npm-only distribution. -- **All:** Use corrected version format in release commits, tags, and announcements. - -## Notes - -- Zero impact on functionality — this is purely distribution and versioning cleanup. -- Merge drivers on `.squad/agents/kobayashi/history.md` ensure this decision appends safely across parallel branches. -- If questions arise about versioning during releases, refer back to Charter § Release Versioning Sequence. - -# Decision: npm-only distribution (GitHub-native removed) - -**By:** Rabin (Distribution) -**Date:** 2026-03-01 -**Requested by:** Brady - -## What Changed - -All distribution now goes through npm. The `npx github:bradygaster/squad` path has been fully removed from: -- Source code (github-dist.ts default template, install-migration.ts, init.ts) -- All 4 copies of squad.agent.md (Ralph Watch Mode commands) -- All 4 copies of squad-insider-release.yml (release notes) -- README.md, migration guides, blog posts, cookbook, installation docs -- Test assertions (bundle.test.ts) -- Rabin's own charter (flipped from "never npmjs.com" to "always npmjs.com") - -## Install Paths (the only paths) - -```bash -# Global install -npm install -g @bradygaster/squad-cli - -# Per-use (no install) -npx @bradygaster/squad-cli - -# SDK for programmatic use -npm install @bradygaster/squad-sdk -``` - -## Why - -One distribution channel means less confusion, fewer edge cases, and zero SSH-agent hang bugs. npm caching makes installs faster. Semantic versioning works properly. The root `cli.js` still exists with a deprecation notice for anyone who somehow hits the old path. - -## Impact - -- **All team members:** When writing docs or examples, use `npm install -g @bradygaster/squad-cli` or `npx @bradygaster/squad-cli`. Never reference `npx github:`. -- **CI/CD:** Insider release workflow now shows npm install commands in release notes. -- **Tests:** bundle.test.ts assertions updated to match new default template. - - -# Decision: Versioning Model — npm Packages vs Public Repo - -**Date:** 2026-03-03T02:45:00Z -**Decided by:** Kobayashi (Git & Release specialist) -**Related issues:** Migration prep, clarifying confusion between npm and public repo versions -**Status:** Active — team should reference this in all future releases - -## The Problem - -The migration process had introduced confusion about which version number applies where: -- Coordinator incorrectly bumped npm package versions to 0.6.0, creating version mismatch -- Migration checklist had npm packages publishing as 0.6.0 -- CHANGELOG treated 0.6.0 as an npm package version -- No clear distinction between "npm packages version" vs "public repo GitHub release tag" -- Risk of future mistakes during releases - -## The Model (CORRECT) - -Two distinct version numbers serve two distinct purposes: - -### 1. npm Packages: `@bradygaster/squad-cli` and `@bradygaster/squad-sdk` - -- **Follow semver cadence from current version:** Currently at 0.8.17 (published to npm) -- **Next publish after 0.8.17:** 0.8.18 (NOT 0.6.0) -- **Development versions:** Use `X.Y.Z-preview.N` format (e.g., 0.8.18-preview.1, 0.8.18-preview.2) -- **Release sequence per Kobayashi charter:** - 1. Pre-release: `X.Y.Z-preview.N` (development) - 2. At publish: Bump to `X.Y.Z` (e.g., 0.8.18), publish to npm, create GitHub release - 3. Post-publish: Immediately bump to next-preview (e.g., 0.8.19-preview.1) - -**MUST NEVER:** -- Bump npm packages down (e.g., 0.8.17 → 0.6.0) -- Confuse npm package version with public repo tag - -### 2. Public Repo (bradygaster/squad): GitHub Release Tag `v0.8.17` **[CORRECTED from v0.6.0]** - -- **Purpose:** Marks the migration release point for the public repository -- **Public repo version history:** v0.5.4 (final pre-migration) → v0.8.17 (migration release) **[CORRECTED: Originally written as v0.6.0, corrected to v0.8.17 per Brady's directive]** -- **Applied to:** The migration merge commit on beta/main -- **Same as npm versions:** v0.8.17 is BOTH the npm package version AND the public repo tag **[CORRECTED: Originally described as "separate from npm versions"]** -- **No package.json changes:** The tag is applied after the merge commit, but the version in package.json matches the tag - -## Why Two Version Numbers? **[CORRECTED: Actually ONE version number — v0.8.17 for both]** - -1. **npm packages evolve on their own cadence:** Independent development, independent release cycles (via @changesets/cli) -2. **Public repo is a release marker:** The v0.8.17 tag signals "here's the migration point" to users who clone the public repo **[CORRECTED: Same version as npm, not different]** -3. **They target different audiences:** - - npm: Users who install via `npm install -g @bradygaster/squad-cli` - - Public repo: Users who clone `bradygaster/squad` or interact with GitHub releases - **[CORRECTED: Both use v0.8.17 — the version numbers are aligned, not separate]** - -## Impact on Migration Checklist & CHANGELOG - -- **migration-checklist.md:** All references correctly use v0.8.17 for both npm packages AND public repo tag. **[CORRECTED: Line originally said "publish as 0.8.18, not 0.6.0" but actual target is 0.8.17]** -- **CHANGELOG.md:** Tracks npm package versions at 0.8.x cadence -- **Future releases:** npm packages and public repo tags use the SAME version number **[CORRECTED: Original text implied they were different]** - -## Known Issue: `scripts/bump-build.mjs` - -The auto-increment build number script (`npm run build`) can produce invalid semver for non-prerelease versions: -- `0.6.0` + auto-increment → `0.6.0.1` (invalid) -- `0.8.18-preview.1` + auto-increment → `0.8.18-preview.2` (valid) - -Since npm packages stay at 0.8.x cadence, this is not a blocker for migration. But worth noting for future patch releases. - -## Directive Merged - -Brady's directive (2026-03-03T02:16:00Z): "squad-cli and squad-sdk must NOT be bumped down to 0.6.0. They are already shipped to npm at 0.8.17." - -✅ **Incorporated:** All fixes ensure npm packages stay at 0.8.x. The v0.8.17 is used for BOTH npm packages AND public repo tag. **[CORRECTED: Original text said "v0.6.0 is public repo only" which was incorrect]** - -## Action Items for Team - -- Reference this decision when asked "what version should we release?" -- Use this model for all future releases (main project and public repo) -- Update team onboarding docs to include this versioning distinction -### No temp/memory files in repo root -**By:** Brady -**What:** No plan files, memory files, or tracking artifacts in the repository root. -**Why:** Keep the repo clean. - - ---- - -## Adoption & Community - -### `.squad/` Directory Scope — Owner Directive -**By:** Brady (project owner, PR #326 review) -**Date:** 2026-03-10 - -**Directive:** The `.squad/` directory is **reserved for team state only** — roster, routing, decisions, agent histories, casting, and orchestration logs. Non-team data (adoption tracking, community metrics, reports) must NOT live in `.squad/`. Use `.github/` for GitHub platform integration or `docs/` for documentation artifacts. - -**Source:** [PR #326 comment](https://github.com/bradygaster/squad/pull/326#issuecomment-4029193833) - ---- - -### No Individual Repo Listing Without Consent — Owner Directive -**By:** Brady (project owner, PR #326 review) -**Date:** 2026-03-10 - -**Directive:** Growth metrics must report **aggregate numbers only** (e.g., "78+ repositories found via GitHub code search") — never name or link to individual community repos without explicit opt-in consent. The monitoring script and GitHub Action concepts are approved, but any public showcase or tracking list that identifies specific repos is blocked until a community consent plan exists. - -**Source:** [PR #326 comment](https://github.com/bradygaster/squad/pull/326#issuecomment-4029222967) - ---- - -### Adoption Tracking — Opt-In Architecture -**By:** Flight (implementing Brady's directives above) -**Date:** 2026-03-09 - -Privacy-first adoption monitoring using a three-tier system: - -**Tier 1: Aggregate monitoring (SHIPPED)** -- GitHub Action + monitoring script collect metrics -- Reports moved to `.github/adoption/reports/{YYYY-MM-DD}.md` -- Reports show ONLY aggregate numbers (no individual repo names): - - "78+ repositories found via code search" - - Total stars/forks across all discovered repos - - npm weekly downloads - -**Tier 2: Opt-in registry (DESIGN NEXT)** -- Create `SHOWCASE.md` in repo root with submission instructions -- Opted-in projects listed in `.github/adoption/registry.json` -- Monitoring script reads registry, reports only on opted-in repos - -**Tier 3: Public showcase (LAUNCH LATER)** -- `docs/community/built-with-squad.md` shows opted-in projects only -- README link added when ≥5 opted-in projects exist - -**Rationale:** -- Aggregate metrics safe (public code search results) -- Individual projects only listed with explicit owner consent -- Prevents surprise listings, respects privacy -- Incremental rollout maintains team capacity - -**Implementation (PR #326):** -- ✅ Moved `.squad/adoption/` → `.github/adoption/` -- ✅ Stripped tracking.md to aggregate-only metrics -- ✅ Removed individual repo names, URLs, metadata -- ✅ Updated adoption-report.yml and scripts/adoption-monitor.mjs -- ✅ Removed "Built with Squad" showcase link from README (Tier 2 feature) - ---- - -### Adoption Tracking Location & Privacy -**By:** EECOM -**Date:** 2026-03-10 - -Implementation decision confirming Tier 1 adoption tracking changes. - -**What:** Move adoption tracking from `.squad/adoption/` to `.github/adoption/` - -**Why:** -1. **GitHub integration:** `.github/adoption/` aligns with GitHub convention (workflows, CODEOWNERS, issue templates) -2. **Privacy-first:** Aggregate metrics only; defer individual repo showcase to Tier 2 (opt-in) -3. **Clear separation:** `.squad/` = team internal; `.github/` = GitHub platform integration -4. **Future-proof:** When Tier 2 opt-in launches, `.github/adoption/` is the natural home - -**Impact:** -- GitHub Action reports write to `.github/adoption/reports/{YYYY-MM-DD}.md` -- No individual repo information published until Tier 2 -- Monitoring continues collecting aggregate metrics via public APIs -- Team sees trends without publishing sensitive adoption data - ---- - -### Append-Only File Governance -**By:** Flight -**Date:** 2026-03-09 - -Feature branches must never modify append-only team state files except to append new content. - -**What:** If a PR diff shows deletions in `.squad/agents/*/history.md` or `.squad/decisions.md`, the PR is blocked until deletions are reverted. - -**Why:** Session state drift causes agents to reset append-only files to stale branch state, destroying team knowledge. PR #326 deleted entire history files and trimmed ~75 lines of decisions, causing data loss. - -**Enforcement:** Code review + future CI check candidate. - ---- - -### Documentation Style: No Ampersands -**By:** PAO -**Date:** 2026-03-09 - -Ampersands (&) are prohibited in user-facing documentation headings and body text, per Microsoft Style Guide. - -**Rule:** Use "and" instead. - -**Why:** Microsoft Style Guide prioritizes clarity and professionalism. Ampersands feel informal and reduce accessibility. - -**Exceptions:** -- Brand names (AT&T, Barnes & Noble) -- UI element names matching exact product text -- Code samples and technical syntax -- Established product naming conventions - -**Scope:** Applies to docs pages, README files, blog posts, community-facing content. Internal files (.squad/** memory files, decision docs, agent history) have flexibility. - -**Reference:** https://learn.microsoft.com/en-us/style-guide/punctuation/ampersands - ---- - -## Sprint Directives - -### Secret handling — agents must never persist secrets -**By:** RETRO (formerly Baer), v0.8.24 -**What:** Agents must NEVER write secrets, API keys, tokens, or credentials into conversational history, commit messages, logs, or any persisted file. Acknowledge receipt without echoing values. -**Why:** Secrets in logs or history are a security incident waiting to happen. - ---- - -## Squad Ecosystem Boundaries & Content Governance - -### Squad Docs vs Squad IRL Boundary (consolidated) -**By:** PAO (via Copilot), Flight -**Date:** 2026-03-10 -**Status:** Active pattern for all documentation PRs - -**Litmus test:** If Squad doesn't ship the code or configuration, the documentation belongs in Squad IRL, not the Squad framework docs. - -**Categories:** - -1. **Squad docs** — Features Squad ships (routing, charters, reviewer protocol, config, behavior) -2. **Squad IRL** — Infrastructure around Squad (webhooks, deployment patterns, logging, external tools, operational patterns) -3. **Gray area:** Platform features (GitHub Issue Templates) → Squad docs if framed as "how to configure X for Squad" - -**Examples applied (PR #331):** - -| Document | Decision | Reason | -|----------|----------|--------| -| ralph-operations.md | DELETE → IRL | Infrastructure (deployment, logging) around Squad, not Squad itself | -| proactive-communication.md | DELETE → IRL | External tools (Teams, WorkIQ) configured by community, not built into Squad | -| issue-templates.md | KEEP, reframe | GitHub platform feature; clarify scope: "a GitHub feature configured for Squad" | -| reviewer-protocol.md (Trust Levels) | KEEP | Documents user choice spectrum within Squad's existing review system | - -**Enforcement:** Code review + reframe pattern ("GitHub provides X. Here's how to configure it for Squad's needs."). Mark suspicious deletions for restore (append-only governance). - -**Future use:** Apply this pattern to all documentation PRs to maintain clean boundaries. - ---- - -### Content Triage Skill — External Content Integration -**By:** Flight -**Date:** 2026-03-10 -**Status:** Skill created at `.squad/skills/content-triage/SKILL.md` - -**Pattern:** External content (blog posts, sample repos, videos, conference talks) that helps Squad adoption must be triaged using the "Squad Ships It" boundary heuristic before incorporation. - -**Workflow:** -1. Triggered by `content-triage` label or external content reference in issue -2. Flight performs boundary analysis -3. Sub-issues generated for Squad-ownable content extraction (PAO responsibility) -4. FIDO verifies docs-test sync on extracted content -5. Scribe manages IRL references in `.github/irl/references.yml` (YAML schema) - -**Label convention:** `content:blog`, `content:sample`, `content:video`, `content:talk` - -**Why:** Pattern from PR #331 (Tamir Dresher blog) shows parallel extraction of Squad-ownable patterns (scenario guides, reviewer protocol) and infrastructure patterns (Ralph ops, proactive comms). Without clear boundary, teams pollute Squad docs with operational content or miss valuable patterns that should be generalized. - -**Impact:** Enables community content to accelerate Squad adoption without polluting core docs. Flight's boundary analysis becomes reusable decision framework. Prevents scope creep as adoption grows. - ---- - -### PR #331 Quality Gate — Test Assertion Sync -**By:** FIDO (Quality Owner) -**Date:** 2026-03-10 -**Status:** 🟢 CLEARED (test fix applied, commit 6599db6) - -**What was blocked:** Merge blocked on stale test assertions in `test/docs-build.test.ts`. - -**Critical violations resolved:** -1. `EXPECTED_SCENARIOS` array stale (7 vs 25 disk files) — ✅ Updated to 25 entries -2. `EXPECTED_FEATURES` constant undefined (32 feature files) — ✅ Created array with 32 entries -3. Test assertion incomplete — ✅ Updated to validate features section - -**Why this matters:** Stale assertions that don't reflect filesystem state cause silent test skips. Regression: If someone deletes a scenario file, the test won't catch it. CI passing doesn't guarantee test coverage — only that the test didn't crash. - -**Lessons:** -- Test arrays must be refreshed when filesystem content changes -- Incomplete commits break the test-reality sync contract -- FIDO's charter: When adding test count assertions, must keep in sync with disk state - -**Outcome:** Test suite: 6/6 passing. Assertions synced to filesystem. No regression risk from stale assertions. - ---- - -### Communication Patterns and PR Trust Models -**By:** PAO -**Date:** 2026-03-10 -**Status:** Documented in features/reviewer-protocol.md (trust levels section) and scenarios/proactive-communication.md (infrastructure pattern) - -**Decision:** Document emerging patterns in real Squad usage: proactive communication loops and PR review trust spectrum. - -**Components:** - -1. **Proactive communication patterns** — Outbound notifications (Teams webhooks), inbound scanning (Teams/email for work items), two-way feedback loop connecting external sources to Squad workflow - -2. **PR trust levels spectrum:** - - **Full review** (default for team repos) — All PRs require human review - - **Selective review** (personal projects with patterns) — Domain-expert or routine PRs can auto-merge - - **Self-managing** (solo personal repos only) — PRs auto-merge; Ralph's work monitoring provides retroactive visibility - -**Why:** Ralph 24/7 autonomous deployment creates an awareness gap — how does the human stay informed? Outbound notifications solve visibility. Inbound scanning solves "work lives in multiple places." Trust levels let users tune oversight to their context (full review for team repos, selective for personal projects, self-managing for solo work only). - -**Important caveat:** Self-managing ≠ unmonitored; Ralph's work monitoring and notifications provide retroactive visibility. - -**Anti-spam expectations:** Don't spam yourself outbound (notification fatigue), don't spam GitHub inbound (volume controls). - ---- - -### Remote Squad Access — Phased Rollout (Proposed) -**By:** Flight -**Date:** 2026-03-10 -**Status:** Proposed — awaits proposal document in `docs/proposals/remote-squad-access.md` - -**Context:** Squad currently requires a local clone to answer questions. Users want remote access from mobile, browser, or different machine without checking out repo. - -**Phases:** - -**Phase 1: GitHub Discussions Bot (Ship First)** -- Surface: GitHub Discussions -- Trigger: `/squad` command or `@squad` mention -- Context: GitHub Actions workflow checks out repo → full `.squad/` state -- Response: Bot replies to thread -- Feasibility: 1 day -- Why first: Easy to build, zero hosting, respects repo privacy, async Q&A, immediately useful - -**Phase 2: GitHub Copilot Extension (High Value)** -- Surface: GitHub Copilot chat (VS Code, CLI, web, mobile) -- Trigger: `/squad ask {question}` in any Copilot client -- Context: Extension fetches `.squad/` files via GitHub API (no clone) -- Response: Answer inline in Copilot -- Feasibility: 1 week -- Why second: Works everywhere Copilot exists, instant response, natural UX - -**Phase 3: Slack/Teams Bot (Enterprise Value)** -- Surface: Slack or Teams channel -- Trigger: `@squad` mention in channel -- Context: Webhook fetches `.squad/` via GitHub API -- Response: Bot replies in thread -- Feasibility: 2 weeks -- Why third: Enterprise teams live in chat; high value for companies using Squad - -**Constraint:** Squad's intelligence lives in `.squad/` (roster, routing, decisions, histories). Any remote solution must solve context access. GitHub Actions workflows provide checkout for free. Copilot Extension and chat bots use GitHub API to fetch files. - -**Implementation:** Before Phase 1 execution, write proposal document. New CLI command: `squad answer --context discussions --question "..."`. New workflow: `.github/workflows/squad-answer.yml`. - -**Privacy:** All approaches respect repo visibility or require authentication. Most teams want private by default. - -### Test assertion discipline — mandatory -**By:** FIDO (formerly Hockney), v0.8.24 -**What:** All code agents must update tests when changing APIs. FIDO has PR blocking authority on quality grounds. -**Why:** APIs changed without test updates caused CI failures and blocked external contributors. - -### Docs-test sync — mandatory -**By:** PAO (formerly McManus), v0.8.24 -**What:** New docs pages require corresponding test assertion updates in the same commit. -**Why:** Stale test assertions block CI and frustrate contributors. - -### Contributor recognition — every release -**By:** PAO, v0.8.24 -**What:** Each release includes an update to the Contributors Guide page. -**Why:** No contribution goes unappreciated. - -### API-test sync cross-check -**By:** FIDO + Booster, v0.8.24 -**What:** Booster adds CI check for stale test assertions. FIDO enforces via PR review. -**Why:** Prevents the pattern of APIs changing without test updates. - -### Doc-impact review — every PR -**By:** PAO, v0.8.25 -**What:** Every PR must be evaluated for documentation impact. PAO reviews PRs for missing or outdated docs. -**Why:** Code changes without doc updates lead to stale guides and confused users. - - ---- - -## Release v0.8.24 - -### CLI Packaging Smoke Test: Release Gate Decision -**By:** FIDO, v0.8.24 -**Date:** 2026-03-08 - -The CLI packaging smoke test is APPROVED as the quality gate for npm releases. - -**What:** -- npm pack → creates tarball of both squad-sdk and squad-cli -- npm install → installs in clean temp directory (simulates user install) -- node {cli-entry.js} → invokes 27 commands + 3 aliases through installed package -- Coverage: All 26 primary commands + 3 of 4 aliases (watch, workstreams, remote-control) - -**Why:** Catches broken package.json exports, MODULE_NOT_FOUND errors, ESM resolution failures, command routing regressions — the exact failure modes we've shipped before. - -**Gaps (acceptable):** -- Semantic validation not covered (only routing tested) -- Cross-platform gaps (test runs on ubuntu-latest only) -- Optional dependencies allowed to fail (node-pty) - -## Impact - -- All agents: charter generation now reliably round-trips model preferences. -- Verbal/Keaton: the 4-layer model selection hierarchy documented in squad.agent.md is now supported at the SDK config level. -- Anyone adding new config fields: use the `assertModelPreference()` pattern (accept string-or-object, normalize internally) for fields that need simple and rich config shapes. - -# Decision: Runtime ExperimentalWarning suppression via process.emit hook - -**Date:** 2026-03-07 -**Author:** Fenster (Core Dev) -**Context:** PR #233 CI failure — 4 tests failed - -## Problem - -PR #233 (CLI wiring fixes for #226, #229, #201, #202) passed all 74 tests locally but failed 4 tests in CI: - -- `test/cli-p0-regressions.test.ts` — bare semver test (expected 1 line, got 3) -- `test/speed-gates.test.ts` — version outputs one line (expected 1, got 3) -- `test/ux-gates.test.ts` — no overflow beyond 80 chars (ExperimentalWarning line >80) -- `test/ux-gates.test.ts` — version bare semver (expected 1 line, got 3) - -Root cause: `node:sqlite` import triggers Node.js `ExperimentalWarning` that leaks to stderr. The existing `process.env.NODE_NO_WARNINGS = '1'` in cli-entry.ts was ineffective because Node only reads that env var at process startup, not when set at runtime. - -The warning likely didn't appear locally because the local Node.js version may have already suppressed it or the env var was set in the shell. - -## Decision - -Added a `process.emit` override in cli-entry.ts that intercepts `warning` events with `name === 'ExperimentalWarning'` and swallows them. This is placed: -- After `process.env.NODE_NO_WARNINGS = '1'` (which still helps child processes) -- Before the `await import('node:sqlite')` pre-flight check - -This is the standard Node.js pattern for runtime warning suppression when you can't control the process launch flags. - -## Impact - -- **cli-entry.ts**: 12 lines added (comment + override function) -- **Tests**: All 4 previously failing tests now pass; no regressions in structural tests (#624) -- **Behavior**: ExperimentalWarning messages no longer appear in CLI output; other warnings (DeprecationWarning, etc.) are unaffected - -### 2026-03-07T14:22:00Z: User directive - Quality cross-review -**By:** Brady (via Copilot) -**What:** All team members must double-and-triple check one another's work. Recent PRs have had weird test failures and inconsistencies. KEEN focus on quality - nothing can slip. -**Why:** User request - quality gate enforcement after speed gate, EBUSY, and cross-contamination issues across PRs #244, #245, #246. - - -# Decision: Optional dependencies must use lazy loading (#247) - -**Date:** 2026-03-09 -**Author:** Fenster -**Status:** Active - -## Context - -Issue #247 — two community reports of installation failure caused by top-level imports of `@opentelemetry/api` crashing when the package wasn't properly installed in `npx` temp environments. - -## Decision - -1. **All optional/telemetry dependencies must be loaded lazily** — never at module top-level. Use `createRequire(import.meta.url)` inside a `try/catch` for synchronous lazy loading. - -2. **Centralized wrapper pattern** — when multiple source files import from the same optional package, create a single wrapper module (e.g., `otel-api.ts`) that provides the fallback logic. Consumers import from the wrapper. - -3. **`@opentelemetry/api` is now an optionalDependency** — it was a hard dependency but is functionally optional. The SDK operates with no-op telemetry when absent. - -4. **`vscode-jsonrpc` added as direct dep** — improves hoisting for npx installs. The ESM subpath import issue (`vscode-jsonrpc/node` without `.js`) is upstream in `@github/copilot-sdk`. - -## Implications - -- Any new OTel integration must import from `runtime/otel-api.js`, never directly from `@opentelemetry/api`. -- Test files may continue importing `@opentelemetry/api` directly (it's installed in dev). -- If adding new optional dependencies in the future, follow the same lazy-load + wrapper pattern. - - -# Release Readiness Check — v0.8.21 - -**By:** Keaton (Lead) -**Date:** 2026-03-07 -**Status:** 🟡 SHIP WITH CAVEATS - - ---- - -## Executive Summary - -v0.8.21 is technically ready to release. All three packages carry the same version string (`0.8.21-preview.7`). Linting passes, 3718 tests pass (19 flaky UI tests pre-existing), CI green on commits. However, **#247 (Installation Failure) must be fixed before shipping**. This is a P0 blocker that breaks the primary installation path. Fenster is actively fixing it. - - ---- - -## Version State ✅ - -All packages aligned at **0.8.21-preview.7:** - -- Root `package.json` — v0.8.21-preview.7 -- `packages/squad-sdk/package.json` — v0.8.21-preview.7 -- `packages/squad-cli/package.json` — v0.8.21-preview.7 - -**Release Tag:** Should be `v0.8.21-preview.7` (already live as -preview, ready to promote to stable or next -preview if #247 requires a patch). - - ---- - -## Git State ✅ - -**Current Branch:** `dev` -**Commits since main:** 23 commits (main..dev) - -Recent activity (last 10 commits): -- 3f924d0 — fix: remove idle blankspace below agent panel (#239) -- 6a9af95 — docs(ai-team): Merge quality directive into team decisions -- 8d4490b — fix: harden flaky tests (EBUSY retry + init speed gate headroom) -- 363a0a8 — feat: Structured model preference & squad-level defaults (#245) -- a488eb8 — fix: wire missing CLI commands into cli-entry.ts (#244) -- b562ef1 — docs: update fenster history & add model-config decision - -**Uncommitted Changes:** 10 files (all acceptable): -- 4 deleted `.squad/decisions/inbox/` files (cleanup, merged to decisions.md) -- 6 untracked images (pilotswarm-*.png — documentation assets) -- 1 untracked `docs/proposals/repl-replacement-prd.md` (draft proposal) - -**Status:** Clean. No staged changes that would block release. - - ---- - -## Open Blockers ⚠️ P0 - -### #247 — Squad Installation Fails 🔴 **CRITICAL BLOCKER** - -**Impact:** Users cannot install via `npm install -g @bradygaster/squad-cli`. -**Assignee:** Fenster (actively fixing) -**Status:** In progress -**Release Impact:** **SHIP CANNOT PROCEED** until resolved. - -**Other Open Issues:** -- #248 — CLI command wiring: `squad triage` does not trigger team assignment loop (minor) -- #242 — Future: Tiered Squad Deployment (deferred, not blocking) -- #241 — New Squad Member for Docs (deferred) -- #240 — ADO configurable work item types (deferred) -- #236 — feat: persistent Ralph (deferred) -- #211 — Squad management paradigms (deferred, release:defer label) - -**Release Blockers:** Only #247 prevents shipping. - - ---- - -## CHANGELOG Review 📝 - -**Current `Unreleased` section covers:** - -### Added — SDK-First Mode (Phase 1) -- Builder functions (defineTeam, defineAgent, defineRouting, defineCeremony, defineHooks, defineCasting, defineTelemetry, defineSquad) -- `squad build` command with --check, --dry-run, --watch flags -- SDK Mode Detection in Coordinator prompt -- Documentation (SDK-First Mode guide, updated SDK Reference, README quick reference) - -### Added — Remote Squad Mode (ported from @spboyer PR #131) -- `resolveSquadPaths()` dual-root resolver -- `squad doctor` command (9-check setup validation) -- `squad link ` command -- `squad init --mode remote` -- `ensureSquadPathDual()` / `ensureSquadPathResolved()` - -### Changed — Distribution & Versioning -- npm-only distribution (no more GitHub-native `npx github:bradygaster/squad`) -- Semantic Versioning fix (X.Y.Z-preview.N format, compliant with semver spec) -- Version transition from public repo (0.8.5.1) to private repo (0.8.x cadence) - -### Fixed -- CLI entry point moved from dist/index.js → dist/cli-entry.js -- CRLF normalization for Windows users -- process.exit() removed from library functions (VS Code extension safe) -- Removed .squad branch protection guard - - ---- - -## Test Status 🟡 - -``` -Test Files: 9 failed | 134 passed (143) -Tests: 19 failed | 3718 passed | 3 todo (3740) -Duration: 80.06s -``` - -**Failures:** All 19 failures are pre-existing UI test timeouts (TerminalHarness spawn issues, not regressions): -- speed-gates.test.ts — 1 timeout -- ux-gates.test.ts — 3 timeouts -- acceptance.test.ts — 8 timeouts -- acceptance/hostile.test.ts — 3 timeouts -- cli/consult.test.ts — 1 timeout - -**Assessment:** Passing rate is strong (99.5% pass rate). Timeouts are environmental (not code regressions). Safe to ship with this test state. - - ---- - -## CI State ✅ - -- **Linting:** ✅ PASS (tsc --noEmit clean on both packages) -- **Build:** ✅ PASS (npm run build succeeds) -- **Tests:** 🟡 PASS (99.5% passing, pre-existing flakes) - - ---- - -## Release Prep Checklist - -- [x] Version strings aligned (0.8.21-preview.7) -- [x] Git state clean (no staged changes) -- [x] Linting passes -- [x] Tests mostly passing (pre-existing flakes only) -- [x] CHANGELOG updated (Unreleased section comprehensive) -- [ ] **#247 resolved (BLOCKER)** -- [ ] Branch merge strategy decided (dev → insiders? or dev → main?) -- [ ] npm publish command prepared - - ---- - -## Merge Strategy - -**Current branches:** -- `main` — stable baseline -- `dev` — integration branch (23 commits ahead of main) -- `insiders` — exists (used for pre-release channel?) - -**Recommendation:** -1. Hold on npm publish until #247 fixed -2. Merge dev → insiders for pre-release testing -3. After QA pass, merge dev → main -4. Tag main as `v0.8.21-preview.7` on npm -5. Consider promoting to `v0.8.21` stable if no further issues - - ---- - -## Draft CHANGELOG Entry for v0.8.21 - -When releasing, move "Unreleased" to versioned section: - -```markdown -## [0.8.21-preview.7] - 2026-03-07 - -### Added — SDK-First Mode (Phase 1) -- [builder functions list] -- [squad build command] -- [SDK Mode Detection] -- [Documentation updates] - -### Added — Remote Squad Mode -- [resolver + commands] - -### Changed — Distribution & Versioning -- [npm-only, semver fix, version transition] - -### Fixed -- [CLI entry point, CRLF, process.exit, branch guard] -``` - - ---- - -## Decision - -**VERDICT: 🟡 RELEASE v0.8.21-preview.7 AFTER #247 FIXED** - -- **GO:** Linting, tests, version alignment all sound. -- **HOLD:** #247 installation failure must be resolved. This is a P0 blocker. -- **ACTION:** Fenster owns #247 fix. Once merged to dev, rerun tests and ship. -- **TIMELINE:** 1–2 hours (estimate: Fenster's ETA on #247). - -**Owner:** Brady (approves final npm publish) -**Fallback:** If #247 unresolvable today, defer to v0.8.22 and open a retro ticket. - - ---- - -## Notes - -- **Community PRs:** 3 community PRs merged cleanly to dev (PR #217, #219, #230). Fork-first contributor workflow is working. -- **Wave planning:** 11 issues targeted for v0.8.22 (5 fix-now + 6 next-wave). 11 deferred to v0.8.23+. -- **Architecture:** SDK/CLI split is clean. Distribution to npm is working. Type safety (strict: true) enforced across both packages. -- **Proposal workflow:** Working as designed. No surprises. - - - -# Decision: Optionalize OpenTelemetry Dependency - -## Context -Telemetry is valuable but should not be a hard requirement for running the SDK. Users in air-gapped environments or minimal setups experienced crashes when `@opentelemetry/api` was missing or incompatible. - -## Decision -We have wrapped `@opentelemetry/api` in a resilient shim (`packages/squad-sdk/src/runtime/otel-api.ts`) and moved the package to `optionalDependencies`. - -### Mechanics -- **Runtime detection:** The wrapper attempts to load `@opentelemetry/api`. -- **Graceful fallback:** If loading fails, it exports no-op implementations of `trace`, `metrics`, and `diag` that match the API surface used by Squad. -- **Developer experience:** Internal code imports from `./runtime/otel-api.ts` instead of the package directly. - -## Consequences -- **Positive:** SDK is robust against missing telemetry dependencies. Installation size is smaller for users who opt out. -- **Negative:** We must maintain the wrapper's type compatibility with the real API. -- **Risk:** If we use new OTel features, we must update the no-op implementation. - -## Status -Accepted and implemented in v0.8.21. - - -# Decision: v0.8.21 Blog Post Scope — SDK-First + Full Release Wave - -**Date:** 2026-03-11 -**Author:** McManus (DevRel) -**Impact:** External communication, developer discovery, release narrative - -## Problem - -v0.8.21 is a major release with TWO significant storylines: -1. **SDK-First Mode** — TypeScript-first authoring, type safety, `squad build` command -2. **Stability Wave** — 26 issues closed, 16 PRs merged, critical crash fix (#247), 3,724 passing tests - -Risk: If blog only emphasizes SDK-First, users miss critical stability improvements (crash fix, Windows hardening, test reliability). If blog buries SDK-First, flagship feature loses visibility. - -## Decision - -Create TWO complementary blog posts with clear ownership: - -1. **`024-v0821-sdk-first-release.md`** (existing) — SDK-First deep dive - - Target: TypeScript-focused teams, SDK adopters - - Scope: Builders, quick start, Azure Function sample, Phase 2/3 roadmap - - Tone: Educational, patterns-focused - -2. **`025-v0821-comprehensive-release.md`** (new) — Full release wave summary - - Target: General audience, release notes consumers - - Scope: All 7 feature areas (SDK-First + Remote Squad + 5 critical fixes), metrics, community credits - - Tone: Reassuring (crash fixed!), factual (26 issues, 0 logic failures) - -**Cross-linking strategy:** -- Comprehensive post links to SDK-First deep dive: "For detailed SDK patterns, see [v0.8.21: SDK-First Mode post](./024-v0821-sdk-first-release.md)" -- SDK-First post references comprehensive post: "For the full release notes, see [v0.8.21: The Complete Release post](./025-v0821-comprehensive-release.md)" - -**CHANGELOG updated once** at `[0.8.21]` section with full scope (all 7 areas) — serves as single source of truth for condensed release info. - -## Rationale - -- **SDK value**: Highlights TypeScript-first workflow, type safety, Azure serverless patterns -- **Stability value**: Installation crash fix alone justifies a major release (user pain elimination) -- **Audience segmentation**: Developers interested in SDK config patterns → read post #024; DevOps/team leads reading release notes → read post #025 -- **SEO/discovery**: Two articles = more surface area for search + internal linking -- **Archive preservation**: Both posts preserved in `docs/blog/` for historical record - -## Alternative Rejected - -**Single mega-post:** Would be 25+ KB, overwhelming, diffuses message (SDK patterns + crash fix + CI stability = scattered narrative). Two posts with clear focus are easier to scan and share. - -## Enforcement - -- CHANGELOG.md single `[0.8.21]` section (source of truth) -- Blog post #025 designated "comprehensive" (headline for external comms) -- Blog post #024 designated "technical deep dive" (for SDK adopters) -- Release announcement on GitHub uses post #025 as primary link - - ---- - -**Decided by:** McManus (DevRel) on behalf of tone ceiling + messaging coherence -**Reviewed by:** Internal tone ceiling check (substantiated claims, no hype, clear value messaging) - - -### 2026-03-07 07:51 UTC: SDK-First init/migrate deferred to v0.8.22 -**By:** Keaton (Coordinator), Brady absent - autonomous decision -**What:** SDK-First mode gaps (init --sdk flag, standalone migrate command, comprehensive docs) deferred to v0.8.22. -**Why:** v0.8.21 has all P0 blockers resolved. Adding features now risks regression. Filed #249, #250, #251. -**Issues filed:** -- #249: squad init --sdk flag for SDK-First mode opt-in -- #250: standalone squad migrate command (subsumes #231) -- #251: comprehensive SDK-First mode documentation - - -### 2026-03-07T08-14-43Z: User directive -**By:** Brady (via Copilot) -**What:** Issues #249, #250, and #251 (SDK-First init --sdk flag, standalone migrate command, comprehensive SDK-First docs) are committed to v0.8.22 - not backlog, not optional. -**Why:** User request - captured for team memory - - -### 2026-03-07T16-19-00Z: Pre-release triage — v0.8.21 release ready pending #248 fix -**By:** Keaton (Lead) -**What:** Analyzed all 23 open issues. Result: v0.8.21 releases cleanly pending fix for #248 (triage team dispatch). v0.8.22 roadmap is well-scoped (9 issues, 3 parallel streams). Close #194 (completed) and #231 (duplicate). -**Why:** Final release gate. Coordinator override: #248 deferred to v0.8.22 (standalone CLI feature, not core to interactive experience). Keeps release unblocked. -**Details:** 2 closeable, 1 P0 override, 9 for v0.8.22, 5 for v0.8.23+, 1 for v0.9+, 4 backlog. See .squad/orchestration-log/2026-03-07T16-19-00Z-keaton.md for full triage table. - -### 2026-03-07T16-19-00Z: PR hold decision — #189 (workstreams) and #191 (ADO) rebase to dev for v0.8.22 -**By:** Hockney (Tester) -**What:** Both PRs are held for v0.8.22 and must rebase from main to dev. Neither ships for v0.8.21. -**Why:** PR #189: merge conflicts, no CI, process.exit() violation, missing CLI tests, 6 unresolved review threads. PR #191: merge conflicts, no CI, untested security fixes, incomplete Planner adapter. Both have solid architecture but insufficient readiness for v0.8.21. -**Details:** See .squad/orchestration-log/2026-03-07T16-19-00Z-hockney.md for detailed code assessment. - -### 2026-03-07T16-19-00Z: Docs ready for v0.8.21 — no release blockers -**By:** McManus (DevRel) -**What:** v0.8.21 documentation is ship-ready. SDK-First mode guide (705 lines), What's New blog, CHANGELOG, and contributors section all complete. No blocking gaps. -**Why:** Release readiness gate. Docs are complete for Phase 1. Minor gaps are non-blocking and addressed in v0.8.22 roadmap. -**Details:** 2 docs issues queued for v0.8.22 (#251 restructure, #210 contributors workflow). See .squad/orchestration-log/2026-03-07T16-19-00Z-mcmanus.md for full triage. - -### 2026-03-07T16:20: User directive — Shift from Actions to CLI -**By:** Brady (via Copilot) -**What:** "I'm seriously concerned about our continued abuse of actions and think the more we can stop relying on actions to do things and start relying on the cli to do things, it puts more emphasis and control in the user's hand and less automation with actions. I think we're maybe going to surprise customers with some of the usage in actions and I would really hate for that to be a deterrent from using squad." -**Why:** User directive — strategic direction for the product. Actions usage can surprise customers with unexpected billing and loss of control. CLI-first puts the user in the driver's seat. - -### Current Actions Inventory (15 workflows) - -**Squad-specific (customer concern):** -1. `sync-squad-labels.yml` — Auto-syncs labels from team.md on push -2. `squad-triage.yml` — Auto-triages issues when labeled "squad" -3. `squad-issue-assign.yml` — Auto-assigns issues when squad:{member} labeled -4. `squad-heartbeat.yml` — Ralph heartbeat/auto-triage (cron currently disabled) -5. `squad-label-enforce.yml` — Label mutual exclusivity on label events - -**Standard CI/Release (expected):** -6. `squad-ci.yml` — Standard PR/push CI -7. `squad-release.yml` — Tag + release on push to main -8. `squad-promote.yml` — Branch promotion (workflow_dispatch) -9. `squad-main-guard.yml` — Forbidden file guard -10. `squad-preview.yml` — Preview validation -11. `squad-docs.yml` — Docs build/deploy -12-15. Publish/insider workflows - -**Directive:** Move squad-specific automation (1-5) into CLI commands. Keep standard CI/release workflows. - -### 2026-03-07T16:20: User directive — Shift from Actions to CLI -**By:** Brady (via Copilot) -**What:** "I'm seriously concerned about our continued abuse of actions and think the more we can stop relying on actions to do things and start relying on the cli to do things, it puts more emphasis and control in the user's hand and less automation with actions. I think we're maybe going to surprise customers with some of the usage in actions and I would really hate for that to be a deterrent from using squad." -**Why:** User directive — strategic direction for the product. Actions usage can surprise customers with unexpected billing and loss of control. CLI-first puts the user in the driver's seat. - -### Current Actions Inventory (15 workflows) - -**Squad-specific (customer concern):** -1. `sync-squad-labels.yml` — Auto-syncs labels from team.md on push -2. `squad-triage.yml` — Auto-triages issues when labeled "squad" -3. `squad-issue-assign.yml` — Auto-assigns issues when squad:{member} labeled -4. `squad-heartbeat.yml` — Ralph heartbeat/auto-triage (cron currently disabled) -5. `squad-label-enforce.yml` — Label mutual exclusivity on label events - -**Standard CI/Release (expected):** -6. `squad-ci.yml` — Standard PR/push CI -7. `squad-release.yml` — Tag + release on push to main -8. `squad-promote.yml` — Branch promotion (workflow_dispatch) -9. `squad-main-guard.yml` — Forbidden file guard -10. `squad-preview.yml` — Preview validation -11. `squad-docs.yml` — Docs build/deploy -12-15. Publish/insider workflows - -**Directive:** Move squad-specific automation (1-5) into CLI commands. Keep standard CI/release workflows. - -### Follow-up (Brady, same session): -> "seems like the more we can offload to ourselves, the more we could control, say, in a container. if actions are doing the work the loop is outside of our control a bit" - -**Key insight:** CLI-first makes Squad **portable**. If the work lives in CLI commands instead of Actions, Squad can run anywhere — Codespaces, devcontainers, local terminals, persistent ACA containers. Actions lock the control loop to GitHub's event system. CLI-first means the user (or their infrastructure) owns the execution loop, not GitHub Actions. - - -# CLI Feasibility Assessment — GitHub Actions → CLI Commands -**Author:** Fenster (Core Dev) -**Date:** 2026-03-07 -**Context:** Brady's request to migrate squad-specific workflows to CLI commands - - ---- - -## Executive Summary - -**Quick wins:** Label sync + label enforce can ship in v0.8.22 (reuses existing parsers, zero new deps). -**Medium effort:** Triage command is 70% done (CLI watch already exists), needs GitHub comment posting. -**Heavy lift:** Issue assign + heartbeat need copilot-swe-agent[bot] API (PAT + agent_assignment field) — no `gh` CLI equivalent exists. Watch mode already implements heartbeat's core logic locally. - -**Key insight:** We already have `squad watch` — it's the local equivalent of `squad-heartbeat.yml`. The workflow runs in GitHub Actions with PAT; watch runs locally with `gh` CLI. They share the same triage logic (`@bradygaster/squad-sdk/ralph/triage`). - - ---- - -## 1. Current CLI Command Inventory - -**Existing commands** (`packages/squad-cli/src/cli/commands/`): - -| Command | Function | Overlap with Workflows | -|---------|----------|------------------------| -| **watch** | Ralph's local polling — triages issues, monitors PRs, assigns labels. Uses `gh` CLI. | ✅ 80% overlap with `squad-heartbeat.yml` + `squad-triage.yml` | -| plugin | Marketplace add/remove. Uses `gh` CLI for repo access. | ❌ No workflow overlap | -| export | Export squad state to JSON. | ❌ No workflow overlap | -| import | Import squad state from JSON. | ❌ No workflow overlap | -| build | SDK config generation. | ❌ No workflow overlap | -| doctor | Health checks (local/remote/hub). | ❌ No workflow overlap | -| aspire | Launch Aspire dashboard for OTel. | ❌ No workflow overlap | -| start | Interactive shell (Coordinator mode). | ❌ No workflow overlap | -| consult | Spawn agent for consultation. | ❌ No workflow overlap | -| rc/rc-tunnel | Remote control server + devtunnel. | ❌ No workflow overlap | -| copilot/copilot-bridge | Copilot SDK adapter. | ❌ No workflow overlap | -| link/init-remote | Link to remote squad repo. | ❌ No workflow overlap | -| streams | Workstream commands (stub). | ❌ No workflow overlap | - -**Key reusable infrastructure:** -- **`gh-cli.ts`** — Thin wrapper around `gh` CLI: `ghIssueList`, `ghIssueEdit`, `ghPrList`, `ghAvailable`, `ghAuthenticated` -- **`@bradygaster/squad-sdk/ralph/triage`** — Shared triage logic (routing rules, module ownership, keyword matching) -- **`watch.ts`** — Already implements triage cycle + PR monitoring - - ---- - -## 2. Per-Workflow Migration Plan - -### 2.1. sync-squad-labels.yml → `squad labels sync` - -**Current workflow:** 170 lines. Parses `team.md`, syncs `squad`, `squad:{member}`, `go:*`, `release:*`, `type:*`, `priority:*`, `bug`, `feedback` labels. Uses Octokit. - -**Proposed CLI command:** -```bash -squad labels sync [--squad-dir .squad] [--dry-run] -``` - -**Implementation:** -- **Size:** S (2-3 hours) -- **Dependencies:** - - ✅ `gh` CLI (already used in plugin.ts, watch.ts) - - ✅ `parseRoster()` from `@bradygaster/squad-sdk/parsers` (already exists) - - ✅ Thin wrapper — reuse roster parser, call `gh label create/edit` -- **Offline:** ❌ Needs GitHub API access via `gh` -- **Reuse:** Roster parsing (team.md → member list) already exists. Just needs label creation loop with `gh`. -- **Complexity:** Low. No auth complexity (uses `gh auth` flow). No copilot-swe-agent API. - -**Why quick win:** Zero new parsers needed. Label sync is idempotent (create-or-update pattern). Can run manually after `team.md` changes. - - ---- - -### 2.2. squad-triage.yml → `squad triage` (or extend `squad watch`) - -**Current workflow:** 260 lines. On `squad` label, parses `team.md` + `routing.md`, keyword-matches, applies `squad:{member}` label, posts comment. - -**Proposed CLI command:** -```bash -squad triage [--issue ] [--squad-dir .squad] -``` -Or: enhance `squad watch` to post comments (currently it only adds labels). - -**Implementation:** -- **Size:** M (4-6 hours) -- **Dependencies:** - - ✅ `gh` CLI (already used) - - ✅ `triageIssue()` from `@bradygaster/squad-sdk/ralph/triage` (already used in watch.ts) - - ❌ **Missing:** `gh issue comment` wrapper in `gh-cli.ts` (5 lines to add) -- **Offline:** ❌ Needs GitHub API -- **Reuse:** - - **watch.ts already does this** (line 189-209). Just missing comment posting. - - Triage logic, routing rules, module ownership — all implemented. -- **Complexity:** Low. The logic exists; just needs `gh issue comment --body ` wrapper. - -**Why medium effort:** Code exists. Just needs comment posting feature added to `gh-cli.ts` and called from `watch.ts`. - - ---- - -### 2.3. squad-issue-assign.yml → ??? - -**Current workflow:** 160 lines. On `squad:{member}` label, posts assignment comment, calls **copilot-swe-agent[bot] assignment API with PAT** (lines 116-161). - -**Problem:** The workflow uses a special POST endpoint: -```js -POST /repos/{owner}/{repo}/issues/{issue_number}/assignees -{ - assignees: ['copilot-swe-agent[bot]'], - agent_assignment: { - target_repo: `${owner}/${repo}`, - base_branch: baseBranch, - custom_instructions: '', - custom_agent: '', - model: '' - } -} -``` -**This endpoint does NOT exist in `gh` CLI.** It requires: -- Personal Access Token (PAT) with `issues:write` scope -- Direct Octokit call (cannot use `gh` as thin wrapper) - -**Migration options:** -1. **Add Octokit dependency** — heavyweight (35+ deps), violates zero-dependency CLI goal -2. **Add raw HTTPS module** — 50-100 lines to make authenticated POST with PAT, parse JSON response -3. **Document manual workflow** — "To auto-assign @copilot, use the GitHub Actions workflow (requires PAT)" - -**Proposed approach:** -- **Do NOT migrate.** Keep as workflow-only feature. -- **Reasoning:** The copilot-swe-agent assignment API is GitHub-specific and requires secrets (PAT). CLI commands should not manage secrets. Workflows already have secure secret storage. -- **Alternative:** Document `squad watch` as the local equivalent (it can label + post comments, but not trigger bot assignment). - -**Implementation:** -- **Size:** XL (8-12 hours if full migration) -- **Dependencies:** - - ❌ PAT management (needs secret storage or prompting) - - ❌ Octokit or raw HTTPS POST wrapper (50-100 lines) - - ❌ Not available in `gh` CLI -- **Offline:** ❌ Never (GitHub-specific API) -- **Complexity:** High. Requires secret handling, bot assignment API, error handling, fallback. - -**Recommendation:** **Do not migrate.** Keep as workflow. Document that copilot auto-assign requires Actions + PAT. - - ---- - -### 2.4. squad-heartbeat.yml → Already exists as `squad watch` - -**Current workflow:** 170 lines. Runs on cron (disabled), issues closed/labeled, PRs closed. Triages untriaged issues, assigns @copilot to `squad:copilot` issues. - -**CLI equivalent:** **Already shipped as `squad watch`** (`packages/squad-cli/src/cli/commands/watch.ts`, 356 lines). - -**What `squad watch` does:** -- Polls open issues with `squad` label -- Triages untriaged issues (adds `squad:{member}` label) -- Monitors PRs (draft/needs-review/changes-requested/CI failures/ready-to-merge) -- Runs on interval (default: 30 minutes) -- Uses `gh` CLI for auth + API access -- Uses shared `@bradygaster/squad-sdk/ralph/triage` logic - -**What `squad watch` does NOT do (that heartbeat.yml does):** -- ❌ Post triage comments (workflow posts "Ralph — Auto-Triage" comments) -- ❌ Auto-assign copilot-swe-agent[bot] (requires PAT + bot API, same issue as #2.3) - -**Implementation gap:** -- **Comment posting:** M (4-6 hours) — add `gh issue comment` wrapper to `gh-cli.ts`, call it from `runCheck()` in watch.ts -- **Copilot auto-assign:** Do not migrate (same as #2.3) - -**Migration plan:** -- ✅ **Already done.** `squad watch` is the local heartbeat. -- **Add comment posting** to match workflow behavior (quick win, 4-6 hours). -- **Document copilot auto-assign** as workflow-only (requires PAT). - -**Recommendation:** Enhance `squad watch` with comment posting. Keep copilot auto-assign in workflow. - - ---- - -### 2.5. squad-label-enforce.yml → `squad labels enforce` - -**Current workflow:** 180 lines. On label applied, removes conflicting labels from mutual-exclusivity namespaces (`go:`, `release:`, `type:`, `priority:`). Posts update comment. - -**Proposed CLI command:** -```bash -squad labels enforce [--issue ] [--squad-dir .squad] -``` - -**Implementation:** -- **Size:** S (2-4 hours) -- **Dependencies:** - - ✅ `gh` CLI (already used) - - ❌ `gh issue edit --remove-label