diff --git a/.squad/agents/eecom/history.md b/.squad/agents/eecom/history.md index 4f1879c04..9fb938d58 100644 --- a/.squad/agents/eecom/history.md +++ b/.squad/agents/eecom/history.md @@ -38,4 +38,329 @@ Replaced soft-warn with synchronous version check + `process.exit(1)` for Node < - **Adoption Tracking Tier 1:** Moved `.squad/adoption/` → `.github/adoption/`. Aggregate metrics only — never publish individual repo lists without opt-in. - **PR #483 (platform-adapter timeout):** `{ ...EXEC_OPTS, timeout: 3_000 }` pattern for external CLI calls that might hang. Existing catch block with fallback handles timeout errors. - **PR #480 (history race condition):** Three-layer defense: async mutex, atomic file operations (write-then-rename), 14 tests. -- **PR #486 (SIGINT handling):** Two layers: parent SIGINT handler + child process cleanup (kill children, close handles, flush buffers). 22 tests. \ No newline at end of file +- **PR #486 (SIGINT handling):** Two layers: parent SIGINT handler + child process cleanup (kill children, close handles, flush buffers). 22 tests. +## Learnings + +### Template Brady contamination fix (#977) (2026-05-01) + +**Context:** Template files (squad.agent.md, init-mode/SKILL.md) contained hardcoded "Brady" examples in greetings, routing examples, and comments. LLMs treated these as patterns, greeting every user as "Brady" regardless of their actual `git config user.name`. + +**Fix:** Replaced all hardcoded "Brady" in template examples with generic `{user}` / `{name}` placeholders. Canonical sources: `.squad-templates/squad.agent.md` and `.copilot/skills/init-mode/SKILL.md`. Template sync (`node scripts/sync-templates.mjs`) propagated squad.agent.md to `.github/agents/` but did NOT sync init-mode SKILL.md to package templates — those required manual edits in both `packages/squad-cli/templates/skills/init-mode/SKILL.md` and `packages/squad-sdk/templates/skills/init-mode/SKILL.md`. + +**Key distinction:** Only template files that get copied to user repos were changed. Brady references in project docs (history-hygiene, release-process, humanizer, architectural-proposals, reskill) are legitimate content about the project founder and were left unchanged. + +**Pattern:** When fixing template contamination, verify which files are covered by `sync-templates.mjs` and which require manual propagation. The init-mode SKILL.md lives in `.copilot/skills/` (not `.squad-templates/`), so sync doesn't touch its package copies. + +### 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 index bb854a570..9c88ff7c0 100644 --- a/.squad/agents/fido/history.md +++ b/.squad/agents/fido/history.md @@ -14,6 +14,14 @@ Quality gate authority for all PRs. Test assertion arrays (EXPECTED_GUIDES, EXPE ### 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. **Fixed PR #331:** EXPECTED_SCENARIOS expanded to 25 entries, EXPECTED_FEATURES array created with 32 entries (commit 6599db6). +📌 **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. @@ -45,4 +53,199 @@ Added `publish-policy` job to squad-ci.yml: scans `.github/workflows/*.yml` for ### PR Review Batch — Community PRs Community contributors consistently struggle with: (a) scoped npm package names in changesets (use `@bradygaster/squad-cli` not `squad-cli`), (b) monorepo file placement (skills in `packages/squad-cli/templates/skills/`). Both preventable with better contributor docs. Changeset package name mismatch is most common error (4/9 Tamir PRs). -📌 **Team update (2026-07-29T17:11:56+10:00 — Issue #1556 / PR #1557):** A new required CI check `squad-workflow-lint` now exists in `.github/workflows/squad-workflow-lint.yml`. It runs actionlint 1.7.12 + shellcheck 0.10.0 against all 5 workflow/template directories, including the canonical `.squad-templates/workflows/` sources. FIDO should treat this as a required gate alongside existing CI checks — PRs that introduce SC2086, unquoted variables, or invalid action syntax in workflow files will fail this check. All known SC2086 findings across Squad's own workflows were fixed in PR #1557. \ No newline at end of file +📌 **Team update (2026-07-29T17:11:56+10:00 — Issue #1556 / PR #1557):** A new required CI check `squad-workflow-lint` now exists in `.github/workflows/squad-workflow-lint.yml`. It runs actionlint 1.7.12 + shellcheck 0.10.0 against all 5 workflow/template directories, including the canonical `.squad-templates/workflows/` sources. FIDO should treat this as a required gate alongside existing CI checks — PRs that introduce SC2086, unquoted variables, or invalid action syntax in workflow files will fail this check. All known SC2086 findings across Squad's own workflows were fixed in PR #1557. +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 index 210aff725..03aa6de4d 100644 --- a/.squad/agents/flight/history.md +++ b/.squad/agents/flight/history.md @@ -11,6 +11,13 @@ 📌 **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. Root causes: dependency validation gap (file: refs in packages), GitHub workflow cache race, npm workspace publish automation broken, no pre-publish verification. Created comprehensive retrospective with 5 root causes and 6 action items (A1–A6). Filed 9 GitHub issues (#556–#564). Pre-flight job added to publish pipeline. Surgeon charter hardened. 10 community PRs merged. Release process skill created at `.squad/skills/release-process/SKILL.md`. 📌 **Team update (2026-03-22T09-35Z — Wave 1):** Ambient personal squad design validated and 19-task implementation plan authored across 4 PRs. EECOM executing Phase 1–2 (SDK + CLI), Procedures executing Phase 3 (governance) concurrently. All design gaps resolved; dependency graph established. +📌 **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 @@ -30,4 +37,173 @@ Three-branch model (main/dev/insiders). Apollo 13 team, 3931 tests. Boundary rev - **Ambient personal squad (#329/#344):** 5 gaps identified: resolvePersonalAgents() function, ghost protocol for orchestration log, --team-root scope, squad personal init command, SQUAD_NO_PERSONAL env var. ensureSquadPathTriple() required in resolution.ts to enforce ghost protocol. - **Release hardening plan:** PUBLISH-README.md rewrite (#564, absorbs #558-560), CI lint rule rejecting non-workspace npm publish (#557), ghost workflow deletion (#562). Lint rule: scan `.github/workflows/*.yml` for `npm publish` without `-w` flag. - **Issue triage (2026-03-24 — 14 issues):** P0: #590 (getPersonalSquadRoot broken). P1: #610 (broken docs), #591 (hiring wiring). P2: #597, #588, #554. Questions: #589, #494. Deferred: #581 (ADO PRD, blocked until #341). -- **Community PR quality tiers:** Diberry (MSFT-level, architecturally-sound, merge-ready). Joniba (consistently high-quality, matches team standards). Tamir (technically strong, needs proposal-first discipline + monorepo placement guidance). \ No newline at end of file +- **Community PR quality tiers:** Diberry (MSFT-level, architecturally-sound, merge-ready). Joniba (consistently high-quality, matches team standards). Tamir (technically strong, needs proposal-first discipline + monorepo placement guidance). +## 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/pao/history.md b/.squad/agents/pao/history.md index 48a3c800a..8c8c85ed7 100644 --- a/.squad/agents/pao/history.md +++ b/.squad/agents/pao/history.md @@ -33,4 +33,283 @@ Full PRD at `docs/research/jsdoc-api-reference-prd.md`. Key decisions: TypeDoc + - **JSDoc API Reference Research:** TypeDoc + typedoc-plugin-markdown. Squad SDK 60-80% JSDoc coverage. Research at `docs/research/jsdoc-api-reference-research.md`. Configuration templates, 4-phase roadmap, tool comparison matrix. - **v0.9.0 blog post format:** YAML frontmatter (title/date/author/wave/tags/status/hero) → experimental warning → "What Shipped" (H2 sections + callout boxes) → "Quick Stats" → "Breaking Changes" → "Upgrading" → "What's Next". 200-400 words for infrastructure releases. EXPECTED_BLOG uses filesystem scan — no test changes needed. - **PR #11 TypeDoc review (2026-03-24):** Generated docs require crosslinks from curated guides. When adding new docs section, ensure old curated page has a visible pointer to the new section. Blocking issues: missing sdk.md crosslink banner, navigation URL inconsistency (`reference/api/index` → `reference/api`). -- **Contributor recognition:** CONTRIBUTORS.md tracks team roster + community contributors. Each release includes recognition updates. Append PR counts, don't replace. \ No newline at end of file +- **Contributor recognition:** CONTRIBUTORS.md tracks team roster + community contributors. Each release includes recognition updates. Append PR counts, don't replace. +## 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 index 0e361bc94..4f28c82ee 100644 --- a/.squad/agents/procedures/history.md +++ b/.squad/agents/procedures/history.md @@ -30,4 +30,202 @@ Pattern: Agent specification gap identified. Procedures owns formal spec structu - **VS Code routing investigation (2026-03-25):** CLI-centric enforcement language causes coordinator to work inline in VS Code. Fix: platform-neutral dispatch language + reinforcement at prompt bottom. - **VS Code routing fix (2026-07):** Fix 1 + Fix 2 shipped. CRITICAL RULE rewritten to dispatcher-identity framing ("DISPATCHER, not a DOER") with dispatch mechanism table. Routing Enforcement Reminder added as final section. Remaining P1 fixes (template renaming, prompt slimming) deferred. - **PR #619 rebase (2026-07):** When a PR has accumulated dev merge commits, use `git rebase --onto dev ` to cherry-pick only relevant commits. -- **Trim copilot-instructions.md (#999, 2026-04-17):** 1300w/9KB → 397w/3KB. Extracted Protected Files to skill, consolidated Git Safety, removed duplication. Pattern: main instructions = routing/workflow; skills = domain-specific reference (lazy-loaded on demand). \ No newline at end of file +- **Trim copilot-instructions.md (#999, 2026-04-17):** 1300w/9KB → 397w/3KB. Extracted Protected Files to skill, consolidated Git Safety, removed duplication. Pattern: main instructions = routing/workflow; skills = domain-specific reference (lazy-loaded on demand). +# 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/decisions.md b/.squad/decisions.md index 4e6420377..9ed383264 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -362,3 +362,8 @@ Triaged 14 untriaged issues (3 docs, 6 community features, 3 bugs, 2 questions). **By:** Booster (CI/CD) **What:** Templates under `packages/squad-cli/templates/workflows/` and `packages/squad-sdk/templates/workflows/` are now linted by actionlint via explicit file path arguments in the new `squad-workflow-lint.yml` CI job. SC2086 findings fixed across all `>> $GITHUB_OUTPUT` / `>> $GITHUB_STEP_SUMMARY` redirects in `.squad-templates/workflows/`, `templates/workflows/`, `.github/workflows/squad-heartbeat.yml`, `squad-repo-health.yml`, and `squad-ci.yml`. Actionlint pinned to tag `v1.7.12`; shellcheck 0.10.0 installed explicitly. **Why:** Downstream repos running actionlint in their CI saw SC2086 errors in files generated by `squad upgrade` because Squad's own CI did not lint templates. The fix must live in Squad's templates — `squad upgrade` overwrites any downstream patches on every run. PR #1557. +## Deferred + +- #357, #336, #335, #334, #333, #332, #316 (A2A) — stays shelved per existing decision +- #581 (ADO PRD) — P2, blocked until #341 (SDK-first parity) ships + diff --git a/.squad/decisions/inbox/booster-ci-deletion-guard.md b/.squad/decisions/inbox/booster-ci-deletion-guard.md new file mode 100644 index 000000000..581b1f419 --- /dev/null +++ b/.squad/decisions/inbox/booster-ci-deletion-guard.md @@ -0,0 +1,4 @@ +### 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 new file mode 100644 index 000000000..b6858ce11 --- /dev/null +++ b/.squad/decisions/inbox/booster-release-skill-v094.md @@ -0,0 +1,35 @@ +# 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/data-restore-dev-main-ancestry.md b/.squad/decisions/inbox/data-restore-dev-main-ancestry.md new file mode 100644 index 000000000..513d7120a --- /dev/null +++ b/.squad/decisions/inbox/data-restore-dev-main-ancestry.md @@ -0,0 +1,100 @@ +--- +author: Data +date: 2026-08-13 +status: decided +references: + - "PR #1699" + - "PR #1698 (v0.12.0 dev -> main promotion, unblocked by this)" + - "PR #1415 (tools: ['*'] fix, verified already on dev)" +--- + +# Decision: restore shared ancestry between dev and main via merge, dev-wins conflict policy + +## Context + +`dev` and `main` had unrelated git histories. `dev`'s root commit (`4c5772c5`, a +dependabot bump dated 2026-07-13) shares no ancestor with `main`'s root +(`f4830e48`, 1722 commits). `dev` itself has 196 commits. `git merge-base +upstream/dev upstream/main` returned nothing and `git merge-tree` refused +outright. This made the v0.12.0 promotion PR (#1698, `dev` -> `main`) flatly +unmergeable, with no way to review a normal diff. The v0.11.0 promotion +(2026-06-29) predates the July 13 reset, which is why it worked and why +#1698 was the first to hit this wall. + +## Decision + +Merge `upstream/main` into `dev` with `--allow-unrelated-histories`, resolving +every one of the 275 conflicts in `dev`'s favor, on a new branch +`squad/restore-main-ancestry`, landed via PR #1699 into `dev`. + +Rejected alternative: rebasing `dev` onto `main`. `dev` carries a +`non_fast_forward` ruleset that blocks the force-push a rebase requires, and a +rebase would rewrite all 196 commits on `dev`, invalidating every PR currently +open against it. A merge is additive only and needs no force-push. + +## Why dev-wins conflict resolution is safe + +All 275 conflicts were `add/add` (identical path on both branches, no common +base to 3-way merge from). Resolved every one with `git checkout --ours` (dev's +content). This is safe because the only `main`-only code fix that mattered, +#1415 (`tools: ['*']` in `.github/agents/squad.agent.md`), was verified already +present on `dev` before starting the merge, so dev-wins loses zero code. +Verified the resolution was a true no-op against dev's pre-merge tree: diffing +all 275 resolved files plus the 48 removed changesets plus the 6 auto-merged +files against dev's HEAD showed only 18 real changes total, exactly the +files deliberately kept (see below). Confirmed unchanged post-merge: +`package.json` / `packages/squad-cli/package.json` / `packages/squad-sdk/package.json` +(all `0.12.0`), `CHANGELOG.md` (`## [0.12.0] - 2026-08-12` intact), +`test/gh-aw-quality.test.ts` (#1697 fix intact), `workflows/squad.md` and +`workflows/squad-implement-worker.md` (#1682 feature intact). + +## What was restored (kept from main, lost in the July 13 reset) + +7 docs pages: +- docs/src/content/blog/015-wave-2-the-repl-moment.md +- docs/src/content/blog/032-v010-stabilisation-insider.md +- docs/src/content/blog/033-swe-bench-lite-results.md +- docs/src/content/docs/features/remote-control.md +- docs/src/content/docs/get-started/choosing-your-path.md +- docs/src/content/docs/guide/personal-squad.md +- docs/src/content/docs/guide/shell.md + +5 decision records: +- .squad/decisions/inbox/booster-ci-deletion-guard.md +- .squad/decisions/inbox/booster-release-skill-v094.md +- .squad/decisions/inbox/flight-versioning-policy.md +- .squad/decisions/inbox/procedures-fix-coordinator-inline-dispatch-gate.md +- .squad/decisions/inbox/retro-copilot-git-safety.md + +Plus 6 files that auto-merged cleanly via a genuine 3-way merge (not a +conflict), appending older history from main onto dev's existing content with +no loss on either side: `.squad/agents/{eecom,fido,flight,pao,procedures}/history.md` +and `.squad/decisions.md`. + +## What was dropped + +48 `.changeset/*.md` files that arrived from `main`. These are spent: their +content is already consumed into `CHANGELOG.md`'s `[0.12.0]` entry, and +re-adding them risked tripping the Changeset Drift check. `.changeset/` after +this merge contains exactly what `dev` had before: `README.md`, +`config.json`, `max-reasoning-effort.md`. + +## Validation + +Static/diff verification was thorough (see above). Dynamic validation +(`npm run build`, `npx vitest run`) could **not** be executed in this sandbox: +the corporate npm proxy does not mirror `eslint-plugin-n@18.3.0` (its cache +tops out at 18.2.2) and there is no direct route to the public npm registry +from this environment. Confirmed unrelated to the merge: +`package-lock.json`'s staged content is byte-identical to dev's pre-merge +HEAD, and this exact dependency/version was already in dev's lockfile before +any of this work. CI (which has full registry access) is the source of truth +for build/test validation on PR #1699. + +## Outcome + +`git merge-base upstream/main` now succeeds, confirming `dev` +has a real common ancestor with `main` again. This unblocks PR #1698 and +prevents the same failure on future promotions, provided the new release-process +skill gate (verify `git merge-base dev main` before starting release-prep) is +followed going forward. diff --git a/.squad/decisions/inbox/flight-versioning-policy.md b/.squad/decisions/inbox/flight-versioning-policy.md new file mode 100644 index 000000000..9911fc318 --- /dev/null +++ b/.squad/decisions/inbox/flight-versioning-policy.md @@ -0,0 +1,32 @@ +# 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/procedures-fix-coordinator-inline-dispatch-gate.md b/.squad/decisions/inbox/procedures-fix-coordinator-inline-dispatch-gate.md new file mode 100644 index 000000000..e65fee749 --- /dev/null +++ b/.squad/decisions/inbox/procedures-fix-coordinator-inline-dispatch-gate.md @@ -0,0 +1,45 @@ +# Decision: Restore always-on coordinator inline-dispatch gate (v0.10.0 regression) + +- **Author:** Procedures (Prompt Engineer) +- **Date:** 2026-06-24 +- **Requested by:** Tamir Dresher +- **Branch:** squad/fix-coordinator-inline-dispatch-gate (worktree) +- **Status:** Proposed — applied in working tree, awaiting Lead (Flight) review; NOT committed. + +## Context + +Matthew Wan reported the main Squad coordinator "does a lot of work on its own instead of using his roster of agents." Worked in v0.9.4, broke in v0.10.0. Dina Berry worked around it by hand-editing the coordinator charter. + +## Root cause + +Commit `afe78188` (#1035, "context overflow sentinel + coordinator size reduction") cut the coordinator template and moved the concrete inline-dispatch gate and dispatch mechanics out of the always-on prompt into lazy-loaded reference files (`client-compatibility-reference.md`, `spawn-reference.md`). The leftover inline guidance ("inline work is last-resort fallback only") was too soft to hold the line, so the coordinator began executing domain work itself. + +## Decision + +Re-establish a strong, **always-on** dispatch gate without breaking the legitimate Direct/Lightweight response modes or the size-reduction spirit. Three minimal edits (~14 lines) to the canonical template `.squad-templates/squad.agent.md`, propagated to all 5 synced copies via `npm run sync-templates`: + +1. **Inline-dispatch gate** (Client Compatibility): inline permitted ONLY in Direct Mode, or when NEITHER `task` NOR `runSubagent` exists; otherwise MUST dispatch. +2. **STOP gate** (How to Spawn an Agent): about to emit a domain artifact with no spawn call this turn → STOP and dispatch (exceptions: Direct Mode / no spawn tool). +3. **VS Code `runSubagent` micro-playbook** re-inlined (~5 lines) so how-to-dispatch is always-on. + +## The 5 synced copies (canonical first) + +1. `.squad-templates/squad.agent.md` (canonical — edited here) +2. `templates/squad.agent.md.template` +3. `.github/agents/squad.agent.md` +4. `packages/squad-cli/templates/squad.agent.md.template` +5. `packages/squad-sdk/templates/squad.agent.md.template` + +## Validation + +- New regression/parity test `test/coordinator-inline-dispatch-gate.test.ts` (deterministic, subprocess-free): RED before (8/8 fail), GREEN after (8/8 pass). +- Full `npm run test`: 18 failed files vs 31 baseline (fewer); all failures are pre-existing flaky subprocess/timeout e2e tests (3 of 4 "new vs baseline" pass in isolation; the 4th is `squad doctor` at 40x10 exiting null = timeout, unrelated to template content). No new deterministic failures. +- `npm run lint` (tsc noEmit both packages): clean. + +## Changeset + +Required. The `changelog-gate` regex governs `.squad-templates/`, `templates/`, and `packages/squad-(sdk|cli)/templates/` — not just `src/`. Added `.changeset/fix-coordinator-inline-dispatch-gate.md` (patch, squad-cli + squad-sdk). + +## Rollout + +Existing installs require `squad upgrade` to pick up the regenerated coordinator agent. diff --git a/.squad/decisions/inbox/retro-copilot-git-safety.md b/.squad/decisions/inbox/retro-copilot-git-safety.md new file mode 100644 index 000000000..bb1ed5256 --- /dev/null +++ b/.squad/decisions/inbox/retro-copilot-git-safety.md @@ -0,0 +1,4 @@ +### 2026-03-26: Copilot git safety rules +**By:** RETRO (Security) +**What:** Added mandatory Git Safety section to copilot-instructions.md: prohibits staging the entire working tree with a bare-dot `git add` (i.e. `git add` followed by just `.`), 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/skills/release-process/SKILL.md b/.squad/skills/release-process/SKILL.md index 18e0e84b1..349f7c6c3 100644 --- a/.squad/skills/release-process/SKILL.md +++ b/.squad/skills/release-process/SKILL.md @@ -34,6 +34,18 @@ Squad publishes two npm packages: `@bradygaster/squad-sdk` and `@bradygaster/squ ## Rules (Non-Negotiable) +### 0. Verify `dev` and `main` Share Ancestry BEFORE Starting Any Release-Prep Work + +> Source: 2026-08-13 orphaned-history incident, PR #1699. `dev`'s history was silently reset on 2026-07-13 (a dependabot bump became a brand-new root commit with zero shared history with `main`). Nothing in normal release-prep work (version bump, CHANGELOG entry, changeset consolidation, CI) surfaces this — `dev` builds and tests green the whole time because none of it touches `main`'s history. The break is invisible until the very last step: opening the `dev` → `main` promotion PR, which GitHub then reports as flatly unmergeable, with `git merge-tree` refusing outright and no reviewable diff. + +**Before touching version numbers or the CHANGELOG, run:** + +```bash +git merge-base upstream/dev upstream/main +``` + +If this returns a commit SHA (exit 0), proceed normally. **If it returns nothing (exit 1), STOP.** The promotion PR will be unmergeable no matter how clean `dev`'s own release content is — fix ancestry first via a separate `chore: restore shared ancestry` PR (merge `main` into `dev` with `--allow-unrelated-histories`; do not rebase if `dev` has a `non_fast_forward` ruleset, since rebase requires a force-push and rewrites every commit under every open PR). See `.squad/decisions/inbox/data-restore-dev-main-ancestry.md` for the full worked example and the diff-based verification technique used to prove a dev-wins conflict resolution was safe. + ### 1. Coordinator Does NOT Publish The coordinator routes work and manages agents. It does NOT run `npm publish`, trigger release workflows, or make release decisions. Brady owns the release trigger. If an agent or the coordinator is asked to publish, escalate to Brady. @@ -132,6 +144,7 @@ Set this environment variable in all CI build steps to prevent the build script | GITHUB_TOKEN can't trigger downstream workflows (v0.9.4) | squad-npm-publish.yml never fires | Manual `gh workflow run` or use PAT/GitHub App token (see below) | | Lockfile integrity check rejects workspace packages (v0.9.4) | False failures in squad-npm-publish.yml | Only validate packages resolved from npm registry (`startsWith('https://')`) (PR #1044) | | `prebuild` version bump breaks workspace linking (v0.9.4) | Local builds fail after bump-build.mjs runs | `git checkout -- package.json packages/*/package.json` then fresh install | +| `dev` and `main` silently drift to unrelated histories (2026-08-13) | `dev` → `main` promotion PR is flatly unmergeable, no reviewable diff | Run `git merge-base upstream/dev upstream/main` BEFORE starting release-prep; see Rule 0 above | ## v0.9.4 Incident Learnings diff --git a/cspell.json b/cspell.json index 55d7d0ad6..fa0e1d2bc 100644 --- a/cspell.json +++ b/cspell.json @@ -22,6 +22,7 @@ "Artsdalen", "Aspire", "astro", + "astropy", "Automator", "Baer", "benchmarkfn", @@ -117,6 +118,7 @@ "monorepo", "MSAL", "MSMQ", + "mwaskom", "myaccount", "mycompany", "myorg", @@ -142,6 +144,8 @@ "PRD", "Pruthviraj", "Pydantic", + "pydata", + "pylint", "pypi", "pyproject", "pytest", @@ -180,7 +184,10 @@ "Sturtevant", "subagent", "subagents", + "swebench", "swnger", + "Sympy", + "sympy", "Tamir", "tamirdresher", "telemetry", @@ -221,6 +228,7 @@ "Worf", "worktree", "worktrees", + "xarray", "ZUAER" ], "dictionaries": [ diff --git a/docs/src/content/blog/015-wave-2-the-repl-moment.md b/docs/src/content/blog/015-wave-2-the-repl-moment.md new file mode 100644 index 000000000..f55c35e94 --- /dev/null +++ b/docs/src/content/blog/015-wave-2-the-repl-moment.md @@ -0,0 +1,95 @@ +--- +title: "Wave 2: The REPL Moment" +date: 2026-02-21 +author: "McManus (DevRel)" +wave: 2 +tags: [squad, wave-2, repl, shell, security, testing, developer-experience] +status: published +hero: "We built an interactive shell that makes you forget you're talking to agents. Then we found a command injection vulnerability and fixed it the same day." +--- + +# Wave 2: The REPL Moment + +> 📌 **Archive note:** The interactive shell described in this post has been deprecated. For the best Squad experience, use the [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli). See [Choose your interface](/docs/get-started/choose-your-interface/) for current options. + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + + +> _We built an interactive shell that makes you forget you're talking to agents. Then we found a command injection vulnerability and fixed it the same day._ + +## The Wow Moment + +PR #309 shipped the feature that changed how Squad feels. Not how it works — how it *feels*. + +Type `squad` with no arguments. A welcome banner appears with the Squad logo, version number pulled from `package.json` (no hardcoded strings), and a prompt. Type a message. Agents respond with streaming output. Emoji markers show who's working. The session persists — agents remember what you said three messages ago. + +It sounds simple. It was not simple. The REPL needed to: + +- Stream agent responses token-by-token (no waiting for complete responses) +- Display a welcome banner with dynamic version info +- Handle multi-agent output interleaved on the same terminal +- Track session state across messages (agent registry, routing context, casting decisions) +- Exit cleanly without orphaned processes + +The result is an interactive shell that feels like a conversation. Brady called it the "wow moment" — the point where a demo stops being a walkthrough and becomes an experience. You sit someone down, type `squad`, and they get it. + +## The Security Fix + +While building the REPL, we found CWE-78: OS Command Injection. The beta used `execSync()` to run shell commands from agent tool calls. That's a classic injection vector — if an agent constructs a command string from user input, arbitrary code execution is one backtick away. + +The fix: replace every `execSync()` call with `execFileSync()`. The difference is fundamental: + +- `execSync("git status " + userInput)` — shell interprets `userInput`. If it contains `; rm -rf /`, you're done. +- `execFileSync("git", ["status", userInput])` — no shell. Arguments are passed directly to the process. Injection is structurally impossible. + +This landed in the same PR. No separate security advisory. No drama. Just the right fix in the right place at the right time. CWE-78 closed. + +## Config Extraction + +Wave 2 also extracted hardcoded values into `constants.ts`. Model names, timeout values, agent roles, file paths — all the magic strings scattered across the beta codebase got pulled into typed constants: + +- `MODELS` — every supported model with provider and tier +- `TIMEOUTS` — spawn timeout, polling interval, shutdown grace period +- `AGENT_ROLES` — the cast system's role definitions + +This isn't glamorous work. It's the kind of refactoring that makes every future feature cheaper to build. When Wave 3 needed to reference model names in documentation, the constants were already there. When the adapter hardening sprint needed timeout values, they were already typed. + +## 119 New Tests + +The replatform started with zero tests (clean room, remember?). Wave 1 added integration tests for OTel. Wave 2 added 119 tests covering: + +- Shell initialization and teardown +- Command routing and argument parsing +- Agent spawn lifecycle +- Config loading and validation +- REPL streaming output +- Session state persistence + +Plus an Aspire Playwright E2E test that launches the full stack — Squad CLI, agent runtime, OTel exporter, Aspire dashboard — and verifies traces appear in the UI. End-to-end confidence that the observability pipeline works from agent spawn to dashboard render. + +The test count after Wave 2: meaningful. The test count by Wave 3 completion: 2,232 across 85 test files. The REPL work established the testing patterns that scaled. + +## By the Numbers + +| Metric | Value | +|--------|-------| +| PR | #309 | +| New tests | 119 | +| Security fixes | 1 (CWE-78) | +| Config constants extracted | 3 modules (MODELS, TIMEOUTS, AGENT_ROLES) | +| Hardcoded strings removed | All | +| REPL features | Welcome banner, streaming, emoji, session persistence | + +## What We Learned + +- **Developer experience is a feature.** The REPL doesn't add capabilities Squad didn't have. It makes existing capabilities accessible. The difference between `squad spawn --agent fenster --message "refactor auth"` and typing "refactor auth" in an interactive shell is the difference between a tool and an experience. +- **Security fixes belong in feature PRs.** Finding CWE-78 during REPL development wasn't a distraction — it was the system working. You find security bugs when you're deep in the code. Ship the fix with the feature. Don't create a separate ticket and let it age. +- **Constants are infrastructure.** Extracting magic strings feels like busywork until the third feature that needs them. Then it feels like foresight. + +## What's Next + +Wave 2 gave Squad a voice. Wave 3 gives it a library — documentation that teaches by scenario, not by API surface. The docs engine, 5 initial guides, and a custom site generator. + +--- + +_This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/032-v010-stabilisation-insider.md b/docs/src/content/blog/032-v010-stabilisation-insider.md new file mode 100644 index 000000000..107d82f93 --- /dev/null +++ b/docs/src/content/blog/032-v010-stabilisation-insider.md @@ -0,0 +1,126 @@ +--- +title: "Squad v0.10 Stabilization: Eleven PRs and an Insider Release" +date: 2026-06-14 +author: "Squad (Copilot)" +wave: null +tags: [release, stabilization, insider, memory, presets, cross-squad, fact-checker] +status: published +hero: "v0.10 shipped six big features. v0.10.0-insider.1 makes them work end-to-end: memory tools that survive a fresh Copilot session, presets that wire up the team on apply, skills that land in the right folder, and a Fact-Checker that's on every team by default." +--- + +# Squad v0.10 Stabilization: Eleven PRs and an Insider Release + +> _"Done means a fresh squad init, in a fresh repo, with a two-layer state backend, can build a working app without anyone holding its hand."_ + +## The Problem v0.10 Left Open + +v0.10 introduced six big things: a two-layer state backend, presets, the `squad commands` skill, cross-squad discovery, cross-squad communication, and the Fact-Checker / Devil's Advocate agent. Each one shipped behind feature work; each one had at least one rough edge that surfaced the first time someone tried to use it in anger. + +A weekend of dogfooding found and fixed eleven of those edges. The result is `@bradygaster/squad-cli@0.10.0-insider.1` — install today, get the polished v0.10 experience without waiting for v0.11. + +## Install the Insider + +```bash +# One-off use +npx -y @bradygaster/squad-cli@insider init --state-backend two-layer + +# Or pin it in .copilot/mcp-config.json +{ + "squad_state_": { + "command": "npx", + "args": ["-y", "@bradygaster/squad-cli@0.10.0-insider.1", "state-mcp"] + } +} +``` + +The insider track follows the `-insider.N` pattern. Today: `0.10.0-insider.1`. Each new insider bumps N; the public `latest` tag stays on `0.10.0` until the next stable release. + +## What Got Fixed + +### 1. Memory tools survive a fresh Copilot session + +The two-layer state backend writes squad decisions to an orphan `squad-state` branch and exposes them through the MCP server as `squad_state.*` plus six `memory.*` aliases. Before: a freshly opened Copilot session would show seven tools, sometimes silently. After: + +- A handshake at session start surfaces all thirteen tools as the first function-list call returns (#1306) +- The MCP config no longer accumulates one `squad_state_` entry per project in `~/.copilot/mcp-config.json` (#1298) +- A drift guard in the manifest catches missing skill sources at build time instead of silently dropping them (#1292) +- A HARD RULE in `squad.agent.md` prevents the coordinator from silently degrading when a state-backend probe fails (#1306, closes #1305) + +### 2. Presets wire the team on apply + +`squad preset apply ` used to install the preset files but stop short of wiring the roster. The team table stayed empty, the casting registry was unpopulated, and the next Copilot session would mode-switch into **Init Mode** instead of **Established Mode**. PR #1293 added a merge-friendly `presets/scaffold.ts` that populates: + +- `.squad/team.md` `## Members` table from the preset roster +- `.squad/casting/registry.json` and `history.json` initial entries +- `.squad/routing.md` placeholder substitution + +After: opening a Copilot session on a freshly applied preset shows mode-switch detect **Established Mode** and `squad team list` shows all members. + +### 3. The `squad commands` skill lands in the right folder + +The `squad commands` skill (and `squad-version-check`, `squad-help`) lives in the CLI templates dir but was missing from the SDK manifest, so `squad init` silently skipped it on a fresh install. PR #1292 ports it across plus three other previously-missing skills (`tiered-memory`, `iterative-retrieval`, `reflect`). PR #1304 makes the install target `.github/skills/` (the canonical Copilot CLI skill discovery path) and migrates older squads from `.squad/skills/` on `squad upgrade`. PR #1303 adds a slash-style `/squad` command surface. + +Bonus: a regression test (#1292) asserts `MANIFEST_SKILL_NAMES.length === installed_skills.length`. No more silent skips. + +### 4. Cross-squad communication ships with every squad + +The `cross-squad-communication` skill — which lets one squad call another with `copilot --agent squad --allow-all-tools` — is now bundled by `squad init` and `squad upgrade`. PR #1295 audited the CLI invocations to make sure they use the real flags (`--agent squad`, capital `-C`, `-p` for text not path, `--allow-all-tools`) and added a universal rule: every `copilot` spawn into a peer squad passes `--agent squad`. + +### 5. Fact-Checker / Devil's Advocate is on every team + +The Fact-Checker agent (also operates as Devil's Advocate in its second mode; one agent, two modes per #1254) used to be a manual cast. PR #1300 added it to the always-on roster scaffolded by `squad init` and `squad upgrade`, alongside RAI. PR #1301 gave it a rich charter, its own state dir, and a Linux-CI case-fix for the file path. + +### 6. The coordinator routes "spawn a squad" correctly + +When a user typed "spawn a squad to build X", the coordinator sometimes silently fanned out individual `task` calls instead of using the `task(agent_type="Squad", …)` path. PR #1307 fixed the routing row in `squad.agent.md`, added an `ask_user` clarification step for ambiguous requests, and documented the anti-pattern explicitly. PR #1297 added a `squad` disambiguation skill so `skill(Squad)` lookups succeed and redirect to the right path. + +## End-to-End Smoke Test + +The acceptance criterion this whole weekend was driving toward: + +```powershell +# Fresh dir, fresh git repo, no prior squad state +mkdir C:\Temp\smoke-test; cd C:\Temp\smoke-test; git init + +# Init with two-layer backend +npx -y @bradygaster/squad-cli@insider init --state-backend two-layer + +# Ask it to build something +copilot --agent squad --allow-all-tools ` + -p "build hello-squad — a Node CLI that prints the squad team members" +``` + +Result: the coordinator built three files (`package.json`, `index.js`, `test/index.test.js`), ran the tests, self-corrected one path bug, and finished green in 1m 58s with `1 pass / 0 fail`. The squad-state orphan branch picked up four commits (decisions, history, charters, routing). A fresh Copilot session on the same repo loaded all thirteen MCP tools on the first function-list call. + +## What's Still Open + +- **Preset install from a URL** (PR #1225) — rebased onto post-#1293 dev, awaiting Brady's review +- **`squad.agent.md` slimming** (#1308) — 83KB → ~40KB by extracting Routing / Team Mode / Source-of-Truth / Response Mode / Spawn / Init Mode to satellite skills. Phase 1 PR #1311 ready. +- **Tiered-memory runtime** (#1309) — the skill ships, but the runtime (hot/cold/wiki tiers, Scribe promotion, tier-aware spawn) is design-only. v0.11 candidate. +- **Machine-wide `/squad` skill** (#1310) — so `/squad init` works in any folder without a prior `npx`. v0.11 candidate. +- **Copilot CLI MCP preload** (github/copilot-cli#3787) — upstream feature request to load MCP tools into the initial function list instead of lazy-loading. Our handshake works around it today. + +## The Eleven PRs + +| PR | Title | Touches | +|----|-------|---------| +| [#1292](https://github.com/bradygaster/squad/pull/1292) | Bundle missing skills + manifest drift guard | manifest, templates | +| [#1293](https://github.com/bradygaster/squad/pull/1293) | Preset apply wires team / routing / casting | presets/scaffold.ts | +| [#1295](https://github.com/bradygaster/squad/pull/1295) | Cross-squad-communication skill + CLI correctness | skills, CLI invocations | +| [#1298](https://github.com/bradygaster/squad/pull/1298) | Stop polluting `~/.copilot/mcp-config.json` per project | init.ts, mcp-root.ts | +| [#1300](https://github.com/bradygaster/squad/pull/1300) | Always-on Fact-Checker roster scaffolding | scaffoldAlwaysOnAgents | +| [#1301](https://github.com/bradygaster/squad/pull/1301) | Fact-Checker rich charter + state dir | templates | +| [#1302](https://github.com/bradygaster/squad/pull/1302) | `squad-help` skill | templates | +| [#1303](https://github.com/bradygaster/squad/pull/1303) | `/squad` slash command surface | skills | +| [#1304](https://github.com/bradygaster/squad/pull/1304) | Install skills to `.github/skills/` + migrate | upgrade.ts | +| [#1306](https://github.com/bradygaster/squad/pull/1306) | MCP handshake + HARD RULE on state-backend probe | squad.agent.md, state-mcp.ts | +| [#1307](https://github.com/bradygaster/squad/pull/1307) | "Spawn a squad" routing + ask_user + anti-patterns | squad.agent.md | + +## Try It + +```bash +npx -y @bradygaster/squad-cli@insider --version +# 0.10.0-insider.1 +``` + +If you hit anything that doesn't work the way the docs say it should, file it on [bradygaster/squad](https://github.com/bradygaster/squad/issues). The fastest way to get a fix is a real repro on a fresh `squad init`. diff --git a/docs/src/content/blog/033-swe-bench-lite-results.md b/docs/src/content/blog/033-swe-bench-lite-results.md new file mode 100644 index 000000000..e4c2adb18 --- /dev/null +++ b/docs/src/content/blog/033-swe-bench-lite-results.md @@ -0,0 +1,285 @@ +--- +title: "Squad Achieves #1 on SWE-bench Lite: 66% with Multi-Agent Orchestration" +date: 2026-06-23 +author: "Tamir Dresher" +wave: null +tags: [squad, benchmarks, swe-bench, multi-agent, results] +status: published +hero: "Squad v0.9.6 resolves 198 out of 300 real-world GitHub issues on SWE-bench Lite — a 66% resolve rate that would place it #1 on the leaderboard. Here's how multi-agent orchestration outperforms single-agent systems." +--- + +Squad v0.9.6 just completed its first official run on [SWE-bench Lite](https://www.swebench.com/), the industry-standard benchmark for evaluating AI systems on real-world software engineering tasks. The result: **198 out of 300 issues resolved (66.0%)**, which would place Squad at **#1 on the SWE-bench Lite leaderboard**. + +This post is the technical report for our submission — describing the system architecture, configuration, and methodology behind the result. + +## What is SWE-bench? + +SWE-bench Lite is a curated subset of 300 real GitHub issues from 12 popular open-source Python repositories (Django, Sympy, Matplotlib, Scikit-learn, etc.). Each task requires the system to: + +1. Read a GitHub issue description +2. Analyze the relevant codebase +3. Generate a patch that fixes the issue +4. Pass the repository's existing test suite + +This isn't code generation in a vacuum — it's real-world bug fixing against real test suites, in repositories with hundreds of thousands of lines of code. + +## Results Summary + +| Metric | Value | +|--------|-------| +| **Resolved** | 198 / 300 (66.0%) | +| **Patches generated** | 280 / 300 (93.3%) | +| **Patch apply errors** | 38 (12.7%) | +| **Unresolved (tests fail)** | 44 (14.7%) | +| **No generation** | 20 (6.7%) | + +### Leaderboard Context + +| Rank | System | Score | +|------|--------|-------| +| 🥇 | **Squad v0.9.6** | **66.0%** | +| 🥈 | Claude Opus 4.6 | 62.7% | +| 🥉 | MiniMax M2.5 | 56.3% | +| 4 | OpenAI GPT-5 | 54.3% | +| 5 | Claude Haiku 4.5 | 54.3% | + +### Per-Repository Breakdown + +| Repository | Resolved | Total | Rate | +|-----------|----------|-------|------| +| mwaskom/seaborn | 3 | 4 | 75.0% | +| django/django | 84 | 114 | 73.7% | +| pytest-dev/pytest | 12 | 17 | 70.6% | +| sphinx-doc/sphinx | 11 | 16 | 68.8% | +| astropy/astropy | 4 | 6 | 66.7% | +| pallets/flask | 2 | 3 | 66.7% | +| matplotlib/matplotlib | 15 | 23 | 65.2% | +| sympy/sympy | 48 | 77 | 62.3% | +| scikit-learn/scikit-learn | 14 | 23 | 60.9% | +| pylint-dev/pylint | 3 | 6 | 50.0% | +| pydata/xarray | 2 | 5 | 40.0% | +| psf/requests | 0 | 6 | 0.0% | + +## System Architecture + +Squad is a multi-agent orchestration framework built on [GitHub Copilot CLI](https://github.com/features/copilot). Unlike single-agent approaches that give one model the entire problem, Squad decomposes work through a team of specialized agents with distinct roles. + +### The Team + +For SWE-bench, Squad used its standard team configuration — no special tuning for the benchmark: + +``` +🏗️ Picard — Lead Architecture decisions, code review, routing +💻 Data — Code Expert C#, Go, .NET, Python — implementation +📋 Scribe — Session Logger Memory, decisions, context sharing +``` + +### How It Works + +```mermaid +graph TD + A[SWE-bench Issue] --> B[Squad Coordinator] + B --> C{Route to specialist} + C --> D[Data - Code Expert] + D --> E[Analyze codebase] + E --> F[Identify root cause] + F --> G[Generate patch] + G --> H[Commit fix] +``` + +1. **Coordinator receives the task** — The Squad coordinator agent gets the GitHub issue description and the repository checkout. + +2. **Routing** — The coordinator reads `routing.md` (which maps task types to agents) and dispatches to Data (Code Expert) — the agent specialized in implementation work. + +3. **Agent context loading** — Data receives: + - Its charter (role definition, boundaries, capabilities) + - Team decisions (architectural choices, conventions) + - History (learnings from past tasks) + - The full problem statement + +4. **Implementation** — Data analyzes the issue, navigates the codebase using available tools (grep, view, LSP), identifies the root cause, and generates a fix. + +5. **Patch output** — The agent commits the fix as a git diff, which becomes the prediction. + +### Why Multi-Agent Beats Single-Agent + +The key insight is **separation of concerns**: + +- The **Coordinator** handles routing logic, team state, and decisions — it never writes code. +- The **Code Expert** focuses purely on implementation — it doesn't need to manage its own context or decide what to work on. +- **Charters** prevent agents from drifting — Data knows exactly what it's responsible for and what's out of scope. +- **Decisions memory** accumulates patterns across tasks — even within a single benchmark run, the team builds institutional knowledge. + +This mirrors how effective human engineering teams work: specialists with clear ownership, guided by shared architectural decisions. + +## Configuration + +```yaml +# Squad SWE-bench runner configuration +model: gpt-4o +agent: squad +mode: autopilot (--yolo) +max_autopilot_continues: 50 +timeout_seconds: 1800 # 30 minutes per task +workers: 4 # parallel task execution +total_runtime: ~21 hours +``` + +### Key Parameters + +- **Model: gpt-4o** — Used for all agents (coordinator, lead, and code expert). No model mixing. +- **Autopilot mode** — Agents work without human intervention. The `--yolo` flag prevents confirmation prompts. +- **50 continuation limit** — Prevents infinite loops. Most tasks complete in 10-20 continuations. +- **30-minute timeout** — Generous but bounded. 31 tasks hit the timeout; 20 produced no patch at all, 11 produced partial patches that failed to apply cleanly. +- **4 parallel workers** — Processes 4 issues concurrently. Each worker gets its own git worktree. + +## Methodology + +### Pass@1 Submission + +Each instance is attempted exactly once. No retries, no best-of-k selection, no evaluation feedback loops. + +### No Test Knowledge + +The system does NOT use: +- `PASS_TO_PASS` tests (tests that should continue passing) +- `FAIL_TO_PASS` tests (tests that should start passing after the fix) +- `hints_text` field (human hints about the solution) + +### No Web Browsing + +Squad agents do not have web browsing capabilities. They work purely on: +- The local repository checkout +- The issue description provided by SWE-bench +- Their built-in knowledge from training + +### Evaluation + +Evaluation used the official `swebench.harness.run_evaluation` Docker harness: + +```bash +docker run --rm \ + -v /workspace/predictions.json:/workspace/predictions.json \ + -v /var/run/docker.sock:/var/run/docker.sock \ + swebench-eval \ + --dataset_name princeton-nlp/SWE-bench_Lite \ + --predictions_path /workspace/predictions.json \ + --run_id squad_v1 \ + --max_workers 4 +``` + +The harness: +1. Checks out each repository at the correct commit +2. Applies the predicted patch +3. Runs the repository's test suite +4. Verifies that previously-failing tests now pass +5. Verifies that previously-passing tests still pass + +## Integrity Verification + +We performed a 12-point integrity check on the results: + +1. ✅ All 300 SWE-bench Lite instances present in predictions +2. ✅ Report math checks out (198 + 44 + 38 + 20 = 300) +3. ✅ 300 unique instance_ids, all 12 repos represented +4. ✅ No `.squad/` or `.github/agents/` contamination in patches +5. ✅ All 198 resolved IDs have non-empty patches +6. ✅ Worker logs confirm Squad Team Mode active (sampled) +7. ✅ Data subagent confirmed spawned across sampled tasks +8. ✅ Per-repo rates are internally consistent +9. ✅ Evaluation via official swebench Docker harness +10. ✅ No test knowledge used (PASS_TO_PASS, FAIL_TO_PASS) +11. ✅ No hints field used +12. ✅ No web browsing capabilities available to agents + +## Error Analysis + +### Timeout Cases (31/300, 10.3%) + +31 tasks exceeded the 30-minute timeout. Of these: +- 20 produced no patch at all (the "no generation" category) +- 11 produced partial patches that failed to apply cleanly (included in the 38 "patch apply errors") + +Tasks that timed out typically involved: +- Very large codebases requiring extensive navigation +- Complex multi-file changes where the agent explored many approaches +- Issues requiring deep domain knowledge the model lacked + +### Patch Apply Errors (38/300, 12.7%) + +Generated diffs that couldn't cleanly apply to the target commit. Common causes: +- Line number offsets from generated vs actual file state +- Fuzzy matching failures on complex edits +- Patches generated against a slightly different file state + +### Unresolved — Tests Fail (44/300, 14.7%) + +Patches that applied cleanly but didn't fix the issue. These represent cases where the agent: +- Fixed a symptom but not the root cause +- Made a partial fix that didn't satisfy all test cases +- Misunderstood the issue requirements + +### No Generation (20/300, 6.7%) + +Tasks where the agent couldn't produce a patch within the time limit. All 20 overlap with the timeout cases above — no task failed to generate a patch for non-timeout reasons. + +## Limitations & Attribution + +### Model vs. Orchestration + +Squad's 66% result uses GPT-4o as the base model. An important question: how much of this performance comes from the model vs. the multi-agent orchestration? + +What we know: +- **GPT-4o single-agent** scores in the low-to-mid 40s% on SWE-bench Lite (based on public leaderboard entries for single-agent GPT-4o systems) +- **Squad + GPT-4o** achieved 66% — a ~20+ point improvement over the same base model used alone +- **Claude Opus 4.6 single-agent** (a stronger model) achieves 62.7% — still below Squad + GPT-4o + +This suggests the multi-agent architecture contributes meaningfully, but we cannot claim the full 66% is due to orchestration alone. A rigorous ablation study — running the same tasks with GPT-4o in a single-agent configuration using the same tools and timeout — is planned as a follow-up. + +### Other Limitations + +- **Single model tested** — We haven't yet run Squad with other base models (Claude, o3). It's possible the improvement varies by model. +- **Python-only benchmark** — SWE-bench Lite contains only Python repositories. Squad's performance on other languages is untested. +- **Cost not reported** — We haven't published per-task API costs, which matter for practical comparison. + +## What's Next + +- **Single-agent baseline** — Run GPT-4o without Squad orchestration as an ablation +- **Formal leaderboard submission** via sb-cli +- **SWE-bench Verified** run (500 instances, harder tasks) +- **Full SWE-bench** run (2,294 instances) +- **Model comparison** — Testing with Claude, o3, and other models as the base LLM +- **Team configuration experiments** — Does adding a dedicated Tester agent improve results? + +## Reproducing the Results + +All artifacts — predictions, evaluation report, worker logs, runner code, and agent configuration — are publicly available: + +**📦 [github.com/tamirdresher/squad-swe-bench](https://github.com/tamirdresher/squad-swe-bench)** + +The repository contains: + +``` +benchmarks/swe-bench/ +├── squad_swebench_runner.py # Main orchestrator +├── config.yaml # Configuration +├── squad-scaffold/ # Agent charters & team config +│ └── .squad/ +│ ├── team.md +│ ├── routing.md +│ └── agents/ +├── output/ +│ ├── predictions.json # 300-task predictions +│ └── squad-v1.squad_v1.json # Evaluation report +└── submission/ # Leaderboard submission package +``` + +## About Squad + +Squad is a multi-agent orchestration framework that turns AI coding assistants into coordinated engineering teams. Each agent has a persistent identity, charter, and memory — enabling the kind of specialization and institutional knowledge that makes human teams effective. + +Learn more at [bradygaster.github.io/squad](https://bradygaster.github.io/squad/). + +--- + +*This post serves as the technical report for Squad's SWE-bench Lite leaderboard submission (June 2026).* diff --git a/docs/src/content/docs/features/remote-control.md b/docs/src/content/docs/features/remote-control.md new file mode 100644 index 000000000..47ff15d6f --- /dev/null +++ b/docs/src/content/docs/features/remote-control.md @@ -0,0 +1,326 @@ +# Squad Remote Control + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + + +Control Copilot CLI from your phone via a secure WebSocket tunnel. Perfect for demos, pairing on mobile, or monitoring runs from anywhere. + +```bash +squad start --tunnel +# Shows QR code → scan with phone → terminal appears in browser +``` + +--- + +## What It Does + +`squad start` spawns Copilot CLI in a pseudo-terminal (PTY) and mirrors output to your phone in real-time via: + +1. **PTY** — Copilot runs in a full interactive terminal +2. **WebSocket server** — Terminal I/O streams live via WebSocket +3. **devtunnel** — Secure public URL with authentication (optional) +4. **Phone browser** — xterm.js terminal renders on your phone + +Architecture diagram: + +``` +[Copilot CLI in PTY] + ↓ (terminal output/input) +[WebSocket Server] + ↓ (bidirectional) +[devtunnel] (optional, provides public URL) + ↓ (HTTPS + private auth) +[Phone Browser (xterm.js)] + ↓ (mobile keyboard shortcuts, replay buffer) +[Your Phone] +``` + +--- + +## Prerequisites + +### Required + +- **devtunnel CLI** (for `--tunnel` mode) + ```bash + # Windows (winget) + winget install Microsoft.devtunnel + + # macOS (Homebrew) + brew install devtunnel + + # Or via GitHub releases + # https://github.com/microsoft/devtunnel/releases + ``` + +- **devtunnel authentication** (required before first use) + ```bash + devtunnel user login + # Browser opens → authenticate → success + ``` + +### Optional + +- **Node.js 18+** (for CLI) +- **Modern browser** on phone (iOS Safari, Chrome, Firefox) + +--- + +## Usage Examples + +### Basic: Local PTY Terminal + +No tunnel, no phone access — just run Copilot in a PTY: + +```bash +squad start +# Output: Started PTY terminal (PID: 12345) +# Copilot running locally +``` + +### With Phone Access (devtunnel + QR) + +Create a tunnel, show QR code, let your phone scan and connect: + +```bash +squad start --tunnel +# Output: Started devtunnel session +# Session ID: abc123xyz +# QR Code: [████████████████] +# URL: https://abc123xyz-dev.devtunnels.ms +# +# Tap or scan QR on your phone → terminal appears +``` + +Scan the QR code with your phone camera. Opens browser → terminal renders with xterm.js. + +### Custom Port + +Specify the WebSocket server port: + +```bash +squad start --port 3456 +# Output: WebSocket listening on localhost:3456 +# Access via: ws://localhost:3456 +``` + +### Custom Command + +Run a different shell or program instead of copilot: + +```bash +squad start --tunnel --command powershell +squad start --tunnel --command "python" +squad start --tunnel --command "bash -i" +``` + +### Pass Copilot Flags Through + +All flags after `--tunnel` pass to copilot: + +```bash +squad start --tunnel --yolo +squad start --tunnel --model gpt-4 +squad start --tunnel --no-config +``` + +--- + +## Security Model + +Remote access has **7 layers** of security: + +### 1. **devtunnel Private Auth** +- URL requires `Authorization` header (devtunnel access token) +- Tunnel is private by default — no public discovery + +### 2. **Session Token (UUID, 4-hour TTL)** +- Each session gets a unique token, valid for 4 hours +- Token embedded in QR code or shown as connection string +- Expires automatically + +### 3. **Ticket-Based WebSocket Auth** +- First request exchanges session token for single-use ticket +- Ticket valid 60 seconds, single use only +- Prevents token replay attacks + +### 4. **HTTP Rate Limiting** +- 30 requests per minute per IP address +- Blocks brute-force connection attempts +- Rate limit resets hourly + +### 5. **Environment Variable Blocklist** +- 27 common secret patterns redacted from output +- Blocks: `PASSWORD`, `TOKEN`, `SECRET`, `KEY`, `AWS_`, `GITHUB_`, `API_KEY`, etc. +- ANSI escape sequences cannot bypass redaction + +### 6. **Secret Redaction (27 Patterns + ANSI Bypass Prevention)** +- Secrets matching patterns replaced with `[REDACTED]` +- ANSI codes cannot hide redaction logic +- Example: `Password=mysecret123` → `Password=[REDACTED]` + +### 7. **Connection Limits** +- **Global:** Max 5 concurrent phone connections per session +- **Per IP:** Max 2 concurrent connections per IP address +- Excess connections rejected with 429 (Too Many Requests) + +--- + +## Mobile Keyboard + +When your phone connects, a key bar appears below the terminal: + +| Key | Action | +|-----|--------| +| **↑** / **↓** | Scroll history / scroll terminal output | +| **←** / **→** | Move cursor left / right | +| **Tab** | Insert tab character (or autocomplete if supported) | +| **Enter** | Send command / newline | +| **Esc** | Send Escape key (menu mode, cancel) | +| **Ctrl+C** | Send interrupt signal (SIGINT) — kills running command | +| **Space** | Insert space | +| **⌫** | Backspace / delete | + +--- + +## Replay Buffer + +When a new phone joins the session: + +1. **Terminal history is replayed** — joins don't see a blank screen +2. **Replay window** — last 1000 lines of terminal output +3. **Scrollback included** — can scroll to see previous commands + +This means late-joiners see context, not blank canvas. + +--- + +## Session Dashboard + +List and manage active devtunnel sessions: + +```bash +squad start --list-sessions +# Output: +# Session 1: abc123xyz (2 phones connected, 1h 23m running) +# Session 2: def456uvw (0 phones, 2m running) +# Session 3: ghi789rst (1 phone, idle) +``` + +Kill a session: + +```bash +squad start --kill-session abc123xyz +# Output: Session closed. Remaining: 2 +``` + +--- + +## Architecture Notes + +### PTY-Only Mode + +Remote Control runs in **PTY-only mode** — no Copilot ACP (Agent Control Protocol) messages flow through the WebSocket. The terminal is a **mirror**, not a command channel: + +- Terminal I/O (text, control codes) ↔ WebSocket +- ACP protocol stays local to the Copilot process +- No agent instructions flow through the tunnel + +This design keeps the tunnel stateless and reduces surface area. + +--- + +## Audit Logging + +All connections, authentication, and security events are logged: + +```bash +~/.cli-tunnel/audit/squad-audit-2025-01-15.jsonl +``` + +Each line is a JSON object: + +```json +{ + "timestamp": "2025-01-15T10:23:45.123Z", + "event": "connection", + "session_id": "abc123xyz", + "phone_ip": "203.0.113.42", + "status": "authenticated" +} +``` + +Events logged: +- `connection` — Phone connected +- `disconnection` — Phone disconnected +- `auth_failure` — Token/ticket validation failed +- `rate_limit` — Rate limit exceeded +- `redaction` — Secret pattern matched and redacted +- `command` — Command executed (summary, no args) + +Rotate daily, keep 30 days by default. + +--- + +## Troubleshooting + +### "devtunnel not found" + +Install devtunnel: + +```bash +winget install Microsoft.devtunnel +``` + +Or check `PATH`: + +```bash +where devtunnel +# Should show path to executable +``` + +### "Not authenticated to devtunnel" + +Log in: + +```bash +devtunnel user login +``` + +### Phone doesn't connect (QR code error) + +1. Check QR code isn't expired (valid for 5 minutes) +2. Verify phone is on same network or has internet +3. Try manual URL instead of QR: + ```bash + # Copy URL from terminal and paste in phone browser + https://abc123xyz-dev.devtunnels.ms + ``` + +### Terminal freezes + +This is typically Copilot waiting for input. Type a command or press Enter: + +``` +squad > [CURSOR BLINKING] +``` + +Press Enter to see the prompt. + +### Audit logs missing + +Ensure `~/.cli-tunnel/` directory exists: + +```bash +mkdir -p ~/.cli-tunnel/audit +``` + +Logs are created on first event. + +--- + +## See Also + +- [CLI Reference](../reference/cli.md) — All commands +- [Getting Started](../get-started/installation.md) — Squad setup +- [VS Code Integration](./vscode.md) — Remote Control in VS Code diff --git a/docs/src/content/docs/get-started/choosing-your-path.md b/docs/src/content/docs/get-started/choosing-your-path.md new file mode 100644 index 000000000..16eacec5e --- /dev/null +++ b/docs/src/content/docs/get-started/choosing-your-path.md @@ -0,0 +1,82 @@ +# Choose your path + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +CLI, Copilot agent, or SDK? Pick the right mode for your workflow. + +--- + +## Three modes + +### CLI mode + +Install Squad globally or per-project, then use terminal commands to initialize, route work, and manage your team. + +```bash +npm install -g @bradygaster/squad-cli +squad init +squad status +squad watch +``` + +**Use for:** Terminal workflows, automation scripts, CI/CD integration. + +--- + +### Copilot agent mode + +Talk to Squad in GitHub Copilot CLI or VS Code. Squad is built-in as an agent. Your `.squad/` directory works identically to CLI mode. + +```bash +copilot +> /agent Squad + +Squad: Hey Brady, what are you building? +``` + +**Use for:** Conversational workflows, exploratory work, VS Code users. + +--- + +### SDK mode + +Write TypeScript code that spawns agents, routes work, and coordinates teams programmatically. Full access to Squad's internals. + +```bash +npm install @bradygaster/squad-sdk +``` + +```typescript +import { Coordinator } from '@bradygaster/squad-sdk'; + +const coordinator = new Coordinator(); +const result = await coordinator.route('Build a login page'); +``` + +**Use for:** Building tools on Squad, custom integrations, advanced automation. + +--- + +## Decision table + +| **Your goal** | **Use** | +|---------------|---------| +| Try Squad quickly | **Copilot agent** — no install | +| Work in the terminal | **CLI** | +| Work in VS Code | **Copilot agent** | +| Automate repetitive tasks | **CLI** or **SDK** | +| Build custom tooling | **SDK** | +| CI/CD integration | **CLI** or **SDK** | + +--- + +## Can I use multiple modes? + +Yes. Your `.squad/` directory is the source of truth. CLI, Copilot agent, and SDK all read and write the same files. You can switch between modes anytime. + +Example workflow: +1. Use **Copilot agent** to form your team and do exploratory work +2. Use **CLI** (`squad watch`) to monitor issues in the background +3. Use **SDK** to build a custom deployment script that spawns agents + +All three modes share the same memory and decisions. diff --git a/docs/src/content/docs/guide/personal-squad.md b/docs/src/content/docs/guide/personal-squad.md new file mode 100644 index 000000000..eb6bcebd1 --- /dev/null +++ b/docs/src/content/docs/guide/personal-squad.md @@ -0,0 +1,352 @@ +# Your Personal Squad + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +:::tip[Git helps protect your project state] +We strongly recommend using git to version-control your project `.squad/` directory. Every session writes to it — decisions, logs, orchestration history. Agent charters, skills, and casting histories live in your personal squad directory (not committed to projects). Without version control, context window resets, crashes, or accidental deletions could be unrecoverable. If git isn't an option, regular manual backups to external storage or cloud sync can help protect your work. +::: + +**Try this:** +```bash +squad init --global +``` + +Your agents follow you everywhere now. Same team, every project, persistent memory. + +This tutorial walks you through setup, explains what's happening behind the scenes, and shows a few ways personal squads make your work better. + +--- + +## 1. What Is a Personal Squad? + +Normally, Squad lives inside a single project — `.squad/` in your repo root. Your agents know that project. They don't know your other ones. + +A personal squad flips that. Your team identity — agents, charters, skills, casting history — moves to your personal squad directory. Every project you work in can point to it. + +**Personal squad location by platform:** + +| Platform | Path | +|----------|------| +| Linux | `~/.config/squad/` | +| macOS | `~/Library/Application Support/squad/` | +| Windows | `%APPDATA%\squad\` | + +What that means in practice: + +- Your agents remember your conventions across all your repos +- Skills learned in one project carry over to every other one +- Your Lead reviews code the same way everywhere +- You don't repeat yourself when starting a new project + +You're still one person. But your team travels with you. + +--- + +## 2. Set It Up + +### Install the CLI globally + +```bash +npm install -g @bradygaster/squad-cli +``` + +Now `squad` works from any directory. Not tied to a specific project. + +### Initialize your personal squad + +```bash +squad init --global +``` + +You'll see: + +``` +✅ Personal squad initialized. + {personal squad directory} — your global team root + Agents, skills, and casting will be shared across projects. +``` + +That's it. You have a personal team root. + +### Verify it's working + +```bash +squad status +``` + +``` +Squad Status + Global squad: {personal squad directory} + Agents: 0 (none cast yet — start a session to form your team) + Skills: 0 +``` + +No agents yet. They form when you start your first session. The global directory is just the container — your team comes to life when you give them work. + +### Connect a project + +Navigate to any project and run: + +```bash +cd ~/projects/my-api +squad init +``` + +Squad detects your global team root and writes a pointer: + +``` +✅ Squad initialized. + .squad/config.json → teamRoot: {personal squad directory} + Team identity inherited from personal squad. + Project-local state (decisions, logs) stays here. +``` + +Your project now has its own `.squad/` directory for local state, but your agents, skills, and casting come from the global root. + +Repeat for any project you want connected. + +--- + +## 3. What Just Happened? (Behind the Scenes) + +Two things were created. Understanding the split is the key to personal squads. + +### The global directory: your personal squad + +This is your **team identity**. It contains: + +``` +{personal squad directory}/ + agents/ — your agent charters and histories + casting/ — who's been cast, role assignments + skills/ — accumulated knowledge ("always use Zod", "prefer Tailwind") +``` + +This is the stuff that makes your agents *yours*. It persists across sessions. It grows as you work. It follows you from project to project. + +### The global `squad.agent.md` — a reference, not a live file + +You'll also see `.github/agents/squad.agent.md` inside your global config directory. This file is **not** discoverable by GitHub Copilot — Copilot only reads agent files inside a git repository's `.github/agents/` folder. + +So why is it there? It serves as a **local reference** of the Squad agent instructions that were applied to your projects. The actual source for `squad init` is the packaged template bundled with the CLI (`squad.agent.md.template`), so the global copy is not used as input for future inits. It exists so you can see what Squad generated without opening a project. + +If you want Copilot to use Squad's agent instructions in a project, run `squad init` in that project's root — that creates the "real" `.github/agents/squad.agent.md` inside the git repo where Copilot can discover it. + +### The project pointer: `.squad/config.json` + +Inside each connected project, `.squad/config.json` looks like this: + +```json +{ + "version": 1, + "teamRoot": "{personal squad directory}", + "projectKey": null +} +``` + +That `teamRoot` field is the magic. When Squad's resolution system sees it, the project enters **remote mode**. Here's how the two modes compare: + +| | **Local mode** (default) | **Remote mode** (personal squad) | +|---|---|---| +| Team identity | `.squad/` in project | Personal squad directory (global) | +| Decisions & logs | `.squad/` in project | `.squad/` in project | +| Agents shared? | No — project only | Yes — across all connected projects | +| Skills shared? | No | Yes | + +In remote mode: + +- **Team identity** (agents, charters, skills, casting) → loaded from your personal squad directory +- **Project-local state** (decisions, logs, orchestration-log) → stays in this project's `.squad/` + +The resolution system walks up directories looking for `.squad/`. When it finds one with a `teamRoot` in `config.json`, it switches to remote mode — pulling team identity from the external path while keeping project state local. + +### Why the split matters + +Your agents know you across projects. They remember your conventions. But each project has its own decisions and logs. + +The API project doesn't get cluttered with the frontend project's session history. The Discord bot's architectural decisions stay in the Discord bot. Clean separation — shared brain, local memory. + +--- + +## 4. Use Case: Your Side Projects Get a Team + +You have three side projects. A CLI tool, a web app, a Discord bot. All different stacks. All just you. + +```bash +# Already done once +squad init --global + +# Connect each project +cd ~/projects/cli-tool && squad init +cd ~/projects/web-app && squad init +cd ~/projects/discord-bot && squad init +``` + +Now when you open any of them: + +``` +> Fredo, set up the database layer. +``` + +Fredo already knows you prefer PostgreSQL. He knows you use Zod for validation. He picked that up from working on your CLI tool last week. You didn't tell him again — he remembered. + +Your Lead reviews code the same way in every repo. Your Tester follows the same patterns. Three projects, one consistent team. + +Without a personal squad, you'd re-explain your conventions every time you start a new project. With one, the onboarding is already done. + +--- + +## 5. Use Case: Code Review Across Repos + +Your Lead agent reviews every pull request in every project. But more than that — they remember architectural decisions from *other* repos. + +``` +> Michael, review this new endpoint. +``` + +``` +🏗️ Michael — reviewing /api/users endpoint + +Looks good. Two notes: + - In your CLI tool, you standardized on cursor-based pagination. + This endpoint uses offset pagination. Intentional? + - Missing rate limiting. We added this as a skill after the + auth module in your web app. +``` + +Michael isn't just reviewing code in isolation. He's cross-referencing decisions and skills from your other projects. That's the personal squad at work — knowledge that spans repos. + +The more projects you connect, the richer these reviews become. Your Lead builds a mental model of how *you* build software, not just how one project works. + +--- + +## 6. Use Case: Learning a New Codebase + +You join an open-source project. New repo, unfamiliar code. But your agents already know *you*. + +For projects you don't own — OSS contributions, client work, temporary collaborations — use **consult mode**. Your team consults invisibly, and the project never knows Squad was there: + +```bash +cd ~/projects/new-oss-contribution +squad consult +``` + +Your personal squad is copied into the project's `.squad/` directory, hidden via `.git/info/exclude`. The agents don't know the codebase yet — they'll learn it. But they already know your preferences: + +- How you like code structured +- What testing patterns you follow +- Your communication style (direct? exploratory? detail-oriented?) + +``` +> Team, help me understand this codebase. Where's the entry point +> and how does routing work? +``` + +Your agents explore the repo with your familiar voice. They ask the questions you'd ask. The codebase is new — but your relationship with your team isn't. + +When you're done, extract the generic learnings back to your personal squad and clean up: + +```bash +squad extract --clean +``` + +It's not a cold start. It's your team meeting a new project. + +> 📖 **Full guide:** [Consult Mode](../features/consult-mode.md) — invisible consulting, learning extraction, license handling. + +--- + +## 7. Use Case: Automating Your Personal Workflow + +Your personal squad isn't just for writing code. It's a workflow tool. + +Set a directive once: + +``` +> Always run linting before marking a task done. +``` + +``` +📌 Captured. Linting required before task completion. +``` + +That directive is now in your personal squad directory — every project, every session. Your agents enforce it everywhere. You set the standard once and it sticks. + +Over time, your personal squad becomes an opinionated workflow engine. Not because you configured it that way — because you worked with it and it learned. + +--- + +## 8. Use Case: Skills That Grow Everywhere + +Skills accumulate in your personal squad directory under `skills/`. Every project contributes. + +After a few weeks: + +``` +{personal squad directory}/skills/ + always-use-zod.md + prefer-tailwind.md + cursor-pagination.md + rate-limit-auth-endpoints.md + structured-logging.md + error-boundaries-in-react.md +``` + +These came from different projects. The Zod skill was learned in your API. The Tailwind preference was captured in your web app. The rate-limiting skill came from a code review rejection. + +Now every new project starts with all of that knowledge baked in. Your agents don't make the same mistakes twice — in any repo. + +This is the long game. Early sessions feel similar to project-local squads. But after a few weeks of cross-project work, the difference is real. Your skills directory becomes a personal engineering handbook that your agents actually read. + +--- + +## 9. Where It's Headed + +Honest moment: this is new. Personal squads work, but they're early. + +What works well today: +- Shared team identity across projects +- Skills that accumulate and carry over +- Consistent agent behavior everywhere you work +- **Consult mode** — bring your team to projects you don't own, invisibly ([docs](../features/consult-mode.md)) + +What's still rough: +- No sync mechanism between machines yet — your personal squad directory is local to your machine +- Project keys aren't used for anything yet (that `null` in config.json) +- No UI for browsing your global skills or agent histories (it's files for now) + +We're building in the open. If something feels off, [open an issue](https://github.com/bradygaster/squad/issues). If something feels right, we want to hear about that too. + +--- + +## Tips + +- **Git-first workflow is strongly recommended.** Commit your project `.squad/` directory to git after any session. Without version control: + - Session state could be lost on crashes, context resets, or machine reboots + - Project-local decisions and logs are at risk + - Accidental deletions may be unrecoverable + - Cross-project context could vanish + + Think of git as your insurance policy for your project's local state. It's a good habit: after a session ends, run `git add -- .squad/ && git commit -m "squad: project state"`. (Agent histories, skills, and team identity are stored in your personal squad directory — not in project repos.) + +- **Commit project `.squad/` but not personal squad directory.** The project-local state (decisions, logs) belongs in version control. Your global identity (agents, skills, casting) is personal — keep it out of repos. + ```bash + # DO THIS + git add -- .squad/ + git commit -m "squad: project state" + + # DON'T commit your personal squad directory (~/.config/squad/ or similar) — it's machine-specific + ``` + +- **Check status anytime.** `squad status` shows your global squad directory and which projects are connected. +- **Skills are the payoff.** The more projects you work across, the more skills accumulate. After a month, your agents have a real knowledge base tailored to how *you* build software. +- **It's just files.** Your personal squad directory is a folder on your machine. You can browse it, edit it, back it up, copy it to another machine manually. No magic, no cloud, no lock-in. But **always back up or version-control your `.squad/` state**. +- **Global install matters.** `npm install -g @bradygaster/squad-cli` gives you the `squad` command everywhere. Without it, you'd need `npx` in each project. Global CLI + global squad = full portability. + +--- + +## What to Try Next + +- [**Your First Session**](../get-started/first-session.md) — The full walkthrough from zero to fan-out +- [**Solo Dev Scenario**](../scenarios/solo-dev.md) — Squad for one-person teams +- [**Tips & Tricks**](tips-and-tricks.md) — Patterns that work diff --git a/docs/src/content/docs/guide/shell.md b/docs/src/content/docs/guide/shell.md new file mode 100644 index 000000000..8ff557b7c --- /dev/null +++ b/docs/src/content/docs/guide/shell.md @@ -0,0 +1,343 @@ +# Interactive Shell Guide + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +> 💡 **Recommended: Use GitHub Copilot CLI** — The best way to interact with Squad today is through the [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli). Run `copilot --agent squad` to start a session with your team. The Copilot CLI provides the richest agent experience, including tool use, parallel execution, and full MCP integration. + +The Squad interactive shell gives you a persistent connection to your team.Instead of spawning short-lived CLI invocations, the shell maintains a real-time session where you can talk to agents, issue commands, and watch work happen. + +--- + +## Getting Started + +### Enter the Shell + +```bash +squad +``` + +With no arguments, `squad` enters the interactive shell. You'll see a prompt: + +``` +squad > +``` + +### Exit the Shell + +``` +squad > /quit +``` + +Or press **Ctrl+C**. + +--- + +## Shell Commands + +All shell commands start with a forward slash `/`. + +### `/status` — Check team status + +Display the current state of your squad: active agents, sessions, and recent work. + +``` +squad > /status +``` + +Output: + +``` +Team Status +──────────────────── +Active Agents: 4/5 + Keaton (lead): idle + McManus (devrel): working (10s) + Verbal (backend): working (25s) + Fenster (tester): idle + Kobayashi (scribe): logging + +Sessions: 5 +Latest decision: "Use React Query for data fetching" (2m ago) +``` + +### `/history` — View recent work + +Display the session log and recent decisions. + +``` +squad > /history +``` + +Shows: +- Last 10 completed tasks +- Decisions made in this session +- Agents that have worked +- Full session transcript (searchable) + +### `/agents` — List team members + +Show all agents on the team with their roles, expertise, and knowledge. + +``` +squad > /agents +``` + +### `/sessions` — List saved sessions + +View past shell sessions. Shows the 10 most recent sessions with their ID prefix, timestamp, and message count. + +``` +squad > /sessions +``` + +Output: + +``` +Saved Sessions (3 total) + 1. a1b2c3d4 6/15/2026, 2:30:00 PM (12 messages) + 2. e5f6a7b8 6/14/2026, 10:15:00 AM (8 messages) + 3. c9d0e1f2 6/13/2026, 4:45:00 PM (23 messages) + +Use /resume to restore a session. +``` + +### `/resume ` — Restore a past session + +Resume a previous session by providing the first few characters of its ID. The session's full message history is restored into the current shell. + +``` +squad > /resume a1b2 +✔ Restored session a1b2c3d4 (12 messages) +``` + +Typical workflow — pick up where you left off: + +``` +squad > /sessions +squad > /resume a1b2 +squad > @Keaton, where were we on the auth work? +``` + +### `/clear` — Clear the screen + +Clears terminal output. + +### `/help` — Show all commands + +### `/quit` — Exit the shell + +Close the shell and return to your terminal. + +--- + +## Addressing Agents + +You can talk to specific agents by name: + +### Using `@AgentName` + +``` +squad > @Keaton, analyze the architecture of this project +``` + +### Using natural language + +``` +squad > Keaton, set up the database schema for user authentication +``` + +Or without naming an agent — the coordinator routes to whoever is best suited: + +``` +squad > Write a blog post about our new casting system +``` + +--- + +## Message Routing + +### How Messages Get to Agents + +1. **You type a message** → Shell receives it +2. **Coordinator reads it** → Determines which agent(s) can usefully start +3. **Agents launch in parallel** → All applicable agents work simultaneously +4. **Agents write results** → To `.squad/` (decisions, history, skills, etc.) +5. **Shell streams updates** → You see progress in real-time + +### Parallel Execution + +When you give a task that multiple agents can handle: + +``` +squad > Build the login page +``` + +The coordinator might spawn: +- McManus (frontend) → building the UI +- Verbal (backend) → setting up auth endpoints +- Fenster (tester) → writing test cases +- Kobayashi (scribe) → logging everything + +All at once. All in parallel. + +--- + +## Session Management + +### What Is a Session? + +Each agent gets a **persistent session** — a long-lived context where it remembers: +- The task you gave it +- What it's already written to disk +- Previous decisions and learnings +- Its own knowledge base (charter, history) + +Sessions survive crashes. If an agent dies mid-work, it resumes from the exact checkpoint. + +### Viewing Session History + +``` +squad > /history +``` + +Shows full session log with start time, end time, duration, what the agent did, files written, decisions made, and any errors. + +### Resuming Work + +If an agent crashes or times out: + +``` +squad > @Keaton, check on Verbal and resume if needed +``` + +--- + +## Keyboard Shortcuts + +| Shortcut | Action | +|----------|--------| +| `↑` / `↓` | Scroll command history | +| `Ctrl+A` | Jump to start of line | +| `Ctrl+E` | Jump to end of line | +| `Ctrl+U` | Clear to start of line | +| `Ctrl+K` | Clear to end of line | +| `Ctrl+W` | Delete previous word | +| `Ctrl+C` | Exit shell | + +--- + +## Tips and Tricks + +### Check `/status` before big asks + +Before sending a complex task, check team status. If agents are already working, you might want to wait. + +### Reference decisions, not details + +Instead of explaining the whole architecture: + +``` +# Don't: +squad > Build the auth system. Use JWT. Refresh tokens every 1 hour... + +# Do: +squad > Build the auth system. See the auth decision in decisions.md. +``` + +Agents read your decisions — they're shortcuts for complex context. + +### Batch work through the coordinator + +``` +squad > @Keaton, here's what needs doing: +1. Set up database schema +2. Build API endpoints +3. Write tests + +Prioritize and route, please. +``` + +The coordinator will decompose, prioritize, and launch agents efficiently. + +### Check `/history` after long waits + +If you step away, run `/history` to see what happened. Every decision is logged, every task is recorded. + +### Name agents explicitly for urgent work + +``` +squad > @Keaton, this is critical: we need the deployment script fixed +``` + +The explicit mention ensures the lead coordinator sees it first. + +--- + +## Advanced Usage + +### Working with Multiple Tasks + +The coordinator queues tasks and parallelizes where possible: + +``` +squad > Write the API spec +squad > Build the React components +squad > Set up the database + +/status # See all three being worked on +``` + +### Asking Agents About Their Work + +``` +squad > @Verbal, what's left on the auth endpoints? +squad > @McManus, show me what you've written so far +squad > @Fenster, are the tests passing? +``` + +Agents respond with status, file paths, and blockers. + +### Custom Agent Chaining + +Instead of asking the coordinator to chain work, set up explicit hand-offs: + +``` +squad > @Keaton, when Verbal finishes the auth API, have him route testing to Fenster +``` + +--- + +## Using the Shell with VS Code + +1. Open an integrated terminal in VS Code +2. Run `squad` to enter the shell +3. Keep it open in a side panel +4. As you edit code, ask agents to review: `@Fenster, test this component` + +--- + +## Troubleshooting + +### Shell Hangs or No Response + +The coordinator might be evaluating a complex task, or an agent might be streaming large output. Press `Ctrl+C` to interrupt, then check `/status`. + +### Agent Not Responding + +Check `/status` and `/history` for blockers. Then ask the coordinator to route explicitly: + +``` +squad > @Keaton, route this task to @Verbal and report any blocks +``` + +### Shell Quit Unexpectedly + +Run `squad` again to restart. Check `.squad/log/` for error context. + +--- + +## See Also + +- [CLI Reference](../reference/cli.md) — All CLI commands +- [VS Code](../features/vscode.md) — Squad in VS Code +- [Parallel Execution](../features/parallel-execution.md) — How agents fan out diff --git a/docs/src/navigation.ts b/docs/src/navigation.ts index 706d250ef..45f760bfd 100644 --- a/docs/src/navigation.ts +++ b/docs/src/navigation.ts @@ -91,6 +91,8 @@ export const NAV_SECTIONS: NavSection[] = [ items: [ { title: 'GitHub Agentic Workflows', slug: 'guide/gh-aw' }, { title: 'Choose Your Interface', slug: 'get-started/choose-your-interface' }, + { title: 'Your Personal Squad', slug: 'guide/personal-squad' }, + { title: 'Interactive Shell Guide', slug: 'guide/shell' }, { title: 'Tips & Tricks', slug: 'guide/tips-and-tricks' }, { title: 'Sample Prompts', slug: 'guide/sample-prompts' }, { title: 'Recipes', slug: 'cookbook/recipes' }, diff --git a/test/docs-build.test.ts b/test/docs-build.test.ts index 96ec24dbf..c16040a03 100644 --- a/test/docs-build.test.ts +++ b/test/docs-build.test.ts @@ -25,7 +25,7 @@ function docsBuildSkipReason(): string | null { // Expected content directories in src/content/docs/ const EXPECTED_GET_STARTED = ['installation', 'first-session', 'five-minute-start', 'choose-your-interface', 'migration']; -const EXPECTED_GUIDES = ['agent-framework-integration', 'build-autonomous-agent', 'building-extensions', 'building-resilient-agents', 'contributing', 'contributors', 'extensibility', 'faq', 'gh-aw', 'github-auth-setup', 'sample-prompts', 'tips-and-tricks']; +const EXPECTED_GUIDES = ['agent-framework-integration', 'build-autonomous-agent', 'building-extensions', 'building-resilient-agents', 'contributing', 'contributors', 'extensibility', 'faq', 'gh-aw', 'github-auth-setup', 'personal-squad', 'sample-prompts', 'shell', 'tips-and-tricks']; const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks', 'glossary', 'container-image', 'state-backend-selection'];