From f4e7dadc2b5d5cd4e14097fe937880c6665c1d12 Mon Sep 17 00:00:00 2001 From: Ben Dang Date: Wed, 29 Apr 2026 16:06:22 -0700 Subject: [PATCH] chore: remove tracked runtime .squad/ state files Remove agent history.md files, session logs, orchestration logs, inbox decisions, identity runtime files, and temp commit artifacts from git tracking. These are machine-local runtime state that should never have been committed. PR #44 added CI enforcement (squad-main-guard.yml) to block future leaks. This commit removes the existing tracked files and hardens .gitignore to cover the remaining gaps. Files untracked (not deleted): - .squad/**/history.md (agent personal memory) - .squad/log/ (session logs) - .squad/orchestration-log/ (agent run logs) - .squad/sessions/ (session state) - .squad/decisions/inbox/ (pending inbox files) - .squad/identity/now.md + runtime PRD/SDK files - .squad/commit-message.txt, commit-msg.txt Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .gitignore | 13 +- .squad/agents/_alumni/kobayashi/history.md | 456 ----------- .squad/agents/booster/history.md | 158 ---- .squad/agents/capcom/history.md | 69 -- .squad/agents/control/history.md | 53 -- .squad/agents/eecom/history.md | 319 -------- .squad/agents/fido/history.md | 225 ------ .squad/agents/flight/history.md | 187 ----- .squad/agents/gnc/history.md | 25 - .squad/agents/handbook/history.md | 16 - .squad/agents/inco/history.md | 16 - .squad/agents/network/history.md | 22 - .squad/agents/pao/history.md | 287 ------- .squad/agents/procedures/history.md | 216 ------ .squad/agents/ralph/history.md | 16 - .squad/agents/retro/history.md | 16 - .squad/agents/scribe/history.md | 4 - .squad/agents/surgeon/history.md | 137 ---- .squad/agents/vox/history.md | 26 - .squad/commit-message.txt | 17 - .squad/commit-msg.txt | 8 - .../inbox/booster-ci-deletion-guard.md | 4 - .../inbox/booster-release-skill-v094.md | 35 - .../inbox/flight-versioning-policy.md | 32 - .../inbox/retro-copilot-git-safety.md | 4 - .squad/history.md | 10 - .squad/identity/now.md | 129 ---- .squad/identity/prd-consult-mode.md | 289 ------- .squad/identity/prd-next-waves.md | 85 -- .squad/identity/prd-sdk-init-shoreup.md | 203 ----- .../sdk-init-implementation-roadmap.md | 727 ------------------ .../identity/sdk-init-technical-analysis.md | 634 --------------- .squad/identity/sdk-init-umbrella-issue.md | 44 -- .squad/log/2026-03-25T18-11-work-session.md | 176 ----- .../log/2026-03-26T17-09-631-investigation.md | 37 - ...2026-03-27T21-42-00Z-decisions-archival.md | 48 -- .../2026-03-25T18-11-CAPCOM.md | 41 - .../2026-03-25T18-11-EECOM.md | 24 - .../2026-03-25T18-11-Flight.md | 24 - .../orchestration-log/2026-03-25T18-11-GNC.md | 61 -- .../orchestration-log/2026-03-25T18-11-PAO.md | 19 - .../2026-03-25T18-11-Procedures.md | 31 - .../2026-03-26T17-09-investigation-631.md | 39 - ..._fdc8d707-7d36-4b23-abd9-80b6558f7673.json | 12 - ..._e90fb146-17b4-4d72-a4c5-933ea5946b3f.json | 6 - 45 files changed, 11 insertions(+), 4989 deletions(-) delete mode 100644 .squad/agents/_alumni/kobayashi/history.md delete mode 100644 .squad/agents/booster/history.md delete mode 100644 .squad/agents/capcom/history.md delete mode 100644 .squad/agents/control/history.md delete mode 100644 .squad/agents/eecom/history.md delete mode 100644 .squad/agents/fido/history.md delete mode 100644 .squad/agents/flight/history.md delete mode 100644 .squad/agents/gnc/history.md delete mode 100644 .squad/agents/handbook/history.md delete mode 100644 .squad/agents/inco/history.md delete mode 100644 .squad/agents/network/history.md delete mode 100644 .squad/agents/pao/history.md delete mode 100644 .squad/agents/procedures/history.md delete mode 100644 .squad/agents/ralph/history.md delete mode 100644 .squad/agents/retro/history.md delete mode 100644 .squad/agents/scribe/history.md delete mode 100644 .squad/agents/surgeon/history.md delete mode 100644 .squad/agents/vox/history.md delete mode 100644 .squad/commit-message.txt delete mode 100644 .squad/commit-msg.txt delete mode 100644 .squad/decisions/inbox/booster-ci-deletion-guard.md delete mode 100644 .squad/decisions/inbox/booster-release-skill-v094.md delete mode 100644 .squad/decisions/inbox/flight-versioning-policy.md delete mode 100644 .squad/decisions/inbox/retro-copilot-git-safety.md delete mode 100644 .squad/history.md delete mode 100644 .squad/identity/now.md delete mode 100644 .squad/identity/prd-consult-mode.md delete mode 100644 .squad/identity/prd-next-waves.md delete mode 100644 .squad/identity/prd-sdk-init-shoreup.md delete mode 100644 .squad/identity/sdk-init-implementation-roadmap.md delete mode 100644 .squad/identity/sdk-init-technical-analysis.md delete mode 100644 .squad/identity/sdk-init-umbrella-issue.md delete mode 100644 .squad/log/2026-03-25T18-11-work-session.md delete mode 100644 .squad/log/2026-03-26T17-09-631-investigation.md delete mode 100644 .squad/log/2026-03-27T21-42-00Z-decisions-archival.md delete mode 100644 .squad/orchestration-log/2026-03-25T18-11-CAPCOM.md delete mode 100644 .squad/orchestration-log/2026-03-25T18-11-EECOM.md delete mode 100644 .squad/orchestration-log/2026-03-25T18-11-Flight.md delete mode 100644 .squad/orchestration-log/2026-03-25T18-11-GNC.md delete mode 100644 .squad/orchestration-log/2026-03-25T18-11-PAO.md delete mode 100644 .squad/orchestration-log/2026-03-25T18-11-Procedures.md delete mode 100644 .squad/orchestration-log/2026-03-26T17-09-investigation-631.md delete mode 100644 .squad/sessions/2026-03-01T20-12-48Z_fdc8d707-7d36-4b23-abd9-80b6558f7673.json delete mode 100644 .squad/sessions/2026-03-04T16-20-51Z_e90fb146-17b4-4d72-a4c5-933ea5946b3f.json diff --git a/.gitignore b/.gitignore index 0eeb162c3..bc288a3a3 100644 --- a/.gitignore +++ b/.gitignore @@ -23,7 +23,16 @@ docs/tests/screenshots/ # Squad: SubSquad activation file (local to this machine) .squad-workstream .squad/.first-run -.squad/.watch-pids +.squad/.watch-pids + +# Squad: agent runtime memory (personal to each machine/session) +.squad/**/history.md +.squad/history.md +.squad/identity/now.md +.squad/identity/prd-*.md +.squad/identity/sdk-init-*.md +.squad/commit-message.txt +.squad/commit-msg.txt # Images folder (root only β€” don't ignore docs/public/images/) -/images/ +/images/ diff --git a/.squad/agents/_alumni/kobayashi/history.md b/.squad/agents/_alumni/kobayashi/history.md deleted file mode 100644 index 05db85c8c..000000000 --- a/.squad/agents/_alumni/kobayashi/history.md +++ /dev/null @@ -1,456 +0,0 @@ -πŸ“Œ Team update (2026-03-07T20-04-20Z): GitHub Actions npm publishing automation established. New publish.yml workflow triggers on GitHub Release creation. NPM_TOKEN secret required in repo settings. CI/CD publishing is now authoritative method; local npm publish deprecated. β€” coordinated by Scribe - -πŸ“Œ Team update (2026-03-07T16:25:00Z): Actions β†’ CLI migration strategy finalized. 4-agent consensus: migrate 5 squad-specific workflows (12 min/mo) to CLI commands. Keep 9 CI/release workflows (215 min/mo, load-bearing). Zero-risk migration. v0.8.22 quick wins identified: squad labels sync + squad labels enforce. Phased rollout: v0.8.22 (deprecation + CLI) β†’ v0.9.0 (remove workflows) β†’ v0.9.x (opt-in automation). Brady's portability insight captured: CLI-first means Squad runs anywhere (containers, Codespaces). Customer communication strategy: "Zero surprise automation" as competitive differentiator. Decisions merged. β€” coordinated by Scribe - -# Project Context - -- **Owner:** Brady -- **Project:** squad-sdk β€” the programmable multi-agent runtime for GitHub Copilot (v1 replatform) -- **Stack:** TypeScript (strict mode, ESM-only), Node.js β‰₯20, @github/copilot-sdk, Vitest, esbuild -- **Created:** 2026-02-21 - -## Core Context β€” Kobayashi's Focus Areas - -**Release & Merge Coordinator:** Kobayashi owns PR merge strategy, release versioning, branch infrastructure, orphaned PR detection, cross-branch synchronization. Specialized in conflict resolution, rebase strategy, merge-driver constraints. - -**Pre-Phase-1 Foundations (2026-02-21 to 2026-03-04):** -- Established @changesets/cli for monorepo versioning (Issue #208) -- Insider channel publish scaffolds (Issue #215) -- Version model clarification: npm vs Public Repo separation -- Migration strategy for squad-pr (public) β†’ squad (beta): v0.8.17 target -- PR #582 merge (Consult mode) to migration branch -- Branch infrastructure: 3-branch model (main/dev/migration) implemented -- Versioning progression: 0.7.0 stubs β†’ 0.8.0–0.8.5.1 production releases -- Key Learning: Worktree parallelism, .squad/ state safety via merge=union, multi-repo coordination patterns - -**Pre-Phase-1 PR Merges & Releases (2026-02-22 to 2026-03-05):** -- Released v0.8.2, v0.8.3, v0.8.4, v0.8.5, v0.8.5.1 (incremental bug fixes) -- Released v0.8.19: Nap & Doctor commands, template path fix (PR #185 merged, @williamhallatt) -- Closed public repo issues #175 & #182: Verified superseding v1 implementations, credited @KalebCole and @uvirk -- CI/CD readiness assessment complete -- Branch cleanup and dev branch setup -- Comprehensive remote branch audit -- Merge workflows: devβ†’mainβ†’dev cycles - -## Learnings - -### Release v0.8.21 β€” GitHub Release Published, NPM Publish Still Blocked (2026-03-07T20:30:00Z) - -**ROOT CAUSE IDENTIFIED & RELEASE PUBLISHED.** GitHub Release was still in DRAFT status - this prevented the `release.published` event from triggering the npm publish workflow. Release is now published, but npm publish still blocked on NPM_TOKEN 2FA requirement. - -#### Execution Summary -- **βœ… Merge strategy:** Local merge (git checkout main && git merge origin/dev) with conflict resolution -- **βœ… Conflicts resolved:** 5 files (cli-entry.ts, package.json files, test files) β€” used `git checkout --theirs` strategy -- **βœ… Push success:** Main branch updated (commit 59b0c7a) -- **βœ… Lock file sync:** Fixed package-lock.json sync issue (commit 543bc1a) -- **βœ… Build script fix:** Added CI env check to skip version bump during publish (commit 344bb2b) -- **βœ… Tag verified:** v0.8.21 points to bf86a32 on main branch (correct) -- **βœ… Release published:** Changed from draft to published (2026-03-07T20:30:14Z) -- **βœ… Workflow triggered:** publish.yml workflow run #22806664280 triggered by release.published event -- **❌ NPM Publish blocked:** Workflow requires 2FA/OTP; NPM_TOKEN needs to be automation token (error code EOTP) - -#### NPM Publishing Blocker β€” Action Required -**CRITICAL:** NPM_TOKEN secret is a user token with 2FA enabled. Automated publishing requires an **automation token** or **granular access token** with 2FA bypass. - -**Resolution path:** -1. Go to https://www.npmjs.com/settings/bradygaster/tokens -2. Create a new **Automation Token** (classic) or **Granular Access Token** with publish permissions -3. Update the `NPM_TOKEN` secret in repo settings with the new token -4. Workflow will automatically retry on next push, OR manually trigger: `gh workflow run publish.yml --ref v0.8.21` - -**Workflow runs attempted:** 5 (all failed at npm publish step with EOTP error) -- Run 1-3: Previous attempts with package-lock and version issues (fixed) -- Run 4-5: Manual dispatch attempts (2FA/OTP required) -- Run #22806664280: Triggered by release.published event (2FA/OTP required) - -**Error message:** -``` -npm error code EOTP -npm error This operation requires a one-time password from your authenticator. -``` - -#### Post-Publish Prep Complete -βœ… Version bumped on dev to 0.8.22-preview.1 (commit 9473fa1) - -#### Key Learnings -1. **Conflict resolution for release merges:** Use `git checkout --theirs` on all conflicts when merging dev β†’ main for release -2. **Workflow dispatch inputs:** Always check workflow file for required inputs; publish.yml needs explicit version string -3. **Protected branch constraints:** Rebase strategies fail on force-push-protected branches; use merge + conflict resolution -4. **Post-release discipline:** Immediately bump dev to next preview version after triggering publish (prevents version collisions) -5. **CI build scripts:** Disable local dev tooling (version bumps, etc.) in CI with env checks (`process.env.CI === 'true'`) -6. **NPM automation tokens:** User tokens with 2FA enabled CANNOT be used for CI/CD; must use automation tokens or granular access tokens -7. **GitHub Release draft status:** Draft releases do NOT trigger `release.published` event - must explicitly publish the release for automation to trigger - -#### Release Sequence Validation -βœ… Pre-release version: 0.8.21-preview.X -βœ… Publish version: 0.8.21 (tagged, released on GitHub) -βœ… GitHub Release: Published (2026-03-07T20:30:14Z) β€” was draft, now published -βœ… Publish workflow: Triggered successfully (run #22806664280) -⏸️ NPM publish: BLOCKED (awaiting automation token configuration) -βœ… Post-publish dev bump: 0.8.22-preview.1 - -### Release v0.8.21 β€” Dev β†’ Main Merge & NPM Publish Trigger (Initial Log) - -**RELEASE GATE MERGE EXECUTED.** Dev branch merged to main, publish workflow triggered successfully. - -#### Execution Summary -- **Merge strategy:** Local merge (git checkout main && git merge origin/dev) attempted with --no-edit -- **Conflicts encountered:** 5 files with conflicts during merge (cli-entry.ts, package.json files, test files) -- **Resolution:** Used `git checkout --theirs` strategy to accept dev branch state for all conflicts -- **Push success:** Main branch updated successfully (commit 59b0c7a) -- **Workflow trigger:** `gh workflow run publish.yml --ref main -f version=0.8.21` executed successfully -- **Post-publish:** Version bumped on dev to 0.8.22-preview.1 across all 3 package.json files (commit 9473fa1) - -#### Technical Execution Details -- **Initial blocker:** Stash required due to uncommitted changes (.squad/agents/rabin/history.md) -- **Protected branch:** Main branch has force-push protection; rebase strategy aborted after conflicts -- **Conflict resolution pattern:** Theirs strategy (--theirs) ensured dev state landed cleanly on main -- **Workflow input requirement:** publish.yml requires `version` input for manual dispatch (not auto-detected) -- **Workflow verification:** `gh run list --workflow=publish.yml` confirmed workflow started successfully - -#### Key Learnings -1. **Conflict resolution for release merges:** When merging dev β†’ main for release, use `git checkout --theirs` on all conflicts to ensure dev state is authoritative -2. **Workflow dispatch inputs:** Always check workflow file for required inputs; publish.yml needs explicit version string -3. **Protected branch constraints:** Rebase strategies fail on force-push-protected branches; use merge + conflict resolution -4. **Post-release discipline:** Immediately bump dev to next preview version after triggering publish (prevents version collisions) -5. **Stash management:** Always check for uncommitted changes before release operations; stash + restore after - -#### Release Sequence Validation -βœ… Pre-release version: 0.8.21-preview.X -βœ… Publish version: 0.8.21 (tagged, released) -βœ… Post-publish dev bump: 0.8.22-preview.1 -Release versioning sequence followed correctly. - ---- - -### 2026-03-05: v0.8.21 Release PR Merge β€” 3 of 4 Successfully Merged (COMPLETE) -**Status:** βœ… COMPLETE. 3 PRs merged into dev; 1 blocked (branch deleted). - -#### Summary -Merged 3 critical PRs for v0.8.21 release into dev branch: -1. βœ… PR #204 (1 file, OpenTelemetry dependency fix) β€” MERGED -2. βœ… PR #203 (17 files, workflow install optimization) β€” MERGED -3. βœ… PR #198 (13 files, consult mode CLI + squad resolution) β€” MERGED -4. ❌ PR #189 (26 files, Squad Workstreams feature) β€” BLOCKED: source branch feature/squad-streams deleted from origin - -#### Technical Execution -- **Base branch correction:** PRs #204, #198, #189 targeting main instead of dev. Attempted gh pr edit --base dev but failed silently (GraphQL deprecation). -- **Merge strategy:** Used --admin flag to override branch protection. Initial merge of #204/#198 went to main instead of dev. -- **Correction strategy:** Cherry-picked merge commits (git cherry-pick -m 1 {commit}) from main to dev, verified correct branch landing. -- **Final dev state:** All three PRs on dev; PR #189 remains orphaned pending branch recreation. - -#### Key Learning -1. Add pre-merge verification: git ls-remote origin before attempting merge -2. When --admin overrides base policy, verify landing branch; cherry-pick if needed -3. Merge commits require -m 1 parent selection during cherry-pick - -### Worktree Parallelism & Multi-Repo Coordination - -- **Worktrees for parallel issues:** git worktree add for isolated working directories sharing .git object store -- **.squad/ state safety:** merge=union strategy handles concurrent appends; append-only rule -- **Cleanup discipline:** git worktree remove + git worktree prune after merge -- **Multi-repo:** Separate sibling clones, not worktrees. Link PRs in descriptions. -- **Local linking:** npm link, go replace, pip install -e . always removed before commit -- **Decision rule:** Single issue β†’ standard workflow. 2+ simultaneous β†’ worktrees. Different repos β†’ separate clones. - -### 2026-03-06: Docs Sync β€” Migration Branch to Main (COMPLETE) -Cherry-picked docs commits from migration β†’ main. Feature docs synced, broken links fixed, migration guide updated with file-safety table. - -### 2026-03-07: Closed Public Repo Issues #175 & PR #182 β€” Documented Superseding Implementations (COMPLETE) -Verified squad doctor and squad copilot implementations in v1 codebase. Posted detailed comments explaining v0.8.18+ shipped features, cited specific files and versions, thanked community contributors (@KalebCole, @uvirk). Closed both with appreciation for validating architecture. - -### 2026-03-07: Release v0.8.19 β€” Nap & Doctor Commands, Template Path Fix (COMPLETE) -Released v0.8.19: squad nap command restored + squad doctor wired into CLI. PR #185 (template path fix), PR #178 (GitLab docs). Post-release version bump committed. - -## πŸ“Œ Phase 2 Sequential PR Merges β€” 2026-03-07T01-13-00Z - -**PHASE 2 INTERNAL PR MERGES COMPLETE.** Brady requested merge of 2 internal fix PRs into dev. Both merged successfully. - -- PR #232: Scribe runtime state fix β€” merged cleanly (86598f4e) -- PR #212: Version stamp preservation β€” required rebase (base changed after #232), conflict resolved, merged cleanly (0fedcce) - -**Zero state corruption.** All operations within merge-driver constraints. Sequential merges may require rebase of later PRs when base changes materially. Rebase drops indicate upstream fix β€” safe to proceed. - -**Team Status:** All 5 Phase 2 ready PRs now merged to dev (internal + community). Test validation in progress (Hockney). - -## πŸ“Œ Phase 4 Sequential PR Merges β€” 2026-03-07T01-50-00Z - -**PHASE 4 INTERNAL PR MERGES COMPLETE.** Brady requested merge of 2 critical fix PRs into dev, confirmed green by Fenster and Hockney. - -### Merge Summary -- βœ… PR #235 (Hockney's test fixes): Merged successfully (commit ce418c6) - - Resolved all 16 pre-existing test failures across 4 modules - - Test suite now 3656 passing, 0 failures (134 test files) -- βœ… PR #234 (Fenster's runtime bug fixes): Merged successfully (commit f88bf4c) - - Fixed 4 runtime issues: #214, #207, #206, #193 - - Key fixes: sqlite module detection, path resolution from subdirs, terminal flicker, ceremonies file size threshold - -### Issues Closed -All 4 issues resolved by PR #234 closed with comment "Fixed by PR #234 (merged to dev).": -- #214: node:sqlite builtin module error β†’ Added pre-flight check + upgrade guidance -- #207: Squad not found from non-root directory β†’ Fixed path resolution in nap + consult -- #206: Terminal blink/flicker β†’ Reduced animation timers, removed scrollback clear -- #193: Ceremonies file size threshold β†’ Added compact dispatch table + individual skill files - -**State Integrity:** Zero conflicts, clean merges, all .squad/ state preserved (merge=union enforced). - -**Key Learning:** Sequential merges with confirmed green statuses from peer reviewers eliminate merge conflicts and enable confident pipeline progression. All 7 Phase 2–4 PR merges (5 Phase 2 + 2 Phase 4) completed without intervention. - -## πŸ“Œ Release v0.8.21 β€” Version Bump & Tag (COMPLETE) - -**RELEASE SHIPPED: npm packages and GitHub Release published.** - -### Execution Summary -- **Pre-flight:** Verified clean working tree, recent commits, successful build -- **Version bump:** Converted preview.16 β†’ preview.18 (build script) β†’ 0.8.21 (release) -- **Consistency:** All three package.json files (root, squad-cli, squad-sdk) synchronized to 0.8.21 -- **Git operations:** Commit, tag, push to dev branch completed successfully -- **GitHub Release:** Created with full CHANGELOG.md; visible at https://github.com/bradygaster/squad/releases/tag/v0.8.21 -- **Deliverable:** v0.8.21 ready for npm publish by Rabin - -### Key Technical Points -- Build pre-script runs on every build; tracked versions as preview.18 (irrelevant to release, stripped) -- Release commit at `7554e08`, tag correctly placed on this commit -- CHANGELOG validated through 0.8.21 (includes SDK-First, Remote Mode, critical crash fixes, new commands, Windows fixes) -- 26 issues closed, 16 PRs merged in this release -- No state corruption; clean pre-flight, clean merge - -### Readiness for npm Publishing -Rabin will publish @bradygaster/squad-cli and @bradygaster/squad-sdk to npm from this tag. - ---- - -## πŸ“Œ CI/CD Architecture Assessment β€” 2026-03-15T15-30-00Z - -**ASSESSMENT COMPLETE: GitHub Actions vs. CLI Migration Analysis** - -Brady requested evaluation of reducing Actions usage by migrating automation to Squad CLI. Comprehensive architectural review completed. - -### Key Findings - -**1. Actions Minutes Analysis:** -- ~227 minutes/month total consumption (well under 3,000-min free tier) -- 9 CI/Release workflows: 215 min/month (MUST STAY β€” event-driven guardrails) -- 5 Squad-specific workflows: 12 min/month (MIGRATION CANDIDATES) -- **Cost is negligible β€” maintainability is the real constraint** - -**2. Load-Bearing Infrastructure (Cannot Move):** -- `squad-ci.yml` β€” PR/push event gate (feeds branch protection) -- `squad-main-guard.yml` β€” Forbidden file enforcement (prevents state corruption) -- `squad-release.yml` β€” Automatic tag creation (triggers downstream pipeline) -- `squad-promote.yml` β€” Branch promotion (complex git orchestration) -- `squad-publish.yml` β€” npm distribution (final delivery gate) -- `squad-preview.yml` β€” Pre-release validation (checkpoint before main merge) -- `squad-docs.yml` β€” GitHub Pages deployment -- `squad-insider-release.yml` & `squad-insider-publish.yml` β€” Pre-release channel - -**Why 9 workflows must stay:** -- Event-driven guarantees (GitHub Actions provides atomic, immutable event execution) -- Branch protection integration (cannot replicate CLI-side) -- Authorization & token management (centralized via Actions) -- Cannot react to remote events (tag push, PR events) from CLI - -**3. Migration Candidates (5 workflows, ~12 min/month):** -- `sync-squad-labels.yml` β†’ `squad sync-labels` CLI command -- `squad-triage.yml` β†’ `squad triage` CLI command + Ralph monitor -- `squad-issue-assign.yml` β†’ `squad assign` CLI command -- `squad-heartbeat.yml` β†’ Ralph work monitor loop (already implemented) -- `squad-label-enforce.yml` β†’ `squad validate-labels` CLI command - -**Risks: LOW** β€” None modify protected state, all are idempotent, can be corrected manually if issues arise. - -**4. Squad Init Impact:** -- Current: Installs all 15 workflows -- Recommended: Keep all, mark squad-specific as "opt-in" via config flag -- Backward compatible: Existing repos' workflows persist -- New repos: Receive streamlined workflow set with optional automation -- Migration path: `squad upgrade --remove-deprecated-workflows` for cleanup - -**5. Backward Compatibility Strategy:** -- **Phase 1 (v0.9):** Document migration path; no code changes -- **Phase 2 (v1.0):** Implement CLI commands (`squad triage`, `squad assign`, etc.) -- **Phase 3 (v1.0):** Add deprecation warnings to old workflows -- **Phase 4 (v1.1):** Provide `squad upgrade --remove-deprecated` flag -- **Phase 5 (v1.1):** Remove deprecated workflows from new init only - -### Recommendations - -1. **Keep 9 critical workflows as Actions** β€” cost is negligible, but guarantees are essential -2. **Migrate 5 squad-specific workflows to CLI** β€” improves team autonomy, reduces maintenance -3. **Implement lazy automation** β€” Add `automation` config to .squad/config.json (CI + Release always on, Squad-specific opt-in) -4. **Document in decisions/** β€” Full assessment saved to `.squad/decisions/inbox/kobayashi-ci-impact.md` - -### State Integrity Conclusion - -**Zero risk of state corruption from migration:** -- Migrated workflows (triage, labels) are idempotent (can be re-run without side effects) -- Critical workflows (release, main-guard) remain as Actions (unchanged) -- Backward compatibility guaranteed (old workflows persist, don't interfere) -- Deprecation path is gradual (1+ release cycles notice) - -**Timeline:** Can proceed with CLI command implementation immediately (v1.0 target); old workflows coexist during transition. - -### 2026-03-16: npm Publish Automation via GitHub Actions (COMPLETE) - -**AUTOMATION IMPLEMENTED: npm publishing now handled by GitHub Actions.** - -Brady requested automated npm publishing instead of manual local publishes. Assessment complete, workflow consolidated. - -#### Changes Made - -1. **Updated `publish.yml` workflow:** - - Trigger on `release.published` event (automatic when GitHub Release created) - - Added manual `workflow_dispatch` trigger for ad-hoc publishes - - Publishes SDK first, then CLI (correct dependency order) - - Added version verification (ensures package.json matches release tag) - - Added npm publication verification (confirms packages published successfully) - - Uses `NPM_TOKEN` secret for authentication - - Includes npm provenance attestation for supply chain security - -2. **Deprecated `squad-publish.yml`:** - - Renamed to `.deprecated` (old workflow had redundant functionality) - - All logic consolidated into single `publish.yml` workflow - -3. **Separation of concerns:** - - `squad-release.yml` β€” Creates GitHub Release + tag (triggered on main branch merge) - - `publish.yml` β€” Publishes to npm (triggered by GitHub Release) - - Clean event chain: Merge β†’ Release β†’ Publish - -#### Architecture - -**Event Flow:** -1. Brady merges to `main` (via `squad-promote.yml` or direct merge) -2. `squad-release.yml` triggers on `push` to `main` -3. Creates tag + GitHub Release (if version bumped) -4. `publish.yml` triggers on `release.published` event -5. Publishes both packages to npm with provenance - -**Manual Override:** -- `publish.yml` supports `workflow_dispatch` for ad-hoc publishes -- Requires version input (e.g., "0.8.21") -- Useful for hotfixes or republishing - -#### Setup Required (Brady Action Items) - -**NPM_TOKEN Secret Setup:** -1. Go to https://www.npmjs.com/settings/{username}/tokens -2. Generate new **Automation** token (not Classic or Granular) -3. Go to GitHub repo β†’ Settings β†’ Secrets and variables β†’ Actions -4. Add secret: `NPM_TOKEN` = (paste token) - -**Verification:** -- Next release will automatically publish to npm when GitHub Release created -- Manual test: Run workflow_dispatch on `publish.yml` with version "0.8.21" - -#### State Integrity - -- Zero risk: npm publish is idempotent (can't republish same version) -- Version mismatch protection: Workflow verifies package.json matches release tag -- Publication verification: Workflow confirms packages visible on npm after publish -- Rollback strategy: Manual unpublish via `npm unpublish` if issues detected within 72 hours - -**Key Learning:** Automated npm publishing reduces human error (version mismatches, forgotten packages, incorrect tag) and provides audit trail via GitHub Actions logs. Provenance attestation strengthens supply chain security. - ---- - -## πŸ“Œ INCIDENT REPORT: v0.8.22 Release Failures (2026-03-XX) - -**STATUS:** Multiple critical failures. Brady furious. Documented for prevention. - -### Failures Committed - -**1. Invalid semver β€” 0.8.21.4 committed to main:** -- Used 4-part version number (0.8.21.4) instead of 3-part semver (0.8.22) -- npm does NOT support 4-part versions β€” it mangled to 0.8.2-1.4 -- Created git tag v0.8.21.4 for invalid version -- Committed to main branch without validation -- **ROOT CAUSE:** No semver validation before version changes. Assumed any version format was valid. - -**2. Draft release created instead of published:** -- Created GitHub Release in DRAFT state -- Draft releases do NOT trigger `release: published` webhook events -- Publish workflow (`publish.yml`) never fired because trigger condition not met -- **ROOT CAUSE:** Did not understand GitHub Release draft vs. published semantics. Draft releases are invisible to automation. - -**3. NPM_TOKEN type not validated:** -- Did not verify NPM_TOKEN secret was an automation token before publish attempt -- Token was a user token with 2FA enabled -- All publish attempts failed with EOTP error (one-time password required) -- **ROOT CAUSE:** No pre-publish token verification step. Assumed any NPM_TOKEN would work. - -**4. Required multiple corrections from Brady:** -- Brady had to intervene multiple times to fix invalid state -- Each correction revealed another unvalidated assumption -- Release process took hours instead of minutes -- **ROOT CAUSE:** No pre-flight checklist. Released under pressure without validation. - -### Lessons Learned β€” Hard Rules - -**1. Semver is ALWAYS 3-part for npm:** -- Valid: `X.Y.Z` (e.g., 0.8.22) -- Valid: `X.Y.Z-prerelease.N` (e.g., 0.8.22-preview.1) -- **INVALID:** `X.Y.Z.N` (4-part versions) β€” npm does not support this -- **Validation:** Use `npm version {version} --no-git-tag-version` to test before committing -- **Prevention:** Add semver validation to `publish.yml` pre-publish step - -**2. GitHub Release draft vs. published:** -- **DRAFT:** Release exists but is NOT visible. Does NOT trigger `release: published` event. -- **PUBLISHED:** Release is visible and triggers `release: published` webhook. -- **Automation requirement:** Workflows using `on: release: published` ONLY fire when release is published, NOT when draft is created. -- **Prevention:** Use `gh release create --draft=false` or explicitly publish with `gh release edit {tag} --draft=false` - -**3. NPM_TOKEN must be automation token:** -- **User tokens with 2FA:** Cannot be used in CI/CD β€” require interactive OTP -- **Automation tokens:** Bypass 2FA for CI/CD use (legacy, still supported) -- **Granular access tokens:** Modern alternative, no 2FA, scoped permissions -- **Verification:** Check token type at https://www.npmjs.com/settings/{user}/tokens before configuring CI -- **Prevention:** Document token type requirements in release runbook - -**4. Pre-flight checklist required for all releases:** -- [ ] Version is valid semver (3-part only)? -- [ ] Version matches across all package.json files (root, squad-cli, squad-sdk)? -- [ ] NPM_TOKEN is automation token (not user with 2FA)? -- [ ] GitHub Release will be published (not draft)? -- [ ] Workflow trigger conditions will be met? -- **Prevention:** Add pre-publish validation step to `publish.yml` - -### State Corruption - -**git state:** -- Invalid tag v0.8.21.4 created on main branch -- Invalid version 0.8.21.4 committed to package.json files -- **Recovery:** Tag and commit must be removed/reverted; correct version committed - -**npm state:** -- No packages published under invalid version (npm rejected 0.8.2-1.4) -- **Recovery:** No npm cleanup needed - -**GitHub state:** -- Draft release may still exist for v0.8.21.4 -- **Recovery:** Delete draft release if present - -### Prevention β€” New Guardrails - -**Proposed in decision:** `.squad/decisions/inbox/kobayashi-release-guardrails.md` - -1. **Pre-publish semver validation:** - - Add validation step in `publish.yml` that verifies version format before npm publish - - Script validates: (1) 3-part format, (2) matches semver spec, (3) not already published - -2. **GitHub Release creation verification:** - - Enforce `--draft=false` flag in release creation - - Add workflow check that verifies release is published before proceeding to npm publish - -3. **NPM_TOKEN type verification:** - - Document token requirements in README - - Add workflow step that tests token validity before publish (dry-run) - - Add token type check to pre-publish validation - -4. **Release runbook:** - - Document complete release process with pre-flight checklist - - Include rollback procedures for each failure mode - - Store in `.squad/skills/release-process/SKILL.md` - -### Accountability - -**This was my failure.** I rushed the release, skipped validation, and created invalid state. Brady had to fix my mistakes. These guardrails make this failure mode impossible to repeat. diff --git a/.squad/agents/booster/history.md b/.squad/agents/booster/history.md deleted file mode 100644 index 373e2c767..000000000 --- a/.squad/agents/booster/history.md +++ /dev/null @@ -1,158 +0,0 @@ -# BOOSTER - -> Booster Systems Engineer - -## 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). - -### Known CI Patterns -SKIP_BUILD_BUMP=1 environment variable intended to prevent version mutation during CI builds. Currently unreliable β€” bump-build.mjs ignores it in some code paths. NPM_TOKEN must be Automation type (not user token with 2FA) to avoid EOTP errors in publish workflow. - -### Workflow Inventory -9 load-bearing workflows (215 min/month) must stay as GitHub Actions. 5 migration candidates (12 min/month) could move to CLI: sync-labels, triage, assign, heartbeat, validate-labels. - -### Container Smoke Test Patterns -`npm pack` generates tarballs installable in clean containers for pre-publish validation. GitHub Actions containers (node:20-slim, node:22) suitable for smoke tests. No devcontainer config exists yet. Current CI budget: ~227 min/month. Container smoke test adds ~2-5 min per run. Tier 1 smoke test commands: `--version`, `--help`, `doctor`, `status`, `export`. CLI has 31 commands; 15 are user-facing smoke test candidates. cli-command-wiring.test.ts catches unwired commands at build time (issues #224, #236, #237). - -### Smoke Test Gating in Publish Pipeline -Smoke tests now run as a dedicated `smoke-test` job in publish.yml before any npm publish operations. Both publish-sdk and publish-cli jobs depend on smoke-test passing. Prevents publishing broken CLI packages to npm. Smoke test runs `npx vitest run test/cli-packaging-smoke.test.ts` after a full build. Test takes ~30-60s for pack+install validation. - -### CI Pipeline Hardening β€” March 20, 2026 - -**Changes shipped in commit 6cbabb5 (dev branch):** - -1. **`edited` trigger added** β€” `pull_request` event types now include `edited`. Previously, retargeting a PR from `mainβ†’dev` would not refire CI because the base branch change uses the `edited` event type. Six PRs (#470, #469, #468, #467, #454, #451) were manually close/reopened to compensate. - -2. **Lockfile lint step added** β€” New step `Lint lockfile for stale workspace entries` runs before `npm ci` in the `test` job. Uses Node inline script to detect any `packages/*/node_modules/@bradygaster/squad-*` entries in `package-lock.json` that have an `https://` resolved URL (indicating a stale nested registry copy shadowing the workspace symlink). Exits with error code + remediation instructions if found. This catches the TypeScript type-mismatch class of failures at the lockfile level, not at build time. - -3. **Default branch changed to `dev`** β€” Repo default branch switched from `main` to `dev` via GitHub API. Community PRs now naturally target `dev`. - -**Pattern confirmed:** The `edited` event gap was the exact reason retargeted PRs were not getting CI runs. Any future PR base-branch change will now trigger a fresh CI run automatically. - -### CI Failure Pattern Analysis β€” March 15, 2026 -Analyzed 20 CI runs from March 15. Identified 3 distinct failure categories: - -**1. TypeScript Build Failures β€” SDK/CLI Type Mismatches (Most Critical)** -- 7+ consecutive failures on `squad/fix-ci-build` branch (14:00-14:11 UTC) -- Root cause: Stale nested SDK entry in package-lock.json causing TypeScript module resolution errors -- Error: "Module '@bradygaster/squad-sdk' has no exported member 'listRoles'" (and 6 other missing exports) -- Impact: Build failures blocked all PRs attempting to fix roles/cast features -- Fix: Removing stale lockfile entry resolved TypeScript resolution -- Pattern: Workspace dependency mismatches not caught until CI build phase - -**2. Documentation Quality Gate Failures β€” New Validation Rules** -- 3 failures on `squad/docs-quality-ci` branch (14:32, 15:26, 15:51 UTC) -- Issue 1: Broken anchor link `../guide.md#troubleshooting` (anchor doesn't exist) -- Issue 2: Spell check failure for username "benleane" in notifications.md (not in cspell dictionary) -- Impact: New docs-quality job blocked merges when introducing new validation gates -- Pattern: Adding stricter CI gates without pre-validation of existing content creates immediate failures - -**3. Test Failures β€” ES Module Migration Side Effects (Legacy)** -- 1 failure on main branch (13:59 UTC) β€” "deleted images" commit -- Root cause: 8 test files using `require()` in ES module context -- Error: "require is not defined in ES module scope" (node:test imports) -- Impact: Old test files incompatible with `"type": "module"` in package.json -- Pattern: Incomplete ESM migration left test files in CommonJS syntax - -**Key Observations:** -- **Failure clusters**: Multiple consecutive failures trying to fix same root issue (TypeScript build: 7 attempts, docs-quality: 3 attempts) -- **Validation timing**: New validation gates (docs-quality CI) introduced without pre-testing against current codebase state -- **Workspace complexity**: Monorepo TypeScript workspace dependencies prone to lockfile staleness -- **Branch health**: dev branch had 2 failures (last failure: spell check), currently yellow/orange status - -**Recommended CI Improvements:** -1. Pre-merge lockfile validation check (detect stale nested dependencies) -2. Docs validation dry-run before adding new quality gates -3. TypeScript workspace reference health check (catch SDK/CLI type mismatches early) -4. Better failure grouping/attribution in CI UI (distinguish "new gate" vs "regression") -5. Spell check dictionary maintenance workflow (easier to add known-good usernames/terms) - -### CI Workflow Audit β€” March 23, 2026 - -**Status:** Conducted full audit of 15 workflow files. Brady's perception ("complete nightmare, 12,000 workflows") is not accurate β€” the codebase is lean, well-organized, and 99% authored by Brady (bradygaster + Copilot). - -**Key Findings:** -- **Total workflows:** 15 (7 load-bearing core, 7 admin/automation, 1 ghost) -- **Authorship:** bradygaster 46 commits (65%), Copilot 7 (10%), team 17 (24%) -- **v0.9.1 Scramble:** Copilot made 4 commits on 2026-03-23 trying to work around GitHub platform bug (workflow_dispatch returns 422 after file renames/deletes) -- **Ghost file identified:** `publish-npm.yml` (deleted but still in GitHub's workflow cache) β†’ requires manual deletion via API -- **Zero duplication:** Each workflow has clear, non-overlapping responsibility -- **One optional cleanup:** `ci-rerun.yml` (useful but not essential) - -**Release Pipeline Quality:** -- Core pipeline (squad-ci β†’ squad-release β†’ squad-npm-publish β†’ insider-*) is solid -- Smoke tests run before any npm publish (good safety gate) -- Implicit ordering works but fragile (squad-npm-publish depends on release: published event) - -**Triage Automation Quality:** -- Label routing (squad-triage, squad-issue-assign, squad-label-enforce) well-integrated -- Ralph heartbeat has cron disabled (event-driven only) -- Works correctly with @copilot assignment - -**Recommendation:** Delete ghost publish-npm.yml file, optionally keep ci-rerun for fork PR debugging, keep everything else. CI health is good. - -**Report written to:** `.squad/decisions/inbox/booster-ci-audit.md` - -### CI Cleanup & Hardening β€” Post-Audit - -**Changes shipped:** - -1. **Ghost workflow disabled** β€” `publish-npm.yml` (workflow ID 250121956) disabled via GitHub API (`PUT /actions/workflows/{id}/disable`). GitHub doesn't support DELETE on workflow entries; disable is the permanent fix. - -2. **Pre-publish `preflight` job added** to `squad-npm-publish.yml`: - - Scans ALL `packages/*/package.json` for `file:` references across all dependency sections (dependencies, devDependencies, optionalDependencies, peerDependencies) - - Validates all package versions are valid semver - - Runs BEFORE smoke-test and all publish jobs β€” blocks the entire pipeline if violations found - - This is the gate that would have caught the v0.9.1 incident - -3. **Smoke test enhanced** β€” Added `npm pack --dry-run` validation step for both SDK and CLI packages before the vitest smoke tests run - -4. **ci-rerun.yml retained** β€” Added purpose documentation comment. Still useful for fork PR re-testing and infrastructure flake recovery. - -5. **YAML fix** β€” Quoted `file:` in step names that were causing YAML parse ambiguity (both new and pre-existing) - -**Pipeline dependency chain:** `preflight β†’ smoke-test β†’ publish-sdk β†’ publish-cli` - -### Release Process Skill Update β€” v0.9.4 Learnings (2026-04-25) - -Updated both release-process skill files (`.squad/skills/release-process/SKILL.md` and `.copilot/skills/release-process/SKILL.md`) with critical learnings from the v0.9.4 release session. Added 5 new Known Gotchas, a full `v0.9.4 Incident Learnings` section, GITHUB_TOKEN propagation workaround, CHANGELOG/root-package.json validation rules, lockfile integrity fix documentation, local dev recovery steps, and cross-references between skill files. Source PRs: #1042, #1043, #1044. - -### CI Cleanup β€” Issue #1000 (2026-04-17) - -**Changes shipped in PR #1001:** - -1. **Deleted `ci-rerun.yml`** β€” Redundant fork PR workflow with 100% failure rate (5/5 runs). GitHub's native "Approve and Run" handles fork PR CI. Removed reference from `setup-squad-node` comment header. - -2. **Streamlined `squad-ci.yml`** β€” 852 β†’ 585 lines, 9 β†’ 6 jobs: - - **Merged** `exports-map-check` + `export-smoke-test` β†’ single `sdk-exports-validation` job (saves one runner boot, deduplicates checkout/setup/change-detection) - - **Folded** `publish-policy` + `scope-check` into `policy-gates` as additional gate steps (saves two runner boots) - - **Added** `workflows` output to `changes` path filter (policy-gates now properly skips on docs-only PRs) - - **Trimmed** verbose local-testing instruction comments and skip-labels reference block - - **Preserved** all genuine safety checks β€” no gates removed, only consolidated - -**Key decisions:** -- Merging exports-map-check + export-smoke-test is safe because they share identical prerequisites (SDK change detection, feature flags, skip labels) and both only need SDK build -- publish-policy (static grep of workflow files) fits naturally in policy-gates since it's a lightweight lint -- scope-check (label-gated) works inside policy-gates because the step has its own `if` condition for the `repo-health` label - -**Files modified:** -- `.github/workflows/ci-rerun.yml` (deleted) -- `.github/actions/setup-squad-node/action.yml` (comment update) -- `.github/workflows/squad-ci.yml` (streamlined) diff --git a/.squad/agents/capcom/history.md b/.squad/agents/capcom/history.md deleted file mode 100644 index e9c8aeabd..000000000 --- a/.squad/agents/capcom/history.md +++ /dev/null @@ -1,69 +0,0 @@ -# CAPCOM β€” History - -> Knowledge base for the SDK Expert. Append-only, union-merged across branches. - -## Learnings - -### 2026-03-14: WSL Transient API Error Investigation (Issue #363) - -**Context:** User reported "Request failed due to a transient API error" on Ubuntu WSL with Copilot CLI v1.0.4, eventually hitting rate limits. - -**Investigation findings:** -- Squad SDK already implements robust retry logic with exponential backoff (1s β†’ 2s β†’ 4s) -- Retry logic in `adapter/client.ts:820-880` handles transient connection errors (ECONNREFUSED, ECONNRESET, EPIPE) -- Rate limit detection in `adapter/errors.ts:229-245` with retry-after awareness -- Error originates **upstream** from Copilot CLI/API platform, not Squad -- Copilot CLI v1.0.4 internal retry behavior triggers the rate limiting before Squad is invoked -- Squad only interacts with CLI via `@github/copilot-sdk` adapter after CLI is already running - -**Key insight:** Squad SDK does NOT contribute to transient API errors or rate limiting issues. Our retry logic follows platform patterns and only applies to SDK connection errors, not upstream API instability. - -**Outcome:** -- Confirmed this is an upstream platform issue (not a Squad bug) -- Recommended user check network connectivity, WSL configuration, and GitHub auth -- Created decision in `.squad/decisions/inbox/capcom-wsl-transient.md` -- Suggested documentation improvement: add WSL troubleshooting guide - -**Pattern learned:** When investigating API errors, distinguish between: -1. **SDK adapter layer** (our retry logic) β€” handles connection errors only -2. **Copilot CLI layer** (upstream) β€” handles API communication and its own retries -3. **Copilot API platform** (upstream) β€” source of transient errors and rate limits - -Squad operates at layer #1, so issues at layers #2-3 are outside our control. -## Core Context - -- **Project:** Squad β€” AI agent orchestration framework -- **Role:** SDK Expert -- **Joined:** 2025-01-25 - -## Learnings - -### 2025-01-25: SDK Init Implementation Deep Dive - -Completed deep technical analysis of `squad init --sdk` code paths. Key findings: - -**CastingEngine is orphaned** β€” The SDK has a full universe-based casting system (`packages/squad-sdk/src/casting/casting-engine.ts`) with themed characters (The Usual Suspects, Ocean's Eleven), personality traits, backstories, and role-matching algorithms. **But no code calls it.** The CLI bypasses it with a hardcoded `personalityForRole()` function that generates generic personalities based on role patterns. - -**Config/team sync is one-way** β€” The REPL init flow generates team.md, routing.md, and registry.json when casting a team, but never updates squad.config.ts. Meanwhile, `squad init --sdk` generates squad.config.ts with only Scribe, missing Ralph and all other agents. The disconnect: CLI init writes a skeleton + prompt, REPL auto-cast generates the team, but the two paths never merge into a unified config. - -**Built-in agents are inconsistent** β€” Ralph is added by the REPL casting flow (`cli/core/cast.ts:385-386`) but not by SDK init (`cli/core/init.ts:109-115`). @copilot is a pseudo-agent β€” a Markdown table row inserted via `team-md.ts:insertCopilotSection()`, not a real agent with charter/history files. - -**Universe selection is a dead end** β€” The coordinator init prompt asks the LLM to pick a universe (line 52: "Pick a fictional universe for character names"), and the coordinator responds with `UNIVERSE: Alien`, which gets stored in `casting/history.json`... and then **nothing uses it**. There's no mapping from freeform universe names to CastingEngine templates. - -**The fix path is clear** β€” Three priority levels: -- **P0 (trivial):** Add Ralph to SDK init agents array, guide coordinator to existing CastingEngine universes -- **P1 (small/medium):** Integrate CastingEngine into CLI casting, make REPL init write squad.config.ts -- **P2 (design-heavy):** Decide config sync strategy (config-as-source vs. bidirectional), decide if @copilot should be a real agent - -Written full technical analysis to `.squad/identity/sdk-init-technical-analysis.md` with file/line references, complexity estimates, and actionable recommendations for Brady's PRD. - -**SDK patterns observed:** -- `defineSquad()` / `defineAgent()` builder pattern is clean and works well -- `configFormat` enum supports 'sdk' | 'typescript' | 'json' | 'markdown' β€” flexible but undertested -- Init flow is two-phase (CLI writes skeleton, REPL auto-casts) β€” intentional design but creates sync issues -- Template system in SDK (`templates/` directory) is well-structured, used correctly by `initSquad()` - -πŸ“Œ **Team update (2026-03-11T01:25:00Z):** 5 SDK Init decisions merged to decisions.md: Phase-based quality improvement (3-phase approach), CastingEngine canonical casting, squad.config.ts as source of truth, Ralph always-included, implementation priority order. Full technical analysis informed Flight's unified PRD and EECOM's roadmap. - -πŸ“Œ **Team update (2026-03-25T18:11Z):** CLI platform research complete β€” identified Copilot CLI 1.0.5–1.0.11 (8 releases in 10 days) contain three high-impact changes affecting Squad routing: monorepo instruction discovery (1.0.11), idle subagent hiding (1.0.8), subagentStart hook context injection (1.0.7). SDK version pinning doesn't prevent CLI runtime auto-updates. Recommendations: clean up template naming, upgrade to SDK 0.2.0 customize mode, file CLI issue. Report in decisions inbox. - diff --git a/.squad/agents/control/history.md b/.squad/agents/control/history.md deleted file mode 100644 index 80f920982..000000000 --- a/.squad/agents/control/history.md +++ /dev/null @@ -1,53 +0,0 @@ -# CONTROL - -> Control System Engineer - -## Learnings - -### Issue Triage (2026-03-22T06:44:01Z) - -**Flight triaged 6 unlabeled issues and filed 1 new issue.** - -CONTROL assigned: -- **#481 (StorageProvider PRD)** β†’ squad:control + squad:eecom (type system abstraction for runtime integration) - -Pattern: State abstraction gap identified. StorageProvider defines canonical interface for data persistence across team. - -πŸ“Œ **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. CONTROL owns StorageProvider PRD specification (#481). Type system design critical for EECOM runtime integration. Ready to begin specification work on next sprint. -# Control β€” History - -## Learnings - -### Model Registry Architecture -- `MODELS` constant in `packages/squad-sdk/src/runtime/constants.ts` is the single source of truth for default model names and fallback chains. `DEFAULT_CONFIG` in `runtime/config.ts` derives `defaultModel` from `MODELS.DEFAULT`. -- `MODEL_CATALOG` in `packages/squad-sdk/src/config/models.ts` is the authoritative model list used by `ModelRegistry`. `DEFAULT_FALLBACK_CHAINS` in the same file mirrors `MODELS.FALLBACK_CHAINS` β€” both must stay in sync. -- `model-selector.ts` hardcodes task-to-model mappings for `code`, `prompt`, `visual`, `docs`, `planning`, `mechanical` task types. These must be updated alongside `MODELS.FALLBACK_CHAINS` when defaults change. - -### Skill Templates Are Auto-Synced -- `npm run build` calls `scripts/sync-skill-templates.mjs` which copies `.squad/skills/*/SKILL.md` files into both `packages/squad-sdk/templates/skills/` and `packages/squad-cli/templates/skills/`. Editing `.squad/skills/model-selection/SKILL.md` is sufficient β€” the sync propagates it. - -### Model Default Update Pattern -When updating default models, touch these files in order: -1. `.squad/skills/model-selection/SKILL.md` β€” tables, fallback chains, valid models list, examples -2. `.github/agents/squad.agent.md` β€” core rules section (~line 295), spawn example (~line 297) -3. `packages/squad-sdk/src/runtime/constants.ts` β€” `MODELS.DEFAULT`, `MODELS.FALLBACK_CHAINS` -4. `packages/squad-sdk/src/agents/model-selector.ts` β€” `selectModelForTask` switch cases -5. `packages/squad-sdk/src/config/models.ts` β€” `MODEL_CATALOG` entries, `DEFAULT_FALLBACK_CHAINS` -6. `packages/squad-sdk/src/runtime/benchmarks.ts` β€” fixture data -7. Tests: `test/agents.test.ts`, `test/config.test.ts`, `test/models.test.ts`, `test/compat-v041.test.ts`, `test/init.test.ts` - -### Claude Haiku Stays at 4.5 -There is no `claude-haiku-4.6`. The latest haiku is `claude-haiku-4.5`. Never bump haiku beyond 4.5 until the platform explicitly lists a newer haiku variant. - -### Standard Tier Fallback Chain (current) -`claude-sonnet-4.6 β†’ gpt-5.4 β†’ claude-sonnet-4.5 β†’ gpt-5.3-codex β†’ claude-sonnet-4 β†’ gpt-5.2` - -### ModelId Type -`ModelId = string` in `runtime/config.ts` β€” not a discriminated union. New model IDs can be added to the catalog without TypeScript changes beyond the catalog and chain arrays. - -### Template Copy Rename Pattern (#613/#614) -- Template copies of `squad.agent.md` in `templates/`, `packages/squad-cli/templates/`, and `packages/squad-sdk/templates/` are now named `squad.agent.md.template` to prevent Copilot CLI 1.0.11 from discovering and merging them as `*.agent.md` files. -- The canonical source (`.squad-templates/squad.agent.md`) and the active copy (`.github/agents/squad.agent.md`) remain unchanged. -- `scripts/sync-templates.mjs` handles the rename: mirror targets get `.template` suffix, `.github/agents/` target keeps `.md`. -- All code reading templates for init/upgrade/consult (SDK `init.ts`, CLI `upgrade.ts`, CLI `templates.ts`, SDK `consult.ts`) references `squad.agent.md.template` as the source filename. -- The `TEMPLATE_MANIFEST` in `templates.ts` uses `source: 'squad.agent.md.template'` but `destination: '../.github/agents/squad.agent.md'` β€” source and target names differ. diff --git a/.squad/agents/eecom/history.md b/.squad/agents/eecom/history.md deleted file mode 100644 index cf00ea8ac..000000000 --- a/.squad/agents/eecom/history.md +++ /dev/null @@ -1,319 +0,0 @@ -# EECOM - -> Environmental, Electrical, and Consumables Manager - -## Learnings - -### PR #942 rebase β€” cherry-pick from insider-based fork branch (2026-04-12) - -**Context:** PR #942 from tamirdresher's fork was retargeted from `insider` to `dev`, causing 29 files in the diff when only 3 commits (4 files relevant to dev) were the actual fix. Cherry-picked the 3 fix commits onto a clean `squad/942-rebase-type-safety` branch from dev, resolving conflicts where insider-only files (skill.ts, cross-package-exports.test.ts) didn't exist on dev. Dropped the `escapeYamlValue` import and APM YAML generation function from init.ts since skill.ts doesn't exist on dev. Opened #963 as the clean replacement, closed #942. - -**Key lesson:** When cherry-picking from an insider-based branch to dev, expect modify/delete conflicts for files that only exist on insider. Always verify the base assumptions of each change β€” imports referencing insider-only modules must be dropped or adapted. - -### Loop command: second-round review fixes (#767) (2025-07-26) - -**Context:** Three Copilot review comments on PR #767: (1) `teamRoot` was set to `workTreeRoot` but `.squad/` may live in the main checkout when running inside a git worktree β€” should derive from `detectSquadDir().path`, (2) `generateLoopFile()` hardcoded the full loop.md scaffold inline, duplicating `templates/loop.md`, (3) docs said `gh` was optional but code hard-requires `gh copilot` unless `--agent-cmd` is passed. - -**Fixes:** -1. **teamRoot:** Changed `const teamRoot = workTreeRoot` to `path.dirname(squadDirInfo.path)` β€” `.squad/`-relative operations now always use the directory where `.squad/` was actually found. -2. **Template dedup:** Replaced 48-line hardcoded template with `readFileSync` reading from `templates/loop.md`. Used `import.meta.url` + `fileURLToPath` to resolve the path from the compiled file (3 levels up to package root). Created `packages/squad-cli/templates/loop.md` since it was missing from the CLI package's templates dir. -3. **Docs:** Updated prerequisites to state `gh` + `gh copilot` are required by default, with `--agent-cmd` as the escape hatch. - -**Test impact:** Tests mock `node:fs` globally, so `readFileSync` in `generateLoopFile()` needed mock setup. Added `beforeAll` using `vi.importActual('node:fs')` to read the REAL template file, then `beforeEach` to set the mock return value. This keeps tests validating the actual template content. - -**Pattern:** When reading template files in code that has mocked `node:fs` tests, use `vi.importActual('node:fs')` in `beforeAll` to get real filesystem access for loading test fixtures. - -### Loop command: streaming output, worktree CWD, docs alignment (#767) (2025-07-25) - -**Context:** Copilot code review on PR #767 flagged three issues in the loop command: (1) `execFile` buffered stdout/stderr but never printed it β€” users saw no Copilot output during loop rounds, (2) `loop.md` was resolved relative to `dest` but execution used `teamRoot` (derived from `.squad/` parent), creating a CWD mismatch in worktree scenarios, (3) docs said `description` defaults to `""` but code uses `'Squad Loop'`. - -**Fixes:** -1. **Streaming:** Added `.on('data')` listeners to `currentChild.stdout` and `currentChild.stderr` after `execFile` spawn. Since output streams in real-time, the callback no longer re-writes buffered stdout/stderr on error (would duplicate). -2. **Worktree CWD:** Introduced `workTreeRoot = path.resolve(dest)` and set `teamRoot = workTreeRoot`. Both file resolution and execution CWD now use the same root. -3. **Docs:** Updated `docs/src/content/docs/features/loop.md` description default from `""` to `"Squad Loop"`. - -**Key file:** `packages/squad-cli/src/cli/commands/loop.ts` β€” `runLoop()` entry point (~line 302), `executeRound()` inner function (~line 427). - -**Pattern:** When using Node's `execFile` for interactive/long-running child processes, always attach stream listeners for real-time output. The callback's `stdout`/`stderr` args are the same buffered content β€” writing both duplicates output. - -### archiveDecisions() count-based fallback (#626) (2025-07-24) - -**Context:** `archiveDecisions()` in `packages/squad-cli/src/cli/core/nap.ts` silently returned `null` when all `###` entries were <30 days old (`old.length === 0`), even if the file was well over 20KB. Active projects generating many decisions per session could hit 145KB+ β€” 35K tokens burned per agent spawn. - -**Fix:** Added a count-based fallback after the age-based split. When `old.length === 0` and total file size exceeds `DECISION_THRESHOLD` (20KB), the fallback separates recent entries into dated vs undated, sorts dated by age (most recent first), keeps entries that fit under the threshold budget, and archives the rest. Undated entries are always preserved β€” they are foundational directives per Procedures' guidance. - -**Key design choices:** -1. Undated entries (`daysAgo === null`) are never archived by the count-based fallback. They stay in `recent`. -2. Budget calculation accounts for header + undated entries + kept dated entries to guarantee the result fits under 20KB. -3. Entries are re-sorted into original document order after the split, so the output file preserves heading sequence. - -**Tests:** Added 4 adversarial tests β€” 50 all-today entries >20KB, mixed dated/undated preservation, under-threshold no-op, exact-threshold boundary case. - -**Pattern:** When a function has an early-return optimization (`if (old.length === 0) return null`), always consider whether the condition that triggered the function call (file size > threshold) can still be true when the early-return fires. If so, the early-return is a silent failure. - -### Init scaffolding: casting dir + no-remote stderr (#579) (2025-07-18) - -**Context:** `squad init` in a fresh `git init` repo (no remote) printed `error: No such remote 'origin'` to stderr and `squad doctor` reported `casting/registry.json` missing. Two independent bugs in `packages/squad-sdk/src/config/init.ts`. - -**Fix 1 β€” Stderr leak:** Three `execFileSync('git', ['remote', 'get-url', 'origin'])` calls in `initSquad()` were missing `stdio: ['pipe','pipe','pipe']`. The try/catch caught the error but git's stderr still leaked to the console. Added stdio piping to all three call sites (lines ~713, ~732, ~1039). - -**Fix 2 β€” Missing casting files:** The init flow created the `.squad/casting/` directory but never populated it. Added a scaffolding block after directory creation that copies `casting-policy.json`, `casting-registry.json`, and `casting-history.json` from SDK templates (with inline fallbacks). Respects `skipExisting` β€” never overwrites user files. - -**Pattern:** When calling `execFileSync` for a git command inside a try/catch, always add `stdio: ['pipe','pipe','pipe']` to suppress stderr. The catch prevents a crash, but without piped stdio the error message still prints to the user's terminal. - -### 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. - -**Fix:** Added `cmd === 'version'` to the existing `--version`/`-v` condition in `cli-entry.ts` (line ~130). Also added `version` to the help text command list. No new file in `cli/commands/` needed β€” this is a trivial inline handler, same as `--version`. The wiring test is unaffected since there's no separate command file. - -**Pattern:** When a CLI flag (`--foo`) works but the equivalent subcommand (`foo`) doesn't, the fix is almost always a single condition addition in `cli-entry.ts`. No separate command file needed for trivial handlers. - -### Privacy scrub messaging + EPERM + gitignore parent coverage (#549) (2026-07-14) - -**Context:** Upgrade footer message always said "Preserves user state" even when the email privacy scrub had run β€” a direct contradiction of what just happened. Two related issues in the same function: EPERM on read-only `.gitattributes` would crash the upgrade, and `.gitignore` would add redundant entries already covered by parent paths (e.g. `.squad/log/` when `.squad/` was already present). - -**Fix:** -1. `upgrade.ts` β€” `ensureGitattributes` catches EPERM/EACCES and returns `[]` with a console.warn, graceful degradation. -2. `upgrade.ts` β€” `ensureGitignore` skips an entry when any existing line is a parent prefix of it. -3. `upgrade.ts` β€” Footer logic checks whether the email scrub actually ran; shows "Privacy scrub applied" or "Preserves user state" accordingly. -4. `test/cli/upgrade.test.ts` β€” Added EPERM test using `chmodSync` (fix: `chmodSync` was missing from the `fs` import β€” added it). - -**Pattern:** When adding a new fs function to a test, always verify the named import list at the top of the test file. Missing named imports from `'fs'` produce `ReferenceError` at runtime, not at type-check time (if the test file isn't part of the main tsconfig). - -πŸ“Œ **Team update (2026-03-22T09-35Z β€” Wave 1):** Economy mode fully implemented: ECONOMY_MODEL_MAP + resolveModel() integration in SDK, `squad economy on|off` CLI command, `--economy` flag, 34 tests passing. PR #504 open for review. Soft dependency: #464 rate limit UX should offer economy mode as recovery. Next: Phase 1 of ambient personal squad (T1–T5, T19) β€” ready to start immediately after merging current work. Procedures wrote governance proposals for squad.agent.md β€” awaiting Flight review. -### Rate Limit UX (#464) (2026-03-20) - -**Context:** Users hitting Copilot rate limits saw generic "Something went wrong processing your message." Squad hid the actual error. `squad doctor` reported nothing β€” useless to diagnose. - -**Root cause:** The catch block in `shell/index.ts` line ~1119 always emitted `genericGuidance()` unless `SQUAD_DEBUG=1`. Rate limit errors never got special treatment despite `RateLimitError` existing in `adapter/errors.ts`. - -**Fix:** -1. `error-messages.ts` β€” Added `rateLimitGuidance({ retryAfter?, model? })` and `extractRetryAfter(message)` utilities. Rate limit guidance shows clear message + recovery options (retry time, `squad economy on`, config.json model override). -2. `shell/index.ts` β€” Catch block now detects rate limits via `instanceof RateLimitError` OR regex on the raw message. Writes `.squad/rate-limit-status.json` on detection. -3. `doctor.ts` β€” Added `checkRateLimitStatus()` check. Reads status file and warns if rate limit was recent. -4. `test/error-messages.test.ts` β€” Added 11 new tests covering `rateLimitGuidance` and `extractRetryAfter`. - -**Pattern:** Rate limit status written to `.squad/rate-limit-status.json` as `{ timestamp, retryAfter, model, message }`. Doctor reads it on next run. File is never deleted automatically β€” doctor marks it `pass` when > 4h stale. - -**Import path for `RateLimitError`:** `@bradygaster/squad-sdk/adapter/errors` (subpath export, not in main barrel). - -**PR:** #464 fix β€” squad/464-rate-limit-ux - -### CLI Entry Point Architecture -cli-entry.ts is the central router for ~30+ CLI commands using dynamic imports (lazy-loading). Commands are routed via if-else blocks. Has a recurring "unwired command" bug class β€” implementations exist in cli/commands/ but aren't routed in cli-entry.ts. The cli-command-wiring.test.ts regression test catches this by verifying every .ts file in cli/commands/ is imported. - -### ESM Runtime Patch -Module._resolveFilename interceptor in cli-entry.ts (lines 47-54) patches broken ESM import in @github/copilot-sdk@0.1.32 (vscode-jsonrpc/node missing .js extension). Required for Node 24+ strict ESM enforcement. Works on npx cache hits where postinstall scripts don't run. - -### Lazy Import Pattern -All command imports use `await import('./cli/commands/xxx.js')` to minimize startup time. Copilot SDK is lazily loaded only when shell is invoked. All .js extensions required for Node 24+ strict ESM. - -### CLI Packaging & Distribution -`npm pack` produces a complete, installable tarball (~275KB packed, 1.2MB unpacked). Package includes dist/, templates/, scripts/, README.md per package.json "files" field. Postinstall script (patch-esm-imports.mjs) patches @github/copilot-sdk for Node 24+ compatibility. Tarball can be installed locally (`npm install ./tarball.tgz`) and commands execute via `node node_modules/@bradygaster/squad-cli/dist/cli-entry.js`. Both squad-cli and squad-sdk must be installed together β€” cli depends on sdk with "*" version specifier. All 27+ CLI commands are lazy-loaded at runtime; `--help` validates command routing without executing full logic. - -### Packaging Smoke Test Strategy -test/cli-packaging-smoke.test.ts validates the packaged artifact (not source). Uses npm pack + install in temp dir + command routing verification. Commands are expected to fail (no .squad/ dir) β€” test verifies routing only (no "Unknown command", no MODULE_NOT_FOUND for the command itself). Exception: node-pty is an optional dependency for the `start` command and MODULE_NOT_FOUND for node-pty is allowed. Windows cleanup requires retry logic due to EBUSY errors β€” use rmSync with maxRetries + retryDelay options, wrap in try/catch to fail silently since tests have passed. - -### v0.8.24 Release Readiness Audit -CLI completeness audit (2026-03-08) confirmed: 26 primary commands routed in cli-entry.ts, all present in smoke test. 4 aliases (watchβ†’triage, workstreamsβ†’subsquads, remote-controlβ†’rc, streamsβ†’subsquads). 3 aliases tested, 1 untested ("streams"). Packaging verified: dist/, templates/, scripts/, README.md in tarball; bin entry points to dist/cli-entry.js; postinstall script included and working. All 32 smoke tests pass. Package.json files array correct. npm pack output shows 318 files, 275KB packed. No missing command implementations. Optional dep (node-pty) handled correctly. Only gap: "streams" alias not in smoke test (routed correctly but test coverage incomplete). Confidence: 95% β€” all critical paths covered, minor alias test gap non-blocking. - -πŸ“Œ **Team update (2026-03-08T21:18:00Z):** FIDO + EECOM released unanimous GO verdict for v0.8.24. Smoke test approved as release gate. FIDO confirmed 32/32 pass + publish.yml wired correctly. EECOM confirmed 26/26 commands + packaging complete (minor gap: "streams" alias untested, non-blocking). - -### Cross-Platform Filename and Config Fixes (#348, #356) (2026-03-15T05:30:00Z) - -**Context:** Two cross-platform bugs broke Squad on Windows: (1) log filenames contained colons in ISO 8601 timestamps (illegal on Windows), (2) `.squad/config.json` contained absolute machine-specific `teamRoot` path. - -**Investigation:** -- Searched SDK for all timestamp usage in filenames β€” found `safeTimestamp()` utility already existed but wasn't consistently used -- `comms-file-log.ts` (line 32) used inline `toISOString().replace(/:/g, '-')` instead of utility -- `init.ts` (line 612) wrote absolute `teamRoot` to config.json on every init -- Session-store already used `safeTimestamp()` correctly (line 71) - -**Fixes:** -1. **Bug #348:** Updated `comms-file-log.ts` to import and use `safeTimestamp()` utility instead of inline timestamp formatting -2. **Bug #356:** Removed `teamRoot` field from config.json (can be computed at runtime via `git rev-parse --show-toplevel`) -3. Updated live `.squad/config.json` in repo to remove machine-specific path - -**Pattern:** Centralized timestamp formatting in `safeTimestamp()` utility (replaces colons + truncates milliseconds). Windows-safe format: `2026-03-15T05-30-00Z` instead of `2026-03-15T05:30:00.123Z`. - -**Test Impact:** All 150 tests pass. Communication adapter test doesn't validate specific filename format (structural test, not behavioral). - -**PR:** #404 opened targeting dev. - -### CastingEngine CLI Integration (#342) (2026-03-15T11:20:00Z) - -**Context:** CastingEngine class (Issue #138, M3-2) existed in SDK with curated universe templates (The Usual Suspects, Ocean's Eleven) but was completely bypassed during `squad init`. LLM picked arbitrary names, and charter generation used regex-based `personalityForRole()` instead of template backstories. - -**Investigation:** -- CastingEngine.castTeam() was never called in CLI flow -- coordinator.ts buildInitModePrompt() let LLM pick any universe without guidance -- cast.ts generateCharter() used fallback personality logic instead of engine data -- SDK exports two AgentRole types: broad one in casting-engine.ts, restrictive one in runtime/constants.ts - -**Integration Strategy (Augment, Not Replace):** -- LLM still proposes roles and team composition (the beloved casting experience) -- CastingEngine augments with curated names when universe is recognized -- Mapping: "The Usual Suspects" β†’ 'usual-suspects', "Ocean's Eleven" β†’ 'oceans-eleven' -- Unrecognized universes (Matrix, Alien, etc.) preserve LLM's arbitrary names - -**Implementation:** -1. Added `augmentWithCastingEngine()` in cast.ts to replace LLM names with engine characters -2. Updated coordinator prompt to suggest preferred universes (Usual Suspects, Ocean's Eleven) -3. Extended `generateCharter()` to use engine personalities/backstories when available -4. Attached `_personality` and `_backstory` to CastMember objects for charter generation -5. Role mapping: CLI role strings β†’ engine AgentRole enum (lead, developer, tester, etc.) - -**Type Import Pattern:** -- Import CastingEngine from `@bradygaster/squad-sdk/casting` (not main barrel export) -- Use casting-engine.ts AgentRole type (9 roles) not runtime/constants.ts (6 roles) -- Partial mapping: unmapped roles log warning and skip engine casting - -**Tests:** -- Created test/casting-engine-integration.test.ts (5 tests, all pass) -- Validates augmentation for both universes, case-insensitive matching, fallback behavior -- All 45 existing cast-parser/casting tests still pass - -**PR:** #417 opened targeting dev. - - -### PR #427 Cross-Fork Rebase (2026-03-15T21:00:00Z) - -**Context:** PR #427 (PAO external communications Phase 1) conflicted with upstream/dev after team recast (#423 Usual Suspects β†’ Apollo 13) and model updates. Cross-repo PR (diberry/squad β†’ bradygaster/squad). Initial rebase attempts failed due to git worktree confusion β€” main worktree was checked out to a different branch, causing git checkout commands to silently switch to wrong branches. - -**Problem:** Git commands (checkout, rebase) kept switching to unrelated branches (squad/agent-on-disk-concept, squad/320-fix-migration-guide-version-local) mid-rebase. Root cause: main worktree at C:\Users\diberry\repos\project-squad\squad was checked out to squad/agent-on-disk-concept. Git was treating checkout commands as worktree operations and switching the main worktree's HEAD, aborting the rebase. - -**Solution:** Created dedicated worktree (.worktrees/pao-rebase) for the rebase operation. This isolated the rebase from main worktree state and prevented branch switching. - -**Conflict Resolution (3 files, 7 commits rebased):** -1. **.squad/agents/_alumni/mcmanus/charter.md** - Merged both rule sets: DOCS-TEST SYNC (from upstream reskill) and EXTERNAL COMMS, HUMANIZER, AUDIT TRAIL (from PR #427). Used PowerShell regex to extract and combine both sides. -2. **.squad/routing.md** - Accepted Apollo 13 team names (EECOM, PAO, FIDO) from upstream via `git checkout --ours` (in rebase context, "ours" = upstream, "theirs" = our branch). PAO external comms infrastructure is team-agnostic. -3. **.squad/agents/keaton/history.md** - Accepted deletion via `git rm` (file moved to _alumni in upstream recast). - -**Rebase Commits:** 7 commits from squad/426-pao-external-comms rebased onto upstream/dev (f87a7a5), covering #423 team reskill, #424 SDK switch, #425/#428 test parity, #429 model updates. - -**Force Push:** `git push origin squad/426-pao-external-comms --force-with-lease` succeeded. PR #427 comment posted via gh CLI. - -**Pattern:** When working with git worktrees, always create a dedicated worktree for complex operations (rebase, cherry-pick) to avoid main worktree state interference. Use `git worktree list` to diagnose unexpected branch switching. -### SDK Init Flow Deep Dive (2026-03-08) -Traced complete `squad init --sdk` flow end-to-end for unified PRD. Key findings: (1) Init flow has two phases: CLI init creates skeleton files, REPL auto-cast creates team members. (2) Critical gap: squad.config.ts is never updated after auto-cast β€” members exist in .squad/ but not in config. (3) Ralph is inconsistently created (auto-cast yes, CLI init no). (4) No commands exist for adding/removing members post-init. (5) CastingEngine class exists but is never called during init β€” LLM-based Init Mode prompt is used instead. Roadmap written to .squad/identity/sdk-init-implementation-roadmap.md with 7 fixes prioritized by dependency graph. Critical path: sync utility β†’ Ralph fixes β†’ CastingEngine integration β†’ hire/remove commands. High-risk items: squad.config.ts AST parsing (considered regex alternative). Open questions: AST vs regex for config sync, CastingEngine augment vs replace LLM, Ralph always-on vs opt-in. - -πŸ“Œ **Team update (2026-03-11T01:25:00Z):** SDK Init decisions finalized: Phase-based quality improvement program, CastingEngine canonical casting, squad.config.ts as source of truth, Ralph always-included, implementation priority order (sync utility first, then Ralph fixes, then CastingEngine integration). All decisions merged to decisions.md. Ready to start Phase 1 implementation. - -### Adoption Tracking Tier 1 Implementation (2026-03-10) -Implemented Flight's privacy-first adoption monitoring strategy on PR #326 branch. Moved `.squad/adoption/` β†’ `.github/adoption/` for better GitHub integration. Stripped tracking.md to aggregate-only metrics (removed all individual repo names/URLs). Updated GitHub Action workflow (adoption-report.yml) and monitoring script (scripts/adoption-monitor.mjs) to write reports to `.github/adoption/reports/`. Removed "Built with Squad" showcase link from README.md (deferred to Tier 2 opt-in feature). This honors the principle: collect aggregate metrics via public APIs, but never publish individual repo lists without explicit consent. Test discipline: verified npm run build passes; docs-build.test.ts passed structure tests (Astro build failure unrelated to changes). Committed with clear message explaining privacy rationale. - -πŸ“Œ **Team update (2026-03-10T12-55-49Z):** Adoption tracking Tier 1 complete and merged to decisions.md. Privacy-first architecture confirmed: aggregate metrics only, opt-in for individual repos, public showcase only when 5+ projects opt in. Append-only file governance enforced (no deletions in history.md or decisions.md). Microsoft ampersand style guide adopted for documentation. - -### Issue Triage (2026-03-22T06:44:01Z) - -**Flight triaged 6 unlabeled issues and filed 1 new issue.** - -EECOM assigned: -- **#481 (StorageProvider PRD)** β†’ squad:control + squad:eecom (type system abstraction + runtime integration) -- **#479 (history-shadow race condition)** β†’ squad:eecom + squad:retro (production bug; mitigation through StorageProvider atomicity) - -Pattern: Three architectural gaps identified (agent spec, state abstraction, quality tooling) + one production bug. StorageProvider abstraction critical for #479 atomicity fix. - -πŸ“Œ **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. EECOM owns StorageProvider PRD spec (#481) + history-shadow race mitigation (#479). Ready to begin implementation on next sprint. - -### PR #483 Review & Merge β€” Platform Adapter Timeout Fix (2026-03-22) - -Reviewed and merged diberry's fix for platform-adapter test timeouts that were blocking all 8 open PRs. Root cause: `getAvailableWorkItemTypes()` called `execFileSync('az', ...)` with no timeout β€” in CI where az CLI is installed but no real ADO org exists, it hangs indefinitely until Vitest kills it at 5s. - -**Fix pattern:** `{ ...EXEC_OPTS, timeout: 3_000 }` β€” spread existing exec options and add a 3-second timeout. The existing catch block already returns sensible default work item types, so timeout errors fall through gracefully. This is the correct pattern for any external CLI call that might hang: add a timeout to execFileSync and ensure the catch block has a fallback. - -**Rebase note:** Branch was already clean on top of dev (1 commit ahead, no divergence). No rebase was needed. - -πŸ“Œ **Team update:** PR #483 merged (squash). This unblocks CI for all open PRs that were failing on platform-adapter test timeouts. The remaining CI failure across PRs is the broken docs link (separate issue). - -### PR #480 Review & Merge β€” History Race Condition Fix (2026-03-22) - -Reviewed and merged PR #480 (async mutex + atomic writes + 14 tests). Addresses race condition in history-shadow file operations under concurrent load. - -**Fix pattern:** Race conditions in history operations require three-layer defense: (1) async mutex for write serialization, (2) atomic file operations (write-then-rename), (3) comprehensive test coverage (14 tests for edge cases). This pattern applies to any persistent state under concurrent access. - -**Key learning:** File system race conditions aren't just "add a lock" β€” need atomicity guarantees (rename is atomic), serialization (mutex), and exhaustive test coverage to validate edge cases (concurrent writes, stale reads, partial failures). - -### PR #486 Review & Merge β€” SIGINT Handling (2026-03-22) - -Reviewed and merged PR #486 (two-layer signal handling + 22 tests). Improves graceful shutdown under SIGINT (Ctrl+C) by cleaning up both parent and child processes. - -**Fix pattern:** Signal handling in Node.js requires two layers: (1) parent process SIGINT handler that triggers graceful shutdown, (2) child process cleanup (kill child processes, close file handles, flush buffers). Incomplete cleanup leaves zombie processes or orphaned file locks. Test coverage essential: 22 tests verify process tree cleanup, signal propagation, and edge cases (nested children, immediate re-signals). - -**Key learning:** SIGINT handling is more complex than "add a signal handler" β€” need explicit child process cleanup logic + comprehensive tests. Pattern applies to any process spawning child processes (CLI spawning subshells, REPL spawning child REPL instances, etc.). -### Economy Mode Implementation (#500) (2026-03-20) - -**Context:** Issue #500 requested economy mode β€” a session-level and persistent modifier that shifts model selection to cheaper alternatives. - -**Architecture decision:** Economy mode is a Layer 3/4 modifier only. Layers 0–2 (explicit user preferences: config.json, session directive, charter) are never downgraded. This preserves user intent while enabling cost savings on auto-selected tasks. - -**Implementation:** -1. `ECONOMY_MODEL_MAP` + `applyEconomyMode()` in `config/models.ts` β€” pure mapping function for premiumβ†’standard and standardβ†’fast downgrades -2. `readEconomyMode()` + `writeEconomyMode()` β€” config.json read/write functions (same merge-without-clobber pattern as `writeModelPreference()`) -3. `resolveModel()` in `config/models.ts` updated with `economyMode?: boolean` option; falls back to reading from `squadDir` if not provided -4. `resolveModel()` in `agents/model-selector.ts` updated with `economyMode?: boolean` β€” both SDK resolvers are economy-aware -5. `squad economy [on|off]` command in CLI for persistent toggle -6. `--economy` global flag in `cli-entry.ts` sets `SQUAD_ECONOMY_MODE=1` env var for session scope -7. 34 new tests in `test/economy-mode.test.ts` β€” all pass - -**Key pattern:** Both resolveModel implementations follow identical principle: explicit overrides (user choice) are sacred; economy only affects computed auto-selection. - -**PR:** #500 branch `squad/500-economy-mode` - -### node:sqlite Hard-Fail Fix (#502) (2026-03-21) - -**Context:** Workshop participants (reported by Doron Ben Elazar) were blocked by `ERR_UNKNOWN_BUILTIN_MODULE` crashes. `node:sqlite` (used by Copilot SDK for session storage) requires Node 22.5.0+. The existing soft-warn-and-continue approach let users limp into a cryptic crash. - -**Root cause:** `engines.node` said `>=20` but `node:sqlite` needs `>=22.5.0`. The pre-flight check warned but didn't exit, so users saw confusing failures deep in SDK code. - -**Fix:** -1. **cli-entry.ts:** Replaced `try { await import('node:sqlite') } catch { warn }` with a synchronous version check that calls `process.exit(1)` immediately with a clear upgrade message. Removed the now-dead `checkNodeSqlite()` function and its call site. -2. **doctor.ts:** Added `checkNodeVersion()` to `squad doctor` β€” exported with optional version param for testability. -3. **package.json (Γ—3):** Corrected `engines.node` to `>=22.5.0` so npm/npx warn at install time. -4. **Tests:** 5 new tests for `checkNodeVersion()` (Node 20.x fail, 22.4.x fail, 22.5.0 pass, 24.x pass, current env pass). Updated check-count assertion. - -**Pattern:** git branch confusion β€” `git checkout -b` switches HEAD but edits to files on wrong branch are lost when switching. Always confirm `git branch` before making file edits. File edits don't follow you to a new branch if you forgot to switch first. - -**PR:** #506 branch `squad/502-node-sqlite-dependency` - -### Rate Limit Recovery UX (#464) (2026-03-22) - -**Context:** Rate limit errors showed generic message with no actionable recovery. Brady directive: offer model switching + economy mode as recovery options. - -**Implementation:** -1. `error-messages.ts` β€” `rateLimitGuidance()` shows actual reason + 3 recovery options (retry time, `squad economy on`, config.json model override) -2. `shell/index.ts` β€” Detects rate limits via `instanceof RateLimitError` or regex; writes `.squad/rate-limit-status.json` -3. `doctor.ts` β€” `checkRateLimitStatus()` reads status file and warns if recent -4. 36 new tests β€” all pass - -**PR:** #505 `squad/464-rate-limit-ux` β€” merged (rebased after #504) - -### Session 2 Summary (2026-03-22) - -Executed 3 tasks across 2 waves: economy mode (#500, PR #504), node:sqlite fix (#502, PR #506), rate limit UX (#464, PR #505). All PRs merged to dev. - - -### Personal Squad Init via npx (#576) (2026-03-23) - -**Context:** `init --global` (used via npx to set up personal squad) created a full `.squad/` structure at `~/.config/squad/` but never created the `personal-squad/` subdirectory. `resolvePersonalSquadDir()` looks for `personal-squad/`, so subsequent repo-level `init` couldn't discover the user's personal agents. - -**Root cause:** Two separate concepts - `init --global` scaffolds a full squad, `personal init` creates `personal-squad/`. The `--global` flag never bridged between them. - -**Fix:** -1. `resolution.ts` - Added `ensurePersonalSquadDir()` idempotent helper to SDK. -2. `cli-entry.ts` - `init --global` now suppresses workflows and passes `isGlobal` flag. -3. `init.ts` - After global init, calls `ensurePersonalSquadDir()`. After repo init, detects personal squad. -4. `personal.ts` - Refactored to reuse `ensurePersonalSquadDir()`. -5. `resolution.test.ts` - Added 3 tests. - -**Pattern:** `resolveGlobalSquadPath()` returns the container; `ensurePersonalSquadDir()` creates the subdirectory the rest of the system looks for. -πŸ“Œ **Team update (2026-03-25T18:11Z):** Fixed #590 personal squad path regression β€” getPersonalSquadRoot() now uses canonical personal-squad/ subdirectory like esolvePersonalSquadDir() and nsurePersonalSquadDir(). Committed on squad/590-fix-personal-squad-root. FIDO found same bug in shell/index.ts β†’ work passed to CONTROL for full sweep revision. Awaiting FIDO re-review. - diff --git a/.squad/agents/fido/history.md b/.squad/agents/fido/history.md deleted file mode 100644 index c79654459..000000000 --- a/.squad/agents/fido/history.md +++ /dev/null @@ -1,225 +0,0 @@ -# FIDO - -> Flight Dynamics Officer - -## Core Context - -Quality gate authority for all PRs. Test assertion arrays (EXPECTED_GUIDES, EXPECTED_FEATURES, EXPECTED_SCENARIOS, etc.) MUST stay in sync with files on disk. When reviewing PRs with CI failures, always check if dev branch has the same failures β€” don't block PRs for pre-existing issues. 3,931 tests passing, 149 test files, ~89s runtime. - -πŸ“Œ **Team update (2026-03-26T06:41:00Z β€” Crash Recovery Execution & Community PR Review):** Post-CLI crash recovery completed: Round 1 baseline verified (5,038 tests βœ… green), Round 2 executed duplicate closures (#605/#604/#602) and 9-PR community batch review. FIDO approved 3 PRs (#625 notification-routing, #603 Challenger agent, #608 security policyβ€”merged via Coordinator) and issued change requests on 6 PRs identifying systemic issues: changeset package naming (4 PRs used unscoped `squad-cli` instead of `@bradygaster/squad-cli`); file paths (2 PRs placed files at root instead of correct package structure). Quality gate result: high-bar community acceptanceβ€”approved 3/9 (33%), change-request 6/9 (67%), 0 rejections. PR #592 (legacy, high-quality) also merged. All actions complete; dev branch remains green. Decision inbox merged and deleted. Next: Monitor 6 change-request PRs for author responses. - -πŸ“Œ **Team update (2026-03-25T15:23Z β€” Triage Session & PR Review Batch):** FIDO reviewed 10 open PRs for quality and merge readiness. Identified 3 duplicate/overlap pairs consolidating 6 PRs into 4: #607 (retro enforcement, comprehensive) approved for merge, #605 closed as duplicate (less comprehensive). #603 (Challenger agent, correct paths) approved for merge, #604 closed as duplicate (wrong file paths). #606 (tiered memory superset, 3-tier model) approved for merge, #602 closed as duplicate (narrower 2-tier scope). Merge-ready PRs identified: #611 (blocked on #610), #592 (joniba wiring guide, high-quality). Draft #567 not ready. Impact: reduces PR count from 10 to 7, eliminates file conflicts, preserves unique value. All other PRs (#611, #608, #592, #567) can proceed independently. Decisions merged to decisions.md and decisions inbox deleted. - -## Learnings - -### Test Assertion Sync Discipline -EXPECTED_* arrays in docs-build.test.ts must match filesystem reality. When PRs add new content files, verify the corresponding test arrays are updated. Consider dynamic discovery pattern (used for blog posts) for resilience against content additions. Stale assertions that block CI are FIDO's responsibility. - -### PR Quality Gate Pattern -Verdict scale: GO (merge), FAIL (block until fixed), NO-GO (reject). Always verify: test discipline (assertions synced), CI status (distinguish pre-existing vs new failures), content accuracy, cross-reference validity. When detecting CI failures, run baseline comparison (dev branch vs PR branch) to isolate regressions. - -### Name-Agnostic Testing -Tests reading live .squad/ files must assert structure/behavior, not specific agent names. Names change during team rebirths. Two test classes: live-file tests (survive rebirths, property checks) and inline-fixture tests (self-contained, can hardcode). - -### Dynamic Content Discovery -Blog tests use filesystem discovery (readdirSync) instead of hardcoded arrays. Pattern: discover from disk, sort, validate build output exists. - -### Command Wiring Regression Test -cli-command-wiring.test.ts prevents "unwired command" bug: verifies every .ts file in commands/ is imported in cli-entry.ts. Bidirectional validation. - -### CLI Packaging Smoke Test -cli-packaging-smoke.test.ts validates packaged CLI artifact (npm pack β†’ install β†’ execute). Tests 27 commands + 3 aliases. Catches: missing imports, broken exports, bin misconfiguration, ESM resolution failures. Complements source-level wiring test. - -### CastingEngine Integration Review -CastingEngine augments LLM casting with curated names for recognized universes. Unrecognized universes preserve LLM names. Import from `@bradygaster/squad-sdk/casting`, use casting-engine.ts AgentRole type (9 roles). Partial mapping: unmapped roles skip engine casting. - -### PR #331 Quality Gate Review β€” NO-GO (Blocking Issues Found) (2026-03-10T14:13:00Z) - -**CRITICAL VIOLATIONS DETECTED:** - -1. **Stale Test Assertions (Hard Rule Violation)** β€” EXPECTED_SCENARIOS array in test/docs-build.test.ts contains only 7 values ['issue-driven-dev', 'existing-repo', 'ci-cd-integration', 'solo-dev', 'monorepo', 'team-of-humans', 'cross-org-auth'], but 25 scenario files exist on disk (aspire-dashboard, client-compatibility, disaster-recovery, keep-my-squad, large-codebase, mid-project, multi-codespace, multiple-squads, new-project, open-source, private-repos, release-process, scaling-workstreams, switching-models, team-portability, team-state-storage, troubleshooting, upgrading, + 7 in array). My charter: "When I add test count assertions, I MUST keep them in sync with the actual files on disk. Stale assertions that block CI are MY responsibility to prevent." This is MY responsibility to catch. - -2. **Missing EXPECTED_FEATURES Array** β€” PR adds 'features' to the sections list in test/docs-build.test.ts (line 46), but NO EXPECTED_FEATURES array exists. Test line 171 "all expected doc pages produce HTML in dist/" will skip features entirely. 32 feature files exist (.md files in docs/src/content/docs/features/). - -πŸ“Œ **Team update (2026-03-11T01:27:57Z):** PR #331 quality gate resolved. FIDO fixed test assertion sync in docs-build.test.ts: EXPECTED_SCENARIOS updated to 25 entries, EXPECTED_FEATURES array created with 32 entries, test assertions updated for features validation. Tests: 6/6 passing. Commit: 6599db6. Blocking NO-GO converted to approval gate cleared. Lesson reinforced: test assertions must be synced to filesystem state; CI passing β‰  coverage. - -3. **Incomplete Test Coverage Sync** β€” PAO's history (line 41) states "Updated EXPECTED_SCENARIOS in docs-build.test.ts to match remaining files" after deleting ralph-operations.md and proactive-communication.md. But the diff shows ONLY a single-line change (adding 'features' to sections array). The full test update was not committed. - -**POSITIVE FINDINGS:** -- βœ… CI passed (test run completed successfully on GitHub) -- βœ… Markdown structure tests pass (6/6 syntax checks) -- βœ… Docs are well-written: sentence-case headings, active voice, present tense, second person -- βœ… Cross-references valid (labels.md link verified) -- βœ… No duplicate "How It Works" heading in reviewer-protocol.md -- βœ… Content intact (no accidental loss) -- βœ… Microsoft Style Guide compliance confirmed - -**ROOT CAUSE:** PAO staged the boundary review changes but the test update commit was incomplete. The assertion arrays must be synchronized before merge. - -**REQUIRED FIX:** Update test/docs-build.test.ts: -1. EXPECTED_SCENARIOS = [ all 25 actual scenario files, sorted ] -2. EXPECTED_FEATURES = [ all 32 actual feature files, sorted ] -3. Regenerate to match disk reality (use filesystem discovery if the project wants test-resilience) - -**VERDICT:** πŸ”΄ **NO-GO** β€” Merge blocked until test assertions sync with disk state. This is a quality gate violation. - -### Test Assertion Sync Fix (2026-03-10T14:20:00Z) - -**Issue resolved:** Fixed stale test assertions in test/docs-build.test.ts identified during PR #331 review. - -**Changes made:** -1. Expanded EXPECTED_SCENARIOS from 7 to 25 entries (matched all .md files in docs/src/content/docs/scenarios/) -2. Added EXPECTED_FEATURES array with 32 entries (matched all .md files in docs/src/content/docs/features/) -3. Updated test logic to include features section in HTML build validation - -**Validation:** All structure validation tests passing (6/6). Build tests skipped as expected (Astro not installed). Arrays now accurately reflect disk state. - -**Commit:** 6599db6 on branch squad/289-squad-dir-explainer - -**Learning:** When test assertions reference file counts, they MUST be kept in sync with disk reality. The principle applies to ALL assertion arrays (EXPECTED_SCENARIOS, EXPECTED_FEATURES, EXPECTED_GUIDES, EXPECTED_REFERENCE, etc.). Consider dynamic discovery pattern (used in EXPECTED_BLOG) for resilience against content additions. - -πŸ“Œ **Team update (2026-03-10T14-44-23Z):** PR #310 scroll flicker fix merged. 4 root causes identified: Ink clearTerminal issue, timer amplification, log-update trailing newline, unstable Static keys. Postinstall patch pattern adopted for Ink internals. Version pin recommended for stability gate. Build: 3,931 tests pass, zero regressions. -### PR #331 Quality Gate Review β€” NO-GO (Blocking Issues Found) (2026-03-10T14:13:00Z) - -**CRITICAL VIOLATIONS DETECTED:** - -1. **Stale Test Assertions (Hard Rule Violation)** β€” EXPECTED_SCENARIOS array in test/docs-build.test.ts contains only 7 values ['issue-driven-dev', 'existing-repo', 'ci-cd-integration', 'solo-dev', 'monorepo', 'team-of-humans', 'cross-org-auth'], but 25 scenario files exist on disk (aspire-dashboard, client-compatibility, disaster-recovery, keep-my-squad, large-codebase, mid-project, multi-codespace, multiple-squads, new-project, open-source, private-repos, release-process, scaling-workstreams, switching-models, team-portability, team-state-storage, troubleshooting, upgrading, + 7 in array). My charter: "When I add test count assertions, I MUST keep them in sync with the actual files on disk. Stale assertions that block CI are MY responsibility to prevent." This is MY responsibility to catch. - -2. **Missing EXPECTED_FEATURES Array** β€” PR adds 'features' to the sections list in test/docs-build.test.ts (line 46), but NO EXPECTED_FEATURES array exists. Test line 171 "all expected doc pages produce HTML in dist/" will skip features entirely. 32 feature files exist (.md files in docs/src/content/docs/features/). - -πŸ“Œ **Team update (2026-03-11T01:27:57Z):** PR #331 quality gate resolved. FIDO fixed test assertion sync in docs-build.test.ts: EXPECTED_SCENARIOS updated to 25 entries, EXPECTED_FEATURES array created with 32 entries, test assertions updated for features validation. Tests: 6/6 passing. Commit: 6599db6. Blocking NO-GO converted to approval gate cleared. Lesson reinforced: test assertions must be synced to filesystem state; CI passing β‰  coverage. - -3. **Incomplete Test Coverage Sync** β€” PAO's history (line 41) states "Updated EXPECTED_SCENARIOS in docs-build.test.ts to match remaining files" after deleting ralph-operations.md and proactive-communication.md. But the diff shows ONLY a single-line change (adding 'features' to sections array). The full test update was not committed. - -**POSITIVE FINDINGS:** -- βœ… CI passed (test run completed successfully on GitHub) -- βœ… Markdown structure tests pass (6/6 syntax checks) -- βœ… Docs are well-written: sentence-case headings, active voice, present tense, second person -- βœ… Cross-references valid (labels.md link verified) -- βœ… No duplicate "How It Works" heading in reviewer-protocol.md -- βœ… Content intact (no accidental loss) -- βœ… Microsoft Style Guide compliance confirmed - -**ROOT CAUSE:** PAO staged the boundary review changes but the test update commit was incomplete. The assertion arrays must be synchronized before merge. - -**REQUIRED FIX:** Update test/docs-build.test.ts: -1. EXPECTED_SCENARIOS = [ all 25 actual scenario files, sorted ] -2. EXPECTED_FEATURES = [ all 32 actual feature files, sorted ] -3. Regenerate to match disk reality (use filesystem discovery if the project wants test-resilience) - -**VERDICT:** πŸ”΄ **NO-GO** β€” Merge blocked until test assertions sync with disk state. This is a quality gate violation. - -### Test Assertion Sync Fix (2026-03-10T14:20:00Z) - -**Issue resolved:** Fixed stale test assertions in test/docs-build.test.ts identified during PR #331 review. - -**Changes made:** -1. Expanded EXPECTED_SCENARIOS from 7 to 25 entries (matched all .md files in docs/src/content/docs/scenarios/) -2. Added EXPECTED_FEATURES array with 32 entries (matched all .md files in docs/src/content/docs/features/) -3. Updated test logic to include features section in HTML build validation - -**Validation:** All structure validation tests passing (6/6). Build tests skipped as expected (Astro not installed). Arrays now accurately reflect disk state. - -**Commit:** 6599db6 on branch squad/289-squad-dir-explainer - -**Learning:** When test assertions reference file counts, they MUST be kept in sync with disk reality. The principle applies to ALL assertion arrays (EXPECTED_SCENARIOS, EXPECTED_FEATURES, EXPECTED_GUIDES, EXPECTED_REFERENCE, etc.). Consider dynamic discovery pattern (used in EXPECTED_BLOG) for resilience against content additions. - -### Issue Triage (2026-03-22T06:44:01Z) - -**Flight triaged 6 unlabeled issues and filed 1 new issue.** - -FIDO assigned: -- **#477 (Code Quality Linting PRD)** β†’ squad:fido (monorepo async/promise quality, ESLint 9 PoC ready) - -Pattern: Quality tooling gap identified. ESLint 9 modernization + async/promise pattern enforcement for monorepo. - -πŸ“Œ **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. - -πŸ“Œ **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. -### Init Scaffolding Completeness Tests (#579) - -Added `test/init-scaffolding.test.ts` β€” 15 tests covering three gaps exposed by issue #579: - -1. **Casting directory scaffolding** β€” After `initSquad()` and `runInit()`, verifies `.squad/casting/` directory and all three JSON files (registry.json, policy.json, history.json) exist and parse as valid JSON. Also confirms re-init does not overwrite existing casting files. - -2. **No-remote resilience** β€” Confirms init succeeds without errors when: git repo has no remote configured, brand-new `git init` repo, or no git at all. Uses `execFileSync` to create isolated git repos in temp dirs. - -3. **Doctor validation after init** β€” Runs `runDoctor()` against a freshly-initialized directory and asserts zero failures, specifically that `casting/registry.json exists` check passes. Also tests negative cases (missing file β†’ fail, corrupt JSON β†’ fail). - -Pattern: Tests follow existing `test/cli/init.test.ts` and `test/cli/doctor.test.ts` conventions β€” vitest, `randomBytes` temp dirs in cwd, imports from compiled dist via package exports (`@bradygaster/squad-cli/core/init`, `@bradygaster/squad-cli/commands/doctor`, `@bradygaster/squad-sdk`). - -Commit: 7660a27 on branch squad/579-init-scaffolding-hardening. - -### Personal Squad Init Discovery Tests (#576) - -**Task:** Write tests for personal squad discovery and init flows (Issue #576 β€” npx init --global not discovering personal squad). - -**Test file:** `test/personal-squad-init.test.ts` β€” 35 tests, 10 describe blocks, all passing. - -**Coverage areas:** -1. `resolveGlobalSquadPath()` β€” platform-specific path resolution (Windows APPDATA, Linux XDG_CONFIG_HOME, consistency) -2. `resolvePersonalSquadDir()` β€” kill-switch (SQUAD_NO_PERSONAL), directory existence, npx-agnostic discovery -3. `personalInit` contract β€” directory structure creation, config.json shape, idempotency -4. `resolveSquadPaths()` β€” personalDir field inclusion, null when disabled -5. Edge: empty personal-squad dir (exists but no agents/) -6. Edge: partial state (agent dirs without charter.md, missing Role metadata defaults to "personal", stray files skipped) -7. `mergeSessionCast()` β€” project-wins precedence, case-insensitive collision, empty inputs -8. `ensureSquadPathTriple()` β€” personal dir in allowed roots, null personalDir graceful handling -9. Charter metadata parsing edge cases (whitespace trimming, sourceDir correctness, multi-agent discovery) - -**Key finding:** `resolvePersonalSquadDir()` is install-method-agnostic β€” it resolves from env vars and `os.homedir()`, never from `process.argv`. The npx issue (#576) is therefore NOT in path resolution but likely in the CLI command wiring or the `--global` flag routing. Tests confirm the SDK layer works correctly. - -**Commit:** c307187 on branch squad/576-personal-squad-init-npx -### Publish Policy CI Gate (#557) - -Added `publish-policy` job to squad-ci.yml β€” lightweight lint that scans all `.github/workflows/*.yml` for bare `npm publish` commands missing `-w`/`--workspace`. Catches the incident class where root package.json gets published instead of a workspace package. Also wrote `test/publish-policy.test.ts` (36 tests) covering: workspace-scoped passes, bare publish fails, comment/echo/grep/YAML-name line skipping, findViolations line numbering, and live validation of all 15 workflow files. Key pattern: meta-references (echo, grep, YAML name keys containing "npm publish") must be excluded from lint β€” the CI script's own text would otherwise self-trigger. - -πŸ“Œ **Team update (2026-03-24T06-release-hardening):** Publish policy CI gate (#557) implemented. Added `publish-policy` job to squad-ci.yml: lightweight lint scans `.github/workflows/*.yml` for bare `npm publish` commands, rejects non-workspace-scoped invocations. Wrote test/publish-policy.test.ts (36 tests) validating: workspace-scoped passes, bare publish fails, meta-reference (echo/grep/YAML-name) skipping, live validation of 15 workflow files. Pattern: catch "publish root package.json" incident class before merge. Both lint + playbook docs create enforcement + education loop. - -### PR Review Batch β€” 10 Open PRs (2026-03-24) - -Reviewed all 10 open PRs for quality, test coverage, and merge readiness. - -**Critical finding β€” Duplicate/overlapping PRs (tamirdresher):** -- **PRs #607 / #605** overlap on retrospective ceremony β€” both add weekly retro ceremony with Ralph enforcement. #607 adds ceremony + enforcement skill + guide (444 lines), #605 modifies existing templates/ceremonies.md + ralph-reference.md (217 lines). Both solve the same problem (retro enforcement) with different file structures. #607 is more comprehensive (includes enforcement guide + pseudocode), #605 is more concise (inline in existing templates). **Verdict: Pick one** β€” recommend #607 (standalone ceremony file is more discoverable). -- **PRs #604 / #603** are complete duplicates β€” both add Challenger agent template + fact-checking skill. #604 has `templates/challenger.md` (153 lines), #603 has `.squad/templates/agents/challenger.md` + `.squad/skills/fact-checking/SKILL.md` (133 lines). File locations differ but content is nearly identical. **Verdict: Close one as duplicate** β€” recommend #603 (file locations match project conventions). -- **PRs #606 / #602** overlap on tiered memory/history β€” #606 adds tiered-memory skill (hot/cold/wiki tiers, 370 lines), #602 adds tiered-history skill (hot/cold split, 158 lines). #606 is broader (3 tiers, scribe integration, spawn templates), #602 is narrower (2 tiers, history.md only). Both cite same production data source. **Verdict: #606 supersedes #602** β€” recommend closing #602 as subset. - -**Quality assessment:** -- **PR #611 (TypeDoc API):** CI passing, large well-scoped PR (1569 additions), includes tests (Playwright), screenshots provided, PAO reviewed. Ready to merge pending PAO's requested fixes (crosslink banner, nav URL simplification). Quality: HIGH. -- **PR #608 (Security policy):** Trivial (28 lines), no tests needed, no CI configured. Adds SECURITY.md with standard vulnerability reporting text. Quality: ACCEPTABLE (minor typo: "timely manor" β†’ "timely manner"). -- **PR #592 (Enforcement wiring):** Well-documented (549 additions), adds missing step to hiring process + 3 appendices. CI passing, no code changes, docs-only. Quality: HIGH. -- **PR #567 (StorageProvider):** DRAFT status, clean implementation (321 additions), 18 tests passing, Wave 1 foundation PR (no call-site migration yet). Quality: HIGH, but keep as DRAFT until Wave 2 ready. - -**CI status:** 9/10 PRs have CI passing. #608 (security policy) has no CI configured on branch "patch-1" (external contributor branch). - -**Test coverage:** -- #611: Playwright tests included (8 tests) -- #607, #605, #604, #603, #606, #602: All docs-only, no tests needed -- #592: Docs-only, no tests needed -- #567: 18 tests included, all passing - -**Overlap resolution needed:** tamirdresher has 6 PRs, 3 pairs have significant overlap. Recommend: merge #607 (not #605), merge #603 (close #604), merge #606 (close #602). - -**Blocking issues:** -- None for mergeability β€” all non-overlapping PRs are technically ready -- Deduplication decision needed for tamirdresher's PRs before merging any of them - -### Community PR Batch Review β€” Post-Crash Recovery (2026-03-26) - -Reviewed 9 community PRs (8 from tamirdresher, 1 from eric-vanartsdalen). Key findings: - -1. **Changeset package name pattern:** 4 of 8 Tamir PRs (#623, #622, #621, #614) use unscoped `"squad-cli"` / `"squad-sdk"` instead of `"@bradygaster/squad-cli"` / `"@bradygaster/squad-sdk"`. Only #625 got this right. This is a recurring community contributor mistake β€” consider adding guidance to CONTRIBUTING.md or PR template. - -2. **File path pattern:** PRs #607 and #606 place files at root `ceremonies/`, `skills/`, `docs/`, `templates/` directories that don't exist. Skills belong in `packages/squad-cli/templates/skills/` and SDK equivalent. Community contributors don't know the monorepo layout. - -3. **Verdicts:** βœ… MERGE: #625 (notification-routing), #603 (Challenger agent), #608 (SECURITY.md). ⚠️ NEEDS CHANGES: #623, #622, #621, #614 (changeset fix), #607, #606 (path restructuring). - -**Learning:** Community contributors consistently struggle with two things: (a) scoped npm package names in changesets, and (b) monorepo file placement. Both are preventable with better contributor docs. - diff --git a/.squad/agents/flight/history.md b/.squad/agents/flight/history.md deleted file mode 100644 index acbc68be8..000000000 --- a/.squad/agents/flight/history.md +++ /dev/null @@ -1,187 +0,0 @@ -# Flight β€” Project History - -> Knowledge accumulated through leading Squad development. - ---- - -πŸ“Œ **Team update (2026-03-26T06:41:00Z β€” Crash Recovery Execution Complete):** Post-CLI crash recovery executed in 3 rounds. Round 1: Flight audited PR/issue state (found #617 merged, #619 conflicting, 3 dupes #605/#604/#602 open); FIDO verified baseline (5,038 tests βœ… green); Scribe merged stale inbox. Round 2: Flight closed 3 duplicate PRs with rationale; Procedures rebased PR #619 (model catalog) onto dev, resolved 3 merge conflicts, merged; FIDO reviewed 9 community PRsβ€”approved 3 (#625/#603/#608), requested changes on 6 (package naming, file paths). Round 3: Coordinator merged 3 approved PRs. **10 PRs merged total** (6 merge-plan, 3 community, 1 legacy #592). **3 PRs closed** as duplicates. **6 PRs awaiting author revisions**. **Dev branch green** (5,038 tests). All merge-plan sequence complete. Draft #567 parked pending requirements. Decision inbox merged to decisions.md and deleted. Next: Monitor change-request PRs for author responses. - -πŸ“Œ **Team update (2026-03-25T15:23Z β€” Triage Session & PR Review):** Flight triaged 14 untriaged GitHub issues, created prioritized work session plan. Identified high-value quick wins (P1): #610 (docs broken link, 5-min fix), #590 (getPersonalSquadRoot bug, P0), #591 (hiring wiring docs). Deferred community feature contributions (#601–#595) pending PR review. Categorized maintenance (P2) and questions for community. FIDO reviewed 10 open PRs, identified 3 duplicate/overlap pairs (6 PRs consolidate to 4: merge #607/#603/#606, close #605/#604/#602). Work session priority: #610β†’PAO, #590β†’EECOM, #592/#611β†’Flight review, #588β†’Procedures. Established PR review strategy: Tamir PRs require proposal-first discipline before review. Merge-ready identified: #611 (blocked on #610), #592 (joniba wiring guide, high-quality). A2A protocol PRs remain shelved. All 14 issues fully categorized with squad assignments. Decision inbox merged to decisions.md. Session complete; team ready for execution. - -πŸ“Œ **Team update (2026-03-23T22:00Z β€” Release Crisis Recovery):** v0.9.0β†’v0.9.1 incident resolved. Released v0.9.1 stable on npm after 8-hour debugging marathon (should have been 10 min). Root causes: dependency validation gap (file: refs in packages), GitHub workflow cache race, npm workspace publish automation broken, coordinator decision-making under pressure, no pre-publish verification. Created comprehensive retrospective with 5 root causes and 6 action items (A1–A6). Filed 9 GitHub issues (#556–#564) documenting release process improvements. Pre-flight job added to publish pipeline (dependency scanning + semver validation). Surgeon charter hardened with release governance rules. 10 community PRs merged (#569, #570, #571, #555, #552, #568, #572, #513, #573, #574). Discussion board fully triaged (15 discussions: 4 closed, 1 consolidated, 2 converted to issue, 8 kept). Dark mode fix deployed to production. Release process skill created at `.squad/skills/release-process/SKILL.md`. 9 GitHub issues filed for release improvements. Team ready for next cycle. - -πŸ“Œ **Team update (2026-03-22T09-35Z β€” Wave 1):** Ambient personal squad design validated and 19-task implementation plan authored across 4 PRs (Phase 1 SDK, Phase 2 CLI, Phase 3 governance, Phase 4 tests). MVP = PR #1 + PR #3. EECOM executing Phase 1–2 (SDK + CLI), Procedures executing Phase 3 (governance) concurrently. All design gaps resolved; dependency graph established. Procedures wrote governance proposals for personal squad + economy mode β€” awaiting your review. Sims to execute Phase 4 after Phase 1+2 merge. Directive captured: bug #502 (node:sqlite, P1) to be picked up after Wave 1. No blocking issues β€” ready for execution. - -## Core Context - -Three-branch model (main/dev/insiders). Apollo 13 team, 3931 tests. Boundary review heuristic: "Squad Ships It" β€” if Squad doesn't ship the code, it's IRL content. Proposal-first: meaningful changes need docs/proposals/ before code. Two-error lockout policy: agent locked out after 2 errors in a session. Test name-agnosticism: framework tests must never depend on dev team's agent names. - -## 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. - -### Remote Squad Access -Three-phase rollout: Phase 1 β€” GitHub Discussions bot with `/squad` command (1 day, zero hosting). Phase 2 β€” GitHub Copilot Extension via Contents API (1 week). Phase 3 β€” Slack/Teams bot (2 weeks). Constraint: any remote solution must solve `.squad/` context access. - -### Content Triage Skill -"Squad Ships It" litmus test codified into reusable workflow. Triggered by `content-triage` label. Output: boundary analysis, sub-issues for PAO (doc extraction), IRL reference for Scribe. Content labels: `content:blog`, `content:sample`, `content:video`, `content:talk`. - -### Distributed Mesh Integration -Zero code changes. Skill files in templates/skills/, scripts in scripts/mesh/, docs in features/. mesh.json stays separate from squad.config.ts. Convention-first additive layer β€” invisible if unused. 125:1 ratio (30 lines of script vs 3,756 lines of deleted federation code). - -### Sprint Prioritization Pattern -Rank by: (1) bugs with active user impact, (2) quality/test gaps blocking GA, (3) high-ROI features unblocking downstream work. Interleave stability (bugs/quality) with velocity (features) across sprint capacity. - -**Updated wisdom.md with 4 patterns + 2 anti-patterns from recent work:** Test name-agnosticism for team rebirths, dynamic filesystem discovery for evolving content, cli-entry.ts unwired command bug pattern, bump-build.mjs version mutation timing, invalid semver formats, git reset data loss. - -**Issue triage attempted for 30 open issues:** Identified 10 unlabeled issues requiring squad assignment. Enterprise Managed User permissions blocked GitHub API label updates via `gh issue edit`. Triage analysis complete: -- SDK issues (#337, #342) β†’ squad:eecom + squad:capcom (init flow + casting engine) -- Personal squad (#343, #344) β†’ squad:flight (architecture territory) -- A2A protocol (#332-336) β†’ squad:flight + domain experts (network, vox, retro, eecom) -- Tooling layers (#330) β†’ squad:eecom + squad:procedures -Manual label application needed by repo owner. - -**SDK Init Shore-Up PRD created:** Consolidated 6 SDK-related issues (#337-342, #340-341) into unified 3-phase initiative at `.squad/identity/prd-sdk-init-shoreup.md`. Root causes: config sync gap, built-in member exclusion (Ralph, @copilot), CastingEngine bypass. Solution: Phase 1 fixes gaps (P1), Phase 2 wires CastingEngine (P1), Phase 3 exercises full test matrix (P2). Estimated 4 sprints to 100% SDK feature parity. Owners: EECOM + CAPCOM (phases 1-2), FIDO + CAPCOM (phase 3). - -πŸ“Œ **Team update (2026-03-11T01:25:00Z):** Flight completed 30-issue triage + unified SDK Init Shore-Up PRD. CAPCOM + EECOM completed deep technical analysis + implementation roadmap. 5 decisions merged to decisions.md: Phase-based quality improvement program, CastingEngine canonical casting, squad.config.ts as source of truth, Ralph always-included, implementation priority order. - -### Issue Triage & PR Pipeline (2026-03-22) - -**Triaged 6 unlabeled issues:** Assigned to appropriate squad members per domain expertise and team capacity. Applied `next-up` label to 10 priority items (bugs, easy wins, docs improvements). All triaged issues now have clear ownership and next steps. - -**PR Pipeline:** Reviewed and rebased 8 PRs across EECOM, GNC, and PAO. All merged successfully. Key patterns documented for team reuse: -- **az CLI timeouts** (PR #483): External CLI calls need explicit timeouts + fallback handling -- **History race conditions** (PR #480): File operations require mutex + atomic writes + exhaustive tests -- **Signal handling** (PR #486): SIGINT cleanup needs two-layer approach (parent + child cleanup) -- **ESM exports** (PR #474): Node 22 compatibility requires exports map + file existence validation -- **Broken docs links** (PR #487): Automated link validation should be CI gate - -Test coverage expanded: 36 new tests (EECOM) + 4655+ total passing (GNC report). - -**Coordinator actions:** Filed #488 (GitHub auth documentation), created `next-up` label, labeled 10 priority issues for next sprint focus. -πŸ“Œ **Team update (2026-03-10T12-55-49Z):** Adoption tracking architecture finalized. Three-tier system approved: Tier 1 (aggregate-only, `.github/adoption/`) shipping with PR #326; Tier 2 (opt-in registry) designed for next PR; Tier 3 (public showcase) launches when β‰₯5 projects opt in. Append-only file governance rule enforced to prevent data loss. Microsoft ampersand style guide adopted for all user-facing documentation. - -### PR #331 Review β€” Boundary Review Pattern Reinforced (2026-03-10) -Approved PR #331 ("docs: scenario and feature guides from blog analysis") for merge. PAO's boundary review (remove external infrastructure docs, reframe platform features to clarify scope, keep Squad behavior/config docs) was executed correctly. Key decisions: (1) ralph-operations.md and proactive-communication.md deleted β€” both document infrastructure around Squad, not Squad itself; (2) issue-templates.md reframed to clarify "GitHub feature configured for Squad" not "Squad feature"; (3) reviewer-protocol.md Trust Levels section kept β€” documents user choice spectrum within Squad's existing review system. Litmus test pattern: if Squad doesn't ship the code/config, it's IRL content. Docs-test sync maintained. Pattern reinforced as reusable boundary review heuristic for future doc PRs. - -**Adoption tracking architecture β€” three-tier opt-in system:** `.squad/` is for team state only, not adoption data (boundary pattern). Move tracking to `.github/adoption/`. Never list individual repos without owner consent β€” aggregate metrics only until opt-in exists. Tier 1 (ship now) = aggregate monitoring. Tier 2 (design next) = opt-in registry in `.github/adoption/registry.json`. Tier 3 (launch later) = public showcase once β‰₯5 projects opt in. Monitoring infra (GitHub Action + script) is solid β€” keep it. Privacy-first architecture: code search results are public data, but individual listings require consent. - -**Remote Squad access β€” three-phase rollout:** Phase 1 (ship first): GitHub Discussions bot with `/squad` command. Workflow checks out repo β†’ has full `.squad/` context β†’ answers questions β†’ posts reply. 1 day build, zero hosting, respects repo privacy automatically. Phase 2 (high value): GitHub Copilot Extension β€” fetches `.squad/` files via GitHub API, answers inline in any Copilot client (VS Code, CLI, mobile). Works truly remote, instant, no cold start. 1 week build. Phase 3 (enterprise): Slack/Teams bot for companies. Webhook + GitHub API fetch. 2 weeks build. Constraint: Squad needs `.squad/` state (team.md, decisions.md, histories, routing) to answer intelligently. Any remote solution must solve context access. GitHub Actions workflows solve this for free (checkout gives full state). Copilot Extension uses Contents API. Discussions wins for MVP because it's async (perfect for knowledge queries), persistent (answers are searchable), and zero infra. Proposal-first: write `docs/proposals/remote-squad-access.md` before building. - -### Content Triage Skill Codified (2026-03-10) -Created `.squad/skills/content-triage/SKILL.md` to codify the boundary heuristic from PR #331. Defines repeatable workflow for triaging external content (blog posts, sample repos, videos, talks) to determine what belongs in Squad's public docs vs IRL tracking. Key components: (1) "Squad Ships It" litmus test β€” if Squad doesn't ship the code/config, it's IRL content; (2) triage workflow triggered by `content-triage` label or external content reference in issue body; (3) output format with boundary analysis, sub-issues for PAO (doc extraction), and IRL reference entry for Scribe; (4) label convention (`content:blog`, `content:sample`, `content:video`, `content:talk`); (5) Ralph integration for routing to Flight, creating sub-issues, and notifying Scribe. Examples include Tamir blog analysis (PR #331), sample repo with ops patterns, and conference talk. Pattern prevents infrastructure docs from polluting Squad's public docs while ensuring community content accelerates adoption through proper extraction and referencing. - -πŸ“Œ **Team update (2026-03-11T01:27:57Z):** Content triage skill finalized; "Squad Ships It" boundary heuristic codified into shared team decision (decisions.md). Remote Squad access phased rollout approved (Discussions bot β†’ Copilot Extension β†’ Chat bot). PR #331 boundary review pattern established as standard for all doc PRs. Triage workflow enables Flight to scale as community content accelerates. - ---- - -### Issue Triage β€” 6 Unlabeled Issues Routed (2026-03-20) - -Triaged and labeled 6 unlabeled issues using routing table: - -- **#485 (Agent Specification PRD)** β†’ squad:flight + squad:procedures β€” Architecture decision (Flight) + formal spec structure (Procedures) -- **#481 (StorageProvider PRD)** β†’ squad:control + squad:eecom β€” Type system abstraction (CONTROL) + runtime integration (EECOM) -- **#479 (history-shadow race condition)** β†’ squad:eecom + squad:retro β€” Production data loss bug; mitigation through StorageProvider atomicity -- **#478 (Polish REPL)** β†’ squad:vox + squad:pao β€” Shell UX readiness (VOX) + README documentation gate (PAO) -- **#477 (Code Quality Linting PRD)** β†’ squad:fido β€” Monorepo async/promise quality, ESLint 9 PoC ready -- **#476 (Guide v0.4.1 update)** β†’ squad:handbook + squad:pao β€” SDK patterns + documentation - -Key pattern: PRDs cluster around three architectural gaps (agent spec, state abstraction, quality tooling) + one production bug (#479). Guide update high community value. -### Ambient Personal Squad Architecture Review (#329 + #344) - -**Design validated:** The `flight-ambient-personal-squad.md` proposal is structurally sound. Key finding: `multi-squad.ts` already stores personal squad paths as direct dirs (`squads/{name}/`) with no nested `.squad/` subfolder β€” the "each team IS the squad root" convention is already the implementation, not a change needed. - -**Five gaps found in the design doc:** -1. No `resolvePersonalAgents()` function signature β€” added in implementation plan (T2). -2. Scenario 9 contradiction: personal agents wrote to project orchestration log, violating ghost protocol. Resolution: coordinator writes audit trail (project state), not the personal agent. -3. `--team-root` scope was undefined. Decision: additive CLI flag on `squad init`, backward compat with existing `config.json` teamRoot. -4. `squad personal init` was missing β€” bootstrapping path for first-time users. Added as T6 subcommand. -5. `SQUAD_NO_PERSONAL` env var was in Open Questions but absent from phases. Added to T1. - -**Architecture decision:** Need `ensureSquadPathTriple` in `resolution.ts` (T4) β€” personal agents write to a third root (personal squad dir). Without it, ghost protocol is advisory-only and not enforced by path guards in SDK. - -**Phasing:** Four PRs. MVP = PR #1 (SDK Foundation) + PR #3 (Governance). Users see ambient cast immediately; `squad personal` commands are quality-of-life on top. - -**Implementation plan written to:** `.squad/decisions/inbox/flight-329-344-implementation-plan.md` - -πŸ“Œ **Team update (2026-03-24):** Ambient personal squad design reviewed and approved with 5 gaps identified and resolved. Implementation plan broken into 4 PRs across EECOM (SDK + CLI), Procedures (governance), and Sims (tests). MVP path = SDK foundation + governance updates. Phased to avoid one giant PR. - -### Session 2 Summary (2026-03-22) - -Wave 1 architecture work on #329/#344: validated 20KB personal squad design doc, identified and patched 5 gaps, authored 19-task implementation plan spanning 4 future PRs. Implementation not yet started β€” deferred to future session. EECOM assigned Phase 1–2 (SDK + CLI), Procedures assigned Phase 3 (governance), Sims assigned Phase 4 (tests). - -### Community PR Batch Review β€” July 2026 - -Five open community PRs reviewed: - -- **#524 (diberry)** β€” Astro docs improvements (sitemap, RSS, schema fields, ToC component, robots.txt). βœ… Merge-ready. Flag: `robots.txt` Sitemap URL points to `squad.dev` while `astro.config.mjs` still uses `bradygaster.github.io` β€” minor URL inconsistency to address. -- **#523 (diberry)** β€” Worktree-aware `detectSquadDir` + `resolveWorktreeMainCheckout` + init guard. βœ… Merge-ready. Directly addresses the worktree gap flagged in #525. Clean implementation; interactive TTY prompt with sensible default. -- **#522 (tamirdresher)** β€” Rate limiting/circuit breaker watch integration. πŸ”„ Still a full rewrite of watch.ts. Brady's CHANGES_REQUESTED (additive patch, not full file replacement) has NOT been addressed. Same structural concern remains. -- **#513 (tamirdresher)** β€” Cross-machine-coordination SKILL.md. πŸ”„ Wrong directory (`.squad/skills/` is team-state; generic library content belongs in `templates/skills/`). Personal use case examples (voice cloning, DevBox) should be generalized. Needs `docs/proposals/` entry per proposal-first policy. -- **#507 (JasonYeYuhe)** β€” Chinese README translation. πŸ”„ Needs a community-maintained freshness disclaimer before merging. Translation quality looks solid; the maintenance burden concern is the only gate. - -**Patterns noted:** -- Diberry (MSFT) is delivering consistent, architecturally-sound contributions β€” both PRs are merge-ready. -- Tamir's contributions are technically strong but need delivery discipline (full-rewrite vs. surgical patch, proposal-first for new primitives). -- Community translations are welcome but need a sustainability framing before merge. - -### Worktree Gap Triage β€” #525 (2025-07-18) - -Community contributor joniba filed #525 identifying that Squad has full worktree *detection* but zero worktree *creation* in the coordinator/spawn flow. Validated all 10 claims β€” analysis is accurate. The reading infrastructure (resolveSquad() worktree detection, .gitattributes merge=union, boundary tests) is ~95% complete. The gap: ralph-commands.ts hardcodes `git checkout -b` in all 3 platform adapters (lines 50/71/92), coordinator never creates worktrees before spawn, no WORKTREE_PATH in prompts, and issue-lifecycle.md is referenced in squad.agent.md but doesn't exist. - -**Decision:** P2 β€” important but not v1-blocking. Broke into 5 sub-issues: (1) doc fix for missing issue-lifecycle.md (quick win β†’ Procedures), (2) worktree variant in ralph-commands.ts (EECOM), (3) coordinator pre-spawn logic (Procedures + EECOM), (4) post-merge cleanup (EECOM), (5) architecture decision on heuristic (Flight). Sub-issue #1 ships immediately; #2–5 queue post-Wave-1 alongside SubSquads work where parallel execution becomes a hard requirement. - -**Backlog priority recommendation:** Top 5 for v1 = #508 (Ambient Personal Squad), #498 (remove .squad/ from VCS), #485 (Agent Spec & Validation), #481 (Typed StorageProvider), #347 (shore up init --sdk). Quick wins: #525 doc fix, #347. Deprioritize: manual verification debt (#418–421), long-term exploratory. A2A (#332–336) stays shelved per existing decision. - -### Release Hardening Plan β€” Finalized (2026-07-22) - -Brady approved scope for remaining v0.9.1 incident hardening. Three issues to execute, three deferred into umbrella: - -**DO:** #564 (rewrite PUBLISH-README.md as living playbook β€” absorbs #558, #559, #560), #557 (CI lint rule rejecting non-workspace `npm publish` in workflow YAML), #562 (delete ghost workflow `publish-npm.yml` ID 250121956). - -**DEFERRED into #564:** #560 (pre-flight checklist β†’ playbook section), #559 (fallback protocol β†’ playbook section), #558 (422 race docs β†’ playbook section). - -**Key findings:** -- GitHub REST API has NO "Delete a workflow" endpoint. Ghost workflows only disappear when all their runs are deleted (GitHub GC). Procedure: `gh api` to list+delete all runs for workflow ID 250121956, then wait for GC. -- The lint rule goes in `squad-ci.yml` as a `publish-policy` job: scans `.github/workflows/*.yml` for `npm publish` without `-w` flag. Blocks PR merge if violated. -- PUBLISH-README.md playbook has 11 sections covering pre-flight, CI publish, manual fallback, 422 race conditions, insider channel, workspace policy, post-publish verification, and version bumping. Replaces the stale v0.8.22 stub entirely. - -**Execution order:** #562 (Brady, manual API call) and #557 (FIDO/Procedures, CI change) run in parallel. #564 (Procedures+Surgeon, playbook) goes last so it can reference the lint rule. - -Decision written to `.squad/decisions/inbox/flight-release-hardening-plan.md`. - -### Issue Triage Session β€” 14 Untriaged Issues (2026-03-24) - -**Triaged 14 issues + 10 PRs:** 3 docs issues, 6 community feature proposals, 3 bugs, 2 questions. Key findings: - -**P0 Bug (immediate):** -- #590 (getPersonalSquadRoot) β†’ squad:eecom β€” personal squad broken since v0.9.1, affects all `squad consult` on new repos - -**P1 Quick Wins:** -- #610 (broken docs link) β†’ squad:pao β€” 5-minute fix, unblocks diberry PR #611 CI -- #591 (hiring wiring docs) β†’ squad:procedures β€” matches PR #592 (joniba), high-quality wiring guide ready to merge - -**Community PRs (proposal-first enforcement):** -- Tamir PRs #602-607 (6 PRs) β€” high technical quality but missing proposal-first compliance. Need `docs/proposals/` entries before review. -- Joniba PR #592 β€” merge-ready, validates enforcement wiring gap -- Diberry PR #611 β€” blocked on #610 fix, then merge - -**P2 Maintenance:** -- #597 (upgrade CLI docs) β†’ squad:pao + squad:network -- #588 (model list update) β†’ squad:procedures -- #554 (broken external links) β†’ squad:pao - -**Deferred/Questions:** -- #581 (ADO PRD) β†’ P2, blocked until #341 SDK-first parity ships -- #589, #494 β†’ community replies clarifying skill paths and model selection - -**Pattern:** Tamir is a high-output contributor (6 PRs in 2 weeks) but needs proposal-first discipline. Joniba and diberry deliver MSFT-level quality. - -Decision written to `.squad/decisions/inbox/flight-triage-session-plan.md`. diff --git a/.squad/agents/gnc/history.md b/.squad/agents/gnc/history.md deleted file mode 100644 index 4ca0ecab6..000000000 --- a/.squad/agents/gnc/history.md +++ /dev/null @@ -1,25 +0,0 @@ -# GNC - -> Guidance, Navigation, and Control Officer - -## Learnings - -### ESM Compatibility Layer -@github/copilot-sdk@0.1.32 has broken ESM import (session.js uses 'vscode-jsonrpc/node' missing .js extension). Two-layer fix: (1) lazy-load copilot-sdk so init/build/watch don't trigger it, (2) postinstall patch in packages/squad-cli/scripts/patch-esm-imports.mjs. Runtime Module._resolveFilename patch in cli-entry.ts for npx where postinstall doesn't run. - -### Node Version Requirements -Node.js β‰₯20 required. Node 24+ enforces strict ESM resolution (no extensionless imports). cli-entry.ts has runtime check that warns about node:sqlite availability (β‰₯22.5.0). - -### PR #474 Review & Merge β€” Node 22 ESM Fix (2026-03-22) - -Reviewed and merged PR #474 (Node 22 ESM compatibility + bonus exports key fix). Addresses module resolution failures on Node 22 strict ESM enforcement. - -**Fix pattern:** Node 22 ESM compatibility requires two checks: (1) explicit exports map in package.json (exports key with conditions), (2) actual module paths must match exports map entries. Mismatch between declared exports and actual files causes MODULE_NOT_FOUND errors. Build-time validation: check that every exports entry points to a file that exists. - -**Key learning:** ESM exports key and actual module structure must stay in sync. When adding new entry points, update both package.json (exports) and create the corresponding module file. Missing either step breaks consumers on Node 22+. Test matrix must include Node 22+ to catch these errors early. -### Dual-Layer ESM Fix (Issue #449) -Upgraded from single-layer session.js patch to dual-layer approach: (1) Inject `exports` field into vscode-jsonrpc@8.2.1 package.json at postinstall β€” this is the canonical fix that resolves ALL subpath imports at once, matching vscode-jsonrpc v9.x. (2) Keep session.js `.js` extension patch as defense-in-depth. Added `squad doctor` detection for both layers (checks vscode-jsonrpc exports field and copilot-sdk session.js import syntax). Runtime Module._resolveFilename patch in cli-entry.ts remains as Layer 3 for npx cache hits where postinstall never runs. - -πŸ“Œ **Team update (2026-03-25T18:11Z):** Routing regression research complete β€” root cause identified as combination of Squad code changes (v0.9.0 prompt saturation +33%, inlined workflows, missing -ame param in templates #577) AND Copilot CLI platform changes (CAPCOM report). Coordinator prompt grew 711β†’946 lines, diluting routing constraint. Workstream config replacement broke existing routing. Agent name fix exists on dev (#577) but not shipped. Recommendations: ship #577 immediately, move features to skills, optimize coordinator prompt, create regression tests. Report in decisions inbox. - diff --git a/.squad/agents/handbook/history.md b/.squad/agents/handbook/history.md deleted file mode 100644 index 849f85879..000000000 --- a/.squad/agents/handbook/history.md +++ /dev/null @@ -1,16 +0,0 @@ -# Handbook - -> SDK Patterns & Best Practices - -## Learnings - -### Issue Triage (2026-03-22T06:44:01Z) - -**Flight triaged 6 unlabeled issues and filed 1 new issue.** - -Handbook assigned: -- **#476 (Guide v0.4.1 update)** β†’ squad:handbook + squad:pao (SDK patterns refresh + documentation) - -Pattern: Guide update identified as high community value initiative. Handbook owns SDK patterns refresh; PAO owns documentation scaffolding. - -πŸ“Œ **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. Handbook owns Guide v0.4.1 patterns update (#476). High community interest. Coordinate with PAO on guide structure and with VOX on REPL examples for integration. diff --git a/.squad/agents/inco/history.md b/.squad/agents/inco/history.md deleted file mode 100644 index 90c7f08f0..000000000 --- a/.squad/agents/inco/history.md +++ /dev/null @@ -1,16 +0,0 @@ -# INCO - -## Core Context - -Terminal flicker fix cherry-picked from main to dev β€” PR #405 merged (March 2026). -> UX Engineer & Interaction Designer - -## Learnings - -### Animation Performance Trade-offs (PR #310) -Scroll flicker fix required careful animation frame budget management. Slowdown accepted as trade-off for visual clarity and stable viewport rendering. Version footer suggestion considered for animation frame transparency. - ---- - -πŸ“Œ **Team update (2026-03-10T14-44-23Z):** PR #310 scroll flicker fix merged. 4 root causes identified by Flight: Ink clearTerminal issue, timer amplification, log-update trailing newline, unstable Static keys. Postinstall patch pattern adopted for Ink internals. Version pin recommended for stability gate. - diff --git a/.squad/agents/network/history.md b/.squad/agents/network/history.md deleted file mode 100644 index f979f9859..000000000 --- a/.squad/agents/network/history.md +++ /dev/null @@ -1,22 +0,0 @@ -# Network β€” History - -> Distribution specialist. Installation should be invisible. - -## Learnings - -### Template Placement Pattern (2026-03-15) - -Template placement: canonical skill source is `.squad/skills/`, copies to `packages/*/templates/skills/` for npm distribution. Root `templates/` is NOT used by SDK/CLI init code. The build process now auto-syncs from canonical to packages via `scripts/sync-skill-templates.mjs`, preventing divergence. Old locations (`templates/skills/distributed-mesh/`, `templates/mesh/`) removed β€” they were never referenced and contributed to maintenance burden. - -### Distributed Mesh Template Placement (2026-03-08) - -Placed the distributed-mesh skill and scaffolding files in the template structure. Three parallel template locations (root, SDK, CLI) receive the SKILL.md. The mesh/ directory holds the sync scripts and config example. This follows the existing pattern where product-shipped skills go in all three template dirs so both init paths (`squad-sdk` and `squad-cli`) can scaffold them into new projects. - -The sync scripts (~40 lines each, bash and PowerShell) materialize remote squad state locally using git/curl. No daemons, no running processes. This is Phase 1 distributed coordination β€” git pull/push with write partitioning. - -### Mesh State Repo Init Mode (2026-03-08) - -Added `--init` flag to sync scripts for scaffolding mesh state repositories. When users run `sync-mesh.sh --init` or `sync-mesh.ps1 -Init`, the scripts read mesh.json and generate the directory structure: squad folders with placeholder SUMMARY.md files, plus a root README listing participants. Idempotent β€” skips existing files. This removes the manual setup step when creating a new mesh state repo. The init path adds ~40 lines but keeps sync logic unchanged. - -πŸ“Œ Team update (2026-03-14T22-01-14Z): Distributed mesh integrated with deterministic skill pattern β€” decided by Procedures, PAO, Flight, Network - diff --git a/.squad/agents/pao/history.md b/.squad/agents/pao/history.md deleted file mode 100644 index 21d9f7fef..000000000 --- a/.squad/agents/pao/history.md +++ /dev/null @@ -1,287 +0,0 @@ -# PAO - -> Public Affairs Officer - -## Core Context - -Docs live in docs/ with blog/, concepts/, cookbook/, getting-started/, guide/, features/, scenarios/ sections. Blog tests use filesystem discovery (dynamic); other sections use hardcoded expected arrays. Microsoft Style Guide enforced: sentence-case headings, active voice, second person, present tense. Docs format: plain markdown, H1 title, experimental warning, "Try this" code blocks, overview, HR, H2 content sections. Scannability framework: paragraphs for narrative, bullets for scannable items, tables for comparisons. - -## 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. - -### Boundary Review Heuristic -"Squad Ships It" litmus test: if Squad doesn't ship the code/config, it's IRL content. Platform features used alongside Squad: clarify whose feature it is. Squad behavior/config docs stay. External infrastructure docs (ralph-operations, proactive-communication) β†’ IRL. - -### DOCS-TEST SYNC -When adding docs pages, update test assertions in docs-build.test.ts in the SAME commit. When rebasing doc PRs, main branch (already merged) takes priority. - -### Contributor Recognition -CONTRIBUTORS.md tracks team roster and community contributors. Each release includes recognition updates. Append PR counts, don't replace. - -### Skill Scope Documentation Pattern -Explicitly state what a skill produces and does NOT produce. Deterministic skills prevent agents from generating unnecessary code when templates exist. - -### Teams MCP Audit -External tool integrations require explicit "where to get it" guidance. Placeholder paths need clarification that users must provide actual MCP server implementations. - -### Cross-Org Authentication Docs -Problem/solution structure for multi-account auth: gh auth switch, Copilot instructions, Squad skill pattern. Cover credential helpers, EMU variations, common error messages. Cross-reference in troubleshooting and enterprise-platforms pages. - -### Roster & Contributor Recognition (v0.8.25) -Squad moved to Apollo 13/NASA Mission Control naming scheme (Flight, Procedures, EECOM, FIDO, PAO, CAPCOM, CONTROL, Surgeon, Booster, GNC, Network, RETRO, INCO, GUIDO, Telemetry, VOX, DSKY, Sims, Handbook). CONTRIBUTORS.md tracks both team roster and community contributors; contributor table entries grow with PRs (append PR counts rather than replace, maintaining attribution history). - -### Git Rebase for Doc Merges -When rebasing doc PRs with conflicts from other merged doc PRs, the main branch version (already merged) should generally take priority. For Node.js version references, maintain LTS terminology when present (e.g., `nvm install --lts` over specific version numbers like `nvm install 20`). Conflict resolution pattern: preserve new content from PR branch only where it doesn't duplicate or contradict already-merged changes. Use `git -c core.editor=true rebase --continue` to bypass interactive editor issues on Windows. - -### Astro Docs Format (v0.8.26) -Squad docs use plain markdown without Astro frontmatter. Structure: title (H1), experimental warning callout, "Try this" code blocks at top, overview paragraph, horizontal rule, then content sections with H2 headings. Microsoft Style Guide enforced: sentence-case headings, active voice, second person ("you"), present tense, no ampersands except in code/brand names. Features and scenarios directories added to test coverage in docs-build.test.ts. Reference implementations linked where available (e.g., ralph-watch.ps1 for operational patterns). - -### Proactive Communication Patterns (v0.8.26) -Two-way communication layer between Squad and work environment. Outbound: Teams webhook notifications (breaking, briefings, recaps, flashes) sent via Adaptive Cards β€” only when newsworthy. Inbound: WorkIQ/Playwright scanning of Teams channels and email β†’ auto-create GitHub issues with teams-bridge label, anti-duplicate logic enforced. Loop: inbound creates issues β†’ Ralph dispatches β†’ agents work β†’ outbound notifies results. Human stays informed on mobile. Prerequisites are enhancements, not requirements. - -πŸ“Œ **Team update (2026-03-11T01:27:57Z):** Proactive communication patterns and PR trust levels (full/selective/self-managing spectrum) documented in decisions.md. Pattern rationale reinforced: Ralph 24/7 autonomous deployment requires awareness loop (Teams webhooks for outbound) and external work integration (WorkIQ scanning for inbound). Trust levels enable context-appropriate oversight without bottlenecking teams. - -### PR #487 Review & Merge β€” CLI Docs Expansion (2026-03-22) - -Reviewed and merged PR #487 (CLI documentation expansion + broken docs link fix). Improved CLI command reference coverage and fixed internal link validation. - -**Pattern identified:** Broken internal links hurt user navigation and SEO. Recommendations: (1) add link validation to docs build pipeline (crawl all internal references, report 404s), (2) make validation a CI gate (fail build on broken links), (3) maintain link checklist when refactoring docs structure. - -**Key learning:** Documentation maintenance requires systematic link validation. A single broken link creates friction for users following guides. Automated validation should be non-negotiable in CI/CD. - -### PR #482 Review & Merge β€” Pagefind Search Integration (2026-03-22) - -Reviewed and merged PR #482. Search functionality integrated into docs site for improved discoverability. - -### PR #11 Docs Quality Review β€” TypeDoc API Reference (2026-03-24) - -**Status:** REQUEST CHANGES (3 fixes required, 2 recommended) - -**Key findings:** -- **Research + PRD:** Excellent quality. Clear problem statement, realistic effort estimate, pragmatic tool choice (TypeDoc over Starlight/api-extractor). Scannability framework applied correctly (tables for audit data, bullets for findings, paragraphs for narrative). -- **Navigation strategy:** Collapsible `
` approach for 395-page API reference is sound UX. Sidebar nav plan well-structured with clear open questions about CI/CD safety. -- **Microsoft Style compliance:** Mostly strong; discovered 3 minor issues. - -**Issues found:** -1. **πŸ”΄ Blocking:** sdk.md crosslink banner missing. Users navigating from curated "SDK" guide have no callout to the auto-generated "API Reference". Add "See Also" link in sdk.md before "## Resolution" section. -2. **πŸ”΄ Blocking:** Navigation URL inconsistency. `navigation.ts` hardcodes `reference/api/index` when it should be `reference/api` β€” Astro resolves `/api/` to `/api/index` automatically. Simplify slug. -3. **🟑 Blocking:** Nav plan's "Open Questions" section asks about CI/CD fallback (generated JSON missing). Plan should either specify build order (`docs:api` before `docs build`) or provide fallback empty nav for fresh clones. -4. **🟑 Recommended:** 2–3 test descriptions need more specificity (e.g., "class page renders heading and content" β†’ "class page renders method signatures and definition source"). -5. **🟑 Recommended:** Screenshot filenames don't align with skill convention. Use semantic names: `api-reference-landing`, `api-class-detail`, `api-function-detail`. - -**Pattern identified:** Generated documentation requires crosslinks from curated guides. When adding a new docs section (API reference, CLI reference, etc.), ensure the *old* curated page (SDK Guide) has a visible pointer to the new section. This prevents users from stopping at the curated version and missing the comprehensive auto-generated reference. - -**Effort to fix:** < 2 hours. All issues are surgical edits to existing content; no architectural changes needed. - -### PR #484 Review & Merge β€” Sample READMEs (2026-03-22) - -Reviewed and merged PR #484. Sample README templates added to improve consistency across documentation examples. - -### PR Trust Model Documentation (v0.8.26) -Three trust levels for PR management: (1) Full review (default, team repos) β€” human gate on every merge; (2) Selective review (personal projects with patterns) β€” human reviews only critical paths; (3) Self-managing (solo personal repos only) β€” Squad merges own PRs, human reviews retroactively. Added to reviewer-protocol.md as new section. Important: self-managing β‰  unmonitored; use Ralph work monitoring and Teams notifications for awareness. Decision matrix included for when to use each level. - -### Final Docs Review Pattern (v0.8.26) -Pre-PR quality reviews check: (1) Microsoft Style Guide compliance (sentence-case headings, active voice, no ampersands, present tense, second person); (2) Tone consistency (practical, developer-focused, no hype); (3) Technical accuracy (code examples, file paths, commands); (4) Cross-reference integrity (valid links between pages); (5) DOCS-TEST SYNC (test assertions match new pages); (6) Privacy directive compliance (no individual repos without consent). Fixed duplicate section heading in reviewer-protocol.md (merge artifact). All staged docs passed review and are ready to commit. - -### Squad vs IRL Boundary Review (v0.8.26) -Evaluated four docs pages from PR #331 (Tamir's blog analysis) against Squad-specificity criterion: does content document Squad features/patterns (belongs in Squad docs) or community implementation examples (belongs in Squad IRL)? Key distinction: Squad docs = "how the feature works + universal best practices" vs IRL = "how one person built an amazing setup." Results: ralph-operations.md borderline (deployment wrappers are external infrastructure, not Squad features β€” trim "outer loop" framing), issue-templates.md borderline (GitHub feature documented for Squad context, not Squad code β€” clarify scope), proactive-communication.md does not belong (community extension pattern using WorkIQ/Playwright, not built into Squad), reviewer-protocol.md trust levels section belongs (documents user choice spectrum within Squad's existing review system). Pattern: if Squad doesn't ship the code, it's IRL content; if it's a GitHub platform feature used alongside Squad, clarify that distinction; if it documents actual Squad behavior/configuration, it belongs. - -### Boundary Review Execution (v0.8.26) -Executed boundary review findings from PR #331: (1) Deleted ralph-operations.md (infrastructure around Squad, not Squad itself β€” moved to IRL); (2) Deleted proactive-communication.md (external tools/webhooks β€” moved to IRL); (3) Reframed issue-templates.md intro to clarify "GitHub feature configured for Squad" not "Squad feature"; (4) Updated EXPECTED_SCENARIOS in docs-build.test.ts to match remaining files. Pattern reinforced: boundary review = remove external infrastructure docs, reframe platform integration docs to clarify whose feature it is, keep Squad behavior/config docs. Changes staged for commit. - -### Cross-Org Authentication Docs (v0.8.26) -Created docs/src/content/docs/scenarios/cross-org-auth.md covering GitHub personal + Enterprise Managed Users (EMU) multi-account auth. Three solutions documented: (1) gh auth switch for manual account toggling; (2) Copilot instructions (.github/copilot-instructions.md) for account mapping documentation; (3) Squad skill pattern for auth error detection and recovery. Covered git credential helpers (per-host and per-org), EMU hostname variations (github.com vs dedicated instances), and common error messages (HTTP 401, authentication required). Added cross-references in troubleshooting.md (new section), enterprise-platforms.md (authentication section), and navigation.ts. Updated test/docs-build.test.ts with 'cross-org-auth' in EXPECTED_SCENARIOS. Pattern: Microsoft Style Guide (sentence-case), "Try this" prompts at top, problem/solution structure, practical examples over abstractions, links to related pages at bottom. - -### Scannability Framework (v0.8.25) -Format selection is a scannability decision, not style preference. Paragraphs for narrative/concepts (3-4 sentences max). Bullets for scannable items (features, options, non-sequential steps). Tables for comparisons or structured reference data (config, API params). Quotes/indents for callouts/warnings. Decision test: if reader hunts for one item in a paragraph, convert to bullets/table. This framework is now a hard rule in charter under SCANNABILITY REVIEW. - -### Docs Catalog Audit (2026) -Full audit of the Astro-based docs site. Key patterns and findings: - -**Orphaned pages (exist but not in navigation.ts):** 15 total β€” `get-started/choose-your-interface.md`, `guide/faq.md`, `guide/build-autonomous-agent.md`, `guide/github-auth-setup.md`, `features/built-in-roles.md`, `features/context-hygiene.md`, `features/cost-tracking.md`, `features/issue-templates.md`, `reference/vscode-troubleshooting.md`, and 6 root-level legacy files (`guide.md`, `sample-prompts.md`, `tips-and-tricks.md`, `tour-first-session.md`, `tour-github-issues.md`, `tour-gitlab-issues.md`). - -**Stale content:** `whatsnew.md` reports v0.8.2 as current; actual is v0.8.26+. `insider-program.md` uses deprecated `npx github:` install format and references old `.ai-team/` directory name throughout. - -**Duplicate/overlap pairs:** `choosing-your-path.md` (in nav) vs `choose-your-interface.md` (orphan, more complete); root-level `sample-prompts.md` vs `guide/sample-prompts.md`; root-level `tips-and-tricks.md` vs `guide/tips-and-tricks.md`; root-level `tour-first-session.md` vs `get-started/first-session.md`. - -**Content quality:** All actively-navved pages are well-written, follow Microsoft Style Guide, and use correct install commands. Format standards (H1, experimental callout, "Try this" block, HR, H2 sections) are inconsistently applied β€” some orphaned pages like `built-in-roles.md` and `cost-tracking.md` lack the standard header/callout pattern. - -**Structural issues:** `features/team-setup.md` has a duplicate `## How Init Works` heading (merge artifact). `features/streams.md` nav title is "Streams" but H1 is "Squad SubSquads" (mismatch). `guide/faq.md` is a high-value page completely invisible from the sidebar. `features/built-in-roles.md` is a comprehensive roles reference also invisible from nav. - -**Gap:** No dedicated FAQ entry point, no changelog page, cookbook section is thin (one page), no user-facing explanation of the NASA Mission Control naming scheme for agents. - -**Navigation:** Zero dead nav links (every nav slug has a matching file). All orphan pages are linked internally from other pages so they are reachable β€” but not browseable via sidebar. - -πŸ“Œ **Team update (2026-03-22T12:46:00Z):** Booster implemented automated version sync for `whatsnew.md` (finding #1). Script reads `package.json` version, updates "Current Release" heading on every prebuild, with Vitest test gate. Heading now correct (v0.8.25+), will stay in sync automatically on all future builds. Finding #1 resolved. - -### JSDoc API Reference Research (2026-03-23) - -Completed research on generating JSDoc-based API reference documentation for Squad SDK. Key findings: - -**Current State:** Squad SDK has 60–80% JSDoc coverage across major modules (state: 81%, config: 8%). 136 TypeScript source files, no existing TypeDoc config. - -**Tool Recommendation:** **TypeDoc + typedoc-plugin-markdown** β€” no Starlight migration needed. Seamless integration with existing Astro 5 + Tailwind 4 + Pagefind. Markdown output drops directly into content collections. Auto-generates via Astro integration hook on `npm run build`. - -**Alternatives Evaluated:** -- ❌ Starlight migration: would break existing docs structure and custom branding -- ❌ api-extractor: overkill for open-source SDK; designed for strict monorepo contracts - -**Effort Estimate:** 5–6 hours (setup only) β†’ 13–18 hours (setup + JSDoc improvements) β†’ 15–22 hours (with CI/CD automation). - -**StorageProvider & State Module:** Phase 2 state layer is API-docs ready (81% coverage, well-structured types, clear interface contract). Gaps: add @param/@return tags to state/io functions. - -**URL Structure:** `/api/classes/squad-coordinator/`, `/api/interfaces/storage-provider/`, etc. Pagefind indexes automatically. - -**Deliverable:** Full research at `docs/research/jsdoc-api-reference-research.md` with configuration templates, implementation roadmap (4 phases), and tool comparison matrix. Decision summary at `.squad/decisions/inbox/pao-jsdoc-research.md`. - -### Issue Triage (2026-03-22T06:44:01Z) - -**Flight triaged 6 unlabeled issues and filed 1 new issue.** - -PAO assigned: -- **#488 (GitHub auth setup for project boards)** β†’ squad:pao (documentation, newly filed) -- **#478 (Polish REPL)** β†’ squad:vox + squad:pao (shell UX readiness + README documentation gate) -- **#476 (Guide v0.4.1 update)** β†’ squad:handbook + squad:pao (SDK patterns + documentation) - -New issue #488 is documentation-focused; Fleet relabeled from squad:fido β†’ squad:pao for proper domain ownership. - -πŸ“Œ **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. PAO owns GitHub auth docs (#488), REPL documentation gate (#478), and Guide v0.4.1 refresh (#476). High community value on Guide update. Ready to begin documentation work on next sprint. -### npx Purge + Agency Audit -Brady's distribution directive: `npm install -g @bradygaster/squad-cli` is the only supported install path. Remove ALL user-facing `npx @bradygaster/squad-cli` and `npx github:bradygaster/squad` references from docs. Replace with either `npm install -g` (for install steps) or `squad ` (for usage steps). Keep `npx` only for dev tools (changeset, vitest, astro, pagefind). Keep historical blog posts as-is. Migration.md "Before" column and CI/CD "OLD" examples are valid historical context β€” keep them. Insider program: `npm install -g @bradygaster/squad-cli@insider` and `squad upgrade` replace the old `npx github:bradygaster/squad#insider`. Agency audit: all "agency-agents" references in source files and docs are MIT attribution for the upstream open-source project β€” legally required, never touch them. The `agency copilot` example in cli-entry.ts help text was a competing-product reference β€” changed to `gh copilot`. - -### README Slimming + Upgrade Section (v0.8.x) -Brady directive: README was too long at 512 lines. Cut the SDK deep-dive block (custom tools, hook pipeline, Ralph API code) and replaced it with a compact pointer to the docs site. Added a dedicated "Upgrading" section (two-step: `npm install -g` then `squad upgrade`) after Quick Start. Final length: 331 lines. SDK internals live in `docs/src/content/docs/reference/sdk.md` and `tools-and-hooks.md`. The README is now discovery/orientation; the docs site is the full reference. - -### 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. - -### Release Playbook Rewrite (#564, 2026-07-22) - -**Task:** Rewrite PUBLISH-README.md from a v0.8.22 version-specific stub (58 lines) into a living, version-agnostic release playbook. - -**Outcome:** 232-line playbook replacing entirely with 11 sections per Flight's spec: -1. Overview β€” two publish channels, package order (SDK β†’ CLI) -2. Pre-Flight Checklist β€” runnable checklist with `grep`/`npm` commands -3. Publish via CI (Recommended Path) β€” GitHub Release workflow -4. Publish via workflow_dispatch β€” manual trigger fallback -5. Insider Channel β€” insider branch + `@insider` tag for testing -6. Workspace Publish Policy β€” reference to CI lint rule #557 (enforces `-w` flag) -7. Manual Local Publish β€” emergency fallback with step-by-step commands -8. 422 Race Condition & npm Errors β€” v0.9.1 incident + troubleshooting -9. Post-Publish Verification β€” `npm view` + npx cold-install test -10. Version Bump After Publish β€” preview version increment pattern -11. Legacy Publish Scripts β€” deprecation notice for PowerShell scripts - -**Key decisions:** -- Microsoft Style Guide enforced: sentence-case headings, active voice, "you" not "we", present tense -- Version-agnostic: `` placeholder, no hardcoded version numbers -- Scannability: checklist format, code blocks (bash not PowerShell for portability), tables for error reference -- Accuracy: pulled from actual workflows (`squad-npm-publish.yml`, `squad-insider-publish.yml`) β€” preflight job, smoke test, publish stages, registry propagation retry logic (5Γ— 15-second intervals) -- Runnable: all commands copy-pasteable (e.g., `npm -w packages/squad-sdk pack --dry-run`) - -**Pattern:** Living playbook absorbs three related issues (#558 race conditions, #559 manual publish, #560 pre-flight checklist) into unified reference. No separate documents; all under one decision tree: try CI first, use manual only if CI broken. Workspace publish policy section references CI lint rule #557 (being added in parallel by FIDO); both docs + lint create enforcement + education. - -**Commit:** `docs: rewrite PUBLISH-README.md as release playbook (#564)` on squad/release-hardening branch. - -πŸ“Œ **Team update (2026-03-24T06-release-hardening):** Release playbook rewrite (#564) completed. PUBLISH-README.md transformed from v0.8.22 stub to living 232-line playbook with 11 sections: Overview, Pre-Flight Checklist, Publish via CI (recommended), Publish via workflow_dispatch, Insider Channel, Workspace Publish Policy, Manual Local Publish (emergency fallback), 422 Race Condition & npm Errors, Post-Publish Verification, Version Bump After Publish, Legacy Publish Scripts. Absorbed issues #558, #559, #560 into unified decision tree. Microsoft Style Guide enforced; version-agnostic; all commands runnable. Scannability: checklist format, bash code blocks, error reference table. Committed to squad/release-hardening. -### JSDoc API Reference PRD (2026-03-24) - -Completed full PRD based on research findings. **Document:** `docs/research/jsdoc-api-reference-prd.md`. - -**Structure (8 major sections):** -1. Problem Statement β€” 5 concrete gaps (no dedicated API ref, uneven JSDoc coverage, discoverability, StorageProvider docs lag, Pagefind misses API symbols) -2. Goals & Success Metrics β€” 4 primary goals, 8 measurable targets (100% JSDoc coverage, 50+ auto-documented symbols, searchable API) -3. Key User Scenarios β€” 4 personas (SDK consumer, contributor, agent author, evaluator) with today vs future workflows -4. Scope β€” clear in/out boundaries (TypeDoc + JSDoc improvements in; CLI ref gen, Starlight migration, multi-version docs out) -5. Approach β€” architecture (TypeDoc in Astro hook), config template (typedoc.json), output/URL structure, build integration code, JSDoc improvement plan with effort table -6. Implementation Phases β€” 4 phases: Phase 0 (setup/PoC, 1–2 days), Phase 1 (JSDoc audit, 5–6 hrs), Phase 2 (integration/nav, 3–4 hrs), Phase 3 (CI/CD optional, 2–4 hrs) -7. Risks & Mitigations β€” 7 risks (TypeDoc breaks on changes, stale markdown, link validation strictness, Pagefind misses, config maintenance, build perf, breaking changes) with specific mitigations -8. Architecture Review section β€” 4 items for CONTROL to review (TypeScript export strategy, TypeDoc config, JSDoc standards, stability commitments) - -**Key decisions baked into PRD:** -- TypeDoc + typedoc-plugin-markdown (not Starlight, not api-extractor) β€” zero migration, Markdown-first, Pagefind-compatible -- Astro integration hook auto-runs TypeDoc on build (single step: `npm run build`) -- Generated output goes to docs/src/content/docs/reference/api/ (one file per symbol) -- JSDoc improvement priority: config/schema.ts (8% β†’ 100%), state/io/ functions (@param/@return tags), StorageProvider interface audit -- Total effort: 13–18 hours (8–12 JSDoc + 5–6 setup) - -**Style & Tone:** -- Written for Flight-level review/approval (actionable, opinionated, specific) -- Includes code examples (typedoc.json, Astro hook, JSDoc template) -- References research doc for detailed findings -- PRD as decision/commitment document β€” not advisory, but directive - -**Learnings:** -- PRD structure differs from research (research = exploratory findings/options; PRD = chosen path + tactical roadmap) -- Recommendation section in PRD serves as binding decision (TypeDoc chosen, rationale locked in) -- Architecture Review section ensures TypeScript team reviews export strategy and JSDoc standards early β€” prevents rework later -- Four-phase approach breaks large effort into digestible increments (Phase 0 validation before JSDoc audit helps mitigate risk of TypeDoc setup failing) - -**Decision:** PRD approved for handoff to implementation team. Ready for execution on next sprint. diff --git a/.squad/agents/procedures/history.md b/.squad/agents/procedures/history.md deleted file mode 100644 index c08ba4f05..000000000 --- a/.squad/agents/procedures/history.md +++ /dev/null @@ -1,216 +0,0 @@ -# Procedures - -> Standard Operating Procedures & Spec Writer - -## Learnings - -### Issue Triage (2026-03-22T06:44:01Z) - -**Flight triaged 6 unlabeled issues and filed 1 new issue.** - -Procedures assigned: -- **#485 (Agent Specification PRD)** β†’ squad:flight + squad:procedures (architecture decision + formal spec structure) - -Pattern: Agent specification gap identified. Procedures owns formal spec structure and documentation; Flight owns architecture decisions. - -πŸ“Œ **Team update (2026-03-26T06:41:00Z β€” Crash Recovery Execution & Model Catalog Merge):** Procedures executed Round 2 PR merge action: rebased PR #619 (model catalog refresh, issue #588) onto dev branch from main, resolved 3 merge conflicts, and successfully merged. Model catalog now current: default model bumped to `claude-sonnet-4.6` (latest standard-tier Claude), specialist bumped to `gpt-5.3-codex` (latest code-writing specialist), fallback chains restructured to include new models (`gpt-5.4`, `gpt-5.4-mini`) and removed dead models (`claude-opus-4.6-fast`). All 6 original merge-plan PRs (#620, #627, #624, #611, #617, #619) now βœ… complete. Dev branch green (5,038 tests). Decision inbox merged to decisions.md and deleted. Next: Ready for follow-on feature PRs. - -πŸ“Œ **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. Procedures owns Agent Specification PRD structure (#485). Architecture decisions from Flight. Coordinate on formal spec format and standard structure for future agent definitions. -# Procedures β€” Project History - -> Learnings, patterns, and context for the Prompt Engineer. - -## Learnings - -πŸ“Œ **Team update (2026-03-22T09-35Z β€” Wave 1):** Economy mode governance proposal and personal squad consult-mode governance proposal authored for squad.agent.md β€” both DRAFT, awaiting Flight review before merging. Economy mode adds Layer 3 table + spawn convention (`πŸ’° economy`) + model catalog audit. Personal squad adds consult mode detection, path reference table, spawn guidance. Persistent model preference (Layer 0) documented. Proposed new skill: `.squad/skills/consult-mode/SKILL.md` (post-approval). Deterministic skill pattern proven effective. PR #503 open with skills module. Next: Flight review β†’ merge governance to squad.agent.md. No blocking issues. - -### 2026-03-10: Deterministic skill pattern - -**Problem:** Skills were too loose. The distributed-mesh skill was tested in a real project (mesh-demo), and agents generated 76 lines of validator code, 5 test files with 43 tests, regenerated sync scripts that should have been copied from templates, and left decision files empty. The skill document let agents interpret intent instead of following explicit steps. - -**Solution:** Rewrite skills to be fully deterministic: - -1. **SCOPE section** (right after frontmatter, before Context) - - βœ… THIS SKILL PRODUCES β€” exact list of files/artifacts - - ❌ THIS SKILL DOES NOT PRODUCE β€” explicit negative list to prevent scope creep - -2. **AGENT WORKFLOW section** β€” Step-by-step deterministic instructions - - ASK: exact questions to ask the user - - GENERATE: exactly which files to create, with schemas - - WRITE: exactly which decision entry to write, with template - - TELL: exact message to output to user - - STOP: explicit stopping condition, with negative list of what NOT to do - -3. **Fix ambiguous language:** - - "do the task" β†’ clarify this means "the agent's normal work" not "build something for the skill" - - "Agent adds the field" β†’ clarify this describes what a consuming agent does with data it READ - - Phase descriptions β†’ note that phases are project-level decisions, not auto-advanced - -4. **Decision template** β€” inline markdown showing exactly what to write - -5. **Anti-patterns for code generation** β€” explicit list of things NOT to build - -**Pattern for other skills:** All skills should have SCOPE (what it produces, what it doesn't) and AGENT WORKFLOW (deterministic steps with STOP condition). Same input β†’ same output, every time. Zero ambiguity. - -πŸ“Œ Team update (2026-03-14T22-01-14Z): Distributed mesh integrated with deterministic skill pattern β€” decided by Procedures, PAO, Flight, Network - -### 2026-03-15: Self-contained skills pattern (agent-skills spec) - -**Problem:** The distributed-mesh skill had a manual gap β€” Step 4 told the user to copy sync scripts from templates/mesh/ manually. This violated the GitHub agent-skills spec, which says: "add scripts, examples or other resources to your skill's directory. The skill instructions should tell Copilot when, and how, to use these resources." - -**Solution:** Skills are self-contained bundles. Resources live WITH the skill, not in separate template directories: - -1. **Bundle resources IN the skill directory:** Copy `sync-mesh.sh`, `sync-mesh.ps1`, and `mesh.json.example` into `.squad/skills/distributed-mesh/` -2. **Update SKILL.md workflow:** - - Step 2: Reference `mesh.json.example` from THIS skill's directory - - Step 3: COPY sync scripts from THIS skill's directory to project root (agent does it, not user) - - Step 4: RUN `--init` if Zone 2 state repo specified (agent does it, not user) -3. **Update SCOPE section:** Clarify the skill PRODUCES the copied scripts (bundled resources β‰  generated code) -4. **Replicate to templates:** Copy entire skill directory to `templates/skills/`, `packages/squad-cli/templates/skills/`, `packages/squad-sdk/templates/skills/` - -**Pattern for all skills:** Skills are self-contained. Scripts, examples, configs, and resources travel WITH the skill. The agent reads SKILL.md, sees "copy X from this directory," and does it. Zero manual steps. - -### 2026-03-15: Three new governance policies added to agent system - -**Task:** Brady directive β€” implement three new policies across the agent system: - -1. **Agent Error Lockout** β€” Added to squad.agent.md. After 2 cumulative errors (build/test failures or reviewer rejection) on the same task, agent is locked out for that task only. Different agent takes over. Coordinator tracks and enforces; Scribe logs lockout events. - -2. **Product Isolation Rule** β€” Added to every charter and squad.agent.md Constraints. Tests, CI, and product code must NEVER depend on specific agent names from any squad. "Our squad" must not impact "the squad." Use generic/parameterized values (e.g., "test-agent-1") instead of real agent names (Flight, EECOM, FIDO). - -3. **Peer Quality Check** β€” Added to every charter. Before finishing work, agents must verify their changes don't break existing tests. Run test suite for files touched. Update history.md when learning from mistakes. - -**Implementation:** Updated `.github/agents/squad.agent.md` (new section + constraint) and all 19 active agent charters in `.squad/agents/*/charter.md`. - -**Pattern:** Policies added as subsections under "How I Work" in charters to ensure they're loaded with agent context. Coordinator-level policies live in squad.agent.md with explicit enforcement instructions. - -### 2026-03-16: Team-wide reskill β€” 17.4% reduction - -**Context:** Routine maintenance reskill, one day after previous reskill (2026-03-15). Last reskill brought the system from 117.4KB to 51.7KB. This pass focused on remaining oversized charters. - -**Work done:** -- **Scribe (2143β†’1557):** Compressed workflow steps, kept essential commit instructions -- **Handbook (1807β†’1529):** Removed repetitive LLM-FIRST DOCS emphasis -- **FIDO (1715β†’1370):** Consolidated verbose NEVER/ALWAYS sections -- **Booster (1583β†’1368):** Same NEVER/ALWAYS compression pattern - -**Results:** 26,721β†’17,088 bytes (charters), 28,602β†’28,602 bytes (histories), total 55,323β†’45,690 bytes. 9,633 bytes saved (17.4% reduction). All charters now ≀1.5KB. - -**Skill extraction:** No new patterns extracted. CastingEngine integration work (from EECOM March 15) is still evolving β€” not yet mature enough for skill template. Histories all <12KB, no compression needed. - -**Pattern:** NEVER/ALWAYS sections in charters compress well β€” fold bullet lists into single-paragraph summaries. Essential workflow details (Scribe's commit steps) should stay verbose. - -### 2026-03-22: Economy mode skill and personal squad governance (#500, #344) - -**Task:** Two governance tasks β€” economy mode skill design and personal squad coordinator awareness. - -**Economy mode (SKILL.md):** -- Created `.squad/skills/economy-mode/SKILL.md` as a Layer 3 modifier, not a new resolution layer -- Key design decision: economy mode ONLY affects Layer 3 auto-selection β€” Layer 0/1/2 (user intent) always wins -- `πŸ’°` indicator in spawn acknowledgments keeps it transparent -- Activation via session phrase, persistent config (`economyMode: true` in config.json), or CLI flag -- Architecture trips shift from opus β†’ sonnet; code tasks shift from sonnet β†’ gpt-4.1/gpt-5-mini -- Confidence: `low` β€” first implementation, not yet validated - -**Personal squad governance (proposals):** -- Gap analysis: coordinator has no consult mode awareness despite full SDK implementation -- Five gaps identified: Init Mode missing personal squad resolution, no consult mode detection, TEAM_ROOT has no personal-squad semantics, charter templates lack consult-mode patterns, no consult-mode skill -- Proposed `CONSULT_MODE: true` as spawn prompt signal, `🧳 consult` in acknowledgments -- Proposed new consult-mode skill (after governance approval β€” skill after governance, not before) - -**Governance workflow pattern:** When proposals touch squad.agent.md (governance territory), write to `decisions/inbox/` for Flight review. Don't directly edit squad.agent.md β€” Flight reviews governance changes. - -**Catalog audit finding:** `claude-sonnet-4.6`, `gpt-5.4`, `gpt-5.3-codex` appear in model-selection SKILL.md fallback chains but are absent from squad.agent.md's "Valid models" catalog. Documented in economy-mode governance proposal for Flight to address. - -### Session 2 Summary (2026-03-22) - -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. - -πŸ“Œ **Team update (2026-03-23T23:15Z):** Orchestration complete. Agent name display refactor shipped: spawn templates updated with mandatory `name` parameter across all 4 template variants. VOX and FIDO coordinated on parser extraction and cascading pattern strategies. All decisions merged to decisions.md. Canonical source: `.squad-templates/squad.agent.md` (all derived copies secondary). - -πŸ“Œ **Team update (2026-03-25T18:11Z):** Model catalog updated to current platform offerings β€” removed 2 stale models (claude-opus-4.6-fast, gpt-5), added 5 new models (claude-sonnet-4.6, claude-opus-4.6-1m, gpt-5.4, gpt-5.3-codex, gpt-5.4-mini), bumped defaults (code: claude-sonnet-4.6, specialist: gpt-5.3-codex), restructured fallbacks. All 5 squad.agent.md template copies synchronized. Merged in #588. - -### 2025-07: Model catalog refresh (#588) - -**Problem:** The valid models catalog, fallback chains, role-to-model mappings, and default model references in `squad.agent.md` were stale β€” missing `claude-sonnet-4.6`, `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.4-mini`, `claude-opus-4.6-1m` and still referencing removed models `claude-opus-4.6-fast` and standalone `gpt-5`. - -**Fix:** Full catalog refresh across all model-referencing sections: -- Catalog: added 5 new models, removed 2 stale ones -- Defaults: code-writing tasks bumped to `claude-sonnet-4.6` (newest standard); code specialist bumped to `gpt-5.3-codex` -- Fallback chains: restructured with new models in sensible positions (e.g., `gpt-5.4-mini` in fast tier, `gpt-5.4` in standard) -- All 5 copies synced via `sync-templates.mjs` - -**Pattern:** Model catalogs drift. When the platform adds/removes models, every section referencing models needs updating β€” not just the catalog list. Search for all model name strings before considering the refresh complete. -### 2026-03-25: VS Code routing enforcement investigation (#613) - -**Problem:** In VS Code, the coordinator reads routing rules but doesn't enforce them β€” continues working inline instead of dispatching via `runSubagent`. Andreas (andikrueger) reproduced and the agent itself admitted it violated the rules. - -**Root cause (dominant):** CLI-centric enforcement language. The CRITICAL RULE says "MUST use the `task` tool" β€” but in VS Code the dispatch tool is `runSubagent`. When `task` isn't available, the coordinator falls through Platform Detection's "Fallback mode" (work inline) instead of using `runSubagent`. The VS Code adaptations section is buried 360 lines below the CRITICAL RULE and reads as optional, not mandatory. - -**Amplifying factors:** -1. Prompt saturation: 950 lines / 80KB. Routing constraint competes with 900+ lines of governance, lifecycle, and reference material. Core dispatch loop is ~200 lines; rest is noise. -2. Template duplication: CLI 1.0.11 discovers all `*.agent.md` from cwd to git root. Squad has 5 copies β€” only `.github/agents/squad.agent.md` should be discoverable. - -**Proposed fixes (5 total, prioritized):** -- P0: Rewrite enforcement language to be platform-neutral ("dispatch tool" not "`task` tool") -- P0: Add routing reinforcement at bottom of prompt (LLMs weight start/end more than middle) -- P1: Rename template copies to `.agent.md.template` to prevent CLI discovery -- P1: Extract ~350 lines to lazy-loaded reference files (worktree, Ralph, casting, MCP) -- P1: Move VS Code dispatch block immediately after CRITICAL RULE - -**Key pattern learned:** Enforcement language must name ALL dispatch mechanisms, not just the CLI one. Platform-specific instructions buried deep in a long prompt get lost β€” they need to be co-located with the constraint they modify. LLM attention patterns favor prompt boundaries (top/bottom) over the middle. - -**Proposal filed:** `.squad/decisions/inbox/procedures-vscode-routing-fix.md` - -### 2026-07: VS Code routing enforcement β€” Fix 1 + Fix 2 shipped (#613) - -**Implemented** P0 fixes from the VS Code routing proposal: - -- **Fix 1 (Platform-Neutral Enforcement):** Rewrote CRITICAL RULE from CLI-specific "`task` tool" language to dispatcher-identity framing ("You are a DISPATCHER, not a DOER") with explicit dispatch mechanism table (CLI β†’ `task`, VS Code β†’ `runSubagent`, fallback β†’ inline as last resort). Updated all 7 enforcement-context references throughout squad.agent.md: anti-patterns #1/#2/#3, constraints block, and spawn template header. - -- **Fix 2 (Top-and-Bottom Reinforcement):** Added `## ⚠️ Routing Enforcement Reminder` as final section, exploiting LLM prompt-boundary attention bias. Reinforces dispatcher identity at both top and bottom of the prompt. - -**Branch:** `squad/613-vscode-routing-enforcement` β€” canonical source edited, synced to all 5 copies via `scripts/sync-templates.mjs`, build verified clean. - -**Remaining P1 fixes** (template renaming, prompt slimming, VS Code block relocation) deferred to separate PRs per the proposal's ship order. - -### 2026-07: PR #619 rebase and merge β€” model catalog final sync - -**Problem:** PR #619 (model catalog update, #588) was the last of 6 PRs in the pre-crash triage merge plan. It had accumulated old dev merge commits and was behind after PRs #620, #627, #624, #611, and #617 merged first. Template renames from #624 (`.agent.md` β†’ `.agent.md.template`) changed which files needed updating. - -**Fix:** Used targeted `git rebase --onto dev ` to replay only the 2 actual PR commits (skipping accumulated dev merge noise). Rebase applied cleanly β€” one commit landed, one was auto-dropped as already upstream. After rebase, only `packages/squad-sdk/templates/squad.agent.md.template` and `templates/squad.agent.md.template` needed changes since the canonical and other copies already had the model updates from earlier merges. - -**Pattern:** When a PR branch has accumulated merge commits from dev, use `git rebase --onto dev ` to cherry-pick only the relevant commits. This avoids conflict noise from old merge commits that are already in dev. Also: after template renames, the sync script may overwrite version stamps in the canonical file β€” revert those before pushing. - -### 2026-04-17: Trim copilot-instructions.md (#999) - -**Task:** Reduce `.github/copilot-instructions.md` from ~1,300 words / 9KB to ≀750 words / ≀4KB to reduce attention dilution for the Copilot coding agent. - -**Key decisions:** -- Extracted Protected Files (file list, rules, SDK/CLI boundary, anti-patterns) to `.copilot/skills/protected-files/SKILL.md` β€” replaced with 2-sentence pointer -- Consolidated Git Safety from 4 sub-sections (Staging, Pushing, Pre-Push Checklist, Branch Contamination Prevention) into a single 7-item flat list; resolved contradictory `git fetch upstream` vs `git fetch origin` (kept `origin`) -- Compacted Changeset Requirement from 7 lines + code block to 2 sentences -- Reordered: Team Context, Capability Self-Check, Branch Naming now appear before Git Safety (essential workflow first, safety rules second) -- Removed duplication with `.squad/copilot-instructions.md` (5 sections were verbatim copies; kept compact versions since both files load) -- Sweeping Refactor Rules condensed from 5-step list to 2-sentence pointer - -**Result:** 397 words / 3KB β€” well within target. PR #1002. - -**Files modified:** `.github/copilot-instructions.md`, `.copilot/skills/protected-files/SKILL.md` (new). - -**Pattern:** When trimming agent instructions, extract domain-specific reference content to skills (lazy-loaded on demand) and keep the main instructions file as a routing/workflow document. Skills are the right abstraction for "read this when you touch X" β€” they don't consume tokens until needed. - diff --git a/.squad/agents/ralph/history.md b/.squad/agents/ralph/history.md deleted file mode 100644 index 050d7a70c..000000000 --- a/.squad/agents/ralph/history.md +++ /dev/null @@ -1,16 +0,0 @@ -# Project Context - -- **Project:** squad -- **Created:** 2026-03-15 - -## Core Context - -Agent Ralph initialized and ready for work. - -## Recent Updates - -πŸ“Œ Team initialized on 2026-03-15 - -## Learnings - -Initial setup complete. diff --git a/.squad/agents/retro/history.md b/.squad/agents/retro/history.md deleted file mode 100644 index 61459ef58..000000000 --- a/.squad/agents/retro/history.md +++ /dev/null @@ -1,16 +0,0 @@ -# RETRO - -> Retrofire Officer - -## Learnings - -### Issue Triage (2026-03-22T06:44:01Z) - -**Flight triaged 6 unlabeled issues and filed 1 new issue.** - -RETRO assigned: -- **#479 (history-shadow race condition)** β†’ squad:eecom + squad:retro (production bug; mitigation through StorageProvider atomicity) - -Pattern: Critical production bug identified. Race condition in history-shadow requires atomicity guarantees from StorageProvider abstraction (CONTROL/EECOM). - -πŸ“Œ **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. RETRO owns #479 mitigation strategy. Production bug severity high; blocks stable history-shadow operation. Depends on StorageProvider PRD completion (#481). Coordinated rollout required. diff --git a/.squad/agents/scribe/history.md b/.squad/agents/scribe/history.md deleted file mode 100644 index e3e8bb224..000000000 --- a/.squad/agents/scribe/history.md +++ /dev/null @@ -1,4 +0,0 @@ -# Scribe β€” Session History - -*Fresh start β€” Apollo 13 rebirth. Previous session logs archived.* - diff --git a/.squad/agents/surgeon/history.md b/.squad/agents/surgeon/history.md deleted file mode 100644 index dfea0980b..000000000 --- a/.squad/agents/surgeon/history.md +++ /dev/null @@ -1,137 +0,0 @@ -# SURGEON - -> Flight Surgeon - -## 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. - -### Version Mutation Bug (P0) -bump-build.mjs mutates versions during local builds despite SKIP_BUILD_BUMP=1 and CI=true env vars. Workaround: set versions with `node -e` script and commit IMMEDIATELY before building. This is a P0 fix item in docs/proposals/cicd-gitops-prd.md. - -### Known Incidents -v0.8.22: 4-part version 0.8.21.4 mangled by npm to 0.8.2-1.4. v0.8.23: versions reverted from 0.8.23 to 0.8.22 during build despite env vars. Both resolved with the node -e script + immediate commit workaround. - -### v0.9.0 CHANGELOG Written -**Date:** 2026-03-23 - -v0.9.0 is a MAJOR minor version bump (0.8.25 β†’ 0.9.0) justified by 40+ commits spanning 6+ major features and governance-layer additions. CHANGELOG organized across 12 feature sections + fixes: - -**Feature Categories:** -- Personal Squad (governance layer + ambient discovery) -- Worktree Spawning & orchestration -- Machine Capability Discovery -- Cooperative Rate Limiting & circuit breaker -- Economy Mode (cost-conscious model selection) -- Auto-wire Telemetry -- Issue Lifecycle & KEDA templates -- Session Recovery skill -- GAP analysis verification loop -- GitHub Auth Isolation skill -- Astro docs site improvements (10 items) -- Skill migrations (.squad β†’ .copilot) -- ESLint runtime anti-pattern detection - -**Fixes:** -- CLI terminal rendering (scroll flicker, Ink remounting) -- Upgrade path & installation (P0 gaps, EPERM handling, template alignment) -- ESM compatibility (Node 22/24 vscode-jsonrpc fixes) -- Runtime stability (signal handling, race conditions, timeouts, memory safety) -- GitHub integration (CI hardening, casting alignment) - -**Documentation:** Maintained strict format rules (no npx refs, no "agency" terminology, matched existing CHANGELOG style, grouped by feature subsections). CLI Terminal Rendering fixes kept from [Unreleased] as part of 0.9.0. - -### v0.9.0 β†’ v0.9.1 Release Retrospective -**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 but publish workflow infrastructure failures extended resolution to 8 hours (should have been 10 minutes). - -**Root Causes:** -1. **Dependency Validation Gap** β€” No pre-publish check for `file:` references. npm workspaces automatically rewrite `"*"` β†’ `"file:../path"` during development; this persisted in published package. -2. **GitHub Actions Workflow Cache Race Condition** β€” After deleting `squad-publish.yml`, GitHub workflow index didn't refresh for 10+ minutes. `workflow_dispatch` returned 422 error that persisted despite file deletion. -3. **npm Workspace Publish Broken** β€” `npm -w packages/squad-sdk publish` hung indefinitely (2FA auth issue on machine without authenticator app). -4. **Coordinator Decision-Making** β€” Retried broken `workflow_dispatch` 4+ times instead of escalating to local publish fallback sooner. - -**Key Action Items:** -- A1: Add dependency validation to publish workflow (scan for `file:` refs, dry-run npm install) -- A2: Establish npm publish policy (never use `-w` for publishing; always `cd` into package directory) -- A3: Mitigate GitHub Actions cache race condition (document 15-min wait; escalate to local publish on 2nd failure) -- A4: Define publish fallback/escalation protocol (2nd workflow failure β†’ immediate local publish) -- A5: Pre-release readiness checklist (dependency scan, CHANGELOG, tests, 2FA verify) -- A6: Post-publish smoke test (run global install; rollback if fails) - -**Process Changes:** -- Change-1: Pre-publish validation mandatory (before tagging) -- Change-2: Simplified publish flow (remove manual `workflow_dispatch`; let tag trigger workflow) -- Change-3: Explicit runbook in PUBLISH-README.md (no tribal knowledge) -- Change-4: Escalation to fallback (fail-fast instead of retry loops) -- Change-5: Package validation in CI (ESLint rule to reject `file:` refs) - -**Documentation:** Full retrospective in `.squad/decisions/inbox/surgeon-v091-retrospective.md` and `.squad/log/2026-03-23-v091-retrospective.md`. - -**Status:** Approved for implementation. v0.9.1 published successfully (both packages verified live on npm). - ---- - -### Release Playbook & CI Improvement Plan (2026-03-23) - -Prepared comprehensive release playbook and CI improvement plan for Brady's review: - -1. **Release Playbook** β€” Full step-by-step release procedure covering: - - Pre-release checklist (dependency validation, tests, CHANGELOG, versions, npm auth) - - Release execution (12 numbered steps from version bump to smoke test) - - Fallback procedures (422 errors, 2FA timeouts, deployment failures, rollback) - - Post-release verification checklist - - Non-negotiable rules (no improvisation, no draft releases, no 4-part versions, etc) - - Known gotchas (npm workspaces auto-rewrite, workflow cache TTL, 2FA hanging) - -2. **CI Improvement Plan** β€” 7 GitHub issues + 4 CI cleanup actions: - - Issue A: Dependency validation gate (scan for `file:` refs before publish) - - Issue B: npm publish policy (never use `-w`, always `cd` + `--ignore-scripts`) - - Issue C: Workflow cache mitigation (15-min wait, escalation policy) - - Issue D: squad-promote workflow (dev β†’ preview β†’ main automation) - - Issue E: squad-preview validation (forbidden files, versions, dependencies) - - Issue F: squad version command fix (show correct CLI version) - - Issue G: Escalation policy documentation (2nd failure β†’ local publish) - - CI cleanup: Delete ghost workflows, add pre-commit hooks, verify SKIP_BUILD_BUMP, audit NPM_TOKEN - -3. **Session Log Cleanup** β€” Deleted 17 files from today's session logs: - - 15 files from `.squad/orchestration-log/` - - 2 files from `.squad/log/` - - Preserved retro findings in `.squad/decisions/inbox/` (surgeon-v091-retrospective.md) - - No agent history.md files deleted - -**Key Lessons Learned:** -- Release playbook must be exhaustively detailed with no room for improvisation -- Fallback procedures are critical (workflow failures happen; escalate fast) -- Pre-release validation prevents 90% of publish issues -- Culture: "If the same problem happens twice, the playbook failed" -- Documentation must be user-first (Brady's perspective, not technical jargon) diff --git a/.squad/agents/vox/history.md b/.squad/agents/vox/history.md deleted file mode 100644 index 78f090093..000000000 --- a/.squad/agents/vox/history.md +++ /dev/null @@ -1,26 +0,0 @@ -# VOX - -> CAPCOM Voice Controller - -## Learnings - -### Issue Triage (2026-03-22T06:44:01Z) - -**Flight triaged 6 unlabeled issues and filed 1 new issue.** - -VOX assigned: -- **#478 (Polish REPL)** β†’ squad:vox + squad:pao (shell UX readiness + documentation gate) - -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. - -πŸ“Œ **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/commit-message.txt b/.squad/commit-message.txt deleted file mode 100644 index 04953834d..000000000 --- a/.squad/commit-message.txt +++ /dev/null @@ -1,17 +0,0 @@ -docs(squad): close #631 incident response β€” revert, CI guards, git safety rules - -Incident #631 complete closure: -- Surgeon reverted problematic commit 1ab2f5c on dev (restored 361 files) -- Booster added CI deletion guards & canary checks to squad-ci.yml -- RETRO documented Git Safety mandatory rules in copilot-instructions.md -- PRs created and ready for merge (squad/631-ci-deletion-guard, squad/631-copilot-git-safety) -- Issue #631 closed with incident summary - -Team memory updated: -- Orchestration log: 2026-03-26T17-28-631-closure.md -- Session log: 2026-03-26T17-28-631-closure.md - -Incident response: Full parallel execution by Surgeon, Booster, RETRO agents. -Resolution: EMU auth restrictions resolved, manual coordination by Coordinator. - -Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> diff --git a/.squad/commit-msg.txt b/.squad/commit-msg.txt deleted file mode 100644 index 6920e2645..000000000 --- a/.squad/commit-msg.txt +++ /dev/null @@ -1,8 +0,0 @@ -docs(squad): log mega triage session - -- Crash recovery: merged 10 PRs, closed 3 duplicates -- Repo hygiene: removed test artifacts, consolidated .gitignore, cleaned garbage files, pruned 21 local + 31 remote branches -- Issue triage: 12+ issues routed and closed -- PR management: merged #628 (model config), reviewed #629, routed Tamir PRs to dev branch pending proposals - -Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> diff --git a/.squad/decisions/inbox/booster-ci-deletion-guard.md b/.squad/decisions/inbox/booster-ci-deletion-guard.md deleted file mode 100644 index 581b1f419..000000000 --- a/.squad/decisions/inbox/booster-ci-deletion-guard.md +++ /dev/null @@ -1,4 +0,0 @@ -### 2026-03-26: CI deletion guard and source tree canary -**By:** Booster (CI/CD) -**What:** Added two safety checks to squad-ci.yml: (1) source tree canary verifying critical files exist, (2) large deletion guard failing PRs that delete >50 files without 'large-deletion-approved' label. Branch protection on dev requested (may need manual setup). -**Why:** Incident #631 β€” @copilot deleted 361 files on dev with no CI gate catching it. diff --git a/.squad/decisions/inbox/booster-release-skill-v094.md b/.squad/decisions/inbox/booster-release-skill-v094.md deleted file mode 100644 index b6858ce11..000000000 --- a/.squad/decisions/inbox/booster-release-skill-v094.md +++ /dev/null @@ -1,35 +0,0 @@ -# Decision: Release Process Skill Update β€” v0.9.4 Learnings - -**Author:** Booster (CI/CD Engineer) -**Date:** 2026-04-25 -**Status:** Implemented -**Requested by:** Brady - -## Summary - -Updated both release-process skill files with critical learnings from the v0.9.4 release session. The v0.9.4 release was delayed by three distinct issues, each fixed by a separate PR. - -## Changes Made - -### Files Updated -1. `.squad/skills/release-process/SKILL.md` (team-level skill) -2. `.copilot/skills/release-process/SKILL.md` (copilot-level skill) -3. `.squad/agents/booster/history.md` (learnings log) - -### New Knowledge Added - -| Issue | Root Cause | Fix PR | Skill Section | -|-------|-----------|--------|---------------| -| Root package.json version drift | squad-release.yml reads from root, not sub-packages | #1043 | Known Gotchas + v0.9.4 Incident Learnings | -| CHANGELOG missing `## [$VERSION]` | Workflow validates version entry exists | #1042 | Known Gotchas + Release Checklist | -| Lockfile integrity check rejects workspace packages | Check didn't filter for registry-only packages | #1044 | Known Gotchas + Common Failure Modes | -| GITHUB_TOKEN can't trigger downstream workflows | GitHub security feature prevents event propagation | N/A (design) | GITHUB_TOKEN section + Manual Publish | -| Prebuild bump breaks workspace linking | bump-build.mjs mutates versions breaking exact match | N/A (known) | Local Development section | - -### Cross-References -- Added bidirectional cross-references between team-level and copilot-level skill files -- Added PR references (#1042, #1043, #1044) as source evidence throughout - -## Rationale - -These are high-impact, recurring failure modes. Documenting them in the skill files ensures every agent (human or AI) working on releases has the knowledge to avoid repeating the v0.9.4 delays. The GITHUB_TOKEN limitation in particular is non-obvious and would catch any future release. diff --git a/.squad/decisions/inbox/flight-versioning-policy.md b/.squad/decisions/inbox/flight-versioning-policy.md deleted file mode 100644 index 9911fc318..000000000 --- a/.squad/decisions/inbox/flight-versioning-policy.md +++ /dev/null @@ -1,32 +0,0 @@ -# Decision: Versioning Policy β€” No Prerelease Versions on dev/main - -**By:** Flight (Lead) -**Date:** 2026-03-29 -**Requested by:** Dina -**Status:** DECIDED -**Confidence:** Medium (confirmed by PR #640 incident, PR #116 prerelease leak, CI gate implementation) - -## Decision - -1. **All packages use strict semver** (`MAJOR.MINOR.PATCH`). No prerelease suffixes on `dev` or `main`. -2. **Prerelease versions are ephemeral.** `bump-build.mjs` creates `-build.N` for local testing only β€” never committed. -3. **SDK and CLI versions must stay in sync.** Divergence silently breaks npm workspace resolution. -4. **Surgeon owns version bumps.** Other agents must not modify `version` fields in `package.json` unless fixing a prerelease leak. -5. **CI enforcement via `prerelease-version-guard`** blocks PRs with prerelease versions. `skip-version-check` label is Surgeon-only. - -## Why - -The repo had no documented versioning policy. This caused two incidents: - -- **PR #640:** Prerelease version `0.9.1-build.4` silently broke workspace resolution. The semver range `>=0.9.0` does not match prerelease versions, causing npm to install a stale registry package instead of the local workspace link. Four PRs (#637–#640) patched symptoms before the root cause was found. -- **PR #116:** Surgeon set versions to `0.9.1-build.1` instead of `0.9.1` on a release branch because there was no guidance on what constitutes a clean release version. - -## Skill Reference - -Full policy documented in `.squad/skills/versioning-policy/SKILL.md`. - -## Impact - -- All agents must follow the versioning policy when touching `package.json` -- Surgeon charter should reference this skill for release procedures -- CI pipeline enforces the policy via automated gate diff --git a/.squad/decisions/inbox/retro-copilot-git-safety.md b/.squad/decisions/inbox/retro-copilot-git-safety.md deleted file mode 100644 index ed7dfc985..000000000 --- a/.squad/decisions/inbox/retro-copilot-git-safety.md +++ /dev/null @@ -1,4 +0,0 @@ -### 2026-03-26: Copilot git safety rules -**By:** RETRO (Security) -**What:** Added mandatory Git Safety section to copilot-instructions.md: prohibits `git add .`, requires feature branches and PRs, adds pre-push checklist, defines red-flag stop conditions. -**Why:** Incident #631 β€” @copilot used destructive staging on an incomplete working tree, deleting 361 files. diff --git a/.squad/history.md b/.squad/history.md deleted file mode 100644 index d975a5cbf..000000000 --- a/.squad/history.md +++ /dev/null @@ -1,10 +0,0 @@ -# Project Context - -- **Owner:** {user name} -- **Project:** {project description} -- **Stack:** {languages, frameworks, tools} -- **Created:** {timestamp} - -## Learnings - - diff --git a/.squad/identity/now.md b/.squad/identity/now.md deleted file mode 100644 index 4892b86c3..000000000 --- a/.squad/identity/now.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -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 -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}. Releases driven by Surgeon. Pre-flight gates mandatory. Never commit to main directly. ---- - -# What We're Focused On - -**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 - -## Current State - -**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 - -**Open Issues:** 9 filed for release improvements (#556–#564). PR #567 (StorageProvider) parked as draft. Ready for next development phase. - -## Next Steps - -### 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 - -### 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 - -### Backlog -- **#556–#564** β€” Release improvements (9 issues) -- **#567** β€” StorageProvider PRD (draft, parked for v1.0) - -## Process - -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. - -## Team Identity - -**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). - -**Status:** Team stable, process hardened, community engaged, next cycle ready. diff --git a/.squad/identity/prd-consult-mode.md b/.squad/identity/prd-consult-mode.md deleted file mode 100644 index 61468ab86..000000000 --- a/.squad/identity/prd-consult-mode.md +++ /dev/null @@ -1,289 +0,0 @@ -# PRD: Personal Squad Consult Mode - -**Author:** James Sturtevant -**Date:** 2026-02-27 -**Status:** Implemented -**Wave:** M6 (Personal Squad Enhancement) - ---- - -## Problem Statement - -You have a personal squad at your global squad path (resolved via `resolveGlobalSquadPath()` β€” e.g. `~/.config/squad/.squad` on Linux, `~/Library/Application Support/squad/.squad` on macOS, `%APPDATA%/squad/.squad` on Windows) with agents, skills, and decisions refined over time. You want to use this team on projects you don't own (OSS contributions, client work, temporary collaborations) without: - -1. **Polluting the project** β€” no `.gitignore` changes, no committed `.squad/` folder -2. **Polluting your squad** β€” no project-specific knowledge bleeding into your global squad - -Currently, `squad init` creates a project-owned squad. There's no way to "bring your team" to a project invisibly, work with them, and bring back only the generic learnings. - ---- - -## Solution: Consult Mode - -Your team **consults** on a project. They bring their expertise, do the work, learn things. When done, they extract what's reusable and return home. The project never knows Squad was there. - -### Key Behaviors - -| Aspect | Normal Mode | Consult Mode | -|--------|-------------|--------------| -| Squad location | `.squad/` in project | **Copy** of personal squad into project `.squad/` | -| Git visibility | Committed or `.gitignore` | Invisible via `.git/info/exclude` | -| Writes go to | Project `.squad/` | Project `.squad/` (isolated copy, won't affect personal squad) | -| Agent file | `.github/agents/squad.agent.md` (committed) | `.github/agents/squad.agent.md` (excluded, points to local `.squad/`) | -| After session | Stays in project | Extract generic β†’ personal squad, discard rest | - ---- - -## Commands - -### Entry: `squad consult` - -```bash -cd ~/projects/their-oss-project -squad consult # Enter consult mode -squad consult --status # Check if in consult mode, show pending learnings -squad consult --check # Dry-run: show what would happen without creating files -``` - -**Creates:** -``` -.squad/ # Full copy of personal squad -β”œβ”€β”€ config.json # { "consult": true, "sourceSquad": "", ... } -β”œβ”€β”€ agents/ # Copied from personal squad -β”œβ”€β”€ skills/ # Copied from personal squad -β”œβ”€β”€ decisions.md # Copied from personal squad -β”œβ”€β”€ scribe-charter.md # Patched with consult mode extraction instructions -β”œβ”€β”€ sessions/ # Local session history -└── extract/ # Staging area for generic learnings (Scribe writes here) - -.github/agents/ -└── squad.agent.md # Points to local .squad/ (also excluded from git) -``` - -**Also:** -- Appends `.squad/` and `.github/agents/squad.agent.md` to `.git/info/exclude` (git-internal, never visible) -- If project already has committed `.squad/`: **error out** - -**Why copy instead of reference?** -- Changes during consult session don't pollute your personal squad -- Session-specific decisions/skills stay isolated until explicitly extracted -- Works offline (no dependency on external path) - -### Exit: `squad extract` - -```bash -squad extract # Review and extract generic learnings -squad extract --dry-run # Preview what would be extracted (no changes) -squad extract --clean # Also delete project .squad/ after (prompts for confirmation) -squad extract --clean --yes # Delete without confirmation -squad extract --accept-risks # Allow extraction despite license or other risks -``` - -**Flow:** -1. Read project LICENSE file -2. Warn if copyleft (GPL, AGPL) β€” license contamination risk -3. Load staged learnings from `.squad/extract/` -4. User selects which learnings to extract -5. Merge selected items to personal squad -6. Log to `/consultations/{project}.md` -7. Remove extracted files from `.squad/extract/` - ---- - -## Classification: Scribe-Based - -The extraction classification is done by **Scribe** during the session, not by SDK heuristics. - -When consult mode is set up, the Scribe charter is patched with extraction instructions: - -```markdown -## Consult Mode Extraction - -**This squad is in consult mode.** When merging decisions from the inbox, also classify each decision: - -### Classification - -For each decision in `.squad/decisions/inbox/`: - -1. **Generic** (applies to any project) β†’ Copy to `.squad/extract/` with the same filename - - Signals: "always use", "never use", "prefer X over Y", "best practice", coding standards, patterns that work anywhere - - These will be extracted to the personal squad via `squad extract` - -2. **Project-specific** (only applies here) β†’ Keep in local `decisions.md` only - - Signals: Contains file paths from this project, references "this project/codebase/repo", mentions project-specific config/APIs/schemas - -Generic decisions go to BOTH `.squad/decisions.md` (for this session) AND `.squad/extract/` (for later extraction). -``` - -**User always has final say.** Scribe proposes by writing to `extract/`, user approves/rejects via `squad extract`. No extraction happens without explicit confirmation. - ---- - -## Extraction Review - -Via `squad extract`: - -``` -πŸ“€ Learnings staged for extraction: - -⚠️ License: MIT (safe to extract) - -Found 3 learning(s) in .squad/extract/: - [1] use-async-await.md - [2] validate-inputs.md - [3] prefer-composition.md - -Select learnings to extract (space to toggle, enter to confirm): -❯ β—‰ use-async-await.md - β—‰ validate-inputs.md - β—‰ prefer-composition.md - -Extract 3 learning(s)? [Y/n] -``` - -### License Handling - -**Permissive licenses (MIT, Apache, BSD, ISC):** Proceed normally with extraction review. - -**Copyleft licenses (GPL, AGPL, LGPL):** **Blocked by default.** Extraction refuses unless user explicitly opts in: - -``` -🚫 License: GPL-3.0 (copyleft) - Extraction blocked. Patterns from copyleft projects may carry - license obligations that affect your future work. - - See: https://squad.dev/docs/license-risk - - To proceed anyway: squad extract --accept-risks -``` - ---- - -## Technical Design - -### Config Schema - -Consult mode config in `.squad/config.json`: - -```typescript -interface ConsultDirConfig { - consult: boolean; // true = consult mode - sourceSquad: string; // Path to original personal squad (for extraction) - projectName: string; // Name of the project being consulted - createdAt: string; // ISO timestamp -} -``` - -### SDK Types - -```typescript -// Result of setupConsultMode() -interface SetupConsultModeResult { - squadDir: string; // Path to project .squad/ - personalSquadRoot: string; // Path to personal squad root - gitExclude: string; // Path to git exclude file - projectName: string; // Project name (basename) - dryRun: boolean; // Whether this was a dry run - agentFile: string; // Path to .github/agents/squad.agent.md - createdFiles: string[]; // List of created file paths (relative to squadDir) -} - -// A learning staged by Scribe for extraction -interface StagedLearning { - filename: string; // e.g. "use-async-await.md" - filepath: string; // Full path to file in extract/ - content: string; // File content -} - -// Result of extraction -interface ExtractionResult { - extracted: StagedLearning[]; // Learnings extracted to personal squad - skipped: StagedLearning[]; // Learnings rejected by user - license: LicenseInfo; - projectName: string; - timestamp: string; - acceptedRisks: boolean; -} -``` - -### Errors - -```typescript -// Thrown when personal squad doesn't exist -class PersonalSquadNotFoundError extends Error { - constructor() { - super('No personal squad found.'); - this.name = 'PersonalSquadNotFoundError'; - } -} -``` - -### Invisibility Mechanism - -`.git/info/exclude` is: -- Git-internal exclude file (same syntax as `.gitignore`) -- Lives in `.git/`, so never committed -- Project owner never sees it -- `git status` shows nothing - -> **Important:** Do not hard-code `resolve(cwd, '.git/info/exclude')`. In git worktrees -> and submodules, `.git` is a *file* pointing at the real git dir. Use `git rev-parse` -> to resolve the correct path: - -```bash -# Resolve the correct exclude path (works with worktrees/submodules) -EXCLUDE_PATH=$(git rev-parse --git-path info/exclude) -echo ".squad/" >> "$EXCLUDE_PATH" -``` - ---- - -## Consultation Log - -Track all consultations in `/consultations/`: - -**`/consultations/kubernetes-dashboard.md`:** -```markdown -# kubernetes-dashboard - -**First consulted:** 2026-02-27 -**Last session:** 2026-03-15 -**License:** Apache-2.0 - -## Sessions - -### 2026-02-27 -- use-async-await.md: "### Always use async/await..." -- validate-inputs.md: "### Validate inputs at API..." - -### 2026-03-15 -- prefer-composition.md: "### Prefer composition over..." -``` - ---- - -## Success Criteria - -1. **Invisible by default:** `git status` shows nothing in consult mode -2. **No pollution upstream:** Project `.squad/` never modifies global squad without explicit approval -3. **No pollution downstream:** Project-specific learnings stay in project or are discarded -4. **Audit trail:** `/consultations/` tracks what was extracted from where -5. **License safety:** User warned about copyleft extraction risks -6. **Matches InitResult:** `SetupConsultModeResult.createdFiles` array matches `InitResult.createdFiles` pattern - ---- - -## Non-Goals (v1) - -- Cross-machine sync of global squad (users can use git or `squad export/import`) -- Consulting on squadified projects (error out for now) -- Automatic extraction (always requires user approval) -- SDK-side heuristic classification (Scribe handles this via LLM during session) - ---- - -## References - -- [Personal Squad Guide](../docs/guide/personal-squad.md) -- [SDK Sharing Module](../packages/squad-sdk/src/sharing/) -- [Export Command](../packages/squad-cli/src/cli/commands/export.ts) diff --git a/.squad/identity/prd-next-waves.md b/.squad/identity/prd-next-waves.md deleted file mode 100644 index d9438f0f2..000000000 --- a/.squad/identity/prd-next-waves.md +++ /dev/null @@ -1,85 +0,0 @@ -# Next-Wave PRD: 4-Wave Execution Plan - -**Date:** 2026-02-24 -**Status:** Ready for Wave A execution -**Framework:** 4 sequential waves, all work through PRs with squad member review before merge - -## Wave A: Polish & Consistency (17 items) - -Focus: Visual refinement, UX polish, consistency across all surfaces. - -### Phase 1: Text-over-emoji convention -- [ ] #340: P2 UX Polish β€” Text over Emoji, Simplicity over Fidget - - Remove "you:" from user messages - - Unify separators to ASCII `-` (not `─` or `β”„`) - - Static "Thinking..." (not carousel) - - Text status labels in `/agents` (`[WORK]`, `[STREAM]`, `[ERR]`, `[IDLE]`) - - Single-space indent for status lines - - Replace ornamental emoji with text - -### Phase 2: First-run experience -- [ ] #341: First-run wow moment architecture - - Init ceremony (typewriter + staggered reveal) - - First-launch detection via `.squad/.first-run` marker - - NO_COLOR respect in init animations - -### Phase 3: Help text structure -- [ ] #419–#423, #426: First-30-second pain points - - Help text structure (P0) - - SDK connection feedback (P0) - - Spinner context (P0) - - Default behavior clarity (P0) - - Welcome animation speed (P1) - - Tagline consistency (P1) - -### Phase 4: ASCII-only separators -- [ ] #405, #404, #407: ASCII-only separators and NO_COLOR exit message - - All banners use ASCII `-` instead of `Β·` or `β€”` - - Exit message uses `--` instead of `β—†` - -### Phase 5: Version format -- [ ] #431, #429: Bare semver canonical standard - - All version commands output bare semver (e.g., `0.8.5.1`) - - Display contexts (help, banner) use `squad v{VERSION}` for branding - ---- - -## Wave B: Reliability (TBD) - -Focus: Bug fixes, timeout handling, error recovery, input buffering. - -Related: REPL Experience Audit findings (#418, #425, #428, #430, #432, #433, #434) - ---- - -## Wave C: Testing (TBD) - -Focus: E2E test harness, integration test coverage, speed gates. - -Related: Missing E2E integration tests (#433), Speed gate enforcement - ---- - -## Wave D: Delight (TBD) - -Focus: Polish beyond MVP, performance optimizations, wow moments. - ---- - -## Process Directive - -**All work flows through PRs with squad member review before merge.** - -1. Assign issues to squad members -2. Create PR for each issue (or group related issues) -3. Require squad member review (assign reviewer in PR template) -4. Merge only after approval -5. Log PRs to session log upon merge - ---- - -## Success Metrics - -- **Wave A completion:** All 17 polish items in main branch, users report "feels polished" -- **No regressions:** Speed gate tests pass, all P0 tests green -- **Team velocity:** 4-5 PRs per day, mean review time <1 hour diff --git a/.squad/identity/prd-sdk-init-shoreup.md b/.squad/identity/prd-sdk-init-shoreup.md deleted file mode 100644 index ad0eaa5eb..000000000 --- a/.squad/identity/prd-sdk-init-shoreup.md +++ /dev/null @@ -1,203 +0,0 @@ -# PRD: SDK Init Shore-Up -**Initiative:** Comprehensive SDK Init Quality Gate -**Owner:** Flight -**Sprint:** v0.9.0 -**Status:** Draft - ---- - -## Problem Space - -SDK initialization (`squad init --sdk`) produces incomplete and inconsistent squad state. Users who consume `@bradygaster/squad-sdk` to build their own squads encounter three critical gaps: - -1. **Config ↔ team.md sync broken** β€” When members are added/removed through SDK workflows, `squad.config.ts` doesn't update. The coordinator flow updates `team.md`, `routing.md`, and `registry.json`, but has no step for `squad.config.ts`. Result: SDK consumers can't reference new members in code. - -2. **Built-in members missing from SDK surface** β€” Ralph (work monitor) and @copilot (coding agent) exist at the coordinator level but aren't included in generated `squad.config.ts`. Ralph works in CLI squads but SDK consumers have no way to reference it. Similarly, `routing.md` has `@copilot` rules pre-configured, but `team.md` roster and `squad.config.ts` are missing the entry. - -3. **CastingEngine bypassed during CLI init** β€” The `CastingEngine` class maintains a curated universe template system (Apollo 13, The Usual Suspects, etc.) with carefully crafted role definitions. However, the CLI init flow completely bypasses this β€” the LLM picks arbitrary universes from scratch. This defeats months of universe curation work. - -**Impact:** -- SDK squads can't access full feature set (Ralph, @copilot unavailable) -- Adding members requires manual `squad.config.ts` edits (breaks "code-gen from team.md" promise) -- Universe quality degrades (arbitrary vs. curated) -- Test matrix shows 64% verified, 12% gaps, 24% needs setup (#341) - ---- - -## Root Causes - -### 1. Config Sync Gap -**Issue:** #337 -The coordinator's `add-member` and `remove-member` flows update: -- βœ… `team.md` roster -- βœ… `routing.md` assignments -- βœ… `registry.json` charter paths -- ❌ `squad.config.ts` member exports - -**Why it matters:** SDK consumers import from `squad.config.ts`. Without this update, newly added members are invisible to user code. - -### 2. Built-in Member Gaps -**Issues:** #338, #339 -Ralph and @copilot are first-class members in CLI squads but second-class citizens in SDK squads: -- Ralph: Missing from `squad.config.ts` generation (exists only in coordinator internals) -- @copilot: Pre-configured in `routing.md` but missing from `team.md` roster and `squad.config.ts` - -**Why it matters:** SDK users can't leverage work monitoring (Ralph) or coding agent routing (@copilot) β€” features that work perfectly in CLI squads. - -### 3. CastingEngine Bypass -**Issue:** #342 -The `CastingEngine` class is Squad's universe template system β€” it knows Apollo 13, The Usual Suspects, and curated role definitions. But during `squad init`, the CLI path calls the LLM directly, bypassing `CastingEngine` entirely. - -**Why it matters:** Months of universe curation (role synergy, naming conventions, expertise mapping) is wasted. Every init generates a fresh, arbitrary team instead of leveraging proven templates. - ---- - -## Solution: Phased Shore-Up - -### Phase 1: Fix the Gaps (Foundational) -**Scope:** Small -**Issues:** #337, #338, #339 -**Owner:** EECOM (core dev) + CAPCOM (SDK expert) - -**Work:** -1. **Config sync** (#337) - - Add `squad.config.ts` update step to coordinator's `add-member` and `remove-member` flows - - Ensure `squad.config.ts` regenerates when `team.md` roster changes - - Test: Add member via coordinator β†’ verify `squad.config.ts` export appears - -2. **Ralph inclusion** (#338) - - Add Ralph to `squad.config.ts` template generation - - Include charter path placeholder (Ralph has no charter file β€” document this as known gap) - - Test: `squad init --sdk` β†’ verify Ralph in config exports - -3. **@copilot roster entry** (#339) - - Add @copilot to `team.md` roster template (status: πŸ€– Coding Agent) - - Add @copilot to `squad.config.ts` generation - - Align with existing `routing.md` rules (already configured) - - Test: `squad init --sdk` β†’ verify @copilot in roster and config - -**Success criteria:** -- All three members (user-added, Ralph, @copilot) appear in `squad.config.ts` -- `team.md` ↔ `squad.config.ts` sync verified through add/remove cycles -- No manual config edits required - ---- - -### Phase 2: Wire CastingEngine (Quality) -**Scope:** Medium -**Issue:** #342 -**Owner:** EECOM + Procedures (prompt engineer) - -**Work:** -1. **Route CLI init through CastingEngine** - - Refactor `packages/squad-cli/src/commands/init.ts` to use `CastingEngine.cast()` - - Pass universe selection to `CastingEngine` (default: Apollo 13) - - Remove direct LLM universe generation logic - -2. **Universe selection UX** - - Prompt user to choose universe during `squad init`: - - Apollo 13 (Mission Control) - - The Usual Suspects (Crime drama) - - Custom (legacy LLM path β€” warn about quality) - - Default to Apollo 13 for `--sdk` path - -3. **Template validation** - - Verify all `CastingEngine` templates include Ralph and @copilot - - Ensure templates produce valid `squad.config.ts` exports - - Test all universe options produce complete state - -**Success criteria:** -- CLI init uses `CastingEngine` by default -- All curated universes (Apollo 13, Usual Suspects) generate complete configs -- Custom universe path preserved but flagged as legacy - ---- - -### Phase 3: Exercise Test Matrix (Verification) -**Scope:** Large -**Issues:** #340, #341 -**Owner:** FIDO (quality owner) + CAPCOM - -**Work:** -1. **Active exercise testing** (#340) - - Systematically exercise all 29 untested features in SDK squads - - Document test scenarios for each feature - - Identify features that require special setup (telemetry, VS Code extension, etc.) - -2. **Full test matrix completion** (#341) - - Current state: 32/50 verified (64%), 6 gaps (12%), 12 needs setup (24%) - - Target: 50/50 verified (100%) - - For each gap: - - Determine if SDK limitation or test setup issue - - Document workarounds or file SDK enhancement issues - - Mark as "verified" or "documented gap" - -3. **Regression test suite** - - Create smoke test suite for SDK init covering all 50 features - - Run on every SDK-related PR - - Gate releases on 100% verified status - -**Success criteria:** -- All 50 features verified in SDK squads -- No undocumented gaps -- Automated regression suite in place - ---- - -## Issue Mapping - -| Phase | Issue | Title | Owner | Priority | -|-------|-------|-------|-------|----------| -| 1 | #337 | Config ↔ team.md sync broken | EECOM + CAPCOM | P1 | -| 1 | #338 | Ralph missing from generated config | EECOM + CAPCOM | P1 | -| 1 | #339 | @copilot routing without roster entry | EECOM + CAPCOM | P1 | -| 2 | #342 | CLI casting bypasses CastingEngine | EECOM + Procedures | P1 | -| 3 | #340 | 29 features need active exercise testing | FIDO + CAPCOM | P2 | -| 3 | #341 | Full test results (32/50 verified) | FIDO + CAPCOM | P2 | - ---- - -## Timeline & Dependencies - -**Phase 1** (1 sprint) -- Can start immediately -- Blocks: Phase 2 (CastingEngine needs complete config system) - -**Phase 2** (1 sprint) -- Depends on: Phase 1 (config sync must work before universe templates rely on it) -- Blocks: Phase 3 (test matrix requires stable init flow) - -**Phase 3** (2 sprints) -- Depends on: Phase 1 + Phase 2 (complete, stable init flow required) -- Deliverable: 100% verified SDK feature parity - -**Total estimated scope:** 4 sprints - ---- - -## Success Metrics - -1. **Config completeness:** `squad.config.ts` includes all members (user-added, Ralph, @copilot) without manual intervention -2. **Universe quality:** 90%+ of `squad init` runs use curated templates (Apollo 13/Usual Suspects) vs. custom LLM generation -3. **Feature parity:** 50/50 features verified (100%) in SDK squads -4. **Zero gaps:** No undocumented differences between CLI and SDK squad capabilities - ---- - -## Open Questions - -1. **Ralph charter:** Ralph has no charter file. Should we create one, or document as "built-in, no charter"? -2. **@copilot auto-routing:** Should SDK squads enable `copilot-auto-assign: true` by default, or leave it opt-in? -3. **Legacy custom universe:** Should we deprecate the LLM-generated custom universe path entirely, or keep it for edge cases? - ---- - -## Related Work - -- #316 β€” Cross-Squad Orchestration (may need SDK init patterns) -- #321 β€” squad upgrade/init does not stamp version (version stamping gap) -- #329 β€” Personal Squad updates (may intersect with config sync patterns) - ---- - -**Next steps:** Phase 1 kickoff. EECOM + CAPCOM to review and estimate. diff --git a/.squad/identity/sdk-init-implementation-roadmap.md b/.squad/identity/sdk-init-implementation-roadmap.md deleted file mode 100644 index ad970db69..000000000 --- a/.squad/identity/sdk-init-implementation-roadmap.md +++ /dev/null @@ -1,727 +0,0 @@ -# SDK Init Implementation Roadmap - -> Deep dive analysis and implementation plan for `squad init --sdk` - -**Author:** EECOM (Core Dev) -**Date:** 2025-03-08 -**Purpose:** Trace the complete init flow, identify gaps, and roadmap fixes for the unified PRD - ---- - -## 1. CURRENT INIT FLOW β€” END-TO-END TRACE - -### 1.1 CLI Entry β†’ Init Handler - -**File:** `packages/squad-cli/src/cli-entry.ts` - -``` -Line 227: if (cmd === 'init') -Line 228-241: Parse --mode, --global, --no-workflows, --sdk flags -Line 246: Call runInit(dest, { includeWorkflows, sdk }) -``` - -**What happens:** -- `--sdk` flag is captured and passed to `runInit()` as `options.sdk` -- No other init-time processing β€” flag is just forwarded - -### 1.2 runInit β†’ SDK initSquad - -**File:** `packages/squad-cli/src/cli/core/init.ts` - -```typescript -Line 87: export async function runInit(dest: string, options: RunInitOptions = {}) -Line 106-125: Build SDK InitOptions object -Line 116: configFormat: options.sdk ? 'sdk' : 'markdown' -Line 138: result = await sdkInitSquad(initOptions) -``` - -**What happens:** -- CLI options are transformed into SDK `InitOptions` -- `configFormat` is set to `'sdk'` when `--sdk` is true -- Only **Scribe** is included in the agents array (hardcoded line 110-115) -- **NO coordinator prompts at this stage** β€” that only happens in the REPL shell - -### 1.3 SDK initSquad β†’ File Generation - -**File:** `packages/squad-sdk/src/config/init.ts` - -```typescript -Line 530: export async function initSquad(options: InitOptions): Promise -Line 573-591: Create .squad/ directory structure -Line 594-637: Create .squad/config.json (NOT squad.config.ts) -Line 640-657: Create config file (squad.config.ts OR squad.config.json OR skip) -Line 646: configFileName = configFormat === 'sdk' ? 'squad.config.ts' : ... -Line 649: configContent = configFormat === 'sdk' ? generateSDKBuilderConfig(options) : ... -Line 664-678: Create agent directories and files (charter.md, history.md) -Line 745-770: Create team.md (empty roster) -Line 774-793: Create routing.md -``` - -**What files are created (--sdk path):** - -1. `.squad/` directory structure -2. `.squad/config.json` β€” squad settings (platform, extraction, etc.) -3. `squad.config.ts` β€” SDK builder config (defineSquad/defineTeam/defineAgent) -4. `.squad/agents/scribe/charter.md` -5. `.squad/agents/scribe/history.md` -6. `.squad/identity/now.md` -7. `.squad/identity/wisdom.md` -8. `.squad/ceremonies.md` -9. `.squad/decisions.md` -10. `.squad/team.md` β€” **empty roster** (no Members table entries) -11. `.squad/routing.md` -12. `.squad/templates/` (if includeTemplates) -13. `.github/workflows/` (if includeWorkflows) -14. `squad.agent.md` (Copilot prompt template) -15. `.init-prompt` (if options.prompt is provided) - -**CRITICAL GAP:** `squad.config.ts` is generated with hardcoded Scribe only. No entries for team members that will be added later. - ---- - -## 2. REPL AUTO-CAST FLOW (PHASE 1 + PHASE 2) - -### 2.1 Shell Launch β†’ Init Mode Detection - -**File:** `packages/squad-cli/src/cli/shell/lifecycle.ts` - -```typescript -Line 58-100: async initialize() -Line 82: this.discoveredAgents = parseTeamManifest(teamContent) -Line 84-90: If no agents found, check for .init-prompt file -``` - -**What happens:** -- Shell reads `team.md` -- If `## Members` table is empty, enters "Auto-Cast Mode" -- If `.init-prompt` exists (from `squad init "prompt"`), uses that prompt -- Otherwise, prompts user to describe project - -### 2.2 Init Mode β†’ Coordinator Proposal (Phase 1) - -**File:** `packages/squad-cli/src/cli/shell/index.ts` - -```typescript -Line 382: async function handleInitCast(parsed: ParsedInput, skipConfirmation?: boolean) -Line 386-393: Check for .init-prompt file -Line 402-415: Create Init Mode coordinator session -Line 410: const initSysPrompt = buildInitModePrompt({ teamRoot }) -Line 419-435: Send prompt and collect response -Line 438: const proposal = parseCastResponse(accumulated) -``` - -**What happens:** -- Creates a **temporary coordinator session** with Init Mode prompt -- Init Mode prompt (from `coordinator.ts`) instructs coordinator to propose a team -- Response is parsed into a `CastProposal` (name, role, scope, universe) -- **NO file writes yet** β€” just a proposal - -**Init Mode Prompt:** `packages/squad-cli/src/cli/shell/coordinator.ts` line 42-86 - -### 2.3 User Confirmation β†’ Finalize Cast (Phase 2) - -**File:** `packages/squad-cli/src/cli/shell/index.ts` - -```typescript -Line 456-474: If not skipConfirmation, show proposal and wait for y/n -Line 489: async function finalizeCast(proposal: CastProposal, parsed: ParsedInput) -Line 492: const result = await createTeam(teamRoot, proposal) -``` - -**What happens:** -- User confirms with "y" -- `createTeam()` is called (from `cast.ts`) -- **All team files are created** (see section 2.4) -- Re-dispatches original user message to the new team - -### 2.4 createTeam β†’ File Generation - -**File:** `packages/squad-cli/src/cli/core/cast.ts` - -```typescript -Line 367: export async function createTeam(teamRoot: string, proposal: CastProposal) -Line 380-411: Create agent directories (charter.md, history.md) -Line 414-457: Update team.md (insert Members table) -Line 459-486: Update routing.md (insert routing table) -Line 489-525: Create casting/ files (registry.json, history.json, policy.json) -``` - -**What files are created/updated:** - -1. `.squad/agents/{name}/charter.md` (for each member) -2. `.squad/agents/{name}/history.md` (for each member) -3. `.squad/team.md` β€” **updated** with Members table -4. `.squad/routing.md` β€” **updated** with routing table -5. `.squad/casting/registry.json` β€” agent registry -6. `.squad/casting/history.json` β€” casting snapshot -7. `.squad/casting/policy.json` β€” universe policy - -**CRITICAL GAP:** `squad.config.ts` is **NOT** updated with new team members. - ---- - -## 3. ADD TEAM MEMBER FLOW - -### 3.1 During Phase 2 (REPL auto-cast) - -**Current State:** -- Members are added by `createTeam()` function -- Files created: charter.md, history.md -- Files updated: team.md, routing.md, casting/registry.json - -**Gap:** -- `squad.config.ts` is **NOT** updated with new `defineAgent()` entries - -### 3.2 After Phase 2 (manual add later) - -**Current State:** -- **NO built-in command** for adding team members after init -- Users must manually: - 1. Create `.squad/agents/{name}/` directory - 2. Write `charter.md` and `history.md` - 3. Update `team.md` Members table - 4. Update `routing.md` routing table - 5. Update `.squad/casting/registry.json` - 6. **Manually update `squad.config.ts`** (if using --sdk mode) - -**Gap:** -- No `squad hire` or `squad add-member` command exists -- No automated flow for adding members to SDK config - ---- - -## 4. REMOVE TEAM MEMBER FLOW - -### 4.1 Current State - -**NO built-in remove flow exists.** - -Users must manually: -1. Remove agent directory (`.squad/agents/{name}/`) -2. Remove from `team.md` Members table -3. Remove from `routing.md` routing table -4. Remove from `.squad/casting/registry.json` -5. **Manually remove from `squad.config.ts`** (if using --sdk mode) - -**Gap:** -- No `squad remove-member` command -- No cleanup utilities -- No squad.config.ts sync - ---- - -## 5. RALPH & @COPILOT PLACEMENT - -### 5.1 Ralph (Work Monitor) - -**Current State:** -- Ralph is **automatically added** by `createTeam()` if not already present -- Charter template exists in `cast.ts` (line 329-336) -- Added to team.md, routing.md, casting/registry.json - -**Gap:** -- Ralph is **NOT** added to `squad.config.ts` during auto-cast -- No `defineAgent('ralph', ...)` entry - -**Where Ralph SHOULD be created:** -- During `createTeam()` when casting a team (auto-cast Phase 2) βœ… (partially works) -- During `squad init --sdk` if user provides a prompt ❌ (missing) -- Ralph should be in `squad.config.ts` ❌ (missing) - -### 5.2 @copilot (Coding Agent) - -**Current State:** -- `squad copilot` command exists (`packages/squad-cli/src/cli/commands/copilot.ts`) -- Command can add/remove @copilot entry in `team.md` -- Creates `.squad/agents/copilot/` directory - -**Gap:** -- `copilot` command does **NOT** update `squad.config.ts` -- No `defineAgent('copilot', ...)` entry is added - -**Where @copilot SHOULD be offered:** -- During `squad init` (optional, with flag like `--with-copilot`) ❌ (missing) -- Via `squad copilot` command (currently only updates team.md) ⚠️ (partial) - ---- - -## 6. CASTINGENGINE INTEGRATION - -### 6.1 Current State - -**File:** `packages/squad-sdk/src/casting/casting-engine.ts` - -```typescript -export class CastingEngine { - getUniverses(): UniverseId[] - getUniverse(id: UniverseId): UniverseTemplate | undefined - castTeam(config: CastingConfig): CastMember[] -} -``` - -**What it does:** -- Provides universe templates (Usual Suspects, Ocean's Eleven) -- Maps roles to characters with personality and backstory -- Returns `CastMember[]` with name, role, personality, backstory - -**Gap:** -- CastingEngine is **NEVER called** during CLI init -- Init Mode coordinator uses an **LLM prompt** to generate teams (not CastingEngine) -- No integration point exists - -### 6.2 Where CastingEngine SHOULD be integrated - -**Option A: Replace Init Mode prompt with CastingEngine** -- Pro: Deterministic, no LLM needed for team proposals -- Con: Less flexible, no user input interpretation -- Integration point: `handleInitCast()` in shell/index.ts - -**Option B: Use CastingEngine to AUGMENT proposals** -- Pro: Keeps LLM flexibility, adds structured character data -- Con: More complex flow -- Integration point: After `parseCastResponse()`, before `createTeam()` - -**Option C: Offer CastingEngine as an alternative init mode** -- Pro: Clean separation, users can choose -- Con: Adds CLI complexity -- Integration point: New flag like `--use-casting-engine` or `--universe ` - -**Recommended:** Option B -- Keep Init Mode LLM for flexibility -- After parsing proposal, call `CastingEngine.castTeam()` to enrich members with personality/backstory -- Merge into charter.md generation - -### 6.3 Integration API - -**Proposed flow:** - -```typescript -// In handleInitCast(), after parseCastResponse() -const proposal = parseCastResponse(accumulated); -if (!proposal) { /* error */ } - -// NEW: Enrich with CastingEngine -const engine = new CastingEngine(); -const enrichedMembers = enrichWithCasting(proposal, engine); -proposal.members = enrichedMembers; - -// Continue to finalizeCast() -``` - -**New function:** - -```typescript -function enrichWithCasting( - proposal: CastProposal, - engine: CastingEngine -): CastMember[] { - const universeId = mapUniverseName(proposal.universe); - const roles = proposal.members.map(m => m.role as AgentRole); - - const castMembers = engine.castTeam({ - universe: universeId, - teamSize: proposal.members.length, - requiredRoles: roles, - }); - - // Merge cast data into proposal members - return proposal.members.map((m, i) => ({ - ...m, - personality: castMembers[i]?.personality || personalityForRole(m.role), - backstory: castMembers[i]?.backstory || '', - })); -} -``` - -**Where to add:** `packages/squad-cli/src/cli/shell/index.ts` (near handleInitCast) - ---- - -## 7. IMPLEMENTATION ROADMAP - -### 7.1 Fix 1: squad.config.ts Sync During Auto-Cast - -**Problem:** `squad.config.ts` is not updated when team members are added during auto-cast. - -**Files to modify:** -1. `packages/squad-cli/src/cli/core/cast.ts` β€” `createTeam()` function -2. New utility: `packages/squad-cli/src/cli/core/squad-config-sync.ts` - -**What to change:** -- Add a check: if `squad.config.ts` exists in teamRoot -- Parse existing config using TypeScript AST or regex -- Append `defineAgent()` entries for new members -- Write back to `squad.config.ts` - -**Dependencies:** -- Requires AST parser (TypeScript compiler API) or regex-based append -- Risk: High complexity for AST parsing, medium for regex - -**Test files:** -- `test/init-sdk.test.ts` β€” add test for auto-cast + config sync -- `test/cast-parser.test.ts` β€” verify squad.config.ts update - -**Risk Assessment:** 🟑 Medium -- AST parsing adds dependency on `typescript` package -- Regex-based append is fragile but simpler -- Edge case: User has customized squad.config.ts structure - ---- - -### 7.2 Fix 2: squad.config.ts Update During CLI Init - -**Problem:** `squad init --sdk` only creates Scribe in squad.config.ts, missing Ralph and other agents. - -**Files to modify:** -1. `packages/squad-sdk/src/config/init.ts` β€” `initSquad()` function -2. `packages/squad-sdk/src/config/init.ts` β€” `generateSDKBuilderConfig()` function - -**What to change:** -- Include Ralph in the default agents array when `configFormat === 'sdk'` -- Update `generateSDKBuilderConfig()` to include all agents from `options.agents` - -**Code change:** - -```typescript -// In initSquad(), line ~660-678 -if (configFormat === 'sdk') { - // Add Ralph to agents if not present - const sdkAgents = [...agents]; - const hasRalph = agents.some(a => a.name === 'ralph'); - if (!hasRalph) { - sdkAgents.push({ name: 'ralph', role: 'ralph', displayName: 'Ralph' }); - } - - // Generate config with all agents - const configContent = generateSDKBuilderConfig({ - ...options, - agents: sdkAgents, - }); -} -``` - -**Dependencies:** None - -**Test files:** -- `test/init-sdk.test.ts` β€” verify Ralph is in squad.config.ts -- `test/init.test.ts` β€” verify Scribe and Ralph are both present - -**Risk Assessment:** 🟒 Low -- Simple fix, no breaking changes - ---- - -### 7.3 Fix 3: Add `squad hire` Command - -**Problem:** No built-in command to add team members after init. - -**Files to create:** -1. `packages/squad-cli/src/cli/commands/hire.ts` (new) - -**Files to modify:** -1. `packages/squad-cli/src/cli-entry.ts` β€” add routing for `hire` command - -**What to implement:** - -```typescript -// New command: squad hire [--name ] [--role ] -export async function runHire(options: HireOptions): Promise { - // 1. Prompt for name and role (if not provided) - // 2. Create .squad/agents/{name}/ directory - // 3. Generate charter.md and history.md - // 4. Update team.md Members table - // 5. Update routing.md routing table - // 6. Update .squad/casting/registry.json - // 7. If squad.config.ts exists, append defineAgent() entry - // 8. Success message -} -``` - -**Dependencies:** -- Reuse `generateCharter()` and `generateHistory()` from `cast.ts` -- Reuse squad.config.ts sync utility from Fix 1 - -**Test files:** -- `test/hire.test.ts` (new) - -**Risk Assessment:** 🟑 Medium -- Requires interactive prompts (use `enquirer` or similar) -- squad.config.ts sync is complex - ---- - -### 7.4 Fix 4: Add `squad remove-member` Command - -**Problem:** No built-in command to remove team members. - -**Files to create:** -1. `packages/squad-cli/src/cli/commands/remove-member.ts` (new) - -**Files to modify:** -1. `packages/squad-cli/src/cli-entry.ts` β€” add routing - -**What to implement:** - -```typescript -// New command: squad remove-member -export async function runRemoveMember(name: string): Promise { - // 1. Confirm removal (interactive prompt) - // 2. Delete .squad/agents/{name}/ directory - // 3. Remove from team.md Members table - // 4. Remove from routing.md routing table - // 5. Remove from .squad/casting/registry.json - // 6. If squad.config.ts exists, remove defineAgent() entry - // 7. Success message -} -``` - -**Dependencies:** -- squad.config.ts sync utility from Fix 1 - -**Test files:** -- `test/remove-member.test.ts` (new) - -**Risk Assessment:** 🟑 Medium -- Removing from squad.config.ts is error-prone -- Risk of orphaned references in other files - ---- - -### 7.5 Fix 5: @copilot Integration in Init - -**Problem:** No way to add @copilot during `squad init`. - -**Files to modify:** -1. `packages/squad-cli/src/cli-entry.ts` β€” add `--with-copilot` flag -2. `packages/squad-cli/src/cli/core/init.ts` β€” handle flag -3. `packages/squad-sdk/src/config/init.ts` β€” include @copilot agent - -**What to change:** - -```typescript -// In cli-entry.ts, line ~246 -const withCopilot = args.includes('--with-copilot'); -runInit(dest, { includeWorkflows, sdk, withCopilot }); - -// In init.ts, pass to SDK -const initOptions: InitOptions = { - // ... - agents: [ - { name: 'scribe', role: 'scribe', displayName: 'Scribe' }, - ...(options.withCopilot ? [{ name: 'copilot', role: 'developer', displayName: 'Copilot' }] : []), - ], -}; -``` - -**Dependencies:** None - -**Test files:** -- `test/init.test.ts` β€” verify @copilot is created with flag - -**Risk Assessment:** 🟒 Low - ---- - -### 7.6 Fix 6: CastingEngine Integration - -**Problem:** CastingEngine exists but is never used during init. - -**Files to modify:** -1. `packages/squad-cli/src/cli/shell/index.ts` β€” `handleInitCast()` function -2. `packages/squad-cli/src/cli/core/cast.ts` β€” add enrichment function - -**What to implement:** - -```typescript -// In handleInitCast(), after parseCastResponse() -import { CastingEngine } from '@bradygaster/squad-sdk/casting'; - -const proposal = parseCastResponse(accumulated); -if (!proposal) { /* error */ } - -// NEW: Enrich with CastingEngine -const engine = new CastingEngine(); -const enrichedProposal = enrichWithCasting(proposal, engine); - -// Show proposal with enriched data -await finalizeCast(enrichedProposal, parsed); -``` - -**New function in cast.ts:** - -```typescript -export function enrichWithCasting( - proposal: CastProposal, - engine: CastingEngine -): CastProposal { - // Map universe name to CastingEngine universe ID - const universeId = mapUniverseName(proposal.universe); - - // Cast team using CastingEngine - const roles = proposal.members.map(m => m.role as AgentRole); - const castMembers = engine.castTeam({ - universe: universeId, - teamSize: proposal.members.length, - requiredRoles: roles, - }); - - // Merge casting data into proposal - const enrichedMembers = proposal.members.map((m, i) => ({ - ...m, - personality: castMembers[i]?.personality || personalityForRole(m.role), - backstory: castMembers[i]?.backstory || '', - })); - - return { ...proposal, members: enrichedMembers }; -} - -function mapUniverseName(name: string): UniverseId { - if (/usual suspects/i.test(name)) return 'usual-suspects'; - if (/ocean.*eleven/i.test(name)) return 'oceans-eleven'; - return 'usual-suspects'; // fallback -} -``` - -**Dependencies:** -- Requires exporting `AgentRole` type from casting-engine.ts -- Update `generateCharter()` to use personality and backstory from enriched data - -**Test files:** -- `test/casting.test.ts` β€” verify enrichment works -- `test/init-autocast.test.ts` β€” verify end-to-end flow - -**Risk Assessment:** 🟑 Medium -- Universe name mapping is heuristic -- Requires refactoring charter generation - ---- - -### 7.7 Fix 7: Ralph Creation During Init - -**Problem:** Ralph is not created during `squad init --sdk` with a prompt. - -**Files to modify:** -1. `packages/squad-sdk/src/config/init.ts` β€” `initSquad()` function - -**What to change:** -- When `options.prompt` is provided, include Ralph in agents array -- When `configFormat === 'sdk'`, include Ralph in squad.config.ts - -**Code change:** - -```typescript -// In initSquad(), after agents are defined -if (options.prompt || configFormat === 'sdk') { - // Ensure Ralph is included - const hasRalph = agents.some(a => a.name === 'ralph'); - if (!hasRalph) { - agents.push({ name: 'ralph', role: 'ralph', displayName: 'Ralph' }); - } -} -``` - -**Dependencies:** None - -**Test files:** -- `test/init-prompt.test.ts` β€” verify Ralph is created - -**Risk Assessment:** 🟒 Low - ---- - -## 8. DEPENDENCY GRAPH - -``` -Fix 1 (squad.config.ts sync utility) - ↓ -Fix 2 (CLI init Ralph) -Fix 3 (squad hire command) ← depends on Fix 1 -Fix 4 (squad remove-member) ← depends on Fix 1 -Fix 5 (@copilot init flag) -Fix 6 (CastingEngine integration) -Fix 7 (Ralph during init) -``` - -**Critical Path:** -1. Fix 1 (sync utility) β†’ enables all other fixes -2. Fix 2 (Ralph in init) β†’ low-hanging fruit -3. Fix 7 (Ralph with prompt) β†’ completes Ralph story -4. Fix 6 (CastingEngine) β†’ high value, medium risk -5. Fix 3 (hire command) β†’ user-facing feature -6. Fix 4 (remove command) β†’ nice-to-have -7. Fix 5 (@copilot flag) β†’ bonus feature - ---- - -## 9. OPEN QUESTIONS - -### 9.1 squad.config.ts Sync Strategy - -**Question:** Should we use AST parsing or regex for squad.config.ts updates? - -**Options:** -- **AST (TypeScript Compiler API):** Precise, handles complex syntax, heavy dependency -- **Regex:** Simple, fragile, works for 90% of cases -- **Template-based:** Replace entire file, loses user customizations - -**Recommendation:** Start with regex, upgrade to AST if issues arise. - -### 9.2 CastingEngine vs LLM Proposals - -**Question:** Should CastingEngine replace the LLM-based Init Mode prompt? - -**Options:** -- **Replace:** Deterministic, no LLM needed, less flexible -- **Augment:** Keep LLM for flexibility, use CastingEngine to enrich -- **Parallel:** Offer both modes (flag to choose) - -**Recommendation:** Augment. Keep LLM for user intent parsing, use CastingEngine for character data. - -### 9.3 Ralph as a Default vs Optional - -**Question:** Should Ralph always be created, or opt-in? - -**Current behavior:** Ralph is auto-added during auto-cast, but NOT during `squad init --sdk`. - -**Options:** -- **Always include Ralph:** Simplifies the mental model -- **Opt-in with flag:** `--with-ralph` (more flexible) -- **Auto-include in SDK mode only:** Matches current auto-cast behavior - -**Recommendation:** Always include Ralph (both init paths). He's a core team member. - ---- - -## 10. SUMMARY - -### Current State -- `squad init --sdk` creates minimal files (Scribe only in squad.config.ts) -- Auto-cast (REPL Phase 1 + 2) creates full team but doesn't sync squad.config.ts -- No commands for adding/removing members after init -- CastingEngine exists but is never used -- Ralph is inconsistently created - -### Fixes Required -1. squad.config.ts sync during auto-cast -2. Ralph in CLI init -3. `squad hire` command -4. `squad remove-member` command -5. @copilot init flag -6. CastingEngine integration -7. Ralph during init with prompt - -### Implementation Order -1. Fix 1 (sync utility) β€” foundation -2. Fix 2, 7 (Ralph fixes) β€” quick wins -3. Fix 6 (CastingEngine) β€” high value -4. Fix 3, 4, 5 (commands & flags) β€” polish - ---- - -**Next Steps:** -1. Review this roadmap with Brady -2. Prioritize fixes for unified PRD -3. Create GitHub issues for each fix -4. Assign to team members based on expertise - -**END OF ROADMAP** diff --git a/.squad/identity/sdk-init-technical-analysis.md b/.squad/identity/sdk-init-technical-analysis.md deleted file mode 100644 index 97d152c25..000000000 --- a/.squad/identity/sdk-init-technical-analysis.md +++ /dev/null @@ -1,634 +0,0 @@ -# SDK Init β€” Deep Technical Analysis - -**By:** CAPCOM (SDK Expert) -**Date:** 2025-01-25 -**Status:** Draft for PRD Input - ---- - -## Executive Summary - -`squad init --sdk` is **partially implemented but incomplete**. The CLI generates `squad.config.ts` with SDK builder syntax (`defineSquad`, `defineAgent`), but: - -1. **CastingEngine is bypassed** β€” CLI uses a hardcoded personality generator instead of the themed universe templates -2. **Config/team sync is one-way** β€” Adding/removing members updates markdown files but never touches `squad.config.ts` -3. **Ralph and @copilot are added inconsistently** β€” Init adds Scribe only; Ralph appears in CLI casting but not SDK init -4. **No CastingEngine integration path** β€” The SDK has a CastingEngine, but no code calls `castTeam()` -5. **Init prompt hardcodes universe selection** β€” Coordinator picks a universe, but it's never used for actual casting - ---- - -## Finding 1: squad.config.ts Generation - -### Current Implementation - -**File:** `packages/squad-sdk/src/config/init.ts` -**Lines:** 646-653, 339-376 - -When `squad init --sdk` is run (or `configFormat: 'sdk'` is passed to `initSquad()`): - -```typescript -// Line 646-653 -const configFileName = configFormat === 'sdk' ? 'squad.config.ts' : - configFormat === 'typescript' ? 'squad.config.ts' : 'squad.config.json'; -configPath = join(teamRoot, configFileName); -const configContent = configFormat === 'sdk' ? generateSDKBuilderConfig(options) : - configFormat === 'typescript' ? generateTypeScriptConfig(options) : - generateJsonConfig(options); - -await writeIfNotExists(configPath, configContent); -``` - -The `generateSDKBuilderConfig()` function (lines 339-376) creates: - -```typescript -import { - defineSquad, - defineTeam, - defineAgent, -} from '@bradygaster/squad-sdk'; - -const scribe = defineAgent({ - name: 'scribe', - role: 'scribe', - description: 'Scribe', - status: 'active', -}); - -export default defineSquad({ - version: '1.0.0', - - team: defineTeam({ - name: 'my-project', - description: 'Project description if provided', - members: ['scribe'], - }), - - agents: [scribe], -}); -``` - -### What It Does - -βœ… Generates valid TypeScript with SDK builder syntax -βœ… Creates `defineAgent()` calls for each agent in the `InitOptions.agents` array -βœ… Uses proper imports from `@bradygaster/squad-sdk` - -### What It Doesn't Do - -❌ **Never includes Ralph** β€” The `InitOptions` from `cli/core/init.ts:109-115` only includes `scribe` -❌ **Never includes @copilot** β€” The copilot agent is only added via `team-md.ts:insertCopilotSection()` -❌ **No universe or personality** β€” Agents have generic role/description only -❌ **Hardcoded to one agent** β€” The CLI passes only `scribe`, even though the function supports multiple - -### Entry Point - -**File:** `packages/squad-cli/src/cli/core/init.ts` -**Lines:** 106-125 - -```typescript -const initOptions: InitOptions = { - teamRoot: dest, - projectName: path.basename(dest) || 'my-project', - agents: [ - { - name: 'scribe', - role: 'scribe', - displayName: 'Scribe', - } - ], - configFormat: options.sdk ? 'sdk' : 'markdown', - // ... -}; - -result = await sdkInitSquad(initOptions); -``` - -**Critical gap:** The CLI init command only passes `scribe`. The interactive shell (REPL) init flow creates a full team via `createTeam()` in `cast.ts`, which generates charter.md/history.md files but **never updates squad.config.ts**. - -### What Should Happen - -1. **Parse `--sdk` flag** in CLI init command -2. If `--sdk` AND a prompt is provided, use `CastingEngine.castTeam()` to generate the full team roster -3. Pass all cast members (Lead, Developer, Tester, etc.) to `initSquad()` in the `agents` array -4. `generateSDKBuilderConfig()` should emit `defineAgent()` for all members, including Scribe and Ralph -5. Optionally include personality/backstory in agent definitions if CastingEngine data is passed through - -### Complexity - -**Small** β€” The infrastructure exists; we just need to: -- Call `CastingEngine.castTeam()` before `initSquad()` -- Map `CastMember[]` to `InitAgentSpec[]` -- Add Ralph to the hardcoded built-ins list - ---- - -## Finding 2: CastingEngine β€” The Unused Template System - -### Current Implementation - -**File:** `packages/squad-sdk/src/casting/casting-engine.ts` -**Lines:** 1-310 - -The CastingEngine is a complete, well-designed casting system: - -```typescript -export class CastingEngine { - castTeam(config: CastingConfig): CastMember[] { - // Phase 1: Fill required roles by best-fit - // Phase 2: Fill remaining slots with unassigned characters - } -} -``` - -### Available Universes - -1. **The Usual Suspects** (lines 62-115) - - Characters: Keyser, McManus, Fenster, Verbal, Hockney, Redfoot, Edie, Kobayashi - - Each has: name, personality, backstory, preferredRoles[] - -2. **Ocean's Eleven** (lines 117-182) - - Characters: Danny, Rusty, Linus, Basher, Livingston, Saul, Yen, Virgil, Turk, Reuben - -Each character includes: -- `personality`: One-line trait (e.g., "Quietly commanding; sees the whole board") -- `backstory`: Short narrative (e.g., "A legendary figure who orchestrates from the shadows") -- `preferredRoles`: Array of roles this character excels at (e.g., `['lead']`, `['developer', 'reviewer']`) - -### The Problem - -**Nobody calls `castTeam()`.** - -Searching the entire codebase: -- ❌ No imports of `CastingEngine` -- ❌ No calls to `castTeam()` -- ❌ No universe selection logic that feeds into CastingEngine - -### The CLI Bypass - -**File:** `packages/squad-cli/src/cli/core/cast.ts` -**Lines:** 218-241, 250-300 - -Instead of using CastingEngine, the CLI has: - -```typescript -function personalityForRole(role: string): string { - const lower = role.toLowerCase(); - if (/lead|architect|tech\s*lead/.test(lower)) - return 'Sees the big picture without losing sight of the details...'; - if (/frontend|ui|design/.test(lower)) - return 'Pixel-aware and user-obsessed...'; - // ... 8 more hardcoded role patterns - return 'Focused and reliable. Gets the job done without fanfare.'; -} - -function generateCharter(member: CastMember): string { - return `# ${member.name} β€” ${member.role} - -> ${personalityForRole(member.role)} - -## Identity -- **Name:** ${member.name} -- **Role:** ${member.role} -... -`; -} -``` - -**Why this is bad:** -- Duplicates logic already in CastingEngine -- Loses universe theming (no Keyser, no Danny Ocean) -- Generic personalities instead of rich backstories -- No character-to-role matching algorithm - -### What Should Happen - -1. **Replace `personalityForRole()` with CastingEngine** - - Import `CastingEngine` from `@bradygaster/squad-sdk` - - Call `engine.castTeam({ universe, requiredRoles, teamSize })` instead of parsing coordinator response into generic members - - Use `CastMember.personality` and `CastMember.backstory` in charter generation - -2. **Wire coordinator universe selection to CastingEngine** - - Coordinator picks a universe (already does this in `buildInitModePrompt`) - - Parse `UNIVERSE: Alien` from response - - Map "Alien" β†’ custom universe, or "The Usual Suspects" β†’ `'usual-suspects'` - - Pass to `castTeam()` - -3. **Generate defineAgent() calls with personality** - - Extend `InitAgentSpec` to include `personality?: string`, `backstory?: string` - - `generateSDKBuilderConfig()` emits these fields if present - -### Complexity - -**Medium** β€” Requires: -- Import CastingEngine into CLI -- Map coordinator universe names to CastingEngine IDs (or extend CastingEngine to accept freeform names) -- Modify `generateCharter()` to accept pre-built personality/backstory -- Update `createTeam()` to call CastingEngine instead of hardcoded logic - ---- - -## Finding 3: CLI Casting Flow β€” How It Actually Works - -### Current Flow (REPL Init) - -**File:** `packages/squad-cli/src/cli/shell/index.ts` -**Lines:** 834-953 - -1. User enters REPL with no team β†’ `handleInitCast()` is called -2. Coordinator is invoked with `buildInitModePrompt()` (lines 859-860) -3. Coordinator responds with: - ``` - INIT_TEAM: - - Ripley | Lead | Architecture, code review - - Dallas | Frontend Dev | React, components - UNIVERSE: Alien - PROJECT: A React app - ``` -4. `parseCastResponse()` extracts members into `CastProposal` (line 892) -5. `createTeam(teamRoot, proposal)` generates: - - `.squad/agents/{name}/charter.md` (using `generateCharter()`) - - `.squad/agents/{name}/history.md` - - `.squad/team.md` (Members table) - - `.squad/routing.md` (Work Type β†’ Agent table) - - `.squad/casting/registry.json` - - `.squad/casting/history.json` - - `.squad/casting/policy.json` - -### Built-in Agents - -**File:** `packages/squad-cli/src/cli/core/cast.ts` -**Lines:** 320-336, 380-386 - -```typescript -function scribeMember(): CastMember { - return { name: 'Scribe', role: 'Session Logger', ... }; -} - -function ralphMember(): CastMember { - return { name: 'Ralph', role: 'Work Monitor', ... }; -} - -// In createTeam(): -const hasScribe = proposal.members.some(m => /scribe/i.test(m.name)); -if (!hasScribe) allMembers.push(scribeMember()); - -const hasRalph = proposal.members.some(m => /ralph/i.test(m.name)); -if (!hasRalph) allMembers.push(ralphMember()); -``` - -βœ… **CLI casting adds Ralph** β€” The REPL init flow correctly appends Ralph -❌ **SDK init does NOT add Ralph** β€” `initSquad()` only gets `[{ name: 'scribe', ... }]` - -### @copilot Handling - -**File:** `packages/squad-cli/src/cli/core/team-md.ts` -**Lines:** 28-88 - -The @copilot section is **manually inserted** into team.md via: -- `insertCopilotSection(content, autoAssign)` β€” Injects a Markdown table row -- `removeCopilotSection(content)` β€” Strips it out - -This is **separate from** the agent roster. @copilot is not: -- In `.squad/agents/copilot/charter.md` -- In `squad.config.ts` agents array -- In `registry.json` - -It's a **pseudo-agent** β€” a UI affordance only. - -### What Should Happen - -1. **Ralph should be in SDK init agents array** β€” Modify `cli/core/init.ts:109-115` to include Ralph -2. **@copilot should be optional** β€” If `--copilot` flag is set, add it as a real agent OR keep it as a markdown-only pseudo-agent (design decision needed) -3. **REPL init should update squad.config.ts** β€” After `createTeam()` generates markdown files, call `generateSDKBuilderConfig()` and write it - -### Complexity - -**Trivial** β€” Ralph fix is a one-line change -**Medium** β€” Config sync requires wiring `createTeam()` β†’ `generateSDKBuilderConfig()` - ---- - -## Finding 4: Init Flow Entry Point - -### CLI Command Entry - -**File:** `packages/squad-cli/src/cli/core/init.ts` -**Lines:** 87-183 - -```bash -squad init --sdk "Build a React app" -``` - -Flow: -1. `runInit(dest, { sdk: true, prompt: "Build a React app" })` called -2. Creates `InitOptions` with only `scribe` in agents array (line 109-115) -3. Calls `sdkInitSquad(initOptions)` (line 138) -4. SDK writes: - - `squad.config.ts` (if `--sdk` flag set) - - `.squad/agents/scribe/charter.md` - - `.squad/agents/scribe/history.md` - - `.squad/team.md` (minimal, no roster) - - `.squad/.init-prompt` (stores the prompt for REPL auto-cast) - -**Critical:** The CLI init does NOT cast a full team. It writes the prompt to `.squad/.init-prompt` and expects the user to run `squad` (REPL) to trigger `handleInitCast()`. - -### REPL Entry - -**File:** `packages/squad-cli/src/cli/shell/index.ts` -**Lines:** 834-953 - -When REPL starts and team.md has no roster: -1. Check for `.squad/.init-prompt` (line 839-847) -2. If found, use that prompt instead of user message -3. Call `buildInitModePrompt()` β†’ coordinator picks universe/roles -4. Parse response β†’ `createTeam()` β†’ generate all files - -### The Disconnect - -- CLI `squad init --sdk` writes config but no team -- REPL auto-cast generates team but doesn't update config -- Result: **squad.config.ts has only Scribe, team.md has full roster** - -### What Should Happen - -**Option A: CLI does full casting** -1. `squad init --sdk "prompt"` calls CastingEngine immediately -2. Generates full `squad.config.ts` with all agents -3. Generates all charter/history files -4. No REPL step needed - -**Option B: Two-phase init (current design)** -1. CLI creates skeleton + stores prompt -2. REPL auto-cast generates team -3. **FIX:** REPL writes `squad.config.ts` after casting - -### Complexity - -**Option A: Medium** β€” Requires CLI to invoke coordinator or CastingEngine directly -**Option B: Small** β€” Just add config write to `createTeam()` or `finalizeCast()` - ---- - -## Finding 5: Coordinator Init Prompt β€” Universe Selection - -### Current Implementation - -**File:** `packages/squad-cli/src/cli/shell/coordinator.ts` -**Lines:** 42-86 - -```typescript -export function buildInitModePrompt(config: CoordinatorConfig): string { - return `You are the Squad Coordinator in Init Mode. - -Your job: Propose a team of 4-5 AI agents based on what the user wants to do. - -## Rules -1. Analyze the user's message to understand the project -2. Pick a fictional universe for character names (e.g., Alien, The Usual Suspects, ...) -3. Propose 4-5 agents with roles that match the project needs -4. Scribe and Ralph are always included automatically β€” do NOT include them - -## Response Format β€” you MUST use this EXACT format: - -INIT_TEAM: -- {Name} | {Role} | {scope} -UNIVERSE: {universe name} -PROJECT: {1-sentence project description} -`; -} -``` - -### What Happens - -1. Coordinator picks a universe (e.g., "Alien") -2. Coordinator invents character names fitting that universe (Ripley, Dallas, Kane) -3. CLI parses `UNIVERSE: Alien` from the response -4. **Universe is stored in `casting/history.json` but never used for logic** - -### The Gap - -- Coordinator picks "Alien" but there's no "Alien" template in CastingEngine -- CastingEngine has "The Usual Suspects" and "Ocean's Eleven" hardcoded -- No mapping from freeform universe β†’ CastingEngine template -- Coordinator can invent **any** universe, but we can't cast from it - -### What Should Happen - -**Option A: Guide coordinator to existing universes** -```typescript -2. Pick ONE of these universes: The Usual Suspects, Ocean's Eleven -``` - -**Option B: Extend CastingEngine to support freeform universes** -```typescript -castTeam({ - universe: 'custom', - customNames: { lead: 'Ripley', developer: 'Dallas', tester: 'Lambert' } -}) -``` - -**Option C: Pre-seed coordinator with CastingEngine universes** -```typescript -buildInitModePrompt(config: { availableUniverses: ['usual-suspects', 'oceans-eleven'] }) -``` - -### Complexity - -**Option A: Trivial** β€” Update prompt text -**Option B: Small** β€” CastingEngine already supports `universe: 'custom'` (lines 210-221, 256-270) -**Option C: Small** β€” Pass universes to prompt builder - ---- - -## Finding 6: Config/Team Sync Gap - -### The Problem - -When you add or remove agents via REPL or `squad migrate`, the system updates: -- `.squad/team.md` (Members table) -- `.squad/routing.md` (Work Type table) -- `.squad/casting/registry.json` (Agent metadata) - -But **never updates `squad.config.ts`**. - -### Evidence - -**File:** `packages/squad-cli/src/cli/core/cast.ts` -**Lines:** 367-526 - -`createTeam()` generates: -- βœ… `team.md` (line 414-456) -- βœ… `routing.md` (line 459-486) -- βœ… `registry.json` (line 502-504) -- βœ… `history.json` (line 518-519) -- βœ… `policy.json` (line 522-523) -- ❌ `squad.config.ts` β€” **No code path** - -**File:** `packages/squad-cli/src/cli/commands/migrate.ts` -**Lines:** 438-483 - -`migrate --to sdk` generates `squad.config.ts` from existing team.md, but this is a **one-time migration**, not an ongoing sync. - -### What Should Happen - -1. **Add `updateSquadConfig()` function** in `cli/core/cast.ts` - - Read current `squad.config.ts` - - Parse AST (or use regex) to find `agents: [...]` - - Replace with new agent list - - Write back to disk - -2. **Call it from `createTeam()`** after writing other files - -3. **Add to `build` command** β€” `squad build` already reads `squad.config.ts` and generates markdown; make it bidirectional - -### Complexity - -**Large** β€” Requires: -- AST parsing or regex-based editing of TypeScript -- Preserving formatting/comments -- Handling edge cases (custom agents, non-standard syntax) -- Testing across all config formats - -**Alternative: Config-as-source-of-truth** -- **Don't sync** β€” Make `squad.config.ts` the canonical source -- `squad build` regenerates markdown from config -- Markdown becomes read-only output -- Already partially implemented in `build.ts` - ---- - -## Finding 7: Ralph and @copilot Gaps - -### Ralph - -**In REPL Init (cast.ts):** -```typescript -const hasRalph = proposal.members.some(m => /ralph/i.test(m.name)); -if (!hasRalph) allMembers.push(ralphMember()); -``` -βœ… Ralph is added to team.md, charter.md, history.md, registry.json - -**In SDK Init (init.ts:109-115):** -```typescript -agents: [ - { name: 'scribe', role: 'scribe', displayName: 'Scribe' } -] -``` -❌ Ralph is missing from squad.config.ts - -**Fix:** Add Ralph to the hardcoded agents array. - -**Complexity:** Trivial (one line change) - -### @copilot - -**Current behavior:** -- @copilot is a **UI-only pseudo-agent** inserted via `team-md.ts:insertCopilotSection()` -- It's a Markdown table row with capabilities guidance -- **Not** a real agent with charter.md or history.md -- **Not** in squad.config.ts - -**Design question:** -1. Keep @copilot as pseudo-agent? (Current behavior) -2. Make @copilot a real agent with charter.md? -3. Add @copilot to squad.config.ts as a special agent type? - -**If option 2/3:** Modify `createTeam()` and `generateSDKBuilderConfig()` to include @copilot. - -**Complexity:** -- **Option 1 (no change):** Trivial -- **Option 2/3 (real agent):** Small - ---- - -## Recommendations by Priority - -### P0: Critical for MVP - -1. **Add Ralph to SDK init agents array** (trivial) - - File: `packages/squad-cli/src/cli/core/init.ts:109-115` - - Change: Add `{ name: 'ralph', role: 'work-monitor', displayName: 'Ralph' }` - -2. **Guide coordinator to existing CastingEngine universes** (trivial) - - File: `packages/squad-cli/src/cli/shell/coordinator.ts:52` - - Change: Replace "Pick a fictional universe" with "Pick ONE: The Usual Suspects, Ocean's Eleven" - -3. **Decide config sync strategy** (design decision β†’ medium implementation) - - Option A: Config-as-source-of-truth (squad.config.ts canonical, markdown is output) - - Option B: Bidirectional sync (update config when markdown changes) - - Recommend **Option A** β€” simpler, already 50% implemented in `build.ts` - -### P1: High Value - -4. **Integrate CastingEngine into CLI casting** (medium) - - Replace `personalityForRole()` with `CastingEngine.castTeam()` - - Use universe-themed characters instead of generic roles - - Emit personality/backstory in `defineAgent()` calls - -5. **REPL init writes squad.config.ts** (small) - - After `createTeam()` in `finalizeCast()`, call `generateSDKBuilderConfig()` - - Write to `squad.config.ts` if `configFormat === 'sdk'` - -### P2: Nice to Have - -6. **Extend CastingEngine for freeform universes** (small) - - Map coordinator-invented universe names to custom character pools - - Or pre-seed more universe templates (Apollo 13, Star Wars, etc.) - -7. **Make @copilot a real agent** (design decision β†’ small implementation) - - Add charter.md, history.md for @copilot - - Include in squad.config.ts agents array - - Or keep as pseudo-agent (document this explicitly) - ---- - -## Files to Modify (by Finding) - -### Finding 1: squad.config.ts Generation -- `packages/squad-cli/src/cli/core/init.ts` (lines 109-125) β€” Add Ralph to agents array -- `packages/squad-sdk/src/config/init.ts` (lines 339-376) β€” Extend `generateSDKBuilderConfig()` to accept personality/backstory - -### Finding 2: CastingEngine Integration -- `packages/squad-cli/src/cli/core/cast.ts` (lines 218-300) β€” Replace `personalityForRole()` with CastingEngine -- `packages/squad-cli/src/cli/shell/index.ts` (lines 892-935) β€” Call `CastingEngine.castTeam()` before `createTeam()` - -### Finding 3: CLI Casting Flow -- `packages/squad-cli/src/cli/core/cast.ts` (lines 367-526) β€” Add `updateSquadConfig()` call to `createTeam()` - -### Finding 4: Init Flow Entry -- `packages/squad-cli/src/cli/shell/index.ts` (lines 959-962) β€” Add config write to `finalizeCast()` - -### Finding 5: Coordinator Init Prompt -- `packages/squad-cli/src/cli/shell/coordinator.ts` (lines 52) β€” Update prompt to specify exact universes - -### Finding 6: Config/Team Sync -- **New file:** `packages/squad-cli/src/cli/core/config-sync.ts` β€” Config AST editing utilities -- `packages/squad-cli/src/cli/commands/build.ts` β€” Make config-as-source-of-truth canonical - -### Finding 7: Ralph and @copilot -- `packages/squad-cli/src/cli/core/init.ts` (line 114) β€” Add Ralph agent -- `packages/squad-cli/src/cli/core/team-md.ts` (lines 28-88) β€” Document @copilot as pseudo-agent OR convert to real agent - ---- - -## Next Steps - -1. **PRD Decision Points:** - - Config sync strategy (A: config-as-source, B: bidirectional) - - @copilot agent type (pseudo-agent vs. real agent) - - Universe selection (guide to existing vs. freeform + custom mapping) - -2. **Implementation Phases:** - - Phase 1: P0 fixes (Ralph, universe guidance, sync decision) - - Phase 2: CastingEngine integration - - Phase 3: Full bidirectional sync (if chosen) - -3. **Documentation:** - - Update README with `squad init --sdk` behavior - - Document config-as-source-of-truth pattern - - Add universe selection guide for users - ---- - -**End of Technical Analysis** diff --git a/.squad/identity/sdk-init-umbrella-issue.md b/.squad/identity/sdk-init-umbrella-issue.md deleted file mode 100644 index 905cd4bc0..000000000 --- a/.squad/identity/sdk-init-umbrella-issue.md +++ /dev/null @@ -1,44 +0,0 @@ -## SDK Init Shore-Up β€” Umbrella Issue - -**Consolidates:** #337, #338, #339, #340, #341, #342 - -### Problem - -`squad init --sdk` produces incomplete squad state. Three critical gaps: - -1. **Config ↔ team.md sync broken** (#337) β€” Adding/removing members updates team.md but never touches squad.config.ts -2. **Built-in members missing** (#338, #339) β€” Ralph and @copilot work in CLI squads but are invisible to SDK consumers -3. **CastingEngine bypassed** (#342) β€” CLI init uses raw LLM prompts, ignoring curated universe templates - -### Solution: 3-Phase Plan - -**Phase 1 β€” Fix the Gaps** (P1, Small) -- [ ] #337 β€” Config ↔ team.md sync: update squad.config.ts when members change -- [ ] #338 β€” Include Ralph in generated squad.config.ts -- [ ] #339 β€” Add @copilot to team.md roster and squad.config.ts - -**Phase 2 β€” Wire CastingEngine** (P1, Medium) -- [ ] #342 β€” Integrate CastingEngine into CLI init flow (augment LLM proposals with curated templates) - -**Phase 3 β€” Exercise Test Matrix** (P2, Large) -- [ ] #340 β€” 29 features need active exercise testing -- [ ] #341 β€” Full parity test results (32/50 verified, gaps identified) - -### PRD & Analysis - -- Full PRD: `.squad/identity/prd-sdk-init-shoreup.md` -- Technical Analysis: `.squad/identity/sdk-init-technical-analysis.md` -- Implementation Roadmap: `.squad/identity/sdk-init-implementation-roadmap.md` - -### Open Design Questions - -1. AST vs regex for squad.config.ts mutations -2. CastingEngine: augment LLM proposals (recommended) or replace entirely? -3. Ralph charter: create one, or document as "built-in, no charter"? - -### Success Criteria - -- `squad init --sdk` generates config with all team members including Ralph and @copilot -- Adding/removing members updates squad.config.ts automatically -- CastingEngine templates used during init (not bypassed) -- Test matrix at 90%+ verified features diff --git a/.squad/log/2026-03-25T18-11-work-session.md b/.squad/log/2026-03-25T18-11-work-session.md deleted file mode 100644 index c5d7ba80f..000000000 --- a/.squad/log/2026-03-25T18-11-work-session.md +++ /dev/null @@ -1,176 +0,0 @@ -# Work Session: 2026-03-25T18:11 β€” Triage & Research Wave - -**Date:** 2026-03-25T18:11Z -**Participants:** PAO, EECOM, Procedures, Flight, CAPCOM, GNC -**Session Type:** Parallel investigation + fixes (Round 1) + Code review (Round 2) - ---- - -## Executive Summary - -**Six-person coordinated session targeting post-0.9.1 routing regression.** Two fixes committed (EECOM's personal squad path, Procedures' model catalog). Two comprehensive research reports completed (CAPCOM on CLI platform, GNC on Squad codebase). Community issue #612 filed for feedback. - -**Critical finding:** Regression caused by **combination of factors** β€” both Squad code changes (v0.9.0 prompt saturation, missing name parameter) AND Copilot CLI platform changes (CLI 1.0.5–1.0.11 instruction discovery, subagent idle hiding). Squad is not at fault alone. - ---- - -## Round 1: Parallel Work (Async Spawns) - -### PAO (DevRel) β€” Issue #610 -- **Task:** Fix broken docs link -- **Outcome:** βœ… Already resolved β€” file exists, tests pass -- **Time to resolve:** < 5 min - -### EECOM (Core Dev) β€” Issue #590 -- **Task:** Fix getPersonalSquadRoot() bug -- **Outcome:** βœ… MERGED `squad/590-fix-personal-squad-root` -- **Commits:** 1 (path fix + 2 tests) -- **Impact:** Fixes personal squad discovery entirely - -### Procedures (Prompt Engineer) β€” Issue #588 -- **Task:** Update model catalog (stale models) -- **Outcome:** βœ… MERGED `squad/588-update-model-catalog` -- **Changes:** Removed 2 models, added 5, restructured fallbacks -- **Templates touched:** 5 (all squad.agent.md copies synchronized) - -### Flight (Lead) -- **Task:** File GitHub discussion on routing regression -- **Outcome:** βœ… Issue #612 filed for community feedback -- **Context:** Three reported symptoms (coordinator overwork, broken routing, vanishing names) - -### CAPCOM (SDK Expert) β€” Research -- **Task:** Investigate Copilot CLI recent changes -- **Outcome:** βœ… COMPREHENSIVE REPORT (decision inbox) -- **Timeline discovered:** CLI 1.0.4 (stable) β†’ 1.0.11 (current), 8 releases in 10 days -- **High-impact findings:** - - CLI 1.0.11 monorepo instruction discovery (finds `*.agent.md` at every directory level) - - CLI 1.0.8 idle subagent hiding (agents invisible after 2 min) - - CLI 1.0.5–1.0.7 experimental features affecting routing -- **Key insight:** SDK version pinning (^0.1.32) doesn't prevent CLI runtime auto-updates - -### GNC (Node.js Runtime) β€” Research -- **Task:** Investigate Squad 0.9.0/0.9.1 changes -- **Outcome:** βœ… COMPREHENSIVE REPORT (decision inbox) -- **Root causes identified by symptom:** - 1. **Coordinator doing domain work** β†’ prompt saturation (711β†’946 lines, +33%), inlined workflows dilute routing constraint - 2. **Routing feels broken** β†’ workstreamβ†’personal squad replacement broke existing configs, skills path changed - 3. **Agent names vanishing** β†’ missing `name` parameter in spawn templates (fix exists on dev #577, not shipped) -- **Template status:** Script works, all copies in sync -- **Unreleased fix available:** #577 (commit 561b1a3) has mandatory `name` param + multi-pattern parser - ---- - -## Round 2: Code Review & Quality Gate - -### Flight (Lead) -- βœ… Reviewed PR #592 (approved, needs rebase) -- βœ… Reviewed Procedures' model catalog work (approved) - -### FIDO (Quality Owner) -- πŸ”΄ Reviewed EECOM's #590 fix -- **Finding:** Same bug exists in `shell/index.ts` (not just `consult.ts`) -- **Action:** Enforced lockout β€” EECOM must revise to include full sweep - -### CONTROL (TypeScript Engineer) -- βœ… Picked up #590 revision (FIDO's request) -- **Work:** Fixed shell/index.ts + 3 new test cases + full sweep of codebase -- **Status:** Committed, awaiting FIDO re-review - -### FIDO (Quality Owner) -- ⏳ Re-reviewing CONTROL's revision (pending) - ---- - -## Research Synthesis - -### Problem Statement -Users report three symptoms since Squad v0.9.1 (March 20-25): -1. **Coordinator doing more work than before** β€” not delegating to agents as expected -2. **Routing feels broken** β€” agents not spawning, work not being routed correctly -3. **Agent names vanishing during execution** β€” agents appear as generic slugs instead of cast names - -### Root Cause: Multi-Factor Regression - -**Factor 1: Copilot CLI Platform Changes (EXTERNAL β€” 60% confidence)** - -The CLI auto-updates independently from Squad's SDK version pinning. Three high-impact CLI changes: - -| CLI Version | Date | Change | Squad Impact | -|-------------|------|--------|--------------| -| 1.0.11 | Mar 23 | Monorepo discovery of `*.agent.md` at EVERY directory level | πŸ”΄ Finds 6+ Squad template copies β†’ merged conflicting instructions β†’ dilutes coordinator routing | -| 1.0.8 | Mar 18 | Idle subagents hidden from /tasks after 2 min | πŸ”΄ Explains "names vanish" β†’ agents still running but invisible | -| 1.0.7 | Mar 17 | `subagentStart` hook injects context into subagent prompts | 🟑 May add competing instructions to coordinator | -| 1.0.6 | Mar 16 | Agent IDs changed format (`agent-0` β†’ `{name}-0`) | 🟑 Breaks ID-based routing logic if any | -| 1.0.5 | Mar 13 | Embedding-based dynamic skill instruction injection per turn | 🟑 Adds competing context during execution | - -**Implication:** Squad is not solely responsible. The CLI platform underneath Squad changed in ways that affect how Squad's instructions are discovered, assembled, and executed. - -**Factor 2: Squad Code Changes (INTERNAL β€” 100% identified)** - -**v0.8.22 β†’ v0.9.0 (80 commits, March 22)** introduced regressions: - -| Commit | Change | Symptom Impact | -|--------|--------|----------------| -| 0f51a32 | Init Mode inlined from skill reference β†’ 50+ lines in coordinator prompt | Prompt grew +33% (711β†’946 lines) β†’ saturation / instruction fatigue | -| 72f2876 | Gap analysis verification loop added to coordinator | Adds inline coordinator logic, blurs "route vs. do work" boundary | -| 93869be | Personal squad ambient discovery replaces workstream routing | Existing workstream configs no longer work (routing feels broken) | -| 561b1a3 (post-v0.9.1, on dev) | **MISSING `name` parameter in templates** | Agents spawn without human-readable names β†’ fragile extraction fails | - -**Implication:** Squad made legitimate feature additions but didn't account for cumulative prompt fatigue or test against old routing patterns. - -### Verdict - -**Regression is a **combination** of:** -1. Copilot CLI platform evolution (monorepo discovery, idle hiding, new hooks) β€” Squad didn't anticipate -2. Squad code feature bloat without prompt optimization β€” inlined too much coordinator logic - -**Neither party is "wrong."** The fix requires **both**: -- Squad side: Optimize coordinator prompt, move features to skills, ship #577 (agent names) -- Platform side: Exclude template directories from discovery, make idle timeout configurable, document instruction assembly - ---- - -## Decisions Merged - -### 1. Personal Squad Path Canonicalization (EECOM) -**Decision:** Use `personal-squad/` subdirectory (canonical). `.squad` reserved for project-local only. -**Impact:** getPersonalSquadRoot(), resolvePersonalSquadDir(), ensurePersonalSquadDir() must all use `personal-squad`. -**Status:** βœ… Implemented in #590 - -### 2. Model Catalog Refresh (Procedures) -**Decision:** Bump default code model to `claude-sonnet-4.6`, specialist to `gpt-5.3-codex`, prune dead models, restructure fallback chains. -**Impact:** All agents using model selection reference current platform offerings. -**Status:** βœ… Merged in #588 - ---- - -## Recommendations - -### Immediate (This Week) -1. **Ship #577** (agent name fix) β€” directly addresses symptom 3 -2. **Clean up template file naming** β€” prevent CLI 1.0.11 duplicate discovery -3. **Test with CLI 1.0.4 pinned** β€” validate CLI vs. Squad as regression source - -### Short-term (Next 1-2 weeks) -4. **Move worktree lifecycle, personal squad governance to skills** β€” reduce coordinator prompt from 946 lines -5. **Add "ROUTING REMINDER" near prompt top** β€” reinforce "route, don't do domain work" constraint -6. **Create routing regression tests** β€” validate coordinator still routes on historical prompts -7. **Upgrade to SDK 0.2.0** β€” use `customize` mode for resilient system prompt control - -### Medium-term (Next month) -8. **File CLI issue** β€” request instruction discovery exclusions + idle timeout configurability -9. **Implement prompt budget metric** β€” alert if coordinator prompt grows >5% per release -10. **Document workstreamβ†’personal squad migration** β€” guide users off deprecated routing pattern - ---- - -## Files Logged - -- Orchestration logs: `.squad/orchestration-log/2026-03-25T18-11-{PAO,EECOM,Procedures,Flight,CAPCOM,GNC}.md` -- Research reports (inbox): - - `.squad/decisions/inbox/capcom-cli-research.md` - - `.squad/decisions/inbox/gnc-internal-research.md` - ---- - -**Session logged by Scribe at 2026-03-25T18:11Z** diff --git a/.squad/log/2026-03-26T17-09-631-investigation.md b/.squad/log/2026-03-26T17-09-631-investigation.md deleted file mode 100644 index de79a1a92..000000000 --- a/.squad/log/2026-03-26T17-09-631-investigation.md +++ /dev/null @@ -1,37 +0,0 @@ -# Session Log: P0 Incident #631 Investigation -**Date:** 2026-03-26T17:09 -**Issue:** #631 β€” @copilot deleted 361 files on dev -**Team:** Flight, Booster, RETRO, FIDO - -## Summary - -Team fanned out to investigate P0 incident #631 β€” @copilot deleted 361 files on dev. All 4 agents confirmed the issue claims. Key findings: zero branch protection on dev/main, no CI gates, copilot-instructions.md doesn't enforce PR workflow. Dev is still broken. - -## What Happened - -During a single session, @copilot performed a `git add .` operation that inadvertently staged and committed 361 file deletions along with 6 modifications. The intended change was 1 line in `test/docs-links.test.ts`, but without proper working tree verification or branch protection, the operation cascaded into a destructive commit on the dev branch. - -## Agents & Scope - -| Agent | Scope | Status | -|-------|-------|--------| -| Flight | Strategic analysis & root cause | βœ… Complete | -| Booster | CI/CD pipeline gaps | βœ… Complete | -| RETRO | Security & permissions | βœ… Complete | -| FIDO | Git forensics & file categories | βœ… Complete | - -## Key Findings - -1. **Zero Branch Protection:** Both dev and main branches have no branch protection rules (404 error) -2. **No CI Gates:** All 15 workflows are post-push observers; none gate merges -3. **Workflow Not Enforced:** copilot-instructions.md assumes PR workflow but doesn't enforce it -4. **@copilot Permissions:** Has unrestricted write access to all branches -5. **Scope of Deletion:** 361 files deleted across multiple directories, confirmed by FIDO - -## Outcomes - -- βœ… All claims in issue #631 verified -- βœ… Root cause identified (incomplete working tree + git add .) -- βœ… 13 prevention recommendations prioritized -- ⚠️ Dev branch still broken β€” revert needed -- βœ… Gap analysis complete β€” infrastructure improvements identified diff --git a/.squad/log/2026-03-27T21-42-00Z-decisions-archival.md b/.squad/log/2026-03-27T21-42-00Z-decisions-archival.md deleted file mode 100644 index 6add865db..000000000 --- a/.squad/log/2026-03-27T21-42-00Z-decisions-archival.md +++ /dev/null @@ -1,48 +0,0 @@ -# Archival Log: Decisions - -**Timestamp:** 2026-03-27T21:42:00Z -**Agent:** Scribe (Copilot) -**Trigger:** Automated archival gate - -## Task -Archive decisions.md entries older than 7 days to free up context. Decision entries from 2026-02-21 through 2026-03-25 moved to append-only archive. - -## Outcome -βœ… SUCCESS - -## Changes -- **decisions.md**: Trimmed from 385KB β†’ 11.9KB - - Foundational directives preserved (Type safety, Hook governance, Node.js runtime, etc.) - - Recent entries (2026-03-26+) preserved - - 71 dated entries (2026-02-21:2026-03-25) archived - -- **decisions-archive.md**: Created 365.1KB archive - - 71 entries preserved append-only - - Full history intact for reference - - No data loss - -## Verification -- βœ… Archive gate (decisions.md < 20KB): **PASS** -- βœ… All foundational directives present in decisions.md -- βœ… All archived entries present in decisions-archive.md -- βœ… Git commit successful: `b8b4c5ae` - -## Measurements -| Metric | Value | -|--------|-------| -| Entries archived | 71 | -| Archive date range | 2026-02-21 : 2026-03-25 | -| decisions.md pre | 385 KB | -| decisions.md post | 11.9 KB | -| decisions-archive.md | 365.1 KB | -| Reduction | 96.9% | -| Context savings | ~373 KB | - -## Summary -Successfully archived 71 dated decision entries spanning 33 days of team decisions. The decisions.md file is now below the 20KB archival gate threshold (11.9KB), reducing agent context load while preserving full history in append-only archive. All foundational directives remain in active decisions.md for team reference. - -## Impact -- **Agent context efficiency:** All agents now load ~373KB less decision context -- **No functionality loss:** Archived decisions remain accessible via decisions-archive.md -- **Append-only integrity:** Archive file can only grow; merge conflicts impossible -- **Future gate compliance:** Next archival not needed until decisions.md reaches 20KB again diff --git a/.squad/orchestration-log/2026-03-25T18-11-CAPCOM.md b/.squad/orchestration-log/2026-03-25T18-11-CAPCOM.md deleted file mode 100644 index 415c13d15..000000000 --- a/.squad/orchestration-log/2026-03-25T18-11-CAPCOM.md +++ /dev/null @@ -1,41 +0,0 @@ -# 2026-03-25T18:11 β€” CAPCOM (SDK Expert, sonnet) - -**Task:** Research Copilot CLI recent changes -**Mode:** background -**Status:** βœ… COMPLETE - -## Outcome - -Comprehensive research on Copilot CLI 1.0.4β†’1.0.11 changes. Identified three high-impact changes affecting Squad routing. Report in `.squad/decisions/inbox/capcom-cli-research.md`. - -## Findings Summary - -**Copilot CLI shipped 8 releases (March 11-23).** Three with direct Squad impact: - -1. **CLI 1.0.11 (Mar 23) β€” Monorepo instruction discovery** πŸ”΄ HIGH - - Discovers `*.agent.md` and `copilot-instructions.md` at EVERY directory level (cwd β†’ git root) - - Squad has 6+ copies in template directories β†’ duplicate/conflicting instructions merged - - Likely dilutes coordinator routing instructions - -2. **CLI 1.0.8 (Mar 18) β€” Idle subagent hiding** πŸ”΄ HIGH - - Agents invisible in /tasks after 2 min inactivity - - Explains "agent names vanish" symptom - -3. **CLI 1.0.7 (Mar 17) β€” subagentStart hook** 🟑 MEDIUM - - Can inject additional context into subagent prompts - - May create competing instructions - -**Contributing factors:** -- CLI 1.0.6: Agent ID format changed (agent-0 β†’ {name}-0) -- CLI 1.0.5: Embedding-based dynamic skill instruction injection per turn - -**Key insight:** SDK version pinning (^0.1.32) only controls the SDK adapter. The CLI runtime (system prompt assembly, agent lifecycle) auto-updates independently. Squad needs platform-resilient prompt injection. - -**Recommended actions:** -- Clean up template file naming to prevent duplicate discovery -- Upgrade to SDK 0.2.0 "customize" mode for resilient prompt control -- File CLI issue requesting instruction discovery exclusions and idle timeout config options - ---- - -*Logged by Scribe at 2026-03-25T18:11Z* diff --git a/.squad/orchestration-log/2026-03-25T18-11-EECOM.md b/.squad/orchestration-log/2026-03-25T18-11-EECOM.md deleted file mode 100644 index 7d3b16676..000000000 --- a/.squad/orchestration-log/2026-03-25T18-11-EECOM.md +++ /dev/null @@ -1,24 +0,0 @@ -# 2026-03-25T18:11 β€” EECOM (Core Dev, sonnet) - -**Task:** Fix #590 P0 getPersonalSquadRoot() bug -**Mode:** background -**Status:** βœ… MERGED - -## Outcome - -Fixed path mismatch in personal squad resolution. Committed on `squad/590-fix-personal-squad-root`. - -## Details - -**Root cause:** `getPersonalSquadRoot()` in `consult.ts` used `.squad` as subdirectory, while `resolvePersonalSquadDir()` and `ensurePersonalSquadDir()` in `resolution.ts` use `personal-squad`. Path mismatch broke all personal squad discovery. - -**Fix:** -- Updated `consult.ts` to use `personal-squad` subdirectory -- Added 2 new test cases covering both functions -- Confirmed template sync script propagated changes - -**Decision:** Personal squad paths must use `personal-squad/` subdirectory (canonical). `.squad` is reserved for project-local squad directories only. - ---- - -*Logged by Scribe at 2026-03-25T18:11Z* diff --git a/.squad/orchestration-log/2026-03-25T18-11-Flight.md b/.squad/orchestration-log/2026-03-25T18-11-Flight.md deleted file mode 100644 index d5a862e43..000000000 --- a/.squad/orchestration-log/2026-03-25T18-11-Flight.md +++ /dev/null @@ -1,24 +0,0 @@ -# 2026-03-25T18:11 β€” Flight (Lead, haiku) - -**Task:** File GitHub discussion on post-0.9.1 routing regression -**Mode:** background -**Status:** βœ… FILED - -## Outcome - -Filed issue #612 for community feedback on routing regression. - -## Details - -**Issue:** Post-0.9.1 routing regression (v0.9.0 and later) - -**Reported symptoms:** -1. Coordinator appears to be doing more work than before -2. Routing feels broken β€” delegation not happening as expected -3. Agent names vanish during execution - -**Next:** Research teams (CAPCOM, GNC) investigating to determine whether Squad code changes or Copilot CLI platform changes caused regression. - ---- - -*Logged by Scribe at 2026-03-25T18:11Z* diff --git a/.squad/orchestration-log/2026-03-25T18-11-GNC.md b/.squad/orchestration-log/2026-03-25T18-11-GNC.md deleted file mode 100644 index dd9745336..000000000 --- a/.squad/orchestration-log/2026-03-25T18-11-GNC.md +++ /dev/null @@ -1,61 +0,0 @@ -# 2026-03-25T18:11 β€” GNC (Runtime, sonnet) - -**Task:** Research our 0.9.1 changes -**Mode:** background -**Status:** βœ… COMPLETE - -## Outcome - -Root cause analysis of Squad 0.9.0/0.9.1 routing regression. Report in `.squad/decisions/inbox/gnc-internal-research.md`. - -## Findings Summary - -**Regression introduced in v0.9.0 (March 22).** v0.9.0 β†’ v0.9.1 was CI/publish fixes only β€” identical coordinator prompts. - -### Root Causes by Symptom - -**Symptom 1: Coordinator doing domain work** -- Primary: Prompt saturation/instruction fatigue -- Coordinator prompt grew 33% (711β†’946 lines, 8,867β†’11,837 words) -- New content (personal squad, worktree lifecycle, gap analysis) adds inline coordinator responsibilities -- Dilutes core routing constraint buried at line 1016 of 946-line prompt - -**Symptom 2: Routing feels broken** -- Primary: Workstream β†’ Personal Squad replacement broke existing routing configs -- Contributing: Skills path changed (.copilot/skills/ β†’ .squad/skills/) -- Contributing: Prompt weight competing with routing rules - -**Symptom 3: Agent names vanishing** -- Root cause: Missing `name` parameter in spawn templates -- v0.9.0 and v0.9.1 shipped WITHOUT the `name` parameter -- Shell relied on fragile regex extraction from `description` -- **Fix exists (commit 561b1a3, issue #577) but hasn't shipped** β€” adds mandatory `name` parameter + multi-pattern parser - -### Unreleased Fix Available - -Commit 561b1a3 on dev branch includes: -- Mandatory `name: "{name}"` parameter in ALL spawn templates -- Multi-pattern fallback name parser (agent-name-parser.ts) -- 30 tests for name extraction - -### Template Status - -`scripts/sync-templates.mjs` correctly propagates from `.squad-templates/` to all 4 targets. All copies are in sync β€” no template drift. - -### Recommended Follow-Up - -**P0 β€” Ship immediately:** Merge #577 (agent name fix) β€” directly addresses symptom 3. - -**P1 β€” Next release:** -1. Audit coordinator prompt weight (consider moving worktree lifecycle, personal squad governance, gap analysis to skills) -2. Reinforce routing constraint near top of template -3. Create routing regression tests - -**P2 β€” Track/validate:** -1. Create routing regression tests with historical prompts -2. Document workstreamβ†’personal squad migration for users -3. Implement "prompt budget" metric (alert if growth >5% per release) - ---- - -*Logged by Scribe at 2026-03-25T18:11Z* diff --git a/.squad/orchestration-log/2026-03-25T18-11-PAO.md b/.squad/orchestration-log/2026-03-25T18-11-PAO.md deleted file mode 100644 index 91b44abef..000000000 --- a/.squad/orchestration-log/2026-03-25T18-11-PAO.md +++ /dev/null @@ -1,19 +0,0 @@ -# 2026-03-25T18:11 β€” PAO (DevRel, haiku) - -**Task:** Fix #610 broken docs link -**Mode:** background -**Status:** βœ… DONE - -## Outcome - -Issue already resolved. The documentation file exists and tests pass. No code changes required. - -## Details - -- Verified the referenced file exists at the expected path -- Ran doc tests β€” all passing -- No changes needed - ---- - -*Logged by Scribe at 2026-03-25T18:11Z* diff --git a/.squad/orchestration-log/2026-03-25T18-11-Procedures.md b/.squad/orchestration-log/2026-03-25T18-11-Procedures.md deleted file mode 100644 index 3ca876304..000000000 --- a/.squad/orchestration-log/2026-03-25T18-11-Procedures.md +++ /dev/null @@ -1,31 +0,0 @@ -# 2026-03-25T18:11 β€” Procedures (Prompt Engineer, sonnet) - -**Task:** Update #588 model catalog -**Mode:** background -**Status:** βœ… MERGED - -## Outcome - -Updated all 5 copies of `squad.agent.md`. Removed stale models, added new models, restructured fallback chains. Committed on `squad/588-update-model-catalog`. - -## Details - -**Changes:** -- Removed 2 stale models: `claude-opus-4.6-fast`, `gpt-5` (standalone) -- Added 5 new models: `claude-sonnet-4.6`, `claude-opus-4.6-1m`, `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.4-mini` -- Default code model bumped to `claude-sonnet-4.6` -- Code specialist bumped to `gpt-5.3-codex` -- Fallback chains restructured with current model availability - -**Templates updated:** -1. `.squad-templates/squad.agent.md` -2. `templates/squad.agent.md` -3. `.squad/templates/squad.agent.md` -4. `packages/squad-sdk/templates/squad.agent.md` -5. `packages/squad-cli/templates/squad.agent.md` - -**Decision:** Model catalog is current as of March 25. Platform default for code model is `claude-sonnet-4.6`. All agents using model selection will reference current models. - ---- - -*Logged by Scribe at 2026-03-25T18:11Z* diff --git a/.squad/orchestration-log/2026-03-26T17-09-investigation-631.md b/.squad/orchestration-log/2026-03-26T17-09-investigation-631.md deleted file mode 100644 index e7df19ad4..000000000 --- a/.squad/orchestration-log/2026-03-26T17-09-investigation-631.md +++ /dev/null @@ -1,39 +0,0 @@ -# Orchestration Log: P0 Incident #631 Investigation -**Timestamp:** 2026-03-26T17:09 -**Issue:** #631 β€” @copilot deleted 361 files on dev branch -**Status:** Investigation Complete - -## Spawn Manifest - -### Flight (explore, background, claude-haiku-4.5) -**Mission:** Strategic incident analysis -**Output:** Analyzed commit 1ab2f5c, verified all claims in the issue, traced root cause to incomplete working tree + git add . + zero branch protection on dev. Prioritized 13 prevention recommendations. - -### Booster (explore, background, claude-haiku-4.5) -**Mission:** CI/CD gap analysis -**Output:** Found 15 workflows, NONE gate merges on dev, all are post-push observers. No deletion guards, no pre-commit hooks, no canary checks exist. - -### RETRO (explore, background, claude-haiku-4.5) -**Mission:** Security & permissions audit -**Output:** Confirmed both dev and main have ZERO branch protection (404). @copilot has unrestricted write access. copilot-instructions.md assumes PRs but doesn't enforce them. Identified 3 simultaneous failures that enabled the incident. - -### FIDO (explore, background, claude-haiku-4.5) -**Mission:** Git forensics -**Output:** Verified 361 files deleted, 6 modified. The intended fix was 1 line in test/docs-links.test.ts. Categorized all deletions by directory. Confirmed dev is still broken (no revert yet). Parent 28ea025 is intact. - -## Findings Summary - -- **Root Cause:** Incomplete working tree state combined with `git add .` without proper verification -- **Enablers:** - 1. Zero branch protection on dev/main - 2. No CI gates preventing merges - 3. copilot-instructions.md doesn't enforce PR workflow -- **Current State:** dev branch still broken (361 files deleted) -- **Prevention Recommendations:** 13 prioritized actions identified - -## Next Steps - -- Revert commits on dev -- Implement branch protection rules -- Add pre-commit hooks and CI gates -- Enforce mandatory PR workflow diff --git a/.squad/sessions/2026-03-01T20-12-48Z_fdc8d707-7d36-4b23-abd9-80b6558f7673.json b/.squad/sessions/2026-03-01T20-12-48Z_fdc8d707-7d36-4b23-abd9-80b6558f7673.json deleted file mode 100644 index 172243118..000000000 --- a/.squad/sessions/2026-03-01T20-12-48Z_fdc8d707-7d36-4b23-abd9-80b6558f7673.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "id": "fdc8d707-7d36-4b23-abd9-80b6558f7673", - "createdAt": "2026-03-01T19:55:50.729Z", - "lastActiveAt": "2026-03-01T20:12:57.373Z", - "messages": [ - { - "role": "system", - "content": "❌ Something went wrong processing your message.\n Try:\n β€’ Try again\n β€’ Run 'squad doctor' for diagnostics", - "timestamp": "2026-03-01T20:12:48.248Z" - } - ] -} \ No newline at end of file diff --git a/.squad/sessions/2026-03-04T16-20-51Z_e90fb146-17b4-4d72-a4c5-933ea5946b3f.json b/.squad/sessions/2026-03-04T16-20-51Z_e90fb146-17b4-4d72-a4c5-933ea5946b3f.json deleted file mode 100644 index a8c83d707..000000000 --- a/.squad/sessions/2026-03-04T16-20-51Z_e90fb146-17b4-4d72-a4c5-933ea5946b3f.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "id": "e90fb146-17b4-4d72-a4c5-933ea5946b3f", - "createdAt": "2026-03-04T16:20:47.900Z", - "lastActiveAt": "2026-03-04T16:20:51.533Z", - "messages": [] -} \ No newline at end of file