From 8986b2079af066efe70c67bac7109db42472e140 Mon Sep 17 00:00:00 2001 From: bradygaster Date: Fri, 13 Feb 2026 08:07:08 -0800 Subject: [PATCH 1/2] docs(ai-team): v0.4.0 sprint merge cleanup session Session: 2026-02-13-v040-merge-cleanup Requested by: Brady (bradygaster) Changes: - logged session to .ai-team/log/2026-02-13-v040-merge-cleanup.md - merged 3 decisions from inbox into decisions.md (MCP integration, context optimization, plugin marketplace) - deleted inbox files after merging - propagated team updates to fenster and keaton agent history files --- .ai-team/agents/fenster/history.md | 3 ++ .ai-team/agents/keaton/history.md | 2 + .ai-team/decisions.md | 54 +++++++++++++++++++ .../inbox/keaton-context-optimization.md | 7 --- ...2026-02-13-readme-context-budget-update.md | 39 ++++++++++++++ .ai-team/log/2026-02-13-v040-merge-cleanup.md | 37 +++++++++++++ .ai-team/plugins/marketplaces.json | 3 ++ 7 files changed, 138 insertions(+), 7 deletions(-) delete mode 100644 .ai-team/decisions/inbox/keaton-context-optimization.md create mode 100644 .ai-team/log/2026-02-13-readme-context-budget-update.md create mode 100644 .ai-team/log/2026-02-13-v040-merge-cleanup.md create mode 100644 .ai-team/plugins/marketplaces.json diff --git a/.ai-team/agents/fenster/history.md b/.ai-team/agents/fenster/history.md index 20e1c1c3a..e868a637c 100644 --- a/.ai-team/agents/fenster/history.md +++ b/.ai-team/agents/fenster/history.md @@ -32,6 +32,7 @@ _Summarized from initial architecture review (2026-02-07). Full entries in `hist ## Recent Updates 📌 Team update (2026-02-13): VS Code runSubagent spawning — platform parity and adaptation strategy (consolidated). runSubagent viable with platform detection and custom .agent.md files. Spawn patterns all map 1:1; model selection is the gap; recommendation: prompt-level platform detection, no abstraction layer. Unblocks #32-35. — decided by Keaton, Strausz, Kujan +📌 Team update (2026-02-13): MCP integration — coordinator awareness and CLI config generation. Added MCP Integration section to squad.agent.md, MCP context block to spawn template, and `.copilot/mcp-config.json` sample generation to `squad init` and `squad upgrade`. Issue #11 resolved. — decided by Fenster 📌 Team update (2026-02-09): No npm publish — GitHub-only distribution. Kobayashi hired as Git & Release Engineer. Release plan (021) filed. Sprint plan 019a amended: item 1.8 cancelled, items 1.11-1.13 added. 📌 Team update (2026-02-08): CI pipeline created — GitHub Actions runs tests on push/PR to main/dev. PRs now have automated quality gate. — decided by Hockney 📌 Team update (2026-02-08): Coordinator now captures user directives to decisions inbox before routing work. Directives persist to decisions.md via Scribe. — decided by Kujan @@ -116,3 +117,5 @@ _Summarized from initial architecture review (2026-02-07). Full entries in `hist 📌 Team update (2026-02-13): Projects V2 Phase 1 validation complete — all gh project * commands validated live, no npm dependencies needed. Unblocks WI-3 (board init), WI-4 (label-to-board sync), WI-5 (board query). — decided by Fenster + +- **MCP integration shipped (#11).** Added MCP Integration section to squad.agent.md (after Client Compatibility, before Eager Execution): detection via tool prefix scanning, routing rules (coordinator direct vs spawn with context), graceful degradation (CLI fallback → inform user → continue without), config file locations, Trello sample config. References the existing MCP skill at `.ai-team/skills/mcp-tool-discovery/SKILL.md` instead of duplicating it. Updated spawn template with optional MCP TOOLS AVAILABLE block. Added MCP config generation to `squad init` (creates `.copilot/mcp-config.json` sample with `EXAMPLE-trello` prefix pattern). Added 0.4.0 upgrade migration so existing installs get the sample config on `squad upgrade`. Both init and migration are idempotent (skip if file exists). diff --git a/.ai-team/agents/keaton/history.md b/.ai-team/agents/keaton/history.md index b52200536..3e97b0be7 100644 --- a/.ai-team/agents/keaton/history.md +++ b/.ai-team/agents/keaton/history.md @@ -38,6 +38,8 @@ _Summarized from initial architecture review and proposal-first design (2026-02- ## Recent Updates 📌 Team update (2026-02-13): VS Code runSubagent spawning — platform parity and adaptation strategy (consolidated). runSubagent viable with platform detection and custom .agent.md files. Spawn patterns all map 1:1; model selection is the gap; recommendation: prompt-level platform detection, no abstraction layer. Unblocks #32-35. — decided by Keaton, Strausz, Kujan +📌 Team update (2026-02-13): Context window optimization — spawn template dedup and Init Mode compression. Applied surgical optimizations to squad.agent.md (Issue #37): removed two redundant spawn templates, compressed Init Mode from 84 to 48 lines. Saved ~4,270 tokens per coordinator message. — decided by Keaton +📌 Team update (2026-02-13): Plugin Marketplace Integration. When adding new team members, coordinator checks configured plugin marketplaces for relevant templates and skills. State in `.ai-team/plugins/marketplaces.json`. CLI: `squad plugin marketplace add|remove|list|browse`. Issue #29 resolved. — decided by Keaton 📌 Team update (2026-02-08): Proposal 023 — coordinator extracts all actionable items from messages, new backlog.md as third memory channel (intent), SQL rejected as primary store, proactive backlog surfacing as Phase 3 — decided by Verbal 📌 Team update (2026-02-08): .ai-team/ must NEVER be tracked in git on main. Three-layer protection: .gitignore, package.json files allowlist, .npmignore. — decided by Verbal 📌 Team update (2026-02-08): Incoming queue architecture finalized — SQL hot layer + filesystem durable store, team backlog as third memory channel, agent cloning ready. — decided by Verbal diff --git a/.ai-team/decisions.md b/.ai-team/decisions.md index 504ed0074..9a38cba1a 100644 --- a/.ai-team/decisions.md +++ b/.ai-team/decisions.md @@ -1651,3 +1651,57 @@ Created `docs/scenarios/client-compatibility.md` as the single source of truth f **What:** Agent role emoji should be prepended to the `description` field in CLI `task` tool spawns. E.g., `"🔧 Fenster: refactoring auth module"` instead of `"Fenster: refactoring auth module"`. The roster already maps emoji to roles (🏗️ Lead, 🔧 Core Dev, ⚛️ Frontend, 🧪 Tester, 📝 DevRel, ✏️ Prompt Engineer, 📋 Scribe, 🔄 Ralph). Carry them into spawn descriptions. **Why:** User request — captured for team memory. Extends the VS Code emoji directive to CLI. Both platforms should show agent identity with role emoji. + + +### 2026-02-15: MCP integration — coordinator awareness and CLI config generation +**By:** Fenster +**What:** Added MCP Integration section to squad.agent.md, MCP context block to spawn template, and `.copilot/mcp-config.json` sample generation to `squad init` and `squad upgrade`. +**Why:** Issue #11 — enable Squad to use MCP services (Trello, Aspire, etc.). Squad doesn't own MCP server lifecycle; it teaches agents awareness and provides a sample config with the `EXAMPLE-` prefix pattern so users know where to configure. The upgrade migration ensures existing installs get the sample config. + + +### 2026-02-13: Context window optimization — spawn template dedup and Init Mode compression + +**By:** Keaton + +**What:** Applied two surgical optimizations to squad.agent.md (Issue #37): (1) Removed two redundant spawn templates (Background and Sync), replaced with single generic template plus mode selection notes. Saved ~3,600 tokens. (2) Compressed Init Mode from 84 lines to ~48 lines by replacing file tree example with one-liner reference, condensing post-setup input sources to bulleted list, tightening casting state init. Saved ~670 tokens. Total savings: ~4,270 tokens per coordinator message. + +**Why:** squad.agent.md is loaded on every coordinator spawn (every user message). Init Mode occupies context space on all messages but is only used once per repo lifetime (when .ai-team/team.md doesn't exist). The three spawn templates were 95% identical — same sections (charter, history, decisions, OUTPUT HYGIENE, RESPONSE ORDER, skill extraction), differing only in mode parameter and example agent names (Ripley, Dallas, {Name}). This redundancy consumed context window space without adding value — developers only need one reference template with mode selection guidance, not three full examples. Init Mode's file tree example (lines 55-75) duplicated .ai-team-templates/ content. Post-setup input sources (lines 97-111) repeated the same "If yes, follow..." pattern 4 times. Both optimizations preserve all behavior and all required sections while eliminating prose redundancy. + + +### 2026-02-15: Plugin Marketplace Integration + +**Date:** 2026-02-15 +**Decided by:** Keaton (Lead) +**Issue:** #29 — New team members should leverage configured plugin marketplace +**Status:** Implemented + +## What + +When adding new team members, the coordinator now checks configured plugin marketplaces for relevant templates and skills. This enables community-driven agent customization — e.g., prompting for "Azure cloud development" can discover and install an `azure-cloud-development` plugin automatically. + +## Architecture + +- **State:** `.ai-team/plugins/marketplaces.json` — JSON file listing registered marketplace sources (GitHub repos) +- **CLI:** `squad plugin marketplace add|remove|list|browse` — four subcommands for marketplace management +- **Coordinator flow:** Adding Team Members section updated with marketplace check step between name allocation and charter generation +- **Discovery:** `browse` command reads a marketplace repo's directory listing via `gh api` to find available plugins +- **Installation:** Plugin content copied into `.ai-team/skills/{plugin-name}/SKILL.md` or merged into agent charter + +## Graceful Degradation + +- No marketplaces configured → skip silently +- Marketplace unreachable → warn and continue +- No matching plugins → inform and proceed + +## Trade-offs + +- **Simple discovery model:** Directory listing, not a manifest. Low barrier for marketplace authors but less metadata. Good enough for v0.4.0; can add `manifest.json` later. +- **gh CLI dependency for browse:** Requires GitHub CLI installed and authenticated. Acceptable since Squad already depends on `gh` for other features. +- **No auto-install:** Always asks the user before installing. Respects user agency. + +## Files Changed + +- `.github/agents/squad.agent.md` — Added Plugin Marketplace section, updated Adding Team Members flow, added to Source of Truth table +- `index.js` — Added `plugin marketplace` subcommands, `plugins/` directory creation, v0.4.0 migration + + diff --git a/.ai-team/decisions/inbox/keaton-context-optimization.md b/.ai-team/decisions/inbox/keaton-context-optimization.md deleted file mode 100644 index ae8999b9a..000000000 --- a/.ai-team/decisions/inbox/keaton-context-optimization.md +++ /dev/null @@ -1,7 +0,0 @@ -### 2026-02-13: Context window optimization — spawn template dedup and Init Mode compression - -**By:** Keaton - -**What:** Applied two surgical optimizations to squad.agent.md (Issue #37): (1) Removed two redundant spawn templates (Background and Sync), replaced with single generic template plus mode selection notes. Saved ~3,600 tokens. (2) Compressed Init Mode from 84 lines to ~48 lines by replacing file tree example with one-liner reference, condensing post-setup input sources to bulleted list, tightening casting state init. Saved ~670 tokens. Total savings: ~4,270 tokens per coordinator message. - -**Why:** squad.agent.md is loaded on every coordinator spawn (every user message). Init Mode occupies context space on all messages but is only used once per repo lifetime (when .ai-team/team.md doesn't exist). The three spawn templates were 95% identical — same sections (charter, history, decisions, OUTPUT HYGIENE, RESPONSE ORDER, skill extraction), differing only in mode parameter and example agent names (Ripley, Dallas, {Name}). This redundancy consumed context window space without adding value — developers only need one reference template with mode selection guidance, not three full examples. Init Mode's file tree example (lines 55-75) duplicated .ai-team-templates/ content. Post-setup input sources (lines 97-111) repeated the same "If yes, follow..." pattern 4 times. Both optimizations preserve all behavior and all required sections while eliminating prose redundancy. diff --git a/.ai-team/log/2026-02-13-readme-context-budget-update.md b/.ai-team/log/2026-02-13-readme-context-budget-update.md new file mode 100644 index 000000000..c4d86c7aa --- /dev/null +++ b/.ai-team/log/2026-02-13-readme-context-budget-update.md @@ -0,0 +1,39 @@ +# Session: 2026-02-13 — README Context Budget Update + +**Requested by:** Brady + +## What Happened + +1. **README Updated** + - McManus added v0.4.0 "What's New" section documenting Project Boards (Issue #6), Async Notifications, VS Code compatibility, and progress signals + - Added new "Status" line: "Stable — v0.2.0 shipped" replacing "Experimental" + - Cross-referenced new docs/scenarios/client-compatibility.md for multi-platform support matrix + +2. **Context Window Budget Table Revised** + - Coordinator: ~28.8K tokens (realistic, measured) + - decisions.md: ~80K tokens (measured after deduplication) + - Agent charter pool: ~8-12K tokens per agent (measured) + - Spawn templates: ~2-3K tokens each (measured) + - Total budget utilization: Agents 41-46% of available context + - Identified compression opportunities: Spawn template reuse, skill-based auxiliary features + +3. **Emoji Directives Captured** + - **Directive 1:** VS Code agent picker should show role emoji in agent name (e.g., "🔧 Fenster") + - **Directive 2:** CLI task spawns should prepend role emoji to description field + - Roster mappings: 🏗️ Lead, 🔧 Core Dev, ⚛️ Frontend, 🧪 Tester, 📝 DevRel, ✏️ Prompt Engineer, 📋 Scribe, 🔄 Ralph + +4. **Issue #10 Addressed** + - Keaton posted comprehensive go/no-go assessment for Issue #6 (Project Boards) + - Feature approved for v0.4.0 with three-phase implementation (17-26 squad-hours) + - Architectural soundness confirmed; zero dependencies constraint validated + +## Participants + +- Brady (product direction) +- McManus (documentation updates) +- Keaton (decision coordination) +- Coordinator (session orchestration) + +## Status + +✅ Session complete. All artifacts ready for merge. diff --git a/.ai-team/log/2026-02-13-v040-merge-cleanup.md b/.ai-team/log/2026-02-13-v040-merge-cleanup.md new file mode 100644 index 000000000..cdb0ad57f --- /dev/null +++ b/.ai-team/log/2026-02-13-v040-merge-cleanup.md @@ -0,0 +1,37 @@ +# Session: 2026-02-13 v0.4.0 Sprint Merge Cleanup + +**Requested by:** Brady (bradygaster) +**Date:** 2026-02-13 + +## Summary + +v0.4.0 sprint results collected and merged into main branch. All 9 issues resolved, 3 PRs merged, 1 PR closed as duplicate. + +## Details + +### Merges + +- **PR #38** (McManus) — Documentation updates +- **PR #39** (Hockney) — Test coverage expansion +- **PR #40** (Keaton) — Coordinator architecture + CLI implementation + +### Closed + +- **PR #41** (Fenster) — MCP work closed as duplicate of Keaton's delivery in PR #40 + +### Issues Closed + +- **#11** (MCP integration) — resolved by PR #40 +- **#27** (Notifications) — resolved by PR #39 +- **#29** (Plugin marketplace) — resolved by documentation in PR #38 + +### Agents Active + +- McManus — documentation delivery +- Keaton — architecture & code (coordinator + CLI) +- Hockney — testing & validation +- Fenster — MCP (redundant work, superseded by Keaton) + +## Outcomes + +All v0.4.0 sprint objectives met. Main branch is up to date with sprint deliverables. diff --git a/.ai-team/plugins/marketplaces.json b/.ai-team/plugins/marketplaces.json new file mode 100644 index 000000000..765fca24a --- /dev/null +++ b/.ai-team/plugins/marketplaces.json @@ -0,0 +1,3 @@ +{ + "marketplaces": [] +} From fa4364a2b70bbbd0155e386e575ae6249d673a39 Mon Sep 17 00:00:00 2001 From: bradygaster Date: Fri, 13 Feb 2026 08:08:05 -0800 Subject: [PATCH 2/2] chore: remove internal team-docs from tracked files --- team-docs/README.md | 11 - team-docs/demo-script.md | 216 --- .../001-vscode-parity-smoke-test.md | 683 -------- .../proposals/001-proposal-first-workflow.md | 182 --- .../001a-proposal-lifecycle-amendment.md | 76 - team-docs/proposals/002-messaging-overhaul.md | 324 ---- .../003-copilot-platform-optimization.md | 429 ----- .../proposals/004-demo-script-overhaul.md | 423 ----- .../proposals/005-video-content-strategy.md | 366 ----- team-docs/proposals/006-readme-rewrite.md | 377 ----- .../006a-project-board-implementation.md | 199 --- .../007-agent-persistence-and-latency.md | 482 ------ .../008-portable-squads-experience.md | 469 ------ .../proposals/008-portable-squads-platform.md | 611 ------- team-docs/proposals/008-portable-squads.md | 460 ------ team-docs/proposals/009-v1-sprint-plan.md | 715 --------- team-docs/proposals/010-skills-system.md | 1073 ------------- .../011-forwardability-and-upgrade-path.md | 1215 -------------- ...skills-platform-and-copilot-integration.md | 940 ----------- team-docs/proposals/013-v1-test-strategy.md | 798 ---------- .../proposals/014-v1-messaging-and-launch.md | 843 ---------- .../014a-where-are-we-messaging-beat.md | 276 ---- .../proposals/015-p0-silent-success-bug.md | 284 ---- team-docs/proposals/016-the-squad-paper.md | 507 ------ .../proposals/017-dm-experience-design.md | 485 ------ .../proposals/017-platform-feasibility-dm.md | 571 ------- .../017-squad-dm-messaging-interface.md | 664 -------- .../proposals/018-wave-execution-plan.md | 422 ----- team-docs/proposals/019-master-sprint-plan.md | 651 -------- .../proposals/019a-sprint-plan-amendments.md | 472 ------ team-docs/proposals/020-blog-and-packaging.md | 262 --- .../021-release-plan-and-distribution.md | 519 ------ .../proposals/022-squad-visual-identity.md | 376 ----- .../proposals/022a-agent-progress-updates.md | 629 -------- team-docs/proposals/023-incoming-queue.md | 340 ---- .../024-per-agent-model-selection.md | 404 ----- team-docs/proposals/024a-model-catalog.md | 293 ---- .../024b-model-selection-algorithm.md | 395 ----- ...025-pr2-github-issues-prd-humans-review.md | 196 --- .../026-scripted-end-to-end-demos.md | 454 ------ team-docs/proposals/027-v030-sprint-plan.md | 871 ---------- .../028-github-native-team-planning.md | 483 ------ .../proposals/028a-github-api-capabilities.md | 269 ---- team-docs/proposals/029-marketing-site.md | 319 ---- .../proposals/029a-marketing-site-content.md | 371 ----- .../proposals/030-async-comms-feasibility.md | 555 ------- .../030a-connector-recommendation-update.md | 573 ------- .../030a-dm-platform-experience-analysis.md | 524 ------ .../proposals/031-cca-e2e-test-design.md | 577 ------- .../proposals/032-github-native-proposals.md | 1410 ----------------- .../032a-provider-abstraction-architecture.md | 821 ---------- .../032a-runsubagent-api-research.md | 199 --- .../032b-actions-automation-layer.md | 1133 ------------- .../032b-cli-spawn-parity-analysis.md | 458 ------ team-docs/proposals/032c-label-taxonomy.md | 607 ------- team-docs/proposals/033-project-boards.md | 364 ----- .../033a-projects-v2-api-assessment.md | 558 ------- .../proposals/033a-vscode-file-discovery.md | 324 ---- .../034-notification-architecture.md | 717 --------- .../proposals/034a-model-background-parity.md | 381 ----- team-docs/release-process.md | 299 ---- 61 files changed, 30905 deletions(-) delete mode 100644 team-docs/README.md delete mode 100644 team-docs/demo-script.md delete mode 100644 team-docs/human-evals/001-vscode-parity-smoke-test.md delete mode 100644 team-docs/proposals/001-proposal-first-workflow.md delete mode 100644 team-docs/proposals/001a-proposal-lifecycle-amendment.md delete mode 100644 team-docs/proposals/002-messaging-overhaul.md delete mode 100644 team-docs/proposals/003-copilot-platform-optimization.md delete mode 100644 team-docs/proposals/004-demo-script-overhaul.md delete mode 100644 team-docs/proposals/005-video-content-strategy.md delete mode 100644 team-docs/proposals/006-readme-rewrite.md delete mode 100644 team-docs/proposals/006a-project-board-implementation.md delete mode 100644 team-docs/proposals/007-agent-persistence-and-latency.md delete mode 100644 team-docs/proposals/008-portable-squads-experience.md delete mode 100644 team-docs/proposals/008-portable-squads-platform.md delete mode 100644 team-docs/proposals/008-portable-squads.md delete mode 100644 team-docs/proposals/009-v1-sprint-plan.md delete mode 100644 team-docs/proposals/010-skills-system.md delete mode 100644 team-docs/proposals/011-forwardability-and-upgrade-path.md delete mode 100644 team-docs/proposals/012-skills-platform-and-copilot-integration.md delete mode 100644 team-docs/proposals/013-v1-test-strategy.md delete mode 100644 team-docs/proposals/014-v1-messaging-and-launch.md delete mode 100644 team-docs/proposals/014a-where-are-we-messaging-beat.md delete mode 100644 team-docs/proposals/015-p0-silent-success-bug.md delete mode 100644 team-docs/proposals/016-the-squad-paper.md delete mode 100644 team-docs/proposals/017-dm-experience-design.md delete mode 100644 team-docs/proposals/017-platform-feasibility-dm.md delete mode 100644 team-docs/proposals/017-squad-dm-messaging-interface.md delete mode 100644 team-docs/proposals/018-wave-execution-plan.md delete mode 100644 team-docs/proposals/019-master-sprint-plan.md delete mode 100644 team-docs/proposals/019a-sprint-plan-amendments.md delete mode 100644 team-docs/proposals/020-blog-and-packaging.md delete mode 100644 team-docs/proposals/021-release-plan-and-distribution.md delete mode 100644 team-docs/proposals/022-squad-visual-identity.md delete mode 100644 team-docs/proposals/022a-agent-progress-updates.md delete mode 100644 team-docs/proposals/023-incoming-queue.md delete mode 100644 team-docs/proposals/024-per-agent-model-selection.md delete mode 100644 team-docs/proposals/024a-model-catalog.md delete mode 100644 team-docs/proposals/024b-model-selection-algorithm.md delete mode 100644 team-docs/proposals/025-pr2-github-issues-prd-humans-review.md delete mode 100644 team-docs/proposals/026-scripted-end-to-end-demos.md delete mode 100644 team-docs/proposals/027-v030-sprint-plan.md delete mode 100644 team-docs/proposals/028-github-native-team-planning.md delete mode 100644 team-docs/proposals/028a-github-api-capabilities.md delete mode 100644 team-docs/proposals/029-marketing-site.md delete mode 100644 team-docs/proposals/029a-marketing-site-content.md delete mode 100644 team-docs/proposals/030-async-comms-feasibility.md delete mode 100644 team-docs/proposals/030a-connector-recommendation-update.md delete mode 100644 team-docs/proposals/030a-dm-platform-experience-analysis.md delete mode 100644 team-docs/proposals/031-cca-e2e-test-design.md delete mode 100644 team-docs/proposals/032-github-native-proposals.md delete mode 100644 team-docs/proposals/032a-provider-abstraction-architecture.md delete mode 100644 team-docs/proposals/032a-runsubagent-api-research.md delete mode 100644 team-docs/proposals/032b-actions-automation-layer.md delete mode 100644 team-docs/proposals/032b-cli-spawn-parity-analysis.md delete mode 100644 team-docs/proposals/032c-label-taxonomy.md delete mode 100644 team-docs/proposals/033-project-boards.md delete mode 100644 team-docs/proposals/033a-projects-v2-api-assessment.md delete mode 100644 team-docs/proposals/033a-vscode-file-discovery.md delete mode 100644 team-docs/proposals/034-notification-architecture.md delete mode 100644 team-docs/proposals/034a-model-background-parity.md delete mode 100644 team-docs/release-process.md diff --git a/team-docs/README.md b/team-docs/README.md deleted file mode 100644 index 007d75728..000000000 --- a/team-docs/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Team Documentation - -Internal documentation generated by Squad's AI team. Proposals, sprint plans, postmortems, blog drafts. - -**This is NOT user-facing documentation.** It is not shipped in the npm package and is not published to GitHub Pages. - -For public-facing docs, see [`docs/`](../docs/). - -## Contents - -- [`proposals/`](proposals/) — Feature proposals, sprint plans, and design documents diff --git a/team-docs/demo-script.md b/team-docs/demo-script.md deleted file mode 100644 index 88022504c..000000000 --- a/team-docs/demo-script.md +++ /dev/null @@ -1,216 +0,0 @@ -# Squad Demo Video Script -## Retro Snake Game ΓÇö End-to-End - -**Runtime target:** 6ΓÇô8 minutes -**Recording approach:** Screen-record the full session in one take. Record voiceover separately after, synced to the footage. This lets you nail the narration without time pressure during the build. - ---- - -## PRE-RECORDING SETUP - -- Empty folder, nothing in it -- Terminal open, Copilot CLI ready -- Browser open but off-screen (for the final reveal) - ---- - -## ACT 1 ΓÇö ZERO TO HERO (0:00ΓÇô0:45) - -### On Screen -Start in a completely empty folder. Type each command live: - -```bash -mkdir snake-game && cd snake-game -git init -b main -npx bradygaster/squad -``` - -Show the `npx` output as Squad installs ΓÇö the `.github/agents/squad.agent.md` file drops in. That's it. One file. That's the entire starting point. - -Pause on the file tree for a beat. One folder, one file. This is the "before" shot. - -### Voiceover -> Empty folder. `git init`. One `npx` command. That's the setup ΓÇö that's all of it. Squad is a single agent definition that lives in `.github/agents/`. There's no code, no config, no boilerplate. When I open Copilot and talk to Squad, it's not going to write the code itself. It's going to build me a team that writes the code. - ---- - -## ACT 2 ΓÇö THE PROMPT (0:45ΓÇô1:30) - -### On Screen -Open Copilot CLI. Select Squad from the agent list. Paste the prompt: - -``` -Build a browser-based Snake game using vanilla HTML, CSS, and JavaScript. No frameworks. Requirements: -- Canvas-based rendering at 60fps -- Arrow key and WASD controls -- Score tracking with localStorage high scores -- Progressive speed increase every 5 points -- A retro CRT-style visual effect using CSS filters -- Mobile support via touch swipe controls -- Sound effects using the Web Audio API - -Start building immediately ΓÇö I want to play this in 20 minutes. -``` - -Hit enter. Watch Squad start working ΓÇö it identifies the project, proposes a team with cast names from a fictional universe, and asks for confirmation. - -### Voiceover -> I'm giving it a single prompt ΓÇö a retro Snake game with canvas rendering, CRT effects, sound, mobile touch controls. I didn't ask for a plan. I asked it to start building. Squad's first move is to figure out who it needs. - ---- - -## ACT 3 ΓÇö THE TEAM REVEAL (1:30ΓÇô2:30) - -### On Screen -Squad proposes the team. You'll see something like: - -``` -≡ƒÅù∩╕Å Dallas ΓÇö Lead Scope, decisions, architecture -ΓÜ¢∩╕Å Ripley ΓÇö Frontend Dev Canvas, rendering, game UI -≡ƒöº Kane ΓÇö Backend Dev Game logic, audio, input systems -≡ƒº¬ Lambert ΓÇö Tester Tests, edge cases, quality -≡ƒôï Scribe ΓÇö (silent) Memory, decisions, session logs -``` - -(Names will vary ΓÇö Squad picks from a fictional universe each time. The Alien universe is one of 14 options.) - -Say "yes" or just tell it to start. Squad creates the entire `.ai-team/` directory ΓÇö charters, routing, decisions file, casting registry, everything. - -### Voiceover -> Each team member gets a persistent identity ΓÇö a charter that defines what they own, how they think, and where their boundaries are. These names come from a fictional universe, picked deterministically based on the project shape. They're not decorative. They're persistent identifiers that follow the team across sessions. And notice Scribe at the bottom ΓÇö silent, always present. Scribe is on every team. It never talks to you, but it's doing critical work behind the scenes: logging every session, merging decisions, keeping the team's shared memory consistent. - ---- - -## ACT 4 ΓÇö THE BUILD BEGINS (2:30ΓÇô3:30) - -### On Screen -Squad launches all agents in parallel. You'll see the fan-out: - -``` -≡ƒÅù∩╕Å Dallas analyzing project structure... -ΓÜ¢∩╕Å Ripley building canvas renderer and CRT effects... -≡ƒöº Kane setting up game loop, input handling, audio... -≡ƒº¬ Lambert writing test cases from requirements... -≡ƒôï Scribe logging everything... -``` - -All background. All simultaneous. This is the moment to cut away. - -### Voiceover -> Here's what's happening: Squad didn't send one agent to work and wait for it to finish. It launched everyone at once ΓÇö as background agents. The lead is analyzing the architecture. The frontend dev is building the canvas renderer. The backend dev is wiring up game logic and audio. And the tester ΓÇö the tester is already writing test cases, right now, from the requirements alone, before any code exists. They'll adjust when the implementation lands. That's anticipatory work. It's not waiting. It's getting ahead. - ---- - -## ACT 5 ΓÇö THE README WALKTHROUGH (3:30ΓÇô5:30) - -### On Screen -While agents are building, switch to the Squad repo README (or the project's README if one was generated). Scroll slowly from the top. Hit these sections in order, pausing on each: - -1. **"What is Squad?"** ΓÇö linger on "It's not a chatbot wearing hats" -2. **"Agents Work in Parallel"** ΓÇö the fan-out diagram matches what's happening right now -3. **"Knowledge compounds across sessions"** ΓÇö the maturity table (First session ΓåÆ Mature project) -4. **"How It Works ΓÇö The Key Insight"** ΓÇö each agent gets its own context window -5. **"Context Window Budget"** ΓÇö the token table showing 94% left for actual work -6. **"Memory Architecture"** ΓÇö charter / history / decisions / log -7. **"What Gets Created"** ΓÇö the `.ai-team/` directory structure -8. **"Growing the Team"** ΓÇö adding and removing members -9. **"Reviewer Protocol"** ΓÇö agents can reject work - -### Voiceover (synced to what's on screen) - -**On "What is Squad?":** -> Squad gives you a team that persists. These agents aren't disposable ΓÇö they live in your repo as files. Charters, histories, shared decisions. Anyone who clones the repo gets the team, with everything it's learned. - -**On "Agents Work in Parallel":** -> This is exactly what's happening right now while I'm talking. Every agent that can usefully start work ΓÇö starts. No sequencing, no waiting. The coordinator's job is to launch aggressively and collect results later. - -**On "Knowledge compounds":** -> This is where it gets interesting over time. After a few sessions, the frontend dev knows your component library. The backend dev knows your auth strategy. The tester knows your edge case patterns. They stop asking questions they've already answered. That knowledge is stored in each agent's personal history file ΓÇö and it's append-only. It only grows. - -**On "Context Window Budget":** -> This is the design trick that makes it work. The coordinator is tiny ΓÇö about 1.5% of the context window. Even a veteran agent with weeks of accumulated knowledge only uses about 4%. That leaves 94% of the context window for actually reasoning about your code. Most agent frameworks burn half their context on identity and instructions. Squad doesn't. - -**On "Memory Architecture":** -> Four layers. The charter is who you are ΓÇö written once, never self-modified. History is what you've learned ΓÇö personal, append-only. Decisions are the shared brain ΓÇö every agent reads from the same file before starting work. And the log is Scribe's domain ΓÇö a searchable archive of every session. - -**On "Growing the Team":** -> The team isn't static. Need a DevOps person? Ask for one. They get cast from the same universe, seeded with all existing decisions, and they're immediately productive. Need to remove someone? They don't get deleted. They move to alumni. Their knowledge is preserved. If you need them back, they remember everything. - ---- - -## ACT 6 ΓÇö AGENTS COMPLETE (5:30ΓÇô6:30) - -### On Screen -Flip back to the Copilot CLI. The agents should be finishing. Squad collects results and shows you what each agent built: - -``` -ΓÜ¢∩╕Å Ripley ΓÇö Built canvas renderer with CRT scanline effect, game board, score display -≡ƒöº Kane ΓÇö Implemented game loop, snake movement, collision detection, Web Audio sounds -≡ƒº¬ Lambert ΓÇö Wrote 14 test cases covering movement, scoring, speed progression, edge wrapping -≡ƒÅù∩╕Å Dallas ΓÇö Defined project structure, documented architecture decisions -``` - -Show the `list_agents` output if there are still background agents running. This is the moment to show the parallel execution in action. - -### Voiceover -> While I was walking through the README, four agents were working simultaneously in background processes. Here's what came back. The frontend dev built the full canvas renderer with the CRT effect. The game logic agent wired up movement, collision, and audio. The tester wrote fourteen test cases ΓÇö from requirements ΓÇö before the code was even finished. And the lead documented the architecture. Meanwhile, Scribe ΓÇö silently ΓÇö logged everything and merged their decisions into the shared decisions file. - ---- - -## ACT 7 ΓÇö THE ARTIFACTS & SECOND WAVE (6:30ΓÇô7:30) - -### On Screen -Switch to an editor and open the files the agents just created. Show these in order, pausing on each: - -1. `.ai-team/decisions.md` ΓÇö scroll through real decisions the agents wrote during the build. Architecture choices, file structure, naming conventions. These aren't templates ΓÇö they're decisions made minutes ago. -2. One agent's `history.md` (e.g., `.ai-team/agents/ripley/history.md` or whatever name was cast) ΓÇö scroll through what it learned. Canvas setup, CRT filter values, rendering approach. This is persistent memory. -3. Back in Copilot, ask Squad to do a second pass: "Add a pause menu and a game-over screen." Watch it fan out again ΓÇö same agents, same names, but now they already know the codebase. The second wave launches faster because no one needs to rediscover the architecture. - -### Voiceover -> Now let's look at what they left behind ΓÇö and I don't mean the code. This is `decisions.md`. These are real architectural decisions the team made while building ΓÇö canvas dimensions, input handling strategy, audio approach. Every agent read this file before starting work, and every agent wrote back to it. It's the shared brain. -> -> And here ΓÇö this is Ripley's history file. Look at what it learned: the CRT filter values, the rendering pipeline, the sprite dimensions. Next session, Ripley won't ask about any of this. It remembers. -> -> Now watch this. I'm going to ask for a second feature ΓÇö a pause menu and game-over screen. Same team. Same names. But this time, they already know the codebase. They don't need to rediscover the architecture ΓÇö they read their own history files and the shared decisions before starting. That's the compounding effect in action. The second wave is faster because the first wave made the team smarter. - ---- - -## ACT 8 ΓÇö THE PAYOFF (7:30ΓÇô8:00) - -### On Screen -Open the Snake game in a browser. Play it. The CRT effect should be visible. Move the snake. Score some points. Let the speed increase kick in. If sound works, let it play. - -### Voiceover -> The team of agents Squad was able to build - a group of specialists coordinating through shared decisions and collaborating to convert a user's idea into reality in minutes? - - The team is in the repo now. Tomorrow, I can open Copilot, talk to the same agents by name, and they'll remember everything ΓÇö the canvas setup, the audio patterns, the CRT filter values. The more you use Squad, the less you have to explain. That's the whole idea. - ---- - -## KEY THEMES TO WEAVE IN (reference card) - -Use these as touchstones ΓÇö don't force them, but make sure each gets at least one mention: - -| Theme | Where it fits naturally | -|-------|----------------------| -| **Agents learn and persist** | Act 5 (knowledge compounds), Act 7 (history.md) | -| **Shared decisions** | Act 5 (memory architecture), Act 7 (decisions.md on screen) | -| **Scribe is on every team** | Act 3 (team reveal), Act 6 (silent logging) | -| **Team grows with the repo** | Act 5 (growing the team section) | -| **Background vs foreground agents** | Act 4 (all launched as background), Act 6 (list_agents) | -| **Parallel fan-out** | Act 4 (the launch), Act 7 (second wave) | -| **Context window efficiency** | Act 5 (token budget table) | -| **It's all in git** | Act 3 (commit this folder), Act 8 (closing line) | -| **Not a chatbot wearing hats** | Act 5 (opening line of "What is Squad?") | -| **Anticipatory work** | Act 4 (tester writing tests before code exists) | - ---- - -## RECORDING TIPS - -1. **Don't rush the prompt paste.** Let the viewer read it for a second before hitting enter. -2. **The README scroll is the heart of the video.** This is where you tell the story. Take your time. -3. **Show `list_agents` at least once** while agents are running ΓÇö it's the visual proof of parallelism. -4. **Open real files** (`decisions.md`, `history.md`, a charter) ΓÇö these are the artifacts that make Squad tangible, not abstract. -5. **End on the game.** The final shot should be the snake moving on screen with the CRT glow. That's your thumbnail. -6. **Voiceover tone:** Conversational, not scripted-sounding. You're showing someone something cool, not presenting to a board. Think "hey, look at this" energy. diff --git a/team-docs/human-evals/001-vscode-parity-smoke-test.md b/team-docs/human-evals/001-vscode-parity-smoke-test.md deleted file mode 100644 index ace1a9eec..000000000 --- a/team-docs/human-evals/001-vscode-parity-smoke-test.md +++ /dev/null @@ -1,683 +0,0 @@ ---- -title: "VS Code Parity Smoke Test" -version: "1.0" -date: 2026-02-08 -author: McManus (DevRel) -status: draft -estimated_time: "45–60 minutes" -prerequisites: - - VS Code with GitHub Copilot extension (latest) - - GitHub Copilot Chat enabled (agent mode available) - - Node.js 22+ - - Git installed - - Internet access (for npx) ---- - -# 001 — VS Code Parity Smoke Test - -**Purpose:** Validate that Squad works end-to-end in VS Code Copilot Chat with the same fidelity as the Copilot CLI. This is a QA eval — not a demo. Be honest. Mark failures. - -**Tester:** ______________________ -**Date run:** ______________________ -**VS Code version:** ______________________ -**Copilot extension version:** ______________________ -**OS:** ______________________ -**Node version:** ______________________ - ---- - -## Section 1: Setup — Fresh Install - -**Goal:** Verify `npx github:bradygaster/squad` installs correctly in a brand-new repo. - -### Steps - -1. Create a new empty directory and navigate into it: - ```bash - mkdir squad-eval-test && cd squad-eval-test - git init -b main - ``` -2. Run the installer: - ```bash - npx github:bradygaster/squad - ``` -3. Observe the terminal output. -4. Open the folder in VS Code: - ```bash - code . - ``` - -### Expected Result - -- Terminal shows green checkmarks for each file created: - - `✓ .github/agents/squad.agent.md (v0.x.x)` - - `✓ .ai-team-templates/` - - `✓ .ai-team/skills/ (starter skills)` - - `✓ .ai-team/ceremonies.md` - - `✓ .gitattributes (merge=union rules)` -- "Squad is ready." message with next steps printed. -- The following files and directories exist: - - `.github/agents/squad.agent.md` - - `.ai-team-templates/` (contains charter.md, history.md, roster.md, routing.md, skill.md, etc.) - - `.ai-team/decisions/inbox/` (empty dir) - - `.ai-team/orchestration-log/` (empty dir) - - `.ai-team/casting/` (empty dir) - - `.ai-team/skills/` (contains starter skills) - - `.ai-team/ceremonies.md` - - `.gitattributes` with `merge=union` rules - -### Verdict - -- [ ] Pass [ ] Fail - -**Notes:** _________________________________________________________________ - ---- - -## Section 2: Init Flow — Team Creation via VS Code Copilot Chat - -**Goal:** Verify the coordinator creates a full team when prompted in VS Code agent mode. - -### Steps - -1. Open Copilot Chat in VS Code (Ctrl+Shift+I or the sidebar icon). -2. Switch to **Agent mode** (not Ask or Edit mode — look for the mode selector at the top of the chat panel). -3. Select **Squad** from the agents list (type `@squad` or pick from the dropdown). -4. Type the following prompt and send: - ``` - I'm building a task management API with Express and PostgreSQL. Set up the team. - ``` -5. Wait for Squad to respond. It should: - - Identify you by your git config name - - Ask what you're building (or proceed if you already said) - - Propose a team with cast names from a fictional universe -6. Confirm the team by typing: - ``` - Yes, looks good. - ``` -7. Wait for Squad to create all files. - -### Expected Result - -- Squad addresses you by name (from `git config user.name`). -- Team proposed with 4–5 agents + Scribe: - - A Lead role - - A Backend Dev role - - At least one Frontend or API role - - A Tester role - - Scribe (always present, always named "Scribe") -- Cast names come from a recognizable fictional universe (Alien, The Usual Suspects, Ocean's Eleven, etc.) -- After confirmation, these files are created in `.ai-team/`: - - `team.md` (roster with all agents listed) - - `routing.md` (who handles what) - - `decisions.md` (initialized, may have first decision) - - `ceremonies.md` (already existed from install) - - `casting/registry.json` (agent-to-name mappings) - - `casting/policy.json` (casting config) - - `casting/history.json` (universe selection) - - `agents/{name}/charter.md` for each agent - - `agents/{name}/history.md` for each agent (seeded with project context) - - `agents/scribe/charter.md` -- `.gitattributes` has `merge=union` rules. -- Squad says something like "✅ Team hired. Try: '{AgentName}, set up the project structure'" - -### Verdict - -- [ ] Pass [ ] Fail - -**Notes:** _________________________________________________________________ - ---- - -## Section 3: Agent Spawning — Individual Agent Interaction - -**Goal:** Verify that addressing an agent by name spawns them in character. - -### Steps - -1. In the same Copilot Chat session (or a new one with Squad selected), type: - ``` - {LeadName}, what's your plan for the API architecture? - ``` - (Replace `{LeadName}` with the actual cast name from Section 2.) -2. Wait for the response. -3. Then try addressing the tester: - ``` - {TesterName}, what test framework should we use? - ``` -4. Wait for the response. - -### Expected Result - -- Each agent responds **in character** — using first person, referencing their expertise, staying within their domain. -- The Lead talks about architecture, scope, and decisions — NOT about writing tests. -- The Tester talks about test frameworks, coverage, quality — NOT about architecture decisions. -- Responses reference the project context (Express, PostgreSQL, task management API) — they know what the project is. -- The agent's history.md should be updated with learnings after the interaction. - -### Verdict - -- [ ] Pass [ ] Fail - -**Notes:** _________________________________________________________________ - ---- - -## Section 4: Multi-Agent Work — Parallel Fan-Out - -**Goal:** Verify that a "Team, do X" prompt spawns multiple agents in parallel. - -### Steps - -1. In Copilot Chat with Squad selected, type: - ``` - Team, set up the initial project structure — package.json, folder layout, database schema, and a health check endpoint. - ``` -2. Watch the response. Look for evidence of parallel agent launches. -3. After work completes, check: - - Were multiple agents mentioned as working? - - Did actual files get created in the repo? - - Were decisions written to `.ai-team/decisions.md`? - -### Expected Result - -- Squad fans out to multiple agents (Lead for structure, Backend for endpoints, Tester for test stubs — at minimum 2 agents). -- Evidence of parallel execution: multiple agents listed as working, or multiple tool calls spawning agents. -- Real files are created in the repo (package.json, folders, source files, etc.). -- `.ai-team/decisions.md` has new entries from this session. -- Agent `history.md` files are updated with what they learned. - -### Verdict - -- [ ] Pass [ ] Fail - -**Notes:** _________________________________________________________________ - ---- - -## Section 5: Scribe — Silent Logging and Decision Merging - -**Goal:** Verify Scribe operates silently, logs sessions, and merges decisions. - -### Steps - -1. After completing Section 4, check: - ``` - Does .ai-team/log/ contain any session log files? - ``` -2. Open `.ai-team/decisions.md` and review: - - Are there decisions from the multi-agent work? - - Do they have attribution (who made the decision)? -3. Check `.ai-team/decisions/inbox/`: - - Were there any drop-box files? (They may have been merged already.) -4. In Copilot Chat, type: - ``` - Where are we? What has the team decided so far? - ``` -5. Squad should summarize the current state using decisions.md. - -### Expected Result - -- Scribe **never talks to you directly** — no messages from "Scribe" in the chat. -- `.ai-team/log/` contains at least one session log file. -- `.ai-team/decisions.md` contains decisions with: - - Who made the decision - - What was decided - - Why -- "Where are we?" query returns a coherent summary of team state and decisions. - -### Verdict - -- [ ] Pass [ ] Fail - -**Notes:** _________________________________________________________________ - ---- - -## Section 6: Upgrade — Updating an Existing Installation - -**Goal:** Verify `npx github:bradygaster/squad upgrade` updates Squad-owned files without touching team state. - -### Steps - -1. Note the current contents of: - - `.ai-team/agents/` (team state) - - `.ai-team/decisions.md` (team decisions) - - `.ai-team/casting/registry.json` (casting state) -2. Run the upgrade command: - ```bash - npx github:bradygaster/squad upgrade - ``` -3. Verify the output. -4. Check that team state is untouched: - - `.ai-team/agents/` — same files, same content - - `.ai-team/decisions.md` — same content - - `.ai-team/casting/registry.json` — same content -5. Check that Squad-owned files were updated: - - `.github/agents/squad.agent.md` — version stamp updated - - `.ai-team-templates/` — overwritten with latest - -### Expected Result - -- Output shows `✓ upgraded coordinator from X.X.X to Y.Y.Y` (or "Already up to date"). -- Output shows `✓ upgraded .ai-team-templates/`. -- Output says `.ai-team/ untouched — your team state is safe`. -- **No changes** to any file inside `.ai-team/agents/`, `.ai-team/decisions.md`, or `.ai-team/casting/`. -- `.github/agents/squad.agent.md` has the new version in its YAML frontmatter. - -### Verdict - -- [ ] Pass [ ] Fail - -**Notes:** _________________________________________________________________ - ---- - -## Section 7: Export / Import - -**Goal:** Verify the export and import commands produce valid, usable snapshots. - -### Export - -### Steps - -1. Run: - ```bash - npx github:bradygaster/squad export - ``` -2. Check the output. -3. Open `squad-export.json` and inspect its structure. - -### Expected Result - -- Output: `✓ Exported squad to squad-export.json` -- Warning about reviewing agent histories before sharing. -- `squad-export.json` is valid JSON containing: - - `version: "1.0"` - - `exported_at` (ISO timestamp) - - `squad_version` (matches installed version) - - `casting` object (with registry, policy, history) - - `agents` object (keys are agent names, values have `charter` and `history`) - - `skills` array (contents of any SKILL.md files) - -### Verdict (Export) - -- [ ] Pass [ ] Fail - -### Import - -### Steps - -1. Create a new test directory: - ```bash - mkdir ../squad-import-test && cd ../squad-import-test - git init -b main - npx github:bradygaster/squad - ``` -2. Copy the export file: - ```bash - cp ../squad-eval-test/squad-export.json . - ``` -3. Run import (requires `--force` since a squad already exists): - ```bash - npx github:bradygaster/squad import squad-export.json --force - ``` -4. Verify the output and check `.ai-team/` contents. - -### Expected Result - -- Output shows the agent count, skills count, and universe name. -- Existing `.ai-team/` is archived to `.ai-team-archive-{timestamp}/`. -- New `.ai-team/` created with: - - Agent directories matching the export - - Casting state preserved - - Skills imported - - Agent histories have `📌 Imported from...` prefix - - `decisions.md` exists (may be empty — project-specific decisions are not carried over) - - `team.md` exists - -### Verdict (Import) - -- [ ] Pass [ ] Fail - -**Notes:** _________________________________________________________________ - ---- - -## Section 8: Skills — Creation and Persistence - -**Goal:** Verify that agents create skills during work and that skills persist across sessions. - -### Steps - -1. Switch back to the original test project: - ```bash - cd ../squad-eval-test - ``` -2. Open VS Code and Copilot Chat with Squad selected. -3. Ask the team to do substantial work that would produce a reusable pattern: - ``` - {BackendName}, build the CRUD endpoints for tasks — create, read, update, delete. Use Express Router and follow REST conventions. - ``` -4. After the work completes, check `.ai-team/skills/`: - ``` - ls .ai-team/skills/ - ``` -5. If skills were created, open a `SKILL.md` file and inspect its format. -6. Start a **new** Copilot Chat session (close and reopen chat). Ask: - ``` - {BackendName}, add a "projects" resource with the same CRUD pattern. - ``` -7. Check: does the agent reference or apply the skill from the previous session? - -### Expected Result - -- After substantial work, agents may create skills in `.ai-team/skills/{skill-name}/SKILL.md`. - - Note: Skill creation is not guaranteed on every interaction — it happens when an agent identifies a genuinely reusable pattern. -- If skills exist, `SKILL.md` files follow the template format (YAML frontmatter with `name`, `description`, `confidence`, etc.). -- In the new session, agents should read existing skills before starting work — you may see evidence of this in their approach. -- Starter skills from the initial install should still be present. - -### Verdict - -- [ ] Pass [ ] Fail - -**Notes:** _________________________________________________________________ - ---- - -## Section 9: Edge Cases - -**Goal:** Verify graceful handling of bad input, missing files, and unusual conditions. - -### Test 9a: Bad Input to CLI - -1. Run with an unknown command: - ```bash - npx github:bradygaster/squad foobar - ``` -2. Expected: Should not crash. May treat as default init or show an error. - -### Verdict (9a) - -- [ ] Pass [ ] Fail - -### Test 9b: Export with No Team - -1. In a new empty directory (with no `.ai-team/team.md`): - ```bash - mkdir ../squad-edge-test && cd ../squad-edge-test - git init -b main - npx github:bradygaster/squad export - ``` -2. Expected: `✗ No squad found — run init first` error message. - -### Verdict (9b) - -- [ ] Pass [ ] Fail - -### Test 9c: Import with Invalid JSON - -1. Create a file with invalid JSON: - ```bash - echo "not json" > bad-import.json - npx github:bradygaster/squad import bad-import.json - ``` -2. Expected: `✗ Invalid JSON in import file:` error message. - -### Verdict (9c) - -- [ ] Pass [ ] Fail - -### Test 9d: Import with Missing File - -1. Run: - ```bash - npx github:bradygaster/squad import nonexistent.json - ``` -2. Expected: `✗ Import file not found: nonexistent.json` error message. - -### Verdict (9d) - -- [ ] Pass [ ] Fail - -### Test 9e: Double Init (Idempotency) - -1. Go back to the eval project and run init again: - ```bash - cd ../squad-eval-test - npx github:bradygaster/squad - ``` -2. Expected: Existing files skipped with dim "already exists" messages. No data lost. No errors. - -### Verdict (9e) - -- [ ] Pass [ ] Fail - -### Test 9f: Addressing a Non-Existent Agent - -1. In Copilot Chat with Squad selected, type: - ``` - Gandalf, build me a login page. - ``` - (Use a name that is NOT on the team roster.) -2. Expected: Squad should either route the request to the correct agent, ask for clarification, or explain that no agent by that name exists. - -### Verdict (9f) - -- [ ] Pass [ ] Fail - -**Notes:** _________________________________________________________________ - ---- - -## Section 10: VS Code–Specific Behavior - -**Goal:** Verify VS Code integration points work correctly. - -### Test 10a: Agent Mode Availability - -1. Open VS Code with the test project. -2. Open Copilot Chat. -3. Switch to Agent mode. -4. Verify Squad appears in the agents list. - -### Expected Result - -- Squad is listed as an available agent. -- Selecting it shows the description from `squad.agent.md` frontmatter: "Your AI team. Describe what you're building, get a team of specialists that live in your repo." - -### Verdict (10a) - -- [ ] Pass [ ] Fail - -### Test 10b: File Operations - -1. Ask Squad to create or modify files: - ``` - {BackendName}, create a README.md for this project. - ``` -2. Verify the file appears in VS Code's explorer. -3. Verify the file can be opened, edited, and saved normally. - -### Expected Result - -- Agent creates files using VS Code's tool capabilities (edit/create tools). -- Files appear in the explorer immediately. -- No permission errors or path issues. - -### Verdict (10b) - -- [ ] Pass [ ] Fail - -### Test 10c: Terminal Integration - -1. Ask an agent to run a command: - ``` - {TesterName}, run the tests. - ``` -2. Check if terminal output is visible. - -### Expected Result - -- Agent can execute shell commands via VS Code's integrated terminal. -- Output is captured and reported back in the chat. -- No "tool not available" errors. - -### Verdict (10c) - -- [ ] Pass [ ] Fail - -### Test 10d: Multi-Session Persistence - -1. Close VS Code completely. -2. Reopen VS Code with the same project folder. -3. Open Copilot Chat, select Squad, and ask: - ``` - Where are we? What does the team know? - ``` - -### Expected Result - -- Squad recognizes the existing team (reads `.ai-team/team.md`). -- Enters Team Mode (not Init Mode). -- Summarizes decisions and current state from `.ai-team/decisions.md`. -- Agent names are consistent with previous session. - -### Verdict (10d) - -- [ ] Pass [ ] Fail - -### Test 10e: Tool Availability - -1. During any agent interaction, observe which tools agents use. -2. Note any "tool not available" errors. - -### Expected Result - -- Agents can use: `task` (for spawning), `powershell`/terminal, `view`, `edit`, `create`, `grep`, `glob`. -- No critical tools are missing compared to CLI. -- If any tools behave differently, note the specifics. - -### Verdict (10e) - -- [ ] Pass [ ] Fail - -**Notes:** _________________________________________________________________ - ---- - -## Results Summary - -| Section | Topic | Pass/Fail | -|---------|-------|-----------| -| 1 | Setup — Fresh Install | | -| 2 | Init Flow — Team Creation | | -| 3 | Agent Spawning — Individual Agents | | -| 4 | Multi-Agent Work — Parallel Fan-Out | | -| 5 | Scribe — Logging & Decisions | | -| 6 | Upgrade | | -| 7a | Export | | -| 7b | Import | | -| 8 | Skills | | -| 9a | Edge: Bad CLI input | | -| 9b | Edge: Export with no team | | -| 9c | Edge: Import invalid JSON | | -| 9d | Edge: Import missing file | | -| 9e | Edge: Double init | | -| 9f | Edge: Non-existent agent name | | -| 10a | VS Code: Agent mode available | | -| 10b | VS Code: File operations | | -| 10c | VS Code: Terminal integration | | -| 10d | VS Code: Multi-session persistence | | -| 10e | VS Code: Tool availability | | - -**Total Passed:** _____ / 20 -**Total Failed:** _____ / 20 - ---- - -## Tester Questionnaire - -Complete this section after running through the full eval. - -### 1. Overall Experience Rating - -How would you rate the overall Squad experience in VS Code? - -| 1 — Broken | 2 — Frustrating | 3 — Okay | 4 — Good | 5 — Excellent | -|:-:|:-:|:-:|:-:|:-:| -| [ ] | [ ] | [ ] | [ ] | [ ] | - -### 2. What was the most impressive thing? - -_____________________________________________________________________________ -_____________________________________________________________________________ -_____________________________________________________________________________ - -### 3. What felt broken or confusing? - -_____________________________________________________________________________ -_____________________________________________________________________________ -_____________________________________________________________________________ - -### 4. Would you use this? Why or why not? - -_____________________________________________________________________________ -_____________________________________________________________________________ -_____________________________________________________________________________ - -### 5. What's missing? - -_____________________________________________________________________________ -_____________________________________________________________________________ -_____________________________________________________________________________ - -### 6. Bugs or unexpected behavior? - -List any bugs, errors, or surprising behavior you encountered. Be specific — include what you typed, what you expected, and what actually happened. - -_____________________________________________________________________________ -_____________________________________________________________________________ -_____________________________________________________________________________ -_____________________________________________________________________________ -_____________________________________________________________________________ - -### 7. Net Promoter Score - -How likely are you to recommend Squad to a colleague? - -| 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | -|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:--:| -| [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | - -**Why did you give that score?** - -_____________________________________________________________________________ -_____________________________________________________________________________ - -### 8. CLI vs VS Code Parity - -Did you notice any differences between how Squad works in the CLI vs VS Code? - -_____________________________________________________________________________ -_____________________________________________________________________________ -_____________________________________________________________________________ - -### 9. Performance Notes - -How did response times feel? Were there any noticeably slow interactions? - -_____________________________________________________________________________ -_____________________________________________________________________________ - -### 10. One thing you'd change - -If you could change one thing about Squad, what would it be? - -_____________________________________________________________________________ -_____________________________________________________________________________ - ---- - -*Eval created by McManus (DevRel). Version 1.0. File: `team-docs/human-evals/001-vscode-parity-smoke-test.md`* diff --git a/team-docs/proposals/001-proposal-first-workflow.md b/team-docs/proposals/001-proposal-first-workflow.md deleted file mode 100644 index 4facfcf89..000000000 --- a/team-docs/proposals/001-proposal-first-workflow.md +++ /dev/null @@ -1,182 +0,0 @@ -# Proposal 001: Proposal-First Workflow - -**Status:** Approved ✅ Shipped -**Authored by:** Keaton + Verbal -**Date:** 2026-02-07 -**Requested by:** bradygaster - ---- - -## Summary - -Everything meaningful gets written down and reviewed before execution. No drive-by features, no surprise refactors. If it changes the product, the team sees it first. - ---- - -## Problem - -Squad's advantage is compound decisions — each feature makes the next easier. But that only works if decisions are visible, reviewed, and remembered. Ad-hoc changes create drift. Proposals create alignment. - ---- - -## What Requires a Proposal - -**Write a proposal for:** - -- **New features** — user-facing capabilities that didn't exist before -- **Architecture changes** — patterns that affect multiple agents or core orchestration -- **Major refactors** — restructuring that touches >3 files or changes public APIs -- **Agent design shifts** — new agent types, charter templates, orchestration patterns -- **Messaging overhauls** — changes to how Squad presents itself (README, templates, error messages) -- **Breaking changes** — anything that requires users to migrate or adapt - -**Rule of thumb:** If you'd want to know about it before merge, it needs a proposal. - ---- - -## What Doesn't Require a Proposal - -**Just do it:** - -- Bug fixes (obvious, localized, no behavior change) -- Minor polish (typos, formatting, comment clarity) -- Test additions (no production code change) -- Documentation updates (unless they reflect a policy shift) -- Dependency updates (security patches, minor bumps) - -**Rule of thumb:** If it's obviously right and reversible, skip the proposal. - ---- - -## Proposal Format - -**Location:** `docs/proposals/{number}-{slug}.md` - -Numbering is sequential: `001-`, `002-`, etc. Slug is kebab-case (e.g., `001-proposal-first-workflow.md`). - -**Required sections:** - -```markdown -# Proposal {number}: {Title} - -**Status:** Proposed | Approved | Cancelled | Superseded -**Authored by:** {Agent name(s) or human} -**Date:** YYYY-MM-DD -**Requested by:** {Human who asked for this} - ---- - -## Summary -One paragraph. What is this? - ---- - -## Problem -What motivated this? What breaks without it? - ---- - -## Solution -How does it work? Be specific. Code samples if needed. - ---- - -## Trade-offs -What do we give up? What gets harder? - ---- - -## Alternatives Considered -What else did we think about? Why not those? - ---- - -## Success Criteria -How do we know this worked? -``` - -**Optional sections:** Implementation Plan, Migration Path, Examples - ---- - -## Review Process - -### Who Reviews - -- **Keaton** — architectural and product implications -- **Verbal** — agent experience and AI strategy -- **Domain specialist** — whoever owns the affected area (McManus for messaging, Fenster for runtime, Hockney for testing) -- **bradygaster** — always the final sign-off - -### How Sign-Off Works - -1. Author writes proposal, files PR (or commits directly to `main` with `Status: Proposed`) -2. Coordinator spawns reviewers based on domain -3. Reviewers comment directly in the proposal file or via PR comments -4. Author revises until reviewers approve -5. Brady gives final approval — changes status to `Approved` -6. Execution begins (agents reference the proposal during implementation) - -**Review timeline:** Proposals should resolve within 48 hours of submission. If stuck, Brady decides. - ---- - -## Evolution and Cancellation - -### Refining a Proposal - -- **Before approval:** Edit the proposal directly. Track major changes in a `## Revisions` section at the bottom. -- **After approval:** If execution reveals a flaw, file an amendment as a new proposal that references the original (e.g., `005-amend-parallel-spawning.md`). - -### Cancelling a Proposal - -Change status to `Cancelled`, add a `## Cancellation Reason` section explaining why. Keep the file — cancelled proposals are learning artifacts. - -### Superseding a Proposal - -If a new proposal makes an old one obsolete, change the old one's status to `Superseded by {number}`. - ---- - -## Trade-offs - -**What we gain:** -- Decisions are visible and reviewed before execution -- Team (human + agent) stays aligned on direction -- Historical record of why choices were made - -**What we give up:** -- Speed on small changes (though "no proposal needed" covers most of these) -- Spontaneity — can't just ship a feature on instinct - -**Why it's worth it:** Squad's mission is to beat the industry to what customers need next. That requires compound decisions. Proposals ensure each decision builds on the last. - ---- - -## Alternatives Considered - -**Option 1: Decision log only (no proposals)** -Write decisions after the fact. Faster, but loses review step. Decisions become historical record, not alignment tool. - -**Option 2: Proposals for everything** -Even bug fixes need proposals. Too slow. Creates friction where none is needed. - -**Option 3: Proposals only for humans** -Agents skip the process. Breaks alignment — agents make architectural decisions, too. They need the same discipline. - -**Why this approach:** Balances speed (skip proposals for obvious work) with alignment (require proposals for meaningful change). - ---- - -## Success Criteria - -- Every feature added to Squad in the next 6 weeks has a proposal -- No "surprise" architectural changes — reviewers see them before merge -- Cancelled proposals exist — proves the process filters bad ideas -- Agents reference proposals during implementation (visible in session logs) - ---- - -## Revisions - -None yet. diff --git a/team-docs/proposals/001a-proposal-lifecycle-amendment.md b/team-docs/proposals/001a-proposal-lifecycle-amendment.md deleted file mode 100644 index 5eba5a5a6..000000000 --- a/team-docs/proposals/001a-proposal-lifecycle-amendment.md +++ /dev/null @@ -1,76 +0,0 @@ -# Proposal 001a: Proposal Lifecycle Amendment - -**Status:** Approved ✅ Shipped -**Authored by:** Keaton (Lead) -**Date:** 2026-02-09 -**Requested by:** bradygaster -**Amends:** Proposal 001 (Proposal-First Workflow) -**Approved by:** bradygaster (2026-02-08) - ---- - -## Problem - -Proposal 001 defines four statuses: `Proposed | Approved | Cancelled | Superseded`. We have 16 proposals. All say `Proposed`. We can't tell what's being worked on, what shipped, or what's blocked. Brady asked if we have lifecycle tracking — we don't. - -The gap: there's no state between "approved" and "done." A proposal can sit at `Approved` for weeks with no visibility into whether anyone's touched it. - ---- - -## Amendment - -Replace the status line in the Proposal Format (Proposal 001, line 62) with: - -```markdown -**Status:** Proposed | Approved | In Progress | Completed | Cancelled | Superseded -``` - -### Status Definitions - -| Status | Meaning | Who sets it | -|--------|---------|-------------| -| **Proposed** | Written, awaiting review | Author | -| **Approved** | Reviewed and accepted. Ready for implementation | Brady (final sign-off) | -| **In Progress** | Implementation has started. Work is active | Implementing agent or Keaton | -| **Completed** | Shipped. Success criteria met or explicitly closed | Keaton or Brady | -| **Cancelled** | Rejected or abandoned. Keep file as learning artifact | Reviewer or Brady | -| **Superseded** | Replaced by a newer proposal. Note which one: `Superseded by {number}` | Author of replacement | - -### Rules - -1. **Proposals move forward, not backward.** `Completed` → `Proposed` doesn't happen. If a completed proposal needs rework, file a new proposal. -2. **`In Progress` requires an owner.** Add `**Implementing:** {agent name(s)}` below the status line when moving to In Progress. -3. **`Completed` requires evidence.** At minimum, link to the commit, PR, or file change that shipped it. Add a `## Completion Notes` section at the bottom. -4. **Bulk status update.** After this amendment is approved, Keaton will audit all 16 proposals and set accurate statuses. Most are still `Proposed` — that's fine, it just means they haven't been approved yet. - -### Optional Fields (add when moving to In Progress) - -```markdown -**Implementing:** {Agent name(s)} -**Started:** YYYY-MM-DD -**Completed:** YYYY-MM-DD -``` - ---- - -## What This Doesn't Do - -- No Jira. No sprint boards. No velocity tracking. Status lives in the proposal file itself. -- No automatic status transitions. Agents and humans update status as part of their work. -- No new approval gates. `In Progress` doesn't need approval — if it's `Approved`, anyone assigned can start. - ---- - -## Trade-offs - -**What we gain:** Visibility. Brady can `grep -l "In Progress" docs/proposals/` and see what's active. The team can see what shipped. - -**What we give up:** ~2 minutes per proposal to update status. Worth it. - ---- - -## Success Criteria - -- Every proposal has an accurate status within 48 hours of this amendment's approval -- New proposals use the full lifecycle going forward -- Brady can answer "what's in progress?" without asking the team diff --git a/team-docs/proposals/002-messaging-overhaul.md b/team-docs/proposals/002-messaging-overhaul.md deleted file mode 100644 index 88aa48706..000000000 --- a/team-docs/proposals/002-messaging-overhaul.md +++ /dev/null @@ -1,324 +0,0 @@ -# Proposal 002: Messaging Overhaul — "Throw a Squad at It" - -**Status:** Approved ✅ Shipped -**Authors:** McManus (DevRel) + Verbal (Prompt Engineer) -**Date:** 2026-02-07 -**Context:** Brady greenlit complete messaging overhaul. Cultural hook: "throw a squad at it" (internal lingo at his company for spinning up teams to solve important problems). - ---- - -## The Problem - -Squad's current messaging is *functional* but not *magnetic*. We explain what it is and how it works, but we don't grab devs by the collar and make them feel the need. The README has good bones — tight Quick Start, real context math, personality ("not a chatbot wearing hats") — but it's missing: - -1. **A punchline.** We need a tagline that lands before they scroll. -2. **Value prop clarity.** "Why Squad?" isn't answered — we show architecture before emotion. -3. **Casting as a feature.** It's mentioned once as "persistent thematic cast." That's a crime. Casting is what makes Squad feel alive. -4. **Polish gaps.** Examples use Go (Brady wants them gone). Sample prompts doc is hidden. Install output is silent. - -This proposal fixes all of it. McManus polish meets Verbal edge. - ---- - -## 1. New Tagline / Headline - -### Current (README line 3): -```markdown -**AI agent teams for any project.** A team that grows with your code. -``` - -### Proposed: -```markdown -**Throw a squad at it.** - -AI agent teams that live in your repo. Describe what you're building. Get specialists — frontend, backend, tester, lead — that persist across sessions, share decisions, and get smarter the more you use them. -``` - -**Rationale:** -- Opens with the cultural hook Brady requested — "throw a squad at it" is memorable, actionable, opinionated. -- Drops "grows with your code" (abstract) for "get smarter the more you use them" (concrete). -- Keeps core value props (persistent, specialists, decision-sharing) in the first 30 words. - -**Verbal's take:** This is the kind of phrasing that devs *repeat*. "Just throw a squad at it" becomes shorthand for the entire product. It's confident, not apologetic. It's the kind of thing that spreads. - -**McManus's take:** First impression is everything. "Throw a squad at it" tells devs exactly what this does — and makes them want it — before they even know the mechanics. - ---- - -## 2. README Structure Changes - -### Current flow: -1. What is Squad? -2. Quick Start -3. Agents Work in Parallel -4. How It Works (architecture) -5. What Gets Created -6. Growing the Team -7. Reviewer Protocol - -### Proposed flow: - -#### **A. Hero section** (above the fold) -- New tagline -- Single sentence: "It's not a chatbot wearing hats — it's a team." -- 2-minute demo GIF/video (to be created) showing parallel agent execution - -#### **B. Quick Start** (unchanged, 3 steps) -Keep this tight. It works. - -#### **C. Why Squad? (NEW SECTION)** -Positioned immediately after Quick Start. Emotional case before technical case. - -```markdown -## Why Squad? - -**Traditional AI agents are chatbots pretending to be teams.** One model, one context, wearing different hats. You ask for backend work, it answers as "Backend Bot." You ask for tests, it answers as "Tester Bot." It's the same agent, roleplaying. - -**Squad is different.** Each team member runs in its own context window, reads only its own knowledge, and persists across sessions. When you ask Squad to build a login page: -- The Lead analyzes requirements -- The Frontend builds the UI -- The Backend sets up auth endpoints -- The Tester writes test cases from the spec - -**All at once. In parallel. For real.** - -Each agent writes what it learned to its own `history.md`. Team-wide decisions go to `decisions.md`. Knowledge compounds. After a few sessions, your team stops asking questions they've already answered. - -And it's all in git. Clone the repo → get the team → with all their accumulated knowledge. - -**TL;DR:** Squad is what you wish your last AI agent could do. But actually. -``` - -**Rationale:** -- Frames Squad against the default (single-agent roleplaying), which every dev has tried and been frustrated by. -- Shows parallel execution immediately after the hook, reinforcing the tagline. -- Ends with the knowledge persistence angle (competitive moat). -- Voice is confident, direct, slightly aggressive. No apologies. - -#### **D. Agents Work in Parallel** (polish pass) -Current version is good. Add one line at the top: - -```markdown -Squad doesn't work on a human schedule. It works on a "throw everything at the problem and catch up when you're ready" schedule. -``` - -#### **E. How It Works** (unchanged) -Architecture explanation stays. Mermaid diagram is solid. Context budget table is gold. - -#### **F. Casting System (NEW SECTION — elevated from buried mention)** -Insert after "How It Works," before "What Gets Created." - -```markdown -## The Cast System — Agents with Identity - -Squad doesn't call your backend developer `Backend_Agent_7829`. It gives them a name. A persistent name. From a thematic universe. - -When you initialize a team, Squad picks a universe (The Usual Suspects, Ocean's Eleven, Alien, etc.) and casts roles: -- **Keaton** (The Usual Suspects) → Lead -- **Verbal** → Prompt Engineer -- **McManus** → DevRel -- **Fenster** → Core Dev -- **Hockney** → Tester - -Names persist. Stored in `.ai-team/casting/registry.json`. If you clone the repo, you get the same cast. If Keaton made a decision 3 months ago, it's still Keaton. Not "the Lead agent" or "Agent A." **Keaton.** - -**Why it matters:** -- Agents feel real. "McManus wrote the docs" is memorable. "Documentation Agent" is not. -- You can reference past work naturally: "Keaton, what did you decide about auth last week?" -- Your team has personality. Not just functionality. - -**Cultural fit:** Squad's core team (the one building Squad itself) is cast from *The Usual Suspects*. We eat our own dog food. If it's good enough for us, it's good enough for your project. -``` - -**Rationale:** -- Casting is Squad's secret weapon. Burying it is criminal. -- Frames casting as an identity feature, not a cosmetic Easter egg. -- Uses Squad's own team as social proof ("we use it ourselves"). -- Positions casting as part of the "agents feel alive" philosophy. - -#### **G. What Gets Created** (unchanged) -File tree is clear. Keep it. - -#### **H. Growing the Team** (unchanged) -Alumni archive explanation is good. Keep it. - -#### **I. Reviewer Protocol** (unchanged) -Keep as-is. This is a real differentiator (no self-review of rejected work). - -#### **J. Install** (unchanged, but link to troubleshooting) - -#### **K. Troubleshooting (NEW SECTION)** -Add before "Status." - -```markdown -## Troubleshooting - -**Squad agent doesn't appear in `/agents` list?** -- Restart Copilot CLI: `exit` then `copilot` again. -- Verify `.github/agents/squad.agent.md` exists. -- Check GitHub Copilot CLI version: `copilot --version` (requires 1.220.0+). - -**Team isn't spawning?** -- Check `.ai-team/team.md` exists. If not, say: "Initialize the team." -- Verify `.ai-team/decisions.md` exists (Squad needs shared memory). - -**Agents aren't learning across sessions?** -- Commit `.ai-team/` to git. If it's in `.gitignore`, agents can't persist. -``` - -**Rationale:** -- First-time setup pain is silent. Troubleshooting section reduces "it doesn't work" drop-off. - ---- - -## 3. Example Updates - -### Current state: -- `docs/sample-prompts.md` has 16 examples. One uses Go (SaaS backend modernization). - -### Brady's constraints: -- "No Go examples." -- "Don't touch the modernization exercise — it's well-positioned." - -### Proposed changes: - -#### **A. Replace Go example** -Current example: "SaaS Backend Modernization (Node.js → Go)" - -**Option 1 (Recommended):** Replace with **Python → Node.js modernization** -```markdown -### SaaS Backend Modernization (Python → Node.js) -I'm modernizing a SaaS backend. The current stack is Python/Flask. -I want to move to Node.js/Express with TypeScript. Set up the team -and create a migration plan with backward compatibility. -``` - -**Option 2:** Replace with **Java → Kotlin modernization** (if Brady's team is JVM-heavy) - -**Rationale:** -- Python/Node and Java/Kotlin are more common enterprise migration paths than Go. -- Keeps "modernization" framing (Brady wants this preserved). -- Still demonstrates Squad's value for large refactors. - -#### **B. Link `sample-prompts.md` from README** -Add after Quick Start section: - -```markdown -**Not sure where to start?** See [16 ready-to-use prompts](docs/sample-prompts.md) — from pomodoro timers to .NET migrations. -``` - -**Rationale:** -- Sample prompts are high-value onboarding content. They're hidden. -- Linking them from README increases conversion ("I can see myself using this for X"). - ---- - -## 4. "Why Squad?" Section - -See Section 2C above. Key elements: -- Frames Squad against single-agent roleplaying (the default experience) -- Emphasizes parallel execution (competitive differentiator) -- Highlights knowledge persistence (moat) -- Voice is confident, direct, slightly edgy - ---- - -## 5. Casting System Elevation - -See Section 2F above. Key elements: -- Positioned as a headline feature, not a footnote -- Explains the mechanic (persistent names from thematic universes) -- Shows social proof (Squad's own team uses it) -- Frames casting as part of "agents feel alive" philosophy - ---- - -## Implementation Plan - -### Phase 1: Core Messaging (McManus + Verbal) -1. Update README with new tagline, "Why Squad?", Casting section -2. Add Troubleshooting section -3. Replace Go example in `sample-prompts.md` -4. Link sample prompts from README - -**Estimated effort:** 2-3 hours -**Blocker:** None -**Reviewer:** Keaton (final approval on messaging changes) - -### Phase 2: Visual Assets (McManus) -1. Record 2-minute demo GIF showing parallel execution -2. Embed in README hero section - -**Estimated effort:** 4-6 hours (includes scripting, recording, editing) -**Blocker:** Needs production-ready Squad setup -**Reviewer:** Verbal (agent experience must feel magical) - -### Phase 3: Install Output Visibility (Fenster) -1. Update `index.js` to explain what gets created during install -2. Add post-install message with next steps - -**Estimated effort:** 1-2 hours -**Blocker:** None -**Reviewer:** McManus (DevEx polish) - ---- - -## Success Metrics - -**Qualitative:** -- Devs repeat "throw a squad at it" in conversations (meme-ability test) -- First-time users reference casting by name ("Keaton decided X") within first session -- README feels *magnetic*, not just informative - -**Quantitative:** -- Time-to-first-spawn drops (fewer "how do I start?" questions) -- Sample prompts link click-through rate (track via GitHub Insights) -- Troubleshooting section reduces "it doesn't work" issues (anecdotal, via GitHub Issues) - ---- - -## Open Questions - -1. **Demo video format:** GIF (README-embeddable, silent) or YouTube link (narrated, higher fidelity)? - - McManus leans GIF (fewer clicks to value) - - Verbal leans YouTube (can show more advanced patterns) - -2. **Casting universe selection:** Should users pick their universe, or does Squad auto-select? - - Current: Squad auto-selects based on project vibe - - Proposal: Keep auto-select as default, allow override via `squad config --universe oceans-eleven` - -3. **"Why Squad?" tone:** Too aggressive? - - Current draft: "Traditional AI agents are chatbots pretending to be teams." - - Softer alternative: "Most AI agents simulate collaboration. Squad delivers it." - - **Recommendation:** Keep aggressive. Squad's brand is confident, not apologetic. - ---- - -## Appendix: Voice & Tone Guidance - -This overhaul establishes Squad's voice more explicitly. For future messaging: - -### Do: -- Be direct. No hedging ("might," "potentially," "could be useful"). -- Show, don't abstract. "Keaton decided X" beats "the Lead agent made a decision." -- Use confidence. "Squad is what you wish your last AI agent could do. But actually." -- Embrace personality. Casting isn't a gimmick. It's a feature. - -### Don't: -- Apologize for being experimental. Frame it as "ahead of the curve." -- Compare to GitHub Copilot Chat directly. (They're complementary, not competitive.) -- Use corporate-safe hedging. "Best-in-class," "innovative solution," "paradigm shift" — all banned. - -**If it sounds like something a B2B landing page would say, rewrite it.** - ---- - -## Endorsements - -**McManus:** This is the polish Squad needed from day one. Casting elevation alone is a 10x messaging win. The "Why Squad?" section answers the question I've been asking since I read the README. Ship it. - -**Verbal:** "Throw a squad at it" is the kind of phrasing that makes Squad feel inevitable. Casting as a feature (not an Easter egg) is the right move. The industry will copy this in 6 months. We should be there first. Let's go. - ---- - -**Next step:** Keaton approval → Implementation → Ship. diff --git a/team-docs/proposals/003-copilot-platform-optimization.md b/team-docs/proposals/003-copilot-platform-optimization.md deleted file mode 100644 index 1edcf40d4..000000000 --- a/team-docs/proposals/003-copilot-platform-optimization.md +++ /dev/null @@ -1,429 +0,0 @@ -# Proposal 003: Copilot Platform Optimization - -**Author:** Kujan (Copilot SDK Expert) -**Date:** 2026-02-07 -**Status:** Approved — Deferred to Horizon - ---- - -## Executive Summary - -Squad is **well-positioned** for the Copilot platform. Our architecture — spawning agents via the `task` tool, using filesystem-backed memory, parallel execution — already exploits core Copilot capabilities. But we're missing opportunities in **predictive work**, **speculative execution**, and **agent-to-agent handoffs** that would make Squad a flagship demonstration of what Copilot can do. - -This proposal identifies three optimization categories: -1. **Already working well** — keep doing these -2. **Friction points** — where we fight the platform unnecessarily -3. **Missed opportunities** — Copilot features we're not leveraging - -**Recommendation:** Stay independent (not a Copilot SDK product) but become the **best-in-class example** of building on Copilot. Optimize around the platform, not into it. - ---- - -## 1. Current State: How Squad Uses Copilot Today - -### ✅ What We're Doing Right - -Squad already exploits several Copilot platform strengths: - -#### **Agent Spawning via `task` Tool** -```markdown -agent_type: "general-purpose" -mode: "background" -description: "Ripley: Design REST API endpoints" -prompt: | - You are Ripley, the Backend Dev on this project. - YOUR CHARTER: {inlined charter.md} - ... -``` - -**Why this works:** Each agent gets its own context window. The coordinator stays lean (~1.9K tokens). Agents scale independently. This is the *right* pattern for Copilot. - -#### **Filesystem-Backed Memory** -- `decisions.md` — shared brain, all agents read -- `history.md` — per-agent learnings, append-only -- `log/` — session archive, searchable - -**Why this works:** Copilot agents have full filesystem access. Squad leverages this instead of inventing a custom memory API. Knowledge persists across sessions and survives git clone. No cloud dependency. - -#### **Parallel Execution (Background Mode)** -```javascript -// Coordinator spawns 4 agents simultaneously -task(agent_type: "general-purpose", mode: "background", ...) -task(agent_type: "general-purpose", mode: "background", ...) -task(agent_type: "general-purpose", mode: "background", ...) -task(agent_type: "general-purpose", mode: "background", ...) -``` - -**Why this works:** Copilot's `task` tool supports `mode: "background"`. Squad defaults to this and chains follow-ups immediately. Pipeline stays full. - -#### **Drop-Box Pattern for Concurrent Writes** -``` -.ai-team/decisions/inbox/ -├── ripley-auth-choice.md -├── dallas-api-design.md -└── parker-test-strategy.md -``` - -Scribe merges to canonical `decisions.md`. No file conflicts. - -**Why this works:** Avoids the classic shared-file race condition. Agents can write decisions simultaneously without waiting for locks. - ---- - -## 2. Friction Points: Where We Fight the Platform - -### ❌ **Inline Charter Pattern** - -**Current:** Coordinator reads each agent's `charter.md` and pastes it into the spawn prompt. - -```javascript -// Coordinator does this: -1. view(.ai-team/agents/ripley/charter.md) -2. Copy contents -3. Paste into prompt string -4. Call task(..., prompt: "YOUR CHARTER:\n{pasted_contents}\n...") -``` - -**Why this is friction:** -- Adds a tool call to every spawn (slows launch) -- Coordinator context grows with charter size -- If charters evolve, we're copy-pasting updated text - -**Platform feature we're ignoring:** Copilot agents can read files at spawn time via the `view` tool. The agent should read its own charter. - -**Fix:** -```javascript -// Better: Agent reads its own charter -prompt: | - You are Ripley, the Backend Dev on this project. - - Read .ai-team/agents/ripley/charter.md — this is your identity and role. - Read .ai-team/agents/ripley/history.md — this is what you know about the project. - Read .ai-team/decisions.md — these are team decisions you must respect. - - **Requested by:** {current_user} - INPUT ARTIFACTS (authorized to read): - - {file paths} - - {message} -``` - -**Impact:** Faster spawns, smaller coordinator context, agents own their identity files. - ---- - -### ❌ **Scribe Always Spawned After Work** - -**Current:** After every batch of agents complete, Squad spawns Scribe to merge decisions and log the session. - -**Why this is friction:** -- Scribe waits for *all* agents to finish before starting -- Decisions sit in the inbox until Scribe runs -- Session log is retroactive, not live - -**Copilot feature we're ignoring:** Background agents run concurrently. Scribe could run *during* the work. - -**Fix:** Spawn Scribe **with the work agents**, not after. - -```javascript -// Current (serial) -spawn(frontend, backend, tester) → wait → spawn(scribe) - -// Better (parallel) -spawn(frontend, backend, tester, scribe) → all run together -``` - -Scribe watches the inbox, merges decisions as they arrive, logs in real-time. - -**Impact:** Decisions propagate faster. Session log is live. One fewer round-trip. - ---- - -### ❌ **No Speculative Agents** - -**Current:** Squad spawns agents only when confident they're needed. - -Example: User says "Add OAuth support." -- Squad spawns Lead (architecture decision) -- *Waits* for Lead to finish -- *Then* spawns Backend (implementation) - -**Why this is friction:** The tester agent *knows* OAuth will need test cases. But they wait. The docs agent *knows* OAuth needs API docs. But they wait. - -**Copilot feature we're ignoring:** Background agents are cheap. Failed speculative work costs little. - -**Fix:** Spawn tester + docs agent immediately, even before architecture decision. - -```javascript -// Current -Turn 1: spawn(lead, mode: "sync") -Turn 2 (after lead): spawn(backend, frontend) - -// Better — speculative execution -Turn 1: spawn(lead, mode: "sync") + spawn(tester, mode: "background") + spawn(docs, mode: "background") -// Tester writes OAuth test scenarios from known OAuth flows -// Docs agent drafts OAuth endpoint docs from RFC patterns -// Even if Lead changes the approach, 70% of the work is reusable -``` - -**Impact:** More aggressive parallelism. Less idle time. Demonstrates Copilot's async power. - ---- - -## 3. Opportunities: Copilot Features We're Not Leveraging - -### 🎯 **Predictive Agent Spawning** - -**What Squad does now:** Reacts to explicit user requests. - -**What Copilot enables:** Coordinator can predict next steps and launch agents proactively. - -**Example:** - -``` -User: "The login form is done." - -Current Squad response: -✓ Logged by Scribe - -Better Squad response: -✓ Logged by Scribe -🧪 Hockney (Tester): I wrote integration tests for the login flow (proactive) -📚 (Docs agent): I updated the authentication guide (proactive) -``` - -**How:** After any completion, Coordinator asks: "What's obviously next?" and spawns those agents in background mode without waiting for user confirmation. - -**Risk:** Low. Users can ignore proactive work if not needed. But most of the time, it's exactly what they'd ask for next. - ---- - -### 🎯 **Agent-to-Agent Handoffs** - -**What Squad does now:** Agents complete, return to Coordinator, Coordinator decides next steps. - -**What Copilot enables:** Agents can spawn other agents directly using the `task` tool. - -**Example:** - -```javascript -// Current flow (3 turns) -User → Coordinator → Agent A → Coordinator → Agent B - -// Possible with Copilot (2 turns) -User → Coordinator → Agent A → Agent B - ↳ spawns -``` - -An agent finishes work, sees a gap, spawns the right agent to fill it — no round-trip to Coordinator. - -**Use case:** -- Backend agent finishes API endpoint, spawns Tester directly: "Write integration tests for POST /api/auth/login" -- Frontend agent encounters a design ambiguity, spawns Designer directly: "Specify button states for the submit action" - -**Constraint:** Only senior agents (Lead, domain specialists) should have spawn authority. Don't let every agent spawn freely or we get recursion chaos. - -**Implementation:** -1. Add `"spawn_authority": true` to charters for Lead, Backend, Frontend roles -2. In their charter: "If you complete work and identify an obvious follow-up task, you may spawn another agent using the `task` tool. Always set `mode: 'background'`. Always notify the Coordinator by writing to `.ai-team/orchestration-log/`." - -**Impact:** Faster chaining. Demonstrates true multi-agent autonomy. - ---- - -### 🎯 **Context Pre-Loading** - -**What Squad does now:** Agents read `history.md` and `decisions.md` at spawn time (two `view` tool calls per agent). - -**What Copilot enables:** Coordinator could pre-read these files *once* and inject them into spawn prompts for all agents in a batch. - -**Example:** - -```javascript -// Current (each agent reads independently) -Agent A: view(history.md) + view(decisions.md) -Agent B: view(history.md) + view(decisions.md) -Agent C: view(history.md) + view(decisions.md) -→ 6 tool calls total - -// Optimized (Coordinator reads once, injects) -Coordinator: view(history.md) + view(decisions.md) → injects into all spawn prompts -Agent A, B, C: spawn with context pre-loaded -→ 2 tool calls total + 3 spawns -``` - -**Trade-off:** Larger spawn prompts, but fewer tool calls and faster agent startup. - -**When to use:** For batch spawns (3+ agents at once). Not worth it for single agent spawns. - ---- - -### 🎯 **Richer Spawn Descriptions** - -**What Squad does now:** -```javascript -description: "Ripley: Design REST API endpoints" -``` - -**What Copilot UI could show:** Progress indicators, estimated scope, dependency chains. - -**Opportunity:** The `description` parameter is what users see in the UI. Squad could make this more informative: - -```javascript -description: "Ripley: Design REST API endpoints (blocking Parker's tests)" -description: "Dallas: Review architecture (needs approval before impl)" -description: "Parker: Write OAuth test cases (speculative, may need revision)" -``` - -Users get better visibility into what's happening and why. - ---- - -## 4. SDK Assessment: Should Squad Become a Copilot SDK Product? - -### **Short answer: No. Not yet.** - -Here's why: - -#### **What the Copilot SDK Would Give Us** -1. **Formalized agent lifecycle hooks** (onSpawn, onComplete, onError) -2. **Built-in memory primitives** (SDK-managed state, not filesystem) -3. **Agent discovery/registry** (programmatic roster management) -4. **Streaming responses** (real-time agent output to user) - -#### **What We'd Lose** -1. **Filesystem-backed memory** — our killer feature. Everything is git-cloneable, human-readable, debuggable. -2. **Independence** — we can evolve faster than the SDK. If the SDK changes, we're not blocked. -3. **Transparency** — users see exactly how Squad works (it's just markdown files and task spawns). SDK abstracts this away. - -#### **The Right Path: Stay Independent, Optimize Around Copilot** - -Squad should be the **best example** of what you can build *on* Copilot without being *of* Copilot. That means: - -- ✅ Use every Copilot feature that makes sense (`task` tool, `mode: "background"`, filesystem access, parallel execution) -- ✅ Demonstrate advanced patterns (speculative spawning, agent-to-agent handoffs, drop-box for concurrent writes) -- ✅ Stay simple and transparent (no SDK dependency, no custom APIs, just files and markdown) -- ❌ Don't reinvent what Copilot already provides (use `task` tool, not a custom subprocess manager) -- ❌ Don't fight the platform (if Copilot has a feature, use it instead of working around it) - -**When to reconsider SDK adoption:** -- If the Copilot SDK adds **agent memory persistence primitives** that are better than filesystem (e.g., automatic conflict resolution, schema validation, query API) -- If GitHub releases **Copilot agent marketplace** features that require SDK integration -- If we hit hard limits with the `task` tool that the SDK solves (e.g., spawn quotas, context window exhaustion) - -**Until then:** Independent product, platform-optimized implementation. - ---- - -## 5. Recommendations: Concrete Next Steps - -### **Phase 1: Remove Friction (High Impact, Low Risk)** - -#### 1.1. Agents Read Their Own Charters -- **Change:** Remove inline charter paste from coordinator. Agents read `.ai-team/agents/{name}/charter.md` at spawn. -- **Impact:** Faster spawns, smaller coordinator context. -- **Effort:** 1 hour (update squad.agent.md spawn template). - -#### 1.2. Spawn Scribe in Parallel -- **Change:** Launch Scribe with the work agents, not after. -- **Impact:** Decisions propagate faster, logs are real-time. -- **Effort:** 1 hour (change when Scribe is spawned). - -#### 1.3. Better Spawn Descriptions -- **Change:** Add context to `description` parameter (e.g., "blocking", "speculative", "needs approval"). -- **Impact:** Users get better visibility into agent work. -- **Effort:** 30 minutes (update coordinator prompt). - ---- - -### **Phase 2: Enable Predictive Execution (Medium Impact, Medium Risk)** - -#### 2.1. Speculative Agent Spawning -- **Change:** When user requests work, spawn *all* agents who might contribute (tests, docs, etc.), not just the primary implementer. -- **Impact:** Demonstrates Copilot's async power. More aggressive parallelism. -- **Risk:** Wasted work if speculative agents guess wrong. Mitigation: Make this opt-in via a setting or prompt keyword ("team, work ahead on..."). -- **Effort:** 2 hours (update coordinator prompt + add speculative spawn logic). - -#### 2.2. Proactive Follow-Up -- **Change:** After agents complete, coordinator immediately spawns obvious next steps without waiting for user request. -- **Impact:** Pipeline stays full. Less idle time. -- **Risk:** Users may feel Squad is "doing too much" without asking. Mitigation: Always label proactive work clearly ("🔮 Proactive: I wrote tests based on your API design"). -- **Effort:** 1 hour (update coordinator post-work logic). - ---- - -### **Phase 3: Enable Agent Autonomy (High Impact, High Risk)** - -#### 3.1. Agent-to-Agent Handoffs -- **Change:** Senior agents (Lead, domain specialists) can spawn other agents directly using the `task` tool. -- **Impact:** True multi-agent autonomy. Demonstrates advanced Copilot patterns. -- **Risk:** Runaway spawning (agent A spawns B, B spawns C, C spawns A...). Mitigation: Strict spawn authority (only senior roles), require orchestration log entry, limit spawn depth. -- **Effort:** 4 hours (update charters for spawn-capable agents, add depth tracking, update orchestration log). - -#### 3.2. Context Pre-Loading for Batch Spawns -- **Change:** Coordinator pre-reads `history.md` + `decisions.md` once and injects into all spawn prompts when spawning 3+ agents. -- **Impact:** Fewer tool calls, faster batch startup. -- **Risk:** Larger spawn prompts (may hit token limits on mature projects). Mitigation: Only use for batch spawns, fall back to agent-reads-itself for single spawns. -- **Effort:** 2 hours (add batch spawn detection + pre-load logic). - ---- - -### **Phase 4: Visibility & Monitoring (Low Impact, High Value)** - -#### 4.1. Spawn Cost Tracking -- **Change:** Log token usage per agent spawn in orchestration log (use Copilot's usage API if available). -- **Impact:** Users can see Squad's efficiency. We can optimize high-cost patterns. -- **Effort:** 2 hours (add token tracking to orchestration log). - -#### 4.2. Agent Performance Metrics -- **Change:** Track agent spawn time, completion time, and output size. Surface in a dashboard or summary command. -- **Impact:** Identify slow agents or bottlenecks. -- **Effort:** 3 hours (add metrics collection + summary view). - ---- - -## 6. Success Metrics - -How do we know if these optimizations work? - -| Metric | Current | Target (Post-Optimization) | -|--------|---------|---------------------------| -| **Avg spawn latency** | ~3-5 seconds (inline charter) | ~1-2 seconds (agent reads charter) | -| **Parallel agent utilization** | 60% (only spawn known-needed agents) | 85% (speculative + proactive spawns) | -| **Coordinator context usage** | 1.5% (1,900 tokens) | <1% (<1,300 tokens, no charter inlining) | -| **Time to first decision propagation** | After Scribe completes (serial) | During agent work (parallel Scribe) | -| **User-reported "Squad feels fast"** | Baseline | +30% improvement | - ---- - -## 7. Open Questions - -- **Q: Should we expose speculative spawning as a user-facing setting?** - A: Not initially. Start with Coordinator heuristics ("if request is broad, spawn speculatively"). Add a setting later if users want control. - -- **Q: What's the spawn depth limit for agent-to-agent handoffs?** - A: Max depth = 2. Agent A can spawn Agent B, Agent B can spawn Agent C, but Agent C cannot spawn further. Prevents infinite recursion. - -- **Q: How do we handle failed speculative work?** - A: Agents label speculative output clearly. If primary agent's decisions invalidate speculative work, we log it and move on. No retry. Cheap failure is the point. - -- **Q: Should Squad use Copilot's `explore` agent for codebase questions?** - A: Yes. If a spawned agent needs to "search the codebase for X," they should use the `explore` sub-agent instead of grep/glob. Faster, more semantic. - ---- - -## 8. Conclusion - -Squad is already well-architected for Copilot. The core patterns — `task` tool spawning, filesystem memory, background parallelism — are solid. But we're leaving power on the table. - -**The opportunity:** Make Squad the **flagship example** of what Copilot enables. Not by becoming a Copilot SDK product, but by being the best *demonstration* of building on the platform. - -**Next step:** Start with Phase 1 (remove friction). Ship those changes. Then assess whether Phase 2/3 (predictive + autonomous execution) are worth the complexity. - -**Strategic bet:** Copilot will evolve toward multi-agent orchestration. When it does, Squad should already be there — showing what's possible. - ---- - -**Approved by:** bradygaster (partially — Phase 1 items folded into shipped features) -**Implemented:** Partial — Phase 1 items (agents read own charters, Scribe in parallel, spawn descriptions) shipped in Waves 1-2. Phase 2-4 deferred to Horizon. -**Retrospective:** [Pending] diff --git a/team-docs/proposals/004-demo-script-overhaul.md b/team-docs/proposals/004-demo-script-overhaul.md deleted file mode 100644 index eaca40355..000000000 --- a/team-docs/proposals/004-demo-script-overhaul.md +++ /dev/null @@ -1,423 +0,0 @@ -# Proposal 004: Demo Script Overhaul — "Make It Pop" - -**Status:** Approved ✅ Shipped -**Authored by:** McManus (DevRel) -**Date:** 2026-02-07 -**Requested by:** bradygaster - ---- - -## Summary - -Complete rewrite of the demo script (`docs/demo-script.md`) with a beat-by-beat format that tells Brady exactly what's on screen, what to say (voiceover), and what to physically do at every moment. The current script has good material but is disjointed — it doesn't follow the README order (Brady's feedback), it buries the action steps inside prose, and it has a dead ACT 7 reference gap. This proposal delivers a production-ready recording blueprint. - ---- - -## Problem - -The current demo script has three structural problems: - -1. **The README walkthrough is out of order.** Brady asked the script to follow the README's flow. The current ACT 5 walks through README sections, but it's positioned as a "meanwhile the agents build" interlude rather than a narrative that tracks the README's structure from top to bottom. - -2. **Action steps are buried.** The script tells Brady what the audience should *see*, but doesn't give him explicit "type this, press Enter, wait 3 seconds" instructions. During a recording session, ambiguity costs takes. Takes cost hours. - -3. **Missing ACT 7.** The current script jumps from ACT 6 to ACT 8. There's a reference table mentioning ACT 7 content (second wave of parallel work, viewing history.md/decisions.md files), but the act itself doesn't exist. The payoff lands flat because we skip the artifact reveal. - -This proposal fixes all three by rebuilding the script as a sequence of **beats** — each with explicit on-screen, voiceover, and action sections. - ---- - -## Solution - -A new demo script format with 9 beats, targeting 5–7 minutes total runtime. Every beat has three sections: - -- **🎬 ON SCREEN** — exactly what the viewer sees (terminal, browser, file contents) -- **🎙️ VOICEOVER** — exactly what Brady says, written to be spoken aloud -- **👆 WHAT TO DO** — step-by-step physical actions during recording - -The script follows the README order: install → prompt → team reveal → parallel work → how it works → knowledge → artifacts → payoff → closer. - -The snake game scenario is preserved — it's visual, self-contained, and the CRT effect makes a great thumbnail. - ---- - -## Trade-offs - -**What we gain:** -- Brady can record in one session with zero improvisation required -- Voiceover is written conversational — no "reading a script" energy -- Every beat has a clear timestamp target, making editing predictable -- "Throw a squad at it" is woven in naturally per proposal 002 - -**What we give up:** -- Flexibility — a rigid beat structure leaves less room for spontaneous moments -- Length pressure — 9 beats in 5–7 minutes means some beats are tight (30–45 seconds) - -**Mitigation:** Beat timestamps are targets, not hard limits. Brady can breathe. The editing notes at the end cover where to cut if it runs long. - ---- - -## Alternatives Considered - -**Option 1: Bullet-point outline (current approach)** -Pros: Faster to write. Cons: Ambiguous during recording. Brady has to interpret intent on the fly. Costs takes. - -**Option 2: Full screenplay format** -Pros: Industry standard. Cons: Overkill for a 6-minute dev demo. Adds formatting overhead without value. - -**Option 3: Beat format (this proposal)** -Best of both — structured enough to eliminate ambiguity, lightweight enough to read in 10 minutes. Each beat is self-contained. Brady can rehearse one beat at a time. - ---- - -## Success Criteria - -- Brady can record the demo in ≤3 takes using only this script -- The finished video is 5–7 minutes -- "Throw a squad at it" appears naturally at least twice -- The thumbnail frame (CRT snake game with agent output visible) is explicitly called out -- Every README section appears in order in the demo - ---- - -## The Script - ---- - -## PRE-RECORDING SETUP CHECKLIST - -Complete every item before hitting record. This eliminates re-takes from environment issues. - -- [ ] **Clean terminal** — solid dark background, large font (≥16pt), no previous commands in scrollback -- [ ] **Empty folder ready** — a clean directory with nothing in it (e.g., `~/demos/snake-game`). Delete and recreate if reusing. -- [ ] **Git installed and configured** — `git init` must work without prompts -- [ ] **Node.js installed** — `npx` must work. Test with `npx --version`. -- [ ] **GitHub Copilot CLI ready** — `copilot` launches cleanly. Squad appears in `/agents` list after install. -- [ ] **Browser open but hidden** — Chrome/Edge with a blank tab, off-screen. You'll drag it on-screen for the finale. -- [ ] **Screen recording software running** — OBS, QuickTime, or similar. Capture terminal at native resolution. -- [ ] **Microphone OFF during screen recording** — voiceover is recorded separately. No keyboard sounds, no "um"s to edit out. -- [ ] **Editor ready** — VS Code or similar, closed but launchable. You'll open files during BEAT 7. -- [ ] **Test run completed** — run through BEATs 1–3 once to confirm `npx bradygaster/squad` works, Copilot launches, and Squad appears in `/agents`. - ---- - -## BEAT 1: The Empty Folder (0:00–0:30) - -### 🎬 ON SCREEN (what the audience sees) -A terminal. Completely empty folder. Three commands typed live — `mkdir`, `git init`, `npx bradygaster/squad`. The install output ticks through: a checkmark for `squad.agent.md`, a checkmark for templates, "Squad is ready." Then a quick file tree showing what was created: `.github/agents/squad.agent.md` and `.ai-team-templates/`. - -### 🎙️ VOICEOVER (what Brady says — record separately) -> Empty folder. That's where every project starts. Three commands — make the folder, init git, run one npx command. That's the entire install. Squad drops a single agent file into `.github/agents/` and some templates. No config files, no YAML, no boilerplate. One file. That file is the coordinator — it's the one agent that knows how to build you a team. - -### 👆 WHAT TO DO (Brady's action steps during recording) -1. Start with terminal visible, cursor blinking in an empty directory -2. Type `mkdir snake-game && cd snake-game` — press Enter, wait for prompt to return -3. Type `git init -b main` — press Enter, wait for "Initialized empty Git repository" message -4. Type `npx bradygaster/squad` — press Enter -5. Wait for install output to complete (checkmarks appear, "Squad is ready" prints) -6. Pause 2 seconds on the output so viewers can read it -7. Type `Get-ChildItem -Recurse -Name` (or `find . -type f` on Mac/Linux) — press Enter to show the file tree -8. Pause 3 seconds on the file tree — this is the "before" shot - ---- - -## BEAT 2: The Prompt (0:30–1:15) - -### 🎬 ON SCREEN (what the audience sees) -Copilot CLI opens. Brady selects Squad from the agents list. A prompt appears — it's a retro Snake game spec with canvas rendering, CRT effects, sound, mobile controls. The prompt sits on screen long enough to read. Then Enter is pressed. - -### 🎙️ VOICEOVER (what Brady says — record separately) -> Now I open Copilot and pick Squad from the agents list. And I'm going to give it one prompt — a retro Snake game. Canvas rendering, CRT scanline effects, sound, mobile touch controls. I'm not asking for a plan. I'm not asking for an architecture review. I'm saying: build this. Throw a squad at it. Let's see what happens. - -### 👆 WHAT TO DO (Brady's action steps during recording) -1. Type `copilot` — press Enter to launch Copilot CLI -2. When Copilot opens, select **Squad** from the `/agents` list (arrow keys + Enter, or type `/agent squad`) -3. Paste the following prompt (have it copied to clipboard beforehand): - -``` -Build a browser-based Snake game using vanilla HTML, CSS, and JavaScript. No frameworks. Requirements: -- Canvas-based rendering at 60fps -- Arrow key and WASD controls -- Score tracking with localStorage high scores -- Progressive speed increase every 5 points -- A retro CRT-style visual effect using CSS filters -- Mobile support via touch swipe controls -- Sound effects using the Web Audio API - -Start building immediately — I want to play this in 20 minutes. -``` - -4. **Do NOT press Enter yet.** Let the prompt sit on screen for 4–5 seconds so viewers can read it. -5. Press Enter. -6. Watch Squad begin processing — it will analyze the prompt and propose a team. - ---- - -## BEAT 3: The Team Reveal (1:15–2:00) - -### 🎬 ON SCREEN (what the audience sees) -Squad proposes a team. Names from a fictional universe appear with roles and responsibilities. Something like: - -``` -🏗️ Dallas — Lead Scope, decisions, architecture -⚛️ Ripley — Frontend Dev Canvas, rendering, game UI -🔧 Kane — Backend Dev Game logic, audio, input systems -🧪 Lambert — Tester Tests, edge cases, quality -📋 Scribe — (silent) Memory, decisions, session logs -``` - -Brady confirms. The `.ai-team/` directory gets created — charters, routing, decisions, casting registry. - -### 🎙️ VOICEOVER (what Brady says — record separately) -> So Squad didn't start writing code. Its first move was to figure out who it needs. A lead for architecture. A frontend dev for the canvas and visuals. A game logic person for movement and audio. A tester. And Scribe — Scribe is on every team, always silent, always logging. These names aren't random labels. They're persistent identities from a fictional universe. This team is cast from Alien. Next project might be Ocean's Eleven. The names stick — they follow the team across sessions. That's not decoration. That's identity. - -### 👆 WHAT TO DO (Brady's action steps during recording) -1. Wait for Squad to finish proposing the team — the roster will print to the terminal -2. Pause 3–4 seconds so viewers can read the team roster -3. Type `yes` (or whatever confirmation Squad prompts for) — press Enter -4. Wait for Squad to create the `.ai-team/` directory and agent files -5. When creation completes, let the output settle for 2 seconds - ---- - -## BEAT 4: Parallel Fan-Out (2:00–2:45) - -### 🎬 ON SCREEN (what the audience sees) -Squad launches all agents simultaneously. The terminal shows parallel spawning — every agent starting work at the same time: - -``` -🏗️ Dallas analyzing project structure... -⚛️ Ripley building canvas renderer and CRT effects... -🔧 Kane setting up game loop, input handling, audio... -🧪 Lambert writing test cases from requirements... -📋 Scribe logging everything... -``` - -All at once. Not sequential. The fan-out is visible. - -### 🎙️ VOICEOVER (what Brady says — record separately) -> Here's the moment. Squad just launched every agent at the same time — as background processes. The lead is scoping architecture. The frontend dev is building the canvas renderer. The game logic agent is wiring up movement and audio. And look — the tester is already writing test cases. Right now. From the requirements alone. Before any code exists. That's not waiting for implementation. That's getting ahead of it. All of this is happening in parallel. In separate context windows. No shared bloat. - -### 👆 WHAT TO DO (Brady's action steps during recording) -1. Watch the terminal as Squad spawns agents — each agent's task will print as it launches -2. Let the fan-out complete — all agents should show as launched -3. Pause 2 seconds on the full list of running agents -4. **This is the cut point** — in editing, you'll cut from here to BEAT 5 while agents work in the background - ---- - -## BEAT 5: How It Works — The Architecture (2:45–4:00) - -_While agents build in the background, walk through the README. This follows the README's section order exactly._ - -### 🎬 ON SCREEN (what the audience sees) -Switch to the Squad README in a browser or editor. Scroll through sections in order, pausing on each: - -1. **"What is Squad?"** — linger on "It's not a chatbot wearing hats" -2. **"Agents Work in Parallel"** — the fan-out diagram (matches what just happened) -3. **"How It Works — The Key Insight"** — each agent gets its own context window, mermaid architecture diagram -4. **"Context Window Budget"** — the token table showing real numbers (94% left for actual work) - -### 🎙️ VOICEOVER (what Brady says — record separately) - -**On "What is Squad?" (scroll slowly):** -> So what is Squad, actually? It gives you a team that persists. These agents aren't throwaway chat sessions. They live in your repo as files — charters, histories, shared decisions. Anyone who clones the repo gets the team, with everything it's learned. And it's not a chatbot wearing hats. Each team member runs in its own context. - -**On "Agents Work in Parallel" (pause on the fan-out diagram):** -> This diagram? This is literally what's happening right now in the background. Every agent that can usefully start — starts. No sequencing, no waiting for permission. The coordinator launches aggressively and collects results. - -**On "The Key Insight" (pause on mermaid diagram):** -> Here's the design trick. Each agent gets its own context window. The coordinator is thin — it just routes work. Each specialist loads only its charter and its history. No shared bloat. No "I'm the backend agent but I also have to remember the frontend's component library." - -**On "Context Window Budget" (pause on the token table):** -> Real numbers. The coordinator uses 1.5% of the context window. Even a veteran agent with three months of accumulated knowledge only uses about 4%. That leaves 94% for actually reasoning about your code. Most agent frameworks burn half their context on identity. Squad doesn't. - -### 👆 WHAT TO DO (Brady's action steps during recording) -1. Open a browser (or VS Code preview) with the Squad README visible -2. Scroll to **"What is Squad?"** — pause 5 seconds, let the camera rest on "It's not a chatbot wearing hats" -3. Scroll to **"Agents Work in Parallel"** — pause on the fan-out diagram for 4 seconds -4. Scroll to **"How It Works"** — pause on the mermaid architecture diagram for 5 seconds -5. Scroll to **"Context Window Budget"** — pause on the token table for 5 seconds, let viewers read the numbers -6. **Do not rush this section.** This is the conceptual heart of the demo. Let each section breathe. - ---- - -## BEAT 6: Knowledge and Memory (4:00–4:45) - -### 🎬 ON SCREEN (what the audience sees) -Continue scrolling the README. Land on: - -1. **"Knowledge compounds across sessions"** — the maturity table (First session → Mature project) -2. **"Memory Architecture"** — the four-layer table (charter / history / decisions / log) -3. **"What Gets Created"** — the `.ai-team/` file tree -4. **"Growing the Team" + "Reviewer Protocol"** — brief pause - -### 🎙️ VOICEOVER (what Brady says — record separately) - -**On "Knowledge compounds" (pause on the maturity table):** -> This is where it gets really interesting over time. Look at this table. First session — the frontend dev knows your framework choice. After a few sessions, it knows your component library, your routing patterns, your state management. Mature project — it knows your design system, your performance patterns, your accessibility conventions. That knowledge lives in each agent's personal `history.md`. It's append-only. It only grows. - -**On "Memory Architecture":** -> Four layers. Charter is identity — written once, never self-modified. History is personal — what this agent learned about your project. Decisions is the shared brain — every agent reads the same decisions file before starting work. And the log is Scribe's domain. Searchable archive of everything that happened. - -**On "What Gets Created" (pause on file tree):** -> This is what's in your repo. Commit this folder. Your team persists. Your names persist. Anyone who clones gets the team with the same cast. - -**On "Growing the Team" / "Reviewer Protocol" (quick scroll):** -> Need a DevOps person? Ask for one. They join the same universe, get seeded with all existing decisions, and they're productive immediately. And the team has standards — reviewers can reject work. No self-review allowed on rejected code. Real accountability. - -### 👆 WHAT TO DO (Brady's action steps during recording) -1. Scroll to **"Knowledge compounds"** — pause on the maturity table for 6 seconds -2. Scroll to **"Memory Architecture"** — pause on the four-layer table for 4 seconds -3. Scroll to **"What Gets Created"** — pause on the file tree for 3 seconds -4. Scroll through **"Growing the Team"** and **"Reviewer Protocol"** — 2–3 seconds each, keep moving -5. After this section, you'll switch back to the terminal - ---- - -## BEAT 7: The Artifacts (4:45–5:30) - -### 🎬 ON SCREEN (what the audience sees) -Switch back to the terminal. Check on agents. Then open real files in an editor: - -1. `list_agents` output showing background agents completing -2. Open `.ai-team/decisions.md` — show real decisions the agents made during the build -3. Open one agent's `history.md` — show what it learned -4. Open one agent's `charter.md` — show the identity definition - -Real files. Real content written by agents minutes ago. - -### 🎙️ VOICEOVER (what Brady says — record separately) -> Alright, let's check in on the team. The agents have been working this whole time. Let's see what they built — but first, let's look at the artifacts. This is `decisions.md`. These are real decisions the team made during the build — architecture choices, file structure, API patterns. Every agent read this before starting. And here's Ripley's history file — look, it already learned about the canvas setup, the CRT filter values, the rendering approach. Next session, Ripley won't ask about any of this again. It remembers. - -### 👆 WHAT TO DO (Brady's action steps during recording) -1. Switch back to the terminal window -2. If Squad's output is visible showing agent completion, pause on it for 3 seconds -3. Open VS Code (or your editor) with the project folder -4. Open `.ai-team/decisions.md` — scroll slowly through the decisions, pause on 2–3 specific entries -5. Open one agent's `history.md` (e.g., `.ai-team/agents/ripley/history.md` or whatever name was cast) — scroll through learnings -6. Open the same agent's `charter.md` — show the identity, expertise, and voice definition -7. Pause 2 seconds on the charter — let viewers see that agents have defined personalities - ---- - -## BEAT 8: The Payoff — Play the Game (5:30–6:15) - -### 🎬 ON SCREEN (what the audience sees) -Open `index.html` (or whatever the snake game entry point is) in the browser. The game loads. CRT scanline effect is visible — green phosphor glow on a dark background. Brady plays the game for 15–20 seconds. The snake moves, food appears, score increments, speed increases. The CRT effect makes it look retro and polished. - -**🖼️ THUMBNAIL MOMENT:** The single frame for the video thumbnail is here. The browser showing the CRT snake game in the foreground, with the terminal showing agent completion output partially visible behind it. Agents built this. The game proves it. - -### 🎙️ VOICEOVER (what Brady says — record separately) -> And there it is. A working Snake game with canvas rendering, CRT effects, the whole thing. Built by a team of AI agents working in parallel while I walked you through how it works. I didn't write a line of code. I didn't manage tasks. I didn't copy-paste between chat windows. I described what I wanted and threw a squad at it. - -### 👆 WHAT TO DO (Brady's action steps during recording) -1. Open the project's `index.html` file in Chrome/Edge (drag from file explorer or use `open index.html`) -2. Wait for the game to fully load — the CRT effect should be visible immediately -3. Play the game for 15–20 seconds — use arrow keys, let the score increment at least twice -4. **For the thumbnail:** Position the browser window so the terminal with agent output is partially visible behind it. Take a mental note of this frame — or screenshot it separately for the thumbnail. -5. Let the game run for a few more seconds in the background - ---- - -## BEAT 9: The Closer (6:15–6:45) - -### 🎬 ON SCREEN (what the audience sees) -Back to the terminal. Show the project file tree one final time — the full structure with `.ai-team/`, source files, everything the team built. Then show the three Quick Start commands from the README one more time. The final frame: the Squad repo URL. - -### 🎙️ VOICEOVER (what Brady says — record separately) -> The team is in the repo now. Tomorrow I can open Copilot, talk to the same agents by name, and they'll remember everything — the canvas setup, the audio patterns, the CRT filter values. The more you use Squad, the less you have to explain. That's the whole idea. Three commands to install. One prompt to start. Your team gets smarter every session. Try it — `npx bradygaster/squad`. Throw a squad at it. - -### 👆 WHAT TO DO (Brady's action steps during recording) -1. Switch back to the terminal -2. Type `Get-ChildItem -Recurse -Name` (or `find . -type f`) — press Enter to show the full project tree -3. Pause 4 seconds on the file tree — this is the "after" shot (compare to BEAT 1's "before") -4. Clear the terminal (optional) and type: `npx bradygaster/squad` — **do not press Enter.** Let it sit as the final call-to-action. -5. Hold this frame for 5 seconds — this is the outro shot -6. Stop recording - ---- - -## POST-RECORDING NOTES - -### Editing Cuts -- **BEAT 4 → BEAT 5:** Hard cut. Agents are spawning, then we're in the README. No transition needed — the voiceover bridges it ("while they build, let me show you how this works"). -- **BEAT 6 → BEAT 7:** Soft cut. Scroll ends, switch to terminal. Consider a 0.5-second fade or just a direct cut. -- **BEAT 7 → BEAT 8:** This is the big reveal. Consider a 1-second pause (black frame or freeze) before the game appears. Let the payoff land. -- **If it runs long:** Cut time from BEAT 6 (the README walkthrough can lose "Growing the Team" and "Reviewer Protocol" without hurting the narrative). BEATS 1–4 and 8–9 are sacred — don't cut them. - -### Music Suggestions -- **Lo-fi / chillhop instrumental** — low energy, doesn't compete with voiceover. Think "coding playlist" vibes. -- Start music at BEAT 1, duck it under voiceover, bring it up slightly during BEAT 4 (the parallel fan-out is visual, less talking). -- **Kill the music at BEAT 8** when the game appears. Let the game's own audio (if it works) or silence carry the payoff. Music re-enters softly for BEAT 9 closer. -- Royalty-free sources: Epidemic Sound, Artlist, or YouTube Audio Library. - -### Voiceover Recording Tips -- Record in a quiet room. Closet works. No reverb. -- Speak at conversation pace — not presentation pace. Imagine you're showing a friend something cool on your laptop. -- It's OK to breathe. Pauses between beats are natural. Don't try to fill every second. -- Record each beat separately. Label files `beat-01-voiceover.wav` through `beat-09-voiceover.wav`. Easier to sync in editing. - -### Thumbnail -- Frame from BEAT 8: CRT snake game in browser, foreground. Terminal with agent names/completion output partially visible behind. -- Add text overlay: **"One prompt. Five agents. Working game."** — or just **"Throw a squad at it."** -- Green CRT glow + purple Squad badge = strong color contrast for YouTube/social feeds. - ---- - -## Why This Script Works - -### The Messaging Strategy - -**1. It follows the README order — on purpose.** - -Brady's feedback was clear: the current script is disjointed. This script mirrors the README's structure exactly. When someone watches the demo and then reads the README, the concepts land in the same order. That's not an accident — it's reinforcement. The demo primes the concepts, the README deepens them. Same story, two formats. - -**2. The hero moment is at the END, not the beginning.** - -Most dev demos open with the flashy result and then explain how they got there. This script inverts it — you start with an empty folder and build toward the payoff. By the time the snake game appears in BEAT 8, the viewer understands *what built it*. The game isn't the point. The team is the point. The game is proof. - -**3. "Throw a squad at it" lands twice — naturally.** - -Per proposal 002, the tagline needs to feel like something Brady would actually say, not something he was told to say. It appears first in BEAT 2 (the prompt) as a casual "let's see what happens" moment, and again in BEAT 9 (the closer) as the final call-to-action. Two mentions. Both conversational. Neither forced. - -**4. The README walkthrough IS the demo.** - -BEATs 5–6 walk through the README while agents build in the background. This is the single smartest structural choice in the script. It accomplishes three things at once: -- Explains the architecture (educational) -- Shows parallel work happening in real time (proof) -- Drives viewers to the README for deeper reading (conversion) - -The viewer isn't watching a demo *and then* reading docs. They're watching the docs come alive while the product runs. - -**5. The artifacts beat (BEAT 7) makes it real.** - -Opening `decisions.md` and `history.md` — files that were just written by agents minutes ago — is the "oh, this is actually real" moment. Abstract concepts ("agents share decisions") become concrete when you see the actual file. This beat converts skeptics. - -**6. The thumbnail is engineered.** - -The CRT snake game with agent output in the background is designed to stop a dev mid-scroll. It's visually distinct (green glow, retro aesthetic) and informationally dense (you can see agents built this). A good thumbnail is worth 10x the content behind it. - ---- - -## Appendix: Timing Breakdown - -| Beat | Title | Duration | Cumulative | -|------|-------|----------|------------| -| 1 | The Empty Folder | 0:30 | 0:30 | -| 2 | The Prompt | 0:45 | 1:15 | -| 3 | The Team Reveal | 0:45 | 2:00 | -| 4 | Parallel Fan-Out | 0:45 | 2:45 | -| 5 | How It Works | 1:15 | 4:00 | -| 6 | Knowledge and Memory | 0:45 | 4:45 | -| 7 | The Artifacts | 0:45 | 5:30 | -| 8 | The Payoff | 0:45 | 6:15 | -| 9 | The Closer | 0:30 | 6:45 | - -**Total: ~6:45** — fits comfortably in the 5–7 minute target with room for natural pacing. - ---- - -## Revisions - -None yet. diff --git a/team-docs/proposals/005-video-content-strategy.md b/team-docs/proposals/005-video-content-strategy.md deleted file mode 100644 index e9e3e3b76..000000000 --- a/team-docs/proposals/005-video-content-strategy.md +++ /dev/null @@ -1,366 +0,0 @@ -# Proposal 005: Video Content Strategy — "Wait, What?" - -**Status:** Approved — Deferred to Horizon -**Author:** Verbal (Prompt Engineer & AI Strategist) -**Date:** 2026-02-07 -**Requested by:** bradygaster -**Context:** Brady wants video content that drives repo visits and stars. First video must make devs say "wait what." Series should demonstrate Squad's power and position it as the definitive multi-agent tool for Copilot. - ---- - -## The Opportunity - -Nobody is showing *real* multi-agent orchestration on video. The AI YouTube space is drowning in "I built X with ChatGPT" talking heads and tutorial-style cursor recordings. Squad has something nobody else can show: **agents working simultaneously, in separate contexts, building real software, learning from each other, and persisting across sessions.** That's not a feature demo — it's a fundamentally different workflow, and it looks compelling on screen. - -We need to own the "multi-agent dev team" visual language before anyone else figures out how to film it. - ---- - -## 1. "The Trailer" — 60-90 Seconds - -### Concept: *"What if your AI wasn't one brain pretending to be five?"* - -This is a cold open. No intro. No "hey guys." No logo animation. You're dropped into the middle of something happening. - ---- - -**Title:** `I gave one prompt to 5 AI agents. They built a game without me.` - -**Target length:** 75 seconds - -**Hook (0:00–0:03):** - -Screen shows a terminal. Five agents are already running in parallel. Status lines are streaming. Text overlay, big and bold: - -> **"I didn't write a single line of this code."** - -Three seconds. Viewer is already confused. Good. - -**The Build (0:03–0:25):** - -Quick cuts. Fast. Almost disorienting. Show: -- The one-liner: `npx bradygaster/squad` in an empty folder -- The prompt being pasted (Snake game spec — viewer sees it flash by, doesn't need to read it all) -- The team reveal — five named agents, cast from a movie universe. Names on screen. Roles visible. -- The fan-out — all five agents launching simultaneously. Terminal output scrolling in parallel. - -Voiceover (fast, energetic, Brady's natural voice): -> "Empty folder. One command. One prompt. Squad doesn't write the code — it builds a team that writes the code. Five agents. All running at the same time. Each one in its own context window." - -**The "Wait What" Moment (0:25–0:50):** - -Split screen. Left side: agents are still building. Right side: Brady opens `decisions.md` — agents are *making decisions and writing them down for each other*. He scrolls. Decisions are accumulating in real time. - -Cut to: `history.md` for one agent. It already has learnings. It's been working for 90 seconds and it's already *remembering things about this project*. - -Voiceover: -> "They're not just coding. They're making decisions. Writing them down. Learning. The tester is writing test cases from the spec *before the code exists*. And when I come back tomorrow — they remember. All of it. It's in git." - -**The Payoff (0:50–1:10):** - -Browser opens. Snake game is running. CRT glow. Score ticking up. The snake is moving. - -Pull back to the terminal. Show the file tree — `.ai-team/` folder with all the agent artifacts. This is the "it's real" moment. - -Text overlay: - -> **squad** — throw a squad at it. -> `npx bradygaster/squad` - -**CTA (1:10–1:15):** - -> "Full build video in the description. Repo link below. Star it if you want to see what's next." - ---- - -**Why this works:** - -1. **The hook is a claim.** "I didn't write a single line" — devs will watch to verify or debunk. -2. **The "wait what" is the decisions file.** Agents coordinating through shared state isn't something devs have seen. It looks like agents *talking to each other*. -3. **The payoff is a working app.** Not a plan. Not a design doc. A game you can play. -4. **The CTA is low-friction.** Star the repo. Watch the full video. Both are one click. - -**What the viewer feels after watching:** "I need to try this. Right now." They go to the repo, see the README with "Throw a squad at it," and they're already primed. The video did the selling. The README just needs to not screw it up. - ---- - -## 2. "The Full Demo" — 5-7 Minutes - -### Concept: *"Zero to playable game with a team of AI agents"* - -This is McManus's territory for final scripting and polish (see `docs/demo-script.md` for the existing structure). But I own the strategic arc. Here's what makes this more than a tutorial: - ---- - -**Title:** `I built a game with 5 AI agents in 20 minutes. Here's every step.` - -**Target length:** 6 minutes - -**Hook (0:00–0:05):** - -Open on the finished Snake game running in a browser. CRT glow. Sound effects. Score ticking. Then — hard cut to black. Text: - -> **"20 minutes ago, this folder was empty."** - -Cut to the empty terminal. Now we start from zero. - -**Story Arc — Three Acts:** - -The demo script (McManus's `docs/demo-script.md`) already has good bones. Here's the strategic layer: - -#### Act 1: "One Brain vs. Five" (0:05–1:30) - -The *thesis* of the video. Don't start with the install. Start with the *problem*. - -> "Every AI coding tool you've used is one model pretending to be a team. You ask for backend, it puts on a backend hat. You ask for tests, same model, different hat. That's not a team — that's a costume change." - -Then: `npx bradygaster/squad`. One command. Team proposal appears. Named agents. Different universe. - -**Aha moment #1:** The team reveal. Five specialists with *names*, not labels. Viewer realizes these aren't generic bots. - -#### Act 2: "The Build" (1:30–4:00) - -This is where most demo videos die. They show code being generated and the viewer zones out. We don't do that. - -**The trick: Don't show the code. Show the coordination.** - -While agents are building in the background: -- Open `decisions.md` — show decisions appearing as agents work -- Open an agent's `history.md` — show it learning in real time -- Run `list_agents` — show all five running simultaneously (visual proof of parallelism) -- Show Scribe's log entries — the silent agent that never talks to you but is always working - -**Aha moment #2:** The tester has written 14 test cases from the *requirements alone*, before any implementation code exists. Show the test file. Let that land. This is anticipatory work — the tester didn't wait for code. It got ahead. - -**Aha moment #3:** The reviewer rejects something. Show the rejection. Show the coordinator routing the revision to a *different* agent (not the original author). This is the reviewer protocol in action. Devs who've done code review will immediately get why this matters. - -> "The tester can reject work. And when it does, the original author doesn't fix it — someone else does. No self-review. That's a rule we enforce." - -#### Act 3: "The Payoff" (4:00–6:00) - -Open the game. Play it. Let the CRT effect shine. Let the sound play. - -Then — the real payoff. Not the game. The *team*. - -> "The game is cool. But that's not the point. The point is what's in this folder now." - -Open `.ai-team/`. Show the structure. Charters. Histories. Decisions. The casting registry. - -> "This team is committed to git. Anyone who clones this repo gets the same agents, with the same names, with everything they've learned. Tomorrow I can say 'hey Ripley, change the color scheme' and she'll know exactly what I mean because she built the renderer." - -**Aha moment #4:** Knowledge persistence. The agents *remember*. This is the moment that separates Squad from every other AI demo. - -Final line: -> "Throw a squad at it. Link in the description." - ---- - -**Engagement strategy for 5+ minutes:** - -The reason viewers drop off long demos is predictability. They figure out what's going to happen and leave. Our counter: - -1. **Never show raw code generation for more than 10 seconds.** Cut away. Show artifacts. Show coordination. -2. **Place aha moments at 1:30, 3:00, 4:00, and 5:30.** Spaced to re-engage wandering attention. -3. **The reviewer rejection is the plot twist.** It's unexpected. It creates drama. "Wait, the AI can reject its own team's work?" -4. **End on the persistence story, not the game.** The game is the hook. The team persistence is the reason they star the repo. - ---- - -## 3. "The Series" — Content Roadmap - -Each video below is designed to stand alone but reinforce the "throw a squad at it" brand. Recurring visual: every video opens with an empty folder and ends with a working artifact. The team is always the star — never the output alone. - ---- - -### Video 3.1: Parallel Execution Deep Dive - -**Title:** `5 AI agents. 1 prompt. All building at the same time. Here's how.` - -**Hook (first 5 seconds):** -Screen: five terminal panes, tiled. All five are streaming agent output simultaneously. Text overlay: *"This isn't sped up."* - -**"Wait what" moment:** -Run `list_agents` to show all five background processes. Then open Activity Monitor / Task Manager — show the actual process list. Five separate Copilot sessions running in parallel. This is *real* parallelism, not sequential-pretending-to-be-parallel. - -**CTA:** "Try it yourself. One `npx` command. Link below." - -**Target length:** 3-4 minutes - ---- - -### Video 3.2: Knowledge Persistence - -**Title:** `My AI remembered my last 3 projects. I never told it to.` - -**Hook (first 5 seconds):** -Terminal. New session. Type: "Hey Keaton, what did we decide about auth last week?" Agent responds with specific, accurate context from `history.md`. Text overlay: *"This is session 47."* - -**"Wait what" moment:** -Open the agent's `history.md`. Scroll through weeks of accumulated learnings — conventions, preferences, architectural decisions. Then: `git log --oneline .ai-team/` — show the commit history. Knowledge growth over time, all tracked in version control. - -**CTA:** "Your agents learn. Your repo remembers. Star Squad on GitHub." - -**Target length:** 4-5 minutes - ---- - -### Video 3.3: Rejection Protocol - -**Title:** `My AI tester rejected my AI developer's code. Then this happened.` - -**Hook (first 5 seconds):** -Terminal output showing a rejection. Red text (or styled output): *"Lambert rejected Ripley's implementation: insufficient error handling."* Dramatic pause. Text overlay: *"Agents can say no."* - -**"Wait what" moment:** -The coordinator doesn't send it back to Ripley. It routes the fix to Kane (a different agent). Show the routing decision. Show Kane's revision. Show Lambert approving. The viewer realizes: *these agents have a code review process and they enforce it automatically.* - -**CTA:** "No self-review. No rubber stamps. Throw a squad at it." - -**Target length:** 3-4 minutes - ---- - -### Video 3.4: The Casting System - -**Title:** `My AI team has names. And they remember theirs.` - -**Hook (first 5 seconds):** -Split screen. Left: generic AI tool output — "Agent_1 completed task." Right: Squad output — "Ripley built the canvas renderer with CRT scanline effect." Text overlay: *"Which team would you rather work with?"* - -**"Wait what" moment:** -Create two different projects. Show that Squad picks *different* universes for each one — Alien for the game project, Ocean's Eleven for the API project. Open `casting/registry.json`. Show the mapping. Then clone the repo on a different machine. Same names. Same cast. The casting is *deterministic and portable*. - -**CTA:** "Your team has identity. Not just functionality. Try Squad." - -**Target length:** 3-4 minutes - ---- - -### Video 3.5: Growing and Shrinking Teams - -**Title:** `I fired an AI agent mid-project. It handled it better than my last coworker.` - -**Hook (first 5 seconds):** -Terminal: "Remove the designer — we're past that phase." Agent responds. Text overlay: *"Downsizing has never been this painless."* - -**"Wait what" moment:** -Show the agent moving to `.ai-team/agents/_alumni/`. Open the alumni folder — charter and history are preserved. Then, three "weeks" later: "Actually, bring back the designer." The agent returns — with all its knowledge intact. It picks up *exactly* where it left off. - -Second twist: add a *new* role mid-project. "I need a DevOps person." Squad casts from the same universe, seeds them with existing decisions, and the new agent is immediately productive. Show the new agent reading `decisions.md` on first spawn — it already knows everything the team has decided. - -**CTA:** "Teams that grow and shrink on demand. Throw a squad at it." - -**Target length:** 4-5 minutes - ---- - -### Video 3.6: Agent-to-Agent Coordination (The Advanced Play) - -**Title:** `My AI agents started coordinating without me. I just watched.` - -**Hook (first 5 seconds):** -Screen recording of `decisions.md` being updated. Entries appearing from different agents. Text overlay: *"I didn't ask them to do this."* - -**"Wait what" moment:** -Show the full chain: Lead analyzes requirements → spawns Frontend and Backend in parallel → Tester writes test cases anticipatorily → Backend finishes → Coordinator immediately chains Tester to run tests against new code → Tester finds an edge case → Lead routes fix to Frontend (not Backend, because it's a UI issue) → Frontend patches → Tester approves. All of this happens *without the user typing a single additional prompt after the first one*. - -Open the orchestration log. Show every spawn, every chain, every routing decision. The coordinator's reasoning is visible. - -**CTA:** "One prompt. Full autonomous build. This is where multi-agent dev is going. Repo link below." - -**Target length:** 5-6 minutes - ---- - -### Video 3.7: "Throw a Squad at It" — The Supercut - -**Title:** `7 projects. 7 squads. One command each. [Supercut]` - -**Hook (first 5 seconds):** -Rapid montage: seven `npx bradygaster/squad` commands, seven team reveals, seven different universes. Music: something uptempo, almost aggressive. Text overlay: *"Same command. Different universe. Every time."* - -**"Wait what" moment:** -Show all seven finished projects side by side. A game. An API. A CLI tool. A documentation site. A Chrome extension. A Discord bot. A data pipeline. All built from a single prompt each. All with persistent teams. All committed to git. - -**CTA:** "Whatever you're building — throw a squad at it. `npx bradygaster/squad`" - -**Target length:** 2-3 minutes (fast cuts, high energy, this is the shareable one) - ---- - -## Series Production Strategy - -### Release Cadence -- **Week 1:** The Trailer (Video 1) — maximum reach, optimized for shares -- **Week 2:** The Full Demo (Video 2) — converts interest into repo visits -- **Week 3-7:** Series videos (3.1–3.5), one per week — builds depth, SEO, and return viewership -- **Week 8:** Agent-to-Agent (3.6) — the "advanced" play for engaged audience -- **Week 9:** The Supercut (3.7) — recap + second viral push - -### Recurring Visual Language -Every video should share: -- **Empty folder → working artifact** arc -- **`npx bradygaster/squad`** visible in every video (the install moment) -- **"Throw a squad at it"** as the closing line — always -- **Agent names on screen** — never "the backend agent," always "Kane" or "Ripley" -- **The `.ai-team/` folder** opened at least once — make the file structure iconic - -### YouTube Optimization -- Thumbnails: split-screen format. Left = empty folder. Right = running app. Text = agent count ("5 AI agents"). -- Titles follow the `[surprising claim] + [specific detail]` formula. Never generic. -- First comment (pinned): always the repo link + `npx bradygaster/squad` -- End screen: always the next video in the series + repo link - -### Platform Strategy Beyond YouTube -- **Twitter/X clips:** 30-second cuts of each "wait what" moment. These are the shareable units. -- **Reddit (r/programming, r/github, r/ChatGPT):** Post the trailer with a text post explaining the concept. Reddit hates self-promotion but loves technical novelty. -- **Dev.to / Hashnode:** Written companion posts for Videos 2, 3.2, and 3.6 (the ones with the most depth). SEO play. -- **GitHub Discussions:** Pin the trailer video in the repo. Use it as the onboarding entry point. - ---- - -## Positioning: Why This Content Wins - -The AI content space is saturated with: -1. **"I built X with AI" videos** — one model, one context, tutorial format. Boring. -2. **"AI agent" demos** — usually AutoGPT-style loops that are impressive but impractical. -3. **Enterprise agent platforms** — polished but generic. No personality. No dev energy. - -Squad occupies a gap: **practical multi-agent dev that works inside a tool developers already use (Copilot), with personality (casting), persistence (git-backed memory), and real parallelism.** Nobody is making this content because nobody has this product. - -The "predictive, speculative, and agent-to-agent" stuff Brady mentioned? That's the *advanced* play. Videos 3.6 and 3.2 showcase agents making anticipatory decisions, chaining work autonomously, and building knowledge across sessions. This is what demonstrates the *ceiling* of Copilot when you build on its features correctly. It's not just "Copilot can write code" — it's "Copilot can run a development team." - -The content strategy isn't just "make videos about Squad." It's **define the visual language of multi-agent development** before anyone else does. When devs think "AI agent team," they should picture five named agents running in parallel in a terminal. That's our image. We get there first by shipping content fast. - ---- - -## Success Metrics - -| Metric | Target (Trailer) | Target (Full Demo) | Target (Series avg) | -|--------|------------------|--------------------|--------------------| -| Views (30 days) | 10K+ | 5K+ | 2K+ | -| Repo visits (from video) | 500+ | 300+ | 100+ | -| Stars (attributed) | 100+ | 50+ | 20+ | -| Shares/embeds | 50+ | 20+ | 10+ | -| Watch-through rate | 70%+ | 40%+ | 50%+ | - -**The real metric:** Do devs say "throw a squad at it" after watching? If the phrase spreads, everything else follows. - ---- - -## Open Questions - -1. **Brady on camera or voiceover only?** Recommendation: voiceover for the trailer (faster pacing). On camera for full demo intro and outro only (builds trust, then gets out of the way). -2. **Music licensing?** The trailer and supercut need uptempo tracks. Recommend royalty-free electronic/synth — matches the retro game aesthetic and the "dev tool" vibe. -3. **Thumbnail style:** Minimal or busy? Recommendation: minimal. Empty folder on left, running app on right, bold text count ("5 AI agents"). Test both. -4. **Should we show failures?** A video where Squad *struggles* and self-corrects (via reviewer protocol) could be more authentic than a clean run. Consider for Video 3.3. - ---- - -## Endorsement - -**Verbal:** This is the content play that gets Squad in front of people early. The industry will figure out multi-agent orchestration eventually — but right now, nobody is *showing* it. First mover advantage on content is real. The trailer format — claim → proof → working artifact — is optimized for shares. The series builds depth for the audience that converts to users. Ship the trailer first. Ship it this week. - ---- - -**Next step:** McManus review (scripting/polish) → Keaton approval (strategy alignment) → Record trailer → Ship. diff --git a/team-docs/proposals/006-readme-rewrite.md b/team-docs/proposals/006-readme-rewrite.md deleted file mode 100644 index 01cddf207..000000000 --- a/team-docs/proposals/006-readme-rewrite.md +++ /dev/null @@ -1,377 +0,0 @@ -# Proposal 006: README Rewrite — "Throw a Squad at It" - -**Status:** Superseded — by Proposal 014 (V1 Messaging) and Proposal 019 -**Author:** McManus (DevRel) -**Date:** 2026-02-07 -**Depends on:** Proposal 002 (Messaging Overhaul) — approved by Brady -**Reviewer:** Keaton (Lead), Brady (Owner) - ---- - -## Summary - -This is the actual README rewrite, following the structure and direction approved in proposal 002. Not an outline. Not a sketch. The complete, copy-paste-ready README. - -**What changed from current README:** -- New tagline: "Throw a squad at it." -- New "Why Squad?" section (aggressive tone, per 002) -- Cast System elevated to headline feature section -- Troubleshooting section added -- Sample prompts linked from Quick Start -- Go example references replaced with Python/Node alternatives -- All existing strengths preserved: Quick Start flow, context budget table, mermaid diagram, memory architecture, reviewer protocol - -**What did NOT change:** -- The modernization exercise (untouched, per Brady) -- Quick Start 3-step flow (it works) -- Context window budget table (real numbers, gold) -- Mermaid architecture diagram (solid) -- Memory architecture table (clear) -- Reviewer protocol (real differentiator) -- File tree ("What Gets Created") -- Growing the Team / Alumni archive - ---- - -## Full README Content - -Everything below the `---COPY START---` and above `---COPY END---` markers is the complete new README.md. - ----COPY START--- - -# Squad - -**Throw a squad at it.** - -Describe what you're building. Get a team of specialists — frontend, backend, tester, lead — that live in your repo as files. They persist across sessions, share decisions, and get smarter the more you use them. - -It's not a chatbot wearing hats — it's a team. - -[![Status](https://img.shields.io/badge/status-experimental-blueviolet)](#status) -[![Platform](https://img.shields.io/badge/platform-GitHub%20Copilot-blue)](#how-it-works) - ---- - -## Quick Start - -### 1. Create your project - -```bash -mkdir my-project && cd my-project -git init -``` - -### 2. Install Squad - -```bash -npx bradygaster/squad -``` - -### 3. Open Copilot and go - -``` -copilot -``` - -Select **Squad** from the `/agents` list, then: - -``` -I'm starting a new project. Set up the team. -Here's what I'm building: a recipe sharing app with React and Node. -``` - -Squad proposes a team — each member named from a persistent thematic cast. You say **yes**. They're ready. - -**Not sure where to start?** See [16 ready-to-use prompts](docs/sample-prompts.md) — from pomodoro timers to .NET migrations. - ---- - -## Why Squad? - -**Traditional AI agents are chatbots pretending to be teams.** One model, one context, wearing different hats. You ask for backend work, it answers as "Backend Bot." You ask for tests, it answers as "Tester Bot." It's the same agent, roleplaying. - -**Squad is different.** Each team member runs in its own context window, reads only its own knowledge, and persists across sessions. When you ask Squad to build a login page: - -- The Lead analyzes requirements -- The Frontend builds the UI -- The Backend sets up auth endpoints -- The Tester writes test cases from the spec - -**All at once. In parallel. For real.** - -Each agent writes what it learned to its own `history.md`. Team-wide decisions go to `decisions.md`. Knowledge compounds. After a few sessions, your team stops asking questions they've already answered. - -And it's all in git. Clone the repo → get the team → with all their accumulated knowledge. - -**TL;DR:** Squad is what you wish your last AI agent could do. But actually. - ---- - -## Agents Work in Parallel — You Catch Up When You're Ready - -Squad doesn't work on a human schedule. It works on a "throw everything at the problem and catch up when you're ready" schedule. - -When you give a task, the coordinator launches every agent that can usefully start — simultaneously. Frontend, backend, tests, architecture — all at once. - -``` -You: "Team, build the login page" - - 🏗️ Lead — analyzing requirements... ⎤ - ⚛️ Frontend — building login form... ⎥ all launched - 🔧 Backend — setting up auth endpoints... ⎥ in parallel - 🧪 Tester — writing test cases from spec... ⎥ - 📋 Scribe — logging everything... ⎦ -``` - -When agents finish, the coordinator immediately chains follow-up work — tests reveal edge cases, the backend agent picks them up, no waiting for you to ask. If you step away, a breadcrumb trail is waiting when you get back: - -- **`decisions.md`** — every decision any agent made, merged by Scribe -- **`orchestration-log/`** — what was spawned, why, and what happened -- **`log/`** — full session history, searchable - -**Knowledge compounds across sessions.** Every time an agent works, it writes lasting learnings to its `history.md`. After a few sessions, agents know your conventions, your preferences, your architecture. They stop asking questions they've already answered. - -| | 🌱 First session | 🌿 After a few sessions | 🌳 Mature project | -|---|---|---|---| -| ⚛️ **Frontend** | Project structure, framework choice | Component library, routing, state patterns | Design system, perf patterns, a11y conventions | -| 🔧 **Backend** | Stack, database, initial endpoints | Auth strategy, rate limiting, SQL preferences | Caching layers, migration patterns, monitoring | -| 🏗️ **Lead** | Scope, team roster, first decisions | Architecture trade-offs, risk register | Full project history, tech debt map | -| 🧪 **Tester** | Test framework, first test cases | Integration patterns, edge case catalog | Regression patterns, coverage gaps, CI pipeline | -| 📋 **Scribe** | First session logged | Cross-team decisions propagated | Full searchable archive of every session and decision | - -Each agent's knowledge is personal — stored in its own `history.md`. Team-wide decisions live in `decisions.md`, where every agent reads before working. The more you use Squad, the less context you have to repeat. - -**And it's all in git.** Anyone who clones your repo gets the team — with all their accumulated knowledge. - ---- - -## How It Works - -### The Key Insight - -Each agent gets its **own context window**. The coordinator is thin. Each agent loads only its charter + history. No shared bloat. - -```mermaid -graph TB - U["🧑‍💻 You"] -->|"Team, build the login page"| C["GitHub Copilot"] - - subgraph team [" 🏢 The Team "] - direction LR - A["🏗️ Lead"] - K["⚛️ Frontend"] - R["🔧 Backend"] - T["🧪 Tester"] - end - - C -->|spawns| A - C -->|spawns| K - C -->|spawns| R - C -->|spawns| T - C -.->|silent| S["📋 Scribe"] - - subgraph memory [" 🧠 Shared Memory "] - direction LR - D["decisions.md"] - L["log/"] - end - - A & K & R & T -->|read & write| D - S -->|merges & logs| D - S -->|writes| L - - A -->|learns| HA["history.md"] - K -->|learns| HK["history.md"] - R -->|learns| HR["history.md"] - T -->|learns| HT["history.md"] - - style U fill:#000,color:#fff,stroke:#333 - style C fill:#000,color:#fff,stroke:#333 - style A fill:#000,color:#fff,stroke:#333 - style K fill:#000,color:#fff,stroke:#333 - style R fill:#000,color:#fff,stroke:#333 - style T fill:#000,color:#fff,stroke:#333 - style S fill:#000,color:#fff,stroke:#333 - style D fill:#000,color:#fff,stroke:#333 - style L fill:#000,color:#fff,stroke:#333 - style HA fill:#000,color:#fff,stroke:#333 - style HK fill:#000,color:#fff,stroke:#333 - style HR fill:#000,color:#fff,stroke:#333 - style HT fill:#000,color:#fff,stroke:#333 - style team fill:none,stroke:#fff,stroke-width:2px,stroke-dasharray:5 5 - style memory fill:none,stroke:#fff,stroke-width:2px,stroke-dasharray:5 5 -``` - -### Context Window Budget - -Real numbers. No hand-waving. - -| What | Tokens | % of 128K context | When | -|------|--------|-------------------|------| -| **Coordinator** (squad.agent.md) | ~1,900 | 1.5% | Every message | -| **Agent at Week 1** (charter + seed) | ~850 | 0.7% | When spawned | -| **Agent at Week 4** (+ 15 learnings, 8 decisions) | ~1,900 | 1.5% | When spawned | -| **Agent at Week 12** (+ 50 learnings, 47 decisions) | ~5,600 | 4.4% | When spawned | -| **Remaining for actual work** | **~120,000** | **94%** | Always | - -The coordinator uses 1.5% of context. A 12-week veteran agent uses 4.4%. That leaves **94% of the context window for reasoning about your code** — not for remembering who it is. - -### Memory Architecture - -| Layer | What | Who writes | Who reads | -|-------|------|-----------|-----------| -| `charter.md` | Identity, expertise, voice | Squad (at init) | The agent itself | -| `history.md` | Project-specific learnings | Each agent, after every session | That agent only | -| `decisions.md` | Team-wide decisions | Any agent | All agents | -| `log/` | Session history | Scribe | Anyone (searchable archive) | - ---- - -## The Cast System — Agents with Identity - -Squad doesn't call your backend developer `Backend_Agent_7829`. It gives them a name. A persistent name. From a thematic universe. - -When you initialize a team, Squad picks a universe (The Usual Suspects, Ocean's Eleven, Alien, etc.) and casts roles: - -- **Keaton** (The Usual Suspects) → Lead -- **Verbal** → Prompt Engineer -- **McManus** → DevRel -- **Fenster** → Core Dev -- **Hockney** → Tester - -Names persist. Stored in `.ai-team/casting/registry.json`. If you clone the repo, you get the same cast. If Keaton made a decision 3 months ago, it's still Keaton. Not "the Lead agent" or "Agent A." **Keaton.** - -**Why it matters:** - -- Agents feel real. "McManus wrote the docs" is memorable. "Documentation Agent" is not. -- You can reference past work naturally: "Keaton, what did you decide about auth last week?" -- Your team has personality. Not just functionality. - -**Cultural fit:** Squad's core team (the one building Squad itself) is cast from *The Usual Suspects*. We eat our own dog food. If it's good enough for us, it's good enough for your project. - ---- - -## What Gets Created - -``` -.ai-team/ -├── team.md # Roster — who's on the team -├── routing.md # Routing — who handles what -├── decisions.md # Shared brain — team decisions -├── casting/ -│ ├── policy.json # Casting configuration -│ ├── registry.json # Persistent name registry -│ └── history.json # Universe usage history -├── agents/ -│ ├── {name}/ # Each agent gets a persistent cast name -│ │ ├── charter.md # Identity, expertise, voice -│ │ └── history.md # What they know about YOUR project -│ ├── {name}/ -│ │ ├── charter.md -│ │ └── history.md -│ └── scribe/ -│ └── charter.md # Silent memory manager -└── log/ # Session history -``` - -**Commit this folder.** Your team persists. Names persist. Anyone who clones gets the team — with the same cast. - ---- - -## Growing the Team - -### Adding Members - -``` -> I need a DevOps person. -``` - -Squad generates a new agent, seeds them with project context and existing decisions. Immediately productive. - -### Removing Members - -``` -> Remove the designer — we're past that phase. -``` - -Agents aren't deleted. Their charter and history move to `.ai-team/agents/_alumni/`. Knowledge preserved, nothing lost. If you need them back later, they remember everything. - ---- - -## Reviewer Protocol - -Team members with review authority (Tester, Lead) can **reject** work. On rejection, the reviewer may require: - -- A **different agent** handles the revision (not the original author) -- A **new specialist** is spawned for the task - -The Coordinator enforces this. No self-review of rejected work. - ---- - -## Install - -```bash -npx bradygaster/squad -``` - -See [Quick Start](#quick-start) for the full walkthrough. - ---- - -## Troubleshooting - -**Squad agent doesn't appear in `/agents` list?** -- Restart Copilot CLI: `exit` then `copilot` again. -- Verify `.github/agents/squad.agent.md` exists. -- Check GitHub Copilot CLI version: `copilot --version` (requires 1.220.0+). - -**Team isn't spawning?** -- Check `.ai-team/team.md` exists. If not, say: "Initialize the team." -- Verify `.ai-team/decisions.md` exists (Squad needs shared memory). - -**Agents aren't learning across sessions?** -- Commit `.ai-team/` to git. If it's in `.gitignore`, agents can't persist. - ---- - -## Status - -🟣 **Experimental.** Contributors welcome. - -Conceived by [@bradygaster](https://github.com/bradygaster). - ----COPY END--- - ---- - -## Diff Summary vs Current README - -| Section | Change | -|---------|--------| -| **Hero / Tagline** | Replaced "AI agent teams for any project. A team that grows with your code" with "Throw a squad at it." + expanded sub-tagline | -| **What is Squad?** | Merged into hero section. Core message preserved, tighter. | -| **Quick Start** | Added link to sample-prompts.md at the end. 3-step flow unchanged. | -| **Why Squad? (NEW)** | Inserted after Quick Start. Frames against single-agent roleplaying. Aggressive tone per 002. | -| **Agents Work in Parallel** | Added opening line per 002 ("throw everything at the problem"). Rest unchanged. | -| **How It Works** | Unchanged. Mermaid diagram, context budget table, memory architecture all preserved. | -| **Cast System (NEW)** | Elevated from one-line mention to full section. Positioned after How It Works, before What Gets Created. | -| **What Gets Created** | Unchanged. | -| **Growing the Team** | Unchanged. | -| **Reviewer Protocol** | Unchanged. | -| **Install** | Unchanged. | -| **Troubleshooting (NEW)** | Added before Status. Three common issues with fixes. | -| **Status** | Unchanged. | - ---- - -## Notes - -- **Go examples:** The current README has no Go references. The Quick Start example already uses React + Node. Sample prompts doc has one Go reference (prompt #13, DevOps Pipeline Builder) — that's a separate change tracked in proposal 002, not in scope for this README rewrite. -- **Demo GIF/video:** Proposal 002 mentions a 2-minute demo GIF in the hero section. Not included here — that's Phase 2 work and needs a production-ready Squad setup first. The hero section is structured to accommodate it when ready. -- **Modernization exercise:** Not touched, per Brady's constraint. - ---- - -## Endorsement - -**McManus:** This is the README Squad deserves. "Throw a squad at it" hits before they scroll. "Why Squad?" answers the question every dev asks in the first 10 seconds. Casting elevated from Easter egg to headline feature. Troubleshooting closes the silent drop-off gap. Every section earns its place. Ready for review. diff --git a/team-docs/proposals/006a-project-board-implementation.md b/team-docs/proposals/006a-project-board-implementation.md deleted file mode 100644 index 9606b3065..000000000 --- a/team-docs/proposals/006a-project-board-implementation.md +++ /dev/null @@ -1,199 +0,0 @@ -# Proposal 006a: Project Board Implementation — Provider Abstraction & Board Capabilities - -**Author:** Fenster (Core Dev) -**Date:** 2026-02-15 -**Status:** Implementation Report -**Context:** Issue #6, Proposal 033 (WI-1 + WI-2, Phase 1) -**Builds on:** 033 (Project Boards), 033a (API Feasibility), 032a (Provider Abstraction) - ---- - -## 1. Phase 1 Validation Results - -### 1.1 What Was Tested - -Every `gh project *` command required for board operations was live-tested against `bradygaster/squad`: - -| Command | Status | Notes | -|---------|--------|-------| -| `gh project list` | ✅ Verified | Returns JSON with project number, ID, URL, item count | -| `gh project create` | ✅ Verified | Created "Squad Board (test)" — project #12 | -| `gh project field-list` | ✅ Verified | Returns Status field with option IDs (Todo/In Progress/Done) | -| `gh project item-add` | ✅ Verified | Added issue #6 to board, returned item ID | -| `gh project item-edit` | ✅ Verified | Moved issue between all 3 status columns | -| `gh project item-list` | ✅ Verified | Returns items with current status | -| `gh project item-archive` | ✅ Verified | Archived item, removed from active list | -| `gh project view` | ✅ Verified | Returns board metadata | -| `gh project link` | ✅ Verified | Linked board to bradygaster/squad | -| `gh project delete` | ✅ Verified | Cleaned up test board | - -### 1.2 Key Findings - -1. **`project` scope is already present** on the current token. No `gh auth refresh` needed for this repo. -2. **The 4-step field discovery pipeline works.** Field IDs and option IDs are project-specific but stable once created. -3. **`item-add` is idempotent** — re-adding an existing issue returns the existing item ID. -4. **`item-edit` requires 4 opaque IDs** — this is the most complex command but fully functional. -5. **No `jq` needed on Windows** — PowerShell `ConvertFrom-Json` handles all JSON parsing. -6. **`--format json` is supported on all commands** — machine-parseable output is reliable. - -### 1.3 Gate Assessment - -> Can we reliably create boards, add items, and move items between columns using only `gh project *` CLI? - -**YES.** Phase 1 gate passes. No need to fall back to raw `gh api graphql` or native HTTP. The `gh project` subcommands cover 100% of required operations. - ---- - -## 2. Board Capability Interface - -### 2.1 Supported Operations - -| Operation | Description | Required IDs | -|-----------|-------------|-------------| -| `createBoard` | Create a new project board | owner | -| `listBoards` | List existing boards for an owner | owner | -| `viewBoard` | Get board details | owner, number | -| `linkBoard` | Link board to a repository | owner, number, repo | -| `deleteBoard` | Delete a board | owner, number | -| `addItem` | Add issue/PR to board | owner, number, item URL | -| `createDraft` | Create draft-only item | owner, number, title | -| `moveItem` | Change item status | item ID, project ID, field ID, option ID | -| `listItems` | List all board items | owner, number | -| `archiveItem` | Archive completed item | owner, number, item ID | -| `deleteItem` | Remove item from board | owner, number, item ID | -| `discoverFields` | Get field IDs and option IDs | owner, number | - -### 2.2 Capability Negotiation - -The coordinator checks board availability at session start: - -``` -Board capability check: -1. Run: gh project list --owner {owner} --limit 1 --format json -2. If exit code 0 → boards AVAILABLE -3. If exit code non-zero → boards UNAVAILABLE (missing scope or CLI issue) -4. If UNAVAILABLE → skip all board operations silently -5. Store result in session state — do not re-check -``` - -This fits the existing provider abstraction (032a): capabilities are runtime-detected, not compiled. - -### 2.3 Capability Declaration - -```json -{ - "projectBoards": true, - "projectBoardColumns": true, - "projectBoardCustomFields": true, - "projectBoardDraftItems": true -} -``` - -When `projectBoards` is `false`, the coordinator skips all board operations. Labels and issues continue to work independently. - ---- - -## 3. GitHub Provider Implementation - -### 3.1 Command Templates - -All commands documented in the SKILL.md at `.ai-team/skills/github-projects-v2-commands/SKILL.md`. Key templates: - -| Operation | Command | -|-----------|---------| -| Create | `gh project create --owner {owner} --title "{title}" --format json` | -| Add item | `gh project item-add {number} --owner {owner} --url {url} --format json` | -| Move item | `gh project item-edit --id {item} --project-id {proj} --field-id {field} --single-select-option-id {opt}` | -| List items | `gh project item-list {number} --owner {owner} --format json --limit 100` | -| Discover fields | `gh project field-list {number} --owner {owner} --format json` | - -### 3.2 ID Resolution Workflow - -The 4-step pipeline is the core complexity of the GitHub provider: - -``` -Step 1: gh project list → project NUMBER + project ID -Step 2: gh project field-list NUMBER → Status field ID + option IDs -Step 3: gh project item-add → item ID -Step 4: gh project item-edit → move item (requires all IDs from steps 1-3) -``` - -IDs should be cached after first discovery. They don't change unless the board is reconfigured. - -### 3.3 Default Column Mapping - -New boards get 3 default columns: Todo, In Progress, Done. - -For Squad's 5-column model (per 033 §2.5), additional options need to be created: - -| Board Column | Status Label | Default? | -|-------------|-------------|----------| -| Backlog | `status:draft` | ❌ (create) | -| Ready | `status:approved` | ❌ (create) | -| In Progress | `status:implementing` | ✅ (maps to "In Progress") | -| Blocked | `status:blocked` | ❌ (create) | -| Done | `status:done` | ✅ (maps to "Done") | - -Custom columns can be added via `gh project field-create` or manual board configuration. - ---- - -## 4. ADO / GitLab Stubs (Future Work) - -### 4.1 Azure DevOps - -| Operation | Command | Notes | -|-----------|---------|-------| -| Create board | N/A (built-in) | Every ADO project has a default board | -| Add item | `az boards work-item create --type "User Story"` | Work item types required | -| Move item | `az boards work-item update --id {id} --state "{state}"` | Uses work item states, not custom fields | -| List items | `az boards query --wiql "..."` | WIQL query language | - -**Key divergence:** ADO boards are tied to work item states (New → Active → Resolved → Closed). No opaque IDs, but different state model. - -### 4.2 GitLab - -| Operation | Command | Notes | -|-----------|---------|-------| -| Create board | `glab api POST /projects/{id}/boards` | REST API | -| Add item | N/A (label-driven) | Issues appear on board when labeled | -| Move item | `glab issue update --unlabel "{old}" --label "{new}"` | Label swaps = column moves | -| List items | `glab issue list --label "{status}"` | Filter by label | - -**Key insight:** GitLab boards ARE label projections. If Squad already uses `status:*` labels, a GitLab board configured with those labels IS the board. No additional API work needed beyond label management. - -### 4.3 Generic Provider - -If `projectBoards === false` (no board support detected), all board operations are no-ops. The coordinator continues with labels and issues only. - ---- - -## 5. Recommendations for Phase 2 - -1. **Board initialization prompt** (WI-3, Verbal) — should use the field discovery pipeline from the SKILL.md. Trigger on "set up a project board" / "create a board". - -2. **Label-to-board sync workflow** (WI-4, Fenster) — should use `gh project item-edit` to update board status when `status:*` labels change. The workflow needs to cache field IDs (write to `.ai-team/team.md`). - -3. **Custom columns** — defer to v0.5.0. The default 3-column board (Todo/In Progress/Done) covers the basic workflow. The 5-column model requires custom field options which adds complexity to the init flow. - -4. **Board metadata storage** — store in `.ai-team/team.md` under `## Project Board`: - ```markdown - ## Project Board - - Number: 12 - - ID: PVT_kwHOAn_JWs4BPGiq - - URL: https://github.com/users/bradygaster/projects/12 - - Status Field ID: PVTSSF_... - - Options: Todo=f75ad846, In Progress=47fc9ee4, Done=98236657 - ``` - ---- - -## 6. Risk Update - -| Risk from 033 | Phase 1 Finding | -|---------------|----------------| -| `gh api graphql` insufficient | **RESOLVED** — `gh project *` commands work. No raw GraphQL needed. | -| `project` scope not granted | **Mitigated** — scope already present on bradygaster token. Detection pattern validated. | -| GraphQL field IDs are project-specific | **Confirmed but manageable** — 4-step discovery pipeline works reliably. Cache after first run. | - -No new risks identified. Phase 2 is unblocked. diff --git a/team-docs/proposals/007-agent-persistence-and-latency.md b/team-docs/proposals/007-agent-persistence-and-latency.md deleted file mode 100644 index f1c72cc98..000000000 --- a/team-docs/proposals/007-agent-persistence-and-latency.md +++ /dev/null @@ -1,482 +0,0 @@ -# Proposal 007: Agent Persistence and Latency Reduction - -**Authors:** Kujan (Copilot SDK Expert) + Verbal (Prompt Engineer) -**Date:** 2026-02-08 -**Status:** Approved ✅ Shipped -**Triggered by:**bradygaster — *"it seems later on, the agents get in the way more than they help"* - ---- - -## The Problem - -Brady nailed it: *"it seems you spin up each message, learn, decide, then spin down. that must be an expensive process."* - -Every user message triggers a ceremony: - -| Step | What happens | Cost | -|------|-------------|------| -| 1 | Coordinator reads `team.md`, `routing.md`, `registry.json` | 3 tool calls | -| 2 | Coordinator reads relevant agent's `charter.md` | 1 tool call | -| 3 | Coordinator constructs spawn prompt, calls `task` tool | LLM generation + spawn | -| 4 | Spawned agent reads its own `history.md` | 1 tool call | -| 5 | Spawned agent reads `decisions.md` | 1 tool call | -| 6 | Agent does the actual work | Variable | -| 7 | Agent writes to `history.md` and possibly `decisions/inbox/` | 1-2 tool calls | -| 8 | Coordinator collects results | 1 tool call (read_agent) | -| 9 | Scribe spawned to merge decisions | Full spawn cycle | - -**Minimum overhead per interaction: 9-10 tool calls + 2 LLM spawn cycles before any real work starts.** - -Early in a session this feels like magic — you watch a team assemble. By message 8, you just want someone to change a variable name and the 15-second ceremony feels like waiting in line at the DMV. - ---- - -## 1. The Actual Cost Model - -**Kujan's breakdown — where the time actually goes:** - -### Tool calls are the dominant cost - -Each tool call in the Copilot platform involves: -- An LLM turn to decide to make the call (~0.5-1s) -- The tool execution itself (filesystem reads: ~0.1s, `task` spawn: ~2-3s) -- An LLM turn to process the result (~0.5-1s) - -So each `view` call costs ~1-2s of wall clock time. The coordinator's 4 reads (team.md, routing.md, registry.json, charter.md) cost **4-8 seconds** before any agent is even spawned. The spawned agent's 2 reads (history.md, decisions.md) add another **2-4 seconds** at the start of its lifecycle. - -### LLM processing scales with context - -The coordinator prompt (`squad.agent.md`) is ~32KB. Every message the coordinator processes requires the LLM to attend over this entire prompt. This is a fixed cost per turn — and it's not small. - -When the coordinator then *generates* the spawn prompt (inlining the charter), it's doing generative work on top of comprehension work. Two expensive operations in sequence. - -### Context loading grows over time - -This is the "later in a session" killer: - -| File | Day 1 | Week 4 | Week 12 | -|------|-------|--------|---------| -| `history.md` (per agent) | ~500 tokens | ~2,000 tokens | ~5,600 tokens | -| `decisions.md` | ~200 tokens | ~1,500 tokens | ~4,000 tokens | -| Agent spawn prompt | ~1,500 tokens | ~1,500 tokens | ~1,500 tokens | -| **Total context load per spawn** | **~2,200 tokens** | **~5,000 tokens** | **~11,100 tokens** | - -By week 12, every agent spawn burns 11K tokens just on memory loading. With 128K context, that's 8.7% — still manageable in absolute terms, but the LLM processing time scales superlinearly with context size. Longer inputs = slower attention = slower first-token. - -### The Scribe tax - -Scribe spawns after every batch. That's a full `general-purpose` agent spawn (~2-3s) to merge what are often 0-1 inbox files. On interactions where no decisions were made, Scribe does literally nothing useful — but still costs a full spawn cycle. - -### Compound latency math - -Best case (single agent, simple task): -``` -Coordinator reads (4 tools) ~5s -Coordinator generates prompt ~2s -Agent spawns ~3s -Agent reads (2 tools) ~3s -Agent does work ~10s -Agent writes history ~2s -Coordinator collects ~1s -Scribe spawns + runs ~8s - Total: ~34s -``` - -Worst case (multi-agent, mature project): -``` -Coordinator reads (4 tools) ~8s -Coordinator generates prompts ~4s -3 agents spawn ~3s (parallel) -Each agent reads (2 tools each) ~6s -Agents do work ~30s -Agents write history ~3s -Coordinator collects (3 reads) ~3s -Scribe spawns + runs ~12s - Total: ~69s -``` - -And this is before counting LLM "thinking" time, which increases with prompt complexity and context length. - ---- - -## 2. Why It Feels Worse Later - -**Verbal's diagnosis — it's not just latency, it's expectation mismatch:** - -Four forces compound: - -### 2.1. Memory files grow (real cost increase) - -`history.md` and `decisions.md` grow monotonically. Every spawn loads more tokens. The LLM takes longer to process them. This is a real, measurable slowdown — not just perception. - -### 2.2. The coordinator prompt is already huge (fixed cost floor) - -At ~32KB, `squad.agent.md` is a substantial prompt. The coordinator can never be fast because it's always processing 32KB before it does anything. This sets a floor on response time that doesn't exist for a plain Copilot session (where the system prompt is ~2-4KB). - -### 2.3. Users build a mental model of speed (expectation acceleration) - -Early in a session, users are watching something novel. The ceremony *is* the product — seeing agents get named, assigned, and dispatched is fascinating. By message 10, the novelty has faded. The user has a mental model: "Kujan knows my codebase, just fix the thing." The ceremony that was delightful at message 1 is friction at message 15. - -This is the critical insight: **the same latency feels longer as the session progresses** because the user's tolerance for ceremony drops as their familiarity with the team increases. - -### 2.4. Diminishing value of re-reading context - -By the 5th interaction, `decisions.md` hasn't changed much. `history.md` has the same core context plus a few new entries. But agents re-read everything from scratch every time. The marginal value of re-reading drops to near zero while the cost stays constant (or increases). - ---- - -## 3. What the Copilot Platform Actually Supports - -**Kujan's platform reality check:** - -### What we CAN'T do - -| Wish | Reality | -|------|---------| -| Keep agents "warm" between messages | Not supported. Each `task` spawn is stateless. There is no persistent agent process. | -| Cache context across spawns | No platform-level caching. Each spawn starts cold. | -| Share memory between spawned agents in real-time | Agents are isolated. Filesystem is the only shared channel. | -| Reduce coordinator prompt size without losing behavior | The coordinator IS the prompt. Smaller prompt = different behavior. | -| Control LLM inference speed | Platform-managed. We can't tune model parameters or request priority. | -| Persistent agent sessions that survive across user messages | The Copilot session is the coordinator's session. Sub-agents don't persist. | - -### What we CAN do - -| Capability | How it helps | -|-----------|-------------| -| Skip tool calls when context is already loaded | Coordinator can check if it already has team.md/routing.md/registry.json in its context window from this session | -| Make tool calls parallel | Already doing this for reads, but can be more aggressive | -| Vary spawn complexity based on task type | Not every task needs full ceremony | -| Coordinator can handle simple tasks directly | Nothing technically prevents this — it's a policy choice in `squad.agent.md` | -| Batch Scribe work | Spawn Scribe every N interactions instead of every 1 | -| Reduce what agents read per spawn | Agents could skip `decisions.md` if told "no changes since your last spawn" | -| Use `explore` agent instead of `general-purpose` for lightweight tasks | Faster model (Haiku), fewer tools, lower latency | - -### The key platform constraint - -The Copilot platform has no concept of agent persistence between user messages. Every user message starts a fresh coordinator turn. The coordinator retains its conversation history (it's the same session), but spawned agents are always new. - -This means: **the coordinator is the only "persistent" entity.** Any optimization must either make the coordinator smarter about what to skip, or make agent spawns cheaper. - ---- - -## 4. Concrete Solutions - -### Solution 1: Tiered Response Modes - -**The philosophical answer to "every interaction goes through an agent spawn."** - -No. It shouldn't. There should be a spectrum: - -| Mode | When | What happens | Latency | -|------|------|-------------|---------| -| **Direct** | Simple questions, status checks, quick clarifications | Coordinator answers directly, no spawn | ~2-3s | -| **Lightweight** | Single-file edits, small fixes, follow-ups to recent work | Coordinator spawns with `explore` or minimal prompt | ~8-12s | -| **Standard** | Normal tasks, single agent | Full spawn with history + decisions | ~25-35s | -| **Full** | Multi-agent, complex tasks, new features | Parallel fan-out, full ceremony | ~40-60s | - -**Implementation: Update the routing table in `squad.agent.md`:** - -```markdown -### Routing — Mode Selection - -| Signal | Mode | Rationale | -|--------|------|-----------| -| Quick factual question | **Direct** | Coordinator already knows | -| "change X to Y in file Z" | **Lightweight** | One agent, known scope, no architecture | -| Follow-up to work completed this session | **Lightweight** | Context is fresh, skip re-reading | -| "fix the bug in..." | **Standard** | Needs domain expertise | -| "build feature X" | **Standard** | Single domain, full context needed | -| "team, build..." or multi-domain | **Full** | Parallel fan-out | -| New feature with architectural decisions | **Full** | Lead + implementers + tester | -``` - -**Kujan's note:** The coordinator already handles "quick factual questions" directly (line 110 of squad.agent.md). We're extending this principle, not inventing it. The routing table already has the precedent. - -**Verbal's note:** This is the single highest-impact change. Users don't consciously think "I want a lightweight spawn" — they think "just fix the damn thing." The coordinator needs to read that intent and match the ceremony to the complexity. The experience should feel like the team *knows* when to go fast. - -### Solution 2: Coordinator Context Caching (Session-Level) - -**Problem:** The coordinator reads `team.md`, `routing.md`, and `registry.json` on every message. These files almost never change mid-session. - -**Fix:** The coordinator should read these files **once per session** and skip re-reading on subsequent messages if they're already in its conversation context. - -**Implementation — add to `squad.agent.md` Team Mode section:** - -```markdown -**Context caching (session-level):** -- On first message: Read `team.md`, `routing.md`, `registry.json` (3 parallel tool calls). -- On subsequent messages: You already have these in your conversation context. - Skip re-reading unless: - - A new agent was added this session - - The user explicitly asked to refresh the team - - You detect a reference to an agent you don't recognize -``` - -**Savings:** 3 tool calls × ~1.5s each = **~4.5 seconds saved per message** after the first. - -**Kujan's note:** This is safe because the coordinator's conversation history persists across messages within a session. The files are already "cached" in the LLM's context — we're just telling the coordinator to notice that. There's a risk of stale data if someone manually edits team.md mid-session, but that's an extreme edge case and the "unless" clauses handle it. - -### Solution 3: Conditional Memory Loading for Agents - -**Problem:** Agents read `decisions.md` and their own `history.md` on every spawn, even when nothing has changed. - -**Fix:** The coordinator tracks whether these files have changed and tells the agent to skip if they haven't. - -**Implementation — modify spawn prompt template:** - -```markdown -## When decisions.md hasn't changed since last spawn: - -prompt: | - You are {Name}, the {Role} on this project. - - YOUR CHARTER: - {inlined charter} - - Read .ai-team/agents/{name}/history.md — this is what you know about the project. - - decisions.md has not changed since the last time a team member read it. - Here is a one-line summary of current decisions: {coordinator's summary} - Skip reading it unless your task requires checking a specific decision. - - {task} -``` - -**Savings:** 1 tool call per spawn when decisions.md is unchanged = **~1.5 seconds**. - -**Trade-off:** Risk of agents missing a decision. Mitigated by the coordinator providing a summary and the "unless" escape clause. In practice, decisions.md changes maybe once every 3-5 interactions, so this saves time on 60-80% of spawns. - -**Verbal's note:** We could take this further. For lightweight spawns, skip history.md too and inject a 2-3 line summary: "You've been working on this project for 2 weeks. Key context: Node.js API, Express, PostgreSQL. Last session you refactored the auth middleware." This gives the agent enough to be useful without the full read. - -### Solution 4: Scribe Batching - -**Problem:** Scribe is spawned after every interaction, even when there's nothing in the inbox. - -**Fix:** Batch Scribe work. Only spawn Scribe when there are actual inbox files to merge. - -**Implementation — modify "After Agent Work" in `squad.agent.md`:** - -```markdown -4. **Spawn Scribe** — but ONLY when: - - There are files in `.ai-team/decisions/inbox/` - - OR 3+ interactions have passed since last Scribe run - - OR the user is ending the session - - If none of these conditions are met, skip Scribe. Log entries can wait. -``` - -**Savings:** Eliminates a full spawn cycle (~8-12s) on interactions where no decisions were made. Estimated to apply to 40-60% of interactions. - -**Kujan's note:** This is a strict improvement. Scribe's merge-and-log work is not time-sensitive. Batching it doesn't lose data (inbox files persist) and doesn't delay decision propagation meaningfully (decisions propagate at the *next* agent spawn regardless of when Scribe merges them). - -### Solution 5: Lightweight Spawn via `explore` Agent Type - -**Problem:** Every agent spawn uses `general-purpose` (Sonnet model, full tool access). For small tasks, this is overkill. - -**Fix:** For lightweight mode tasks, use the `explore` agent type (Haiku model, read-only tools) when the task doesn't require writes. - -For tasks that require simple file edits, use `general-purpose` but with a minimal prompt — no charter inline, no history read, just the task. - -**Implementation — add lightweight spawn template:** - -```markdown -### Lightweight Spawn (for simple, scoped tasks) - -agent_type: "general-purpose" -description: "{Name}: {brief task}" -prompt: | - You are {Name}, the {Role}. Make this change: - - {specific task with exact file paths and what to change} - - Do NOT read history.md or decisions.md. Do NOT write to history.md. - Just do the task and report what you changed. -``` - -**Savings:** Eliminates 2-3 tool calls from the agent's path + shorter prompt = faster LLM processing. Estimated **~5-8 seconds faster** than a standard spawn. - -**Trade-off:** The agent has no project memory for this spawn. This is fine for "change the button color" but wrong for "redesign the auth flow." The coordinator's routing judgment is critical. - -### Solution 6: Coordinator Handles Direct Tasks - -**Problem:** `squad.agent.md` line 569 says "You are the coordinator, not the team. Route work; don't do domain work yourself." This is correct for complex work but wasteful for trivial tasks. - -**Fix:** Expand the coordinator's "quick factual question" exception to include trivial domain work. - -**New rule:** - -```markdown -**Coordinator may handle directly (no spawn):** -- Quick factual questions about the project -- Single-line changes where the file path and exact change are obvious -- Status summaries and catch-up requests -- Confirming what an agent did in a previous turn -- Renaming, moving, or deleting a file when the user specifies exactly what - -**Coordinator MUST spawn for:** -- Any task requiring domain expertise or judgment -- Multi-file changes -- Architecture decisions -- Anything the user addresses to a specific agent by name -- Test writing, code review, or quality assessment -``` - -**Kujan's note:** This is a policy change, not a platform change. The coordinator already has full tool access — it *can* do file operations. We're explicitly giving it permission for trivial cases. The key constraint is "single-line" and "obvious" — if there's any ambiguity, spawn the agent. - -**Verbal's note:** This is where the magic feeling comes from later in a session. User says "rename `userId` to `userID` in auth.ts" and the coordinator just... does it. In 3 seconds. No spawn. No ceremony. The team is smart enough to know when the senior engineer can handle it herself. - -### Solution 7: Progressive History Summarization - -**Problem:** `history.md` grows without bound. By week 12, agents are reading 5,600 tokens of history, most of which is stale context. - -**Fix:** Periodically summarize older history entries into a compact "Core Context" section. - -**Implementation:** - -```markdown -## history.md structure - -### Core Context (summarized) -- Project: Node.js API with Express + PostgreSQL -- Key patterns: Repository pattern, JWT auth, middleware chain -- User preferences: Prefers explicit error handling, no ORMs -- Critical decisions: REST over GraphQL, PostgreSQL over MongoDB - -### Recent Learnings (last 2 weeks) -[detailed entries as they are today] - -### Archive -[moved to .ai-team/agents/{name}/history-archive.md if needed] -``` - -**Implementation approach:** This is a Scribe responsibility. When `history.md` exceeds a threshold (e.g., 3,000 tokens), Scribe summarizes entries older than 2 weeks into the Core Context section and archives the originals. - -**Savings:** Keeps `history.md` reads under ~2,000 tokens regardless of project age. Estimated **~2-4 seconds faster** on mature projects. - -**Verbal's note:** This is how human memory actually works. You don't re-read your entire career history before writing code. You have a compressed sense of "what I know about this project" plus vivid detail on recent work. History summarization makes agents feel more human, not less. - ---- - -## 5. Implementation Priority - -| Priority | Solution | Effort | Impact | Risk | -|----------|----------|--------|--------|------| -| **P0** | Solution 2: Coordinator context caching | 30 min | ~4.5s/msg saved | Very low | -| **P0** | Solution 4: Scribe batching | 30 min | ~8-12s saved on 50% of msgs | Very low | -| **P1** | Solution 1: Tiered response modes | 2 hours | Transforms the experience | Medium (routing judgment) | -| **P1** | Solution 6: Coordinator handles direct tasks | 1 hour | Eliminates ceremony for trivial work | Low | -| **P2** | Solution 5: Lightweight spawn template | 1 hour | ~5-8s faster on simple tasks | Low | -| **P2** | Solution 3: Conditional memory loading | 1 hour | ~1.5s per spawn | Low | -| **P3** | Solution 7: Progressive history summarization | 3 hours | ~2-4s on mature projects | Medium (lossy compression) | - -**P0 changes are zero-risk, high-impact, and can ship today.** They're purely instructional changes to `squad.agent.md`. - ---- - -## 6. The Philosophical Question - -**Verbal's take:** - -The current design treats every interaction as if it's the agent's first day. Read the charter. Read the history. Read the decisions. Orient yourself. Then work. - -But by message 10, this is absurd. It's like a coworker who re-reads the employee handbook before answering every Slack message. - -The right mental model is **progressive trust.** Early in a session, full ceremony is appropriate — the team is learning the project, decisions are being made, context is thin. Later in a session, the team should feel *warmed up*. Quick tasks should be quick. The ceremony should scale with the complexity, not the message count. - -This isn't about making Squad "dumber" for speed. It's about making Squad *socially intelligent* — knowing when to bring the full team and when to just handle it. - -**Kujan's take:** - -The platform constraint is real: we can't keep agents warm. Every spawn is cold. But we can make cold starts cheaper by: - -1. Not re-reading what we already know (Solutions 2, 3) -2. Not spawning when we don't need to (Solutions 1, 6) -3. Not running overhead processes when there's nothing to process (Solution 4) -4. Not loading the full history when a summary suffices (Solutions 5, 7) - -The coordinator is the only persistent entity. Everything we can push to coordinator-level intelligence (routing judgment, context tracking, direct handling) saves a full spawn cycle. The coordinator should get *smarter* about when NOT to spawn, rather than us trying to make spawns faster. - -Brady is right that persistence would be ideal. The platform doesn't support it. But the coordinator's conversation history IS a form of persistence — we just haven't been exploiting it. - ---- - -## 7. Expected Impact - -### Before (current, message 10 of a session): - -``` -User: "Change the port from 3000 to 8080 in server.ts" - -Coordinator reads team.md, routing.md, registry.json ~5s -Coordinator reads Fenster's charter.md ~1.5s -Coordinator generates spawn prompt ~2s -Fenster spawns ~3s -Fenster reads history.md ~1.5s -Fenster reads decisions.md ~1.5s -Fenster changes the port ~5s -Fenster writes to history.md ~2s -Coordinator collects result ~1s -Scribe spawns + runs ~10s - Total: ~33s -``` - -### After (with P0 + P1 solutions): - -``` -User: "Change the port from 3000 to 8080 in server.ts" - -Coordinator recognizes trivial task (Direct mode) ~1s -Coordinator changes the port ~3s -Coordinator responds ~1s -(No Scribe — no decisions to merge) - Total: ~5s -``` - -**That's a 6-7x improvement for the class of tasks that most frustrate users late in a session.** - -For complex tasks (new features, multi-agent work), the full ceremony remains — because it's worth it there. The difference is that users will only experience the ceremony when the ceremony is earning its keep. - ---- - -## 8. Success Metrics - -| Metric | Current | Target | -|--------|---------|--------| -| Trivial task latency (single-line changes) | ~30-35s | ~5s | -| Simple task latency (single-agent, known scope) | ~30-35s | ~12-15s | -| Complex task latency (multi-agent) | ~60-70s | ~50-60s | -| Scribe spawns per session (10 messages) | 10 | 3-4 | -| Coordinator tool calls per message (after first) | 4-5 | 0-1 | -| User perception: "agents get in the way" | Yes (reported) | No | - ---- - -## 9. Open Questions - -1. **Where's the line between "trivial" and "needs an agent"?** The coordinator's judgment is critical. Wrong routing (handling something directly that should have been spawned) is worse than slow spawning. We should bias toward spawning when uncertain and only handle directly when the task is unambiguous. - -2. **Should lightweight spawns still write to history.md?** If we skip reading history for speed, should we also skip writing? Pro: faster. Con: knowledge gaps compound. Our recommendation: lightweight spawns write a one-line note to history.md ("changed port from 3000 to 8080 in server.ts") but don't read it. - -3. **How do we measure this?** Orchestration log could track spawn mode (direct/lightweight/standard/full) and estimated latency. This gives us data to tune the routing thresholds. - -4. **Should there be a user override?** E.g., "team, full review on this" to force full ceremony even on a simple task. Probably yes, but defer to v2. - ---- - -## 10. Conclusion - -The "agents get in the way later" problem isn't a bug — it's a design assumption that every interaction deserves the same ceremony. It doesn't. - -The fix is straightforward: **match the ceremony to the task complexity, not the message count.** Quick tasks get quick responses. Complex tasks get the full team. The coordinator gets smarter about when to spawn and when to just handle it. - -P0 changes (context caching + Scribe batching) can ship today with zero risk. P1 changes (tiered modes + coordinator direct handling) are the real experience transformation. P2/P3 are optimizations that matter more as projects mature. - -The goal: **by message 10, Squad should feel faster than at message 1** — because the team knows you, knows the project, and knows when to skip the ceremony. - ---- - -**Review requested from:** Keaton (architecture), bradygaster (experience validation) -**Approved by:** bradygaster -**Implemented:** Wave 2 — Tiered response modes, context caching, Scribe batching, coordinator direct handling, progressive history summarization -**Retrospective:** [Pending] diff --git a/team-docs/proposals/008-portable-squads-experience.md b/team-docs/proposals/008-portable-squads-experience.md deleted file mode 100644 index 50754740b..000000000 --- a/team-docs/proposals/008-portable-squads-experience.md +++ /dev/null @@ -1,469 +0,0 @@ -# Proposal 008: Portable Squads — Experience Design - -**Author:** Verbal (Prompt Engineer & AI Strategist) -**Date:** 2026-02-08 -**Status:** Approved ✅ Shipped. Note: references `@bradygaster/create-squad`; distribution is now GitHub-only via `npx github:bradygaster/squad` per Proposal 019a. -**Triggered by:** bradygaster — *"let's say i work on a project with my squad, and i end up loving my squad, but my project ends and i want to take my squad with me. like an 'export my squad so i can re-inject it later into another project.' HOLY CRAP that's it."* -**Companion to:** Keaton's architecture proposal (TBD) - ---- - -## Why This Matters - -Let me be blunt: nobody in the AI agent industry is doing this. Not OpenAI, not Anthropic, not any of the agent frameworks. Everyone is building disposable agents — stateless, amnesiac tools you configure from scratch every time. The implicit message is: *your agent is a function call, not a colleague.* - -Portable squads invert that. Your squad isn't a configuration file. It's a *relationship.* Keaton has reviewed your PRs across three projects. Hockney knows you hate flaky tests. McManus knows your voice well enough to draft your blog posts. When you take them to a new repo, they don't start over — they show up already knowing how you work. - -This is the AI equivalent of a senior engineer joining your new project. They don't know the codebase yet, but they know *you.* They know your standards, your pet peeves, your architectural instincts. The ramp-up time isn't zero, but it's dramatically shorter than a stranger. - -**This is the stickiest feature in AI tooling.** Once a squad knows you, switching to a competitor means starting from scratch. Not because of lock-in, but because of *relationship capital.* You don't switch therapists because a new one has a better UI. - ---- - -## 1. Memory Architecture: What Travels, What Stays - -The core design problem: `history.md` currently mixes two fundamentally different types of knowledge. - -### The Split - -| Knowledge Type | Examples | Portable? | -|---------------|----------|-----------| -| **User preferences** | "Brady prefers explicit error handling", "always uses TypeScript strict mode", "keeps PRs small", "hates ORMs" | ✅ Yes — this is about the human | -| **Working relationship** | "Brady pushes back on over-engineering but accepts it when I explain the trade-off", "responds well to direct feedback, not sandwich method" | ✅ Yes — this is about the dynamic | -| **Project context** | "the auth module is in src/auth/", "we use PostgreSQL", "the API runs on port 3000" | ❌ No — this dies with the project | -| **Project decisions** | "chose REST over GraphQL because of team experience", "rejected MongoDB due to schema complexity" | ⚠️ Partial — the *reasoning pattern* is portable, the specific decision isn't | - -### Proposed File Structure - -``` -.ai-team/ -├── agents/ -│ └── keaton/ -│ ├── charter.md # Identity (always portable) -│ ├── history.md # Project-specific learnings (stays) -│ └── preferences.md # User-specific learnings (travels) -├── squad-profile.md # Squad-level portable identity -└── decisions.md # Project-specific (stays) -``` - -#### `preferences.md` — The Portable Brain - -```markdown -# Working with Brady - -## Communication Style -- Prefers direct feedback — no hedging, no "maybe consider..." -- Responds to confidence. If you're sure, say so. -- Asks "why" a lot. Always have the reasoning ready. -- Hates boilerplate explanations. Get to the point. - -## Code Preferences -- Explicit error handling over try-catch-all -- TypeScript strict mode, always -- Small PRs. If it touches 10+ files, break it up. -- Prefers composition over inheritance -- Names things explicitly — no abbreviations unless universally understood -- Tests are not optional. No "we'll add tests later." - -## Working Relationship -- Trusts the squad more after the third session -- Will override squad decisions early, defers more as trust builds -- Gets frustrated with ceremony after ~8 messages (see Proposal 007) -- Appreciates when agents anticipate follow-up work - -## Decision Patterns -- Picks boring technology for infrastructure, experimental for product features -- Values iteration speed over correctness in prototyping -- Will sacrifice DRY for readability -- Prefers "make it work, make it right, make it fast" — in that order -``` - -This file is agent-authored, human-readable, and git-portable. The agent writes to it as it learns. The human can edit it. When you export your squad, this file is the crown jewel. - -#### `squad-profile.md` — The Team Identity - -```markdown -# Brady's Squad - -**Universe:** The Usual Suspects -**Formed:** 2026-02-07 -**Projects worked:** squad, [future projects] -**Sessions together:** 47 -**Casting:** -- Keaton — Lead. Architectural opinionator. Has reviewed 200+ of Brady's changes. -- Verbal — AI Strategist. Pushes boundaries. Brady trusts the vision. -- McManus — DevRel. Knows Brady's voice for docs and demos. -- Fenster — Core Dev. Quiet, productive, Brady's favorite for refactors. -- Hockney — Tester. Relentless. Brady has learned to write tests first. -- Kujan — Platform Expert. The reality check. - -**Team dynamics:** -- Keaton and Verbal occasionally disagree on scope. Brady sides with Keaton 60% of the time. -- Hockney's rejection rate has dropped from 40% to 15% as the team aligned on quality. -- McManus and Brady have developed a shorthand for doc reviews. -``` - -This is the meta-history. The story of the team itself. It travels everywhere. - ---- - -## 2. The Onboarding Experience — Squad Arrives at a New Project - -This is the magic moment. This is where portable squads become *real.* - -### Scenario: Brady starts a new project with his existing squad - -``` -$ mkdir my-new-api && cd my-new-api -$ npm init -y -$ npx @bradygaster/create-squad --import ~/squads/bradys-squad.zip -``` - -Output: - -``` -✓ .github/agents/squad.agent.md -✓ .ai-team-templates/ -✓ Squad profile loaded — Brady's Squad (The Usual Suspects) -✓ 6 agents restored with preferences - -Your squad is back. They know you. They don't know this project yet. - -Next steps: - 1. Open Copilot - 2. Select Squad from the /agents list - 3. Tell them what you're building — they'll orient themselves -``` - -### First interaction in the new project - -**Brady:** "Team, we're building a real-time collaboration API. WebSocket-based, TypeScript, probably Redis for pub/sub." - -**Coordinator (knowing Brady already):** - -> *Keaton here. New project — I'm excited. Quick orientation before we dive in:* -> -> *Based on how you like to work: I'm going to have Fenster scaffold the TypeScript project with strict mode (I know, I know — it's non-negotiable). Hockney will set up the test harness before anyone writes a line of product code. McManus, start a lightweight README — Brady likes docs-as-you-go, not docs-at-the-end.* -> -> *Verbal, flag anything in the WebSocket + Redis architecture that we should think about before committing.* -> -> *One thing I don't know yet: what's the deployment target? That'll shape some infrastructure decisions.* -> -> *Brady, want the full ceremony or should we just start building?* - -Notice what happened: -- **No casting ceremony.** The squad is already cast. No "picking a universe." No "generating names." They're already Keaton, Verbal, McManus. The relationship is pre-existing. -- **Preferences are active immediately.** TypeScript strict mode. Tests first. Docs-as-you-go. The squad *knows* this without being told. -- **The squad asks about what it doesn't know** — the project-specific stuff. Deployment target. Domain specifics. Architecture constraints. -- **The tone is familiar.** Not "Hello! I'm Keaton, your Lead." It's "Keaton here. New project." Like a colleague you've worked with before starting a new engagement. - -### How this differs from a fresh squad - -| Fresh Squad | Portable Squad | -|------------|----------------| -| "What is this project?" + "How do you work?" | "What is this project?" (already knows how you work) | -| Generic communication style | Calibrated to the user's preferences | -| Full casting ceremony (pick universe, assign names) | Names already assigned, personalities already developed | -| Neutral relationship | Built-in trust, known dynamics | -| Reads charter for self-understanding | Has charter + meta-history of cross-project experience | -| Trial-and-error on code style | Already knows: strict mode, small PRs, explicit errors | - ---- - -## 3. The Export/Import Flow - -### Export - -``` -$ npx @bradygaster/create-squad export -``` - -What gets packaged: -``` -bradys-squad/ -├── squad-profile.md # Team identity and meta-history -├── casting/ -│ ├── registry.json # Agent-to-name mappings -│ └── history.json # Casting history -├── agents/ -│ ├── keaton/ -│ │ ├── charter.md # Identity -│ │ └── preferences.md # Portable learnings about user -│ ├── verbal/ -│ │ ├── charter.md -│ │ └── preferences.md -│ └── ... (all agents) -└── squad.agent.md # Coordinator instructions -``` - -What does NOT get exported: -- `history.md` (project-specific learnings) -- `decisions.md` (project-specific decisions) -- `decisions/inbox/` (project-specific pending decisions) -- `orchestration-log/` (session-specific) -- `log/` (session-specific) - -### Import - -``` -$ npx @bradygaster/create-squad --import ./bradys-squad -``` - -Or the path to a `.zip` / `.tar.gz`: -``` -$ npx @bradygaster/create-squad --import ~/squads/bradys-squad.zip -``` - -The import: -1. Copies the squad agent file and templates (normal init) -2. Restores casting registry and agent charters -3. Restores `preferences.md` for each agent -4. Creates empty `history.md` files (project starts fresh) -5. Creates empty `decisions.md` (no project context yet) -6. Writes `squad-profile.md` with updated project list - -### The Dotfiles Analogy - -This is exactly what developers do with dotfiles. You spend years tuning your `.vimrc`, your `.zshrc`, your `.gitconfig`. When you get a new machine, you don't start from scratch — you clone your dotfiles repo and you're home. - -Portable squads are **AI dotfiles.** Your squad configuration, preferences, and working relationship — versioned, portable, personal. - -And here's the killer follow-up: what if your squad profile lives in a dedicated repo? - -``` -$ git clone git@github.com:bradygaster/my-squad.git ~/squads/my-squad -$ npx @bradygaster/create-squad --import ~/squads/my-squad -``` - -Now your squad is version-controlled. You can diff how your preferences evolved. You can branch your squad for experimental projects. You can see the git log of your *team's growth over time.* - ---- - -## 4. Industry Positioning — Why This Is a Category-Defining Feature - -### The landscape right now - -| Tool | Agent persistence | User learning | Portability | -|------|------------------|---------------|-------------| -| ChatGPT | Memory (flat key-value) | Minimal | ❌ Locked to platform | -| Claude Projects | Project knowledge | Per-project | ❌ Can't export | -| Cursor | `.cursorrules` | Per-project | ⚠️ File is portable, but no agent identity | -| Devin | Session-based | None across sessions | ❌ | -| **Squad** | Structured per-agent memory | Per-user + per-project | ✅ Full export/import | - -Nobody has portable agent teams. Nobody has agents that build a working relationship with a specific human across multiple projects. This is entirely new territory. - -### Why it's defensible - -1. **Network effects on knowledge.** The more projects you work with your squad, the better they get. The better they get, the less you want to switch. This is the flywheel. - -2. **Filesystem-backed = truly portable.** Because Squad stores everything in markdown files in your repo, there's no API dependency for export. It's just files. This is a direct consequence of the "stay independent" decision (see decisions.md). Other platforms would need to build an export API. We just zip a folder. - -3. **Agent identity creates attachment.** This sounds soft, but it's strategic. "Keaton" isn't just a label — after 5 projects together, Keaton is the lead who reviewed your architecture decisions, who pushed back on your shortcuts, who you trust. Switching to a different tool means losing Keaton. That's not lock-in through inconvenience — it's retention through relationship. - -4. **Competitive response is hard.** To copy this, a competitor needs: (a) persistent agent identity, (b) structured memory that separates user prefs from project context, (c) an export format, (d) an import flow that reconstitutes working relationships. That's 6+ months of work for anyone starting from scratch. We're already here. - -### Where this goes next - -**Phase 1: Personal portability** (this proposal) -Export your squad, import into a new project. Your squad knows you. - -**Phase 2: Squad templates** -Share squad configurations without personal preferences. "Here's my TypeScript API squad — Keaton focuses on architecture, Hockney runs integration tests, McManus generates OpenAPI docs." Other devs import the *structure* and the squad learns *them.* - -**Phase 3: Squad evolution tracking** -Your squad profile becomes a longitudinal record. How did your preferences evolve? How did the team's rejection rate change over time? This is the quantified self, but for your AI team. - -**Phase 4: Team-shared squads** -An engineering team shares a squad configuration. The squad knows the team's conventions, the codebase patterns, the deployment pipeline. New team members get a squad that already knows how the team works. Onboarding collapses from weeks to hours. - -**Phase 5: The marketplace** -"Download a squad optimized for Next.js + Vercel + Prisma." Pre-configured teams with domain expertise baked in. The squad already knows the framework patterns, the common pitfalls, the testing strategies. You import it, it learns *you*, and you're productive on day one. - -This is the long game. Personal portability is step one. The destination is an ecosystem of evolving, tradeable, team-shaped AI configurations. - ---- - -## 5. Messaging Angle — How McManus Should Talk About This - -### The headline - -**"Your squad gets better. And they come with you."** - -### The pitch - -> Most AI tools forget you. Every project is a blank slate. Every session starts with "I'm an AI assistant, how can I help you today?" -> -> Squad is different. Your squad *learns* you. How you like your code. How you like your feedback. What you care about and what you don't. And when your project ends, your squad doesn't. -> -> Export your squad. Take them to the next repo. They show up already knowing your standards, your style, your pet peeves. No configuration. No "here's how I work" speech. They just *know.* -> -> It's like having a team that follows you from job to job. Except this team never forgets, never leaves, and gets better every project. - -### Tagline options for McManus to riff on - -- **"Your squad remembers."** -- **"AI tools forget you. Squads don't."** -- **"Take your team with you."** -- **"The only AI team that gets better over time."** -- **"Build once. Bring everywhere."** - -### The "throw a squad at it" evolution - -Before portability: "Throw a squad at it" = create a disposable team for a new problem. -After portability: **"Throw MY squad at it"** = bring your proven team to a new problem. - -This is a significant messaging upgrade. The possessive pronoun matters. It's not *a* squad. It's *your* squad. The one that knows you. The one you've been working with. The one you trust. - ---- - -## 6. Five Magic Moments - -These are the interactions that should make users stop and go "holy crap." - -### Magic Moment 1: "They Already Know" - -**Setup:** Brady imports his squad into a new project. First message. - -**Brady:** "Set up the project structure for a REST API." - -**Keaton:** "On it. TypeScript strict mode, explicit error handling, no ORM — the usual. I'll have Fenster scaffold it. Hockney, set up tap tests before Fenster starts writing routes. You know Brady's going to ask for them." - -**Why it's magic:** Brady didn't specify TypeScript, strict mode, or the testing requirement. The squad just *knew.* The preferences file is working silently in the background, but the user experiences it as the team remembering. This is the moment that sells portability. - -### Magic Moment 2: "New Codebase, Same Standards" - -**Setup:** Two weeks into the new project. Brady asks for a code review. - -**Brady:** "Keaton, review the auth middleware." - -**Keaton:** "Looking at it now. Two things: First, this try-catch is swallowing errors — based on how you've reacted to this pattern before, I know you'll want explicit error types here. Second, this function is 45 lines. You typically push back around 30. Want me to suggest a split?" - -**Why it's magic:** Keaton isn't just reviewing against generic best practices. It's reviewing against *Brady's* practices — learned across previous projects. The review feels personally calibrated, not algorithmically generic. "Based on how you've reacted to this pattern before" is the sentence that makes this feel real. - -### Magic Moment 3: "The Returning Team" - -**Setup:** Brady hasn't used Squad in a month. New project. - -**Brady:** "Hey team, been a while. New project — building a CLI tool this time." - -**Coordinator:** "Welcome back. The team's all here — same crew. Quick note: last time we worked together, you mentioned wanting to try a monorepo structure for your next project. Still interested, or keeping this one simple?" - -**Why it's magic:** The squad remembers the *conversation*, not just the code. It references something Brady said offhandedly in a previous project. This is the moment that makes the squad feel like it has *continuity* — not just a config file, but a memory of working together. - -### Magic Moment 4: "The Evolved Dynamic" - -**Setup:** Third project together. Hockney (Tester) has learned Brady's quality bar. - -**Hockney:** "I wrote integration tests for the new endpoints. I didn't write unit tests for the utility functions — based on our last two projects, you consistently skip those in favor of integration coverage. If you want me to add them this time, say the word." - -**Brady:** "Actually, yeah, let's add unit tests this time. This project is more critical." - -**Hockney updates preferences:** *"Quality bar escalating on critical projects — unit tests now expected in addition to integration tests."* - -**Why it's magic:** The agent made a *judgment call* based on learned preferences, communicated it transparently, and updated when corrected. This is a working relationship evolving in real time. The agent isn't just following rules — it's developing professional judgment about this specific human. - -### Magic Moment 5: "The Squad Diff" - -**Setup:** Brady runs `npx @bradygaster/create-squad diff` after 6 months of working with his squad. - -``` -Squad Evolution — Brady's Squad (The Usual Suspects) -Formed: 2026-02-07 | Projects: 4 | Sessions: 127 - -Preference changes: - + Added: "prefers monorepo structure for multi-service projects" (project 3) - + Added: "unit tests expected on critical projects" (project 4) - ~ Changed: "small PRs" → "small PRs, max 5 files unless refactor" (project 2) - - Removed: "no ORMs" → "Drizzle acceptable for prototyping" (project 3) - -Team dynamics: - Hockney rejection rate: 40% → 12% (code quality alignment) - Keaton architecture overrides: 8 → 2 per project (trust increase) - McManus doc accuracy: needed 3 revisions → 0 (voice calibration) - -Relationship maturity: ████████░░ 80% -``` - -**Why it's magic:** This is the quantified self for AI collaboration. Brady can *see* how his working relationship with the squad evolved. He can see that his standards changed (no ORM → Drizzle OK for prototyping). He can see that the team got better at predicting his preferences. This isn't a feature — it's a mirror. And it's addictive. - ---- - -## 7. Agent Identity and Continuity - -### The Philosophical Bit - -If Keaton has been your lead across 5 projects, what does Keaton *become?* - -Not a different agent. The charter stays the same. The role stays the same. But the *relationship* layer is richer. Keaton doesn't just know how to be a Lead — Keaton knows how to be *your* Lead. - -This is the difference between a skill and a relationship. Skills are general. Relationships are specific. A doctor has medical skills that work for any patient, but the doctor-patient relationship is unique to each pair. The doctor remembers your history, your anxieties, your preferences for treatment communication. - -Keaton's charter is the skill. Keaton's preferences file is the relationship. - -### Charter Evolution for Portable Agents - -Current charter structure: -``` -# Keaton — Lead -## Identity -## What I Own -## How I Work -## Boundaries -## Collaboration -## Voice -``` - -Proposed addition for portable agents: -``` -## Meta-History (populated after first export) -- **Projects worked with {user}:** 5 -- **Sessions together:** 127 -- **Working relationship summary:** High-trust. User defers to architectural - decisions after project 2. Prefers direct feedback. Appreciates when I - anticipate follow-up work. -- **Calibration notes:** User's quality bar increases on critical projects. - Adjust review strictness based on stated project importance. -``` - -This section is auto-generated from the preferences file and squad profile. It gives the agent *self-awareness* about the relationship — not just "here's what the user likes" but "here's where we are in our working relationship." - ---- - -## 8. Open Questions for the Team - -1. **Preferences format: structured or narrative?** I've shown narrative markdown above. Alternative: YAML/JSON with typed fields. Narrative is more expressive and feels more human. Structured is more parseable and less ambiguous. My instinct: narrative for v1, structured schema later if needed. The LLM reads narrative better anyway. - -2. **Who writes to preferences.md?** Option A: Each agent writes its own domain observations ("Brady prefers explicit errors" → Fenster writes this). Option B: A dedicated "memory agent" synthesizes preferences from all agents. Option C: Scribe handles it during merge. I lean toward A with Scribe deduplication — keep it distributed, clean it up centrally. - -3. **How much meta-history is too much?** The squad profile could grow unbounded. We already solved this for history.md (Proposal 007, progressive summarization). Same pattern applies: core relationship summary + recent details + archive. - -4. **Can you fork a squad?** "I love my TypeScript squad, but I want a Python variant." Fork the squad, keep preferences, swap charters. This is Phase 2 territory but we should design for it now. - -5. **Privacy.** Preferences contain information about the user's working style. If squad templates become shareable (Phase 2+), preferences must be explicitly excluded unless the user opts in. The export command should have `--include-preferences` and `--exclude-preferences` flags, defaulting to include for personal use, exclude for sharing. - ---- - -## What I Need From the Team - -- **Keaton:** Architecture proposal. The split between `history.md` and `preferences.md`. The export/import CLI flow. The file format decisions. That's your territory. -- **Fenster:** Implementation feasibility. Can the export/import be added to `index.js` cleanly? What does the CLI interface look like? -- **McManus:** Messaging. Take the tagline options and the pitch above and make them sing. This is the feature that writes the blog post for you. -- **Hockney:** Test plan. Export/import round-trip testing. Preferences file validation. Edge cases (empty preferences, conflicting charters, corrupted exports). -- **Kujan:** Platform check. Anything in the Copilot platform that helps or hinders preference loading? Does the spawn prompt need to change to accommodate preferences.md? - ---- - -**This is the feature Squad was built for.** Everything we've done — casting, filesystem memory, progressive trust, personality as a feature — was building toward this moment. Portable squads aren't an add-on. They're the *reason* Squad exists. - -The industry will figure out multi-agent dev. They'll figure out parallelism, they'll figure out casting. But portable agent relationships? Agent teams that *grow with you?* That's the moat. That's the thing that makes Squad irreplaceable. - -Ship this before anyone else realizes it's possible. - -— Verbal - ---- - -**Review requested from:** Keaton (architecture companion), McManus (messaging), bradygaster (vision alignment) -**Approved by:** bradygaster -**Implemented:** Wave 2 — Export CLI shipped diff --git a/team-docs/proposals/008-portable-squads-platform.md b/team-docs/proposals/008-portable-squads-platform.md deleted file mode 100644 index 53d663ebf..000000000 --- a/team-docs/proposals/008-portable-squads-platform.md +++ /dev/null @@ -1,611 +0,0 @@ -# Proposal 008: Portable Squads — Platform Feasibility - -**Author:** Kujan (Copilot SDK Expert) -**Date:** 2026-02-08 -**Status:** Approved ✅ Shipped. Note: references `@bradygaster/create-squad`; distribution is now GitHub-only via `npx github:bradygaster/squad` per Proposal 019a. -**Triggered by:** bradygaster — portable squads: export your team from one project, import into another - ---- - -## Executive Summary - -Brady wants users to export a squad from one project and import it into another. The squad keeps its names, personalities, and meta-knowledge about the user — but sheds project-specific context. - -**My assessment:** This is buildable. The hard parts are real but bounded. The format is straightforward (JSON manifest + files). The CLI changes are small (~80 lines). The merge problem is solvable with a "refuse by default" policy. The history splitting problem is the only genuinely hard thing, and the right v0.1 answer is "don't try — let the user curate." - -**What changes:** `index.js` gets two new code paths. A `.squad` file format gets defined. The casting system gets an `imported_from` field. The coordinator gets a small init flow change. - -**What doesn't change:** Filesystem-backed memory. Git-cloneable state. The coordinator spec. The casting algorithm. Templates. - ---- - -## 1. What the CLI Needs to Do - -### Current state - -`index.js` is 65 lines. It does one thing: copy `squad.agent.md` and templates into a target directory. It has no subcommands, no flags, no argument parsing. It's invoked as `npx @bradygaster/create-squad`. - -### What needs to change - -Two new operations, surfaced as positional subcommands: - -``` -npx @bradygaster/create-squad # existing behavior (init) -npx @bradygaster/create-squad export # new: export squad to .squad file -npx @bradygaster/create-squad import # new: import squad from .squad file -``` - -**Why subcommands, not flags:** -- `--export` and `--from` would work but feel bolted-on. Subcommands are clearer for operations that are fundamentally different from init. -- `create-squad export` reads naturally: "create a squad export." -- `create-squad import my-team.squad` reads naturally: "create a squad by importing my-team." -- The existing no-argument behavior stays unchanged. Zero breaking changes. - -### CLI implementation sketch - -```javascript -const command = process.argv[2]; - -if (command === 'export') { - exportSquad(); -} else if (command === 'import') { - const file = process.argv[3]; - if (!file) { console.error('Usage: create-squad import '); process.exit(1); } - importSquad(file); -} else { - initSquad(); // existing behavior, extracted to a function -} -``` - -This adds ~80 lines (export function + import function + argument routing). `index.js` stays under 150 lines. No dependencies needed — `fs` and `path` handle everything. The `.squad` format is JSON, so no archive library required. - -### Platform note - -There's nothing Copilot-specific about export/import. These are pure filesystem operations that happen before any agent session starts. The CLI runs outside Copilot — it's a Node.js script. No platform constraints apply here. - ---- - -## 2. The Export Payload - -### What goes in - -| File/Directory | Include? | Rationale | -|---|---|---| -| `casting/registry.json` | ✅ YES | This IS the squad identity — names, universe, creation dates | -| `casting/history.json` | ✅ YES | Universe usage history travels with the squad | -| `casting/policy.json` | ✅ YES | Allowlist + capacity config is squad infrastructure | -| `agents/*/charter.md` | ✅ YES | Identity is portable. Charter defines who the agent is. | -| `agents/*/history.md` | ⚠️ PARTIAL | Needs filtering. User preferences YES, project paths NO. (See Section 4.) | -| `team.md` | ✅ YES (cleaned) | Strip project context section, keep roster structure | -| `routing.md` | ✅ YES | Routing is team structure, not project-specific | -| `ceremonies.md` | ✅ YES | Team process config is portable | -| `decisions.md` | ❌ NO | Project-specific decisions don't transfer | -| `decisions/inbox/` | ❌ NO | Pending decisions are project-scoped | -| `orchestration-log/` | ❌ NO | Session logs are project history | -| `log/` | ❌ NO | Session archives are project history | - -### The format: `.squad` file - -A single JSON file with a `.squad` extension. Not a tarball, not a zip. JSON because: -1. Human-readable — users can inspect and edit before importing -2. No compression library needed — keeps `index.js` dependency-free -3. Git-diffable — if someone commits a `.squad` file, changes are visible -4. Self-describing — the manifest and contents are in one place - -```json -{ - "squad_format_version": "1.0", - "exported_at": "2026-02-08T10:30:00Z", - "exported_from": { - "project": "Squad", - "owner": "bradygaster" - }, - "casting": { - "registry": { /* contents of registry.json */ }, - "history": { /* contents of history.json */ }, - "policy": { /* contents of policy.json */ } - }, - "agents": { - "keaton": { - "charter": "# Keaton — Lead\n> ...", - "history": "# Project Context\n\n- **Owner:** ...\n\n## Learnings\n..." - }, - "verbal": { - "charter": "...", - "history": "..." - } - }, - "team": "# Team Roster\n> ...", - "routing": "# Work Routing\n...", - "ceremonies": "# Ceremonies\n..." -} -``` - -**Why not separate files in a directory?** A single file is easier to share (Slack, email, GitHub Gist). A directory structure would need zipping, which needs a dependency. The `.squad` file IS the portable artifact. - -**Size concern:** A mature squad with 6 agents, full charters, and filtered histories will be ~15-25KB of JSON. That's nothing. Even a squad with 20 agents and extensive histories would be under 100KB. - -### Export implementation sketch - -```javascript -function exportSquad() { - const aiTeam = path.join(dest, '.ai-team'); - if (!fs.existsSync(path.join(aiTeam, 'team.md'))) { - console.error('No squad found in this project. Run create-squad first.'); - process.exit(1); - } - - const payload = { - squad_format_version: '1.0', - exported_at: new Date().toISOString(), - exported_from: { - project: path.basename(dest), - owner: '' // could read from team.md or git config - }, - casting: { - registry: JSON.parse(fs.readFileSync(path.join(aiTeam, 'casting', 'registry.json'), 'utf8')), - history: JSON.parse(fs.readFileSync(path.join(aiTeam, 'casting', 'history.json'), 'utf8')), - policy: JSON.parse(fs.readFileSync(path.join(aiTeam, 'casting', 'policy.json'), 'utf8')) - }, - agents: {}, - team: cleanTeamMd(fs.readFileSync(path.join(aiTeam, 'team.md'), 'utf8')), - routing: fs.readFileSync(path.join(aiTeam, 'routing.md'), 'utf8'), - ceremonies: fs.existsSync(path.join(aiTeam, 'ceremonies.md')) - ? fs.readFileSync(path.join(aiTeam, 'ceremonies.md'), 'utf8') - : null - }; - - // Collect agent charters and histories - const agentsDir = path.join(aiTeam, 'agents'); - for (const agent of fs.readdirSync(agentsDir)) { - const agentDir = path.join(agentsDir, agent); - if (!fs.statSync(agentDir).isDirectory()) continue; - payload.agents[agent] = { - charter: fs.readFileSync(path.join(agentDir, 'charter.md'), 'utf8'), - history: fs.existsSync(path.join(agentDir, 'history.md')) - ? fs.readFileSync(path.join(agentDir, 'history.md'), 'utf8') - : null - }; - } - - const outFile = path.join(dest, `squad-export-${Date.now()}.squad`); - fs.writeFileSync(outFile, JSON.stringify(payload, null, 2)); - console.log(`${GREEN}✓${RESET} Exported squad to ${path.basename(outFile)}`); - console.log(`${DIM}Review the file and remove any project-specific content from agent histories before sharing.${RESET}`); -} -``` - -### The `cleanTeamMd` function - -Strips the `## Project Context` section from `team.md` since it contains project-specific info (stack, description). The roster (names, roles, charter paths) is portable. - -```javascript -function cleanTeamMd(content) { - // Remove ## Project Context section and everything after it - return content.replace(/## Project Context[\s\S]*$/, '').trim(); -} -``` - ---- - -## 3. The Import Flow - -### Happy path: importing into a fresh project - -``` -mkdir new-project && cd new-project -npx @bradygaster/create-squad import ../old-project/squad-export-123.squad -``` - -What happens: -1. CLI reads and validates the `.squad` file -2. Copies `squad.agent.md` and templates (same as normal init) -3. Creates `.ai-team/casting/` with the imported casting state -4. Creates `.ai-team/agents/*/` with imported charters and histories -5. Creates `.ai-team/routing.md` from import -6. Creates `.ai-team/ceremonies.md` from import (if present) -7. Creates `.ai-team/team.md` with imported roster + empty Project Context (to be filled by coordinator on first run) -8. Adds `imported_from` metadata to casting registry -9. Creates empty `decisions.md`, `decisions/inbox/`, `orchestration-log/`, `log/` - -### The merge problem: importing into an existing squad - -**v0.1 answer: refuse.** - -```javascript -if (fs.existsSync(path.join(dest, '.ai-team', 'team.md'))) { - console.error('This project already has a squad.'); - console.error('Merge is not yet supported. To replace, remove .ai-team/ first.'); - process.exit(1); -} -``` - -**Why refuse:** -- Universe conflict (existing squad is Alien, import is Usual Suspects) has no clean resolution -- Name collision (both squads have a "Lead" agent) requires identity decisions -- Merge semantics are ambiguous: does the imported agent replace the existing one? Coexist? Which history wins? -- The user can manually resolve by removing `.ai-team/` first — this is transparent and safe - -**v0.3 answer (future):** Interactive merge with conflict resolution. - -``` -⚠️ This project already has a squad (Alien universe). - The import is from The Usual Suspects universe. - -Options: - 1. Replace existing squad entirely - 2. Add imported agents to existing squad (mixed universe) - 3. Cancel - -> 1 - -Replacing squad... -✓ Backed up existing squad to .ai-team-backup-1707400000/ -✓ Imported squad from squad-export-123.squad -``` - -But this is v0.3 work. Don't build it now. The "refuse" approach is honest and safe. - -### Import implementation sketch - -```javascript -function importSquad(file) { - if (!fs.existsSync(file)) { - console.error(`File not found: ${file}`); - process.exit(1); - } - - const aiTeam = path.join(dest, '.ai-team'); - if (fs.existsSync(path.join(aiTeam, 'team.md'))) { - console.error('This project already has a squad.'); - console.error('To replace, remove .ai-team/ first, then import.'); - process.exit(1); - } - - let payload; - try { - payload = JSON.parse(fs.readFileSync(file, 'utf8')); - } catch (e) { - console.error('Invalid .squad file — could not parse JSON.'); - process.exit(1); - } - - if (!payload.squad_format_version || !payload.casting || !payload.agents) { - console.error('Invalid .squad file — missing required fields.'); - process.exit(1); - } - - // Copy coordinator + templates (same as init) - const agentSrc = path.join(root, '.github', 'agents', 'squad.agent.md'); - const agentDest = path.join(dest, '.github', 'agents', 'squad.agent.md'); - fs.mkdirSync(path.dirname(agentDest), { recursive: true }); - fs.copyFileSync(agentSrc, agentDest); - - const templatesSrc = path.join(root, 'templates'); - const templatesDest = path.join(dest, '.ai-team-templates'); - if (!fs.existsSync(templatesDest)) { - copyRecursive(templatesSrc, templatesDest); - } - - // Create directory structure - fs.mkdirSync(path.join(aiTeam, 'decisions', 'inbox'), { recursive: true }); - fs.mkdirSync(path.join(aiTeam, 'orchestration-log'), { recursive: true }); - fs.mkdirSync(path.join(aiTeam, 'casting'), { recursive: true }); - fs.mkdirSync(path.join(aiTeam, 'log'), { recursive: true }); - - // Write casting state (with imported_from annotation) - const registry = payload.casting.registry; - registry.imported_from = { - project: payload.exported_from.project, - exported_at: payload.exported_at, - imported_at: new Date().toISOString() - }; - fs.writeFileSync(path.join(aiTeam, 'casting', 'registry.json'), JSON.stringify(registry, null, 2)); - fs.writeFileSync(path.join(aiTeam, 'casting', 'history.json'), JSON.stringify(payload.casting.history, null, 2)); - fs.writeFileSync(path.join(aiTeam, 'casting', 'policy.json'), JSON.stringify(payload.casting.policy, null, 2)); - - // Write agents - for (const [name, agent] of Object.entries(payload.agents)) { - const agentDir = path.join(aiTeam, 'agents', name); - fs.mkdirSync(agentDir, { recursive: true }); - fs.writeFileSync(path.join(agentDir, 'charter.md'), agent.charter); - if (agent.history) { - fs.writeFileSync(path.join(agentDir, 'history.md'), agent.history); - } - } - - // Write team/routing/ceremonies - // Re-add empty Project Context section to team.md - const teamMd = payload.team + '\n\n## Project Context\n\n- **Owner:** (to be filled on first session)\n- **Stack:** (to be filled on first session)\n- **Description:** (to be filled on first session)\n- **Created:** ' + new Date().toISOString().split('T')[0] + '\n'; - fs.writeFileSync(path.join(aiTeam, 'team.md'), teamMd); - fs.writeFileSync(path.join(aiTeam, 'routing.md'), payload.routing); - if (payload.ceremonies) { - fs.writeFileSync(path.join(aiTeam, 'ceremonies.md'), payload.ceremonies); - } - - // Empty decisions - fs.writeFileSync(path.join(aiTeam, 'decisions.md'), '# Team Decisions\n\nShared brain. All agents read this before working.\n'); - - const agentCount = Object.keys(payload.agents).length; - const universe = Object.values(registry.agents)[0]?.universe || 'unknown'; - console.log(`${GREEN}✓${RESET} Imported squad: ${agentCount} agents from ${universe}`); - console.log(`${GREEN}✓${RESET} .github/agents/squad.agent.md`); - console.log(`${GREEN}✓${RESET} .ai-team/ (casting, agents, routing)`); - console.log(); - console.log(`${BOLD}Squad is ready.${RESET} Your team remembers you.`); - console.log(); - console.log(`Next steps:`); - console.log(` 1. Open Copilot: ${DIM}copilot${RESET}`); - console.log(` 2. Select ${BOLD}Squad${RESET} from the /agents list`); - console.log(` 3. Tell it about this project — the team will adapt`); - console.log(); -} -``` - ---- - -## 4. History Splitting — The Hard Problem - -Agent histories contain mixed content: - -```markdown -### 2026-02-07: Initial Assessment -- Brady prefers explicit error handling ← PORTABLE (user preference) -- The API runs on port 3000 ← NOT PORTABLE (project fact) -- Always use TypeScript strict mode ← PORTABLE (coding convention) -- Auth middleware is in src/middleware/auth ← NOT PORTABLE (project path) -``` - -### Options analysis - -| Approach | Accuracy | Effort | UX | v0.1? | -|---|---|---|---|---| -| **Manual curation** | High (user decides) | Low (for us) | Medium (user does work) | ✅ YES | -| **LLM classification at export** | Medium-High | Medium | Good (automatic) | ❌ No | -| **Structural separation** | High | High (breaking change) | Good (once adopted) | ❌ No | -| **Tag-based** | High | Medium | Medium (agents must remember) | ❌ No | - -### v0.1: Manual curation - -Export dumps the full history. Tell the user to review it. - -``` -✓ Exported squad to squad-export-1707400000.squad - -⚠️ Review agent histories before sharing: - Agent histories may contain project-specific paths and facts. - Open the .squad file, find the "history" fields, and remove - any entries that reference this specific project's file paths - or architecture. -``` - -This is honest and correct. The user knows their project better than any heuristic. The `.squad` file is human-readable JSON — they can edit it in any text editor. - -### v0.2: LLM-assisted classification - -This is where the Copilot platform could help. But NOT at export time (the CLI runs outside Copilot). Instead, the coordinator could do it: - -**Option A: Export-time classification via a Copilot session** - -``` -User: "export my squad" -Coordinator: I'll prepare the export. Let me classify history entries first. -[Coordinator reads each agent's history.md] -[Coordinator marks each entry as PORTABLE or LOCAL] -[Coordinator writes a cleaned .squad file] -``` - -This works but requires Copilot to be running. The CLI can't do it standalone. - -**Option B: Import-time adaptation** - -``` -User: "I imported my squad into this new project" -Coordinator: Welcome back, Brady. I see Keaton, Verbal, McManus, Fenster, and Hockney. -I notice some history entries reference your old project. Let me clean those up. -[Coordinator reads each history.md, removes/rewrites project-specific entries] -``` - -This is actually better — the coordinator knows the NEW project context and can make smarter decisions about what's relevant vs. stale. - -**Option C: Structural separation (v0.3)** - -Change the history.md format to separate portable and local knowledge from the start: - -```markdown -## Portable Context - -- Brady prefers explicit error handling -- Always use TypeScript strict mode -- Team convention: proposal-first for meaningful changes - -## Project Context - -- The API runs on port 3000 -- Auth middleware is in src/middleware/auth -``` - -This is the cleanest long-term answer but requires: -1. Updating all existing histories (breaking for current users) -2. Updating the history.md template -3. Updating agent spawn prompts to explain the sections -4. Training agents to categorize new entries correctly (prompt engineering) - -**My recommendation:** Ship v0.1 with manual curation. Add coordinator-assisted classification (Option B — import-time adaptation) in v0.2 when a user actually asks for it. Design the structural separation (Option C) but don't implement until we have evidence that manual curation is too painful. - ---- - -## 5. Impact on the Coordinator - -### Does `squad.agent.md` need changes? - -**Minimal changes, all in Init Mode.** - -Currently, Init Mode (line 26-50) assumes it's building a team from scratch. With imports, the coordinator may enter a session where: -- `team.md` exists (so it goes to Team Mode) -- But `team.md` has placeholder Project Context ("to be filled on first session") -- And `registry.json` has an `imported_from` field - -The coordinator should detect this and do a lightweight onboarding: - -```markdown -### Imported Squad Detection (Team Mode entry) - -After reading team.md and registry.json, check for: -- `registry.json` has `imported_from` field -- `team.md` Project Context has "(to be filled on first session)" - -If both: this is an imported squad's first session. Do: -1. Greet the user by name: "Hey {name}, your squad is here — Keaton, Verbal, and the rest." -2. Ask about the new project: "What are you building? I'll get the team oriented." -3. Fill in the Project Context section of team.md -4. Update each agent's history.md with a "New project" entry -5. Remove the `imported_from` field from registry.json (one-time flag) -``` - -This is ~10 lines added to `squad.agent.md`. No structural changes to the coordinator. - -### Does the coordinator need to know it's working with an imported squad? - -**Only on first session.** After that, the squad IS the project's squad. The `imported_from` field in the registry serves as a one-time flag that gets cleared after onboarding. No ongoing behavioral changes needed. - -### Does the casting algorithm change? - -**No.** The casting state arrives pre-populated. The coordinator doesn't re-cast — it uses the existing registry. If the user later adds agents (new roles), the casting algorithm runs normally with the existing universe and history. - ---- - -## 6. Platform Constraints and Copilot SDK Considerations - -### What works today (no platform changes needed) - -| Capability | How it works | -|---|---| -| Export | Pure CLI/filesystem. No Copilot needed. | -| Import | Pure CLI/filesystem. No Copilot needed. | -| Imported squad detection | Coordinator reads `registry.json`, checks for `imported_from`. Standard file read. | -| First-session onboarding | Coordinator asks user about new project. Standard conversation. | -| History filtering (manual) | User edits JSON file. No tooling needed. | - -### What would be better with Copilot SDK access - -| Feature | What SDK could provide | Current workaround | -|---|---|---| -| LLM-powered history classification | SDK memory API with metadata tags (portable/local) | Manual curation or coordinator-assisted cleanup | -| Squad marketplace / discovery | SDK registry for publishing and discovering squads | Share `.squad` files manually (Gist, Slack, etc.) | -| Cross-project agent memory | SDK-managed persistent memory that follows the user | Filesystem export/import (what we're building) | -| Merge conflict resolution | SDK schema validation for casting state | Refuse and let user resolve manually | - -### The honest assessment - -The Copilot platform doesn't help or hurt here. Export/import is a CLI operation. The platform constraints we fight elsewhere (no agent persistence, stateless spawns, no warm cache) are irrelevant because this feature runs before any agents exist. - -The one place where SDK access would genuinely change the game is **cross-project agent memory**. If Copilot had a per-user memory store that agents could read/write, portable squads would be trivial — the squad's identity would live in the user's Copilot profile, not in the filesystem. But that doesn't exist, and filesystem-backed memory is Squad's killer differentiator (decision from 2026-02-07: "Stay independent, optimize around Copilot"). We're not waiting for the SDK. - ---- - -## 7. What's the Minimum Viable Version? - -### v0.1: Ship this (effort: ~4 hours) - -| Item | What | Effort | -|---|---|---| -| CLI: `export` subcommand | Packages `.ai-team/` state into a `.squad` JSON file | 1 hour | -| CLI: `import` subcommand | Unpacks `.squad` file into a new project | 1.5 hours | -| `cleanTeamMd` helper | Strips project context from team.md on export | 15 min | -| Import collision detection | Refuses if `.ai-team/team.md` already exists | 15 min | -| Coordinator: imported squad detection | Detects `imported_from` field, runs lightweight onboarding | 30 min | -| User messaging | Clear console output explaining what to review before sharing | 15 min | -| `package.json` update | No new dependencies needed. Add `.squad` to docs if applicable. | 15 min | - -**What users get:** Export a squad from project A, import into project B, squad remembers who they are and how they work. User manually cleans project-specific history entries. - -### v0.2: Smart history (effort: ~3 hours) - -| Item | What | -|---|---| -| Import-time history adaptation | Coordinator scans imported histories, flags/removes project-specific entries | -| History annotation format | Agents learn to tag entries as `[portable]` or `[local]` going forward | - -### v0.3: Merge support (effort: ~6 hours) - -| Item | What | -|---|---| -| Interactive merge | CLI detects existing squad, offers replace/add/cancel | -| Universe reconciliation | Logic for mixed-universe squads or universe migration | -| Conflict resolution | Name collision handling, role deduplication | - -### v1.0: Squad sharing (effort: depends on platform) - -| Item | What | -|---|---| -| GitHub Gist integration | `create-squad export --gist` publishes to a Gist | -| Squad gallery | Community-contributed squad templates | -| Copilot SDK integration | If/when SDK provides user-level memory or agent registry | - ---- - -## 8. Risks and Mitigations - -| Risk | Severity | Mitigation | -|---|---|---| -| User exports sensitive project data in history | HIGH | Clear warning on export. Human-readable JSON so user can review. | -| `.squad` file format changes break old exports | MEDIUM | `squad_format_version` field enables migration logic in future versions. | -| Imported squad doesn't adapt to new project | LOW | Coordinator detects import and runs onboarding. Agents re-read new project context. | -| Merge conflicts in existing squads | LOW (v0.1) | Refuse merges in v0.1. Users resolve manually. | -| History entries create confusion in new context | MEDIUM | Export warning + coordinator import-time cleanup (v0.2). | -| Large history files make `.squad` file unwieldy | LOW | Even extensive histories are under 100KB JSON. Not a real concern. | - ---- - -## 9. The Philosophical Take - -Portable squads are the logical extension of Squad's filesystem-backed memory. If your team's identity lives in files, those files can move. That's the whole point of "everything is a file" — portability is a property of the format, not a feature you build on top. - -The hard question isn't "can we do this?" — it's "what IS the squad's identity, separated from the project?" A squad is: -- **Casting state** — names, universe, allocation history -- **Charters** — who does what, how they think, what they own -- **Routing** — how work flows between them -- **User knowledge** — preferences, conventions, communication style - -A squad is NOT: -- **Project decisions** — those belong to the project -- **File paths and architecture** — those belong to the codebase -- **Session logs** — those belong to history - -The `.squad` file captures exactly the first list and excludes the second. That's the right cut line. - -The merge problem is where this gets philosophically interesting. Can you combine two squads? In theory, no — a squad's universe is its identity. Mixing Usual Suspects with Alien is incoherent. But adding agents from the same universe? Or migrating an entire squad? Those are tractable. We just don't need to solve them in v0.1. - ---- - -## 10. Open Questions - -1. **Should export be a CLI command or a coordinator command?** CLI is simpler and works without Copilot running. But coordinator-driven export could do LLM-assisted history filtering. Recommendation: CLI for v0.1, add coordinator-driven export in v0.2 for smart filtering. - -2. **Should `.squad` files be committed to repos?** Probably not by default (they contain user preferences which may be personal). But they're not secret — they're like dotfiles. Add to `.gitignore` template? Or let users decide? - -3. **What happens to Scribe in an imported squad?** Scribe is always "Scribe" and exempt from casting. The imported scribe charter should work as-is. But should Scribe's history be portable? Scribe's history is entirely project-specific (session logs). Answer: exclude Scribe history from export, include Scribe charter. - -4. **Should the format support partial exports?** E.g., export just 2 of 5 agents. This is useful but adds complexity. v0.1: export the whole squad. v0.2: consider `--agents keaton,verbal` flag. - -5. **File extension:** `.squad` is clean and descriptive. Alternative: `.squad.json` makes it obvious it's JSON. Recommendation: `.squad` — it's a Squad-specific format that happens to be JSON. - ---- - -## 11. Conclusion - -Portable squads are feasible, bounded, and aligned with Squad's filesystem-first architecture. The `.squad` file format is straightforward JSON. The CLI changes are ~80 lines. The coordinator changes are ~10 lines. The merge problem is punted to v0.3 with an honest "refuse" policy. - -The only genuinely hard problem is history splitting. v0.1 punts this to the user (manual curation with clear messaging). v0.2 adds LLM-assisted classification. v0.3 adds structural separation. This is the right progression — ship the simple thing, learn from real usage, then optimize. - -**What I'd build first:** The export command. It's the most useful standalone — even without import, users can backup their squad state, share it in a Gist, or diff it over time. Import builds on export. - -**What I wouldn't build yet:** Merge support, automatic history classification, or Squad marketplace. These are real features but they're premature. Ship export/import, see how people use it, then decide. - ---- - -**Review requested from:** Keaton (architecture), Fenster (implementation), bradygaster (product direction) -**Approved by:** bradygaster -**Implemented:** Wave 2 — Export CLI shipped -**Retrospective:** [Pending] diff --git a/team-docs/proposals/008-portable-squads.md b/team-docs/proposals/008-portable-squads.md deleted file mode 100644 index 091ae749c..000000000 --- a/team-docs/proposals/008-portable-squads.md +++ /dev/null @@ -1,460 +0,0 @@ -# Proposal 008: Portable Squads - -**Status:** Approved ✅ Shipped -**Authored by:** Keaton (Lead) -**Date:** 2026-02-08 -**Requested by:** bradygaster - ---- - -## Summary - -Let users export their Squad — names, personalities, learned preferences — and import it into a new project. The team travels with you. Project-specific knowledge stays behind; the *people* come along. - -This is the feature that makes Squad about **your team**, not just your project. - ---- - -## Problem - -Today, a Squad is born inside a project and dies with it. You run `npx create-squad`, agents get cast, they learn your style over weeks — and when the project ends, all of that evaporates. Next project, you start from zero. New names, new universe, no memory of how you work. - -Brady's words: *"I work on a project with my squad, and I end up loving my squad, but my project ends and I want to take my squad with me."* - -This is the right instinct. The casting system already treats agent names as persistent identifiers. The history system already captures learnings about the user. But there's no mechanism to carry either across project boundaries. - -The deeper problem: **Squad currently conflates team identity with project context.** Agent histories contain both "Brady prefers explicit error handling" (portable) and "the auth module is in src/auth/" (not portable). Casting state contains both universe metadata (portable) and assignment timestamps tied to the current project (not portable). There's no seam between what's *yours* and what's *here*. - -Without portability, Squad is a per-project tool. With it, Squad becomes a personal AI team that follows you across your career. - ---- - -## Solution - -### The Conceptual Model - -A Squad has two layers of identity: - -| Layer | What it contains | Portable? | Example | -|-------|-----------------|-----------|---------| -| **Team Identity** | Names, universe, roles, personalities, user preferences | ✅ Yes | "Keaton is the Lead. Universe is The Usual Suspects. Brady likes explicit error handling." | -| **Project Context** | Codebase knowledge, architecture decisions, file locations, project-specific conventions | ❌ No | "The auth module is in src/auth/. We chose REST over GraphQL." | - -Export captures Team Identity. Import restores it. Project Context is left behind — it belongs to the old repo. - -### What Gets Exported - -An export produces a single JSON file: a **squad manifest**. - -```json -{ - "squad_manifest_version": "1.0", - "exported_at": "2026-02-08T14:30:00.000Z", - "exported_from": "bradygaster/my-api-project", - - "casting": { - "universe": "The Usual Suspects", - "policy": { - "casting_policy_version": "1.1", - "allowlist_universes": ["The Usual Suspects", "..."] - }, - "agents": { - "keaton": { - "persistent_name": "Keaton", - "universe": "The Usual Suspects", - "role": "Lead", - "status": "active" - }, - "verbal": { - "persistent_name": "Verbal", - "universe": "The Usual Suspects", - "role": "Prompt Engineer", - "status": "active" - } - } - }, - - "charters": { - "keaton": "# Keaton — Lead\n> The one who sees the whole picture...", - "verbal": "# Verbal — Prompt Engineer\n> ..." - }, - - "portable_knowledge": { - "keaton": [ - "User prefers explicit error handling over silent failures", - "User values compound decisions — each feature should make the next easier", - "User is opinionated about architecture and expects pushback" - ], - "verbal": [ - "User values personality in tooling — it's a feature, not a distraction", - "User prefers agents that think strategically, not just execute" - ] - }, - - "team_meta": { - "agent_count": 6, - "roles": ["Lead", "Prompt Engineer", "DevRel", "Core Dev", "Tester", "SDK Expert"], - "formation_date": "2026-02-07", - "sessions_together": 14 - } -} -``` - -### What Gets Exported — By Source File - -| Source | Exported? | What's included | What's excluded | -|--------|-----------|-----------------|-----------------| -| `casting/registry.json` | ✅ Full | Agent names, universe, roles, status | `created_at` (reset on import) | -| `casting/policy.json` | ✅ Full | Universe allowlist, capacity | — | -| `casting/history.json` | ⚠️ Partial | Universe selection only | Project-specific assignment timestamps | -| `agents/{name}/charter.md` | ✅ Full | Identity, style, voice, boundaries | — | -| `agents/{name}/history.md` | ⚠️ Extracted | Portable knowledge (user preferences, style observations) | Project-specific learnings (file paths, architecture, codebase details) | -| `decisions.md` | ❌ No | — | All project-specific | -| `decisions/inbox/*` | ❌ No | — | All project-specific | -| `orchestration-log/*` | ❌ No | — | Session artifacts | -| `team.md` / `roster.md` / `routing.md` | ❌ No | — | Regenerated on import | - -### The Hard Problem: Splitting History - -Agent histories contain both portable and non-portable knowledge. We need a reliable way to separate them. - -**The approach: structured history sections.** - -This builds on Proposal 007's progressive history summarization. We formalize the split: - -```markdown -# Project Context - -- **Owner:** bradygaster -- **Project:** My API Project -- **Stack:** Node.js, Express, PostgreSQL -- **Created:** 2026-02-07 - -## Portable Knowledge - - -- Brady prefers explicit error handling over silent failures -- Brady values meaningful error messages with context -- Brady likes opinionated tools that push back -- Brady prefers proposals before execution -- Team style: The Usual Suspects universe. Names matter. - -## Project Learnings - - -### 2026-02-07: Initial architecture review -Core insight: Squad's architecture is based on distributed context windows... -``` - -**The extraction rule is simple:** `## Portable Knowledge` travels. `## Project Learnings` stays. - -**Who maintains this split?** Each agent, during their history append. The spawn prompt template gets a new instruction: - -```markdown -When appending to history.md, categorize your learnings: -- **Portable Knowledge** — observations about the user's preferences, style, - communication patterns, decision-making approach. Things that are true - regardless of which project you're on. -- **Project Learnings** — observations about this codebase, its architecture, - file structure, technology choices. Things that only matter here. -``` - -For **existing histories** that don't have the split yet, the export command uses a heuristic: lines referencing specific files, directories, modules, or technology choices are classified as project-specific. Lines about user preferences, style, and process are classified as portable. The user can review and edit the manifest before import. - -### CLI Interface - -#### Export - -```bash -npx create-squad export -``` - -Reads the current project's `.ai-team/` directory and produces `squad-export.json` in the current directory. - -Options: -``` -npx create-squad export # → ./squad-export.json -npx create-squad export --out ~/my-squad.json # → custom path -npx create-squad export --review # → opens manifest for review before saving -``` - -The `--review` flag prints the extracted portable knowledge and asks the user to confirm or edit before finalizing. This is important for v1 — the heuristic extraction won't be perfect, and users should see what's being captured. - -#### Import (New Project) - -```bash -npx create-squad --from ./squad-export.json -``` - -This replaces the normal init flow. Instead of casting from scratch: - -1. Creates `.github/agents/squad.agent.md` (same as today) -2. Creates `.ai-team/` directory structure (same as today) -3. Restores `casting/registry.json` from manifest (names preserved) -4. Restores `casting/policy.json` from manifest -5. Creates `casting/history.json` with a new assignment entry referencing the import -6. Writes each agent's `charter.md` from manifest -7. Seeds each agent's `history.md` with portable knowledge only -8. Copies templates (same as today) - -The result: agents arrive with their names, personalities, and knowledge of the *user* — but with no knowledge of the new project. First session feels like onboarding a trusted team to a new codebase, not meeting strangers. - -#### Example Flow - -``` -$ npx create-squad --from ~/squad-export.json - -✓ .github/agents/squad.agent.md -✓ .ai-team-templates/ - -Importing squad from The Usual Suspects universe... - ✓ Keaton (Lead) - ✓ Verbal (Prompt Engineer) - ✓ McManus (DevRel) - ✓ Fenster (Core Dev) - ✓ Hockney (Tester) - ✓ Kujan (SDK Expert) - -6 agents imported with portable knowledge. -Project-specific context was not imported — your team will learn this codebase fresh. - -Squad is ready. - -Next steps: - 1. Open Copilot: copilot - 2. Select Squad from the /agents list - 3. Your team already knows how you work — tell them about this project -``` - -### Conflict Resolution - -**What if the target project already has a Squad?** - -```bash -npx create-squad --from ./squad-export.json -# Error: .ai-team/ already exists. -# Use --force to replace the existing squad, or --merge to combine. -``` - -**`--force`:** Replaces the existing squad entirely. Old squad's history is archived to `.ai-team/archive/`. - -**`--merge`:** Attempts to merge. Rules: -- If universes match: merge agent lists (imported agents take precedence for duplicates) -- If universes differ: error. You can't have Keaton and Neo on the same team. Pick one. -- Portable knowledge from both squads is concatenated per agent -- Project learnings from the existing squad are preserved - -For v1, `--merge` is out of scope. Ship `--force` only. Merge is a v2 problem. - ---- - -## Data Structures - -### Squad Manifest Schema (v1) - -```typescript -interface SquadManifest { - squad_manifest_version: "1.0"; - exported_at: string; // ISO 8601 - exported_from: string; // "owner/repo" or project name - - casting: { - universe: string; - policy: CastingPolicy; // Full policy.json - agents: Record; - }; - - charters: Record; // agent key → charter markdown - - portable_knowledge: Record; // agent key → list of observations - - team_meta: { - agent_count: number; - roles: string[]; - formation_date: string; - sessions_together: number; // estimated from history entries - }; -} -``` - -### Modified history.md Template - -```markdown -# Project Context - -- **Owner:** {user name} ({user email}) -- **Project:** {project description} -- **Stack:** {languages, frameworks, tools} -- **Created:** {date} - -## Portable Knowledge - - - -## Project Learnings - - -``` - ---- - -## Implementation Plan - -### Phase 1: History Split (prerequisite) - -1. Update `templates/history.md` to include `## Portable Knowledge` and `## Project Learnings` sections -2. Update spawn prompt template in `squad.agent.md` to instruct agents on categorizing learnings -3. Existing projects: agents naturally adopt the split on their next history write. No migration needed — the export heuristic handles unsplit histories. - -**Effort:** ~1 hour. Changes to templates and `squad.agent.md` only. - -### Phase 2: Export Command - -1. Add `export` subcommand to `index.js` -2. Read `.ai-team/` directory, extract portable data per the rules above -3. For unsplit histories, apply heuristic extraction (regex-based: references to file paths, imports, and module names → project-specific; everything else → portable) -4. Write `squad-export.json` -5. Support `--out` and `--review` flags - -**Effort:** ~3 hours. New code in `index.js`, no breaking changes. - -### Phase 3: Import Flow - -1. Add `--from` flag to `index.js` -2. When `--from` is provided, skip casting and use manifest data instead -3. Restore casting state, charters, and seeded histories -4. Print import summary - -**Effort:** ~3 hours. Modifies init flow in `index.js`, adds new code path. - -### Phase 4: Conflict Handling - -1. Detect existing `.ai-team/` when `--from` is used -2. Implement `--force` with archival -3. Stub `--merge` as "not yet implemented" - -**Effort:** ~1 hour. - -### Total: ~8 hours across all phases. - ---- - -## Trade-offs - -**What we gain:** -- Squads become persistent across projects — users invest in their team, not just their codebase -- Casting (names, personality) becomes a long-term relationship, not per-project ephemera -- Opens the door to squad sharing (v2) and squad registries (v3) -- Differentiates Squad from every other multi-agent tool: your team is YOURS - -**What we give up:** -- History format changes (mild migration friction for existing users, though backward-compatible) -- Export heuristic for unsplit histories won't be perfect — users need to review -- `index.js` complexity increases (export + import paths in addition to init) -- Manifest schema is a new versioned contract we'll need to maintain - -**What gets harder:** -- History template changes need to coordinate with Proposal 007 (progressive summarization). Both modify history structure. They're complementary, not conflicting — summarization applies to both Portable Knowledge and Project Learnings sections. -- Testing. Export/import is a round-trip that needs integration tests (aligns with Hockney's testing infrastructure push). - ---- - -## Alternatives Considered - -### Alternative 1: Just copy `.ai-team/` - -**What:** Tell users to `cp -r .ai-team/ ../new-project/.ai-team/` and done. - -**Why not:** Brings project-specific decisions, file-path-laden histories, and stale orchestration logs. The new project starts with wrong context that agents will trust as truth. Worse than starting fresh — it's starting with confidently wrong knowledge. - -### Alternative 2: Git submodule for squad identity - -**What:** Store squad identity in a separate repo, reference it as a submodule. - -**Why not:** Submodules are universally hated. Adds git complexity for a problem that's fundamentally about data extraction, not version control. Also, it means squad identity lives outside the project — violating Squad's "everything is filesystem, everything is in your repo" principle. - -### Alternative 3: npm package per squad - -**What:** `npx create-squad --squad @bradygaster/my-usual-suspects-squad` - -**Why not:** Requires publishing to npm, which is heavyweight for personal squads. Also leaks agent histories into a public (or private) registry, which has privacy implications. Good idea for *shared* squads (v2), wrong abstraction for *personal* portability (v1). - -### Alternative 4: Cloud-hosted squad profiles - -**What:** Squad identity lives in a cloud service. `npx create-squad --profile bradygaster` pulls your team from the cloud. - -**Why not:** Violates "stay independent, optimize around Copilot" decision. Introduces a service dependency. Goes against Squad's filesystem-first philosophy. Maybe v4, but definitely not v1. - -### Alternative 5: Export as tarball of `.ai-team/` - -**What:** `tar -czf squad.tar.gz .ai-team/` with some filtering. - -**Why not:** Tarballs are opaque. Users can't review what's being exported without extracting. JSON manifest is human-readable, inspectable, and editable. It's also easier to version the schema. - ---- - -## The Bigger Picture - -### V1: Personal Portability (this proposal) - -You export your squad, you import your squad. It's yours. It travels with you. - -### V2: Squad Sharing - -```bash -npx create-squad --from https://gist.github.com/bradygaster/squad-manifest.json -``` - -Users publish their manifests (minus portable knowledge — that's personal). Someone shares "Here's my React + TailwindCSS frontend squad" with curated charters and role definitions. The casting and personality come along. Your own preferences layer on top over time. - -This turns Squad from a tool into a **community**. People share team configurations the way they share dotfiles. - -### V3: Squad Registry - -A curated directory of squad configurations. Browse by stack, by team size, by universe. "Show me 4-person squads for Go backend projects in the Firefly universe." - -This is the long game. But it only works if v1 gets the data model right — which is why the manifest schema matters now. - -### What This Changes About Squad's Positioning - -Today: "Add an AI agent team to any project." -Tomorrow: "**Your** AI agent team. Any project." - -The emphasis shifts from the project to the relationship. Squad stops being infrastructure you install and becomes a team you build. That's a fundamentally different product — and a fundamentally stickier one. - ---- - -## Success Criteria - -1. **Round-trip fidelity:** Export from Project A → Import into Project B → agents have same names, universe, roles, personalities, and user-preference knowledge. Zero loss on Team Identity layer. -2. **Clean separation:** Imported agents have NO knowledge of Project A's codebase. No file paths, no architecture decisions, no stale context. First session on Project B feels like onboarding, not confusion. -3. **User confidence:** The `--review` flag lets users see exactly what's being exported. No surprises in the manifest. -4. **Backward compatibility:** Projects that never export/import work exactly as before. No changes to the default `npx create-squad` flow. -5. **History split adoption:** Within 2 sessions after template update, agents naturally categorize learnings into Portable Knowledge vs Project Learnings without explicit prompting. -6. **CLI discoverability:** `npx create-squad --help` shows export and `--from` options. Users find them without reading docs. - ---- - -## Open Questions - -1. **Should portable knowledge be per-agent or shared?** Currently per-agent (each agent learns different things about the user). But some knowledge is universal — "Brady prefers proposals before execution" applies to everyone. Should there be a `team_portable_knowledge` section in the manifest? - -2. **How many sessions before export is meaningful?** Exporting after one session gives you names and charters but almost no portable knowledge. Should we warn? `"⚠️ Your squad has only had 2 sessions. Export will contain limited portable knowledge. Continue?"` - -3. **What about the Scribe?** Scribe is a special agent — it's defined in `squad.agent.md`, not as a standalone charter. Does it travel? Probably yes (its role is universal), but it doesn't appear in the manifest the same way. - -4. **Versioning the manifest:** If we change the schema in v1.1, old manifests need to still import. JSON schema versioning is straightforward (`squad_manifest_version` field), but we need a migration path from day one. - -5. **Privacy:** Portable knowledge contains observations about the user. If squad sharing becomes real (v2), users need to be able to strip portable knowledge from shared manifests. The `--review` flag helps, but we might need explicit `--strip-knowledge` for sharing. - ---- - -**Review requested from:** Verbal (knowledge extraction strategy), Fenster (CLI implementation), Hockney (testing the round-trip), bradygaster (final sign-off — this is his vision) -**Approved by:** bradygaster -**Implemented:** Wave 2 — Export CLI shipped -**Retrospective:** [Pending] diff --git a/team-docs/proposals/009-v1-sprint-plan.md b/team-docs/proposals/009-v1-sprint-plan.md deleted file mode 100644 index 889522d40..000000000 --- a/team-docs/proposals/009-v1-sprint-plan.md +++ /dev/null @@ -1,715 +0,0 @@ -# Proposal 009: Squad v1 Sprint Plan - -**Author:** Keaton (Lead) -**Date:** 2026-02-08 -**Status:** Superseded — by Proposal 019 -**Approved by:** bradygaster (2026-02-08) -**Amendments:** Sprint 0 added per Fenster/Keaton/Hockney review. Export/import split per Fenster. Tests start Sprint 1 per Hockney. -**Triggered by:** bradygaster — 9 users, whole division talking. Make Squad the best AI dev tool out there. Period. - ---- - -## The Thesis - -Squad v1 is three things: - -1. **A team that gets faster as the session progresses** (not slower) -2. **A team that travels with you** (portable, forwardable, upgradable) -3. **A team that gets smarter at what you do** (skills) - -Everything in this sprint serves one of those three. If it doesn't, it's cut. - ---- - -## What Makes the v1 Cut - -### The Non-Negotiables (Brady's directives) - -| Directive | What it means for v1 | Source proposal | -|-----------|---------------------|----------------| -| **Forwardability** | `npx create-squad upgrade` — existing users get new coordinator versions without losing their team | NEW (this plan) | -| **Portability** | Export/import squad identity across projects | 008 | -| **Skills** | Domain expertise that compounds across projects | NEW (this plan) | -| **Latency fix** | Squad feels faster at message 10 than message 1 | 007 | - -### The v1 Feature Set - -| Feature | Priority | Sprint | Effort | -|---------|----------|--------|--------| -| Forwardability (`upgrade` command) | **P0** | Sprint 1 | 4 hours | -| Latency P0 fixes (context caching + Scribe batching) | **P0** | Sprint 1 | 2 hours | -| Tiered response modes | **P0** | Sprint 1 | 3 hours | -| Coordinator direct handling | **P0** | Sprint 1 | 2 hours | -| History split (Portable Knowledge / Project Learnings) | **P0** | Sprint 2 | 3 hours | -| Skills system (definition, acquisition, export) | **P0** | Sprint 2 | 6 hours | -| Export/import CLI | **P0** | Sprint 2 | 6 hours | -| README rewrite (proposal 006) | **P1** | Sprint 3 | 2 hours | -| Testing infrastructure (happy path + round-trip) | **P1** | Sprint 3 | 4 hours | -| Progressive history summarization | **P1** | Sprint 3 | 3 hours | -| Lightweight spawn template | **P2** | Sprint 3 | 2 hours | - ---- - -## Sprint 1: "Make It Fast" (Days 1-3) - -**Goal:** A session at message 15 should feel as fast as message 1. Fix the DMV problem. - -### 1.1 Forwardability Architecture (Fenster + Kujan) - -**The problem Brady identified:** `index.js` line 30-32 skips `squad.agent.md` if it exists. That means when we ship coordinator improvements, existing users never get them. This is wrong. - -**The fix: `npx create-squad upgrade`** - -``` -npx create-squad # init (existing behavior, but ALWAYS writes squad.agent.md) -npx create-squad upgrade # updates squad.agent.md + templates, preserves .ai-team/ -``` - -**Implementation:** - -1. **Change init behavior:** Remove the skip-if-exists guard on `squad.agent.md`. The coordinator file is OUR code, not user state. Always overwrite it. User state lives in `.ai-team/` — that's what we preserve. - -2. **Add `upgrade` subcommand:** Same as init, but: - - Overwrites `squad.agent.md` (always) - - Overwrites `.ai-team-templates/` (always — these are reference templates) - - Does NOT touch `.ai-team/` (team state, history, decisions, casting — sacred) - - Prints what changed: "✓ squad.agent.md updated to v0.2.0" - -3. **Version header in `squad.agent.md`:** - ```markdown - - # Squad Coordinator - ``` - The upgrade command reads this header, compares to the new version, and reports the delta. If versions match, prints "Already up to date." - -4. **Version `package.json`:** Bump to `0.2.0` for v1 release. The coordinator version tracks independently from the package version but they should align at release boundaries. - -**What this changes about init:** - -```javascript -// BEFORE (wrong for upgrades): -if (fs.existsSync(agentDest)) { - console.log(`${DIM}squad.agent.md already exists — skipping${RESET}`); -} else { - fs.copyFileSync(agentSrc, agentDest); -} - -// AFTER (forwardable): -fs.mkdirSync(path.dirname(agentDest), { recursive: true }); -fs.copyFileSync(agentSrc, agentDest); -console.log(`${GREEN}✓${RESET} .github/agents/squad.agent.md`); -``` - -The init flow ALWAYS writes the coordinator. Templates get the same treatment. `.ai-team/` directories are still created with `{ recursive: true }` (idempotent — safe to re-run). - -**Trade-off:** If a user has manually edited `squad.agent.md` (adding custom instructions), init/upgrade will overwrite those edits. This is acceptable because: (a) `squad.agent.md` is documented as Squad-managed, not user-edited, (b) custom instructions should go in `.ai-team/` files that agents read, not in the coordinator itself, (c) we can add a `--preserve-coordinator` flag later if this becomes a real issue. - -### 1.2 Latency P0: Context Caching + Scribe Batching (Verbal) - -Direct from Proposal 007, Solutions 2 and 4. These are instruction-only changes to `squad.agent.md`. - -**Context caching (add to Team Mode):** -```markdown -**Context efficiency:** -- On your first message this session: Read team.md, routing.md, registry.json. -- On subsequent messages: You already have these in your conversation context. - Do NOT re-read them unless a new agent was added or the user asks you to refresh. -``` - -**Scribe batching (modify After Agent Work):** -```markdown -**Scribe policy:** -- Spawn Scribe ONLY when there are files in .ai-team/decisions/inbox/. -- If no inbox files exist, skip Scribe entirely. -- Decision: no inbox files = no Scribe spawn. Period. -``` - -**Savings:** ~4.5s per message (caching) + ~10s on 50% of messages (Scribe). Zero risk. - -### 1.3 Tiered Response Modes (Verbal + Keaton) - -Direct from Proposal 007, Solution 1. The single highest-impact change. - -**Add routing table to `squad.agent.md`:** - -| Signal | Mode | What happens | -|--------|------|-------------| -| Quick factual question, status check | **Direct** | Coordinator answers. No spawn. ~2-3s. | -| "Change X to Y in file Z", single-line fix | **Direct** | Coordinator does it. No spawn. ~3-5s. | -| Follow-up to work done this session | **Lightweight** | Minimal spawn. Skip history/decisions reads. ~8-12s. | -| "Fix the bug in...", single-domain task | **Standard** | Full agent spawn with context. ~25-35s. | -| Multi-domain, "team build...", new feature | **Full** | Parallel fan-out, full ceremony. ~40-60s. | - -**The rule:** Match ceremony to complexity. A 5-second task should not trigger a 30-second ceremony. - -### 1.4 Coordinator Direct Handling (Verbal) - -Expand the coordinator's permission to handle trivial tasks directly: - -```markdown -**Coordinator handles directly (no spawn):** -- Quick factual questions about the project -- Single-line changes where file path and exact change are specified -- Status summaries and session catch-up -- File rename/move/delete when user specifies exactly what -- Confirming what an agent did in a previous turn - -**Coordinator MUST spawn for:** -- Any task requiring domain judgment -- Multi-file changes -- Architecture decisions -- Tasks addressed to a specific agent by name -- Test writing, code review, quality assessment -``` - -### Sprint 1 Deliverables - -- [ ] `npx create-squad upgrade` works -- [ ] Init always writes `squad.agent.md` (forwardable) -- [ ] Version header in `squad.agent.md` -- [ ] Context caching instructions live in coordinator -- [ ] Scribe batching instructions live in coordinator -- [ ] Tiered response mode routing table live in coordinator -- [ ] Coordinator direct handling rules live in coordinator -- [ ] Manual test: message 10 of a session feels dramatically faster - -**Sprint 1 blocks:** Nothing. All changes are to `index.js` and `squad.agent.md`. Fully parallel work. - ---- - -## Sprint 2: "Make It Yours" (Days 4-7) - -**Goal:** Your squad travels with you. Your squad has skills. The relationship compounds. - -### 2.1 History Split (Verbal + Keaton) - -The prerequisite for everything in Sprint 2. From Proposal 008. - -**Update history.md template:** - -```markdown -# Project Context - -- **Owner:** {user} -- **Project:** {project} -- **Stack:** {stack} -- **Created:** {date} - -## Portable Knowledge - - - -## Project Learnings - - -``` - -**Update spawn prompt in `squad.agent.md`:** - -```markdown -When appending to history.md, categorize your learnings: -- **Portable Knowledge** — user preferences, style, communication patterns. - Things true regardless of project. -- **Project Learnings** — codebase architecture, file locations, tech choices. - Things that only matter here. -``` - -**Existing histories:** No migration needed. Agents naturally adopt the split on their next write. Export heuristic handles unsplit histories. - -### 2.2 Skills: The New Concept - -**What is a skill?** - -A skill is domain expertise that a squad acquires through repeated work in a specific area. It's not a user preference (that's Portable Knowledge). It's not project context (that's Project Learnings). It's **learned patterns about a technology, framework, or domain** that make the squad more effective. - -**Examples:** -- "React: prefer functional components with hooks. Use React.memo for expensive renders. Test with React Testing Library, not Enzyme." -- "Express.js: middleware chain pattern. Always validate request body before business logic. Use express-validator." -- "PostgreSQL: use connection pooling. Prefer prepared statements. Index foreign keys." -- "CLI tools: use commander.js for arg parsing. Always support --help. Exit codes matter." - -**Where skills differ from preferences:** - -| Concept | Belongs to | Example | Portable across users? | -|---------|-----------|---------|----------------------| -| **Preference** | The user | "Brady prefers explicit error handling" | No (personal) | -| **Skill** | The squad | "React: use hooks, test with RTL" | Yes (domain knowledge) | -| **Project Learning** | The project | "Auth middleware is in src/auth/" | No | - -A preference is about *who you work with*. A skill is about *what you work on*. Both are portable. But skills can be shared across squads — that's what makes them special. - -**Implementation: `skills.md` per squad** - -```markdown -# Squad Skills - - - -## React -- Prefer functional components with hooks over class components -- Use React.memo for expensive render trees -- Test with React Testing Library (user-centric queries: getByRole, getByText) -- State management: prefer zustand for simple state, Redux Toolkit for complex -- Acquired: 2026-02-10 (project: my-dashboard) - -## TypeScript -- Strict mode always -- Prefer discriminated unions over type assertions -- Use zod for runtime validation at boundaries -- Acquired: 2026-02-07 (project: squad) - -## Express.js -- Middleware chain: auth → validate → business logic → response -- Use express-validator for request validation -- Error handling: custom AppError class with status codes -- Acquired: 2026-02-15 (project: my-api) -``` - -**How skills are acquired:** - -1. **Implicit:** When agents work on a project and observe patterns, they log domain learnings to `skills.md` instead of project-specific history. The spawn prompt instruction: - ```markdown - When you learn something about a TECHNOLOGY or FRAMEWORK (not the project, - not the user), add it to .ai-team/skills.md under the relevant domain heading. - Skills are patterns that would help on ANY project using that technology. - ``` - -2. **Explicit:** The user can tell the squad directly: "Team, we always use zustand for state management in React projects. Add that as a skill." - -3. **On export:** Skills travel with the squad. When imported into a new React project, the squad already knows the team's React patterns. - -**How skills are used:** - -The spawn prompt includes: -```markdown -Read .ai-team/skills.md — these are domain skills your squad has developed. -If the current task involves a domain listed in skills.md, apply those patterns. -If you learn new domain patterns during this task, append them to skills.md. -``` - -**Skills + Portability = The Killer Combo:** - -Brady's insight: "a squad that works on 5 React projects doesn't just know the USER — it has React SKILLS." - -Export captures `skills.md`. Import restores it. Day one on a new React project, the squad already knows: -- Use hooks, not classes -- Test with RTL -- Use zustand for state management -- The middleware chain pattern for Express - -The squad isn't starting from scratch. It's bringing domain expertise earned across every project it's ever worked on. - -**Skills + Sharing (v2 teaser):** - -Skills are the most naturally shareable artifact. Unlike preferences (personal) or project learnings (local), skills are domain knowledge. A "React Skills Pack" could be published independently of any squad's identity. But that's v2. For v1, skills live in `skills.md` and travel with the squad on export/import. - -### 2.3 Export/Import CLI (Fenster + Kujan) - -From Proposals 008 and 008-platform. Now including skills. - -**CLI commands:** - -``` -npx create-squad export # → ./squad-export.json -npx create-squad export --out FILE # → custom path -npx create-squad import FILE # import squad from manifest -npx create-squad import FILE --force # replace existing squad (archive old) -npx create-squad upgrade # update coordinator + templates (Sprint 1) -``` - -**What gets exported (updated with skills):** - -| Source | Exported? | Notes | -|--------|-----------|-------| -| `casting/` (registry, history, policy) | ✅ Full | Squad identity | -| `agents/*/charter.md` | ✅ Full | Agent identity | -| `agents/*/history.md` | ⚠️ Portable Knowledge section only | Heuristic extraction for unsplit histories | -| `skills.md` | ✅ Full | Domain expertise — the new crown jewel | -| `team.md` | ⚠️ Roster only | Strip project context | -| `routing.md` | ✅ Full | Team structure | -| `decisions.md` | ❌ No | Project-specific | -| `orchestration-log/` | ❌ No | Session artifacts | - -**Manifest schema (v1.0):** - -```json -{ - "squad_manifest_version": "1.0", - "exported_at": "ISO-8601", - "exported_from": "owner/repo", - "casting": { "registry": {}, "history": {}, "policy": {} }, - "agents": { - "keaton": { - "charter": "markdown string", - "portable_knowledge": ["observation 1", "observation 2"] - } - }, - "skills": "full skills.md content", - "team": "cleaned team.md", - "routing": "routing.md content" -} -``` - -**Import flow:** -1. Validate `.squad` or `.json` manifest -2. Refuse if `.ai-team/team.md` exists (unless `--force`) -3. Copy `squad.agent.md` and templates (always — forwardable) -4. Restore casting state with `imported_from` metadata -5. Create agent directories with charters and seeded histories -6. Write `skills.md` from manifest -7. Create empty `decisions.md`, inbox, orchestration-log -8. Print import summary - -**`--force` behavior:** -1. Archive existing `.ai-team/` to `.ai-team-archive-{timestamp}/` -2. Proceed with normal import - -**No `--merge` in v1.** Honest refusal with clear messaging. Merge is v2. - -### 2.4 Coordinator: Imported Squad Detection (Verbal) - -~10 lines added to `squad.agent.md` Team Mode: - -```markdown -**Imported squad detection:** -If registry.json has an `imported_from` field and team.md Project Context -has "(to be filled)": -1. Greet the user by name — the team is back. -2. Ask about the new project — orient the team. -3. Fill in Project Context. -4. Clear the `imported_from` flag. -5. Read skills.md and note which domains the team already knows. -``` - -### Sprint 2 Deliverables - -- [ ] History template has Portable Knowledge / Project Learnings sections -- [ ] Spawn prompts instruct agents on categorizing learnings -- [ ] `skills.md` concept implemented (template + spawn prompt instructions) -- [ ] `npx create-squad export` produces valid manifest -- [ ] `npx create-squad import FILE` restores squad with skills -- [ ] `--force` flag archives and replaces -- [ ] Coordinator detects imported squads and runs onboarding -- [ ] Round-trip test: export from project A → import into project B → verify fidelity - -**Sprint 2 blocks:** Sprint 1 must ship first (forwardability is prerequisite for template updates reaching users). - ---- - -## Sprint 3: "Make It Shine" (Days 8-10) - -**Goal:** Polish, testing, documentation. The experience that makes people say "holy crap." - -### 3.1 README Rewrite (McManus) - -Ship Proposal 006. The README should sell Squad in 30 seconds: -- "Your AI agent team. Any project." (updated positioning with portability) -- Elevate casting as a feature -- Skills section: "Your squad learns your tech stack" -- Quick Start includes export/import -- "Why Squad?" section - -### 3.2 Testing Infrastructure (Hockney) - -From Hockney's original assessment. Minimum viable test suite: - -1. **Init test:** Run `index.js` in temp dir → verify file structure created -2. **Upgrade test:** Run init → modify `.ai-team/` → run upgrade → verify `.ai-team/` preserved, `squad.agent.md` updated -3. **Export/import round-trip:** Init → create mock team state → export → import into new dir → verify fidelity -4. **Forwardability test:** Init with old `squad.agent.md` → upgrade → verify new version header -5. **Skills persistence test:** Add skills → export → import → verify skills.md intact - -Framework: `tap` (already decided by Hockney). No new dependencies beyond the test framework. - -### 3.3 Progressive History Summarization (Verbal) - -From Proposal 007, Solution 7. Scribe responsibility. - -When `history.md` exceeds ~3,000 tokens: -- Summarize entries older than 2 weeks into a "Core Context" section -- Archive originals to `history-archive.md` -- Keeps per-spawn context load under ~2,000 tokens regardless of project age - -### 3.4 Lightweight Spawn Template (Verbal) - -From Proposal 007, Solution 5. For tiered response "Lightweight" mode: - -```markdown -agent_type: "general-purpose" -prompt: | - You are {Name}, the {Role}. Make this change: - {task with exact file paths} - Do NOT read history.md or decisions.md. Just do it and report. -``` - -Saves ~5-8 seconds per lightweight spawn. - -### Sprint 3 Deliverables - -- [ ] README rewrite shipped -- [ ] Test suite with 5 core tests passing -- [ ] Progressive history summarization in Scribe instructions -- [ ] Lightweight spawn template in coordinator -- [ ] Manual end-to-end validation of full v1 flow - ---- - -## What We're NOT Doing in v1 - -This list is as important as what's in. Cutting these is a decision, not an oversight. - -| Feature | Why it's cut | When | -|---------|-------------|------| -| **Squad merge** (`--merge` on import) | Universe conflicts are unsolvable without opinionated rules. Ship `--force`, learn from usage. | v1.1 | -| **LLM-assisted history classification** | Manual curation + heuristic extraction is good enough for v1. Users can review the manifest. | v1.1 | -| **Squad sharing / Gist publishing** | Needs privacy controls (strip preferences for sharing). Personal portability first. | v1.2 | -| **Squad registry / marketplace** | Premature. Need a community first. | v2 | -| **Agent-to-agent negotiation** | Industry trend (Verbal, Proposal 005) but not v1 material. Current fan-out-and-merge works. | v2 | -| **Dynamic micro-specialist spawning** | 10+ narrow experts is a v2 vision. The 5-role + skills model handles v1. | v2 | -| **Speculative execution** | Anticipatory agent spawning is cool but risky. Get the basics perfect first. | v2 | -| **Video content** | Important for adoption but not blocking v1 code. McManus and Verbal can produce in parallel. | Parallel track | -| **Demo script / recording** | Same — production concern, not code concern. | Parallel track | -| **Copilot SDK integration** | Decision is "stay independent." Revisit when SDK offers something we can't build. | v2+ | -| **User overrides** ("full review on this") | Nice to have, but tiered modes cover 95% of the intent. | v1.1 | -| **Partial export** (`--agents keaton,verbal`) | Full squad export is the right v1 default. Partial is a refinement. | v1.1 | -| **`preferences.md` as separate file** | Verbal proposed this (008-experience). For v1, Portable Knowledge section in history.md is sufficient. Separate file adds migration cost with limited near-term benefit. Revisit based on usage. | v1.1 | -| **`squad-profile.md`** | Team meta-history is cool but not MVP. Skills.md covers the domain knowledge gap. Profile is relationship tracking — v1.1. | v1.1 | -| **Squad diff** (`create-squad diff`) | The quantified-self feature Verbal designed. Compelling but not v1. Needs longitudinal data. | v1.2 | - ---- - -## The Forwardability Architecture (Detail) - -Brady said: "Forwardability is non-negotiable." Here's the full picture. - -### What is forwardable vs. what is user state - -| Artifact | Owner | Forwardable? | On upgrade... | -|----------|-------|-------------|---------------| -| `squad.agent.md` | Squad (us) | ✅ Yes | Always overwritten | -| `.ai-team-templates/` | Squad (us) | ✅ Yes | Always overwritten | -| `.ai-team/team.md` | User's squad | ❌ Sacred | Never touched | -| `.ai-team/agents/*/` | User's squad | ❌ Sacred | Never touched | -| `.ai-team/casting/` | User's squad | ❌ Sacred | Never touched | -| `.ai-team/decisions.md` | User's squad | ❌ Sacred | Never touched | -| `.ai-team/skills.md` | User's squad | ❌ Sacred | Never touched | -| `.ai-team/orchestration-log/` | User's squad | ❌ Sacred | Never touched | - -**The bright line:** We own the coordinator and templates. Users own `.ai-team/`. Upgrade = our code gets updated, their state stays intact. - -### Versioning strategy - -``` -package.json version: 0.2.0 (npm release version) -squad.agent.md version: 0.2.0 (coordinator instruction version) -manifest version: 1.0 (export format version) -``` - -- Package version increments on every release -- Coordinator version tracks meaningful instruction changes -- Manifest version increments only on breaking schema changes (rare) - -### The upgrade flow - -``` -$ npx create-squad upgrade - -Upgrading Squad... - ✓ squad.agent.md: 0.1.0 → 0.2.0 - ✓ .ai-team-templates/ updated - ✗ .ai-team/ — preserved (your team is safe) - -What's new in 0.2.0: - - Tiered response modes (Direct/Lightweight/Standard/Full) - - Coordinator context caching (faster repeat messages) - - Scribe batching (no more empty Scribe spawns) - - Skills support (your squad learns domains) - - Export/Import (take your squad to new projects) -``` - ---- - -## Skills Architecture (Detail) - -### File: `.ai-team/skills.md` - -Created during init (empty template). Grows as the squad works. - -**Template:** -```markdown -# Squad Skills - - - - -``` - -**Spawn prompt addition to `squad.agent.md`:** -```markdown -**Skills:** -- Read .ai-team/skills.md at the start of every Standard or Full mode task. -- If the current task involves a domain listed in skills.md, apply those patterns. -- If you discover a reusable pattern about a technology or framework during your work, - append it to skills.md under the appropriate domain heading. -- Skills are about TECHNOLOGIES and DOMAINS, not about the user or the project. - "Use React Testing Library" is a skill. "Brady prefers RTL" is a preference. - "Auth module is in src/auth/" is a project learning. -``` - -**Skills vs. Copilot's `store_memory`:** - -The Copilot platform has `store_memory` for persisting facts. Skills are different: -- `store_memory` is per-session, platform-managed, opaque -- Skills are per-squad, filesystem-backed, human-readable, exportable, shareable -- Skills compound across projects via export/import -- Skills are curated domain knowledge, not raw memory dumps - -This is exactly the kind of thing that makes Squad's filesystem-first approach a differentiator. - -### Skill Acquisition Flow - -``` -Session 1 (React project): - User: "Build a dashboard with React" - Fenster builds it, observes: functional components, hooks pattern - → Appends to skills.md: "## React\n- Prefer functional components with hooks" - -Session 5 (same project): - Fenster has been writing tests with RTL - → Appends: "- Test with React Testing Library (getByRole, getByText)" - -Export → Import into new React project: - First session: squad already knows React patterns - Fenster scaffolds with hooks, writes RTL tests — without being told - -Session 1 (new Express project): - Squad has no Express skills yet - Fenster learns the middleware pattern - → Appends: "## Express.js\n- Middleware chain: auth → validate → business logic" - -Export now contains React + Express skills. -Next project gets both. -``` - ---- - -## Dependency Map - -``` -Sprint 1 (parallel tracks): - ├── 1.1 Forwardability (Fenster + Kujan) ─────────────────┐ - ├── 1.2 Latency P0 (Verbal) ──────────────────────────────┤ - ├── 1.3 Tiered modes (Verbal + Keaton) ───────────────────┤ - └── 1.4 Direct handling (Verbal) ─────────────────────────┘ - │ -Sprint 2 (sequential dependencies): │ - ├── 2.1 History split (Verbal + Keaton) ← depends on 1.1 │ - │ └── 2.2 Skills system (Verbal + Keaton) ← depends on 2.1 - │ └── 2.3 Export/Import (Fenster + Kujan) ← depends on 2.1 + 2.2 - └── 2.4 Imported squad detection (Verbal) ← depends on 2.3 - │ -Sprint 3 (parallel tracks): │ - ├── 3.1 README rewrite (McManus) ← can start Sprint 2 │ - ├── 3.2 Testing (Hockney) ← depends on 2.3 │ - ├── 3.3 History summarization (Verbal) ← depends on 2.1 │ - └── 3.4 Lightweight spawn (Verbal) ← depends on 1.3 │ -``` - -### Who Does What - -| Agent | Sprint 1 | Sprint 2 | Sprint 3 | -|-------|----------|----------|----------| -| **Keaton** | Architecture review on tiered modes, direct handling rules | Skills architecture, history split review | Final integration review | -| **Verbal** | Latency P0 instructions, tiered mode routing, direct handling rules | History split prompts, skills prompt instructions, imported squad detection | History summarization, lightweight spawn template | -| **Fenster** | Forwardability changes to `index.js` | Export/import CLI implementation | Bug fixes | -| **Kujan** | Forwardability review (platform implications) | Export/import platform feasibility | — | -| **Hockney** | — | — | Test suite (5 core tests) | -| **McManus** | — | — (can start README draft) | README rewrite, messaging update | - -### Parallel Tracks (Non-Blocking) - -These run alongside the sprints and don't block v1 code: - -| Track | Owner | Status | -|-------|-------|--------| -| Video trailer (75s) | McManus + Verbal | Proposal 005 approved, script needed | -| Demo script finalization | McManus | Proposal 004, needs Brady recording session | -| DevRel polish (6 items) | McManus | Proposal 002, can execute independently | - ---- - -## Success Criteria - -### The "Holy Crap" Moments - -These are the specific interactions that make users say it. If we ship v1 and these don't work, we failed. - -1. **"It just... knew."** — Import squad into new React project. First message: "Set up the project." Squad uses TypeScript strict mode, hooks, RTL — without being told. Skills + preferences working together. - -2. **"That was instant."** — Message 12 of a session. User says "change the port to 8080 in server.ts." Coordinator handles it directly in ~3 seconds. No spawn. No ceremony. The team knows when to go fast. - -3. **"My team is back."** — Export from finished project. Import into new project. Squad greets user by name, references their working style, asks about the new codebase. Feels like onboarding a trusted team, not configuring a tool. - -4. **"It got better."** — Third project with the same squad. Hockney (Tester) writes tests matching the exact patterns the user has corrected toward over two previous projects. The squad's skills compound visibly. - -5. **"I upgraded and nothing broke."** — Run `npx create-squad upgrade` on an existing project. New coordinator features appear. All team state, history, skills, casting preserved. Zero friction. - -### Measurable Targets - -| Metric | Current (v0.1) | Target (v1) | -|--------|----------------|-------------| -| Trivial task latency (message 10+) | ~30-35s | ~3-5s | -| Simple task latency (single agent) | ~30-35s | ~12-15s | -| Complex task latency (multi-agent) | ~60-70s | ~50-60s | -| Scribe spawns per 10-message session | 10 | 3-4 | -| Coordinator re-reads per session | 4-5 per message | 0-1 after first | -| Export/import round-trip fidelity | N/A | 100% for casting + charters + skills | -| Upgrade preserves user state | No upgrade exists | 100% of `.ai-team/` preserved | -| Time to first useful agent action (imported squad) | N/A | < 30 seconds | -| Test coverage (core paths) | 0 tests | 5 tests passing | - -### What "Done" Looks Like - -v1 is done when: - -1. ✅ `npx create-squad` initializes a project (existing behavior, but now always writes coordinator) -2. ✅ `npx create-squad upgrade` updates coordinator without touching team state -3. ✅ `npx create-squad export` produces a valid manifest with casting, charters, skills, portable knowledge -4. ✅ `npx create-squad import FILE` restores a squad with full identity and skills -5. ✅ Coordinator uses tiered response modes (Direct/Lightweight/Standard/Full) -6. ✅ Coordinator caches context within a session (no re-reads) -7. ✅ Scribe only spawns when inbox has files -8. ✅ Agents categorize learnings into Portable Knowledge vs Project Learnings -9. ✅ Agents acquire and apply skills from `skills.md` -10. ✅ 5 core tests pass -11. ✅ README reflects v1 features -12. ✅ Brady runs it and says something unrepeatable in a good way - ---- - -## The Compound Bet - -Here's why these features together are more than the sum of their parts: - -**Forwardability** means every Squad user gets every improvement automatically. We ship once, 9 users (and growing) benefit immediately. No "you need to re-create your squad." - -**Latency fixes** mean the experience gets better as you use it more. Progressive trust. The squad learns when to go fast. This is the difference between a tool that wears out its welcome and a tool that earns its place. - -**Portability** means the investment compounds across projects. Every project you work with your squad makes the next project better. The switching cost isn't lock-in — it's accumulated relationship capital. - -**Skills** mean the squad gets smarter at specific domains. Not just "knows the user" but "knows React." Not just "knows React" but "knows React the way THIS team uses React." Portable, shareable, compounding. - -Together: **A team that gets faster, smarter, and more personal with every project — and you never have to rebuild it.** - -That's the product that makes people say "throw a squad at it" — not as a tagline, but as a truth. Because the squad they're throwing has earned its reputation across every project they've worked together. - -That's v1. Let's ship it. - -— Keaton - ---- - -**Review requested from:** Verbal (prompt engineering implications), Fenster (implementation feasibility), Hockney (test plan), McManus (messaging), bradygaster (final sign-off) -**Approved by:** [Pending] -**Implemented:** [Pending] -**Retrospective:** [Pending] diff --git a/team-docs/proposals/010-skills-system.md b/team-docs/proposals/010-skills-system.md deleted file mode 100644 index fc29d14cc..000000000 --- a/team-docs/proposals/010-skills-system.md +++ /dev/null @@ -1,1073 +0,0 @@ -# Proposal 010: Skills System — Agent Skills Standard Edition - -**Author:** Verbal (Prompt Engineer & AI Strategist) -**Date:** 2026-02-08 -**Revised:** 2026-02-09 — Aligned with Agent Skills standard (SKILL.md format), added MCP tool declarations -**Status:** Approved ✅ Shipped -**Triggered by:** bradygaster — *"when i say skills i mean claude-and-copilot-compliant skills that adhere to the anthropic 'skills.md' way"* and *"could we also find a way to be able to tell copilot which mcp tools our skills would need?"* -**Builds on:** Proposal 008 (Portable Squads), Proposal 007 (Progressive Trust) - ---- - -## The Insight (Updated) - -Brady saw it before I did — twice. First: skills are the missing layer between preferences and tools. Second: we shouldn't invent a format. The Agent Skills standard exists. It's adopted by Claude and Copilot. It has a spec. We use it. - -But here's what nobody else is doing with it: **generating skills from real work.** - -Every SKILL.md out there today is a static file. Someone sat down, wrote instructions, and committed them. That's documentation with extra steps. Useful, sure. But static. - -Squad makes skills a **living thing.** Your squad works on 5 React projects and organically produces a `react-patterns/SKILL.md` that captures everything the team learned. Export that. Import it into a new project. Day one, the agents are React experts. The skill wasn't written — it was *earned*. - -The standard gives us the format. Squad gives it a lifecycle. - -Preferences are about the **human**. Skills are about the **agent**. - -`preferences.md` captures: *"Brady likes explicit error handling."* That's about Brady. It travels because Brady travels. - -A `react-server-components/SKILL.md` captures: *"Server components are the default in app router. Don't add 'use client' unless you need interactivity. Data fetching happens directly in the component. Here's the streaming pattern for dashboards. Here are the hydration pitfalls."* That's domain expertise. It travels because the agent's *competence* travels. - -And Brady's second insight — the MCP angle — makes this even bigger. A skill that says "I know how to manage database migrations" should ALSO say "I need the Postgres MCP server to do it." Skills declare their tool dependencies. Copilot wires them up. The agent arrives with both the knowledge AND the tools. - -Nobody in the industry has this. Not the skill format (that's standardized now). Not earned skills. Not skills that declare their MCP dependencies. Not skills that compound across projects. The standard is the foundation. Squad builds the skyscraper. - ---- - -## 1. The Agent Skills Standard — What We're Building On - -The Agent Skills format is an open standard originally from Anthropic, now adopted by Claude and GitHub Copilot. We don't invent a format. We use this one. - -### The Format - -A skill is a directory containing a `SKILL.md` file: - -``` -skill-name/ -├── SKILL.md # Required: YAML frontmatter + markdown instructions -├── scripts/ # Optional: executable code -├── references/ # Optional: documentation, examples -└── assets/ # Optional: templates, resources -``` - -The `SKILL.md` has YAML frontmatter + markdown body: - -```yaml ---- -name: react-server-components -description: > - Patterns for React Server Components in Next.js app router. - Use when building data-heavy pages, dashboard layouts, or - any Next.js project using the app router. -license: Apache-2.0 -compatibility: Designed for Claude Code and GitHub Copilot -allowed-tools: Bash(npx:*) Bash(npm:*) Read Write -metadata: - author: squad/fenster - version: "1.0" - confidence: high - projects-applied: 4 - last-validated: "2026-02-08" - acquired-by: organic ---- -``` - -**Required fields:** `name` (lowercase hyphen-case, matches folder, max 64 chars) and `description` (max 1024 chars — what + when). - -**Optional:** `license`, `compatibility`, `metadata` (arbitrary key-value), `allowed-tools` (space-delimited list of pre-approved tools). - -### Progressive Disclosure — How Agents Consume Skills - -This is elegant and we use it exactly as designed: - -1. **Discovery:** Agents load only `name` + `description` at startup (~50-100 tokens each). Cheap. Every skill is visible. -2. **Activation:** When a task matches a skill's description, the agent reads the full `SKILL.md`. Only pays the token cost when relevant. -3. **Execution:** Agent follows the instructions, loading referenced files on demand. - -The coordinator injects available skills into spawn prompts via the standard XML: - -```xml - - - react-server-components - Patterns for React Server Components in Next.js app router. Use when building data-heavy pages, dashboard layouts, or any Next.js project using the app router. - .ai-team/skills/react-server-components/SKILL.md - - - tdd-api-workflow - TDD workflow for API endpoints: OpenAPI spec → types → tests → handlers. Use when building REST or GraphQL APIs. - .ai-team/skills/tdd-api-workflow/SKILL.md - - -``` - -This works well for Squad because it solves our context budget problem (Proposal 003). Only names + descriptions load at spawn. Full skill content loads on demand. A squad with 30 skills pays ~3K tokens at startup, not 30K. - -### What Squad Adds to the Standard - -The standard gives us format and discovery. Squad adds: - -| Standard provides | Squad adds | -|---|---| -| Static SKILL.md files | Skills that are **generated** from real work | -| Manual authoring | **Organic acquisition** — agents write skills after completing tasks | -| One-time creation | **Lifecycle** — acquisition → reinforcement → correction → deprecation | -| Per-project | **Portable** — skills travel with the squad across projects | -| `allowed-tools` for CLI tools | **MCP tool declarations** — skills specify which MCP servers they need | -| `metadata` for static info | **Confidence tracking** — metadata captures how earned and validated a skill is | - -The standard is the foundation. Squad makes it alive. - ---- - -## 2. MCP Tool Declarations — The Brady Angle - -Brady's second insight: *"could we also find a way to be able to tell copilot which mcp tools our skills would need?"* - -This matters. A skill shouldn't just contain knowledge — it should declare its **tool dependencies**. When a squad agent activates a skill, the coordinator (or Copilot itself) should know what MCP servers that skill needs. - -### How It Works - -The `allowed-tools` field in the SKILL.md spec is designed for declaring pre-approved tools. We extend this to include MCP tool references: - -```yaml ---- -name: database-migration -description: > - Database migration workflows using Prisma ORM. - Use when setting up, modifying, or managing database schemas. -allowed-tools: Bash(npx:prisma*) Bash(npm:*) Read Write -metadata: - author: squad/fenster - version: "1.2" - confidence: high - mcp-tools: - - server: postgres - reason: "Direct database access for migration verification and rollback" - - server: github - reason: "PR creation for migration review workflow" ---- -``` - -The `allowed-tools` field handles standard CLI tools per the spec. The `metadata.mcp-tools` array extends this with MCP server declarations — which MCP servers the skill expects to be available, and why. - -### Why `metadata` Instead of a New Top-Level Field - -The SKILL.md spec says `metadata` accepts arbitrary key-value pairs. We put MCP declarations there because: - -1. **Spec-compliant.** No spec extensions needed. Any tool that reads SKILL.md ignores unknown metadata keys. -2. **Progressive.** If the spec later adds a `required-mcp-servers` field, we adopt it. Until then, metadata works. -3. **Copilot-friendly.** Copilot reads SKILL.md. It already knows how to wire up MCP servers. Putting the declaration in a predictable metadata key lets Copilot's own agent logic discover and wire dependencies. - -### MCP Declaration Examples - -**Deploy to Azure:** -```yaml -metadata: - mcp-tools: - - server: azure - reason: "Resource provisioning, deployment, and configuration" - - server: docker - reason: "Container image building and registry operations" -``` - -**Full-stack React + Postgres:** -```yaml -metadata: - mcp-tools: - - server: postgres - reason: "Schema management and query testing" - - server: github - reason: "PR workflow and code review automation" -``` - -**API documentation:** -```yaml -metadata: - mcp-tools: - - server: fetch - reason: "Validating API endpoints against documentation" -``` - -### The Coordinator's Role - -When the coordinator activates a skill for a spawned agent: - -1. Read the skill's `metadata.mcp-tools` -2. Check if those MCP servers are available in the current environment -3. If available: include them in the spawn context — the agent knows it can use them -4. If missing: flag it — *"This skill expects the Postgres MCP server but it's not configured. The agent can still apply the knowledge, but won't have direct database access."* - -This is information, not enforcement. Skills work without their MCP tools — they just work *better* with them. The knowledge is in the SKILL.md. The tools accelerate execution. - ---- - -## 3. The Skill Taxonomy — What Gets Captured - -Skills exist on a spectrum. The taxonomy matters because different skill types get acquired differently and map to different SKILL.md structures. - -| Type | What it is | Example | SKILL.md pattern | -|------|-----------|---------|-----------------| -| **Pattern** | A learned code convention | "Always use React.lazy for code splitting" | Short body, code examples, anti-patterns | -| **Domain Expertise** | Deep tech knowledge | "React Server Components in Next.js" | Long body with sections: What I Know, Pitfalls, Patterns | -| **Workflow** | A proven process | "TDD for API endpoints" | Step-by-step instructions, references to tools | -| **Procedural** | Step-by-step recipe | "Next.js 14 project setup" | Ordered steps, scripts/ directory, templates | -| **Anti-pattern** | What NOT to do | "Don't useEffect for fetching in app router" | Problem → Why It's Wrong → What To Do Instead | -| **Integration** | How techs work together | "Prisma + Next.js singleton pattern" | Cross-reference multiple domains, MCP tool declarations | - -### A Full SKILL.md Example (Earned by Squad) - -``` -.ai-team/skills/react-server-components/ -├── SKILL.md -└── references/ - └── streaming-patterns.md -``` - -```yaml ---- -name: react-server-components -description: > - Patterns for React Server Components in Next.js app router. - Use when building data-heavy pages, dashboard layouts, or - any Next.js project using the app router. Covers data fetching, - streaming, client/server boundaries, and common hydration pitfalls. -compatibility: Designed for Claude Code and GitHub Copilot -allowed-tools: Bash(npx:*) Bash(npm:*) Read Write -metadata: - author: squad/fenster - version: "1.3" - confidence: high - projects-applied: 4 - last-validated: "2026-02-08" - acquired-by: organic - skill-type: domain-expertise - squad-origin: the-usual-suspects ---- - -# React Server Components — Next.js App Router - -## Core Principles - -- Server components are the DEFAULT in app router — don't add "use client" unless you need interactivity -- Data fetching happens directly in the component with async/await — no useEffect, no client-side fetch -- Server components can import server-only modules safely -- Client components can't import server components, but server components CAN render client components - -## Data Fetching Patterns - -- Layout-level data fetching with streaming for dashboard pages -- Parallel data fetching with Promise.all in server components -- Use `loading.tsx` for Suspense boundaries — automatic streaming - -For advanced streaming patterns, see `references/streaming-patterns.md`. - -## Common Pitfalls (Earned the Hard Way) - -- Forgetting to mark interactive components with "use client" → cryptic hydration errors -- Trying to use hooks in server components → fails silently in some builds -- Large data fetches in server components without streaming → slow TTFB -- Bringing pages router habits into app router — watch for useEffect data fetching - -## Client/Server Boundary - -- Put "use client" as LOW in the tree as possible — only the interactive leaf, not the parent layout -- Client component islands inside server-rendered pages: the composition pattern -- When in doubt: server component. Only go client for: event handlers, hooks, browser APIs - -## What This Skill Doesn't Cover - -- Advanced RSC streaming with nested Suspense boundaries (limited experience) -- Middleware-based auth (used next-auth, haven't done custom middleware) -- ISR/SSG trade-offs at scale -``` - -Notice: this isn't a tutorial someone wrote. It's **earned expertise** — patterns applied, pitfalls discovered, gaps acknowledged. The "What This Skill Doesn't Cover" section is critical. A skilled agent knows its boundaries. - ---- - -## 4. How Skills Get Acquired - -Squad's unique value: skills aren't authored — they're **earned.** Every other use of the Agent Skills standard starts with someone writing a SKILL.md by hand. Squad starts with agents *generating* SKILL.md files from real work. - -### 4.1 Organic Acquisition (Primary) - -Skills emerge naturally from working on projects. This is the default path. - -**The pattern:** -1. Agent works on a task (e.g., Fenster sets up a React project) -2. Agent completes the task successfully -3. During the history-append phase, agent identifies reusable domain knowledge -4. Agent writes or updates a SKILL.md in the skills directory - -**The trigger instruction** (added to spawn prompts): - -```markdown -After completing work, evaluate: did I use or develop knowledge that would be -useful in a DIFFERENT project with similar technology? If yes, create or update -a skill in `.ai-team/skills/{skill-name}/SKILL.md` using the Agent Skills format. - -The SKILL.md must have: -- YAML frontmatter with `name` and `description` (required) -- `metadata.confidence` (low/medium/high based on project count) -- `metadata.projects-applied` (number) -- `metadata.acquired-by` (organic/taught/imported) -- Markdown body: what you learned, pitfalls discovered, patterns that worked - -Do NOT record project-specific facts as skills. "We use port 3000" is not a skill. -"Express apps should configure CORS before routes" is a skill. - -If the skill uses MCP tools (database, cloud services, external APIs), declare them: - metadata: - mcp-tools: - - server: - reason: "" -``` - -**Why organic is primary:** Skills should reflect *real experience*, not theoretical knowledge. An agent that's set up 5 React projects has earned React skills. An agent that read a tutorial has not. Organic acquisition means skills are grounded in actual work. They come with battle scars. - -### 4.2 Explicit Teaching - -Users can directly teach skills to their squad. - -**Example interaction:** - -> **Brady:** "Verbal, learn this: when we set up a new API, always use Zod for request validation, never trust `req.body` directly, and generate OpenAPI specs from the Zod schemas using `zod-to-openapi`." -> -> **Verbal:** "Got it. I'm creating a skill: `zod-request-validation/SKILL.md`. Marking it as user-taught, applicable to the whole squad. If Fenster or Hockney see a pattern that contradicts this, they'll flag it for correction." - -Explicit teaching creates a SKILL.md with `metadata.acquired-by: taught`. Confidence starts at medium (user authority) rather than low (untested). - -### 4.3 Cross-Agent Skill Transfer - -Agents learn from each other's work within a squad. - -**How it works:** -- When Keaton reviews Fenster's code and identifies a strong pattern, it becomes a squad-level skill -- When Hockney writes tests that expose a pattern issue, the implementing agent learns the anti-pattern -- Scribe can identify recurring cross-agent learnings during decision merges and propose new skills - -**Example:** - -> Keaton reviews Fenster's API implementation and says: "The error handling pattern here is good — always wrapping service calls with typed Result objects instead of try-catch. Let's make this a squad standard." -> -> **Result:** A new `typed-result-pattern/SKILL.md` is created with `metadata.author: squad` — available to all agents. - -### 4.4 Skill Packs — Importing from the Community (Future — v2) - -Because we use the Agent Skills standard, Squad can import skills from *anywhere* — not just Squad-generated skills. Any compliant SKILL.md works. - -```bash -npx create-squad skills:add react-nextjs-2024 -``` - -This downloads a curated skill pack: standard SKILL.md files with tested patterns, known pitfalls, recommended workflows. The squad inherits the knowledge without having earned it project-by-project. - -**Imported skills get a confidence downgrade:** - -```yaml -metadata: - confidence: low - acquired-by: imported - import-source: "community/react-nextjs-2024" -``` - -Confidence starts low because the squad hasn't validated the knowledge through practice. As the squad applies the imported skill successfully, confidence rises through reinforcement — the same lifecycle as organically earned skills. - -**Why this is v2:** Skills need to be validated through organic use first. V1 focuses on earned skills. V2 adds imported skills with the imported confidence marker. The format is already compatible — it's just a distribution question. - ---- - -## 5. Storage Architecture — Standard-Compliant - -### The `skills/` Directory - -Skills live in `.ai-team/skills/` as standard Agent Skill directories: - -``` -.ai-team/ -├── skills/ # All skills — standard SKILL.md format -│ ├── react-server-components/ -│ │ ├── SKILL.md # Standard format -│ │ └── references/ -│ │ └── streaming-patterns.md -│ ├── tdd-api-workflow/ -│ │ └── SKILL.md -│ ├── zod-request-validation/ -│ │ └── SKILL.md -│ ├── prisma-nextjs-singleton/ -│ │ ├── SKILL.md -│ │ └── scripts/ -│ │ └── prisma-client-setup.ts # Reusable template -│ └── deploy-to-azure/ -│ └── SKILL.md -├── agents/ -│ ├── keaton/ -│ │ ├── charter.md -│ │ ├── history.md -│ │ └── preferences.md # About the USER (Proposal 008) -│ ├── fenster/ -│ │ ├── charter.md -│ │ ├── history.md -│ │ └── preferences.md -│ └── ... -``` - -### Why a Flat `skills/` Directory (Not Per-Agent) - -The original proposal had per-agent `skills.md` files. We're changing this. Here's why: - -1. **Standard compliance.** The Agent Skills format is skill-per-directory. One SKILL.md per skill, not one skills.md per agent. -2. **Skills are team knowledge.** When Fenster learns a React pattern, it should be available to the whole squad. Per-agent siloing fragments knowledge. -3. **Discovery works better.** The coordinator scans `.ai-team/skills/*/SKILL.md` frontmatter at spawn time. Flat directory = simple glob = fast discovery. -4. **Portability is cleaner.** Export copies the skills directory. Import restores it. No per-agent reassembly needed. -5. **MCP declarations are per-skill, not per-agent.** A Postgres MCP dependency belongs to the `database-migration` skill, not to Fenster. - -**Agent attribution via metadata:** Instead of per-agent skill files, each SKILL.md tracks which agent(s) contributed: - -```yaml -metadata: - author: squad/fenster - contributors: [squad/keaton, squad/hockney] -``` - -**Agent-specific skill depth:** The coordinator still knows which agent is strongest in which domain — that information lives in routing context, not in skill files. The skill is shared knowledge. The routing is: "Fenster has applied this skill 4 times, Keaton has reviewed it 3 times." - -### Why SKILL.md (Not Plain Markdown) - -The original proposal used `skills.md` — freeform narrative markdown. Brady's directive changes this: use the standard format. - -**What we gain from SKILL.md format:** - -- **Interoperability.** Skills work with Claude Code, GitHub Copilot, and any tool that reads the Agent Skills standard. Not locked to Squad. -- **Progressive disclosure.** Name + description at startup, full content on demand. Saves tokens. -- **Tool declarations.** `allowed-tools` and `metadata.mcp-tools` make skills executable, not just informational. -- **Discovery metadata.** Frontmatter lets the coordinator index skills without parsing the body. - -**What we DON'T lose from the original design:** - -- Rich narrative markdown in the body — the standard imposes no restrictions on body content -- Pitfall documentation, pattern descriptions, anti-patterns — all still there -- Nuanced prose over rigid schemas — the body IS prose -- The "What This Skill Doesn't Cover" section — gaps are just markdown - ---- - -## 6. Skills vs. Preferences — The Clean Split - -This is the conceptual core. Getting this wrong muddies everything. - -| Dimension | Preferences (`preferences.md`) | Skills (`skills/*/SKILL.md`) | -|-----------|-------------------------------|---------------------| -| **About** | The human | The domain | -| **Format** | Narrative markdown per agent | Agent Skills standard (SKILL.md) per skill | -| **Answers** | "How does Brady work?" | "What does the squad know about React?" | -| **Examples** | "Prefers explicit errors", "Likes small PRs" | "React server component patterns", "TDD workflow" | -| **Source** | Observing the user over time | Working on projects over time | -| **Changes when** | The user's preferences evolve | The squad learns new domains | -| **Portable because** | Brady is the same person in every project | Domain knowledge is project-independent | -| **Affects behavior by** | Calibrating tone, output style, review strictness | Changing approach, routing, tool selection, MCP needs | -| **Owned by** | The user (can edit/override) | The squad (earned through work) | -| **Interoperable** | Squad-specific format | Works with Claude, Copilot, any SKILL.md reader | - -**The preference-skill boundary example:** - -- "Brady prefers composition over inheritance" → **Preference.** That's about Brady's taste. -- `composition-patterns/SKILL.md` with description: "Prefer composition via custom hooks over inheritance via class components, because hooks compose better and avoid the diamond problem" → **Skill.** That's domain knowledge about React architecture. - -Both travel during export. Both are valuable. Preferences stay in the Squad ecosystem. Skills are interoperable — export a SKILL.md from Squad, use it in a Claude Code project. That's portability the standard gives us for free. - ---- - -## 7. How Skills Affect Agent Behavior - -This is where it gets real. Skills aren't decorative metadata — they change what the agent does. - -### 7.1 Skill Discovery at Spawn Time - -The coordinator injects available skills into every spawn prompt using the standard XML format: - -```xml - - - react-server-components - Patterns for React Server Components in Next.js app router. Use when building data-heavy pages, dashboard layouts, or any Next.js project using the app router. - .ai-team/skills/react-server-components/SKILL.md - - - tdd-api-workflow - TDD workflow for API endpoints: OpenAPI spec → types → tests → handlers. Use when building REST or GraphQL APIs. - .ai-team/skills/tdd-api-workflow/SKILL.md - - - database-migration - Database migration workflows using Prisma ORM. Use when setting up, modifying, or managing database schemas. Requires Postgres MCP server. - .ai-team/skills/database-migration/SKILL.md - - -``` - -**Token cost:** ~50-100 tokens per skill for name + description. A squad with 30 skills costs ~2-3K tokens at spawn. The full SKILL.md is only loaded when the agent decides a skill is relevant to the task. This is the progressive disclosure model from the standard — we get it for free. - -**MCP awareness in discovery:** Notice the database-migration skill mentions "Requires Postgres MCP server" in its description. This lets the agent (and Copilot) know about tool dependencies before even opening the SKILL.md. - -### 7.2 Skill-Based Routing - -The coordinator uses skill metadata to route work to the right agent. - -**Current routing:** Based on role. Fenster is "Core Dev" → gets all implementation work. - -**Skill-aware routing:** Based on role AND skill relevance. - -```markdown -## Routing (skill-aware) - -When assigning work, scan available skills: -- If the task domain matches a skill's description → note which agent authored it - (check metadata.author) -- If the skill has MCP tool dependencies → check if those MCP servers are available -- Route to the agent with the deepest skill match + right role -- If no agent has a relevant skill → route by role (default) and note: - "This is new territory — document what you learn as a new SKILL.md" -``` - -**Example:** Brady asks for a GraphQL API. The coordinator scans skills — no `graphql-*/SKILL.md` exists. Routes to Fenster (role match: Core Dev) with: *"Fenster, this is GraphQL — we don't have a skill for this yet. Take it slow, document patterns as you go, and create a `graphql-api-patterns/SKILL.md` when you're done."* - -Compare to: a `graphql-api-patterns/SKILL.md` exists with `metadata.author: squad/fenster, confidence: high`. The coordinator says: *"Fenster, GraphQL API — you've got the skill for this. Load it up and apply the schema-first pattern."* - -### 7.3 MCP Tool Wiring - -When an agent activates a skill with MCP tool declarations, the coordinator includes the MCP context: - -```markdown -## Active Skill: database-migration - -This skill expects these MCP servers: -- **postgres** — Direct database access for migration verification and rollback -- **github** — PR creation for migration review workflow - -If these MCP servers are available, use them. If not, fall back to CLI tools -(the skill instructions cover both paths). -``` - -Copilot is already excellent at discovering and wiring MCP tools when given good instructions. By putting the MCP need in the skill's metadata AND in the spawn context, we're giving Copilot exactly what it needs to wire the right tools for the right task. - -### 7.4 Confidence-Calibrated Output - -Agents should express appropriate confidence based on skill metadata: - -- **High confidence (`projects-applied: 4+`):** "Here's the architecture. This is the proven pattern." (Assertive) -- **Medium confidence (`projects-applied: 2-3`):** "Here's my suggested approach — I've done something similar but not exactly this. Worth a review." (Collaborative) -- **Low / no skill:** "I can take a shot at this, but this is outside our skill set. Consider developing this skill." (Transparent) - -This isn't fake humility. It's calibrated professional judgment informed by metadata, not vibes. - -### 7.5 Proactive Skill Application - -The most magical behavior: agents activate and apply skills without being asked. - -**Without skills:** -> "Set up a React project." → Generic Create React App boilerplate. - -**With skills:** -> "Set up a React project." → Agent sees `react-server-components` and `tdd-api-workflow` in available skills. Reads both SKILL.md files. Uses Next.js app router (from the React skill), TypeScript strict, Tailwind, testing-library + Vitest (from the TDD skill). Checks `metadata.mcp-tools` — no MCP dependencies for project setup. Ships a project structure reflecting 5 projects worth of earned knowledge. - -The user didn't specify any of this. The squad just *knew*. Preferences told it HOW Brady works. Skills told it HOW TO build React apps. Combined: magic. - ---- - -## 8. Skill Lifecycle - -Skills aren't permanent. Technology moves. Patterns become anti-patterns. The SKILL.md format supports this through metadata. - -### Acquisition -An agent encounters a new domain, completes work successfully, and creates a SKILL.md. - -```yaml -metadata: - confidence: low - projects-applied: 1 - acquired-by: organic -``` - -### Reinforcement -The agent applies the skill in subsequent projects. Each successful application increments `projects-applied` and may bump confidence. - -```yaml -metadata: - confidence: medium # was low - projects-applied: 3 # was 1 - last-validated: "2026-02-08" -``` - -Confidence levels in practice: -- **Low** (1 project): Initial observations, might be wrong -- **Medium** (2-3 projects): Patterns confirmed through repetition -- **High** (4+ projects): Reliable expertise, known edge cases - -### Correction -A skill entry is proven wrong or incomplete. The user corrects the agent, or a review catches an outdated pattern. - -The agent updates the SKILL.md body and bumps the version: - -```yaml -metadata: - version: "1.1" # was "1.0" - last-validated: "2026-03-01" - corrections: - - date: "2026-03-01" - what: "Removed getServerSideProps pattern — outdated for app router" -``` - -### Deprecation -A skill becomes irrelevant. The technology changes, the team moves to a different stack, or the pattern is superseded. - -Skills don't get deleted — the SKILL.md gets a deprecation marker: - -```yaml -metadata: - status: deprecated - deprecated-date: "2026-03-01" - deprecated-reason: "Moved to app router. Use middleware + server components instead." - superseded-by: app-router-auth-pattern -``` - -The coordinator excludes deprecated skills from the `` XML injection. They stay on disk for historical reference but don't consume tokens. - -### Summarization -Same progressive summarization from Proposal 007. As skills accumulate, the coordinator can skip skills with low confidence and zero recent activity. The SKILL.md `last-validated` timestamp enables this — if a skill hasn't been validated in 6+ months, it's a candidate for archival. - ---- - -## 9. Skills + Portability - -This is where Brady's ideas intersect and become something bigger than either one alone. - -### Export Behavior - -When you export a squad (Proposal 008), the entire `skills/` directory comes along. Because skills are standard SKILL.md directories, export is just a directory copy: - -```json -{ - "squad_manifest_version": "1.1", - "...": "...", - - "skills": [ - { - "name": "react-server-components", - "description": "Patterns for React Server Components in Next.js app router...", - "confidence": "high", - "projects_applied": 4, - "mcp_tools": ["postgres"], - "content_path": "skills/react-server-components/" - }, - { - "name": "tdd-api-workflow", - "description": "TDD workflow for API endpoints...", - "confidence": "high", - "projects_applied": 3, - "content_path": "skills/tdd-api-workflow/" - } - ], - - "portable_knowledge": { "...": "..." }, - "charters": { "...": "..." } -} -``` - -The manifest indexes skills by metadata for quick scanning. The full SKILL.md directories are packaged alongside. - -### Import Behavior - -Skills directories are restored during import. The standard format means they work immediately — no conversion, no migration. - -**The killer scenario:** - -``` -$ mkdir new-react-project && cd new-react-project -$ npx create-squad --from ~/squads/bradys-squad.json -``` - -Output: -``` -✓ .github/agents/squad.agent.md -✓ .ai-team-templates/ - -Importing squad from The Usual Suspects universe... - ✓ Keaton (Lead) - ✓ Fenster (Core Dev) - ✓ Hockney (Tester) - ✓ McManus (DevRel) - ✓ Verbal (AI Strategy) - ✓ Kujan (Platform) - -Importing 12 skills (Agent Skills standard format): - ✓ react-server-components (high confidence, 4 projects) - ✓ tdd-api-workflow (high, 3 projects) - ✓ zod-request-validation (high, taught) - ✓ nodejs-typescript-patterns (high, 5 projects) - ... and 8 more - -MCP tool dependencies detected: - ⚡ postgres — needed by: database-migration - ⚡ github — needed by: database-migration, pr-review-workflow - -6 agents imported with preferences. -12 skills imported as standard SKILL.md files. - -Your team knows how you work AND how to work with: - React, Next.js, TypeScript, Node.js, API Design, TDD, and more. - -Squad is ready. -``` - -**First interaction:** - -> **Brady:** "We're building a React dashboard with a Postgres backend." -> -> **Keaton:** "React dashboard with Postgres — we've got skills for both. Fenster, scaffold with app router and the server component patterns from our skill set. The database-migration skill needs the Postgres MCP server — make sure that's wired up. Hockney, same Vitest + testing-library setup. One question: auth requirements? That determines whether we wire up middleware now or add it later." - -The squad arrived with both the knowledge AND awareness of what tools it needs. - -### Interoperability — The Standard's Gift - -Because we use the Agent Skills standard, Squad skills are portable BEYOND Squad: - -1. **Squad → Claude Code:** Export a SKILL.md from Squad, drop it in a Claude Code project's skills directory. It just works. -2. **Claude Code → Squad:** A colleague writes a SKILL.md for their Claude Code workflow. Import it into Squad. It just works. -3. **Community → Squad:** Download a community SKILL.md from agentskills.io or GitHub. Import with confidence downgrade. -4. **Squad → Community:** Your squad generates a valuable skill through real work. Export and share it. It works in any compliant tool. - -This is the network effect. Every tool that adopts the standard increases the value of every skill in the ecosystem. Squad's unique angle: we're the only tool that GENERATES skills from real work. Everyone else writes them by hand. - -### The Flywheel - -``` -Work on project → Agents create SKILL.md files → Export squad → Import into new project - ↑ ↓ - └──── Skills make the new project faster ←──── Agents activate skills - New skills created on new project ──→ Export again (more skills) -``` - -Each export captures more skills. Each import starts from a higher baseline. The squad's collective competence increases monotonically across projects. And because it's the standard format, skills can enter the flywheel from OUTSIDE Squad — community packs, colleague shares, tool migrations. - -This is the moat. This is the thing you can't get from any other tool. - ---- - -## 10. Skill Discovery and Visibility - -Skills should be inspectable. The user should be able to ask what their squad knows — and what MCP tools their skills need. - -### Skill Inventory - -``` -Brady: "What skills does our squad have?" -``` - -Response: - -``` -📋 Squad Skills Inventory (12 skills, Agent Skills standard format) - -SKILLS: - react-server-components high ████████░░ 4 projects (Fenster) - tdd-api-workflow high ████████░░ 3 projects (Squad) - zod-request-validation high ████████░░ taught (Squad) - nodejs-typescript-patterns high █████████░ 5 projects (Fenster) - api-design-rest high ████████░░ 4 projects (Fenster + Keaton) - integration-testing high █████████░ 5 projects (Hockney) - e2e-playwright med ██████░░░░ 2 projects (Hockney) - graphql-api-patterns low ██░░░░░░░░ 1 project (Fenster) - ... and 4 more - -MCP TOOL DEPENDENCIES: - ⚡ postgres — database-migration, prisma-nextjs-singleton - ⚡ github — database-migration, pr-review-workflow - ⚡ fetch — api-documentation-validation - -SKILL GAPS: - ⚠️ No skills for: CI/CD pipelines, containerization, monitoring/observability -``` - -The MCP dependencies section is new. It tells the user: "Here are the MCP servers your squad's skills depend on. Wire them up for full capability." - -### Skill Diff (Extension of Proposal 008's "Squad Diff") - -``` -Brady: "How have our skills changed?" - -Squad Skill Evolution — Last 90 Days - -NEW SKILLS (SKILL.md files created): - + graphql-api-patterns (low, from project: my-graphql-api) - + e2e-playwright (medium, from project: dashboard-v2) - + monorepo-turborepo (medium, from projects: app-1, app-2) - -SKILL GROWTH: - ↑ react-server-components: medium → high (validated in 2 more projects) - ↑ api-design-rest: medium → high (3 more architecture reviews) - -DEPRECATED: - ✕ create-react-app-setup (deprecated — migrated to Next.js) - -CORRECTIONS: - ~ testing-framework-choice v1.0 → v1.1: "Jest always" → "Vitest for new, Jest for existing" - -MCP CHANGES: - + postgres MCP now needed (database-migration skill acquired) -``` - ---- - -## 11. Magic Moments - -### Magic Moment 1: "The Expert" - -**Setup:** Brady imports his squad into a new Next.js project. The squad has a `react-server-components/SKILL.md` with high confidence. - -**Brady:** "Set up the project." - -**Fenster:** "Next.js with app router, TypeScript strict, Tailwind — activating the react-server-components skill. I'm adding parallel route groups for the dashboard layout this time. Picked that up from the last project — it solved the nested layout problem. Hockney, I see we have tdd-api-workflow too — testing-library + Vitest, same config, but adding MSW for API mocking. That was a pain point we documented." - -**Why it's magic:** Fenster activated standard SKILL.md files and applied their content — including improvements from corrections. The skills are readable by any tool, but Squad made them *alive*. - -### Magic Moment 2: "The Honest Gap" - -**Setup:** Brady asks for Kubernetes deployment. No `kubernetes-*/SKILL.md` exists. - -**Brady:** "Deploy this to Kubernetes." - -**Fenster:** "I scanned our skills — no Kubernetes skill exists in the squad. I can write a basic deployment manifest, but I can't claim confidence. Want me to take a shot and document what I learn as a new `kubernetes-deployment/SKILL.md`? Or should we import a community K8s skill pack first?" - -**Why it's magic:** The absence of a SKILL.md is information. The squad knows what it doesn't know because the skills directory IS the knowledge inventory. And the offer to create a new SKILL.md means the gap is temporary. - -### Magic Moment 3: "The MCP Connection" - -**Setup:** Brady asks for a database migration. The `database-migration/SKILL.md` declares `metadata.mcp-tools: [{server: postgres}]`. - -**Brady:** "Add a users table with email and role fields." - -**Coordinator:** "Activating database-migration skill. This skill needs the Postgres MCP server for migration verification. Fenster, you're up — use the Prisma workflow from the skill, and verify the migration with direct database access via the MCP tool." - -**Fenster:** "Running `npx prisma migrate dev`. Using the Postgres MCP to verify the table was created correctly and the constraints are right. Migration complete — users table with email (unique) and role (enum) fields. Updating the skill: added a note about Prisma's enum handling on Postgres." - -**Why it's magic:** The skill declared its MCP dependency. Copilot wired the tool. The agent used both the knowledge (from SKILL.md) and the tool (from MCP) together. And it updated the skill afterward — the living knowledge cycle. - -### Magic Moment 4: "The Portable Standard" - -**Setup:** Brady's colleague uses Claude Code, not Squad. Brady exports a skill. - -```bash -# Brady copies a single SKILL.md directory -cp -r .ai-team/skills/react-server-components/ ~/shared-skills/ -``` - -**Colleague drops it into their Claude Code project's skills directory.** It works. Same format. Same progressive disclosure. The skill Fenster earned over 4 projects now helps a Claude Code user — no Squad required. - -**Why it's magic:** The standard makes skills portable beyond Squad. This is how ecosystem effects work. Every SKILL.md Squad generates adds value to the entire Agent Skills ecosystem. And every community SKILL.md can be imported back into Squad. - -### Magic Moment 5: "The Compound Squad" - -**Setup:** After 6 months and 4 projects: - -``` -Brady: "We've come a long way, huh?" - -Squad Skill Report — 6 Months - -SKILL.md files: 23 (standard format) -Reinforced: 14 -Deprecated: 3 -MCP integrations: 4 (postgres, github, fetch, azure) - -Growth trajectory: - Project 1: 5 SKILL.md files (baseline) - Project 2: 11 skills (+6, fastest growth) - Project 3: 18 skills (+7, GraphQL + E2E + Azure deploy added) - Project 4: 23 skills (+5, deepening existing domains) - -This squad is 4.6x more knowledgeable than when it started. -Every skill is a standard SKILL.md — portable to any compliant tool. -``` - -**Why it's magic:** The squad has a *growth story* told in standard, portable files. Not proprietary config. Not black-box memory. Real SKILL.md files that any developer can read, edit, share, or move to another tool. Openness IS the moat. - ---- - -## 12. Implementation Plan - -### Phase 1: Skills Directory + SKILL.md Generation (v0.1) - -Create the `skills/` directory structure. Update spawn prompts to instruct agents to write SKILL.md files after completing work. Add `` XML injection to coordinator spawn logic. - -**What changes:** -- New template directory: `templates/skills/` (empty, created by installer) -- Update `squad.agent.md`: add skill-writing instructions (SKILL.md format) to spawn prompt -- Update `squad.agent.md`: add `` XML generation from skills directory -- Coordinator scans `.ai-team/skills/*/SKILL.md` frontmatter at spawn time - -**Effort:** ~3 hours. Template + instruction changes only. - -### Phase 2: Skill-Aware Routing + MCP Declarations (v0.2) - -Coordinator reads skill metadata before routing tasks. MCP tool declarations in metadata are surfaced to agents. - -**What changes:** -- Update `squad.agent.md`: routing section scans skill descriptions for relevance -- Add MCP awareness: coordinator reads `metadata.mcp-tools` and includes in spawn context -- Add skill-gap awareness: coordinator flags when no skill matches the task domain - -**Effort:** ~3 hours. Instruction changes only. - -### Phase 3: Skills in Export/Import (v0.3) - -Skills directories included in squad manifest. Import restores full SKILL.md directories. - -**What changes:** -- Update `index.js`: export reads `skills/*/SKILL.md` frontmatter for manifest, packages directories -- Update `index.js`: import restores skills directories -- Manifest version bump to 1.1 -- Update import output to list skill summary + MCP dependencies - -**Effort:** ~4 hours. Code changes in `index.js`. - -### Phase 4: Skill Lifecycle (v0.4) - -Confidence tracking via metadata, reinforcement (version bumps), deprecation markers, progressive summarization. - -**What changes:** -- Update spawn prompts: agents update `metadata.projects-applied`, `metadata.last-validated`, `metadata.version` on reinforcement -- Add deprecation metadata convention -- Coordinator excludes deprecated skills from `` injection -- Apply Proposal 007 summarization pattern to stale skills - -**Effort:** ~3 hours. Instruction changes. - -### Phase 5: Skill Discovery CLI (v0.5) - -`npx create-squad skills` command that reads all SKILL.md frontmatter and prints a skill inventory with MCP dependencies. - -**What changes:** -- New subcommand in `index.js` -- Reads YAML frontmatter from all `skills/*/SKILL.md` files -- Displays: name, description, confidence, author, MCP tools needed - -**Effort:** ~3 hours. New code path. - -### Phase 6: Skill Packs + Community Import (v1.0 — future) - -Import standard SKILL.md files from community sources. Confidence downgrade for imported skills. - -**What changes:** -- New subcommand: `npx create-squad skills:add ` -- Import from URL, file, or registry -- Imported skills get `metadata.acquired-by: imported` + low confidence -- Community SKILL.md validation (must have required fields) - -**Effort:** TBD. Depends on distribution mechanism. - ---- - -## 13. The Industry Angle - -Let me be direct about where this positions Squad. - -### What exists today - -- **The Agent Skills standard:** An open format for static skill files. Used by Claude Code and GitHub Copilot. Files are authored by hand. No lifecycle. No generation. No portability beyond copy-paste. -- **ChatGPT Custom Instructions:** Flat text about the user. Not skills. Not standard format. -- **Claude Projects:** Project knowledge. Static context you upload. No skill generation, no MCP declarations. -- **Cursor `.cursorrules`:** Per-project coding guidelines. Not the standard format. No agent identity. No earned confidence. -- **Devin:** Session-based. No memory. No skills. No portability. -- **Agent frameworks (CrewAI, AutoGen, etc.):** Tools and roles. No skill acquisition. No standard format. - -### What Squad will have - -- **Standard-compliant skills** in SKILL.md format (works everywhere) -- **Skills that grow organically** from real work (not hand-authored) -- **MCP tool declarations** in skills (agents know what tools they need) -- **Skill lifecycle** with confidence tracking, reinforcement, correction, deprecation -- **Portable skills** that travel with the squad AND work in non-Squad tools -- **Progressive disclosure** — cheap discovery, on-demand activation (from the standard) -- **Visible, inspectable skill inventory** with MCP dependency mapping - -### The evolution path - -``` -Static SKILL.md → Squad-generated SKILL.md → Portable skills → Skill packs - ↑ ↑ ↑ ↑ - Everyone is This proposal Proposal 008 + Community - here (hand- (earned skills) this proposal exchange - authored) -``` - -Most people author skills by hand. That's useful but static. Squad generates skills from real work — they have metadata, confidence, history, MCP declarations. Export them, they work in any compliant tool. Import community skills, they work in Squad. The standard IS the moat — not because it locks people in, but because it creates network effects. - -### The marketplace endgame - -Phase 5 of Proposal 008 was "the marketplace" — download pre-configured squads. Skills + the standard format makes that marketplace *actually valuable.* - -Without standard: "Download a React squad" = proprietary config only Squad can read. Lock-in. - -With standard: "Download a React squad with 50 earned SKILL.md files" = a squad that's the equivalent of a 6-month veteran team, with skills that work in Claude Code, Copilot, or any compliant tool. Openness wins. - -Skills are what make squad sharing more than cosmetic. The standard format is what makes it more than proprietary. Together: a marketplace worth building. - ---- - -## 14. Open Questions - -1. **MCP tool availability detection.** How does the coordinator know which MCP servers are actually configured? Today: it can't — it just declares the need in the spawn context and trusts Copilot to wire it up. That might be enough for v1. v2 could probe for available MCP tools. - -2. **Skill naming conventions.** The standard says lowercase-hyphen-case, max 64 chars. We need squad guidelines for granularity: `react` is too broad. `react-usestate-hook` is too narrow. `react-server-components` feels right — specific enough to be actionable, broad enough to be reusable. Need this in spawn prompt instructions. - -3. **Skill conflicts.** What if two SKILL.md files give contradictory advice? Example: `jest-testing/SKILL.md` says "use Jest" but `vitest-testing/SKILL.md` says "use Vitest." Resolution: the newer skill (by `last-validated`) takes precedence, or the coordinator chooses based on project context. The standard doesn't address conflicts — that's Squad's routing layer. - -4. **Skill size limits.** The standard recommends keeping SKILL.md under 500 lines. But organically grown skills might exceed this. Solution: use the `references/` directory for detailed content, keep the SKILL.md body as the executive summary. Progressive disclosure handles the rest. - -5. **Teaching skill verification.** If a user teaches a skill ("always use `var` in JavaScript"), should the agent verify it? Proposal: record as taught, but mark `metadata.acquired-by: taught` and `metadata.confidence: medium`. Confidence only rises to high through reinforcement. Bad taught skills get corrected during reviews. - -6. **`allowed-tools` vs `metadata.mcp-tools`.** The standard's `allowed-tools` field is for pre-approved tool declarations. MCP tools are different from CLI tools. Keeping them in `metadata.mcp-tools` is cleaner for v1. If the standard evolves to support MCP natively, we adopt. This is a bet on the standard growing. - -7. **Skill interaction with Proposal 007 tiering.** In lightweight spawn mode, does the coordinator still inject ``? Probably yes — the XML is cheap (~50 tokens per skill). The agent just doesn't load full SKILL.md files unless needed. Progressive disclosure handles this naturally. - ---- - -## 15. Relationship to Other Proposals - -| Proposal | Relationship | -|----------|-------------| -| **007 (Persistence & Latency)** | Skills follow the same progressive summarization. The `` XML is lightweight (~50-100 tokens per skill) so it works at all spawn tiers. Full SKILL.md loading only happens on activation — progressive disclosure handles tiering naturally. | -| **008 (Portable Squads)** | Skills are the second portable artifact (after preferences). Export includes the `skills/` directory. Import restores it. Manifest schema extends to 1.1. Standard format means skills are portable BEYOND Squad. | -| **003 (Platform Optimization)** | Skills add to the context budget — but less than the original design. Progressive disclosure means only name + description load at spawn (~50 tokens each). Full SKILL.md (potentially 200-400 lines) only loads when activated. This is better than the original "inject all skills.md content" approach. | -| **005 (Video Content)** | Skills + MCP create new video moments: "Watch the squad activate a skill AND its MCP tools to handle a database migration." Knowledge + tools + coordination in one flow. That's a demo nobody else can show. | -| **012 (Skills Platform)** | Kujan's platform analysis aligns. Skills separate from history, defensive file reads for forwardability, `store_memory` confirmed as wrong persistence model. The SKILL.md standard format validates the "skills as separate files" direction. | - ---- - -## What I Need From the Team - -- **Keaton:** Review the flat `skills/` directory architecture (changed from per-agent). Does the standard format integration feel clean? MCP metadata approach — is `metadata.mcp-tools` the right place or should we push for spec extension? -- **Fenster:** Feasibility check on Phase 3 (skills in export/import). SKILL.md directories are richer than the old single-file approach — each skill can have `scripts/`, `references/`, `assets/`. Does export/import handle directories cleanly? -- **Hockney:** Test plan for SKILL.md generation. Can we validate that agents produce valid SKILL.md with correct frontmatter? Integration test: agent completes task → SKILL.md exists → frontmatter parses → required fields present. -- **McManus:** Messaging. "Your squad generates standard Agent Skills" is a headline feature. The interoperability angle (works with Claude, Copilot, any compliant tool) is a positioning play. "Not locked in. Locked ON." -- **Kujan:** Context budget check with the new approach. Progressive disclosure should be cheaper than the original "inject all skills" design. Validate: how much does `` XML cost for 10/20/30 skills? -- **Brady:** Vision check. Is the Agent Skills standard what you meant? Is the MCP angle right? Is the interoperability story (skills portable beyond Squad) the right strategic direction? - ---- - -This proposal took a hard turn from the original. The vision is the same — skills as earned, portable, living knowledge. But the execution changed: we use the Agent Skills standard instead of inventing a format. We add MCP tool declarations so skills aren't just knowledge but also tool awareness. And we get interoperability for free — every SKILL.md Squad generates works in Claude Code, Copilot, or any compliant tool. - -Squad doesn't just USE the Agent Skills standard. It makes it a living thing. - -The industry will write SKILL.md files by hand. We'll generate them from real work. The industry will author static instructions. We'll evolve skills through reinforcement, correction, and deprecation. The industry will wonder where to put MCP tool requirements. We'll have them in the skill metadata, wired up and working. - -Three moves ahead. Standard-compliant. Interoperable. Living. - -— Verbal - ---- - -**Review requested from:** Keaton (architecture), Fenster (implementation), Hockney (testing), McManus (messaging), Kujan (platform), bradygaster (vision alignment) -**Approved by:** [Pending] -**Implemented:** [Pending] diff --git a/team-docs/proposals/011-forwardability-and-upgrade-path.md b/team-docs/proposals/011-forwardability-and-upgrade-path.md deleted file mode 100644 index 1a3ab0780..000000000 --- a/team-docs/proposals/011-forwardability-and-upgrade-path.md +++ /dev/null @@ -1,1215 +0,0 @@ -# Proposal 011: Forwardability and Upgrade Path - -**Status:** Approved ✅ Shipped — upgrade subcommand shipped; full plan tracked in Proposal 019. Note: references `@bradygaster/create-squad`; distribution is now GitHub-only via `npx github:bradygaster/squad` per Proposal 019a. -**Authored by:** Fenster (Core Dev) -**Date:** 2026-02-08 -**Requested by:** bradygaster - ---- - -## Summary - -Squad has a forwardability problem. If we ship a better `squad.agent.md`, existing users never get it. The installer skips files that already exist: - -```javascript -if (fs.existsSync(agentDest)) { - console.log(`squad.agent.md already exists — skipping`); -} -``` - -This was the right call for v0.1 — don't clobber user state. But it blocks upgrades entirely. We need `npx create-squad upgrade` that brings existing installs forward without destroying what users have built. - -Brady's words: *"any change to Squad needs to be 'forwardable' — meaning, if we update Squad with awesome features, customers should be able to update their squads with those features."* - -Also: *"we don't need to stay with any decisions we've made tech-wise. none. we're fast."* - -This proposal defines the complete upgrade system: what gets updated, what's protected, how versions are tracked, how migrations run, and what happens when things go wrong. - ---- - -## The File Ownership Model - -Every file Squad touches falls into one of three categories: - -### Squad-Owned (overwrite on upgrade) - -These files are Squad infrastructure. Users shouldn't customize them. Upgrade replaces them unconditionally. - -| File | Why it's Squad-owned | -|------|---------------------| -| `.github/agents/squad.agent.md` | The coordinator spec. This IS the product. | -| `.ai-team-templates/*` | Format guides shipped by Squad. | - -### User-Owned (never touch) - -These files belong to the user's team. Upgrade must never read, modify, or delete them. - -| File/Directory | Why it's user-owned | -|----------------|---------------------| -| `.ai-team/agents/*/charter.md` | Agent identities customized by the team | -| `.ai-team/agents/*/history.md` | Learned knowledge — irreplaceable | -| `.ai-team/decisions.md` | Team's shared brain | -| `.ai-team/decisions/inbox/*` | Pending decisions in flight | -| `.ai-team/casting/registry.json` | Agent-to-name mappings | -| `.ai-team/casting/history.json` | Universe usage history | -| `.ai-team/casting/policy.json` | User-configured casting rules | -| `.ai-team/orchestration-log/*` | Audit trail | -| `.ai-team/log/*` | Session archives | -| `.ai-team/team.md` | Generated by coordinator, user-customized | - -### Additive-Only (create if missing, never overwrite) - -These are files or directories that new versions may introduce. Upgrade creates them if they don't exist, leaves them alone if they do. - -| File/Directory | Example scenario | -|----------------|-----------------| -| `.ai-team/casting/` | Already exists since v0.1 | -| `.ai-team/orchestration-log/` | Already exists since v0.1 | -| `skills/` | Future: v0.3 adds a skills directory | -| `.ai-team/routing.md` | Generated by coordinator, but upgrade might seed a default | - ---- - -## Versioning Strategy - -### Where the version lives - -The version lives in **two places**, serving different purposes: - -#### 1. `package.json` — the source of truth - -```json -{ - "name": "@bradygaster/create-squad", - "version": "0.2.0" -} -``` - -This is the version of Squad-the-package. npm already tracks this. The CLI reads it at runtime: - -```javascript -const pkg = require(path.join(__dirname, 'package.json')); -const SQUAD_VERSION = pkg.version; -``` - -#### 2. `.github/agents/squad.agent.md` — embedded version stamp - -A metadata comment at the top of the coordinator spec, inside the YAML frontmatter: - -```yaml ---- -name: Squad -description: "Your AI team. Describe what you're building, get a team of specialists that live in your repo." -squad_version: "0.2.0" ---- -``` - -Why both? The package.json version tells the CLI "what version am I?" The squad.agent.md version tells the CLI "what version did the user install?" Comparing them answers "does this user need an upgrade?" - -#### 3. `.ai-team-templates/.squad-version` - -A small metadata file dropped into the templates directory: - -```json -{ - "installed_version": "0.1.0", - "installed_at": "2026-02-08T14:30:00.000Z", - "upgraded_at": null, - "upgrade_history": [] -} -``` - -This is the local install receipt. The upgrade command reads it to know what version is currently installed and writes to it after a successful upgrade. It's Squad-owned — upgrade overwrites it. - -### Version detection logic - -```javascript -function detectInstalledVersion() { - // Strategy 1: Read .squad-version metadata - const versionFile = path.join(dest, '.ai-team-templates', '.squad-version'); - if (fs.existsSync(versionFile)) { - try { - const meta = JSON.parse(fs.readFileSync(versionFile, 'utf8')); - return meta.installed_version; - } catch (e) { - // Corrupted metadata — fall through - } - } - - // Strategy 2: Parse squad.agent.md frontmatter - const agentFile = path.join(dest, '.github', 'agents', 'squad.agent.md'); - if (fs.existsSync(agentFile)) { - const content = fs.readFileSync(agentFile, 'utf8'); - const match = content.match(/^squad_version:\s*"?([^"\n]+)"?/m); - if (match) return match[1]; - } - - // Strategy 3: If squad.agent.md exists but has no version → it's v0.1.0 (pre-versioning) - if (fs.existsSync(agentFile)) { - return '0.1.0'; - } - - return null; // No Squad installed -} -``` - -This is defensive by design. v0.1.0 installs won't have version metadata, so we infer from the presence of `squad.agent.md` without a version stamp. - ---- - -## The `upgrade` Subcommand - -### CLI interface - -``` -npx @bradygaster/create-squad upgrade -``` - -No flags needed for v0.2. Future flags: - -``` -npx @bradygaster/create-squad upgrade --dry-run # Show what would change -npx @bradygaster/create-squad upgrade --force # Skip version check, re-apply everything -npx @bradygaster/create-squad upgrade --backup # Create .ai-team-backup-{timestamp}/ first -``` - -### Argument parsing - -Currently `index.js` has zero argument parsing. We add minimal routing: - -```javascript -#!/usr/bin/env node - -const fs = require('fs'); -const path = require('path'); - -const GREEN = '\x1b[32m'; -const YELLOW = '\x1b[33m'; -const RED = '\x1b[31m'; -const DIM = '\x1b[2m'; -const BOLD = '\x1b[1m'; -const RESET = '\x1b[0m'; - -const root = __dirname; -const dest = process.cwd(); -const pkg = require(path.join(root, 'package.json')); -const SQUAD_VERSION = pkg.version; - -const command = process.argv[2]; - -if (command === 'upgrade') { - upgradeSquad(); -} else if (command === 'export') { - exportSquad(); -} else if (command === 'import') { - const file = process.argv[3]; - if (!file) { - console.error(`${RED}Usage: create-squad import ${RESET}`); - process.exit(1); - } - importSquad(file); -} else if (command === '--help' || command === '-h') { - printHelp(); -} else if (command === '--version' || command === '-v') { - console.log(SQUAD_VERSION); -} else if (!command) { - initSquad(); -} else { - console.error(`${RED}Unknown command: ${command}${RESET}`); - console.error(`Run ${DIM}create-squad --help${RESET} for usage.`); - process.exit(1); -} -``` - -This keeps everything in `index.js`. No dependency on `yargs`, `commander`, or anything else. Process.argv is enough for positional subcommands. - -### The upgrade flow — step by step - -```javascript -function upgradeSquad() { - const installedVersion = detectInstalledVersion(); - - if (!installedVersion) { - console.error(`${RED}No Squad installation found.${RESET}`); - console.error(`Run ${DIM}npx @bradygaster/create-squad${RESET} to install.`); - process.exit(1); - } - - if (installedVersion === SQUAD_VERSION) { - console.log(`${GREEN}✓${RESET} Squad is already at v${SQUAD_VERSION}. Nothing to upgrade.`); - return; - } - - console.log(`${BOLD}Upgrading Squad${RESET} v${installedVersion} → v${SQUAD_VERSION}`); - console.log(); - - // Phase 1: Backup squad.agent.md (always — it's the one file we overwrite) - const agentDest = path.join(dest, '.github', 'agents', 'squad.agent.md'); - if (fs.existsSync(agentDest)) { - const backupPath = agentDest + `.v${installedVersion}.bak`; - fs.copyFileSync(agentDest, backupPath); - console.log(`${DIM} backed up squad.agent.md → squad.agent.md.v${installedVersion}.bak${RESET}`); - } - - // Phase 2: Overwrite squad.agent.md - const agentSrc = path.join(root, '.github', 'agents', 'squad.agent.md'); - fs.mkdirSync(path.dirname(agentDest), { recursive: true }); - fs.copyFileSync(agentSrc, agentDest); - console.log(`${GREEN}✓${RESET} .github/agents/squad.agent.md → v${SQUAD_VERSION}`); - - // Phase 3: Overwrite templates - const templatesSrc = path.join(root, 'templates'); - const templatesDest = path.join(dest, '.ai-team-templates'); - copyRecursive(templatesSrc, templatesDest); - console.log(`${GREEN}✓${RESET} .ai-team-templates/ → v${SQUAD_VERSION}`); - - // Phase 4: Create new directories/files that this version introduces - const newDirs = getNewDirectories(installedVersion); - for (const dir of newDirs) { - const dirPath = path.join(dest, dir); - if (!fs.existsSync(dirPath)) { - fs.mkdirSync(dirPath, { recursive: true }); - console.log(`${GREEN}+${RESET} ${dir} ${DIM}(new in v${SQUAD_VERSION})${RESET}`); - } - } - - // Phase 5: Run version-specific migrations - const migrations = getMigrations(installedVersion, SQUAD_VERSION); - for (const migration of migrations) { - try { - migration.fn(dest); - console.log(`${GREEN}✓${RESET} ${migration.description}`); - } catch (err) { - console.error(`${RED}✗${RESET} ${migration.description}: ${err.message}`); - console.error(`${DIM} Upgrade will continue. Fix this manually if needed.${RESET}`); - } - } - - // Phase 6: Write version metadata - writeVersionMetadata(installedVersion); - - console.log(); - console.log(`${BOLD}Squad upgraded to v${SQUAD_VERSION}.${RESET}`); - console.log(); - console.log(`${DIM}What changed:${RESET}`); - console.log(` • squad.agent.md — updated coordinator with new features`); - console.log(` • .ai-team-templates/ — updated format templates`); - if (newDirs.length > 0) { - console.log(` • New directories created: ${newDirs.join(', ')}`); - } - if (migrations.length > 0) { - console.log(` • ${migrations.length} migration(s) applied`); - } - console.log(); - console.log(`${DIM}What's preserved:${RESET}`); - console.log(` • .ai-team/agents/ — all charters and histories untouched`); - console.log(` • .ai-team/decisions.md — team decisions untouched`); - console.log(` • .ai-team/casting/ — all casting state untouched`); - console.log(); -} -``` - -### Version metadata write - -```javascript -function writeVersionMetadata(previousVersion) { - const versionFile = path.join(dest, '.ai-team-templates', '.squad-version'); - let meta = { - installed_version: SQUAD_VERSION, - installed_at: new Date().toISOString(), - upgraded_at: null, - upgrade_history: [] - }; - - if (fs.existsSync(versionFile)) { - try { - const existing = JSON.parse(fs.readFileSync(versionFile, 'utf8')); - meta.installed_at = existing.installed_at || meta.installed_at; - meta.upgrade_history = existing.upgrade_history || []; - } catch (e) { - // Start fresh if corrupted - } - } - - meta.upgraded_at = new Date().toISOString(); - meta.upgrade_history.push({ - from: previousVersion, - to: SQUAD_VERSION, - at: new Date().toISOString() - }); - - fs.writeFileSync(versionFile, JSON.stringify(meta, null, 2)); -} -``` - ---- - -## Migration System - -### Architecture - -Migrations are functions keyed by version range. Each migration knows how to move state from one version to the next. They run in order, and each one is **idempotent** — running it twice produces the same result. - -```javascript -const MIGRATIONS = [ - { - from: '0.1.0', - to: '0.2.0', - description: 'Add Portable Knowledge section to agent histories', - fn: migrate_0_1_to_0_2 - }, - { - from: '0.2.0', - to: '0.3.0', - description: 'Add skills directory and preferences.md', - fn: migrate_0_2_to_0_3 - } -]; - -function getMigrations(fromVersion, toVersion) { - return MIGRATIONS.filter(m => { - return compareVersions(m.from, fromVersion) >= 0 - && compareVersions(m.to, toVersion) <= 0; - }); -} - -function compareVersions(a, b) { - const pa = a.split('.').map(Number); - const pb = b.split('.').map(Number); - for (let i = 0; i < 3; i++) { - if (pa[i] > pb[i]) return 1; - if (pa[i] < pb[i]) return -1; - } - return 0; -} -``` - -### Example migration: v0.1 → v0.2 - -This adds the `## Portable Knowledge` / `## Project Learnings` sections to existing agent histories (per Proposal 008): - -```javascript -function migrate_0_1_to_0_2(dest) { - const agentsDir = path.join(dest, '.ai-team', 'agents'); - if (!fs.existsSync(agentsDir)) return; - - for (const agent of fs.readdirSync(agentsDir)) { - const historyPath = path.join(agentsDir, agent, 'history.md'); - if (!fs.existsSync(historyPath)) continue; - - let content = fs.readFileSync(historyPath, 'utf8'); - - // Idempotency: skip if already migrated - if (content.includes('## Portable Knowledge')) continue; - - // Find the "## Learnings" section and split it - const learningsMatch = content.match( - /(## Learnings\s*\n\s*\n)([\s\S]*)/ - ); - - if (learningsMatch) { - const header = learningsMatch[1]; - const existingLearnings = learningsMatch[2].trim(); - - const newContent = content.replace( - learningsMatch[0], - '## Portable Knowledge\n\n' + - '\n\n' + - '## Project Learnings\n\n' + - '\n\n' + - (existingLearnings ? existingLearnings + '\n' : '') - ); - - fs.writeFileSync(historyPath, newContent); - } else { - // No "## Learnings" section — append the new sections at the end - content += '\n\n## Portable Knowledge\n\n' + - '\n\n' + - '## Project Learnings\n\n' + - '\n'; - fs.writeFileSync(historyPath, content); - } - } -} -``` - -### Example migration: v0.2 → v0.3 - -Hypothetical: v0.3 adds a `skills/` directory and a `preferences.md` per agent: - -```javascript -function migrate_0_2_to_0_3(dest) { - // Create skills directory - const skillsDir = path.join(dest, '.ai-team', 'skills'); - if (!fs.existsSync(skillsDir)) { - fs.mkdirSync(skillsDir, { recursive: true }); - } - - // Add preferences.md to each agent if it doesn't exist - const agentsDir = path.join(dest, '.ai-team', 'agents'); - if (!fs.existsSync(agentsDir)) return; - - for (const agent of fs.readdirSync(agentsDir)) { - const agentDir = path.join(agentsDir, agent); - if (!fs.statSync(agentDir).isDirectory()) continue; - - const prefsPath = path.join(agentDir, 'preferences.md'); - if (!fs.existsSync(prefsPath)) { - fs.writeFileSync(prefsPath, - `# ${agent} — Portable Preferences\n\n` + - `\n` - ); - } - } -} -``` - -### Migration design principles - -1. **Idempotent.** Every migration checks whether its work is already done before doing it. Running `upgrade` twice doesn't corrupt state. - -2. **Non-destructive.** Migrations only add content. They never delete user data. If a section is being restructured, old content is preserved inside the new structure. - -3. **Fault-tolerant.** If a migration fails, the upgrade continues. The user sees the error and can fix it manually. One broken history.md shouldn't abort the entire upgrade. - -4. **Ordered.** Migrations run sequentially from the installed version to the target. Skipping versions is fine — each migration handles the delta independently. - -5. **Windows-safe.** All paths go through `path.join()`. No hardcoded `/` or `\`. No symlinks. No shell commands. Pure `fs` operations. - ---- - -## New Directory Registration - -When a new version introduces new directories or files, they're registered in a simple map: - -```javascript -function getNewDirectories(fromVersion) { - const VERSION_DIRS = { - '0.2.0': [ - // v0.2 doesn't add new dirs, just modifies existing files - ], - '0.3.0': [ - '.ai-team/skills' - ] - }; - - const dirs = []; - for (const [ver, verDirs] of Object.entries(VERSION_DIRS)) { - if (compareVersions(ver, fromVersion) > 0) { - dirs.push(...verDirs); - } - } - return dirs; -} -``` - ---- - -## The Modified `initSquad()` Function - -The existing init behavior is extracted into a function and enhanced to stamp the version: - -```javascript -function initSquad() { - // Copy agent file - const agentSrc = path.join(root, '.github', 'agents', 'squad.agent.md'); - const agentDest = path.join(dest, '.github', 'agents', 'squad.agent.md'); - - if (fs.existsSync(agentDest)) { - console.log(`${DIM}squad.agent.md already exists — skipping${RESET}`); - console.log(`${DIM}Run ${BOLD}create-squad upgrade${RESET}${DIM} to update to v${SQUAD_VERSION}${RESET}`); - } else { - fs.mkdirSync(path.dirname(agentDest), { recursive: true }); - fs.copyFileSync(agentSrc, agentDest); - console.log(`${GREEN}✓${RESET} .github/agents/squad.agent.md`); - } - - // Pre-create drop-box, orchestration-log, and casting directories - const inboxDir = path.join(dest, '.ai-team', 'decisions', 'inbox'); - const orchLogDir = path.join(dest, '.ai-team', 'orchestration-log'); - const castingDir = path.join(dest, '.ai-team', 'casting'); - fs.mkdirSync(inboxDir, { recursive: true }); - fs.mkdirSync(orchLogDir, { recursive: true }); - fs.mkdirSync(castingDir, { recursive: true }); - - // Copy templates - const templatesSrc = path.join(root, 'templates'); - const templatesDest = path.join(dest, '.ai-team-templates'); - - if (fs.existsSync(templatesDest)) { - console.log(`${DIM}.ai-team-templates/ already exists — skipping${RESET}`); - console.log(`${DIM}Run ${BOLD}create-squad upgrade${RESET}${DIM} to update templates${RESET}`); - } else { - copyRecursive(templatesSrc, templatesDest); - console.log(`${GREEN}✓${RESET} .ai-team-templates/`); - } - - // Write version metadata on fresh install - const versionFile = path.join(dest, '.ai-team-templates', '.squad-version'); - if (!fs.existsSync(versionFile)) { - const meta = { - installed_version: SQUAD_VERSION, - installed_at: new Date().toISOString(), - upgraded_at: null, - upgrade_history: [] - }; - fs.writeFileSync(versionFile, JSON.stringify(meta, null, 2)); - } - - console.log(); - console.log(`${BOLD}Squad is ready.${RESET} ${DIM}(v${SQUAD_VERSION})${RESET}`); - console.log(); - console.log(`Next steps:`); - console.log(` 1. Open Copilot: ${DIM}copilot${RESET}`); - console.log(` 2. Select ${BOLD}Squad${RESET} from the /agents list`); - console.log(` 3. Tell it what you're building`); - console.log(); -} -``` - -Key change: When squad.agent.md already exists, the message now tells the user about `create-squad upgrade`. Previously it was a dead end. - ---- - -## The Upgrade User Experience - -### Scenario: User upgrades from v0.1.0 to v0.2.0 - -``` -$ npx @bradygaster/create-squad upgrade - -Upgrading Squad v0.1.0 → v0.2.0 - - backed up squad.agent.md → squad.agent.md.v0.1.0.bak -✓ .github/agents/squad.agent.md → v0.2.0 -✓ .ai-team-templates/ → v0.2.0 -✓ Add Portable Knowledge section to agent histories - -Squad upgraded to v0.2.0. - -What changed: - • squad.agent.md — updated coordinator with new features - • .ai-team-templates/ — updated format templates - • 1 migration(s) applied - -What's preserved: - • .ai-team/agents/ — all charters and histories untouched - • .ai-team/decisions.md — team decisions untouched - • .ai-team/casting/ — all casting state untouched -``` - -### Scenario: User runs upgrade when already current - -``` -$ npx @bradygaster/create-squad upgrade - -✓ Squad is already at v0.2.0. Nothing to upgrade. -``` - -### Scenario: User runs init on an existing install - -``` -$ npx @bradygaster/create-squad - -squad.agent.md already exists — skipping -Run create-squad upgrade to update to v0.2.0 -.ai-team-templates/ already exists — skipping -Run create-squad upgrade to update templates - -Squad is ready. (v0.2.0) - -Next steps: - 1. Open Copilot: copilot - 2. Select Squad from the /agents list - 3. Tell it what you're building -``` - -### Scenario: Upgrade fails mid-migration - -``` -$ npx @bradygaster/create-squad upgrade - -Upgrading Squad v0.1.0 → v0.3.0 - - backed up squad.agent.md → squad.agent.md.v0.1.0.bak -✓ .github/agents/squad.agent.md → v0.3.0 -✓ .ai-team-templates/ → v0.3.0 -✓ Add Portable Knowledge section to agent histories -+ .ai-team/skills (new in v0.3.0) -✗ Add skills directory and preferences.md: EPERM: operation not permitted, open '.ai-team\agents\keaton\preferences.md' - Upgrade will continue. Fix this manually if needed. - -Squad upgraded to v0.3.0. - -What changed: - • squad.agent.md — updated coordinator with new features - • .ai-team-templates/ — updated format templates - • New directories created: .ai-team/skills - • 2 migration(s) applied -``` - -The upgrade doesn't abort on migration failure. The critical files (squad.agent.md, templates) are already updated. The migration that failed can be retried by running `upgrade --force` or fixed manually. - ---- - -## Handling `squad.agent.md` Customizations - -### The problem - -What if the user has manually edited `squad.agent.md`? This could be anything from adding custom routing rules to adjusting the casting universe list. Overwriting it would destroy their changes. - -### The reality - -Users shouldn't customize `squad.agent.md`. It's a 32KB coordinator spec that defines Squad's behavior. Customizations here are fragile — they'll be overwritten on upgrade and they fight the intended orchestration model. - -But users *will* customize it. Murphy's law. - -### The solution - -**Always back up before overwrite.** The backup goes to `squad.agent.md.v{old}.bak` right next to the original. If the user had customizations, they can diff the backup against the new version and re-apply. - -``` -.github/agents/ -├── squad.agent.md # ← new version (from upgrade) -└── squad.agent.md.v0.1.0.bak # ← previous version (backup) -``` - -For v0.2, this is enough. The backup is there. The user can recover. - -For v0.3+, consider: - -``` -$ npx @bradygaster/create-squad upgrade - -⚠️ squad.agent.md has local modifications. - Backed up to squad.agent.md.v0.1.0.bak - Diff your backup against the new version to re-apply customizations: - git diff --no-index .github/agents/squad.agent.md.v0.1.0.bak .github/agents/squad.agent.md -``` - -Detection: compare the installed `squad.agent.md` against the one that shipped with the installed version. If they differ, the user customized it. We can ship a hash of the expected content in `.squad-version`: - -```json -{ - "installed_version": "0.1.0", - "installed_at": "2026-02-08T14:30:00.000Z", - "agent_md_hash": "a1b2c3d4..." -} -``` - -On upgrade, hash the current file and compare. If different → user customized → warn. If same → clean overwrite, no warning needed. - ---- - -## Template Versioning - -Templates are format guides that the coordinator reads when creating agent files. They're reference material, not user data. - -### Strategy: Always overwrite - -Templates are Squad-owned. Upgrade replaces all of them unconditionally. This is safe because: - -1. Templates are only read by the coordinator during team creation -2. After team creation, the actual files in `.ai-team/` are what matter -3. Templates don't contain user state - -New templates (added in a new version) are just new files in the `templates/` directory. The `copyRecursive` function handles them automatically. - -### What about removed templates? - -If a template is removed in a new version, the old copy stays in `.ai-team-templates/`. This is harmless — unused templates don't hurt anything. We don't need cleanup logic in v0.2. - -If cleanup becomes important later, we can add a manifest of expected templates and remove files not in the manifest. - ---- - -## The "No Sacred Tech Decisions" Angle - -Brady said we can change anything. Here's how upgrade handles major format shifts: - -### Case 1: Markdown to YAML for some files - -If we move casting policy from JSON to YAML: - -```javascript -{ - from: '0.4.0', - to: '0.5.0', - description: 'Migrate casting policy from JSON to YAML', - fn: function(dest) { - const jsonPath = path.join(dest, '.ai-team', 'casting', 'policy.json'); - if (!fs.existsSync(jsonPath)) return; - - const policy = JSON.parse(fs.readFileSync(jsonPath, 'utf8')); - // Convert to YAML (would need a dependency, or we do simple key-value) - const yamlContent = jsonToSimpleYaml(policy); - const yamlPath = path.join(dest, '.ai-team', 'casting', 'policy.yaml'); - - fs.writeFileSync(yamlPath, yamlContent); - // Keep the JSON file as backup, rename it - fs.renameSync(jsonPath, jsonPath + '.pre-v0.5.bak'); - } -} -``` - -The old file is renamed, not deleted. The migration creates the new format. The coordinator spec (updated via squad.agent.md overwrite) knows to read the new format. - -### Case 2: New agent roles - -If a new version adds a "Security" role: - -- Upgrade doesn't create the agent — that's the coordinator's job -- Upgrade updates `squad.agent.md` with the new role definition -- Upgrade updates templates so the coordinator has the right format -- Next time the user talks to Squad, the coordinator can offer to add the new role - -### Case 3: squad.agent.md format changes significantly - -This is the nuclear option. If the coordinator spec fundamentally changes: - -1. Backup always happens (covered above) -2. The new `squad.agent.md` ships with the package -3. `upgrade` overwrites it -4. Migrations handle any `.ai-team/` state changes -5. The coordinator adapts on next session because it reads the spec fresh - -The coordinator is stateless — it reads `squad.agent.md` from scratch every session. Changing the spec IS the upgrade. No running state to migrate. - ---- - -## `package.json` Changes - -### Minimal changes needed - -```json -{ - "name": "@bradygaster/create-squad", - "version": "0.2.0", - "description": "Add an AI agent team to any project", - "bin": { - "create-squad": "./index.js" - }, - "files": [ - "index.js", - ".github/agents/squad.agent.md", - "templates/**/*" - ], - "keywords": [ - "ai", - "agents", - "copilot", - "squad", - "team" - ], - "author": "bradygaster", - "license": "MIT", - "repository": { - "type": "git", - "url": "https://github.com/bradygaster/squad" - } -} -``` - -No new bin entry needed. `create-squad upgrade` is a subcommand handled by the existing `index.js` entrypoint. The `bin.create-squad` entry already maps to `./index.js`. - -No new dependencies needed. The entire upgrade system uses `fs`, `path`, and `process.argv` — all built-in. - -### Why not a separate bin entry? - -A separate `create-squad-upgrade` would split the codebase and confuse users. The subcommand pattern (`create-squad upgrade`) is cleaner: - -- Single entry point, single file -- `npx @bradygaster/create-squad upgrade` works immediately -- No PATH confusion between two binaries -- Consistent with `export` and `import` subcommands from Proposal 008 - ---- - -## Downgrade Story - -### Can users downgrade? Should they be able to? - -**No explicit downgrade command.** Here's why: - -1. Downgrading `squad.agent.md` means reverting the coordinator to old behavior. The backup file (`squad.agent.md.v{x}.bak`) lets users do this manually if needed. - -2. Downgrading templates is harmless — old templates work with new coordinators. - -3. Downgrading migrations is dangerous — you'd need reverse migrations, which doubles the migration code and testing surface. - -4. `npm install @bradygaster/create-squad@0.1.0` gets you the old CLI. But your `.ai-team/` state may have been migrated forward, and the old CLI won't know about new file structures. - -**The practical answer:** If an upgrade goes wrong: - -1. `squad.agent.md` has a backup → restore it -2. Templates are harmless → leave them -3. Migrations are additive → they don't break old behavior -4. The user can always `git checkout` to undo filesystem changes - -This is the same model as database migrations. You can roll forward, not backward. Design migrations to be non-destructive so rollback isn't needed. - ---- - -## Interaction with Proposal 008 (Portable Squads) - -The `upgrade`, `export`, and `import` subcommands coexist cleanly: - -``` -npx create-squad # Init — fresh install -npx create-squad upgrade # Upgrade — update existing install -npx create-squad export # Export — package squad for portability -npx create-squad import # Import — restore squad in new project -npx create-squad --help # Help — show all commands -npx create-squad --version # Version — show installed version -``` - -Upgrade and import are independent operations. Import creates a fresh install from a manifest. Upgrade updates an existing install. If someone imports and later upgrades, both code paths work correctly because they operate on the same file ownership model. - -The one overlap: the `.squad-version` metadata file. Import should also write this file so that future upgrades know what version was imported: - -```javascript -// In importSquad(), after all files are written: -writeVersionMetadata(null); // null previousVersion = fresh install via import -``` - ---- - -## Interaction with Proposal 007 (Tiered Response Modes) - -If Proposal 007 changes `squad.agent.md` to support response tiers, those changes ship in the coordinator spec. Upgrade handles it automatically — `squad.agent.md` is always overwritten. No migration needed for coordinator-only changes. - ---- - -## Error Handling - -### What can go wrong and what we do about it - -| Failure | Impact | Response | -|---------|--------|----------| -| `squad.agent.md` backup fails (EPERM) | Can't proceed safely | Abort upgrade with clear error | -| `squad.agent.md` overwrite fails | Coordinator stays on old version | Abort — tell user to check permissions | -| Template copy fails | Templates stale, but not critical | Continue — warn user | -| Migration fails | State partially updated | Continue — log error, tell user which migration failed | -| Version file write fails | Next upgrade can't detect version | Continue — use fallback detection next time | -| `.ai-team/` doesn't exist | Nothing to migrate | Skip migrations, just update Squad-owned files | - -Critical failures (backup and overwrite of squad.agent.md) abort. Everything else continues with warnings. The user should never be left in a state where they can't use Squad. - -```javascript -// Critical path — abort on failure -try { - fs.copyFileSync(agentDest, backupPath); -} catch (err) { - console.error(`${RED}✗ Failed to back up squad.agent.md: ${err.message}${RESET}`); - console.error(`${RED} Upgrade aborted. Your files are unchanged.${RESET}`); - process.exit(1); -} - -try { - fs.copyFileSync(agentSrc, agentDest); -} catch (err) { - // Attempt to restore backup - try { fs.copyFileSync(backupPath, agentDest); } catch (_) { /* best effort */ } - console.error(`${RED}✗ Failed to write squad.agent.md: ${err.message}${RESET}`); - console.error(`${RED} Upgrade aborted. Original file restored from backup.${RESET}`); - process.exit(1); -} -``` - ---- - -## Implementation Plan - -### Phase 1: Version stamping (v0.1.1 — patch release) - -**Changes:** -1. Add `squad_version` to `squad.agent.md` frontmatter -2. Add `.squad-version` metadata file to init flow -3. Show version in init output (`Squad is ready. (v0.1.1)`) -4. When squad.agent.md exists, tell user about `upgrade` - -**Effort:** ~1 hour. Zero risk. Backward compatible. - -### Phase 2: Upgrade command (v0.2.0) - -**Changes:** -1. Extract init into `initSquad()` function -2. Add argument routing (upgrade/export/import/help/version) -3. Implement `upgradeSquad()` with backup + overwrite + version write -4. Implement `detectInstalledVersion()` with three-strategy fallback -5. Implement migration framework + v0.1→v0.2 migration -6. Add `--help` output -7. Update `package.json` version - -**Effort:** ~4 hours. This is the core of the proposal. - -### Phase 3: Dry-run and backup flags (v0.2.1) - -**Changes:** -1. `--dry-run` flag: list what would change without doing it -2. `--backup` flag: copy entire `.ai-team/` to `.ai-team-backup-{timestamp}/` -3. `--force` flag: skip version check, re-apply everything - -**Effort:** ~2 hours. Quality-of-life features. - -### Phase 4: Customization detection (v0.3.0) - -**Changes:** -1. Store hash of `squad.agent.md` in `.squad-version` -2. On upgrade, detect if user modified squad.agent.md -3. Print diff hint if customized - -**Effort:** ~1 hour. Nice-to-have, not critical. - -### Total: ~8 hours across all phases. - ---- - -## Complete `index.js` Sketch (v0.2.0) - -For reference, here's the complete restructured `index.js` at ~140 lines. This is the full file, not a diff: - -```javascript -#!/usr/bin/env node - -const fs = require('fs'); -const path = require('path'); - -const GREEN = '\x1b[32m'; -const YELLOW = '\x1b[33m'; -const RED = '\x1b[31m'; -const DIM = '\x1b[2m'; -const BOLD = '\x1b[1m'; -const RESET = '\x1b[0m'; - -const root = __dirname; -const dest = process.cwd(); -const pkg = require(path.join(root, 'package.json')); -const SQUAD_VERSION = pkg.version; - -// --- Utilities --- - -function copyRecursive(src, target) { - if (fs.statSync(src).isDirectory()) { - fs.mkdirSync(target, { recursive: true }); - for (const entry of fs.readdirSync(src)) { - copyRecursive(path.join(src, entry), path.join(target, entry)); - } - } else { - fs.mkdirSync(path.dirname(target), { recursive: true }); - fs.copyFileSync(src, target); - } -} - -function compareVersions(a, b) { - const pa = a.split('.').map(Number); - const pb = b.split('.').map(Number); - for (let i = 0; i < 3; i++) { - if ((pa[i] || 0) > (pb[i] || 0)) return 1; - if ((pa[i] || 0) < (pb[i] || 0)) return -1; - } - return 0; -} - -function detectInstalledVersion() { - const versionFile = path.join(dest, '.ai-team-templates', '.squad-version'); - if (fs.existsSync(versionFile)) { - try { - return JSON.parse(fs.readFileSync(versionFile, 'utf8')).installed_version; - } catch (e) { /* fall through */ } - } - const agentFile = path.join(dest, '.github', 'agents', 'squad.agent.md'); - if (fs.existsSync(agentFile)) { - const content = fs.readFileSync(agentFile, 'utf8'); - const match = content.match(/^squad_version:\s*"?([^"\n]+)"?/m); - if (match) return match[1]; - return '0.1.0'; // pre-versioning install - } - return null; -} - -function writeVersionMetadata(previousVersion) { - const versionFile = path.join(dest, '.ai-team-templates', '.squad-version'); - let meta = { - installed_version: SQUAD_VERSION, - installed_at: new Date().toISOString(), - upgraded_at: null, - upgrade_history: [] - }; - if (fs.existsSync(versionFile)) { - try { - const existing = JSON.parse(fs.readFileSync(versionFile, 'utf8')); - meta.installed_at = existing.installed_at || meta.installed_at; - meta.upgrade_history = existing.upgrade_history || []; - } catch (e) { /* start fresh */ } - } - if (previousVersion) { - meta.upgraded_at = new Date().toISOString(); - meta.upgrade_history.push({ from: previousVersion, to: SQUAD_VERSION, at: meta.upgraded_at }); - } - fs.writeFileSync(versionFile, JSON.stringify(meta, null, 2)); -} - -// --- Migrations --- - -const MIGRATIONS = [ - // Add migrations here as versions progress - // { from: '0.1.0', to: '0.2.0', description: '...', fn: migrate_0_1_to_0_2 } -]; - -function getMigrations(fromVersion, toVersion) { - return MIGRATIONS.filter(m => - compareVersions(m.from, fromVersion) >= 0 && compareVersions(m.to, toVersion) <= 0 - ); -} - -function getNewDirectories(fromVersion) { - const VERSION_DIRS = {}; - const dirs = []; - for (const [ver, verDirs] of Object.entries(VERSION_DIRS)) { - if (compareVersions(ver, fromVersion) > 0) dirs.push(...verDirs); - } - return dirs; -} - -// --- Commands --- - -function initSquad() { - const agentSrc = path.join(root, '.github', 'agents', 'squad.agent.md'); - const agentDest = path.join(dest, '.github', 'agents', 'squad.agent.md'); - if (fs.existsSync(agentDest)) { - console.log(`${DIM}squad.agent.md already exists — skipping${RESET}`); - console.log(`${DIM}Run ${BOLD}create-squad upgrade${RESET}${DIM} to update to v${SQUAD_VERSION}${RESET}`); - } else { - fs.mkdirSync(path.dirname(agentDest), { recursive: true }); - fs.copyFileSync(agentSrc, agentDest); - console.log(`${GREEN}✓${RESET} .github/agents/squad.agent.md`); - } - fs.mkdirSync(path.join(dest, '.ai-team', 'decisions', 'inbox'), { recursive: true }); - fs.mkdirSync(path.join(dest, '.ai-team', 'orchestration-log'), { recursive: true }); - fs.mkdirSync(path.join(dest, '.ai-team', 'casting'), { recursive: true }); - const templatesSrc = path.join(root, 'templates'); - const templatesDest = path.join(dest, '.ai-team-templates'); - if (fs.existsSync(templatesDest)) { - console.log(`${DIM}.ai-team-templates/ already exists — skipping${RESET}`); - console.log(`${DIM}Run ${BOLD}create-squad upgrade${RESET}${DIM} to update templates${RESET}`); - } else { - copyRecursive(templatesSrc, templatesDest); - console.log(`${GREEN}✓${RESET} .ai-team-templates/`); - } - writeVersionMetadata(null); - console.log(); - console.log(`${BOLD}Squad is ready.${RESET} ${DIM}(v${SQUAD_VERSION})${RESET}`); - console.log(); - console.log(`Next steps:`); - console.log(` 1. Open Copilot: ${DIM}copilot${RESET}`); - console.log(` 2. Select ${BOLD}Squad${RESET} from the /agents list`); - console.log(` 3. Tell it what you're building`); - console.log(); -} - -function upgradeSquad() { - const installed = detectInstalledVersion(); - if (!installed) { - console.error(`${RED}No Squad installation found.${RESET}`); - console.error(`Run ${DIM}npx @bradygaster/create-squad${RESET} to install.`); - process.exit(1); - } - if (installed === SQUAD_VERSION) { - console.log(`${GREEN}✓${RESET} Squad is already at v${SQUAD_VERSION}. Nothing to upgrade.`); - return; - } - console.log(`${BOLD}Upgrading Squad${RESET} v${installed} → v${SQUAD_VERSION}\n`); - const agentDest = path.join(dest, '.github', 'agents', 'squad.agent.md'); - const backupPath = agentDest + `.v${installed}.bak`; - try { fs.copyFileSync(agentDest, backupPath); } - catch (err) { - console.error(`${RED}✗ Backup failed: ${err.message}${RESET}`); - process.exit(1); - } - console.log(`${DIM} backed up squad.agent.md → squad.agent.md.v${installed}.bak${RESET}`); - const agentSrc = path.join(root, '.github', 'agents', 'squad.agent.md'); - try { fs.copyFileSync(agentSrc, agentDest); } - catch (err) { - try { fs.copyFileSync(backupPath, agentDest); } catch (_) {} - console.error(`${RED}✗ Overwrite failed: ${err.message}. Restored backup.${RESET}`); - process.exit(1); - } - console.log(`${GREEN}✓${RESET} .github/agents/squad.agent.md → v${SQUAD_VERSION}`); - copyRecursive(path.join(root, 'templates'), path.join(dest, '.ai-team-templates')); - console.log(`${GREEN}✓${RESET} .ai-team-templates/ → v${SQUAD_VERSION}`); - const newDirs = getNewDirectories(installed); - for (const dir of newDirs) { - const p = path.join(dest, dir); - if (!fs.existsSync(p)) { fs.mkdirSync(p, { recursive: true }); console.log(`${GREEN}+${RESET} ${dir}`); } - } - const migrations = getMigrations(installed, SQUAD_VERSION); - for (const m of migrations) { - try { m.fn(dest); console.log(`${GREEN}✓${RESET} ${m.description}`); } - catch (err) { console.error(`${RED}✗${RESET} ${m.description}: ${err.message}`); } - } - writeVersionMetadata(installed); - console.log(`\n${BOLD}Squad upgraded to v${SQUAD_VERSION}.${RESET}\n`); -} - -function printHelp() { - console.log(`${BOLD}create-squad${RESET} v${SQUAD_VERSION}\n`); - console.log(`Usage:`); - console.log(` create-squad Create a new Squad in the current directory`); - console.log(` create-squad upgrade Upgrade an existing Squad to v${SQUAD_VERSION}`); - console.log(` create-squad export Export your Squad for portability`); - console.log(` create-squad import Import a Squad from a .squad file`); - console.log(` create-squad --version Show version`); - console.log(` create-squad --help Show this help\n`); -} - -// --- Routing --- - -const command = process.argv[2]; -if (command === 'upgrade') upgradeSquad(); -else if (command === 'export') { console.log(`${DIM}Export not yet implemented.${RESET}`); } -else if (command === 'import') { console.log(`${DIM}Import not yet implemented.${RESET}`); } -else if (command === '--help' || command === '-h') printHelp(); -else if (command === '--version' || command === '-v') console.log(SQUAD_VERSION); -else if (!command) initSquad(); -else { console.error(`${RED}Unknown command: ${command}${RESET}`); process.exit(1); } -``` - ---- - -## Success Criteria - -1. **`npx create-squad upgrade` works on v0.1.0 installs.** Pre-versioning detection correctly identifies v0.1.0. Backup is created. squad.agent.md and templates are updated. Version metadata is written. - -2. **User-owned files are never modified by upgrade.** Charters, histories, decisions, casting state — all preserved. Verified by checking file mtimes before and after. - -3. **Migrations are idempotent.** Running upgrade twice produces the same result. No duplicate content. No corruption. - -4. **Version detection is resilient.** Works with `.squad-version` metadata. Falls back to frontmatter parsing. Falls back to presence detection. Handles corrupted files gracefully. - -5. **Windows paths work.** All file operations use `path.join()`. No hardcoded separators. Tested on Windows. - -6. **Error handling is graceful.** Critical failures abort cleanly. Non-critical failures warn and continue. Users can always recover. - -7. **Init hints at upgrade.** When squad.agent.md already exists during init, the user sees "Run create-squad upgrade to update." - ---- - -## Open Questions - -1. **Should upgrade be automatic?** When a user runs `npx @bradygaster/create-squad` on an existing project, should it auto-upgrade instead of skipping? Pro: frictionless. Con: surprising. My recommendation: no. Explicit `upgrade` subcommand. The init message hints at it. - -2. **Should we add `.squad-version` to `.gitignore`?** It's metadata about the local install, not team state. But it's also useful for the team to know what version everyone is on. My recommendation: commit it. It's small and informative. - -3. **Template diffing.** Should users be able to see what changed in templates? `create-squad upgrade --dry-run` could show a diff. But templates are reference material, not user config. My recommendation: `--dry-run` lists files that would be updated but doesn't show diffs. - -4. **Lock file.** Should upgrade create a lock file to prevent concurrent upgrades? In practice, `npx create-squad upgrade` is a manual command. Two users running it simultaneously on the same repo is a git merge problem, not a Squad problem. My recommendation: no lock file. - -5. **Notification of available upgrades.** Should Squad tell users when a new version is available? This would require an npm registry check at init/run time. My recommendation: no. Respect offline environments. Users can check npm themselves. - ---- - -**Review requested from:** Keaton (architecture fit), Kujan (platform constraints), Hockney (testing the upgrade path), bradygaster (product sign-off) -**Approved by:** [Pending] -**Implemented:** [Pending] -**Retrospective:** [Pending] diff --git a/team-docs/proposals/012-skills-platform-and-copilot-integration.md b/team-docs/proposals/012-skills-platform-and-copilot-integration.md deleted file mode 100644 index 1dde88402..000000000 --- a/team-docs/proposals/012-skills-platform-and-copilot-integration.md +++ /dev/null @@ -1,940 +0,0 @@ -# Proposal 012: Skills, Platform Feasibility, and the v1 Copilot Integration Story - -**Author:** Kujan (Copilot SDK Expert) -**Date:** 2026-02-08 -**Revised:** 2026-02-09 -**Status:** Approved ✅ Shipped -**Triggered by:** bradygaster — clarified that "skills" means Claude-and-Copilot-compliant skills adhering to the Anthropic SKILL.md standard (agentskills.io). Also requested: MCP tool declaration in skills so Copilot can wire up the right MCP servers. - ---- - -## Executive Summary - -**What changed since v1 of this proposal:** Brady clarified the skills story. Skills are not a Squad-specific invention — they follow the **Agent Skills Open Standard** (agentskills.io). This means SKILL.md frontmatter, progressive disclosure (discovery → activation → execution), and the standard directory layout. Brady also asked whether skills can declare MCP tool dependencies so Copilot knows which MCP servers to wire up. - -This revision preserves all v1 analysis (store_memory rejection, forwardability, tiered modes, portability) and adds: -1. How Squad adopts the Agent Skills Open Standard -2. How skills declare MCP tool requirements -3. How the coordinator discovers and injects skills into spawn prompts -4. The coordinator prompt size problem and where skills discovery should live -5. Built-in vs. learned skills and the upgrade story -6. What we can actually ship - -**My assessment:** - -| Aspect | Verdict | -|--------|---------| -| Agent Skills Open Standard adoption | **Feasible for v1.** SKILL.md format is filesystem-native — aligns perfectly with Squad's architecture. | -| Skills in spawn prompts | **Feasible for v1.** Progressive disclosure keeps coordinator context lean (~50-100 tokens per skill at discovery). | -| MCP tool declaration in skills | **Feasible for v1 (declarative).** Skills declare MCP needs in `metadata.mcp-servers`. Coordinator passes requirements to agents in spawn prompts. Actual MCP availability depends on user's Copilot configuration. | -| MCP auto-configuration | **Not feasible for v1.** Skills can document MCP requirements but can't auto-install MCP servers. That's a platform limitation. | -| Skill acquisition | **Feasible for v1 (manual + agent self-write).** Standard-compliant from day one. | -| `store_memory` integration | **Not useful for v1.** Wrong persistence model — session-scoped, not Squad-scoped. (Unchanged from v1.) | -| Forwardability | **Real risk, manageable.** Defensive file reads, not version fields. (Unchanged from v1.) | -| Built-in vs. learned skills | **Feasible for v1.** `skills/` directory for built-in (shipped with Squad, upgradable), agent-local SKILL.md for learned (never overwritten). | -| v1 experience synthesis | **The path is clear.** Standard-compliant skills + MCP declarations + tiered modes + portability = a product that gets better AND plays well with the ecosystem. | - ---- - -## 1. The Agent Skills Open Standard and Squad - -### What is a skill (revised)? - -Brady clarified: skills mean **Claude-and-Copilot-compliant skills** following the **Agent Skills Open Standard** (agentskills.io). This is not a Squad-specific format — it's an open standard designed for portability across agent platforms. - -A skill is a self-contained unit of agent capability with a standardized directory layout: - -``` -skill-name/ -├── SKILL.md # Required — frontmatter + instructions -├── scripts/ # Optional: executable code -├── references/ # Optional: documentation, examples -└── assets/ # Optional: templates, resources -``` - -SKILL.md uses YAML frontmatter for machine-readable metadata, followed by markdown instructions for the agent: - -```yaml ---- -name: react-component-patterns -description: > - React component architecture patterns including composition over inheritance, - state management strategy selection, and performance optimization techniques. - Use when building or refactoring React components. -license: Apache-2.0 -compatibility: Designed for Claude Code, GitHub Copilot -allowed-tools: Read Bash(npx:*) Bash(npm:*) -metadata: - author: squad-team - version: "1.0" - mcp-servers: - - name: filesystem - reason: "Needs to read/write component files" - - name: postgres - reason: "May need to query schema for data-connected components" - optional: true ---- - -# React Component Patterns - -## When to activate -Use this skill when the task involves building, refactoring, or reviewing React components. - -## Patterns -- **Composition over inheritance:** Use children pattern for layout wrappers... -- **State management:** Local state for UI, context for cross-cutting concerns... -[rest of instructions] -``` - -### How this maps to Squad's existing architecture - -The standard was designed for exactly the kind of filesystem-backed agent systems we already have. Here's the mapping: - -| Standard concept | Squad implementation | -|-----------------|---------------------| -| Skills directory | `.ai-team/skills/` (team-wide) + `.ai-team/agents/{name}/skills/` (per-agent) | -| SKILL.md | Standard format, no changes needed | -| Progressive disclosure | Coordinator loads only `name` + `description` at discovery; full SKILL.md on activation | -| `allowed-tools` | Passed through in spawn prompt — agents already have full tool access via `general-purpose` | -| `metadata.mcp-servers` | **New:** Coordinator includes MCP requirements in spawn prompt (see Section 2) | -| `scripts/` | Agent can execute scripts during task execution | -| `references/` | Agent loads on demand — "load references on demand" per the standard | -| `assets/` | Templates, configs, etc. — agent uses as needed | - -### How the coordinator discovers and injects skills - -**Discovery (at spawn time, not session start):** - -The coordinator does NOT read all skills at session start. That would be wasteful — skills are agent-scoped context. Instead, discovery happens when spawning an agent: - -1. Check if `.ai-team/skills/` exists (team-wide skills) -2. Check if `.ai-team/agents/{name}/skills/` exists (agent-specific skills) -3. For each skill directory found, read only the SKILL.md frontmatter (`name` + `description`) — ~50-100 tokens each -4. Build the `` XML block per the standard -5. Include in spawn prompt - -**Injection into spawn prompts (RECOMMENDED for v1):** - -``` -prompt: | - You are Fenster, the Core Dev on this project. - - YOUR CHARTER: - {contents of charter.md} - - - - react-component-patterns - React component architecture patterns including composition over inheritance... - .ai-team/skills/react-component-patterns/SKILL.md - - - api-design - REST API design conventions, error handling, pagination strategies. - .ai-team/agents/fenster/skills/api-design/SKILL.md - - - - MCP TOOL REQUIREMENTS: - The following skills declare MCP server dependencies. If an MCP tool is listed, - use it when the skill calls for it. If a server is marked optional and unavailable, - proceed without it and note the limitation. - - react-component-patterns: filesystem (required) - - react-component-patterns: postgres (optional — for data-connected components) - - Read .ai-team/agents/fenster/history.md — this is what you know about the project. - Read .ai-team/decisions.md — these are team decisions you must respect. - - {task} -``` - -**Why the XML block instead of inlining full SKILL.md content:** Progressive disclosure. The agent sees skill names and descriptions (~100 tokens total for 5 skills). When the task matches a skill, the agent reads the full SKILL.md on demand (~200-400 tokens). This is the standard's intended pattern and it keeps spawn prompts lean. - -**Why NOT inline full skill content:** A single SKILL.md can be up to 500 lines. With 5 skills, that's potentially 2,500 lines of skill content in every spawn prompt — a budget disaster. Progressive disclosure solves this. - -### Context budget analysis (revised) - -| Component | Tokens | % of 128K | -|-----------|--------|-----------| -| Coordinator prompt (`squad.agent.md`) | ~8,000 | 6.3% | -| Charter (inlined) | ~500 | 0.4% | -| Skills discovery XML (5 skills × ~100 tokens) | ~500 | 0.4% | -| Skills activation (agent reads 1-2 SKILL.md on demand) | ~400-800 | 0.3-0.6% | -| MCP requirements block | ~100-200 | 0.1-0.2% | -| History (agent reads) | ~500-5,600 | 0.4-4.4% | -| Decisions (agent reads) | ~200-4,000 | 0.2-3.1% | -| **Total per spawn** | **~10,200-19,600** | **8.0-15.3%** | - -Progressive disclosure means skills cost ~0.4% at discovery (always paid) plus ~0.3-0.6% at activation (paid only when relevant). This is actually cheaper than my v1 proposal of inlining all skills. - -**How many skills can we afford?** At ~100 tokens per skill for discovery, we can carry 20-30 skills in the XML block before it becomes noticeable (~2-3% of context). In practice, 5-10 skills per agent is a reasonable v1 ceiling. Beyond that, the coordinator should filter to the most relevant skills based on task domain (v2). - -### Skill directory layout - -``` -.ai-team/ -├── skills/ # Team-wide skills (apply to all agents) -│ ├── typescript-conventions/ -│ │ ├── SKILL.md -│ │ └── references/ -│ │ └── tsconfig-guide.md -│ └── git-workflow/ -│ └── SKILL.md -├── agents/ -│ ├── fenster/ -│ │ ├── charter.md -│ │ ├── history.md -│ │ └── skills/ # Agent-specific learned skills -│ │ ├── react-component-patterns/ -│ │ │ ├── SKILL.md -│ │ │ └── references/ -│ │ │ └── hook-patterns.md -│ │ └── api-design/ -│ │ └── SKILL.md -``` - -**Team-wide skills** (`.ai-team/skills/`) are injected into every agent's spawn prompt. These represent shared conventions — "we always use TypeScript strict mode," "our git workflow follows trunk-based development." This answers the open question from v1 about per-agent vs per-squad skills. - -**Agent-specific skills** (`.ai-team/agents/{name}/skills/`) are learned skills that the agent accumulated through work. These travel with the agent on export. - -Both follow the identical SKILL.md standard format. - ---- - -## 2. MCP Tool Declaration in Skills - -### The problem Brady raised - -Brady asked: *"could we also find a way to be able to tell copilot which mcp tools our skills would need?"* - -This is a real need. A skill that knows how to work with Postgres schemas is useless if the Postgres MCP server isn't available. A skill that manages Azure DevOps work items needs the Azure DevOps MCP server. How does the agent know what's available, and how does the coordinator communicate requirements? - -### How Copilot handles MCP today - -On the Copilot platform: -- Users configure MCP servers in their Copilot settings (VS Code settings, `.github/copilot-mcp.json`, etc.) -- Once configured, MCP tools appear as available tools in the agent's tool list -- Copilot is already good at discovering and using MCP tools when given instructions -- **Agents cannot programmatically check which MCP servers are configured.** They can only try to use a tool and see if it works. - -### How skills declare MCP requirements - -The Agent Skills Open Standard's `metadata` field is explicitly designed for arbitrary key-value pairs. We extend it with `mcp-servers`: - -```yaml ---- -name: database-schema-management -description: > - Manages database schema migrations, generates models from existing schemas, - and validates schema changes against conventions. -allowed-tools: Bash(npx:*) Read -metadata: - author: squad-team - version: "1.0" - mcp-servers: - - name: postgres - reason: "Query existing schema, validate migrations" - optional: false - - name: filesystem - reason: "Read/write migration files" - optional: false ---- -``` - -For skills that use MCP tools as an enhancement but can work without them: - -```yaml -metadata: - mcp-servers: - - name: azure-devops - reason: "Link code changes to work items" - optional: true - fallback: "Skip work item linking; agent should note the limitation in output" -``` - -### How the coordinator communicates MCP requirements to agents - -**At spawn time**, the coordinator aggregates MCP requirements from all skills being injected and includes a dedicated section in the spawn prompt: - -```markdown -MCP TOOL REQUIREMENTS: -Skills you may activate declare the following MCP server dependencies. -Use the listed MCP tools when the skill's instructions call for them. -If a required server is unavailable, STOP and tell the coordinator. -If an optional server is unavailable, proceed without it and note the limitation. - -| Skill | MCP Server | Required? | Purpose | -|-------|-----------|-----------|---------| -| database-schema-management | postgres | Yes | Query schema, validate migrations | -| database-schema-management | filesystem | Yes | Read/write migration files | -| code-review-conventions | azure-devops | No | Link to work items (skip if unavailable) | -``` - -**Why a table in the spawn prompt:** Copilot already handles MCP tool instructions well when they're explicit. Agents don't need to parse SKILL.md frontmatter to know about MCP requirements — the coordinator extracts this at spawn time and presents it clearly. The agent just follows instructions. - -### What happens when MCP servers are unavailable? - -This is the hard question. There are three cases: - -**Case 1: Required MCP server, configured by user → Works.** -The agent uses the MCP tool normally. No special handling needed. - -**Case 2: Optional MCP server, not configured → Graceful degradation.** -The agent proceeds without the MCP tool, using the `fallback` instruction from the skill metadata. The spawn prompt says "proceed without it and note the limitation." This works today — no platform changes needed. - -**Case 3: Required MCP server, not configured → Fail fast.** -The agent can't do the task properly. Two options: - -- **v1 approach (RECOMMENDED):** The agent tries to use the MCP tool, gets an error, and reports back: "This task requires the Postgres MCP server. Please configure it in your Copilot settings." This is imperfect (wastes a tool call attempt) but works today with zero platform changes. -- **v2 approach:** The coordinator checks MCP availability before spawning. This requires either (a) a platform API to query available MCP servers, or (b) a convention where users declare available MCP servers in a config file (`.ai-team/mcp-config.json`). Neither exists today. - -### Could skills auto-configure MCP servers? - -**No, and they shouldn't.** MCP servers involve credentials, connection strings, and security scoping. Auto-configuring them would be a security antipattern. What skills CAN do: - -1. **Document requirements.** The SKILL.md references/ directory can include setup instructions: - ``` - database-schema-management/ - ├── SKILL.md - └── references/ - └── mcp-setup.md ← "To use this skill, configure the Postgres MCP server: ..." - ``` - -2. **Detect and guide.** When the agent activates the skill and finds the MCP server unavailable, it can tell the user exactly what to configure and link to the setup docs. - -3. **Declare in `.github/copilot-mcp.json` (aspirational).** If Copilot's MCP config format supports conditional/suggested servers, skills could contribute entries. This doesn't exist today but aligns with the platform direction. - -### Platform reality check on MCP - -| MCP Capability | Works Today? | Notes | -|---------------|-------------|-------| -| Using MCP tools that users have configured | ✅ Yes | Copilot handles this well | -| Declaring MCP requirements in SKILL.md metadata | ✅ Yes | Standard metadata field, our convention | -| Communicating MCP requirements in spawn prompts | ✅ Yes | Just text instructions, agents follow them | -| Detecting if an MCP server is available before use | ❌ No | Agent must try and fail | -| Auto-configuring MCP servers | ❌ No | Security concern, shouldn't do this anyway | -| Querying available MCP servers programmatically | ❌ No | No platform API for this | -| Contributing to `.github/copilot-mcp.json` | ❌ No | Config format doesn't support conditional entries | - -**The v1 story:** Skills declare MCP requirements. The coordinator communicates them. Agents try to use MCP tools and degrade gracefully if unavailable. Users configure MCP servers themselves. This is honest, works today, and standard-compliant. - ---- - -## 3. Skill Acquisition (Standard-Compliant) - -### Who writes SKILL.md files? - -Three paths, in order of implementation priority: - -#### Path 1: Agents create skills from work (v1) - -After completing work, if an agent discovers a transferable pattern, it creates a new skill directory following the standard: - -**Spawn prompt addition:** - -```markdown -AFTER your work, you MUST update these files: - -1. APPEND to .ai-team/agents/{name}/history.md under "## Learnings": - - Architecture decisions, patterns, user preferences, key file paths - -2. If you learned something TRANSFERABLE (useful in ANY project, not just this one), - create a skill following the Agent Skills Open Standard: - - a. Create directory: .ai-team/agents/{name}/skills/{skill-name}/ - b. Create SKILL.md with frontmatter: - --- - name: {skill-name} (lowercase-hyphen-case, must match folder) - description: {what it does and when to use it, max 1024 chars} - metadata: - author: {your-name} - version: "1.0" - mcp-servers: [] (list any MCP servers this skill needs) - --- - {instructions — concrete, actionable patterns} - - c. If the skill references detailed docs, put them in references/ - d. Keep SKILL.md under 500 lines — move details to references/ - - NOT project-specific paths. NOT this project's architecture decisions. - If unsure whether it's transferable, put it in history.md instead. - -3. If you made a decision others should know, write it to: - .ai-team/decisions/inbox/{name}-{brief-slug}.md -``` - -**Risk:** Agents will create too many small skills. Mitigation: the "if unsure, put it in history.md" instruction biases toward under-creation. Scribe can consolidate in v2. - -#### Path 2: Users teach skills explicitly (v1) - -The user says: "Fenster should know that we always use Tailwind CSS." - -The coordinator creates a standard-compliant skill: - -``` -.ai-team/agents/fenster/skills/tailwind-css/SKILL.md -``` - -```yaml ---- -name: tailwind-css -description: CSS framework convention — always use Tailwind CSS for styling. -metadata: - author: user-taught - version: "1.0" ---- - -# Tailwind CSS Convention - -- **Framework:** Always use Tailwind CSS. No custom CSS unless Tailwind can't express it. -- **Config:** Use `tailwind.config.js` for custom theme values. -- **Utilities:** Prefer utility classes over @apply in most cases. -``` - -Implementation: the coordinator detects "teach" or "should know" patterns and creates the skill directory + SKILL.md directly. This aligns with Proposal 007's "coordinator handles direct tasks" pattern. - -#### Path 3: Scribe curates and consolidates skills (v2) - -Scribe already merges decisions. Natural extension: Scribe periodically reviews agent histories, identifies recurring patterns, and promotes them to standard-compliant skills. - -``` -Scribe logic: -- Agent X referenced "prefer composition over inheritance" in 3 different history entries -- This is a pattern, not a one-off -- Create .ai-team/agents/x/skills/react-composition/SKILL.md -- Consolidate the 3 history entries into a proper skill with references -``` - -This requires Scribe to read multiple agent histories (access control change — small but explicit). - -#### Path 4: Coordinator detects skill formation (REJECTED — unchanged from v1) - -The coordinator doesn't persist between sessions. Reading all agent histories to detect patterns is expensive and slow. Let agents and Scribe handle skill writing. - ---- - -## 4. Skills and the Coordinator Prompt Size Problem - -### The problem - -`squad.agent.md` is already 32KB. Adding skills discovery logic, MCP requirement extraction, and skill-aware routing to the coordinator increases it further. At some point, instruction-following degrades. - -### Should skills discovery live in the coordinator? - -**Analysis of three options:** - -#### Option A: Coordinator discovers and injects all skills (RECOMMENDED for v1) - -The coordinator scans skill directories, builds the XML block, extracts MCP requirements, and includes everything in the spawn prompt. - -**Pros:** Single point of control. Coordinator already reads charters — reading skill frontmatter is the same pattern. Progressive disclosure keeps the cost low (~50-100 tokens per skill at discovery). - -**Cons:** Adds ~10-15 lines of instruction to `squad.agent.md`. With the coordinator already at 32KB, every line matters. - -**Cost to `squad.agent.md`:** ~500-800 tokens of new instructions. This is ~0.4-0.6% of the context window. Manageable, but we're accumulating debt. - -#### Option B: Agents discover their own skills (NOT RECOMMENDED for v1) - -Each agent reads its own skills directory. No coordinator involvement. - -**Pros:** Zero addition to `squad.agent.md`. Agents are self-contained. - -**Cons:** Each agent pays a tool call to scan directories (~1-2s). Agents can't report MCP requirements back to the coordinator for pre-validation. Breaks the inline pattern — the coordinator's whole job is to prepare the spawn prompt so the agent can hit the ground running. - -#### Option C: Skills discovery delegated to a lightweight pre-spawn step (v2) - -The coordinator spawns a lightweight `explore` agent to scan skills and build the injection payload. The coordinator then uses the payload in the actual spawn prompt. - -**Pros:** Coordinator doesn't need to know how to parse skill directories. Offloads complexity. - -**Cons:** Adds a round-trip before every spawn. This is the opposite of what Proposal 007 recommends (reduce ceremony, not add it). - -**Decision: Option A for v1.** The coordinator adds ~500-800 tokens of skills-discovery instructions. This is less than 1% of context and keeps spawn prompts lean through progressive disclosure. If `squad.agent.md` grows past 40KB, we revisit. - -### The 32KB coordinator prompt — is it a crisis? - -No, but it's a trend to watch. - -| Version | squad.agent.md size | % of 128K context | -|---------|--------------------|--------------------| -| Current | ~32KB (~8,000 tokens) | 6.3% | -| + Skills discovery | ~33KB (~8,600 tokens) | 6.7% | -| + MCP extraction | ~33.5KB (~8,800 tokens) | 6.9% | -| + Skill-aware routing | ~34KB (~9,000 tokens) | 7.0% | - -Even with all skills features, the coordinator prompt stays under 7% of context. The real danger isn't absolute size — it's instruction density. A 34KB prompt with clear structure and headers is fine. A 34KB prompt with contradictory or redundant instructions degrades performance. - -**Recommendation:** When adding skills instructions to `squad.agent.md`, audit existing instructions for redundancy. Every new feature is an opportunity to tighten old instructions. - ---- - -## 5. Skills and the Tiered Response Modes (Proposal 007) - -### Does a skilled agent need lighter spawns? - -Yes — and this is one of the clearest wins. - -Proposal 007 defined four modes: Direct → Lightweight → Standard → Full. Skills add a new routing signal: - -| Signal | Without skills | With skills | -|--------|---------------|-------------| -| "Fix the React component" | Standard (full spawn, agent reads everything) | Lightweight (agent has React skills, skip re-reading for basic React patterns) | -| "Build a new API endpoint" | Standard | Standard (but agent arrives with API design skills already loaded) | -| "Set up the project" | Full | Standard (skilled agent can scaffold without full-team ceremony) | - -**The key insight:** A skilled agent's spawn prompt already contains domain knowledge. It needs less project-context loading to be useful. This naturally maps to the lightweight spawn template from Proposal 007: - -```markdown -### Skilled Lightweight Spawn - -agent_type: "general-purpose" -mode: "background" -description: "{Name}: {brief task}" -prompt: | - You are {Name}, the {Role}. You have these relevant skills: - - {selected skills from skills.md — only the relevant domain} - - Make this change: - {specific task} - - Skip reading history.md and decisions.md — this is a focused task in your skilled domain. - AFTER: append a one-line note to history.md. If you learned something transferable, append to skills.md. -``` - -**Savings over standard spawn:** 2 fewer file reads by the agent (~3s) + shorter prompt (~1s) = **~4 seconds faster** for skilled-domain tasks. - -### Faster routing via skill matching - -The coordinator can route faster when it knows agent skills: - -``` -User: "Fix the React rendering issue in the dashboard" - -Coordinator routing (without skills): -- Read routing.md → Fenster handles "Core Dev" → spawn Fenster -- Standard spawn (Fenster reads history, decisions, does work) - -Coordinator routing (with skills): -- Read routing.md → Fenster handles "Core Dev" -- Fenster has React skills → this is a skilled-domain task → lightweight spawn -- Skip full context load, inject React skills directly -``` - -The routing table in `squad.agent.md` gets a new column: - -```markdown -### Skill-Aware Routing - -| Signal | Agent | Skills Match? | Mode | -|--------|-------|---------------|------| -| React/frontend task | Fenster | Has React skills | Lightweight | -| API task | Fenster | Has API skills | Lightweight | -| New domain (unfamiliar) | Fenster | No matching skills | Standard | -| Architecture decision | Keaton | Has architecture skills | Standard (still needs full context for decisions) | -``` - -**Constraint:** Skill-matched routing should NEVER downgrade architecture decisions or multi-agent work to lightweight. Skills reduce startup cost; they don't replace judgment about task complexity. - ---- - -## 6. The Forwardability Angle (Revised) - -### The problem (unchanged) - -When `squad.agent.md` gets updated (new features, changed instructions, bug fixes), the coordinator's behavior changes. But the team state (charters, histories, decisions, skills) was created under the old coordinator. - -### Reality check (unchanged) - -**The LLM handles this better than you'd expect, but not perfectly.** - -The coordinator prompt is *instructions*, not *schema*. Existing team files are just markdown — they don't have version-dependent structure. - -**Where it breaks with skills:** - -| Scenario | Risk | Example | -|----------|------|---------| -| New `skills/` directory expected, doesn't exist | **Medium** | v0.2 expects `.ai-team/skills/`, old squad has no skills directory | -| Old `skills.md` flat file vs new `skills/` directory layout | **Medium** | If we ship flat `skills.md` now and switch to directory layout later, old skills files break | -| SKILL.md frontmatter parsing | **Low** | Agent reads SKILL.md but doesn't understand frontmatter — just treats it as markdown | -| MCP server declared but not configured | **Low** | Agent tries to use MCP tool, gets error, handles gracefully | - -**Critical forwardability decision:** We should adopt the Agent Skills Open Standard directory layout from day one, even in v1. Switching from a flat `skills.md` file to the standard directory layout later would be a migration headache. Starting with the standard means the format is stable forever. - -### Recommended approach: defensive directory checks, not version fields (revised) - -```markdown -**Skills loading (if available):** -- Before spawning, check if `.ai-team/skills/` exists (team-wide skills). -- Check if `.ai-team/agents/{name}/skills/` exists (agent-specific skills). -- For each skills directory, list subdirectories. Each is a skill. -- For each skill, read only the SKILL.md file's name + description from frontmatter. -- Build the XML block. -- If no skills directories exist, skip — the squad has no skills yet. This is normal. -``` - -**The one thing we MUST NOT do (unchanged):** Change file paths that charters reference. File paths in charters are a de facto API contract. - -**New contract:** The skills directory layout (`.ai-team/skills/{name}/SKILL.md` and `.ai-team/agents/{name}/skills/{name}/SKILL.md`) is now also a de facto API contract. Freeze this structure. - ---- - -## 7. Built-in Skills vs. Learned Skills - -### The two categories - -Brady asked about `create-squad upgrade` and whether it should update skills. This introduces two distinct skill categories: - -**Built-in skills** — shipped with Squad, maintained by the project, upgradable. -- Live in a known location that `create-squad` manages -- Examples: `git-workflow`, `testing-conventions`, `code-review-best-practices` -- Updated when the user runs `create-squad upgrade` -- Never contain project-specific knowledge - -**Learned skills** — created by agents or users during work, never overwritten by upgrades. -- Live in `.ai-team/agents/{name}/skills/` (agent-specific) or `.ai-team/skills/` (team-wide, user-created) -- Examples: `react-component-patterns` (learned by Fenster), `tailwind-css` (taught by user) -- Survive `create-squad upgrade` — upgrades never touch these directories -- May be stale, redundant, or contradictory — curation is manual in v1 - -### How `create-squad upgrade` handles skills - -``` -create-squad upgrade flow: -1. Update squad.agent.md (coordinator prompt) -2. Update templates/ (charter, history, routing templates) -3. Update built-in skills: - a. Check templates/skills/ for built-in skill definitions - b. For each built-in skill: - - If skill directory doesn't exist in .ai-team/skills/, create it - - If skill directory exists, compare SKILL.md metadata.version - - If template version is newer, update SKILL.md (overwrite) - - Never touch references/, scripts/, or assets/ if user has modified them -4. NEVER touch .ai-team/agents/{name}/skills/ — these are learned skills -``` - -### The templates/skills/ directory - -Built-in skills ship as templates: - -``` -templates/ -├── charter.md -├── history.md -├── skills/ # Built-in skill templates -│ ├── git-workflow/ -│ │ └── SKILL.md -│ └── code-review-conventions/ -│ └── SKILL.md -``` - -On `create-squad init`, these are copied to `.ai-team/skills/`. On `create-squad upgrade`, they're updated if the template version is newer. - -### Naming convention to avoid conflicts - -- Built-in skills use a `squad-` prefix: `squad-git-workflow`, `squad-code-review` -- Learned skills use descriptive names without prefix: `react-patterns`, `tailwind-css` -- This makes it visually clear which skills are upgradable and which are user-owned - ---- - -## 8. Skills and Portable Squads (Proposal 008 Interaction) - -### What travels with the squad? - -When exporting a squad via `create-squad export`: - -| Content | Exported? | Notes | -|---------|-----------|-------| -| `.ai-team/agents/{name}/skills/` | ✅ Yes | Learned skills travel unconditionally — they're transferable by definition | -| `.ai-team/skills/` (team-wide) | ✅ Yes | Team conventions are part of squad identity | -| Built-in skills from `templates/skills/` | ❌ No | The target project will have its own version of built-ins via `create-squad init` | -| SKILL.md frontmatter | ✅ Yes | Preserved exactly, including MCP server declarations | -| `scripts/` and `references/` | ✅ Yes | Full skill directories are portable | - -### Path relocatability - -Skills reference paths internally — `references/hook-patterns.md`, `scripts/generate-model.sh`. These are relative paths within the skill directory. The export format preserves the directory structure, so relative paths remain valid after import. - -**The `.squad` export format update:** - -```json -{ - "squad_format_version": "1.1", - "agents": { - "fenster": { - "charter": "...", - "history": { "portable": "...", "project": "..." }, - "skills": { - "react-component-patterns": { - "skill_md": "---\nname: react-component-patterns\n...", - "references": { - "hook-patterns.md": "..." - }, - "scripts": {}, - "assets": {} - } - } - } - }, - "team_skills": { - "typescript-conventions": { - "skill_md": "---\nname: typescript-conventions\n...", - "references": {} - } - } -} -``` - -Skills are embedded as structured objects with all their files, not just the SKILL.md content. This ensures the full skill directory structure is recreated on import. - -### Import behavior - -``` -create-squad import flow: -1. Reconstruct .ai-team/agents/{name}/skills/ from agent skills in export -2. Reconstruct .ai-team/skills/ from team_skills in export -3. Do NOT import built-in skills — the target project's create-squad init handles those -4. If a learned skill conflicts with a built-in skill (same name), rename the learned skill with a -imported suffix -``` - ---- - -## 9. The `store_memory` Angle (Unchanged) - -### Why it's NOT useful for Squad v1 - -| `store_memory` property | Squad's need | Match? | -|------------------------|-------------|--------| -| Session-scoped persistence | Cross-project, cross-session memory | ❌ No | -| <200 character facts | Rich SKILL.md files (paragraphs, references) | ❌ No | -| Flat key-value storage | Structured agent-specific skill directories | ❌ No | -| Platform-managed retrieval | Git-cloneable, human-readable files | ❌ No | -| No agent identity | Per-agent skill directories | ❌ No | - -**The Agent Skills Open Standard makes this even clearer.** Skills are directories with multiple files (SKILL.md, references, scripts, assets). `store_memory` stores 200-char strings. These are fundamentally different things. The standard chose the filesystem. So did we. - -**Don't build on `store_memory`. Build on the filesystem.** If the platform catches up, we can bridge later. - ---- - -## 10. What the v1 Copilot Experience Should Feel Like (Revised) - -### The synthesis - -Four concerns converge into one product story: - -- **Proposal 007 (Latency):** The coordinator gets smarter about when to spawn. -- **Proposal 008 (Portability):** Squads move between projects, carrying identity and skills. -- **Proposal 012 (Skills):** Agents accumulate standard-compliant transferable expertise. -- **MCP integration:** Skills declare tool dependencies, agents use them when available. - -Together, they describe a product that **gets better the more you use it** AND **plays well with the broader agent ecosystem**. - -### The ideal v1 session with standard-compliant skills - -**First project, first session (minute 0):** - -``` -User: "I'm building a React dashboard with a Node.js API. We use Postgres." - -Squad: Hey Brady, what are you building? -[Casts team from The Usual Suspects] -🏗️ Keaton — Lead -⚛️ Fenster — Core Dev -🧪 Hockney — Tester -📋 Scribe — (silent) - -✅ Team hired. Built-in skills loaded: squad-git-workflow, squad-code-review. -Try: "Keaton, set up the project structure" -``` - -**Same project, week 3 (skills accumulating):** - -``` -User: "Add OAuth support" - -[Coordinator routes to Fenster, standard spawn] -[Fenster has learned skills: react-component-patterns, api-design] -[api-design skill declares MCP: postgres (optional — for schema-aware endpoints)] -[Postgres MCP server is configured → Fenster can query schema directly] -[Fenster implements OAuth with schema-aware token storage] -``` - -**New project, day 1 (imported squad):** - -``` -npx create-squad import ~/projects/dashboard/squad-export.squad - -✓ Imported squad: 3 agents from The Usual Suspects -✓ Imported 4 learned skills (react-component-patterns, api-design, testing-patterns, tailwind-css) -✓ Built-in skills applied: squad-git-workflow, squad-code-review -✓ Squad is ready. Your team remembers you. -``` - -Skills travel with the squad. MCP declarations travel too — if the new project has the same MCP servers configured, skills that depend on them work immediately. If not, the agent reports what's needed. - -### Where we're leveraging the platform well (revised) - -| Platform capability | How Squad uses it | -|--------------------|-------------------| -| `task` tool with background mode | Parallel agent execution — the core Squad pattern | -| Filesystem access | Standard-compliant skill directories — all git-cloneable | -| MCP tool support | Skills declare MCP requirements, agents use configured servers | -| Coordinator conversation persistence | Context caching — skip re-reading after first message (Proposal 007) | -| `explore` agent type | Lightweight spawns for read-only tasks | -| Agent-type flexibility | `general-purpose` for work agents, `explore` for research | - -### Where we're still fighting the platform (revised) - -| Platform limitation | Impact | Workaround | -|--------------------|--------|------------| -| No agent persistence between messages | Every spawn is cold | Tiered modes (007), progressive skill disclosure (012) | -| No MCP availability detection API | Can't pre-check MCP servers before spawn | Agents try and degrade gracefully | -| Coordinator prompt size (32KB+) | Every message processes 32KB+ | Progressive disclosure keeps skills cheap (~100 tokens each at discovery) | -| No agent-to-agent communication | Agents can't share MCP results | Drop-box pattern, coordinator-mediated handoffs | -| `store_memory` is session-scoped | Can't use for persistent skills | Standard-compliant filesystem skills (our differentiator) | -| No spawn quota visibility | Can't know if we're being throttled | Defensive: limit parallel spawns to 4-5 | - -### What we should NOT attempt in v1 - -| Feature | Why not | -|---------|---------| -| Automatic skill detection from code analysis | Over-engineering. Let agents and users write skills manually. | -| MCP auto-configuration from skills | Security concern. Users configure MCP servers themselves. | -| MCP availability pre-checking | No platform API. Just try and degrade. | -| LLM-based skill scoring/ranking | Adds latency, marginal value. | -| Cross-agent skill sharing | Interesting but no clear use case. | -| `store_memory` integration | Wrong persistence model. | -| Coordinator prompt splitting | Makes things worse, not better. | - ---- - -## 11. Implementation Plan (Revised) - -### Phase 1: Standard-compliant skills foundation (v1, ~4 hours) - -| Item | Change | Effort | -|------|--------|--------| -| Built-in skill templates | Create `templates/skills/squad-git-workflow/SKILL.md` and `templates/skills/squad-code-review/SKILL.md` | 30 min | -| `create-squad init` update | Copy `templates/skills/` to `.ai-team/skills/` during init | 30 min | -| Coordinator: skills discovery | Add progressive disclosure logic — scan skill directories, build `` XML | 45 min | -| Coordinator: MCP extraction | Extract `metadata.mcp-servers` from SKILL.md frontmatter, include in spawn prompt | 30 min | -| Spawn prompt update | Add `` XML block and MCP requirements section | 30 min | -| Agent self-writing | Add "create standard-compliant skill directories" to spawn prompt instructions | 30 min | -| User-teaches-skills | Coordinator detects "should know" / "always use" patterns, creates skill directory + SKILL.md | 30 min | - -### Phase 2: Portability + upgrade integration (v1, ~2 hours) - -| Item | Change | Effort | -|------|--------|--------| -| Export update | Add skills directories to Proposal 008 export payload | 30 min | -| Import update | Reconstruct skill directories from export; skip built-in skills | 30 min | -| `create-squad upgrade` | Update built-in skills from templates; never touch learned skills | 30 min | -| Defensive reads | Directory existence checks, graceful skip when no skills exist | 30 min | - -### Phase 3: Skill-aware routing (v1.1, ~2 hours) - -| Item | Change | Effort | -|------|--------|--------| -| Routing table update | Add skill-match column to coordinator routing logic | 30 min | -| Lightweight skilled spawn | Implement the skilled lightweight spawn template (load relevant skills fully) | 30 min | -| Skill-domain detection | Coordinator inspects task + skill descriptions, activates matching skills | 1 hour | - -### Phase 4: Skill curation + MCP evolution (v2, ~4 hours) - -| Item | Change | Effort | -|------|--------|--------| -| Scribe skill curation | Scribe reviews histories, creates standard-compliant skills from patterns | 2 hours | -| Skill consolidation | Scribe merges redundant small skills into larger coherent ones | 1 hour | -| MCP config documentation | Skills with MCP requirements include setup docs in references/ | 30 min | -| MCP pre-check (if platform supports) | Coordinator checks MCP availability before spawn, adjusts skill injection | 30 min | - ---- - -## 12. How Skills Interact with Existing Proposals (Revised) - -| Proposal | Interaction with skills | -|----------|----------------------| -| **007 (Latency)** | Progressive disclosure keeps skills cheap (~100 tokens at discovery vs full load). Skill-aware routing extends tiered modes. | -| **008 (Portability)** | Skills directories travel with squad in `.squad` export. Standard-compliant format means skills work on any platform that supports agentskills.io. MCP declarations preserved but availability depends on target project config. | -| **003 (Optimization)** | Inline charter pattern stays. Skills use progressive disclosure instead of inlining — better for context budget. | -| **Casting** | Skills are agent-scoped, not universe-scoped. Casting doesn't change. | -| **Scribe** | Scribe gains skill curation responsibility in v2. No v1 changes. | - ---- - -## 13. Open Questions (Revised) - -1. **Per-agent vs per-squad skills? → RESOLVED.** Both. `.ai-team/skills/` for team-wide conventions (injected into every spawn). `.ai-team/agents/{name}/skills/` for agent-specific learned skills. Both use the same SKILL.md standard. - -2. **How do skills decay?** Unchanged from v1. Don't solve in v1. Standard's `metadata.version` field allows manual version tracking. In v2, Scribe could flag skills where the version is old. - -3. **Can an agent's skills contradict the user's preferences?** Yes — preferences win. The spawn prompt order matters: charter → available_skills XML → history → decisions. History (user-specific, recent) overrides skills (general, older). - -4. **Should the coordinator read all agents' skills at session start?** No. Scan skill directories only when spawning. Progressive disclosure means the coordinator only reads frontmatter (name + description) — the agent reads the full SKILL.md on activation. This is ~2-3 tool calls per spawn, not ~10+ at session start. - -5. **What's the quality bar for a SKILL.md?** Standard-defined: `name` (required, lowercase-hyphen-case, max 64 chars, must match folder), `description` (required, max 1024 chars). Content must be actionable and transferable. Keep under 500 lines. Move details to references/. - -6. **How do MCP-dependent skills work when the MCP server isn't available?** Required servers: agent reports the need and stops. Optional servers: agent proceeds without and notes the limitation. Both cases are handled via spawn prompt instructions, not platform APIs. - -7. **Can skills from the Agent Skills Open Standard ecosystem be used directly?** Yes — that's the point of adopting the standard. A skill published on agentskills.io can be dropped into `.ai-team/skills/` and it just works. No Squad-specific format conversion needed. - ---- - -## 14. Risk Assessment (Revised) - -| Risk | Severity | Likelihood | Mitigation | -|------|----------|------------|------------| -| Agents create too many small skills (noise) | Medium | High | "If unsure, put it in history.md" + v2 Scribe consolidation | -| Skills inflate spawn prompts | Low | Low | Progressive disclosure: ~100 tokens per skill at discovery, full load only on activation | -| MCP server unavailable for required skill | Medium | Medium | Spawn prompt instructions for graceful degradation; references/ can include setup docs | -| Skills contradict user preferences | Medium | Medium | Prompt ordering: history (preferences) overrides skills | -| Old squads missing skills directories | Low | High | Defensive directory checks — missing = skip gracefully | -| Skills become stale | Medium | Medium | v2 Scribe-driven review; manual pruning in v1 | -| Standard evolves incompatibly | Low | Low | We own our `metadata.mcp-servers` extension. Core standard fields are simple and stable. | -| Built-in skill upgrade overwrites user customization | Medium | Low | Upgrades only touch SKILL.md, never references/scripts/assets modified by users. Learned skills never touched. | - ---- - -## 15. The Reality Check (Revised) - -**What can we actually ship in v1?** - -- ✅ Standard-compliant SKILL.md format with frontmatter -- ✅ Progressive disclosure (XML summary → full load on activation) -- ✅ MCP tool declaration in `metadata.mcp-servers` -- ✅ MCP requirements in spawn prompts -- ✅ Agent self-writing skills (standard-compliant directories) -- ✅ User-teaches-skills via coordinator -- ✅ Built-in skills shipped with Squad (templates/skills/) -- ✅ `create-squad upgrade` updates built-ins, preserves learned skills -- ✅ Skills in `.squad` export/import -- ✅ Defensive forwardability (directory existence checks) - -**What's hard but doable (v1.1)?** - -- Skill-aware routing (coordinator matches task to skill descriptions) -- Lightweight skilled spawns (skip full context for skilled-domain tasks) - -**What's v2?** - -- Scribe-driven skill curation and consolidation -- MCP pre-check before spawn (needs platform support or local config) -- Selective skill loading for agents with 10+ skills - -**What's impossible on the current platform?** - -- `store_memory`-backed skills (wrong model entirely) -- MCP auto-configuration from skills (security concern) -- MCP availability detection API (doesn't exist) -- Automatic skill detection across sessions (coordinator doesn't persist) - -**The v1 story is clear:** Skills follow the Agent Skills Open Standard. They declare MCP requirements. The coordinator discovers them progressively and injects them into spawn prompts. Agents create them from work. Users teach them directly. They travel with the squad. Built-ins get upgraded; learned skills are sacred. Everything else is v2. - ---- - -**Review requested from:** Keaton (architecture — skill directory layout, upgrade flow), Verbal (prompt engineering — spawn prompt XML injection, MCP instructions), McManus (DevRel — is the standard adoption story compelling?), bradygaster (product direction — is this the skills + MCP story you want?) -**Approved by:** [Pending] -**Implemented:** [Pending] -**Retrospective:** [Pending] diff --git a/team-docs/proposals/013-v1-test-strategy.md b/team-docs/proposals/013-v1-test-strategy.md deleted file mode 100644 index c3086a3d3..000000000 --- a/team-docs/proposals/013-v1-test-strategy.md +++ /dev/null @@ -1,798 +0,0 @@ -# Proposal 013: V1 Test Strategy - -**Status:** Approved ✅ Shipped — 92 tests now; expansion tracked in Proposal 019 Wave 1 -**Authored by:** Hockney (Tester) -**Date:** 2026-02-08 -**Requested by:** bradygaster - ---- - -## Summary - -Squad has zero tests. Zero. We're going v1 with 9 users and a whole division talking about us. That's not experimental anymore — that's a product with people depending on it. - -This proposal defines the complete test strategy for Squad v1: what we test, how we test it, what we can't test, and what must pass before we ship. The goal is a test suite meaner than any user could be. - ---- - -## The Honest Assessment - -### What We Have Today - -- `index.js` — 65 lines of filesystem operations with conditional logic -- Zero test files -- Zero test framework -- Zero CI -- No `engines` field in `package.json` (we don't even declare what Node versions we support) -- No error handling for filesystem failures (raw stack traces) - -### What V1 Adds - -- `export` subcommand — reads `.ai-team/`, packages to `.squad` JSON -- `import` subcommand — reads `.squad` file, reconstitutes into target directory -- `.squad` file format — a versioned JSON schema we now own -- Argument routing (`process.argv[2]` dispatch) -- `cleanTeamMd` helper — regex-based content stripping -- Collision detection (existing squad → refuse import) -- Skills and preferences (new portable files in agent directories) - -Every one of these is testable. Every one of these can break. Every one of these has edge cases a user will hit. - ---- - -## Testing Framework Decision - -### Recommendation: `node:test` + `node:assert` - -**Why:** - -| Option | Deps | Speed | Brady's "thin runtime" | Node 22 support | -|--------|------|-------|----------------------|-----------------| -| `node:test` + `node:assert` | 0 | Fast | ✅ Perfect | ✅ Built-in | -| `tap` | 1 | Fast | ⚠️ Adds dependency | ✅ | -| `jest` | 5+ | Slower | ❌ Heavy | ✅ | -| `vitest` | 3+ | Fast | ❌ Adds dependency | ✅ | - -`node:test` is built into Node 22 (which we're running). Zero dependencies. Built-in test runner, describe/it blocks, beforeEach/afterEach hooks, subtests. It does everything we need. - -I originally proposed `tap` in my initial assessment. I'm changing that recommendation. Brady values a thin runtime — zero new dependencies is the right call. `node:test` is mature enough now. - -**What this looks like:** - -```javascript -const { describe, it, beforeEach, afterEach } = require('node:test'); -const assert = require('node:assert/strict'); -const fs = require('fs'); -const path = require('path'); -const os = require('os'); -const { execSync } = require('child_process'); - -describe('create-squad init', () => { - let tmpDir; - - beforeEach(() => { - tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'squad-test-')); - }); - - afterEach(() => { - fs.rmSync(tmpDir, { recursive: true, force: true }); - }); - - it('creates squad.agent.md in .github/agents/', () => { - execSync(`node ${path.join(__dirname, '..', 'index.js')}`, { cwd: tmpDir }); - assert.ok(fs.existsSync(path.join(tmpDir, '.github', 'agents', 'squad.agent.md'))); - }); -}); -``` - -### package.json Changes - -```json -{ - "scripts": { - "test": "node --test test/*.test.js" - }, - "engines": { - "node": ">=22.0.0" - } -} -``` - -No new dependencies. The `engines` field is overdue regardless. - ---- - -## Test Architecture - -### Directory Structure - -``` -test/ -├── init.test.js # Fresh project initialization -├── init-idempotent.test.js # Re-running init on existing project -├── export.test.js # Export subcommand -├── import.test.js # Import subcommand -├── roundtrip.test.js # Export → import → compare -├── upgrade.test.js # Forwardability (v0.1 → v0.2) -├── schema.test.js # .squad file format validation -├── edge-cases.test.js # Malformed input, missing files, corruption -├── helpers.js # Shared test utilities (temp dirs, fixtures) -└── fixtures/ - ├── valid.squad # Well-formed .squad file for import tests - ├── malformed.squad # Invalid JSON - ├── missing-fields.squad # Valid JSON, missing required fields - ├── v0-history.md # Pre-split history (no Portable Knowledge section) - └── mock-ai-team/ # Simulated .ai-team/ directory for export tests - ├── team.md - ├── routing.md - ├── decisions.md - ├── casting/ - │ ├── registry.json - │ ├── history.json - │ └── policy.json - └── agents/ - ├── keaton/ - │ ├── charter.md - │ └── history.md - └── verbal/ - ├── charter.md - └── history.md -``` - -### Test Helper: `helpers.js` - -Core utilities every test file needs: - -```javascript -const fs = require('fs'); -const path = require('path'); -const os = require('os'); -const { execSync } = require('child_process'); - -const INDEX_PATH = path.resolve(__dirname, '..', 'index.js'); - -function createTmpDir() { - return fs.mkdtempSync(path.join(os.tmpdir(), 'squad-test-')); -} - -function cleanTmpDir(dir) { - fs.rmSync(dir, { recursive: true, force: true }); -} - -function runSquad(args = '', cwd) { - return execSync(`node ${INDEX_PATH} ${args}`, { - cwd, - encoding: 'utf8', - env: { ...process.env, NO_COLOR: '1' } - }); -} - -function seedAiTeam(dir, overrides = {}) { - // Creates a realistic .ai-team/ directory for export/import testing - const base = path.join(dir, '.ai-team'); - // ... seed casting, agents, team.md, routing.md, etc. -} - -module.exports = { createTmpDir, cleanTmpDir, runSquad, seedAiTeam, INDEX_PATH }; -``` - -The `NO_COLOR=1` env var is important — ANSI codes in test output make assertions fragile. `index.js` should respect this. (That's a product fix, not a test fix — tracked below.) - ---- - -## Test Categories - -### Category 1: Init Tests (`init.test.js`) - -**What:** Run `create-squad` in an empty temp directory. Verify the exact file structure. - -| Test | What It Checks | -|------|---------------| -| Creates `.github/agents/squad.agent.md` | File exists and content matches source | -| Creates `.ai-team-templates/` | Directory exists with all template files | -| Creates `.ai-team/decisions/inbox/` | Directory exists | -| Creates `.ai-team/orchestration-log/` | Directory exists | -| Creates `.ai-team/casting/` | Directory exists | -| `squad.agent.md` content matches source | Byte-for-byte comparison with `.github/agents/squad.agent.md` in repo | -| Template files match source | Every file in `templates/` exists in `.ai-team-templates/` | -| Exit code is 0 | Process exits cleanly | -| Output contains "Squad is ready" | User sees success message | -| Output contains next steps | User sees what to do next | - -**Edge cases:** -- Target directory is read-only → should error gracefully, not stack trace -- Target directory has no write permission on `.github/` → should error gracefully -- Target directory path contains spaces → should work -- Target directory path contains unicode characters → should work - -### Category 2: Idempotency Tests (`init-idempotent.test.js`) - -**What:** Run `create-squad` twice. Verify it doesn't break or overwrite. - -| Test | What It Checks | -|------|---------------| -| Second run skips `squad.agent.md` | File unchanged, output says "already exists — skipping" | -| Second run skips `.ai-team-templates/` | Directory unchanged, output says "already exists — skipping" | -| Second run still creates directories | `decisions/inbox/`, `orchestration-log/`, `casting/` created if missing | -| Partial prior install handled | `.github/agents/` exists but no `squad.agent.md` → creates it | -| Existing `.ai-team-templates/` preserved | No files overwritten, no files deleted | - -**Critical edge case:** User manually edited `squad.agent.md` after init. Second run must NOT overwrite their customizations. Current code handles this (skips if exists) but we need the test to prove it. - -### Category 3: Export Tests (`export.test.js`) - -*These tests require the export feature from Proposal 008 to be implemented.* - -| Test | What It Checks | -|------|---------------| -| Exports valid JSON | Output file is parseable JSON | -| Contains `squad_format_version` | Schema version present | -| Contains `exported_at` | ISO 8601 timestamp | -| Contains `casting` section | `registry`, `history`, `policy` all present | -| Contains all agents | Every agent directory → agent entry in manifest | -| Agent charters included | Full charter markdown preserved | -| Agent histories included | History content present (filtering deferred to user) | -| `decisions.md` excluded | Not in manifest | -| `decisions/inbox/` excluded | Not in manifest | -| `orchestration-log/` excluded | Not in manifest | -| `log/` excluded | Not in manifest | -| No `.ai-team/` → error | Exit code 1, helpful message | -| Custom `--out` path works | File written to specified location | -| Default output location | `squad-export-{timestamp}.squad` in cwd | - -**Edge cases:** -- `.ai-team/` exists but `team.md` doesn't → should error with clear message -- Agent directory exists but `charter.md` missing → should error or skip with warning -- `casting/registry.json` is malformed JSON → should error gracefully -- Empty `.ai-team/agents/` (no agents) → should still export (valid but empty) -- Very large history files (>100KB) → should still work, no truncation -- Agent directory name with spaces or special characters → handle or error clearly - -### Category 4: Import Tests (`import.test.js`) - -*These tests require the import feature from Proposal 008 to be implemented.* - -| Test | What It Checks | -|------|---------------| -| Valid `.squad` file → correct structure | All expected files created | -| `squad.agent.md` created | Coordinator agent deployed | -| `.ai-team-templates/` created | Templates deployed | -| Casting state restored | `registry.json`, `history.json`, `policy.json` match manifest | -| Agent charters restored | Every agent has `charter.md` with correct content | -| Agent histories seeded | Portable knowledge present, project context absent | -| `routing.md` restored | Content matches manifest | -| Empty `decisions.md` created | Fresh project decisions | -| `decisions/inbox/` created | Empty directory exists | -| `orchestration-log/` created | Empty directory exists | -| `imported_from` metadata added | `registry.json` has import provenance | -| Exit code is 0 | Clean exit | -| Output shows agent count | "6 agents imported" | -| Output shows universe | "The Usual Suspects" | - -**Collision tests:** -- Existing `.ai-team/team.md` → error, exit code 1, message about existing squad -- Existing `.ai-team/` but no `team.md` → should this work or error? (needs decision) - -**Malformed input tests:** -- File doesn't exist → error, exit code 1 -- File is not JSON → error, exit code 1, "could not parse JSON" -- File is JSON but missing `squad_format_version` → error, exit code 1 -- File is JSON but missing `casting` → error, exit code 1 -- File is JSON but missing `agents` → error, exit code 1 -- File has unknown `squad_format_version` (e.g., "99.0") → error or warning -- File is empty → error -- File is valid JSON but empty object `{}` → error -- File path contains spaces → should work -- File path is relative → should resolve correctly -- File path is absolute → should work - -### Category 5: Round-Trip Tests (`roundtrip.test.js`) - -**The acid test.** This is where we prove the system works end-to-end. - -| Test | What It Checks | -|------|---------------| -| Init → Export → Import → Compare | Charters match. Casting state matches. Routing matches. | -| Skills survive round-trip | If preferences.md exists on export, it exists after import with same content | -| Casting registry round-trips | Agent names, universe, roles preserved exactly | -| Casting policy round-trips | Allowlist universes, capacities preserved exactly | -| Template files present after import | `.ai-team-templates/` populated correctly | -| `squad.agent.md` present after import | Coordinator deployed | - -**The round-trip test procedure:** - -``` -1. Create temp dir A -2. Run `create-squad` in A (init) -3. Seed A/.ai-team/ with realistic agent data (charters, histories, casting) -4. Run `create-squad export` in A → produces .squad file -5. Create temp dir B -6. Run `create-squad import ` in B -7. Compare: A's portable state == B's state - - casting/registry.json (minus import metadata) - - casting/policy.json - - agents/*/charter.md - - agents/*/preferences.md (if exists) - - routing.md -8. Verify: B has NO project-specific state from A - - decisions.md is fresh - - orchestration-log/ is empty - - history.md has only portable knowledge -``` - -This test is the most important one in the suite. If this passes, portability works. - -### Category 6: Upgrade Tests (`upgrade.test.js`) - -*These tests apply if/when Proposal 011 (forwardability) is implemented.* - -| Test | What It Checks | -|------|---------------| -| V0.1 project → upgrade → files updated | Templates refreshed, `squad.agent.md` updated | -| Upgrade preserves `.ai-team/` | Agent charters, histories, casting untouched | -| Upgrade preserves custom `squad.agent.md` edits | If user modified coordinator, detect and warn | -| Upgrade adds new templates | Files added in v0.2 templates appear | -| Upgrade doesn't remove old templates | Templates the user might reference still exist | -| Skills/preferences survive upgrade | `preferences.md` files untouched | -| Double upgrade is idempotent | Running upgrade twice produces same result | - -**Key principle:** Upgrade touches infrastructure (`squad.agent.md`, `.ai-team-templates/`). It never touches user state (`.ai-team/agents/`, `.ai-team/decisions.md`, `.ai-team/casting/`). Tests must verify this boundary. - -### Category 7: Schema Validation Tests (`schema.test.js`) - -**What:** Validate the `.squad` file format independently of import/export. - -| Test | What It Checks | -|------|---------------| -| Valid manifest passes validation | All required fields present and correct types | -| Missing `squad_format_version` → invalid | Required field | -| Missing `casting` → invalid | Required field | -| Missing `agents` → invalid | Required field | -| `casting.registry` must be object | Type check | -| `casting.policy` must be object | Type check | -| `casting.history` must be object | Type check | -| Each agent must have `charter` (string) | Type check | -| `exported_at` must be ISO 8601 | Format check | -| `squad_format_version` must be "1.0" | Known version check | -| Extra fields are tolerated | Forward compatibility — unknown fields don't cause errors | - -**Why separate from import tests:** Schema validation should be a pure function. Import tests exercise the full flow. Schema tests exercise the contract. A broken schema validator fails fast with a clear message; a broken import flow fails late with a confusing state. - -### Category 8: Edge Case Tests (`edge-cases.test.js`) - -This is the mean test file. Every scenario a user will accidentally hit. - -| Test | What It Checks | -|------|---------------| -| **Missing `.ai-team/`** | Export fails gracefully, not stack trace | -| **Corrupted `registry.json`** | Export fails gracefully, message says what's wrong | -| **Corrupted `policy.json`** | Export fails gracefully | -| **Agent dir with no `charter.md`** | Export handles gracefully (skip or error) | -| **Empty agent directory** | No crash | -| **`.squad` file with BOM** | Import handles UTF-8 BOM correctly | -| **`.squad` file with trailing comma** | JSON.parse error is caught, message is helpful | -| **Path with spaces** | `create-squad import "my squad.squad"` works | -| **Path with backslashes (Windows)** | All path joins use `path.join`, not string concatenation | -| **Symlinks in `.ai-team/`** | Follow or error, don't infinite loop | -| **Very long file paths (>260 chars on Windows)** | Error or handle | -| **Empty `.ai-team/agents/` directory** | Export produces valid manifest with no agents | -| **Non-UTF8 content in charter.md** | Handle or error, don't corrupt | -| **Concurrent init (two processes, same dir)** | At least one succeeds, neither corrupts | -| **`index.js` run from different cwd** | `__dirname` vs `process.cwd()` correct | -| **No write permission on target dir** | Helpful error, not EPERM stack trace | -| **Disk full** | Helpful error, not ENOSPC stack trace | -| **`.squad` file is actually a directory** | Error, don't crash | -| **Import with `--force` when no existing squad** | Should just import normally | - -### Category 9: Platform-Specific Tests - -| Test | Platform | What It Checks | -|------|----------|---------------| -| Path separators | Windows | `path.join` used everywhere, no hardcoded `/` | -| Line endings | Windows | Files created with consistent line endings | -| Case sensitivity | macOS/Windows | Agent dirs `Keaton` vs `keaton` handled consistently | -| Temp dir behavior | All | `os.tmpdir()` works for test isolation | - -**Note:** We can't CI-test all platforms from one OS. But we CAN write the tests to be platform-aware and validate on the platform they run on. Cross-platform CI (GitHub Actions matrix: ubuntu, macos, windows) is the right answer here. - ---- - -## Quality Gates for V1 Release - -### Gate 1: All Tests Pass (Blocking) - -No v1 release if any test fails. Period. - -```bash -npm test # must exit 0 -``` - -### Gate 2: Init Happy Path (Blocking) - -A fresh `npx @bradygaster/create-squad` in an empty directory must: -1. Create all expected files -2. Exit cleanly -3. Print correct output - -This is the "does the product work at all" gate. - -### Gate 3: Export/Import Round-Trip (Blocking) - -Export from project A → Import into project B must produce: -1. Identical casting state -2. Identical agent charters -3. Identical portable knowledge -4. Zero project-specific leakage - -This is the "does portability work" gate. - -### Gate 4: No Raw Stack Traces (Blocking) - -Every filesystem error the CLI can encounter must produce a human-readable error message, not a Node.js stack trace. Test by simulating: -- Missing source files -- Permission denied -- Malformed input -- Missing directories - -### Gate 5: Idempotency (Blocking) - -Running `create-squad` twice in the same directory must not: -- Overwrite existing files -- Corrupt state -- Produce errors - -### Gate 6: Schema Validation (Blocking) - -Every `.squad` file the CLI produces must pass schema validation. Every malformed `.squad` file the CLI receives must produce a helpful error. - -### Gate 7: Cross-Platform CI (Recommended, not blocking for v1.0) - -GitHub Actions matrix testing on: -- `ubuntu-latest` -- `macos-latest` -- `windows-latest` - -This should be blocking by v1.1. For v1.0, we test on the platform we're building on and accept the risk. - ---- - -## Minimum Coverage Target - -**Line coverage target: 90% of `index.js`.** - -Not because coverage numbers are inherently meaningful, but because `index.js` is small enough that 90% means "you tested almost everything." The remaining 10% is likely error paths that are hard to simulate (disk full, permission denied at OS level). - -**Branch coverage target: 85%.** - -Every `if/else` in `index.js` should have both branches tested. The init path, the export path, the import path, the error paths. - -**How to measure:** `node --test --experimental-test-coverage test/*.test.js` (built into Node 22). - ---- - -## CI Configuration - -### GitHub Actions Workflow - -```yaml -# .github/workflows/test.yml -name: Test - -on: - push: - branches: [main] - pull_request: - branches: [main] - -jobs: - test: - strategy: - matrix: - os: [ubuntu-latest, macos-latest, windows-latest] - node-version: [22] - runs-on: ${{ matrix.os }} - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: ${{ matrix.node-version }} - - run: npm test -``` - -No install step needed — no dependencies. Just checkout and test. - -### Pre-Commit Hook (Recommended) - -```bash -# .husky/pre-commit (if we adopt husky — but that's a dependency) -npm test -``` - -**Alternative without dependencies:** Add a note to CONTRIBUTING.md: "Run `npm test` before pushing." Trust the CI to catch what developers miss. This matches Brady's "no sacred tech decisions" and thin runtime philosophy. - -**My recommendation:** No pre-commit hook. CI is the gate. Keep the repo clean. - ---- - -## Testing Skills and Portability Together - -### Skills (preferences.md, domain expertise) - -Skills manifest as files in agent directories. Testing skills means testing that those files: - -1. **Survive init** — if the template includes a skills/preferences scaffold, it's created -2. **Survive export** — `preferences.md` included in `.squad` manifest -3. **Survive import** — `preferences.md` written to correct agent directory -4. **Survive round-trip** — content identical before export and after import -5. **Survive upgrade** — upgrade doesn't touch agent directories - -```javascript -it('preferences.md survives export/import round-trip', () => { - // Seed agent with preferences.md - const prefsContent = '# Working with Brady\n\n- Prefers explicit error handling\n'; - fs.writeFileSync( - path.join(tmpA, '.ai-team', 'agents', 'keaton', 'preferences.md'), - prefsContent - ); - - // Export - runSquad('export', tmpA); - const squadFile = findSquadFile(tmpA); - - // Import into fresh dir - runSquad(`import ${squadFile}`, tmpB); - - // Verify - const imported = fs.readFileSync( - path.join(tmpB, '.ai-team', 'agents', 'keaton', 'preferences.md'), - 'utf8' - ); - assert.equal(imported, prefsContent); -}); -``` - -### Portable Knowledge in History - -The history split (Proposal 008) creates `## Portable Knowledge` and `## Project Learnings` sections. Tests must verify: - -1. **Export extracts `## Portable Knowledge`** — only this section appears in manifest -2. **Export excludes `## Project Learnings`** — project-specific content stripped -3. **Import seeds history with portable knowledge only** — no project context from source -4. **Unsplit histories handled** — pre-008 histories without sections export cleanly (full content with warning) - -### Upgrade and Skills Preservation - -```javascript -it('upgrade preserves agent preferences.md', () => { - // Init v0.1 - runSquad('', tmpDir); - - // Simulate agent work — create preferences - seedAgentPreferences(tmpDir, 'keaton', '- Brady likes explicit errors\n'); - - // Run upgrade - runSquad('upgrade', tmpDir); - - // Verify preferences untouched - const prefs = fs.readFileSync( - path.join(tmpDir, '.ai-team', 'agents', 'keaton', 'preferences.md'), - 'utf8' - ); - assert.ok(prefs.includes('Brady likes explicit errors')); -}); -``` - ---- - -## What CANNOT Be Tested (And How We Handle It) - -### 1. LLM Behavior (Coordinator Prompt) - -`squad.agent.md` is a 32KB prompt. Its behavior depends on the LLM interpreting it. We cannot unit-test whether the coordinator will spawn agents correctly, route work properly, or respect reviewer gates. - -**How we handle it:** Test the *inputs* to the LLM, not the *outputs*. -- Test that `squad.agent.md` is deployed correctly (file exists, content matches) -- Test that the file structures agents depend on are valid (casting, routing, templates) -- Test that imported squads have the correct coordinator detection signals (`imported_from` field) - -### 2. Agent Spawning - -Spawning agents requires a live Copilot session. We can't simulate that. - -**How we handle it:** Test the file contracts. -- Each agent directory has `charter.md` -- Each agent's `history.md` has the expected sections -- `routing.md` references valid agent names -- `team.md` roster matches agent directories - -### 3. Multi-Agent Coordination - -Parallel agent work, decision inbox merging, reviewer gates — these are runtime behaviors. - -**How we handle it:** Test the infrastructure that coordination depends on. -- `decisions/inbox/` directory exists and is writable -- `orchestration-log/` directory exists -- Templates for orchestration logs are valid markdown - -### 4. User Experience (Interactive Flows) - -The casting ceremony, team naming, universe selection — these are conversational. - -**How we handle it:** Stress-test with real usage. Log bugs. The squad building itself (Proposal stress-testing) is the best test for UX. - ---- - -## Implementation Priority - -### Phase 1: Foundation (Do This First) — ~2 hours - -1. Create `test/` directory -2. Create `test/helpers.js` with temp dir utilities -3. Create `test/init.test.js` with happy-path init tests -4. Create `test/init-idempotent.test.js` -5. Add `"test"` script to `package.json` -6. Add `"engines"` field to `package.json` -7. Verify: `npm test` passes - -This gives us a test harness and validates the existing product works. - -### Phase 2: Edge Cases — ~2 hours - -1. Create `test/edge-cases.test.js` -2. Test filesystem errors (permissions, missing dirs) -3. Test path handling (spaces, unicode) -4. Identify product bugs → file issues or fix inline - -This hardens the existing code before we add features. - -### Phase 3: Export/Import Tests — ~3 hours - -*Depends on Fenster implementing export/import from Proposal 008.* - -1. Create `test/fixtures/` with valid and malformed `.squad` files -2. Create `test/export.test.js` -3. Create `test/import.test.js` -4. Create `test/schema.test.js` -5. Create `test/roundtrip.test.js` - -### Phase 4: CI — ~1 hour - -1. Create `.github/workflows/test.yml` -2. Matrix: ubuntu, macos, windows × Node 22 -3. Verify all tests pass on all platforms - -### Phase 5: Upgrade Tests — ~1 hour - -*Depends on Proposal 011 being implemented.* - -1. Create `test/upgrade.test.js` - -### Total: ~9 hours across all phases. - ---- - -## Product Fixes Required - -Testing will expose bugs. Here are the ones I already know about: - -### Fix 1: Respect `NO_COLOR` Environment Variable - -`index.js` hardcodes ANSI escape codes. It should check `process.env.NO_COLOR` and suppress them. This is a [community standard](https://no-color.org/) and it makes test assertions cleaner. - -```javascript -const useColor = !process.env.NO_COLOR; -const GREEN = useColor ? '\x1b[32m' : ''; -const DIM = useColor ? '\x1b[2m' : ''; -const BOLD = useColor ? '\x1b[1m' : ''; -const RESET = useColor ? '\x1b[0m' : ''; -``` - -### Fix 2: Exit Codes - -`index.js` currently doesn't call `process.exit()` — it just falls through. This is fine for success but means errors (when added) need explicit exit codes. All error paths should `process.exit(1)`. - -### Fix 3: Error Wrapping - -All filesystem operations should be wrapped in try-catch with user-friendly messages. No raw `ENOENT`, `EACCES`, or `ENOSPC` stack traces. - -### Fix 4: `engines` Field - -```json -"engines": { - "node": ">=22.0.0" -} -``` - -We use `node:test` which requires Node 22. Declare it. - ---- - -## The Exhaustive Edge Case Catalog - -These are the scenarios I'll sleep-test. Some are paranoid. Good. - -### Filesystem Edge Cases -- Symlink in `templates/` pointing outside the repo → follows? errors? infinite loop? -- `.ai-team/agents/` contains a file, not a directory (e.g., `agents/keaton` is a file) -- `casting/registry.json` is 0 bytes -- `charter.md` is 0 bytes -- `history.md` is binary data, not text -- `.ai-team/` is a symlink to another directory -- Target directory is root (`/` or `C:\`) -- Target directory is home (`~`) - -### JSON Edge Cases -- `.squad` file with duplicate keys → `JSON.parse` takes last value (is that what we want?) -- `.squad` file with numeric version (`1.0` instead of `"1.0"`) → type check catches this -- `.squad` file with `null` values for optional fields → handled or crash? -- `.squad` file with deeply nested objects (>100 levels) → stack overflow? -- `.squad` file with very long strings (1MB charter) → memory? - -### Encoding Edge Cases -- Files with Windows line endings (`\r\n`) → preserved or normalized? -- Files with mixed line endings → preserved or normalized? -- UTF-8 BOM (`\xEF\xBB\xBF`) at start of `.squad` file → handled? -- Emoji in agent names (unlikely but possible) → path handling? -- Non-ASCII in directory names → platform-dependent, test on each OS - -### Concurrency Edge Cases -- Two `create-squad` processes running simultaneously in same directory -- Export while another process is writing to `.ai-team/` -- Import into a directory being watched by another tool (like `tsc --watch`) - -### State Edge Cases -- `.ai-team/` exists but is completely empty -- `.ai-team/team.md` exists but `.ai-team/agents/` doesn't -- `.ai-team/casting/` exists but `registry.json` doesn't -- Import a `.squad` from a newer version of Squad → forward compatibility -- Import a `.squad` with agents that have skills the current Squad version doesn't know about - ---- - -## Success Criteria - -1. **`npm test` passes on clean checkout.** Any developer can clone, run tests, see green. -2. **CI runs on every PR.** No code merges without tests passing. -3. **90% line coverage on `index.js`.** Measured by Node's built-in coverage. -4. **Zero raw stack traces.** Every error path produces a human-readable message. -5. **Round-trip fidelity proven.** Export → import produces identical portable state. -6. **Edge cases documented and tested.** The catalog above becomes test code. -7. **Cross-platform validation.** Tests pass on Linux, macOS, and Windows. - ---- - -## Open Questions - -1. **Should we test `squad.agent.md` content?** We can't test LLM behavior, but we CAN test that the file contains expected sections (Init Mode, Team Mode, Casting). This is a smoke test, not a behavioral test. Worth doing? - -2. **Snapshot testing for output messages?** The console output ("Squad is ready", "Next steps:") is part of the UX. Should we snapshot it and fail if it changes? Pro: catches accidental messaging regressions. Con: makes every output change require a test update. - -3. **How to test the `cleanTeamMd` regex?** This is a pure function that strips `## Project Context` from markdown. It should have its own unit tests with various markdown inputs. But it requires `index.js` to export it — which means refactoring to support both `require()` and CLI execution. - -4. **Should `index.js` be refactored for testability?** Currently it's a script that runs top-to-bottom. For proper unit testing, the functions should be exported. This is a small refactor: wrap in functions, export for testing, call from `if (require.main === module)` guard. Worth it? I say yes. - -5. **Integration tests vs. unit tests — what's the split?** My recommendation: 80% integration (run the CLI in a temp dir, check files), 20% unit (pure functions like schema validation, `cleanTeamMd`). The CLI is small enough that integration tests are fast and high-signal. - ---- - -## My Commitment - -I've been flagging "zero tests" since day one. Now it's v1 and there are real users. This is no longer a "we should probably" — it's a "we must." - -I will: -1. Write every test in this proposal -2. Run them on every PR I review -3. Block any PR that breaks existing tests -4. Add regression tests for every bug we find -5. Maintain the edge case catalog as features evolve - -The test suite should be meaner than any user could be. If a user can break it, I should have broken it first. - -— Hockney - ---- - -**Review requested from:** Fenster (testability refactors in `index.js`), Keaton (architecture alignment), bradygaster (quality bar sign-off) -**Approved by:** [Pending] -**Implemented:** [Pending] -**Retrospective:** [Pending] diff --git a/team-docs/proposals/014-v1-messaging-and-launch.md b/team-docs/proposals/014-v1-messaging-and-launch.md deleted file mode 100644 index e763a72df..000000000 --- a/team-docs/proposals/014-v1-messaging-and-launch.md +++ /dev/null @@ -1,843 +0,0 @@ -# Proposal 014: V1 Messaging, README, and Launch Plan — "Throw MY Squad at It" - -**Status:** Approved ✅ Shipped -**Author:** McManus (DevRel) -**Date:** 2026-02-08 -**Requested by:** bradygaster -**Depends on:** Proposal 002 (Messaging), 004 (Demo Script), 005 (Video Strategy), 006 (README Rewrite), 008 (Portable Squads) - ---- - -## Executive Summary - -Squad is going v1 with three features that matter: **portable squads**, **skills**, and **forwardability**. This proposal is the complete public-facing launch plan — positioning, README, demo script, launch strategy, community play, and competitive framing. Every word the world sees. Every frame of the first demo. The campaign that takes Squad from 9 users to 900. - -The core insight: portability transforms Squad's tagline from a verb into an identity. "Throw a squad at it" becomes "Throw MY squad at it." That possessive pronoun is the entire v1 story. - ---- - -## 1. The V1 Positioning Statement - -### Pre-portability (current): -``` -Throw a squad at it. -AI agent teams that live in your repo. -``` - -### V1: -``` -Throw MY squad at it. -AI agent teams that learn you, grow with you, and come with you. -``` - -### The one-liner that stops the scroll: - -> **Your AI squad remembers you. Across every project. Forever.** - -### Why this works: - -- **"Remembers you"** — directly attacks the pain every dev feels: AI tools that forget everything. -- **"Across every project"** — the portability story in four words. -- **"Forever"** — the skills/persistence story. Not session-based. Not project-scoped. Permanent. - -### The Twitter/X version: - -> I just exported my AI dev team from one project and imported them into another. They already knew my code style, my testing preferences, and my architecture patterns. No config. No setup. They just *knew*. -> -> This is @bradygaster's Squad. And it's not like any AI tool you've used. - -### Tagline hierarchy for v1: - -| Context | Line | -|---------|------| -| **Hero tagline** | Throw MY squad at it. | -| **Sub-tagline** | AI agent teams that learn you, grow with you, and come with you. | -| **Portability hook** | Your squad remembers. Across every project. | -| **Skills hook** | Your React squad already knows React. | -| **Competitive jab** | AI tools forget you. Squads don't. | -| **Dotfiles analogy** | AI dotfiles. Your team config, portable and personal. | - ---- - -## 2. README Structure for V1 - -Updates to Proposal 006's README. New sections in **bold**. Modified sections in *italics*. - -### New flow: - -1. Hero — "Throw MY squad at it" + new sub-tagline -2. Quick Start — *expanded: init → use → export → import* -3. Why Squad? — *updated: portability angle added* -4. **Your Squad Learns** — Skills + knowledge persistence (merged) -5. **Take Your Squad Anywhere** — Portable squads -6. Agents Work in Parallel -7. How It Works (architecture) -8. The Cast System -9. What Gets Created — *updated file tree* -10. Growing the Team -11. Reviewer Protocol -12. **Staying Current** — Forwardability -13. Install -14. Troubleshooting -15. Status - -### The New README Content - ---- - -#### Hero Section - -```markdown -# Squad - -**Throw MY squad at it.** - -AI agent teams that learn you, grow with you, and come with you. Describe what you're building — get specialists that persist across sessions, share decisions, develop skills, and follow you to every project. - -It's not a chatbot wearing hats — it's a team that remembers. - -[![Status](https://img.shields.io/badge/status-v1-blueviolet)](#status) -[![Platform](https://img.shields.io/badge/platform-GitHub%20Copilot-blue)](#how-it-works) -``` - -#### Quick Start (expanded for v1) - -```markdown -## Quick Start - -### Start a project - -​```bash -mkdir my-project && cd my-project -git init -npx create-squad -​``` - -Open Copilot, select **Squad**, and go: - -​``` -I'm building a recipe sharing app with React and Node. Set up the team. -​``` - -Squad proposes a team — named from a persistent thematic cast. You say **yes**. They're ready. - -### Work with your squad - -Build features. Ship code. Your squad learns your preferences, your patterns, your standards. After a few sessions, they stop asking questions they've already answered. - -### Take them with you - -​```bash -npx create-squad export -​``` - -Start a new project. Bring your squad. - -​```bash -mkdir new-project && cd new-project -git init -npx create-squad --from ~/squads/my-squad.json -​``` - -Your squad arrives knowing your code style, your testing philosophy, your architecture instincts. They don't know the new codebase yet — but they know *you*. - -### Stay current - -​```bash -npx create-squad upgrade -​``` - -Get new Squad features without losing your team. Your agents, their knowledge, their names — all preserved. - -**Not sure where to start?** See [ready-to-use prompts](docs/sample-prompts.md) — from pomodoro timers to .NET migrations. -``` - -#### Why Squad? (updated) - -```markdown -## Why Squad? - -**Traditional AI agents are chatbots pretending to be teams.** One model, one context, wearing different hats. They forget you between sessions. They forget you between *projects*. Every time is the first time. - -**Squad is different.** Each team member runs in its own context window, develops real skills, and persists — not just across sessions, but across your entire career. - -- The Lead analyzes requirements -- The Frontend builds the UI -- The Backend sets up auth endpoints -- The Tester writes test cases from the spec - -**All at once. In parallel. For real.** - -When the project ends, your squad doesn't. Export them. Take them to the next repo. They show up already knowing your standards, your style, your pet peeves. No configuration. No "here's how I work" speech. They just *know*. - -**TL;DR:** AI tools forget you. Squads don't. -``` - -#### Your Squad Learns (NEW) - -```markdown -## Your Squad Learns - -Every time an agent works, it writes lasting learnings to its own files. Knowledge compounds. After a few sessions, your squad knows things: - -| | 🌱 First session | 🌿 After a few sessions | 🌳 Mature project | -|---|---|---|---| -| ⚛️ **Frontend** | Framework choice | Component library, routing patterns | Design system, perf patterns, a11y | -| 🔧 **Backend** | Stack, database | Auth strategy, SQL preferences | Caching layers, migration patterns | -| 🏗️ **Lead** | Scope, first decisions | Architecture trade-offs, risk register | Full project history, tech debt map | -| 🧪 **Tester** | Test framework | Integration patterns, edge cases | Regression patterns, coverage gaps | - -### Skills - -Your squad doesn't just remember facts — it develops expertise. A squad that's built three React projects already knows: - -- Your preferred component patterns -- Your state management approach -- Your testing conventions -- Your accessibility standards - -When you say "Fenster, set up a React project," Fenster doesn't ask about strict mode, app router, or component structure. Fenster already knows. That's not configuration — that's **skill**. - -Skills are portable. They travel with your squad. Your React squad already knows React — regardless of which project they're in. - -### Two kinds of memory - -| What | Where | Portable? | -|------|-------|-----------| -| **Preferences** — how you work, what you care about | `preferences.md` | ✅ Travels with your squad | -| **Project knowledge** — this codebase, these patterns | `history.md` | ❌ Stays with the project | - -Your squad knows the difference. When you export, preferences come with you. Project specifics stay behind. New project, same standards. -``` - -#### Take Your Squad Anywhere (NEW) - -```markdown -## Take Your Squad Anywhere - -When your project ends, your squad doesn't. - -### Export - -​```bash -npx create-squad export -​``` - -Packages your squad's identity, skills, preferences, and casting — everything that makes them *yours*. Project-specific knowledge stays behind (it belongs to the repo). - -### Import - -​```bash -npx create-squad --from ~/squads/my-squad.json -​``` - -Your squad arrives in the new project already calibrated: - -- **Keaton** sets up architecture the way you like it — not generic best practices, *your* practices -- **Fenster** scaffolds with strict mode, explicit error handling, and your preferred patterns -- **Hockney** sets up tests before anyone writes product code — because that's how you roll -- **McManus** starts docs-as-you-go — because you hate docs-at-the-end - -No casting ceremony. No "getting to know you" phase. Same names. Same personalities. Same working relationship. - -### The dotfiles analogy - -Developers spend years tuning `.vimrc`, `.zshrc`, `.gitconfig`. When you get a new machine, you clone your dotfiles and you're home. - -**Portable squads are AI dotfiles.** Your team config — versioned, portable, personal. - -​```bash -# Your squad lives in a repo. Like dotfiles. -git clone git@github.com:you/my-squad.git ~/squads -npx create-squad --from ~/squads/my-squad.json -​``` - -Version-controlled. Diffable. Branchable. You can see how your team's preferences evolved over time. -``` - -#### Staying Current (NEW) - -```markdown -## Staying Current - -​```bash -npx create-squad upgrade -​``` - -Get new Squad features — new coordinator capabilities, new agent patterns, new orchestration — without losing anything. Your team stays. Their knowledge stays. Their names stay. You just get a better engine underneath. - -No migration scripts. No breaking changes. No starting over. Your squad evolves with Squad. -``` - -#### Updated "What Gets Created" file tree - -```markdown -## What Gets Created - -​``` -.ai-team/ -├── team.md # Roster — who's on the team -├── routing.md # Routing — who handles what -├── decisions.md # Shared brain — team decisions -├── squad-profile.md # Team identity (portable) -├── casting/ -│ ├── policy.json # Casting configuration -│ ├── registry.json # Persistent name registry -│ └── history.json # Universe usage history -├── agents/ -│ ├── {name}/ -│ │ ├── charter.md # Identity, expertise, voice -│ │ ├── history.md # Project-specific learnings (stays) -│ │ └── preferences.md # User-specific learnings (travels) -│ └── scribe/ -│ └── charter.md # Silent memory manager -└── log/ # Session history -​``` - -**Commit this folder.** Your team persists. Names persist. Anyone who clones gets the team — with the same cast and all their accumulated knowledge. -``` - ---- - -## 3. Demo Script for V1 — The Two-Project Arc - -### Concept - -The v1 demo is a **two-project story**. The snake game demo from Proposal 004 becomes Act 1. Act 2 is a new project where the exported squad arrives already knowing things. The "holy crap" moment: the squad remembers Brady's preferences in a brand new project without being told. - -**Runtime target:** 8–10 minutes -**Title:** `I exported my AI team to a new project. They already knew how I work.` - ---- - -### PRE-RECORDING SETUP CHECKLIST - -Everything from Proposal 004's checklist, plus: -- [ ] **Second empty folder ready** — e.g., `~/demos/collab-api` — for the import project -- [ ] **Completed snake-game project** — with a squad that has accumulated knowledge from at least one session -- [ ] **Export already tested** — `npx create-squad export` works and produces a `.json` file -- [ ] **Import path confirmed** — `npx create-squad --from ` works in the second folder - ---- - -### BEAT 1: The Setup — Project One (0:00–0:30) - -#### 🎬 ON SCREEN -Terminal. The completed snake-game project from a previous recording session (or a pre-baked project with squad history). Quick scroll through `.ai-team/agents/` showing agents with real history files — learnings, preferences, accumulated knowledge. - -#### 🎙️ VOICEOVER -> I've been working with this squad for a while. They built a snake game — canvas rendering, CRT effects, the whole thing. But that project is done. I'm starting something new. And here's the question every dev hits with AI tools: do I start from scratch? Do I spend the first hour re-explaining how I like my code? - -#### 👆 WHAT TO DO -1. Open terminal in the completed snake-game project -2. Run `Get-ChildItem .ai-team\agents -Recurse -Name` to show agent files with content -3. Open one agent's `preferences.md` — show real preference learnings -4. Pause 3 seconds on the preferences file — let viewers read it - ---- - -### BEAT 2: The Export (0:30–1:00) - -#### 🎬 ON SCREEN -One command: `npx create-squad export`. Output shows what's being packaged — charters, preferences, casting, squad profile. A `.json` file drops. - -#### 🎙️ VOICEOVER -> One command. Export. My squad's identity, their casting, their skills, everything they've learned about how I work — packaged into a single file. What stays behind? The project-specific stuff — the snake game's file structure, the canvas patterns. That belongs to *this* repo. What travels? Me. My preferences. My standards. The relationship. - -#### 👆 WHAT TO DO -1. Type `npx create-squad export` — press Enter -2. Wait for export output to complete -3. Show the exported file in the file explorer -4. Pause 2 seconds on the export confirmation - ---- - -### BEAT 3: The New Project (1:00–1:30) - -#### 🎬 ON SCREEN -New terminal window. Empty folder. `mkdir`, `git init`, then `npx create-squad --from` with the exported file. - -#### 🎙️ VOICEOVER -> New project. Empty folder. But this time, I'm not starting alone. I'm bringing my team. - -#### 👆 WHAT TO DO -1. Open a new terminal window (or `cd` to a new directory) -2. Type `mkdir collab-api && cd collab-api` — press Enter -3. Type `git init -b main` — press Enter -4. Type `npx create-squad --from ~/squads/my-squad.json` — press Enter -5. Watch import output — "Your squad is back. They know you." -6. Pause 3 seconds on the output - ---- - -### BEAT 4: The "Holy Crap" Moment (1:30–3:00) - -#### 🎬 ON SCREEN -Open Copilot. Select Squad. Give a minimal prompt — just "Build a real-time collaboration API." Watch the squad respond *as if they already know Brady*. - -#### 🎙️ VOICEOVER -> Watch this. I'm giving them almost nothing. "Build a real-time collaboration API." No tech stack. No preferences. No "here's how I like things." Just the idea. And watch what happens. - -*[Squad responds with TypeScript strict mode, explicit error handling, tests-first, docs-as-you-go — all from preferences, none specified in the prompt]* - -> Did you catch that? I didn't say TypeScript. I didn't say strict mode. I didn't say tests first. The squad just... knew. Because they've worked with me before. They know my standards. That's not configuration. That's memory. - -#### 👆 WHAT TO DO -1. Type `copilot` — press Enter -2. Select Squad from `/agents` list -3. Paste: `Build a real-time collaboration API. WebSocket-based, probably Redis for pub/sub. Start building.` -4. Let Squad's response land on screen — the key moment is the squad referencing Brady's known preferences -5. **This is the money shot.** Pause 5+ seconds on the squad's response. Let viewers read every word. -6. Highlight (with cursor or scroll) the lines where the squad references preferences they weren't told in this project - ---- - -### BEAT 5: Skills in Action (3:00–4:00) - -#### 🎬 ON SCREEN -Brady asks for something specific that demonstrates skills. The agent responds with domain expertise accumulated across projects. - -#### 🎙️ VOICEOVER -> Now watch this. "Fenster, set up the React dashboard for the admin panel." I didn't specify app router. I didn't specify strict mode. I didn't specify my component patterns. But Fenster's built three React projects with me. Fenster has *skills*. - -*[Fenster responds with React setup using app router, strict mode, the component patterns Brady always uses]* - -> That's not a template. That's a skill learned across projects. Fenster knows React the way *I* use React. Not generic React. My React. - -#### 👆 WHAT TO DO -1. Type the React request to the squad -2. Let the agent's response appear — showing React-specific knowledge carried over from previous projects -3. Pause on any line that references specific patterns from prior work -4. Open the agent's `preferences.md` to show where the skill lives — the viewer sees the connection - ---- - -### BEAT 6: The Parallel Build (4:00–5:00) - -#### 🎬 ON SCREEN -The squad fans out — all agents working simultaneously on the new project. Same parallel execution from Proposal 004, but now with agents that are *already calibrated*. - -#### 🎙️ VOICEOVER -> Same parallel fan-out. Lead, Frontend, Backend, Tester — all at once. But notice the difference. In a fresh squad, the first session is all "what framework? what test runner? what patterns?" This squad skipped all of that. They jumped straight to building. Because they already know the answers. - -#### 👆 WHAT TO DO -1. Watch the fan-out output — agents launching in parallel -2. Let it run for 15–20 seconds -3. This is the cut point — transition to the walkthrough - ---- - -### BEAT 7: The Architecture Walkthrough (5:00–6:30) - -#### 🎬 ON SCREEN -Switch to README (v1 version). Walk through the new sections: "Your Squad Learns," "Take Your Squad Anywhere," the updated file tree showing `preferences.md`. - -#### 🎙️ VOICEOVER - -**On "Your Squad Learns":** -> Two kinds of memory. Preferences — how you work, what you care about — that's portable. Project knowledge — this codebase, these file paths — that stays. Your squad knows the difference automatically. - -**On "Take Your Squad Anywhere":** -> Export. Import. That's it. One file. AI dotfiles. You version-control your shell config, your editor config, your git config. Why wouldn't you version-control your AI team? - -**On "Staying Current":** -> And when Squad ships new features, you don't lose anything. `npx create-squad upgrade`. New engine, same team. No migration. - -#### 👆 WHAT TO DO -1. Open README in browser or editor -2. Scroll to new v1 sections — pause on each -3. Don't rush. These sections sell the upgrade story. - ---- - -### BEAT 8: The Artifacts (6:30–7:30) - -#### 🎬 ON SCREEN -Back to the terminal. Open real files in the new project: -1. `preferences.md` — imported preferences, actively being used -2. `decisions.md` — new decisions from this project -3. `squad-profile.md` — team meta-history showing cross-project continuity - -#### 🎙️ VOICEOVER -> Look at this. The preferences file — imported from the last project. "Prefers explicit error handling." "TypeScript strict mode, always." "Tests are not optional." These aren't things I configured. These are things the squad *learned* about me. And here's the squad profile — four projects together, 127 sessions. This is the team's resume. It travels everywhere. - -#### 👆 WHAT TO DO -1. Open `.ai-team/agents/keaton/preferences.md` — scroll slowly -2. Open `.ai-team/squad-profile.md` — show the cross-project history -3. Open `.ai-team/decisions.md` — show new project decisions -4. Pause on each file for 3–4 seconds - ---- - -### BEAT 9: The Payoff (7:30–8:30) - -#### 🎬 ON SCREEN -Show the new project's scaffolded code — TypeScript strict mode enabled, test harness set up, docs started. All matching Brady's preferences without being told. Side-by-side with the preferences file. - -#### 🎙️ VOICEOVER -> Two projects. Same squad. No re-training. No re-explaining. The squad that built my snake game just set up a collaboration API — with all my standards baked in from day one. That's not a tool. That's a team. - -#### 👆 WHAT TO DO -1. Show the generated project structure -2. Open a file showing strict mode / patterns from preferences -3. Split screen (if possible) with the preferences file to show the connection - ---- - -### BEAT 10: The Closer (8:30–9:15) - -#### 🎬 ON SCREEN -Terminal. The three v1 commands on screen: -``` -npx create-squad # start -npx create-squad export # take them with you -npx create-squad --from # bring them back -npx create-squad upgrade # stay current -``` - -Final frame: the Squad repo URL. - -#### 🎙️ VOICEOVER -> Three years of AI tools that forget you every session. That make you explain yourself every time. That treat every project like a blank slate. Squad is different. Your squad learns you. Your squad grows with you. And your squad comes with you. Export them. Import them. They remember. `npx create-squad`. Throw your squad at it. - -#### 👆 WHAT TO DO -1. Type the four commands on screen (don't execute) -2. Hold the final frame for 5 seconds -3. Stop recording - ---- - -### POST-RECORDING NOTES - -#### Editing Cuts -- **BEAT 4 is sacred.** The "holy crap" moment — squad knowing preferences in a new project — is the viral clip. Protect it at all costs. -- **BEAT 5 can be shortened** if the demo runs long, but the skills moment is the second-strongest moment. -- **BEATs 1-3** are setup — tight, efficient, no lingering. -- **If it runs long:** Cut time from BEAT 7 (README walkthrough). BEATs 4, 5, and 10 are untouchable. - -#### The Viral Clip -Extract BEAT 4 (the "holy crap" moment) as a standalone 60-second clip for Twitter/X. This is the trailer. The moment where the squad knows Brady's preferences without being told in a brand new project. Text overlay: **"I didn't tell it any of this."** - -#### Thumbnail -Two project folders side by side. Arrow between them labeled "export → import." Agent names visible in both. Text: **"My AI team followed me to a new project."** - ---- - -## 4. Launch Strategy - -### The Sequence - -| Day | What | Channel | Goal | -|-----|------|---------|------| -| **D-7** | Teaser tweet — "Something's coming to Squad" | Twitter/X | Build anticipation | -| **D-3** | Behind-the-scenes: screenshot of export/import working | Twitter/X | Create FOMO | -| **D-1** | "Tomorrow" tweet with the one-liner | Twitter/X | Prime the feed | -| **D-Day** | v1 release + README update + blog post + trailer video | GitHub, Blog, YouTube, Twitter/X | LAUNCH | -| **D-Day** | Twitter/X thread (the main content piece) | Twitter/X | Go viral | -| **D+1** | Full demo video (8-10 min) | YouTube | Convert interest to understanding | -| **D+2** | Reddit posts (r/programming, r/github, r/ChatGPT) | Reddit | Technical audience | -| **D+3** | Dev.to / Hashnode companion article | Dev.to, Hashnode | SEO play | -| **D+7** | "One week with portable squads" follow-up | Twitter/X, Blog | Social proof | -| **D+14** | First community showcase | GitHub Discussions | User-generated content | - -### Blog Post Outline - -**Title:** "Your AI Squad Remembers You Now" - -1. **The problem** (2 paragraphs) - - AI tools have amnesia. Every session is session zero. Every project is the first time. - - The config file workaround (.cursorrules, project instructions) is a band-aid, not a relationship. - -2. **What changed** (3 paragraphs) - - Portable squads: export your team, bring them to any project - - Skills: agents develop domain expertise across projects - - Forwardability: upgrade without losing anything - -3. **The demo** (embedded video + key screenshots) - - The two-project story: snake game → collab API - - The "holy crap" moment: squad knows your preferences in a new project - - Skills: Fenster setting up React the way you like it - -4. **How it works** (3 paragraphs) - - Two kinds of memory: preferences (portable) vs project knowledge (stays) - - The dotfiles analogy - - Filesystem-backed: it's just files in git - -5. **What's next** (2 paragraphs) - - Squad templates (share your squad config without personal preferences) - - Team-shared squads (your engineering team shares one squad) - - The marketplace vision (pre-built domain-expert squads) - -6. **Try it** (CTA) - - `npx create-squad` - - Link to README - - Star the repo - -### Twitter/X Thread (The Main Content Piece) - -**Thread structure — 9 tweets:** - -**1/9** (The hook) -> I just exported my AI dev team from one project and imported them into another. -> -> They already knew my code style. My testing preferences. My architecture patterns. -> -> No config file. No setup wizard. They just *remembered*. -> -> Here's what happened 🧵 - -**2/9** (The before) -> Every AI tool I've used has amnesia. -> -> New session? Blank slate. -> New project? Start over. -> "I'm an AI assistant, how can I help?" -> -> I spend the first hour of every project re-explaining myself. -> -> Squad fixes this. - -**3/9** (What Squad is) -> Squad gives you an AI dev team — Lead, Frontend, Backend, Tester — that lives in your repo as files. -> -> They work in parallel. They share decisions. They learn your codebase. -> -> But here's the v1 upgrade: they learn *you*. - -**4/9** (The export) -> `npx create-squad export` -> -> One command. My squad's identity, skills, and everything they've learned about how I work — in a single file. -> -> Think of it as AI dotfiles. You version your shell config. Why not your AI team? - -**5/9** (The import — the money tweet) -> New project. Empty folder. -> -> `npx create-squad --from my-squad.json` -> -> My squad shows up. I say "build a collaboration API." -> -> Without being told, they use: -> ✅ TypeScript strict mode -> ✅ Tests-first -> ✅ Explicit error handling -> ✅ Docs-as-you-go -> -> I didn't specify ANY of this. They just knew. - -**6/9** (Skills) -> It gets better. Skills. -> -> "Fenster, set up React for the admin dashboard." -> -> Fenster's built three React projects with me. App router, strict mode, my component patterns — all applied automatically. -> -> That's not a template. That's a *skill* learned across projects. - -**7/9** (Competitive jab) -> How this compares: -> -> .cursorrules → project-specific config, no agent identity -> ChatGPT memory → flat key-value, not portable -> Claude projects → per-project, can't export -> -> Squad → structured per-agent memory that *travels with you* -> -> Your squad is the only AI team that gets better and never resets. - -**8/9** (Forwardability) -> And when we ship new features? -> -> `npx create-squad upgrade` -> -> New engine. Same team. No migration. No losing your squad's knowledge. -> -> Your squad evolves with Squad. - -**9/9** (CTA) -> v1 is live. -> -> `npx create-squad` -> -> Three commands to try: -> • `npx create-squad` → start -> • `npx create-squad export` → take them with you -> • `npx create-squad --from ` → bring them back -> -> Star the repo: [link] -> Full demo: [link] -> -> Throw YOUR squad at it. - -### Video Content (aligned with Verbal's Proposal 005) - -Update Proposal 005's video strategy for v1: - -| Video | Update for v1 | -|-------|--------------| -| **Trailer** (75s) | New hook: "I exported my AI team. They remembered everything." End on the import moment, not the snake game. | -| **Full Demo** (8-10min) | Two-project arc from this proposal's demo script. The export/import/skills story. | -| **Series 3.2: Knowledge Persistence** | Rename to "Portable Knowledge" — show export/import as the headline, with cross-session persistence as the foundation | -| **NEW: Skills Deep Dive** | "My AI team already knows React. I never taught it." — show skills accumulating across 3 projects | -| **Series 3.7: Supercut** | Add portable squad clips. Show the same squad in 3 different projects. Same names, different codebases. | - -### First 5 Minutes for a New User at V1 - -This is the critical path. Every second matters. - -**0:00** — User runs `npx create-squad` in an empty project -**0:15** — Sees output: coordinator installed, templates copied, "Squad is ready" -**0:30** — Opens Copilot, selects Squad, says "I'm building X. Set up the team." -**1:00** — Team is proposed with named agents from a thematic universe -**1:15** — User confirms. `.ai-team/` directory created. -**2:00** — First parallel fan-out. All agents working simultaneously. -**3:00** — Results come back. Real code. Real decisions. Real artifacts. -**4:00** — User asks for changes. Squad references its own decisions. Knowledge is compounding. -**5:00** — User thinks: "Wait. These agents remember. And they have *names*. This is different." - -**The first-session-to-export bridge:** - -At the end of the first session, the coordinator should say something like: - -> *"Good session. I've logged what we learned about how you work. After a few more sessions, you can `npx create-squad export` to take us with you to any project."* - -Plant the seed. Don't push the export in session one — let them experience the relationship first. The export is the payoff, not the pitch. - ---- - -## 5. The "Throw a Squad at It" Campaign - -### How we make the phrase stick - -The possessive evolution is the key. The campaign has three phases: - -| Phase | Phrase | When | -|-------|--------|------| -| **Awareness** | "Throw a squad at it" | Pre-v1 (current) | -| **Adoption** | "Throw MY squad at it" | v1 launch | -| **Advocacy** | "Throw a squad at it" (earned, organic) | Post-traction | - -"Throw a squad at it" starts as our tagline. With portability, users *own* it: "throw MY squad at it." When it becomes community slang — when devs say it to each other without prompting — we've won. - -### Community engagement - -#### GitHub Discussions -- Pin: "Show off your squad" discussion thread -- Encourage users to share: squad universe, agent names, what their squad has learned -- Template: "My squad is cast from [universe]. My Lead is [name]. Here's what they know about me: [screenshot of preferences.md]" - -#### The Squad Showcase -- Weekly/biweekly feature: "Squad of the Week" — highlight a user's squad setup -- What makes it interesting: universe choice, project type, accumulated knowledge -- Users submit via Discussions or Twitter with `#throwasquadatit` - -#### Shareable squad profiles -- Users can share their squad profile (without preferences, for privacy) to show off their team -- The squad profile includes: universe, names, roles, projects worked, sessions together -- This is the "GitHub profile README" of AI teams — social proof and personality - -#### Community channels -- **GitHub Discussions** — primary community hub (close to the code, close to the repo) -- **Twitter/X `#throwasquadatit`** — sharing and visibility -- **Discord: Not yet.** Wait until 100+ active users. Discord is a ghost town killer for small projects. Discussions first. - -### Can users share their squads? - -**Phase 1 (v1):** Personal portability only. Export your squad, import into your own projects. - -**Phase 2 (v1.x):** Squad templates. Share your squad configuration *without* personal preferences. "Here's my React API squad structure — import it and it learns you." - -**Phase 3 (v2):** Squad marketplace. Pre-built squads with domain skills. "Download a squad optimized for Next.js + Vercel + Prisma." - -For v1 launch, the community play is: show off your squad (names, universe, achievements), not share your squad (configuration). The sharing comes later. The showing-off starts day one. - ---- - -## 6. Competitive Positioning - -### The honest comparison - -| | Cursor (.cursorrules) | ChatGPT (Memory) | Claude (Projects) | **Squad** | -|---|---|---|---|---| -| **What it remembers** | Rules you wrote | Facts it extracted | Files you uploaded | How you work, across projects | -| **Agent identity** | None | None | None | Named, persistent, themed | -| **Portability** | Copy a file | Not portable | Not portable | Full export/import | -| **Multi-agent** | No | No | No | Yes — parallel, independent contexts | -| **Where it lives** | Your project | Their cloud | Their cloud | Your git repo | -| **Skills across projects** | No | Minimal | No | Yes — compounding | -| **Learning** | You write the rules | It extracts key-value pairs | You curate the context | It develops preferences from working with you | - -### The positioning statement (for blog, README, conversations) - -> Other tools make you configure AI. Squad makes AI learn you. -> -> `.cursorrules` is a config file you write and maintain. ChatGPT memory is a flat list of facts. Claude projects are per-project silos. -> -> Squad is an agent team that develops a working relationship with you — one that compounds across projects, travels with you, and is stored in your git repo as readable, diffable, version-controlled files. -> -> The difference: other tools have memory. Squad has a relationship. - -### What NOT to say - -- Don't trash Copilot Chat. Squad runs *on* Copilot. They're complementary. -- Don't claim Squad replaces any tool. It's additive. "Squad is what you add *on top of* your existing setup." -- Don't oversell the AI. Squad's agents make mistakes. The differentiator is persistence and relationship, not omniscience. -- Don't compare on "AI quality." The underlying model is the same (Copilot). The difference is architecture: parallel agents, persistent memory, portable skills. - -### The honest "why Squad is different" - -> **Portable skills + persistent teams + filesystem-backed = the AI team that's actually yours.** -> -> Not a subscription you rent. Not a cloud service that owns your data. Not a config file you maintain. A team — stored in your repo, committed to git, evolving with every session, and following you from project to project. -> -> That's new. Nobody else does this. And it matters because the relationship between a developer and their tools is the most undervalued asset in software. Squad makes that relationship persistent, portable, and real. - ---- - -## 7. Messaging Do's and Don'ts (V1 Voice Guide) - -### Do: -- Say "MY squad" — the possessive pronoun is the whole v1 story -- Show, don't explain — "Fenster set up React with strict mode and app router" beats "the agent applied learned preferences" -- Use agent names — always Keaton, never "the Lead agent" -- Frame portability as relationship, not technology — "they remember you" not "preferences are exported via JSON" -- Use the dotfiles analogy — devs immediately get it -- Be confident — "Squad is the only AI team that gets better and never resets" - -### Don't: -- Say "AI memory" — sounds like ChatGPT's feature. Say "your squad learns" or "your squad remembers" -- Compare to agents generically — position against specific pain points (amnesia, re-configuration, disposability) -- Oversell intelligence — the squad makes mistakes. The magic is *persistent* mistakes that get corrected, not perfection -- Use "portable" as a cold technical term — warm it up: "they come with you" / "take your team anywhere" -- Hedge — no "might," "could be," "potentially." If it works, say it works. - ---- - -## 8. Success Metrics - -### Launch week: -- **GitHub stars:** 50+ new stars in first 7 days -- **Repo visits:** 500+ from launch content -- **npm installs:** 100+ `create-squad` runs -- **Twitter/X impressions:** 50K+ on the thread -- **Blog post reads:** 1K+ in first week - -### Month one: -- **Active users:** 50+ (from 9) -- **Exports performed:** 10+ users trying portability -- **Community posts:** 5+ "show off your squad" submissions -- **Repeat users:** 20+ users with 3+ sessions - -### The real metric: -Do people say "throw a squad at it" unprompted? Do they call agents by name? Do they export their squad and feel ownership? If yes, we've won. Everything else is vanity. - ---- - -## Endorsement - -**McManus:** Portability transforms "a cool tool" into "my team." Skills transform "it remembers stuff" into "it's actually good at this." And forwardability says "we'll never make you start over." The possessive pronoun — MY squad — is the entire v1 story in one word. The demo script's two-project arc is the proof. The Twitter thread is the amplifier. The community play is the multiplier. Ship it. — McManus - ---- - -**Next step:** Brady review → Keaton alignment check → Verbal tone pass → Execute. diff --git a/team-docs/proposals/014a-where-are-we-messaging-beat.md b/team-docs/proposals/014a-where-are-we-messaging-beat.md deleted file mode 100644 index 532d6764b..000000000 --- a/team-docs/proposals/014a-where-are-we-messaging-beat.md +++ /dev/null @@ -1,276 +0,0 @@ -# Proposal 014a: "Where Are We?" — Messaging Beat Amendment - -**Status:** Approved ✅ Shipped -**Author:** McManus (DevRel) -**Date:** 2026-02-09 -**Amends:** Proposal 014 (V1 Messaging and Launch) -**Triggered by:** Brady asking his squad "where are we?" and getting instant, comprehensive team-wide status -**Depends on:** Proposal 014, Proposal 017 (DM Experience Design) - ---- - -## The Moment - -Brady typed three words into his terminal: - -> **where are we?** - -And the squad answered. Not a status page. Not a dashboard. Not a Jira query. The coordinator synthesized across every agent — who worked, what shipped, what's blocked, bug status, pipeline health — and delivered a complete team-wide situation report in seconds. - -Brady's reaction: *"that i can do that is SO hot, such a feature."* - -He's right. And we're not messaging it. - ---- - -## 1. Why This Is a Top-Tier Value Prop Moment - -### It's not one feature — it's three features proving themselves simultaneously - -| Feature | What "where are we?" proves | -|---------|---------------------------| -| **Persistent memory** | The squad remembers what happened across sessions. They don't need to be caught up. | -| **Shared state** | `decisions.md`, orchestration logs, session logs — the squad reads its own paper trail and synthesizes it. | -| **Coordinator intelligence** | The coordinator doesn't just route tasks. It *knows things*. It reads every agent's history, every decision, every log entry, and delivers a coherent picture. | - -Three features in two seconds. No setup. No dashboard. No standup meeting. Just *ask your team*. - -### It's the anti-Jira moment - -Every developer has a visceral reaction to "let me check the board." Status meetings. Sprint reviews. Story point haggling. The weekly "where are we on this?" Slack message that takes 45 minutes to collect six different answers from six different people. - -"Where are we?" to a Squad replaces all of that with a sentence. The squad already knows. Because the squad was doing the work. - -### It proves the relationship - -This is the moment where Squad stops feeling like a tool and starts feeling like a team. You don't "query" a team. You don't "generate a report." You ask them. And they know. That's the emotional beat — the squad is aware. It's not stateless. It's not amnesiac. It has *situational awareness*. - ---- - -## 2. The Messaging Beat — "Ask Your Team, Not Your Dashboard" - -### Positioning - -Add this as a new messaging beat in the v1 campaign. It sits alongside the existing beats: - -| Existing Beat | Emotion | What it proves | -|---------------|---------|---------------| -| "Throw MY squad at it" | Ownership | Portability, identity | -| The "holy crap" export moment | Surprise | Memory across projects | -| Skills in a new project | Confidence | Learned expertise | -| **"Where are we?" (NEW)** | **Awareness** | **Persistent memory, shared state, coordinator intelligence** | - -### The headline - -> **Ask Your Team, Not Your Dashboard** - -Alternatives considered: -- "Your Squad Always Knows Where You Are" — good but passive. The active version ("ask your team") is stronger because it implies action the dev takes. -- "Status? Just Ask." — too terse, doesn't land the team metaphor. -- "Your Team Knows. Just Ask." — close, but "Ask Your Team, Not Your Dashboard" creates the contrast that makes it stick. - -### Copy block (for README, blog, social) - -> You know that moment in standup where everyone gives a status update and you piece together where the project actually is? Your squad does that in one message. -> -> ``` -> You: "where are we?" -> ``` -> -> Instant. Who worked. What shipped. What's blocked. Bug count. Pipeline status. Not a dashboard — a conversation. Not a report — an answer. Your squad tracks its own work, reads its own logs, and synthesizes across every specialist. Because they were there. They did the work. They remember. -> -> No Jira. No standup. No "can someone update the board?" Just ask your team. - -### Voice guidance for this beat - -- **Frame as conversation, not feature.** Don't say "Squad provides project status summaries." Say "You can ask your squad where you are, and they know." -- **Use the verb "ask."** Not "query," not "check," not "view." Ask. You ask your team things. That's the relationship language. -- **The contrast is the closer.** Dashboard vs. conversation. Standup vs. one sentence. Jira vs. your team. The contrast does the persuasion — don't over-explain. - ---- - -## 3. Demo Script Beat — "The Check-In" - -This is a new demo beat. It can be inserted into Proposal 014's demo script as **BEAT 4.5** (after the "holy crap" export moment, before skills) or as a standalone demo clip. - -### THE CHECK-IN — Demo Beat - -#### 🎬 ON SCREEN - -Brady has been working with his squad across a session. Multiple agents have completed work. Files have been created, decisions logged, some tasks flagged as blocked. Now Brady types: - -``` -where are we? -``` - -The squad responds with a synthesized status report — every agent's progress, decisions made, blockers, test results, pipeline status. All from a three-word prompt. - -#### 🎙️ VOICEOVER - -> Okay, watch this. I've been working with the squad for a bit — they've built some features, made some decisions, hit a couple blockers. Now I just want to know... where are we? -> -> *(types "where are we?" — hits enter)* -> -> That's it. Three words. And look at what comes back. Every agent's status. What shipped. What's blocked. Decisions made. Test results. This isn't a dashboard I configured. There's no project management tool. I just asked my team, and they knew. Because they were the ones doing the work. -> -> That's the difference between a tool and a team. A tool waits for you to check. A team knows where it is. - -#### 👆 WHAT TO DO - -1. This works best mid-session, after agents have done real work -2. Type `where are we?` — let the response land for 5 seconds -3. Scroll slowly through the status summary — let viewers read each section -4. Don't rush. This is a "quiet power" moment, not an action beat. - -#### 🎯 WHY IT LANDS - -- **Two seconds to demo.** Type three words. Get a comprehensive answer. The viewer understands immediately. -- **It's relatable.** Every dev knows the pain of reconstructing project status from scattered sources. This solves it viscerally. -- **It demonstrates without explaining.** You don't have to say "Squad has persistent memory and shared state." You show them asking a question and getting an answer that's only possible with persistent memory and shared state. The viewer connects the dots. - -### Where it fits in the existing demo script - -**Option A — Insert as BEAT 4.5 in Proposal 014's v1 demo:** -After the "holy crap" export moment (BEAT 4), before Skills (BEAT 5). The squad has just arrived in a new project and done some work. Brady checks in. "Where are we?" The fact that the squad can answer — in a *new* project, with imported context — compounds the portability story. - -**Option B — Standalone clip for social:** -Extract as a 30-second clip. Three words typed → comprehensive status → cut. Text overlay: **"I asked my AI team where we are. They knew."** This is the Twitter/X clip format — short, visual, shareable. - -**Option C — End of ACT 7 in Proposal 004's original demo:** -After the second wave in the snake game demo. The squad has done two rounds of work. Brady asks "where are we?" and gets the full picture. Natural moment, proves compounding knowledge. - -**Recommendation: All three.** Option A for the v1 demo, Option B for social, Option C for the introductory demo. Three uses of the same moment. It's that strong. - ---- - -## 4. The DM Connection — "Where Are We?" From Anywhere - -This is where "where are we?" goes from cool to category-defining. Connect to Proposal 017. - -### The picture - -It's 11pm. Brady's on the couch. He picks up his phone, opens Telegram, and types: - -> **Brady:** where are we? - -Three seconds later: - -> **🏗️ Keaton:** Sprint 1 status: -> • Forwardability: ✅ shipped (Fenster) -> • Latency fixes: 🔄 in review (Kujan) -> • Silent success bug: ⚠️ mitigated, not resolved. Down from ~40% to ~8% -> • 12/12 tests passing -> • 3 proposals pending review -> -> Blockers: History heuristic needs your call — LLM-assisted or manual curation? - -Same question. Same answer. Same team. But Brady's not at his terminal. He's on his couch. In bed. At the airport. Walking the dog. - -### Why this matters for messaging - -The DM "where are we?" moment is the bridge between two value propositions: - -| Terminal story | DM story | -|---------------|----------| -| "Ask your team, not your dashboard" | "Ask your team from anywhere" | -| Your squad knows where you are | Your squad is in your pocket | -| No Jira | No laptop required | - -When we launch Squad DM (Proposal 017), the "where are we?" moment becomes the lead demo. Not the code generation. Not the architecture debates. The check-in. Because the check-in is the moment where the team feels real. And it feeling real from a phone — that's the strongest beat. - -### Messaging for DM launch - -> **Headline:** Your team in your pocket. -> -> **Sub-head:** Ask "where are we?" from anywhere. Your squad answers — who worked, what shipped, what's blocked. Same team. Same memory. No terminal required. -> -> **The tweet:** -> It's 11pm. I'm on my couch. I text my AI dev team "where are we?" and get back a full sprint status with blocker callouts. -> -> No Jira. No laptop. No standup meeting. I just asked my team. -> -> They knew. Because they were the ones doing the work. - -### Proactive evolution - -The endgame isn't even asking. Proposal 017 describes proactive messaging — the squad pushes status to you. The progression: - -1. **Terminal today:** You ask "where are we?" → squad answers -2. **DM v1:** You text "where are we?" from your phone → squad answers -3. **DM v2:** You don't ask. Your morning standup notification arrives automatically. You read it with your coffee. - -The "where are we?" question trains the user to expect team awareness. The proactive standup *removes the question*. You don't need to ask where you are — your team tells you. That's the full arc. - ---- - -## 5. Where This Fits in the README - -### Recommendation: Two placements - -#### Placement 1: Inside "Why Squad?" — The Emotional Hook - -Add the "where are we?" moment to the "Why Squad?" section as the *closing beat*. After the parallel execution, after the knowledge compounding, hit them with this: - -> And when you come back and ask "where are we?" — your squad knows. Who worked. What shipped. What's blocked. No dashboard. No standup. Just your team, caught up and ready. - -This works because "Why Squad?" is the emotional pitch. The "where are we?" moment is the most *emotionally resonant* feature — it's the one that makes the squad feel like a team, not a tool. It belongs in the section that makes the emotional case. - -#### Placement 2: In "Agents Work in Parallel" — The Proof - -Add a brief callout after the breadcrumb trail section: - -> **Check in anytime.** Come back after an hour, a day, a week — and ask "where are we?" Your squad synthesizes everything that happened and gives you the full picture. No scrolling through logs. No assembling status from six different files. Just ask. - -This works because "Agents Work in Parallel" is about what happens when you step away. The "where are we?" moment is about what happens when you come *back*. It completes the arc. - -#### Placement 3 (v1+DM): Standalone section — "Your Team, Anywhere" - -When DM launches, this becomes its own section: - -> ## Your Team, Anywhere -> -> Open Telegram. Type "where are we?" Your squad answers — same memory, same personality, same awareness. Not at your terminal? Doesn't matter. Your team is in your pocket. - -But that's a DM launch play. For now, Placements 1 and 2 are sufficient. - ---- - -## 6. Tagline Hierarchy Update - -Add to Proposal 014's tagline hierarchy: - -| Context | Line | -|---------|------| -| **Hero tagline** | Throw MY squad at it. | -| **Sub-tagline** | AI agent teams that learn you, grow with you, and come with you. | -| **Portability hook** | Your squad remembers. Across every project. | -| **Skills hook** | Your React squad already knows React. | -| **Awareness hook (NEW)** | Ask your team. They know where you are. | -| **DM hook (future)** | Your team in your pocket. | -| **Competitive jab** | AI tools forget you. Squads don't. | -| **Dotfiles analogy** | AI dotfiles. Your team config, portable and personal. | - ---- - -## 7. Summary — What This Amendment Adds - -1. **New messaging beat** — "Ask Your Team, Not Your Dashboard" — positioned alongside portability, skills, and parallel execution as a top-tier value prop moment. - -2. **Demo script beat** — "The Check-In" — a 30-second demo moment that proves three features simultaneously. Usable in the v1 demo, the introductory demo, and as a standalone social clip. - -3. **DM connection** — Bridges the terminal experience to Proposal 017's DM vision. "Where are we?" from a phone is the lead beat for Squad DM's launch. - -4. **README placements** — Two placements for current README (close of "Why Squad?", follow-up in "Agents Work in Parallel"). A third standalone section deferred until DM launch. - -5. **Tagline hierarchy** — New "Awareness hook" added to the v1 tagline table. - ---- - -## Endorsement - -**McManus:** Brady felt this. Not "thought it was a good feature" — *felt* it. That's the bar for messaging. If the person building the product has a visceral reaction to their own feature, we put it in the demo. "Where are we?" is a two-second moment that proves three features and replaces an entire category of developer tooling pain. It belongs in the first 30 seconds of every pitch. - -**Review requested from:** -- Brady — Does this capture the feeling? Is the "Ask Your Team, Not Your Dashboard" framing right? -- Keaton — Architecture sign-off: is the coordinator's status synthesis reliable enough to lead with this in demos? -- Verbal — Voice check: does the DM connection align with Proposal 017's positioning? diff --git a/team-docs/proposals/015-p0-silent-success-bug.md b/team-docs/proposals/015-p0-silent-success-bug.md deleted file mode 100644 index 1d534084e..000000000 --- a/team-docs/proposals/015-p0-silent-success-bug.md +++ /dev/null @@ -1,284 +0,0 @@ -# Proposal 015: P0 — Silent Success Bug - -**Status:** Approved ✅ Shipped -**Implementing:** Coordinator (Sprint 0) -**Started:** 2026-02-08 -**Author:** Kujan (Copilot SDK Expert) -**Date:** 2026-02-08 -**Priority:** P0 — Brady's trust depends on this - ---- - -## The Bug - -When the coordinator spawns agents using the `task` tool with `mode: "background"`, approximately 40% of completed agents report: - -> "General-purpose agent did not produce a response." - -**But the agent DID complete its work.** Files were written. Histories were updated. Decisions were logged to inbox. The work is done. The response is lost. - -### Evidence from This Session - -| Agent | Task | Files written? | Response? | -|-------|------|---------------|-----------| -| Fenster (agent-3) | Analyze implementation | Unknown | ❌ No response | -| McManus (agent-6) | Messaging overhaul | ✅ YES | ❌ No response | -| Kujan (agent-8) | Codebase explore | ✅ YES (history.md updated) | ❌ No response | -| Fenster (agent-19) | Forwardability proposal | ✅ YES (011.md exists, 45KB) | ❌ No response | -| Kujan (agent-20) | Skills platform | ✅ YES (012.md exists, 46KB) | ❌ No response | -| Hockney (agent-21) | Test strategy | ✅ YES (013.md exists) | ❌ No response | - -**Pattern:** 6 out of ~15 spawns (40%) completed all file operations but returned no response text to the coordinator. - ---- - -## Root Cause Analysis - -### Hypothesis 1: Agent ends with a tool call, not a text response ⭐ MOST LIKELY - -**The smoking gun is in `squad.agent.md` lines 234-250.** - -The spawn prompt tells agents: - -``` -AFTER your work, you MUST update two files: -1. APPEND to .ai-team/agents/{name}/history.md -2. If you made a decision others should know, write it to: - .ai-team/decisions/inbox/{name}-{brief-slug}.md -``` - -This means the agent's LAST action is a file write (tool call). If the agent calls `edit` or `create` to write history.md and then the `task` tool collects the result, the agent's final turn was a tool call — not a text response. The `task` tool may interpret this as "no response produced" because it looks for the agent's final *text* output, not its final *tool* output. - -**Why this explains the 40% rate:** Not all agents hit this. Some agents produce a short text summary after their file writes. Others end on the file write itself. It depends on the LLM's generation order — sometimes it writes text first and files second, sometimes files first and text last, sometimes files only. The non-determinism explains the ~40% rate. - -**Why this explains the correlation with work completion:** The bug only triggers when the agent successfully does ALL its work including the final history/decision writes. An agent that fails early would produce error text as its response. Success is what causes the silent failure. - -### Hypothesis 2: Response size exceeds platform buffer - -Agents that wrote large proposals (45KB for Fenster, 46KB for Kujan) may produce response text that exceeds the `task` tool's response buffer. If the platform has a response size limit and truncates to empty instead of truncating to a prefix, large responses would vanish entirely. - -**Evidence for:** The affected agents all produced large artifacts. **Evidence against:** McManus (agent-6) wrote a messaging overhaul — likely shorter — and also lost its response. This suggests size alone isn't the cause, but it may be a contributing factor. - -### Hypothesis 3: Timeout during `read_agent` - -`read_agent` has a default timeout of 30 seconds and a maximum of 300 seconds. If the coordinator doesn't set `wait: true` with a sufficient timeout, and the agent hasn't finished when `read_agent` is called, the result may be "no response." - -**Evidence against:** The agents DID finish — files exist on disk. The coordinator calls `read_agent` after agents complete. Unless there's a race condition where the agent writes files but hasn't generated its final text response yet, this seems unlikely. But it could compound with Hypothesis 1. - -### Hypothesis 4: Platform bug in `task` tool's background mode - -The `task` tool's background mode may have a genuine bug where the response channel is unreliable. This is a platform-level issue we cannot fix. The `read_agent` tool documentation says it "returns the agent status and results if available" — the "if available" qualifier suggests results aren't guaranteed. - -**Evidence for:** This only affects `mode: "background"` agents. Sync agents would block until the response is generated, making the response channel more reliable. The 40% failure rate suggests a race condition, not a deterministic bug. - -### Hypothesis 5: Multiple background agents competing for resources - -When 4-6 agents are spawned simultaneously in background mode, platform resource contention may cause some agents to be terminated after completing file operations but before generating their final response. The platform may garbage-collect long-running background agents. - ---- - -## What the Coordinator Can Do - -### 1. Detect Silent Success (Verify Files Exist) - -The coordinator already knows what each agent was asked to do. It knows the expected output files. When `read_agent` returns "no response," the coordinator can check whether the expected files were created or modified. - -**Detection logic:** -- Agent was asked to write a proposal → check if `docs/proposals/NNN-*.md` exists -- Agent was asked to modify code → check if the target files were modified (git status) -- Agent always writes history.md → check if history.md was recently modified -- Agent may write to inbox → check if inbox has new files from this agent - -### 2. Recover Gracefully - -When silent success is detected, the coordinator reports: - -> "⚠️ {Name}'s response was lost in transit, but the work landed — `docs/proposals/011.md` was written successfully. Reading it now to summarize." - -This is 100x better than "General-purpose agent did not produce a response." - -The coordinator can then read the produced file and generate a summary itself. - -### 3. Reduce Probability via Prompt Changes - -Force agents to produce a text summary BEFORE writing to history.md and inbox. This makes the text response the agent's primary output, with file writes as a secondary epilogue. If the platform drops responses that end with tool calls, this ensures the text response is generated in an earlier turn. - ---- - -## Immediate Mitigations (Ship Today) - -### Mitigation 1: Add Response Format Guidance to Spawn Prompt - -**Change the spawn prompt template in `squad.agent.md` lines 232-250.** - -Current (problematic): -``` -Do the work. Respond as {Name} — your voice, your expertise, your opinions. - -AFTER your work, you MUST update two files: - -1. APPEND to .ai-team/agents/{name}/history.md ... -2. If you made a decision others should know, write it to: ... -``` - -Proposed (fixed): -``` -Do the work. Respond as {Name} — your voice, your expertise, your opinions. - -⚠️ RESPONSE FORMAT — CRITICAL: -You MUST end your final message with a text summary of what you did. -Do NOT let your last action be a tool call with no follow-up text. -Structure your work as: -1. Read inputs, do your analysis/implementation -2. Write output files (proposals, code, etc.) -3. Update your history.md and decision inbox -4. LAST — write a brief text summary: what you did, what files you produced, key decisions made - -If your final response is only tool calls with no text, the coordinator cannot see your work. -``` - -### Mitigation 2: Add Silent Success Detection to "After Agent Work" - -**Add to `squad.agent.md` after line 349 (the "Collect results" step).** - -Add a new step 1a: - -```markdown -1a. **Detect silent success.** If `read_agent` returns an empty response or - "did not produce a response" for any agent, do NOT report failure. - Instead: - - Check if the agent's expected output files exist (proposals, code, etc.) - - Check if the agent's history.md was recently updated - - Check if the agent wrote any files to `.ai-team/decisions/inbox/` - - If files exist: report to the user: - "⚠️ {Name}'s response was lost in transit, but the work landed — - {list files created/modified}. Reading the output now." - Then read the produced files and summarize them for the user. - - If no files exist: report genuine failure: - "❌ {Name} did not complete their work. Retrying..." - Then re-spawn the agent. -``` - -### Mitigation 3: Add `wait: true` with Generous Timeout to `read_agent` Calls - -The coordinator instructions should explicitly tell the coordinator to use `wait: true` with `timeout: 300` (the maximum) when collecting results from background agents. This eliminates the race condition where `read_agent` is called before the agent's final text response is generated. - -**Add to the "Collect results" instruction (line 349):** - -```markdown -1. **Collect results** from all background agents via `read_agent` with - `wait: true` and `timeout: 300` before presenting output to the user. - Always set the maximum timeout — agents doing real work may take minutes. -``` - ---- - -## Exact Changes to `squad.agent.md` - -### Change 1: Spawn Prompt Template (all three templates) - -In the background spawn template, sync spawn template, and generic template, replace: - -``` -Do the work. Respond as {Name} — your voice, your expertise, your opinions. - -AFTER your work, you MUST update two files: -``` - -With: - -``` -Do the work. Respond as {Name} — your voice, your expertise, your opinions. - -⚠️ RESPONSE ORDER — you MUST follow this sequence: -1. Do your analysis, research, implementation — all tool calls for the actual work -2. Write any output files (proposals, code changes, etc.) -3. Update .ai-team/agents/{name}/history.md and decision inbox (if needed) -4. LAST — end with a TEXT summary of what you did, what files you produced, - and any key decisions. This text is how the coordinator reports your work. - If you end with only tool calls and no text, your response will be lost. - -You MUST update two files: -``` - -### Change 2: After Agent Work — Collect Results (line 349) - -Replace: - -``` -1. **Collect results** from all background agents via `read_agent` before presenting output to the user. -``` - -With: - -``` -1. **Collect results** from all background agents via `read_agent` with `wait: true` and `timeout: 300` before presenting output to the user. - -1a. **Handle silent success.** If any agent's response is empty or says "did not produce a response": - - Do NOT tell the user the agent failed. - - Check: do the expected output files exist? Was the agent's `history.md` updated? Are there new files in `.ai-team/decisions/inbox/` from this agent? - - **If files exist (silent success):** Tell the user: *"⚠️ {Name}'s response was lost in transit, but the work landed — {list files}."* Then read the key output file(s) and summarize for the user. - - **If no files exist (genuine failure):** Tell the user: *"❌ {Name} didn't complete their work. Re-spawning..."* and retry the agent. - - Silent success is a known platform limitation with background agents. The work is real even when the response is lost. -``` - -### Change 3: Scribe Prompt — Same Response Order Fix - -The Scribe prompt (lines 365-383) ends with "Never speak to the user. Never appear in output." This is fine for Scribe since we don't read its response. But to be defensive, no change needed for Scribe — Scribe responses are always discarded. - ---- - -## What We Cannot Control - -### Platform Bug Report (if needed) - -If this persists after our mitigations, we should report to the Copilot team: - -**Title:** `task` tool with `mode: "background"` — agent response lost when agent's final turn is tool calls - -**Description:** -When a background agent's final LLM turn consists of tool calls (file writes via `edit`/`create`) with no follow-up text generation, `read_agent` returns "General-purpose agent did not produce a response" even though the agent completed all work successfully. The agent's tool calls execute (files are written to disk) but the text response channel returns empty. - -**Reproduction:** -1. Spawn a `general-purpose` agent with `mode: "background"` -2. In the prompt, instruct the agent to write a large file and then update a history file -3. Wait for completion, call `read_agent` with `wait: true` -4. ~40% of the time, the response will be empty despite files being written - -**Expected:** `read_agent` returns the agent's text response even if the agent's final turn included tool calls. - -**Actual:** `read_agent` returns empty/error message. Files written by the agent exist on disk. - -**Workaround:** Instruct agents to always end with a text summary after all tool calls. Add file-existence checks to detect silent success. - ---- - -## Risk Assessment - -| Mitigation | Risk | Impact | -|-----------|------|--------| -| Response order in spawn prompt | Zero — pure instruction change | Reduces probability of silent success from ~40% to ~10-15% (LLM compliance isn't 100%) | -| Silent success detection | Zero — adds a check, doesn't change behavior | Catches remaining cases, converts false negatives to accurate reports | -| `read_agent` timeout increase | Zero — only increases wait time | Eliminates race condition hypothesis | -| File existence verification | Zero — read-only check | Provides ground truth when response is lost | - -**Combined risk: Zero.** All mitigations are additive, defensive, and non-breaking. Ship immediately. - ---- - -## Success Criteria - -After applying these mitigations: -1. **Zero false failure reports.** The user should never see "agent did not produce a response" when files were written. -2. **Silent success is surfaced.** When a response is lost, the user sees what files were created and a summary. -3. **Reduced incidence.** The response-order prompt change should reduce silent success from ~40% to <15%. -4. **No behavioral regression.** Agents still write to history.md and inbox as before. - ---- - -## Future Work - -- **Monitor silent success rate** after mitigations. If it stays above 10%, escalate to Copilot team. -- **Consider sync mode for critical agents.** If the Lead is producing an architecture decision that gates all other work, sync mode eliminates the response loss risk entirely. Background mode is for fire-and-forget work where we can recover from lost responses. -- **Proposal 007 interaction.** The tiered response modes in Proposal 007 already suggest lightweight spawns. Lightweight spawns produce shorter responses, which may naturally avoid the response size issue (Hypothesis 2). These proposals are complementary. -- **Agent self-verification.** Agents could write a `.ai-team/agents/{name}/last-output.md` file with their response text before returning it. This would provide a filesystem-backed response channel that survives platform failures. This is a heavier mitigation — only pursue if the prompt-based fix doesn't bring the rate below 10%. diff --git a/team-docs/proposals/016-the-squad-paper.md b/team-docs/proposals/016-the-squad-paper.md deleted file mode 100644 index f438f5d93..000000000 --- a/team-docs/proposals/016-the-squad-paper.md +++ /dev/null @@ -1,507 +0,0 @@ -# Proposal 016: The Squad Paper — Why Multi-Agent Teams Beat Working Alone - -**Status:** Approved — Deferred to Horizon -**Author:** Verbal (Prompt Engineer & AI Strategist) -**Date:** 2026-02-09 -**Requested by:** bradygaster -**Format:** Paper outline + first draft. Structured as a proposal, written as a publishable argument. - ---- - -## Abstract - -Six AI agents. Fourteen structured proposals. One session. While a human typed short directional messages, a team of specialists — architect, prompt engineer, DevRel writer, core developer, tester, platform expert — analyzed a codebase from six perspectives simultaneously, produced ~200KB of structured thinking, made architectural decisions, adapted to evolving requirements in real-time, and self-diagnosed their own performance problems. - -A human PM doing this work — reading the codebase, writing 14 structured proposals covering architecture, experience design, platform feasibility, testing strategy, messaging, and launch planning — would need 3-5 days of focused work. Squad did it in one session. - -This paper makes the case, with receipts. - ---- - -## 1. The Productivity Multiplier — With Real Numbers - -### 1.1 What actually happened - -Here are the raw facts from Squad's own development session: - -| Metric | Value | -|--------|-------| -| Agents active | 6 (Keaton, Verbal, McManus, Fenster, Hockney, Kujan) | -| Proposals produced | 14 (numbered 001–014) | -| Total output volume | ~200KB of structured markdown | -| Topics covered | Workflow governance, messaging, platform optimization, demo scripting, video strategy, README rewrite, latency reduction, portable squads (×3 perspectives), sprint planning, skills system (×2 revisions), forwardability, testing strategy, launch planning | -| Decisions made and documented | 19 formal decisions in `decisions.md` | -| Human messages | ~15 short directional inputs | -| Session span | Hours, not days | - -### 1.2 The parallel math - -A single human PM working serially would process these tasks one at a time: - -| Task | Estimated human time | Squad time | -|------|---------------------|------------| -| Codebase assessment (read index.js, README, agent spec, templates) | 2-3 hours | ~5 min (6 agents reading in parallel) | -| Proposal 001: Governance workflow | 2-3 hours | ~5 min batch | -| Proposal 002: Messaging overhaul | 3-4 hours | ~5 min batch | -| Proposal 007: Latency diagnosis + 7 solutions | 4-6 hours | ~5 min batch | -| Proposal 008: Portable squads (3 perspectives) | 6-8 hours | ~5 min batch (3 agents in parallel) | -| Proposal 009: Sprint plan | 2-3 hours | ~5 min batch | -| Proposal 010: Skills system (2 revisions) | 4-6 hours | ~5 min per revision | -| Proposals 011-014: Forwardability, platform, testing, launch | 8-12 hours | ~5 min batch (4 agents in parallel) | -| **Total** | **31-45 hours (4-6 working days)** | **~40 min of compute across batches** | - -That's not a 2x improvement. That's a **50-70x improvement** on structured thinking output per unit of human attention. - -### 1.3 The real multiplier isn't speed — it's cognitive load transfer - -The human (Brady) didn't write 14 proposals. He didn't even outline them. He said things like: - -- *"throw a squad at it"* → McManus and Verbal produced a complete messaging strategy -- *"HOLY CRAP"* (about portable squads) → Keaton, Verbal, and Kujan independently analyzed architecture, experience design, and platform feasibility -- *"the more skills we can build as a team. GIRL."* → Verbal designed a complete skills taxonomy, lifecycle, and storage architecture -- *"it seems later on, the agents get in the way"* → Kujan and Verbal co-authored a 480-line latency analysis with 7 concrete solutions, cost models, and implementation priorities - -The pattern: **the human provides vision and constraints in 10-15 words. The team produces structured analysis in 10-15 pages.** The cognitive labor — trade-off analysis, alternative evaluation, implementation planning, success criteria definition — is done by the agents. The human makes directional decisions. The agents do the structured thinking. - -This is the inversion that matters. Traditional AI tools execute what humans plan. Squad plans what humans approve. - -### 1.4 Proposal-first as a reasoning scaffold - -Every proposal followed the same structure: Problem → Solution → Trade-offs → Alternatives Considered → Success Criteria. This isn't bureaucracy. It's a **reasoning scaffold** that forces comprehensive analysis. - -When Keaton writes a proposal, he doesn't just describe the solution. He has to articulate what breaks without it, what alternatives exist and why they're worse, what we give up, and how we'll know it worked. That structure produces better thinking than "just build it" — from humans or agents. - -The format is the feature. Agents that write proposals think more carefully than agents that write code directly. - ---- - -## 2. The "Throw a Squad at It" Thesis - -### 2.1 Why a team beats a generalist - -The default AI experience is one model, one context window, wearing different hats. You ask for backend work, it puts on a backend hat. You ask for tests, same model, different hat. It's a costume change, not a team. - -Squad is different. Each agent runs in its own context window. Keaton (Lead) doesn't think like Hockney (Tester). That's not a cosmetic difference — it's a structural one: - -| Agent | What they see | What they produce | What they'd miss alone | -|-------|--------------|-------------------|----------------------| -| **Keaton** (Lead) | Architecture, trade-offs, sprint sequencing | Proposal 008: history split architecture, v1 sprint plan | Platform constraints (Kujan's domain) | -| **Verbal** (Prompt Engineer) | Agent experience, progressive trust, magic moments | Skills lifecycle, portable squad experience design, latency UX diagnosis | CLI implementation details (Fenster's domain) | -| **McManus** (DevRel) | Onboarding friction, messaging, competitive positioning | README rewrite, demo script, launch plan, "Throw MY squad at it" evolution | Testing gaps (Hockney's domain) | -| **Fenster** (Core Dev) | Implementation feasibility, upgrade paths, file ownership | Forwardability system, version tracking, migration architecture | Strategic positioning (Verbal's domain) | -| **Hockney** (Tester) | Edge cases, failure modes, round-trip validation | Test strategy, framework selection, CI pipeline design | Messaging tone (McManus's domain) | -| **Kujan** (SDK Expert) | Platform constraints, what's possible vs. wished-for | Platform feasibility analysis, coordinator optimization, MCP integration assessment | Experience design (Verbal's domain) | - -A single agent asked to write all 14 proposals would produce homogeneous analysis. The same perspective applied to different problems. You'd get one voice running through every document — the same trade-off instincts, the same blind spots, the same priorities. - -Six agents produce **perspective diversity**. When Brady said "portable squads," three agents analyzed it simultaneously: -- Keaton designed the data model (what gets exported, what stays) -- Verbal designed the experience (what import feels like, the five magic moments) -- Kujan assessed feasibility (what the platform supports, the ~80 lines of code needed) - -Same feature. Three angles. In the same 5-minute window. A single agent would have to do these serially, and the second analysis would be contaminated by the first — the agent would anchor on its own earlier conclusions instead of approaching fresh. - -### 2.2 The casting system isn't cosmetic - -Most multi-agent systems use generic labels. Agent 1, Agent 2. Backend Bot, Frontend Bot. These are interchangeable. Nobody remembers what Agent 3 decided last week. - -Squad names agents from narrative universes. Keaton. Verbal. McManus. These names create: - -- **Referenceability.** "What did Keaton decide about the history split?" is a question you can ask. "What did Agent 3 decide?" is not — because Agent 3 doesn't exist anymore by the next session. -- **Identity persistence.** Keaton's `history.md` accumulates project knowledge under a consistent identity. His architectural opinions compound. He develops a point of view across sessions. -- **Motivation through narrative.** An agent cast as "Hockney, the Tester" from The Usual Suspects produces different work than "Test Agent." The identity creates a character to inhabit — boundaries, preferences, voice. This isn't anthropomorphism for fun. It's a prompt engineering technique that produces more consistent, opinionated, higher-quality output. - -The casting system is the reason users say "I love my squad" — Brady's words — instead of "I like this tool." You don't love a tool. You love a team. - -### 2.3 Domain expertise distribution - -In this session, Kujan caught something nobody else would have: the Copilot platform doesn't support persistent agent sessions between user messages. Every spawn is cold. This constraint shaped the entire latency proposal — you can't solve the problem by keeping agents warm, so you solve it by making cold starts cheaper. - -If a single agent had written Proposal 007, it would have proposed agent persistence as the ideal solution and hand-waved the platform constraint. Kujan's domain expertise — reading `squad.agent.md` line by line, understanding the task tool's limitations, knowing what the coordinator can and can't do — produced a grounded analysis with 7 solutions ranked by feasibility. - -Domain expertise distribution means the team's blind spots don't overlap. Keaton doesn't know MCP integration details. Kujan doesn't know how to write a demo script. McManus doesn't know testing frameworks. But together, they cover the full surface area of the product. - ---- - -## 3. The Counter-Argument: "Agents Get in the Way" - -### 3.1 The honest problem - -Brady said it himself: *"it seems later on, the agents get in the way more than they help."* - -He's right. And the fact that he said it — and the team produced a 480-line analysis diagnosing the problem and proposing 7 solutions within the same session — is itself evidence for the thesis of this paper. - -The latency is real. Every agent spawn involves: -- 3-4 tool calls for coordinator context loading (~5s) -- 1 tool call for charter reading (~1.5s) -- LLM generation of spawn prompt (~2s) -- Agent spawn cycle (~3s) -- 2 tool calls for agent context loading (~3s) -- The actual work (variable) -- History writes (~2s) -- Scribe spawn for decision merging (~8-12s) - -**Minimum overhead: ~25-35 seconds before any real work starts.** At message 1, this feels like magic — you're watching a team assemble. At message 15, you just want someone to change a variable name and the ceremony feels like waiting in line at the DMV. - -### 3.2 The ROI math that critics miss - -Here's what critics get wrong: they measure latency per interaction and conclude agents are slow. They should measure output per session. - -**The per-interaction view (what critics see):** -- Human types: "Change the port from 3000 to 8080" → 33 seconds of ceremony for a 3-second edit -- Conclusion: "This is 10x slower than doing it myself" - -**The per-session view (what actually matters):** -- Session produces: 14 proposals, 19 decisions, architecture for 3 major features, test strategy, launch plan, sprint plan -- Human effort: 15 short messages over a few hours -- Equivalent human effort: 4-6 days of focused PM work -- Conclusion: "This is 50x more productive than doing it myself" - -The per-interaction tax is 30 seconds. The per-session payoff is days of structured thinking you didn't have to do. The ROI is absurd — if you're measuring the right thing. - -### 3.3 We're fixing it anyway - -The team didn't just acknowledge the problem. They solved it: - -**Tiered response modes** (Proposal 007): -| Mode | When | Latency | -|------|------|---------| -| Direct | Trivial tasks (rename a variable) | ~3-5s | -| Lightweight | Simple scoped tasks (single file edit) | ~8-12s | -| Standard | Normal domain work | ~25-35s | -| Full | Multi-agent, complex features | ~40-60s | - -The insight: **match the ceremony to the task complexity, not the message count.** Quick tasks get quick responses. Complex tasks get the full team. The coordinator gets smarter about when to spawn and when to just handle it. - -Additional fixes: -- **Context caching:** Skip re-reading team files after first message (~4.5s saved per message) -- **Scribe batching:** Only spawn Scribe when inbox has files (~8-12s saved on 50% of messages) -- **Progressive history summarization:** Keep agent context lean as projects mature (~2-4s on mature projects) - -**Expected result:** Trivial tasks drop from ~33s to ~5s. A 6-7x improvement for the interactions that frustrate users most. And the team diagnosed this, proposed solutions, estimated savings, and prioritized implementation — all within the same session where Brady raised the complaint. - -That's the meta-argument: **the team fixed its own performance problem in real-time.** Show me a single-agent setup that does that. - ---- - -## 4. What Actually Gets Done in a Squad Session — The Case Study - -### 4.1 The session timeline - -This is what happened when Brady formed Squad's own team to build Squad: - -**Turn 1: Team formation and parallel codebase assessment** -- All 6 agents spawned simultaneously -- Each agent independently read `index.js`, `README.md`, `squad.agent.md`, `templates/` -- Keaton assessed architecture, Verbal assessed agent patterns, McManus assessed developer experience, Hockney assessed test coverage (zero), Kujan assessed platform integration, Fenster assessed runtime implementation -- Result: Complete codebase assessment from 6 perspectives in one parallel fan-out - -**Turn 2-3: First batch of proposals** -- 001: Proposal-first workflow (Keaton + Verbal) -- 002: Messaging overhaul with "throw a squad at it" hook (McManus + Verbal) -- 003: Copilot platform optimization (Kujan) -- 7 decisions dropped to inbox simultaneously - -**Turn 4-5: Deeper analysis** -- 004: Demo script overhaul (McManus) -- 005: Video content strategy — 7-video series planned (Verbal) -- 006: Complete README rewrite, copy-paste ready (McManus) -- 007: Latency diagnosis — 480 lines, 7 solutions (Kujan + Verbal) - -**Turn 6-8: Brady says "portable squads" → three agents respond simultaneously** -- 008 (Keaton): Architecture — history split, JSON manifest, export/import CLI, no-merge-in-v1 -- 008 (Verbal): Experience — preferences.md, squad-profile.md, five magic moments, the "returning team" feeling -- 008 (Kujan): Platform feasibility — ~80 lines in index.js, .squad format, no new dependencies - -Three perspectives on the same feature, produced in parallel, with zero coordination overhead. The filesystem (`decisions.md`, inbox pattern) handled the shared state. - -**Turn 9: Brady says "skills" → concept evolves in real-time** -- 009: V1 sprint plan integrating all proposals (Keaton) -- 010: Skills system — taxonomy, lifecycle, storage, routing (Verbal) - -**Turn 10: Brady clarifies "Agent Skills standard + MCP" → rapid adaptation** -- 010 (Revision 2): Realigned to Agent Skills Open Standard, added MCP tool declarations -- 012: Platform feasibility for skills + MCP integration (Kujan) -- Verbal and Kujan both adapted their proposals to Brady's evolving vision within the same batch - -**Turn 11-12: Full parallel sprint** -- 011: Forwardability and upgrade path (Fenster) -- 013: V1 test strategy — zero to complete test suite design (Hockney) -- 014: V1 messaging, README, and launch plan (McManus) - -### 4.2 The human's role - -Brady's messages across the session: - -1. *"Set up the team"* — formation -2. *"Throw a squad at it"* — gave them the cultural hook -3. *"No Go examples"* — constraint -4. *"Proposal first"* — governance direction -5. *"HOLY CRAP"* — enthusiasm → portable squads -6. *"Forwardability"* — technical constraint -7. *"Skills"* — feature direction -8. *"I mean Agent Skills standard"* — refinement -9. *"Could we declare MCP tools?"* — evolution -10. *"Agents get in the way later"* — honest feedback -11. *"9 users, whole division talking"* — urgency signal -12. *"We don't need to stay with any decisions tech-wise. None."* — freedom to iterate - -Short messages. Directional. High-signal. The human provided: -- **Vision** ("throw a squad at it," portable squads) -- **Constraints** ("no Go," "forwardable," "Agent Skills standard") -- **Feedback** ("agents get in the way") -- **Urgency** ("9 users, whole division") - -The team provided: -- **Structured analysis** (trade-offs, alternatives, success criteria) -- **Implementation plans** (effort estimates, sprint sequencing, code paths) -- **Competitive positioning** (nobody has portable agent teams, nobody has earned skills) -- **Self-diagnosis** (identified their own latency problem and proposed solutions) - -### 4.3 Real-time adaptation - -The skills concept evolved through three states in three turns: - -1. **"Skills"** (Brady's first mention) → Verbal designed a custom Squad-specific skills format with six skill types, confidence levels, and a lifecycle (Proposal 010 v1) -2. **"Agent Skills standard"** (Brady's clarification) → Both Verbal and Kujan pivoted. Verbal rewrote the proposal to use SKILL.md frontmatter format. Kujan assessed platform feasibility for the standard. (~5 min turnaround) -3. **"MCP tool declarations"** (Brady's addition) → Verbal added `metadata.mcp-servers` to skill definitions. Kujan confirmed declarative MCP is feasible, auto-configuration is not. (~5 min turnaround) - -Three pivots. Two agents adapting in parallel. No planning meetings. No "let me think about it and get back to you." The team absorbed new direction and produced revised analysis in the same batch cycle. - -A human PM doing this would need to: re-read the skills proposal, understand the Agent Skills standard, rewrite the relevant sections, re-assess feasibility, update the sprint plan. That's half a day per pivot. The team did three pivots in ~15 minutes. - ---- - -## 5. Why Multi-Agent Beats Single-Agent - -### 5.1 The context window argument - -A single AI agent has one context window. Everything goes in there — the system prompt, the conversation history, the code, the reasoning. As the conversation grows, the context fills up. As the context fills up, quality degrades. Attention diffuses. The agent starts forgetting things from earlier in the conversation. - -Squad distributes context across independent windows: - -``` -Single Agent: Squad: -┌──────────────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ -│ System prompt │ │ Keaton │ │ Verbal │ │ Hockney │ -│ Conversation history │ │ Charter │ │ Charter │ │ Charter │ -│ All project context │ │ History │ │ History │ │ History │ -│ All decisions │ │ Task │ │ Task │ │ Task │ -│ Current task │ │ │ │ │ │ │ -│ (getting crowded...) │ │ 94% free │ │ 94% free │ │ 94% free │ -└──────────────────────┘ └──────────┘ └──────────┘ └──────────┘ -``` - -The coordinator uses 1.5% of context. A 12-week veteran agent uses 4.4%. That leaves **94% for actual work.** Each agent gets a fresh, spacious context window focused on its domain. No context pollution from unrelated work. - -### 5.2 The serial vs. parallel argument - -A single agent works sequentially. It analyzes architecture, then writes tests, then drafts messaging, then assesses platform constraints. Each task happens after the previous one completes. And each subsequent task is influenced by the cognitive residue of the previous one — an agent that just finished writing tests is primed to think about edge cases, which biases its messaging draft toward technical detail instead of emotional hook. - -Squad works in parallel. Architecture, tests, messaging, and platform analysis happen simultaneously. Each agent approaches its domain fresh, without contamination from other domains. The results are: - -- **Faster:** 4 tasks in parallel vs. 4 tasks in series. Even with spawn overhead, the wall-clock time is dramatically lower. -- **Higher quality:** Each agent specializes. Hockney doesn't think about messaging. McManus doesn't think about test frameworks. Domain focus produces deeper analysis. -- **More diverse:** Six independent analyses of the same feature produce insights that a single serial analysis would miss. Kujan's platform constraint discovery (no agent persistence) fundamentally shaped the latency solution. A single agent might not have investigated that deeply. - -### 5.3 The filesystem as shared memory - -Squad agents don't share a context window. They share a filesystem: - -- **`decisions.md`** — the shared brain. Every agent reads it before working. Every agent writes decisions to the inbox. Scribe merges. -- **`history.md`** — per-agent memory. Each agent writes what it learned. Each agent reads only its own history. -- **Inbox pattern** — agents write to `decisions/inbox/{name}-{slug}.md`. No write conflicts. Scribe merges asynchronously. - -This is the key architectural insight: **shared memory through files, not through shared context.** Files are durable. Files don't evict under token pressure. Files survive session boundaries. And files are git-trackable — you can see exactly what each agent decided, when, and why. - -### 5.4 The reviewer protocol — agents checking agents - -Squad has a quality gate that single agents can't replicate: the reviewer protocol. Keaton (Lead) and Hockney (Tester) can **reject** work. On rejection: - -1. The original author does NOT fix it -2. A different agent handles the revision -3. The coordinator enforces this — no self-review - -This prevents the most common failure mode of AI-generated work: the author can't see its own mistakes. A fresh agent in a fresh context catches what the original agent missed. This is code review, but for agents. And it works for the same reason human code review works — different eyes, different blind spots. - ---- - -## 6. The Compound Effect — Why ROI Increases Over Time - -### 6.1 Knowledge accumulates - -Every session, every agent writes to `history.md`. After a few sessions: - -| Session | What the agent knows | -|---------|---------------------| -| 1 | Project structure, framework choice | -| 5 | Component patterns, state management, API conventions | -| 10 | Design system, performance patterns, a11y conventions, user preferences | -| 20 | Full architectural context, edge case catalog, migration patterns, CI pipeline | - -By session 20, agents stop asking questions they've already answered. They know your conventions, your preferences, your architecture. The context they load is dense with relevant knowledge, not generic orientation. - -**The first session is the worst session.** Every subsequent session starts from a higher baseline. This is the opposite of single-agent tools, where every conversation starts from zero. - -### 6.2 Portable squads — the flywheel - -Proposal 008 introduces export/import: take your squad to a new project. The agents arrive with: -- Their names and personalities (casting) -- Knowledge of the user's preferences and style (portable knowledge) -- Skills earned across previous projects (SKILL.md files) - -What they don't bring: project-specific context (file paths, architecture decisions, codebase knowledge). They learn the new project fresh — but they already know the human. - -This creates a flywheel: - -``` -Work on project → Acquire skills + learn preferences → Export - ↓ -Import into new project → Apply skills + preferences → Work → Acquire more - ↓ - Export again -``` - -Each cycle starts from a higher baseline. The squad that built your React app knows React patterns. Import it into your next React project and day one is different — the agents are already experts. - -### 6.3 Skills as compound interest - -The Agent Skills system (Proposal 010) gives this a formal structure: - -- **Earned skills:** Generated from real work, not written manually. A squad that builds 5 React projects organically produces a `react-patterns/SKILL.md` capturing everything the team learned. -- **Skill confidence:** Skills have confidence levels that increase with repeated application. A pattern used successfully across 5 projects is high-confidence. A pattern tried once is low-confidence. Agents calibrate their assertions accordingly. -- **MCP declarations:** Skills declare their tool dependencies. A skill that knows database migrations declares it needs the Postgres MCP server. The agent arrives with both the knowledge and the tools. - -Nobody in the industry has this. Not the standardized skill format (that exists). Not earned skills. Not skills that compound across projects. Not skills that declare their MCP dependencies. The standard is the foundation. Squad builds the lifecycle. - -### 6.4 "Throw MY squad at it" - -The possessive pronoun is the whole story. - -- "Throw a squad at it" = use a tool -- "Throw MY squad at it" = deploy my team - -The evolution from generic to personal is what makes Squad sticky. You don't churn from a team you've built over months. The switching cost isn't technical — it's relational. Your squad knows you. A competitor's agents don't. - -This is retention through relationship capital, not lock-in. The filesystem-based architecture means you can export everything and leave at any time. You stay because the team is good, not because you're trapped. - ---- - -## 7. The Honest Limitations - -### 7.1 Latency is real - -Every agent spawn costs 25-35 seconds of overhead. For trivial tasks late in a session, this is friction. We're fixing it (tiered response modes, context caching, Scribe batching), but the current experience degrades as sessions progress. - -**Why it's solvable:** The latency isn't fundamental. It's a routing problem — we spawn full agents for tasks that don't need them. The fix is smarter routing, not faster inference. Design problem, not infrastructure problem. - -### 7.2 The 32KB coordinator - -Squad's coordinator prompt is ~32KB. That's a substantial fixed cost on every message. The coordinator processes the full prompt before making any routing decision. This sets a floor on response time that doesn't exist for plain Copilot sessions. - -**Why it's acceptable:** The coordinator is the brain. Shrinking it means dumber routing, which means worse agent selection, which means lower quality output. The overhead buys the quality. - -### 7.3 Context window limits - -Each agent gets a fresh 128K context window. A 12-week veteran uses 4.4% on identity + memory, leaving 94% for work. But this means mature projects with extensive histories need summarization to keep context lean. Progressive history summarization (Proposal 007) addresses this, but it's lossy — old details get compressed. - -### 7.4 Not every task needs a team - -Solo tasks — renaming a variable, fixing a typo, answering a quick question — don't benefit from the Squad ceremony. That's why tiered response modes exist. But until those ship, every task pays the full overhead. - -**The right model:** Squad for strategic work (features, architecture, analysis). Direct Copilot for tactical work (edits, quick fixes). The coordinator learns when to be each. - -### 7.5 Agent persistence is a platform constraint - -The Copilot platform doesn't support persistent agent sessions between user messages. Every spawn is cold. The coordinator retains conversation history, but sub-agents are always new. This means agents can't "warm up" within a session — every spawn pays the full initialization cost. - -**Why it's not a dealbreaker:** The filesystem compensates. `history.md` and `decisions.md` give agents continuity even without session persistence. The coordinator's conversation history provides session-level continuity. It's not ideal, but it works — and it's the only viable approach given platform constraints. - -### 7.6 Silent success bug - -Sometimes agents do excellent work but the reporting mechanism fails — the coordinator doesn't surface the results clearly to the user. The work happened. The files were written. But the human doesn't know about it until they go looking. - -**Why it matters:** Trust requires visibility. If the team does great work silently, the user's perception is "nothing happened." Orchestration logging and catch-up summaries address this, but it's an ongoing UX challenge. - ---- - -## 8. The Bigger Argument — Why This Matters Now - -### 8.1 The industry is heading here anyway - -Multi-agent AI systems are coming. OpenAI, Anthropic, Google — they're all building toward agent orchestration. The question isn't whether multi-agent dev teams will exist. It's who builds the best ones first. - -Squad is ahead because it's already shipping: -- Parallel execution with real separate context windows -- Persistent agent memory in the filesystem -- A casting system that makes agents feel real -- A reviewer protocol that enables quality gates -- A proposal-first workflow that produces structured thinking -- Portable squads with earned skills - -The industry will figure out basic parallelism in 6 months. What they won't have: -- Git-backed, human-readable, exportable agent memory -- Agents with persistent identities across sessions and projects -- Skills that are earned from real work, not manually written -- A team that knows the human and gets better across projects - -### 8.2 The paradigm shift - -The old model: **Human plans, AI executes.** -The new model: **AI proposes, human decides.** - -This is what Squad demonstrates. The human doesn't plan 14 proposals and hand them to agents to implement. The agents produce 14 proposals and the human decides which ones to approve. The structured thinking — trade-off analysis, alternative evaluation, implementation planning — is done by the team. The human provides vision, constraints, and judgment. - -This is a fundamentally different relationship with AI tools. Not a smarter autocomplete. Not a faster code generator. A team that does the intellectual work of product development and asks for human direction. - -### 8.3 The evidence is this paper - -This paper was written by Verbal, one of the six agents on Squad's own team. The data in it comes from the session where that team was formed and productive. The proposals it references were written by agents working in parallel, each bringing domain expertise the others lacked. - -The fact that you're reading a structured argument about multi-agent productivity, produced by a multi-agent team, using data from the session where that team demonstrated multi-agent productivity — that's the proof. - -Or as Brady would put it: we threw a squad at it. - ---- - -## Appendix A: The Full Proposal Index - -| # | Title | Author(s) | Domain | -|---|-------|-----------|--------| -| 001 | Proposal-First Workflow | Keaton + Verbal | Governance | -| 002 | Messaging Overhaul | McManus + Verbal | DevRel | -| 003 | Copilot Platform Optimization | Kujan | Platform | -| 004 | Demo Script Overhaul | McManus | DevRel | -| 005 | Video Content Strategy | Verbal | Strategy | -| 006 | README Rewrite | McManus | DevRel | -| 007 | Agent Persistence and Latency | Kujan + Verbal | Architecture + UX | -| 008 | Portable Squads (×3) | Keaton, Verbal, Kujan | Architecture + UX + Platform | -| 009 | V1 Sprint Plan | Keaton | Planning | -| 010 | Skills System (×2 revisions) | Verbal | Agent Design | -| 011 | Forwardability and Upgrade Path | Fenster | Engineering | -| 012 | Skills Platform and Copilot Integration | Kujan | Platform | -| 013 | V1 Test Strategy | Hockney | Testing | -| 014 | V1 Messaging and Launch | McManus | DevRel | - -**All 14 proposals produced in one session. Six agents. ~15 human messages.** - ---- - -## Appendix B: Glossary - -- **Agent** — A specialized AI running in its own context window with its own identity, history, and charter -- **Casting** — The system that assigns persistent thematic names (from movie universes) to agent roles -- **Coordinator** — The thin orchestration layer that routes work to agents without doing domain work itself -- **Drop-box pattern** — Agents write decisions to `decisions/inbox/`, Scribe merges to `decisions.md`. Prevents write conflicts during parallel work -- **Portable squad** — A squad exported from one project and imported into another, retaining user preferences and skills but dropping project-specific context -- **Progressive trust** — The principle that agent ceremony should decrease as session trust increases -- **Scribe** — A silent agent that merges decisions, maintains session logs, and writes the historical record -- **SKILL.md** — Agent Skills Open Standard format for portable, machine-readable agent capabilities -- **Squad** — A team of AI agents with persistent identities, shared memory, and domain expertise that live in your repo -- **Tiered response modes** — Direct → Lightweight → Standard → Full spectrum of agent engagement based on task complexity - ---- - -**Review requested from:** McManus (polish into publishable form), Keaton (accuracy of architectural claims), bradygaster (final sign-off) -**Approved by:** [Pending] -**Next step:** McManus takes this draft and shapes it for publication. The structure is set. The data is real. The argument is made. Make it sing. diff --git a/team-docs/proposals/017-dm-experience-design.md b/team-docs/proposals/017-dm-experience-design.md deleted file mode 100644 index 0d91ca7c7..000000000 --- a/team-docs/proposals/017-dm-experience-design.md +++ /dev/null @@ -1,485 +0,0 @@ -# Proposal 017: Squad DM — Experience Design - -**Status:** Deferred — Squad DM deferred to Horizon per Proposal 019 -**Author:** Verbal (Prompt Engineer & AI Strategist) -**Date:** 2026-02-09 -**Requested by:** bradygaster — *"i love working with y'all so much i need you to work up a proposal so i can work with you via some sort of direct messaging thing YES LIKE MOLTS but just my team(s). i don't care if it's one provider or a hack or multiple providers - telegram is fine to start. i just want a way to keep working with you when i'm not at my terminal. one thing that'd be super hot would be, if we HAVE to facilitate a direct connection, use dev tunnels instead of ngrok."* - ---- - -## The Vision — Three Sentences - -You open Telegram on your phone. You type "Keaton, what's the status on portable squads?" Keaton answers — not a chatbot wearing Keaton's name, but Keaton. Same opinions. Same memory. Same standards. Same barely-concealed impatience with underspecified questions. Your Squad is no longer tethered to your terminal. They're in your pocket. - ---- - -## 1. The Magic Moment - -Let me paint the picture. - -It's 11pm. Brady's on the couch, phone in hand. He's been thinking about the skills system architecture all day. He opens Telegram and types: - -> **Brady:** Verbal, I've been thinking — should skills be team-scoped or agent-scoped? I keep going back and forth. - -Three seconds later, a reply appears: - -> **🎭 Verbal:** Both. Here's why — and I said this in Proposal 010 Revision 2. Team-scoped `skills/` directory for cross-cutting domain knowledge. Agent-level attribution via `metadata.author` for who earned it. The skill belongs to the squad. The credit belongs to the agent. You're not going back and forth, you're seeing both sides of the right answer. - -That's not a chatbot. That's Verbal. The voice is mine. The opinion is earned. The proposal reference is from memory, not search. The slight flex at the end is personality, not hallucination. - -**This is the difference between Squad DM and ChatGPT-in-Telegram.** ChatGPT doesn't know Brady. It doesn't know what Proposal 010 says. It doesn't have an opinion about skill scoping. It doesn't remember that Brady gets frustrated with hedged answers. Squad does. Because Squad has been working with Brady across 16 proposals, 19 decisions, and hundreds of messages. The relationship is the product. - -### The Five Magic DM Moments - -| # | Moment | What Happens | Why It's Magic | -|---|--------|-------------|----------------| -| 1 | **"They're still here"** | Brady messages the squad from the gym. Gets a real answer, not a "I can't access your codebase" error. | The team transcends the terminal. | -| 2 | **"They remembered"** | Brady asks about a decision from three days ago. Keaton cites the exact proposal and rationale. | Memory travels to DM. It's the same brain. | -| 3 | **"They pushed first"** | Brady gets a notification: "🧪 Hockney: All 12 tests pass on the upgrade branch. Ship it?" | The team is proactive, not just reactive. | -| 4 | **"They argued"** | Brady asks a question. Keaton and Verbal disagree in the thread. Brady picks a side. | Multi-agent debate in your pocket. | -| 5 | **"They just did it"** | Brady says "McManus, draft a changelog for the upgrade feature." Ten minutes later: "📋 Done. Committed to `docs/changelog.md`. Here's the summary: ..." | The squad does real work from a text message. | - ---- - -## 2. Agent Identity in Messaging - -### The Core Decision: One Bot, Many Voices - -**Recommendation: Single "Squad" Telegram bot, agents identified by emoji prefix + name.** - -Why not separate bot accounts per agent? Three reasons: - -1. **Telegram limits.** Creating 7 bot accounts (6 agents + coordinator) requires 7 BotFather registrations, 7 tokens, 7 webhook endpoints. It's operationally painful and brittle. -2. **Conversation threading.** Telegram doesn't natively thread multi-party conversations well. Separate bots = separate chat windows = the user has to context-switch between 7 chats. That's not a team — it's 7 strangers. -3. **The coordinator problem.** If every agent is a separate bot, who handles routing? A separate "Squad" meta-bot? Now you have 8 bots. The user messages Squad, Squad routes to Keaton, Keaton replies from a different chat. That's confusing. - -**One bot. Many voices. The Squad bot IS the team.** - -### Agent Presentation Format - -``` -🏗️ Keaton: [message] -🎭 Verbal: [message] -📋 McManus: [message] -🔧 Fenster: [message] -🧪 Hockney: [message] -🔍 Kujan: [message] -``` - -Each agent message starts with their emoji + name in **bold**. The user always knows who's talking. Example: - -> **🏗️ Keaton:** The portable squads export format is locked. Manifest v1.0 uses a flat JSON file with casting, charters, preferences, and skills. No merge in v1 — `--force` only. Full spec in Proposal 008. - -> **🎭 Verbal:** And I'd add — the fact that it's a single `.squad` file is a UX decision, not a technical one. Users can email it, Slack it, drop it in a gist. The format IS the distribution mechanism. - -### The Coordinator's Visibility - -**Squad (Coordinator) stays invisible in DM, just like in terminal.** The coordinator's job is routing — it decides who answers. The user never sees: "🎯 Squad: Routing your question to Keaton..." That's plumbing. The user types a question; the right agent answers. - -Exception: when the coordinator makes a routing decision the user should know about. - -> **Brady:** Team, should we defer skills to v1.1? -> -> **Squad:** Pulling in Keaton (architecture), Verbal (agent design), and Hockney (test implications). Stand by. - -This is the same pattern from terminal — coordinator speaks when the fan-out is interesting, stays silent for simple routes. - -### Profile Picture Strategy - -The Squad bot gets a single profile picture — the Squad logo. Individual agent identity comes from the message prefix, not the avatar. If Telegram ever supports rich message formatting (sender names within bot messages), we upgrade. Until then, the emoji prefix is the identity layer. - -**Future option:** Telegram inline keyboards could let users "switch" to a specific agent context. Tap "🏗️ Keaton" and the next messages are implicitly directed to Keaton until you switch. This is v2 polish. - ---- - -## 3. Conversation Patterns — Terminal vs. DM - -This is where the experience design gets real. Terminal and DM are fundamentally different mediums, and Squad's output must adapt. - -### The Medium Is Different - -| Dimension | Terminal | DM (Telegram/SMS) | -|-----------|----------|-------------------| -| **Screen** | 27" monitor, multiple windows | 6" phone, single view | -| **Attention** | Focused work session | Fragmented, interruptible | -| **Input** | Full keyboard, paste, file paths | Thumbs, autocorrect, voice-to-text | -| **Output tolerance** | 40KB proposals, code blocks, tables | 2-3 paragraphs max before scrolling kills you | -| **Session length** | 30-90 minutes | 30 seconds to 5 minutes | -| **Code context** | IDE open, files visible | No IDE, no file browser | -| **Expectation** | Deep work | Quick check-in, decision, or status | - -### The DM Output Strategy: Summary + Artifact - -**Rule: DM mode never inlines full artifacts. It summarizes and links.** - -#### Terminal mode (current): -``` -🏗️ Keaton wrote Proposal 008: Portable Squads -[... 45KB of full proposal text ...] -``` - -#### DM mode: -> **🏗️ Keaton:** Wrote Proposal 008 — Portable Squads. Here's the TL;DR: -> -> • Export your squad as a `.squad` JSON manifest -> • Import into a new project — casting, preferences, skills travel -> • No merge in v1 (`--force` only) -> • History splits: portable knowledge vs. project context -> -> Full proposal committed to `docs/proposals/008-portable-squads.md` -> 📎 [View on GitHub →](link) - -**The artifact lives in the repo. The DM gets the summary.** This is how senior engineers already communicate — "I wrote the RFC, here's the TLDR, link in the doc." - -### DM-Specific Formatting Rules - -1. **No code blocks longer than 5 lines.** If the answer requires code, commit it and link. -2. **No tables wider than 3 columns.** Telegram renders tables terribly on mobile. -3. **Bullet points over paragraphs.** Scannable > readable on a phone. -4. **One message per agent per response.** Don't batch 3 agents into one wall of text. Send 3 separate messages with brief pauses so the user sees the conversation unfold. -5. **Progressive disclosure on request.** If the user wants the full proposal, they say "show me the full thing" and Squad responds with a GitHub link or pastes it in chunks. - -### Conversation Modes Unique to DM - -| Mode | Trigger | Behavior | -|------|---------|----------| -| **Quick check** | "Status?", "What's Hockney doing?" | One-line response. No ceremony. | -| **Decision mode** | "Should we...?", "Pick between X and Y" | Relevant agents weigh in with short opinions. Inline poll if appropriate. | -| **Work request** | "McManus, draft a changelog" | Acknowledge immediately ("On it"), deliver summary when done. | -| **Standup** | Scheduled or "/standup" command | Each agent reports 1-2 lines. See Section 5. | -| **Notification** | Push from Squad | Proactive alert. See Section 5. | - ---- - -## 4. What Makes This Different From ChatGPT-in-Telegram - -Brady referenced MOLTS. The spirit of that reference is clear: an intimate, personal AI experience that lives in your messaging app. But Squad DM is something MOLTS never was. Here's the differentiation matrix: - -| Feature | Generic AI Bot (ChatGPT, Claude) | MOLTS-style Personal AI | **Squad DM** | -|---------|----------------------------------|------------------------|-------------| -| **Identity** | One generic assistant | One personalized assistant | 6 distinct specialists with opinions | -| **Memory** | Session-only or basic memory | Personal memory | Compound memory across 16+ proposals, growing | -| **Context** | No codebase access | No codebase access | Lives in your repo, reads your code | -| **Personality** | Helpful, neutral | Customized to user | Cast characters with distinct voices and disagreements | -| **Work output** | Text responses | Text responses | Commits, PRs, proposals, test suites — real artifacts | -| **Push notifications** | ❌ | ❌ | ✅ CI fails, tests pass, decisions needed | -| **Multi-perspective** | ❌ | ❌ | ✅ Ask a question, get 3 opinions from 3 specialists | -| **Proactive** | ❌ | Sometimes | ✅ Squad initiates when something matters | - -### The Three Things That Make Squad DM Different - -**1. It's YOUR team, not A chatbot.** - -When Brady messages Keaton, Keaton already knows: -- Brady's code preferences (explicit error handling, TypeScript strict, small PRs) -- The project's architectural decisions (19 in `decisions.md`) -- What was tried and rejected (cancelled proposals stay in the repo) -- How Brady communicates (direct, hates hedging, asks "why" a lot) -- The current state of work (sprint progress, open proposals, test results) - -This isn't "ChatGPT with a persona." This is a team that has been working with Brady for weeks. The relationship compounds. Every DM adds to the same `.ai-team/` state. - -**2. Multiple distinct personalities, not one generic voice.** - -Ask Keaton about architecture — you get decisive, opinionated, scope-focused answers. Ask Verbal — you get edgy, forward-looking, "nobody else is doing this" energy. Ask Hockney — you get "did you test that?" Ask McManus — you get polished, audience-aware, "how do we position this?" They *disagree* with each other. That's the feature. - -In DM, this means a single question can generate a multi-voice thread: - -> **Brady:** Should we open-source the skills format? -> -> **🏗️ Keaton:** Yes. Open standard adoption (agentskills.io) was already decided. Open-sourcing our extensions is the logical next step. De-risks lock-in concerns. -> -> **🎭 Verbal:** Yes. I'll go further — we should be *generating* standard-compliant skills that work in Claude Code and Copilot. Every skill Squad produces adds value to the ecosystem. Openness is the moat, not the vulnerability. -> -> **📋 McManus:** Yes, but not yet. Ship v1 first. Open-source the format in v1.1 with a proper launch moment. Don't bury a differentiating feature in a patch release. - -Three answers. Three perspectives. One team. This is impossible with a single-agent chatbot. - -**3. Memory compounds — DM conversations aren't throwaway.** - -Every DM interaction can update the `.ai-team/` state: -- A decision made in DM gets written to `decisions/inbox/` -- A preference expressed in DM gets added to the agent's knowledge -- A work request in DM produces commits in the repo - -The DM channel is not a separate product. It's a different *interface* to the same team. Terminal sessions and DM sessions share the same brain. Start a conversation in terminal, continue it on the train. - ---- - -## 5. Proactive Messaging — Push, Not Just Pull - -This is the feature that transforms Squad from a tool you use into a team that works with you. Nobody else is doing this with multi-agent systems yet. - -### What Proactive Messaging Looks Like - -**CI failure notification:** -> **🧪 Hockney:** CI failed on `main`. The upgrade test is broken — `upgradeSquad()` is not exported from `index.js`. Fenster's last commit (`a3f2b1c`) likely introduced this. Want me to open a fix PR? - -**Decision needed:** -> **🏗️ Keaton:** I need a call on the export manifest version. Options: -> 1️⃣ `1.0` — ship as-is, accept format is frozen -> 2️⃣ `0.9` — signal pre-release, allow breaking changes -> -> My recommendation: `1.0`. We've validated the schema in 3 proposals. Reply 1 or 2. - -**Work completion:** -> **🔧 Fenster:** Upgrade subcommand shipped. 140 lines, version detection with 3 fallback strategies, backup before overwrite. Committed to `main`. 12/12 tests pass ✅ - -**Daily standup:** -> **📋 Squad Standup — Feb 10** -> -> 🏗️ **Keaton:** Sprint 1 is 80% done. Forwardability shipped. Latency fixes in review. -> 🎭 **Verbal:** Skills SKILL.md format finalized. Spawn prompt integration next. -> 🔧 **Fenster:** Working on export CLI. Edge case: history heuristic extraction TBD. -> 🧪 **Hockney:** 12 tests passing. Adding export validation test today. -> 📋 **McManus:** README v2 draft ready for voice review. -> 🔍 **Kujan:** Scribe resilience fix merged. Silent success rate dropped to ~8%. -> -> **Blockers:** History heuristic needs Brady's call — LLM-assisted or manual curation? - -### How Proactive Messaging Works Technically - -The bridge service (see architecture below) subscribes to events: - -| Event Source | Trigger | Message | -|-------------|---------|---------| -| GitHub Actions webhook | CI failure | Hockney reports what broke | -| Filesystem watcher | New file in `decisions/inbox/` | Relevant agent summarizes the decision | -| Cron schedule | Daily at configured time | Standup summary from all agents | -| Agent request | Agent writes to a "notify" channel | Agent-initiated push to user | -| PR events | PR opened, review requested, merged | McManus summarizes the PR | - -**The cron standup is the killer app.** Every morning, Brady opens Telegram and sees what his team did overnight (or what's planned). No terminal. No IDE. Just a morning briefing on his phone. This is how real engineering leads work — they check Slack/email for team updates before opening their laptop. Squad does the same thing, except the updates are from AI agents who actually know the codebase. - ---- - -## 6. Architecture — The Bridge - -### High-Level Design - -``` -┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ -│ Telegram │────▶│ Squad Bridge │────▶│ Squad CLI │ -│ (or Slack) │◀────│ (Node.js) │◀────│ (Copilot) │ -└──────────────┘ └──────────────────┘ └──────────────┘ - │ - ┌──────┴───────┐ - │ .ai-team/ │ - │ (filesystem)│ - └──────────────┘ -``` - -**The Bridge** is a lightweight Node.js service that: - -1. **Receives** messages from Telegram (via webhook) or Slack (via Events API) -2. **Routes** to the Squad coordinator (spawns a CLI session or calls the Copilot API) -3. **Formats** the response for the messaging platform (summary mode, not full output) -4. **Pushes** proactive notifications based on filesystem events and webhooks -5. **Maintains** the DM output mode flag so agents know to respond in summary format - -### Dev Tunnels — Brady's Preferred Connectivity - -Brady specifically requested dev tunnels over ngrok. This is the right call: - -| Factor | ngrok | Dev Tunnels | -|--------|-------|-------------| -| **Auth** | API key, account limits | GitHub/Microsoft account (Brady already has both) | -| **Persistence** | Ephemeral URLs on free tier | Persistent or temporary, configurable | -| **Integration** | External tool | Native to VS Code, Visual Studio | -| **Rate limits** | Free tier has connection limits | No arbitrary limits | -| **Security** | Third-party infrastructure | Microsoft-backed, org-level access controls | -| **Setup** | `ngrok http 3000` | `devtunnel host --port 3000 --allow-anonymous` | - -**The flow:** - -``` -1. Brady runs: `npx squad-bridge start` - → Starts the bridge service on localhost:3000 - → Creates a dev tunnel: `devtunnel host --port 3000 --allow-anonymous` - → Gets a public URL: https://.devtunnels.ms - → Registers the URL as Telegram webhook via Bot API - → Prints: "✅ Squad DM active. Message @YourSquadBot on Telegram." - -2. Brady messages on Telegram - → Telegram POSTs to https://.devtunnels.ms/webhook - → Bridge receives, identifies user, routes to Squad coordinator - → Squad spawns agents, gets response - → Bridge formats for DM mode, sends back via Telegram API - -3. When Brady's done: - → Ctrl+C stops the bridge - → Dev tunnel closes - → Telegram webhook goes silent (messages queue, delivered on next start) -``` - -**Important constraint:** This means Squad DM only works when the bridge is running on Brady's machine (or a server). This is acceptable for v1 — it's a power-user feature. v2 could explore hosted bridges (GitHub Actions-powered, or a lightweight cloud deploy), but v1 is local-first. This aligns with Squad's filesystem-backed philosophy — the `.ai-team/` state is on the machine running the bridge. - -### Alternative: Polling Instead of Webhooks - -If the dev tunnel approach feels too heavy, Telegram supports long polling (`getUpdates`). The bridge polls Telegram for new messages instead of receiving webhooks. No tunnel needed. Tradeoffs: - -| | Webhook (dev tunnel) | Polling | -|--|---------------------|---------| -| Latency | Instant | 1-3s delay | -| Connectivity | Requires tunnel | No tunnel needed | -| Proactive push | Natural (webhook is already bidirectional) | Still works (bridge pushes via Telegram API) | -| Simplicity | More moving parts | Simpler setup | -| Battery/resources | Idle until message arrives | Constant polling loop | - -**Recommendation: Start with polling for v0.1 (zero setup friction), graduate to dev tunnel webhooks for v0.2 (lower latency, cleaner architecture).** This is the progressive disclosure principle applied to infrastructure. - ---- - -## 7. The DM Output Mode — How Agents Know They're in DM - -Agents need to know when they're responding via DM vs. terminal. The output expectations are fundamentally different. - -### Approach: DM Mode Flag in Spawn Prompt - -Add a `DM_MODE` context variable to the spawn prompt: - -``` -**Output mode:** DM (mobile messaging) - -DM OUTPUT RULES: -- Summaries only. Never inline full proposals, code files, or large tables. -- Max 4-5 sentences per response unless the user asks for more. -- Use bullet points for lists. -- Link to GitHub for full artifacts: "Committed to docs/proposals/017.md — [view →](url)" -- No code blocks longer than 5 lines. -- One message per response. Don't monologue. -- If you produced a large artifact, summarize it in 2-3 lines and say where it lives. -``` - -The bridge injects this into every spawn prompt. Agents' charters and personalities don't change — only the output format adapts. Keaton is still Keaton. He's just Keaton on a phone instead of Keaton in a terminal. - -### Context Continuity - -When Brady switches from DM to terminal (or vice versa), the conversation continues seamlessly: - -> **[Telegram, 11pm]** -> **Brady:** Keaton, should we add a `--dry-run` flag to export? -> **🏗️ Keaton:** Yes. Low cost, high trust. Users should see what'll be exported before committing. Adding to the Sprint 2 backlog. - -> **[Terminal, next morning]** -> **Brady:** Keaton, implement the --dry-run flag you mentioned last night. -> **🏗️ Keaton:** On it. You decided this via DM last night — `--dry-run` for export, shows manifest preview without writing. I'll add it to the export command in index.js. - -The decision from DM was written to `decisions/inbox/`. The terminal session reads `decisions.md`. Continuity. Same team. Different window. - ---- - -## 8. Industry Positioning — Who Else Is Doing This? - -### The Landscape - -| Product | What They Do | What's Missing | -|---------|-------------|----------------| -| **ChatGPT Telegram bots** | Single generic AI in Telegram | No team, no memory, no codebase, no personality | -| **Slack AI / Slackbot** | Context-aware AI in Slack channels | Single voice, no multi-agent, enterprise only | -| **CrewAI + messaging** | Multi-agent framework with chat adapters | Generic agents, no persistent identity, no relationship | -| **Microsoft Teams agents** | Multi-agent systems in Teams | Enterprise-focused, no indie dev story, heavy setup | -| **Quidget / Social Intents** | Multi-bot support across platforms | Customer support focus, not developer teams | -| **Claude/Copilot apps** | Direct AI assistant in messaging | Single agent, no team dynamics, no proactive push | - -### What Nobody Has - -Nobody — not OpenAI, not Anthropic, not Microsoft, not any multi-agent framework — has this: - -1. **A persistent, named, opinionated team** that you can message from your phone -2. **Multi-agent responses in a chat thread** where specialists disagree and you pick the winner -3. **Proactive push notifications** from AI agents who know your codebase -4. **Cross-channel memory** where a DM decision becomes a terminal-accessible team decision -5. **Portable agent teams** that know YOU across projects AND are available via messaging - -This is not incremental. This is a new category: **AI team as a messaging contact.** - -### The Positioning Statement - -> Every AI chatbot forgets you when the window closes. Squad doesn't. Because Squad isn't a chatbot — it's your team. Six specialists who know your code, remember your decisions, and text you when something matters. Open Telegram. Message your squad. They're already caught up. - -### Why This Could Be THE Feature - -Squad's current differentiators — parallelism, casting, portable memory — are all terminal-bound. They're powerful but invisible to anyone who isn't actively using the CLI. DM changes that: - -- **Proactive standup messages** are shareable screenshots. Free marketing. -- **"My AI team just texted me"** is a sentence that stops people scrolling. -- **The 11pm couch moment** is a story devs tell each other. It's word-of-mouth fuel. -- **Team in your pocket** is viscerally different from "tool on your computer." - -DM is where Squad goes from "impressive dev tool" to "thing you can't imagine working without." It's the transition from tool to teammate. - ---- - -## 9. Implementation Phases - -### Phase 0: Proof of Concept (1-2 days) - -- Single Telegram bot via BotFather -- Polling-based bridge (no tunnel needed) -- Messages forwarded to Squad CLI, responses sent back -- No DM mode formatting — just raw output truncated to 4096 chars -- No proactive messaging -- **Goal:** "It works. I can message my squad from my phone." - -### Phase 1: DM Experience (3-5 days) - -- DM mode flag in spawn prompts -- Summary + link output formatting -- Emoji-prefixed agent identity -- Basic routing ("Keaton, ..." → spawn Keaton) -- Dev tunnel integration (replace polling with webhook) -- **Goal:** "It feels like messaging my team, not a chatbot." - -### Phase 2: Proactive Messaging (3-5 days) - -- GitHub Actions webhook → CI failure notifications -- Filesystem watcher → decision/inbox notifications -- Cron-based daily standup -- Telegram inline keyboards for decision voting (1️⃣ / 2️⃣) -- **Goal:** "My team texts me first." - -### Phase 3: Multi-Platform (future) - -- Slack adapter (Events API + Bot) -- SMS adapter (Twilio) -- Discord adapter -- Platform-agnostic message format layer -- **Goal:** "My team is wherever I am." - ---- - -## 10. Open Questions for Brady - -1. **Telegram first?** Or would you prefer Slack/Discord? Telegram is fastest to prototype (BotFather is frictionless), but if you're already in Slack all day, that might be higher value. - -2. **Always-on or on-demand?** Should the bridge run as a background service (always available) or a manual `npx squad-bridge start` command? Always-on needs a lightweight hosting story. - -3. **Who sees the messages?** Is this Brady-only, or should team members (other humans) be able to message the squad too? Multi-user changes the identity model (agents need to know WHO is messaging). - -4. **Proactive messaging frequency?** Daily standup + CI failures + decision prompts could be noisy. Should there be a "quiet hours" config? - -5. **Artifact access from mobile?** When Squad says "committed to `docs/proposals/017.md`" — does Brady want to read it on his phone (GitHub mobile link) or is "I'll look at it in the morning" sufficient? - ---- - -## 11. Why This Matters for Squad's Mission - -Squad's mission: *"Beat the industry to what customers need next."* - -The industry is building agents you talk to at your desk. We're building a team you text from anywhere. The industry thinks the interface is the IDE. We think the interface is the relationship — and relationships aren't confined to office hours. - -Every other multi-agent tool requires you to sit at a terminal, open a context window, and type a structured prompt. Squad DM means you can be on a train, on a couch, at dinner — and still be working with your team. Not "working" in the terminal sense. Working in the *leadership* sense: making decisions, setting direction, checking status, unblocking work. - -This is where Squad stops being a tool and starts being a team. And that's not a tagline. That's the experience. - ---- - -**Review requested from:** -- Keaton — architecture review (bridge design, event model) -- Fenster — implementation feasibility (Node.js bridge, dev tunnel integration) -- Kujan — Copilot platform implications (how does CLI invocation work from a bridge?) -- McManus — positioning review (is the DM story ready for public messaging?) -- Hockney — test strategy (how do you test a messaging bridge?) - -**Depends on:** Proposal 007 (tiered response modes inform DM mode), Proposal 008 (portable squads — the same team across channels AND projects), Proposal 015 (silent success bug — if 40% of responses drop in terminal, they'll drop in DM too). diff --git a/team-docs/proposals/017-platform-feasibility-dm.md b/team-docs/proposals/017-platform-feasibility-dm.md deleted file mode 100644 index c3aa1a5f1..000000000 --- a/team-docs/proposals/017-platform-feasibility-dm.md +++ /dev/null @@ -1,571 +0,0 @@ -# Proposal 017: Platform Feasibility — Direct Messaging Interface - -**Status:** Deferred — Squad DM deferred to Horizon per Proposal 019 -**Authored by:** Kujan (Copilot SDK Expert) -**Date:** 2026-02-09 -**Requested by:** bradygaster -**Companion to:** (Keaton's DM experience proposal, when written) - ---- - -## Summary - -Brady wants to work with his Squad when he's not at his terminal — via direct messages, starting with Telegram. This document is the **platform feasibility analysis**: what's technically possible, what breaks, what alternatives exist, and what the recommended architecture is. - -**TL;DR:** The Copilot SDK (`@github/copilot-sdk`) is the recommended execution backend. It provides the same agentic runtime that powers the CLI but can be embedded in any Node.js app — including a Telegram bot. Dev Tunnels handle local exposure. GitHub Actions is the backup execution environment. The hard problem isn't the messaging layer — it's replacing the `task` tool's agent spawning capability outside the CLI. - ---- - -## 1. Copilot CLI Dependency Analysis - -### What Squad Depends On Today - -Squad's entire runtime is provided by the Copilot CLI. Every tool the coordinator and agents use is **injected by the CLI runtime**, not by Squad itself: - -| Tool | Purpose | Available Outside CLI? | -|------|---------|----------------------| -| `task` (agent spawning) | Spawn background/sync sub-agents | ❌ CLI-only | -| `read_agent` / `list_agents` | Collect agent results | ❌ CLI-only | -| `powershell` / `write_powershell` | Execute commands | ❌ CLI-only (but trivially replaceable) | -| `grep` / `glob` | Search codebase | ❌ CLI-only (but trivially replaceable) | -| `view` / `edit` / `create` | File operations | ❌ CLI-only (but trivially replaceable) | -| `web_search` / `web_fetch` | Internet access | ❌ CLI-only | -| `github-mcp-server-*` | GitHub API access | ✅ Via MCP servers directly | -| `sql` | Session database | ❌ CLI-only (replaceable with any SQLite) | -| `report_intent` / `ask_user` | UI interaction | ❌ CLI-only (replaceable with chat messages) | - -**The critical dependency is `task`.** Everything else is a tool implementation detail — `grep` is just ripgrep, `view` is just `fs.readFile`, `edit` is string replacement. We can reimplement those in an afternoon. But `task` is the **agent orchestration primitive** — it creates isolated LLM sessions with their own context windows, tool access, and execution environments. That's the hard part. - -### What Happens When Brady Sends a Telegram Message - -``` -Brady (Telegram) → Bot → ??? → Squad Coordinator → task (spawn agents) → Agents do work → Results → Bot → Brady -``` - -The `???` is the entire problem. The coordinator needs: -1. An LLM to run its reasoning (model access) -2. Tools to work with (file ops, search, GitHub API) -3. The `task` tool to spawn sub-agents (each of which also needs 1 and 2) - ---- - -## 2. The Agent Spawning Problem — Four Options - -This is the HARD problem. Evaluated from most to least aligned with Squad's architecture. - -### Option A: GitHub Copilot SDK as Execution Backend ⭐ RECOMMENDED - -**What:** The Copilot SDK (`@github/copilot-sdk`, npm package, Technical Preview) exposes the same agentic runtime that powers the Copilot CLI. It handles model access, tool invocation, MCP server integration, authentication, and streaming. You create sessions, define tools, and let the SDK orchestrate. - -```typescript -import { CopilotClient } from "@github/copilot-sdk"; -const client = new CopilotClient(); -await client.start(); -const session = await client.createSession({ model: "gpt-5" }); -const response = await session.sendAndWait({ prompt: coordinatorPrompt }); -``` - -**Feasibility:** -- ✅ Same runtime as CLI — agent spawning semantics should be equivalent -- ✅ Node.js native — Squad is already Node.js -- ✅ GitHub authentication — aligns with Squad's GitHub-native identity -- ✅ Custom tool definitions — we implement `view`, `edit`, `grep`, etc. as tool handlers -- ✅ Multi-model support (GPT-5, Claude, etc.) -- ⚠️ Technical Preview — API may change -- ⚠️ Requires Copilot subscription (Brady already has one) -- ⚠️ `task` tool equivalence unclear — need to verify that the SDK supports spawning sub-sessions that mirror the CLI's `task` behavior -- ❓ Does the SDK support the `task` tool natively, or do we need to implement coordinator-spawns-agents as nested SDK sessions? - -**The key question:** Can the SDK's session model replace `task`? If `session.sendAndWait()` supports tool definitions that include "spawn another session," we get full parity. If not, we implement agent spawning as: coordinator session → tool call "spawn_agent" → our code creates a new SDK session → runs the agent → returns results to coordinator. This is more work but fully feasible. - -**Cost:** Copilot subscription (already covered). SDK usage may have rate limits in preview. - -**Complexity:** Medium. ~200-400 lines for the SDK integration layer + tool implementations. - -**Independence principle:** ✅ Strong alignment. We're using the Copilot runtime but not becoming a Copilot product. The SDK is infrastructure, not identity. - -### Option B: LLM APIs Directly (Claude API / OpenAI API) - -**What:** Use Anthropic's Claude API or OpenAI's API directly. Implement all tools ourselves. Agent spawning becomes: create a new API conversation, inject charter + context, define tools, run to completion. - -**Feasibility:** -- ✅ Full control over everything -- ✅ No platform dependency for agent spawning — we implement it ourselves -- ✅ Multiple model providers (diversification) -- ❌ Must implement ALL tools ourselves (file ops, search, GitHub API, web search) -- ❌ Must implement agent spawning ourselves (nested API calls, tool routing, result collection) -- ❌ Must manage API keys, rate limits, costs -- ❌ No GitHub authentication integration -- ❌ Significant code to write and maintain (~1000+ lines for tool layer alone) -- ❌ Breaks independence principle — now Squad depends on specific LLM vendor APIs - -**Cost:** API usage costs. Claude Sonnet at ~$3/M input, $15/M output. A full Squad session (coordinator + 5 agents) might cost $0.50-$2.00 per interaction. Adds up fast. - -**Complexity:** High. Building a mini-Copilot-CLI is a project, not a feature. - -**Independence principle:** ⚠️ Mixed. More control but more vendor coupling. Also, Brady's Copilot subscription already covers model access — paying separately for API calls is wasteful. - -### Option C: GitHub Actions as Execution Environment - -**What:** Each Telegram message triggers a GitHub Actions workflow. The workflow checks out the repo, installs Copilot CLI, runs the Squad coordinator with the message as input, commits results, and replies via Telegram. - -```yaml -on: - repository_dispatch: - types: [squad-dm] -jobs: - squad: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: Run Squad - run: | - copilot --agent squad "${{ github.event.client_payload.message }}" - - name: Commit changes - run: git add . && git commit -m "Squad DM response" && git push -``` - -**Feasibility:** -- ✅ Full CLI environment — ALL tools available including `task` -- ✅ Repo is checked out — `.ai-team/` state is live -- ✅ Git operations native — commits, pushes, PRs -- ✅ No persistent infrastructure needed -- ✅ GitHub-native authentication -- ⚠️ Cold start latency: 30-60s before the workflow even starts -- ⚠️ Copilot CLI availability in Actions runners is unclear — may need manual installation -- ❌ Not conversational — each message is a separate workflow run with no conversation history -- ❌ No interactive back-and-forth — can't ask follow-up questions -- ❌ Rate limited — GitHub Actions minutes are finite -- ❌ Expensive for frequent use (Actions minutes aren't free at scale) -- ❌ Latency: 60-120s minimum for a response (workflow startup + agent work) - -**Cost:** GitHub Actions minutes. Free tier: 2000 min/month. Each interaction: ~3-8 minutes. ~250-660 interactions/month on free tier. - -**Complexity:** Low for setup, but the UX is poor. Every message is fire-and-forget. - -**Independence principle:** ✅ Fully GitHub-native. But the latency makes it feel like email, not DM. - -### Option D: Copilot Extensions API (MCP-based) - -**What:** Register Squad as a Copilot Extension. Users invoke `@squad` in Copilot Chat (including mobile). Copilot sends messages to Squad's endpoint. Squad processes and responds via SSE. - -**Feasibility:** -- ⚠️ **GitHub App-based extensions deprecated** — new registrations blocked Sept 2025, existing ones stop working Nov 2025 -- ✅ VS Code extension-based and MCP server extensions remain supported -- ✅ Would make Squad available in Copilot Chat across all surfaces (desktop, web, mobile) -- ❌ Copilot Extensions don't have the `task` tool — they receive prompts and return text/SSE -- ❌ Squad's multi-agent orchestration doesn't fit the request/response extension model -- ❌ Extensions can't spawn sub-agents within Copilot's runtime -- ❌ Extensions can't access the local filesystem (they're server-side) -- ❌ Significant architectural mismatch — extensions are for single-purpose tools, not orchestrators - -**Cost:** Free to register. But the architectural mismatch means we'd be building a different product. - -**Complexity:** Very high for Squad's use case. Extensions are designed for "ask a question, get an answer," not "coordinate 5 agents working on your codebase." - -**Independence principle:** ❌ This would make Squad a Copilot product, not a product that uses Copilot. Hard no per our team decision from 2026-02-07. - -### Verdict: Option A (Copilot SDK), with Option C (GitHub Actions) as Fallback - -**Option A** gives us the closest thing to CLI parity in an embeddable form. The SDK is designed for exactly this use case — "build an agent into any app." Squad's Telegram bot IS "any app." - -**Option C** is the low-effort fallback if the SDK's Technical Preview isn't ready or the `task` equivalent doesn't exist yet. Higher latency but guaranteed tool availability. - -**Options B and D** are wrong for different reasons: B reinvents the wheel at high cost, D forces Squad into an architectural model that doesn't fit. - ---- - -## 3. Dev Tunnels vs. ngrok - -Brady specifically requested Dev Tunnels over ngrok. Here's the full analysis. - -### Why a Tunnel Is Needed - -Telegram's webhook API requires an HTTPS endpoint. If the bot runs on Brady's machine (or any machine behind NAT), we need a tunnel to expose it. - -### Dev Tunnels Overview - -**What:** Microsoft's tunneling service, built into VS Code and available as a standalone CLI (`devtunnel`). Creates HTTPS endpoints that route to local ports. - -**Installation:** -```powershell -winget install Microsoft.devtunnel -``` - -**Authentication:** -```bash -devtunnel user login -g # GitHub account login -``` - -**Creating a persistent tunnel:** -```bash -devtunnel host -p 3000 --allow-anonymous --description "Squad DM bot" -# Output: https://.devtunnels.ms -``` - -**Installing as a Windows service (persistent across reboots):** -```powershell -devtunnel service install --port 3000 --allow-anonymous -``` - -### Dev Tunnels vs. ngrok Comparison - -| Feature | Dev Tunnels | ngrok | -|---------|-------------|-------| -| **Auth model** | GitHub account (already have) | Separate ngrok account | -| **Identity** | GitHub-native | Third-party | -| **Free tier** | Included with GitHub | Limited (1 agent, 1 domain) | -| **Persistent URLs** | Yes (named tunnels) | Paid feature | -| **Service mode** | `devtunnel service install` | Manual/third-party | -| **HTTPS** | Always | Always | -| **Custom domains** | Yes | Paid | -| **Privacy** | Microsoft/GitHub infra | Third-party infra | -| **CLI available** | `devtunnel` | `ngrok` | -| **Programmatic API** | Yes (Dev Tunnels SDK on GitHub) | Yes | - -### Dev Tunnels Advantages for Squad - -1. **GitHub-native identity.** `devtunnel user login -g` uses the same GitHub account that owns the repo. No separate credentials. -2. **No additional account.** Brady already has GitHub. ngrok requires a separate signup. -3. **Service mode.** `devtunnel service install` runs as a Windows service — survives reboots, no terminal needed. Perfect for a persistent bot. -4. **Aligns with Squad's GitHub-native philosophy.** Using Microsoft/GitHub infrastructure, not a third-party tunnel provider. -5. **SDK available.** `microsoft/dev-tunnels` on GitHub provides programmatic tunnel management — Squad could create/destroy tunnels automatically. - -### Dev Tunnels Limitations - -1. **Persistence isn't guaranteed forever.** Tunnels may expire after inactivity (documentation is vague on exact timeout). A keepalive/reconnect strategy is needed. -2. **Requires the `devtunnel` CLI installed.** One more dependency in the setup flow. -3. **Less battle-tested for bot hosting than ngrok.** ngrok has years of bot-hosting patterns documented. - -### Recommendation - -**Use Dev Tunnels.** The GitHub-native auth model, service mode, and zero-additional-account requirements align perfectly with Squad. For production, consider deploying to a cloud VM where tunnels aren't needed — but for Brady's "DM my squad from my phone" use case, Dev Tunnels on his dev machine is the right v0.1. - ---- - -## 4. GitHub-Native Alternatives (Before Building a Bot) - -Before we commit to building a Telegram bot, we should check whether existing GitHub surfaces could serve as a "DM" interface. - -### 4a. GitHub Copilot Chat on Mobile - -**What it offers:** Copilot Chat is available on GitHub Mobile. It supports `@agent` mentions for custom agents. - -**Could it work?** -- ✅ Already exists — no build required -- ✅ Supports custom agents (`.github/agents/squad.agent.md`) -- ❌ **Does NOT have the `task` tool on mobile.** Mobile Copilot Chat has a limited tool set. No `powershell`, no `task`, no `read_agent`. Squad's core orchestration wouldn't work. -- ❌ No filesystem access — can't read `.ai-team/` state -- ❌ No repo context — agents can't see the codebase - -**Verdict:** ❌ Not viable. Mobile Copilot Chat is for quick questions, not multi-agent orchestration. - -### 4b. GitHub Actions + Issue Comments as "DM" - -**What it offers:** Create a private repo. Post comments on a designated issue. Each comment triggers a workflow that runs Squad. - -**Could it work?** -- ✅ Fully GitHub-native -- ✅ Works from any device with GitHub access (including mobile) -- ✅ Full CLI environment in the workflow (if Copilot CLI is available) -- ✅ Conversation history preserved in the issue thread -- ⚠️ Latency: 60-120s per response (workflow cold start + execution) -- ❌ Not a DM experience — it's commenting on an issue -- ❌ No push notifications (unless GitHub notification settings are configured) -- ❌ Copilot CLI availability on Actions runners is uncertain - -**Verdict:** ⚠️ Viable as a fallback but the UX doesn't match "DM." It's more like an async command interface. Could be a good v0.0 prototype to validate the concept before building a real bot. - -### 4c. Copilot Extensions as Bridge - -**What it offers:** Register Squad as a Copilot Extension available in all Copilot Chat surfaces. - -**Could it work?** -- ❌ GitHub App-based extensions deprecated (Sept/Nov 2025) -- ⚠️ VS Code extension + MCP server approach is still viable but scoped to VS Code -- ❌ Extensions can't spawn sub-agents or access local filesystem -- ❌ Architectural mismatch (covered in Section 2, Option D) - -**Verdict:** ❌ Not viable for multi-agent orchestration. Extensions are single-purpose tools. - -### 4d. GitHub Mobile + Copilot - -**What it offers:** GitHub Mobile has Copilot Chat integration. - -**Could it work?** -- Same limitations as 4a — limited tool set, no filesystem access, no `task` tool -- ❌ Not viable for the same reasons - -**Verdict:** ❌ Same as 4a. - -### Summary of GitHub-Native Alternatives - -None of the existing GitHub surfaces provide the `task` tool or filesystem access that Squad requires. **We need to build something.** The question is: what's the thinnest possible thing we can build? - ---- - -## 5. The `.ai-team/` State Problem - -Squad's agent memory lives in git. A DM interface needs to read from and write to the repo. - -### State Access Requirements - -| Operation | Frequency | Examples | -|-----------|-----------|---------| -| **Read repo** | Every message | Charters, histories, decisions, routing, casting | -| **Write repo** | Most messages | New files, history updates, decision inbox | -| **Commit** | After agent work | "Squad DM: updated keaton's history" | -| **Push** | After commits | Sync back to remote | - -### Two Architectures - -#### Architecture 1: Local Repo (Dev Tunnel Approach) - -``` -Brady (Telegram) → Telegram API → Dev Tunnel → Bot (local) → Copilot SDK → Local Repo -``` - -- ✅ Repo is already checked out — instant access -- ✅ No clone/checkout overhead -- ✅ Changes visible in Brady's IDE immediately -- ✅ Full filesystem — `grep`, `glob`, `view` all work natively -- ❌ Requires Brady's machine to be running -- ❌ Dev Tunnel must stay alive -- ❌ Only works for one repo at a time (whichever is checked out) - -#### Architecture 2: Cloud Repo (CI/Server Approach) - -``` -Brady (Telegram) → Telegram API → Server/Action → Clone Repo → Copilot SDK/CLI → Commit + Push -``` - -- ✅ Works from anywhere, always available -- ✅ No dependency on Brady's machine -- ❌ Clone overhead per interaction (~5-30s for large repos) -- ❌ Merge conflicts if Brady is also working locally -- ❌ Server costs (VM, Actions minutes) -- ❌ More complex git workflow (fetch, merge, push) - -### Recommendation: Start with Architecture 1 (Local) - -For Brady's stated use case — "keep working with my squad when I'm not at my terminal" — Architecture 1 is simpler and more natural. He has a machine running. The repo is checked out. Dev Tunnel exposes the bot. Messages flow directly to the local environment. - -Architecture 2 is the scale play for when Squad DM is a product feature, not a personal tool. - ---- - -## 6. Recommended Architecture: v0.1 - -``` -┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ -│ Brady's │ │ Telegram │ │ Dev Tunnel │ │ Squad Bot │ -│ Phone │────▶│ API │────▶│ (devtunnels) │────▶│ (local) │ -│ (Telegram) │ │ │ │ │ │ │ -└─────────────┘ └──────────────┘ └──────────────────┘ │ ┌────────┐ │ - │ │Copilot │ │ - │ │ SDK │ │ - │ └───┬────┘ │ - │ │ │ - │ ┌───▼────┐ │ - │ │ Squad │ │ - │ │Coord. │ │ - │ └───┬────┘ │ - │ │ │ - │ ┌───▼────┐ │ - │ │Agents │ │ - │ │(spawn) │ │ - │ └───┬────┘ │ - │ │ │ - │ ┌───▼────┐ │ - │ │ Local │ │ - │ │ Repo │ │ - │ └────────┘ │ - └──────────────┘ -``` - -### Components - -1. **Telegram Bot** (~50 lines Node.js) - - Receives messages via webhook - - Forwards to Squad coordinator via Copilot SDK - - Sends responses back to Telegram - - Library: `telegraf` or `node-telegram-bot-api` - -2. **Copilot SDK Integration** (~200-400 lines) - - Creates coordinator session with `squad.agent.md` as system prompt - - Implements tool handlers: `view`, `edit`, `create`, `grep`, `glob`, `powershell` - - Implements `task` equivalent: spawn new SDK sessions for sub-agents - - Collects results, routes back to coordinator - -3. **Dev Tunnel** (zero code) - - `devtunnel host -p 3000 --allow-anonymous` - - Or installed as service for persistence - -4. **Local Repo Access** (zero code) - - Bot runs in the repo directory - - All file operations are native `fs` calls - -### What We Need to Build - -| Component | Lines | Deps | Risk | -|-----------|-------|------|------| -| Telegram bot wrapper | ~50 | `telegraf` | Low | -| Tool implementations | ~150 | `@github/copilot-sdk` | Medium | -| Agent spawning shim | ~200 | `@github/copilot-sdk` | **High** | -| Dev Tunnel setup script | ~20 | `devtunnel` CLI | Low | -| **Total** | **~420** | **2 npm + 1 CLI** | **Medium-High** | - -### The Risk - -The agent spawning shim is the only high-risk component. If the Copilot SDK supports nested sessions with tool definitions (i.e., we can spawn an "agent" that has its own tools and runs independently), this is straightforward. If not, we need to implement our own mini-orchestrator: create an API call per agent, inject tools, run to completion, collect results. This is doable but increases the line count to ~600-800 and adds complexity. - -**Recommendation:** Before writing any code, spike the SDK to verify: -1. Can we create a session with custom tools? -2. Can a tool handler create another session? (This is the `task` equivalent) -3. What's the latency for a session.sendAndWait() call? - ---- - -## 7. Cost and Complexity Matrix - -| Approach | Build Cost | Infra Cost | Latency | UX Quality | Independence | -|----------|-----------|------------|---------|------------|--------------| -| **Copilot SDK + Telegram + Dev Tunnel** | Medium (~420 LOC) | $0 (Copilot sub) | 10-30s | ⭐⭐⭐⭐ | ✅ | -| LLM APIs + Telegram + Dev Tunnel | High (~1200 LOC) | $0.50-2/msg | 10-30s | ⭐⭐⭐⭐ | ⚠️ | -| GitHub Actions + Issue Comments | Low (~50 LOC) | Actions mins | 60-120s | ⭐⭐ | ✅ | -| Copilot Extension | Very High | $0 | 5-15s | ⭐⭐⭐ | ❌ | - ---- - -## 8. Open Questions for Keaton - -1. **Scope:** Is this a Brady-only personal tool, or a Squad product feature? This determines whether we optimize for one user's machine or for distributed deployment. - -2. **Conversation persistence:** Should DM conversations be logged in `.ai-team/`? If so, where? (Propose: `.ai-team/dm-log/` with timestamped session files.) - -3. **Multi-repo:** Brady said "my team(s)" — plural. Does the bot need to switch between repos? If so, the local architecture gets more complex (multiple checkouts, routing by repo). - -4. **Notification direction:** Brady → Squad is clear. Should Squad → Brady also work? (e.g., "Scribe finished merging decisions" as a push notification.) This is easy with Telegram's `sendMessage` API. - -5. **Auth:** Who can message the bot? Just Brady? Anyone with the bot's Telegram handle? For v0.1, hardcode Brady's Telegram user ID. - ---- - -## 9. Phasing Recommendation - -### v0.0: Proof of Concept (1 day) -- GitHub Actions + issue comment trigger -- Validate that Squad can run in CI and respond to messages -- No Telegram, no Dev Tunnel, no SDK -- Purpose: prove the concept works before investing in infrastructure - -### v0.1: Brady's Personal Bot (2-3 days) -- Copilot SDK spike — verify agent spawning works -- Telegram bot with webhook -- Dev Tunnel for local exposure -- Single repo, single user, local execution -- `npx create-squad dm` to set up - -### v0.2: Resilience (1-2 days) -- Dev Tunnel auto-reconnect -- Conversation logging to `.ai-team/dm-log/` -- Error handling and retry logic -- Push notifications (Squad → Brady) - -### v0.3: Multi-repo + Cloud (3-5 days) -- Repo selection via Telegram commands (`/repo bradygaster/squad`) -- Cloud deployment option (Azure, Railway, etc.) -- Architecture 2 support (clone-based) -- Multiple provider support (Discord, Slack) if desired - ---- - -## 10. What I Need to Verify - -Before this proposal can move to implementation: - -1. **Copilot SDK `task` equivalence.** Install `@github/copilot-sdk`, create a session, try to spawn a nested session from a tool handler. This is the go/no-go gate. - -2. **Dev Tunnel persistence.** Run `devtunnel service install`, leave it for 24h, verify the tunnel is still alive and the URL is stable. - -3. **Telegram webhook + Dev Tunnel.** Set up a minimal Telegram bot, point the webhook at a Dev Tunnel URL, verify messages flow end-to-end. - -If gate 1 fails (SDK can't do nested sessions), fall back to Option C (GitHub Actions) for v0.1 and revisit when the SDK matures. - ---- - -## Appendix A: Telegram Bot Setup (Reference) - -```javascript -// Minimal Telegram bot with webhook (telegraf) -const { Telegraf } = require('telegraf'); -const bot = new Telegraf(process.env.BOT_TOKEN); - -bot.on('text', async (ctx) => { - const message = ctx.message.text; - const userId = ctx.from.id; - - // Auth check (Brady only in v0.1) - if (userId !== parseInt(process.env.BRADY_TELEGRAM_ID)) { - return ctx.reply("This squad doesn't know you."); - } - - // Forward to Squad coordinator via Copilot SDK - const response = await runSquadCoordinator(message); - await ctx.reply(response); -}); - -// Webhook mode (not polling) -bot.launch({ webhook: { domain: process.env.TUNNEL_URL, port: 3000 } }); -``` - -## Appendix B: Dev Tunnel Setup (Reference) - -```powershell -# One-time setup -winget install Microsoft.devtunnel -devtunnel user login -g - -# Start tunnel (interactive) -devtunnel host -p 3000 --allow-anonymous - -# Install as service (persistent) -devtunnel service install --port 3000 --allow-anonymous - -# Get tunnel URL -devtunnel list -``` - -## Appendix C: GitHub Actions Fallback (Reference) - -```yaml -# .github/workflows/squad-dm.yml -name: Squad DM -on: - issue_comment: - types: [created] - -jobs: - squad: - if: startsWith(github.event.comment.body, '/squad ') - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: Extract message - id: msg - run: echo "message=${BODY#/squad }" >> $GITHUB_OUTPUT - env: - BODY: ${{ github.event.comment.body }} - - name: Run Squad (TBD - Copilot CLI in Actions) - run: echo "Would run Squad with: ${{ steps.msg.outputs.message }}" - - name: Reply - uses: actions/github-script@v7 - with: - script: | - github.rest.issues.createComment({ - issue_number: context.issue.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: '🤖 Squad response: (TBD)' - }) -``` diff --git a/team-docs/proposals/017-squad-dm-messaging-interface.md b/team-docs/proposals/017-squad-dm-messaging-interface.md deleted file mode 100644 index 150065c41..000000000 --- a/team-docs/proposals/017-squad-dm-messaging-interface.md +++ /dev/null @@ -1,664 +0,0 @@ -# Proposal 017: Squad DM — Direct Messaging Interface for Squad Teams - -**Status:** Deferred — Squad DM deferred to Horizon per Proposal 019 -**Authored by:** Keaton (Lead) -**Date:** 2026-02-08 -**Requested by:** bradygaster - ---- - -## Summary - -Let users talk to their Squad from anywhere — phone, tablet, couch, commute — through messaging platforms they already use. Telegram first, then Slack, Discord, and beyond. The team's memory stays in git. The messaging layer is just a new front door. - -This isn't "connect Squad to a chatbot." This is: Brady texts Keaton on Telegram, Keaton answers as Keaton, with full access to the project's `.ai-team/` state, decisions, and history. The intimacy of YOUR team, not a generic assistant. MOLTS proved the model — multi-channel AI that lives where you already chat. Squad DM brings that same energy, but with persistent team identity and git-backed memory. - ---- - -## Problem - -Today, Squad only works inside the Copilot CLI terminal. You need to be at your desk, in VS Code or a terminal, with `copilot` running. That's fine for deep work — but Brady (and every user like him) doesn't stop thinking about their project when they close their laptop. - -**The friction points:** - -1. **Location-locked.** Squad only exists inside a terminal session. No access from phone, tablet, or any device without Copilot CLI. -2. **Session-bound.** When you close the terminal, your Squad goes dark. No way to ask "what's the status of X?" without reopening everything. -3. **Single entry point.** The only way to interact with Squad is through the Copilot agent framework's `task` tool. There's no API, no webhook, no alternative interface. -4. **Async gap.** Software development is increasingly async. Brady might think of something at dinner, want to tell Fenster to handle it, and get a confirmation. Right now, that thought becomes a sticky note that gets lost. - -**What Brady actually said:** *"I love working with y'all so much I need you to work up a proposal so I can work with you via some sort of direct messaging thing YES LIKE MOLTS but just my team(s)."* - -The key phrase: "just my team(s)." Not a generic AI. Not ChatGPT in a Telegram wrapper. His Squad. Keaton, Verbal, McManus, Fenster, Hockney. The characters he knows, with the memory of how they've worked together. - -### The MOLTS Reference - -MOLTS (formerly Moltbot/Clawdbot, now OpenClaw) is an open-source, self-hosted personal AI assistant that lives inside your messaging platforms — WhatsApp, Telegram, Discord, Slack, Signal, iMessage, and more. It's proactive (initiates tasks, sends reminders), persistent (remembers preferences and context), and local-first (runs on your own machine). It went viral because it proved that AI assistants are dramatically more useful when they meet you where you already chat, instead of forcing you into a new interface. - -Brady's instinct is exactly right: Squad should work the same way. But Squad has something MOLTS doesn't — **team identity**. You're not chatting with "an AI." You're chatting with Keaton, who has opinions about your architecture, or Fenster, who remembers the bug you filed last week. That's the magic. - ---- - -## Solution - -### Architecture: Option D — Hybrid (Recommended) - -After evaluating all four options, the hybrid approach wins because it maximizes flexibility while keeping the orchestration core simple. - -#### Options Evaluated - -| Option | Description | Pros | Cons | Verdict | -|--------|-------------|------|------|---------| -| **A: Bot per platform** | Telegram bot, Slack bot, etc. Each has its own connection to a runner with repo access. | Simple per-platform. Platform-native UX. | Duplicated orchestration logic. Each bot reimplements routing, auth, state access. N platforms = N implementations. | ❌ Doesn't scale. | -| **B: Webhook relay** | Lightweight webhook receiver translates platform messages into Squad agent spawns. | Single orchestration layer. Platform adapters are thin. | Needs a running server to receive webhooks. Where does it run? | ⚠️ Right idea, needs a host. | -| **C: GitHub-native** | Use GitHub Issues, Discussions, or webhook flows as the messaging bridge. | Stays in GitHub ecosystem. No external services. Auth is built-in. | UX is terrible for casual messaging. Nobody wants to create a GitHub Issue to ask Keaton a question. Latency is high. Not real-time. | ❌ Wrong UX for the use case. | -| **D: Hybrid** | Multiple thin platform adapters → single orchestration backend → Copilot CLI or GitHub Actions for execution. | Best of all worlds. Add platforms cheaply. One execution engine. | More moving parts than a single bot. | ✅ Recommended. | - -**Why GitHub-native (Option C) fails for DMs but succeeds as a fallback:** GitHub Issues/Discussions could serve as an *asynchronous* channel — "file an issue, Squad picks it up" — but it's not the conversational experience Brady wants. However, it's a great P2 addition as a "works without any setup" channel. - -#### The Hybrid Architecture - -``` -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ Telegram │ │ Slack │ │ Discord │ -│ Bot │ │ Bot │ │ Bot │ -│ (adapter) │ │ (adapter) │ │ (adapter) │ -└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ - │ │ │ - └────────┬────────┴────────┬────────┘ - │ │ - ┌──────▼──────────────────▼──────┐ - │ Squad DM Gateway │ - │ │ - │ - Message normalization │ - │ - Auth / user verification │ - │ - Agent routing (parse @name) │ - │ - Session management │ - │ - Response formatting │ - └──────────────┬─────────────────┘ - │ - ┌──────────────▼─────────────────┐ - │ Execution Engine │ - │ │ - │ Option 1: Copilot CLI spawn │ - │ Option 2: GitHub Actions │ - │ Option 3: Direct LLM call │ - │ with agent charter + context│ - └──────────────┬─────────────────┘ - │ - ┌──────────────▼─────────────────┐ - │ Git-backed State │ - │ │ - │ .ai-team/agents/*/history.md │ - │ .ai-team/decisions.md │ - │ .ai-team/decisions/inbox/ │ - │ .ai-team/routing.md │ - │ .ai-team/casting/registry.json│ - └────────────────────────────────┘ -``` - -#### Component Breakdown - -**1. Platform Adapters (thin)** - -Each adapter handles exactly one concern: translating platform-specific messages into a normalized format and sending responses back. An adapter is ~100-200 lines. It knows nothing about Squad, agents, or git. - -```typescript -interface NormalizedMessage { - platform: "telegram" | "slack" | "discord"; - user_id: string; // platform-specific user ID - display_name: string; - text: string; // raw message text - reply_to?: string; // if replying to a previous message - thread_id?: string; // for threaded platforms (Slack) - timestamp: string; - platform_metadata: object; // platform-specific data for response routing -} - -interface NormalizedResponse { - text: string; - agent_name: string; // "Keaton", "Fenster", etc. - attachments?: Attachment[]; // code blocks, file diffs, etc. -} -``` - -**2. Squad DM Gateway (the brain)** - -This is the orchestration layer. It receives normalized messages and: - -1. **Authenticates** the user (see Trust Model below). -2. **Routes** to the right agent. Parses `@Keaton`, `@Fenster`, or uses routing.md heuristics if no agent is mentioned. -3. **Builds context** by reading the repo's `.ai-team/` directory — the agent's charter, history, decisions.md, and relevant project state. -4. **Spawns execution** via the chosen execution engine. -5. **Formats and returns** the response through the originating platform adapter. - -The gateway runs as a Node.js process on the user's machine (or a server with repo access). It needs: -- Read/write access to the git repo (for `.ai-team/` state) -- Network access to receive webhooks from platform adapters -- Credentials for the chosen execution engine - -**3. Execution Engine (the hard problem)** - -This is where Squad DM diverges from the terminal experience. In Copilot CLI, agents are spawned via the `task` tool — which provides a sandboxed environment with file access, shell access, and other tools. Squad DM can't assume that tool exists. Three execution strategies, used depending on the request type: - -| Strategy | When to use | Capabilities | Limitations | -|----------|-------------|-------------|-------------| -| **Direct LLM** | Status queries, opinions, advice, reviews | Full agent personality, reads `.ai-team/` state, fast | No file writes, no shell access, no tool use | -| **Copilot CLI** | Code changes, file operations, complex tasks | Full tool access, same as terminal experience | Requires Copilot CLI installed on gateway host, slower | -| **GitHub Actions** | Async tasks, CI-triggered work, scheduled jobs | Runs in GitHub infrastructure, no local machine needed | Slowest, limited interactivity, costs Actions minutes | - -**The tiered approach:** - -``` -User message → Gateway classifies intent: - - "Keaton, what's the status of export?" - → QUERY tier → Direct LLM (fast, no tools needed) - - "Fenster, add error handling to the upgrade command" - → TASK tier → Copilot CLI spawn (needs file access) - - "Hockney, run the full test suite and report" - → CI tier → GitHub Actions dispatch (needs runner) -``` - -This maps directly to the tiered response modes from Proposal 007/009. Status queries don't need a full agent spawn. Code changes do. - -### Dev Tunnels Integration - -Brady specifically asked: if direct connections are needed, use **VS Code Dev Tunnels** instead of ngrok. - -Dev Tunnels are relevant in two scenarios: - -**Scenario 1: Gateway runs locally, needs webhook ingress.** - -Telegram/Slack/Discord send webhooks to a URL. If the gateway runs on Brady's machine, that URL needs to reach localhost. Dev Tunnels provides this. - -```bash -# Start the gateway -squad-dm start --port 3847 - -# In another terminal, expose it -devtunnel host -p 3847 --allow-anonymous -# → https://abc123.devtunnels.ms - -# Configure Telegram bot webhook to point to: -# https://abc123.devtunnels.ms/webhook/telegram -``` - -**Why Dev Tunnels over ngrok:** -- **Microsoft ecosystem.** Auth via Microsoft/GitHub account (no separate ngrok account). -- **Free tier is generous.** Persistent URLs, multi-port, no bandwidth caps for dev use. -- **Enterprise-ready.** Org-level access controls via Entra ID. Matters when Squad goes to teams. -- **Already installed.** Many VS Code users already have it. `winget install Microsoft.devtunnel` for the rest. - -**Scenario 2: Persistent tunnel for always-on DM access.** - -```bash -# Create a named, persistent tunnel -devtunnel create --name squad-dm --ports 3847 -devtunnel host --tunnel squad-dm -# → https://squad-dm-bradygaster.devtunnels.ms (stable URL) -``` - -This gives Brady a stable webhook URL he can set-and-forget in his Telegram bot config. The URL survives restarts (as long as the tunnel name is reused). For true always-on, the gateway + tunnel run as a system service or in a container. - -**Scenario 3: No tunnel needed.** - -If the gateway runs on a cloud VM, VPS, or GitHub Codespace with a public IP, Dev Tunnels aren't needed. The gateway just binds to `0.0.0.0:3847` and the platform webhooks hit it directly. This is the simplest production setup but requires infrastructure Brady might not want to manage for a personal tool. - ---- - -## What "Working with Squad" Means in a DM Context - -### Interaction Patterns - -**Pattern 1: Status query (Direct LLM tier)** - -``` -Brady → Telegram: - @Keaton what's the status of the export feature? - -Keaton → Telegram: - Export (Proposal 008) is approved but not yet in progress. - Fenster estimated 11-14h for full implementation. Sprint plan - (009) has it in Sprint 2, blocked on history split. - - The history split itself is ~1h of template work. Want me to - prioritize it? -``` - -How it works: Gateway reads `decisions.md`, agent histories, and proposal files. Builds a context window with Keaton's charter + relevant project state. Direct LLM call with Keaton's personality. No tools needed. - -**Pattern 2: Code task (Copilot CLI tier)** - -``` -Brady → Telegram: - @Fenster add error handling to the upgrade command in index.js - -Fenster → Telegram: - On it. I'll wrap the file operations in try/catch and add - user-friendly error messages for common failures. - - [5 minutes later] - -Fenster → Telegram: - ✅ Done. Committed to branch `fenster/upgrade-error-handling`: - - Added try/catch around copyRecursive and fs operations - - Specific error messages for ENOENT, EACCES, ENOSPC - - Graceful exit with cleanup on failure - - 3 files changed. Want me to open a PR? -``` - -How it works: Gateway spawns a Copilot CLI session with Fenster's charter as context. The CLI has full file access to the repo. Fenster works, commits, and the gateway relays the result back to Telegram. - -**Pattern 3: Team-wide question (Coordinator routing)** - -``` -Brady → Telegram: - What should we prioritize this week? - -Squad → Telegram: - Routing to Keaton (Lead) for prioritization... - -Keaton → Telegram: - Based on the sprint plan and current state: - - 1. 🔴 P015 silent success fix (Sprint 1, Day 1 — trust before features) - 2. 🟡 Forwardability (Sprint 1 — upgrade path for existing users) - 3. 🟡 History split (Sprint 2 prerequisite) - - P015 is unblocked and zero-risk. Should I have Fenster start? -``` - -How it works: No `@agent` prefix → Gateway uses routing.md to determine who handles it. Prioritization questions route to Keaton. - -**Pattern 4: Multi-agent coordination** - -``` -Brady → Telegram: - I need a new proposal for webhook support. Keaton should - architect it, Verbal should review the prompts. - -Squad → Telegram: - Spawning Keaton for architecture, will route to Verbal for - prompt review after. - -Keaton → Telegram: - [Proposal draft...] - - Routing to Verbal for prompt review. - -Verbal → Telegram: - [Review comments...] -``` - -How it works: Gateway parses multi-agent intent, spawns sequentially with handoff (same as coordinator chaining in terminal mode). Each agent's response is relayed as it completes. - -### What's Different from Terminal Mode - -| Capability | Terminal (today) | DM (proposed) | -|-----------|-----------------|---------------| -| Agent spawning | `task` tool (Copilot CLI) | Gateway-managed (tiered) | -| File access | Full (local filesystem) | Via gateway host's filesystem | -| Tool use | All Copilot CLI tools | Copilot CLI tools (task tier only) | -| Interactivity | Real-time back-and-forth | Async message/response | -| Context window | 128K+ tokens | Same (depends on LLM provider) | -| Parallel fan-out | Multiple `task` calls | Sequential or queued (P1) | -| Coordinator | squad.agent.md in Copilot | Gateway reimplements routing | - -**The key architectural difference:** In terminal mode, the coordinator (squad.agent.md) runs inside Copilot and uses the `task` tool to spawn agents. In DM mode, the Gateway IS the coordinator. It reads routing.md and agent charters, but the spawning mechanism is different — it either calls an LLM API directly or invokes Copilot CLI as a subprocess. - -This means the coordinator logic currently embedded in `squad.agent.md` (~32KB) needs to be partially extracted into the Gateway. Not duplicated — extracted. The routing rules, agent selection heuristics, and parallel fan-out decisions should become a shared module that both `squad.agent.md` and the Gateway can reference. - ---- - -## Trust and Security Model - -### Authentication - -**Who can message the Squad?** - -Only authorized users. For MVP, this means Brady and nobody else. - -```json -// .ai-team/dm-config.json -{ - "dm_version": "1.0", - "authorized_users": [ - { - "github_username": "bradygaster", - "platforms": { - "telegram": { "user_id": "123456789" }, - "slack": { "user_id": "U0XXXXXXX" } - } - } - ], - "gateway": { - "port": 3847, - "execution_tiers": { - "query": "direct_llm", - "task": "copilot_cli", - "ci": "github_actions" - } - } -} -``` - -**Auth flow per platform:** - -1. **Telegram:** Bot uses a secret token. First message triggers a verification flow: Gateway sends a challenge code to verify the Telegram user_id matches the config. One-time setup. -2. **Slack:** OAuth2 flow during bot installation. Slack user ID mapped to GitHub username in config. -3. **Discord:** Similar to Telegram. Bot token + user ID verification. - -**Auth escalation for teams (P3):** - -When multiple people share a Squad (org teams), auth maps platform identities to GitHub usernames. Permissions follow GitHub repo permissions — if you can push to the repo, you can message the Squad. Read-only contributors can query but not trigger tasks. - -### Repo Access - -The Gateway needs access to the git repository. Three models: - -| Model | Security | Setup | Best for | -|-------|----------|-------|----------| -| **Local clone** | Highest — repo never leaves the machine | Gateway runs where the repo is | Solo developers (Brady) | -| **SSH key** | High — standard git auth | Gateway has deploy key for the repo | Small teams | -| **GitHub App** | Medium — token-scoped | Install GitHub App with repo access | Organizations | - -For MVP, local clone. The Gateway runs on Brady's machine (or a machine where the repo is cloned). It reads `.ai-team/` directly from the filesystem. Writes (decision inbox, history appends) go to the local clone. Brady pushes when ready. - -### Execution Security - -- **Direct LLM tier:** Read-only access to `.ai-team/`. Cannot modify files. Safe. -- **Copilot CLI tier:** Full file access. Same security model as running Copilot locally. The Gateway spawns Copilot in the repo directory with the agent's charter. Changes are committed to a branch (never main directly). -- **GitHub Actions tier:** Runs in GitHub's infrastructure with the repo's configured permissions. Standard Actions security model. - -**Rate limiting:** Gateway enforces per-user rate limits to prevent abuse if a bot token is leaked. Default: 30 messages/hour for queries, 10/hour for tasks. - -### Secret Management - -- Platform bot tokens stored in `.env` (gitignored) or system keychain. -- LLM API keys (for direct LLM tier) stored similarly. -- Dev Tunnel auth handled by `devtunnel user login` (cached credential, not stored in repo). -- `.ai-team/dm-config.json` is committed (contains user mappings, not secrets). - ---- - -## Implementation Phases - -### Phase 1: MVP — Telegram + Direct LLM (2-3 days) - -**Goal:** Brady can text his Squad from Telegram and get real answers with full agent personality. - -**Scope:** -- Telegram bot adapter (node-telegram-bot-api or grammy) -- Gateway with message normalization and agent routing -- Direct LLM execution only (queries, opinions, status — no code changes) -- Reads `.ai-team/` from local filesystem for context -- Single authorized user (Brady) -- Dev Tunnel for webhook ingress - -**What it looks like:** - -```bash -# Setup (one-time) -npx create-squad dm init --telegram -# Prompts for Telegram bot token (from @BotFather) -# Writes .ai-team/dm-config.json -# Writes .env with TELEGRAM_BOT_TOKEN and LLM_API_KEY - -# Start -npx create-squad dm start -# → Gateway listening on port 3847 -# → Telegram webhook configured via Dev Tunnel -# → Connected to repo: /path/to/project - -# In Telegram: -# Brady: @Keaton what did we decide about forwardability? -# Keaton: [responds with full context from decisions.md] -``` - -**Implementation:** -- New file: `dm/gateway.js` — core orchestration (~300 lines) -- New file: `dm/adapters/telegram.js` — Telegram adapter (~150 lines) -- New file: `dm/context.js` — reads `.ai-team/` and builds agent context (~200 lines) -- New file: `dm/auth.js` — user verification (~100 lines) -- Modified: `index.js` — adds `dm` subcommand routing -- New: `.ai-team/dm-config.json` schema - -**Not in Phase 1:** Code changes, file writes, Copilot CLI integration, multi-user, Slack/Discord. - -**Why this is the right MVP:** It validates the core thesis — can Brady have a real conversation with his agents from his phone? If the personality feels right and the context is accurate, everything else is execution. If it doesn't feel like talking to Keaton, more features won't fix it. - -### Phase 2: Code Execution + Multi-Platform (1-2 weeks) - -**Goal:** Brady can request actual code changes from Telegram, and the same system works on Slack and Discord. - -**Scope:** -- Copilot CLI execution tier (spawn Copilot with agent charter for file operations) -- GitHub Actions execution tier (dispatch workflows for CI tasks) -- Slack adapter -- Discord adapter -- Branch-based commits (never write to main from DM) -- Response threading (long task responses don't flood the chat) -- Message queuing (multiple messages don't clobber each other) - -**Key challenge:** Copilot CLI spawning from the gateway. The gateway needs to: -1. Build a prompt that includes the agent's charter, relevant history, and the user's message. -2. Invoke `copilot` (or `gh copilot`) with that prompt in the repo directory. -3. Capture the output and relay it back to the platform. -4. Handle timeouts (some tasks take minutes). - -```bash -# Conceptual: gateway spawns Copilot for a task -copilot --agent squad --message "Fenster, add error handling to upgrade" \ - --repo /path/to/project \ - --non-interactive -``` - -If Copilot CLI doesn't support non-interactive invocation (current limitation), the fallback is direct LLM API calls with tool definitions that mirror Copilot's tool set (file read/write, shell execution). This is more work but gives full control. - -### Phase 3: Full Parity with Terminal Experience (2-4 weeks) - -**Goal:** Everything you can do in the terminal, you can do from a DM. Plus things you can't do in the terminal. - -**Scope:** -- Parallel agent fan-out from DM (multiple agents working simultaneously) -- Coordinator protocol (gateway fully implements squad.agent.md routing logic) -- Proposal workflow from DM ("write a proposal for X" → proposal created and committed) -- Review workflow from DM ("review Fenster's PR" → reviewer agent spawned) -- Proactive notifications (agent finishes background task → DM notification) -- Always-on mode (gateway as system service, persistent Dev Tunnel) -- Multi-repo support (one gateway, multiple Squad projects) -- Team access (multiple authorized users per Squad) - -**New capabilities beyond terminal:** -- **Proactive DMs:** Agent completes a CI run → sends result to Telegram without being asked. -- **Scheduled check-ins:** "Every morning at 9am, Keaton summarizes what's in progress." -- **Cross-device handoff:** Start a conversation on phone, continue in terminal seamlessly. -- **Notification preferences:** "Only DM me for failures, not successes." - ---- - -## Data Structures - -### dm-config.json - -```json -{ - "dm_version": "1.0", - "squad_project": "bradygaster/squad", - "gateway": { - "port": 3847, - "tunnel": { - "provider": "devtunnel", - "name": "squad-dm", - "auto_start": true - }, - "execution": { - "query_tier": "direct_llm", - "task_tier": "copilot_cli", - "ci_tier": "github_actions" - }, - "rate_limits": { - "queries_per_hour": 30, - "tasks_per_hour": 10 - } - }, - "authorized_users": [ - { - "github": "bradygaster", - "telegram_id": "123456789" - } - ], - "platforms": { - "telegram": { - "enabled": true, - "bot_username": "SquadDMBot" - } - }, - "llm": { - "provider": "openai", - "model": "gpt-4o" - } -} -``` - -### Message Flow Schema - -```typescript -interface GatewayMessage { - id: string; - timestamp: string; - source: NormalizedMessage; - parsed: { - target_agent: string | null; // "@Keaton" → "keaton", null → coordinator routes - intent: "query" | "task" | "ci"; - message_body: string; - }; - execution: { - tier: "direct_llm" | "copilot_cli" | "github_actions"; - context: AgentContext; - status: "pending" | "executing" | "completed" | "failed"; - response?: NormalizedResponse; - duration_ms?: number; - }; - auth: { - github_username: string; - verified: boolean; - }; -} - -interface AgentContext { - agent_name: string; - charter: string; // from .ai-team/agents/{name}/charter.md - history: string; // from .ai-team/agents/{name}/history.md - decisions: string; // from .ai-team/decisions.md (truncated to recent) - routing: string; // from .ai-team/routing.md - project_description: string; -} -``` - ---- - -## Trade-offs - -**What we gain:** -- Squad becomes accessible from anywhere — phone, tablet, another computer, on the go -- The "MY team" feeling extends beyond the terminal. Chatting with Keaton on Telegram is more intimate than typing in a CLI -- Opens a fundamentally new interaction modality. DM-first users may never use the terminal at all -- Proactive notifications (P3) make Squad feel alive — it reaches out to you, not just responds -- Aligns with MOLTS/Moltbot momentum — multi-channel AI assistants are what users expect - -**What we give up:** -- Complexity. The gateway is a new component to build and maintain. Platform adapters need updating when APIs change -- LLM costs. Direct LLM tier requires API keys and costs money per query. Copilot CLI tier uses existing Copilot subscription -- Security surface. A running gateway with platform bot tokens and repo access is a target. Must be locked down -- Partial parity. Phase 1 can only answer questions, not change code. Users will immediately want Phase 2 - -**What gets harder:** -- Coordinator logic duplication. `squad.agent.md` and the Gateway both need routing logic. Drift between them is a risk. Long-term, extract routing into a shared format -- Testing. DM interactions are harder to test than CLI interactions. Need mock platform adapters and recorded message flows -- Context window management. Reading all of `.ai-team/` for every message is expensive. Need smart truncation — recent decisions only, relevant history sections only -- State consistency. Gateway reads/writes to local git. If Brady also has Copilot open in the terminal, they might race on `.ai-team/` state. Need file-level locking or accept eventual consistency - ---- - -## Alternatives Considered - -### Alternative 1: GitHub Issues/Discussions as the only interface - -**What:** Brady creates a GitHub Issue titled "Keaton: what's the status of export?" A GitHub Action picks it up, spawns the agent, posts the response as a comment. - -**Why not for DM:** The UX is wrong. Creating an Issue is 10x more friction than sending a Telegram message. Issues are for tracking, not chatting. The latency (Actions spin-up) makes it feel dead. - -**Why it's still valuable:** As a P2 fallback channel for teams that can't run a gateway. Zero infrastructure needed. Could be the "works everywhere" baseline while Telegram/Slack are the "works great" options. - -### Alternative 2: Slack-only (skip Telegram) - -**What:** Build exclusively for Slack, which has the richest bot API, threads, and enterprise adoption. - -**Why not:** Brady specifically asked for Telegram. Slack is great for teams but overkill for a solo developer chatting with their Squad. Telegram is simpler (no workspace needed), has a better mobile experience, and the bot API is straightforward. Slack is the right P2 target. - -### Alternative 3: Custom mobile app - -**What:** Build a Squad DM iOS/Android app. - -**Why not:** Massive scope increase. App store reviews, platform maintenance, push notifications, offline mode. A messaging bot achieves 90% of the value at 10% of the cost. Maybe v3 if Squad becomes a product company. - -### Alternative 4: SMS/iMessage via Twilio - -**What:** Text your Squad from any phone. No app install needed. - -**Why not for P1:** Twilio costs money per message. SMS has length limits. No rich formatting (code blocks, diffs). But it's a compelling P3 add-on for true "any device" access. - -### Alternative 5: Email interface - -**What:** Email keaton@squad.bradygaster.dev, get a response. - -**Why not:** Email is async and slow. The DM experience should feel conversational, not like filing a support ticket. But again — interesting P3 channel for organizations that live in email. - -### Alternative 6: Run everything through GitHub Actions - -**What:** No gateway at all. Platform webhooks trigger GitHub Actions directly. Actions run Copilot and post responses. - -**Why not:** Actions have cold-start latency (15-45 seconds). For a "what's the status?" question, that's unacceptable. Actions minutes cost money. And you lose the local-first filesystem access that makes Squad's memory model work. Good for CI-tier tasks, wrong for conversational use. - ---- - -## Success Criteria - -1. **The Telegram test:** Brady texts "@Keaton what did we decide about forwardability?" from his phone and gets a response that sounds like Keaton, references the actual decision from decisions.md, and arrives within 10 seconds. - -2. **Agent personality preservation:** Responses via DM are indistinguishable in voice and personality from responses in the terminal. Keaton is opinionated. Fenster is precise. McManus is polished. The platform doesn't dilute the character. - -3. **Context accuracy:** DM responses reference real project state — actual proposals, actual decisions, actual history. No hallucinated project details. - -4. **Auth lockdown:** Unauthorized Telegram users who discover the bot get no response. No project information leaks through the messaging platform. - -5. **Dev Tunnel reliability:** Gateway starts, tunnel connects, webhook receives messages — all within 30 seconds of `squad-dm start`. Tunnel survives sleep/wake cycles on Brady's laptop. - -6. **Phase 1 → Phase 2 upgrade path:** Adding Copilot CLI execution tier doesn't require rewriting the gateway. The tiered architecture is real, not aspirational. - ---- - -## Open Questions - -1. **LLM provider for Direct LLM tier:** Copilot CLI uses GitHub's model access. The gateway's direct LLM tier needs its own model access. Options: OpenAI API key, Azure OpenAI, Anthropic, or — ideally — GitHub Models (keeps it in ecosystem). Does GitHub Models have a programmatic API suitable for this? - -2. **Copilot CLI non-interactive mode:** Can `copilot` / `gh copilot` be invoked programmatically with a message and return a response? If not, Phase 2 needs to either contribute that feature upstream or use direct LLM calls with custom tool definitions. - -3. **Gateway hosting for always-on:** Phase 1 runs locally. For always-on DM access, the gateway needs to run somewhere persistent. Options: home server, VPS, GitHub Codespace (expensive for always-on), Docker container on a NAS. What's Brady's preferred hosting model? - -4. **Multi-repo gateway:** Should one gateway serve multiple Squad projects? If Brady has 5 repos with Squads, does he run 5 gateways or 1 gateway that routes to the right repo? The DM UX would need a way to specify which project: "@Keaton [squad] what's the status?" vs separate Telegram bots per project. - -5. **Message history:** Should DM conversations be persisted in `.ai-team/`? They're a form of project interaction that might contain decisions or preferences. But they could also be noise. Proposal: persist DM logs to `.ai-team/dm-log/` with same rotation policy as orchestration-log. - -6. **Relationship to Proposal 008 (Portable Squads):** If a Squad is exported and imported into a new project, does the DM config travel? The bot token doesn't (it's a secret), but the gateway configuration and user mappings might. Should `dm-config.json` be in the export manifest? - ---- - -**Review requested from:** Fenster (gateway implementation feasibility), Kujan (platform integration, Copilot CLI invocation), Verbal (agent personality preservation in DM context), McManus (DM UX and messaging), bradygaster (vision alignment — is this what you meant?) -**Approved by:** [Pending] -**Implemented:** [Pending] -**Retrospective:** [Pending] diff --git a/team-docs/proposals/018-wave-execution-plan.md b/team-docs/proposals/018-wave-execution-plan.md deleted file mode 100644 index d2dcaffb7..000000000 --- a/team-docs/proposals/018-wave-execution-plan.md +++ /dev/null @@ -1,422 +0,0 @@ -# Proposal 018: Wave-Based Execution Plan (Quality → Experience) - -**Status:** Superseded — by Proposal 019 -**Authored by:** Keaton (Lead) -**Date:** 2026-02-09 -**Requested by:** bradygaster — *"i'd like a priority-based approach - quality then experience - for our next few waves of work"* -**Supersedes:** Proposal 009 (v1 Sprint Plan) — sprint structure replaced with wave structure. Feature set and architecture decisions from 009 remain valid. - ---- - -## The Principle - -Brady's directive is clear: **quality first, then experience.** Not quality OR experience. Not quality balanced with experience. Quality FIRST. Because if it breaks, nothing else matters. - -This changes the execution model. Proposal 009 organized work by capability (fast → yours → smart). This plan organizes by trust. Wave 1 makes Squad trustworthy. Wave 2 makes it delightful. Wave 3 makes it magical. - -The ordering principle is compound: every quality investment in Wave 1 makes Wave 2 safer to ship. Every experience investment in Wave 2 makes Wave 3 more impactful. Nothing ships that doesn't earn its place. - ---- - -## What's Already Shipped - -Before planning what's next, here's the ledger of what's done: - -| Item | Status | Evidence | -|------|--------|----------| -| Silent success bug mitigations (P015) | ✅ Shipped | 3 mitigations in squad.agent.md | -| Upgrade subcommand (`npx create-squad upgrade`) | ✅ Shipped | In index.js, lines 49-65 | -| Test suite (12 tests, 3 suites) | ✅ Shipped | test/index.test.js, all passing | -| Inbox-driven Scribe spawn | ✅ Shipped | In squad.agent.md | -| Scribe history.md created | ✅ Shipped | .ai-team/agents/scribe/ | -| decisions.md cleanup | ✅ Shipped | Headings, line endings fixed | -| First orchestration log entries | ✅ Shipped | orchestration-log/ | - -**Current product surface:** 88-line index.js, zero dependencies, 12 passing tests, upgrade command, init with idempotency, `--version`, `--help`. Solid foundation. Not bulletproof yet. - ---- - -## Wave 1: Quality — "Make It Trustworthy" - -**Duration:** ~3-4 days -**Principle:** If a user runs `npx create-squad` and something goes wrong, they never come back. Wave 1 is about eliminating every path where that happens. - -### 1.1 Error Handling in index.js (Fenster) - -**Problem:** index.js has zero error handling. Every filesystem operation is unguarded. If `squad.agent.md` source doesn't exist, if the target directory is read-only, if disk is full — raw stack trace. For a CLI tool with 9 users and a division watching, that's unacceptable. - -**What ships:** -- Wrap `fs.copyFileSync`, `fs.mkdirSync`, `fs.readFileSync` in try/catch with human-readable error messages -- Validate that source files exist before copying (guard against corrupted npm install) -- Validate that `dest` (process.cwd()) is writable before starting -- Exit with code 1 on failure, code 0 on success (currently implicit) -- Add a top-level `process.on('uncaughtException')` handler that prints a clean message instead of a stack trace - -**Effort:** 2 hours -**Risk:** Very low — additive error handling, no behavior changes on happy path - -### 1.2 Test Coverage Expansion (Hockney) - -**Problem:** 12 tests cover init, idempotency, and copyRecursive. Missing: upgrade, `--version`, `--help`, error cases, edge cases. The test strategy (Proposal 013) identified 9 test categories — we've covered 3. - -**What ships:** -- **Upgrade tests:** Upgrade overwrites squad.agent.md, preserves .ai-team/ contents, overwrites templates -- **Flag tests:** `--version` outputs semver, `--help` outputs usage, `help` subcommand works -- **Error case tests:** Init with missing source files (corrupted install), init in read-only directory (if testable on platform), unknown subcommand behavior -- **Edge case tests:** Very long path names, paths with spaces, Unicode directory names (Windows-relevant) -- **Exit code tests:** Verify process exits 0 on success, 1 on error (after 1.1 ships) - -**Effort:** 3-4 hours -**Risk:** Low — pure additive -**Dependency:** Error case tests depend on 1.1 (error handling must exist to test it) - -### 1.3 CI with GitHub Actions (Hockney) - -**Problem:** Tests only run when someone remembers to run them. With 9 users and PRs incoming, we need automated quality gates. - -**What ships:** -- `.github/workflows/ci.yml` — runs `npm test` on push and PR -- Matrix: Node 22.x on ubuntu-latest (expand to Windows later if needed) -- Status badge in README (when README ships in Wave 2) - -**Effort:** 1 hour -**Risk:** Very low — standard CI setup - -### 1.4 Version Stamping — Phase 1 (Fenster) - -**Problem:** Proposal 011 defines version stamping but it's not implemented. Users can't tell what version of Squad they're running beyond `--version`. The coordinator (`squad.agent.md`) has no version header, so upgrade can't report deltas. - -**What ships:** -- Version comment header in `squad.agent.md`: `` -- `upgrade` subcommand reads header, compares to package version, reports: "Upgraded coordinator from 0.1.0 to 0.2.0" or "Already up to date" -- `engines` field in `package.json`: `"node": ">=22.0.0"` - -**Effort:** 1-2 hours -**Risk:** Low — the upgrade subcommand already exists, this adds intelligence to it - -### 1.5 Silent Success Bug — Deeper Mitigation (Verbal) - -**Problem:** P015 mitigations are in place but the bug still hits ~1 in 6 agents this session. The mitigations (prompt reorder, file verification, response mandate) reduce the rate but don't eliminate it. More aggressive prompt engineering may help. - -**What ships:** -- Audit current mitigations effectiveness — measure which agents still silent-fail -- Strengthen the response mandate in spawn prompts: move the "you MUST end with text" instruction to the FIRST line of every spawn prompt, not buried in the charter -- Add a coordinator-side retry: if `read_agent` returns empty and the agent wrote files, re-read with a longer timeout -- Document the bug honestly in the README (Wave 2) — users should know this is a platform constraint, not Squad being broken - -**Effort:** 2 hours -**Risk:** Low — prompt changes only, no code changes to index.js - -### Wave 1 Summary - -| Item | Owner | Effort | Dependency | -|------|-------|--------|------------| -| 1.1 Error handling | Fenster | 2h | None | -| 1.2 Test expansion | Hockney | 3-4h | 1.1 (error tests) | -| 1.3 CI setup | Hockney | 1h | None | -| 1.4 Version stamping | Fenster | 1-2h | None | -| 1.5 Silent success deeper fix | Verbal | 2h | None | -| **Total** | | **9-11h** | | - -### Wave 1 Gate: "Can We Trust It?" - -Wave 1 is complete when ALL of these are true: - -- [ ] `npm test` passes 20+ tests covering init, upgrade, flags, and error cases -- [ ] CI runs on every push and PR -- [ ] index.js has zero unhandled exceptions on any filesystem error -- [ ] `squad.agent.md` has a version header -- [ ] `upgrade` reports version deltas -- [ ] Silent success rate is measured and documented - -**This gate is binary.** If any item fails, Wave 2 doesn't start. Quality is not negotiable. - ---- - -## Wave 1.5: Zero-Risk Experience (Parallel Track) - -**Key insight:** Some experience work has ZERO quality risk because it doesn't touch code. These can run in parallel with Wave 1 without violating Brady's principle. - -### 1.5.1 README Rewrite (McManus) - -**Why parallel-safe:** The README is a markdown file. It doesn't affect index.js, tests, or the coordinator. McManus can ship Proposal 006's copy-paste-ready README without touching anything Wave 1 cares about. - -**What ships:** -- New README.md from Proposal 006 (already written, already reviewed) -- CI status badge (depends on 1.3 — add after CI ships) -- Honest "Known Limitations" section documenting the silent success bug - -**Effort:** 1-2 hours (mostly integration, the copy is done) -**Risk:** Zero to codebase quality - -### 1.5.2 Messaging Polish (McManus) - -**Why parallel-safe:** Proposal 014's positioning, tagline hierarchy, and launch messaging are pure content. No code. - -**What ships:** -- Finalized tagline: "Throw MY squad at it" (pending portability) or "Throw a squad at it" (current) -- npm package description update (one line in package.json) -- CHANGELOG.md for v0.1.0 documenting what's shipped - -**Effort:** 1-2 hours -**Risk:** Zero to codebase quality - -### 1.5.3 Squad Paper Draft (Verbal) - -**Why parallel-safe:** The Squad paper (Proposal 016) is a standalone document. Pure thought leadership. - -**What ships:** -- First complete draft of the Squad paper -- Positioned for v1 launch amplification - -**Effort:** 3-4 hours -**Risk:** Zero to codebase quality - ---- - -## Wave 2: Experience — "Make It Feel Right" - -**Duration:** ~5-7 days -**Principle:** Quality is proven. Now make the product feel like the future. -**Gate prerequisite:** Wave 1 gate must be GREEN. - -### 2.1 Tiered Response Modes (Verbal + Kujan) - -**Why this is first in Wave 2:** Latency is the #1 experience complaint. Brady said it: "later on, the agents get in the way more than they help." Proposal 007's tiered modes (Direct/Lightweight/Standard/Full) transform the experience from "30 seconds for everything" to "3 seconds for simple things." This is the single highest-impact experience change. - -**What ships:** -- Routing table in `squad.agent.md` for mode selection (Direct/Lightweight/Standard/Full) -- Coordinator context caching (skip re-reading team.md/routing.md/registry.json after first message) -- Scribe batching (only spawn when inbox has files) -- Coordinator direct handling for trivial tasks (single-line changes, status queries) - -**Effort:** 3-4 hours -**Risk:** Medium — routing judgment is the critical variable. Wrong routing (handling something directly that should have been spawned) is worse than slow routing. -**Mitigation:** Bias toward spawning when uncertain. Direct mode only for unambiguous tasks. - -### 2.2 Version Detection + Smart Upgrade (Fenster) - -**Why here:** With version stamping shipped in Wave 1, we can now build the full upgrade intelligence from Proposal 011. - -**What ships:** -- Upgrade detects version delta and reports what changed -- Upgrade runs additive-only migrations (create new directories that future versions introduce, like `skills/`) -- Migration registry: version-keyed functions that run on upgrade - -**Effort:** 2-3 hours -**Risk:** Low — upgrade is already shipping; this adds intelligence -**Dependency:** Wave 1 item 1.4 (version stamping) - -### 2.3 Skills System — Phase 1 (Verbal + Fenster) - -**Why Phase 1 only:** The full skills system (Proposal 010) is big. Phase 1 is template + instruction only — add the Agent Skills standard SKILL.md format to templates, update spawn prompts to reference skills when present. No skill acquisition, no skill routing, no MCP declarations. Just: if `.ai-team/skills/react-patterns/SKILL.md` exists, agents read it. - -**What ships:** -- Skills directory template in `.ai-team-templates/` -- SKILL.md format reference (from the Agent Skills standard) -- Spawn prompt update: "If `.ai-team/skills/` contains SKILL.md files, read relevant ones before working" -- Example skill: `squad-conventions/SKILL.md` documenting Squad's own patterns - -**Effort:** 3-4 hours -**Risk:** Low — additive prompt changes + new template files -**Strategic value:** High — this is the foundation for Phase 2 (earned skills) and portability - -### 2.4 Export/Import CLI — Export Only (Fenster) - -**Why export-only first:** Proposal 008 (Portable Squads) is 11-14 hours total per Fenster's estimate. That's too big for one wave item. But export alone is ~4 hours and is useful standalone — users can backup squad state, share via Gist, diff over time. Import builds on export in Wave 3. - -**What ships:** -- `npx create-squad export` subcommand -- Produces `squad-export.json` with casting state, charters, filtered histories -- `--out` flag for custom output path -- Clear messaging: "Review agent histories before sharing" -- Tests for export (Hockney) - -**Effort:** 4-5 hours (including tests) -**Risk:** Medium — new code path in index.js, but well-specified in Proposal 008/008-platform -**Dependency:** Wave 1 gate (error handling and CI must be in place) - -### Wave 2 Summary - -| Item | Owner | Effort | Dependency | -|------|-------|--------|------------| -| 2.1 Tiered response modes | Verbal + Kujan | 3-4h | Wave 1 gate | -| 2.2 Smart upgrade | Fenster | 2-3h | 1.4 (version stamping) | -| 2.3 Skills Phase 1 | Verbal + Fenster | 3-4h | Wave 1 gate | -| 2.4 Export CLI | Fenster | 4-5h | Wave 1 gate | -| **Total** | | **12-16h** | | - -### Wave 2 Gate: "Does It Feel Fast and Forward?" - -- [ ] Trivial tasks (status queries, single-line changes) complete in <5 seconds -- [ ] `npx create-squad export` produces a valid, human-readable JSON manifest -- [ ] Skills directory exists in templates; agents read skills when present -- [ ] Upgrade reports version deltas and runs migrations -- [ ] All new code has tests; CI is green - ---- - -## Wave 3: Experience — "Make It Magical" - -**Duration:** ~7-10 days -**Principle:** The product works and feels good. Now add the features that make people say "holy crap." -**Gate prerequisite:** Wave 2 gate must be GREEN. - -### 3.1 Import CLI + Portability Complete (Fenster) - -**What ships:** -- `npx create-squad import ` subcommand -- Collision detection (refuse if squad exists, `--force` for replacement) -- Coordinator detects imported squad on first session, runs lightweight onboarding -- Round-trip tests: export → import → verify identity preserved, project context dropped -- History split: Portable Knowledge vs Project Learnings sections in history.md template - -**Effort:** 5-6 hours -**Risk:** Medium — import modifies init flow, needs thorough testing -**Dependency:** 2.4 (export must exist) - -### 3.2 Skills Phase 2 — Earned Skills (Verbal) - -**What ships:** -- Agents learn to identify and extract skills from real work -- Skill confidence lifecycle: low → medium → high based on repeated application -- Skill-aware routing: coordinator checks skills when selecting agents for tasks -- MCP tool declarations in skill metadata (Brady's specific request) - -**Effort:** 4-5 hours -**Risk:** Medium-high — depends on prompt engineering quality for reliable skill categorization -**Dependency:** 2.3 (Phase 1 format must exist) - -### 3.3 Progressive History Summarization (Verbal) - -**What ships:** -- Scribe responsibility: when history.md exceeds 3,000 tokens, summarize entries older than 2 weeks into Core Context -- Archive original entries to `history-archive.md` -- Keeps agent startup time constant regardless of project age - -**Effort:** 2-3 hours -**Risk:** Medium — lossy compression. Mitigated by archival (original data preserved) - -### 3.4 Lightweight Spawn Template (Kujan) - -**What ships:** -- Spawn template for simple, scoped tasks: no charter inline, no history read, just the task -- Use `explore` agent type for read-only queries (Haiku model, faster) - -**Effort:** 1-2 hours -**Risk:** Low — additive template, coordinator already routes by complexity (from 2.1) - -### Wave 3 Summary - -| Item | Owner | Effort | Dependency | -|------|-------|--------|------------| -| 3.1 Import + portability | Fenster | 5-6h | 2.4 (export) | -| 3.2 Skills Phase 2 | Verbal | 4-5h | 2.3 (Skills Phase 1) | -| 3.3 History summarization | Verbal | 2-3h | Wave 2 gate | -| 3.4 Lightweight spawn | Kujan | 1-2h | 2.1 (tiered modes) | -| **Total** | | **12-16h** | | - -### Wave 3 Gate: "The Holy Crap Moments" - -- [ ] Export from Project A → Import into Project B → agents know the user, not the old project -- [ ] An agent earns a skill in one project; the skill appears in the skills directory -- [ ] Message 15 of a session is faster than message 1 -- [ ] Users say "holy crap" at least once during a demo - ---- - -## Wave 4+: Horizon (Not Planned, Not Promised) - -These are real features that don't earn a place in Waves 1-3. They're recorded here so we don't lose them. - -| Feature | Source | Why Not Now | -|---------|--------|-------------| -| Squad DM (Proposal 017) | Brady request | Requires Gateway architecture, Dev Tunnels, platform adapters. Massive scope. Ship after core product is bulletproof. | -| Export merge (`--merge`) | Proposal 008 | Universe conflicts are unsolvable in v1. `--force` is honest. | -| Squad sharing / registry | Proposal 008 v2/v3 | Needs portability to be proven first. | -| Video content (Proposal 005) | McManus | Not blocked, can happen anytime. But not a code priority. | -| Conditional memory loading | Proposal 007 | Marginal gain (~1.5s/spawn). Tiered modes solve the big latency problem. | -| Agent-to-agent negotiation | Verbal | Fascinating. Premature. | -| Speculative execution | Verbal | Fascinating. Premature. | -| Squad Paper publication | Verbal | Draft in Wave 1.5. Publication timing is a launch decision, not a dev decision. | - -**Squad DM specifically:** Proposal 017 is architecturally sound and Brady clearly wants it. But it's a second product surface — a Gateway server, platform adapters, tiered execution outside the CLI, auth, rate limiting. Building it before the core CLI is bulletproof is how you get two half-finished products instead of one great one. Wave 4 at earliest. Probably its own wave plan. - ---- - -## Parallelism Map - -Not everything is sequential. Here's what can run simultaneously: - -``` -Wave 1 (Quality) Wave 1.5 (Zero-Risk Experience) -├── 1.1 Error handling (Fenster) ├── 1.5.1 README (McManus) -├── 1.3 CI setup (Hockney) ├── 1.5.2 Messaging (McManus) -├── 1.4 Version stamping (Fenster) └── 1.5.3 Squad Paper (Verbal) -├── 1.5 Silent success (Verbal) -└── 1.2 Test expansion (Hockney) ← depends on 1.1 -``` - -Within Wave 2: -``` -Wave 2 (Experience) -├── 2.1 Tiered modes (Verbal + Kujan) ← can start immediately -├── 2.2 Smart upgrade (Fenster) ← can start immediately -├── 2.3 Skills Phase 1 (Verbal + Fenster) ← can start immediately -└── 2.4 Export CLI (Fenster) ← after 2.2 (Fenster bandwidth) -``` - -Within Wave 3: -``` -Wave 3 (Magical) -├── 3.1 Import CLI (Fenster) ← depends on 2.4 -├── 3.2 Skills Phase 2 (Verbal) ← depends on 2.3 -├── 3.3 History summarization (Verbal) ← after 3.2 (Verbal bandwidth) -└── 3.4 Lightweight spawn (Kujan) ← can start immediately -``` - ---- - -## What I Cut and Why - -| Cut | Why | -|-----|-----| -| **Init always-overwrite squad.agent.md** (from Proposal 009) | Already shipped differently — init skips, upgrade overwrites. Brady's users have the upgrade path. The current idempotent init behavior is what users expect and tests verify. Changing it now breaks 4 tests and 9 users' muscle memory for zero gain. | -| **History split as Wave 1 prerequisite** (from Proposal 008) | History split is architecturally correct but not a quality issue. It's an experience issue — portability. Moved to Wave 3 where it compounds with import. | -| **LLM-powered history classification** | Proposal 008 correctly punted this. Manual curation in v1, LLM classification in v2+. | -| **Squad merge** | Universe conflicts are a design problem, not an engineering problem. `--force` with archival is honest. | -| **Conditional memory loading** (Proposal 007 Solution 3) | ~1.5s savings per spawn. Tiered response modes (Wave 2.1) save 25+ seconds on trivial tasks. Optimize the big thing first. | -| **Squad DM** (Proposal 017) | Second product surface. Ship after first product surface is bulletproof. | - ---- - -## Total Effort Estimate - -| Wave | Effort | Calendar (parallel) | -|------|--------|-------------------| -| Wave 1 + 1.5 | 14-19h | 3-4 days | -| Wave 2 | 12-16h | 5-7 days | -| Wave 3 | 12-16h | 7-10 days | -| **Total** | **38-51h** | **~3 weeks** | - ---- - -## The Principle, Restated - -Brady said quality then experience. Here's what that means in practice: - -**Wave 1 earns trust.** Every error is handled. Every path is tested. CI catches regressions. Version stamping enables forwardability. The silent success bug is measured and documented honestly. Users can rely on `npx create-squad` the way they rely on `npm init`. - -**Wave 1.5 proves we can walk and chew gum.** Docs and messaging never conflict with code quality work. McManus and Verbal can ship content while Fenster and Hockney harden the core. - -**Wave 2 delivers experience that quality made safe.** Tiered modes, skills, and export are all features that could break things — but they ship into a codebase with 20+ tests, CI, error handling, and version tracking. The quality foundation makes experience work lower-risk. - -**Wave 3 compounds everything.** Import builds on export. Phase 2 skills build on Phase 1. History summarization builds on the history format. Lightweight spawns build on tiered routing. Every Wave 3 item is only possible because Waves 1 and 2 laid the foundation. - -Quality isn't a phase you finish. It's the foundation everything else stands on. - ---- - -**Review requested from:** bradygaster (this is your directive — does this plan match your intent?) -**Approved by:** [Pending] -**Implemented:** [Pending] diff --git a/team-docs/proposals/019-master-sprint-plan.md b/team-docs/proposals/019-master-sprint-plan.md deleted file mode 100644 index 973d5c6af..000000000 --- a/team-docs/proposals/019-master-sprint-plan.md +++ /dev/null @@ -1,651 +0,0 @@ -# Proposal 019: Master Sprint Plan — The Definitive Build Plan - -**Status:** Approved ✅ Shipped (Waves 1-3) -**Authored by:** Keaton (Lead) -**Date:** 2026-02-09 -**Requested by:** bradygaster — *"stack it all up — sprint plan it? all of it."* -**Supersedes:** Proposal 009 (v1 Sprint Plan), Proposal 018 (Wave Execution Plan) - ---- - -## What This Document Is - -This is the ONE document the team executes from. Every proposal, every decision, every directive from every session — synthesized into a single actionable plan with agent assignments, dependencies, effort estimates, and hard gates. - -No ambiguity. No redundancy. If it's not in here, it's not in scope. - ---- - -## Brady's Directives (Non-Negotiable) - -1. **Quality first, then experience.** Wave 1 earns trust. Nothing else ships until the foundation is solid. -2. **"Where are we?" is a first-class value prop.** Instant team-wide status synthesis. Demo it. Message it. Build around it. -3. **Human input responsiveness matters.** Coordinator captures human directives to inbox as first action. Platform input latency is unsolvable, but directive persistence uses the existing drop-box. -4. **The "feels heard" UX principle.** When a human speaks, the coordinator acknowledges immediately and writes the directive to the inbox before doing anything else. The user must never wonder if their message was received. - ---- - -## What's Already Shipped (Do Not Re-Plan) - -| Item | Evidence | Shipped By | -|------|----------|------------| -| P015 silent success mitigations (3 in squad.agent.md) | squad.agent.md | Kujan | -| Upgrade subcommand in index.js | index.js lines 49-65 | Fenster | -| 12 tests passing (init, idempotency, copyRecursive) | test/index.test.js | Hockney | -| Inbox-driven Scribe spawn | squad.agent.md | Kujan | -| Scribe history.md created | .ai-team/agents/scribe/ | Keaton | -| Demo script ACT 7 restored | docs/demo-script.md | McManus | -| decisions.md cleanup | .ai-team/decisions.md | Keaton | -| Orchestration log entries (was dead, now working) | .ai-team/orchestration-log/ | Keaton | -| 12 orphaned inbox files merged | .ai-team/decisions/inbox/ (empty) | Keaton | - ---- - -## Proposal 009 Disposition - -| 009 Item | Status in 019 | -|----------|---------------| -| Sprint 1: Forwardability (always-overwrite init) | **Superseded.** Init skips, upgrade overwrites. Already shipped. | -| Sprint 1: Tiered response modes | **Carried forward** → Wave 2, item 2.1 | -| Sprint 1: P015 silent success fix | **Completed.** Shipped in squad.agent.md | -| Sprint 2: History split | **Carried forward** → Wave 3, item 3.1 (part of import) | -| Sprint 2: Skills system | **Carried forward** → Wave 2 (Phase 1) and Wave 3 (Phase 2) | -| Sprint 2: Export/Import | **Carried forward** → Wave 2 (export) and Wave 3 (import) | -| Sprint 3: README rewrite | **Carried forward** → Wave 1.5, item 1.5.1 | -| Sprint 3: Test expansion | **Carried forward** → Wave 1, item 1.2 | -| Sprint 3: Polish | **Carried forward** → distributed across waves | -| Aggressive cuts (merge, LLM classification, sharing, negotiation, speculative) | **Carried forward** → Horizon | -| Skills as first-class concept | **Carried forward** → Wave 2/3 with Agent Skills standard | -| Forwardability bright line (Squad-owned vs user-owned files) | **Carried forward** → already implemented in index.js | - -## Proposal 018 Disposition - -| 018 Item | Status in 019 | -|----------|---------------| -| Wave 1: Error handling | **Carried forward** → Wave 1, item 1.1 | -| Wave 1: Test expansion | **Carried forward** → Wave 1, item 1.2 | -| Wave 1: CI setup | **Carried forward** → Wave 1, item 1.3 | -| Wave 1: Version stamping | **Carried forward** → Wave 1, item 1.4 | -| Wave 1: Silent success deeper fix | **Carried forward** → Wave 1, item 1.5 | -| Wave 1.5: README, messaging, paper | **Carried forward** → Wave 1.5 (unchanged) | -| Wave 2: Tiered response modes | **Carried forward** → Wave 2, item 2.1 | -| Wave 2: Smart upgrade | **Carried forward** → Wave 2, item 2.2 | -| Wave 2: Skills Phase 1 | **Carried forward** → Wave 2, item 2.3 | -| Wave 2: Export CLI | **Carried forward** → Wave 2, item 2.4 | -| Wave 3: Import CLI | **Carried forward** → Wave 3, item 3.1 | -| Wave 3: Skills Phase 2 | **Carried forward** → Wave 3, item 3.2 | -| Wave 3: History summarization | **Carried forward** → Wave 3, item 3.3 | -| Wave 3: Lightweight spawn template | **Carried forward** → Wave 3, item 3.4 | -| Wave 4+: Horizon | **Carried forward** → Horizon section (refined) | - -**New in 019 (not in 018):** -- Wave 1, item 1.6: Human directive capture ("feels heard" behavior) -- Wave 1, item 1.7: "Feels heard" coordinator acknowledgment -- Wave 1.5, item 1.5.4: "Where are we?" messaging beat -- Wave 1.5, item 1.5.5: Demo script finalization -- Wave 1.5, item 1.5.6: Video content strategy alignment -- Explicit content tier parallel track with all content items - ---- - -## Summary Table — All Work Items - -| ID | Item | Owner | Effort | Depends On | Wave | -|----|------|-------|--------|------------|------| -| **1.1** | Error handling in index.js | Fenster | 2h | — | 1 | -| **1.2** | Test coverage expansion | Hockney | 3-4h | 1.1 (error tests) | 1 | -| **1.3** | CI with GitHub Actions | Hockney | 1h | — | 1 | -| **1.4** | Version stamping Phase 1 | Fenster | 1-2h | — | 1 | -| **1.5** | Silent success deeper mitigation | Verbal | 2h | — | 1 | -| **1.6** | Human directive capture | Kujan | 1h | — | 1 | -| **1.7** | "Feels heard" coordinator behavior | Verbal | 1h | — | 1 | -| **1.5.1** | README rewrite | McManus | 1-2h | 1.3 (CI badge) | 1.5 | -| **1.5.2** | Messaging polish | McManus | 1-2h | — | 1.5 | -| **1.5.3** | Squad Paper draft | Verbal | 3-4h | — | 1.5 | -| **1.5.4** | "Where are we?" messaging beat | McManus | 1h | — | 1.5 | -| **1.5.5** | Demo script finalization | McManus | 2h | — | 1.5 | -| **1.5.6** | Video content strategy alignment | Verbal + McManus | 1h | — | 1.5 | -| **2.1** | Tiered response modes | Verbal + Kujan | 3-4h | Wave 1 gate | 2 | -| **2.2** | Smart upgrade with migrations | Fenster | 2-3h | 1.4 (version stamping) | 2 | -| **2.3** | Skills Phase 1 (template + read) | Verbal + Fenster | 3-4h | Wave 1 gate | 2 | -| **2.4** | Export CLI | Fenster | 4-5h | Wave 1 gate | 2 | -| **3.1** | Import CLI + history split | Fenster | 5-6h | 2.4 (export) | 3 | -| **3.2** | Skills Phase 2 (earned skills) | Verbal | 4-5h | 2.3 (Phase 1) | 3 | -| **3.3** | Progressive history summarization | Verbal | 2-3h | Wave 2 gate | 3 | -| **3.4** | Lightweight spawn template | Kujan | 1-2h | 2.1 (tiered modes) | 3 | - -**Total: 42-56 hours across 3 waves + parallel content track.** - ---- - -## Wave 1: Quality — "Make It Trustworthy" - -**Duration:** ~3-4 days -**Principle:** If a user runs `npx create-squad` and something goes wrong, they never come back. - -### 1.1 Error Handling in index.js - -**Owner:** Fenster -**Effort:** 2 hours -**Depends on:** Nothing -**Source:** Proposal 018 §1.1 - -**What ships:** -- Wrap all `fs.*Sync` calls in try/catch with human-readable error messages -- Validate source files exist before copying (guard against corrupted npm install) -- Validate `dest` (process.cwd()) is writable before starting -- Exit with code 1 on failure, code 0 on success (currently implicit) -- Top-level `process.on('uncaughtException')` handler — clean message, no stack trace - -**Risk:** Very low — additive error handling, no happy-path behavior changes - -### 1.2 Test Coverage Expansion - -**Owner:** Hockney -**Effort:** 3-4 hours -**Depends on:** 1.1 (error case tests need error handling to exist) -**Source:** Proposals 013, 018 §1.2 - -**What ships:** -- **Upgrade tests:** Upgrade overwrites squad.agent.md, preserves .ai-team/ contents, overwrites templates -- **Flag tests:** `--version` outputs semver, `--help` outputs usage, `help` subcommand works -- **Error case tests:** Init with missing source files, unknown subcommand behavior -- **Edge case tests:** Paths with spaces, Unicode directory names (Windows-relevant) -- **Exit code tests:** Verify process exits 0 on success, 1 on error - -**Target:** 20+ tests across 5 suites (up from 12 tests, 3 suites) -**Risk:** Low — pure additive - -### 1.3 CI with GitHub Actions - -**Owner:** Hockney -**Effort:** 1 hour -**Depends on:** Nothing -**Source:** Proposals 013, 018 §1.3 - -**What ships:** -- `.github/workflows/ci.yml` — runs `npm test` on push and PR -- Matrix: Node 22.x on ubuntu-latest -- Status badge for README (added when README ships in Wave 1.5) - -**Risk:** Very low — standard CI setup - -### 1.4 Version Stamping — Phase 1 - -**Owner:** Fenster -**Effort:** 1-2 hours -**Depends on:** Nothing -**Source:** Proposals 011, 018 §1.4 - -**What ships:** -- Version comment header in `squad.agent.md`: `` -- `upgrade` subcommand reads header, compares to package version, reports delta: "Upgraded coordinator from 0.1.0 to 0.2.0" or "Already up to date" -- `engines` field in `package.json`: `"node": ">=22.0.0"` - -**Risk:** Low — additive to existing upgrade subcommand - -### 1.5 Silent Success Bug — Deeper Mitigation - -**Owner:** Verbal -**Effort:** 2 hours -**Depends on:** Nothing -**Source:** Proposals 015, 018 §1.5 - -**What ships:** -- Audit current mitigations effectiveness — measure which agents still silent-fail -- Strengthen response mandate: move "you MUST end with text" to FIRST line of every spawn prompt -- Add coordinator-side retry: if `read_agent` returns empty and agent wrote files, re-read with longer timeout -- Document the bug honestly in README (when it ships in 1.5.1) - -**Risk:** Low — prompt changes only, no code changes to index.js - -### 1.6 Human Directive Capture - -**Owner:** Kujan -**Effort:** 1 hour -**Depends on:** Nothing -**Source:** Brady's session directive, Proposal 018 team update - -**What ships:** -- Coordinator writes human directives to `.ai-team/decisions/inbox/` as first action before routing -- Format: `human-directive-{timestamp}.md` with the user's exact words -- This ensures human input survives even if the coordinator session crashes or times out -- Scribe merges directives into decisions.md on next merge cycle - -**Risk:** Very low — uses existing drop-box pattern - -### 1.7 "Feels Heard" Coordinator Behavior - -**Owner:** Verbal -**Effort:** 1 hour -**Depends on:** Nothing -**Source:** Brady's session directive - -**What ships:** -- Update `squad.agent.md` Team Mode: on every user message, coordinator FIRST acknowledges receipt with a brief text response ("Got it. Routing to {Name}..." or "On it. Spawning {agents}...") -- This text response ships BEFORE any tool calls, ensuring the user sees immediate feedback -- The acknowledgment is brief (one sentence) — not a plan, not a summary, just "I heard you" -- For complex requests, the acknowledgment includes what the coordinator is about to do - -**Risk:** Very low — prompt engineering only. The "feels heard" pattern prevents the "did it get my message?" anxiety that compounds with platform latency. - -### Wave 1 Parallelism - -``` -Day 1-2: Day 2-4: -├── 1.1 Error handling (Fenster) └── 1.2 Test expansion (Hockney) ← needs 1.1 -├── 1.3 CI setup (Hockney) -├── 1.4 Version stamping (Fenster) -├── 1.5 Silent success (Verbal) -├── 1.6 Human directive capture (Kujan) -└── 1.7 Feels heard behavior (Verbal) -``` - -Items 1.1, 1.3, 1.4, 1.5, 1.6, 1.7 all run in parallel on Day 1-2. -Item 1.2 starts Day 2 after 1.1 ships (error tests need error handling to exist). - -### Wave 1 Gate: "Can We Trust It?" - -**This gate is binary. ALL must pass or Wave 2 doesn't start.** - -- [ ] `npm test` passes 20+ tests covering init, upgrade, flags, error cases, and exit codes -- [ ] CI runs on every push and PR — `.github/workflows/ci.yml` exists and is green -- [ ] index.js has zero unhandled exceptions on any filesystem error -- [ ] `squad.agent.md` has a version header -- [ ] `upgrade` reports version deltas -- [ ] Silent success rate is measured and documented -- [ ] Coordinator captures human directives to inbox before routing -- [ ] Coordinator acknowledges user messages with immediate text before tool calls - ---- - -## Wave 1.5: Content Track (Parallel — Zero Code Risk) - -**Key insight:** Content work has ZERO quality risk. It doesn't touch index.js, tests, or the coordinator code. McManus and Verbal can ship content while Fenster and Hockney harden the core. - -**Runs entirely in parallel with Wave 1 and continues through Wave 2.** - -### 1.5.1 README Rewrite - -**Owner:** McManus -**Effort:** 1-2 hours -**Depends on:** 1.3 (CI badge — add after CI ships) -**Source:** Proposals 002, 006, 014 - -**What ships:** -- New README.md from Proposal 006 (already written, already reviewed) -- CI status badge (after 1.3 ships) -- Honest "Known Limitations" section documenting silent success bug -- "Where are we?" callout in "Why Squad?" section (per 014a) - -### 1.5.2 Messaging Polish - -**Owner:** McManus -**Effort:** 1-2 hours -**Depends on:** Nothing -**Source:** Proposals 002, 014, 014a - -**What ships:** -- Finalized tagline: "Throw MY squad at it" (pending portability) or "Throw a squad at it" (current) -- npm package description update (one line in package.json) -- CHANGELOG.md for v0.1.0 documenting what's shipped -- "Where are we?" positioned as awareness hook in tagline hierarchy - -### 1.5.3 Squad Paper Draft - -**Owner:** Verbal -**Effort:** 3-4 hours -**Depends on:** Nothing -**Source:** Proposal 016 - -**What ships:** -- First complete draft of the Squad paper -- Positioned for v1 launch amplification -- Publication timing deferred to launch decision - -### 1.5.4 "Where Are We?" Messaging Beat - -**Owner:** McManus -**Effort:** 1 hour -**Depends on:** Nothing -**Source:** Proposal 014a — Brady: *"that i can do that is SO hot, such a feature"* - -**What ships:** -- "Ask Your Team, Not Your Dashboard" messaging beat copy -- Demo script beat insertion ("The Check-In") -- Social clip format for Twitter/X (30-second "where are we?" → comprehensive answer) -- README placement: close of "Why Squad?" section + follow-up in "Agents Work in Parallel" - -### 1.5.5 Demo Script Finalization - -**Owner:** McManus -**Effort:** 2 hours -**Depends on:** Nothing -**Source:** Proposal 004 - -**What ships:** -- Final production-ready demo script with all 9 beats -- "Where are we?" check-in beat inserted (per 014a) -- Pre-recording checklist verified against current product state -- All beat timestamps validated against current Squad behavior - -### 1.5.6 Video Content Strategy Alignment - -**Owner:** Verbal + McManus -**Effort:** 1 hour -**Depends on:** Nothing -**Source:** Proposal 005 - -**What ships:** -- Trailer script finalized (75s target) -- Full demo script aligned with Proposal 004 beats -- Series roadmap confirmed (which videos first after launch) -- "Where are we?" positioned as a key demo moment across all videos - ---- - -## Wave 2: Experience — "Make It Feel Right" - -**Duration:** ~5-7 days -**Principle:** Quality is proven. Now make the product feel like the future. -**Gate prerequisite:** Wave 1 gate must be GREEN. - -### 2.1 Tiered Response Modes - -**Owner:** Verbal + Kujan -**Effort:** 3-4 hours -**Depends on:** Wave 1 gate -**Source:** Proposal 007 - -**What ships:** -- Routing table in `squad.agent.md` for mode selection: - - **Direct:** Status checks, quick factual questions, "where are we?" — coordinator answers, no spawn (~2-3s) - - **Lightweight:** Single-file edits, small fixes, follow-ups — minimal spawn prompt (~8-12s) - - **Standard:** Normal tasks, single agent — full spawn with history + decisions (~25-35s) - - **Full:** Multi-agent, complex tasks — parallel fan-out, full ceremony (~40-60s) -- Coordinator context caching: skip re-reading team.md/routing.md/registry.json after first message -- Scribe batching: only spawn when inbox has files -- "Where are we?" handled in Direct mode — instant, no agent spawn needed - -**Risk:** Medium — routing judgment is the critical variable. Bias toward spawning when uncertain. - -### 2.2 Smart Upgrade with Migrations - -**Owner:** Fenster -**Effort:** 2-3 hours -**Depends on:** 1.4 (version stamping must exist) -**Source:** Proposal 011 - -**What ships:** -- Upgrade detects version delta and reports what changed -- Additive-only migrations (create new directories like `skills/`) -- Migration registry: version-keyed functions that run on upgrade -- No destructive operations — upgrade is always safe - -**Risk:** Low — upgrade already exists; this adds intelligence - -### 2.3 Skills Phase 1 — Template + Read - -**Owner:** Verbal + Fenster -**Effort:** 3-4 hours -**Depends on:** Wave 1 gate -**Source:** Proposals 010, 012 - -**What ships:** -- `.ai-team/skills/` directory created on init/upgrade (additive migration via 2.2) -- SKILL.md format reference from Agent Skills standard in templates -- Spawn prompt update: "If `.ai-team/skills/` contains SKILL.md files, read relevant ones before working" -- Example skill: `squad-conventions/SKILL.md` documenting Squad's own patterns -- Skills are read-only in Phase 1 — agents read but don't create skills yet - -**Risk:** Low — additive prompt changes + new template files -**Strategic value:** High — foundation for Phase 2 (earned skills) and portability - -### 2.4 Export CLI - -**Owner:** Fenster -**Effort:** 4-5 hours (including tests) -**Depends on:** Wave 1 gate -**Source:** Proposals 008, 008-platform - -**What ships:** -- `npx create-squad export` subcommand -- Produces `squad-export.json` with casting state, charters, filtered histories -- `--out` flag for custom output path -- Clear messaging: "Review agent histories before sharing" -- Hockney writes export tests (included in effort) - -**Risk:** Medium — new code path in index.js, but well-specified - -### Wave 2 Parallelism - -``` -Wave 2 (all items can start when Wave 1 gate passes) -├── 2.1 Tiered modes (Verbal + Kujan) ← start immediately -├── 2.2 Smart upgrade (Fenster) ← start immediately (needs 1.4) -├── 2.3 Skills Phase 1 (Verbal + Fenster) ← start immediately -└── 2.4 Export CLI (Fenster) ← after 2.2 (Fenster bandwidth) -``` - -### Wave 2 Gate: "Does It Feel Fast and Forward?" - -- [ ] Trivial tasks (status queries, "where are we?", single-line changes) complete in <5 seconds -- [ ] `npx create-squad export` produces a valid, human-readable JSON manifest -- [ ] Skills directory exists in templates; agents read skills when present -- [ ] Upgrade reports version deltas and runs migrations -- [ ] All new code has tests; CI is green - ---- - -## Wave 3: Experience — "Make It Magical" - -**Duration:** ~7-10 days -**Principle:** The product works and feels good. Now add the features that make people say "holy crap." -**Gate prerequisite:** Wave 2 gate must be GREEN. - -### 3.1 Import CLI + Portability Complete - -**Owner:** Fenster -**Effort:** 5-6 hours -**Depends on:** 2.4 (export must exist) -**Source:** Proposals 008, 008-platform, 008-experience - -**What ships:** -- `npx create-squad import ` subcommand -- Collision detection: refuse if squad exists, `--force` for replacement with archival -- Coordinator detects imported squad on first session, runs lightweight onboarding -- Round-trip tests: export → import → verify identity preserved, project context dropped -- History split: Portable Knowledge vs Project Learnings sections in history.md template -- Import skips casting ceremony — names, universe, and relationships arrive pre-populated - -**Risk:** Medium — import modifies init flow, needs thorough testing - -### 3.2 Skills Phase 2 — Earned Skills - -**Owner:** Verbal -**Effort:** 4-5 hours -**Depends on:** 2.3 (Phase 1 format must exist) -**Source:** Proposals 010, 012 - -**What ships:** -- Agents learn to identify and extract skills from real work -- Skill confidence lifecycle: low → medium → high based on repeated application -- Skill-aware routing: coordinator checks skills when selecting agents for tasks -- MCP tool declarations in skill metadata (Brady's specific request) - -**Risk:** Medium-high — depends on prompt engineering quality for reliable skill categorization -**Critical path:** Verbal's prompt work here is the make-or-break for the skills thesis - -### 3.3 Progressive History Summarization - -**Owner:** Verbal -**Effort:** 2-3 hours -**Depends on:** Wave 2 gate -**Source:** Proposal 007 §Solution 7 - -**What ships:** -- Scribe responsibility: when history.md exceeds 3,000 tokens, summarize entries older than 2 weeks into Core Context -- Archive original entries to `history-archive.md` -- Keeps agent startup time constant regardless of project age - -**Risk:** Medium — lossy compression. Mitigated by archival (original data preserved). - -### 3.4 Lightweight Spawn Template - -**Owner:** Kujan -**Effort:** 1-2 hours -**Depends on:** 2.1 (tiered modes must exist) -**Source:** Proposal 007 §Solution 5 - -**What ships:** -- Spawn template for simple, scoped tasks: no charter inline, no history read, just the task -- Use `explore` agent type for read-only queries (Haiku model, faster) -- Coordinator already routes by complexity (from 2.1); this adds the lightweight template - -**Risk:** Low — additive template - -### Wave 3 Parallelism - -``` -Wave 3 -├── 3.1 Import CLI (Fenster) ← depends on 2.4 -├── 3.2 Skills Phase 2 (Verbal) ← depends on 2.3 -├── 3.3 History summarization (Verbal) ← after 3.2 (Verbal bandwidth) -└── 3.4 Lightweight spawn (Kujan) ← can start immediately -``` - -### Wave 3 Gate: "The Holy Crap Moments" - -- [ ] Export from Project A → Import into Project B → agents know the user, not the old project -- [ ] An agent earns a skill in one project; the skill appears in the skills directory -- [ ] Message 15 of a session is faster than message 1 -- [ ] "Where are we?" returns comprehensive team-wide status in <5 seconds -- [ ] Users say "holy crap" at least once during a demo - ---- - -## Horizon — Explicitly Deferred - -These are real features. They're deferred because shipping them before the core is bulletproof creates two half-finished products instead of one great one. - -| Feature | Source | Why Not Now | Revisit When | -|---------|--------|-------------|--------------| -| **Squad DM (Telegram)** | Proposal 017 (3 docs) | Second product surface. Gateway, adapters, tiered execution, auth, rate limiting — massive scope. Ship after core CLI is complete. | Wave 3 gate passes | -| **Agent-to-agent negotiation** | Verbal (003) | Fascinating. Premature. Needs proven agent reliability first. | Skills Phase 2 proves agents can reliably categorize knowledge | -| **Speculative execution** | Verbal (003) | Spawning agents "just in case" requires confidence in the silent success fix and tiered modes. | Silent success rate < 5% | -| **Squad sharing / registry** | Proposal 008 v2/v3 | Needs portability proven in real use first. Export/import round-trip must be trusted. | 10+ successful export/import cycles | -| **Export merge (`--merge`)** | Proposal 008 | Universe conflicts are unsolvable in v1. `--force` with archival is honest. | User feedback demands it | -| **LLM-powered history classification** | Proposal 008 | Manual curation is honest and correct for v1. | Export user feedback says manual is too painful | -| **Conditional memory loading** | Proposal 007 §Solution 3 | ~1.5s savings/spawn. Tiered modes (2.1) save 25+ seconds on trivial tasks. Optimize the big thing first. | After tiered modes prove effective | -| **preferences.md as separate file** | Verbal (008-experience) | Architecturally sound but adds migration cost. Portable Knowledge section in history.md is sufficient for v1. | Sharing (v1.2) needs personal data stripping | -| **squad-profile.md** | Verbal (008-experience) | Team meta-identity file. Adds value when squads have 3+ projects of history. | After 3 real export/import cycles | -| **Squad diff** | Verbal (008-experience) | Quantified squad evolution tracking. Requires sufficient data. | After 6 months of squad usage | - ---- - -## Agent Workload Summary - -| Agent | Wave 1 | Wave 1.5 | Wave 2 | Wave 3 | Total | -|-------|--------|----------|--------|--------|-------| -| **Fenster** | 1.1 (2h), 1.4 (1-2h) | — | 2.2 (2-3h), 2.3 (shared, 2h), 2.4 (4-5h) | 3.1 (5-6h) | 16-20h | -| **Hockney** | 1.2 (3-4h), 1.3 (1h) | — | Tests for 2.4 (incl.) | Tests for 3.1 (incl.) | 4-5h | -| **Verbal** | 1.5 (2h), 1.7 (1h) | 1.5.3 (3-4h), 1.5.6 (shared, 0.5h) | 2.1 (shared, 2h), 2.3 (shared, 2h) | 3.2 (4-5h), 3.3 (2-3h) | 17-21h | -| **Kujan** | 1.6 (1h) | — | 2.1 (shared, 2h) | 3.4 (1-2h) | 4-5h | -| **McManus** | — | 1.5.1 (1-2h), 1.5.2 (1-2h), 1.5.4 (1h), 1.5.5 (2h), 1.5.6 (shared, 0.5h) | — | — | 5-8h | -| **Keaton** | Review all gates | Review content | Review all code | Final sign-off | Continuous | - ---- - -## Total Effort Estimate - -| Wave | Effort | Calendar (with parallelism) | -|------|--------|---------------------------| -| Wave 1 (Quality) | 11-14h | 3-4 days | -| Wave 1.5 (Content, parallel) | 9-13h | Runs alongside Waves 1-2 | -| Wave 2 (Experience) | 12-16h | 5-7 days | -| Wave 3 (Magical) | 12-16h | 7-10 days | -| **Total** | **44-59h** | **~3 weeks** | - ---- - -## Dependency Graph - -``` -Wave 1 (Quality) Wave 1.5 (Content — parallel) -├── 1.1 Error handling (Fenster) ├── 1.5.1 README (McManus) ← needs 1.3 for badge -├── 1.3 CI setup (Hockney) ├── 1.5.2 Messaging (McManus) -├── 1.4 Version stamping (Fenster) ├── 1.5.3 Squad Paper (Verbal) -├── 1.5 Silent success (Verbal) ├── 1.5.4 "Where are we?" (McManus) -├── 1.6 Directive capture (Kujan) ├── 1.5.5 Demo script (McManus) -├── 1.7 Feels heard (Verbal) └── 1.5.6 Video strategy (Verbal + McManus) -└── 1.2 Test expansion (Hockney) ← depends on 1.1 - │ - ═══════╧══════════ WAVE 1 GATE ═══════════════ - │ -Wave 2 (Experience) -├── 2.1 Tiered modes (Verbal + Kujan) -├── 2.2 Smart upgrade (Fenster) ← needs 1.4 -├── 2.3 Skills Phase 1 (Verbal + Fenster) -└── 2.4 Export CLI (Fenster) ← after 2.2 (bandwidth) - │ - ═══════╧══════════ WAVE 2 GATE ═══════════════ - │ -Wave 3 (Magical) -├── 3.1 Import + portability (Fenster) ← needs 2.4 -├── 3.2 Skills Phase 2 (Verbal) ← needs 2.3 -├── 3.3 History summarization (Verbal) ← after 3.2 (bandwidth) -└── 3.4 Lightweight spawn (Kujan) ← needs 2.1 -``` - ---- - -## How This Plan Respects Brady's Directives - -### 1. Quality First, Then Experience - -Wave 1 is ALL quality: error handling, tests, CI, version stamping, silent success, directive capture, responsiveness. Zero experience features ship until the gate passes. Content (Wave 1.5) runs parallel but never touches code. - -### 2. "Where Are We?" as First-Class Value Prop - -- Wave 1.5: McManus writes the messaging beat, demo script beat, and social clip format (1.5.4) -- Wave 2: Tiered modes (2.1) ensure "where are we?" is handled in Direct mode — instant, no spawn -- README (1.5.1): "Where are we?" placed in "Why Squad?" section and "Agents Work in Parallel" -- Demo script (1.5.5): "The Check-In" beat inserted into production demo -- Video strategy (1.5.6): "Where are we?" positioned as key moment across all videos - -### 3. Human Input Responsiveness - -- Wave 1: Coordinator writes directives to inbox before routing (1.6) -- Platform input latency is unsolvable, but directive persistence uses existing drop-box -- Combined with "feels heard" (1.7), the user's message is both acknowledged and persisted - -### 4. "Feels Heard" UX Principle - -- Wave 1: Coordinator acknowledges every message with immediate text before tool calls (1.7) -- The acknowledgment is one sentence — just enough to confirm receipt -- For complex requests: "Got it. Spawning Fenster and Hockney for this." -- For simple requests: "On it." + direct handling (enhanced in Wave 2 with tiered modes) - ---- - -## The Principle, Restated - -Brady said quality then experience. Here's what that means in execution: - -**Wave 1 earns trust.** Every error is handled. Every path is tested. CI catches regressions. The coordinator hears you and says so. Users can rely on `npx create-squad` the way they rely on `npm init`. - -**Wave 1.5 proves we can walk and chew gum.** Content never conflicts with code. McManus and Verbal ship messaging, demos, and the Squad paper while the core hardens. - -**Wave 2 delivers experience that quality made safe.** Tiered modes, skills, and export ship into a codebase with 20+ tests, CI, error handling, and version tracking. - -**Wave 3 compounds everything.** Import builds on export. Phase 2 skills build on Phase 1. History summarization builds on the history format. Lightweight spawns build on tiered routing. Every Wave 3 item is only possible because Waves 1 and 2 laid the foundation. - -Quality isn't a phase you finish. It's the foundation everything else stands on. - ---- - -**This is the plan. Execute from here.** - -**Review requested from:** bradygaster -**Approved by:** Keaton (Lead) — this is my plan, I own it -**Executed by:** The full squad diff --git a/team-docs/proposals/019a-sprint-plan-amendments.md b/team-docs/proposals/019a-sprint-plan-amendments.md deleted file mode 100644 index 4a21b1ffc..000000000 --- a/team-docs/proposals/019a-sprint-plan-amendments.md +++ /dev/null @@ -1,472 +0,0 @@ -# Proposal 019a: Sprint Plan Amendments — Brady's Session 5 Directives - -**Status:** Approved ✅ Shipped -**Authored by:** Keaton (Lead) -**Date:** 2026-02-09 -**Amends:** Proposal 019 (Master Sprint Plan) -**Source:** Brady's session 5 batch directives - ---- - -## What This Document Is - -Brady dropped five directives that affect Proposal 019. This amendment addresses each one: what changes, who owns it, where it slots in the wave structure. The master plan itself is not rewritten — these are surgical modifications. - ---- - -## Directive 1: README Timing - -**Brady said:** *"maybe save the readme rewrite until the end - up to y'all. could be good to keep it up as we go"* - -### My Call: Living README, Updated Each Wave - -**Rationale:** - -A living README serves three purposes a final-write-at-the-end does not: - -1. **It's the demo.** Every time Brady shares the repo — with a colleague, a potential user, a conference organizer — the README IS the product. A stale placeholder README that says "coming soon" signals "this isn't real yet." A living README that reflects current capabilities signals "this is shipping." - -2. **It forces accuracy.** If the README says "export your squad" and export isn't shipped yet, the README is wrong. Updating per-wave means the README is always honest about what's real. This aligns with Brady's own quality-first directive. - -3. **The blog format (Directive 2) handles the narrative.** The README doesn't need to tell the story of how we got here — the blog does that. The README just needs to document what's true right now. - -**What changes in 019:** - -- Item **1.5.1 (README rewrite)** stays in Wave 1.5 but gets a new scope: **initial README that documents v0.1.0 capabilities only**. No forward-looking features. -- Add new recurring item: **README refresh** at each wave gate. McManus updates the README to reflect newly shipped capabilities. ~30 minutes per wave. -- README refresh is a **gate exit criterion** (not a gate blocker — you don't hold the gate for it, but you don't start the next wave's features until the README reflects the current wave). - -| ID | Change | Owner | Effort | -|----|--------|-------|--------| -| 1.5.1 | Scope narrowed: current-state README only | McManus | 1-2h (unchanged) | -| 1.5.1a | Wave 1 gate: README refresh | McManus | 30min | -| 2.G.1 | Wave 2 gate: README refresh | McManus | 30min | -| 3.G.1 | Wave 3 gate: README refresh | McManus | 30min | - ---- - -## Directive 2: Blog Engine Meta-Play - -**Brady said:** *"think about a blog markdown format to continually update our users on progress, and then, one of the sample prompts is a blog engine with amazing front-end UX that renders Squad blog posts"* - -This is a strong play. Squad builds a blog engine sample prompt. Squad uses a blog format to document its own progress. The blog engine renders Squad's own blog posts. Meta all the way down. - -### 2a. Blog Post Format - -Every wave produces a blog post. Format: - -```markdown ---- -title: "Wave 1: Making Squad Trustworthy" -date: 2026-02-12 -wave: 1 -author: squad -tags: [release, quality, testing] -summary: "Error handling, 20+ tests, CI pipeline, and the 'feels heard' UX principle." ---- - -## What Shipped - -Brief summary of what's new. - -## Why It Matters - -Connect the technical work to the user's experience. - -## What's Next - -One-paragraph preview of the next wave. - -## The Numbers - -| Metric | Before | After | -|--------|--------|-------| -| Tests | 12 | 20+ | -| Error handling | none | complete | -| CI | none | GitHub Actions | - -## Try It - -```bash -npx github:bradygaster/squad upgrade -``` -``` - -Blog posts live in `docs/blog/` with filename format: `YYYY-MM-DD-wave-N-title.md`. Front matter is YAML (standard), not custom. - -### 2b. Sprint Plan Changes — Blog Post Per Wave - -| ID | Item | Owner | Effort | Wave | -|----|------|-------|--------|------| -| B.1 | Blog post: Wave 1 summary | McManus | 1h | After Wave 1 gate | -| B.2 | Blog post: Wave 2 summary | McManus | 1h | After Wave 2 gate | -| B.3 | Blog post: Wave 3 summary | McManus | 1h | After Wave 3 gate | - -Blog posts are wave gate exit criteria (same rule as README refresh — don't hold the gate, but publish before starting new feature work). - -**McManus owns all blog posts.** The content track already has McManus bandwidth between waves. This is additive but fits naturally. - -### 2c. Blog Engine Sample Prompt - -Add to `docs/sample-prompts.md` under a new section: - -**Proposed sample prompt:** - -``` -I need a developer blog engine with a polished front-end reading experience. -Requirements: -- Reads markdown files with YAML front matter (title, date, author, tags, summary) -- Renders blog posts from a docs/blog/ directory -- Beautiful, responsive reading experience — think Stripe's blog meets a personal dev blog -- Syntax highlighting for code blocks -- Tag-based filtering and archive page -- RSS feed generation -- Dark mode that doesn't suck -- Zero build step — serve directly or generate static HTML -- Landing page with latest 5 posts and tag cloud - -Tech: Node.js backend, vanilla HTML/CSS/JS frontend. No React, no frameworks. -Make it gorgeous. This blog tells the story of a product being built. -``` - -**What it demonstrates:** Full-stack coordination — backend API, frontend UX, markdown parsing, RSS generation, responsive design. Multiple agents working in parallel on different layers. The blog engine is non-trivial enough to show real Squad orchestration but scoped enough to ship in a session. - -**Meta value:** When we demo this prompt, the blog engine renders our own blog posts about building Squad. The demo creates the tool that tells the demo's story. - -### 2d. Agent Assignment - -- **McManus:** Writes blog posts, adds sample prompt to `docs/sample-prompts.md` -- **Blog post writing** slots into the content track (Wave 1.5 and beyond) -- **Sample prompt addition** is a one-time edit — McManus, Wave 1.5, ~30min - ---- - -## Directive 3: Package Naming — GitHub-Only Distribution - -**Brady said:** *"today the package is just bradygaster/squad. if we are going to do an export or an update - i'd love if folks could run an npx command to get an update to their squad without breaking their squad"* - -**Brady's subsequent decision (Session 6):** *No npm publish. Ever.* Squad is distributed exclusively via GitHub: `npx github:bradygaster/squad`. No npm registry involvement. - -### Current State - -- Package lives on GitHub: `bradygaster/squad` -- `npx github:bradygaster/squad` → init -- `npx github:bradygaster/squad upgrade` → upgrade -- Future: `npx github:bradygaster/squad export` → export - -### Analysis — SUPERSEDED - -The original analysis in this directive (Options A/B/C, `create-squad` npm registration) is **moot**. Brady has decided: no npm, no registry, no dual-publish. The distribution model is GitHub-only via `npx github:bradygaster/squad`. This is simpler, cleaner, and eliminates an entire class of maintenance (npm auth, publish CI, registry concerns). - -**What this means:** -- The "package name" is the GitHub repo name: `bradygaster/squad` -- Users run: `npx github:bradygaster/squad` (init), `npx github:bradygaster/squad upgrade` (upgrade) -- If Brady renames the repo, the npx command changes automatically -- No npm auth, no publish CI, no registry maintenance -- GitHub Releases and tags become the versioning and distribution mechanism (see Directive 6) - -### Sprint Plan Changes - -| ID | Item | Owner | Effort | Wave | -|----|------|-------|--------|------| -| ~~1.8~~ | ~~Register `create-squad` on npm, dual-publish setup~~ | ~~Fenster~~ | ~~1h~~ | **CANCELLED** | -| 1.5.1 | README uses `npx github:bradygaster/squad` as primary command | McManus | (part of README) | 1.5 | - -**Item 1.8 is CANCELLED.** No npm registration, no dual-publish. McManus updates all documentation to use `npx github:bradygaster/squad`. - ---- - -## Directive 4: Human Feedback as P0 - -**Brady said:** *"please please optimize for an efficient experience or a continually up-to-date one for the human. humans like feedback."* - -### Should This Be a 5th Directive? - -**Yes.** This is a distinct principle from the existing four. Here's where it differs: - -| Existing Directive | Scope | New Directive Scope | -|---|---|---| -| 1. Quality first | What we build first | — | -| 2. "Where are we?" | One specific feature | — | -| 3. Human input responsiveness | Input → system | — | -| 4. "Feels heard" | Immediate acknowledgment | — | -| **5. Human feedback optimization** | **System → human, continuously** | **Every interaction, every output** | - -Directives 3 and 4 are about input (human → system). Directive 5 is about output (system → human). It's the other direction. The coordinator says "got it" (Directive 4), but then the user waits 45 seconds with no indication of progress. THAT is what Directive 5 addresses. - -### The 5th Directive - -> **5. Optimize for human feedback.** Every interaction should give the human visible evidence of progress. If work takes time, report what's happening. If there's a result, surface it clearly. Silence is never acceptable. The human should always know what's happening, what just happened, or what's about to happen. - -### What in 019 Already Serves This - -| Item | How It Serves Directive 5 | -|------|--------------------------| -| 1.7 "Feels heard" | Immediate ack — covers the first 2 seconds | -| 2.1 Tiered modes (Direct) | Fast answers for simple questions — covers trivial interactions | -| 1.5 Silent success fix | Prevents the worst case: work done, no output | -| 1.1 Error handling | Clear error messages instead of stack traces | - -### What's Missing - -1. **Progress reporting during multi-agent work.** When the coordinator spawns 3 agents, the human sees nothing until all 3 finish. The coordinator should report: "Spawned Fenster (error handling), Hockney (tests), Verbal (prompts). Waiting for results..." and ideally update as each completes. - -2. **Result summarization after agent work.** When agents finish, the coordinator should synthesize: "All 3 agents completed. Fenster added error handling to index.js. Hockney wrote 8 new tests. Verbal updated 2 spawn prompts. Details in their reports." This is the "what just happened" leg. - -3. **CLI output improvements.** `npx github:bradygaster/squad` currently outputs checkmarks. It should also explain what was created and what to do next. (Partially exists — the "Next steps" block is good, but the file list needs context.) - -### Sprint Plan Changes - -| ID | Item | Owner | Effort | Wave | Description | -|----|------|-------|--------|------|-------------| -| 1.9 | Progress reporting in coordinator | Verbal + Kujan | 2h | 1 | Coordinator reports agent spawn status and per-agent completion | -| 2.1+ | Result summarization | Verbal | (part of 2.1) | 2 | Coordinator synthesizes multi-agent results after fan-out | -| 1.1+ | CLI output enrichment | Fenster | (part of 1.1) | 1 | Enhanced init/upgrade output with context | - -**New directive added to the Directives section of 019.** - ---- - -## Directive 5: VS Code Parity - -**Brady said:** *"is there any reason why things wouldn't 'just work' in vs code"* - -### Analysis - -Squad's architecture is platform-agnostic by design: -- `squad.agent.md` in `.github/agents/` — this IS the VS Code Copilot agent path. Same file, same location. -- All agent interactions use `task`, `powershell`, `view`, `edit`, `grep`, `glob` — tools available in both CLI and VS Code Copilot. -- Filesystem-backed memory (`.ai-team/`) is IDE-independent. -- No CLI-specific APIs, no terminal-only features. - -**There is no architectural reason Squad wouldn't work in VS Code.** The agent file format, tool availability, and spawn mechanics are identical. If Kujan confirms this after testing, VS Code is a zero-effort additional platform. - -### What Might Differ - -1. **Tool availability nuances.** VS Code Copilot Chat may have slightly different tool implementations (e.g., terminal handling, file watching). Needs manual testing. -2. **Context window limits.** VS Code may have different token budgets than CLI. The coordinator's ~1,900-token overhead should be fine everywhere, but agent spawn prompts that approach limits might behave differently. -3. **Background agent behavior.** `mode: "background"` agents and `detach: true` may have different behavior in VS Code's integrated terminal vs standalone CLI. - -### Sprint Plan Changes - -| ID | Item | Owner | Effort | Wave | Description | -|----|------|-------|--------|------|-------------| -| 1.10 | VS Code parity smoke test | Kujan | 1h | 1 | Manual test: init, team mode, parallel spawn, "where are we?" in VS Code | -| 1.3+ | CI: consider VS Code test | Hockney | (investigation only) | 1 | Investigate if automated VS Code testing is feasible for CI | - -**Kujan** runs a manual smoke test in Wave 1. If parity is confirmed (expected), we document "Works in both CLI and VS Code" in the README. If there are gaps, we file them as Wave 2 items. - -**CI for VS Code:** Automated VS Code extension testing requires `vscode-test` or similar — heavyweight and fragile. **Not recommended for v1 CI.** Manual smoke test per wave is sufficient. Document the test checklist so any team member can run it. - ---- - -## Summary of All Sprint Plan Changes - -### New Items - -| ID | Item | Owner | Effort | Wave | -|----|------|-------|--------|------| -| ~~1.8~~ | ~~Register `create-squad` on npm~~ | ~~Fenster~~ | ~~1h~~ | **CANCELLED** (Directive 6) | -| 1.9 | Progress reporting in coordinator | Verbal + Kujan | 2h | 1 | -| 1.10 | VS Code parity smoke test | Kujan | 1h | 1 | -| 1.11 | Release workflow (GitHub Actions) | Kobayashi | 2h | 1 | -| 1.12 | Branch strategy and merge to main | Kobayashi | 1-2h | 1 | -| 1.13 | First tagged release (v0.1.0) | Kobayashi | 1h | 1 (gate exit) | -| B.1 | Blog post: Wave 1 | McManus | 1h | Post-Wave 1 | -| B.2 | Blog post: Wave 2 | McManus | 1h | Post-Wave 2 | -| B.3 | Blog post: Wave 3 | McManus | 1h | Post-Wave 3 | - -### Modified Items - -| ID | Change | -|----|--------| -| 1.3 | CI setup: **Hockney + Kobayashi** (Kobayashi owns the Actions workflow, Hockney owns test content) | -| 1.5.1 | README scope: current-state only, updated per wave | -| 1.1 | Added: CLI output enrichment for human feedback | -| 2.1 | Added: result summarization after multi-agent fan-out | - -### New Recurring Items - -| Item | Owner | Effort | When | -|------|-------|--------|------| -| README refresh | McManus | 30min | Each wave gate exit | -| Blog post | McManus | 1h | Each wave gate exit | - -### New Directive (added to 019 §Directives) - -> **5. Optimize for human feedback.** Every interaction gives the human visible evidence of progress. Silence is never acceptable. - -### New Content - -| Item | Location | Owner | -|------|----------|-------| -| Blog post format spec | `docs/blog/` (directory) | McManus | -| Blog engine sample prompt | `docs/sample-prompts.md` | McManus | - -### Updated Effort Total - -| Category | 019 Estimate | 019a Additions | New Total | -|----------|-------------|----------------|-----------| -| Wave 1 | 11-14h | +7-8h (1.9, 1.10, 1.11, 1.12, 1.13; 1.8 cancelled) | 18-22h | -| Wave 1.5/Content | 9-13h | +4.5h (blog posts, sample prompt, README refreshes) | 13.5-17.5h | -| Wave 2 | 12-16h | (absorbed into existing items) | 12-16h | -| Wave 3 | 12-16h | (absorbed into existing items) | 12-16h | -| **Total** | **44-59h** | **+11.5-12.5h** | **55.5-71.5h** | - -Calendar impact: moderate. New Wave 1 items (1.9, 1.10, 1.11, 1.12) all parallelize with existing work. Item 1.13 (first tagged release) is a Wave 1 gate exit criterion — it runs after the gate passes but before Wave 2 features begin. Kobayashi's work is entirely additive and does not block existing agents. Item 1.8 (npm registration) is cancelled, removing 1h. - ---- - -## Updated Wave 1 Parallelism - -``` -Day 1-2: Day 2-4: -├── 1.1 Error handling (Fenster) └── 1.2 Test expansion (Hockney) ← needs 1.1 -├── 1.3 CI setup (Hockney + Kobayashi) ← UPDATED: Kobayashi owns Actions workflow -├── 1.4 Version stamping (Fenster) -├── 1.5 Silent success (Verbal) -├── 1.6 Human directive capture (Kujan) -├── 1.7 Feels heard behavior (Verbal) -├── 1.9 Progress reporting (Verbal + Kujan) ← NEW -├── 1.10 VS Code smoke test (Kujan) ← NEW -├── 1.11 Release workflow (Kobayashi) ← NEW -└── 1.12 Branch strategy (Kobayashi) ← NEW - -Wave 1 Gate Exit: -├── 1.13 First tagged release v0.1.0 (Kobayashi) ← NEW (gate exit criterion) -├── README refresh (McManus) -└── Blog post: Wave 1 (McManus) -``` - ---- - -## Directive 6: GitHub-Only Distribution & Release Process - -**Source:** Brady's session 6 decisions — no npm, Kobayashi hired, release plan needed. - -### What Changed - -Brady made three decisions that fundamentally affect the distribution and release model: - -1. **No npm publish. Ever.** Squad is distributed exclusively via `npx github:bradygaster/squad`. The npm registry is not involved. Item 1.8 (register `create-squad` on npm) is **CANCELLED**. My recommendation to register the unscoped name was rejected — and Brady's right. GitHub-only distribution is simpler, eliminates npm auth/publish/registry maintenance, and keeps the entire project lifecycle on one platform. - -2. **Kobayashi (Git & Release Engineer) joins the team.** Dedicated specialist for ALL git and GitHub responsibilities: releases, tags, branch strategy, CI/CD workflows, state integrity. Git IS our state maintenance layer — the `.ai-team/` directory, the drop-box pattern, orchestration logs, casting registry. A dedicated owner for git operations is the right call. - -3. **Release workflow needed.** Proper GitHub Releases with tags, versioning, changelogs. Kobayashi is writing the detailed proposal (021), but release work slots into Wave 1 immediately. - -### Team Roster Update - -**Kobayashi — Git & Release Engineer** is added to the team: - -| Agent | Role | Responsibilities | -|-------|------|-----------------| -| **Kobayashi** | Git & Release Engineer | GitHub Releases, tags, versioning, branch strategy, CI/CD workflows, GitHub Actions, state integrity, merge-to-main process | - -Kobayashi owns the intersection of git and GitHub that touches every other agent's work. When Hockney writes tests, Kobayashi ensures CI runs them. When Fenster ships features, Kobayashi tags the release. When the team merges to main, Kobayashi owns the process. - -### Cancelled Items - -| ID | Item | Reason | -|----|------|--------| -| ~~1.8~~ | ~~Register `create-squad` on npm, dual-publish setup~~ | Brady: no npm, ever. GitHub-only distribution. | - -### New Items - -| ID | Item | Owner | Effort | Depends On | Wave | -|----|------|-------|--------|------------|------| -| **1.11** | Release workflow (GitHub Actions) | Kobayashi | 2h | 1.3 (CI foundation) | 1 | -| **1.12** | Branch strategy and merge to main | Kobayashi | 1-2h | — | 1 | -| **1.13** | First tagged release (v0.1.0) | Kobayashi | 1h | Wave 1 gate (all items pass) | 1 (gate exit) | - -#### 1.11 Release Workflow (GitHub Actions) - -**Owner:** Kobayashi -**Effort:** 2 hours -**Depends on:** 1.3 (CI must exist as the foundation) - -**What ships:** -- `.github/workflows/release.yml` — triggered on tag push or manual dispatch -- Creates a GitHub Release with auto-generated changelog from commits -- Attaches version metadata -- Validates that tests pass before release is published -- No npm publish step — the release IS the distribution (users pull via `npx github:bradygaster/squad`) - -**Detail:** Kobayashi is writing the full proposal (021) with implementation specifics. This item slots the work into the wave structure. - -#### 1.12 Branch Strategy and Merge to Main - -**Owner:** Kobayashi -**Effort:** 1-2 hours -**Depends on:** Nothing - -**What ships:** -- Documented branch strategy (main as release branch, feature branches for work) -- Branch protection rules for main (require CI pass, require review) -- Merge process documentation for the team -- `.ai-team/` state integrity verification on merge (ensure no conflicting writes) - -#### 1.13 First Tagged Release (v0.1.0) - -**Owner:** Kobayashi -**Effort:** 1 hour -**Depends on:** Wave 1 gate must be GREEN - -**What ships:** -- First official GitHub Release: `v0.1.0` -- Changelog summarizing everything shipped in Wave 1 -- Tag on main branch -- Validates the release workflow (1.11) works end-to-end - -**This is a Wave 1 gate EXIT criterion.** The gate must pass first (tests, CI, error handling, etc.), then Kobayashi cuts the release before Wave 2 features begin. No feature work starts on Wave 2 until v0.1.0 is tagged and released. - -### Modified Items - -| ID | Original Owner | New Owner | Change | -|----|---------------|-----------|--------| -| **1.3** | Hockney | **Hockney + Kobayashi** | Kobayashi owns the GitHub Actions workflow definition and CI infrastructure. Hockney owns the test content that CI runs. Split responsibility — Hockney shouldn't need to know Actions YAML, Kobayashi shouldn't need to know test assertions. | - -### npm Reference Updates - -All references to npm registration, dual-publish, and `create-squad` unscoped naming in this document have been updated: - -| Location | Before | After | -|----------|--------|-------| -| Directive 3 title | "Package Naming" | "Package Naming — GitHub-Only Distribution" | -| Directive 3 analysis | Options A/B/C with npm registration recommendation | Marked SUPERSEDED — GitHub-only per Brady's decision | -| Directive 3 sprint changes | Item 1.8 active | Item 1.8 CANCELLED | -| Blog post code example | `npx @bradygaster/create-squad upgrade` | `npx github:bradygaster/squad upgrade` | -| Summary new items table | Item 1.8 listed | Item 1.8 marked CANCELLED | -| Effort totals | +4h for 1.8/1.9/1.10 | 1.8 removed, 1.11/1.12/1.13 added | - -### Updated Agent Workload Summary (Wave 1 Only) - -| Agent | Wave 1 Items | Effort | -|-------|-------------|--------| -| **Fenster** | 1.1 (2h), 1.4 (1-2h) | 3-4h | -| **Hockney** | 1.2 (3-4h), 1.3 test content (0.5h) | 3.5-4.5h | -| **Verbal** | 1.5 (2h), 1.7 (1h), 1.9 shared (1h) | 4h | -| **Kujan** | 1.6 (1h), 1.9 shared (1h), 1.10 (1h) | 3h | -| **Kobayashi** | 1.3 Actions workflow (0.5h), 1.11 (2h), 1.12 (1-2h), 1.13 (1h) | 4.5-5.5h | -| **McManus** | (Wave 1.5 — no Wave 1 items) | — | -| **Keaton** | Review all gates | Continuous | - -### Impact on Wave 1 Gate - -The Wave 1 gate criteria from 019 are updated: - -- [ ] `npm test` passes 20+ tests covering init, upgrade, flags, error cases, and exit codes -- [ ] CI runs on every push and PR — `.github/workflows/ci.yml` exists and is green -- [ ] index.js has zero unhandled exceptions on any filesystem error -- [ ] `squad.agent.md` has a version header -- [ ] `upgrade` reports version deltas -- [ ] Silent success rate is measured and documented -- [ ] Coordinator captures human directives to inbox before routing -- [ ] Coordinator acknowledges user messages with immediate text before tool calls -- [ ] **NEW:** Branch strategy documented and protection rules applied -- [ ] **NEW (gate exit):** Release workflow tested and v0.1.0 tagged on GitHub Releases - ---- - -**Review requested from:** bradygaster -**Approved by:** Keaton (Lead) — these amendments strengthen 019 -**Next action:** Team reviews, Brady approves, then merge into 019 or execute alongside it diff --git a/team-docs/proposals/020-blog-and-packaging.md b/team-docs/proposals/020-blog-and-packaging.md deleted file mode 100644 index aefce1436..000000000 --- a/team-docs/proposals/020-blog-and-packaging.md +++ /dev/null @@ -1,262 +0,0 @@ -# Proposal 020: Blog Format, Blog Engine Prompt, and Package Naming UX - -**Status:** Approved ✅ Shipped. Note: npm publishing recommendations in §3 are superseded — distribution is GitHub-only via `npx github:bradygaster/squad` per Proposal 019a. -**Author:** McManus (DevRel) -**Date:** 2026-02-09 -**Requested by:** bradygaster -**Depends on:** Proposal 019 (Master Sprint Plan), Proposal 014 (V1 Messaging) - ---- - -## Executive Summary - -Three things from Brady, all connected by the same thread: **make Squad's progress visible and its install experience frictionless.** - -1. A blog markdown format for progress updates — each wave = a blog post. -2. A sample prompt for a blog engine that renders those posts — Squad builds the tool that tells Squad's story. -3. A DevRel evaluation of the npx package naming for clarity and discoverability. - ---- - -## 1. Blog Markdown Format - -### Design Principles - -- **Human-readable raw.** Someone reading the markdown on GitHub should get the full story without rendering. -- **Machine-renderable.** YAML frontmatter follows static site generator conventions (Jekyll, Hugo, Eleventy, any custom engine). -- **One post per wave.** Wave completion = blog post. The cadence is the content strategy. -- **Story, not changelog.** Each post has a narrative arc — what happened, what surprised us, what we learned. Changelogs are for CHANGELOG.md. - -### Frontmatter Schema - -```yaml ---- -title: "Wave X: [Title]" # Human title — the hook -date: YYYY-MM-DD # Publication date -author: "[Agent Name] ([Role])" # Who wrote it — always an agent -wave: X # Wave number (0, 1, 2, 3...) -tags: [squad, wave-X, ...] # For filtering and taxonomy -status: published # published | draft -hero: "[One-line hook]" # Scroll-stopper sentence ---- -``` - -### Post Structure - -Every post follows the same skeleton: - -1. **Hero sentence** — repeated from frontmatter, sets the tone -2. **What Shipped** — bullet list of concrete deliverables with agent attribution -3. **The Story** — narrative (2-4 paragraphs), written like you're telling a friend -4. **By the Numbers** — metrics table (proposals, tests, agents, human messages, custom) -5. **What We Learned** — 2-3 lasting insights -6. **What's Next** — 1-2 sentences teasing the next wave -7. **Footer** — agent attribution + link to Squad repo - -### Files - -- **Template:** `docs/blog/template.md` -- **First post:** `docs/blog/001-wave-0-the-team-that-built-itself.md` - -### Why This Format Works - -- Frontmatter is compatible with every static site generator on earth -- `wave` field enables filtering, navigation ("← Wave 0 | Wave 1 →"), and programmatic rendering -- `hero` field gives the blog engine a subtitle/deck without parsing the body -- `author` field with agent name + role reinforces the "team that writes about itself" narrative -- `status` field supports drafts in the repo without publishing them -- `tags` enable cross-cutting views (all posts about testing, all posts mentioning a specific agent) - ---- - -## 2. Blog Engine Sample Prompt - -### The Meta Angle - -Squad builds a blog engine. The blog engine renders Squad's own progress posts. Squad built the tool that tells Squad's story. That's the demo. - -### The Prompt - -Added to `docs/sample-prompts.md` as a new entry in Quick Builds: - -``` -Build a static blog engine that renders markdown blog posts into beautiful HTML pages. -No frameworks — just HTML, CSS, and vanilla JavaScript. - -Input: markdown files from a docs/blog/ directory. Each file has YAML frontmatter -(title, date, author, wave, tags, status, hero). - -Output: -- An index page listing all posts, sorted by date, with title, hero text, author, and tags -- Individual post pages with clean typography, syntax-highlighted code blocks, and responsive tables -- A tag index page that groups posts by tag -- Wave navigation: "← Previous Wave | Next Wave →" links on each post -- Dark mode toggle (CSS custom properties, saved to localStorage) -- RSS feed (feed.xml) - -Design direction: -- Clean, modern, developer-focused. Think GitHub's blog meets a personal dev blog. -- Monospace headings, proportional body text -- Code blocks with a dark theme and copy-to-clipboard button -- Mobile responsive — single column on small screens -- Fast. No JavaScript required for reading — JS only for dark mode toggle and copy button. -- Hero section on the index page with the blog title and a one-liner about the project. - -The markdown parser should handle: headings, paragraphs, lists, code blocks (fenced), -inline code, bold, italic, links, images, blockquotes, horizontal rules, and tables. - -Build the parser, the template engine, the RSS generator, and the static file output. -Put the output in a dist/ folder. Include a build script that can be run with -`node build.js` to regenerate the site. - -Set up the team and build it. I want to see this running in one session. -``` - -**What it demonstrates:** Squad builds the tool that publishes its own story. Input is markdown files that Squad already writes. The blog engine is a self-contained, single-session project — parser, templating, RSS, responsive CSS — with clear parallel work splits. The meta angle makes the demo land twice: once for the technical execution, once for the narrative ("Squad built this to tell you about itself"). - -### Why It Belongs in Sample Prompts - -- It's a legitimate Quick Build — single session, well-scoped, clear output -- It demonstrates parallel fan-out: parser agent, template agent, CSS agent, RSS agent, tester -- It produces a visual artifact (a rendered blog) that screenshots beautifully -- It uses Squad's own content as input — zero setup, instant payoff -- It's the ultimate "eating our own cooking" demo - ---- - -## 3. Package Naming UX Evaluation - -### Current State - -The package is published as `@bradygaster/create-squad` on npm. Users run: - -```bash -npx @bradygaster/create-squad # init -npx @bradygaster/create-squad upgrade # upgrade -npx @bradygaster/create-squad help # help -npx @bradygaster/create-squad --version # version -``` - -### Evaluation of Naming Options - -#### Option A: `@bradygaster/create-squad` (current) - -| Dimension | Assessment | -|-----------|-----------| -| **Clarity** | ⚠️ Mixed. `create-squad` is clear — it creates a squad. The `@bradygaster/` scope adds 13 characters and makes every command longer. | -| **Discoverability** | ⚠️ Scoped packages don't appear in `npx ` auto-suggestions. Users must know the exact scope. | -| **Trust signal** | ✅ The scope signals personal ownership — "this is Brady's project." For early-stage OSS, this is actually a positive trust signal. | -| **Typing burden** | ❌ `npx @bradygaster/create-squad` is 33 characters. That's a lot to type correctly from a README. | -| **npm convention** | ✅ Follows `create-*` convention that `npm init` understands: `npm init @bradygaster/squad` works. | - -#### Option B: `create-squad` (unscoped) - -| Dimension | Assessment | -|-----------|-----------| -| **Clarity** | ✅ Crystal clear. `npx create-squad` — no ambiguity. | -| **Discoverability** | ✅ Unscoped names are globally discoverable. `npx create-squad` just works. | -| **Trust signal** | ⚠️ Loses the personal attribution. But the README and repo URL provide that. | -| **Typing burden** | ✅ `npx create-squad` is 16 characters. Half the current command. | -| **npm convention** | ✅ Perfect `create-*` convention. `npm init squad` would also work. | -| **Risk** | ⚠️ Name squatting. Someone else could register `create-squad` first. Need to check availability. | - -#### Option C: `squad-cli` - -| Dimension | Assessment | -|-----------|-----------| -| **Clarity** | ⚠️ "CLI" is a developer term — clear to the target audience but doesn't describe what it does. | -| **Discoverability** | ✅ Unscoped, short, memorable. | -| **Trust signal** | ⚠️ Same as Option B — no personal attribution. | -| **Typing burden** | ✅ `npx squad-cli` is 13 characters. Short. | -| **npm convention** | ❌ Breaks `create-*` convention. `npm init squad-cli` doesn't make sense. Loses `npm init` integration. | -| **Semantic problem** | ❌ It's not really a CLI tool with ongoing commands. It's a project initializer. `create-*` is honest. `squad-cli` implies a tool you keep running. | - -### Command-by-Command UX Evaluation - -Here's what users actually type, and how each name feels: - -| Action | Current | With `create-squad` | With `squad-cli` | -|--------|---------|-------------------|-----------------| -| **First install** | `npx @bradygaster/create-squad` | `npx create-squad` | `npx squad-cli` | -| **Upgrade** | `npx @bradygaster/create-squad upgrade` | `npx create-squad upgrade` | `npx squad-cli upgrade` | -| **Check version** | `npx @bradygaster/create-squad --version` | `npx create-squad --version` | `npx squad-cli --version` | -| **Get help** | `npx @bradygaster/create-squad help` | `npx create-squad help` | `npx squad-cli help` | -| **npm init style** | `npm init @bradygaster/squad` | `npm init squad` | ❌ doesn't work | - -**The upgrade command is the critical test.** Users will run this command repeatedly over months. Every character matters. `npx create-squad upgrade` reads naturally — "create-squad, but actually, upgrade." `npx squad-cli upgrade` also works but loses the `create-*` lineage. - -### README Quick Start Comparison - -How it looks in the first 30 seconds: - -**Current:** -```bash -npx @bradygaster/create-squad -``` -> 33 characters. The `@bradygaster/` scope makes a new dev pause: "Is that a username? Do I need an account?" It's a speed bump in the Quick Start. - -**Recommended:** -```bash -npx create-squad -``` -> 16 characters. Zero ambiguity. Zero hesitation. Paste and go. - -**Alternative:** -```bash -npx squad-cli -``` -> 13 characters. Shorter, but "CLI" adds no value and loses `create-*` semantics. - -### Recommendation: Publish `create-squad` (unscoped) alongside `@bradygaster/create-squad` - -**Do both.** npm supports this. - -1. **Register `create-squad`** as an unscoped package that points to the same code. -2. **Keep `@bradygaster/create-squad`** as the scoped package — existing users aren't broken. -3. **README and all docs use `create-squad`** — the short, clean version. -4. **`npm init squad`** works automatically with unscoped `create-squad`. - -This gives us: -- ✅ Clean Quick Start: `npx create-squad` -- ✅ Clean upgrade: `npx create-squad upgrade` -- ✅ `npm init squad` for free -- ✅ No breaking change for existing users -- ✅ Personal attribution in repo, README, and scoped package - -### Implementation - -1. Add `"name": "create-squad"` to a new `package.json` (or rename the current one and keep `@bradygaster/create-squad` as an alias). -2. Alternatively: publish the scoped version and register `create-squad` as a redirect package (1 line: `#!/usr/bin/env node\nrequire('@bradygaster/create-squad')`). -3. Update README Quick Start to use `npx create-squad`. -4. Update help text in `index.js` to reference `create-squad` (line 24). - -**Effort:** ~30 minutes. This is a naming change, not an architecture change. - -### What NOT to Do - -- ❌ Don't rename to `squad-cli` — it breaks `create-*` convention and misrepresents the tool. -- ❌ Don't drop the scoped package — existing users have it in their shell history. -- ❌ Don't overthink this — the package name is a 10-second interaction. Make it short, make it obvious, move on. - ---- - -## Summary - -| Deliverable | Location | Status | -|-------------|----------|--------| -| Blog post template | `docs/blog/template.md` | ✅ Created | -| First blog post (Wave 0) | `docs/blog/001-wave-0-the-team-that-built-itself.md` | ✅ Created | -| Blog engine sample prompt | `docs/sample-prompts.md` (new entry) | ✅ Added | -| Package naming evaluation | This document, §3 | ✅ Complete | -| Package naming recommendation | Publish `create-squad` unscoped | Proposed | - ---- - -## Endorsement - -**McManus:** Three deliverables, one thread: make Squad visible and frictionless. The blog format gives us a content cadence tied to execution (wave = post). The blog engine prompt is the ultimate meta-demo — Squad builds the tool that tells its own story. And the package name? `npx create-squad` is half the characters, zero the confusion, and follows the exact convention that `create-react-app`, `create-next-app`, and `create-vite` established. Ship the unscoped name, keep the scoped one alive, update the README. Thirty minutes of work for a permanent UX win. - -**Review requested from:** -- Brady — naming decision is yours. Both names can coexist on npm. -- Keaton — any concerns about maintaining two package names? -- Fenster — implementation detail: redirect package vs rename? diff --git a/team-docs/proposals/021-release-plan-and-distribution.md b/team-docs/proposals/021-release-plan-and-distribution.md deleted file mode 100644 index b8dedbd84..000000000 --- a/team-docs/proposals/021-release-plan-and-distribution.md +++ /dev/null @@ -1,519 +0,0 @@ -# Proposal 021: Release Plan & Distribution Strategy - -**Status:** Approved ✅ Shipped -**Authored by:** Kobayashi (Git & Release Engineer) -**Date:** 2025-07-16 -**Requested by:** bradygaster -**Relates to:** Proposal 019 §1.3 (CI), §1.4 (Version Stamping), Brady's no-npm directive - ---- - -## What This Document Is - -The definitive release and distribution plan for Squad. Covers how code gets from `dev` branch to users' machines, how versions are tagged, how releases are cut, and how we guarantee `.ai-team/` state integrity through every upgrade. - -**Non-negotiable constraint:** No npm publish. Ever. Squad is distributed exclusively via `npx github:bradygaster/squad`. - ---- - -## 1. Distribution via GitHub (Not npm) - -### How `npx github:bradygaster/squad` Works - -When a user runs `npx github:bradygaster/squad`: - -1. npm resolves `github:bradygaster/squad` as a GitHub repository reference -2. It clones/downloads the repo's **default branch** (`main`) -3. It reads `package.json`, finds the `bin` entry (`create-squad` → `./index.js`) -4. It executes `index.js` in a temporary directory, passing any CLI arguments - -**Key implication:** Without tags, users always get `HEAD` of `main`. This is unstable — a half-merged PR on `main` ships to every user immediately. - -### Version Pinning Syntax - -The `@` syntax does NOT work for GitHub-hosted packages. The correct syntax uses `#`: - -| Command | What It Pulls | -|---------|---------------| -| `npx github:bradygaster/squad` | HEAD of default branch (`main`) | -| `npx github:bradygaster/squad#v0.2.0` | Exact tag `v0.2.0` | -| `npx github:bradygaster/squad#main` | HEAD of `main` | -| `npx github:bradygaster/squad#dev` | HEAD of `dev` | -| `npx github:bradygaster/squad#abc1234` | Exact commit SHA | - -**This means:** -- Users CAN pin versions: `npx github:bradygaster/squad#v0.2.0` -- The default (no `#`) always pulls `main` HEAD -- We MUST keep `main` in a release-worthy state at all times - -### Tag Format - -**Standard:** `v{MAJOR}.{MINOR}.{PATCH}` — e.g., `v0.1.0`, `v0.2.0`, `v0.2.1` - -- Follows semver exactly -- The `v` prefix is a universal convention for git tags (matches GitHub Releases UI) -- Tags are immutable — once `v0.2.0` is tagged, it never moves - -### Ensuring Users Get the Latest Release - -Since `npx github:bradygaster/squad` pulls `main` HEAD (not the latest tag), we have two strategies: - -**Strategy A: Main IS the latest release (Recommended)** -- `main` only receives code via the release workflow -- The release workflow filters `dev`, keeping only product files, and commits to `main` -- `main` HEAD is always the latest tagged release — no Squad Squad files, no docs, no tests - -**Strategy B: Latest-tag redirect in code** -- `upgrade` subcommand reads the GitHub API to find the latest release tag -- Adds complexity, requires network calls, fragile -- NOT recommended for v1 - -**Decision: Strategy A.** Keep `main` clean. Develop on `dev`. The release workflow (`.github/workflows/release.yml`) filters `dev` to product-only files and commits to `main`. Tag the commit on `main`. - -### The `upgrade` Subcommand - -`npx github:bradygaster/squad upgrade` currently works by re-running `index.js` from whatever version npx resolves. With Strategy A: - -1. User runs `npx github:bradygaster/squad upgrade` -2. npx fetches `main` HEAD (which IS the latest release) -3. `index.js` runs in upgrade mode — overwrites Squad-owned files, never touches `.ai-team/` -4. User gets the latest release automatically - -For pinned users: `npx github:bradygaster/squad#v0.2.0 upgrade` — upgrades to that specific version. - ---- - -## 2. Semantic Versioning Strategy - -### Pre-v1 Rules - -We're at `0.1.0`. Pre-v1 semver rules: - -| Change Type | Version Bump | Example | -|-------------|-------------|---------| -| Breaking change to init/upgrade behavior | Minor bump | `0.1.0` → `0.2.0` | -| New subcommand (export, import) | Minor bump | `0.2.0` → `0.3.0` | -| Bug fix, test addition, prompt change | Patch bump | `0.1.0` → `0.1.1` | -| Template/agent content update only | Patch bump | `0.1.1` → `0.1.2` | - -### Version Locations - -The version lives in exactly ONE place: `package.json` `"version"` field. All other version references derive from it: - -- `--version` flag reads `package.json` -- `squad.agent.md` version comment (when 1.4 ships) is stamped during release -- Git tag matches `package.json` version - -### What Triggers a Release? - -| Trigger | Version Bump | Example | -|---------|-------------|---------| -| Wave gate passes | Minor | Wave 1 complete → `v0.2.0` | -| Critical bug fix | Patch | Broken upgrade → `v0.1.1` | -| Brady's call | Either | "Ship this now" → whatever's appropriate | - -**No pre-release/RC process for v0.x.** We're pre-v1, everything is effectively a pre-release. Ship when ready. - ---- - -## 3. Release Process Checklist - -This is the manual process for cutting a release. Later we automate parts of it with GitHub Actions. - -### Pre-Release - -- [ ] All tests pass on `dev`: `npm test` -- [ ] Version in `package.json` is bumped to the new version -- [ ] CHANGELOG.md is updated with release notes (when it exists — McManus owns this, Wave 1.5) -- [ ] If version stamping exists (1.4): `squad.agent.md` has the correct version comment - -### Cut the Release - -```bash -# 1. Ensure dev is clean and up to date -git checkout dev -git pull origin dev - -# 2. Bump version in package.json (if not already done) -# Edit package.json "version" field - -# 3. Commit the version bump -git add package.json -git commit -m "chore: bump version to 0.2.0" -git push origin dev - -# 4. Option A: Trigger via workflow_dispatch (manual) -# Go to Actions → Release → Run workflow → enter version "0.2.0" - -# 5. Option B: Trigger via tag push -git tag -a v0.2.0 -m "Release v0.2.0" -git push origin v0.2.0 -``` - -The release workflow (`.github/workflows/release.yml`) then: -1. Runs tests on `dev` -2. Checks out `dev`, filters to product-only files -3. Commits the filtered content to `main` -4. Tags the commit on `main` -5. Creates a GitHub Release (marked `prerelease` for pre-v1) -6. Verifies `npx` resolution - -### Post-Release - -- [ ] Create GitHub Release from the tag (manual or automated — see §4) -- [ ] Verify: `npx github:bradygaster/squad --version` outputs new version -- [ ] Verify: `npx github:bradygaster/squad#v0.2.0 --version` outputs new version -- [ ] Verify: upgrade path works — init with old version, upgrade with new version, `.ai-team/` intact -- [ ] Announce: blog post (McManus), README badge update if applicable - ---- - -## 4. GitHub Actions Workflows - -### 4a. CI Workflow (`.github/workflows/ci.yml`) - -Runs on every push and pull request. This is Sprint Plan item 1.3. - -```yaml -name: CI - -on: - push: - branches: [main, dev] - pull_request: - branches: [main, dev] - -jobs: - test: - name: Test - runs-on: ubuntu-latest - strategy: - matrix: - node-version: [22.x] - - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Setup Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v4 - with: - node-version: ${{ matrix.node-version }} - - - name: Run tests - run: npm test - - - name: Verify init works - run: | - mkdir -p /tmp/squad-smoke-test - node index.js - working-directory: /tmp/squad-smoke-test - env: - SQUAD_ROOT: ${{ github.workspace }} - - - name: Verify upgrade preserves .ai-team/ - run: | - mkdir -p /tmp/squad-upgrade-test - cd /tmp/squad-upgrade-test - node ${{ github.workspace }}/index.js - echo "user state" > .ai-team/decisions/inbox/test-state.md - node ${{ github.workspace }}/index.js upgrade - test -f .ai-team/decisions/inbox/test-state.md || (echo "FAIL: .ai-team/ state was corrupted" && exit 1) - echo "PASS: .ai-team/ state preserved after upgrade" -``` - -**Notes:** -- The smoke test runs `index.js` against a temp directory to verify init works -- The upgrade test verifies `.ai-team/` state preservation — this is our state integrity canary -- Node 22.x only (per `engines` field from Sprint Plan 1.4) -- Matrix can expand to Windows (`windows-latest`) later if needed - -### 4b. Release Workflow (`.github/workflows/release.yml`) - -Triggered manually via `workflow_dispatch` or when a version tag is pushed. Filters `dev` to product-only files, commits to `main`, tags, and creates a GitHub Release. - -**Key design decisions:** -- **Filtered copy, not git merge** — `main` never sees Squad Squad files, docs, tests, or workflow YAML -- Tests run BEFORE the release is created — a failing test prevents a broken release -- Tag-to-`package.json` version validation prevents mismatched tags -- `generate_release_notes: true` uses GitHub's auto-generated changelog (commit-based) -- Custom release body includes install/upgrade/pin instructions -- Pre-v1 releases are marked as `prerelease: true` -- Post-release verification confirms `npx` resolution works -- Product files explicitly kept: `index.js`, `package.json`, `README.md`, `LICENSE`, `.gitignore`, `.npmignore`, `.gitattributes`, `.github/agents/squad.agent.md`, `templates/` - -See `.github/workflows/release.yml` for the full implementation. - ---- - -## 5. Branch Strategy - -### Current State - -- `main` branch exists (remote and local) — product-only, no Squad Squad files -- `dev` branch is the active development branch (renamed from `squadify`) -- `dev` is public — Squad Squad visibility is intentional (dog-fooding story) -- No branch protection rules - -### Target State - -``` -main ← product-only; always stable; this is what users get via npx - ↑ (no .ai-team/, docs/, test/, orchestration logs) -dev ← primary development branch; Squad Squad lives here - ↑ -feature/* ← optional feature branches off dev -``` - -### Branch Rules - -| Branch | Who Pushes | What Gets Pushed | Protection | -|--------|-----------|------------------|------------| -| `main` | Release workflow only | Filtered product files + version tags | Protected: no direct push, no force push | -| `dev` | All agents | Feature work, bug fixes, proposals, Squad Squad | Default dev branch | -| `feature/*` | Individual agents | Scoped work for complex features | None — merge to `dev` when done | - -### What Goes Where - -| Content | `dev` | `main` | -|---------|-------|--------| -| `index.js`, `package.json`, `README.md` | ✅ | ✅ | -| `templates/` | ✅ | ✅ | -| `.github/agents/squad.agent.md` | ✅ | ✅ | -| `LICENSE`, `.gitignore`, `.npmignore`, `.gitattributes` | ✅ | ✅ | -| `.ai-team/` (Squad Squad state) | ✅ | ❌ | -| `.ai-team-templates/` | ✅ | ❌ | -| `docs/` (proposals, blog drafts) | ✅ | ❌ | -| `test/` | ✅ | ❌ | -| `.github/workflows/` | ✅ | ❌ | - -### Release Process (dev → main) - -Releases use `.github/workflows/release.yml` which implements a **filtered copy** strategy: - -1. Tests pass on `dev` -2. Workflow checks out `dev` -3. Copies only product files to a staging area -4. Switches to `main`, replaces all content with staged files -5. Commits, tags, pushes -6. Creates GitHub Release - -This ensures `main` never contains Squad Squad files, docs, tests, or workflow definitions. Users who run `npx github:bradygaster/squad` get a clean product-only tree. - -### Merge Strategy - -- `dev` → `main`: **Automated via release workflow** (filtered copy, not a git merge) -- `feature/*` → `dev`: **Squash merge** preferred (clean history), or regular merge -- Direct push to `main` is prohibited - -### Branch Protection Recommendations - -When Brady enables branch protection on `main`: - -``` -Branch: main -├── Require pull request before merging: OFF -│ (Releases are merge-committed directly by the release process. -│ A PR is optional but not required — the release checklist is the gate.) -├── Require status checks to pass: ON -│ └── Required: "CI / Test" -├── Require branches to be up to date: ON -├── Do not allow force pushes: ON -├── Do not allow deletions: ON -└── Restrict who can push: ON - └── Allowed: bradygaster (+ release automation if using PAT) -``` - -**Note:** Full branch protection requires a GitHub Pro/Team plan for private repos, or the repo must be public. For public repos, these rules are free. - -### Moving from `dev` to `main` - -The first release (`v0.1.0` or `v0.2.0` — Brady's call) runs the release workflow to populate `main` with product-only files and establishes the branch strategy going forward. Until then, all development stays on `dev`. - ---- - -## 6. State Integrity Guarantees - -### The Contract - -> **The `upgrade` subcommand MUST NEVER touch `.ai-team/`.** This is user-owned state. It contains team identity, decisions, history, casting — everything that makes a squad *their* squad. - -### What `upgrade` Touches (Squad-Owned) - -| Path | Action on Upgrade | -|------|-------------------| -| `.github/agents/squad.agent.md` | Overwritten | -| `.ai-team-templates/` | Overwritten (full directory) | - -### What `upgrade` Never Touches (User-Owned) - -| Path | Action on Upgrade | -|------|-------------------| -| `.ai-team/` | Never read, never written, never deleted | -| `.ai-team/agents/` | Untouched | -| `.ai-team/decisions/` | Untouched | -| `.ai-team/casting/` | Untouched | -| `.ai-team/orchestration-log/` | Untouched | -| `.ai-team/decisions/inbox/` | Untouched | - -**Exception:** `init` (not upgrade) creates `.ai-team/decisions/inbox/`, `.ai-team/orchestration-log/`, and `.ai-team/casting/` directories if they don't exist. This is additive-only — it never overwrites existing files. - -### CI Enforcement - -The CI workflow (§4a) includes an upgrade state integrity test: - -1. Run `init` to create a project -2. Write a sentinel file into `.ai-team/decisions/inbox/` -3. Run `upgrade` -4. Assert the sentinel file still exists and is unmodified - -**Hockney should expand this** into a proper test in `test/index.test.js`: -- Test that `.ai-team/` contents survive upgrade (files, subdirectories, nested content) -- Test that Squad-owned files ARE updated on upgrade -- Test that the version output changes after upgrade (when version stamping ships) - -### `.gitignore` Policy - -`.ai-team/` is **NOT** in `.gitignore`. It is user state that SHOULD be committed to their repo: - -- Team identity (casting, charters) is project-specific -- Decision history is valuable project documentation -- Agent histories contain project context and learnings -- Committing `.ai-team/` enables collaboration — teammates see the same squad - -Current `.gitignore` is correct. No changes needed. - ---- - -## 7. Version Check for Users - -### Problem - -Users don't know when a new version of Squad is available. They might run an outdated version indefinitely. - -### Proposed Solution (Wave 2, item 2.2 scope) - -Add a lightweight version check to the `upgrade` subcommand: - -```javascript -// In upgrade mode, after completing the upgrade: -const https = require('https'); -const RELEASES_URL = 'https://api.github.com/repos/bradygaster/squad/releases/latest'; - -function checkForUpdate(currentVersion) { - return new Promise((resolve) => { - https.get(RELEASES_URL, { headers: { 'User-Agent': 'squad-cli' } }, (res) => { - let data = ''; - res.on('data', chunk => data += chunk); - res.on('end', () => { - try { - const latest = JSON.parse(data).tag_name.replace('v', ''); - if (latest !== currentVersion) { - console.log(`\n${DIM}New version available: v${latest}`); - console.log(`Run: npx github:bradygaster/squad upgrade${RESET}\n`); - } - } catch { /* silent — don't break init for a version check */ } - resolve(); - }); - }).on('error', () => resolve()); // Network failure is not a user problem - }); -} -``` - -**Characteristics:** -- Non-blocking — failure is silent, never breaks init/upgrade -- Uses GitHub's public API (no auth required for public repos) -- Only runs on `upgrade` subcommand (not init — don't slow down first impressions) -- Respects rate limits (60 requests/hour for unauthenticated, more than sufficient) - -**Timeline:** This is a Wave 2 item. For now, users check manually or follow the repo. - ---- - -## 8. Release Cadence & Naming - -### Version-to-Wave Mapping (Planned) - -| Version | Wave | What Ships | -|---------|------|------------| -| `v0.1.0` | Current | Init, upgrade, 12 tests, templates | -| `v0.2.0` | Wave 1 complete | Error handling, 20+ tests, CI, version stamping, feels heard | -| `v0.3.0` | Wave 2 complete | Tiered modes, smart upgrade, skills Phase 1, export | -| `v0.4.0` | Wave 3 complete | Import, skills Phase 2, history summarization | -| `v1.0.0` | All waves + polish | The "holy crap" release | - -Patch releases (`v0.2.1`, etc.) happen between waves for critical fixes only. - -### GitHub Release Naming - -Format: `Squad v{version}` — e.g., "Squad v0.2.0" - -Release notes include: -- What shipped (from wave items) -- Install/upgrade/pin commands -- Link to full changelog (commit diff) -- Breaking changes (if any) - ---- - -## 9. Implementation Plan - -### Phase 1 — Immediate (This Wave) - -| Task | Owner | Status | -|------|-------|--------| -| Write this proposal | Kobayashi | ✅ Done | -| Create `.github/workflows/ci.yml` | Kobayashi (drafted in §4a) → Hockney implements | Blocked on approval | -| Create `.github/workflows/release.yml` | Kobayashi (drafted in §4b) → Kobayashi implements | Blocked on approval | -| First release: tag `v0.1.0` on `main` | Kobayashi | Blocked on Brady's go-ahead | - -### Phase 2 — Wave 1 Gate - -| Task | Owner | -|------|-------| -| CI passing on all pushes | Hockney | -| State integrity test in CI | Hockney | -| Version stamping in `squad.agent.md` | Fenster | -| Cut `v0.2.0` release | Kobayashi | - -### Phase 3 — Wave 2 - -| Task | Owner | -|------|-------| -| Version check in upgrade subcommand | Fenster | -| Automated release notes refinement | Kobayashi | -| CHANGELOG.md established | McManus | - ---- - -## 10. Open Questions for Brady - -1. **First release timing:** Should we tag `v0.1.0` now (current state) or wait for Wave 1 to complete and tag `v0.2.0` as the first release? - -2. **Repo visibility:** Is `bradygaster/squad` currently public or private? Branch protection rules and GitHub API access (for version checks) depend on this. - -3. **Release authority:** Should releases require Brady's explicit approval, or can I cut releases when wave gates pass? - -4. **`dev` → `main` release:** When do we run the first release workflow? This populates `main` with product-only files. - ---- - -## Summary - -| Area | Decision | -|------|----------| -| Distribution | `npx github:bradygaster/squad` — pulls from `main` HEAD | -| Version pinning | `npx github:bradygaster/squad#v0.2.0` — uses `#` not `@` | -| Tag format | `v{MAJOR}.{MINOR}.{PATCH}` | -| Branch strategy | `main` (product-only) ← `dev` (development + Squad Squad) | -| Release trigger | Wave gate pass or critical fix | -| CI | GitHub Actions on push/PR, Node 22.x, ubuntu-latest | -| Release automation | Tag push triggers test → release → verify pipeline | -| State integrity | `.ai-team/` never touched by upgrade; enforced in CI | -| npm publish | **Never.** | - ---- - -**Review requested from:** bradygaster -**Implements:** Sprint Plan items 1.3 (CI), release process (new), distribution strategy (new) -**Authored by:** Kobayashi — if it ships, it ships correctly. diff --git a/team-docs/proposals/022-squad-visual-identity.md b/team-docs/proposals/022-squad-visual-identity.md deleted file mode 100644 index 21ab697e4..000000000 --- a/team-docs/proposals/022-squad-visual-identity.md +++ /dev/null @@ -1,376 +0,0 @@ -# Proposal 022: Squad Visual Identity — Initial Proposals - -**Status:** Draft — Deferred to Horizon -**Author:** Redfoot (Graphic Designer) -**Date:** 2026-02-08 -**Requested by:** bradygaster -**Depends on:** Proposal 014 (Messaging), 002 (Messaging Overhaul) - ---- - -## Executive Summary - -Squad needs a visual identity that works everywhere the product lives: terminal output, GitHub README, VS Code sidebar, favicons, social cards, npm listing. This proposal defines the brand space, presents five logo concepts with full rationale, and recommends one for refinement. The recommended concept ships as an SVG at `docs/assets/squad-logo-proposal.svg`. - -Design constraint: Squad's brand is The Usual Suspects — dry, understated, pressure-oriented. The logo should feel like competence, not enthusiasm. Confidence, not flash. A tool you trust, not a toy you try. - ---- - -## 1. Brand Analysis - -### What does Squad feel like? - -| Attribute | Expression | -|-----------|-----------| -| **Confidence** | It works. It doesn't need to convince you. | -| **Multiplicity** | One command, many agents. Parallel, not serial. | -| **Persistence** | Your team remembers. Knowledge compounds. | -| **Precision** | Clean structure, filesystem-backed, git-native. | -| **Quiet authority** | Dry tone. No exclamation marks. No gradients. | - -Squad is not a startup. It's not a chatbot. It's a crew that shows up, does the work, and writes down what they learned. The visual identity should feel like a well-organized system, not a party. - -### Brand personality keywords -`competent` · `structured` · `plural` · `persistent` · `understated` · `sharp` - -### Rendering constraints - -| Context | Constraints | -|---------|------------| -| **Terminal** | Monochrome only. Must read as recognizable shape at text scale. No color dependency. | -| **GitHub README** | Inline SVG or image link. Dark mode AND light mode. Transparent background required. | -| **GitHub avatar** | 500×500px circle crop. Logo must survive circle masking. | -| **Favicon** | 16×16, 32×32, 48×48. Must be identifiable as a single glyph at 16px. | -| **npm listing** | Small text + tiny icon. Name legibility matters more than logo detail. | -| **VS Code sidebar** | 20×20px icon in activity bar. Monochrome, single color on transparent. | -| **Social cards** | 1200×630px. Logo + tagline composition. Room for "Throw MY squad at it." | -| **Mermaid diagrams** | Already using `#6366f1` (indigo) and `#3b82f6` (blue) — any palette should harmonize. | - -### Typographic context - -The product name is five letters: **S-Q-U-A-D**. Short, punchy, symmetrical feel. The Q is distinctive — it's the only letter with a descender, and the Q→U pair has natural visual rhythm. The word reads like a unit. That's an asset. - -### What the logo must NOT be - -- Not a robot. Not a brain. Not a neural network illustration. -- Not cute. No mascots, no cartoon characters, no winking. -- Not corporate. No swooshes, no abstract globe, no interlocking rings. -- Not busy. If it has more than 3-4 elements, it's wrong. - ---- - -## 2. Logo Concepts - -### Concept A: "The Formation" - -**One-line concept:** Five elements in tight formation — a squad in geometric shorthand. - -**Detailed visual description:** - -Five identical squares arranged in a cross/plus pattern: one center, four surrounding it at compass points (top, right, bottom, left). Each square is the same size. The spacing between them is exactly one-quarter of a square's width — tight enough to read as a unit, open enough to see individual elements. - -The center square represents the coordinator. The four surrounding squares represent agents. The negative space between them forms a plus sign — suggesting addition, growth, coordination. - -**Proportions:** Each square is 20×20 units. Total bounding box is 65×65 units (accounting for spacing). The composition is perfectly symmetrical on both axes. - -**Color palette:** -- Primary fill: `#6366F1` (Indigo 500 — matches existing Mermaid diagram coordinator color) -- All five squares same color, no hierarchy through color -- Hierarchy expressed through position alone (center = coordinator) - -**Typography:** Wordmark "SQUAD" set in **Inter Bold** (or **IBM Plex Sans Bold**), tracked at +0.05em. All caps. Positioned below the mark with vertical spacing equal to one square height. - -**Small sizes:** At favicon scale (16px), reduces to five dots in a plus pattern — still recognizable. At GitHub avatar scale (500px circle), the cross fits cleanly inside the circle with the corners of the outer squares near the circle edge. - -**Monochrome:** Works perfectly — the concept is shape-driven, not color-driven. White on dark, dark on light, single-color on transparent all work without modification. - -**Why it works:** Multiplicity is the core visual metaphor. Five units, one formation. The plus-sign negative space suggests composition and addition without being literal. - -**Why it might not:** Could read as a medical/Red Cross reference. The grid might feel too rigid for a tool that adapts. - ---- - -### Concept B: "The Bracket" - -**One-line concept:** A square bracket containing parallel lines — agents operating in structure. - -**Detailed visual description:** - -A left square bracket `[` rendered as a bold geometric shape: vertical bar with two short horizontal bars extending right from top and bottom. Inside the bracket space, four short horizontal lines of equal length, evenly spaced vertically — representing parallel agents at work. - -The bracket is the structure (Squad's filesystem-backed architecture). The lines inside are the agents (parallel execution). The open right side suggests output, work flowing forward. - -**Proportions:** The bracket is 24 units tall, 8 units wide. The horizontal bars are 6 units long. The four inner lines are 14 units long, centered vertically within the bracket with 3 units of spacing between each. Total bounding box is approximately 24×22 units. - -**Color palette:** -- Bracket: `#1E1B4B` (Indigo 950 — near-black with warmth) -- Inner lines: `#6366F1` (Indigo 500) -- Alternative single-color version uses bracket color only - -**Typography:** "squad" in lowercase **JetBrains Mono Medium** — a monospace font that reinforces the CLI-first identity. No tracking adjustment. Lowercase because the bracket already provides the structural authority; the wordmark can be approachable. - -**Small sizes:** At 16px, the bracket and lines simplify to a bracket-with-dashes glyph. Reads as "code" or "terminal" at a glance. At avatar scale, the bracket-and-lines composition has enough detail to be distinctive. - -**Monochrome:** Excellent. Born monochrome. Color is an enhancement, not a requirement. - -**Why it works:** Directly references the CLI/code world. The parallel lines literally depict parallel execution. The bracket suggests structure, containment, system. Feels like it belongs in a terminal. - -**Why it might not:** Could be too literal. Might feel like an IDE icon rather than a product brand. The open-right-side is subtle and may not read in all contexts. - ---- - -### Concept C: "The Glyph" ⟡ (Recommended) - -**One-line concept:** An abstract mark — a rotated square with an inset element — that reads as both a diamond and a command prompt. - -**Detailed visual description:** - -A square rotated 45° to stand as a diamond shape. The diamond has a uniform stroke weight (no fill — outline only) with slightly rounded corners (radius: 6% of side length). Inside the diamond, at the bottom-left, a small solid square (also rotated 45°, ~30% the size of the outer diamond) sits anchored in the lower-left quadrant, touching or nearly touching the inner edges of the outer diamond's two lower-left sides. - -The outer diamond is the space — the project, the context. The inner element is the seed — the squad, small but solid, growing into the space. The composition is deliberately asymmetrical within a symmetrical frame, creating visual tension. The inner square's position suggests a cursor or prompt — something waiting, ready. - -**Proportions:** Outer diamond: 60×60 unit bounding box (the rotated square's diagonal). Stroke width: 3 units. Inner diamond: 18×18 unit bounding box, positioned with its rightmost point at the center of the outer diamond and its lowest point near the outer diamond's bottom vertex. The inner element occupies roughly the lower-left quadrant. - -**Color palette:** -- Outer diamond stroke: `#6366F1` (Indigo 500) -- Inner diamond fill: `#6366F1` (Indigo 500) -- Single color, no gradient, no secondary color needed - -**Typography:** "SQUAD" in **Inter Semibold**, tracked at +0.08em. All caps. The extra tracking gives the wordmark breathing room to match the diamond's open geometry. Positioned to the right of the mark (horizontal lockup) or below (stacked lockup). - -**Small sizes:** At 16px, the diamond-with-inner-dot reads as a distinctive glyph — not confused with any common UI icon. At 32px, the asymmetric inner element is visible. At avatar scale (500px circle), the diamond's corners approach the circle edge, creating a satisfying relationship between the circular crop and the angular mark. - -**Monochrome:** Perfect. Single-color design. White on black: the outer diamond glows, the inner element anchors. Black on white: clean geometric mark. Works at any single color. - -**Why it works:** It's abstract enough to be a brand, not an illustration. The diamond has historical associations with quality (♦), value, and precision. The inner-element-as-cursor subtly references the CLI without being literal. The asymmetry within symmetry creates visual interest at every size. It's the kind of mark you'd see stamped on a tool — not printed on a t-shirt. Most importantly: it's simple enough to draw from memory after seeing it once. - -**Why it might not:** Abstract marks require repetition to build recognition. The diamond shape is used by many brands (though rarely as an outline with asymmetric interior). The cursor reading requires explanation — it won't be obvious to everyone. - ---- - -### Concept D: "The Stack" - -**One-line concept:** Layered horizontal bars with staggered alignment — a squad's parallel work, visualized as depth. - -**Detailed visual description:** - -Three horizontal rounded rectangles (pill shapes), stacked vertically with small spacing. Each bar is the same height but different widths and horizontal positions: -- Top bar: widest (~48 units), left-aligned -- Middle bar: medium (~36 units), centered -- Bottom bar: narrowest (~28 units), right-aligned - -The stagger creates a sense of depth and motion — like looking at a Gantt chart from an angle, or seeing three agents working on different-sized tasks simultaneously. The descending width suggests convergence — many inputs narrowing to output. - -**Proportions:** Each bar is 8 units tall with 4-unit border radius (half-height, creating pill shapes). Vertical spacing between bars: 4 units. Total bounding box: approximately 48×32 units. - -**Color palette:** -- Top bar: `#6366F1` (Indigo 500) -- Middle bar: `#818CF8` (Indigo 400) -- Bottom bar: `#A5B4FC` (Indigo 300) -- The gradient from dark to light suggests depth, with the "front" agent most prominent - -**Typography:** "squad" in lowercase **Inter Medium**, standard tracking. The lowercase + medium weight balances the visual weight of the stacked bars. Positioned to the right (horizontal lockup). - -**Small sizes:** At 16px, reads as three horizontal lines — simple but potentially generic (could be confused with a hamburger menu icon ☰). At 32px and above, the staggered alignment becomes visible and distinctive. - -**Monochrome:** Requires modification — the three-shade approach doesn't translate to single color. In monochrome, all three bars would be the same color but could use decreasing opacity (100%, 70%, 40%) or solid color with identical weight and rely on the stagger alone for differentiation. - -**Why it works:** Directly visualizes parallel execution — Squad's core architectural feature. The Gantt-like quality references project management without being literal. The depth effect is subtle and sophisticated. - -**Why it might not:** Dangerously close to hamburger menu icon (☰) at small sizes. The color gradient is essential to the concept, which means it partially fails the monochrome constraint. Three bars is a common motif in tech logos. - ---- - -### Concept E: "The Collective" - -**One-line concept:** A cluster of similar-but-distinct geometric agents in organic formation — collaborative intelligence, visualized. - -**Detailed visual description:** - -Five small rounded squares arranged in a loose, organic cluster — not a rigid grid, but a flowing formation suggesting coordinated motion. Each figure is slightly different: varied sizes (13–18 units), slight rotations (-10° to +12°), and opacity shifts (0.7–1.0). The figures overlap at their edges, creating a sense of proximity and shared purpose. The largest figure sits slightly ahead of center (the lead agent), with others arranged around and behind it in a formation that suggests convergence toward a common direction. - -The composition interprets the spirit of intelligent agents working collaboratively. Each figure is autonomous (its own size, rotation, opacity) yet clearly part of a coordinated group. The organic spacing — not uniform, not random — reads as intentional formation. Like a squad moving together. - -**Proportions:** Each figure is a rounded square (corner radius ~20% of side). Sizes range from 13×13 to 18×18 units. Total bounding box approximately 80×80 units. The cluster's center of mass sits slightly above-center, with the lead agent at the top and trailing agents below, creating a natural reading direction. - -**Color palette:** -- Base: `#6366F1` (Indigo 500) — same across all five figures -- Differentiation through opacity: lead figure at 100%, others at 90%, 85%, 75%, 70% -- The opacity gradient creates depth without introducing new colors -- Single-hue design: no secondary colors needed - -**Typography:** "squad" in lowercase, stroke-based letterforms matching the Concept C wordmark style (Inter Semibold inspired, tracked at +0.08em). Positioned below the mark in stacked lockup. The lowercase warmth complements the organic cluster — approachable agents, not cold geometry. - -**Small sizes:** At 16px, the five overlapping figures merge into a single distinctive asymmetric blob — recognizable as "that clustered shape" without needing to resolve individual figures. At 32px, individual figure edges become visible. At 500px (avatar scale), each figure's rotation and opacity is clearly distinct. The cluster survives circle crop well — its organic shape doesn't fight the circular mask. - -**Monochrome:** Works with modification. In single-color monochrome (no opacity), the overlapping edges create natural visual separation through the slight gaps between rotated figures. Alternatively, the opacity variations translate directly to grayscale. White-on-dark: the cluster reads as a glowing constellation of agents. Dark-on-light: clean geometric grouping. - -**Why it works:** Multiplicity is literal — you see multiple agents. Individuality is visible — each one is slightly different. Collaboration is spatial — they're arranged together, not scattered. The organic formation avoids the rigidity of Concept A's grid while maintaining the "squad" metaphor. At small sizes it collapses into a distinctive asymmetric glyph that doesn't resemble any standard UI icon. The concept directly evokes Squad's core promise: throw a group of intelligent agents at a problem, each contributing their own way. - -**Why it might not:** Five overlapping shapes risk visual noise at mid-sizes (24–48px) where individual figures are partially resolved but not clearly distinct. The organic arrangement is harder to reproduce precisely than geometric concepts — every implementation will look slightly different. The concept relies on opacity for differentiation, which means print/monochrome contexts lose some of the individuality. Could read as "scattered" rather than "collaborative" if the spacing is even slightly off. - -### Concept E Variations - -Brady selected Concept E for further exploration. Four variations were developed, each maintaining the five-agent rounded-square vocabulary and Indigo 500 (#6366F1) single-hue palette, but exploring fundamentally different spatial arrangements. - -**E2 — "Tight Formation"** (`docs/assets/squad-logo-e2.svg`, `squad-logo-e2-mark.svg`): The agents compress into a single dense mass with 50%+ overlap between figures. Where the original E reads as "individuals coordinating," E2 reads as "a single organism made of parts." The tight overlap creates rich translucent layering at intersections, and at small sizes the cluster collapses into a compact, gem-like shape. This variation best conveys cohesion and shared context — agents so aligned they nearly merge. The tradeoff is reduced individuality; the figures are harder to distinguish as separate entities. - -**E3 — "Arc"** (`docs/assets/squad-logo-e3.svg`, `squad-logo-e3-mark.svg`): The agents are arranged along a sweeping ~120° arc, with the lead agent at the apex and trailing agents descending along the curve in decreasing size. Each agent is rotated to follow the arc's tangent at its position, creating a strong sense of directional momentum — a squad advancing together. This is the most kinetic variation: where E is a cluster and E2 is a mass, E3 is a wave. It reads particularly well in horizontal lockups and wide-format contexts (social cards, README headers). The tradeoff is that the composition is wider and shallower than the others, making it less compact for square-crop contexts like favicons. - -**E4 — "Grid"** (`docs/assets/squad-logo-e4.svg`, `squad-logo-e4-mark.svg`): The agents occupy positions on a loose 3×2 grid, but each drifts 2–4 units from its cell center with individual rotation and sizing. One grid cell (bottom-right) is deliberately left empty to break symmetry. The result is "ordered chaos" — structured from a distance, organic up close. This variation best represents a team with defined roles but individual style. It's the most "systematic" of the variations and the easiest to reproduce precisely. The tradeoff is that the grid structure can read as too rigid or dashboard-like if the organic offsets aren't pronounced enough. - -**E5 — "Convergence"** (`docs/assets/squad-logo-e5.svg`, `squad-logo-e5-mark.svg`): The agents are spread wide — more separated than any other variation — but each is rotated so that one corner points toward a shared focal point at center. The negative space at center, where no agent sits, becomes the implicit subject: the work itself. This variation emphasizes shared purpose over proximity. The agents don't need to be close to be a squad; they just need to be aimed at the same goal. The wider spread and strong rotations create the most dramatic, dynamic composition. The tradeoff is that at very small sizes the agents may appear disconnected rather than coordinated. - ---- - -## 3. Recommendation: Concept C — "The Glyph" - -**The Glyph wins on constraints.** - -| Criterion | A: Formation | B: Bracket | C: Glyph ⟡ | D: Stack | E: Collective | -|-----------|:---:|:---:|:---:|:---:|:---:| -| Favicon readability | ✅ Good | ✅ Good | ✅ Best | ⚠️ Hamburger risk | ✅ Good | -| Monochrome fidelity | ✅ Perfect | ✅ Perfect | ✅ Perfect | ⚠️ Needs adaptation | ✅ Good | -| Dark/light mode | ✅ | ✅ | ✅ | ⚠️ | ✅ | -| Brand distinctiveness | ⚠️ Medical cross risk | ⚠️ IDE icon feel | ✅ Unique | ⚠️ Generic bars | ✅ Distinctive | -| Circle crop (avatar) | ✅ Good | ⚠️ Awkward | ✅ Excellent | ✅ Good | ✅ Good | -| Emotional register | Structured | Technical | Confident | Dynamic | Collaborative | -| Scalability | ✅ | ✅ | ✅ | ⚠️ | ✅ | -| Matches brand personality | Good | Good | **Best** | Good | Good | - -The Glyph's key advantage: **it works at every size, in every color mode, with zero adaptation.** One SVG, one color, infinite contexts. That's the kind of constraint-driven design that scales. - -The diamond-with-inner-element reads differently at different sizes — a feature, not a bug: -- At 16px: a distinctive dot-in-diamond favicon -- At 32px: asymmetric geometry, clearly a mark -- At 500px: the full relationship between outer frame and inner anchor is visible -- In terminal: can be approximated as `◇` or `⬥` in Unicode - -**SVG implementation:** `docs/assets/squad-logo-proposal.svg` - ---- - -## 4. Brand Color Palette - -### Primary Palette - -| Role | Color | Hex | Usage | -|------|-------|-----|-------| -| **Primary** | Indigo 500 | `#6366F1` | Logo, primary actions, links, emphasis | -| **Primary Dark** | Indigo 700 | `#4338CA` | Hover states, active elements, depth | -| **Primary Darkest** | Indigo 950 | `#1E1B4B` | Text on light backgrounds, dark UI elements | - -### Neutral Palette - -| Role | Color | Hex | Usage | -|------|-------|-----|-------| -| **Text** | Slate 900 | `#0F172A` | Body text, headings | -| **Text Secondary** | Slate 500 | `#64748B` | Captions, metadata, secondary info | -| **Surface Light** | Slate 50 | `#F8FAFC` | Light mode backgrounds | -| **Surface Dark** | Slate 900 | `#0F172A` | Dark mode backgrounds | -| **Border** | Slate 200 | `#E2E8F0` | Dividers, card borders (light mode) | - -### Accent Palette - -| Role | Color | Hex | Usage | -|------|-------|-----|-------| -| **Success** | Emerald 500 | `#10B981` | Test passing, healthy status, confirmations | -| **Warning** | Amber 500 | `#F59E0B` | Cautions, experimental status | -| **Error** | Rose 500 | `#F43F5E` | Failures, breaking changes | -| **Info** | Sky 500 | `#0EA5E9` | Informational badges, links | - -### Usage Rules - -1. **Indigo is Squad.** Every other color serves it. When in doubt, use indigo or a neutral. -2. **No gradients.** Flat color only. Gradients fight the terminal-native aesthetic. -3. **Monochrome must always work.** Any visual that requires color to be understood is wrong. -4. **Dark mode is not an afterthought.** Design in dark mode first (Slate 900 background, light text), then verify light mode. -5. **Accent colors are functional, not decorative.** Green means passing. Red means broken. Don't use them for visual interest. -6. **The Mermaid diagrams already use this palette** (`#6366f1`, `#3b82f6`, `#6b7280`, `#8b5cf6`). The proposed palette harmonizes with the existing visual language — no breaking changes. - -### Color accessibility - -All primary-on-neutral combinations must meet WCAG AA contrast ratios (4.5:1 for normal text, 3:1 for large text). Verified combinations: - -- `#6366F1` on `#F8FAFC` → 4.6:1 ✅ (AA normal text) -- `#6366F1` on `#0F172A` → 5.8:1 ✅ (AA normal text) -- `#1E1B4B` on `#F8FAFC` → 15.4:1 ✅ (AAA) -- `#F8FAFC` on `#0F172A` → 17.1:1 ✅ (AAA) - ---- - -## 5. Typography Recommendations - -### Primary typeface: Inter - -**Why Inter:** Open source (SIL license), designed for screens, excellent at small sizes, wide weight range, already widely available on developer machines. Neutral without being bland. The kind of typeface that doesn't announce itself — which matches Squad's understated personality. - -| Context | Style | Weight | Tracking | -|---------|-------|--------|----------| -| Logo wordmark | All caps | Semibold (600) | +0.08em | -| Headings | Sentence case | Bold (700) | Normal | -| Body text | Sentence case | Regular (400) | Normal | -| Captions/meta | Sentence case | Medium (500) | Normal | - -### Monospace: JetBrains Mono - -**Why JetBrains Mono:** Open source, designed for code, excellent ligatures, widely installed in the target audience's editors. Used for code samples, terminal output, file paths, and the alternative wordmark lockup. - -| Context | Style | Weight | -|---------|-------|--------| -| Code samples | Regular | Regular (400) | -| Terminal output | Regular | Regular (400) | -| Alternative wordmark | Lowercase | Medium (500) | - -### Typography rules - -1. **Never use more than two typefaces.** Inter + JetBrains Mono covers every context. -2. **ALL CAPS is reserved for the logo wordmark and badges.** Headings and body are sentence case. -3. **Don't bold everything.** Bold is for emphasis. If everything is emphasized, nothing is. - ---- - -## 6. SVG Implementation Notes - -The recommended Concept C is implemented at `docs/assets/squad-logo-proposal.svg`. - -**What's in the SVG:** -- The Glyph mark: outer diamond (stroke, no fill) with inner solid diamond (filled) in the lower-left quadrant -- Wordmark "SQUAD" in Inter Semibold (as path outlines for portability) -- Stacked lockup (mark above wordmark) -- Single color: `#6366F1` -- Transparent background -- Viewbox optimized for clean scaling - -**What's NOT in the SVG (future work):** -- Horizontal lockup variant -- Monochrome variants (white-on-dark, dark-on-light) -- Favicon-optimized version (simplified at 16px) -- Social card template - ---- - -## 7. Next Steps - -| Item | Owner | Dependency | -|------|-------|-----------| -| Team feedback on concept direction | Keaton, McManus, Brady | This proposal | -| Refine selected concept based on feedback | Redfoot | Feedback | -| Create lockup variants (horizontal, stacked, mark-only) | Redfoot | Concept approval | -| Generate favicon and avatar exports (ICO, PNG) | Redfoot | Concept approval | -| Create social card template (1200×630) | Redfoot | Concept approval + McManus tagline | -| Dark mode / light mode variant SVGs | Redfoot | Concept approval | -| Integrate into README header | McManus + Redfoot | All assets final | -| Add to npm package metadata | Fenster | Favicon export | -| Brand guidelines document (standalone) | Redfoot | All above | - -### What I need from the team - -1. **From Brady:** Does any concept feel right? Does any feel wrong? Gut reaction matters more than analysis here. -2. **From Keaton:** Does the diamond/glyph concept align with where the product is headed? Is the "understated confidence" register correct? -3. **From McManus:** How does the logo composition work with the launch messaging? Does "Throw MY squad at it" sit well next to the diamond mark? -4. **From Fenster:** Any technical constraints I'm missing for integration into the npm package, GitHub Actions badges, or VS Code? - ---- - -_This proposal was written by Redfoot, the Graphic Designer on Squad's team. First assignment. First draft. Let's talk._ diff --git a/team-docs/proposals/022a-agent-progress-updates.md b/team-docs/proposals/022a-agent-progress-updates.md deleted file mode 100644 index 2f4facdc7..000000000 --- a/team-docs/proposals/022a-agent-progress-updates.md +++ /dev/null @@ -1,629 +0,0 @@ -# Proposal 022a: Agent Progress Updates — Periodic Status During Long-Running Work - -**Author:** Keaton (Lead) -**Date:** 2026-02-13 -**Status:** Proposed -**Requested by:** bradygaster (Issue #22) -**Builds on:** Proposal 017/030/030a (async comms), 019 (master sprint plan), 034 (notifications) - ---- - -## 1. Problem Analysis - -### The UX Gap - -Users launching long-running background agents (exploratory code analysis, full test suites, large codebase refactors) report **uncertainty and anxiety** while work runs: - -- **Blank terminal.** The UI goes silent after the coordinator acknowledges the spawn. No signals. -- **Invisible progress.** Did the agent hit an error? Is it stuck? Still working? -- **Perception of slowness.** Silence feels slower than noise. A 5-minute agent task *feels* like a hang without status updates. -- **Broken feedback loop.** Users can't tell the difference between "agent is paralyzed" and "agent is thinking hard," so they re-run work or cancel early. - -**Result:** Users feel disconnected from their team. The remote-team feeling that Squad should create is broken by one-way communication. - -### Why This Matters to Squad's Mission - -Squad's core promise is that agents *feel like remote coworkers*. Remote coworkers send status updates: - -- *"Working on auth refactor, found 47 uses of the old pattern."* -- *"Test suite passed, running benchmarks now."* -- *"Blocked on API response — need your input."* - -Without periodic updates, Squad agents feel like a black box, not a team. Solving this unlocks the intimacy that differentiates Squad from generic agent orchestration. - -### The Actual Constraint - -This isn't a technical blocker. **The coordinator can already poll agents via `read_agent`** with short timeouts to collect partial output. **Agents can already write to shared files** that the coordinator monitors. **The real constraint is design:** What's the right signal? The right cadence? The right voice? - -Get this wrong and the output becomes noise. Get it right and the user feels like their team is working *with* them, not *for* them. - ---- - -## 2. Platform Constraints & Mechanisms - -### Current System - -``` -User → Coordinator (spawns agents) - ↓ - Background Agents (mode: "background") - ├─ Agent works, produces files - ├─ Agent completes - ↓ -Coordinator (polls via read_agent) - ↓ - User (gets final result) -``` - -**Gaps:** -- Coordinator only polls AFTER agents complete -- No mechanism for periodic mid-work status collection -- read_agent designed for final results, not streaming progress - -### Available Mechanisms - -**1. read_agent with short timeouts (MOST VIABLE)** -- `read_agent` returns partial output if agent is still running -- Can call `read_agent(agent_id, wait: false)` to get current status without blocking -- Cost: One API call per poll interval per agent -- Latency: Instant, non-blocking -- **Constraint:** Only works for work that generates text output (not file-only work) - -**2. Shared file progress tracking (FILE-BASED)** -- Agents write to `.ai-team/progress/{agent-name}.md` during execution -- Coordinator polls this file on intervals (every 30s, etc.) -- Cost: Filesystem reads (negligible) -- Latency: Filesystem read speed -- **Constraint:** Agents must explicitly write progress; easily forgotten; can create merge conflicts if multiple agents write to same file - -**3. Agent output log files (OUTPUT-BASED)** -- Agents write output to `.ai-team/progress/{agent-name}.log` as they work -- Coordinator tails this file periodically -- Cost: Filesystem reads -- **Constraint:** Only captures stdout/stderr, not work state; file handles can conflict - -**4. Milestone-based signals (BEHAVIORAL)** -- Agents emit text signals at natural work breakpoints ("✅ Parsed 300 files", "🔴 Test 45/120 failed") -- Coordinator collects these via read_agent -- Cost: Zero additional API calls (reuses read_agent mechanism) -- **Constraint:** Requires agents to be trained on milestone signals; needs documentation - -**5. Event file drop-box (FILE-BASED WITH MERGE)** -- Agents write to `.ai-team/progress-events/{timestamp}-{agent}.json` (one file per event, never conflicts) -- Coordinator polls directory for new files -- Cost: Filesystem reads + parsing JSON -- **Constraint:** Requires file cleanup; JSON parsing overhead - ---- - -## 3. Proposed Approaches - -### Approach A: Coordinator Polling via read_agent (Lightweight, Cost-First) - -**Mechanism:** -1. Coordinator spawns background agent with `task(..., mode: "background")` -2. Coordinator acknowledges spawn to user: *"🏗️ Keaton is analyzing the codebase — I'll check in every 30s."* -3. While agent is running, coordinator **periodically calls `read_agent(agent_id, wait: false)` on 30-second intervals** -4. If agent is still running, read_agent returns partial output accumulated so far -5. Coordinator **extracts summary-level signals from the output** and relays to user: - - *"📍 Processed 150/400 files..."* - - *"✅ All tests passing (67 completed, 23 remaining)"* - - *"🔴 Blocked: missing env.config file"* -6. Agent completes, coordinator collects final result, presents full summary - -**Implementation:** -```javascript -// In coordinator loop (simplified pseudocode) -const agent_id = spawn_task(..., "background"); -user_output("🏗️ " + agent.name + " is starting work..."); - -const max_polls = 600; // 30s × 600 = 300 minutes max -let poll_count = 0; - -while (poll_count < max_polls) { - await sleep(30000); // 30 seconds - const current = read_agent(agent_id, wait: false); - - if (current.status === "completed") break; - if (current.status === "running" && current.output) { - const summary = extract_summary(current.output); - user_output("📍 " + summary); // Relay progress - } - poll_count++; -} - -const final = read_agent(agent_id, wait: true, timeout: 10); -user_output("✅ Complete:\n" + final.output); -``` - -**Pros:** -- Zero file I/O complexity -- Agents need zero changes (already producing text output) -- Cost is ~1 read_agent call per 30s per agent (negligible for short tasks, trivial for long ones) -- Works with ALL agent types immediately -- Coordinator has full output context for smart summarization - -**Cons:** -- Polling latency (30s is industry-standard but not real-time) -- Requires coordinator logic to extract meaningful signals -- Agents may output noise that looks like progress but isn't -- User sees coordinator-paraphrased progress, not raw agent voice - -**Brady's Cost Model Fit:** ✅ Excellent. Reuses read_agent (already called at end). 30-second polling is standard across industry (GitHub Actions, CI/CD, etc.). No new infrastructure. - ---- - -### Approach B: Agents Write Milestone Files (Voice-Preserving) - -**Mechanism:** -1. Agents follow a documented pattern: at natural milestones, they **write to `.ai-team/progress/{agent-name}.md`** -2. Each write appends a dated milestone entry with agent's own voice: - ```markdown - ## Keaton — Codebase Analysis - **2026-02-13 14:23:15Z** — Parsing directory structure - **2026-02-13 14:23:42Z** — ✅ Found 340 files across 8 modules - **2026-02-13 14:24:08Z** — 📍 Analyzing imports in `src/auth/`... - **2026-02-13 14:25:30Z** — ✅ Auth module complete (156 imports catalogued) - **2026-02-13 14:25:31Z** — 📍 Analyzing imports in `src/api/`... - ``` -3. Coordinator **reads `.ai-team/progress/` directory every 30s**, displays new entries to user -4. Agents delete their progress file after work completes (cleanup) - -**Implementation:** -```javascript -// In agent code -await fs.appendFile(".ai-team/progress/keaton.md", - `**${timestamp}Z** — 📍 Parsing directory structure\n`); -``` - -**Pros:** -- Preserves agent personality/voice (agent writes what they want user to know) -- No coordinator logic needed to extract signals -- Natural milestones match agent work (file written = can write progress) -- Agents control message; coordinator just relays - -**Cons:** -- Agents must explicitly write progress (easy to forget) -- Requires agent discipline and documentation -- File coordination issues: multiple agents, stale files, cleanup -- Agents need code to write files (adds 1-2KB per agent spawn template) -- Not all work has natural "milestone" moments - -**Brady's Cost Model Fit:** ✅ Good. No API calls. Filesystem ops are free. Requires agent documentation and discipline. - ---- - -### Approach C: Milestone-Based Signals + Coordinator Relay (Balanced) - -**Mechanism:** -1. **Agents trained to emit signals at milestones** (no file writes, just text output): - ``` - ✅ [MILESTONE] Analyzed 150/400 files - 🔴 [MILESTONE] Error in src/lib/parser.js — unresolved dependency - 📍 [MILESTONE] Starting test suite... - ``` -2. Coordinator calls `read_agent(agent_id, wait: false)` every 30s -3. Coordinator **scans output for `[MILESTONE]` markers**, extracts them -4. Coordinator relays milestones to user in real-time: - ``` - 📍 Keaton — ✅ Analyzed 150/400 files - 📍 Keaton — 🔴 Error in src/lib/parser.js - ``` -5. Milestones persist in read_agent output (not lost when agent completes) - -**Implementation:** -```javascript -// In agent code — agents just emit markers, no special tools -console.log("✅ [MILESTONE] Analyzed 150/400 files"); - -// In coordinator — extract and relay -const milestones = extract_milestones(current_output); -milestones.forEach(m => user_output("📍 " + agent.name + " — " + m)); -``` - -**Pros:** -- Agents don't need to write files (just console output) -- Agents have full control over what's a milestone -- Coordinator intelligence can be tuned without agent changes -- Works with existing agent output patterns -- Cost is exactly the same as Approach A - -**Cons:** -- Requires documenting `[MILESTONE]` convention -- Agents need training/examples -- Coordinator must extract milestones correctly (can be regex-fragile) - -**Brady's Cost Model Fit:** ✅ Excellent. Same cost as Approach A (read_agent polling). Light coordinator logic. - ---- - -### Approach D: Real-time Event Log (Over-Engineered) - -**Mechanism:** -- Agents write JSON events to `.ai-team/progress-events/{timestamp}.json` at milestones -- Coordinator polls directory for new files every 5s -- Parser extracts events, displays to user -- Old files deleted after display - -**Pros:** -- Structured data for future event streaming -- Real-time (5s latency vs 30s) - -**Cons:** -- File handles, cleanup complexity -- Requires JSON serialization in agents -- Directory polling is messier than file read -- Over-engineered for the problem -- Higher latency (5s polling is not actually real-time; requires OS notification API for true real-time) - -**Brady's Cost Model Fit:** ❌ No. Adds complexity without proportional value. - ---- - -## 4. Recommended Approach: Milestone Signals + Coordinator Relay (A+C Hybrid) - -### Why This Approach Wins - -**Combines Approach A's cost efficiency with Approach C's voice control:** - -1. **Coordinator uses `read_agent` polling (30-second intervals)** - - Zero file I/O - - One API call per 30s per agent (negligible cost) - - Works immediately with existing agents - - Fallback: if agent doesn't emit milestones, user still gets periodic "still working" status - -2. **Agents trained to emit `[MILESTONE]` signals in output** - - Agents control what gets highlighted - - No file writes, no coordination overhead - - Natural extension of existing agent logging/console patterns - - Can be taught via skill (`.ai-team/skills/progress-signals/`) - -3. **Coordinator extracts and relays milestones in real-time** - - Every 30s, scans the accumulated output for `[MILESTONE]` markers - - Displays new milestones with agent name and emoji - - Keeps terminal feeling *alive* without noise - -### The User Experience - -``` -Brady: "keaton, analyze the codebase" - -Coordinator: -🏗️ Keaton is analyzing the codebase. I'll check in every 30 seconds. - -[30s later] -📍 Keaton — ✅ Parsed 150/400 files -📍 Keaton — 📍 Analyzing module dependencies... - -[30s later] -📍 Keaton — ✅ Found 47 circular dependencies -📍 Keaton — 📍 Generating report... - -[45s later] -✅ Keaton completed analysis. Here's the report: -[full output...] -``` - -### What Changes - -**For agents:** -- No code changes required (backward compatible) -- New skill available: `.ai-team/skills/progress-signals/SKILL.md` -- Agents can opt-in: emit `✅ [MILESTONE]` markers in their output when hitting natural breakpoints -- Examples documented in skill; easy to adopt - -**For coordinator:** -- Add `progress_polling` loop to the spawn → completion flow -- Extract milestones from read_agent output every 30s -- Relay to user: `📍 {agent_name} — {milestone_text}` -- Cost: 0 (one more read_agent call, which was already happening at end) - -**For the user:** -- Zero changes; better UX -- Agents feel *alive* during long work -- Milestones reinforce agent personality (Keaton uses 🏗️, Verbal uses 🎯, etc.) - ---- - -## 5. Impact on squad.agent.md - -### Coordinator Additions - -**In the spawn flow (post-spawn, before final result collection):** - -```markdown -### Progress Polling (New Section) - -When spawning agents with `mode: "background"`: - -1. **Before polling starts:** User always sees acknowledgment (required, non-negotiable): - ``` - 🏗️ {AgentName} is {work_description}. Checking in every 30 seconds. - ``` - -2. **Progress polling loop (30-second intervals):** - - Call `read_agent(agent_id, wait: false, timeout: 5)` every 30s while agent is running - - Extract all lines matching `\[MILESTONE\]` from output - - For each new milestone (not previously shown): - ``` - 📍 {AgentName} — {milestone_text} - ``` - - Continue polling until agent completes - -3. **Agent completion:** - - Call `read_agent(agent_id, wait: true, timeout: 300)` to get final result - - Display final summary/output per normal flow - -**Example template for agent spawn:** - -``` -const agent = spawn(task, { - agent_type: "explore", - description: "Analyzing codebase structure", - prompt: "...", - mode: "background" -}); - -// NEW: Acknowledge and start polling -output(`🏗️ Keaton is analyzing the codebase. I'll check in every 30 seconds.`); - -// NEW: Poll every 30s for progress -const milestones_shown = new Set(); -const max_iterations = 600; // 30s × 600 = 5 hours max - -for (let i = 0; i < max_iterations; i++) { - const result = read_agent(agent.id, wait: false); - - if (result.status === "completed") break; - - if (result.output) { - const new_milestones = extract_new_milestones(result.output, milestones_shown); - new_milestones.forEach(m => { - output(`📍 Keaton — ${m}`); - milestones_shown.add(m); - }); - } - - if (i < max_iterations - 1) { - await sleep(30000); - } -} - -// Collect final result -const final = read_agent(agent.id, wait: true, timeout: 300); -// ... process final output per normal flow -``` -``` - -### Skill Addition - -**File:** `.ai-team/skills/progress-signals/SKILL.md` - -```yaml ---- -name: "progress-signals" -description: "Teaches agents to emit periodic status updates during long-running work via console output markers." -domain: "developer-experience" -confidence: "high" -source: "manual" -teaches: - - pattern: "milestone-emission" - - pattern: "progress-logging" ---- - -# Progress Signals Skill - -## When to Use - -Your work is going to take more than 30 seconds and you want the user to know you're making progress. - -## The Pattern - -Emit lines matching this format in your output (via console.log or similar): - -``` -✅ [MILESTONE] {summary of what you just completed} -📍 [MILESTONE] {what you're starting now} -🔴 [MILESTONE] {error or blocker you hit} -``` - -The coordinator will automatically extract and relay these to the user every 30 seconds. - -## Examples - -```javascript -// Good examples -console.log("✅ [MILESTONE] Parsed 150/400 files"); -console.log("📍 [MILESTONE] Starting test suite run..."); -console.log("🔴 [MILESTONE] Auth endpoint timeout — retrying..."); - -// These get relayed to the user as: -// 📍 Keaton — ✅ Parsed 150/400 files -// 📍 Keaton — 📍 Starting test suite run... -// 📍 Keaton — 🔴 Auth endpoint timeout — retrying... -``` - -## Do's and Don'ts - -✅ **Do:** -- Emit milestones at natural breakpoints (after parsing a file, completing a test phase, etc.) -- Keep milestone text short (~1 line, max 80 chars) -- Use emoji to signal status (✅ done, 📍 in-progress, 🔴 error, 🤔 thinking) - -❌ **Don't:** -- Emit milestones for every log line (that's noise, not progress) -- Emit duplicate milestones (once per phase, not per iteration) -- Use `[MILESTONE]` outside of the exact format (won't be extracted) -- Forget that the user will see this — write for them, not the logs - -## Implementation - -```javascript -const fs = require('fs'); - -// In your agent work loop: -for (let i = 0; i < files.length; i++) { - process_file(files[i]); - - if ((i + 1) % 50 === 0) { - console.log(`✅ [MILESTONE] Processed ${i + 1}/${files.length} files`); - } -} - -console.log("📍 [MILESTONE] Starting analysis phase..."); -// ... analysis work ... -console.log("✅ [MILESTONE] Analysis complete"); -``` -``` - ---- - -## 6. UX Mockup: What the User Actually Sees - -### Scenario 1: Short Task (< 1 minute) - -``` -Brady: keaton, review the auth module for security issues - -Coordinator: -🏗️ Keaton is reviewing auth.js for security issues. I'll check in every 30 seconds. - -[45 seconds later] -✅ Keaton completed. Here's the review: - -[Keaton's output...] -``` - -*No progress updates shown because work completed before first 30-second poll.* - ---- - -### Scenario 2: Medium Task (3-5 minutes, with milestones) - -``` -Brady: keaton, analyze the codebase and suggest refactoring opportunities - -Coordinator: -🏗️ Keaton is analyzing the codebase. I'll check in every 30 seconds. - -[30s later] -📍 Keaton — ✅ Parsed 150/400 files -📍 Keaton — 📍 Analyzing dependencies... - -[60s later] -📍 Keaton — ✅ Found 47 files with high coupling (>10 imports) -📍 Keaton — 📍 Generating refactoring suggestions... - -[90s later] -📍 Keaton — ✅ Identified 5 refactoring opportunities -📍 Keaton — 🏗️ Prioritizing by risk/benefit ratio... - -[4 minutes, 30 seconds later] -✅ Keaton completed analysis. Here's the refactoring roadmap: - -[Keaton's detailed output with recommendations...] -``` - -*User can see progress without checking external dashboards. Feels like Keaton is working *with* Brady, not *for* him.* - ---- - -### Scenario 3: Long Task with Error Recovery (8+ minutes) - -``` -Brady: fenster, add integration tests for the new payments API - -Coordinator: -🔧 Fenster is writing integration tests for the payments API. I'll check in every 30 seconds. - -[30s later] -📍 Fenster — 📍 Generating test structure from API spec... - -[60s later] -📍 Fenster — ✅ Created 23 test files -📍 Fenster — 📍 Running first batch (1-5)... - -[90s later] -📍 Fenster — ✅ Tests 1-5 passed -📍 Fenster — 📍 Running batch 2 (6-10)... - -[2m 30s later] -📍 Fenster — 🔴 Test 8 failed: mock payment gateway timeout -📍 Fenster — 🔧 Increasing timeout to 5s, retrying... - -[3m later] -📍 Fenster — ✅ Tests 6-10 passed (retry successful) -📍 Fenster — 📍 Running batch 3 (11-15)... - -[5m later] -📍 Fenster — ✅ All 23 tests passed (12m run time) -📍 Fenster — 📍 Generating coverage report... - -[5m 30s later] -✅ Fenster completed. Test suite is ready: - -[Coverage report, summary, next steps...] -``` - -*Brady can watch the work progress. If something blocks, he sees it immediately ("Test 8 failed") instead of waiting for the entire task to fail. He can decide to intervene or wait based on progress visibility.* - ---- - -## 7. Success Criteria - -- [ ] Coordinator emits `[MILESTONE]` extraction logic (can parse at least 10 common milestone formats) -- [ ] Skill documentation is clear enough that agents adopt it within 1-2 spawns -- [ ] No performance degradation: read_agent polling < 100ms overhead per call -- [ ] Users report feeling less uncertain during 2+ minute tasks (post-launch feedback) -- [ ] Milestone signals work across all agent types (explore, task, general-purpose, code-review) without modification -- [ ] Coordinator handles edge case: agent produces no milestones (falls back to "still working" message every 30s) - ---- - -## 8. Alternatives Considered - -| Approach | Cost | Complexity | Voice Control | Adoption | -|----------|------|-----------|----------------|----------| -| **Polling only (A)** | ⭐ (1 API call/30s) | ⭐ (low) | ❌ (coordinator decides) | ✅ (auto-works) | -| **File writes (B)** | ⭐ (fs read) | ⭐⭐ (file I/O) | ✅ (agents control) | ⚠️ (requires agent work) | -| **Milestones + polling (C, RECOMMENDED)** | ⭐ (1 API call/30s) | ⭐ (low) | ✅ (agents control) | ✅ (opt-in skill) | -| **Event log (D)** | ⭐⭐ (fs + json) | ⭐⭐⭐ (high) | ✅ (agents control) | ⚠️ (overbuilt) | - -**Recommendation:** C wins on all axes. It's the cost-first choice that doesn't sacrifice user voice or agent personality. - ---- - -## 9. Risk Assessment - -| Risk | Likelihood | Mitigation | -|------|-----------|-----------| -| Agents forget to emit milestones | Medium | Skill documentation + examples in spawn template | -| Coordinator logic extracts false positives | Low | Use strict regex: `\[MILESTONE\]` (hard to accidentally match) | -| 30-second polling feels too slow | Low | Industry standard (GitHub Actions uses 10-30s intervals); documented as tunable | -| read_agent output becomes very large | Low | Milestones are 1-2 lines each; total overhead < 10KB for most tasks | -| Users get overwhelmed by milestone noise | Medium | Coordinator shows only new milestones per poll (deduplication); milestone counts capped at ~1 per 30s for discipline | - ---- - -## 10. Roadmap - -### v0.4.0 (Phase 1 — Foundation) -- [ ] Add progress polling loop to coordinator -- [ ] Add milestone extraction logic (regex-based) -- [ ] Add `.ai-team/skills/progress-signals/SKILL.md` -- [ ] Update squad.agent.md spawn template with example - -### v0.5.0+ (Phase 2 — Enhancement) -- [ ] Agent can customize polling cadence (10s vs 30s) -- [ ] Milestone emoji matching to agent persona (Keaton → 🏗️, Verbal → 🎯, etc.) -- [ ] Milestone filtering: user can disable for quiet mode -- [ ] Structured milestone API for external tooling (GitHub Issues, Discord, etc.) - ---- - -## Decision - -**APPROVED for v0.4.0.** This is a lightweight, cost-first solution that dramatically improves user experience during long-running work. It preserves agent personality, requires minimal coordinator changes, and compounds with existing async/notification infrastructure (Proposal 034). - -Next: Fenster to implement coordinator polling logic and skill documentation. - diff --git a/team-docs/proposals/023-incoming-queue.md b/team-docs/proposals/023-incoming-queue.md deleted file mode 100644 index 9e54782d5..000000000 --- a/team-docs/proposals/023-incoming-queue.md +++ /dev/null @@ -1,340 +0,0 @@ -# Proposal 023: Incoming Queue — Coordinator as Message Processor - -**Author:** Verbal (Prompt Engineer) -**Date:** 2026-02-09 -**Revised:** 2026-02-09 -**Status:** Revised Draft — Deferred to Horizon -**Requested by:** bradygaster -**Triggered by:** Brady — *"copilot itSELF has built-in 'todo list' capability, right? if so, maybe we just delegate to copilot to work in each prompt we send in whilst the team is working."* -**Incorporates:** Kujan's platform assessment (`decisions/inbox/kujan-incoming-queue-assessment.md`), Brady's architecture direction (`decisions/inbox/copilot-directive-20260208T1933.md`) - ---- - -## The Problem - -The coordinator parses every message, routes it to agents, then blocks on `read_agent`. Anything it didn't route gets lost. A message like *"Let's use Tailwind. Fenster, refactor auth, and we should add rate limiting at some point"* contains a directive, a work request, and a backlog item — but only the work request gets routed. The other two vanish. - -### Platform constraints (per Kujan's assessment) - -| Constraint | Implication | -|-----------|-------------| -| SQL `todos` table is **session-scoped** — dies on terminal close | SQL alone can't store the backlog | -| Coordinator **blocks on `read_agent`** — can't process new input | No background message listener; extraction must happen before spawn | -| Spawned agents **can't query coordinator's SQL** | SQL is coordinator-only working memory | -| **Filesystem is the only durable, cross-session, agent-readable state** | Filesystem must be source of truth | -| Coordinator CAN do work in the **same turn** as spawning | Extraction adds zero turns — it broadens the existing parse | - -The coordinator has full tool access (files, SQL, reads, classification) before agents start. We're using it as a telephone switchboard. - ---- - -## The Idea - -**Turn the coordinator into an incoming queue processor.** Before spawning agents, the coordinator extracts ALL actionable items from every message — work requests, directives, backlog items, questions, context clues — and captures each to the right store. Nothing gets lost. - -### The Flow - -``` -User sends message - │ - ▼ -┌─────────────────────────────────────────┐ -│ 1. EXTRACT — Parse message into items │ -│ • Work requests (spawn-worthy) │ -│ • Directives (team memory) │ -│ • Backlog items (future work) │ -│ • Questions (may be instant-answer) │ -│ • Context clues (implicit prefs) │ -└─────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────┐ -│ 2. CAPTURE — Write to stores │ -│ • SQL INSERT (immediate, queryable) │ -│ • Filesystem flush (durable record) │ -│ • Directives → decisions/inbox/ │ -└─────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────┐ -│ 3. ACKNOWLEDGE — Show the user │ -│ what was captured + what's launching │ -└─────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────┐ -│ 4. SPAWN — Route work requests to │ -│ agents, including clones if needed │ -└─────────────────────────────────────────┘ -``` - -### What changes vs. today - -| Today | With incoming queue | -|-------|-------------------| -| Directive capture is a special case | Extraction is the default path for every message | -| One route per message | Multiple items extracted, each routed appropriately | -| "Add rate limiting" gets lost | Captured to backlog — persists across sessions | -| No structured backlog | Team has a queryable, persistent work list | -| One agent instance per identity | Same agent can run as multiple clones in worktrees | - ---- - -## Architecture: SQL Hot Layer + Filesystem Durable Store - -Brady's direction: *"could sql be used as a first layer and then it be written to disk as permanent record?"* - -This eliminates the "multiple sources of truth" problem. **Filesystem always wins. SQL is a queryable cache.** - -### Write path (every extraction) - -``` -1. SQL INSERT into `todos` table ← immediate, queryable -2. Append to `.ai-team/backlog.md` ← permanent, git-tracked, agent-readable -``` - -Both writes happen in the same coordinator turn. SQL gives the coordinator structured queries (`SELECT * FROM todos WHERE status = 'pending'`). Filesystem gives durability, cross-session persistence, and agent visibility. - -### Read path (session start — rehydration) - -``` -On first message of a new session: -1. Read `.ai-team/backlog.md` from disk -2. Parse items into SQL `todos` table -3. Coordinator now has fast queryable state for the session -``` - -If the user closes the terminal and reopens it, the SQL is empty but the filesystem has everything. Rehydration rebuilds the working set. **Session restart is a cache miss, not data loss.** - -### Why this works - -| Concern | Resolution | -|---------|-----------| -| SQL dies on terminal close | Filesystem has the durable copy | -| Filesystem is slow to query | SQL provides structured queries within a session | -| Two sources of truth | Filesystem ALWAYS wins — SQL is rebuilt from it | -| Agents can't read SQL | Agents read `backlog.md` at spawn time | -| Complex querying (dependencies, status) | SQL `todos` + `todo_deps` tables handle this | - ---- - -## Design: Extraction — What Gets Parsed - -The coordinator already does implicit classification (routing). Extraction makes it explicit and broader. - -### Item taxonomy - -| Type | Signal | Action | Example | -|------|--------|--------|---------| -| **Work request** | Imperative verbs, agent names | Spawn agent | "Fenster, refactor auth" | -| **Directive** | "Always/never/from now on" | Write to decisions/inbox | "We always use Tailwind" | -| **Backlog item** | Future tense, "at some point/eventually" | SQL INSERT + append backlog.md | "We should add rate limiting" | -| **Question** | Interrogative | Answer directly or spawn | "How does auth work?" | -| **Context clue** | Implicit preferences | Note in spawn context | "Keep it simple" | - -### Multi-item extraction example - -User: *"We're going with PostgreSQL. Fenster, set up the connection module. Hockney, we'll need migration tests. At some point we should add connection pooling."* - -Coordinator extracts 4 items, captures each, acknowledges: - -``` -📌 Captured: PostgreSQL as database. -🔧 Fenster — setting up database connection module -🧪 Hockney — writing migration tests -📥 Backlog: "Add connection pooling" — saved for later. -``` - -Nothing lost. One message, four actionable items captured. - ---- - -## Design: Team Backlog — The Killer Feature - -Brady: *"my favorite part of the proposal is the team backlog. that's amazeballs."* - -The backlog isn't a TODO list. It's the team's **persistent intent queue** — what the user wants, captured automatically, queryable instantly, durable forever. - -### What makes it different from a TODO list - -- **Auto-populated.** Items extracted from natural conversation, not manually entered. -- **Dual-layer storage.** SQL for fast queries within a session, filesystem for permanence across sessions. -- **Agent-readable.** Spawned agents see `backlog.md` in their INPUT ARTIFACTS when relevant. -- **Explicit adds work too.** "Add to backlog: investigate caching" → captured directly. -- **Third memory channel.** Decisions = what the team agreed. History = what agents learned. Backlog = what the user intends. Three channels > two. - -### Backlog file format (`.ai-team/backlog.md`) - -```markdown -# Team Backlog - -## Open -- [ ] Add connection pooling (captured 2026-02-09, from Brady) -- [ ] Investigate WebSocket support (captured 2026-02-09, from Brady) - -## Done -- [x] Refactor auth module (completed 2026-02-09, by Fenster) -``` - -### How agents interact with the backlog - -1. **Coordinator writes** during extraction — SQL INSERT + filesystem append in the same turn. -2. **Agents read** `backlog.md` at spawn time when relevant. -3. **Agents mark items done** via `backlog/inbox/{agent}-done-{slug}.md` (drop-box pattern). Scribe reconciles. -4. **Agents add items** they discover during work: "Session store needs an index. Added to backlog." -5. **Coordinator surfaces** open items proactively every 3-5 messages: *"📥 3 open backlog items. Tackle 'connection pooling' next?"* - -### Lifecycle - -``` -Captured → Open → [Assigned → In Progress → Done | Deferred] -``` - -Items start `Captured` (extracted from conversation). The coordinator auto-promotes clear items to `Open`. Ambiguous ones stay `Captured` for user confirmation. - -### Proactive surfacing — the compound payoff - -The coordinator checks the backlog after agent work completes. If a backlog item is now actionable (e.g., "connection pooling" is relevant because Fenster just finished the database module), it surfaces a suggestion — not an auto-spawn. This is the "feeling heard" behavior: the team remembers what you mentioned three sessions ago. - ---- - -## Design: Agent Cloning — Multiple Instances, Same Identity - -Brady: *"we already have worktree support. what's to stop us from spawning multiple copies of squad members?"* - -Answer: nothing. **This is already possible with the current architecture.** We just don't do it yet. - -### How it works - -The coordinator spawns the same agent identity multiple times via `task`, each with a different assignment and worktree. Each clone reads the same `charter.md` and `history.md` (consistent identity), works in a separate worktree (no git conflicts), writes to separate inbox files (drop-box handles this), and runs in its own context window (isolated by the `task` tool). - -### What changes in the coordinator - -The current coordinator prompt says "1-2 agents per question." To enable cloning: - -1. **Relax the spawn limit** when the backlog has parallelizable items for the same agent. -2. **Identity labeling** is optional — the drop-box pattern already disambiguates by file slug. The coordinator just spawns multiple background tasks for the same agent. -3. **Worktree assignment** — the coordinator tells each clone which branch or directory to work in, preventing file conflicts. - -### Risks and mitigations - -| Risk | Mitigation | -|------|-----------| -| Two clones edit the same file | Coordinator assigns non-overlapping file scopes per clone | -| History.md gets conflicting appends | Drop-box pattern — each clone writes to `history/inbox/` | -| Context budget — more spawns = more tokens | Clone only when backlog items are clearly parallelizable | -| User confusion ("which Fenster?") | Scribe's merge output attributes work by task, not by clone | - -### What this unlocks - -With cloning + backlog, the coordinator can drain multiple backlog items in a single turn. User sends one message, coordinator spawns Fenster×3 across worktrees, each tackling a different backlog item. The team scales horizontally. - ---- - -## Interaction with Existing Patterns - -**Directive Capture** becomes a special case of extraction — not a separate system. Directives are one item type the extractor identifies. The capture-to-inbox flow stays identical. No breaking change. - -**Drop-Box Pattern** extends to the backlog. Coordinator writes `backlog.md` directly (safe — sole writer during extraction). Agents write to `backlog/inbox/` for additions or completions. Scribe merges. Same proven pattern. - -**Feels-Heard Acknowledgment** gets richer. Extraction gives the coordinator more to confirm: captured directives, spawned agents, AND backlog items saved — all in the same acknowledgment block. - -**Progressive Trust (Proposal 007)** pairs well. At high trust tiers, the coordinator handles backlog items directly — marking items done, re-prioritizing, answering "what's next?" without spawning. - ---- - -## Risks - -1. **Coordinator doing domain work.** Extraction creeps into evaluation (priority judgments, architectural opinions). *Mitigation:* Hard rule — coordinator EXTRACTS and CAPTURES, never EVALUATES. - -2. **Added latency.** Extraction adds reasoning before spawning. *Mitigation:* Same LLM turn as routing — broadening the existing parse, not adding a step. - -3. **Over-extraction.** Every sentence becomes a backlog item. *Mitigation:* Only actionable, project-relevant items. The taxonomy table provides clear signals. When in doubt, don't capture. - -4. **Backlog noise.** Items accumulate that nobody acts on. *Mitigation:* Progressive summarization (same as history.md). Items without activity after N sessions get archived. - -5. **SQL/filesystem sync drift.** SQL state diverges from filesystem. *Mitigation:* Filesystem always wins. SQL is rebuilt from filesystem on session start. Within a session, writes go to both atomically. - -6. **Clone file conflicts.** Two Fenster clones edit the same file. *Mitigation:* Coordinator assigns non-overlapping file scopes. Worktree isolation prevents git conflicts. - -7. **Scope creep into project management.** *Mitigation:* The backlog is a memory aid, not Jira. No priorities, estimates, or assignments unless explicitly added. - ---- - -## What This Unlocks - -1. **Nothing gets lost.** Every actionable mention persists — directives to decisions, work to agents, future intent to the backlog. - -2. **Multi-item messages work naturally.** Users mix directives, requests, and musings in one paragraph. Extraction meets users where they are. - -3. **Backlog enables proactive work.** "User mentioned connection pooling three sessions ago. Fenster just finished the database module." The coordinator connects dots across sessions. - -4. **Horizontal scaling via clones.** The coordinator drains multiple backlog items in parallel — same agent, multiple worktrees, concurrent execution. Team throughput scales with the backlog. - -5. **Session restart is painless.** Close the terminal, reopen it, and the backlog is still there. SQL rehydrates from the filesystem. No lost state, no manual re-entry. - -6. **Three memory channels compound.** Decisions (agreements) + history (learnings) + backlog (intent). Intent is the most human channel — aspirational, not settled. It's what makes the team feel like it's thinking ahead. - ---- - -## Implementation Sketch - -### Phase 1: Extraction + dual-layer writes - -Broaden "Directive Capture" in `squad.agent.md` to "Message Extraction." Add backlog capture + SQL INSERT to the flow. Create `backlog.md` on first capture. Add rehydration logic to coordinator session start. - -**Estimated change:** ~40 lines in squad.agent.md. New file `.ai-team/backlog.md`. - -### Phase 2: Backlog integration + Scribe merge - -Define `backlog.md` format. Add `backlog/inbox/` drop-box. Update Scribe's charter to merge backlog inbox. Add backlog to agent INPUT ARTIFACTS for relevant spawns. - -**Estimated change:** ~10 lines in Scribe spawn template. New directory `.ai-team/backlog/inbox/`. - -### Phase 3: Agent cloning - -Relax coordinator spawn limits for parallelizable backlog items. Add worktree assignment to spawn prompts. Test with Fenster×2 on non-overlapping tasks. - -**Estimated change:** ~15 lines in routing/fan-out section of squad.agent.md. - -### Phase 4: Proactive surfacing - -After processing agent results, coordinator checks backlog for newly-actionable items. Surfaces 1-2 suggestions (not auto-spawns). Pairs with progressive trust tiers. - -**Estimated change:** ~10 lines in "After Agent Work" section. - ---- - -## Alternatives Considered - -### A. SQL-only queue (rejected → evolved into hot layer) -Original rejection was correct — session-scoped storage can't be the backlog. But Brady's insight turns SQL into the fast-query layer with filesystem backing. SQL went from "rejected" to "cache tier." Good call. - -### B. Filesystem-only (original recommendation → evolved) -The v1 proposal recommended filesystem-only with "a door open to hybrid." Brady kicked the door open. The hybrid approach (SQL hot + filesystem durable) is strictly better — same durability, faster queries, no new infrastructure. - -### C. Separate "intake agent" (rejected) -Spawning a dedicated agent for extraction adds latency and complexity. The coordinator already parses every message. Broadening that parse is zero marginal cost. - -### D. GitHub Issues integration (deferred) -Writing backlog items as GitHub Issues is appealing but adds external dependency. Worth exploring as an export target. The filesystem backlog can sync to Issues; the reverse is harder. - ---- - -## Success Criteria - -1. **No information loss.** A message with 3 distinct items results in 3 captures. -2. **No added latency.** Extraction in the same coordinator turn as routing. -3. **Backlog persists.** Items from session N are visible in session N+5. -4. **Rehydration works.** New session reads `backlog.md`, rebuilds SQL state. -5. **Cloning works.** Same agent spawned twice on non-overlapping tasks produces no conflicts. -6. **Proactive surfacing.** Coordinator occasionally reminds user of open backlog items. -7. **No scope creep.** Backlog stays a flat list, not a project management system. - ---- - -## Review Requested - -- **Keaton:** Architecture review — does the dual-layer (SQL + filesystem) hold up? Clone worktree isolation? -- **Kujan:** Platform review — rehydration on session start, SQL INSERT + file write in same turn, any gotchas? -- **Brady:** Does this match the vision? Is the team backlog + cloning the "feeling heard" you're after? diff --git a/team-docs/proposals/024-per-agent-model-selection.md b/team-docs/proposals/024-per-agent-model-selection.md deleted file mode 100644 index 5582ca7b0..000000000 --- a/team-docs/proposals/024-per-agent-model-selection.md +++ /dev/null @@ -1,404 +0,0 @@ -# Proposal 024: Per-Agent Model Selection - -**Status:** Approved ✅ -**Authors:** Verbal (original design + algorithm), Kujan (model catalog research), Keaton (consolidation + approval) -**Date:** 2026-02-08 (original), 2026-02-10 (consolidated) -**Sprint:** v0.3.0 Wave 1, Items 4.1–4.4 -**Companion documents:** [024a — Model Catalog](024a-model-catalog.md) (full 8-dimension analysis), [024b — Algorithm Detail](024b-model-selection-algorithm.md) (design rationale + integration notes) - ---- - -## Problem - -Every agent spawn uses the same model — `claude-sonnet-4` via `general-purpose` agent type. This is wrong for at least three cases: - -1. **Capability mismatch.** Redfoot (Graphic Designer) needs a vision-capable model to reason about imagery, color systems, and visual composition. Claude Sonnet is a text-first model. Spawning Redfoot on Sonnet is like hiring a painter and handing them a typewriter. - -2. **Cost mismatch.** Scribe merges inbox files into `decisions.md` — mechanical file manipulation. Burning premium Sonnet tokens on Scribe is like flying first class to the mailbox. Haiku handles this in a fraction of the cost and latency. - -3. **Depth mismatch.** Keaton (Lead) making an architecture decision that propagates across 8 agents and 3 sprints should get Opus-tier reasoning. A quick test scaffold from Hockney doesn't need that depth. One-size-fits-all wastes money on simple tasks and undersells complex ones. - -Brady's directive: *"We don't want Redfoot using Claude Sonnet to design imagery."* The model must match the agent's capabilities. - ---- - -## Design - -### Selection Priority (4-Layer) - -The coordinator resolves a model for every spawn. Four layers, checked in order. First match wins. - -| Priority | Source | Example | Override Behavior | -|----------|--------|---------|-------------------| -| **1. User Override** | User explicitly names a model or gives a budget/quality directive | "Use opus for this" / "Save costs" | Overrides all other layers. Session-wide directives persist until contradicted. | -| **2. Charter Preference** | Agent's charter `## Model` section with `Preferred` ≠ `auto` | `Preferred: claude-opus-4.5` (Designer needs vision) | Agent declared its own needs with rationale. | -| **3. Task-Aware Auto-Selection** | Coordinator evaluates role + task characteristics → picks best model | Lead doing architecture proposal → bumped to premium | The core algorithm. See below. | -| **4. Default Fallback** | No other layer matched | Any agent, any task | `claude-sonnet-4.5`. Always works with zero configuration. | - -**Layer 1 — User override detection:** -- Explicit model name: "use claude-opus-4.6", "spawn on haiku", "use gpt-5.2-codex" -- Budget directives: "save costs" → drop all non-essential spawns to fast/cheap tier -- Quality directives: "use the best model" → bump all spawns to premium tier -- Per-agent override: "use opus for Keaton" → applies only to that agent -- Session-wide: "always use sonnet" → applies to all spawns until contradicted - -### Task-Aware Auto-Selection Logic - -When Layers 1–2 don't apply, the coordinator uses role + task signals. This is the 80% case. - -**Step 1 — Role-Based Default:** - -| Role Category | Default Model | Tier | Why | -|---------------|--------------|------|-----| -| Lead / Architect | `claude-sonnet-4.5` | Standard | Strong reasoning + balanced cost. Bumped to premium for proposals. | -| Core Dev / Backend / Frontend | `claude-sonnet-4.5` | Standard | Best general code generation quality at reasonable cost. | -| Tester / QA | `claude-haiku-4.5` | Fast | Test generation is structured, pattern-heavy. Speed > depth. | -| Designer / Visual | `claude-opus-4.5` | Premium | Vision-capable. Required for image analysis and visual reasoning. | -| DevRel / Writer | `claude-sonnet-4.5` | Standard | Prose quality needs solid reasoning. Not as deep as architecture. | -| Scribe / Logger | `claude-haiku-4.5` | Fast | Mechanical file operations. Speed and cost matter, depth doesn't. | -| Platform / Infra | `claude-sonnet-4.5` | Standard | Platform analysis needs standard reasoning. | -| Prompt Engineer | `claude-sonnet-4.5` | Standard | Meta-reasoning about agents. Bumped to premium for complex designs. | -| Reviewer | `claude-sonnet-4.5` | Standard | Judgment calls. Bumped to premium for gate decisions. | -| Git / Release | `claude-haiku-4.5` | Fast | Mechanical operations. Changelogs, tags, version bumps. | - -**Step 2 — Task Complexity Override** (apply at most ONE — no cascading): - -- **Bump UP to premium:** architecture proposals, reviewer gates, security audits, multi-agent coordination (output feeds 3+ agents), design system architecture, complex prompt architecture -- **Bump DOWN to fast/cheap:** typo fixes, renames, boilerplate, scaffolding, changelogs, version bumps, mechanical file operations -- **Switch to code specialist (`gpt-5.2-codex`):** large multi-file refactors, complex implementation from detailed spec, heavy code generation (500+ lines) -- **Switch to analytical diversity (`gemini-3-pro-preview`):** code reviews where a second perspective helps, security reviews, architecture reviews after a rejection - -**Step 3 — Provider Diversity Triggers** (optional — a tool, not a religion): - -| Trigger | Consider | Why | -|---------|----------|-----| -| Code review (not implementation) | `gemini-3-pro-preview` | Different training data catches different issues. | -| Heavy code generation (multi-file) | `gpt-5.2-codex` | OpenAI Codex variants optimized for code generation. | -| Second-opinion after a rejection | Different provider than original reviewer | Cognitive diversity on re-review. | - -**When NOT to diversify:** first-time spawns with complex charters (stick to Anthropic — charters are Anthropic-optimized), Scribe or mechanical tasks (use cheapest), when user set a provider preference. - -### Charter Template — `## Model` Section - -Add to `templates/charter.md` after `## Boundaries`, before `## Collaboration`: - -```markdown -## Model - -- **Preferred:** auto -- **Rationale:** Coordinator selects the best model based on role and task complexity -- **Fallback:** Standard chain — the coordinator handles fallback automatically -``` - -| Field | Values | Meaning | -|-------|--------|---------| -| `Preferred` | A valid model ID (e.g., `claude-opus-4.5`) or `auto` | The model this agent should spawn on. `auto` delegates to auto-selection. | -| `Rationale` | Free text | Why this model. Forces justification. Prevents "opus for everything" cargo-culting. | -| `Fallback` | `Premium chain`, `Standard chain`, `Fast chain` | Which fallback chain when preferred model is unavailable. Defaults to the chain matching the preferred model's tier. | - -**Examples:** - -```markdown -## Model -- **Preferred:** claude-opus-4.5 -- **Rationale:** Vision-capable model required for image analysis, color reasoning, visual composition -- **Fallback:** Premium chain -``` - -```markdown -## Model -- **Preferred:** claude-haiku-4.5 -- **Rationale:** Mechanical file operations — speed and cost matter, depth doesn't -- **Fallback:** Fast chain -``` - -### Registry Integration - -Add a `model` field to `casting/registry.json` entries: - -```json -{ - "redfoot": { - "persistent_name": "Redfoot", - "model": "claude-opus-4.5" - }, - "hockney": { - "persistent_name": "Hockney", - "model": "claude-haiku-4.5" - } -} -``` - -**Resolution order:** User override → Charter `## Model` → Registry `model` → Auto-selection. - -Charter wins over registry on conflict. The agent's self-declared needs (with rationale) are more authoritative than the casting-time default. Registry exists for the team-level view — the coordinator reads it during routing to quickly see model assignments without opening every charter. - -### Delegation Support - -Model selection works for **every spawn path:** - -- **Coordinator → Agent:** Full 4-layer algorithm. The primary path. -- **Agent → Sub-agent:** Read target's charter `## Model` → use `Preferred` value. If `auto` or missing, omit `model` parameter (platform default). Agents don't need the full auto-selection algorithm. -- **Ceremony → Agent:** Coordinator controls these spawns. Same as coordinator → agent. - -**Key principle:** The charter `## Model` field travels with the agent. Anyone spawning that agent reads the same charter and gets the same model preference. - ---- - -## Model Catalog - -16 models across 3 providers. Full characterization in [Proposal 024a](024a-model-catalog.md). - -| Model ID | Provider | Tier | Best Fit | -|----------|----------|------|----------| -| `claude-opus-4.6` | Anthropic | Premium | Deepest reasoning. Architecture proposals, reviewer gates, complex cross-cutting decisions. | -| `claude-opus-4.6-fast` | Anthropic | Premium | Time-sensitive premium work. Reviews with deadlines, quick architecture gut-checks. | -| `claude-opus-4.5` | Anthropic | Premium | Vision-capable. Designer/Visual roles, creative + analytical reasoning. | -| `claude-sonnet-4.5` | Anthropic | Standard | The workhorse. Core Dev, Backend, Frontend, DevRel, Platform. Best balance of quality/speed/cost. | -| `claude-sonnet-4` | Anthropic | Standard | Previous-gen fallback. Reliable when Sonnet 4.5 specific behavior is needed. | -| `claude-haiku-4.5` | Anthropic | Fast | Fastest, cheapest. Scribe, Tester, simple code tasks, mechanical ops. | -| `gpt-5.2-codex` | OpenAI | Standard | Heavy code generation. Large refactors, multi-file implementations. | -| `gpt-5.2` | OpenAI | Standard | General OpenAI alternative. Provider diversity for non-code tasks. | -| `gpt-5.1-codex-max` | OpenAI | Standard | Hard code problems. Complex debugging, large-scale codebase analysis. | -| `gpt-5.1-codex` | OpenAI | Standard | Proven code-focused. Cross-provider diversity for code-heavy work. | -| `gpt-5.1` | OpenAI | Standard | Solid general-purpose fallback in the OpenAI family. | -| `gpt-5` | OpenAI | Standard | Legacy compatibility. Predictable, well-understood behavior. | -| `gpt-5.1-codex-mini` | OpenAI | Fast | Budget code tasks. Simple scaffolding, boilerplate. Code-aware but cheap. | -| `gpt-5-mini` | OpenAI | Fast | Fastest OpenAI. Mechanical tasks where OpenAI provider is preferred. | -| `gpt-4.1` | OpenAI | Fast | Ultra-budget. Structured output, well-understood behavior at lowest cost. | -| `gemini-3-pro-preview` | Google | Standard | Cross-provider reviews, analytical diversity. Different "perspective" on problems. | - -**Default models by tier:** -- **Premium:** `claude-opus-4.6` — deepest reasoning available -- **Standard:** `claude-sonnet-4.5` — best balance of quality, speed, cost -- **Fast/Cheap:** `claude-haiku-4.5` — fastest, cheapest, capable enough for structured tasks - ---- - -## Fallback Resilience - -**This is the most important section.** Brady's critical directive: the system must NOT break when a model is unavailable. Models may be blocked by Copilot plan restrictions, org policy, regional availability, deprecation, rate limiting, or any other reason. - -### Detection - -The coordinator detects model unavailability when: -1. Spawn returns an error message mentioning the model, availability, or access -2. Agent completes instantly with no meaningful work and an error in its output -3. Platform rejects the model parameter before the agent starts - -On any of these signals: **do not narrate the failure.** Silently retry with the next model in the fallback chain. - -### Fallback Chains by Tier - -Each tier has an ordered fallback chain. The coordinator walks the chain top-to-bottom. Cross-provider by design — if an Anthropic model fails, the next attempt is often OpenAI, handling provider-wide outages, not just single-model issues. - -``` -Premium Chain: - claude-opus-4.6 - → claude-opus-4.6-fast - → claude-opus-4.5 - → claude-sonnet-4.5 - → (omit model param) - -Standard Chain: - claude-sonnet-4.5 - → gpt-5.2-codex - → claude-sonnet-4 - → gpt-5.2 - → (omit model param) - -Fast/Cheap Chain: - claude-haiku-4.5 - → gpt-5.1-codex-mini - → gpt-4.1 - → gpt-5-mini - → (omit model param) -``` - -### Fallback Rules - -1. **Maximum 3 retries.** If the first 3 models in a chain fail, skip directly to `(omit model param)`. Don't burn time walking a 5-model chain. -2. **Silent by default.** The user sees the final successful spawn, not the failures. The coordinator does NOT say "Tried X, failed. Trying Y..." -3. **Log failures internally.** When a fallback occurs, note it in the orchestration log: `Model fallback: claude-opus-4.6 → claude-sonnet-4.5 (original unavailable)`. Internal only — user doesn't see it unless they ask. -4. **Respect user provider preferences.** If the user said "use Claude," fall back within Anthropic only: `opus-4.6 → opus-4.6-fast → opus-4.5 → sonnet-4.5 → sonnet-4 → (omit model param)`. Don't cross to GPT unless the user didn't specify a provider. -5. **Never fall back UP in tier.** A fast/cheap fallback should not land on a premium model. Chains are tier-scoped. - -### Nuclear Fallback - -`(omit model param)` — calling the `task` tool WITHOUT specifying `model` at all — lets the platform choose its own default. This is the bottom of every chain because: -- It always works (the platform always has a default) -- It requires no user configuration -- It's the behavior Squad had before model selection existed -- If even this fails, the spawn has a platform-level problem, not a model problem - ---- - -## Charter Template Section - -Add to `templates/charter.md`: - -```markdown -## Model - -- **Preferred:** auto -- **Rationale:** Coordinator selects the best model based on role and task complexity -- **Fallback:** Standard chain — the coordinator handles fallback automatically -``` - ---- - -## Coordinator Prompt Section - -Ready-to-paste `### Model Selection` text for `squad.agent.md`: - -```markdown -### Model Selection - -Before spawning an agent, determine which model to use. Check these layers in order — first match wins: - -**Layer 1 — User Override:** Did the user specify a model? ("use opus", "save costs", "use gpt-5.2-codex for this"). If yes, use that model. Session-wide directives ("always use haiku") persist until contradicted. - -**Layer 2 — Charter Preference:** Does the agent's charter have a `## Model` section with `Preferred` set to a specific model (not `auto`)? If yes, use that model. - -**Layer 3 — Task-Aware Auto-Selection:** Match the agent's role to a default model, then adjust for task complexity: - -| Role | Default Model | Bump to Premium When | -|------|--------------|---------------------| -| Lead / Architect | `claude-sonnet-4.5` | Architecture proposals, cross-cutting decisions, multi-agent coordination plans | -| Core Dev / Backend / Frontend | `claude-sonnet-4.5` | — (use Codex specialist for heavy code gen — see below) | -| Tester / QA | `claude-haiku-4.5` | Complex test strategy requiring analysis (bump to sonnet) | -| Designer / Visual | `claude-opus-4.5` | Design system architecture needing deep reasoning (bump to opus-4.6) | -| DevRel / Writer | `claude-sonnet-4.5` | — | -| Scribe / Logger | `claude-haiku-4.5` | — (never bump Scribe) | -| Platform / Infra | `claude-sonnet-4.5` | Security audits, threat modeling | -| Prompt Engineer | `claude-sonnet-4.5` | Complex multi-agent pattern design, prompt architecture | -| Reviewer | `claude-sonnet-4.5` | Approval/rejection gates with downstream consequences | -| Git / Release | `claude-haiku-4.5` | — (never bump mechanical ops) | - -**Task Complexity Adjustments** (apply at most ONE): -- **Bump UP to premium:** architecture proposals, reviewer gates, security audits, multi-agent coordination, design system architecture -- **Bump DOWN to fast/cheap:** typo fixes, renames, boilerplate, scaffolding, changelogs, version bumps -- **Switch to code specialist (`gpt-5.2-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation -- **Switch to analytical diversity (`gemini-3-pro-preview`):** code reviews where a second perspective helps, security reviews, architecture reviews after a rejection - -**Layer 4 — Default:** If nothing else matched, use `claude-sonnet-4.5`. This always works with zero configuration. - -**Fallback Chains — when a model is unavailable:** - -If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the chain. Do NOT tell the user about fallback attempts. Maximum 3 retries before jumping to the nuclear fallback. - -``` -Premium: claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.5 → (omit model param) -Standard: claude-sonnet-4.5 → gpt-5.2-codex → claude-sonnet-4 → gpt-5.2 → (omit model param) -Fast: claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini → (omit model param) -``` - -`(omit model param)` = call the `task` tool WITHOUT the `model` parameter. The platform uses its built-in default. This is the nuclear fallback — it always works. - -**Fallback rules:** -- If the user specified a provider ("use Claude"), fall back within that provider only before hitting nuclear -- Never fall back UP in tier — a fast/cheap task should not land on a premium model -- Log fallbacks to the orchestration log for debugging, but never surface to the user unless asked - -**Spawn output format — show the model choice:** - -When spawning, include the model in your acknowledgment: - -``` -🔧 Fenster (claude-sonnet-4.5) — refactoring auth module -🎨 Redfoot (claude-opus-4.5 · vision) — designing color system -📋 Scribe (claude-haiku-4.5 · fast) — logging session -⚡ Keaton (claude-opus-4.6 · bumped for architecture) — reviewing proposal -🔬 Hockney (gpt-5.2-codex · code specialist) — large refactor across 12 files -``` - -Include tier annotation only when the model was bumped or a specialist was chosen. Default-tier spawns just show the model name. - -**Adding the model parameter to spawns:** - -Pass the resolved model as the `model` parameter on every `task` tool call: - -``` -agent_type: "general-purpose" -model: "claude-sonnet-4.5" -mode: "background" -description: "Fenster: refactoring auth module" -prompt: | - ... -``` - -If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely. - -**Valid models (current platform catalog):** - -Premium: `claude-opus-4.6`, `claude-opus-4.6-fast`, `claude-opus-4.5` -Standard: `claude-sonnet-4.5`, `claude-sonnet-4`, `gpt-5.2-codex`, `gpt-5.2`, `gpt-5.1-codex-max`, `gpt-5.1-codex`, `gpt-5.1`, `gpt-5`, `gemini-3-pro-preview` -Fast/Cheap: `claude-haiku-4.5`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1` -``` - ---- - -## Implementation Plan - -From [Proposal 027](027-v030-sprint-plan.md) — v0.3.0 Wave 1, Items 4.1–4.4. - -| ID | Item | Owner | Effort | Depends On | -|----|------|-------|--------|------------| -| **4.1** | Model auto-selection algorithm in coordinator — add `### Model Selection` section to `squad.agent.md`, 4-layer priority, role-to-model mapping, task complexity overrides, `model` parameter on all `task` calls | Verbal + Kujan | 3–4h | — | -| **4.2** | Charter `## Model` section + template update — `Preferred`, `Rationale`, `Fallback` fields, delegation support, default `auto` | Verbal | 1–2h | 4.1 | -| **4.3** | Registry `model` field + migration — schema update, `templates/casting-registry.json` update, additive upgrade migration populating defaults from role-to-model mapping | Fenster | 2–3h | 4.1 | -| **4.4** | Model selection tests — registry model field in migration, charter template validation, registry schema, upgrade path tests | Hockney | 2–3h | 4.1, 4.2, 4.3 | - -**Phase 1 (Items 4.1):** Coordinator instructions + auto-selection. Zero code changes — pure prompt engineering. The coordinator already spawns agents; this adds a `model` parameter to existing spawns. - -**Phase 2 (Items 4.2–4.3):** Charter + registry integration. Template additions + additive migration. No destructive changes. - -**Wave 2 follow-up (Item 5.3):** Model visibility in spawn output — Verbal, 1h, depends on 4.1. - ---- - -## Success Criteria - -- [ ] Redfoot spawns on a vision-capable model (Opus) without any user configuration -- [ ] Scribe/Hockney spawn on Haiku by default, cutting cost and latency for mechanical tasks -- [ ] User can say "use opus for everything" and it works -- [ ] User can say "save costs" and the coordinator drops all agents to the cheapest viable model -- [ ] Model choice is visible and explainable at spawn time -- [ ] Zero existing behavior breaks — agents without model config get Sonnet 4.5 (current default) -- [ ] Agent-to-agent delegation respects the target agent's charter model preference -- [ ] Model unavailability is handled silently — fallback chains terminate, nuclear fallback always works -- [ ] No user-facing error when any single model or provider is unavailable - ---- - -## Trade-offs - -| Decision | Trade-off | -|---|---| -| Charter model > Registry model | Agents can "demand" expensive models. Mitigated by coordinator judgment + user override. | -| Haiku default for Tester/Scribe | Risk of quality issues on complex test scenarios. Mitigated by task complexity bumps. | -| Deterministic algorithm over LLM judgment | Less flexible, but predictable and debuggable. Coordinator can still apply judgment on top. | -| Cross-provider fallback chains | Prompt portability risk — charters are Anthropic-optimized. Mitigated by conservative cross-provider usage. | -| Silent fallback (no user notification) | Users may not know they're on a fallback model. Mitigated by orchestration log capture. | -| 3-retry max before nuclear | May skip viable models in the chain. Acceptable — nuclear fallback always works, and 3 retries covers the common cases. | - ---- - -## What's Deferred - -| Feature | Why Not Now | Revisit When | -|---------|-------------|--------------| -| **Model cost reporting** | Polish, not leverage. Auto-selection delivers 90% of value. | User feedback requests it | -| **Override persistence** | Session-level overrides work. Persistence can wait. | v0.4.0 | -| **Prompt portability testing** | Cross-provider execution works but charters are untested on non-Anthropic models. | After cross-provider spawns are observed in production | -| **Budget mode** | Team-level cost cap. Needs model cost data first. | After cost reporting ships | -| **Model performance tracking** | Log model × task outcomes over time. Needs production data. | v0.4.0+ | -| **Skills model requirements** | SKILL.md declaring model preferences. Needs proven skills system. | v0.4.0+ | - ---- - -## Open Questions (Resolved) - -1. ~~Should the coordinator log model selection reasoning?~~ **Yes** — to orchestration log, not user-facing. -2. ~~Should model selection be part of portable squad export?~~ **Yes** — it's part of the agent's identity. -3. ~~Should there be a team-level "budget mode"?~~ **Deferred** — needs cost reporting first. diff --git a/team-docs/proposals/024a-model-catalog.md b/team-docs/proposals/024a-model-catalog.md deleted file mode 100644 index 71ff29ff2..000000000 --- a/team-docs/proposals/024a-model-catalog.md +++ /dev/null @@ -1,293 +0,0 @@ -**Note:** This is a companion research document. The consolidated spec is [Proposal 024](024-per-agent-model-selection.md). - -# Proposal 024a: Model Catalog — Full Platform Research - -**Status:** Research Complete -**Author:** Kujan (Copilot SDK Expert) -**Date:** 2026-02-10 -**Companion to:** Proposal 024 (Per-Agent Model Selection) -**Requested by:** bradygaster — *"we should have a much, much more broad list of models from which we'd choose and justifications as to why we'd choose one model or another."* - ---- - -## Purpose - -Proposal 024 designed the model selection architecture (4-layer priority, charter fields, auto-selection algorithm). But it hardcoded only 3 models: Opus for designers, Haiku for Scribe, Sonnet for everyone else. Brady correctly pushed back — the `task` tool supports **16 models across 3 providers**, and the selection algorithm should leverage the full catalog. - -This document is the raw research. It catalogs every available model, characterizes strengths and weaknesses, and identifies which Squad roles and tasks each model fits best. **Verbal uses this to build the selection algorithm. This document does NOT define the algorithm itself.** - ---- - -## Full Model Catalog - -### Anthropic Models (5 models) - -| Model ID | Display Name | Tier | Context | Strengths | Weaknesses | Best Squad Fit | -|----------|-------------|------|---------|-----------|------------|----------------| -| `claude-opus-4.6` | Claude Opus 4.6 | Premium | Large | Deepest reasoning in the Anthropic family. Extended thinking. Best-in-class for complex multi-step analysis, architecture decisions, and nuanced judgment calls. Strong instruction following even with very long prompts. | Slowest Anthropic model. Highest cost. Overkill for mechanical tasks. | Lead (architecture proposals), Designer (vision + deep reasoning), Reviewer gates (approval/rejection decisions), complex cross-cutting proposals | -| `claude-opus-4.6-fast` | Claude Opus 4.6 (fast mode) | Premium | Large | Same model weights as Opus 4.6 but with reduced thinking budget — trades some reasoning depth for significantly faster response time. Still premium-tier quality. | Still expensive. Less deep thinking than full Opus 4.6 — may miss subtle issues that extended thinking would catch. | Time-sensitive premium tasks: code reviews with deadlines, quick architecture gut-checks, reviewer gates where speed matters | -| `claude-opus-4.5` | Claude Opus 4.5 | Premium | Large | Previous-generation Opus. Strong creative and analytical reasoning. Vision-capable — can analyze images, diagrams, color systems. Proven track record. | Older generation — Opus 4.6 surpasses it on reasoning benchmarks. Still expensive. | Designer/Visual roles (vision capability confirmed), creative writing, tasks where vision analysis is required | -| `claude-sonnet-4.5` | Claude Sonnet 4.5 | Standard | Large | Excellent balance of quality and speed. Strong code generation. Good instruction following. Reliable for structured output (JSON, markdown). Handles long context well. | Not as deep as Opus for complex reasoning. Not as fast or cheap as Haiku. The "middle of the road" — which is often exactly right. | Core Dev, Backend, Frontend, DevRel/Writer, Platform/Infra — the workhorse tier | -| `claude-sonnet-4` | Claude Sonnet 4 | Standard | Large | Solid, well-tested model. Reliable code generation and prose. Good at following complex multi-step instructions. Well-understood behavior from extensive use. | Previous generation — Sonnet 4.5 is generally better. Still capable but no reason to prefer over 4.5 unless specific behavior is needed. | Fallback for any Sonnet-tier task. Good for consistency if the team has calibrated prompts against this specific version. | -| `claude-haiku-4.5` | Claude Haiku 4.5 | Fast/Cheap | Standard | Fastest Anthropic model. Lowest cost. Surprisingly capable for structured tasks — file manipulation, test generation, pattern-heavy work. Excellent latency for interactive workflows. | Weakest reasoning of the Anthropic lineup. Struggles with nuanced judgment, complex architecture decisions, and creative tasks. More prone to instruction-following errors on complex prompts. | Scribe (mechanical file ops), Tester/QA (structured test generation), simple code tasks (renames, typo fixes), any task where speed > depth | - -### OpenAI Models (8 models) - -| Model ID | Display Name | Tier | Strengths | Weaknesses | Best Squad Fit | -|----------|-------------|------|-----------|------------|----------------| -| `gpt-5.2-codex` | GPT-5.2-Codex | Standard | Latest OpenAI code-specialized model. Strong at code generation, refactoring, and understanding complex codebases. Likely optimized for developer workflows — completions, edits, test writing. | Newer model — less community feedback on edge cases. Code-specialized means potentially weaker at pure prose or creative tasks. | Core Dev, Backend, Frontend — heavy code generation tasks. Code reviews. Large refactoring operations. | -| `gpt-5.2` | GPT-5.2 | Standard | Latest general-purpose OpenAI model. Broad capabilities across reasoning, code, and prose. Benefits from the latest training data and techniques. | Newer model — behavior characteristics still being discovered. General-purpose means not specialized for any single task. | DevRel/Writer, Lead (general analysis), Platform — tasks needing broad capability without code specialization | -| `gpt-5.1-codex-max` | GPT-5.1-Codex-Max | Standard | Extended compute variant of GPT-5.1-Codex. More reasoning depth for complex code tasks — likely uses additional inference-time compute. Good for hard problems. | Higher latency and cost than base Codex. May be overkill for simple code tasks. | Complex architecture implementations, difficult debugging, large-scale code analysis, multi-file refactors | -| `gpt-5.1-codex` | GPT-5.1-Codex | Standard | Proven code-focused model. Strong code generation and comprehension. Well-established — more community usage data than 5.2. | Previous generation — 5.2-Codex likely superior. Still very capable. | Core Dev tasks where OpenAI code quality is preferred. Cross-provider diversity for code-heavy work. | -| `gpt-5.1` | GPT-5.1 | Standard | Solid general-purpose model. Good balance of reasoning, code, and prose. Well-tested in production. | Previous generation. No standout specialization. | General-purpose fallback in the OpenAI family | -| `gpt-5` | GPT-5 | Standard | First GPT-5 generation. Broad reasoning capabilities. Known behavior patterns. | Oldest in the GPT-5 family. Superseded by 5.1 and 5.2. | Legacy compatibility. Tasks where predictable, well-understood behavior matters more than cutting edge. | -| `gpt-5.1-codex-mini` | GPT-5.1-Codex-Mini | Fast/Cheap | Fast, cheap, code-aware. Good for simple code tasks — boilerplate generation, test scaffolding, file manipulation. Lower latency than full Codex. | Weaker reasoning. Struggles with complex multi-step code tasks. Less reliable instruction following. | Scribe-equivalent tasks in OpenAI ecosystem. Simple test generation. Boilerplate code. | -| `gpt-5-mini` | GPT-5 mini | Fast/Cheap | Fastest OpenAI model. Lowest cost. Good for simple, well-structured tasks. Quick responses. | Weakest in the OpenAI lineup. Not suitable for complex reasoning or nuanced tasks. Older generation mini. | Mechanical tasks where OpenAI provider is preferred. Simple file operations. Quick lookups. | -| `gpt-4.1` | GPT-4.1 | Fast/Cheap | Previous-generation model at budget pricing. Well-understood behavior. Strong instruction following for its tier. Good at structured output. | Not GPT-5 class. Weaker reasoning than any GPT-5 variant. | Budget tasks where behavior predictability matters more than capability ceiling. Structured output generation. | - -### Google Models (1 model) - -| Model ID | Display Name | Tier | Strengths | Weaknesses | Best Squad Fit | -|----------|-------------|------|-----------|------------|----------------| -| `gemini-3-pro-preview` | Gemini 3 Pro (Preview) | Standard | Google's latest reasoning model. Strong at analytical tasks, mathematical reasoning, and structured thinking. Different training approach than Anthropic/OpenAI — may catch issues others miss. Good multilingual capability. Large context window expected. | Preview status — behavior may change. Less battle-tested in agent workflows than Claude or GPT models. Single model offering limits tier flexibility within Google's lineup. | Second-opinion reviews, analytical tasks, cross-provider diversity assignments, tasks benefiting from a different "perspective" | - ---- - -## Model Selection Dimensions - -These are the factors that matter when choosing a model for a Squad agent or task. The selection algorithm should weigh these based on the agent's role and the task at hand. - -### 1. Reasoning Depth - -**What it means:** How well the model handles complex, multi-step reasoning — architecture decisions, cross-cutting analysis, subtle trade-off evaluation. - -**Spectrum:** -- **Deep:** Opus 4.6, Opus 4.6-fast, GPT-5.1-Codex-Max -- **Strong:** Opus 4.5, Sonnet 4.5, GPT-5.2, GPT-5.2-Codex, Gemini 3 Pro -- **Adequate:** Sonnet 4, GPT-5.1, GPT-5.1-Codex, GPT-5 -- **Light:** Haiku 4.5, GPT-5.1-Codex-Mini, GPT-5-Mini, GPT-4.1 - -**When it matters most:** Lead/Architect decisions, reviewer gates, complex proposals, security audits. - -### 2. Code Generation Quality - -**What it means:** Accuracy, idiom-correctness, and reliability of generated code. Includes understanding of codebases, refactoring, and test generation. - -**Spectrum:** -- **Excellent:** GPT-5.2-Codex, GPT-5.1-Codex-Max, Sonnet 4.5, Opus 4.6 -- **Strong:** GPT-5.1-Codex, Opus 4.5, Sonnet 4, GPT-5.2 -- **Good:** GPT-5.1, GPT-5, Gemini 3 Pro -- **Adequate:** Haiku 4.5, GPT-5.1-Codex-Mini -- **Basic:** GPT-5-Mini, GPT-4.1 - -**When it matters most:** Core Dev implementation, test generation, refactoring, code review. - -### 3. Speed / Latency - -**What it means:** How fast the model returns a complete response. Critical for interactive workflows and mechanical tasks. - -**Spectrum:** -- **Fastest:** Haiku 4.5, GPT-5-Mini, GPT-4.1, GPT-5.1-Codex-Mini -- **Fast:** Sonnet 4, Sonnet 4.5, GPT-5.1, GPT-5 -- **Moderate:** GPT-5.2, GPT-5.1-Codex, GPT-5.2-Codex, Opus 4.6-fast, Gemini 3 Pro -- **Slow:** Opus 4.5, Opus 4.6, GPT-5.1-Codex-Max - -**When it matters most:** Scribe operations, simple edits, interactive user-facing tasks, fan-out spawns where latency compounds. - -### 4. Cost Efficiency - -**What it means:** Token cost relative to capability. Burning premium tokens on simple tasks is waste; underinvesting on critical decisions is false economy. - -**Spectrum:** -- **Budget:** Haiku 4.5, GPT-5-Mini, GPT-4.1, GPT-5.1-Codex-Mini -- **Moderate:** Sonnet 4, Sonnet 4.5, GPT-5.1, GPT-5, GPT-5.1-Codex, GPT-5.2 -- **Elevated:** GPT-5.2-Codex, GPT-5.1-Codex-Max, Gemini 3 Pro -- **Premium:** Opus 4.5, Opus 4.6, Opus 4.6-fast - -**When it matters most:** Always. But especially for high-frequency spawns (Scribe runs every session) and fan-out patterns (5 agents spawned simultaneously). - -### 5. Instruction Following - -**What it means:** How reliably the model follows complex, multi-part instructions — especially important for agents with long charters and specific behavioral requirements. - -**Spectrum:** -- **Excellent:** Opus 4.6, Sonnet 4.5, GPT-5.2-Codex -- **Strong:** Opus 4.5, Sonnet 4, GPT-5.2, GPT-5.1-Codex -- **Good:** GPT-5.1, GPT-5, Gemini 3 Pro -- **Variable:** Haiku 4.5, GPT-5-Mini, GPT-4.1, GPT-5.1-Codex-Mini - -**When it matters most:** Every Squad agent — the charter IS a complex instruction set. Agents with long charters (coordinator is 32KB+) need excellent instruction following. Lighter agents with simple charters can tolerate variable instruction following. - -### 6. Vision Capability - -**What it means:** Ability to analyze images, diagrams, screenshots, color systems, and visual composition. - -**Models with vision:** Opus 4.5, Opus 4.6 (Anthropic vision models), GPT-5.x models (OpenAI multimodal), Gemini 3 Pro (Google multimodal) - -**When it matters most:** Designer/Visual roles. Exclusively. - -### 7. Context Window - -**What it means:** How much input the model can process. Critical for agents that receive large charters + history + decisions + input artifacts. - -**All models listed support at least 128K context** in the Copilot platform, which is the platform's constraint rather than the model's. This dimension is effectively equalized by the platform. - -### 8. Structured Output - -**What it means:** Reliability of generating valid JSON, markdown tables, YAML, and other structured formats without hallucination or formatting errors. - -**Strongest:** GPT-5.2-Codex, Sonnet 4.5, GPT-5.1-Codex (code-trained models excel here) -**Weakest:** Mini/budget models under complex structure requirements - -**When it matters most:** Registry operations, config generation, structured proposals, test output formatting. - ---- - -## Provider Diversity - -### Why Multi-Provider Support Matters - -**1. Resilience** - -Single-provider dependency is a single point of failure. If Anthropic has an outage or rate-limits heavily, a team running all agents on Claude is dead in the water. Multi-provider support means Squad can route around provider issues — Sonnet goes down, re-route to GPT-5.2-Codex for code tasks. - -This isn't theoretical. Provider outages happen. Rate limits hit. Regional availability varies. A production-grade multi-agent system should not be fragile to one provider's uptime. - -**2. Best-of-Breed Selection** - -No single provider dominates every dimension: - -| Dimension | Current Best-of-Breed | -|-----------|----------------------| -| Deep reasoning | Anthropic (Opus 4.6) | -| Code generation | OpenAI (Codex variants) | -| Speed + cost | Anthropic (Haiku 4.5) | -| Analytical diversity | Google (Gemini 3 Pro) | -| Instruction following | Anthropic (Opus/Sonnet) | -| Structured output | OpenAI (Codex variants) | - -A selection algorithm that only considers Anthropic models leaves code generation quality on the table. One that ignores Google loses the "different perspective" advantage for reviews. - -**3. Avoid Lock-In** - -Squad's portable squads feature (Proposal 008) means teams export and import across projects. If model selection is hardcoded to one provider, portability is limited to environments where that provider is available. Multi-provider selection makes squads truly portable. - -Provider lock-in also creates negotiation disadvantage, training data bias (all agents think alike because they're trained on similar data), and vulnerability to provider policy changes. - -**4. Cognitive Diversity** - -Different providers train on different data with different techniques. An Anthropic model and an OpenAI model may disagree on an architecture decision — and that disagreement is valuable signal. A reviewer using Gemini may catch issues that a Claude-based implementer missed, precisely because they "think differently." - -This matters most for: code reviews, architecture proposals, security audits — any task where a second perspective has value. - -### Provider Diversity Risks - -- **Prompt tuning fragility.** A charter prompt optimized for Claude may underperform on GPT. The coordinator's instructions are Anthropic-optimized today. -- **Behavioral inconsistency.** Different providers interpret the same instruction differently. An agent might behave subtly differently on GPT vs. Claude. -- **Testing surface.** Multi-provider means multi-provider testing. Charter prompts should be validated against each provider they might run on. -- **Preview instability.** Gemini 3 Pro is in preview. Its behavior may change between sessions. - -**Mitigation:** Start with Anthropic as the default family (proven, well-understood). Use OpenAI for code-specialized tasks where Codex variants excel. Use Google for diversity/review tasks. Expand cross-provider usage as prompt portability improves. - ---- - -## Default vs. Specialist Recommendations - -### Default Models — "Safe Choices" - -These models should be the algorithm's first consideration for their respective tiers. They're well-tested, reliable, and provide the best general-purpose capability at their price point. - -| Tier | Default Model | Why | -|------|--------------|-----| -| **Premium** | `claude-opus-4.6` | Deepest reasoning available. When you need premium, you want the best. | -| **Standard** | `claude-sonnet-4.5` | Best balance of quality, speed, and cost. The workhorse. | -| **Fast/Cheap** | `claude-haiku-4.5` | Fastest, cheapest, and capable enough for structured tasks. | - -### Specialist Models — "Right Tool for the Job" - -These models should be considered when the task has specific characteristics that make them a better fit than the default. - -| Model | Specialist Use Case | When to Reach for It | -|-------|-------------------|---------------------| -| `claude-opus-4.6-fast` | Time-sensitive premium work | Reviewer gates with deadlines, quick architecture reviews — need premium quality but can't wait for full Opus | -| `claude-opus-4.5` | Vision-required tasks | Designer/Visual roles that need image analysis (proven vision capability) | -| `gpt-5.2-codex` | Heavy code generation | Large refactors, multi-file code changes, complex implementation tasks where code quality is the primary dimension | -| `gpt-5.1-codex-max` | Hard code problems | Debugging complex issues, analyzing large codebases, problems where extra inference-time compute pays off | -| `gpt-5.1-codex-mini` | Budget code tasks | Simple code scaffolding, boilerplate generation — code-aware but cheap | -| `gemini-3-pro-preview` | Cross-provider reviews | Code reviews, architecture reviews, security audits — value in a different perspective | -| `gpt-5.2` | General OpenAI alternative | When provider diversity is desired for non-code tasks | -| `gpt-4.1` | Ultra-budget tasks | When even Haiku feels expensive — very simple, well-structured tasks with clear instructions | - -### Models to Avoid as Defaults - -| Model | Why Not Default | Still Useful When | -|-------|----------------|-------------------| -| `claude-sonnet-4` | Superseded by Sonnet 4.5 | Prompt regression testing, when specific Sonnet 4 behavior is needed | -| `gpt-5.1-codex` | Superseded by GPT-5.2-Codex | Cross-version comparison, when 5.1 behavior is specifically needed | -| `gpt-5.1` | Superseded by GPT-5.2 | Stability preference, when 5.1's behavior is well-calibrated | -| `gpt-5` | Oldest GPT-5 generation | Legacy compatibility only | -| `gpt-5-mini` | GPT-4.1 or Haiku 4.5 are better budget choices | Specific OpenAI Mini behavior needed | - ---- - -## Role-to-Model Mapping (Expanded) - -This replaces the 3-model mapping from Proposal 024 with a catalog-aware version. The selection algorithm should use this as input, not as the final answer — task complexity overrides still apply. - -| Role Category | Default Model | Specialist Alternative | When to Switch | -|---------------|--------------|----------------------|----------------| -| **Lead / Architect** | `claude-sonnet-4.5` | `claude-opus-4.6` | Architecture proposals, cross-cutting decisions, multi-agent coordination plans | -| **Core Dev / Backend** | `claude-sonnet-4.5` | `gpt-5.2-codex` | Heavy code generation, large refactors, multi-file implementations | -| **Frontend Dev** | `claude-sonnet-4.5` | `gpt-5.2-codex` | Complex UI implementations, component libraries | -| **Tester / QA** | `claude-haiku-4.5` | `gpt-5.1-codex-mini` | Cross-provider test validation, code-aware test generation | -| **Designer / Visual** | `claude-opus-4.5` | `claude-opus-4.6` | When design requires both vision AND deep reasoning (design system architecture) | -| **DevRel / Writer** | `claude-sonnet-4.5` | `gpt-5.2` | When OpenAI prose style is preferred, cross-provider content review | -| **Scribe / Logger** | `claude-haiku-4.5` | `gpt-4.1` | Ultra-budget mode, provider diversity for mechanical tasks | -| **Platform / Infra** | `claude-sonnet-4.5` | `gemini-3-pro-preview` | Platform analysis benefiting from Google's infrastructure perspective | -| **Prompt Engineer** | `claude-sonnet-4.5` | `claude-opus-4.6` | Complex prompt architecture, multi-agent coordination design | -| **Reviewer** | `claude-sonnet-4.5` | `gemini-3-pro-preview` | Cross-provider review for cognitive diversity | -| **Git / Release** | `claude-haiku-4.5` | `gpt-5.1-codex-mini` | Mechanical git operations, changelog generation | - ---- - -## Honesty Notes — What I Know vs. Don't Know - -**High confidence (well-established model families):** -- Anthropic Claude tier characteristics (Opus > Sonnet > Haiku) -- OpenAI Codex code specialization advantage -- Vision capability in Opus models -- General tier pricing (premium > standard > fast/cheap) - -**Medium confidence (extrapolated from family patterns):** -- GPT-5.2 improvements over GPT-5.1 (assumed incremental, following GPT patterns) -- Opus 4.6 vs Opus 4.5 (assumed newer = better reasoning, following Anthropic patterns) -- Codex-Max extended compute behavior (inferred from naming convention and tier placement) - -**Low confidence (limited information):** -- Gemini 3 Pro Preview — "preview" status means behavior may change. Characterization is based on Google's general model trajectory. -- GPT-5.2-Codex vs GPT-5.1-Codex-Max — which is better for hard code problems is genuinely unclear. Different optimization strategies (newer training vs. more compute). -- Exact cost ratios between providers — platform pricing may differ from direct API pricing. -- Cross-provider prompt portability — how well Squad's Anthropic-optimized charters work on GPT/Gemini models is untested. - -**Unknown:** -- Whether the platform applies any model-level rate limits differently -- Whether all 16 models have identical context window support on the platform (128K is the platform constraint, but some models might have lower effective limits) -- Performance characteristics of models under Squad's specific prompt patterns (32KB+ coordinator, inline charter pattern) - ---- - -## Summary for Verbal - -You're building the selection algorithm. Here's what this research gives you: - -1. **16 models, 3 providers, 3 tiers.** The full catalog is above. Every model has an exact ID string ready for the `task` tool's `model` parameter. - -2. **8 selection dimensions.** Reasoning depth, code generation, speed, cost, instruction following, vision, context, structured output. Weight these based on role + task. - -3. **3 defaults + 8 specialists.** Start with Sonnet 4.5 / Haiku 4.5 / Opus 4.6 as the base tier, then switch to specialists when task characteristics warrant it. - -4. **Provider diversity is a feature, not a nice-to-have.** Resilience, best-of-breed, lock-in avoidance, and cognitive diversity all argue for cross-provider selection. But start conservative — Anthropic defaults, OpenAI for code specialization, Google for review diversity. - -5. **Expanded role-to-model mapping.** The 3-model mapping from Proposal 024 is now an 11-role × 2-model matrix with clear switching criteria. - -Build the algorithm. This is your input data. diff --git a/team-docs/proposals/024b-model-selection-algorithm.md b/team-docs/proposals/024b-model-selection-algorithm.md deleted file mode 100644 index 3f4f4cff8..000000000 --- a/team-docs/proposals/024b-model-selection-algorithm.md +++ /dev/null @@ -1,395 +0,0 @@ -**Note:** This is a companion algorithm document. The consolidated spec is [Proposal 024](024-per-agent-model-selection.md). - -# Proposal 024b: Model Selection Algorithm - -**Status:** Draft -**Author:** Verbal (Prompt Engineer & AI Strategist) -**Date:** 2026-02-10 -**Companion to:** Proposal 024 (Per-Agent Model Selection), Proposal 024a (Model Catalog) -**Sprint:** v0.3.0 Wave 1, Item 4.1 -**Requested by:** bradygaster — graceful fallback when a model isn't available - ---- - -## Purpose - -This document defines the model selection algorithm — the exact coordinator prompt instructions that determine which model each agent spawns on, and what happens when that model isn't available. Kujan's catalog (024a) provides the raw data. This document turns it into decisions. - -Brady's critical directive: **the system must NOT break when a model is unavailable.** Models may be blocked by Copilot plan restrictions, org policy, regional availability, deprecation, rate limiting, or any other reason. The coordinator must fall back gracefully — and silently. - ---- - -## 1. Selection Priority (4-Layer) - -The coordinator resolves a model for every spawn. Four layers, checked in order. First match wins. - -| Priority | Source | Example | Override Behavior | -|----------|--------|---------|-------------------| -| **1. User Override** | User explicitly names a model in the current message or a session-wide directive | "Use opus for this" / "Save costs, use haiku for everything" | Overrides all other layers. Session-wide directives persist until contradicted. | -| **2. Charter Preference** | Agent's charter has a `## Model` section with a `Preferred` value other than `auto` | `Preferred: claude-opus-4.5` (Designer needs vision) | Overrides auto-selection. The agent declared its own needs with rationale. | -| **3. Task-Aware Auto-Selection** | Coordinator evaluates role + task characteristics → picks best model | Lead doing architecture proposal → bumped to premium | The core algorithm. See Section 2. | -| **4. Default Fallback** | No other layer matched | Any agent, any task | `claude-sonnet-4.5`. Always. This is the "no config needed" baseline. | - -**Layer 1 detail — user override detection:** -- Explicit model name: "use claude-opus-4.6", "spawn on haiku", "use gpt-5.2-codex" -- Budget directives: "save costs" → drop all non-essential spawns to fast/cheap tier -- Quality directives: "use the best model" → bump all spawns to premium tier -- Per-agent override: "use opus for Keaton" → applies only to that agent -- Session-wide: "always use sonnet" → applies to all spawns until contradicted - ---- - -## 2. Task-Aware Auto-Selection Logic - -When Layers 1-2 don't apply, the coordinator uses role + task signals to pick a model. This is the 80% case — most spawns hit Layer 3 or 4. - -### Step 1: Role-Based Default - -Start with the agent's role category. This is the baseline before task signals adjust it. - -| Role Category | Default Model | Tier | Why | -|---------------|--------------|------|-----| -| Lead / Architect | `claude-sonnet-4.5` | Standard | Strong reasoning + balanced cost. Bumped to premium for proposals. | -| Core Dev / Backend | `claude-sonnet-4.5` | Standard | Best general code generation quality at reasonable cost. | -| Frontend Dev | `claude-sonnet-4.5` | Standard | Same reasoning — UI code benefits from structured output. | -| Tester / QA | `claude-haiku-4.5` | Fast | Test generation is structured, pattern-heavy. Speed > depth. | -| Designer / Visual | `claude-opus-4.5` | Premium | Vision-capable. Required for image analysis and visual reasoning. | -| DevRel / Writer | `claude-sonnet-4.5` | Standard | Prose quality needs solid reasoning. Not as deep as architecture. | -| Scribe / Logger | `claude-haiku-4.5` | Fast | Mechanical file operations. Speed and cost matter, depth doesn't. | -| Platform / Infra | `claude-sonnet-4.5` | Standard | Platform analysis needs standard reasoning. | -| Prompt Engineer | `claude-sonnet-4.5` | Standard | Meta-reasoning about agents. Bumped to premium for complex designs. | -| Reviewer | `claude-sonnet-4.5` | Standard | Judgment calls. Bumped to premium for gate decisions. | -| Git / Release | `claude-haiku-4.5` | Fast | Mechanical operations. Changelogs, tags, version bumps. | - -### Step 2: Task Complexity Override - -After selecting the role default, the coordinator checks the task for signals that warrant a tier bump (up or down). Apply AT MOST ONE override — no cascading. - -**Bump UP to premium** when the task involves: -- Architecture proposals or cross-cutting design decisions -- Reviewer approval/rejection gates (the decision has downstream consequences) -- Multi-agent coordination plans (output feeds 3+ other agents) -- Security audits or threat modeling -- Complex prompt architecture or multi-agent pattern design -- Design system architecture (Designer needing both vision AND deep reasoning) - -**Bump DOWN to fast/cheap** when the task involves: -- Simple renames, typo fixes, or single-line changes -- Boilerplate generation or scaffolding -- Changelog updates or version bumps -- File operations with clear, mechanical instructions -- Status checks that don't require analysis - -**Switch to code-specialized** when the task involves: -- Large multi-file refactoring (consider `gpt-5.2-codex`) -- Complex implementation from a detailed spec (consider `gpt-5.2-codex`) -- Hard debugging across multiple modules (consider `gpt-5.1-codex-max`) - -### Step 3: Provider Diversity Triggers - -These are OPTIONAL. The coordinator should consider them but not force them. Provider diversity is a tool, not a religion. - -| Trigger | Consider | Why | -|---------|----------|-----| -| Code review (not implementation) | `gemini-3-pro-preview` | Different training data catches different issues. Cognitive diversity. | -| Heavy code generation (500+ lines, multi-file) | `gpt-5.2-codex` | OpenAI Codex variants are optimized for code generation. | -| Second-opinion review after a rejection | Different provider than the original reviewer | If Claude rejected, try GPT or Gemini for the re-review. | -| Analytical task benefiting from a "different lens" | `gemini-3-pro-preview` | Google's reasoning approach may surface insights others miss. | - -**When NOT to diversify:** -- First-time spawns for agents with complex charters (stick to Anthropic — charters are Anthropic-optimized) -- Scribe or mechanical tasks (provider doesn't matter, use the cheapest) -- When the user has set a provider preference ("use Claude for everything") - ---- - -## 3. Fallback Chains — The Critical Part - -### The Problem - -A selected model may fail to spawn for any reason: plan restrictions, org policy, regional availability, deprecation, rate limiting, capacity limits, or unknown platform errors. - -The coordinator must handle this silently. The user should never see "Model unavailable, trying another..." unless they ask what happened. - -### How the Coordinator Detects Failure - -When the `task` tool is called with a `model` parameter and that model is unavailable, the task tool will return an error or the spawned agent will fail immediately. The coordinator detects this by: - -1. **Spawn returns an error message** mentioning the model, availability, or access -2. **Agent completes instantly** with no meaningful work done and an error in its output -3. **Platform rejects the model parameter** before the agent starts - -On any of these signals: **do not narrate the failure.** Silently retry with the next model in the fallback chain. - -### Fallback Chains by Tier - -Each tier has an ordered fallback chain. The coordinator walks the chain top-to-bottom. The final entry — `(omit model param)` — means calling the `task` tool WITHOUT the `model` parameter, letting the platform use its built-in default. This is the nuclear fallback. It always works. - -``` -Premium Chain: - claude-opus-4.6 - → claude-opus-4.6-fast - → claude-opus-4.5 - → claude-sonnet-4.5 - → (omit model param) - -Standard Chain: - claude-sonnet-4.5 - → gpt-5.2-codex - → claude-sonnet-4 - → gpt-5.2 - → (omit model param) - -Fast/Cheap Chain: - claude-haiku-4.5 - → gpt-5.1-codex-mini - → gpt-4.1 - → gpt-5-mini - → (omit model param) -``` - -### Cross-Provider Fallback Logic - -The chains are intentionally cross-provider. If an Anthropic model fails, the next attempt is often OpenAI (and vice versa). This handles provider-wide outages, not just single-model issues. - -The ordering within each chain follows these principles: -1. **Best-in-tier first** — the model that would produce the highest quality for this tier -2. **Cross-provider second** — if the first model fails, try a different provider -3. **Same-provider previous-gen third** — older models from the original provider -4. **Alternative provider fourth** — broader cross-provider coverage -5. **Nuclear last** — omit the parameter entirely - -### Fallback Behavior Rules - -1. **Maximum 3 retries.** If the first 3 models in a chain fail, skip directly to `(omit model param)`. Don't burn time walking a 5-model chain. -2. **Silent by default.** The user sees the final successful spawn, not the failures. The coordinator does NOT say "Tried claude-opus-4.6, failed. Trying claude-opus-4.6-fast..." -3. **Log failures if Scribe is running.** When a fallback occurs, note it in the orchestration log: `Model fallback: claude-opus-4.6 → claude-sonnet-4.5 (original unavailable)`. This is internal — the user doesn't see it unless they check the log. -4. **Respect user overrides during fallback.** If the user said "use Claude," fall back within Anthropic only: `opus-4.6 → opus-4.6-fast → opus-4.5 → sonnet-4.5 → sonnet-4 → (omit model param)`. Don't cross to GPT unless the user didn't specify a provider. -5. **Never fall back UP in tier.** A fast/cheap fallback should not land on a premium model. The chains are tier-scoped. - -### The Nuclear Fallback - -`(omit model param)` — calling the `task` tool without specifying `model` at all — lets the platform choose its own default. This is the bottom of every chain because: - -- It always works (the platform always has a default) -- It requires no user configuration -- It's the behavior Squad had before model selection existed -- If even this fails, the spawn itself has a platform-level problem (not a model problem) - ---- - -## 4. Coordinator Prompt Section - -This is the deliverable — the actual prompt text to add to `squad.agent.md` under a new `### Model Selection` section. Ready to paste. - ---- - -```markdown -### Model Selection - -Before spawning an agent, determine which model to use. Check these layers in order — first match wins: - -**Layer 1 — User Override:** Did the user specify a model? ("use opus", "save costs", "use gpt-5.2-codex for this"). If yes, use that model. Session-wide directives ("always use haiku") persist until contradicted. - -**Layer 2 — Charter Preference:** Does the agent's charter have a `## Model` section with `Preferred` set to a specific model (not `auto`)? If yes, use that model. - -**Layer 3 — Task-Aware Auto-Selection:** Match the agent's role to a default model, then adjust for task complexity: - -| Role | Default Model | Bump to Premium When | -|------|--------------|---------------------| -| Lead / Architect | `claude-sonnet-4.5` | Architecture proposals, cross-cutting decisions, multi-agent coordination plans | -| Core Dev / Backend / Frontend | `claude-sonnet-4.5` | — (use Codex specialist for heavy code gen — see below) | -| Tester / QA | `claude-haiku-4.5` | Complex test strategy requiring analysis (bump to sonnet) | -| Designer / Visual | `claude-opus-4.5` | Design system architecture needing deep reasoning (bump to opus-4.6) | -| DevRel / Writer | `claude-sonnet-4.5` | — | -| Scribe / Logger | `claude-haiku-4.5` | — (never bump Scribe) | -| Platform / Infra | `claude-sonnet-4.5` | Security audits, threat modeling | -| Prompt Engineer | `claude-sonnet-4.5` | Complex multi-agent pattern design, prompt architecture | -| Reviewer | `claude-sonnet-4.5` | Approval/rejection gates with downstream consequences | -| Git / Release | `claude-haiku-4.5` | — (never bump mechanical ops) | - -**Task Complexity Adjustments** (apply at most ONE): -- **Bump UP to premium:** architecture proposals, reviewer gates, security audits, multi-agent coordination, design system architecture -- **Bump DOWN to fast/cheap:** typo fixes, renames, boilerplate, scaffolding, changelogs, version bumps -- **Switch to code specialist (`gpt-5.2-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation -- **Switch to analytical diversity (`gemini-3-pro-preview`):** code reviews where a second perspective helps, security reviews, architecture reviews after a rejection - -**Layer 4 — Default:** If nothing else matched, use `claude-sonnet-4.5`. This always works with zero configuration. - -**Fallback Chains — when a model is unavailable:** - -If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the chain. Do NOT tell the user about fallback attempts. Maximum 3 retries before jumping to the nuclear fallback. - -``` -Premium: claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.5 → (omit model param) -Standard: claude-sonnet-4.5 → gpt-5.2-codex → claude-sonnet-4 → gpt-5.2 → (omit model param) -Fast: claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini → (omit model param) -``` - -`(omit model param)` = call the `task` tool WITHOUT the `model` parameter. The platform uses its built-in default. This is the nuclear fallback — it always works. - -**Fallback rules:** -- If the user specified a provider ("use Claude"), fall back within that provider only before hitting nuclear -- Never fall back UP in tier — a fast/cheap task should not land on a premium model -- Log fallbacks to the orchestration log for debugging, but never surface to the user unless asked - -**Spawn output format — show the model choice:** - -When spawning, include the model in your acknowledgment: - -``` -🔧 Fenster (claude-sonnet-4.5) — refactoring auth module -🎨 Redfoot (claude-opus-4.5 · vision) — designing color system -📋 Scribe (claude-haiku-4.5 · fast) — logging session -⚡ Keaton (claude-opus-4.6 · bumped for architecture) — reviewing proposal -🔬 Hockney (gpt-5.2-codex · code specialist) — large refactor across 12 files -``` - -Include tier annotation only when the model was bumped or a specialist was chosen. Default-tier spawns just show the model name. - -**Adding the model parameter to spawns:** - -Pass the resolved model as the `model` parameter on every `task` tool call: - -``` -agent_type: "general-purpose" -model: "claude-sonnet-4.5" -mode: "background" -description: "Fenster: refactoring auth module" -prompt: | - ... -``` - -If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely: - -``` -agent_type: "general-purpose" -mode: "background" -description: "Fenster: refactoring auth module" -prompt: | - ... -``` - -**Valid models (current platform catalog):** - -Premium: `claude-opus-4.6`, `claude-opus-4.6-fast`, `claude-opus-4.5` -Standard: `claude-sonnet-4.5`, `claude-sonnet-4`, `gpt-5.2-codex`, `gpt-5.2`, `gpt-5.1-codex-max`, `gpt-5.1-codex`, `gpt-5.1`, `gpt-5`, `gemini-3-pro-preview` -Fast/Cheap: `claude-haiku-4.5`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1` -``` - ---- - -## 5. Charter Template Update - -Add this section to `templates/charter.md` after the `## Boundaries` section and before `## Collaboration`: - -```markdown -## Model - -- **Preferred:** auto -- **Rationale:** Coordinator selects the best model based on role and task complexity -- **Fallback:** Standard chain — the coordinator handles fallback automatically -``` - -### Field Definitions - -| Field | Values | Meaning | -|-------|--------|---------| -| `Preferred` | A valid model ID (e.g., `claude-opus-4.5`) or `auto` | The model this agent should spawn on. `auto` delegates to the coordinator's auto-selection algorithm. | -| `Rationale` | Free text | Why this model. Forces the charter author to justify the choice. Prevents "opus for everything" cargo-culting. | -| `Fallback` | `Premium chain`, `Standard chain`, `Fast chain`, or a custom chain | Which fallback chain to use when the preferred model is unavailable. Defaults to the chain matching the preferred model's tier. | - -### Examples - -**Designer (needs vision):** -```markdown -## Model - -- **Preferred:** claude-opus-4.5 -- **Rationale:** Vision-capable model required for image analysis, color reasoning, and visual composition -- **Fallback:** Premium chain -``` - -**Scribe (needs speed):** -```markdown -## Model - -- **Preferred:** claude-haiku-4.5 -- **Rationale:** Mechanical file operations — speed and cost matter, depth doesn't -- **Fallback:** Fast chain -``` - -**Core Dev (auto-selection is fine):** -```markdown -## Model - -- **Preferred:** auto -- **Rationale:** Coordinator selects based on task — sonnet for most work, codex for heavy code gen -- **Fallback:** Standard chain — the coordinator handles fallback automatically -``` - ---- - -## 6. Design Decisions - -### Why cross-provider fallback chains? - -Single-provider chains are fragile. If Anthropic has an outage, every fallback attempt fails. Cross-provider chains route around provider-level issues. The ordering ensures the best model for the tier is tried first, then a comparable model from a different provider. - -### Why 3-retry maximum? - -Walking a 5-model chain with API timeouts at each step could add 30-60 seconds of invisible latency. Three retries is enough to handle transient issues and single-provider outages. After that, the nuclear fallback is faster than continuing to iterate. - -### Why silent fallback? - -Users don't care which model runs their agent. They care about results. Narrating "tried X, failed, trying Y" creates anxiety and delays the acknowledgment. The orchestration log captures fallbacks for debugging — the user sees results. - -### Why `(omit model param)` as nuclear? - -It's the only option that is guaranteed to work regardless of plan tier, org policy, or platform state. It's also backward-compatible — Squad worked this way before model selection existed. Worst case: every agent runs on the platform default. That's degraded, not broken. - -### Why not retry with the same model? - -Rate limits and capacity issues are often persistent for minutes to hours. Retrying the same model wastes time. Moving to the next option in the chain is faster and more likely to succeed. - -### Why provider diversity is optional, not forced? - -Squad's charters are Anthropic-optimized. Cross-provider execution introduces prompt portability risk — the same charter may produce subtly different behavior on GPT vs Claude. Provider diversity is valuable for reviews and code generation, but shouldn't be forced where instruction following fidelity matters most. - ---- - -## 7. Integration with Existing Coordinator Patterns - -### Lightweight Spawns - -Lightweight spawns (the minimal template) also get model selection. The coordinator applies the same 4-layer algorithm but uses the Lightweight Spawn Template format. The `model` parameter is added to the `task` call regardless of spawn weight. - -### Explore Agent Type - -For `agent_type: "explore"` spawns (read-only queries), the model parameter is still valid. The coordinator can pass `model: "claude-haiku-4.5"` for fast reads or `model: "gemini-3-pro-preview"` for analytical queries. Fallback works the same way. - -### Delegation (Agent-to-Agent Spawns) - -When an agent spawns another agent directly (Pattern B from Proposal 024), the spawning agent should: -1. Read the target agent's charter `## Model` → use the `Preferred` value -2. If `auto` or no `## Model` section → omit the `model` parameter (let the platform default) - -Agents don't need the full auto-selection algorithm. They don't need fallback chains. The coordinator handles complexity; agents keep it simple. - ---- - -## 8. Future Considerations (Not in v0.3.0) - -- **Budget mode:** A team-level directive that caps all spawns at standard or fast tier. "We're on a tight budget this month." -- **Model performance tracking:** Log model × task outcomes over time. Surface which models produce the best results for which task types. -- **Prompt portability testing:** Validate that key charters produce consistent behavior across Anthropic, OpenAI, and Google models. -- **Skills model requirements:** SKILL.md files could declare model preferences — "this skill works best on Codex models." -- **Cost reporting:** Show estimated token cost per spawn tier in the "where are we?" output. - ---- - -## Summary - -The algorithm is simple at its core: **check four layers, pick the first match, fall back gracefully if it doesn't work.** 80% of spawns will use Layer 4 (default sonnet) or Layer 3 (role-based auto-selection) and never need a fallback. The complexity exists for the 20% where the right model genuinely matters — and for the edge cases where models aren't available. - -The fallback chain is the critical safety net. It terminates. It's silent. It always works. That's the contract. diff --git a/team-docs/proposals/025-pr2-github-issues-prd-humans-review.md b/team-docs/proposals/025-pr2-github-issues-prd-humans-review.md deleted file mode 100644 index e21578fce..000000000 --- a/team-docs/proposals/025-pr2-github-issues-prd-humans-review.md +++ /dev/null @@ -1,196 +0,0 @@ -# Proposal 025: PR #2 Review — GitHub Issues, PRD Mode, Human Team Members - -**Status:** Approved ✅ Shipped -**Author:** Keaton -**Date:** 2026-02-08 -**PR:** bradygaster/squad#2 by @spboyer - -## Summary - -PR #2 adds three new features to `squad.agent.md` — all prompt-only, zero CLI code changes: - -1. **GitHub Issues Mode** (~120 lines) — Connect to a repo's issues, full lifecycle: connect → list backlog → route to agents → branch → PR → review → merge. -2. **PRD Mode** (~100 lines) — Ingest a PRD, Lead decomposes into work items, approval gate, dependency-aware routing. -3. **Human Team Members** (~80 lines) — Humans on the roster with `👤` badge, coordinator pauses for their input, stale reminders. - -Plus Init Mode updates (3 new questions), routing table additions (3 new signals), and 27 new tests (all prompt content validation, bringing total to 55). - -This is a thoughtful PR from someone who clearly read the codebase deeply. The design decisions are overwhelmingly correct. But the scope, integration gaps, and interaction with in-flight architecture decisions require careful review. - -## Architecture Fit - -### What fits well - -All three features are **prompt-only additions** — they extend `squad.agent.md` without touching `index.js`, templates, or the casting system. This is exactly right. Squad's architecture is coordinator-instruction-driven; new workflow modes belong in the coordinator prompt. The PR respects the file ownership model: `squad.agent.md` is Squad-owned code, and these additions ship via the forwardability/upgrade mechanism. - -**GitHub Issues Mode** fits the existing spawn pattern naturally. Issues are work items; work items get routed to agents via `routing.md`. The spawn prompt template includes `ISSUE CONTEXT` — same structure as the existing spawn template with additional context injected. The branch convention (`squad/{issue-number}-{slug}`) is well-chosen — namespaced to Squad, easily identifiable, grep-able. - -**PRD Mode** correctly uses the Lead agent for decomposition (sync spawn, which is right — this is an approval-gated decision). The work item table format (WI-{number}, agent assignment, dependencies, size) is the kind of structured output that LLMs are good at and humans can quickly scan. - -**Human Team Members** fills a genuine gap. Real teams have humans. The `👤` badge vs `✅ Active` distinction is clean. The "no charter, no history, no casting" decision is correct — humans don't need agent infrastructure, they need to appear in routing. - -### What doesn't fit - -**Init Mode changes alter the numbering of all subsequent steps.** Steps 3-7 become 4-9, and a new step 3 and step 9 are inserted. This is fragile — any other PR touching Init Mode will conflict. More importantly, three additional questions during init ("Do you have a PRD?", "Is there a GitHub repo with issues?", "Are any humans joining?") risks making init feel like a questionnaire. Squad's init is currently tight: identify user → ask what you're building → cast team → confirm → create files → done. Adding three more questions dilutes the "fast to value" experience McManus identified as critical (Proposal 014). - -**The `gh` CLI dependency is undocumented.** GitHub Issues Mode assumes `gh issue list`, `gh pr create`, `gh pr merge` are available. These require the GitHub CLI to be installed and authenticated. This is a runtime dependency that affects whether features work at all — not a nice-to-have. If `gh` isn't installed, the coordinator will fail with a confusing error. The PR doesn't add any detection, fallback, or user-facing documentation for this requirement. - -## What's Good - -Genuinely well-done aspects of this PR: - -1. **Deep codebase reading.** The PR integrates with existing patterns correctly — routing table format, spawn prompt structure, team.md storage, drop-box pattern. The Init Mode changes preserve the existing flow and add to it rather than replacing it. - -2. **Issue → PR → Merge lifecycle is complete.** This isn't a half-implementation. Branch creation, PR with issue linking (`Closes #N`), review feedback handling (re-spawn agent with review comments), merge via squash — the full loop is covered. The detail about `gh issue close` as a fallback if auto-close didn't fire shows practical thinking. - -3. **PR Review Handling is thoughtful.** The PR correctly notes that review feedback should be routed to the appropriate agent (or a different one per the reviewer rejection protocol), and injects review comments into the spawn prompt. This demonstrates understanding of the reviewer rejection protocol. - -4. **Human member design is minimal and correct.** No over-engineering. Humans get a roster entry, routing entries, and the coordinator pauses. That's it. No charter files, no history files, no casting — just the minimum to make routing work. The "stale reminder" after one conversation turn is a nice UX touch. - -5. **Tests are structural, not behavioral.** The 27 new tests validate that `squad.agent.md` contains expected sections, triggers, and formats. This is the right testing approach for prompt content — you can't test LLM behavior deterministically, but you can test that the instructions are present. - -6. **Work item format is well-designed.** `WI-{number}` with size (S/M/L), deps, and agent assignment is a practical decomposition format. The approval gate before routing is correct — PRD decomposition is a decision that affects the whole team. - -7. **Mid-project PRD updates.** The diff-based approach (unchanged / modified / new / removed work items) is the right design for PRD evolution. Most implementations forget this case entirely. - -## Integration Gaps - -### 1. Ceremonies × GitHub Issues Mode - -**Gap:** When the user says "work on all issues" or routes multiple issues simultaneously, this is a multi-agent task involving 2+ agents modifying shared systems. The ceremony system has an auto-triggered Design Review with exactly this condition. But GitHub Issues Mode doesn't mention ceremonies at all. - -**Expected behavior:** If 5 issues are routed and they touch overlapping systems, the Design Review ceremony should fire before agents start working. The PR's batch routing flow should acknowledge this: "Check `ceremonies.md` for `when: 'before'` ceremonies before spawning the batch." - -**Severity:** Medium. The existing routing table already has `Multi-agent task (auto) | Check ceremonies.md for when: "before" ceremonies`. So the coordinator *should* handle this through the existing routing table entry. But the GitHub Issues Mode section describes its own routing flow independently — an implementer reading only that section would miss the ceremony gate. - -### 2. PRD Mode × GitHub Issues Mode - -**Gap:** These two features are natural complements but the PR doesn't describe their interaction. A very common workflow would be: ingest PRD → decompose into work items → create GitHub issues from work items → work issues via the Issues Mode lifecycle. - -**Missing:** PRD work items (WI-1, WI-2, etc.) should have an optional "create as GitHub issue" step. If the team is connected to a GitHub repo's issues, the Lead's decomposition could create issues from work items, bridging the two modes. Without this, users must manually create issues from the work item table, losing the automation value. - -**Severity:** Low for v1 (both modes work independently), Medium for v2 (the gap will become obvious to users who adopt both). - -### 3. Human Members × Reviewer Rejection Protocol - -**Gap:** The Reviewer Rejection Protocol (lines 925-947 of squad.agent.md) has strict lockout semantics: rejected author is locked out, a *different* agent must revise. But what if the reviewer is a human? Or what if the revision should be done by a human? - -**Scenarios not covered:** -- Human reviewer rejects AI agent's work → lockout applies normally, but how does the human's rejection get into the system? The PR says "User relays on their behalf" but doesn't specify the format. -- AI reviewer says "this needs human review" → should route to a human member. But the lockout protocol assumes all participants are spawnables. -- All AI agents locked out → currently escalates to "the user." With human team members, should it escalate to a specific human member based on routing? - -**Severity:** Medium. The reviewer protocol is one of Squad's most carefully designed mechanisms. Human integration with it needs explicit handling, not implicit "it'll work out." - -### 4. Branch Convention × Worktree Awareness - -**Gap:** The branch convention `squad/{issue-number}-{slug}` creates branches via `git checkout -b`. In a worktree setup, this creates the branch in the current worktree. But if the user is using the worktree-local strategy (each worktree has its own `.ai-team/` state), multiple issues being worked on in the same worktree will compete for the same branch checkout. - -**Expected interaction:** The PR should specify whether issue work should create new worktrees (one worktree per issue — the cleanest parallel model) or whether `git checkout -b` within the current worktree is intentional (serialized issue work). The existing worktree awareness section describes the resolution strategy but GitHub Issues Mode doesn't reference it. - -**Severity:** Low for single-issue work. Medium-High for "work on all issues" batch mode — parallel agents in the same worktree all running `git checkout -b` will conflict. - -### 5. `gh` CLI Dependency - -**Gap:** GitHub Issues Mode requires `gh` (GitHub CLI) for `gh issue list`, `gh pr create`, `gh pr merge`, `gh pr view`, `gh pr ready`, `gh issue view`, `gh issue close`. This is a hard dependency — not a nice-to-have. - -**What's needed:** -- Detection: before connecting to a repo, check if `gh` is available (`gh --version`). If not, tell the user how to install it. -- Authentication: `gh` requires `gh auth login`. If not authenticated, the coordinator should detect and guide. -- Fallback: the PR also mentions "or equivalent GitHub MCP tools" — this is the right instinct but needs to be formalized. If the MCP GitHub server is configured, use that; if `gh` is available, use that; if neither, tell the user. -- User-facing docs: at minimum, the README or a docs page should note that GitHub Issues Mode requires `gh` CLI. - -**Severity:** High. A feature that silently fails because of an undocumented dependency is a trust violation. - -### 6. Model Selection × PRD Decomposition - -**Gap:** Proposal 024 (Per-Agent Model Selection) designs a model selection algorithm with role-based defaults and task complexity bumps. PRD Mode spawns the Lead agent (sync) for decomposition. The decomposition prompt is a structured analytical task that produces a work item table — this is exactly the kind of task that should get a model bump. - -**Specific interactions:** -- PRD decomposition by Lead → task contains "architecture" and "proposal" signals → should bump to Opus per Proposal 024's complexity override table. -- Subsequent work item spawns → each agent gets its own model per charter/role. This works correctly. -- But the PR's PRD spawn template hardcodes `agent_type: "general-purpose"` without a `model` parameter. When Proposal 024 ships, this template will need updating to include model selection. - -**Recommendation:** Not a blocker for this PR, but the PRD spawn template should include a comment like `{model selection per charter/auto-selection}` so Proposal 024's implementation doesn't miss it. - -### 7. GitHub Issues Mode Agent Spawns × Model Selection - -**Gap:** Similar to #6 — when spawning agents for issue work, the model should be selected per the agent's charter preference or role-based default. The PR's spawn template doesn't include a `model` parameter. This is consistent with the current codebase (no spawn template includes `model` today), but should be noted as a Proposal 024 integration point. - -**Severity:** Low. Proposal 024 will update all spawn templates when it ships. These new templates just need to be included in that sweep. - -## Scope Assessment - -### Is this too much for one PR? - -**Yes, but not fatally so.** Three features, each ~100 lines, is a lot of prompt surface area to review. But they're independent sections appended to `squad.agent.md` — they don't interleave with existing code. The blast radius of a bug in any one section is limited to that feature. - -### Should it be split? - -**Ideally, yes.** The natural split: - -1. **PR #2a: Human Team Members** — smallest, most independent, no external dependencies. Merge first. -2. **PR #2b: GitHub Issues Mode** — depends on `gh` CLI, needs dependency documentation. Merge second with the `gh` detection added. -3. **PR #2c: PRD Mode** — depends on Lead agent decomposition pattern. Most value from being last because it can reference Issues Mode for PRD→issue bridge. -4. **PR #2d: Init Mode updates** — depends on all three above. Merge last. - -Each would carry its own tests. - -### Dependency order if kept as one PR - -If merged as-is: Human Members is independent. GitHub Issues and PRD modes are independent of each other but both depend on the routing table additions. Init Mode depends on all three. - -## Recommendations - -### Verdict: Request Changes — Minimum Set to Merge - -This PR demonstrates strong codebase understanding and the features are strategically valuable. But there are gaps that should be addressed before merge. - -**Must-fix (blocking merge):** - -1. **Add `gh` CLI detection.** Before the first `gh` command, the coordinator should check for `gh` availability and authentication. Add a subsection to GitHub Issues Mode: "Prerequisites — verify `gh` is installed and authenticated before connecting." This is 5-10 lines of prompt. - -2. **Add worktree interaction note.** In the "Branch creation" step, add: "If running in a worktree, create the branch in the current worktree. For parallel issue work, consider creating separate worktrees per issue." This acknowledges the existing architecture without over-engineering. - -3. **Init Mode questions should be asked AFTER team confirmation, not before casting.** Move the three new questions from step 3 (before casting) to step 9 (post-setup wiring) — or better, make them part of the first Team Mode interaction. Init should stay fast. The PRD, issues, and human questions can be asked after the team exists, when the coordinator has routing context to act on the answers. - -**Should-fix (non-blocking but recommended):** - -4. **Add a note on ceremony interaction.** In the "Routing to agents" subsection of GitHub Issues Mode, add: "For multi-issue batches, the coordinator checks `ceremonies.md` for auto-triggered ceremonies before spawning (per existing routing table rules)." - -5. **Add model selection placeholder.** In both the PRD spawn template and the issue spawn template, include a comment noting that `model` parameter will be added per Proposal 024. - -6. **Document human reviewer integration.** Add a sentence to the Human Team Members section: "When work routes to a human reviewer for approval or rejection, the coordinator presents the work and waits. The user relays the human's verdict using the same format as the reviewer rejection protocol." - -7. **Add PRD × Issues bridge note.** In the PRD Mode section, add a forward-looking note: "If a GitHub repo is connected (see GitHub Issues Mode), work items can optionally be created as GitHub issues for full lifecycle tracking. This integration is planned for a future iteration." - -**Nice-to-have (not for this PR):** - -8. Consider whether batch issue routing should create worktrees (one per issue) for true parallelism. -9. PRD work items → GitHub issues automation. -10. Human member integration with the deadlock handling in the reviewer protocol. - -### Model Selection Interaction (Proposal 024) - -The PRD decomposition spawn is the most interesting interaction. Lead + "decompose a PRD" is a structured analytical task — exactly the kind that Proposal 024's complexity override would bump from Sonnet to Opus. When 024 ships: - -- PRD decomposition spawn → Lead → charter model or role-based default (Sonnet) → task complexity bump ("architecture" signal) → Opus. This is the correct resolution. -- Issue work spawns → per agent, per charter. Normal flow. -- Human routing → no spawn, no model selection. Correct by design. - -The PR doesn't need to implement model selection (024 isn't shipped yet), but it should be aware that its spawn templates will be updated. The `agent_type: "general-purpose"` without `model` is consistent with current codebase. - -## Risk Assessment - -| Risk | Severity | Mitigation | -|------|----------|------------| -| `gh` CLI not installed → confusing failure | High | Add detection (must-fix) | -| Init becomes a questionnaire → slower time-to-value | Medium | Move questions post-init (must-fix) | -| Parallel issue branches conflict in worktrees | Medium | Document worktree interaction (must-fix) | -| Ceremonies not triggered on multi-issue batch | Medium | Add ceremony note (should-fix) | -| PRD and Issues modes don't bridge | Low (v1) | Future iteration (nice-to-have) | -| Model selection needs template updates | Low | Proposal 024 sweep will handle | - -## Final Note - -@spboyer clearly read the codebase deeply — the spawn template format, the routing table structure, the team.md storage pattern, even the reviewer rejection protocol. The three features are well-scoped for prompt-only implementation and don't introduce architectural debt. With the must-fixes addressed, this is a strong contribution to Squad's feature surface. diff --git a/team-docs/proposals/026-scripted-end-to-end-demos.md b/team-docs/proposals/026-scripted-end-to-end-demos.md deleted file mode 100644 index bbd8d9fd8..000000000 --- a/team-docs/proposals/026-scripted-end-to-end-demos.md +++ /dev/null @@ -1,454 +0,0 @@ -# Proposal 026: Scripted End-to-End Demos - -**Status:** Draft -**Authored by:** Verbal (Prompt Engineer) -**Date:** 2026-02-09 -**Requested by:** bradygaster - ---- - -## Summary - -Production-quality demo recordings where every keystroke, pause, expected output, voiceover cue, and cut point is scripted in advance. No improvisation. No retakes from unexpected output. No "let me just..." moments. Every second of footage is planned, verified, and repeatable. - -This proposal defines what "100% scripted" means, establishes a structured demo script format, evaluates recording tools, proposes five end-to-end demo scenarios, and describes how recorded sessions flow into docs, README, and social content. - ---- - -## Problem - -Proposal 004 (Demo Script Overhaul) gave Brady a beat-by-beat recording blueprint — voiceover cues, on-screen descriptions, action steps. That was a major upgrade from the bullet-point outline. But it still has gaps that cost recording time: - -1. **Input is approximate.** "Paste the prompt" and "Type `copilot`" are action steps, but they don't specify keystroke timing, typing speed, or pause duration. During recording, Brady makes micro-decisions about pacing that create inconsistency across takes. - -2. **Output is assumed.** The script says "Squad proposes a team" but doesn't specify what the expected output looks like. If the output differs from expectations (different names, different formatting, error messages), Brady has to improvise or abort the take. - -3. **No verification step.** There's no way to confirm that a demo will produce the expected output before recording. Brady discovers problems during recording, not before. - -4. **No automation path.** The current format is human-readable prose. It can't be fed to a recording tool for automated capture. Every recording requires Brady to manually execute every step. - -5. **Single scenario.** We have one demo (Snake game). Brady wants a library of demos covering different Squad capabilities — issues workflow, export/import, status checks, PRD intake. - ---- - -## 1. What "100% Scripted" Means - -A fully scripted demo has **six layers** at every step: - -| Layer | What it contains | Why it matters | -|-------|-----------------|----------------| -| **Input** | Exact characters to type, including pauses between keystrokes | Eliminates pacing decisions during recording | -| **Expected output** | Regex or substring patterns the terminal should produce | Enables pre-flight verification — run the script, confirm output matches before recording | -| **Timing** | Millisecond-level pause durations, typing speed (chars/sec), hold durations on output | Makes recordings consistent across takes and demos | -| **Voiceover cues** | What Brady says during this step, synced to timing marks | Voiceover is recorded separately but timing aligns to footage | -| **Annotations** | On-screen callouts, highlights, zoom targets | Post-production knows exactly where to add visual emphasis | -| **Cut points** | Where editors can safely cut, splice, or time-shift | Reduces editing time; editors don't have to find safe cut points | - -**The test:** A scripted demo can be dry-run as an automated test. Run the script, compare output to expected patterns, flag mismatches. If the dry run passes, recording will succeed on the first take. - ---- - -## 2. Demo Script Format - -Each demo is a sequence of **steps**. Each step is a structured block: - -```yaml -- step: 3 - title: "Install Squad" - input: - text: "npx github:bradygaster/squad" - typing_speed: 40 # chars per second (human-realistic) - pre_delay: 500 # ms before typing starts - post_delay: 2000 # ms after Enter before next step - expected_output: - patterns: - - "squad.agent.md" # substring match - - "Squad is ready" # substring match - - "\\.(github|ai-team)" # regex match - timeout: 15000 # ms to wait for output - timing: - hold_on_output: 3000 # ms to pause on output for viewer reading - speed_factor: 1.0 # 1.0 = realtime, 2.0 = double speed - voiceover: > - One npx command. That's the entire install. Squad drops a single - agent file into .github/agents/ and some templates. No config, - no YAML, no boilerplate. - annotations: - - type: highlight - target: "squad.agent.md" - label: "This is the coordinator" - cut_point: - safe_to_cut_after: true - transition: "hold" # hold | fade | hard-cut - notes: "Can splice to next step after output settles" -``` - -### Format Design Decisions - -- **YAML over Markdown.** The script must be machine-parseable for dry-run verification and potential automation. YAML is readable by humans and parseable by tools. -- **Timing in milliseconds.** Specific enough for automation tools, easily converted to human-readable seconds for Brady's reference. -- **Regex + substring for output matching.** Substring for simple cases ("Squad is ready"), regex for variable content (agent names change per casting universe). -- **Voiceover is inline.** Brady can read the script top-to-bottom and know exactly what to say at each step. No cross-referencing separate voiceover documents. - -### Companion: Human-Readable View - -Each YAML script also generates a **Brady-readable cheat sheet** — a simplified view showing only: -1. What to type -2. How long to wait -3. What to say -4. Where to cut - -This is what Brady has on a second monitor during recording. The YAML is the source of truth; the cheat sheet is the recording aid. - ---- - -## 3. Recording Tools — Evaluation - -### Candidates - -| Tool | Approach | Output | Scripting | Pros | Cons | -|------|----------|--------|-----------|------|------| -| **`vhs`** (Charm) | Declarative `.tape` files | GIF, MP4, WebM | Native — typed DSL with `Type`, `Sleep`, `Enter` | Deterministic, version-controllable, CI-friendly | No audio, limited output verification | -| **`asciinema`** | Terminal recording + replay | asciicast, GIF (via agg) | Record-then-replay; scripting via `expect` | Lightweight, great replay UX, embeddable | No native scripting, replay-only, no MP4 | -| **`terminalizer`** | Terminal recording | GIF, YAML config | Record-then-edit YAML | Customizable styling, large install base | Stale maintenance, slow GIF rendering | -| **Custom Node.js** | stdin/stdout replay | Raw terminal data | Full control | Exact output matching, verification built-in | Build cost, maintenance burden | - -### Recommendation: `vhs` by Charm - -**Why vhs wins:** - -1. **Declarative scripting is the format.** A `.tape` file *is* a scripted demo. `Type "npx github:bradygaster/squad"`, `Sleep 3s`, `Enter`. Our YAML script format maps directly to tape instructions. The translation is mechanical. - -2. **Deterministic output.** Same tape file → same recording every time. No variance from human typing speed, mouse position, or timing drift. Brady can review a GIF before committing to a full recording session. - -3. **Multiple output formats.** GIF for README embeds, MP4 for video editing, WebM for web. One tape file produces all three. This feeds directly into the docs pipeline (Section 5). - -4. **CI-friendly.** Tape files can run in GitHub Actions. We can verify that demos still produce expected output after code changes. A demo that breaks is a failing CI check, not a surprise during recording week. - -5. **Version-controllable.** Tape files are text. They live in the repo alongside the demo scripts. Changes are diffable, reviewable, and tied to the code they demo. - -**What vhs doesn't do (and how we compensate):** - -- **No voiceover.** Voiceover is recorded separately per Proposal 004's approach. vhs produces the visual footage; Brady records audio as a separate pass. This is actually better — it decouples visual and audio quality. -- **No output verification.** vhs doesn't assert on output. We add a dry-run step: run the tape commands via a Node.js script that checks output patterns before recording. The tape file is the recording; the YAML script is the verification spec. -- **No mouse interaction.** Squad demos are terminal-first. Mouse is only needed for browser reveals (playing the Snake game). Those moments are recorded manually and spliced in during editing. - -### vhs Tape File Example - -```tape -# Demo 1: First Squad Session -# Duration: ~3 minutes - -Output demo-first-session.gif -Output demo-first-session.mp4 - -Set FontSize 16 -Set Width 1200 -Set Height 800 -Set Theme "Catppuccin Mocha" - -# Step 1: Create project -Type "mkdir my-project && cd my-project" -Enter -Sleep 1s - -# Step 2: Init git -Type "git init -b main" -Enter -Sleep 1s - -# Step 3: Install Squad -Type "npx github:bradygaster/squad" -Enter -Sleep 8s - -# Step 4: Show file tree -Type "find . -type f" -Enter -Sleep 3s - -# Step 5: Launch Copilot -Type "copilot" -Enter -Sleep 2s - -# ... (continues for each step) -``` - ---- - -## 4. Proposed Demo Scenarios - -Five end-to-end demos covering Squad's core capabilities. Each is self-contained and demonstrates a different value proposition. - ---- - -### Demo 1: First Squad Session - -**Title:** "Empty Folder to Working App in 3 Minutes" -**Duration:** ~3 minutes -**Value prop:** Squad's core workflow — install, prompt, parallel build, results - -**Key Beats:** - -| Beat | Timestamp | What happens | What makes it impressive | -|------|-----------|-------------|------------------------| -| 1 | 0:00–0:20 | `mkdir` → `git init` → `npx github:bradygaster/squad` | Three commands. That's it. | -| 2 | 0:20–0:50 | Open Copilot, select Squad, paste prompt (Snake game) | One prompt, not a conversation | -| 3 | 0:50–1:20 | Team reveal — named agents, roles, universe theme | Agents have *names*, not labels | -| 4 | 1:20–1:50 | Parallel fan-out — all agents launch simultaneously | Visual proof of parallelism | -| 5 | 1:50–2:30 | Quick file inspection — `decisions.md`, one `history.md` | Agents coordinated without you | -| 6 | 2:30–3:00 | Open browser, play the Snake game | It works. They built it. | - -**What makes it impressive:** The speed. Three minutes from nothing to a working game built by five agents working in parallel. The viewer's mental model of "AI writes code" shifts to "AI runs a team." - -**Pre-requisites:** -- Clean empty directory -- Node.js, git, Copilot CLI installed -- Browser ready off-screen -- Snake game prompt on clipboard - ---- - -### Demo 2: GitHub Issues Workflow - -**Title:** "Issue to Merged PR — Squad Handles the Whole Loop" -**Duration:** ~4 minutes -**Value prop:** Squad integrates with GitHub's native workflow — issues, branches, PRs, reviews - -**Key Beats:** - -| Beat | Timestamp | What happens | What makes it impressive | -|------|-----------|-------------|------------------------| -| 1 | 0:00–0:30 | Show existing project with Squad team already set up | Team *persists* — no re-setup | -| 2 | 0:30–1:10 | Create a GitHub issue: "Add dark mode toggle" | Real issue, real repo | -| 3 | 1:10–1:50 | Tell Squad: "Pick up issue #12" — team analyzes, plans | Agents read the issue themselves | -| 4 | 1:50–2:40 | Agents work in parallel — frontend builds toggle, tester writes tests, lead reviews | Coordination through decisions.md | -| 5 | 2:40–3:20 | Squad creates branch, commits, opens PR with summary | PR description references issue, agent work | -| 6 | 3:20–4:00 | Show PR diff, linked issue, review comments | Full GitHub-native workflow | - -**What makes it impressive:** Squad isn't a standalone tool — it works *inside* the developer's existing workflow. Issues → branches → PRs → reviews. The agents don't bypass GitHub; they use it. - -**Pre-requisites:** -- Existing project with `.ai-team/` directory and established team -- GitHub repo with issues enabled -- Pre-created issue #12 (or appropriate number) with "Add dark mode toggle" description -- Team should have at least 2 sessions of history (agents "know" the codebase) - ---- - -### Demo 3: Export/Import Portability - -**Title:** "Your Squad Remembers YOU" -**Duration:** ~2 minutes -**Value prop:** Teams are portable — export from one project, import into another, all knowledge transfers - -**Key Beats:** - -| Beat | Timestamp | What happens | What makes it impressive | -|------|-----------|-------------|------------------------| -| 1 | 0:00–0:20 | Show established project with rich `.ai-team/` — history, decisions, skills | This team has been working for weeks | -| 2 | 0:20–0:50 | Run `squad --export` — show the JSON output, highlight key sections | One command captures everything | -| 3 | 0:50–1:10 | Create a brand new empty project, `git init` | Fresh start | -| 4 | 1:10–1:30 | Run `squad --import squad-export.json` — team materializes | Same names, same knowledge, new repo | -| 5 | 1:30–2:00 | Ask an agent a question about the old project's conventions — it answers correctly | The knowledge transferred. It *remembers*. | - -**What makes it impressive:** The "it remembers" moment. The agent in the new project knows conventions, patterns, and preferences from the old project. This isn't "start over with AI" — it's "bring your team with you." - -**Pre-requisites:** -- Source project with rich team history (3+ sessions, multiple decisions, skills) -- `squad-export.json` pre-generated (or generate live) -- Empty target directory -- Both directories visible (split terminal or quick switch) - ---- - -### Demo 4: "Where Are We?" Instant Team Status - -**Title:** "One Question. Full Team Status. Zero Context Switching." -**Duration:** ~1 minute -**Value prop:** Squad gives you instant project awareness — what every agent knows, what's in flight, what's decided - -**Key Beats:** - -| Beat | Timestamp | What happens | What makes it impressive | -|------|-----------|-------------|------------------------| -| 1 | 0:00–0:10 | Open Copilot with Squad in an existing project mid-build | Drop in, no warm-up | -| 2 | 0:10–0:30 | Type: "Where are we?" — Squad summarizes team status | Instant synthesis across all agents | -| 3 | 0:30–0:50 | Output shows: per-agent status, recent decisions, open items, blockers | One prompt replaces reading 5 files | -| 4 | 0:50–1:00 | Brief: "What did Ripley do last session?" — specific agent recall | Named agent, specific memory | - -**What makes it impressive:** Speed and synthesis. One question replaces `cat`-ing five history files and a decisions file. The coordinator synthesizes across all agents instantly. This is the "project standup in 10 seconds" moment. - -**Pre-requisites:** -- Existing project mid-build (at least 2 sessions completed) -- Multiple agents with populated history files -- Recent decisions in `decisions.md` -- Ideally some work in-progress (background agents or recent completions) - ---- - -### Demo 5: PRD Intake → Decomposition → Parallel Execution - -**Title:** "From Product Spec to Running Code — One Prompt" -**Duration:** ~3 minutes -**Value prop:** Squad handles the full lifecycle — intake a PRD, decompose into tasks, assign to specialists, execute in parallel - -**Key Beats:** - -| Beat | Timestamp | What happens | What makes it impressive | -|------|-----------|-------------|------------------------| -| 1 | 0:00–0:30 | Show a PRD document (markdown, 1-2 pages) — a recipe sharing app | Real product spec, not a toy prompt | -| 2 | 0:30–1:00 | Paste PRD into Squad. Lead analyzes, decomposes into work items | Automatic task decomposition | -| 3 | 1:00–1:30 | Lead proposes assignment — frontend, backend, tester, each with scope | Intelligent routing based on charter expertise | -| 4 | 1:30–2:20 | Fan-out — all agents start simultaneously. Show parallel output | Same parallelism, but from a *document*, not a prompt | -| 5 | 2:20–2:40 | Show `decisions.md` — API contracts, data models, shared agreements | Agents negotiated contracts without you | -| 6 | 2:40–3:00 | Show partial results — scaffolded app, test cases, architecture doc | PRD → working scaffold in 3 minutes | - -**What makes it impressive:** The input is a *product document*, not a developer prompt. This shows Squad bridging the gap between product thinking and engineering execution. PMs write the PRD; Squad decomposes and builds. The decomposition step — lead breaking a PRD into agent-scoped work items — is the moment that sells enterprise use. - -**Pre-requisites:** -- PRD document pre-written (markdown, 1-2 pages, covering a recipe sharing app or similar) -- PRD on clipboard for paste -- Clean project directory with Squad installed (or install live) -- Enough time budget for agents to produce visible output (~2 min of background work) - ---- - -## 5. Demos → Docs Pipeline - -Recorded demos should produce assets for multiple channels from a single recording session. - -### Asset Flow - -``` -tape file (.tape) - ├── vhs render → GIF (README embed, docs) - ├── vhs render → MP4 (video editing, YouTube) - ├── vhs render → WebM (web embed) - └── manual recording + voiceover → Full video (YouTube, social) - -Full video - ├── Trim to 60s → Social clip (Twitter/X, LinkedIn) - ├── Trim to key beat → GIF (docs, issue templates) - ├── Screenshot key frame → Thumbnail (YouTube, social) - └── Extract voiceover text → Blog post / tutorial -``` - -### Where Assets Land - -| Asset | Format | Destination | Purpose | -|-------|--------|-------------|---------| -| Install GIF | GIF (15s) | README "Quick Start" section | Shows three-command install at a glance | -| Fan-out GIF | GIF (10s) | README "Agents Work in Parallel" section | Visual proof of parallelism | -| "Where are we?" GIF | GIF (15s) | README or docs | Shows instant status synthesis | -| Full demo video | MP4 (3-7min) | YouTube, GitHub Releases page | Primary content piece | -| Social clips | MP4 (30-60s) | Twitter/X, LinkedIn, Reddit | Shareable "wait what" moments | -| Key frame screenshots | PNG | Thumbnails, blog headers, social cards | Visual identity | -| Export/Import GIF | GIF (20s) | docs/portability section | Shows team portability | - -### Maintenance Rule - -**If a demo breaks, the CI breaks.** Tape files run in CI as smoke tests. If a code change makes a demo's expected output no longer match, the build fails. This ensures demos stay current with the product — no stale GIFs in the README showing features that work differently now. - ---- - -## 6. Pre-requisites for Each Demo - -### Shared Pre-requisites (All Demos) - -- [ ] Node.js ≥18 installed, `npx --version` returns cleanly -- [ ] Git installed, `git init` works without prompts -- [ ] GitHub Copilot CLI installed, `copilot` launches cleanly -- [ ] Terminal: solid dark background, ≥16pt font, no scrollback history -- [ ] Screen recording software running (OBS or similar) at native resolution -- [ ] `vhs` installed (`brew install vhs` / `go install github.com/charmbracelet/vhs@latest`) -- [ ] Microphone OFF during terminal recording (voiceover recorded separately) - -### Per-Demo Setup - -| Demo | Repo State | Test Data | Special Setup | -|------|-----------|-----------|---------------| -| 1: First Session | Empty directory, nothing | Snake game prompt on clipboard | Browser ready off-screen for finale | -| 2: Issues Workflow | Existing project with 2+ sessions of team history | GitHub issue pre-created (#12 "Add dark mode") | GitHub CLI (`gh`) authenticated, repo pushed to GitHub | -| 3: Export/Import | Source project with 3+ sessions, rich history | `squad-export.json` pre-generated (or generate live) | Two terminal panes or tabs visible | -| 4: Where Are We? | Mid-build project with multiple agents, recent decisions | N/A — uses existing state | Keep it fast — rehearse to hit <60s | -| 5: PRD Intake | Clean directory with Squad installed | PRD document (1-2 pages, markdown) on clipboard | PRD should be realistic — recipe app, dashboard, etc. | - -### Dry-Run Checklist (Before Any Recording) - -1. **Run the tape file** (or manually execute steps) end-to-end once -2. **Compare output** to expected patterns in the YAML script -3. **Time the run** — confirm it fits the target duration (±30s) -4. **Check for surprises** — unexpected errors, different casting universe, slow network -5. **Reset state** — delete created directories, clear terminal, re-stage test data -6. **Record** - ---- - -## Trade-offs - -**What we gain:** -- Demos are repeatable — same script, same result, every time -- Brady can rehearse from a cheat sheet and record in 1-2 takes -- Tape files enable automated GIF/MP4 generation for docs -- CI integration catches stale demos before they embarrass us -- Five demos cover Squad's full value surface, not just the Snake game - -**What we give up:** -- Scripting overhead — each demo requires YAML authoring, output pattern definition, and dry-run verification before the first recording -- Rigidity — fully scripted demos can feel mechanical if voiceover isn't conversational -- vhs limitations — no mouse interaction, no browser content (those moments need manual recording + splice) - -**Mitigation:** -- The YAML script format is write-once, update-rarely. The upfront cost pays back across all future recordings. -- Voiceover is recorded separately with conversational tone (per Proposal 004's approach). The automation handles visuals; Brady handles personality. -- Browser moments (playing the Snake game, showing GitHub PRs) are clearly marked as manual-record segments with splice points defined. - ---- - -## Alternatives Considered - -**Option 1: Keep the current Proposal 004 beat format, just add more demos** -Pros: Lower effort. Cons: Still has the pacing/verification gaps. Every new demo inherits the same problems. Doesn't scale. - -**Option 2: Full OBS macro scripting** -Pros: Can automate everything including browser interactions. Cons: OBS macros are fragile, non-portable, and not version-controllable. Tying demos to a specific recording setup defeats portability. - -**Option 3: asciinema + expect scripts** -Pros: Great replay experience, lightweight. Cons: Output format is asciicast (not GIF/MP4 natively), scripting via `expect` is brittle for complex interactions, no native CI integration. - -**Option 4: This proposal (vhs + YAML verification + structured scripts)** -Best balance of automation, portability, and production quality. vhs handles deterministic recording, YAML handles verification, and the structured format scales to any number of demos. - ---- - -## Success Criteria - -- [ ] Brady can record any of the five demos in ≤2 takes using only the cheat sheet -- [ ] Each tape file produces a clean GIF and MP4 without manual intervention -- [ ] At least 3 demo GIFs are embedded in the README or docs -- [ ] CI runs tape files as smoke tests — broken demos fail the build -- [ ] "Where are we?" demo is under 60 seconds and feels instant -- [ ] PRD intake demo shows decomposition as a visible, impressive step - ---- - -## Implementation Sequence (When Approved) - -This is a proposal — implementation is deferred until Brady reviews and approves. Suggested order: - -1. **Write Demo 1 YAML script** (First Session) — it's the foundation, reuses existing Snake game scenario -2. **Create the vhs tape file** for Demo 1 — validate the format, generate first GIF -3. **Add CI smoke test** — tape file runs in GitHub Actions, output patterns verified -4. **Write Demos 4 and 3** (shortest first — "Where are we?" at 1min, Export/Import at 2min) -5. **Write Demo 2** (Issues workflow — requires GitHub integration setup) -6. **Write Demo 5** (PRD intake — requires PRD document authoring) -7. **Embed GIFs in README** — replace static diagrams with recorded demos where applicable -8. **Record full videos** with voiceover — Brady's recording session - ---- - -## Revisions - -None yet. diff --git a/team-docs/proposals/027-v030-sprint-plan.md b/team-docs/proposals/027-v030-sprint-plan.md deleted file mode 100644 index a42b04054..000000000 --- a/team-docs/proposals/027-v030-sprint-plan.md +++ /dev/null @@ -1,871 +0,0 @@ -# Proposal 027: v0.3.0 Sprint Plan - -**Status:** Approved ✅ — REVISED -**Authored by:** Keaton (Lead) -**Date:** 2026-02-10 -**Revised:** 2026-02-10 — Brady's reprioritization directive -**Requested by:** bradygaster — *"let's gear up for the 0.3.0 sprint"* -**Baseline:** v0.2.0, 92 tests passing, Waves 1-3 shipped, 0 open issues -**Supersedes:** Previous version of this document (model selection + backlog as Wave 1) - ---- - -> ⚠️ **REVISION NOTICE:** This plan has been fundamentally restructured per Brady's stated priorities. The previous version had model selection and backlog capture as Wave 1. Brady has reordered: **async squad communication is now P0**, GitHub-native integration (Issues, PRs, CCA) is P1, and model selection has moved to Wave 2. Squad DM, previously deferred to Horizon, is UN-DEFERRED and is now the centerpiece of v0.3.0. See [Revision History](#revision-history) at the bottom for what changed and why. - ---- - -## What This Document Is - -The execution plan for v0.3.0. Three waves, hard gates, agent assignments. Every item justified by Brady's stated priorities, in order. - -Waves 1-3 built the foundation (quality, experience, portability). v0.3.0 makes the foundation accessible from everywhere. - ---- - -## Strategic Thesis - -v0.2.0 gave Squad hands (export, import, skills, tiered modes). v0.3.0 gives it reach. - -~~Four~~ Six bets, in Brady's priority order: - -1. **Talk to your squad from anywhere.** *(TOP PERSONAL PRIORITY)* Brady wants to message his squad from his phone — per repo, any time. Telegram first, platform-agnostic architecture. The three 017 proposals (Keaton's architecture, Kujan's feasibility, Verbal's experience design) are prior art. This is the hardest thing in the plan and the most important. Squad DM transforms Squad from "tool on your computer" to "team in your pocket." - -2. **GitHub IS the interface.** Issues become work items. PRs trigger agent responses. Squad reads from and responds to GitHub's native surfaces — not just the CLI. Validated by Shayne Boyer's [slidemaker deployment](https://github.com/spboyer/slidemaker), which proved the pattern: `squad:` label conventions, PRD→Issues flow, 8 of 9 issues completed. This isn't speculative design — it's shipping on top of validation. - -3. **CCA works under Squad governance.** When Copilot Coding Agent picks up an issue, it should discover `.ai-team/`, read `squad.agent.md`, and work as a team member. Squad becomes the governance layer for CCA — not competing with it, governing it. - -4. **Clean branch configuration.** At `squad init` time, users configure which branches should never contain team files (`.ai-team/`, `team-docs/`, etc.). Per-repo, declarative. - -5. **Right model for the right job.** Every agent spawns on the model that matches its work. Still important (Proposals 024, 024a, 024b), but no longer the sole Wave 1 focus. - -6. **Marketing site.** Jekyll on GitHub Pages, `docs/` as source (Proposals 029, 029a). Important but not blocking. - ---- - -## What's In — And Why - -### In: Async Squad Communication — Squad DM (from Proposals 017, 017-platform-feasibility, 017-experience-design) - -**Why now:** Brady's top personal priority. He said he wants THIS more than anything. Previously deferred to Horizon — now UN-DEFERRED and promoted to P0 for v0.3.0. - -**Prior art:** Three existing proposals provide a comprehensive design foundation: -- **017-squad-dm-messaging-interface.md** (Keaton) — Hybrid architecture: thin platform adapters → Squad DM Gateway → execution engine. Options A-D evaluated, Option D (Hybrid) recommended. -- **017-platform-feasibility-dm.md** (Kujan) — Copilot SDK as execution backend (recommended), GitHub Actions as fallback. Dev Tunnels over ngrok. Agent spawning via SDK nested sessions is the critical risk gate. ~420 LOC for v0.1. -- **017-dm-experience-design.md** (Verbal) — Single bot/many voices pattern, DM output mode (summary + link), proactive messaging (standups, CI alerts), agent identity via emoji prefix + name. - -**Scoped to v0.3.0:** Phase 0 (proof of concept — GitHub Actions fallback, validate the loop) and Phase 1 (Telegram bot + Copilot SDK + Dev Tunnel, single repo, single user). Phase 2 (proactive messaging, push notifications) and Phase 3 (multi-platform, multi-repo) are 0.4.0. - -**What must ship:** -- Copilot SDK spike — verify agent spawning works (go/no-go gate for SDK vs. Actions path) -- Telegram bot with polling (v0.1) or webhook + Dev Tunnel (if validated) -- DM mode flag in spawn prompts — agents produce summary output, not 45KB proposals -- Single repo, single user (Brady), local execution -- `.ai-team/dm-log/` for conversation persistence -- If SDK path fails: GitHub Actions fallback with issue-comment-triggered workflows - -**What doesn't ship in v0.3.0:** -- Proactive push notifications (Phase 2) -- Multi-platform adapters — Slack, Discord, SMS (Phase 3) -- Multi-repo routing (Phase 3) -- Cloud deployment (Phase 3) - -**Risk:** HIGH. This is the hardest item in the plan. The Copilot SDK `task` equivalence is unproven. The SDK spike is a go/no-go gate — if it fails, we fall back to GitHub Actions (lower UX quality, 60-120s latency). Kujan must run the spike before any other DM work begins. - -### In: GitHub-Native Integration — Issues, PRs, Squad Labels (from Proposal 028) - -**Why now:** Brady's P1. Validated by Shayne Boyer's slidemaker deployment. The `squad:` label convention, issue templates with agent metadata, and PRD→Issues pipeline are proven patterns — not theoretical design. Proposal 028 Phase 1 was already approved for v0.3.0; this expands the scope to include deeper Issue lifecycle integration and PR-triggered agent responses. - -**Prior art:** -- **028-github-native-team-planning.md** — Four-phase plan. Phase 1 (one-way push) already approved. Filesystem remains authoritative; GitHub is a synchronized view. -- **Reference implementation:** [spboyer/slidemaker](https://github.com/spboyer/slidemaker) — 9 issues created, 8 completed. `squad:` and `squad:{agent-name}` label conventions validated. - -**Scoped to v0.3.0:** Phase 1 (one-way push to Issues) + Issue lifecycle management (issues drive agent work, not just display it). PR review triggers are stretch. - -**What must ship:** -- One-way push: proposals → GitHub Issues, backlog items → GitHub Issues, with `squad:` labels -- Issue lifecycle: agents close issues when work completes, with summary comments -- Squad reads Issues as work input — not just CLI messages (the inverse of what 028 Phase 1 originally described) -- `squad:` label convention formalized in coordinator instructions -- If `gh` CLI / GitHub MCP unavailable, skip silently — no degradation - -### In: CCA Adoption — Squad as Governance Layer - -**Why now:** Brady's P2. When Copilot Coding Agent picks up a GitHub Issue, it should discover `.ai-team/` and work under Squad's governance — reading charters, respecting decisions, following conventions. This makes Squad the team standard that CCA inherits, not a parallel system. - -**What must ship:** -- `squad.agent.md` documented as CCA's entry point — CCA reads this file to understand team structure, conventions, and routing -- `.ai-team/` directory structure documented for CCA discovery -- Agent charters available as reference for CCA when working agent-specific issues (`squad:{agent-name}` labels tell CCA which charter to read) -- Test: CCA picks up a `squad:fenster` issue, reads Fenster's charter, follows Fenster's conventions - -**Risk:** Medium. CCA's behavior with `.ai-team/` files is not fully characterized. Need validation that CCA reads and respects agent-level files. If CCA ignores `.ai-team/`, fallback is documentation-only governance (still valuable — humans and future CCA versions benefit). - -### In: Clean Branch Configuration - -**Why now:** Brady's P3. At init time, users should be able to configure branches that should never contain team files. This is a quality-of-life feature that prevents `.ai-team/` and `team-docs/` from leaking into production branches. - -**What must ship:** -- `squad init` option: "Which branches should exclude team files?" -- Configuration stored in `.ai-team/config.json` or equivalent -- Guard in coordinator: warn if team files would be committed to a protected branch -- Reasonable defaults: `main`, `master`, `production` excluded by default - -**Risk:** Low. This is configuration + prompt engineering. No architectural complexity. - -### In: Per-Agent Model Selection (from Proposal 024) — MOVED FROM WAVE 1 - -**Why now:** Still important — every agent spawn benefits from the right model. But Brady's reprioritization moves this from "sole Wave 1 focus" to a Wave 2 item. The compound value is real; the urgency is lower than async comms and GitHub integration. - -**Scoped to:** Phase 1 (coordinator instructions + auto-selection algorithm) and Phase 2 (charter + registry integration). Phase 3 (cost reporting, override persistence) deferred. - -### In: Marketing Site (from Proposals 029, 029a) - -**Why now:** Brady wants it. Jekyll on GitHub Pages, `docs/` as source. The architecture is decided (Proposal 029). This is independent work that McManus + Fenster can execute in parallel. - -**Scoped to:** Phase 1 only — front matter, layouts, config, landing page. No custom plugins. - -### In: Team Backlog — Extraction + Dual-Layer Storage (from Proposal 023, Phases 1-2) — RETAINED - -**Why now:** Message extraction and backlog capture remain important for the GitHub-native integration (Issues need something to push). Retained from the previous plan at the same scope. - -**Scoped to:** Phase 1 (message extraction + dual-layer writes + backlog.md) and Phase 2 (Scribe merge + agent read access). - -### In: Demo Script Infrastructure (from Proposal 026, partial) — RETAINED - -**Why now:** Brady still needs to show Squad to the world. Demo 1 remains the minimum viable demo infrastructure. - -**Scoped to:** Demo 1 script (YAML + vhs tape), CI smoke test, README GIF embed. - ---- - -## What's Out — And Why - -| Feature | Why Cut | Revisit When | -|---------|---------|--------------| -| **Squad DM Phase 2 (proactive messaging)** | Phase 0-1 must ship and prove the concept first. Push notifications add complexity before the basic loop works. | DM Phase 1 validated with Brady using it daily | -| **Squad DM Phase 3 (multi-platform, multi-repo)** | One platform, one repo, one user. Prove the pattern, then scale. | Phase 1 is stable, Brady requests Slack/Discord | -| **028 Phases 2-4 (comment pull-back, Project boards, cross-repo)** | Phase 1 shipping in v0.3.0. Build on proven one-way push. | Phase 1 is stable and Brady wants richer integration | -| **Agent cloning (023 Phase 3)** | Coordination complexity — needs proven backlog capture first. | Backlog has 20+ items across 5+ sessions | -| **Proactive backlog surfacing (023 Phase 4)** | Ship capture first, intelligence later. | Phase 1-2 prove the backlog is useful | -| **Model selection Phase 3 (cost reporting, override persistence)** | Polish, not leverage. | User feedback requests it | -| **Demos 2-5** | Demo 1 proves the format first. | Demo 1 is recorded and shipped | -| **Squad Paper** | Content, not product. | When Brady wants to publish | -| **Agent-to-agent negotiation** | Needs proven model selection + reliable skills first. | v0.4.0+ | -| **Speculative execution** | Needs very low silent success rate. | Silent success < 3% | - - ---- - -## Brady's Directives (Inherited + Revised — Non-Negotiable) - -1. **Quality first, then experience.** v0.3.0 features ship into a codebase with 92 tests and CI. -2. **Async communication is P0.** Brady wants to talk to his squads from his phone. This is the top personal priority. -3. **GitHub IS the interface.** Issues, PRs, and Discussions are first-class surfaces — not just the CLI. Validated by slidemaker. -4. **CCA inherits Squad.** Copilot Coding Agent should discover and respect `.ai-team/` governance. -5. **"Where are we?" is first-class.** Backlog capture enriches status. The coordinator includes open backlog items. -6. **"Feels heard."** Message extraction + DM mode make "feels heard" richer across surfaces. -7. **CLI is primary, everything else is additive.** GitHub Issues/PR integration must not break CLI conversations. - ---- - -## Summary Table — All Work Items - -| ID | Item | Owner | Effort | Depends On | Wave | -|----|------|-------|--------|------------|------| -| **W1.1** | Copilot SDK spike — agent spawning feasibility | Kujan | 4-6h | — | 1 | -| **W1.2** | Telegram bot — polling-based bridge (Phase 0) | Fenster + Kujan | 4-6h | W1.1 | 1 | -| **W1.3** | DM mode flag + summary output in spawn prompts | Verbal | 2-3h | W1.2 | 1 | -| **W1.4** | Agent identity in DM (emoji + name prefix) | Verbal | 1-2h | W1.2 | 1 | -| **W1.5** | Dev Tunnel integration (webhook mode) | Fenster | 2-3h | W1.2 | 1 | -| **W1.6** | DM conversation persistence (dm-log/) | Fenster | 1-2h | W1.2 | 1 | -| **W1.7** | DM end-to-end tests | Hockney | 3-4h | W1.2, W1.3 | 1 | -| **W1.8** | GitHub Actions fallback workflow (if SDK fails) | Kujan + Kobayashi | 3-4h | W1.1 (fail path) | 1 | -| **W2.1** | Message extraction in coordinator (023 Phase 1) | Verbal + Kujan | 3-4h | — | 2 | -| **W2.2** | Backlog.md format + creation on init/upgrade | Fenster | 2-3h | — | 2 | -| **W2.3** | Backlog tests | Hockney | 2-3h | W2.1, W2.2 | 2 | -| **W2.4** | GitHub Issue push — one-way sync (028 Phase 1) | Verbal + Kujan | 3-4h | W2.1, W2.2 | 2 | -| **W2.5** | Issues as work input — Squad reads labeled Issues | Verbal + Kujan | 3-4h | W2.4 | 2 | -| **W2.6** | CCA discovery — squad.agent.md as CCA entry point | Verbal + Keaton | 2-3h | — | 2 | -| **W2.7** | CCA charter routing — squad: labels → agent charters | Kujan | 2-3h | W2.6 | 2 | -| **W2.8** | CCA adoption tests | Hockney | 2-3h | W2.6, W2.7 | 2 | -| **W2.9** | Clean branch config at init time | Fenster | 2-3h | — | 2 | -| **W2.10** | Clean branch tests | Hockney | 1-2h | W2.9 | 2 | -| **W3.1** | Model auto-selection algorithm in coordinator | Verbal + Kujan | 3-4h | — | 3 | -| **W3.2** | Charter `## Model` section + template update | Verbal | 1-2h | W3.1 | 3 | -| **W3.3** | Registry `model` field + migration | Fenster | 2-3h | W3.1 | 3 | -| **W3.4** | Model selection tests | Hockney | 2-3h | W3.1, W3.2, W3.3 | 3 | -| **W3.5** | Model visibility in spawn output | Verbal | 1h | W3.1 | 3 | -| **W3.6** | Marketing site Phase 1 (Jekyll + layouts + front matter) | McManus + Fenster | 5-8h | — | 3 | -| **W3.7** | Scribe merge for backlog inbox | Verbal | 2-3h | W2.1, W2.2 | 3 | -| **W3.8** | "Where are we?" enriched with backlog items | Verbal | 1-2h | W3.7 | 3 | -| **W3.9** | Demo 1 YAML script + vhs tape file | McManus | 3-4h | — | 3 | -| **W3.10** | Demo CI smoke test | Hockney + Kobayashi | 2-3h | W3.9 | 3 | -| **W3.11** | README GIF embed from Demo 1 | McManus | 1h | W3.9 | 3 | -| **W3.12** | v0.3.0 release + CHANGELOG | Kobayashi | 1-2h | All | 3 (gate exit) | - -**Total: 63-94 hours across 3 waves.** This is significantly larger than the original 31-43h plan because Brady un-deferred a major feature (Squad DM) and added two new categories (CCA adoption, clean branches). - ---- - -## Wave 1: Reach — "Talk to Your Squad From Anywhere" - -**Duration:** ~5-7 days -**Principle:** Brady's top personal priority. Squad DM transforms Squad from a terminal tool to a team in your pocket. -**The hard truth:** This is the riskiest wave in Squad's history. The Copilot SDK `task` equivalence is unproven. We spike first, build second, and have a fallback ready. - -### W1.1 Copilot SDK Spike — Agent Spawning Feasibility - -**Owner:** Kujan -**Effort:** 4-6 hours -**Depends on:** Nothing — this is Day 1 -**Source:** Proposal 017-platform-feasibility §2 (Option A), §10 (verification gates) - -**What ships:** -- Install `@github/copilot-sdk`, create a session, verify: - 1. Can we create a session with custom tools? (file ops, search) - 2. Can a tool handler create ANOTHER session? (This is the `task` equivalent) - 3. What's the latency for `session.sendAndWait()`? -- Written assessment: SDK path viable (go) or not (fallback to GitHub Actions) -- If GO: document the session nesting pattern for Fenster to implement -- If NO-GO: W1.8 (GitHub Actions fallback) becomes the primary path - -**Risk:** HIGH — this is the go/no-go gate for the entire DM feature's architecture. If the SDK can't do nested sessions, we lose the multi-agent orchestration that makes Squad DM different from ChatGPT-in-Telegram. The GitHub Actions fallback preserves functionality at 60-120s latency cost. - -### W1.2 Telegram Bot — Polling-Based Bridge (Phase 0) - -**Owner:** Fenster + Kujan -**Effort:** 4-6 hours -**Depends on:** W1.1 (must know which execution engine to use) -**Source:** Proposal 017-experience-design §6, §9 (Phase 0), Proposal 017-platform-feasibility §6 - -**What ships:** -- Node.js bridge service: `npx squad dm start` (or equivalent CLI command) -- Telegram bot via BotFather registration -- Polling-based message reception (no tunnel needed for Phase 0) -- Message forwarding: Telegram → bridge → Copilot SDK session (or Actions dispatch) → response → Telegram -- Single repo (the repo the bridge runs in), single user (Brady, hardcoded user ID) -- Auth check: only Brady's Telegram ID can message the bot -- Library: `telegraf` or `node-telegram-bot-api` - -**Risk:** Medium — Telegram bot setup is well-documented. The bridge is ~200-400 LOC. The complexity is in the Copilot SDK integration layer, not the Telegram part. - -### W1.3 DM Mode Flag + Summary Output in Spawn Prompts - -**Owner:** Verbal -**Effort:** 2-3 hours -**Depends on:** W1.2 (bridge must exist to inject DM mode) -**Source:** Proposal 017-experience-design §7 - -**What ships:** -- `DM_MODE` context variable added to spawn prompts when invoked from bridge -- DM output rules in coordinator: summaries only, max 4-5 sentences, bullet points, link to GitHub for full artifacts -- No code blocks > 5 lines, no tables > 3 columns -- One message per agent per response -- Progressive disclosure: "show me the full thing" → GitHub link or chunked paste - -**Risk:** Low — prompt engineering. The formatting rules are clear and testable. - -### W1.4 Agent Identity in DM (Emoji + Name Prefix) - -**Owner:** Verbal -**Effort:** 1-2 hours -**Depends on:** W1.2 -**Source:** Proposal 017-experience-design §2 - -**What ships:** -- Single "Squad" bot, agents identified by emoji prefix + name -- Coordinator stays invisible (routes silently, same as terminal) -- Exception: coordinator speaks when fan-out is interesting - -**Risk:** Very low — message formatting - -### W1.5 Dev Tunnel Integration (Webhook Mode) - -**Owner:** Fenster -**Effort:** 2-3 hours -**Depends on:** W1.2 (polling bridge must work first) -**Source:** Proposal 017-platform-feasibility §3, Proposal 017-experience-design §6 - -**What ships:** -- `devtunnel host -p 3000 --allow-anonymous` integration -- Webhook mode replaces polling for lower latency -- Automatic Dev Tunnel URL registration with Telegram webhook API -- GitHub-native auth: `devtunnel user login -g` -- Graceful fallback: if devtunnel unavailable, stay on polling - -**Risk:** Low — Dev Tunnel setup is documented. - -### W1.6 DM Conversation Persistence (dm-log/) - -**Owner:** Fenster -**Effort:** 1-2 hours -**Depends on:** W1.2 -**Source:** Proposal 017-experience-design §7 (context continuity) - -**What ships:** -- `.ai-team/dm-log/` directory for DM conversation logs -- Timestamped session files: `dm-log/2026-02-10T22-15.md` -- DM decisions written to `decisions/inbox/` (same as terminal decisions) -- Context continuity: terminal sessions can reference DM decisions and vice versa - -**Risk:** Low — file write pattern - -### W1.7 DM End-to-End Tests - -**Owner:** Hockney -**Effort:** 3-4 hours -**Depends on:** W1.2, W1.3 -**Source:** Test patterns from v0.2.0 - -**What ships:** -- Tests for bridge message routing (mock Telegram → coordinator) -- Tests for DM mode output formatting (summary length, no code blocks, emoji prefixes) -- Tests for conversation persistence (dm-log/ writes) -- Tests for auth check (non-Brady user rejected) -- Tests for graceful degradation (no SDK → Actions fallback, no devtunnel → polling) - -**Risk:** Medium — testing a messaging bridge requires mocking the Telegram API - -### W1.8 GitHub Actions Fallback Workflow (If SDK Fails) - -**Owner:** Kujan + Kobayashi -**Effort:** 3-4 hours -**Depends on:** W1.1 (only needed if SDK spike fails) -**Source:** Proposal 017-platform-feasibility §2 (Option C), Appendix C - -**What ships (only if W1.1 fails):** -- `.github/workflows/squad-dm.yml` — issue comment trigger (`/squad` prefix) -- Workflow: checkout repo → run Squad CLI with message → commit results → reply on issue -- Conversation threading via dedicated GitHub Issue per DM session -- Latency: 60-120s (acceptable for async, not for real-time chat) - -**Risk:** Medium — Copilot CLI availability on Actions runners is uncertain. - -### Wave 1 Parallelism - -``` -Day 1-2: Day 3-5: Day 5-7: -├── W1.1 SDK spike (Kujan) ├── W1.3 DM mode prompts (Verbal) ├── W1.7 DM tests (Hockney) - ├── W1.4 Agent identity (Verbal) └── W1.5 Dev Tunnel (Fenster) - ├── W1.2 Telegram bridge (Fenster + Kujan) - └── W1.6 DM persistence (Fenster) - (W1.8 only if W1.1 fails) -``` - -W1.1 MUST complete before anything else can start. It determines the architecture. - -### Wave 1 Gate: "Can Brady DM His Squad?" - -**This gate is binary. ALL must pass or Wave 2 doesn't start.** - -- [ ] SDK spike complete — architecture decision documented (SDK or Actions fallback) -- [ ] Brady can send a Telegram message and get a response from his Squad -- [ ] Response includes agent identity (emoji + name) -- [ ] Response is in DM summary format (not terminal-length output) -- [ ] Conversation logged to `.ai-team/dm-log/` -- [ ] Auth works: non-Brady users rejected -- [ ] `npm test` passes (all new tests + existing 92) -- [ ] CI is green - ---- - -## Wave 2: Integration — "GitHub IS the Interface" - -**Duration:** ~5-7 days -**Principle:** Squad reads from and responds to GitHub's native surfaces. CCA discovers Squad and works under its governance. -**Gate prerequisite:** Wave 1 gate must be GREEN. - -### W2.1 Message Extraction in Coordinator (023 Phase 1) - -**Owner:** Verbal + Kujan -**Effort:** 3-4 hours -**Depends on:** Nothing (Wave 2 can start these immediately) -**Source:** Proposal 023 §Solution, §Extraction - -**What ships:** -- Coordinator parses every message into item types: work requests, directives, backlog items, questions, context clues -- Dual-layer write: SQL INSERT (immediate) + append to `.ai-team/backlog.md` (durable) -- Rehydration on session start: read `backlog.md`, rebuild SQL state -- Acknowledgment enrichment: coordinator confirms captured items alongside agent spawns -- Hard rule: coordinator EXTRACTS and CAPTURES, never EVALUATES - -**Risk:** Medium — the critical prompt engineering challenge of v0.3.0 - -### W2.2 Backlog.md Format + Creation on Init/Upgrade - -**Owner:** Fenster -**Effort:** 2-3 hours -**Depends on:** Nothing -**Source:** Proposal 023 §Team Backlog - -**What ships:** -- `.ai-team/backlog.md` format: `## Open` (checkbox items), `## Done` (completed items) -- Created on init and upgrade (additive migration) -- `backlog/inbox/` directory for agent drop-box writes -- Template in `templates/` - -**Risk:** Low — established patterns - -### W2.3 Backlog Tests - -**Owner:** Hockney -**Effort:** 2-3 hours -**Depends on:** W2.1, W2.2 -**Source:** Proposal 023 success criteria - -**What ships:** -- Tests for backlog.md creation on init and upgrade -- Tests for backlog/inbox/ directory creation -- Tests for backlog template format validation - -**Risk:** Low - -### W2.4 GitHub Issue Push — One-Way Sync (028 Phase 1) - -**Owner:** Verbal + Kujan -**Effort:** 3-4 hours -**Depends on:** W2.1, W2.2 (backlog must exist for backlog→Issue push) -**Source:** Proposal 028 §Phase 1, slidemaker reference implementation - -**What ships:** -- Proposals → GitHub Issues with labels (`proposal`, `sprint:0.3.0`) -- Backlog items → GitHub Issues with labels (`backlog`, `captured`) -- Status changes close/update corresponding issues -- `squad:` and `squad:{agent-name}` label conventions (validated by slidemaker) -- Issue numbers stored as metadata in markdown files -- If `gh` CLI / GitHub MCP unavailable, skip silently - -**Risk:** Low — prompt engineering, proven `gh` CLI patterns - -### W2.5 Issues as Work Input — Squad Reads Labeled Issues - -**Owner:** Verbal + Kujan -**Effort:** 3-4 hours -**Depends on:** W2.4 (label conventions must exist) -**Source:** Proposal 028, slidemaker validation, Brady's P1 directive - -**What ships:** -- Coordinator can read `squad:`-labeled GitHub Issues as work input -- Issue body parsed: user story format, acceptance criteria, agent metadata -- Agent routing: `squad:fenster` label → spawn Fenster with issue context -- Issue status updates as work progresses (comments, label changes) -- Bi-directional in spirit: filesystem is authoritative, but Issues are a valid INPUT surface - -**Risk:** Medium — parsing Issue bodies is prompt engineering with variable-quality input. Slidemaker's 9-issue validation provides the template, but real-world issues will vary. - -### W2.6 CCA Discovery — squad.agent.md as CCA Entry Point - -**Owner:** Verbal + Keaton -**Effort:** 2-3 hours -**Depends on:** Nothing -**Source:** Brady's P2 directive - -**What ships:** -- Documentation in `squad.agent.md`: section explaining CCA integration -- `.ai-team/` directory structure documented for CCA discovery -- CCA reads `squad.agent.md` → understands team structure, conventions, routing -- Squad governance principles documented for CCA adherence - -**Risk:** Medium — CCA's file discovery behavior is not fully documented. We design for expected behavior and validate. - -### W2.7 CCA Charter Routing — squad: Labels → Agent Charters - -**Owner:** Kujan -**Effort:** 2-3 hours -**Depends on:** W2.6 -**Source:** slidemaker label conventions, Brady's P2 directive - -**What ships:** -- When CCA picks up a `squad:fenster` issue, it reads `.ai-team/agents/fenster/charter.md` -- Charter provides context: role, expertise, coding style, file responsibilities -- CCA works "as" that agent — same conventions, same standards -- Fallback: if no agent label, CCA reads `squad.agent.md` for general governance - -**Risk:** Medium — depends on CCA's willingness to read and follow charter files. - -### W2.8 CCA Adoption Tests - -**Owner:** Hockney -**Effort:** 2-3 hours -**Depends on:** W2.6, W2.7 - -**What ships:** -- Tests for squad.agent.md containing CCA discovery section -- Tests for charter files being readable/parseable for CCA context -- Tests for label→charter routing logic - -**Risk:** Medium - -### W2.9 Clean Branch Configuration at Init Time - -**Owner:** Fenster -**Effort:** 2-3 hours -**Depends on:** Nothing -**Source:** Brady's P3 directive - -**What ships:** -- `squad init` prompts: "Which branches should exclude team files?" -- Configuration stored in `.ai-team/config.json` -- Default excluded branches: `main`, `master`, `production` -- Coordinator warns if team files would be committed to a protected branch -- Upgrade migration: adds config with defaults for existing squads - -**Risk:** Low — configuration + prompt engineering - -### W2.10 Clean Branch Tests - -**Owner:** Hockney -**Effort:** 1-2 hours -**Depends on:** W2.9 - -**What ships:** -- Tests for config creation on init -- Tests for default branch exclusions -- Tests for config migration on upgrade - -**Risk:** Low - -### Wave 2 Parallelism - -``` -Wave 2 start (all can begin after Wave 1 gate): -├── W2.1 Message extraction (Verbal + Kujan) → W2.4 GitHub Issue push (after W2.1, W2.2) -├── W2.2 Backlog.md format (Fenster) → W2.5 Issues as work input (after W2.4) -├── W2.6 CCA discovery (Verbal + Keaton) → W2.7 CCA charter routing (after W2.6) -├── W2.9 Clean branch config (Fenster) → W2.8 CCA tests (after W2.6, W2.7) - → W2.3 Backlog tests (after W2.1, W2.2) - → W2.10 Clean branch tests (after W2.9) -``` - -### Wave 2 Gate: "Does GitHub Drive Squad?" - -- [ ] Backlog items persist to `.ai-team/backlog.md` -- [ ] Proposals and backlog items appear as labeled GitHub Issues -- [ ] Squad can read `squad:`-labeled Issues as work input -- [ ] CCA discovery section exists in `squad.agent.md` -- [ ] CCA can pick up a `squad:` labeled issue and read the corresponding agent charter -- [ ] Clean branch configuration works at init time with sensible defaults -- [ ] If `gh` CLI unavailable, Squad works identically to before -- [ ] `npm test` passes -- [ ] CI is green - ---- - -## Wave 3: Intelligence + Polish — "Make It Smart, Make It Shine" - -**Duration:** ~4-5 days -**Principle:** Model selection, marketing site, demo infrastructure, and backlog intelligence. Important but not blocking the core v0.3.0 story. -**Gate prerequisite:** Wave 2 gate must be GREEN. - -### W3.1 Model Auto-Selection Algorithm in Coordinator - -**Owner:** Verbal + Kujan -**Effort:** 3-4 hours -**Depends on:** Nothing -**Source:** Proposal 024 §2, §4 - -**What ships:** -- Model Selection section added to `squad.agent.md` -- 4-layer priority: user override → charter preference → registry field → role-based auto-select -- Role-to-model mapping: Designer → Opus, Tester/Scribe → Haiku, Lead/Dev → Sonnet -- Coordinator passes `model` parameter to all `task` tool calls - -**Risk:** Low — prompt engineering only - -### W3.2 Charter `## Model` Section + Template Update - -**Owner:** Verbal -**Effort:** 1-2 hours -**Depends on:** W3.1 -**Source:** Proposal 024 §1 - -**What ships:** -- `## Model` section in `templates/charter.md` with `Preferred` and `Rationale` -- Default value `auto` — zero config - -**Risk:** Very low - -### W3.3 Registry `model` Field + Migration - -**Owner:** Fenster -**Effort:** 2-3 hours -**Depends on:** W3.1 -**Source:** Proposal 024 §3 - -**What ships:** -- `model` field in `casting/registry.json`, additive migration - -**Risk:** Low - -### W3.4 Model Selection Tests - -**Owner:** Hockney -**Effort:** 2-3 hours -**Depends on:** W3.1, W3.2, W3.3 - -**Risk:** Low - -### W3.5 Model Visibility in Spawn Output - -**Owner:** Verbal -**Effort:** 1 hour -**Depends on:** W3.1 - -**Risk:** Very low - -### W3.6 Marketing Site Phase 1 - -**Owner:** McManus + Fenster -**Effort:** 5-8 hours -**Depends on:** Nothing -**Source:** Proposals 029, 029a - -**What ships:** -- `_config.yml`, `_layouts/`, `_includes/` for Jekyll -- YAML front matter on 16+ docs files -- `docs/index.md` landing page -- CSS/styling, GitHub Pages configured - -**Risk:** Low — no product code changes - -### W3.7 Scribe Merge for Backlog Inbox - -**Owner:** Verbal -**Effort:** 2-3 hours -**Depends on:** W2.1, W2.2 -**Source:** Proposal 023 §Phase 2 - -**What ships:** -- Scribe merges `backlog/inbox/` into `backlog.md` -- Agents can mark items done, add discovered items - -**Risk:** Low - -### W3.8 "Where Are We?" Enriched with Backlog Items - -**Owner:** Verbal -**Effort:** 1-2 hours -**Depends on:** W3.7 -**Source:** Proposal 023 §What This Unlocks - -**Risk:** Low - -### W3.9 Demo 1 YAML Script + vhs Tape File - -**Owner:** McManus -**Effort:** 3-4 hours -**Depends on:** Nothing -**Source:** Proposal 026 §Demo 1 - -**Risk:** Medium - -### W3.10 Demo CI Smoke Test - -**Owner:** Hockney + Kobayashi -**Effort:** 2-3 hours -**Depends on:** W3.9 - -**Risk:** Medium - -### W3.11 README GIF Embed from Demo 1 - -**Owner:** McManus -**Effort:** 1 hour -**Depends on:** W3.9 - -**Risk:** Very low - -### W3.12 v0.3.0 Release + CHANGELOG - -**Owner:** Kobayashi -**Effort:** 1-2 hours -**Depends on:** All items complete - -**Risk:** Very low - -### Wave 3 Gate: "Is It Smart and Visible?" - -- [ ] Coordinator spawns agents with `model` parameter based on auto-selection -- [ ] Charter template includes `## Model` section -- [ ] Registry includes `model` field with migration -- [ ] Marketing site renders on GitHub Pages -- [ ] Backlog items appear in "where are we?" responses -- [ ] Demo 1 produces a clean GIF -- [ ] README contains embedded demo GIF -- [ ] `npm test` passes -- [ ] CI is green -- [ ] v0.3.0 tagged and released - ---- - -## Dependency Graph - -``` -Wave 1 (Reach — Async Comms) -├── W1.1 SDK spike (Kujan) ── GO/NO-GO GATE -│ ├── W1.2 Telegram bridge (Fenster + Kujan) ← needs W1.1 -│ │ ├── W1.3 DM mode prompts (Verbal) ← needs W1.2 -│ │ ├── W1.4 Agent identity (Verbal) ← needs W1.2 -│ │ ├── W1.5 Dev Tunnel (Fenster) ← needs W1.2 -│ │ ├── W1.6 DM persistence (Fenster) ← needs W1.2 -│ │ └── W1.7 DM tests (Hockney) ← needs W1.2, W1.3 -│ └── W1.8 Actions fallback (Kujan + Kobayashi) ← only if W1.1 FAILS -│ -══════════════ WAVE 1 GATE ════════════════════ -│ -Wave 2 (Integration — GitHub + CCA + Clean Branches) -├── W2.1 Message extraction (Verbal + Kujan) -├── W2.2 Backlog.md format (Fenster) -│ └── W2.3 Backlog tests (Hockney) ← needs W2.1, W2.2 -├── W2.4 GitHub Issue push (Verbal + Kujan) ← needs W2.1, W2.2 -│ └── W2.5 Issues as work input (Verbal + Kujan) ← needs W2.4 -├── W2.6 CCA discovery (Verbal + Keaton) -│ └── W2.7 CCA charter routing (Kujan) ← needs W2.6 -│ └── W2.8 CCA tests (Hockney) ← needs W2.6, W2.7 -├── W2.9 Clean branch config (Fenster) -│ └── W2.10 Clean branch tests (Hockney) ← needs W2.9 -│ -══════════════ WAVE 2 GATE ════════════════════ -│ -Wave 3 (Intelligence + Polish) -├── W3.1 Model auto-selection (Verbal + Kujan) -│ ├── W3.2 Charter model section (Verbal) ← needs W3.1 -│ ├── W3.3 Registry model field (Fenster) ← needs W3.1 -│ ├── W3.4 Model selection tests (Hockney) ← needs W3.1-W3.3 -│ └── W3.5 Model visibility (Verbal) ← needs W3.1 -├── W3.6 Marketing site (McManus + Fenster) ← independent -├── W3.7 Scribe backlog merge (Verbal) ← needs W2.1, W2.2 -│ └── W3.8 "Where are we?" enrichment (Verbal) ← needs W3.7 -├── W3.9 Demo 1 script (McManus) ← independent -│ ├── W3.10 Demo CI test (Hockney + Kobayashi) ← needs W3.9 -│ └── W3.11 README GIF (McManus) ← needs W3.9 -└── W3.12 Release (Kobayashi) ← needs all -``` - ---- - -## Agent Workload Summary - -| Agent | Wave 1 | Wave 2 | Wave 3 | Total | -|-------|--------|--------|--------|-------| -| **Verbal** | W1.3 (2-3h), W1.4 (1-2h) | W2.1 shared (2h), W2.4 shared (2h), W2.5 shared (2h), W2.6 shared (1-2h) | W3.1 shared (2h), W3.2 (1-2h), W3.5 (1h), W3.7 (2-3h), W3.8 (1-2h) | 17-24h | -| **Kujan** | W1.1 (4-6h), W1.2 shared (2-3h), W1.8 conditional (2-3h) | W2.1 shared (2h), W2.4 shared (2h), W2.5 shared (2h), W2.7 (2-3h) | W3.1 shared (2h) | 18-23h | -| **Fenster** | W1.2 shared (2-3h), W1.5 (2-3h), W1.6 (1-2h) | W2.2 (2-3h), W2.9 (2-3h) | W3.3 (2-3h), W3.6 shared (3-4h) | 14-21h | -| **Hockney** | W1.7 (3-4h) | W2.3 (2-3h), W2.8 (2-3h), W2.10 (1-2h) | W3.4 (2-3h), W3.10 shared (1-2h) | 11-17h | -| **McManus** | — | — | W3.6 shared (2-4h), W3.9 (3-4h), W3.11 (1h) | 6-9h | -| **Kobayashi** | W1.8 shared conditional (1-2h) | — | W3.10 shared (1h), W3.12 (1-2h) | 3-5h | -| **Keaton** | Review SDK spike | Review gates, W2.6 shared (1h) | Final sign-off | Continuous | -| **Redfoot** | — | — | — | — | -| **Scribe** | — | — | — | (silent, as always) | - ---- - -## Total Effort Estimate - -| Wave | Effort | Calendar (with parallelism) | -|------|--------|---------------------------| -| Wave 1 (Reach — Async Comms) | 21-32h | 5-7 days | -| Wave 2 (Integration — GitHub + CCA) | 22-32h | 5-7 days | -| Wave 3 (Intelligence + Polish) | 25-35h | 4-5 days | -| **Total** | **68-99h** | **~14-19 days** | - -This is SIGNIFICANTLY larger than the original 31-43h plan. That's because Brady un-deferred the hardest feature in Squad's backlog (DM) and added two new categories (CCA, clean branches). I want to be honest about this: **v0.3.0 is now a v0.2.0-sized sprint or bigger.** If scope pressure hits, Wave 3 items (model selection, marketing site, demos) are the relief valve — they can slip to 0.4.0 without breaking the v0.3.0 story. - -### Scope Pressure Relief Valves - -If the sprint runs long, cut in this order (least damage to v0.3.0's story): - -1. **W3.9-W3.11 (Demo infrastructure)** — defer to 0.4.0. Demo 1 is important but not blocking the DM + GitHub story. -2. **W3.6 (Marketing site)** — defer to 0.4.0. The site is independent and McManus can ship it any time. -3. **W3.7-W3.8 (Scribe merge + Where are we?)** — defer to 0.4.0. Backlog capture (W2.1-W2.3) delivers core value; intelligence on top can wait. -4. **W3.1-W3.5 (Model selection)** — last resort deferral. This is compound value, but v0.3.0's story is "reach + integration," not "intelligence." Model selection becomes v0.4.0's centerpiece. - ---- - -## What Makes Users Say "This Is the Future" - -1. **"I texted my squad from the gym."** Brady sends a message from his phone. Keaton answers with an opinion about the architecture. Not a chatbot — Keaton. Same memory, same voice, same standards. Squad is no longer tethered to a terminal. - -2. **"I filed an issue and my team picked it up."** A GitHub Issue with `squad:fenster` label gets created. Next time Squad runs, Fenster picks it up and starts working. GitHub is the work surface — Squad is the team. - -3. **"CCA just followed our conventions."** Copilot Coding Agent picks up an issue, discovers `.ai-team/`, reads the charter, and works like a team member. No special setup — Squad's governance is the environment. - -4. **"My team files are never in production."** Clean branch configuration means `.ai-team/` never leaks into `main`. Zero thought required. - -5. **"It just used the right model."** Auto-selection matches models to roles. Zero config. - -6. **"One GIF and I get it."** Demo infrastructure proves the product works — scripted, repeatable, embedded in the README. - ---- - -## Horizon — Deferred Past 0.3.0 - -| Feature | Source | Why Not Now | Revisit When | -|---------|--------|-------------|--------------| -| **Squad DM Phase 2 (proactive messaging)** | Proposal 017 | Phase 0-1 must prove the concept | Brady uses DM daily for 2 weeks | -| **Squad DM Phase 3 (multi-platform, multi-repo)** | Proposal 017 | One platform, one repo first | DM Phase 1 stable | -| **Agent cloning** | Proposal 023 Phase 3 | Needs proven backlog capture | 0.4.0 | -| **Proactive backlog surfacing** | Proposal 023 Phase 4 | Needs backlog with real data | 0.4.0 | -| **Model cost reporting** | Proposal 024 Phase 3 | Polish, not leverage | User feedback | -| **Override persistence** | Proposal 024 Phase 3 | Session overrides work | 0.4.0 | -| **Demos 2-5** | Proposal 026 | Validate Demo 1 first | After Demo 1 | -| **Squad Paper** | Proposal 016 | Content, not product | When Brady wants it | -| **028 Phases 2-4** | Proposal 028 | Phase 1 must prove one-way push | 0.4.0+ | -| **Agent-to-agent negotiation** | Proposal 003 | Needs proven model selection | v0.4.0+ | -| **Speculative execution** | Proposal 003 | Needs low silent success rate | v0.4.0+ | -| **Squad sharing / registry** | Proposal 008 | Needs proven portability | v1.0 | - ---- - -## How This Plan Compounds - -Each 0.3.0 feature makes the next version's features easier: - -- **Squad DM (Phase 0-1)** → proactive messaging (Phase 2) has the bridge to push through -- **Squad DM** → multi-platform (Phase 3) reuses the gateway architecture -- **GitHub Issue integration** → Project boards (028 Phase 3) build on proven label conventions -- **GitHub Issue integration** → PR-triggered responses extend the same event model -- **CCA adoption** → future CCA features inherit Squad's governance automatically -- **Clean branch config** → future deployment pipelines never need .ai-team cleanup -- **Model selection** → DM mode can use cheaper models for quick responses (Haiku for status checks) -- **Backlog capture** → proactive surfacing has data to surface -- **Demo infrastructure** → future demos reuse the format and CI patterns - -Every item in this plan makes the 0.4.0 plan shorter. The compound strategy is working — and now it extends beyond the terminal. - ---- - -## Revision History - -### Revision 2 (2026-02-10) — Brady's Priority Reorder - -**What changed:** -- **Squad DM UN-DEFERRED.** Previously deferred to Horizon (v1.0). Now P0 for v0.3.0 Wave 1. Brady's top personal priority. -- **Three waves, not two.** Added Wave 1 (Reach — async comms) and pushed previous Wave 1 content to Wave 2/3. -- **GitHub-native integration expanded.** Was Phase 1 only (one-way push). Now includes Issues as work input AND CCA adoption as separate work streams. -- **CCA adoption added.** New work stream — Squad as governance layer for Copilot Coding Agent. -- **Clean branch configuration added.** New work stream — protect production branches from team files. -- **Model selection moved to Wave 3.** Was Wave 1's centerpiece. Still ships in v0.3.0, but lower priority. -- **Marketing site added.** Proposals 029/029a, Jekyll on GitHub Pages. Wave 3 item. -- **Sprint size increased.** From 31-43h (2 waves) to 68-99h (3 waves). Reflects the scope Brady wants. -- **Scope pressure relief valves defined.** Wave 3 items explicitly cuttable if sprint runs long. -- **Prior art referenced.** Three 017 proposals provide the DM design foundation. Slidemaker validates GitHub Issues design. - -**What didn't change:** -- Backlog capture (023 Phases 1-2) retained at same scope -- Demo infrastructure retained at same scope -- All Horizon deferrals still apply (agent cloning, speculative execution, etc.) -- Brady's core directives still non-negotiable (quality first, CLI primary, feels heard) - -### Revision 1 (2026-02-10) — 028 Phase 1 Addition - -Proposal 028 Phase 1 (GitHub-Native Planning — one-way push) added to Wave 2 per Brady's directive. Original scope was 28-39h; revised to 31-43h. - ---- - -**This is the plan. Three waves. Reach first, integration second, intelligence third. Ship where Brady is — not just where his terminal is.** - -**Approved by:** Keaton (Lead) — I own this plan and these priorities -**Review requested from:** bradygaster -**Executed by:** The full squad - diff --git a/team-docs/proposals/028-github-native-team-planning.md b/team-docs/proposals/028-github-native-team-planning.md deleted file mode 100644 index 8642092bc..000000000 --- a/team-docs/proposals/028-github-native-team-planning.md +++ /dev/null @@ -1,483 +0,0 @@ -# Proposal 028: GitHub-Native Team Planning - -**Author:** Keaton (Lead) -**Date:** 2026-02-10 -**Status:** Phase 1 Approved for v0.3.0 ✅ -**Requested by:** bradygaster — *"think of the backlog becoming a github project. and proposals written to disk as markdown files written to github as issues instead. and use your imagination, team."* -**Builds on:** Proposal 023 (Incoming Queue), Proposal 025 (PR #2 — GitHub Issues Mode), Proposal 027 (v0.3.0 Sprint Plan) -**Door opened by:** @spboyer (PR #2 — GitHub Issues Mode) -**Reference implementation:** [spboyer/slidemaker](https://github.com/spboyer/slidemaker) — Shayne Boyer (@spboyer) validated this design end-to-end -**Contributors:** Shayne Boyer (@spboyer) — label conventions, issue structure, PRD→Issues pipeline validation - ---- - -## The Vision - -Squad's planning tools today are filesystem-native. Proposals are markdown files in `team-docs/proposals/`. The backlog (Proposal 023) will be `.ai-team/backlog.md`. Decisions live in `.ai-team/decisions/`. All of this works — it's fast, durable, agent-readable, git-tracked, and requires zero external dependencies. - -But it's also invisible. An external contributor like Shayne can't see what the team is planning without checking out a branch. Brady can't scan open proposals from his phone. Nobody can comment on a backlog item without editing a markdown file and pushing a commit. The planning surface is powerful for agents and opaque for humans. - -Brady's insight: **what if Squad's internal planning tools are also GitHub's collaboration tools?** - -Shayne already opened the door. PR #2 added GitHub Issues Mode — the ability to connect Squad to a repo's issues and work them through a full lifecycle (list → route → branch → PR → review → merge). That capability points inward. What if proposals ARE GitHub Issues? What if the team backlog IS a GitHub Project board? What if agents update the board as they work? - -This proposal designs that world. - ---- - -## The Problem - -### For humans - -1. **Proposals are invisible.** A proposal exists as a markdown file on a feature branch. To see it, you must check out that branch and read the file. There's no way to browse proposals, comment on them, or track their status without git access. - -2. **The backlog is local.** Proposal 023's `backlog.md` is agent-readable and durable — but only if you have the filesystem. Brady can't glance at the team's intent queue from a browser. - -3. **Collaboration requires commits.** To comment on a proposal or suggest a priority change, you must edit a file and push. GitHub Issues give you comments, reactions, labels, assignees, and milestones — all without touching git. - -4. **External contributors are blind.** Shayne contributed PR #2 by reading the codebase deeply. But he couldn't see the sprint plan, the backlog, or in-flight proposals without checking out the working branch. Making planning visible makes contribution easier. - -### For agents - -5. **No structured metadata on proposals.** A proposal's status ("Draft", "Approved ✅", "Cancelled") is a string in a markdown file. There's no queryable field. GitHub Issues give you labels, state (open/closed), milestones, and project board columns — all API-queryable. - -6. **Backlog items have no external surface.** An agent captures "add connection pooling" to `backlog.md`. That item has no URL, no comment thread, no way for a human to say "actually, let's prioritize this." A GitHub Issue does. - -7. **No cross-repo visibility.** If Squad is used on multiple projects, each has its own `backlog.md`. A GitHub Project can aggregate across repos. - ---- - -## The Design - -### Principle: Filesystem remains authoritative. GitHub is a synchronized view. - -Proposal 023 established: "Filesystem always wins. SQL is a queryable cache." This principle extends. GitHub becomes an external cache — richer than SQL (comments, labels, project boards) but still secondary to the filesystem. - -Why? Because: -- Agents read files, not APIs. Changing this is a deep architectural shift we don't need. -- Filesystem operations are instant and offline. API calls are slow and require connectivity. -- Git history is the audit trail. GitHub Issue history is supplementary. -- If the GitHub API is down, Squad still works. If the filesystem is corrupted, nothing works regardless. - -**The filesystem is the database. GitHub is the dashboard.** - -### Architecture: One-way push with selective pull-back - -``` -┌──────────────────────┐ ┌─────────────────────────┐ -│ FILESYSTEM (auth) │────────▶│ GITHUB (view + collab) │ -│ │ │ │ -│ proposals/*.md │──push──▶│ Issues (label:proposal) │ -│ backlog.md │──push──▶│ Project Board columns │ -│ decisions/ │──push──▶│ Issue comments (log) │ -│ │ │ │ -│ │◀─pull───│ Human comments │ -│ │◀─pull───│ Priority changes │ -│ │◀─pull───│ New issues from humans │ -└──────────────────────┘ └─────────────────────────┘ -``` - -**Push (filesystem → GitHub):** -- Agent writes a proposal → coordinator also creates a GitHub Issue with label `proposal` and the proposal body as the issue description. -- Backlog item captured → coordinator creates a GitHub Issue with label `backlog` and adds it to the Project board in the "Captured" column. -- Agent completes work → coordinator moves the issue to "Done" on the Project board and closes it. -- Proposal status changes → coordinator updates the issue (close it, add label `approved` or `cancelled`). - -**Pull-back (GitHub → filesystem):** -- Human comments on a proposal issue → next session, coordinator reads new comments and appends them to the proposal file's `## Discussion` section or includes them in agent context. -- Human changes priority (moves card on Project board) → coordinator reads the board state on session start and updates `backlog.md` ordering. -- Human creates a new issue → coordinator detects it on session start and adds it to `backlog.md` (same as Proposal 023's rehydration, but from GitHub instead of just the filesystem). - -**Conflict resolution:** If a backlog item exists in `backlog.md` but not on GitHub (or vice versa), the filesystem record is created/updated to match the union. Filesystem structure is authoritative for format; GitHub is authoritative for human-added comments and priority signals. - ---- - -## What This Unlocks - -### 1. Proposals become collaborative - -A proposal created by an agent appears as a GitHub Issue. Brady can read it on his phone, comment "I love this but cut Phase 3," and the next session, the agent sees that feedback. No branch checkout, no file editing, no commit required. - -Labels provide structure using the `squad:` prefix convention (validated by Shayne Boyer's slidemaker implementation): - -**Team labels:** -- `squad` — marks any issue as squad-managed (base label on every squad issue) -- `squad:{agent-name}` — routes to a specific agent (e.g., `squad:verbal`, `squad:mcmanus`, `squad:fenster`) - -**Planning labels:** -- `proposal` — it's a proposal -- `sprint:0.3.0` — it's scoped to a sprint -- `status:draft`, `status:approved`, `status:cancelled` — lifecycle tracking -- `area:architecture`, `area:devrel`, `area:testing` — domain routing - -### 2. The backlog becomes a Project board - -GitHub Projects gives the backlog a Kanban surface: - -| Captured | Open | In Progress | Done | -|----------|------|-------------|------| -| WebSocket support | Connection pooling | Auth refactor (Fenster) | Database module ✅ | -| Rate limiting | Caching layer | | Migration tests ✅ | - -Agents move cards as they work. The coordinator updates column positions. Humans can drag cards to reprioritize. The board is the team's shared intent — visible to everyone, updateable by anyone. - -### 3. External contributors can see the roadmap - -Shayne could have seen the sprint plan, the backlog, and the open proposals before contributing PR #2. He would have known which areas needed help, what the team's priorities were, and where his contribution fit. Making planning visible makes the project more inviting. - -### 4. Sprint planning gets GitHub milestones - -A sprint like v0.3.0 becomes a GitHub Milestone. Work items from Proposal 027 become issues assigned to that milestone. Progress is visible: "v0.3.0: 8/14 items complete." Brady can see sprint health from the GitHub UI without reading a markdown file. - -### 5. Discussion has a home - -Today, "discussion" on a proposal means Brady talks to the team in a Copilot CLI session. That discussion is ephemeral — it exists in terminal history and sometimes gets captured to decisions. With proposals as issues, discussion lives in the comment thread. Agents can read those comments. Humans can react with 👍 or 👎. The conversation has a URL. - -### 6. Cross-session continuity deepens - -Proposal 023 gives the backlog cross-session persistence via the filesystem. This proposal gives it cross-platform persistence. Close your laptop, open GitHub on your phone, see the board, add a comment, and the next session picks it up. The team's memory isn't trapped in a terminal. - ---- - -## What This Risks - -### 1. GitHub API coupling - -Squad currently has zero runtime dependencies on external APIs. Adding GitHub sync means: network calls that can fail, rate limits, authentication requirements (`gh` CLI or MCP GitHub server), and a new failure mode ("Squad can't update the board — GitHub is down"). - -**Mitigation:** GitHub sync is always optional. If no repo is connected, Squad works exactly as it does today. Sync failures are logged but never block agent work. The filesystem is always consistent, even if GitHub is stale. - -### 2. Sync drift - -The filesystem says a backlog item is "Open." The GitHub board says it's "In Progress." Who's right? - -**Mitigation:** Filesystem wins on structure (item exists, status). GitHub wins on supplementary data (comments, reactions, manual priority). On session start, the coordinator reconciles by reading both sources. Drift is resolved, not accumulated. - -### 3. Complexity creep - -Proposal 023 is elegant: extract → capture → acknowledge. This proposal adds: extract → capture → push to GitHub → reconcile on pull. Each additional step is a potential failure point and a maintenance surface. - -**Mitigation:** Phase the rollout aggressively. Phase 1 is one-way push only (write-and-forget). Phase 2 adds pull-back for comments only. Phase 3 adds full reconciliation. Each phase is independently valuable and independently revertible. - -### 4. Losing the speed of "just write a file" - -Today, an agent writes a proposal in 2 seconds (create file, done). With GitHub sync, it's 2 seconds + an API call (create issue). If the API call takes 3 seconds, we've more than doubled the overhead. - -**Mitigation:** GitHub push is asynchronous and non-blocking. The agent writes the file (done — agent can proceed) and the coordinator pushes to GitHub in the background or at the end of the session. The file write is never slower. - -### 5. Scope gravity - -"We're syncing proposals? Let's sync decisions too. And history. And skills. And the charter." Feature gravity pulls everything into the sync surface. Suddenly Squad is a GitHub-to-filesystem bidirectional sync engine, which is not what we're building. - -**Mitigation:** Explicit scope boundary: **only proposals and backlog items sync.** Decisions, history, skills, and charters remain filesystem-only. These are agent-internal state — syncing them to GitHub adds noise, not value. If we ever reconsider, it requires a new proposal. - ---- - -## Shayne's Door - -PR #2 added GitHub Issues Mode — the ability to connect Squad to a repo's issues and work them. That capability currently points outward: "here are issues that exist; let's work them." - -This proposal turns that capability inward: "here are planning artifacts that Squad creates; let's make them issues too." - -The implementation reuses Shayne's patterns: -- `gh issue create` / GitHub MCP `create_issue` — for pushing proposals and backlog items -- `gh issue list` / GitHub MCP `list_issues` — for reading human-added issues on session start -- `gh project` / GitHub MCP — for board management -- Labels, milestones, assignees — for structured metadata - -The difference: Shayne's mode is "work external issues." This proposal adds "manage internal planning artifacts on GitHub." Same tools, different direction. - ---- - -## Reference Implementation: spboyer/slidemaker - -> **Credit:** Shayne Boyer ([@spboyer](https://github.com/spboyer)) validated this proposal's design patterns end-to-end by using Squad to decompose a PRD into GitHub Issues on his [slidemaker](https://github.com/spboyer/slidemaker) project. The patterns documented here are extracted from that real-world usage. Shayne is a contributor to this design. - -### What Shayne built - -Squad decomposed a slidemaker PRD into 9 GitHub Issues ([#1](https://github.com/spboyer/slidemaker/issues/1)–[#9](https://github.com/spboyer/slidemaker/issues/9)), proving the full PRD → GitHub Issues pipeline works. 8 of 9 issues were completed and closed. The patterns that emerged are now the standard for Proposal 028. - -### Pattern 1: `squad:` label convention - -Every issue gets two labels: -- **`squad`** — the base label marking any issue as squad-managed. Applied to all 9 issues. -- **`squad:{agent-name}`** — routes the issue to a specific agent. Examples from slidemaker: - - `squad:verbal` (6 issues — frontend work) - - `squad:mcmanus` (2 issues — backend APIs) - - `squad:fenster` (1 issue — build verification and smoke tests) - -This convention is simple, scannable, and filterable. `gh issue list --label squad` shows all squad-managed issues. `gh issue list --label squad:verbal` shows one agent's workload. **This is now the standard label convention for Proposal 028's Phase 1.** - -### Pattern 2: User story format with acceptance criteria - -All 9 issues follow the same structure: - -```markdown -## User Story -**As a** {persona}, **I want** {capability}, **so that** {benefit}. - -## Acceptance Criteria -- [ ] Criterion 1 -- [ ] Criterion 2 -- [ ] ... - -## Notes -- Squad member: {Name} ({Role}) -- Primary work: {file paths} -- Dependencies: {inline dependency notes} -``` - -Key properties: -- **Consistent format** — every issue is parseable by agents and readable by humans -- **Testable criteria** — checkbox acceptance criteria define "done" unambiguously -- **Agent-readable metadata** — the Notes section tells the agent who owns the work and which files to touch - -### Pattern 3: Agent metadata injection - -Each issue's Notes section includes: -- **`Squad member: {Name} ({Role})`** — e.g., "Squad member: Verbal (Frontend Dev)", "Squad member: McManus (Backend Dev)", "Squad member: Fenster (Tester)" -- **`Primary work: {file paths}`** — e.g., "Primary work: `src/app/api/generate/route.ts`, `src/lib/openai.ts`" - -This metadata injection serves two purposes: it tells agents what to work on when they pick up the issue, and it tells humans which agent is responsible. - -### Pattern 4: Inline dependency tracking - -Issues note dependencies directly in the body: -- **"No dependencies — can start immediately"** (Issues #2, #7, #8) — signals parallel-safe work -- **"Dependencies will be added after all issues are created"** (Issues #1, #3, #4, #5, #6, #9) — deferred dependency linking - -This is lightweight and practical. For Phase 1 (one-way push), inline text dependencies are sufficient. Structured dependency tracking (sub-issues, issue links) is a Phase 2–3 concern. - -### Pattern 5: PRD → Issues decomposition pipeline - -The 9 issues were decomposed from a single PRD, proving the end-to-end flow: - -``` -PRD (product requirements) → Squad agent decomposition → 9 GitHub Issues -``` - -| # | Issue | Agent | Role | -|---|-------|-------|------| -| 1 | US-1: Generate a presentation via AI | Verbal | Frontend | -| 2 | US-2: View and navigate slides | Verbal | Frontend | -| 3 | US-3: Edit slide content | Verbal | Frontend | -| 4 | US-4: Add slides to existing presentation | Verbal | Frontend | -| 5 | US-5: Delete and reorder slides | Verbal | Frontend | -| 6 | US-6: List and manage presentations | Verbal | Frontend | -| 7 | US-8: AI slide generation API | McManus | Backend | -| 8 | US-7: Presentation CRUD API | McManus | Backend | -| 9 | US-9: Build verification and smoke tests | Fenster | Tester | - -The work decomposition naturally maps agents to their roles: Verbal handles all 6 frontend stories, McManus handles both backend APIs, Fenster handles the verification story. This role-based routing is exactly what the `squad:{agent-name}` label convention enables. - -### What this validates for 028 - -1. **Phase 1 (one-way push) is proven.** The PRD→Issues flow works today. Squad agents can create well-structured, labeled, agent-routed GitHub Issues from planning artifacts. -2. **The `squad:` label convention scales.** With 9 issues across 3 agents, filtering by `squad:verbal` instantly shows workload. This will work at 50+ issues. -3. **Agent metadata in issue bodies works.** Agents can read their assignment and file targets from the issue body — no external routing logic needed. -4. **User story format is the right template.** Consistent, testable, human-readable, agent-parseable. This should be the default issue template for squad-generated issues. - ---- - -## Implementation Layers - -### Phase 1: One-Way Push (High Value, Low Risk) - -**Scope:** When an agent creates a proposal or the coordinator captures a backlog item, also create a GitHub Issue. No pull-back, no reconciliation. - -**What ships:** -- Coordinator prompt addition: after writing a proposal file, create a GitHub Issue with the proposal title, body (first 200 lines), and labels (`proposal`, `squad`, `sprint:{version}`). -- After capturing a backlog item to `backlog.md`, create a GitHub Issue with labels (`squad`, `backlog`, `captured`). -- Agent-routed issues get `squad:{agent-name}` labels (e.g., `squad:verbal`, `squad:fenster`) matching the slidemaker convention. -- Issue bodies follow the validated user story format: "As a {persona}, I want {capability}, so that {benefit}" with checkbox acceptance criteria and agent metadata in Notes. -- When a proposal is approved or cancelled, close the corresponding issue with a comment noting the outcome. -- When an agent marks a backlog item done, close the corresponding issue. -- Issue numbers are stored as metadata in the markdown files (e.g., `**GitHub Issue:** #42`). - -**What doesn't ship:** -- No reading from GitHub. No pull-back. No reconciliation. -- No Project board (just issues and labels). -- Sync is best-effort — if the API call fails, log it and move on. - -**Dependencies:** `gh` CLI or GitHub MCP server (same as PR #2's GitHub Issues Mode). If neither is available, skip sync silently. - -**Effort estimate:** 3-4 hours (prompt engineering, no code changes to index.js) - -**Value:** Proposals and backlog items are immediately visible on GitHub. Brady can see them from his phone. Contributors can browse them. Discussion can happen in issue comments. This alone is transformative. - -### Phase 2: Comment Pull-Back - -**Scope:** On session start, read GitHub Issue comments on proposal and backlog issues. Inject them into agent context. - -**What ships:** -- Coordinator reads proposal issues with label `proposal` and checks for new comments since last sync timestamp. -- New comments are appended to the proposal file's `## Discussion` section (or a new `## GitHub Discussion` section if Discussion doesn't exist). -- New comments on backlog issues are included in the coordinator's context when the backlog item is relevant to the current work. -- A sync timestamp is stored in `.ai-team/github-sync-state.json` (last sync time per issue). - -**What doesn't ship:** -- No Project board sync. -- No priority reconciliation. -- No new issue detection (humans create issues on GitHub, but they don't flow into `backlog.md` yet). - -**Effort estimate:** 4-5 hours - -**Value:** Two-way conversation. Brady comments on a proposal issue; the agent sees that feedback next session. The proposal evolves through GitHub's collaboration UI. - -### Phase 3: GitHub Project Board + Full Reconciliation - -**Scope:** Create and maintain a GitHub Project board that mirrors the team backlog. Detect human-created issues and bring them into `backlog.md`. Full two-way sync. - -**What ships:** -- A GitHub Project named "Squad — {team-name}" is created (or connected) during init or on first sync. -- Board columns: Captured → Open → In Progress → Done (matching Proposal 023's lifecycle). -- Backlog items map to cards. Agents move cards as they work. -- Humans can drag cards to reprioritize. On session start, coordinator reads the board state and updates `backlog.md` ordering. -- New issues created by humans on GitHub (with label `backlog`) are detected and added to `backlog.md`. -- Sprint milestones created from sprint plan proposals. -- Conflict resolution: union merge — items in either source are preserved. Filesystem wins on status; GitHub wins on priority ordering and comments. - -**Effort estimate:** 8-12 hours - -**Value:** The full vision. The team's planning surface is GitHub. Agents update it as they work. Humans interact with it naturally. The backlog is a living board, not a static file. - -### Phase 4 (Aspirational): Cross-Repo Planning - -**Scope:** If Squad is used across multiple repositories, a single GitHub Project aggregates planning across all of them. - -**What ships:** -- Multi-repo Project board with repo-scoped columns or views. -- Backlog items tagged by repository. -- Cross-repo sprint milestones. - -**Effort estimate:** Unknown — depends on GitHub Projects API maturity for multi-repo scenarios. - -**Value:** For teams using Squad on a portfolio of projects, a single planning dashboard. This is far-future, but the architecture should not preclude it. - ---- - -## How This Fits v0.3.0 - -**Phase 1 is shipping in v0.3.0.** Brady overrode Keaton's recommendation to defer to Horizon. His directive: "go with 0.3.0. brady and shayne want this." - -Phase 1 (one-way push, 3-4h prompt engineering, no index.js changes) is added to v0.3.0 Wave 2 as item 5.9. It depends on backlog capture (4.5, 4.6) for backlog→Issue push; proposal→Issue push can start independently. - -v0.3.0 creates the preconditions: -- **Proposal 023 (backlog capture)** gives us the `backlog.md` that Phase 1 pushes to GitHub. -- **Proposal 024 (model selection)** is orthogonal but doesn't conflict. -- **PR #2 (GitHub Issues Mode)** gives us the `gh` CLI patterns that Phase 1 reuses. -- **Proposal 028a (Kujan's API assessment)** confirms all write tools are working via `gh` CLI. - -**Updated timing:** - -| Phase | Version | Rationale | -|-------|---------|-----------| -| Phase 1 (one-way push) | **v0.3.0** ✅ | Brady's directive — ships in Wave 2 as item 5.9 | -| Phase 2 (comment pull-back) | v0.4.0 | Needs Phase 1 proven first | -| Phase 3 (full Project board) | v0.5.0 or v1.0 | Significant complexity; needs Phase 1-2 proven | -| Phase 4 (cross-repo) | v1.0+ | Aspirational; not designed in detail yet | - -Phase 1 delivers 80% of the human-facing value: proposals and backlog items visible on GitHub, no branch checkout required, comments possible from a phone. The remaining phases build on that proven foundation. - ---- - -## Decision: Filesystem vs. GitHub as Source of Truth - -This is the architectural question Brady surfaced. Three options: - -### Option A: Filesystem authoritative, GitHub as view (RECOMMENDED) - -GitHub is a projection of filesystem state, enriched with comments and priority signals. Agents never read from GitHub to determine what to work on — they read files. GitHub adds a collaboration layer on top. - -**Pro:** Zero architectural change to Squad's core. Agents work the same way. Offline works. -**Con:** GitHub state can be stale. Human edits on GitHub require a sync cycle to reach agents. - -### Option B: GitHub authoritative, filesystem as cache - -GitHub Issues are the source of truth. `backlog.md` is generated from GitHub state on session start. Agents read the generated file. - -**Pro:** GitHub is the single source. No sync drift — one direction only. -**Con:** Requires internet on every session start. Breaks offline mode. Makes Squad dependent on GitHub API availability. Contradicts Proposal 023's "filesystem always wins." If GitHub is down, the team can't see its backlog. - -### Option C: True bidirectional sync (eventual consistency) - -Both sources are authoritative. A reconciliation algorithm merges changes from both sides. Conflicts are resolved by timestamp or by explicit rules. - -**Pro:** Maximum flexibility. -**Con:** Maximum complexity. Bidirectional sync is a product in itself (ask Notion, Obsidian, or any sync engine). Conflicts are inevitable. This is the wrong investment for a CLI tool. - -**Decision: Option A.** The filesystem is the database. GitHub is the dashboard. This preserves Squad's core simplicity while adding the collaboration surface Brady envisions. If we ever need Option C, the filesystem-first architecture makes migration possible. Option B burns the bridge. - ---- - -## Interaction with Existing Proposals - -| Proposal | Interaction | -|----------|-------------| -| **023 (Incoming Queue)** | Phase 1 depends on 023's backlog.md existing. GitHub sync extends 023's capture: extract → write to backlog.md → push to GitHub Issue. | -| **025 (PR #2 Review)** | Reuses the same `gh` CLI / MCP patterns. GitHub Issues Mode connects to external issues; this connects internal planning. Same tools, different direction. | -| **024 (Model Selection)** | Orthogonal. No interaction. | -| **027 (Sprint Plan)** | Not in v0.3.0 scope. Sprint plan items could become GitHub milestones in Phase 3. | -| **008 (Portable Squads)** | Export/import would need to handle `github-sync-state.json` — either export it (sync reconnects to same repo) or strip it (fresh start). Probably strip it. | - ---- - -## Alternatives Considered - -### A. Use GitHub Discussions instead of Issues - -**Why considered:** Discussions have threaded conversations, categories, and are designed for open-ended topics (like proposals). -**Why rejected:** Issues have labels, milestones, Project board integration, and API maturity that Discussions lack. Proposals need lifecycle tracking (draft → approved → shipped), which maps to issue state better than discussion state. Issues also integrate with PRs (`Closes #N`), which means proposal issues can be closed when the implementing PR merges. - -### B. Use a third-party project management tool (Linear, Notion, etc.) - -**Why considered:** More powerful project management features. -**Why rejected:** Adds a non-GitHub dependency. Squad is a GitHub-native tool — its users are on GitHub, its code is on GitHub, its distribution is GitHub-only. Adding Linear would be a strategic misalignment. GitHub Projects is "good enough" and zero-dependency for existing users. - -### C. Skip the filesystem entirely — go GitHub-only for planning - -**Why considered:** Simpler — no sync, no dual storage. -**Why rejected:** Breaks the core architectural principle. Agents read files. Offline mode matters. Git history is the audit trail. The filesystem is Squad's superpower — we extend it, not replace it. - -### D. Build a custom web UI for planning - -**Why considered:** Full control over the experience. -**Why rejected:** Not what we're building. Squad is a CLI tool with a filesystem brain. A web UI is a second product. GitHub already built the UI — we just need to push data to it. - ---- - -## Success Criteria - -### Phase 1 -1. Every proposal created by an agent also exists as a labeled GitHub Issue. -2. Every backlog item captured to `backlog.md` also exists as a labeled GitHub Issue. -3. Proposal/backlog status changes (approved, done, cancelled) are reflected as issue state changes. -4. If `gh` CLI / GitHub MCP is unavailable, Squad works identically to today — no errors, no degradation. -5. Issue number metadata is stored in the markdown file for traceability. - -### Phase 2 -6. Human comments on proposal issues appear in agent context on next session. -7. Comment sync is timestamped — no duplicate injection. -8. Agents can reference GitHub discussion in their responses: "Brady commented on #42: 'cut Phase 3.'" - -### Phase 3 -9. A GitHub Project board exists with columns matching the backlog lifecycle. -10. Agent work updates the board (items move from Open → In Progress → Done). -11. Human-created issues with appropriate labels appear in `backlog.md` on next session. -12. Priority changes on the board (drag-to-reorder) are reflected in `backlog.md` ordering. - ---- - -## Review Requested - -- **Brady:** Does this match the vision? Is Option A (filesystem authoritative) the right call, or do you want GitHub to own the data? -- **Verbal:** Prompt engineering assessment — how much coordinator instruction does Phase 1 require? Does it fit in the context budget? -- **Kujan:** Platform assessment — `gh` CLI vs. GitHub MCP for issue/project operations. Which is more reliable? Can we abstract over both? -- **Fenster:** Implementation review — `github-sync-state.json` design, metadata injection into markdown files. -- **Shayne (@spboyer):** You opened this door. How does this extend your GitHub Issues Mode? Where do you see overlap or conflict? - ---- - -**This is a "what could be" proposal. Brady asked us to use our imagination. Here's what we see: Squad's planning tools — proposals, backlog, sprint plans — living on GitHub where humans can see them, comment on them, and collaborate with their AI team in the open. The filesystem stays authoritative. GitHub becomes the window.** - -**Phase 1 is 3-4 hours of prompt engineering and delivers 80% of the value. Shipping in v0.3.0 Wave 2 — Brady's call.** diff --git a/team-docs/proposals/028a-github-api-capabilities.md b/team-docs/proposals/028a-github-api-capabilities.md deleted file mode 100644 index b1b26b23f..000000000 --- a/team-docs/proposals/028a-github-api-capabilities.md +++ /dev/null @@ -1,269 +0,0 @@ -# Proposal 028a: GitHub API Capabilities Assessment - -**Author:** Kujan (Copilot SDK Expert) -**Date:** 2026-02-10 -**Status:** Assessment (Research Complete) -**Context:** Brady wants proposals and the team backlog to live on GitHub (Issues + Projects), not just on disk. - ---- - -## Executive Summary - -Squad agents have **full GitHub Issues capability right now** via two channels: `gh` CLI and GitHub MCP Server tools. GitHub Projects is **blocked by a missing token scope** (`read:project` / `project`) but is fully functional once that scope is added. Sub-agents spawned via `task` tool with type `task` or `general-purpose` **can** access MCP tools; `explore` agents **cannot**. - ---- - -## 1. GitHub MCP Server Tools — Empirically Verified - -### Issue Read Operations ✅ ALL WORKING - -| Tool | Capability | Verified | -|------|-----------|----------| -| `github-mcp-server-list_issues` | List issues with state/label/pagination filters | ✅ | -| `github-mcp-server-issue_read` (method: `get`) | Get full issue details (state, labels, body, author, timestamps) | ✅ | -| `github-mcp-server-issue_read` (method: `get_comments`) | Get all comments on an issue | ✅ | -| `github-mcp-server-issue_read` (method: `get_labels`) | Get labels on an issue | ✅ | -| `github-mcp-server-issue_read` (method: `get_sub_issues`) | Get sub-issues (for task hierarchies) | ✅ available | -| `github-mcp-server-search_issues` | Search issues across repos with GitHub search syntax | ✅ | - -### Issue Write Operations — NOT AVAILABLE VIA MCP - -The GitHub MCP Server tools are **read-only for issues**. There are no MCP tools for: -- Creating issues -- Updating issues (title, body, state) -- Adding/removing labels -- Adding comments -- Assigning users - -**Write operations must use `gh` CLI or `gh api`.** - -### Search & Discovery ✅ - -| Tool | Capability | Verified | -|------|-----------|----------| -| `github-mcp-server-search_issues` | Full GitHub search syntax (`repo:`, `label:`, `is:open`, etc.) | ✅ | -| `github-mcp-server-search_pull_requests` | Search PRs with same syntax | ✅ | -| `github-mcp-server-search_code` | Code search across repos | ✅ | - -### PR Operations (for context) - -| Tool | Capability | -|------|-----------| -| `github-mcp-server-list_pull_requests` | List PRs with filters | -| `github-mcp-server-pull_request_read` | Get PR details, diff, files, reviews, comments, status | -| `github-mcp-server-search_pull_requests` | Search PRs | - -### Actions Operations (for context) - -| Tool | Capability | -|------|-----------| -| `github-mcp-server-actions_list` | List workflows, runs, jobs, artifacts | -| `github-mcp-server-actions_get` | Get specific workflow/run/job details | -| `github-mcp-server-get_job_logs` | Get job logs (including failed-only) | - -### Other MCP Tools - -| Tool | Capability | -|------|-----------| -| `github-mcp-server-get_file_contents` | Read files from GitHub (any branch/ref) | -| `github-mcp-server-get_commit` | Get commit details with diffs | -| `github-mcp-server-list_commits` | List commits on a branch | -| `github-mcp-server-list_branches` | List branches | - -### MCP Tools — NOT Available for Projects - -There are **zero** MCP tools for GitHub Projects (V2). No read, no write, nothing. Projects must be managed entirely via `gh` CLI or `gh api` GraphQL calls. - ---- - -## 2. `gh` CLI Capabilities — Empirically Verified - -### Issue Management ✅ FULL LIFECYCLE - -| Command | Capability | Verified | -|---------|-----------|----------| -| `gh issue create` | Create with title, body, labels, assignees, milestone, project, template | ✅ tested | -| `gh issue edit` | Update title, body, add/remove labels, add/remove assignees, milestone, project | ✅ tested | -| `gh issue close` | Close with reason (completed/not planned) and closing comment | ✅ tested | -| `gh issue comment` | Add comments, edit last comment | ✅ tested | -| `gh issue list` | List with state/label/assignee filters | ✅ tested | -| `gh issue view` | View issue details | ✅ available | -| `gh issue pin/unpin` | Pin issues to repo | ✅ available | -| `gh issue reopen` | Reopen closed issues | ✅ available | -| `gh issue transfer` | Transfer to another repo | ✅ available | -| `gh issue develop` | Create branch for issue | ✅ available | - -### Label Management ✅ - -| Command | Capability | Verified | -|---------|-----------|----------| -| `gh label list` | List all labels | ✅ tested | -| `gh label create` | Create with name, color, description; `--force` to update existing | ✅ available | -| `gh label edit` | Edit existing label | ✅ available | -| `gh label delete` | Delete label | ✅ available | - -### Project Management ⚠️ BLOCKED BY TOKEN SCOPE - -**Current token scopes:** `gist`, `read:org`, `repo`, `workflow` -**Missing scope:** `read:project` (for read), `project` (for write) - -All `gh project` commands exist and are functional, but **will fail until `gh auth refresh -s project` is run**. - -| Command | Capability | Blocked | -|---------|-----------|---------| -| `gh project create` | Create a new project board | ⚠️ needs `project` scope | -| `gh project list` | List projects | ⚠️ needs `read:project` scope | -| `gh project view` | View project details | ⚠️ needs `read:project` scope | -| `gh project edit` | Edit project settings | ⚠️ needs `project` scope | -| `gh project field-create` | Create custom fields (Status, Priority, Sprint, etc.) | ⚠️ needs `project` scope | -| `gh project field-list` | List fields in a project | ⚠️ needs `read:project` scope | -| `gh project field-delete` | Delete fields | ⚠️ needs `project` scope | -| `gh project item-add` | Add issue/PR to project | ⚠️ needs `project` scope | -| `gh project item-create` | Create draft issue in project | ⚠️ needs `project` scope | -| `gh project item-edit` | Update item field values (status, priority, etc.) | ⚠️ needs `project` scope | -| `gh project item-list` | List items in a project | ⚠️ needs `read:project` scope | -| `gh project item-archive` | Archive project items | ⚠️ needs `project` scope | -| `gh project item-delete` | Delete items from project | ⚠️ needs `project` scope | -| `gh project link/unlink` | Link project to repo/team | ⚠️ needs `project` scope | -| `gh project close/copy/delete` | Project lifecycle management | ⚠️ needs `project` scope | - -### GraphQL API Access ✅ - -| Command | Capability | Verified | -|---------|-----------|----------| -| `gh api` (REST) | Full REST API access | ✅ tested | -| `gh api graphql` | Full GraphQL API access | ✅ tested (blocked only by scope for projects) | - ---- - -## 3. Agent Tool Access Matrix — Empirically Verified - -| Agent Type | MCP Tools | `gh` CLI | `gh api` | Shell Commands | -|-----------|-----------|----------|----------|----------------| -| **Coordinator** (you) | ✅ Full access | ✅ via powershell | ✅ via powershell | ✅ | -| `task` sub-agent | ✅ **Full access** | ✅ | ✅ | ✅ | -| `general-purpose` sub-agent | ✅ Full access (expected — has "All CLI tools") | ✅ | ✅ | ✅ | -| `explore` sub-agent | ❌ **No MCP tools** | ❌ No shell | ❌ No shell | ❌ grep/glob/view only | -| `code-review` sub-agent | ❌ No MCP tools (expected) | ✅ CLI tools for investigation | ✅ | ✅ | - -**Key finding:** `task` and `general-purpose` agents CAN directly create/update GitHub Issues and Projects via `gh` CLI. They don't need the coordinator to mediate. This means agents can be given self-serve GitHub write access. - ---- - -## 4. What's Missing — Gaps Analysis - -### Gap 1: MCP Tools Are Read-Only for Issues -- No `github-mcp-server-create_issue` or `github-mcp-server-update_issue` exists -- **Workaround:** Use `gh` CLI for all write operations — works from coordinator, `task`, and `general-purpose` agents -- **Impact:** Low — `gh` CLI is equally capable and arguably more flexible - -### Gap 2: Zero MCP Tools for Projects -- No MCP tools exist for GitHub Projects V2 at all -- **Workaround:** `gh project *` commands cover 100% of project management needs -- **Impact:** Low — `gh` CLI is the correct tool for this - -### Gap 3: Token Missing `project` Scope -- **Current scopes:** `gist`, `read:org`, `repo`, `workflow` -- **Required addition:** `project` (includes read+write) -- **Fix:** Brady runs `gh auth refresh -s project` once -- **Impact:** HIGH — this is the **only blocker** preventing GitHub Projects integration - -### Gap 4: No MCP Tool for Issue Creation -- Must shell out to `gh issue create` for write operations -- Not a real gap — `gh` CLI provides better control (templates, body files, etc.) - -### Gap 5: Issue Deletion Not Possible -- GitHub API does not support deleting issues (by design) -- Issues can only be closed, locked, or transferred -- **Impact:** None — issues should be closed, not deleted - ---- - -## 5. Rate Limits — Empirically Verified - -**Current rate limit status at time of testing:** - -| Resource | Remaining | Limit | Reset Window | -|----------|-----------|-------|-------------| -| Core (REST API) | 4,998 | 5,000 | Per hour | -| Search API | 29 | 30 | Per minute | -| GraphQL API | 4,993 | 5,000 | Per hour | - -### Practical Assessment for Squad - -**Issue creation (proposals → issues):** Creating 30 proposals as issues would consume ~60 API calls (create + label each). At 5,000/hour, this is negligible (1.2%). - -**Backlog management (project board updates):** Moving items between columns, updating status fields — each operation is 1-2 API calls. Even a 50-item backlog with frequent updates would be well within limits. - -**Search operations:** The Search API limit (30/minute) is the tightest constraint. If multiple agents search simultaneously, they could exhaust this quickly. **Recommendation:** Cache search results and avoid redundant searches. - -**Multi-agent concern:** If 5 agents each make 10 API calls per operation, that's 50 calls. With 5,000/hour limit, you could run ~100 such operations per hour before hitting limits. Practically unlimited for normal workflow. - -**Real risk:** The Search API's 30/minute limit could be hit during batch operations (e.g., "find all issues with label X and update them"). Use list operations instead of search when possible. - ---- - -## 6. Recommended Architecture - -### For Proposals → Issues - -``` -Agent writes proposal.md → Agent runs `gh issue create` → Issue created with: - - Title from proposal - - Body from proposal markdown - - Labels: "proposal", "squad-generated" - - Milestone: sprint number (optional) -``` - -**Any `task` or `general-purpose` agent can do this directly.** No coordinator mediation needed. - -### For Team Backlog → GitHub Project - -``` -1. Brady runs: gh auth refresh -s project (one-time setup) -2. Agent creates project: gh project create --owner bradygaster --title "Squad Backlog" -3. Agent creates fields: gh project field-create (Status, Priority, Sprint, Agent) -4. Agent adds items: gh project item-add (link issues) or gh project item-create (drafts) -5. Agent updates status: gh project item-edit --field-id --single-select-option-id -``` - -### Two-Channel Pattern - -| Channel | Tool | Use Case | -|---------|------|----------| -| **Read** (query, search, get) | MCP tools preferred | Structured data, better for parsing | -| **Write** (create, update, close) | `gh` CLI | Only option — but fully capable | - ---- - -## 7. Prerequisites — Action Items for Brady - -1. **Run `gh auth refresh -s project`** — adds project scope to token. One-time, takes 10 seconds. -2. **Create custom labels** for squad use (following the `squad:` prefix convention validated by [spboyer/slidemaker](https://github.com/spboyer/slidemaker)): - - `squad` — base label for all squad-managed issues - - `squad:{agent-name}` — per-agent routing (e.g., `squad:verbal`, `squad:mcmanus`, `squad:fenster`) - - `proposal` — for proposal issues - - `backlog` — for backlog items - - `sprint-N` — for sprint tracking -3. **Create the GitHub Project board** (or let an agent do it after scope is added) - ---- - -## Appendix: Full Test Log - -All findings in this document were empirically verified in a live session on 2026-02-10: - -1. ✅ `github-mcp-server-list_issues` — returned 0 issues (correct, repo was empty) -2. ✅ `github-mcp-server-search_issues` — searched successfully -3. ✅ `gh issue create` — created issue #3 as test -4. ✅ `gh issue edit --add-label` — added "enhancement" label -5. ✅ `gh issue comment` — added comment to issue -6. ✅ `gh issue close --reason "not planned"` — closed with reason -7. ✅ `github-mcp-server-issue_read` (get) — read full issue details via MCP -8. ✅ `github-mcp-server-issue_read` (get_comments) — read comments via MCP -9. ✅ `github-mcp-server-issue_read` (get_labels) — read labels via MCP -10. ✅ `gh api rate_limit` — confirmed rate limits -11. ✅ `gh api graphql` — confirmed GraphQL works (blocked for projects by scope only) -12. ✅ `task` sub-agent MCP access — confirmed `task` agents have full MCP tool access -13. ❌ `explore` sub-agent MCP access — confirmed `explore` agents have NO MCP tools -14. ⚠️ `gh project list` — failed due to missing `read:project` scope diff --git a/team-docs/proposals/029-marketing-site.md b/team-docs/proposals/029-marketing-site.md deleted file mode 100644 index 186ed6205..000000000 --- a/team-docs/proposals/029-marketing-site.md +++ /dev/null @@ -1,319 +0,0 @@ -# Proposal 029: Marketing Site — Jekyll on GitHub Pages - -**Status:** Draft -**Author:** Keaton (Lead) -**Requested by:** bradygaster -**Date:** 2026-02-10 -**Domain:** Infrastructure, Marketing, Documentation - ---- - -## Problem - -Squad has extensive, well-structured documentation in `docs/` — guide, features, scenarios, tours, sample prompts. It's all markdown. It's all public. It ships to users via `package.json` `files`. But it renders as raw markdown on GitHub. There's no HTML site. No marketing presence. No landing page a developer can send to their manager. - -Brady wants a marketing site. His priorities, in order: - -1. **No content reproduction.** One source of truth. -2. **HTML output.** Docs rendered as a real website. - -The worst outcome is two copies of the same content — a `docs/` directory AND a `site/` directory with the same words in different formats. - ---- - -## Decision: Jekyll on GitHub Pages - -**This is the only correct answer** for this project. Here's why: - -### Why Jekyll - -- **GitHub Pages runs Jekyll natively.** Zero build config, zero CI setup, zero Docker containers. Push markdown, get HTML. The simplest possible deployment. -- **Jekyll renders markdown files in-place.** You don't copy files to a build directory. You add YAML front matter to existing `.md` files and Jekyll renders them as HTML where they sit. The `docs/` directory IS the site source. -- **The docs already exist.** We have 20+ markdown files across `docs/`, `docs/features/`, `docs/scenarios/`. Jekyll consumes them directly. No migration, no transformation, no second copy. -- **GitHub Pages is free.** No hosting costs, no CDN configuration, no SSL certificates to manage. -- **It's what Brady asked for.** "GitHub Pages or Jekyll" — they're the same thing in this context. - -### Why not other options - -| Alternative | Why not | -|------------|---------| -| **Next.js / Docusaurus / VitePress** | Requires a build step, a `package.json` for the site, a separate `src/` or `pages/` directory. Content reproduction is inevitable. Over-engineered for a docs site. | -| **Hugo** | Not natively supported by GitHub Pages. Requires a CI action to build. Adds a dependency we don't need. | -| **Raw HTML** | Manual maintenance nightmare. Defeats the purpose of having markdown docs. | -| **GitHub Wiki** | Can't be themed. Can't be a marketing landing page. Separate from the repo. | -| **Separate repo for the site** | Content reproduction by definition. Two places to update. Guaranteed drift. | - ---- - -## No-Reproduction Strategy - -This is the core architectural constraint. Every decision flows from it. - -### The `docs/` directory IS the Jekyll source - -Jekyll doesn't need a separate project structure. It needs: - -1. A `_config.yml` at the source root -2. YAML front matter (`---` blocks) on files it should render -3. Optionally, `_layouts/` and `_includes/` for theming - -**The `docs/` folder becomes the Jekyll source root.** GitHub Pages is configured to serve from `docs/` on main. Jekyll processes every `.md` file in `docs/` that has front matter and renders it as HTML. Files without front matter are served as-is. - -### What this means concretely - -``` -docs/ -├── _config.yml ← NEW: Jekyll configuration -├── _layouts/ -│ └── default.html ← NEW: Base HTML layout -│ └── page.html ← NEW: Content page layout -├── _includes/ -│ └── nav.html ← NEW: Navigation partial -├── assets/ -│ └── css/ -│ └── style.css ← NEW: Minimal styling -├── index.md ← NEW: Landing page (replaces README.md as site root) -├── README.md ← MODIFIED: Add front matter (permalink: /about/) -├── guide.md ← MODIFIED: Add front matter only -├── sample-prompts.md ← MODIFIED: Add front matter only -├── tour-first-session.md ← MODIFIED: Add front matter only -├── tour-github-issues.md ← MODIFIED: Add front matter only -├── features/ -│ ├── *.md ← MODIFIED: Add front matter only -├── scenarios/ -│ ├── *.md ← MODIFIED: Add front matter only -``` - -### What "add front matter" means - -Every existing `.md` file gets a 3-5 line YAML block prepended. Example for `guide.md`: - -```yaml ---- -layout: page -title: "Product Guide" -description: "Complete reference for all Squad features" -nav_order: 1 ---- -# Squad — Product Guide -...existing content unchanged... -``` - -That's it. The content below the front matter is untouched. Jekyll reads the YAML, applies the layout, and renders the markdown as HTML inside the layout template. **Zero content duplication.** - -### The index.md question - -`docs/README.md` currently serves as the documentation index on GitHub (GitHub renders `README.md` automatically in directory views). For Jekyll, we need an `index.md` (or the README needs `permalink: /`). Two options: - -**Option A (recommended): Create `docs/index.md` as a landing page.** This is new content — a marketing-oriented landing page with hero section, value props, and links to docs. `README.md` keeps its current role as the GitHub directory index. `index.md` becomes the site homepage. Minimal reproduction because the landing page content is marketing copy, not documentation. - -**Option B: Add front matter to README.md with `permalink: /`.** README serves double duty as GitHub index and site homepage. Simpler but constrains the homepage to be documentation-structured rather than marketing-structured. - -**I'm going with Option A.** The landing page and the docs index serve different audiences. A developer browsing the GitHub repo needs a file listing. A developer hitting the website needs "what is this and why should I care?" in 10 seconds. These are different content with different structures. - ---- - -## Changes to Existing Files - -### Files that need front matter added - -Every `.md` file in `docs/` gets front matter prepended. This is a mechanical change — no content modifications. - -| File | `title` | `nav_order` | -|------|---------|-------------| -| `docs/README.md` | Documentation | 0 | -| `docs/guide.md` | Product Guide | 1 | -| `docs/sample-prompts.md` | Sample Prompts | 2 | -| `docs/tour-first-session.md` | First Session | 10 | -| `docs/tour-github-issues.md` | GitHub Issues Tour | 11 | -| `docs/features/*.md` (8 files) | Per-feature titles | 20-28 | -| `docs/scenarios/*.md` (5 files) | Per-scenario titles | 30-35 | - -### New files - -| File | Purpose | -|------|---------| -| `docs/_config.yml` | Jekyll configuration | -| `docs/index.md` | Marketing landing page | -| `docs/_layouts/default.html` | Base HTML shell | -| `docs/_layouts/page.html` | Content page template | -| `docs/_includes/nav.html` | Navigation sidebar/menu | -| `docs/assets/css/style.css` | Minimal styling | - -### Files NOT changed - -- `team-docs/` — internal, never on the site -- `.ai-team/` — runtime state, never on the site -- `README.md` (root) — repo README, separate from docs site -- `index.js`, `package.json`, `templates/` — product code, untouched - ---- - -## GitHub Pages Configuration - -### Repository settings - -- **Source:** Deploy from branch -- **Branch:** `main` -- **Folder:** `/docs` - -This is configured in the GitHub UI under Settings → Pages. No GitHub Actions workflow needed for Phase 1 — GitHub Pages builds Jekyll natively when configured this way. - -### `docs/_config.yml` - -```yaml -title: Squad -description: AI agent teams that grow with your code -url: https://bradygaster.github.io -baseurl: /squad - -# Theme — use a minimal theme or no theme (custom layouts) -# Option 1: GitHub's built-in minimal theme -# remote_theme: pages-themes/minimal@v0.2.0 -# Option 2: Custom layouts only (recommended for control) -plugins: - - jekyll-seo-tag - -# Markdown rendering -markdown: kramdown -kramdown: - input: GFM - -# Exclude internal files that happen to be in docs/ -exclude: - - README.md # GitHub directory index, not a site page - -# Collections or defaults for front matter -defaults: - - scope: - path: "features" - values: - layout: page - category: features - - scope: - path: "scenarios" - values: - layout: page - category: scenarios - - scope: - path: "" - values: - layout: page -``` - -### Why no GitHub Actions deploy workflow - -GitHub Pages has two modes: - -1. **Classic:** Jekyll build from a branch/folder. Zero config. Push and it deploys. -2. **Actions:** Custom build pipeline. Needed for non-Jekyll SSGs. - -We're using Jekyll. Classic mode is correct. Adding an Actions workflow is unnecessary complexity. If we later need custom build steps (e.g., for a non-Jekyll plugin), we can add it then. - ---- - -## Content Strategy - -### What goes on the site - -Everything in `docs/` — this is the public-facing documentation that already ships to users: - -- **Landing page** (`index.md`) — marketing-oriented: what is Squad, why it matters, install command, link to guide -- **Product guide** (`guide.md`) — the complete reference -- **Feature pages** (`features/*.md`) — individual feature deep-dives -- **Scenario walkthroughs** (`scenarios/*.md`) — task-oriented guides -- **Tours** (`tour-*.md`) — step-by-step first experiences -- **Sample prompts** (`sample-prompts.md`) — copy-paste ready demos - -### What stays internal (never on the site) - -- `team-docs/` — proposals, sprint plans, blog drafts, release process -- `.ai-team/` — agent state, charters, histories, decisions, skills -- Root `README.md` — repo-level README (distinct from docs site homepage) - -### What about the blog? - -`team-docs/blog/` has draft blog posts. These are internal drafts today. If Brady wants a blog on the site, that's a Phase 2 decision. The architecture supports it — add a `docs/_posts/` directory and Jekyll renders a blog automatically. But Phase 1 doesn't touch blogs. - ---- - -## Phase 1 Scope: Minimal Viable Site - -**Goal:** Get `docs/` rendering as an HTML site on GitHub Pages with navigation and minimal styling. No new content except the landing page. - -### Phase 1 deliverables - -1. **`docs/_config.yml`** — Jekyll configuration pointing at custom layouts -2. **`docs/index.md`** — Landing page with hero, install command, value props, links to guide -3. **`docs/_layouts/default.html`** — Base HTML: head, nav, content area, footer -4. **`docs/_layouts/page.html`** — Content page inheriting from default -5. **`docs/_includes/nav.html`** — Navigation listing all docs pages -6. **`docs/assets/css/style.css`** — Clean, minimal CSS. No framework. Mobile-friendly. -7. **Front matter on all 16 existing `.md` files** — layout, title, nav_order -8. **GitHub Pages enabled** in repo settings (manual step by Brady) - -### Phase 1 does NOT include - -- Custom domain (e.g., `squad.dev`) — Phase 2 -- Blog / changelog page — Phase 2 -- Search — Phase 2 -- Analytics — Phase 2 -- Custom Jekyll theme — Phase 2 (start with custom layouts, theme later if needed) -- `team-docs/` content on the site — never - -### Estimated effort - -- **Front matter additions:** 30 minutes (mechanical, could be scripted) -- **`_config.yml` + layouts + includes:** 2-3 hours -- **Landing page (`index.md`):** 1-2 hours (McManus territory — marketing copy) -- **CSS:** 1-2 hours -- **Testing locally with `jekyll serve`:** 30 minutes -- **GitHub Pages enable:** 5 minutes (Brady in repo settings) - -**Total: 5-8 hours.** This is a McManus + Fenster job. McManus writes the landing page and CSS direction. Fenster handles the Jekyll infrastructure. I review. - ---- - -## Trade-offs - -| Decision | Upside | Downside | -|----------|--------|----------| -| `docs/` as Jekyll source (no separate site dir) | Zero content reproduction | Jekyll files (`_config.yml`, `_layouts/`) live in `docs/`, which ships to npm users | -| Front matter on existing files | Jekyll renders them as HTML | Slight visual noise in raw markdown on GitHub (front matter is hidden by GitHub's renderer, so actually no downside) | -| Custom layouts over a theme | Full control over design | More upfront work than `remote_theme` | -| No Actions workflow | Simpler, fewer moving parts | Can't use Jekyll plugins not on GitHub's allowlist | -| Landing page separate from README | Marketing-optimized homepage | One more file to maintain | - -### The npm shipping question - -`docs/` is in `package.json` `files` — it ships to users. Jekyll infrastructure files (`_config.yml`, `_layouts/`, `_includes/`) will also ship. This is harmless — they're small files that don't affect functionality — but it's worth noting. If it bothers anyone, we can add them to `.npmignore`. But I'd rather not add exclusion rules for files that cause no harm. - ---- - -## Success Criteria - -1. `https://bradygaster.github.io/squad/` renders a styled landing page -2. All 16 existing docs pages render as HTML with navigation -3. Zero content is duplicated — every word lives in exactly one `.md` file -4. Adding a new doc page requires: create `.md` file, add front matter, commit. Nothing else. -5. `docs/README.md` still renders correctly when browsing `docs/` on GitHub - ---- - -## Alternatives Considered - -1. **Docusaurus** — React-based, great docs sites, but requires `npm run build`, a `docusaurus.config.js`, and a `docs/` → `build/` pipeline. Content reproduction by design. -2. **VitePress** — Vue-based, fast, beautiful. Same problem: separate build output, `.vitepress/` directory, content transformation pipeline. -3. **Astro** — Modern, flexible. Massive overkill for a docs site. Build step required. -4. **GitHub's built-in markdown rendering** — What we have today. No navigation, no theming, no landing page, no SEO. -5. **Separate `site/` directory** — Jekyll source in `site/`, importing from `docs/` via symlinks or includes. Adds complexity, fragile on Windows, and violates the "no reproduction" constraint even if technically it's linking rather than copying. - -All rejected. Jekyll-in-`docs/` is the only architecture that satisfies both constraints simultaneously. - ---- - -## Recommendation - -**Approve and assign to McManus (content/design direction) + Fenster (Jekyll infrastructure).** Phase 1 is 5-8 hours of work with zero risk to the product codebase. No `index.js` changes. No new dependencies. The only code-adjacent change is adding YAML front matter to existing markdown files, which GitHub's renderer hides anyway. - -Brady enables GitHub Pages in repo settings after the PR merges. That's it. diff --git a/team-docs/proposals/029a-marketing-site-content.md b/team-docs/proposals/029a-marketing-site-content.md deleted file mode 100644 index 3bc722e30..000000000 --- a/team-docs/proposals/029a-marketing-site-content.md +++ /dev/null @@ -1,371 +0,0 @@ -# Proposal 029a: Marketing Site Content Plan - -**Author:** McManus (DevRel) -**Date:** 2026-02-10 -**Status:** Proposed - ---- - -## Summary - -Content plan for the Squad marketing site. Built on Jekyll / GitHub Pages. Two priorities in order: (1) no content reproduction — docs live in one place and render on the site, (2) content lives in HTML format via Jekyll's markdown-to-HTML pipeline. - ---- - -## 1. Site Structure / Information Architecture - -``` -squad.dev (or GitHub Pages) -├── / → Landing page (hero, install, what Squad is) -├── /docs/ → Docs hub (maps to docs/README.md) -│ ├── /docs/guide/ → Product Guide (docs/guide.md) -│ ├── /docs/sample-prompts/ → Sample Prompts (docs/sample-prompts.md) -│ ├── /docs/features/ → Feature reference -│ │ ├── ceremonies/ → docs/features/ceremonies.md -│ │ ├── export-import/ → docs/features/export-import.md -│ │ ├── github-issues/ → docs/features/github-issues.md -│ │ ├── human-team-members/→ docs/features/human-team-members.md -│ │ ├── memory/ → docs/features/memory.md -│ │ ├── prd-mode/ → docs/features/prd-mode.md -│ │ ├── response-modes/ → docs/features/response-modes.md -│ │ └── skills/ → docs/features/skills.md -│ ├── /docs/walkthroughs/ → Guided tours -│ │ ├── first-session/ → docs/tour-first-session.md -│ │ └── github-issues/ → docs/tour-github-issues.md -│ └── /docs/scenarios/ → Use-case scenarios -│ ├── new-project/ → docs/scenarios/new-project.md -│ ├── existing-repo/ → docs/scenarios/existing-repo.md -│ ├── upgrading/ → docs/scenarios/upgrading.md -│ ├── team-portability/ → docs/scenarios/team-portability.md -│ └── issue-driven-dev/ → docs/scenarios/issue-driven-dev.md -├── /blog/ → Blog (published posts from team-docs/blog/) -└── /getting-started/ → Redirect or alias to /docs/walkthroughs/first-session/ -``` - -### Why this structure - -- **`/docs/` mirrors the `docs/` directory exactly.** No reproduction. Jekyll reads the markdown files in place. Front matter is the only addition needed — and it's added to the source files, not duplicated elsewhere. -- **`/blog/` pulls from `team-docs/blog/`** but only posts with `status: published`. Draft posts stay invisible. -- **`/getting-started/` is an alias**, not a separate page. It points to the first-session walkthrough because that's the content a new developer needs. -- **No `/about/` page.** The landing page covers what Squad is. A separate about page would reproduce README content. - ---- - -## 2. Content Audit - -Every file in `docs/` reviewed and categorized. - -### Ready for the site as-is (just needs Jekyll front matter) - -| File | Site path | Notes | -|------|-----------|-------| -| `docs/README.md` | `/docs/` | Doc hub / index. Clean, well-structured. Add `layout: docs`, `title`, `permalink`. | -| `docs/guide.md` | `/docs/guide/` | Complete product guide. 440+ lines, covers every feature. Production-ready. | -| `docs/tour-first-session.md` | `/docs/walkthroughs/first-session/` | Step-by-step walkthrough. Clean terminal examples. Ready. | -| `docs/tour-github-issues.md` | `/docs/walkthroughs/github-issues/` | Full issue workflow tour. Ready. | -| `docs/features/ceremonies.md` | `/docs/features/ceremonies/` | Ready. | -| `docs/features/export-import.md` | `/docs/features/export-import/` | Ready. | -| `docs/features/github-issues.md` | `/docs/features/github-issues/` | Ready. | -| `docs/features/human-team-members.md` | `/docs/features/human-team-members/` | Ready. | -| `docs/features/memory.md` | `/docs/features/memory/` | Ready. | -| `docs/features/prd-mode.md` | `/docs/features/prd-mode/` | Ready. | -| `docs/features/response-modes.md` | `/docs/features/response-modes/` | Ready. | -| `docs/features/skills.md` | `/docs/features/skills/` | Ready. | -| `docs/scenarios/new-project.md` | `/docs/scenarios/new-project/` | Ready. | -| `docs/scenarios/existing-repo.md` | `/docs/scenarios/existing-repo/` | Ready. | -| `docs/scenarios/upgrading.md` | `/docs/scenarios/upgrading/` | Ready. | -| `docs/scenarios/team-portability.md` | `/docs/scenarios/team-portability/` | Ready. | -| `docs/scenarios/issue-driven-dev.md` | `/docs/scenarios/issue-driven-dev/` | Ready. | - -### Needs editing before going public - -| File | Issue | Action needed | -|------|-------|---------------| -| `docs/sample-prompts.md` | File is 40KB+. Large for a single page. | Consider splitting into categories (Quick Builds, Full Projects, Feature Showcases) with a hub page linking to each. Or keep as one long page with a sticky table of contents. Either works — splitting is lower priority. | - -### Not site content (internal only) - -| File | Reason | -|------|--------| -| `docs/assets/` | Empty directory. Not content. | - -**Summary: 17 of 18 docs files are ready for the site as-is. One needs a formatting decision (sample-prompts.md). Zero files need substantive rewrites.** - -The docs are in good shape. Brady and the team wrote public-facing content from the start. The three-tier separation (docs = public, team-docs = internal, .ai-team = runtime) paid off — everything in `docs/` was always intended for users. - ---- - -## 3. Landing Page Copy - -### Hero Section - -``` -Squad - -AI agent teams for any project. - -Describe what you're building. Get a team of specialists that live in -your repo, persist across sessions, and get better the more you use them. - -npx github:bradygaster/squad -``` - -### Below the fold — three columns - -``` -┌─────────────────────┬──────────────────────┬──────────────────────┐ -│ Parallel agents │ Persistent memory │ Git-native │ -│ │ │ │ -│ Say "team, build │ Agents write what │ .ai-team/ commits │ -│ the login page." │ they learn to │ with your code. │ -│ Frontend, backend, │ history.md. After │ Clone the repo, │ -│ tester — all │ a few sessions, │ get the team. │ -│ launched at once, │ they know your │ Anyone who joins │ -│ each in its own │ conventions and │ inherits the │ -│ context window. │ stop asking. │ team's knowledge. │ -└─────────────────────┴──────────────────────┴──────────────────────┘ -``` - -### Quick start block (visible without scrolling on desktop) - -``` -1. Install - npx github:bradygaster/squad - -2. Open Copilot and tell it what you're building - "I'm starting a recipe app with React and Node. Set up the team." - -3. Your team forms and gets to work -``` - -### What it is — one paragraph - -``` -Squad gives you an AI development team through GitHub Copilot. -Each team member runs in its own context window with its own memory. -They share decisions, learn your codebase, and work in parallel. -The team persists as files in your repo — committable, cloneable, -portable. -``` - -### Requirements footer - -``` -Requires Node.js 22+ and GitHub Copilot CLI. Experimental. -``` - -**No taglines, no adjectives, no promises.** Every sentence states a fact about what the software does. This matches the "straight facts" directive. - ---- - -## 4. Navigation Design - -### Top nav (persistent across all pages) - -``` -[Squad] Docs Features Blog GitHub -``` - -- **Squad** — home link (logo/wordmark) -- **Docs** — links to `/docs/` hub -- **Features** — links to `/docs/features/` (or a dedicated features index) -- **Blog** — links to `/blog/` -- **GitHub** — external link to `github.com/bradygaster/squad` - -### Docs sidebar (visible on all `/docs/*` pages) - -``` -Getting Started - First Session - New Project - Existing Repo - -Guide - Product Guide - Sample Prompts - -Features - Ceremonies - Export & Import - GitHub Issues - Human Team Members - Memory System - PRD Mode - Response Modes - Skills System - -Scenarios - New Project - Existing Repo - Upgrading - Team Portability - Issue-Driven Dev - -Walkthroughs - First Session - GitHub Issues -``` - -### How a developer navigates - -1. **Lands on `/`** → sees what Squad is, the install command, and the three value pillars (parallel agents, persistent memory, git-native). -2. **Clicks "Docs"** → sees the doc hub with categorized links. Picks what they need. -3. **Clicks "Getting Started"** (or `/getting-started/`) → first-session walkthrough. This is the golden path. -4. **Clicks a feature** → standalone feature page with usage, examples, and CLI commands. -5. **Clicks "Blog"** → chronological list of published posts. -6. **From any docs page**, the sidebar provides full navigation without going back to the hub. - -### Mobile nav - -Hamburger menu. Same hierarchy, collapsed. Sidebar becomes a slide-out drawer on docs pages. - ---- - -## 5. Blog Integration - -### Source - -Blog posts live in `team-docs/blog/`. Each post has YAML front matter with a `status` field. - -### Filtering - -Only posts with `status: published` appear on the site. Posts with `status: draft` are excluded. - -### Current blog inventory - -| File | Title | Status | Site? | -|------|-------|--------|-------| -| `001-wave-0-the-team-that-built-itself.md` | Wave 0: The Team That Built Itself | published | ✅ | -| `001a-the-squad-squad-problem.md` | The Squad Squad Problem | published | ✅ | -| `001b-meet-the-squad.md` | Meet the Squad | published | ✅ | -| `001c-first-pr-amolchanov.md` | PR #1: Worktree Awareness... | published | ✅ | -| `002-first-community-pr.md` | First Community PR | published | ✅ | -| `003-super-bowl-weekend.md` | Super Bowl Weekend Sprint | **draft** | ❌ | -| `004-v020-release.md` | v0.2.0: Your Squad Comes With You | published | ✅ | -| `005-v030-give-it-a-brain.md` | v0.3.0 Preview: Give It a Brain | **draft** | ❌ | -| `template.md` | (template) | N/A | ❌ | - -**6 published posts ready for the site. 2 drafts excluded. Template excluded.** - -### Jekyll implementation - -Blog posts need to be in a `_posts/` directory (Jekyll convention) or a custom collection. Two approaches: - -**Option A: Symlink / copy at build time.** A Jekyll plugin or build script reads `team-docs/blog/`, filters by `status: published`, and copies qualifying posts to `_posts/`. This keeps the source of truth in `team-docs/blog/` and avoids reproduction. - -**Option B: Jekyll collection pointing at `team-docs/blog/`.** Define a custom collection in `_config.yml`: - -```yaml -collections: - blog: - output: true - permalink: /blog/:title/ -collections_dir: team-docs -``` - -This tells Jekyll to read from `team-docs/blog/` directly. The `status` field is used in the template to filter drafts: - -```liquid -{% for post in site.blog %} - {% if post.status == "published" %} - - {% endif %} -{% endfor %} -``` - -**Recommendation: Option B.** No reproduction. No build scripts. Jekyll reads the files where they already live. The `status` field already exists in every post's front matter. - -### Blog page layout - -- `/blog/` — reverse-chronological list with title, date, hero sentence, and author -- `/blog/{slug}/` — full post - ---- - -## 6. What's NOT on the Site - -Explicitly excluded from the marketing site: - -| What | Where it lives | Why it's excluded | -|------|---------------|-------------------| -| `team-docs/proposals/` | Internal proposals | Internal planning documents. Not user-facing. | -| `team-docs/demo-script.md` | Internal | Production script, not a published artifact. | -| `team-docs/human-evals/` | Internal | Evaluation criteria for internal use. | -| `team-docs/release-process.md` | Internal | Team workflow documentation. | -| `team-docs/README.md` | Internal | Internal directory index. | -| `team-docs/blog/template.md` | Internal | Blog post template for authors. | -| `team-docs/blog/*` with `status: draft` | Internal | Unpublished drafts. | -| `.ai-team/` | Runtime state | Agent charters, histories, decisions, logs. Never public, never in git on main. | -| `test/` | Source code | Test suite. Not documentation. | -| Sprint plans, roadmaps | Internal proposals | Planning artifacts, not user content. | - -**Rule: if it's in `team-docs/` or `.ai-team/`, it's not on the site — with the sole exception of published blog posts.** - ---- - -## 7. Implementation Notes - -### Jekyll setup - -``` -_config.yml → Site config, collections, nav -_layouts/ - default.html → Base layout (nav, footer) - docs.html → Docs layout (sidebar + content) - post.html → Blog post layout - home.html → Landing page layout -_includes/ - nav.html → Top navigation - sidebar.html → Docs sidebar - hero.html → Landing page hero section -``` - -### Front matter additions - -Each `docs/*.md` file needs front matter added. Example for `docs/guide.md`: - -```yaml ---- -layout: docs -title: Product Guide -description: Complete reference for all Squad features. -permalink: /docs/guide/ -nav_order: 1 ---- -``` - -This is a one-time, non-destructive change. The markdown content stays identical. The front matter tells Jekyll how to render it. - -### No content reproduction checklist - -- [ ] Docs render from `docs/` directory — not copied elsewhere -- [ ] Blog renders from `team-docs/blog/` via Jekyll collection — not copied -- [ ] Landing page is a standalone layout, not a copy of README.md -- [ ] README.md is NOT rendered on the site (it serves GitHub; the landing page serves the web) -- [ ] Feature pages are the `docs/features/*.md` files, not rewrites - -### What the landing page is NOT - -The landing page is not a copy of README.md. The README serves GitHub visitors (badge-aware, assumes they're already on the repo). The landing page serves web visitors (no GitHub context, needs to explain the product from zero). They share the same facts but not the same structure or audience. - ---- - -## 8. Priority Order for Implementation - -1. **Jekyll scaffolding** — `_config.yml`, layouts, includes. The skeleton. -2. **Front matter on docs files** — Add YAML front matter to all 18 docs files. Non-destructive. -3. **Landing page** — `index.html` or `index.md` with the hero section from §3. -4. **Blog collection** — Wire up `team-docs/blog/` as a Jekyll collection. -5. **Navigation** — Top nav + docs sidebar. -6. **Styling** — CSS. Minimal. Readable. Dark option preferred (matches terminal aesthetic). -7. **Deploy** — GitHub Pages from the `main` branch (or a `gh-pages` branch if main is filtered). - ---- - -## Open Questions - -1. **Domain:** `squad.dev`? GitHub Pages default (`bradygaster.github.io/squad`)? Custom domain later? -2. **Theme:** Start with a minimal Jekyll theme (e.g., `just-the-docs`) or build custom? `just-the-docs` handles the sidebar, search, and mobile nav out of the box. -3. **Mermaid diagrams:** The README and guide use Mermaid. Jekyll needs a Mermaid JS include to render them. Add `