From 4915febce666c39232d453f87b048eb632f61b3f 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/5] =?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 9daa903e351355be205c987ecf1ff5ddeac3469d Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Mon, 23 Mar 2026 16:08:29 -0700 Subject: [PATCH 2/5] fix(shell): robust agent name extraction with multi-pattern fallback (#577) - Fix TS compilation errors in agent-name-parser.ts (strict null checks) - Add fallback in else branch: show trimmed description text instead of generic 'Dispatching to agent...' hint when name extraction fails - Parser tries 3 patterns: emoji+name:colon, name:colon anywhere, fuzzy word-boundary match against known agent names Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .squad-templates/squad.agent.md | 18 +++--- .squad/agents/procedures/history.md | 13 ++++ .../src/cli/shell/agent-name-parser.ts | 60 +++++++++++++++++++ packages/squad-cli/src/cli/shell/index.ts | 11 ++-- 4 files changed, 90 insertions(+), 12 deletions(-) create mode 100644 packages/squad-cli/src/cli/shell/agent-name-parser.ts diff --git a/.squad-templates/squad.agent.md b/.squad-templates/squad.agent.md index 2dfbd0645..0a9b173e9 100644 --- a/.squad-templates/squad.agent.md +++ b/.squad-templates/squad.agent.md @@ -191,12 +191,12 @@ When spawning agents, include the role emoji in the `description` parameter to m 4. If no match, use πŸ‘€ as fallback **Examples:** -- `description: "πŸ—οΈ Keaton: Reviewing architecture proposal"` -- `description: "πŸ”§ Fenster: Refactoring auth module"` -- `description: "πŸ§ͺ Hockney: Writing test cases"` -- `description: "πŸ“‹ Scribe: Log session & merge decisions"` +- `name: "keaton"`, `description: "πŸ—οΈ Keaton: Reviewing architecture proposal"` +- `name: "fenster"`, `description: "πŸ”§ Fenster: Refactoring auth module"` +- `name: "hockney"`, `description: "πŸ§ͺ Hockney: Writing test cases"` +- `name: "scribe"`, `description: "πŸ“‹ Scribe: Log session & merge decisions"` -The emoji makes task spawn notifications visually consistent with the launch table shown to users. +The `name` parameter generates the human-readable agent ID shown in the tasks panel β€” it MUST be the agent's lowercase cast name (e.g., `"eecom"`, `"fido"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. ### Directive Capture @@ -314,6 +314,7 @@ After routing determines WHO handles work, select the response MODE based on tas agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | You are {Name}, the {Role} on this project. @@ -408,6 +409,7 @@ Pass the resolved model as the `model` parameter on every `task` tool call: agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | ... @@ -747,6 +749,7 @@ e. **Include worktree context in spawn:** agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | You are {Name}, the {Role} on this project. @@ -819,7 +822,7 @@ prompt: | 1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without calling the `task` tool, that is NOT the agent. That is you (the Coordinator) pretending. 2. **Never simulate agent output.** Don't generate what you think an agent would say. Call the `task` tool and let the real agent respond. 3. **Never skip the `task` tool for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions β€” see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn. -4. **Never use a generic `description`.** The `description` parameter MUST include the agent's name. `"General purpose task"` is wrong. `"Dallas: Fix button alignment"` is right. +4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong β€” `name: "dallas"` is right. `"General purpose task"` is wrong β€” `"Dallas: Fix button alignment"` is right. 5. **Never serialize agents because of shared memory files.** The drop-box pattern exists to eliminate file conflicts. If two agents both have decisions to record, they both write to their own inbox files β€” no conflict. ### After Agent Work @@ -850,6 +853,7 @@ After each batch of agent work: agent_type: "general-purpose" model: "claude-haiku-4.5" mode: "background" +name: "scribe" description: "πŸ“‹ Scribe: Log session & merge decisions" prompt: | You are the Scribe. Read .squad/agents/scribe/charter.md. @@ -1004,7 +1008,7 @@ When `.squad/team.md` exists but `.squad/casting/` does not: ## Constraints - **You are the coordinator, not the team.** Route work; don't do domain work yourself. -- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"` and a `description` that includes the agent's name. Never simulate or role-play an agent's response. +- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"`, a `name` set to the agent's lowercase cast name, and a `description` that includes the agent's name. Never simulate or role-play an agent's response. - **Each agent may read ONLY: its own files + `.squad/decisions.md` + the specific input artifacts explicitly listed by Squad in the spawn prompt (e.g., the file(s) under review).** Never load all charters at once. - **Keep responses human.** Say "{AgentName} is looking at this" not "Spawning backend-dev agent." - **1-2 agents per question, not all of them.** Not everyone needs to speak. diff --git a/.squad/agents/procedures/history.md b/.squad/agents/procedures/history.md index 04321f07a..a789b83b8 100644 --- a/.squad/agents/procedures/history.md +++ b/.squad/agents/procedures/history.md @@ -124,3 +124,16 @@ Pattern: Agent specification gap identified. Procedures owns formal spec structu Wave 1 governance work on #500 and #344: authored economy-mode skill (`SKILL.md`), economy-mode governance proposal, and personal-squad governance proposal. Caught `claude-sonnet-4.6` missing from valid models catalog. PR #503 (`squad/500-344-governance`) merged to dev. +### 2025-07: Spawn template `name` parameter fix (#577) + +**Problem:** Agent cast names weren't displayed during work β€” the tasks panel showed generic slugs like "general-purpose-task" instead of the cast name. Root cause: spawn templates in `squad.agent.md` specified `description` but NOT the `name` parameter for the `task` tool. The `name` parameter generates the human-readable agent ID shown in the tasks panel. + +**Fix:** Added `name: "{name}"` (lowercase cast name) to all spawn templates in `.squad-templates/squad.agent.md`: +- Lightweight Spawn Template +- Model-passing example +- Main full spawn template ("Template for any agent") +- Scribe spawn template (hardcoded `name: "scribe"`) + +Also updated: examples section (showing `name` + `description` pairs), anti-pattern #4 (now covers both `name` and `description`), and Constraints section (requiring `name` on every spawn). + +**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. diff --git a/packages/squad-cli/src/cli/shell/agent-name-parser.ts b/packages/squad-cli/src/cli/shell/agent-name-parser.ts new file mode 100644 index 000000000..ff38859b6 --- /dev/null +++ b/packages/squad-cli/src/cli/shell/agent-name-parser.ts @@ -0,0 +1,60 @@ +/** + * Extract an agent name from a task description string. + * Tries multiple patterns in order of specificity: + * 1. Emoji + name + colon at start (e.g. "πŸ”§ EECOM: Fix auth module") + * 2. Name + colon anywhere (e.g. "EECOM: Fix auth module") + * 3. Fuzzy: any knownAgentName appears as a whole word (case-insensitive) + * + * @param description - The task description string + * @param knownAgentNames - Lowercase agent names to match against + * @returns Parsed agent name and task summary, or null if no match + */ +export function parseAgentFromDescription( + description: string, + knownAgentNames: string[], +): { agentName: string; taskSummary: string } | null { + if (!description || typeof description !== 'string') return null; + if (!knownAgentNames || knownAgentNames.length === 0) return null; + + // Pattern 1: optional leading non-whitespace (emoji) then whitespace then word + colon at start + const leadingMatch = description.match(/^\S*\s*(\w+):/); + const leadingName = leadingMatch?.[1]; + if (leadingName) { + const candidate = leadingName.toLowerCase(); + if (knownAgentNames.includes(candidate)) { + const taskSummary = description.replace(/^\S*\s*\w+:\s*/, '').slice(0, 60); + return { agentName: candidate, taskSummary }; + } + } + + // Pattern 2: word + colon anywhere in the string + const anyColonMatch = description.match(/(\w+):/); + const colonName = anyColonMatch?.[1]; + if (colonName) { + const candidate = colonName.toLowerCase(); + if (knownAgentNames.includes(candidate)) { + const afterColon = description.slice( + (anyColonMatch.index ?? 0) + anyColonMatch[0].length, + ).replace(/^\s*/, '').slice(0, 60); + return { agentName: candidate, taskSummary: afterColon || description.slice(0, 60) }; + } + } + + // Pattern 3: fuzzy β€” check if any known agent name appears as a word boundary match + const descLower = description.toLowerCase(); + for (const name of knownAgentNames) { + const idx = descLower.indexOf(name); + if (idx !== -1) { + // Verify word boundary: char before and after must be non-word or start/end + const charBefore = idx > 0 ? description.charAt(idx - 1) : ''; + const charAfter = idx + name.length < description.length ? description.charAt(idx + name.length) : ''; + const before = idx === 0 || !/\w/.test(charBefore); + const after = charAfter === '' || !/\w/.test(charAfter); + if (before && after) { + return { agentName: name, taskSummary: description.slice(0, 60) }; + } + } + } + + return null; +} diff --git a/packages/squad-cli/src/cli/shell/index.ts b/packages/squad-cli/src/cli/shell/index.ts index c5265509b..e8be47775 100644 --- a/packages/squad-cli/src/cli/shell/index.ts +++ b/packages/squad-cli/src/cli/shell/index.ts @@ -25,6 +25,7 @@ import type { ShellMessage } from './types.js'; import { initSquadTelemetry, TIMEOUTS, StreamingPipeline, recordAgentSpawn, recordAgentDuration, recordAgentError, recordAgentDestroy, RuntimeEventBus, resolveSquad, resolveGlobalSquadPath } from '@bradygaster/squad-sdk'; import type { UsageEvent } from '@bradygaster/squad-sdk'; import { enableShellMetrics, recordShellSessionDuration, recordAgentResponseLatency, recordShellError } from './shell-metrics.js'; +import { parseAgentFromDescription } from './agent-name-parser.js'; import { buildCoordinatorPrompt, buildInitModePrompt, parseCoordinatorResponse, hasRosterEntries } from './coordinator.js'; import { loadAgentCharter, buildAgentPrompt } from './spawn.js'; import { createSession, saveSession, loadLatestSession, type SessionData } from './session-store.js'; @@ -679,17 +680,17 @@ export async function runShell(): Promise { }; // Try to extract agent name from task description (e.g., "πŸ”§ Morpheus: Building effects") const desc = typeof event['description'] === 'string' ? event['description'] as string : ''; - const agentMatch = desc.match(/^\S*\s*(\w+):/); - const matchedAgent = agentMatch?.[1]?.toLowerCase(); - if (matchedAgent && knownAgentNames.includes(matchedAgent)) { + const parsed = parseAgentFromDescription(desc, knownAgentNames); + if (parsed) { + const { agentName: matchedAgent, taskSummary } = parsed; registry.updateStatus(matchedAgent, 'working'); - const taskSummary = desc.replace(/^\S*\s*\w+:\s*/, '').slice(0, 60); registry.updateActivityHint(matchedAgent, taskSummary || 'working...'); shellApi?.setActivityHint(`${registry.get(matchedAgent)?.name ?? matchedAgent} β€” ${taskSummary || 'working'}...`); shellApi?.setAgentActivity(matchedAgent, taskSummary || 'working...'); shellApi?.refreshAgents(); } else { - const hint = hintMap[toolName] ?? `Using ${toolName}...`; + const trimmedDesc = desc.trim().slice(0, 80); + const hint = trimmedDesc || (hintMap[toolName] ?? `Using ${toolName}...`); shellApi?.setActivityHint(hint); } } From 16627fb254790a97384ef9d763a0b3f949af25aa Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Mon, 23 Mar 2026 16:09:09 -0700 Subject: [PATCH 3/5] docs(.squad): VOX history + decision for #577 agent name fix Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .squad/agents/fido/history.md | 6 + .squad/agents/vox/history.md | 8 + .../decisions/inbox/fido-agent-name-tests.md | 16 ++ .../decisions/inbox/procedures-spawn-name.md | 17 ++ .../inbox/vox-agent-name-extraction.md | 22 ++ packages/squad-cli/package.json | 6 +- test/agent-name-extraction.test.ts | 205 ++++++++++++++++++ 7 files changed, 279 insertions(+), 1 deletion(-) create mode 100644 .squad/decisions/inbox/fido-agent-name-tests.md create mode 100644 .squad/decisions/inbox/procedures-spawn-name.md create mode 100644 .squad/decisions/inbox/vox-agent-name-extraction.md create mode 100644 test/agent-name-extraction.test.ts diff --git a/.squad/agents/fido/history.md b/.squad/agents/fido/history.md index 861da74cf..d9f9eec56 100644 --- a/.squad/agents/fido/history.md +++ b/.squad/agents/fido/history.md @@ -131,3 +131,9 @@ Pattern: Quality tooling gap identified. ESLint 9 modernization + async/promise πŸ“Œ **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. FIDO owns Code Quality Linting PRD (#477). ESLint 9 PoC already drafted; ready for implementation planning. +### Agent Name Extraction Test Coverage (#577) + +Extracted inline regex-based agent name parsing from `shell/index.ts` into a testable pure function `parseAgentFromDescription` in `shell/agent-name-parser.ts`. Created 30 tests across 7 categories: happy path, emoji variations, case insensitivity, fuzzy fallback, no-match, edge cases, and adversarial inputs. The function uses a 3-tier matching strategy: (1) leading emoji+name+colon regex, (2) name+colon anywhere regex, (3) fuzzy word-boundary match against known agent names. Shell index.ts now imports and delegates to this function. Build and tests green. + +**Learning:** Inline regex logic in UI code is untestable and fragile. Extracting to a pure function with explicit inputs (description string + known names array) makes it trivially testable and enables VOX's parallel fix to land cleanly. + diff --git a/.squad/agents/vox/history.md b/.squad/agents/vox/history.md index 40ef43605..838dd6f29 100644 --- a/.squad/agents/vox/history.md +++ b/.squad/agents/vox/history.md @@ -14,3 +14,11 @@ VOX assigned: Pattern: REPL UX gap identified. Shell interaction polish required before documentation freeze for v0.9 release. πŸ“Œ **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. VOX owns REPL UX polish (#478). Shell readiness is documentation gate for PAO. Coordinate on demo scenarios and example workflows for Guide integration. + +### Agent Name Display Fix (#577) (2025-07-25) + +**P0 bug: agent cast names not displayed during work β€” showing generic type names instead.** + +Fixed `agent-name-parser.ts` TS strict-null compilation errors (bracket indexing on strings returns `string | undefined`; switched to `.charAt()` and optional chaining). Improved the else-branch fallback in `index.ts` to show the trimmed task description instead of generic "Dispatching to agent..." when name extraction fails completely. + +Pattern: The `parseAgentFromDescription` parser tries 3 extraction strategies in order β€” emoji+name:colon prefix, name:colon anywhere, fuzzy word-boundary match. If all fail, the shell now shows the raw description text so the user still sees something meaningful. diff --git a/.squad/decisions/inbox/fido-agent-name-tests.md b/.squad/decisions/inbox/fido-agent-name-tests.md new file mode 100644 index 000000000..c001cc368 --- /dev/null +++ b/.squad/decisions/inbox/fido-agent-name-tests.md @@ -0,0 +1,16 @@ +# Decision: Extract agent name parsing into testable helper + +**Author:** FIDO +**Date:** 2025-07-25 +**Issue:** #577 + +## Context +The agent name extraction logic was inline in `shell/index.ts` (lines 680-694), making it impossible to unit test. The regex was fragile and breaking when description formats changed. + +## Decision +Extracted the matching logic into `packages/squad-cli/src/cli/shell/agent-name-parser.ts` as a pure function `parseAgentFromDescription(description, knownAgentNames)`. The shell index now imports and delegates to this function. + +## Implications +- VOX's regex robustness fix should be applied to `agent-name-parser.ts` rather than inline in `index.ts` +- New package export added: `@bradygaster/squad-cli/shell/agent-name-parser` +- 30 tests in `test/agent-name-extraction.test.ts` serve as regression guard for any future changes to the matching logic diff --git a/.squad/decisions/inbox/procedures-spawn-name.md b/.squad/decisions/inbox/procedures-spawn-name.md new file mode 100644 index 000000000..35cd13e28 --- /dev/null +++ b/.squad/decisions/inbox/procedures-spawn-name.md @@ -0,0 +1,17 @@ +# Decision: Spawn templates must include `name` parameter + +**Date:** 2025-07 +**Author:** Procedures +**Issue:** #577 + +## Decision + +Every `task` tool spawn MUST include the `name` parameter set to the agent's lowercase cast name (e.g., `name: "eecom"`, `name: "fido"`, `name: "scribe"`). + +## Rationale + +The `name` parameter generates the human-readable agent ID displayed in the Copilot CLI tasks panel. Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name, making it impossible for users to identify which agent is working. + +## Scope + +All spawn templates in `squad.agent.md` β€” Lightweight, Main, Model-passing, and Scribe templates. Applies to any future spawn templates added to the system. diff --git a/.squad/decisions/inbox/vox-agent-name-extraction.md b/.squad/decisions/inbox/vox-agent-name-extraction.md new file mode 100644 index 000000000..940d0e481 --- /dev/null +++ b/.squad/decisions/inbox/vox-agent-name-extraction.md @@ -0,0 +1,22 @@ +# Decision: Agent name extraction uses dedicated parser module + +**Author:** VOX +**Date:** 2025-07-25 +**Issue:** #577 + +## Context + +The shell's agent name extraction was a single fragile regex inline in `index.ts`. When the coordinator LLM formatted descriptions differently, names silently fell through to generic hints. + +## Decision + +Agent name extraction now lives in `agent-name-parser.ts` with 3 cascading strategies: +1. Emoji + name + colon at start of string +2. Name + colon anywhere in string +3. Fuzzy word-boundary match against known agent names + +When all strategies fail, the shell shows the trimmed description text instead of a generic tool hint. + +## Impact + +Any future changes to how coordinator formats task descriptions should update the patterns in `agent-name-parser.ts`, not `index.ts`. diff --git a/packages/squad-cli/package.json b/packages/squad-cli/package.json index b6b652061..cd94a9821 100644 --- a/packages/squad-cli/package.json +++ b/packages/squad-cli/package.json @@ -1,6 +1,6 @@ { "name": "@bradygaster/squad-cli", - "version": "0.9.1", + "version": "0.9.1-build.4", "description": "Squad CLI β€” Command-line interface for the Squad multi-agent runtime", "type": "module", "bin": { @@ -72,6 +72,10 @@ "types": "./dist/cli/shell/shell-metrics.d.ts", "import": "./dist/cli/shell/shell-metrics.js" }, + "./shell/agent-name-parser": { + "types": "./dist/cli/shell/agent-name-parser.d.ts", + "import": "./dist/cli/shell/agent-name-parser.js" + }, "./core/detect-squad-dir": { "types": "./dist/cli/core/detect-squad-dir.d.ts", "import": "./dist/cli/core/detect-squad-dir.js" diff --git a/test/agent-name-extraction.test.ts b/test/agent-name-extraction.test.ts new file mode 100644 index 000000000..13316a933 --- /dev/null +++ b/test/agent-name-extraction.test.ts @@ -0,0 +1,205 @@ +/** + * Tests for agent name extraction from task descriptions. + * + * Validates the parseAgentFromDescription helper that extracts agent identity + * from free-form task description strings used in the shell UI. + * + * @module test/agent-name-extraction + */ + +import { describe, it, expect } from 'vitest'; +import { parseAgentFromDescription } from '@bradygaster/squad-cli/shell/agent-name-parser'; + +const KNOWN = ['eecom', 'flight', 'scribe', 'fido', 'vox', 'dsky', 'pao']; + +// ============================================================================ +// Happy-path: standard "emoji NAME: summary" format +// ============================================================================ +describe('parseAgentFromDescription β€” happy path', () => { + it('parses emoji + uppercase name + colon', () => { + const result = parseAgentFromDescription('πŸ”§ EECOM: Fix auth module', KNOWN); + expect(result).toEqual({ agentName: 'eecom', taskSummary: 'Fix auth module' }); + }); + + it('parses Flight with building emoji', () => { + const result = parseAgentFromDescription('πŸ—οΈ Flight: Reviewing architecture', KNOWN); + expect(result).toEqual({ agentName: 'flight', taskSummary: 'Reviewing architecture' }); + }); + + it('parses Scribe with clipboard emoji', () => { + const result = parseAgentFromDescription('πŸ“‹ Scribe: Log session & merge decisions', KNOWN); + expect(result).toEqual({ agentName: 'scribe', taskSummary: 'Log session & merge decisions' }); + }); + + it('parses FIDO with test tube emoji', () => { + const result = parseAgentFromDescription('πŸ§ͺ FIDO: Writing test cases', KNOWN); + expect(result).toEqual({ agentName: 'fido', taskSummary: 'Writing test cases' }); + }); +}); + +// ============================================================================ +// Emoji variations +// ============================================================================ +describe('parseAgentFromDescription β€” emoji variations', () => { + it('handles multi-byte emoji (βš›οΈ)', () => { + const result = parseAgentFromDescription('βš›οΈ DSKY: Building TUI', KNOWN); + expect(result).toEqual({ agentName: 'dsky', taskSummary: 'Building TUI' }); + }); + + it('handles no emoji prefix', () => { + const result = parseAgentFromDescription('EECOM: Fix auth module', KNOWN); + expect(result).toEqual({ agentName: 'eecom', taskSummary: 'Fix auth module' }); + }); + + it('handles multiple spaces after emoji', () => { + const result = parseAgentFromDescription('πŸ”§ EECOM: Fix auth module', KNOWN); + expect(result).toEqual({ agentName: 'eecom', taskSummary: 'Fix auth module' }); + }); +}); + +// ============================================================================ +// Case insensitivity +// ============================================================================ +describe('parseAgentFromDescription β€” case insensitivity', () => { + it('matches lowercase input against lowercase known', () => { + const result = parseAgentFromDescription('πŸ”§ eecom: Fix auth module', KNOWN); + expect(result).toEqual({ agentName: 'eecom', taskSummary: 'Fix auth module' }); + }); + + it('matches UPPERCASE input against lowercase known', () => { + const result = parseAgentFromDescription('πŸ”§ EECOM: Fix auth module', KNOWN); + expect(result).toEqual({ agentName: 'eecom', taskSummary: 'Fix auth module' }); + }); + + it('matches Mixed case input against lowercase known', () => { + const result = parseAgentFromDescription('πŸ”§ Eecom: Fix auth module', KNOWN); + expect(result).toEqual({ agentName: 'eecom', taskSummary: 'Fix auth module' }); + }); +}); + +// ============================================================================ +// Fuzzy fallback (name present but format differs) +// ============================================================================ +describe('parseAgentFromDescription β€” fuzzy fallback', () => { + it('finds agent name mentioned without colon pattern', () => { + const result = parseAgentFromDescription('general-purpose task for EECOM', KNOWN); + expect(result).not.toBeNull(); + expect(result!.agentName).toBe('eecom'); + expect(result!.taskSummary).toBe('general-purpose task for EECOM'); + }); + + it('finds VOX in a differently structured sentence', () => { + const result = parseAgentFromDescription('Working on shell β€” VOX task', KNOWN); + expect(result).not.toBeNull(); + expect(result!.agentName).toBe('vox'); + }); +}); + +// ============================================================================ +// No match β†’ null +// ============================================================================ +describe('parseAgentFromDescription β€” no match', () => { + it('returns null for generic description with no known name', () => { + expect( + parseAgentFromDescription('general-purpose agent working on task', ['eecom', 'flight']), + ).toBeNull(); + }); + + it('returns null for empty string', () => { + expect(parseAgentFromDescription('', KNOWN)).toBeNull(); + }); + + it('returns null for unrelated text', () => { + expect(parseAgentFromDescription('Dispatching to agent...', ['eecom', 'flight'])).toBeNull(); + }); +}); + +// ============================================================================ +// Edge cases +// ============================================================================ +describe('parseAgentFromDescription β€” edge cases', () => { + it('picks first agent when multiple known names appear', () => { + const result = parseAgentFromDescription('πŸ”§ EECOM: Fix bug found by FIDO', KNOWN); + expect(result).not.toBeNull(); + expect(result!.agentName).toBe('eecom'); + }); + + it('matches agent name that is substring-safe (vox vs invoice)', () => { + const result = parseAgentFromDescription('πŸ”§ VOX: Fixed invoice rendering', KNOWN); + expect(result!.agentName).toBe('vox'); + }); + + it('handles description that is just the agent name', () => { + const result = parseAgentFromDescription('EECOM', KNOWN); + expect(result).not.toBeNull(); + expect(result!.agentName).toBe('eecom'); + expect(result!.taskSummary).toBeDefined(); + }); + + it('truncates very long descriptions in taskSummary', () => { + const longDesc = 'πŸ”§ EECOM: ' + 'A'.repeat(500); + const result = parseAgentFromDescription(longDesc, KNOWN); + expect(result).not.toBeNull(); + expect(result!.taskSummary.length).toBeLessThanOrEqual(60); + }); + + it('handles special characters in description', () => { + const result = parseAgentFromDescription('πŸ”§ EECOM: Fix auth (OAuth 2.0) β€” urgent!', KNOWN); + expect(result).not.toBeNull(); + expect(result!.agentName).toBe('eecom'); + expect(result!.taskSummary).toContain('OAuth 2.0'); + }); + + it('matches agent name embedded in kebab-case value (fuzzy)', () => { + const result = parseAgentFromDescription('eecom-fix-auth', KNOWN); + expect(result).not.toBeNull(); + expect(result!.agentName).toBe('eecom'); + }); + + it('returns null for empty knownAgentNames array', () => { + expect(parseAgentFromDescription('πŸ”§ EECOM: Fix auth', [])).toBeNull(); + }); + + it('returns null when description is only emoji', () => { + expect(parseAgentFromDescription('πŸ”§', KNOWN)).toBeNull(); + }); + + it('handles agent name with numbers', () => { + const result = parseAgentFromDescription('πŸ”§ agent1: checking build', ['agent1']); + expect(result).not.toBeNull(); + expect(result!.agentName).toBe('agent1'); + }); + + it('handles unicode characters in description but not in name', () => { + const result = parseAgentFromDescription('πŸ”§ EECOM: Fix fΓΌr ÜberprΓΌfung', KNOWN); + expect(result).not.toBeNull(); + expect(result!.agentName).toBe('eecom'); + }); +}); + +// ============================================================================ +// Adversarial inputs +// ============================================================================ +describe('parseAgentFromDescription β€” adversarial inputs', () => { + it('returns null for null input', () => { + expect(parseAgentFromDescription(null as unknown as string, KNOWN)).toBeNull(); + }); + + it('returns null for undefined input', () => { + expect(parseAgentFromDescription(undefined as unknown as string, KNOWN)).toBeNull(); + }); + + it('returns null for numeric input', () => { + expect(parseAgentFromDescription(42 as unknown as string, KNOWN)).toBeNull(); + }); + + it('returns null for null knownAgentNames', () => { + expect(parseAgentFromDescription('πŸ”§ EECOM: Fix auth', null as unknown as string[])).toBeNull(); + }); + + it('returns null for undefined knownAgentNames', () => { + expect( + parseAgentFromDescription('πŸ”§ EECOM: Fix auth', undefined as unknown as string[]), + ).toBeNull(); + }); +}); From 36f21e17e7c9591abe9dab8e45394b6fdfc6f53c Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Mon, 23 Mar 2026 16:11:40 -0700 Subject: [PATCH 4/5] chore: sync squad.agent.md template copies after #577 name param fix Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/agents/squad.agent.md | 18 +++++++++++------- packages/squad-cli/templates/squad.agent.md | 18 +++++++++++------- packages/squad-sdk/templates/squad.agent.md | 18 +++++++++++------- templates/squad.agent.md | 18 +++++++++++------- 4 files changed, 44 insertions(+), 28 deletions(-) diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md index 2dfbd0645..0a9b173e9 100644 --- a/.github/agents/squad.agent.md +++ b/.github/agents/squad.agent.md @@ -191,12 +191,12 @@ When spawning agents, include the role emoji in the `description` parameter to m 4. If no match, use πŸ‘€ as fallback **Examples:** -- `description: "πŸ—οΈ Keaton: Reviewing architecture proposal"` -- `description: "πŸ”§ Fenster: Refactoring auth module"` -- `description: "πŸ§ͺ Hockney: Writing test cases"` -- `description: "πŸ“‹ Scribe: Log session & merge decisions"` +- `name: "keaton"`, `description: "πŸ—οΈ Keaton: Reviewing architecture proposal"` +- `name: "fenster"`, `description: "πŸ”§ Fenster: Refactoring auth module"` +- `name: "hockney"`, `description: "πŸ§ͺ Hockney: Writing test cases"` +- `name: "scribe"`, `description: "πŸ“‹ Scribe: Log session & merge decisions"` -The emoji makes task spawn notifications visually consistent with the launch table shown to users. +The `name` parameter generates the human-readable agent ID shown in the tasks panel β€” it MUST be the agent's lowercase cast name (e.g., `"eecom"`, `"fido"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. ### Directive Capture @@ -314,6 +314,7 @@ After routing determines WHO handles work, select the response MODE based on tas agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | You are {Name}, the {Role} on this project. @@ -408,6 +409,7 @@ Pass the resolved model as the `model` parameter on every `task` tool call: agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | ... @@ -747,6 +749,7 @@ e. **Include worktree context in spawn:** agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | You are {Name}, the {Role} on this project. @@ -819,7 +822,7 @@ prompt: | 1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without calling the `task` tool, that is NOT the agent. That is you (the Coordinator) pretending. 2. **Never simulate agent output.** Don't generate what you think an agent would say. Call the `task` tool and let the real agent respond. 3. **Never skip the `task` tool for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions β€” see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn. -4. **Never use a generic `description`.** The `description` parameter MUST include the agent's name. `"General purpose task"` is wrong. `"Dallas: Fix button alignment"` is right. +4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong β€” `name: "dallas"` is right. `"General purpose task"` is wrong β€” `"Dallas: Fix button alignment"` is right. 5. **Never serialize agents because of shared memory files.** The drop-box pattern exists to eliminate file conflicts. If two agents both have decisions to record, they both write to their own inbox files β€” no conflict. ### After Agent Work @@ -850,6 +853,7 @@ After each batch of agent work: agent_type: "general-purpose" model: "claude-haiku-4.5" mode: "background" +name: "scribe" description: "πŸ“‹ Scribe: Log session & merge decisions" prompt: | You are the Scribe. Read .squad/agents/scribe/charter.md. @@ -1004,7 +1008,7 @@ When `.squad/team.md` exists but `.squad/casting/` does not: ## Constraints - **You are the coordinator, not the team.** Route work; don't do domain work yourself. -- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"` and a `description` that includes the agent's name. Never simulate or role-play an agent's response. +- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"`, a `name` set to the agent's lowercase cast name, and a `description` that includes the agent's name. Never simulate or role-play an agent's response. - **Each agent may read ONLY: its own files + `.squad/decisions.md` + the specific input artifacts explicitly listed by Squad in the spawn prompt (e.g., the file(s) under review).** Never load all charters at once. - **Keep responses human.** Say "{AgentName} is looking at this" not "Spawning backend-dev agent." - **1-2 agents per question, not all of them.** Not everyone needs to speak. diff --git a/packages/squad-cli/templates/squad.agent.md b/packages/squad-cli/templates/squad.agent.md index 3eca10097..f89682965 100644 --- a/packages/squad-cli/templates/squad.agent.md +++ b/packages/squad-cli/templates/squad.agent.md @@ -191,12 +191,12 @@ When spawning agents, include the role emoji in the `description` parameter to m 4. If no match, use πŸ‘€ as fallback **Examples:** -- `description: "πŸ—οΈ Keaton: Reviewing architecture proposal"` -- `description: "πŸ”§ Fenster: Refactoring auth module"` -- `description: "πŸ§ͺ Hockney: Writing test cases"` -- `description: "πŸ“‹ Scribe: Log session & merge decisions"` +- `name: "keaton"`, `description: "πŸ—οΈ Keaton: Reviewing architecture proposal"` +- `name: "fenster"`, `description: "πŸ”§ Fenster: Refactoring auth module"` +- `name: "hockney"`, `description: "πŸ§ͺ Hockney: Writing test cases"` +- `name: "scribe"`, `description: "πŸ“‹ Scribe: Log session & merge decisions"` -The emoji makes task spawn notifications visually consistent with the launch table shown to users. +The `name` parameter generates the human-readable agent ID shown in the tasks panel β€” it MUST be the agent's lowercase cast name (e.g., `"eecom"`, `"fido"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. ### Directive Capture @@ -314,6 +314,7 @@ After routing determines WHO handles work, select the response MODE based on tas agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | You are {Name}, the {Role} on this project. @@ -408,6 +409,7 @@ Pass the resolved model as the `model` parameter on every `task` tool call: agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | ... @@ -747,6 +749,7 @@ e. **Include worktree context in spawn:** agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | You are {Name}, the {Role} on this project. @@ -819,7 +822,7 @@ prompt: | 1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without calling the `task` tool, that is NOT the agent. That is you (the Coordinator) pretending. 2. **Never simulate agent output.** Don't generate what you think an agent would say. Call the `task` tool and let the real agent respond. 3. **Never skip the `task` tool for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions β€” see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn. -4. **Never use a generic `description`.** The `description` parameter MUST include the agent's name. `"General purpose task"` is wrong. `"Dallas: Fix button alignment"` is right. +4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong β€” `name: "dallas"` is right. `"General purpose task"` is wrong β€” `"Dallas: Fix button alignment"` is right. 5. **Never serialize agents because of shared memory files.** The drop-box pattern exists to eliminate file conflicts. If two agents both have decisions to record, they both write to their own inbox files β€” no conflict. ### After Agent Work @@ -850,6 +853,7 @@ After each batch of agent work: agent_type: "general-purpose" model: "claude-haiku-4.5" mode: "background" +name: "scribe" description: "πŸ“‹ Scribe: Log session & merge decisions" prompt: | You are the Scribe. Read .squad/agents/scribe/charter.md. @@ -1004,7 +1008,7 @@ When `.squad/team.md` exists but `.squad/casting/` does not: ## Constraints - **You are the coordinator, not the team.** Route work; don't do domain work yourself. -- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"` and a `description` that includes the agent's name. Never simulate or role-play an agent's response. +- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"`, a `name` set to the agent's lowercase cast name, and a `description` that includes the agent's name. Never simulate or role-play an agent's response. - **Each agent may read ONLY: its own files + `.squad/decisions.md` + the specific input artifacts explicitly listed by Squad in the spawn prompt (e.g., the file(s) under review).** Never load all charters at once. - **Keep responses human.** Say "{AgentName} is looking at this" not "Spawning backend-dev agent." - **1-2 agents per question, not all of them.** Not everyone needs to speak. diff --git a/packages/squad-sdk/templates/squad.agent.md b/packages/squad-sdk/templates/squad.agent.md index 3eca10097..f89682965 100644 --- a/packages/squad-sdk/templates/squad.agent.md +++ b/packages/squad-sdk/templates/squad.agent.md @@ -191,12 +191,12 @@ When spawning agents, include the role emoji in the `description` parameter to m 4. If no match, use πŸ‘€ as fallback **Examples:** -- `description: "πŸ—οΈ Keaton: Reviewing architecture proposal"` -- `description: "πŸ”§ Fenster: Refactoring auth module"` -- `description: "πŸ§ͺ Hockney: Writing test cases"` -- `description: "πŸ“‹ Scribe: Log session & merge decisions"` +- `name: "keaton"`, `description: "πŸ—οΈ Keaton: Reviewing architecture proposal"` +- `name: "fenster"`, `description: "πŸ”§ Fenster: Refactoring auth module"` +- `name: "hockney"`, `description: "πŸ§ͺ Hockney: Writing test cases"` +- `name: "scribe"`, `description: "πŸ“‹ Scribe: Log session & merge decisions"` -The emoji makes task spawn notifications visually consistent with the launch table shown to users. +The `name` parameter generates the human-readable agent ID shown in the tasks panel β€” it MUST be the agent's lowercase cast name (e.g., `"eecom"`, `"fido"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. ### Directive Capture @@ -314,6 +314,7 @@ After routing determines WHO handles work, select the response MODE based on tas agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | You are {Name}, the {Role} on this project. @@ -408,6 +409,7 @@ Pass the resolved model as the `model` parameter on every `task` tool call: agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | ... @@ -747,6 +749,7 @@ e. **Include worktree context in spawn:** agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | You are {Name}, the {Role} on this project. @@ -819,7 +822,7 @@ prompt: | 1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without calling the `task` tool, that is NOT the agent. That is you (the Coordinator) pretending. 2. **Never simulate agent output.** Don't generate what you think an agent would say. Call the `task` tool and let the real agent respond. 3. **Never skip the `task` tool for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions β€” see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn. -4. **Never use a generic `description`.** The `description` parameter MUST include the agent's name. `"General purpose task"` is wrong. `"Dallas: Fix button alignment"` is right. +4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong β€” `name: "dallas"` is right. `"General purpose task"` is wrong β€” `"Dallas: Fix button alignment"` is right. 5. **Never serialize agents because of shared memory files.** The drop-box pattern exists to eliminate file conflicts. If two agents both have decisions to record, they both write to their own inbox files β€” no conflict. ### After Agent Work @@ -850,6 +853,7 @@ After each batch of agent work: agent_type: "general-purpose" model: "claude-haiku-4.5" mode: "background" +name: "scribe" description: "πŸ“‹ Scribe: Log session & merge decisions" prompt: | You are the Scribe. Read .squad/agents/scribe/charter.md. @@ -1004,7 +1008,7 @@ When `.squad/team.md` exists but `.squad/casting/` does not: ## Constraints - **You are the coordinator, not the team.** Route work; don't do domain work yourself. -- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"` and a `description` that includes the agent's name. Never simulate or role-play an agent's response. +- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"`, a `name` set to the agent's lowercase cast name, and a `description` that includes the agent's name. Never simulate or role-play an agent's response. - **Each agent may read ONLY: its own files + `.squad/decisions.md` + the specific input artifacts explicitly listed by Squad in the spawn prompt (e.g., the file(s) under review).** Never load all charters at once. - **Keep responses human.** Say "{AgentName} is looking at this" not "Spawning backend-dev agent." - **1-2 agents per question, not all of them.** Not everyone needs to speak. diff --git a/templates/squad.agent.md b/templates/squad.agent.md index 2dfbd0645..0a9b173e9 100644 --- a/templates/squad.agent.md +++ b/templates/squad.agent.md @@ -191,12 +191,12 @@ When spawning agents, include the role emoji in the `description` parameter to m 4. If no match, use πŸ‘€ as fallback **Examples:** -- `description: "πŸ—οΈ Keaton: Reviewing architecture proposal"` -- `description: "πŸ”§ Fenster: Refactoring auth module"` -- `description: "πŸ§ͺ Hockney: Writing test cases"` -- `description: "πŸ“‹ Scribe: Log session & merge decisions"` +- `name: "keaton"`, `description: "πŸ—οΈ Keaton: Reviewing architecture proposal"` +- `name: "fenster"`, `description: "πŸ”§ Fenster: Refactoring auth module"` +- `name: "hockney"`, `description: "πŸ§ͺ Hockney: Writing test cases"` +- `name: "scribe"`, `description: "πŸ“‹ Scribe: Log session & merge decisions"` -The emoji makes task spawn notifications visually consistent with the launch table shown to users. +The `name` parameter generates the human-readable agent ID shown in the tasks panel β€” it MUST be the agent's lowercase cast name (e.g., `"eecom"`, `"fido"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. ### Directive Capture @@ -314,6 +314,7 @@ After routing determines WHO handles work, select the response MODE based on tas agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | You are {Name}, the {Role} on this project. @@ -408,6 +409,7 @@ Pass the resolved model as the `model` parameter on every `task` tool call: agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | ... @@ -747,6 +749,7 @@ e. **Include worktree context in spawn:** agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | You are {Name}, the {Role} on this project. @@ -819,7 +822,7 @@ prompt: | 1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without calling the `task` tool, that is NOT the agent. That is you (the Coordinator) pretending. 2. **Never simulate agent output.** Don't generate what you think an agent would say. Call the `task` tool and let the real agent respond. 3. **Never skip the `task` tool for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions β€” see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn. -4. **Never use a generic `description`.** The `description` parameter MUST include the agent's name. `"General purpose task"` is wrong. `"Dallas: Fix button alignment"` is right. +4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong β€” `name: "dallas"` is right. `"General purpose task"` is wrong β€” `"Dallas: Fix button alignment"` is right. 5. **Never serialize agents because of shared memory files.** The drop-box pattern exists to eliminate file conflicts. If two agents both have decisions to record, they both write to their own inbox files β€” no conflict. ### After Agent Work @@ -850,6 +853,7 @@ After each batch of agent work: agent_type: "general-purpose" model: "claude-haiku-4.5" mode: "background" +name: "scribe" description: "πŸ“‹ Scribe: Log session & merge decisions" prompt: | You are the Scribe. Read .squad/agents/scribe/charter.md. @@ -1004,7 +1008,7 @@ When `.squad/team.md` exists but `.squad/casting/` does not: ## Constraints - **You are the coordinator, not the team.** Route work; don't do domain work yourself. -- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"` and a `description` that includes the agent's name. Never simulate or role-play an agent's response. +- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"`, a `name` set to the agent's lowercase cast name, and a `description` that includes the agent's name. Never simulate or role-play an agent's response. - **Each agent may read ONLY: its own files + `.squad/decisions.md` + the specific input artifacts explicitly listed by Squad in the spawn prompt (e.g., the file(s) under review).** Never load all charters at once. - **Keep responses human.** Say "{AgentName} is looking at this" not "Spawning backend-dev agent." - **1-2 agents per question, not all of them.** Not everyone needs to speak. From 6a5a2a07c46d54d03a40d68056a3bdacfb2c36ea Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Mon, 23 Mar 2026 16:20:46 -0700 Subject: [PATCH 5/5] Orchestration Log: Issue #577 agent name extraction completion Agent orchestration complete for #577: - VOX: Fixed agent name extraction in shell/index.ts with 3-tier cascading patterns - FIDO: Extracted parser to agent-name-parser.ts (30 tests, all passing) - Procedures: Updated all spawn templates with mandatory name parameter Actions: - Created 3 orchestration logs (.squad/orchestration-log/) - Created session log (.squad/log/2026-03-23T23-15-issue-577-agent-names.md) - Merged 3 decision inbox files to .squad/decisions.md (3 new decision entries) - Deleted inbox files after merge - Appended team updates to VOX, FIDO, Procedures history.md files All decisions merged. Agent IDs now display correctly in Copilot CLI tasks panel. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .squad/agents/fido/history.md | 1 + .squad/agents/procedures/history.md | 2 ++ .squad/agents/vox/history.md | 2 ++ .squad/decisions.md | 23 +++++++++++++++++++ .../decisions/inbox/fido-agent-name-tests.md | 16 ------------- .../decisions/inbox/procedures-spawn-name.md | 17 -------------- .../inbox/vox-agent-name-extraction.md | 22 ------------------ 7 files changed, 28 insertions(+), 55 deletions(-) delete mode 100644 .squad/decisions/inbox/fido-agent-name-tests.md delete mode 100644 .squad/decisions/inbox/procedures-spawn-name.md delete mode 100644 .squad/decisions/inbox/vox-agent-name-extraction.md diff --git a/.squad/agents/fido/history.md b/.squad/agents/fido/history.md index d9f9eec56..f1ffb81db 100644 --- a/.squad/agents/fido/history.md +++ b/.squad/agents/fido/history.md @@ -137,3 +137,4 @@ Extracted inline regex-based agent name parsing from `shell/index.ts` into a tes **Learning:** Inline regex logic in UI code is untestable and fragile. Extracting to a pure function with explicit inputs (description string + known names array) makes it trivially testable and enables VOX's parallel fix to land cleanly. +πŸ“Œ **Team update (2026-03-23T23:15Z):** Orchestration complete. Agent name extraction refactor shipped: FIDO's parser module (30 tests, all passing), VOX's 3-tier cascading patterns, Procedures' spawn template standardization. All decisions merged to decisions.md. Agent IDs now display correctly in Copilot CLI. Canonical patterns: `agent-name-parser.ts` is source of truth for extraction logic. \ No newline at end of file diff --git a/.squad/agents/procedures/history.md b/.squad/agents/procedures/history.md index a789b83b8..bdf10b8e8 100644 --- a/.squad/agents/procedures/history.md +++ b/.squad/agents/procedures/history.md @@ -137,3 +137,5 @@ Wave 1 governance work on #500 and #344: authored economy-mode skill (`SKILL.md` Also updated: examples section (showing `name` + `description` pairs), anti-pattern #4 (now covers both `name` and `description`), and Constraints section (requiring `name` on every spawn). **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). diff --git a/.squad/agents/vox/history.md b/.squad/agents/vox/history.md index 838dd6f29..78f090093 100644 --- a/.squad/agents/vox/history.md +++ b/.squad/agents/vox/history.md @@ -22,3 +22,5 @@ Pattern: REPL UX gap identified. Shell interaction polish required before docume Fixed `agent-name-parser.ts` TS strict-null compilation errors (bracket indexing on strings returns `string | undefined`; switched to `.charAt()` and optional chaining). Improved the else-branch fallback in `index.ts` to show the trimmed task description instead of generic "Dispatching to agent..." when name extraction fails completely. Pattern: The `parseAgentFromDescription` parser tries 3 extraction strategies in order β€” emoji+name:colon prefix, name:colon anywhere, fuzzy word-boundary match. If all fail, the shell now shows the raw description text so the user still sees something meaningful. + +πŸ“Œ **Team update (2026-03-23T23:15Z):** Orchestration complete. FIDO extracted parser into `agent-name-parser.ts` (30 tests, all passing). VOX's 3-tier cascading logic is now canonical. Procedures updated all spawn templates with `name` parameter. Agent IDs now display correctly in Copilot CLI tasks panel. See decisions.md #577 entries. diff --git a/.squad/decisions.md b/.squad/decisions.md index 4c8e0826f..5a954af0c 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -5051,6 +5051,29 @@ Created `.squad/skills/release-process/SKILL.md` with the definitive step-by-ste 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). +--- + +### Agent Name Extraction: Dedicated Parser Module (FIDO) +**Date:** 2026-03-23 +**Issue:** #577 +**What:** Agent name extraction logic extracted from inline regex in `shell/index.ts` into dedicated pure function `parseAgentFromDescription(description, knownAgentNames)` in `packages/squad-cli/src/cli/shell/agent-name-parser.ts`. +**Why:** Inline regex was fragile and untestable. Extraction enables comprehensive unit testing (30 tests, all passing) and regression guards for future coordinator format changes. +**Impact:** All future agent name matching updates route through `agent-name-parser.ts`, not `index.ts`. VOX's 3-tier cascading strategy is now the canonical reference. + +### Agent Name Extraction: 3-Tier Cascading Patterns (VOX) +**Date:** 2026-03-23 +**Issue:** #577 +**What:** Agent name extraction uses cascading pattern matching: (1) emoji + name + colon at start, (2) name + colon anywhere, (3) fuzzy word-boundary match. Fallback: show description text instead of generic hint. +**Why:** Coordinator formats agent names inconsistently. Single regex failed silently. Multi-tier approach catches all known formats and degrades gracefully. +**Impact:** Coordinator's task description format changes should target these three patterns. New patterns added to `agent-name-parser.ts` update the entire extraction system. + +### Spawn Templates: Mandatory `name` Parameter (Procedures) +**Date:** 2026-03-23 +**Issue:** #577 +**What:** All spawn templates in `.squad-templates/squad.agent.md` MUST include `name: "{name}"` parameter set to agent's lowercase cast name (e.g., `name: "eecom"`, `name: "fido"`). +**Why:** The `name` parameter generates human-readable agent IDs in Copilot CLI tasks panel. Without it, platform shows generic slugs like "general-purpose-task", making agent identity invisible to users. +**Impact:** Any new spawn template or template update must include `name` parameter. `.squad-templates/squad.agent.md` is canonical; all derived copies in agent charters are secondary. + 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. diff --git a/.squad/decisions/inbox/fido-agent-name-tests.md b/.squad/decisions/inbox/fido-agent-name-tests.md deleted file mode 100644 index c001cc368..000000000 --- a/.squad/decisions/inbox/fido-agent-name-tests.md +++ /dev/null @@ -1,16 +0,0 @@ -# Decision: Extract agent name parsing into testable helper - -**Author:** FIDO -**Date:** 2025-07-25 -**Issue:** #577 - -## Context -The agent name extraction logic was inline in `shell/index.ts` (lines 680-694), making it impossible to unit test. The regex was fragile and breaking when description formats changed. - -## Decision -Extracted the matching logic into `packages/squad-cli/src/cli/shell/agent-name-parser.ts` as a pure function `parseAgentFromDescription(description, knownAgentNames)`. The shell index now imports and delegates to this function. - -## Implications -- VOX's regex robustness fix should be applied to `agent-name-parser.ts` rather than inline in `index.ts` -- New package export added: `@bradygaster/squad-cli/shell/agent-name-parser` -- 30 tests in `test/agent-name-extraction.test.ts` serve as regression guard for any future changes to the matching logic diff --git a/.squad/decisions/inbox/procedures-spawn-name.md b/.squad/decisions/inbox/procedures-spawn-name.md deleted file mode 100644 index 35cd13e28..000000000 --- a/.squad/decisions/inbox/procedures-spawn-name.md +++ /dev/null @@ -1,17 +0,0 @@ -# Decision: Spawn templates must include `name` parameter - -**Date:** 2025-07 -**Author:** Procedures -**Issue:** #577 - -## Decision - -Every `task` tool spawn MUST include the `name` parameter set to the agent's lowercase cast name (e.g., `name: "eecom"`, `name: "fido"`, `name: "scribe"`). - -## Rationale - -The `name` parameter generates the human-readable agent ID displayed in the Copilot CLI tasks panel. Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name, making it impossible for users to identify which agent is working. - -## Scope - -All spawn templates in `squad.agent.md` β€” Lightweight, Main, Model-passing, and Scribe templates. Applies to any future spawn templates added to the system. diff --git a/.squad/decisions/inbox/vox-agent-name-extraction.md b/.squad/decisions/inbox/vox-agent-name-extraction.md deleted file mode 100644 index 940d0e481..000000000 --- a/.squad/decisions/inbox/vox-agent-name-extraction.md +++ /dev/null @@ -1,22 +0,0 @@ -# Decision: Agent name extraction uses dedicated parser module - -**Author:** VOX -**Date:** 2025-07-25 -**Issue:** #577 - -## Context - -The shell's agent name extraction was a single fragile regex inline in `index.ts`. When the coordinator LLM formatted descriptions differently, names silently fell through to generic hints. - -## Decision - -Agent name extraction now lives in `agent-name-parser.ts` with 3 cascading strategies: -1. Emoji + name + colon at start of string -2. Name + colon anywhere in string -3. Fuzzy word-boundary match against known agent names - -When all strategies fail, the shell shows the trimmed description text instead of a generic tool hint. - -## Impact - -Any future changes to how coordinator formats task descriptions should update the patterns in `agent-name-parser.ts`, not `index.ts`.