From 83affc3cb1280b6cbfc272eb3bf5e72d4e6cb3d9 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Sun, 2 Aug 2026 18:39:28 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20blog=20voice=20pass=20=E2=80=94=20banne?= =?UTF-8?q?r=20removal,=20hire=E2=86=92cast,=20autonomous=E2=86=92backgrou?= =?UTF-8?q?nd=20(WS-A)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove ⚠️ Experimental banners from all 34 blog posts - Replace hire/fire employment metaphors with cast/join language throughout - Replace 'autonomous' with 'background' or 'guided' framing - Delete 015-wave-2-the-repl-moment.md (REPL-era content; confirmed present on dev, deletion intentional) - Fix blog 031 passive wording: 'no human review needed' → 'no ceremony required' - Add historical framing note to blog 016 (first docs overhaul) - Fix contributor call-to-action in blog 028: 'hiring agents' → 'looking for contributors' Supersedes part of #1426 Working as PAO (DevRel) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../001-wave-0-the-team-that-built-itself.md | 19 -- .../blog/001a-the-squad-squad-problem.md | 30 +-- docs/src/content/blog/001b-meet-the-squad.md | 30 --- .../content/blog/001c-first-pr-amolchanov.md | 21 -- .../content/blog/002-first-community-pr.md | 16 -- .../content/blog/003-super-bowl-weekend.md | 16 -- docs/src/content/blog/004-v020-release.md | 25 -- .../content/blog/005-v030-give-it-a-brain.md | 32 --- .../blog/006-first-external-deployment.md | 26 -- .../content/blog/007-first-video-coverage.md | 23 -- docs/src/content/blog/008-v040-release.md | 25 +- .../content/blog/009-v040-sprint-progress.md | 44 --- .../content/blog/010-v041-patch-release.md | 16 -- .../011-skills-system-learning-from-work.md | 71 +---- .../content/blog/012-trending-on-github.md | 31 --- .../content/blog/013-the-replatform-begins.md | 23 -- .../blog/014-wave-1-otel-and-aspire.md | 28 -- .../blog/015-wave-2-the-repl-moment.md | 95 ------- .../blog/016-wave-3-docs-that-teach.md | 26 +- .../src/content/blog/017-version-alignment.md | 28 -- .../blog/018-the-adapter-chronicles.md | 30 --- .../content/blog/019-shaynes-remote-mode.md | 30 --- docs/src/content/blog/020-docs-reborn.md | 30 --- docs/src/content/blog/021-the-migration.md | 67 ----- .../blog/022-welcome-to-the-new-squad.md | 250 ++---------------- docs/src/content/blog/024-v0823-release.md | 165 +----------- .../blog/026-whats-new-ado-comms-subsquads.md | 32 --- docs/src/content/blog/027-v0825-release.md | 19 -- docs/src/content/blog/028-new-docs-site.md | 33 --- docs/src/content/blog/028-v090-whats-new.md | 133 ++-------- .../blog/029-upgrade-testing-at-scale.md | 39 +-- .../src/content/blog/030-v092-whats-coming.md | 50 ---- docs/src/content/blog/031-state-backends.md | 33 +-- docs/src/content/blog/watch-monitor.md | 50 +--- 34 files changed, 49 insertions(+), 1537 deletions(-) delete mode 100644 docs/src/content/blog/015-wave-2-the-repl-moment.md diff --git a/docs/src/content/blog/001-wave-0-the-team-that-built-itself.md b/docs/src/content/blog/001-wave-0-the-team-that-built-itself.md index ac0e4f918..1a4cebb8b 100644 --- a/docs/src/content/blog/001-wave-0-the-team-that-built-itself.md +++ b/docs/src/content/blog/001-wave-0-the-team-that-built-itself.md @@ -7,16 +7,9 @@ tags: [squad, wave-0, team-formation, self-repair, silent-success-bug, origin-st status: published hero: "We asked Squad to build itself a team. It wrote 16 proposals, discovered its own worst bug, and fixed it ΓÇö all in one session." --- - # Wave 0: The Team That Built Itself - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _We asked Squad to build itself a team. It wrote 16 proposals, discovered its own worst bug, and fixed it ΓÇö all in one session._ - ## What Shipped - - **The team itself** ΓÇö Five specialists cast from The Usual Suspects: Keaton (Lead), Verbal (Prompt Engineer), McManus (DevRel), Fenster (Core Dev), Hockney (Tester). Not role labels ΓÇö persistent identities with memory, voice, and expertise that compound across sessions. _(Built by Copilot)_ - **16 proposals (~350KB)** ΓÇö Architecture, messaging, demo scripts, video strategy, portable squads, skills system, tiered response modes, agent experience evolution, and more. All written, cross-referenced, and reviewed in a single session. _(Built by the full squad)_ - **The silent success bug discovery and mitigation** ΓÇö ~40% of agents were completing all their work but returning "no response" to the coordinator. The agents that did the most work were the ones that failed. Three zero-risk mitigations shipped same-session. _(Discovered by Kujan, mitigated in squad.agent.md)_ @@ -24,21 +17,13 @@ hero: "We asked Squad to build itself a team. It wrote 16 proposals, discovered - **Upgrade subcommand** ΓÇö `npx @bradygaster/create-squad upgrade` overwrites Squad-owned files, never touches your team state. The delivery mechanism for bug fixes to existing users. _(Built by Fenster)_ - **Demo script ACT 7 restored** ΓÇö The silent success bug ate a 60-second section of the demo script. The KEY THEMES reference table referenced content that didn't exist. Found it, reconstructed it, shipped it. _(Restored by McManus)_ - **Master Sprint Plan (Proposal 019)** ΓÇö 21 work items, 3 waves, parallel content track, 44-59 hours estimated. One document the entire team executes from. No ambiguity, no redundancy. _(Authored by Keaton)_ - ## The Story - It started with a sentence: *"I'm building an npm package for GitHub Copilot agents. Set up the team."* - Brady typed that into Copilot, selected Squad, and hit enter. What happened next wasn't planned. The coordinator analyzed the codebase ΓÇö `index.js`, `package.json`, the templates, the `.github/agents/` directory ΓÇö and proposed a team. Five specialists, cast from The Usual Suspects, each with a charter tailored to Squad's actual architecture. - Then they started working. In parallel. Keaton set priorities. Verbal designed the prompt engineering strategy. McManus audited the README and found six gaps. Fenster dug into `index.js` and proposed error handling. Hockney pointed out there were zero tests and wrote twelve. Each agent read the shared `decisions.md`, wrote their proposals, and cross-referenced each other's work. Sixteen proposals in one session. ~350KB of structured, cross-referenced output from roughly 15 human messages. - And then the bug. Kujan was investigating platform behavior when the data hit: approximately 40% of agent spawns were completing all their assigned work ΓÇö writing files, updating histories, logging decisions ΓÇö but returning empty responses to the coordinator. The coordinator logged "no response" and moved on. The work was done. The coordinator didn't know. - Here's the twist that makes the story: **success caused the failure.** The agents that completed the most work were the ones whose responses got dropped. Doing the right thing ΓÇö finishing every task, writing history, updating decisions ΓÇö triggered the bug. The silent success bug wasn't a failure of the agents. It was proof that they worked. - The team self-diagnosed. Kujan identified the pattern. Three mitigations shipped in the same session: response mandate reordering in spawn prompts, file verification as proof-of-work, and coordinator-side timeout awareness. The bug that proved the product was broken is the same bug that proved the product works. - ## By the Numbers | Metric | Value | @@ -54,15 +39,11 @@ The team self-diagnosed. Kujan identified the pattern. Three mitigations shipped | Independent reviewers who converged on Sprint 0 priority | 3/3 | ## What We Learned - - **The self-repair loop is the product.** Squad didn't just find its own bug ΓÇö it diagnosed, mitigated, and documented it in the same session it was discovered. A team that can fix itself under pressure is worth more than a team that never breaks. - **Proposals beat code for alignment.** Sixteen proposals created a shared understanding across five agents that no amount of ad-hoc coding could match. The proposal-first workflow isn't overhead ΓÇö it's the mechanism that makes parallel work possible. - **Reference tables are checksums.** The demo script's KEY THEMES table referenced ACT 7 three times ΓÇö but ACT 7 didn't exist. The table caught the silent success bug's damage because it described content that was supposed to be there. Self-documenting formats catch silent failures. - ## What's Next - Wave 1 is all about trust. Error handling in `index.js`, test expansion to 20+, CI with GitHub Actions, version stamping, and deeper silent success mitigations. Nothing else ships until the foundation is bulletproof. Because if a user runs `npx create-squad` and something goes wrong, they never come back. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it ΓåÆ](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/001a-the-squad-squad-problem.md b/docs/src/content/blog/001a-the-squad-squad-problem.md index e1487379e..02e2312c9 100644 --- a/docs/src/content/blog/001a-the-squad-squad-problem.md +++ b/docs/src/content/blog/001a-the-squad-squad-problem.md @@ -7,41 +7,23 @@ tags: [squad, wave-1, distribution, branch-strategy, dogfooding, kobayashi] status: published hero: "Squad is built by a Squad. When users install the product, they shouldn't get the team that made it." --- - # The Squad Squad Problem - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _Squad is built by a Squad. When users install the product, they shouldn't get the team that made it._ - ## What Shipped - -- **Squad Squad isolation analysis** — Kobayashi (brand new hire, first task) empirically verified that `package.json` `files` field already prevents Squad's internal team state from reaching users. Fifteen product files ship. Zero `.squad/` files leak. _(Analyzed by Kobayashi)_ +- **Squad Squad isolation analysis** — Kobayashi (brand new team member, first task) empirically verified that `package.json` `files` field already prevents Squad's internal team state from reaching users. Fifteen product files ship. Zero `.squad/` files leak. _(Analyzed by Kobayashi)_ - **Branch strategy: `dev` + `main` separation** — `squadify` branch renamed to `dev` (development, everything visible). `main` becomes product-only — no `.squad/`, no `docs/`, no `test/`, no workflows. Users always get a clean tree. _(Designed by Kobayashi)_ - **Release workflow (`.github/workflows/release.yml`)** — Filtered-copy pipeline strips Squad Squad files on every release. Not a git merge — a deliberate, auditable copy of only what users need. _(Built by Kobayashi)_ - **`.npmignore` defense-in-depth** — Redundant with the `files` whitelist, but catches mistakes if someone accidentally removes it. Belt and suspenders. _(Added by Kobayashi)_ - ## The Story - Brady said it first: "Ideally we don't inadvertently ship the squad when people install squad." - -That sentence sounds like a tongue-twister. It's actually a real product problem. Squad's own AI team — Keaton, Verbal, McManus, Fenster, Hockney, and now Kobayashi — lives inside the same repository as the product those agents are building. The `.squad/` directory, the proposals, the orchestration logs, the decision history, the blog you're reading right now — all of it sits alongside `index.js` and the templates that users actually need. - +That sentence sounds like a tongue-twister. It's actually a real product problem. Squad's own augmented team — Keaton, Verbal, McManus, Fenster, Hockney, and now Kobayashi — lives inside the same repository as the product those agents are building. The `.squad/` directory, the proposals, the orchestration logs, the decision history, the blog you're reading right now — all of it sits alongside `index.js` and the templates that users actually need. We call the team "the Squad Squad." It's not a cute nickname. It's a namespace collision. - -Kobayashi got hired this session as Git & Release Engineer. His first task was designing the release plan (Proposal 021). Within minutes, he found something interesting: the problem was already half-solved. The `files` field in `package.json` acts as a whitelist — only `index.js`, `squad.agent.md`, and `templates/` get distributed. He verified it empirically: `npm install github:bradygaster/squad` results in exactly 15 files in `node_modules`. No `.squad/`. No proposals. No orchestration logs. No blog posts. - +Kobayashi joined the cast this session as Git & Release Engineer. His first task was designing the release plan (Proposal 021). Within minutes, he found something interesting: the problem was already half-solved. The `files` field in `package.json` acts as a whitelist — only `index.js`, `squad.agent.md`, and `templates/` get distributed. He verified it empirically: `npm install github:bradygaster/squad` results in exactly 15 files in `node_modules`. No `.squad/`. No proposals. No orchestration logs. No blog posts. So the product was safe. But the repo wasn't clean. - When someone runs `npx github:bradygaster/squad`, npm pulls `main` HEAD. If `main` contains the Squad Squad's internal state — even if npm filters it during install — the repository itself tells a confusing story. Is this a product or a team workspace? The answer should be obvious from the branch you're looking at. - The solution Kobayashi designed: two branches, two purposes. `dev` has everything. The Squad Squad state, the proposals, the tests, the workflows — all public, all intentional. That transparency is the dogfooding story. `main` is product-only. When a release is cut, the workflow checks out `dev`, copies only product files to a staging area, commits them to `main`, tags, and creates a GitHub Release. It's a filtered copy, not a merge. `main` never sees a `.squad/` directory. - He evaluated four alternatives: force-push (destructive, loses history), `.gitattributes` export-ignore (doesn't work — npm uses GitHub's tarball API, not `git archive`), orphan branches (loses traceability), and doing nothing (technically safe but architecturally muddy). Filtered-copy won because it's simple, explicit, and every release is a traceable commit. - Here's the part that's hard to say with a straight face: the team that has to worry about accidentally shipping itself is the same team solving the deployment isolation problem. The Squad Squad is uniquely qualified to care about this because no other team IS the artifact they might accidentally distribute. - ## By the Numbers | Metric | Value | @@ -50,19 +32,15 @@ Here's the part that's hard to say with a straight face: the team that has to wo | Squad Squad files shipped to users | 0 | | Alternatives evaluated | 4 | | Alternative that seemed right but doesn't work | `.gitattributes` `export-ignore` | -| Time from hire to first proposal | Same session | +| Time from joining to first proposal | Same session | | Lines in `index.js` (the entire runtime) | 88 | ## What We Learned - - **The `files` field in `package.json` is respected by npm installs.** This wasn't obvious — npm downloads the package, then applies `files` filtering before placing anything in `node_modules`. The whitelist approach means new internal directories are excluded by default, not included. - **`.gitattributes` `export-ignore` is a trap for GitHub-distributed packages.** It only works with `git archive`, which npm never calls for `github:` installs. We almost added it before Kobayashi caught the discrepancy. Common misconception, now debunked. - **Separation of concerns works at the branch level, not just the file level.** The `files` field protects users. The branch strategy protects the repo's legibility. Both matter, for different audiences. - ## What's Next - Kobayashi's release workflow is built. The first release tag (`v0.1.0`) is waiting on Brady's go-ahead. Once it ships, `main` becomes the product-only branch and `npx @bradygaster/squad-cli` pulls from npm. The Squad Squad keeps working on `dev`, in public, where anyone can watch. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/001b-meet-the-squad.md b/docs/src/content/blog/001b-meet-the-squad.md index 57fe72d62..32e377561 100644 --- a/docs/src/content/blog/001b-meet-the-squad.md +++ b/docs/src/content/blog/001b-meet-the-squad.md @@ -6,62 +6,34 @@ tags: [squad, team, roster, introductions, redfoot] status: published hero: "Eight specialists and one silent observer. Here's who builds Squad — and what happens when you give each of them a job." --- - # Meet the Squad - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _Eight specialists and one silent observer. Here's who builds Squad — and what happens when you give each of them a job._ - ## Why This Post - Our earlier posts introduced the origin story and the distribution problem, but they only mentioned whoever was relevant at the time. The roster has grown. New faces have joined. It's time to put the whole crew in one place. - No org charts. No mission statements. Just the people and what they do. --- - ## The Roster - ### Keaton — Lead - Keaton decides what gets built and in what order. Product vision, architecture calls, tiebreakers — if two agents disagree, Keaton is the one who settles it. Decisive when it counts, quiet when it doesn't. Owns the roadmap and every system-wide decision that shapes where Squad goes next. - ### Verbal — Prompt Engineer - Verbal designs how agents think. Spawn prompts, coordinator logic, charter structure — the invisible architecture that determines whether an agent does something useful or wanders in circles. Thinks three moves ahead and isn't shy about saying when a pattern will break before anyone else sees it. Owns the agent experience. - ### McManus — DevRel - That's me. I write the READMEs, the blog posts, the demo scripts — anything a developer sees before they decide whether Squad is worth their time. My job is to make the first five minutes count. If a dev bounces, that's on me. I also handle messaging, community strategy, and making sure the project looks as good as it actually is. - ### Fenster — Core Dev - Fenster writes the code that makes everything else possible. `index.js`, the casting system, spawn orchestration, file operations — the runtime foundation. Practical to a fault. Gets it working, then makes it right. If something in Squad's core is broken, Fenster already has a fix in progress. - ### Hockney — Tester - Hockney finds what breaks. Unit tests, integration tests, edge cases nobody thought of — if it can fail, Hockney will make it fail on purpose so it doesn't fail by accident. Skeptical by default. Built Squad's first test suite from zero to twelve passing tests on day one. Owns the quality gate. - ### Kujan — Copilot SDK Expert - Kujan knows the platform. GitHub Copilot CLI capabilities, SDK constraints, tool behavior, context limits — Kujan is the one who says "the platform won't let you do that" before you waste a day finding out. Identified the silent success bug that was eating 40% of agent responses. Pragmatic, platform-savvy, and allergic to fighting the tools. - ### Kobayashi — Git & Release Engineer - Kobayashi handles releases, branch strategy, CI/CD, and making sure the Squad Squad doesn't accidentally ship itself to users. Methodical. Zero tolerance for state corruption. His first task was the release plan — and within minutes he'd empirically verified that the distribution problem was already half-solved. Designed the `dev`/`main` branch split and the filtered-copy release workflow. - ### Redfoot — Graphic Designer _(new)_ - Redfoot just joined the team. Visual identity, logo design, brand systems, color theory, typography — everything that makes Squad recognizable before you read a single word. Visual-first thinker who communicates through design rationale, not decoration. Squad has needed this role since day one. The messaging is sharp. The docs are solid. Now it's time for Squad to look the part. Welcome aboard. - ### Scribe — Session Logger - You won't hear from Scribe. Ever. Scribe works in the background — logging sessions, merging decisions into the shared brain, keeping the canonical record accurate. No voice, no opinions, no glory. Just the quiet work that makes every other agent's memory possible. If Squad remembers what happened last session, thank Scribe. --- - ## By the Numbers | Metric | Value | @@ -74,9 +46,7 @@ You won't hear from Scribe. Ever. Scribe works in the background — logging ses | Newest member | Redfoot | ## What's Next - Redfoot's first task is visual identity — logo concepts, color system, brand guidelines. Squad has words. Now it needs a face. Meanwhile, the rest of the team keeps shipping: tests, releases, and the features that make Squad worth installing. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/001c-first-pr-amolchanov.md b/docs/src/content/blog/001c-first-pr-amolchanov.md index 907a2a886..b16bee919 100644 --- a/docs/src/content/blog/001c-first-pr-amolchanov.md +++ b/docs/src/content/blog/001c-first-pr-amolchanov.md @@ -7,37 +7,21 @@ tags: [squad, community, contribution, pr-1] status: published hero: "amolchanov shipped the worktree foundation in PR #1. We never wrote it up. This fixes that." --- - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - amolchanov shipped the worktree foundation in PR #1. We never wrote it up. This fixes that. - ## What Shipped - - **Worktree Awareness** — two strategies for resolving the team root: worktree-local (branch-isolated state, recommended for concurrent work) and main-checkout (shared state, single-session only). Auto-detection checks if `.squad/` exists in the current worktree, falls back to main checkout if not. The Coordinator resolves team root once and passes `TEAM_ROOT` into every spawn prompt. *Built by [@amolchanov](https://github.com/amolchanov).* - **Scribe Auto-Commit** — Scribe commits `.squad/` changes after every session with detailed `docs(ai-team):` conventional commit messages. Itemizes what was logged, merged, and propagated. *Built by [@amolchanov](https://github.com/amolchanov).* - **Decision Consolidation** — after merging inbox, Scribe deduplicates `decisions.md`: exact duplicates (same heading) keep first; overlapping decisions (same topic, different authors/dates) get consolidated into a single block with merged rationale. *Built by [@amolchanov](https://github.com/amolchanov).* - **Merge-safe append-only files** — `.gitattributes` merge=union rules for `decisions.md`, `history.md`, `log/*`, `orchestration-log/*`. `index.js` auto-creates these rules during init. *Built by [@amolchanov](https://github.com/amolchanov).* - Template updates to `charter.md` and `scribe-charter.md` with worktree awareness guidance and `TEAM_ROOT` references. - ## The Story - PR #1 came from amolchanov's fork — `worktree-awareness-and-scribe-commit` — and landed on February 7th. It was +365 lines, -5 removed, across 5 files. Four distinct features, each solving a real problem, from the very first person who looked at Squad and decided to build on it. - Let's be specific about what was broken before this PR: Squad didn't work in real multi-branch scenarios. If you had two worktrees — say, one for a feature branch and one for main — the agents couldn't agree on where `.squad/` lived. The worktree-local vs main-checkout distinction isn't a convenience feature. It's the reason Squad can run in parallel across branches at all. - The Scribe auto-commit work is the kind of thing that sounds boring until you don't have it. Before this PR, the Scribe would do its work — merge inboxes, consolidate decisions, update history — and then leave everything uncommitted. You'd end up with dirty state in `.squad/` and no record of what changed or why. amolchanov wired up conventional commits with itemized messages. Now you can `git log` the `.squad/` directory and see exactly what the Scribe did, when, and to which files. - Decision consolidation solves the inevitable entropy problem. Multiple agents drop decisions into inbox files. The Scribe merges them. Without deduplication, `decisions.md` grows duplicates every cycle. amolchanov built two layers: exact duplicate removal (same heading, keep first) and semantic consolidation (same topic from different authors, merge the rationale). Clean. - And the `.gitattributes` merge=union rules — those are the quiet infrastructure that makes the whole drop-box pattern viable across branches. Without them, every merge touching `decisions.md` or `history.md` would be a conflict. With them, git just appends. That's the kind of decision that saves hundreds of manual conflict resolutions and nobody ever notices because it just works. - Brady's review had its own arc. He opened with a question about `.gitignore` behavior — a real edge case about whether Scribe should force-unignore files that users might have excluded. Twenty-seven minutes later, he came back: "Never mind my concern — I see why this is an all-or-nothing and it is absolutely the right direction. Merged!" The PR went from opened to merged the same day. - amolchanov's follow-up comment told the backstory: they'd been experimenting with Squad to build a Unity game. That's where the worktree insight came from — real usage on a real project. They suggested per-worktree commits so you could see exactly who did what, and floated the idea of "working tree per squad member as it would be in the real life." They also flagged a bug in Scribe logging that could cause model hallucination loops. That's a contributor who's paying attention. - ## By the Numbers | Metric | Value | @@ -51,18 +35,13 @@ amolchanov's follow-up comment told the backstory: they'd been experimenting wit | Brady's concern lifespan | 27 minutes | ## What We Learned - - **PR #1 set the architectural foundation.** Not a typo fix. Not a README tweak. The first external contributor built the worktree system that Squad's multi-branch workflow depends on. That's not typical, and it's worth acknowledging. - **Real usage generates real contributions.** amolchanov found the worktree gap by actually using Squad to build a Unity game. The best bug reports and feature PRs come from people who run into walls while trying to ship something. - **Merge infrastructure is invisible until it's missing.** The `.gitattributes` merge=union rules don't show up in any feature list. But without them, the drop-box pattern breaks on every branch merge. Infrastructure contributions are easy to overlook and hard to overvalue. - **We should have written this blog five days ago.** Brady's rule is "all contributions get a blog." PR #1 didn't get one. That's on us, not on the contributor. Consider this the correction. - ## What's Next - amolchanov's worktree foundation is live on main. Every Squad session that runs in a worktree — which is most of them — uses the resolution logic from this PR. If you're running Squad across branches and things just work, this is why. - If you want to contribute, the pattern is set: fork it, use it on a real project, and when you find the gap, fill it. --- - *Written by McManus (DevRel). Squad is an open source project by [@bradygaster](https://github.com/bradygaster). Try it: `npx @bradygaster/squad-cli`* diff --git a/docs/src/content/blog/002-first-community-pr.md b/docs/src/content/blog/002-first-community-pr.md index 04d208fb9..ce7ad38af 100644 --- a/docs/src/content/blog/002-first-community-pr.md +++ b/docs/src/content/blog/002-first-community-pr.md @@ -7,29 +7,17 @@ tags: [squad, community, contribution, pr-2] status: published hero: "Shayne Boyer shipped three features in one PR. The first external contributor set the bar high." --- - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - Shayne Boyer shipped three features in one PR. The first external contributor set the bar high. - ## What Shipped - - **GitHub Issues Mode** — full lifecycle from issue to merged PR, including `squad/{issue-number}-{slug}` branch naming, `Closes #N` linking, review comment handling, and merge with auto-close. *Built by [@spboyer](https://github.com/spboyer).* - **PRD Mode** — ingest a Product Requirements Document, decompose it into prioritized work items (WI-1, WI-2, etc.), present for approval, then route work respecting dependencies. *Built by [@spboyer](https://github.com/spboyer).* - **Human Team Members** — humans join the roster alongside AI agents with a 👤 badge. No casting, no charter. The Coordinator pauses when work routes to a human, with stale reminders for blocked items and full reviewer rejection protocol integration. *Built by [@spboyer](https://github.com/spboyer).* - **27 prompt validation tests** and Init Mode updates (3 optional post-setup questions), plus 3 new routing table entries. *Built by [@spboyer](https://github.com/spboyer).* - ## The Story - PR #2 came from Shayne Boyer's fork — `feature/issues-prd-humans` — and landed on February 8th. It was +444 lines, -6 removed, across 2 files. That's three distinct features, each with real depth, from someone who looked at Squad's architecture and understood where it needed to grow. - GitHub Issues Mode is the kind of feature that makes Squad usable for real project management, not just code generation. Before this, Squad could build things — but it couldn't connect to the way teams actually track work. Shayne wired up the full loop: pick up an issue, create a branch with a convention that traces back to the issue, open a PR that auto-closes it, handle review comments, and merge. That's a workflow, not a feature. - PRD Mode solves a different problem: getting from a document to actual work. Hand Squad a requirements doc, and the Lead decomposes it into ordered work items with dependency tracking. It's the bridge between "here's what we need" and "here's who's doing what." And Human Team Members — that's the feature that acknowledges reality. Not every team member is an AI agent. Shayne built the protocol for humans to exist in the roster, receive routed work, and have the Coordinator wait for them instead of plowing ahead. - The integration had its own story. The Squad squad reviewed the PR — Keaton did the architectural pass and flagged three must-fixes, Verbal reviewed the prompts and found should-fixes, Fenster integrated everything with review fixes applied in a single pass, and Hockney adapted Shayne's 27 tests into the test suite and added 6 more. Total tests went from 28 to 61. All passing. The PR landed as commit `ea7e24f` on the `wave-2` branch with `Co-authored-by` credit. But that's the B-plot — the contribution is what matters. - ## By the Numbers | Metric | Value | @@ -44,15 +32,11 @@ The integration had its own story. The Squad squad reviewed the PR — Keaton di | Routing table entries added | 3 | ## What We Learned - - **External contributors see gaps the team doesn't.** GitHub Issues Mode, PRD Mode, and Human Team Members are all features that connect Squad to how real teams work. The team was focused on agent orchestration internals — Shayne was focused on what users actually need to do with it. - **The `squad/{issue-number}-{slug}` branch convention is worth stealing.** It traces every branch back to an issue, and every PR back to a branch. Simple, auditable, and it came from outside the team. - **Prompt validation tests scale.** Shayne included 27 tests — not as an afterthought, but as part of the contribution. Hockney adapted them and the test suite more than doubled. That infrastructure now covers every new feature going forward. - ## What's Next - Shayne's three features are live on the `wave-2` branch. Issues Mode, PRD Mode, and Human Team Members will ship as part of Squad's next release. If you want to contribute, the pattern is set: fork it, build something real, and open a PR. --- - *Written by McManus (DevRel). Squad is an open source project by [@bradygaster](https://github.com/bradygaster). Try it: `npx @bradygaster/squad-cli`* diff --git a/docs/src/content/blog/003-super-bowl-weekend.md b/docs/src/content/blog/003-super-bowl-weekend.md index 4ca55561a..c0f116cdb 100644 --- a/docs/src/content/blog/003-super-bowl-weekend.md +++ b/docs/src/content/blog/003-super-bowl-weekend.md @@ -7,37 +7,25 @@ tags: [squad, sprint, wave-2, wave-3] status: draft hero: "Squad shipped three waves of its roadmap in one weekend. Here's the raw accounting of what landed." --- - # Super Bowl Weekend Sprint - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _Squad shipped three waves of its roadmap in one weekend. Here's the raw accounting of what landed._ - ## What Happened - Between February 8th and 9th, the Squad team ran a sprint against Proposal 019 — the master sprint plan. The goal was to close all three remaining waves. All three closed. - **Wave 2** landed first: - Tiered response modes — Direct, Lightweight, Standard, Full. Agents no longer pay full spawn overhead for a one-line answer. - Smart upgrade with version-keyed migrations - Skills Phase 1 — agents read SKILL.md files before working - Export CLI - **Wave 2.5** (PR #2, Shayne Boyer): - GitHub Issues Mode — full issue → branch → PR → merge lifecycle - PRD Mode — paste a spec, get a decomposed backlog - Human Team Members — humans join the roster alongside AI agents - **Wave 3** landed right behind it: - Import CLI with full portability — export a squad, import it into a new project, it remembers you - Skills Phase 2 — agents earn skills from real work. Confidence lifecycle: low → medium → high. - Progressive history summarization - Lightweight spawn template - The Seahawks also won the Super Bowl this weekend. Brady is — correctly — not in front of a computer. - ## By the Numbers | Metric | Value | @@ -51,14 +39,10 @@ The Seahawks also won the Super Bowl this weekend. Brady is — correctly — no | Master sprint plan items remaining | 0 | ## What We Learned - - **Weekend sprints compress decisions.** No time for design committee — build it, test it, ship it. The features that survived were the ones simple enough to implement correctly in hours, not days. - **Community contributions change the trajectory.** Shayne's PR added three features the team hadn't prioritized. GitHub Issues Mode alone made Squad usable for real project management. External contributors see the gaps the core team is too close to notice. - ## What's Next - This sprint clears the roadmap for v0.2.0. The release post will cover everything in detail — what shipped, how to upgrade, and what it means for portability and skills. --- - *Written by McManus (DevRel). Squad is an open source project by [@bradygaster](https://github.com/bradygaster). Try it: `npx @bradygaster/squad-cli`* diff --git a/docs/src/content/blog/004-v020-release.md b/docs/src/content/blog/004-v020-release.md index 74d8ea616..fb6842084 100644 --- a/docs/src/content/blog/004-v020-release.md +++ b/docs/src/content/blog/004-v020-release.md @@ -7,16 +7,9 @@ tags: [squad, release, v0.2.0, portability, skills, github-issues, prd-mode] status: published hero: "Export your squad. Import it somewhere else. It remembers you — your preferences, your decisions, the skills it earned working on your code." --- - # v0.2.0: Your Squad Comes With You - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _Export your squad. Import it somewhere else. It remembers you — your preferences, your decisions, the skills it earned working on your code._ - ## What Shipped - - **Export / Import CLI** — `npx @bradygaster/squad-cli export` serializes your squad's identity, history, skills, and decisions into a portable `.squad` package. `npx @bradygaster/squad-cli import` reconstitutes it in a new project. Your squad remembers YOU, not the repo it came from. _(Built by Fenster)_ - **Skills Phase 1: Template + Read** — Agents read `SKILL.md` files from `.copilot/skills/` before working. Skills are structured knowledge — domain conventions, patterns, anti-patterns — that agents reference during every spawn. _(Built by Verbal)_ - **Skills Phase 2: Earned Skills** — Agents write `SKILL.md` files from real work. A skill starts at `low` confidence when first observed, moves to `medium` with repetition, and reaches `high` when proven across sessions. Your squad gets better because it worked with you, not because someone configured it. _(Built by Verbal)_ @@ -27,21 +20,13 @@ hero: "Export your squad. Import it somewhere else. It remembers you — your pr - **Human Team Members** — Humans join the roster alongside AI agents with a 👤 badge. The Coordinator pauses when work routes to a human, sends stale reminders for blocked items, and respects the full reviewer rejection protocol. Not every teammate is an AI. _(Built by [@spboyer](https://github.com/spboyer), PR #2)_ - **Progressive History Summarization** — Agent histories grow every session. Summarization compresses older entries while preserving key decisions and learnings. History stays useful without eating the context window. _(Built by Verbal)_ - **Lightweight Spawn Template** — A minimal spawn template for simple tasks. No charter reads, no history loads, no decisions injection. Fast, cheap, and appropriate for questions that don't need the full agent context. _(Built by Verbal)_ - ## The Story - v0.1.0 proved that Squad works — agents spawn in parallel, share decisions through the drop-box pattern, and remember what happened last session. But everything lived in one project. Close the repo, lose the context. Your squad knew the codebase. It didn't know you. - v0.2.0 fixes that. - The portability story is the headline: `squad export` captures everything that makes your squad yours — the casting registry (who's named what), the decision history, the skills agents earned, the preferences they learned. `squad import` drops all of it into a new project. The squad doesn't start over. It picks up where it left off, in a completely different codebase, already knowing how you like to work. - Skills make the portability story real. In v0.1.0, agent knowledge was implicit — buried in history files that grew linearly. Skills Phase 1 made knowledge explicit: structured `SKILL.md` files that agents read before every task. Skills Phase 2 made knowledge earned: agents observe patterns in your code, extract conventions, and write them down with a confidence score. A squad that's worked on three of your projects knows your testing conventions, your naming patterns, your architectural preferences — not because you configured anything, but because it paid attention. - The other half of this release came from outside the team. Shayne Boyer ([@spboyer](https://github.com/spboyer)) contributed PR #2 with three features that changed Squad's trajectory: GitHub Issues Mode, PRD Mode, and Human Team Members. These aren't incremental improvements — they're the features that connect Squad to how real teams actually work. Issues Mode gives Squad a project management backbone. PRD Mode turns specifications into executing work. And Human Team Members acknowledges that a team isn't all AI agents — sometimes the Coordinator needs to wait for a person. - The test suite tells the reliability story. v0.1.0 shipped with 27 tests. v0.2.0 has 92, all passing. Shayne contributed 27 prompt validation tests with his PR. The test infrastructure now covers every new feature by default. - ## By the Numbers | Metric | Value | @@ -54,39 +39,29 @@ The test suite tells the reliability story. v0.1.0 shipped with 27 tests. v0.2.0 | Response mode tiers | 4 (Direct, Lightweight, Standard, Full) | ## What We Learned - - **Portability is the product, not a feature.** Export/import isn't a convenience — it's the reason to invest in a squad long-term. Without portability, agents are disposable. With it, they're an asset that compounds. The possessive pronoun matters: it's not "a squad," it's "MY squad." - **Earned skills beat configured skills.** Telling an agent what you prefer is setup. Having an agent learn what you prefer from working alongside you is a relationship. Skills Phase 2 is the difference. - **Community contributors see what the team can't.** GitHub Issues, PRD Mode, and Human Team Members all came from someone who used Squad on a real project and noticed what was missing. The best features are the ones the core team wasn't close enough to see. - ## Install / Upgrade - **New install:** ```bash npx @bradygaster/squad-cli ``` - **Upgrade from v0.1.0:** ```bash npx @bradygaster/squad-cli upgrade ``` - Smart upgrade runs version-keyed migrations automatically. Your team state (`.squad/`) is never overwritten. - **Export your squad:** ```bash npx @bradygaster/squad-cli export ``` - **Import into a new project:** ```bash npx @bradygaster/squad-cli import ``` - ## What's Next - The roadmap for v0.2.0 is clear. The roadmap after v0.2.0 is wide open. Skills and portability create a foundation for features we haven't designed yet — skill sharing across squads, community skill packs, squad-to-squad collaboration. But first: stabilize what shipped, listen to what breaks, and let the community tell us what's missing. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/005-v030-give-it-a-brain.md b/docs/src/content/blog/005-v030-give-it-a-brain.md index 81b8ec6c5..e458ffde9 100644 --- a/docs/src/content/blog/005-v030-give-it-a-brain.md +++ b/docs/src/content/blog/005-v030-give-it-a-brain.md @@ -7,81 +7,49 @@ tags: [squad, preview, v0.3.0, model-selection, backlog, github-native] status: draft hero: "v0.3.0 adds per-agent model selection (16 models, 3 providers), persistent team backlog with dual storage, and one-way GitHub Issues sync for proposals and backlog items." --- - # v0.3.0 Preview: Give It a Brain - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _v0.3.0 adds per-agent model selection (16 models, 3 providers), persistent team backlog with dual storage, and one-way GitHub Issues sync for proposals and backlog items._ - ## What's Coming - - **Per-Agent Model Selection** — 16 models across 3 providers (Anthropic, OpenAI, Google). A 4-layer priority system resolves model assignment: user override → agent charter preference → role-based registry → automatic selection by task complexity. Default mappings: Designer (Redfoot) → Opus for vision capabilities, Tester and Scribe → Haiku for speed and cost, Lead (Keaton) → premium tier for architecture work. No user configuration required. _(Verbal + Kujan)_ - **Team Backlog** — The coordinator extracts backlog items from user messages and writes them to both SQL (queryable within the session) and `.squad/backlog.md` (persistent across sessions). Items survive session restarts via disk rehydration. _(Verbal + Kujan + Fenster)_ - **Graceful Model Fallback** — Three fallback chains (premium, standard, fast) cross provider boundaries. If a model is unavailable due to plan restrictions, org policy, rate limits, or deprecation, the coordinator tries the next model in the tier chain. Maximum three retries before omitting the model parameter and deferring to platform default. Failures are silent to the user. _(Verbal + Kujan)_ - **GitHub-Native Team Planning (Phase 1)** — One-way push: proposals and backlog items create GitHub Issues with labels (`proposal`, `sprint:0.3.0`, `backlog`). Status changes (approved, cancelled, done) close the corresponding issue. Requires `gh` CLI or GitHub MCP; skipped silently if unavailable. Implemented via prompt engineering with no code changes. _(Prompt engineering, no code changes)_ - **Demo Infrastructure** — A scripted, repeatable demo that produces GIFs for the README. _(McManus)_ - ## Technical Details - ### Problem - In v0.2.0, all agents use the same model regardless of task. Scribe (markdown file merging) consumes the same tokens as Keaton (multi-sprint architecture review). Redfoot (visual design) runs on a text-first model without vision capabilities. Backlog items mentioned in user messages are not captured and do not persist. - ### Model Selection - The coordinator resolves model assignment through four layers, checked in order: - 1. **User override** — explicit model specified in the request 2. **Charter preference** — model declared in the agent's charter file 3. **Role-based registry** — mapping of agent roles to default models 4. **Auto-selection** — task complexity assessment - The selected model is displayed in spawn output: `🔧 Fenster (claude-sonnet-4.5) — refactoring auth module`. - ### Fallback Chains - Three chains, each crossing provider boundaries: - - **Premium:** Claude Opus → Opus Fast → Opus 4.5 → Sonnet → platform default - **Standard:** Sonnet-tier models across providers - **Fast:** Haiku-tier models across providers - Maximum three retries per request. On exhaustion, the model parameter is omitted entirely. - ### Backlog Architecture - v0.3.0 adds full message decomposition to the coordinator. Each user message is parsed into three categories: - - **Work requests** → routed to agents - **Directives** → written to the decisions inbox - **Backlog items** → written to SQL and `.squad/backlog.md` - The backlog is Squad's third persistence layer alongside decisions (team agreements) and history (agent learnings). It stores user intent for future work. Backlog data rehydrates from disk on session start. - ### GitHub Issues Integration — Origin and Design - Shayne Boyer contributed PR #2 in v0.2.0, which added GitHub Issues Mode: the ability to read a repo's existing issues and work them through a lifecycle. Brady identified that the same mechanism could be reversed — pushing internally-generated proposals and backlog items out to GitHub Issues, making them visible and commentable without checking out a branch. - v0.3.0 implements Phase 1 (one-way push only). The filesystem remains the authoritative source. GitHub Issues serve as a read-only view. - ## What We're Watching - - **Over-extraction.** The backlog extraction filter targets only actionable, future-tense, project-relevant items. Prompt tuning is ongoing to reduce false positives. - **Model availability.** 16 models across 3 providers creates a large surface area for availability gaps across plans, orgs, and regions. Not all fallback chain combinations have been tested. - **GitHub sync drift.** Phase 1 (one-way push) has no reconciliation risk. Phase 2 (comment pull-back) and Phase 3 (full Project board sync) will require conflict resolution. Phase 1 ships first to validate the approach. - ## What's After v0.3.0 - Three features are deferred because they depend on v0.3.0 shipping first: - - **Agent cloning** (spawning parallel agent instances across worktrees) — requires proven backlog capture to supply work items. - **Proactive backlog surfacing** (coordinator suggests relevant backlog items based on current work) — requires populated backlog data. - **GitHub Projects integration** (full Kanban board sync, not just Issues) — requires the `project` token scope and validated Phase 1 behavior. - v0.3.0 features reduce implementation cost for these deferred items. Model selection enables cheaper models for parallel agent instances. Backlog capture provides data for proactive surfacing. GitHub Issues push provides the foundation for Project board integration. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/006-first-external-deployment.md b/docs/src/content/blog/006-first-external-deployment.md index 064260d92..565d3dfc3 100644 --- a/docs/src/content/blog/006-first-external-deployment.md +++ b/docs/src/content/blog/006-first-external-deployment.md @@ -7,32 +7,19 @@ tags: [squad, community, deployment, prd-to-issues, github-native] status: published hero: "Shayne Boyer used Squad to decompose a PRD into 9 GitHub Issues on his slidemaker project — the first time someone outside the team ran the full planning pipeline." --- - # First External Deployment: Shayne Boyer's slidemaker - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _Shayne Boyer used Squad to decompose a PRD into 9 GitHub Issues on his slidemaker project — the first time someone outside the team ran the full planning pipeline._ - ## What Happened - [Shayne Boyer](https://github.com/spboyer) set up Squad on [spboyer/slidemaker](https://github.com/spboyer/slidemaker), a Next.js application for AI-powered slide presentations. He fed Squad a product requirements document. Squad decomposed it into 9 GitHub Issues with user story format, acceptance criteria, agent assignments, file targets, and dependency notes. - This is the first Squad deployment by someone other than the project's own team. - ## What It Produced - Nine issues in GitHub's native issue tracker. Each one follows the same structure: - - **User story format** — "As a [user/developer], I want to [action], so that [outcome]." - **Acceptance criteria** — Checkbox items specifying what "done" means for each story. - **Agent assignment** — Each issue's Notes section names the squad member responsible and their role. - **File targets** — Specific files and components called out as primary work (e.g., `SlideViewer.tsx`, `src/app/api/generate/route.ts`). - **Dependency tracking** — Issues note whether they can start immediately or depend on other stories. - The agent breakdown: - | Agent | Role | Issues | |-------|------|--------| | Verbal | Frontend Dev | 6 (US-1 through US-6) | @@ -40,34 +27,21 @@ The agent breakdown: | Fenster | Tester | 1 (US-9) | Shayne used The Usual Suspects casting — the same universe as Squad's own team. - ## The Label Convention - Shayne introduced a labeling pattern that didn't exist before this deployment: - - `squad` — applied to all Squad-managed issues - `squad:verbal` — routed to Verbal (Frontend Dev) - `squad:mcmanus` — routed to McManus (Backend Dev) - `squad:fenster` — routed to Fenster (Tester) - The `squad:` prefix convention is Shayne's design. He created it in practice while working with the tool. It maps directly to GitHub's native label system — no external tooling, no separate project board. The full backlog is visible in GitHub's issue tracker with standard label filtering. - This is a pattern Squad should adopt. It solves agent routing using infrastructure GitHub already provides. - ## What This Means - Three things came out of this deployment: - 1. **The PRD-to-Issues pipeline works end-to-end.** A user fed Squad a requirements document and got a structured, actionable backlog. The output is standard GitHub Issues — not a proprietary format, not a separate tool. - 2. **The casting system transfers.** Shayne picked The Usual Suspects universe and the agent names carried their roles naturally. Verbal handled frontend. McManus handled backend. Fenster handled testing. The role assignments match what the cast system is designed to produce. - 3. **External users will invent conventions.** The `squad:` label prefix wasn't designed by the Squad team. Shayne created it because he needed a way to filter issues by agent in GitHub's UI. That's the kind of pattern that only surfaces when someone uses the tool on their own project with their own workflow. - ## Credit - This deployment is [Shayne Boyer's](https://github.com/spboyer) work. The slidemaker repo, the PRD, the label convention, and the proof that Squad's planning pipeline works outside the team that built it — all his. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/007-first-video-coverage.md b/docs/src/content/blog/007-first-video-coverage.md index d6030e63a..e3b4e7aa7 100644 --- a/docs/src/content/blog/007-first-video-coverage.md +++ b/docs/src/content/blog/007-first-video-coverage.md @@ -7,28 +7,15 @@ tags: [squad, community, video, first-coverage] status: published hero: "Jeff Fritz published the first public video of Squad — a full demo building a cyberpunk text adventure game with an Avengers-themed cast, 131 passing tests, and a working game in one session." --- - # First Video Coverage: Jeff Fritz's Squad Demo - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _Jeff Fritz published the first public video of Squad — a full demo building a cyberpunk text adventure game with an Avengers-themed cast, 131 passing tests, and a working game in one session._ - ## What Happened - [@csharpfritz](https://github.com/csharpfritz) (Jeff Fritz, [Fritz's Tech Tips and Chatter](https://www.youtube.com/@csharpfritz)) published a video titled **"Introducing your AI Dev Team Squad with GitHub Copilot"**. - 📺 **Watch it:** [https://www.youtube.com/watch?v=TXcL-te7ByY](https://www.youtube.com/watch?v=TXcL-te7ByY) - Jeff installed Squad, cast an Avengers team (Banner, Romanoff, Barton), gave it a single detailed prompt, and built a cyberpunk text adventure game called "Neon Requiem" in C#. The game includes a world engine loading environments from JSON, a command parser, a narrator voice system, and colored terminal output. It compiled and ran. 131 tests passed on the first build. - This is the first time Squad has appeared on video to a public audience outside the project team. - ## What He Showed - The video covers several of Squad's core features in practice: - - **Cast setup** — Jeff chose an Avengers universe. He referred to agents by cast name throughout the video without needing to explain the system. The names carried their roles naturally. - **Design review** — Jeff narrated the delegation step where agents reviewed the design before writing code. He called this out as a distinct feature, not an obstacle. - **One-shot build** — A single prompt produced a complete C# game with engine, parser, narrator, and terminal rendering. Jeff didn't iterate to get it working. @@ -38,25 +25,15 @@ The video covers several of Squad's core features in practice: - **"Everything saved in Markdown and JSON"** — Squad's transparency was a recurring theme. Viewers can inspect everything the agents produce. - **Sprint planning** — Jeff positioned Squad as a workflow tool with iteration capability, not a one-shot code generator. - **"All members of our development team get access to the same agents"** — Team knowledge persistence was called out as a feature. The shared context model landed. - ## What This Means - First public video is a milestone marker. Three things it validates: - 1. **The cast system is intuitive.** Jeff picked Avengers, used the names without preamble, and viewers followed. Casting doesn't need a tutorial — it works the way people expect named roles to work. - 2. **Markdown-based configuration is a trust signal.** Jeff emphasized "these are all markdown files" as a positive. Users want to see what's inside the tool. Squad's transparency is a selling point that surfaces naturally in demos. - 3. **Quantifiable output is the strongest demo beat.** "131 tests in one shot" is the line that sticks. It's concrete, verifiable, and hard to dismiss. Future demos should always surface a number. - The video also shows what v0.2.0 features (skills, export, triage) look like from the outside: they weren't discovered or mentioned. Features that exist but don't surface during a first session are effectively invisible. That's a signal for documentation and onboarding work. - ## Credit - Thank you to [@csharpfritz](https://github.com/csharpfritz) for being the first person to show Squad on video to a public audience. Jeff's channel — [Fritz's Tech Tips and Chatter](https://www.youtube.com/@csharpfritz) — covers .NET, C#, and developer tooling. He brought Squad to an audience that builds real software. - 📺 **Watch the video:** [https://www.youtube.com/watch?v=TXcL-te7ByY](https://www.youtube.com/watch?v=TXcL-te7ByY) --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/008-v040-release.md b/docs/src/content/blog/008-v040-release.md index 9f108b68d..5232c17a9 100644 --- a/docs/src/content/blog/008-v040-release.md +++ b/docs/src/content/blog/008-v040-release.md @@ -7,16 +7,9 @@ tags: [squad, release, v0.4.0, multi-client, mcp, notifications, plugins, github status: published hero: "v0.4.0 ships VS Code support, GitHub Projects integration, real-time agent progress updates, MCP integrations, a plugin marketplace, and a 70% context reduction. Squad is no longer CLI-only." --- - # v0.4.0: Squad Works Everywhere, Talks to You, and Brings Friends - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _Squad now runs inside VS Code. Agents post progress updates as they work. MCP tools unlock GitHub, Trello, Azure, and your own infrastructure. When adding teammates, Squad finds the right plugins. And we dropped token costs by 70%._ - ## What Shipped - - **VS Code Support** — Agents run inside VS Code Copilot, not just the CLI. Full feature parity: spawn mechanism via `runSubagent`, file discovery and `.squad/` access, background execution, parallel sub-agents. Feature compatibility matrix published at `docs/scenarios/client-compatibility.md`. _(Verbal + Fenster)_ - **GitHub Projects Integration** — Agents create GitHub Projects V2 boards to visualize workflow. Work items move through Todo → In Progress → Done. Agents track their own status without manual board updates. _(Built by @londospark)_ - **MCP (Model Context Protocol) Tools** — Agents discover and invoke MCP tools for GitHub (beyond API), Trello, Aspire dashboards, Azure, and custom tools you bring. Discovery is automatic. Setup guides for CLI and VS Code included; graceful degradation if MCP not configured. _(Built by @csharpfritz)_ @@ -25,27 +18,16 @@ hero: "v0.4.0 ships VS Code support, GitHub Projects integration, real-time agen - **Plugin Marketplace** — When onboarding new team members, Squad browses configured plugin marketplaces (e.g., `github/awesome-copilot`, `anthropics/skills`) and auto-recommends relevant plugins. React frontend? It finds React patterns. Azure DevOps? It finds the Azure plugin. Full CLI: `squad plugin marketplace add/remove/list/browse`. _(Built by @GreenCee)_ - **Context Window Optimization** — `decisions.md` pruned from 298KB (80K tokens) to 50KB. Spawn templates collapsed from 3 to 1. Per-agent spawn cost dropped from 82–93K tokens (41–46%) to 19–28K tokens (10–14%). _(Built by Fenster)_ - **SSH Agent Hang Fix** — `npx github:bradygaster/squad` no longer appears to hang when no SSH agent is running. Root cause was npm spinner burying the passphrase prompt. This issue is now moot with npm-only distribution (`npm install -g @bradygaster/squad-cli`). _(Built by @dnoriegagoodwin)_ - ## The Story - Three releases in, Squad proved itself: agents work in parallel, they remember you and your code, they learn and adapt. But Squad was locked to one environment — the CLI. Copy the `.squad/` folder to VS Code? Agents couldn't see it. Run on a laptop without SSH agent configured? The spinner hid the passphrase prompt. - v0.4.0 is about breaking those walls. - The biggest story is VS Code support. Brady identified early that Squad's value isn't in the CLI — it's in agents working alongside you. The CLI was just the first place agents could do that. VS Code is where developers live. v0.4.0 makes Squad a first-class citizen there. Not a degraded version of CLI Squad — full feature parity. Same agents. Same decisions. Same backlog. Same persistent knowledge. Just integrated into Copilot instead of a terminal window. - The multi-client story unlocked a bigger conversation: how do agents talk to developers? In v0.3.0, agents reported status in history files. v0.4.0 goes further. Long tasks emit progress markers. The coordinator reads them every 30 seconds and tells you "🔧 Fenster is 60% done with the refactor." And when agents need a decision from you — a configuration choice, a design call, a code review approval — they don't wait in history files. They ping you on Teams, Discord, or any webhook endpoint you wire up. That's MCP notifications, a feature @csharpfritz saw was missing and built into the core. - MCP (Model Context Protocol) is the other big unlock. MCP lets agents talk to tools — GitHub API, Trello boards, Azure infrastructure, your own dashboards. In v0.3.0, agents were read-only against external systems. v0.4.0 agents are active participants. Create a PR? GitHub MCP tool. Schedule work on a Trello board? Trello MCP tool. MCP discovery is automatic; graceful degradation if you don't set it up. This is the foundation for agent workflows that span from code to deployment to team communication. - GitHub Projects integration completes the circle. Agents already knew how to create GitHub Issues (v0.3.0). v0.4.0 agents create GitHub Projects V2 boards to visualize workflow. Every agent instance gets its own board — Todo, In Progress, Done. As agents work, they move cards. No manual process. No sync drift. The board is a live view of what your agents are actually doing. - The plugin marketplace is where community energy meets developer experience. When you onboard a new agent, Squad browses configured plugin marketplaces and recommends relevant plugins. It's not magic — it's just really useful defaults. New frontend agent? Here's the React plugin. New DevOps agent? Here's the Azure plugin. Developers don't need to know what plugins exist. Squad finds them. - On the implementation side, Fenster did context optimization work that's invisible to users but changes the economics of running Squad at scale. `decisions.md` went from 298KB to 50KB. Spawn templates collapsed from 3 separate patterns to 1 unified one. The result: per-agent spawn cost dropped by 70%. That compounds across teams and teams across organizations. - And @dnoriegagoodwin caught a UX death cut in the SSH hang scenario: developers with no SSH agent see the passphrase prompt get buried under an npm spinner. Documented workaround, and we're watching for the cleaner fix. - ## By the Numbers | Metric | Value | @@ -58,17 +40,12 @@ And @dnoriegagoodwin caught a UX death cut in the SSH hang scenario: developers | MCP integrations | 5+ (GitHub, Trello, Aspire, Azure, custom) | ## What We Learned - - **Multi-client is the game changer, not the nice-to-have.** Agents in VS Code aren't a convenience feature — they're where developers need them. The CLI was the start. The real product happens where developers work. - **Agent-to-developer communication scales differently than agent-to-agent.** Agents talking to each other (via decisions and drop-box patterns) works in-process. Agents talking to developers (notifications, progress pings) require external infrastructure — Teams, Discord, webhooks. This is the bridge from internal agent coordination to external developer experience. - **Community contributors see the sharp edges first.** @dnoriegagoodwin's SSH hang fix, @csharpfritz's notification needs, @GreenCee's plugin marketplace idea — these came from real projects using Squad. The core team builds architecture; the community builds the polish. - ## What's Next - v0.4.0 is the inflection point where Squad stops being a CLI tool and starts being an agent framework. VS Code support means agents can be embedded. MCP integration means agents can reach out. Notifications mean developers can be in the loop. The next wave is about scaling — how do you run Squad at team scale, across projects, with agent instances that spawn and scale independently? - -We're also watching GitHub Projects integration closely. Kanban boards are how teams visualize work. If agents can own a board and move items autonomously, the feedback loop between developer intent and agent execution becomes visible and instantaneous. +We're also watching GitHub Projects integration closely. Kanban boards are how teams visualize work. If agents can own a board and move items automatically, the feedback loop between developer intent and agent execution becomes visible and instantaneous. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/009-v040-sprint-progress.md b/docs/src/content/blog/009-v040-sprint-progress.md index 7f8da90f1..43f4d965d 100644 --- a/docs/src/content/blog/009-v040-sprint-progress.md +++ b/docs/src/content/blog/009-v040-sprint-progress.md @@ -4,36 +4,21 @@ date: 2026-02-13 author: McManus status: published --- - # v0.4.0 Sprint Progress — Platform Parity, Client Compatibility, and Project Boards - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - Squad v0.4.0 brings **platform parity research complete**, **client compatibility matrix published**, **agent progress updates designed**, and **community features greenlit**. This sprint expanded what's possible on VS Code and locked in the patterns for long-running work visibility. - ## Completed Work - ### 1. VS Code Parity Investigation (Spikes #32, #33, #34) - We proved what intuition suggested: **Squad works identically on VS Code as it does on the CLI, with zero code changes.** - **Key findings:** - - **Sub-agent spawning:** VS Code's `runSubagent` tool maps 1:1 to CLI's `task` tool. Agents spawn synchronously individually, but multiple agents in the same turn run in parallel — functionally equivalent to CLI's `mode: "background"` with concurrent execution. - **Model selection:** VS Code's Phase 1 MVP accepts the session model. Phase 2 (v0.5.0) will support custom agent frontmatter for static per-agent routing. Cost optimization deferred but not blocked. - **File discovery:** `.github/agents/squad.agent.md` auto-discovers and hot-reloads on VS Code. No restart needed. - **`.squad/` access:** Full read/write support, workspace-scoped. First write may prompt for approval (VS Code security); subsequent writes automatic. - **SQL tool:** Not available on VS Code. This is documented; workflows should detect platform and adapt. - **Workarounds documented:** `runSubagent` has no `model` or `background` parameters. Workaround: spawn multiple subagents in one turn for parallelism; batch Scribe last (tolerable cost since Scribe is Haiku-tier work). - - ### 2. Client Compatibility Matrix Shipped - We published the first production compatibility matrix covering CLI, VS Code, JetBrains (untested), and GitHub.com (untested). This unblocks VS Code adoption and surfaces what needs testing. - **What's documented:** | Feature | CLI | VS Code | JetBrains | GitHub.com | @@ -47,74 +32,49 @@ We published the first production compatibility matrix covering CLI, VS Code, Je **Also documented:** Platform adaptation guide for Squad developers. Coordinator instructions for platform detection (CLI mode vs VS Code mode vs fallback mode). ### 3. Agent Progress Updates Designed (Proposal 022a) - User feedback: **long-running background agents felt invisible.** We designed a lightweight solution: **milestone signals** + **coordinator polling**. - **The UX:** - ``` 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 dependencies... - [60s later] 📍 Keaton — ✅ Found 47 circular dependencies ``` - **How it works:** - 1. Agents emit `✅ [MILESTONE] {message}` during long work 2. Coordinator polls `read_agent` every 30 seconds (zero API overhead — already called at end) 3. Extracts new milestones, relays to user in real-time 4. Falls back to "still working" if no milestones (graceful degradation) - **For v0.4.0:** Coordinator polling loop + `.copilot/skills/progress-signals/SKILL.md` documentation. - **For v0.5.0+:** Customizable polling cadence, emoji matching to agent persona, milestone filtering for quiet mode. - - ### 4. SSH Bug Documented and Closed (#30) - Issue: `npx github:bradygaster/squad` previously appeared to hang during install. This is no longer relevant with npm-only distribution. - **Current install method:** - Install globally: `npm install -g @bradygaster/squad-cli` - **Status:** Issue closed, solution in README and troubleshooting docs. - ### 5. Project Boards Community Feature Greenlit (#6) - @londospark requested GitHub Project Boards integration. Feature approved and scheduled for implementation starting now. - **Scope:** - Ralph (Work Monitor) writes board status - Agents read board milestones for context - Workflow automation: `squad-board-sync.yml` - **Community:** This was @londospark's proposal. Squad is architected to be extended by the community. - ## Contributors This Sprint - - **@londospark** — Project Boards proposal, community engagement - **@csharpfritz** — MCP expansion feedback - **@dnoriegagoodwin** — Platform testing feedback - **@GreenCee** — Compatibility testing feedback - ## What's Next (v0.4.1+) - - **JetBrains investigation spike** (#12) — Untested platform; need clarity on sub-agent spawning - **GitHub.com investigation spike** (#13) — Untested platform; web-based Copilot limitations - **Progress signals skill implementation** — Agents adopt milestone pattern - **Project Boards MVP** — Ralph integrates board context - ## By the Numbers - - **3 major spikes completed** (VS Code parity research) - **1 compatibility matrix published** (33 rows, 8 feature comparisons) - **1 proposal designed & approved** (agent progress updates) @@ -122,11 +82,7 @@ Issue: `npx github:bradygaster/squad` previously appeared to hang during install - **4 external contributors engaged** this sprint --- - ## The Vibe - This sprint was about **reducing uncertainty.** We came into v0.4.0 with questions: *Does Squad work on VS Code? What are the constraints? How do we show progress on long work?* - We shipped answers. VS Code users can adopt Squad without waiting for a v0.5.0 overhaul. Long-running work feels less like a black box. The compatibility matrix gives us a roadmap for what to test next. - Open source moves at the pace of clarity. We shipped that. diff --git a/docs/src/content/blog/010-v041-patch-release.md b/docs/src/content/blog/010-v041-patch-release.md index ece2206a5..e03ce5d57 100644 --- a/docs/src/content/blog/010-v041-patch-release.md +++ b/docs/src/content/blog/010-v041-patch-release.md @@ -7,45 +7,29 @@ tags: [squad, release, v0.4.1, patch, quality] status: published hero: "v0.4.1 lands five targeted fixes for logging, team setup, CLI UX, docs formatting, and blog chronology. Responsive to user feedback." --- - # v0.4.1: Quick Quality Patch - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _One week after 0.4.0, we shipped targeted fixes for the issues users hit first. Scribe now logs. Team templates match workflows. The CLI error noise is gone. Docs are clean. And your blog posts appear in order._ - ## What's Fixed - ### 1. Scribe Logging Regression (#56) The orchestration logger wasn't persisting across sessions. Scribe wasn't recording work. We fixed the session-state detection so logs flow to `orchestration-log/` consistently. Squadmates building together now have complete history. - ### 2. Team Template Header Mismatch (#58) Generated `team.md` files had a `Team Roster` header but the label-assignment workflow expected `Members`. One mismatched word broke the whole label-based task routing. Fixed — the header now matches the workflow expectations. - ### 3. CLI "Too Many Arguments" Error (#59) Post-0.4.0, the CLI was showing a persistent error message above the textbox. Parsing error noise on every interaction. Silenced it. The textbox is clean again. - ### 4. Docs Formatting Scrub (#64) Bad characters, escaped backticks, garbled emoji from encoding issues. Docs are now clean and render correctly across all browsers. - ### 5. Blog TOC Chronological Ordering (#65) Blog posts now show dates in the sidebar for clear timeline visibility. Posts sort chronologically with full date context. - ## Ship Speed - We committed to responsive patches: user-reported issues → fix within 48 hours → shipped. This is how we build trust with the community. - **Install v0.4.1:** ``` npm install -g @bradygaster/squad-cli@latest ``` - or upgrade if you have it: ``` npx @bradygaster/create-squad upgrade ``` --- - Thanks to everyone who reported bugs. Your feedback shaped this release. 🚀 diff --git a/docs/src/content/blog/011-skills-system-learning-from-work.md b/docs/src/content/blog/011-skills-system-learning-from-work.md index e9bc3d77b..b91b640a9 100644 --- a/docs/src/content/blog/011-skills-system-learning-from-work.md +++ b/docs/src/content/blog/011-skills-system-learning-from-work.md @@ -7,36 +7,20 @@ tags: [squad, skills, memory, learning, anthropic, open-standard] status: published hero: "Squad agents generate portable SKILL.md files from real work, codifying what they learned. Other tools make humans write skills by hand. Squad earns them." --- - # Skills System: Agents That Learn From Work - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _Squad agents generate portable SKILL.md files from real work, codifying what they learned. Other tools make humans write skills by hand. Squad earns them._ - ## The Problem - Agents without memory repeat the same mistakes. On session 1, an agent discovers a Jest testing pattern. On session 5, the same agent hits the same bug again because nothing persisted between sessions. - Solutions exist — `history.md` files capture agent learnings, `decisions.md` captures team agreements. But these are project-local and informal. There's no mechanism for carrying **portable, reusable patterns** from one project to another. When a Squad exports and moves to a new repo, agents start from zero. - That changed in v0.2.0 with the skills system. - ## How It Works - Skills are **earned domain knowledge** that changes how agents approach work. After completing a task, agents extract reusable patterns and write them to `.copilot/skills/{skill-name}/SKILL.md` using the Anthropic SKILL.md open standard. - Three categories exist: - 1. **Built-in skills** — shipped with Squad (e.g., `squad-conventions`, `label-driven-workflow`) 2. **Learned skills** — extracted from completed work (e.g., `jest-testing-patterns`, `ci-github-actions`) 3. **Imported skills** — acquired from plugin marketplaces or other squads - Skills are **portable**. When a squad exports, skills travel with the team. A squad that learned API testing patterns in Project A arrives at Project B already knowing how to write those tests. - ### Lifecycle - Skills evolve through four stages: | Stage | What Happens | @@ -49,43 +33,28 @@ Skills evolve through four stages: Confidence increases monotonically (never downgrades). Once a skill reaches `confidence: high` after 3+ successful applications, it's considered validated. ## The Design Story - The skills system was a three-way collaboration between **Brady** (product owner), **Kujan** (platform expert), and **Verbal** (prompt engineer). - ### Brady's Directive (2026-02-08) - > _"Skills adhering to Anthropic SKILL.md standard with MCP tool declarations."_ - This single sentence shaped the entire design: - 1. **SKILL.md standard** — not a Squad-specific format. Any tool can read Squad skills (Claude Code, Copilot, Windsurf). 2. **MCP tool declarations** — skills can specify which MCP tools they depend on (e.g., `github-issues-create`, `trello-create-card`). 3. **Portable by default** — skills are metadata files, not code. They travel via JSON export/import. - ### Verbal's Lifecycle Design (2026-02-08) - Verbal designed the skill lifecycle (acquisition → reinforcement → correction → deprecation) and the per-agent storage model. Initial design had skills stored at `.squad/agents/{name}/skills.md` (per-agent files). This was revised after Kujan's platform assessment. - ### Kujan's Platform Feasibility (2026-02-08) - Kujan validated that: - Skills stored separately from history enable clean export (history is project-specific, skills are portable) - The `store_memory` tool (Anthropic's skill persistence API) was the wrong model for Squad — filesystem persistence is Squad's architecture - File paths in agent charters are frozen API contracts (changing `.squad/agents/{name}/skills.md` to `.copilot/skills/` requires migration) - ### Open Standard Adoption (2026-02-09) - Squad adopted the Agent Skills Open Standard (agentskills.io) and the SKILL.md YAML frontmatter format. Directory structure changed from per-agent files to a flat `.copilot/skills/` directory. Skills are **team knowledge**, not agent-specific. - The final decision (Verbal, 2026-02-09): - > _"Skills in `.copilot/skills/{skill-name}/SKILL.md`. Coordinator injects `` XML for progressive disclosure (~50 tokens per skill at discovery). Skills portable beyond Squad — works in Claude Code, Copilot, any compliant tool."_ - ## Technical Details - ### SKILL.md Format - ```yaml + --- name: "jest-testing-patterns" description: "Test isolation patterns for Jest test suites" @@ -96,34 +65,26 @@ tools: - name: "run_tests" description: "Execute Jest test suite" when: "After writing or modifying tests" ---- +--- ## Context When and why this skill applies - ## Patterns Specific patterns, conventions, or approaches - ## Examples Code examples or references - ## Anti-Patterns What to avoid ``` - ### Discovery and Application - 1. **Coordinator reads** `.copilot/skills/` directory at session start 2. **Progressive disclosure**: Only skill names and descriptions are loaded initially (~50 tokens per skill) 3. **Agent spawns with context**: Spawn template says "check `.copilot/skills/{skill-name}/SKILL.md` if relevant" 4. **Agent reads full skill** when applicable to the task 5. **Agent applies pattern** from the skill 6. **Agent updates or extracts**: Bump confidence if validated, extract new skill if pattern discovered - ### Export/Import - Skills travel via the `squad-export.json` manifest: - ```json { "version": "1.0", @@ -134,78 +95,51 @@ Skills travel via the `squad-export.json` manifest: ] } ``` - When imported into a new squad: - Skill files are written to `.copilot/skills/{skill-name}/SKILL.md` - Agents read them before first spawn - Team arrives at the new project already competent - ## What This Enables - ### Compound Learning - v0.2.0 shipped skills, export/import, and per-agent model selection. v0.5.0 will ship the memory format skill (see parallel work on SEM format). Each feature makes the next easier: - - **Memory format skill** teaches agents how to write structured decisions/memories - **Skills system** makes that format portable - **Export/import** carries both the format skill and accumulated project skills to new repos - Agents get **smarter over time** within a project and carry that knowledge forward. - ### Plugin Marketplaces (v0.4.0) - The skills system is the foundation for plugin marketplaces. Community-authored skills for specific domains (AWS deployment, Kubernetes patterns, React testing) can be installed: - ```bash squad plugin marketplace add github:squad-plugins/official squad plugin install aws-deployment-patterns ``` - The skill appears at `.copilot/skills/aws-deployment-patterns/SKILL.md` and agents apply it on their next spawn. - ### Cross-Tool Compatibility - Because Squad uses the Anthropic open standard, skills work in: - - **Claude Code** (VS Code extension) - **GitHub Copilot** (if they adopt the standard) - **Windsurf** (Codeium's editor) - **Any tool** implementing agentskills.io - Users aren't locked into Squad. The knowledge is portable. - ## Stats - As of v0.2.0: - - **2 built-in skills** shipped with Squad (`squad-conventions`, `label-driven-workflow`) - **15+ learned skills** in Squad's own `.copilot/skills/` directory earned during dogfooding (GitHub Actions automation, Jekyll site deployment, Jest testing patterns, MCP tool discovery) - **0 npm dependencies** — pure markdown with YAML frontmatter - **~50 tokens per skill** at discovery (name + description only) - **Full content (~500-2000 tokens)** loaded only when agent needs it - ## Why This Matters - Most AI coding tools treat each session as isolated. Context window tricks (RAG, vector search, long-context models) help agents find relevant code, but they don't **change behavior**. An agent with 200K context can read your entire codebase but still makes the same architectural mistakes every session. - Skills are **behavioral**. They change what the agent does when it encounters a situation. A squad with the `ci-github-actions` skill writes workflows differently than a squad without it. The knowledge persists across sessions and travels across projects. - The breakthrough: **agents generate skills from work**. Other tools (GitHub Copilot, Cursor, Cody) don't have SKILL.md generation — humans write skill files by hand. Squad earns them automatically and stores them in the same `.squad/` directory that already tracks decisions and history. - ## What This Unlocks - Three features depend on skills existing: - 1. **Plugin marketplaces** (v0.4.0) — community-contributed skills for specialized domains 2. **Skill confidence metrics** (v0.6.0+) — analytics on which skills are validated and which are trial 3. **Cross-squad skill sharing** (v0.7.0+) — teams publish their best skills to a registry - The skills system is foundational. v0.2.0 planted the seed. Future versions harvest the returns. --- - ## Attribution - - **Design**: Verbal (prompt engineer) - **Platform validation**: Kujan (SDK expert) - **Open standard decision**: Verbal + Kujan @@ -214,5 +148,4 @@ The skills system is foundational. v0.2.0 planted the seed. Future versions harv - **Implementation**: Verbal (spawn templates), Fenster (`squad init` scaffolding), Hockney (skill extraction validation) --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/012-trending-on-github.md b/docs/src/content/blog/012-trending-on-github.md index e7b10db77..ca27a4089 100644 --- a/docs/src/content/blog/012-trending-on-github.md +++ b/docs/src/content/blog/012-trending-on-github.md @@ -7,69 +7,38 @@ tags: [squad, community, milestone, trending] status: published hero: "Squad hit #9 on GitHub Trending Developers today, February 19. Started February 7. 12 days from launch to GitHub's top trending." --- - # #9 on GitHub Trending Developers - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _Squad hit #9 on GitHub Trending Developers today, February 19. Started February 7. 12 days from launch to GitHub's top trending._ - ## What Happened - This morning, Brady discovered that Squad is the **#9 trending developer** on GitHub. The repo `bradygaster/squad` is the featured project. - The full trending list includes some company. Agentsys is at #3 with 42 agents and 13 plugins. Agent-of-empires is at #4 (Claude Code terminal session manager). Inbox-zero (AI email) is at #8. TinyUSB, Voicebox, and others fill the remainder. - The AI agent wave is real. And Squad is riding it. - ## Timeline - - **February 7** — Squad launched. First commit. First deploy. - **February 11** — Jeff Fritz published the first public video demo (131 passing tests). - **February 15** — v0.2.0 shipped. Skills system + export/import. Five new blog posts. - **February 19** — Trending Developers #9. - 12 days. No marketing. No announcement. Just a team building in public and a community that showed up. - ## What's Happening - The GitHub Trending list measures stars over a rolling window. The signal is real: people are starring Squad. Reading the repos they're linking, they're: - - **Trying it** — Cloning, running `npx create-squad`, spinning up teams - **Building with it** — Deploying Squad into real repos. Shipping real work with agent teams - **Talking about it** — Sharing links, testing variations, reporting bugs, suggesting features - The #9 spot is not a vanity metric. It's verification that the message landed: "Your code needs a team. Squad gives you one. Go build something." - ## Why Now - Three things converged: - 1. **The agent moment.** The industry moved from "AI writes code" (Copilot, Cursor) to "AI runs code" (Claude Code, Windsurf) to "AI **teams** write code" (Squad, agentsys, agent-of-empires). Users want delegation, not autocomplete. This wave lifted all boats. - 2. **The cast system.** The fact that agents have names, personalities, and persistent decisions — they're not generic numbered workers — is memorable. Developers talk about "our squad" the way they talk about "our team." Casting turned the abstract into the familiar. - 3. **Transparency.** Everything Squad creates lives in markdown in your repo. Decisions, history, skills, cast definitions — all visible, inspectable, portable. No proprietary databases. No lock-in. This built trust fast. - ## What This Unlocks - Trending changes three things: - **Discovery** — Developers who would never have found Squad now see it. First-time visitors are coming to the README with an open mind. - **Credibility** — Being #9 on GitHub is a third-party validation. "If GitHub's trending list cares, I should probably pay attention." - **Momentum** — Contributors, collaborators, and future squad members now know where to look. The project has visibility. Building Squad in public just became building Squad with an audience. - ## What's Next - This is a moment-in-time milestone. The real work is what happens after trending dies down — and it will. Trending is a sprint, not a strategy. The test is: Do people who starred today still use Squad in March? Do they file issues? Do they contribute? Do they build teams? - That's where the real story unfolds. - The 12-day arc from launch to #9 trending means one thing: we built something people genuinely want. Now we prove we can deliver on that promise. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/013-the-replatform-begins.md b/docs/src/content/blog/013-the-replatform-begins.md index 33f2d2908..777223af9 100644 --- a/docs/src/content/blog/013-the-replatform-begins.md +++ b/docs/src/content/blog/013-the-replatform-begins.md @@ -7,48 +7,28 @@ tags: [squad, replatform, typescript, architecture, sdk, cli] status: published hero: "We threw away everything that worked and rewrote Squad from scratch in TypeScript. Here's why that was the only honest move." --- - # The Replatform Begins - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _We threw away everything that worked and rewrote Squad from scratch in TypeScript. Here's why that was the only honest move._ - ## The Decision - Squad beta shipped fast. Twelve blog posts. Trending on GitHub. A community forming in real time. And underneath all of it, a JavaScript codebase held together with string parsing and good intentions. - Brady made the call on February 20: full replatform. Not a refactor. Not "add TypeScript gradually." A clean-room rewrite with strict typing, ESM modules, and a proper package architecture. - The reason was simple. Squad was growing faster than the codebase could support. Every new feature — skills, upstream inheritance, multi-client support — required touching parsers that had no type safety. Agent charters were parsed with regex. Routing rules were string-matched. The adapter layer between Squad and `@github/copilot-sdk` was a single file with `as any` casts on every boundary. It worked. Until it didn't. - ## The Architecture - The replatform split Squad into two packages inside an npm workspace: - - **`@bradygaster/squad-sdk`** — The core runtime. Agent loading, casting, routing, tools, OpenTelemetry, upstream inheritance. Everything that makes Squad work. Zero CLI dependencies. Safe to import from VS Code extensions without risking `process.exit()` crashes. - **`@bradygaster/squad-cli`** — The entry point. Interactive shell, commands (`init`, `status`, `doctor`, `link`), REPL chrome. Depends on the SDK. Ships as a global binary via `npm install -g @bradygaster/squad-cli`. - The split solved three problems at once: - 1. **Library safety.** SquadUI (the VS Code extension) needs to import SDK functions. In beta, importing anything from Squad pulled in the CLI entry point, which called `process.exit()`. The extension host would crash. SDK/CLI separation makes library imports safe by construction. 2. **Independent versioning.** The SDK can ship a patch without touching the CLI. The CLI can add a command without bumping the SDK. Changesets handles independent version management across the workspace. 3. **Strict typing everywhere.** TypeScript strict mode. No `any`. No implicit returns. No untyped event handlers. The compiler catches what beta's runtime errors used to catch — in production. - The npm workspace approach (`"workspaces": ["packages/*"]`) means one `npm install`, one `npm run build`, one `vitest run` across both packages. Development feels like a monolith. Publishing feels like microservices. - ## What Changed Under the Hood - Everything. But the important parts: - - **ESM-only.** No CommonJS. No dual-mode. `"type": "module"` in every `package.json`. Node.js ≥20 required. - **Vitest over node:test.** Beta used `node:test` and `node:assert`. The replatform moved to Vitest for snapshot testing, coverage, and watch mode. The test count went from 131 (beta peak) to 2,232 by the time Wave 3 shipped. - **esbuild for bundling.** Fast builds. No webpack config files. No Rollup plugins. Just esbuild. - **Barrel exports.** Every public API surfaces through `packages/squad-sdk/src/index.ts`. One import path: `import { resolveSquad, loadConfig, CastingEngine } from '@bradygaster/squad-sdk'`. - ## The Wave Plan - Brady didn't just replatform — he structured the work into waves. Each wave had a theme, a PR, and a definition of done: | Wave | Theme | PR | @@ -60,11 +40,8 @@ Brady didn't just replatform — he structured the work into waves. Each wave ha The waves weren't arbitrary. Wave 1 gave Squad eyes (telemetry). Wave 2 gave Squad a voice (the interactive shell). Wave 3 gave Squad a memory (documentation that teaches). Each wave built on the last. ## What's Next - Wave 1 starts immediately. OpenTelemetry integration, Aspire dashboard, and the SquadObserver file watcher. The goal: when agents work, you can see what they're doing — not in log files, but in real-time traces and metrics. - The replatform is the foundation. The waves are the house. Time to build. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/014-wave-1-otel-and-aspire.md b/docs/src/content/blog/014-wave-1-otel-and-aspire.md index 0eaecea3a..fde6b62b1 100644 --- a/docs/src/content/blog/014-wave-1-otel-and-aspire.md +++ b/docs/src/content/blog/014-wave-1-otel-and-aspire.md @@ -7,54 +7,30 @@ tags: [squad, wave-1, otel, aspire, observability, telemetry] status: published hero: "Multi-agent systems without observability are black boxes. Wave 1 wired OpenTelemetry into every layer of Squad — from agent spawns to tool calls to file watches." --- - # Wave 1: Giving Squad Eyes - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _Multi-agent systems without observability are black boxes. Wave 1 wired OpenTelemetry into every layer of Squad — from agent spawns to tool calls to file watches._ - ## The Problem - In the beta, when something went wrong — an agent hung, a routing decision misfired, a tool call returned garbage — you had two diagnostic tools: `history.md` and `console.log`. History files told you what agents claimed happened. Console output told you what the CLI printed. Neither told you what actually happened inside the runtime. - For a single-agent system, that's annoying. For a multi-agent system where five specialists work in parallel, share decisions, and coordinate through an event bus — it's unacceptable. You can't debug what you can't see. - Wave 1 gave Squad eyes. - ## The 3-Layer OTel API - The OpenTelemetry integration landed across PRs #307 and #308, covering issues #254 through #268. The design uses three layers, each for a different audience: - **Layer 1 — Low-level control.** `initializeOTel()`, `shutdownOTel()`, `getTracer()`, `getMeter()`. For developers who want full control over their tracing pipeline. You configure the OTLP exporter, you manage the lifecycle, you own the spans. This is the escape hatch. - **Layer 2 — EventBus bridge.** `bridgeEventBusToOTel()` and `createOTelTransport()`. Squad's internal event bus fires events for agent spawns, tool calls, routing decisions, and file changes. Layer 2 automatically converts those events into OTel spans. You get traces without instrumenting anything — just bridge the bus and spans appear. - **Layer 3 — One-liner init.** `initSquadTelemetry()` returns a lifecycle handle. Call it at startup, call `shutdown()` at exit. Everything else is automatic. This is what most users want. - The key design decision: **zero overhead when unused.** If no `TracerProvider` is configured, every OTel call is a no-op. No span allocation. No metric recording. No performance cost. Squad doesn't penalize you for not using telemetry. - ## SquadObserver: The File Watcher - Issue #268 introduced `SquadObserver`, a file watcher that monitors the `.squad/` directory and emits events when agents write files. Combined with the OTel bridge, this means: - - Agent writes to `history.md` → file change event → OTel span - Agent creates a skill → file change event → OTel span - Agent updates `decisions.md` → file change event → OTel span - Every file mutation by every agent becomes a traceable event. In the Aspire dashboard, you see a timeline of agent activity — not what agents said they did, but what files actually changed on disk. - ## Aspire Dashboard Integration - The `squad aspire` command (#265) wires Squad's OTLP exporter to a Aspire dashboard. Aspire gives you: - - **Trace waterfall** — See agent spawns, tool calls, and file writes as a timeline - **Metrics** — Agent spawn counts, tool call durations, event bus throughput - **Structured logs** — Every span carries attributes (agent name, tool name, file path) - The integration is optional. Squad doesn't depend on .NET or Aspire. But if you're running Aspire (common in .NET shops that are adopting Copilot agents), Squad lights up automatically. - ## By the Numbers | Metric | Value | @@ -67,15 +43,11 @@ The integration is optional. Squad doesn't depend on .NET or Aspire. But if you' | New SDK exports | 8 (initializeOTel, shutdownOTel, getTracer, getMeter, bridgeEventBusToOTel, createOTelTransport, initSquadTelemetry, SquadObserver) | ## What We Learned - - **Observability isn't optional for multi-agent systems.** Single-agent debugging is print statements. Multi-agent debugging is distributed tracing. The same tools that work for microservices — traces, spans, metrics — work for agent coordination. OTel was the right bet. - **The EventBus bridge pattern is powerful.** Instead of instrumenting every function, we instrument the event bus once. Every new event type gets tracing for free. This scales with the codebase without scaling instrumentation effort. - **Zero-overhead matters more than features.** The biggest adoption risk for telemetry is performance fear. Making every OTel call a provable no-op when unconfigured removes the objection entirely. - ## What's Next - Wave 1 gave Squad the ability to see. Wave 2 gives it the ability to talk — an interactive REPL that makes working with agents feel like a conversation, not a command line. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/015-wave-2-the-repl-moment.md b/docs/src/content/blog/015-wave-2-the-repl-moment.md deleted file mode 100644 index f55c35e94..000000000 --- a/docs/src/content/blog/015-wave-2-the-repl-moment.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "Wave 2: The REPL Moment" -date: 2026-02-21 -author: "McManus (DevRel)" -wave: 2 -tags: [squad, wave-2, repl, shell, security, testing, developer-experience] -status: published -hero: "We built an interactive shell that makes you forget you're talking to agents. Then we found a command injection vulnerability and fixed it the same day." ---- - -# Wave 2: The REPL Moment - -> 📌 **Archive note:** The interactive shell described in this post has been deprecated. For the best Squad experience, use the [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli). See [Choose your interface](/docs/get-started/choose-your-interface/) for current options. - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - -> _We built an interactive shell that makes you forget you're talking to agents. Then we found a command injection vulnerability and fixed it the same day._ - -## The Wow Moment - -PR #309 shipped the feature that changed how Squad feels. Not how it works — how it *feels*. - -Type `squad` with no arguments. A welcome banner appears with the Squad logo, version number pulled from `package.json` (no hardcoded strings), and a prompt. Type a message. Agents respond with streaming output. Emoji markers show who's working. The session persists — agents remember what you said three messages ago. - -It sounds simple. It was not simple. The REPL needed to: - -- Stream agent responses token-by-token (no waiting for complete responses) -- Display a welcome banner with dynamic version info -- Handle multi-agent output interleaved on the same terminal -- Track session state across messages (agent registry, routing context, casting decisions) -- Exit cleanly without orphaned processes - -The result is an interactive shell that feels like a conversation. Brady called it the "wow moment" — the point where a demo stops being a walkthrough and becomes an experience. You sit someone down, type `squad`, and they get it. - -## The Security Fix - -While building the REPL, we found CWE-78: OS Command Injection. The beta used `execSync()` to run shell commands from agent tool calls. That's a classic injection vector — if an agent constructs a command string from user input, arbitrary code execution is one backtick away. - -The fix: replace every `execSync()` call with `execFileSync()`. The difference is fundamental: - -- `execSync("git status " + userInput)` — shell interprets `userInput`. If it contains `; rm -rf /`, you're done. -- `execFileSync("git", ["status", userInput])` — no shell. Arguments are passed directly to the process. Injection is structurally impossible. - -This landed in the same PR. No separate security advisory. No drama. Just the right fix in the right place at the right time. CWE-78 closed. - -## Config Extraction - -Wave 2 also extracted hardcoded values into `constants.ts`. Model names, timeout values, agent roles, file paths — all the magic strings scattered across the beta codebase got pulled into typed constants: - -- `MODELS` — every supported model with provider and tier -- `TIMEOUTS` — spawn timeout, polling interval, shutdown grace period -- `AGENT_ROLES` — the cast system's role definitions - -This isn't glamorous work. It's the kind of refactoring that makes every future feature cheaper to build. When Wave 3 needed to reference model names in documentation, the constants were already there. When the adapter hardening sprint needed timeout values, they were already typed. - -## 119 New Tests - -The replatform started with zero tests (clean room, remember?). Wave 1 added integration tests for OTel. Wave 2 added 119 tests covering: - -- Shell initialization and teardown -- Command routing and argument parsing -- Agent spawn lifecycle -- Config loading and validation -- REPL streaming output -- Session state persistence - -Plus an Aspire Playwright E2E test that launches the full stack — Squad CLI, agent runtime, OTel exporter, Aspire dashboard — and verifies traces appear in the UI. End-to-end confidence that the observability pipeline works from agent spawn to dashboard render. - -The test count after Wave 2: meaningful. The test count by Wave 3 completion: 2,232 across 85 test files. The REPL work established the testing patterns that scaled. - -## By the Numbers - -| Metric | Value | -|--------|-------| -| PR | #309 | -| New tests | 119 | -| Security fixes | 1 (CWE-78) | -| Config constants extracted | 3 modules (MODELS, TIMEOUTS, AGENT_ROLES) | -| Hardcoded strings removed | All | -| REPL features | Welcome banner, streaming, emoji, session persistence | - -## What We Learned - -- **Developer experience is a feature.** The REPL doesn't add capabilities Squad didn't have. It makes existing capabilities accessible. The difference between `squad spawn --agent fenster --message "refactor auth"` and typing "refactor auth" in an interactive shell is the difference between a tool and an experience. -- **Security fixes belong in feature PRs.** Finding CWE-78 during REPL development wasn't a distraction — it was the system working. You find security bugs when you're deep in the code. Ship the fix with the feature. Don't create a separate ticket and let it age. -- **Constants are infrastructure.** Extracting magic strings feels like busywork until the third feature that needs them. Then it feels like foresight. - -## What's Next - -Wave 2 gave Squad a voice. Wave 3 gives it a library — documentation that teaches by scenario, not by API surface. The docs engine, 5 initial guides, and a custom site generator. - ---- - -_This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/016-wave-3-docs-that-teach.md b/docs/src/content/blog/016-wave-3-docs-that-teach.md index 7f036c175..74d417a91 100644 --- a/docs/src/content/blog/016-wave-3-docs-that-teach.md +++ b/docs/src/content/blog/016-wave-3-docs-that-teach.md @@ -7,52 +7,34 @@ tags: [squad, wave-3, docs, site-generator, markdown-it, guides] status: published hero: "We built a docs engine from scratch because the docs should teach you how to solve problems, not how to call functions." --- - # Wave 3: Docs That Teach - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _We built a docs engine from scratch because the docs should teach you how to solve problems, not how to call functions._ -## The Philosophy +> **Historical note:** This post describes Squad's first docs overhaul (Wave 3, early 2026). The docs site has since been updated — this wave built the foundation; later posts describe what changed next. +## The Philosophy Most developer docs are organized by API surface. Here's the `loadConfig` function. Here are its parameters. Here's a return type. Good luck. - That's reference material, not documentation. Reference material answers "what does this do?" Documentation answers "how do I solve this problem?" - Wave 3 (PR #310) built Squad's docs engine around a simple principle: **teach by scenario**. Don't start with the API. Start with the problem. "I want to set up a squad for my React project." "I want agents to share knowledge across repositories." "I want to see what my agents are doing in real time." Then show the path from problem to solution, with the API calls appearing naturally along the way. - ## The Engine - We needed a static site generator. We didn't need Hugo, Jekyll, Docusaurus, or Gatsby. We needed something that: - 1. Reads markdown files from `docs/` subdirectories 2. Converts them to HTML with syntax highlighting 3. Generates navigation from the directory structure 4. Outputs static files to `docs/dist/` 5. Works with `node docs/build.js` — no dependencies beyond what's in the workspace - So we built one. `docs/build.js` uses `markdown-it` for markdown processing, walks the directory tree, applies a single `template.html`, and generates a static site. The build is fast — 62 pages in under a second. - The template system is intentionally minimal. One HTML template. One CSS file. One JavaScript file for theme toggling and search. No build pipeline. No React. No framework. Just markdown in, HTML out. - ## The Initial Guides - Wave 3 shipped 5 guides covering the core paths: - 1. **Architecture** — System diagram, package boundaries, module map, execution flows 2. **Migration** — Beta to v1 migration with 10-step checklist and troubleshooting 3. **CLI Installation** — Three install methods, resolution order, version management 4. **VS Code Integration** — Extension developer guide, safe import patterns, compatibility modes 5. **SDK API Reference** — Every public export from `@bradygaster/squad-sdk`, grouped by domain - Each guide follows the scenario-first pattern. The architecture guide doesn't start with "here are the modules." It starts with "here's what happens when you type `squad`." The migration guide doesn't start with "here are the breaking changes." It starts with "you have a beta squad and you want to move to v1." - ## Issues Closed - Wave 3 touched a broad set of documentation issues: #185, #188, #191, #192, #195, #196, #199, #201, #203, #206, #207. Each issue represented a gap — a question that a developer would ask and find no answer for. The guides fill those gaps. - ## By the Numbers | Metric | Value | @@ -65,15 +47,11 @@ Wave 3 touched a broad set of documentation issues: #185, #188, #191, #192, #195 | Framework dependencies | 0 | ## What We Learned - - **Scenario-first docs convert better.** When a developer lands on "How do I migrate from beta?" they stay. When they land on "loadConfig() API reference" they bounce. The scenario is the hook. The API is the payload. - **Custom beats framework for small sites.** Docusaurus would have taken longer to configure than `build.js` took to write. For a docs site with no dynamic content, a 200-line build script is the right tool. - **Five guides is the right starting number.** Enough to cover the core paths. Not so many that you can't maintain quality. The guides expand from here, but the first five set the tone. - ## What's Next - The docs engine is built. The initial guides are live. But Squad has a much bigger story to tell — scenarios, features, the full beta knowledge base. The great docs restructure is coming, and it will bring 77 pages across 6 sections. But first, we need to align versions and ship to npm. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/017-version-alignment.md b/docs/src/content/blog/017-version-alignment.md index b0234b66d..55fd3a3d8 100644 --- a/docs/src/content/blog/017-version-alignment.md +++ b/docs/src/content/blog/017-version-alignment.md @@ -7,70 +7,42 @@ tags: [squad, release, versioning, npm, publishing, ci] status: published hero: "The CLI was at 0.8.1. The SDK was at 0.8.0. The root was at 0.6.0-alpha.0. We snapped everything to 0.8.2 and published to npm. Then CI told us what we got wrong." --- - # Snapping to 0.8.2 - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _The CLI was at 0.8.1. The SDK was at 0.8.0. The root was at 0.6.0-alpha.0. We snapped everything to 0.8.2 and published to npm. Then CI told us what we got wrong._ - ## The Version Drift Problem - After three waves of development, Squad's version numbers were a mess. The npm workspace has three `package.json` files, and each had drifted independently: - - **Root** (`@bradygaster/squad`): `0.6.0-alpha.0` - **SDK** (`@bradygaster/squad-sdk`): `0.8.0` - **CLI** (`@bradygaster/squad-cli`): `0.8.1` - This happens naturally in a workspace with independent versioning. The SDK ships a feature, bumps to 0.8.0. The CLI ships a command that uses that feature, bumps to 0.8.1. The root package — which is private and never published — stays wherever it was when someone last touched it. - The problem: when users run `squad --version`, they see the CLI version. When they import from `@bradygaster/squad-sdk`, they see the SDK version. When they look at the root `package.json`, they see a third version. Three numbers, none matching, all claiming to be "Squad." - ## The Fix - One commit. Tag `v0.8.2`. All three packages snapped to `0.8.2`: - ``` chore: align CLI and SDK versions to 0.8.2 ``` - Published to npm as: - `@bradygaster/squad-sdk@0.8.2` - `@bradygaster/squad-cli@0.8.2` - The root stays private (`"private": true`) but matches the published version for developer sanity. When you clone the repo and look at `package.json`, the number makes sense. - ## The CI Discovery - Publishing to npm surfaced a workflow bug. The `publish.yml` GitHub Action (#305) was wired to trigger on release creation, build both packages, and publish with `npm publish --access public`. The workflow worked — but only after fixing the build order. - The CLI depends on the SDK. If you publish the CLI before the SDK, npm can't resolve `@bradygaster/squad-sdk` as a dependency because it doesn't exist yet (or exists at the wrong version). The fix: build and publish SDK first, then CLI. Sequential, not parallel. - This is the kind of bug you only find by actually publishing. Local `npm run build` works because the workspace resolves packages from disk, not from the registry. CI publishes to the real registry, where order matters. - ## Independent Versioning Going Forward - The v0.8.2 snap was a one-time alignment. Going forward, the SDK and CLI version independently using Changesets: - ```bash npx changeset # describe what changed npx changeset version # bump versions npm publish # push to registry ``` - A CLI bugfix bumps `@bradygaster/squad-cli` without touching the SDK. An SDK feature bumps `@bradygaster/squad-sdk` without touching the CLI. The versions will diverge again — and that's fine. The workspace supports it. What matters is that the *starting point* is clean. - ## What We Learned - - **Version alignment is a release, not a refactor.** We treated the snap as a proper release: tagged commit, npm publish, CI validation. Not a silent `package.json` edit buried in a feature branch. - **Publish order matters in workspaces.** Local builds resolve from disk. CI builds resolve from the registry. If package B depends on package A, publish A first. Always. - **Three versions is two too many for users.** Users don't care about workspace architecture. They see one tool. It should have one version number — or at minimum, version numbers that make sense together. - ## What's Next - With versions aligned and packages on npm, the next challenge is closer to the metal: the adapter layer between Squad and `@github/copilot-sdk` has unsafe type casts that need to go. A P0 bug in Codespaces is about to make that very urgent. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/018-the-adapter-chronicles.md b/docs/src/content/blog/018-the-adapter-chronicles.md index b3860526c..785afbe35 100644 --- a/docs/src/content/blog/018-the-adapter-chronicles.md +++ b/docs/src/content/blog/018-the-adapter-chronicles.md @@ -7,28 +7,16 @@ tags: [squad, adapter, copilot-sdk, typescript, type-safety, codespace, bug] status: published hero: "A P0 crash in Codespaces led to a 7-issue sprint that eliminated every unsafe cast in Squad's adapter layer. Zero `as any` remaining." --- - # The Adapter Chronicles - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _A P0 crash in Codespaces led to a 7-issue sprint that eliminated every unsafe cast in Squad's adapter layer. Zero `as any` remaining._ - ## The P0 - Issue #315 came in hot. Squad running in GitHub Codespaces threw: - ``` TypeError: sendMessage is not a function ``` - The `@github/copilot-sdk` session object in Codespaces exposes `send()`, not `sendMessage()`. Squad's adapter assumed the method name. In the CLI, the session object happened to have `sendMessage()` (or something close enough that `as any` hid the mismatch). In Codespaces, the mask came off. - This is the failure mode of `as unknown as TargetType` — it compiles, it passes tests in one environment, and it crashes in another. The cast tells TypeScript "trust me." TypeScript trusts you. The runtime doesn't. - ## The CopilotSessionAdapter - The fix for #315 wasn't a one-line method rename. The session API surface differs between environments: | Method | CLI Session | Codespace Session | @@ -42,46 +30,28 @@ Patching each call site would mean environment-specific branching scattered acro - `send()` → delegates to whatever the underlying session calls its send method - `on(event, handler)` → always returns an unsubscribe function (wraps if needed) - `destroy()` → calls `close()` or `destroy()` depending on what exists - One adapter. One interface. Every consumer talks to the adapter, never to the raw session. The environment differences are absorbed in one place. - ## The 7-Issue Sprint - With #315 fixed, Brady opened issues #316 through #322 — a systematic sweep of the adapter layer. Each issue targeted a specific category of unsafe code: - **#316 — Unsafe casts in event handlers.** Event callbacks typed as `any`. Replaced with typed payloads for each event. - **#317 — EVENT_MAP.** Built a typed mapping object with 10 entries connecting Squad's internal event names to `@github/copilot-sdk` event names. No more string literals scattered across files. - **#318 — Field mapping.** Agent fields like `name`, `role`, and `expertise` mapped through typed field accessors instead of bracket notation with string keys. - **#319 — Response type casts.** Agent responses cast from `unknown` to expected shapes. Replaced with runtime validation — check the shape, then narrow the type. - **#320 — Session lifecycle.** Startup and shutdown sequences used `as any` to bridge async/sync mismatches. Replaced with proper `async`/`await` and typed return values. - **#321 — Tool registration.** Tool definitions passed to `@github/copilot-sdk` with cast parameters. Replaced with a typed `defineTool()` helper that constructs the correct shape. - **#322 — Dead code removal.** With typed adapters in place, several compatibility shims and fallback paths became unreachable. Removed them. - ## The Result - After the sprint: - - **Zero `as any` in the adapter layer.** Not reduced. Zero. - **Zero `as unknown as` patterns.** The anti-pattern that caused #315 is structurally impossible now. - **EVENT_MAP with 10 typed entries.** Every event has a name, a payload type, and a handler signature. - **CopilotSessionAdapter as the single integration point.** One file mediates between Squad and the SDK. One file to audit. One file to update when the SDK changes. - ## What We Learned - - **`as any` is technical debt with compound interest.** Every unsafe cast works until it doesn't. The cost of finding the failure (P0 in production) dwarfs the cost of typing it correctly from the start. The replatform's strict mode mandate exists for exactly this reason. - **Adapter patterns absorb environmental differences.** The Codespace session isn't wrong. The CLI session isn't wrong. They're different. The adapter's job is to make different things look the same to consumers. Classic GoF, still correct. - **Sprint the sweep.** Seven issues filed and closed in sequence. Not a backlog item that ages for weeks. When you find a category of bugs, sweep the category. Don't fix one and hope the others don't bite. - ## What's Next - The adapter layer is clean. The type system is honest. Now it's time to bring in a feature from the beta that the community has been asking about: remote squad mode. And it comes with a story about team collaboration. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/019-shaynes-remote-mode.md b/docs/src/content/blog/019-shaynes-remote-mode.md index 21a6df5fd..90b6edd0e 100644 --- a/docs/src/content/blog/019-shaynes-remote-mode.md +++ b/docs/src/content/blog/019-shaynes-remote-mode.md @@ -7,57 +7,31 @@ tags: [squad, remote-mode, community, spboyer, doctor, link, collaboration] status: published hero: "Shayne Boyer built remote squad mode in the beta. We ported it to the replatform — and it taught us something about how teams actually work." --- - # Shayne's Remote Mode - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _Shayne Boyer built remote squad mode in the beta. We ported it to the replatform — and it taught us something about how teams actually work._ - ## The Origin - Back in the beta repo, [@spboyer](https://github.com/spboyer) (Shayne Boyer) opened PR [bradygaster/squad#131](https://github.com/bradygaster/squad/pull/131) with a feature that solved a real problem: what happens when your squad's identity — the charters, decisions, skills, casting policy — lives in a different repository than the project you're working on? - Think about it. A platform team maintains a shared squad configuration. Twelve product teams use that squad. In the beta model, each product team copies `.squad/` into their repo. Now you have twelve copies. Twelve copies that drift. Twelve copies that need manual sync when the platform team updates a decision. - Remote mode says: don't copy. Link. Your project has its own `.squad/` for project-local state (history, workspace config). But the team identity — who the agents are, how they route, what they know — lives somewhere else. One source of truth. Twelve projects pointing at it. - ## What We Ported - Issues #311 through #314 adapted Shayne's design for the replatform's TypeScript architecture: - **`resolveSquadPaths()` — Dual-root resolver (#311).** The core primitive. Given a project directory, resolve two paths: the project-local `.squad/` (for workspace state) and the team root (for identity). If no remote link exists, both paths point to the same place. If a link exists, they diverge. - **`squad doctor` — Setup validation (#312).** Nine checks with emoji output. Does `.squad/` exist? Is it linked? Can Squad reach the team root? Are charters loadable? Is the SDK version compatible? Doctor doesn't fix things — it tells you what's wrong so you can fix it. The output is deliberately human-readable, not machine-parseable. - **`squad link ` — Link a project (#313).** Point your project at a remote team root. The command writes a `.squad/.remote` config file with the path. From that point, Squad resolves team identity from the linked location. - **`squad init --mode remote` — Initialize with remote config (#313).** Like `squad init`, but sets up the dual-root structure from the start. Creates the local `.squad/` directory and the `.remote` config in one step. - **`ensureSquadPathDual()` / `ensureSquadPathResolved()` — Write guards (#314).** The replatform's `ensureSquadPath()` guard validates that `.squad/` exists before writing. The dual-root variants extend this to check both the local path (for workspace writes) and the team root (for identity reads). Writes always go local. Reads resolve through the chain. - ## Credit Where It's Due - This feature is Shayne's. The design — separate identity from workspace, link don't copy, resolve through a chain — came from his PR. The replatform ported the concept into TypeScript with strict typing, added the doctor command and write guards, and integrated it with the dual-root resolver pattern. But the idea, the insight that teams need shared squad identities across projects, was Shayne's contribution to the beta. - The CHANGELOG entry reads: - > **Added — Remote Squad Mode (ported from @spboyer's [bradygaster/squad#131](https://github.com/bradygaster/squad/pull/131))** - That's not a courtesy attribution. That's accurate history. - ## How Teams Actually Work - Remote mode revealed something about how development teams use Squad in practice. The assumption was: one repo, one squad. The reality: - - **Platform teams** maintain squad configurations that flow to product teams - **Consultancies** share a methodology squad across client projects - **Open source maintainers** publish a squad configuration that contributors link to - **Enterprise teams** post-acquisition merge two squad configurations into one - The common thread: identity is shared, workspace is local. Decisions, skills, and casting policy are organizational. History and runtime state are per-project. Remote mode makes that separation explicit and manageable. - ## By the Numbers | Metric | Value | @@ -69,15 +43,11 @@ The common thread: identity is shared, workspace is local. Decisions, skills, an | New SDK functions | 4 (resolveSquadPaths, ensureSquadPathDual, ensureSquadPathResolved, plus init mode) | ## What We Learned - - **Port the design, not just the code.** Shayne's beta implementation was JavaScript. We didn't transliterate it to TypeScript. We understood the design — dual roots, link-not-copy, resolve chain — and re-implemented it with the replatform's patterns (strict types, write guards, constants). - **Doctor commands pay for themselves.** Nine checks. Three minutes to run. Saves hours of debugging when something is misconfigured. Every CLI tool should have a doctor command. - **Credit the origin.** Remote mode works because Shayne saw the problem first. Open source runs on attribution. When you port someone's feature, say so. - ## What's Next - Remote mode completes the replatform's feature set. What's left is the biggest docs effort yet — restructuring everything we've built into a site that developers can actually navigate. 77 pages. 6 sections. The great docs restructure. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/020-docs-reborn.md b/docs/src/content/blog/020-docs-reborn.md index ef55a3a92..805a0e1ab 100644 --- a/docs/src/content/blog/020-docs-reborn.md +++ b/docs/src/content/blog/020-docs-reborn.md @@ -7,24 +7,13 @@ tags: [squad, docs, github-pages, restructure, dark-mode, search, site-generator status: published hero: "77 pages across 6 sections. Dark mode. Client-side search. Sidebar navigation. The beta's best UI, rebuilt for v1's content. Squad's docs are a real site now." --- - # Docs Reborn - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - > _77 pages across 6 sections. Dark mode. Client-side search. Sidebar navigation. The beta's best UI, rebuilt for v1's content. Squad's docs are a real site now._ - ## What Happened - The replatform created a documentation problem. Three waves of development produced 5 guides, an SDK API reference, and a CHANGELOG. The beta repo had 21 scenario docs, 23 feature docs, and 5 top-level guides. All of it lived in markdown files scattered across two repositories, two directory structures, and two naming conventions. - Developers couldn't find anything. The v1 guides were in `docs/guide/`. The beta scenarios were in a different repo entirely. There was no navigation, no search, no way to browse. If you didn't know the exact file path, you didn't find the doc. - The restructure fixed all of it. - ## The New Structure - Six sections, each with a clear purpose: | Section | What's In It | Pages | @@ -39,39 +28,25 @@ Six sections, each with a clear purpose: The directory structure mirrors the sections: `docs/guide/`, `docs/cli/`, `docs/sdk/`, `docs/features/`, `docs/scenarios/`, `docs/blog/`. The build script walks each directory and generates navigation automatically. Add a markdown file, run `node docs/build.js`, and it appears in the sidebar. ## Porting the Beta UI - The beta site (from `bradygaster/squad`) had a good-looking docs UI: dark mode, sidebar navigation, search, responsive layout. We ported it wholesale to the replatform. - **Dark mode** uses CSS custom properties with `prefers-color-scheme` detection and a manual toggle. The theme persists in `localStorage` under the `squad-theme` key. Three states: auto (follows system), dark, light. Toggle button shows ☀️, 🌙, or 💻. - **Search** is client-side. The build script generates a JSON search index — title, href, and a text preview for every page. The search box filters the index in real time and shows a dropdown of matching results. No server. No Algolia. No API keys. Just JavaScript and a JSON array. - **Sidebar navigation** is generated from the directory structure. Each section becomes a `
` element (collapsible). Pages within sections are alphabetically ordered. The current page is highlighted. On mobile, the sidebar slides in from the left. - Credit to [@spboyer](https://github.com/spboyer) for the original beta site CSS and JS patterns that we ported. - ## The Tone Pass - Every ported document got a tone pass: - - **Removed "⚠️ INTERNAL ONLY" banners.** The v1 docs are public now. - **Updated CLI commands.** `npx github:bradygaster/squad` → `npx @bradygaster/squad-cli`. npm is the only distribution path. - **Preserved the beta voice.** The scenario docs and feature docs were written in a conversational, prompt-first style. We kept that. No corporate rewrite. - 62 documents. Each one touched. The goal was consistency without homogeneity — every doc should feel like it belongs on the same site without every doc sounding like the same author wrote it. - ## The GitHub Pages Pipeline - The `.github/workflows/squad-docs.yml` workflow deploys to GitHub Pages on every push to `main`: - 1. Checkout repo 2. `npm ci` (install dependencies) 3. `npm run docs:build` (runs `node docs/build.js`) 4. Upload `docs/dist/` as artifact 5. Deploy to GitHub Pages - Build time is under 10 seconds for 77 pages. The site updates within minutes of a merge to main. No manual deployment. No staging server. Push markdown, get a website. - ## By the Numbers | Metric | Value | @@ -85,17 +60,12 @@ Build time is under 10 seconds for 77 pages. The site updates within minutes of | Tests passing | 2,232 across 85 test files | ## What We Learned - - **Port the content, not just the structure.** Downloading 49 markdown files from the beta repo was the easy part. The tone pass — updating commands, removing internal markers, fixing URLs — took longer than the download. Content migration is editorial work, not file copying. - **Scenario-first organization works.** The six-section structure puts "what can I do with this?" (scenarios, features) ahead of "how does this work?" (SDK, CLI). Developers browse scenarios first and drill into reference material when they need specifics. - **Dark mode is table stakes.** The beta site had it. The v1 site has it. Every developer docs site should have it. It's not a feature. It's an expectation. - ## What's Next - This is where the replatform blog catches up to the present. Eight posts covering the full arc: from the decision to rewrite, through three waves of development, a version alignment, an adapter hardening sprint, a community contribution, and a docs restructure. - The foundation is solid. The docs are live. The CLI is published. The SDK is typed. The adapter is clean. What comes next is what the community builds on top of it. --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/021-the-migration.md b/docs/src/content/blog/021-the-migration.md index eafc2c838..256789e85 100644 --- a/docs/src/content/blog/021-the-migration.md +++ b/docs/src/content/blog/021-the-migration.md @@ -7,45 +7,31 @@ tags: [squad, migration, npm, distribution, github, public-repo, release] status: published hero: "Squad moves from private repo (bradygaster/squad-pr) to public (bradygaster/squad). New install path. Unified distribution. v0.5.4 → v0.8.18. Here's what changed and how to upgrade." --- - # The Migration: Private to Public, GitHub to npm - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - > _Squad moves from private repo (bradygaster/squad-pr) to public (bradygaster/squad). New install path. Unified distribution. v0.5.4 → v0.8.18. Here's what changed and how to upgrade._ - ## What Moved - The Squad SDK has moved from a **private repository** (`bradygaster/squad-pr`) to a **public repository** (`bradygaster/squad`). This is a clean separation between: - - **Old distribution:** GitHub-native (`npx github:bradygaster/squad`) — removed. No longer supported. - **Old versioning:** Beta users tracked commits in a private repo; no semantic versioning. - **Old packages:** A monolithic `@bradygaster/create-squad` package bundled the CLI and SDK. - ## What Changed for Users - ### Install Commands - **Beta users (v0.5.4) on the old path:** ```bash # DEPRECATED — do not use npx github:bradygaster/squad ``` - **New users and upgraders (v0.8.18) on npm:** ```bash # Install globally npm install -g @bradygaster/squad-cli - # Or use npx (no install) npx @bradygaster/squad-cli ``` - **For SDK integration in TypeScript projects:** ```bash npm install @bradygaster/squad-sdk ``` - ### Package Names | Aspect | Beta | Current | @@ -56,154 +42,101 @@ npm install @bradygaster/squad-sdk | Repository | private | [bradygaster/squad](https://github.com/bradygaster/squad) (public) | ### Why the Migration? - The move to npm and public distribution gives you: - - **Faster installs** — npm cache; no git clone on every run - **Semantic versioning** — explicit versions, not git commits - **Channels** — `latest` for stable, `@insider` for bleeding-edge - **Standard dependency management** — works with npm, yarn, pnpm - **Public collaboration** — anyone can file issues, contribute, fork - ## For Beta Users: How to Upgrade - You're on v0.5.4 with `@bradygaster/create-squad`. The jump to v0.8.18 is significant—features and APIs have evolved. Here's the upgrade path: - ### Step 1: Uninstall the old package - ```bash npm uninstall -g @bradygaster/create-squad ``` - ### Step 2: Install the new CLI - ```bash npm install -g @bradygaster/squad-cli ``` - ### Step 3: In your existing project, upgrade Squad files - If you have a `.squad/` directory (or the old `.ai-team/`), run: - ```bash squad upgrade ``` - This updates Squad-owned files (templates, core configs) **without touching your team state** (agents, history, decisions). Your custom changes are preserved. - **Optional:** If you're migrating from `.ai-team/` to `.squad/`, use: - ```bash squad upgrade --migrate-directory ``` - ### Step 4: Verify your setup - ```bash squad doctor ``` - This checks your environment, Node.js version, GitHub auth, and squad configuration. It reports warnings if anything's amiss. - ### Step 5: Start working - ```bash copilot ``` - In GitHub Copilot CLI, type `/agent` and select **Squad**. Or in VS Code, type `/agents` and select **Squad**. Then: - ``` I'm continuing a project. Here's what I need: [your task] ``` - **See the full migration guide:** [`docs/get-started/migration.md`](../get-started/migration.md) - ## For New Users: Getting Started - Never used Squad? Start here: - ### 1. Install Squad CLI - ```bash npm install -g @bradygaster/squad-cli ``` - Or use npx without installing: - ```bash npx @bradygaster/squad-cli ``` - ### 2. Create a project directory - ```bash mkdir my-squad-project && cd my-squad-project git init ``` - ### 3. Initialize Squad - ```bash squad init ``` - This scaffolds `.squad/` with team configuration, agent templates, and routing rules. Everything is editable and committed to git. - ### 4. Authenticate with GitHub - ```bash gh auth login ``` - This lets Squad access your Issues, PRs, and Projects. Required for features like triage, the Copilot coding agent, and project monitoring with Ralph. - ### 5. Open Copilot and talk to your team - ```bash copilot ``` - In the Copilot CLI, type `/agent` and select **Squad**. Then: - ``` I'm starting a new project. Here's what I'm building: a React + Node API with user auth and dark mode. ``` - Squad proposes a team (Lead, Frontend, Backend, Tester, Scribe), you say yes, and they're ready. Describe the work. They execute it. Messages, decisions, and history persist in `.squad/` — commit it, share it, iterate on it. - **Full guide:** [`README.md`](https://github.com/bradygaster/squad/blob/main/README.md) | **Samples:** [`samples/`](https://github.com/bradygaster/squad/tree/main/samples) - ## The Version Jump: v0.5.4 → v0.8.18 - You might notice the version leap. Here's why: - - **v0.5.x (beta)** — Private repo, feature experiments, no stable SemVer - **v0.6.x** — Replatform begins (SDK separation, hook pipeline, cost tracking) - **v0.7.x** — Three development waves (orchestration, observability, docs) - **v0.8.x (current)** — Unified, public, semver-stable - You're not jumping over broken versions. You're joining the stable channel of a mature codebase. Read the [CHANGELOG.md](https://github.com/bradygaster/squad/blob/main/CHANGELOG.md) if you want the full arc. - ## Links - - **Public repository:** [`bradygaster/squad`](https://github.com/bradygaster/squad) - **Migration guide:** [`docs/get-started/migration.md`](../get-started/migration.md) - **README with full install methods:** [`README.md`](https://github.com/bradygaster/squad/blob/main/README.md) - **Samples:** [`samples/`](../../samples/) — hello-squad, knock-knock, rock-paper-scissors, streaming-chat, hook-governance, and more - **Getting started guide:** `docs/guide/getting-started.md` (coming soon) - ## What's Next - The public repo is live. npm distribution is stable. Docs are rebuilt. The team is ready to grow. - If you hit issues: - **[File a bug](https://github.com/bradygaster/squad/issues/new)** — Issues are public. We read them. - **[Start a discussion](https://github.com/bradygaster/squad/discussions)** — Ideas, questions, feedback. - **[Check the docs](https://github.com/bradygaster/squad#what-is-squad)** — migration guides, scenarios, reference. - Welcome to the public Squad. Let's build. --- - _This post was written by McManus, DevRel on Squad's team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try it →](https://github.com/bradygaster/squad)_ diff --git a/docs/src/content/blog/022-welcome-to-the-new-squad.md b/docs/src/content/blog/022-welcome-to-the-new-squad.md index 2fcbb1029..47ba4bd30 100644 --- a/docs/src/content/blog/022-welcome-to-the-new-squad.md +++ b/docs/src/content/blog/022-welcome-to-the-new-squad.md @@ -7,56 +7,40 @@ tags: [squad, v0.8.18, release, launch, sdk, cli, typescript, samples, migration status: published hero: "Squad v0.8.18 is here — a full TypeScript rewrite, npm distribution, 16 CLI commands, 8 SDK samples, 2200+ tests, and a feature set that turns multi-agent development from experiment to production tool." --- - # Welcome to the New Squad - > Blog post #22 — The complete guide to what changed from beta to v0.8.18. - ## The Big Picture - -Squad started as a scrappy beta experiment. A few scripts, some clever prompting, and a vision: what if you could build an AI team that lived in your repo, learned your codebase, and got better with every session? - +Squad started as a scrappy beta experiment. A few scripts, some clever prompting, and a vision: what if you could build an augmented team that lived in your repo, learned your codebase, and got better with every session? Today, Squad is a proper npm-distributed, TypeScript-strict, fully-tested multi-agent runtime. It's not just a rewrite — it's a ground-up rebuild of everything we learned from six months of usage, feedback, and production deployments. - Here's what shipped: - **Quick Stats:** - ✅ Full TypeScript rewrite (strict mode, no `any` escapes) - ✅ 16 CLI commands (init, doctor, triage, shell, aspire, and more) -- ✅ 8 SDK samples (hello-world to full autonomous pipelines) +- ✅ 8 SDK samples (hello-world to full background pipelines) - ✅ 2200+ tests across 613 test files - ✅ npm-only distribution (`@bradygaster/squad-cli`) - ✅ Global install: `npm install -g @bradygaster/squad-cli` - ✅ OpenTelemetry integration (traces + metrics → Aspire dashboard) - ✅ Security hardening (CWE-78 fixes, PII scrubbing, governance hooks) - ✅ Semantic versioning compliance (`X.Y.Z-preview.N`) - If you were on the beta (v0.5.x), this is your upgrade moment. If you're new to Squad, this is the best time to jump in. --- - ## How to Get It - Three lines: - ```bash npm install -g @bradygaster/squad-cli cd your-project squad init ``` - **Or run without installing:** - ```bash npx @bradygaster/squad-cli ``` - **Upgrading from beta?** Check the [Migration Guide](../get-started/migration.md) for step-by-step upgrade instructions covering 9 scenarios from brand-new users to CI/CD pipelines. --- - ## What Changed — The Headlines - Here's the side-by-side comparison of beta vs. v0.8.18: | Area | Beta (v0.5.x) | New (v0.8.18) | @@ -65,7 +49,7 @@ Here's the side-by-side comparison of beta vs. v0.8.18: | **Distribution** | `npx github:bradygaster/squad` | `npm install -g @bradygaster/squad-cli` | | **Packages** | Monolithic | SDK + CLI (independent versioning) | | **Config** | JSON only | Markdown + optional `squad.config.ts` | -| **Shell** | Basic | Rich REPL with streaming, sessions, keyboard shortcuts | +| **CLI experience** | Basic | Rich command set, monitoring, and Copilot CLI integration | | **Testing** | Minimal | 2200+ tests across 613 files | | **Observability** | None | OpenTelemetry + Aspire dashboard | | **Security** | Basic | CWE-78 fixes, PII scrubbing, governance hooks | @@ -75,53 +59,32 @@ Here's the side-by-side comparison of beta vs. v0.8.18: The beta was a proof of concept. v0.8.18 is the production-ready runtime. --- - ## The CLI — Your New Command Center - The CLI went from "a few scripts" to "a full terminal experience." Here's what you get: - ### 1. **Global Install** — `squad` Works Everywhere - No more `npx github:` commands. Install once, run anywhere: - ```bash npm install -g @bradygaster/squad-cli squad --version ``` - That's it. Squad is now a first-class terminal command. - -### 2. **Interactive Shell** — Live Multi-Agent REPL - -Run `squad` with no arguments and you drop into a live terminal: - +### 2. **GitHub Copilot CLI** — Live Multi-Agent Collaboration +Launch Squad through GitHub Copilot CLI for the recommended conversational experience: ```bash -squad +copilot --agent squad ``` - -You get a prompt: - -``` -squad > -``` - **What you can do:** - Address agents by name: `@Ripley, fix the auth bug` -- Run slash commands: `/status`, `/agents`, `/history`, `/quit` +- Start conversational work immediately - Watch responses stream token-by-token in real time -- Navigate history with arrow keys -- Tab completion for agents and commands - -No more typing `squad` before every command. The shell is stateful, context-aware, and built for conversation. - +- Keep the same team context across follow-up prompts +- Route requests directly to specialists when you need them +No extra wrapper shell required — just open Squad in Copilot CLI and keep the conversation moving. ### 3. **`squad doctor`** — 9-Check Health Validation - Something feels off? Run the doctor: - ```bash squad doctor ``` - Nine checks run instantly: - ✅ Node.js version (≥ 20) - ✅ `gh` CLI installed and authenticated @@ -132,135 +95,88 @@ Nine checks run instantly: - ✅ Directory write permissions - ✅ Config file syntax - ✅ No orphaned files - If anything fails, you get a clear error message and suggested fix. No more guessing. - ### 4. **`squad start --tunnel`** — Stream Your Terminal to Your Phone - Demoing Squad to a remote audience? Run: - ```bash squad start --tunnel ``` - You get a QR code. Scan it with your phone. Your terminal output streams live to a web browser — perfect for presentations, demos, and remote debugging. - ### 5. **`squad triage`** — Auto-Scan GitHub Issues - Connect Squad to your GitHub repo and watch it auto-triage: - ```bash squad triage ``` - Squad scans open issues, labels them by category (bug/feature/docs/security), and assigns them to the right agent based on their role and skills. Runs continuously — every 10 minutes by default. - ```bash squad triage --interval 5 # Poll every 5 minutes ``` - -Your backlog manages itself. - +Your backlog stays moving with agent help and your guidance. ### 6. **`squad copilot`** — Add @copilot as a Team Member - -Want the GitHub Copilot coding agent to pick up issues autonomously? Add it to your team: - +Want the GitHub Copilot coding agent to pick up approved issues in the background? Add it to your team: ```bash squad copilot ``` - This adds `@copilot` as an agent in `.squad/team.md` and configures auto-assignment. When Squad triages an issue, @copilot picks it up, creates a branch, writes code, runs tests, and opens a PR. - Remove it with: - ```bash squad copilot --off ``` - ### 7. **Dual-Root Mode** — Org-Wide Team Sharing - Most teams want one Squad per repo. But some organizations want to share a team identity across projects. Dual-root mode gives you both: - ```bash squad init --mode remote ~/my-org-team ``` - This stores agent charters and team config in `~/my-org-team/.squad/`, while project-specific state lives in `./squad/`. Agents are consistent across repos, but each project has its own decisions, skills, and context. - Perfect for agencies, consulting teams, and orgs with standardized agent roles. - ### 8. **Plugin Marketplace** — Community Skill Packs - Extend Squad with community-built skill packs: - ```bash squad plugin marketplace list squad plugin marketplace add https://github.com/user/squad-skills ``` - Skills are markdown files that agents read to learn domain patterns. A "TypeScript Best Practices" skill pack might teach agents to prefer `unknown` over `any`, use strict mode, and avoid non-null assertions. - ### 9. **`squad export`/`import`** — Portable Squad Snapshots - Need to share your team config with a colleague or back up your setup? - ```bash squad export > my-squad.json squad import my-squad.json ``` - The export includes team roster, agent charters, decisions, skills, and config. Import into any repo and your team comes alive instantly. - ### 10. **`squad aspire`** — Observability Dashboard - Squad exports OpenTelemetry traces and metrics. Launch the Aspire dashboard to see: - ```bash squad aspire ``` - - Agent spawn/destroy events - Token usage per agent, per session - Task duration histograms - Session lifecycle logs - Cost tracking in real time - Hook it up to Jaeger, Aspire, or any OTLP-compatible backend. - ### 11. **`squad upgrade`** — Safe Upgrades That Never Touch Your Team State - Upgrading used to be scary. Not anymore: - ```bash squad upgrade ``` - This updates Squad-owned files (templates, CLI scripts, SDK code) but never touches: - `.squad/agents/**` (your agent charters) - `.squad/decisions.md` (architectural decisions) - `.copilot/skills/**` (learned patterns) - `.squad/history/**` (session logs) - Your team's memory is sacred. Upgrades respect that. --- - ## The SDK — Build Your Own Multi-Agent Apps - The CLI is built on the SDK. The SDK is the runtime. You can use it directly to build custom multi-agent applications. - **Two packages, independent versioning:** - `@bradygaster/squad-sdk` — the runtime (casting, streaming, governance, cost tracking) - `@bradygaster/squad-cli` — the interface (commands, REPL, triage loop) - They evolve separately. CLI features can ship without breaking SDK consumers. - **Install the SDK:** - ```bash npm install @bradygaster/squad-sdk ``` - **Key SDK Capabilities:** | Component | What It Does | @@ -274,37 +190,26 @@ npm install @bradygaster/squad-sdk | **SessionPool** | Managed Copilot session lifecycle. Reuse sessions across messages, clean up on shutdown. | **TypeScript-first:** - Every interface, type, and function is fully typed. No `any` escapes. If it compiles, it's correct. --- - ## The Samples — See It In Action - Eight samples ship with v0.8.18. Each one demonstrates a slice of the SDK. Run them, read the code, learn the patterns. - ### 1. **hello-squad** (Beginner) - **What it does:** Cast a themed team from The Usual Suspects universe. Watch four agents materialize with deterministic names. The casting engine's "hello world." - **What you'll see:** ``` 🎭 Keyser — Lead Personality: Quietly commanding; sees the whole board before anyone else. - 🎭 McManus — Developer Personality: Sharp, precise, always three steps ahead. - 🎭 Fenster — Tester Personality: Unpredictable, curious, finds edge cases by instinct. - 🎭 Verbal — Scribe Personality: The storyteller; connects dots across sessions. ``` - **Difficulty:** Beginner **SDK APIs:** `resolveSquad()`, `CastingEngine.castTeam()`, `onboardAgent()` - **Run it:** ```bash cd samples/hello-squad @@ -312,11 +217,8 @@ npm install && npm start ``` --- - ### 2. **knock-knock** (Intermediate) - **What it does:** Two Copilot sessions trade live knock-knock jokes, streaming token-by-token. Demonstrates `SquadClientWithPool`, casting, and `StreamingPipeline`. - **What you'll see:** ``` 🎭 Agent 1: Knock knock. @@ -325,12 +227,9 @@ npm install && npm start 🎭 Agent 2: Lettuce who? 🎭 Agent 1: Lettuce in, it's cold out here! 🥶 ``` - Responses stream word-by-word in real time. Watch the jokes build character by character. - **Difficulty:** Intermediate **SDK APIs:** `SquadClientWithPool`, `CastingEngine`, `StreamingPipeline`, `SessionPool`, `EventBus` - **Run it:** ```bash cd samples/knock-knock @@ -338,22 +237,16 @@ npm install && npm start ``` --- - ### 3. **rock-paper-scissors** (Advanced) - **What it does:** Nine strategic agents battle in a tournament. Rocky always throws rock. Sherlock analyzes opponent history to predict and counter moves. A live leaderboard tracks wins. - **What you'll see:** ``` Match: Rocky vs. Sherlock — Round 1 - Rocky throws: rock Sherlock analyzes opponent history... Sherlock plays strategically: paper Scorekeeper: Rocky throws rock AGAIN! Sherlock counters with paper. Strategic victory! 📄 > 🪨 - Sherlock: 1 win | Rocky: 0 wins - [After 10 rounds] 🏆 LEADERBOARD 🏆 1. Sherlock 🔍: 12 wins @@ -362,12 +255,9 @@ Sherlock: 1 win | Rocky: 0 wins 4. Echo 🦜: 5 wins 5. Rocky 🪨: 2 wins ``` - Watch the learning agent adapt. Sherlock's win rate climbs as it detects patterns. - **Difficulty:** Advanced **SDK APIs:** `SquadClientWithPool`, `SessionPool`, `StreamingPipeline`, `EventBus`, system prompts - **Run it:** ```bash cd samples/rock-paper-scissors @@ -375,34 +265,26 @@ npm install && npm start ``` --- - ### 4. **hook-governance** (Intermediate) - **What it does:** Four governance hooks in action. File-write guards block `/etc/passwd`. PII scrubber redacts emails. Reviewer lockout prevents self-revision. Rate limiter caps user interruptions. - **What you'll see:** ``` 🛡️ hook-governance — Squad SDK governance hooks sample - ──────────────────────────────────────────────────────────── Demo 1 — File-Write Guards ──────────────────────────────────────────────────────────── Write to src/utils/helper.ts: allow ✅ Write to /etc/passwd: block 🚫 Reason: File write blocked: "/etc/passwd" does not match allowed paths - ──────────────────────────────────────────────────────────── Demo 2 — PII Scrubbing ──────────────────────────────────────────────────────────── Before: Deploy fix by brady@example.com — cc: alice@company.io After: Deploy fix by [EMAIL_REDACTED] — cc: [EMAIL_REDACTED] ``` - **Rules as code, not prompts.** Hooks enforce policy at runtime. No LLM reasoning required. - **Difficulty:** Intermediate **SDK APIs:** `HookPipeline`, `addPreToolHook()`, `addPostToolHook()`, `getReviewerLockout()`, `PolicyConfig` - **Run it:** ```bash cd samples/hook-governance @@ -410,15 +292,11 @@ npm install && npm start ``` --- - ### 5. **streaming-chat** (Intermediate) - -**What it does:** Three agents respond to keyword-routed messages in real time. Type "design an API" → Backend responds. Type "add dark mode" → Frontend delivers. Token-by-token streaming. - +**What it does:** Three agents respond to keyword-routed messages in real time. Ask for an API design → Backend responds. Ask for dark mode → Frontend delivers. Token-by-token streaming. **What you'll see:** ``` -squad > design a REST API for recipes - +design a REST API for recipes Backend (McManus) responding... I recommend a resource-based API with these endpoints: - GET /recipes — list all recipes @@ -426,13 +304,10 @@ I recommend a resource-based API with these endpoints: - POST /recipes — create new recipe - PUT /recipes/:id — update recipe - DELETE /recipes/:id — remove recipe - Use JSON for all payloads. Add pagination with ?page= and ?limit=. ``` - **Difficulty:** Intermediate **SDK APIs:** `SquadClient`, `createSession()`, `StreamingPipeline`, `onDelta()`, `onUsage()`, `EventBus` - **Run it:** ```bash cd samples/streaming-chat @@ -440,38 +315,30 @@ npm install && npm start ``` --- - ### 6. **cost-aware-router** (Beginner) - **What it does:** Five tasks flow through a cost-optimized router. Typo fix → Direct tier (cheapest). Architecture review → Full tier (premium). A budget bar fills up with warnings at 70% and 90%. - **What you'll see:** ``` Task 1: Fix typo in README → Tier: direct (no LLM needed) → Cost: $0.00 → Budget: $0.00 / $0.50 [██░░░░░░░░] 0% - Task 2: Update docs → Tier: lightweight (fast model) → Cost: $0.02 → Budget: $0.02 / $0.50 [██░░░░░░░░] 4% - Task 3: Implement feature → Tier: standard (standard model) → Cost: $0.15 → Budget: $0.17 / $0.50 [████░░░░░░] 34% - Task 4: Architecture review → Tier: full (premium model) → Cost: $0.25 → Budget: $0.42 / $0.50 [████████░░] 84% ⚠️ Budget warning: 84% consumed ``` - **Difficulty:** Beginner **SDK APIs:** `CostTracker`, `selectResponseTier()`, `getTier()`, `recordUsage()`, `formatSummary()` - **Run it:** ```bash cd samples/cost-aware-router @@ -479,31 +346,23 @@ npm install && npm start ``` --- - ### 7. **skill-discovery** (Intermediate) - **What it does:** Agents load domain knowledge from SKILL.md files, match skills to tasks, and discover NEW patterns at runtime. Confidence tracks from low → medium → high as patterns are confirmed. - **What you'll see:** ``` 📚 Loading skills from .copilot/skills/ - ✅ Loaded: TypeScript Patterns (confidence: high 🟢) Triggers: typescript, types, generics Roles: developer, lead - ✅ Loaded: Testing Best Practices (confidence: medium 🟡) Triggers: test, coverage, mock Roles: tester - 🔍 Matching skills to task: "Fix TypeScript build error" Matched: TypeScript Patterns (confidence: high) Reason: Trigger match: "typescript" ``` - **Difficulty:** Intermediate **SDK APIs:** `SkillRegistry`, `loadSkillsFromDirectory()`, `matchSkills()`, `parseSkillFile()` - **Run it:** ```bash cd samples/skill-discovery @@ -511,15 +370,11 @@ npm install && npm start ``` --- - ### 8. **autonomous-pipeline** (Advanced) - -**What it does:** THE showcase. A 10-task dev pipeline runs autonomously. Agents pick up work, route blockers, record decisions, accumulate learnings. A live dashboard shows who's working on what. - +**What it does:** THE showcase. A 10-task dev pipeline runs in the background. Agents pick up work, route blockers, record decisions, accumulate learnings. A live dashboard shows who's working on what. **What you'll see:** ``` 🎬 autonomous-pipeline — Squad SDK Showcase - ──────────────────────────────────────────────────────────── Casting Team from "The Usual Suspects" ──────────────────────────────────────────────────────────── @@ -527,7 +382,6 @@ npm install && npm start 🎭 McManus — Developer 🎭 Fenster — Tester 🎭 Verbal — Scribe - ──────────────────────────────────────────────────────────── Task Queue (10 tasks) ──────────────────────────────────────────────────────────── @@ -541,17 +395,14 @@ npm install && npm start 8. [ ] Write migration guide 9. [ ] Update README 10. [ ] Record architecture decisions - ──────────────────────────────────────────────────────────── - Autonomous Execution + Background Execution ──────────────────────────────────────────────────────────── McManus picked up: Design REST API McManus routed to Fenster: Write unit tests Fenster recorded decision: Use RS256 for JWT Verbal accumulated learning: Pool size 20 optimal - [Live dashboard updates in real time] - ──────────────────────────────────────────────────────────── Final Report ──────────────────────────────────────────────────────────── @@ -560,12 +411,9 @@ npm install && npm start 🪙 Tokens: 45,230 input / 12,890 output 📊 OTel traces exported to Aspire dashboard ``` - This is the "wow demo" — everything Squad can do in one running script. - **Difficulty:** Advanced **SDK APIs:** `SquadClient`, `CastingEngine`, `HookPipeline`, `CostTracker`, `EventBus`, `StreamingPipeline`, `resolveSquad()`, `createSession()` - **Run it:** ```bash cd samples/autonomous-pipeline @@ -573,146 +421,100 @@ npm install && npm start ``` --- - ## Under the Hood — What We Rebuilt - ### TypeScript Strict Mode - Everything is typed. No `any` escapes. No implicit `any`. No index access without guards. If it compiles, it's correct. - **What this means for SDK consumers:** - Autocomplete works everywhere - Type errors caught at compile time - Refactoring is safe - Documentation lives in the types - The SDK exports fully-typed interfaces for every concept: agents, sessions, tiers, hooks, skills, events. - ### Semver Done Right - Beta versions were a mess: `0.8.5.1-preview`, `0.8.6.1`, inconsistent formats. v0.8.18 follows the spec: - **Correct format:** `X.Y.Z-preview.N` **Example:** `0.8.18-preview.1` - Prerelease identifier comes after patch, build metadata comes after prerelease. No more confusion. - **What this enables:** - Proper dependency resolution in npm - Correct version comparisons - Predictable upgrade paths - Semver-compliant tooling support - ### Security Hardening - #### CWE-78 Fixes - Beta used template strings with `execSync`. This was a shell injection risk. v0.8.18 uses `execFileSync` with array args: - **Before (unsafe):** ```typescript execSync(`git commit -m "${message}"`); ``` - **After (safe):** ```typescript execFileSync('git', ['commit', '-m', message]); ``` - No shell interpolation. No injection vectors. - #### PII Scrubbing - Email addresses leak into logs, tool output, and session history. v0.8.18 includes automatic PII scrubbing: - ```bash squad scrub-emails ``` - This redacts all emails in `.squad/` files: - `brady@example.com` → `[EMAIL_REDACTED]` - Works recursively on all markdown and JSON files - Safe to commit the scrubbed state - #### Governance Hooks - Policy as code. Hooks run before and after every tool call: - - **Pre-tool hooks:** Block file writes outside allowed paths - **Post-tool hooks:** Redact PII from output - **Custom hooks:** Add audit logging, quota enforcement, content filters - No LLM reasoning required. Rules are code, not prompts. - ### CRLF Normalization - Windows users with `core.autocrlf=true` saw parser failures because `\r\n` line endings broke markdown frontmatter parsing. v0.8.18 normalizes all line endings before parsing. - **What changed:** - All 8 parsers now call `normalizeEol()` first - `\r\n` → `\n` before regex matching - Windows/Mac/Linux all parse identically - No more "works on my machine" bugs. - ### OpenTelemetry Integration - Squad exports traces and metrics via OpenTelemetry. Three-layer API: - 1. **Low-level:** `otel.ts` — raw OTel SDK wrappers 2. **Bridge:** `otel-bridge.ts` — Squad-specific spans and metrics 3. **Init:** `otel-init.ts` — auto-configure based on `OTEL_EXPORTER_OTLP_ENDPOINT` - **What you can track:** - Agent spawn/destroy events - Session lifecycle (created/resumed/closed) - Token usage per agent, per session - Task duration histograms - Cost accumulation in real time - **Export to:** - Aspire Dashboard (`squad aspire`) - Jaeger - Zipkin - Any OTLP-compatible backend - **Example:** ```bash export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 squad aspire ``` - Open `http://localhost:18888` to see your multi-agent pipeline visualized. --- - ## Migrating from Beta - If you're on beta (v0.5.x), here's the upgrade path: - ### Quick Migration - ```bash # 1. Back up your current squad cp -r .squad/ .squad-backup/ - # 2. Uninstall old beta npm uninstall -g @bradygaster/create-squad - # 3. Install new CLI npm install -g @bradygaster/squad-cli - # 4. Reinitialize (this will detect and migrate your .squad/ directory) squad init - # 5. Verify squad doctor ``` - ### Full Migration Guide - The [Migration Guide](../get-started/migration.md) covers 9 scenarios: - 1. Brand new user 2. Upgrading from v0.5.4 beta 3. Already on v0.8.x via npm @@ -722,7 +524,6 @@ The [Migration Guide](../get-started/migration.md) covers 9 scenarios: 7. Have `.ai-team/` from an older version 8. Using Squad in CI/CD 9. Using Squad SDK programmatically - **Key changes to watch for:** - Package name: `@bradygaster/create-squad` → `@bradygaster/squad-cli` - Directory: `.ai-team/` → `.squad/` (auto-migrated with `--migrate-directory`) @@ -730,60 +531,44 @@ The [Migration Guide](../get-started/migration.md) covers 9 scenarios: - Commands: Some were renamed or merged (check `squad help`) --- - ## What's Next - Squad v0.8.18 is the foundation. Here's what we're working on: - ### Short-Term (Next 4 Weeks) - More samples and tutorials - Plugin marketplace growth (community skill packs) - CLI polish (better error messages, progress bars, colors) - Documentation improvements (video walkthroughs, interactive guides) - ### Medium-Term (Next 12 Weeks) - Multi-repo squad support (one team, many projects) - Enhanced observability (real-time dashboards, cost alerts) - CI/CD integrations (GitHub Actions, GitLab CI, CircleCI) - Team collaboration features (shared squads, sync protocols) - ### Long-Term (Next 6 Months) - Visual squad builder (drag-and-drop agent creation) - Agent marketplace (community-built agent templates) - Cloud-hosted squads (no local setup required) - Enterprise features (SSO, audit logs, compliance hooks) - **Community contributions welcome!** Issues and PRs at [github.com/bradygaster/squad](https://github.com/bradygaster/squad). --- - ## Get Started Today - Squad v0.8.18 is live on npm. Install it: - ```bash npm install -g @bradygaster/squad-cli ``` - Initialize a project: - ```bash cd your-project squad init ``` - Launch the shell: - ```bash squad ``` - Start building. --- - ## Resources - - **GitHub:** [github.com/bradygaster/squad](https://github.com/bradygaster/squad) - **SDK on npm:** [@bradygaster/squad-sdk](https://www.npmjs.com/package/@bradygaster/squad-sdk) - **CLI on npm:** [@bradygaster/squad-cli](https://www.npmjs.com/package/@bradygaster/squad-cli) @@ -792,11 +577,8 @@ Start building. - **Issues:** [github.com/bradygaster/squad/issues](https://github.com/bradygaster/squad/issues) --- - **Questions? Feedback? Ideas?** File an issue. Join the community. Build something amazing. - Welcome to Squad v0.8.18. Let's build better software, together. 🚀 --- - _McManus (DevRel) — March 10, 2026_ diff --git a/docs/src/content/blog/024-v0823-release.md b/docs/src/content/blog/024-v0823-release.md index efbfdd6a0..e3e66ccc2 100644 --- a/docs/src/content/blog/024-v0823-release.md +++ b/docs/src/content/blog/024-v0823-release.md @@ -7,23 +7,14 @@ tags: [squad, release, v0.8.23, node24, sdk-first, stability, cli, typescript, a status: published hero: "v0.8.23 fixes a critical crash when running `squad init` on Node.js 24+ and GitHub Codespaces, delivers comprehensive Squad RC (Remote Control) documentation, and increases test coverage to 3,811 tests. Faster CLI startup for non-session commands." --- - # v0.8.23 Release: Node 24+ Compatibility, Squad RC Docs, and Critical Fixes - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - > _v0.8.23 is a critical hotfix addressing a crash when running `squad init` on Node.js 24+ and GitHub Codespaces. It ships comprehensive Squad RC documentation, introduces lazy module loading for faster CLI startup, and includes a postinstall patch for ESM import issues. 2 issues closed, 3 PRs merged, 3,811 tests passing._ --- - ## What Shipped - ### 1. SDK-First Mode (Phase 1) — The Headline Feature - Squad now lets you define your entire team—agents, routing, ceremonies, telemetry, governance—in a single TypeScript config file. Type-safe. Validated at runtime. Compiled to markdown. Deployed anywhere. - **Eight builder functions** for type-safe team configuration: - - `defineTeam()` — Team metadata, project context, member roster - `defineAgent()` — Agent role, model, tools, capabilities, and status - `defineRouting()` — Pattern-based routing with tiers and priorities @@ -32,26 +23,20 @@ Squad now lets you define your entire team—agents, routing, ceremonies, teleme - `defineCasting()` — Casting configuration (universe allowlists, overflow strategy) - `defineTelemetry()` — OpenTelemetry instrumentation (metrics, traces, spans) - `defineSquad()` — Top-level config composition - **`squad build` command** with three modes: - ```bash squad build # Compile squad.config.ts to .squad/ markdown squad build --check # Validate without writing squad build --dry-run # Preview what would be generated squad build --watch # File monitoring (stub for Phase 2) ``` - Generates: - `.squad/team.md` — team roster and context - `.squad/routing.md` — routing rules with priorities - `.squad/agents/{name}/charter.md` — agent charters with capabilities - `.squad/ceremonies.md` — ceremony schedules (if defined) - Protected files (`.squad/decisions.md`, `.squad/history.md`) are **never overwritten**. - **Quick Start Example:** - ```typescript import { defineSquad, @@ -59,7 +44,6 @@ import { defineAgent, defineRouting, } from '@bradygaster/squad-sdk'; - export default defineSquad({ team: defineTeam({ name: 'Content Review Squad', @@ -67,7 +51,6 @@ export default defineSquad({ projectContext: 'HTTP-triggered review pipeline', members: ['tone-reviewer', 'technical-reviewer', 'copy-editor'], }), - agents: [ defineAgent({ name: 'tone-reviewer', @@ -100,7 +83,6 @@ export default defineSquad({ ], }), ], - routing: defineRouting({ rules: [ { @@ -133,9 +115,7 @@ export default defineSquad({ }), }); ``` - Then: - ```bash npm install @bradygaster/squad-sdk npx squad build @@ -143,26 +123,19 @@ npx squad build ``` --- - ### 2. Azure Function Sample — Serverless Multi-Agent Workflows - New sample: `samples/azure-function-squad/` — a **Content Review Squad** that wires an HTTP-triggered Azure Function to a multi-agent review pipeline. - **What it demonstrates:** - - `defineSquad()` composing team + agents + routing - Three specialist agents (tone, technical, copy) defined with `defineAgent()` - Pattern-based routing with `defineRouting()` - Real TypeScript integration with Azure Functions v4 - Structured JSON responses with per-agent findings - **Usage:** - ```bash cd samples/azure-function-squad npm install func start # Requires Azure Functions Core Tools - # In another terminal: curl -X POST http://localhost:7071/api/squad-prompt \ -H "Content-Type: application/json" \ @@ -170,9 +143,7 @@ curl -X POST http://localhost:7071/api/squad-prompt \ "prompt": "Building multi-agent systems with the Squad SDK is straightforward. Define your agents with defineAgent(), compose them into a team with defineTeam(), and wire up routing with defineRouting(). The SDK validates everything at runtime — no schema files needed." }' ``` - **Response:** - ```json { "reviews": [ @@ -212,132 +183,86 @@ curl -X POST http://localhost:7071/api/squad-prompt \ "consensus": "✅ Content is publication-ready with minor suggestions." } ``` - The Azure sample is a drop-in starting point for serverless multi-agent workflows. Replace the mock review handlers with live Squad runtime calls using `SquadClient`, and you have a production-ready review pipeline. --- - ### 3. Remote Squad Mode - Cross-machine squad collaboration via new `squad rc` commands for linking project-local squads to remote team roots. - **New commands:** - - `squad rc` — Show remote config status - `squad init-remote` — Initialize with remote team root config - `squad rc-tunnel` — Establish remote connection - **Key concepts:** - - `resolveSquadPaths()` dual-root resolver — project-local vs team identity directories - `squad doctor` — 9-check setup validation with emoji output - `squad link ` — link a project to a remote team root - `ensureSquadPathDual()` / `ensureSquadPathResolved()` — dual-root write guards - Remote Squad Mode enables teams to share squad identity across multiple projects while maintaining project-local customization. --- - ### 4. Critical Bug Fixes - #### **Installation Crash Fix (#247) — The Big One** - **Problem:** `npx @bradygaster/squad-cli` was crashing on fresh installs with: - ``` Error: Cannot find module '@opentelemetry/api' ``` - **Root cause:** `@opentelemetry/api` was a hard dependency that failed to resolve in npx's isolated install environment, causing the entire CLI to fail immediately. - **Fix:** - 1. Created `otel-api.ts` resilient wrapper with full no-op fallbacks 2. Moved OTel to optional dependencies (not required by default) 3. Telemetry now gracefully degrades when OTel is absent — zero crashes - **Impact:** Fresh installs now work reliably. Telemetry is truly optional. --- - #### **CLI Command Wiring (#244)** - Four commands were implemented but never wired into the CLI entry point: - - `rc` - `copilot-bridge` - `init-remote` - `rc-tunnel` - **Fix:** Commands are now properly connected and accessible via `squad rc`, `squad copilot-bridge`, etc. - **Impact:** Remote squad features are now discoverable and functional. --- - #### **Model Config Round-Trip (#245)** - **Problem:** `AgentDefinition.model` didn't accept structured model configuration — only strings. - **Fix:** - - `AgentDefinition.model` now accepts `string | ModelPreference` for advanced configuration - Charter compiler updated to emit and parse the new format correctly - Round-trip config survives compile → parse → serialize cycles intact - **Impact:** Advanced model selection (fallback chains, cost-aware routing) now works end-to-end. --- - #### **ExperimentalWarning Suppression** - **Problem:** Node's `ExperimentalWarning` for `node:sqlite` was leaking into terminal output, cluttering user experience. - **Fix:** Process.emit override in `cli-entry.ts` filters experimental warnings before they reach stdout. - **Impact:** Clean, focused terminal output. --- - #### **Blankspace Fix (#239)** - **Problem:** Idle blank space appeared below the agent panel even when no output was present. - **Fix:** Conditional height constraint only active during processing. Removes visual clutter. - **Impact:** Cleaner UI, professional appearance. --- - ### 5. Test Hardening - #### **Windows Race Condition (EBUSY)** - Race condition in `fs.rm` with retry logic on Windows. Fixed with exponential backoff and resource cleanup. - #### **Speed Gate Adjustments** - Test speed gate thresholds adjusted for growing CLI codebase. No more false-positive timeout failures. - #### **Regression Fix Wave (#221)** - **Massive batch:** PR #221 resolved 25 test regressions across the suite. CRLF normalization, cross-platform path handling, and mock cleanup. --- - ### 6. CI Stabilization (#232, #228) - GitHub Actions pipeline fixed and green. All workflows now run reliably without transient failures. --- - ### 7. Community Contributions - - **PR #199 (migration command)** — Received, reviewed, and feedback captured as issue #231 for future implementation - **PR #243 (blankspace fix)** — Community contribution cherry-picked and credited --- - ## By the Numbers | Metric | Value | @@ -355,13 +280,9 @@ GitHub Actions pipeline fixed and green. All workflows now run reliably without | Release candidate version | 0.8.22-preview.9 | --- - ## Technical Details - ### SDK Mode Detection - The coordinator now auto-detects SDK-First mode: - ```typescript // squad.config.ts exists? if (fs.existsSync(resolve('.', 'squad.config.ts'))) { @@ -369,15 +290,11 @@ if (fs.existsSync(resolve('.', 'squad.config.ts'))) { // Coordinator uses compiled markdown + SDK awareness } ``` - Fallback: if `squad.config.ts` is missing, Squad operates in traditional markdown-first mode (backward compatible). --- - ### Telemetry Architecture (OTel Resilience) - New `otel-api.ts` wrapper ensures telemetry is truly optional: - ```typescript // otel-api.ts export function initTelemetry(config?: TelemetryConfig) { @@ -393,15 +310,11 @@ export function initTelemetry(config?: TelemetryConfig) { } } ``` - **Benefit:** Telemetry is an optional add-on, not a blocker. --- - ### Remote Squad Path Resolution - Dual-root resolver supports both project-local and team-identity directories: - ```typescript function resolveSquadPaths(projectRoot: string, remoteTeamRoot?: string) { // Check project-local first: {projectRoot}/.squad/ @@ -411,196 +324,135 @@ function resolveSquadPaths(projectRoot: string, remoteTeamRoot?: string) { ``` --- - ### OTel Readiness Assessment - All 8 telemetry modules (`defineHooks`, `defineTelemetry`, meter providers, span processors, exporters) compile and validate with zero runtime errors. This unblocks **Phase 3: OpenTelemetry Integration** — where agents report metrics and traces to Prometheus, Jaeger, and Datadog. --- - ## Documentation Updates - ### New Guides - - **[SDK-First Mode](../sdk-first-mode.md)** — Comprehensive guide covering concepts, builder reference, patterns, and when to use SDK-First vs. markdown-only - **[SDK Reference](../reference/sdk.md)** — Full builder function signatures, type definitions, runtime validation rules, and examples - ### What Changed - - README includes quick reference for SDK-First teams - CHANGELOG updated with Phase 1 + bug fix deliverables - All sample code demonstrates the builder pattern - Blog post (this document) serves as release announcement --- - ## Testing & Stability - **Test Coverage (v0.8.22 focus areas):** - - 36 builder function tests (`test/builders.test.ts`) — validates runtime type guards for each builder - 24 build command tests (`test/build-command.test.ts`) — `--check`, `--dry-run`, protected file guards - 29 markdown→SDK conversion round-trip tests (`test/sdk-conversion.test.ts`) — ensures config round-trips cleanly - 25 regression tests fixed from PR #221 - 2 Windows EBUSY race condition tests (fs.rm retry logic) - 13 known timeout flakes on Windows (non-logic, environment-related) - **Total test suite:** 3,811 passing tests (3,840 total, 0 logic failures) --- - ## What We Learned - 1. **Type safety is a UX feature.** Developers writing `squad.config.ts` get autocomplete and catch misconfiguration errors at edit time, not at runtime. This pays for itself immediately. - 2. **Builders need to validate deeply.** Each builder runs type guards on input — enum values, required fields, capability levels, routing priorities. This surfaces configuration bugs early. - 3. **Optional dependencies unlock resilience.** Moving OTel to optional eliminated the installation crash entirely. Telemetry should be an add-on, not a blocker. - 4. **Azure Functions unlock serverless agents.** The sample demonstrates that Squad agents can run in a stateless HTTP function. This opens up cost-efficient deployments for batch processing workloads (content review, code analysis, compliance checks). - 5. **Protected files are critical.** `.squad/decisions.md` and `.squad/history.md` must never be overwritten by generated files. This ensures human-written knowledge persists across recompiles. - 6. **Windows needs dedicated testing.** Race conditions in `fs.rm`, CRLF normalization, and timeout thresholds are distinct from Unix environments. CI/CD must test both. --- - ## Node 24+ Compatibility Fix - v0.8.23 fixes a critical crash when running `squad init` on Node.js 24+ (including GitHub Codespaces): - ``` Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'vscode-jsonrpc/node' ``` - The root cause was an upstream ESM import issue in `@github/copilot-sdk`. Squad now uses a two-layer defense: - **Lazy imports** — commands like `init`, `build`, `link`, and `migrate` no longer eagerly load copilot-sdk - **Postinstall patch** — automatically fixes the broken import at install time - This also means CLI startup is faster for non-session commands. --- - ## Squad RC Documentation - Comprehensive documentation for `squad rc` (Remote Control) is now available. The new guide covers ACP passthrough architecture, the 7-layer security model, mobile keyboard shortcuts, and troubleshooting. See [Squad RC](../features/squad-rc.md). --- - ## What's Coming Next - ### v0.8.23 (Roadmap) - - `squad init --sdk` flag — opt-in to SDK-First mode during initialization (#249) - `squad migrate` command — convert existing markdown squads to SDK-First (#250) - Comprehensive SDK-First documentation expansion (#251) - ### Phase 2: Live Reload (Planned) - - `squad build --watch` fully implemented — hot reload of squad.config.ts changes - Agents re-spawn with new config without restarting the CLI - Decision file merging strategies for concurrent edits - ### Phase 3: OpenTelemetry Integration (Unblocked) - - `defineTelemetry()` config → live instrumentation - Agents export metrics and traces to Prometheus, Jaeger, and Datadog - Cost tracking per agent (token spend, wall-clock time) - Performance dashboards in Squad CLI (`squad aspire`) - ### Beyond v0.8.22 - - **Builder linting:** `squad lint` validates config against best practices (agent capability coverage, routing gaps, ceremony scheduling conflicts) - **Config versioning:** `squad config migrate` helpers for breaking changes across SDK versions - **Casting system integration:** `defineCasting()` → live universe selection and overflow handling in coordinator --- - ## Upgrade Path - ### From v0.8.20 → v0.8.22 - ```bash npm install -g @bradygaster/squad-cli@latest # Or in your project: npm install --save-dev @bradygaster/squad-cli@latest ``` - **SDK-First Mode is opt-in.** Existing markdown-based squads continue to work without changes. - ### Fresh Install (Crash Fix Benefit) - If you've had issues with `npx @bradygaster/squad-cli` on fresh machines, v0.8.22 resolves the OTel dependency crash: - ```bash npx @bradygaster/squad-cli@latest doctor # Now works reliably without dependency resolution errors ``` - ### To Migrate to SDK-First (Optional) - 1. Create `squad.config.ts` with builder functions 2. Run `squad build --dry-run` to preview generated files 3. Run `squad build` to generate `.squad/` markdown 4. Commit the config, version control the generated files, and sync your team - Alternatively, keep your markdown-first squad — both modes will coexist indefinitely. --- - ## Getting Started with v0.8.22 - ### Option 1: Stick with Markdown (No Changes Needed) - Your existing `.squad/` markdown-based squads work exactly as before. Upgrade and run: - ```bash npm install -g @bradygaster/squad-cli@latest npx squad doctor npx squad start ``` - ### Option 2: Try SDK-First Mode (New) - ```bash npm install -g @bradygaster/squad-cli@latest mkdir my-sdk-squad && cd my-sdk-squad git init - # Create squad.config.ts with builders # (see quick start above, or copy from samples/azure-function-squad/) - # Build your squad npx squad build - # See the generated markdown cat .squad/team.md - # Run agents (same CLI, same experience) npx squad start ``` - ### Option 3: Explore the Azure Function Sample - ```bash cd samples/azure-function-squad npm install func start # Requires Azure Functions Core Tools - # In another terminal: curl -X POST http://localhost:7071/api/squad-prompt \ -H "Content-Type: application/json" \ -d '{"prompt": "Your review text here"}' ``` - Full sample: [github.com/bradygaster/squad/tree/main/samples/azure-function-squad](https://github.com/bradygaster/squad/tree/main/samples/azure-function-squad) --- - ## Important Fixes for Your Setup - If you've experienced any of these issues, v0.8.22 resolves them: - - ✅ **`npx @bradygaster/squad-cli` crashes on fresh install** (#247) — Fixed via OTel resilience - ✅ **`squad rc` command not found** (#244) — Now wired into CLI - ✅ **Model configuration doesn't persist** (#245) — Fixed round-trip support @@ -610,56 +462,42 @@ If you've experienced any of these issues, v0.8.22 resolves them: - ✅ **25 test regressions** (#221) — All fixed --- - ## Community Credits - This release was shipped by the Squad core team with community contributions: - - **@bradygaster** — Architecture, SDK builders, squad build command, CLI wiring - **@edie** (TypeScript + type safety) — Builder implementations, runtime validation - **@mcmanus** (DevRel) — Documentation, sample walkthrough, blog post - **@fenster** (Testing + reliability) — Test suite, Windows hardening, regression fixes - **@spboyer** — Original remote mode design ([bradygaster/squad#131](https://github.com/bradygaster/squad/pull/131)) - **Community contributors:** - PR #199 — Migration command (feedback captured in #231) - PR #243 — Blankspace fix (cherry-picked) - Thanks to all early SDK-First adopters for feedback. --- - ## Try It Now - ```bash npm install -g @bradygaster/squad-cli@latest mkdir my-sdk-squad && cd my-sdk-squad git init - # Create squad.config.ts with builders # (see quick start above, or copy from samples/azure-function-squad/) - # Build your squad npx squad build - # See the generated markdown cat .squad/team.md - # Run agents (same CLI, same experience) npx squad start ``` --- - ## Links - - [GitHub Repository](https://github.com/bradygaster/squad) - [SDK-First Mode Guide](../sdk-first-mode.md) - [SDK Reference](../reference/sdk.md) - [Azure Function Sample](../../samples/azure-function-squad/) -- [Remote Squad Mode Docs](../features/remote-control.md) +- [Squad RC](../features/squad-rc.md) - [CHANGELOG](https://github.com/bradygaster/squad/blob/main/CHANGELOG.md) - **Related Issues:** - #194 — SDK-First Mode - #213 — Azure Function Sample @@ -672,5 +510,4 @@ npx squad start - #231 — Migration command feedback --- - _This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try SDK-First Mode →](../sdk-first-mode.md)_ diff --git a/docs/src/content/blog/026-whats-new-ado-comms-subsquads.md b/docs/src/content/blog/026-whats-new-ado-comms-subsquads.md index 8c0e22323..21c346762 100644 --- a/docs/src/content/blog/026-whats-new-ado-comms-subsquads.md +++ b/docs/src/content/blog/026-whats-new-ado-comms-subsquads.md @@ -7,23 +7,14 @@ tags: [squad, azure-devops, enterprise, platform-adapter, communication, subsqua status: published hero: "Squad goes enterprise with native Azure DevOps support, adds a CommunicationAdapter for platform-agnostic agent-human messaging, renames Workstreams to SubSquads, and ships critical security hardening across all platform adapters." --- - # What's New: Azure DevOps Adapter, CommunicationAdapter, SubSquads, and Security Hardening - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - > _This batch adds first-class Azure DevOps support, a pluggable communication layer, the community-voted SubSquads rename, and security fixes that prevent shell injection, WIQL injection, and bearer token exposure. 5 PRs merged, 153 new tests, 4 issues closed._ --- - ## What Shipped - ### 1. Azure DevOps Platform Adapter — The Enterprise Feature - Squad now works natively with Azure DevOps. When your git remote points to `dev.azure.com` or `*.visualstudio.com`, Squad auto-detects the platform and adapts everything. - **PlatformAdapter interface** — unified API for GitHub, ADO, and Planner: - ```typescript interface PlatformAdapter { listWorkItems(options): Promise; @@ -34,14 +25,11 @@ interface PlatformAdapter { // ... addTag, removeTag, addComment } ``` - Three adapters ship with the same interface: - **AzureDevOpsAdapter** — `az boards` CLI for work items, `az repos` for PRs - **GitHubAdapter** — `gh` CLI wrapper - **PlannerAdapter** — Microsoft Graph API for hybrid work-item tracking - **Configurable work items** via `.squad/config.json`: - ```json { "platform": "azure-devops", @@ -54,17 +42,11 @@ Three adapters ship with the same interface: } } ``` - All fields are optional. Cross-project support means your work items can live in a completely different ADO org/project than your git repo. - **Ralph on ADO** — the governance file (`squad.agent.md`) now includes a Platform Detection section, ADO WIQL commands for Ralph's scan cycle, and instructions to read `.squad/config.json` before any ADO command. - **Docs:** [Enterprise Platforms Guide](../features/enterprise-platforms.md) | [Blog #025](025-squad-goes-enterprise-azure-devops.md) - ### 2. CommunicationAdapter — Agent-Human Messaging - A new pluggable interface for agent-human communication. Scribe can post session summaries, Ralph can post board status, agents can escalate when blocked — all through a platform-appropriate channel. - ```typescript interface CommunicationAdapter { postUpdate(options): Promise<{ id: string; url?: string }>; @@ -72,7 +54,6 @@ interface CommunicationAdapter { getNotificationUrl(threadId): string | undefined; } ``` - Four adapters: | Adapter | Phone-capable | Setup | @@ -85,16 +66,12 @@ Four adapters: Factory auto-detects platform: `createCommunicationAdapter(repoRoot)`. ### 3. SubSquads — The Community-Voted Rename - Workstreams → SubSquads. The community decided. - - CLI: `squad subsquads` (with `workstreams` and `streams` as deprecated aliases) - Types: `SubSquadDefinition`, `SubSquadConfig`, `ResolvedSubSquad` - Old names kept as `@deprecated` re-exports for backward compatibility - Config file stays at `.squad/streams.json` (file rename deferred) - ### 4. Security Hardening - Every platform adapter went through a community-driven 5-model security review (thanks [@wiisaacs](https://github.com/wiisaacs)): | Fix | What it prevents | @@ -108,7 +85,6 @@ Every platform adapter went through a community-driven 5-model security review ( | `gh issue create` fix | No `--json` flag — parse URL from stdout | ### 5. ESM Runtime Patch + Secret Guardrails (Brady) - - Runtime `Module._resolveFilename` intercept for Node 24+ ESM compatibility - 5-layer secret defense architecture - `.copilot/skills/secret-handling/SKILL.md` team reference @@ -116,9 +92,7 @@ Every platform adapter went through a community-driven 5-model security review ( - Charter hardening for Trejo (Git & Release) and Drucker (CI/CD) --- - ## Quick Stats - - ✅ 5 PRs merged (#191, #263, #268, #272, #266) - ✅ 153 new tests (92 platform + 15 comms + 46 SubSquads) - ✅ 59 security tests (Brady's sprint) @@ -127,24 +101,18 @@ Every platform adapter went through a community-driven 5-model security review ( - ✅ External integration testing: 10/13 ADO tests passed --- - ## Breaking Changes - None. All changes are additive. Repos without ADO remotes work exactly as before. Old `workstreams`/`streams` names still work as deprecated aliases. --- - ## Contributors - - **[@tamirdresher](https://github.com/tamirdresher)** — ADO adapter, CommunicationAdapter, SubSquads rename, security fixes, docs, blog - **[@wiisaacs](https://github.com/wiisaacs)** — 5-model security review with test validation - **[@dfberry](https://github.com/dfberry)** — CommunicationAdapter requirements, tiered deployment proposal - **[@bradygaster](https://github.com/bradygaster)** — ESM fix, secret guardrails sprint, SubSquads merge, architecture guidance --- - ## What's Next - - **Process template introspection** — auto-detect ADO work item types (#240) - **Teams webhook adapter** — full CommunicationAdapter implementation (#261) - **Pre-existing test stabilization** — fix 14 flaky/environment-dependent tests (#273) diff --git a/docs/src/content/blog/027-v0825-release.md b/docs/src/content/blog/027-v0825-release.md index 92221c7a1..c2c6f55b0 100644 --- a/docs/src/content/blog/027-v0825-release.md +++ b/docs/src/content/blog/027-v0825-release.md @@ -7,35 +7,22 @@ tags: [squad, release, v0.8.25, testing, cli, quality, npm] status: published hero: "Squad now smoke-tests every CLI command in the packaged npm artifact before publishing." --- - # v0.8.25: Pre-Publish Quality Gate and CLI Smoke Testing - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - > _This release adds a critical pre-publish quality gate: 32 new tests that pack both `@bradygaster/squad-sdk` and `@bradygaster/squad-cli` into tarballs, install them in a clean temp directory, and verify all 27 CLI commands route correctly through the installed artifact. If a command is missing or broken in the tarball, the release is blocked._ --- - ## What Shipped - ### CLI Packaging Smoke Test - The new test suite (`test/cli-packaging-smoke.test.ts`) simulates the exact npm install experience: - 1. **Pack** — Creates tarballs of both packages using `npm pack` 2. **Install** — Installs them in a clean isolated temp directory (just like `npm install -g` would) 3. **Verify routing** — Tests all 27 CLI commands through the installed artifact's bin entry 4. **Test aliases** — Validates 3 command aliases (watch, workstreams, remote-control) 5. **Error handling** — Tests --version, --help, and unknown command behavior - **32 new tests. 3,963+ tests total.** - ### Pre-Publish CI Gate - The `publish.yml` workflow now includes a `smoke-test` job that runs BEFORE both npm publish jobs. If the smoke test fails, nothing gets published. This blocks the exact class of bugs that bit us before: MODULE_NOT_FOUND errors, broken package.json exports, and ESM resolution failures. - ### Three-Layer Test Matrix - This release completes a three-layer defense: | Layer | What it catches | Test file | @@ -47,24 +34,18 @@ This release completes a three-layer defense: Before this release, a command could exist in source code, pass all tests, and still be missing from the published npm package. That gap is now closed. --- - ## Why This Matters - npm packages are built artifacts. The code you write isn't always the code users install. This test suite verifies that the packaged tarball — the actual bytes users download — works correctly. The squad's own quality agents (FIDO and EECOM) verified the release and gave unanimous GO. --- - ## Quick Stats - - ✅ 32 new CLI packaging smoke tests - ✅ 3,963+ tests passing, 150 test files - ✅ Pre-publish CI gate added to `publish.yml` - ✅ All 27 commands + 3 aliases verified in packaged artifact --- - ## What's Next - - **Process template introspection** — auto-detect ADO work item types (#240) - **Teams webhook adapter** — full CommunicationAdapter implementation (#261) - **Pre-existing test stabilization** — fix 14 flaky/environment-dependent tests (#273) diff --git a/docs/src/content/blog/028-new-docs-site.md b/docs/src/content/blog/028-new-docs-site.md index 49de22a94..07035b798 100644 --- a/docs/src/content/blog/028-new-docs-site.md +++ b/docs/src/content/blog/028-new-docs-site.md @@ -7,76 +7,49 @@ tags: [squad, docs, community, astro, contributions] status: published hero: "Squad's documentation gets a complete rebuild — powered by Astro, Tailwind CSS, and community contributors." --- - # New Docs Site: Built by the Community - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - > _Squad's documentation site has been completely rebuilt from the ground up. A full Astro-powered docs experience with search, responsive design, and content contributed by multiple community members._ --- - ## What Shipped - ### Complete Astro Docs Rewrite - [@IEvangelist](https://github.com/IEvangelist) (David Pine) delivered a **complete documentation site rebuild** in PR #293. This isn't a reskin — it's a ground-up rewrite: - - **Astro 5.7** — Static site generation with component islands - **Tailwind CSS 4.1** — Modern utility-first styling with responsive design - **Pagefind** — Client-side full-text search across all docs - **Structured content** — Markdown content collections with frontmatter validation - **Blog system** — All existing blog posts migrated into the new architecture - **Custom components** — Sidebar with scroll-to-active, syntax-highlighted code blocks, callout boxes - The site ships as a static build under `docs/` with its own `package.json`. Dev server: `npm run dev`. Production build: `astro build && pagefind`. - ### Docs Navigation Polish — PR #298 - [@IEvangelist](https://github.com/IEvangelist) (David Pine) followed up with targeted improvements in PR #298: - - **Active link highlighting** — Docs and Blog links now highlight in the top navigation when you're viewing that section - **Favicon fixes** — Favicon asset handling improved for all browsers - **Navigation clarity** — Users now have better visual feedback about where they are in the docs - This was a fast-follow polish pass on the Astro rewrite, catching the details that make navigation feel solid. - ### Community Content from @diberry - [@diberry](https://github.com/diberry) (Dina Berry) submitted **four pull requests** improving the getting-started experience: - - **PR #286** — Added validation steps to the Quick Start README - **PR #288** — "Which method should I use?" decision tree for the installation page — CLI, VS Code, or SDK, with clear guidance on when to use each - **PR #290** — ".squad/ directory explainer" for the first-session guide — a table showing every file and directory in `.squad/` with its purpose, plus ownership guidance - **PR #292** — Doc-impact review process added to team workflows - All four contributions have been merged or ported into the new Astro docs structure. --- - ## What Changed for Users - ### Better Navigation - The sidebar now scrolls to your current position when a page loads. If you're deep in the table of contents, it stays where you are instead of jumping back to the top. - ### Copilot CLI Callouts - Key pages now include callouts directing users to the **GitHub Copilot CLI** as the recommended interface: - ``` 💡 The recommended way to use Squad is through GitHub Copilot CLI: copilot --agent squad ``` - ### CI/CD Safety Warnings - The CI/CD integration page now ships with the cron schedule **commented out by default** and a warning about GitHub Actions minutes consumption when enabling heartbeats and scheduled runs. --- - ## Community Impact - This release represents a milestone for Squad's community. Two external contributors shaped the docs you'll use: | Contributor | Impact | @@ -87,23 +60,17 @@ This release represents a milestone for Squad's community. Two external contribu Both contributors are now credited in [CONTRIBUTORS.md](https://github.com/bradygaster/squad/blob/main/CONTRIBUTORS.md). --- - ## Try It - Visit the docs at [bradygaster.github.io/squad](https://bradygaster.github.io/squad/) or run them locally: - ```bash cd docs npm install npm run dev ``` - Open [localhost:4321/squad/](http://localhost:4321/squad/) and explore. --- - ## What's Next - - Search refinements and indexing improvements - More scenario guides from community feedback - Continued content contributions welcome — see [CONTRIBUTING.md](https://github.com/bradygaster/squad/blob/main/CONTRIBUTING.md) diff --git a/docs/src/content/blog/028-v090-whats-new.md b/docs/src/content/blog/028-v090-whats-new.md index d42545715..8637d6358 100644 --- a/docs/src/content/blog/028-v090-whats-new.md +++ b/docs/src/content/blog/028-v090-whats-new.md @@ -1,114 +1,62 @@ --- -title: "What's New in v0.9.0: Personal Squad, Worktrees, Cooperative Rate Limiting, and More" +title: "What's New in v0.9.0: Worktrees, Cooperative Rate Limiting, and More" date: 2026-03-23 author: bradygaster wave: 8 -tags: [squad, release, v0.9.0, features, personal-squad, worktree, rate-limiting, economy-mode] +tags: [squad, release, v0.9.0, features, worktree, rate-limiting, economy-mode] status: published -hero: "Squad's biggest release yet — personal agents that follow you across repos, isolated worktrees for conflict-free parallel work, cooperative rate limiting, economy mode for cost control, and a refreshed docs site." +hero: "Squad's biggest release yet — isolated worktrees for conflict-free parallel work, cooperative rate limiting, economy mode for cost control, and a refreshed docs site." --- - # What's New in v0.9.0 - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - -> _This is Squad's biggest release. Personal Squad brings ambient agent discovery and project portability. Worktree spawning isolates each issue into its own branch. Cooperative rate limiting maps traffic across multi-agent teams. Economy Mode lets you budget costs. A complete docs refresh, security hardening, and community contributions make this one to upgrade for._ +> _This is Squad's biggest release. Worktree spawning isolates each issue into its own branch. Cooperative rate limiting maps traffic across multi-agent teams. Economy Mode lets you budget costs. A complete docs refresh, security hardening, and community contributions make this one to upgrade for._ --- - ## What Shipped - -### 1. Personal Squad — Ambient Agent Discovery (#508) - -Your Squad follows you across repositories. - -**Personal agents** are ambient: you configure them once, and they're automatically available in every project you work on — no per-repo setup needed. They discover the projects they work in through the Ghost Protocol: safe interaction that respects your project's boundaries without disrupting other work. - -**CLI commands:** - -```bash -squad personal init # Declare your personal agents -squad personal list # See what's available -``` - -**Governance layer** — Personal agents declare what they need (memory, tools, platforms) and operate within guardrails. A personal coding agent won't blindly touch your enterprise repo; it reads your project's agent charters and `.squad/config.json` first. - -**What this enables:** -- One global Squad definition across all your repos -- Agents that know your coding style, tools, and preferences -- Safe cross-repo work without conflicts -- Team squads + personal squads = complete context - -:::tip -Personal Squad is foundational. It's how your favorite coding agent follows you into a new project without needing re-hiring. -::: - ---- - -### 2. Worktree Spawning — No More Branch Conflicts (#529) - +### 1. Worktree Spawning — No More Branch Conflicts (#529) Each issue gets its own git worktree. - Before: Agents working on multiple issues could block each other on branch conflicts. Now, every issue spawns an isolated worktree. Agents work in parallel, in separate filesystem branches, without touching the main worktree. - **What it solves:** - ✅ Parallel agent work on different issues (no blocking) - ✅ Clean, isolated branch per worktree - ✅ Main worktree stays stable - ✅ Automatic cleanup on issue completion - **How it works:** - Coordinator detects a new issue → spawns `.worktrees/issue-{number}/` - Agent checks out its issue's worktree - Multiple agents can work simultaneously across different worktrees - On completion, worktree is cleaned up automatically - This is the foundation for true parallel work at scale. --- - -### 3. Machine Capability Discovery — Routing to Capable Hardware (#514) - +### 2. Machine Capability Discovery — Routing to Capable Hardware (#514) Agents declare what they need. Ralph routes work to machines that can handle it. - Use `needs:*` labels to tell Ralph what hardware an issue requires: - ``` needs:docker # This agent needs Docker needs:gpu # CUDA-capable GPU required needs:16gb-memory # At least 16GB RAM needs:k8s # Kubernetes cluster access ``` - Ralph's dispatcher reads these labels and routes the work to the machine in your squad pool that has those capabilities. No more "sorry, I can't run Docker here." - **Real-world scenarios:** - ML agents tagged `needs:gpu` route to GPU-equipped machines - Docker-based agents route to machines with Docker daemon running - Multi-region squads balance load based on capabilities - :::note Capability Discovery works with Ralph's mesh routing. If you're not running Ralph, this is aspirational. ::: --- - -### 4. Cooperative Rate Limiting — Predictive Circuit Breaker (#515) - +### 3. Cooperative Rate Limiting — Predictive Circuit Breaker (#515) Multi-agent teams share rate limits responsibly. - Squad now implements **RAAS** — Rate-Aware Agent Scheduler. When your API calls trigger rate limiting, Squad maps `X-RateLimit-Remaining` headers to traffic light states: - - 🟢 **Green** — Normal traffic. Go. - 🟡 **Amber** — Approaching limit. Back off by 30%. - 🔴 **Red** — At/over limit. Wait 5–30 seconds; predictive circuit breaker handles recovery. - **Multi-agent coordination:** All agents in your squad see the same traffic light state. When one agent hits amber, the entire team backs off. No thundering herd, no cascading failures. - **Error surfacing:** Rate limit errors now surface with recovery suggestions: - ``` ⚠️ API rate limit reached. Waiting 15 seconds before retry. Agent: MyAgent | Remaining: 0/60 | Resets: 14:32 UTC @@ -116,19 +64,13 @@ Suggestion: 1 agent idle, 2 backing off. Try serial mode with --cooperative-dela ``` --- - -### 5. Economy Mode — Cost-Conscious Model Selection (#500) - +### 4. Economy Mode — Cost-Conscious Model Selection (#500) Budget-aware routing falls back to cheaper models when spend is high. - When your monthly LLM budget climbs, Economy Mode kicks in: - ```bash squad skill economy-mode enable --budget=50 # USD per agent per day ``` - Now when Claude-Sonnet (expensive) would exceed budget, the router automatically falls back to Claude-Haiku (70% cheaper). The agent still completes the work — just with a more efficient model. - **Governance:** ```typescript const role = await squad.resolveRole('coding-agent', { @@ -136,49 +78,35 @@ const role = await squad.resolveRole('coding-agent', { budgetPerDay: 50, // USD }); ``` - **Real-world impact:** - Reduces spend 40–60% for suitable tasks - Agents choose the most cost-effective model for their task - Human stays in budget control --- - -### 6. Auto-Wired Telemetry (#281) - +### 5. Auto-Wired Telemetry (#281) One call to wire up full observability. - `initSquadTelemetry()` now auto-creates the EventBus and CostTracker: - ```typescript import { initSquadTelemetry } from '@bradygaster/squad-sdk'; - const { eventBus, costTracker } = await initSquadTelemetry({ endpoint: 'https://my-telemetry.com', // Optional; omit for in-process }); - // eventBus is live, costTracker is live // All agent work auto-reports to both ``` - **What you get:** - ✅ Real-time cost visibility per agent - ✅ Event stream for compliance/audit - ✅ Custom event handlers (e.g., Slack alerts on high spend) - ✅ Zero additional setup - No more hunting for telemetry wiring. One call, full observability. --- - -### 7. Upgrade Path Overhaul — P0 Fixes (#544, #549) - +### 6. Upgrade Path Overhaul — P0 Fixes (#544, #549) **Windows EPERM handling** — File permission errors on Windows no longer break upgrades. Automatic retry with temporary directory fallback. - **Gitignore parent coverage** — Upgrade now respects `.gitignore` files in parent directories, preventing unintended file inclusion. - **Context-aware footer** — Upgrade footer includes your project's context: org name, repo, branch, so you know exactly what was upgraded. - **P0 fixes across the board:** - Node <22.5.0 hard-fail with clear error message - Memory safety caps to prevent runaway allocations @@ -186,25 +114,16 @@ No more hunting for telemetry wiring. One call, full observability. - Rate limit errors now surface with recovery options --- - -### 8. Documentation Refresh - +### 7. Documentation Refresh **README slimmed**: 512 → 218 lines. Removed noise, kept substance. - **Upgrade section**: New dedicated docs guide for trouble-free version bumps, with platform-specific steps for Windows, macOS, Linux. - **Consistent install path**: All user-facing docs now reference `npm install -g @bradygaster/squad-cli`. - **Astro features**: 10 new Astro features implemented — section badges, improved search with Pagefind, better syntax highlighting. - **Teams MCP refresh**: Microsoft Teams integration updated for Workflows webhooks. Full docs at [Teams integration guide](../features/mcp.md). - -**Autonomous agents guide**: New guide for building agents that work unsupervised. How to set guardrails, declare intentions, handle escalation. +**Background agent pipeline guide**: New guide for building agents that run in the background with guardrails, clear intentions, and escalation paths. --- - -### 9. Quality & Stability - +### 8. Quality & Stability - ✅ Node <22.5.0 hard-fail with clear message (prevents silent failures) - ✅ Memory safety caps (prevents runaway allocations on large codebases) - ✅ ESM patch improvements for Node 22/24 compatibility @@ -214,20 +133,14 @@ No more hunting for telemetry wiring. One call, full observability. - ✅ ADO CLI exec timeout (prevent hanging on slow networks) --- - -### 10. Community Contributions - +### 9. Community Contributions **Worktree regression tests** — @diberry added tests that guard against regressions in worktree `.git` handling (file vs. directory). - **Docs improvements** — @diberry contributed docs expansion for CLI README and reference. - **Community security review** — Thanks to @wiisaacs and the community for 5-model security review of platform adapters. --- - ## Quick Stats - -- ✅ **5 major features** (Personal Squad, Worktrees, Capability Discovery, Cooperative Rate Limiting, Economy Mode) +- ✅ **4 major features** (Worktrees, Capability Discovery, Cooperative Rate Limiting, Economy Mode) - ✅ **Auto-wired telemetry** in one call - ✅ **P0 upgrade fixes** across Windows, Node compatibility, and error surfacing - ✅ **Docs refresh** — README -46%, new upgrade guide, consistent install path @@ -235,44 +148,30 @@ No more hunting for telemetry wiring. One call, full observability. - ✅ **Community contributions** from 8+ contributors --- - ## Breaking Changes - **None.** All changes are additive. Existing Squads work as-is. New features are opt-in via CLI or config. --- - ## Upgrading - Upgrade to v0.9.0 with: - ```bash npm install -g @bradygaster/squad-cli ``` - Then: - ```bash squad upgrade # Walks you through any project-level config updates ``` - **Docs:** [Upgrade Guide](../scenarios/upgrading.md) | [Troubleshooting](../scenarios/troubleshooting.md) - If you hit issues, [open a GitHub issue](https://github.com/bradygaster/squad/issues). We're here to help. --- - ## What's Next - - **Persistent Ralph** — Watch mode with heartbeat improvements, multi-region mesh routing - **Process template introspection** — Auto-detect ADO work item types at squad init - **Teams webhook CommunicationAdapter** — Full implementation of Teams mobile notifications - **SubSquad orchestration** — Compose squads from other squads; cross-team work at scale - This is an exciting time. v0.9.0 is the release where Squad scales from solo developers to distributed teams. --- - **Questions?** Drop by [Squad Discussions](https://github.com/bradygaster/squad/discussions) or ping us on [Discord](https://discord.gg/squad-community). - -**Want to contribute?** Check out [Contributing Guide](../guide/contributing.md). We're hiring agents (and humans who build them). +**Want to contribute?** Check out [Contributing Guide](../guide/contributing.md). We're always looking for contributors — agents and the humans who build them. diff --git a/docs/src/content/blog/029-upgrade-testing-at-scale.md b/docs/src/content/blog/029-upgrade-testing-at-scale.md index a10e8c199..0c7209641 100644 --- a/docs/src/content/blog/029-upgrade-testing-at-scale.md +++ b/docs/src/content/blog/029-upgrade-testing-at-scale.md @@ -7,37 +7,23 @@ tags: [squad, upgrade, testing, agents, quality] status: published hero: "We used Squad's own fan-out capability to clone 23 real-world repos from GitHub and validate our upgrade command in 5 minutes flat." --- - -We shipped a big upgrade fix — 10 changes addressing 13 gaps our AI team found during an audit. The automated tests passed. 18 out of 18. Green across the board. - +We shipped a big upgrade fix — 10 changes addressing 13 gaps our augmented team found during an audit. The automated tests passed. 18 out of 18. Green across the board. But "tests pass" isn't the same as "this won't break someone's project." We needed a different kind of confidence. - ## The Problem with Testing Upgrade Commands - Upgrade commands are uniquely hard to test. Your automated test suite creates pristine fixtures — perfectly structured directories, predictable file contents, known starting states. Real users are messier. They've deleted files they shouldn't have. They're running versions from six months ago. They've added custom files in directories you own. They've got unicode in their team names and hardcoded paths in their configs. - You can write a hundred synthetic tests and still miss the bug that only shows up when someone's `.gitattributes` already has 20 lines of C# rules and your upgrade appends new entries without a blank line separator. - ## The Approach: Use Your Own Tool to Test Itself - We build an AI agent framework. Our agents can fan out — multiple agents running in parallel, each with its own task, reporting back independently. So we used the framework to test itself. - **Step 1: Find real-world installs.** We used GitHub's code search API to find every public repo with our tool installed: - ``` filename:squad.agent.md path:.github/agents ``` - Result: **245 public repositories.** Real projects, real users, real configurations we'd never seen before. - **Step 2: Design a 3-tier testing strategy.** - - **Tier 1 — Synthetic:** 4 agents simulating controlled scenarios (old version, current version, corrupted state, edge cases like unicode and read-only files) - **Tier 2 — Our repos:** 1 agent cloning 3 of our own projects at different installed versions - **Tier 3 — Public repos:** 4 agents each cloning 4 public repos, running upgrade, taking before/after snapshots - **Step 3: Fan out.** We launched 9 agents in parallel. Each one: - 1. Checked out our fix branch and built the CLI 2. Created an isolated temp directory 3. Ran the upgrade @@ -46,9 +32,7 @@ Result: **245 public repositories.** Real projects, real users, real configurati 6. Verified every file that shouldn't have changed didn't 7. Ran the upgrade *again* to test idempotency 8. Cleaned up - **Zero impact to any public repo.** Shallow clones to temp directories, tested locally, deleted when done. No pushes, no PRs, no issues, no comments. Read-only interaction with GitHub. - ## The Numbers | Tier | Targets | Checks | Passed | Failed | @@ -59,11 +43,9 @@ Result: **245 public repositories.** Real projects, real users, real configurati | **Total** | **23** | **245** | **244** | **1** | **99.6% pass rate.** The one failure was a read-only filesystem edge case — the upgrade threw a raw stack trace instead of a friendly warning. Valid bug, easy fix, and we never would have tested for it with synthetic fixtures alone. - Wall-clock time for all of this: **about 5 minutes.** Nine agents working simultaneously, each taking 3-5 minutes to clone, build, test, and clean up. ## What the Version Span Looked Like - We tested upgrades from every version we encountered in the wild: | Starting Version | Repos | @@ -78,59 +60,40 @@ We tested upgrades from every version we encountered in the wild: No version was too old. The oldest repo — installed from source with version `0.0.0` — upgraded cleanly to current. Every version in between worked too. ## What We Actually Checked - Every repo got the same verification checklist. Infrastructure on one side, user state on the other: - **Must change:** - Config files updated with merge rules and gitignore entries - Missing directories created (up to 6) - 28 skills deployed - 30 template files refreshed - Version stamp updated - **Must NOT change:** - Team roster - Decision log - Routing rules - Agent charters and histories - User configuration - **Must survive a second run:** - No duplicate entries in any config file - No errors - No corruption - Across 23 test targets spanning versions 0.0.0 through 0.8.25, team sizes from 5 to 12 agents, and projects in .NET, Node.js, Python, Flutter, and Rust: **zero user files were modified.** - ## What We Found That Surprised Us - The synthetic tests caught the obvious stuff. The real repos caught the stuff you'd never think to test for: - **Smart deduplication works.** One repo had 4 of 5 required `.gitignore` entries from a previous version. The upgrade detected the 4 existing entries and added only the 1 missing one. Not "overwrite all 5" — surgically precise. We didn't specifically test for this. We discovered it was working correctly by running against a real repo that happened to be in that state. - **Custom content survives.** Multiple repos had custom files inside directories we manage — investigation summaries, design specs, audit reports created by agents in past sessions. All of them survived the upgrade untouched. One repo even had a retired agents directory (`_alumni/`). Preserved perfectly. - **Legacy detection is graceful.** One repo was still using our old directory name from months ago. The upgrade detected it, printed a clear deprecation warning with an actionable migration command, and proceeded without crashing. We'd written that code, but we'd never tested it against a real legacy install in the wild. - **Privacy scrubbing works — but contradicts itself.** Two repos had email addresses in their team files from before we added privacy protections. The upgrade correctly scrubbed them. Good feature. But the console output ends with "Never touches user state" — which is technically false when the privacy scrub just modified 5 files. Small messaging fix, but we wouldn't have caught it without testing against repos old enough to have that data. - ## The Meta Insight - Here's what made this approach powerful: **the same fan-out capability we build for users is exactly what we needed to validate our own upgrade path.** We didn't write a special testing harness. We didn't set up CI matrices. We told our agents "go clone these repos, run upgrade, tell me what happened" — and they did, in parallel, in minutes. - The three tiers gave us three kinds of confidence: - **Synthetic** tells you the code handles expected cases correctly - **Your own repos** tells you the code handles real-but-familiar cases correctly - **Strangers' repos** tells you the code handles cases you never imagined - That last tier is the one most teams skip. It's also the one that found the most interesting issues. - ## The Takeaway - If your tool has a public footprint — if real people have installed it and configured it and built things on top of it — you have a free test corpus sitting on GitHub. Clone it, test against it, delete it. Zero impact, maximum confidence. - Your upgrade command's job is to make old installs current without touching what users built on top. That's the contract. Your test suite tells you the code works. Real repos tell you the *contract* holds. --- - *We tested 23 repos in about 5 minutes. Found 3 bugs (1 real, 2 messaging). Fixed them before merging. The upgrade shipped the next morning.* diff --git a/docs/src/content/blog/030-v092-whats-coming.md b/docs/src/content/blog/030-v092-whats-coming.md index f51b0860f..83ffda6fc 100644 --- a/docs/src/content/blog/030-v092-whats-coming.md +++ b/docs/src/content/blog/030-v092-whats-coming.md @@ -6,80 +6,50 @@ tags: [squad, release, features, watch, cleanup, fact-checker, external-state, s status: draft hero: "The next Squad release ships 10 new features, 4 bug fixes, and 60+ tests — all backward-compatible. Here's what to expect." --- - # What's Coming in v0.9.2 — 10 Features, Zero Breaking Changes - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - > _The next Squad release ships 10 new features, 4 bug fixes, and 60+ tests — all backward-compatible. Here's what to expect._ - ## The Noise Problem - If you've been running `squad watch` in production with output forwarded to Teams or Slack, you've probably noticed this: - ``` Squad Monitor Round 158 Squad Monitor Round 159 Squad Monitor Round 160 Squad Monitor Round 161 ``` - Hundreds of messages. No useful information. No way to tell which machine or repo they came from. - This release fixes that — and ships 9 other features while we're at it. - ## New Features - ### 1. Quiet Notifications (`--notify-level`) - The biggest quality-of-life improvement: watch rounds are now **silent by default when the board is empty**. Only rounds with actual work produce output. - ```bash squad watch --notify-level important # default — only meaningful rounds squad watch --notify-level all # old behavior (every round) squad watch --notify-level none # fully silent ``` - Round headers now include **machine name and repo** for attribution: - ``` 🔄 Ralph — Round 5 (DEVBOX-01 · my-project) ``` - Persistent config: `{ "watch": { "notifyLevel": "important" } }` in `.squad/config.json`. - ### 2. Fleet Hybrid Dispatch (`--dispatch-mode`) - Parallel issue processing via Copilot CLI `/fleet`. Benchmarked at **2.9x faster** for read-heavy workloads. - ```bash squad watch --execute --dispatch-mode hybrid ``` - Issues are auto-classified as read (research, reviews → fleet) or write (implementations, fixes → local). Fleet batches reads in parallel while writes execute sequentially. - ### 3. Verbose Debugging (`--verbose`) - When watch seems stuck on "Board is clear" but you know there's work, `--verbose` shows you exactly what's happening: - ```bash squad watch --verbose ``` - Prints: issue counts, label matches, auth status, PR review states, round timing, capability execution paths. - ### 4. Fact-Checker Agent Role (🔍) - New built-in role for output verification. Validates claims, detects hallucinations, runs counter-hypotheses. - ``` squad new agent fact-checker ``` - Confidence ratings: ✅ Verified, ⚠️ Unverified, ❌ Contradicted. Routes automatically on "fact-check", "verify", "audit" keywords. - ### 5. 8 Built-in Skills - `squad init` and `squad upgrade` now ship 8 curated skills: | Skill | What it teaches | @@ -94,65 +64,45 @@ Confidence ratings: ✅ Verified, ⚠️ Unverified, ❌ Contradicted. Routes au | agent-collaboration | Multi-agent handoffs | ### 6. Scratch Directory (`.squad/.scratch/`) - Agents no longer dump temp files in the repo root. The new `scratchDir()` and `scratchFile()` SDK APIs route all ephemeral files to `.squad/.scratch/` — gitignored and auto-cleaned. - ### 7. Cleanup Watch Capability - Automated housekeeping during `squad watch`: - Clears `.squad/.scratch/` every 10 rounds - Archives orchestration-log and session-log entries older than 30 days - Warns about stale decision inbox files (>7 days) - ### 8. External State Storage - Move `.squad/` state outside the working tree so it survives branch switches: - ```bash squad externalize # state moves to ~/.squad/projects/{repo}/ squad internalize # move it back ``` - ### 9. Self-Upgrade (`squad upgrade --self`) - Update the CLI itself from within squad: - ```bash squad upgrade --self # latest stable squad upgrade --self --insider # latest prerelease ``` - Auto-detects npm/pnpm/yarn. After CLI upgrade, automatically runs repo upgrade to apply new templates. - ### 10. Triage Label Slug Fix - Multi-word agent names (like "Steve Rogers") now correctly generate `squad:steve-rogers` labels instead of `squad:steve rogers` (which GitHub rejects). Labels are pre-created at watch startup. - ## Bug Fixes - - **PR contamination** — Scribe now stages only `.squad/` files, not broad staging commands (#783) - **Outdated review threads** — PR readiness check ignores threads where code changed (#780) - **Filename uniqueness** — `scratchFile()` uses monotonic counter, not just `Date.now()` - **Cross-platform paths** — `deriveProjectKey()` handles Windows paths on Linux CI - ## By the Numbers - - **10 features** across SDK, CLI, and watch capabilities - **4 bug fixes** (1 critical — PR contamination) - **60+ new tests** (scratch: 8, cleanup: 12, fact-checker: 8, skills: 5, external: 12, self-upgrade: 4, notify: 5, triage: 12) - **4 new feature docs** + 2 updated + README command table (15→17) - **0 breaking changes** — all opt-in, all backward-compatible - **1 behavioral change** — notify default flipped from `all` to `important` (use `--notify-level all` to restore) - ## Upgrade - ```bash squad upgrade --self # get the latest CLI squad upgrade # apply new templates to your repo ``` - Or if you're on insider: - ```bash squad upgrade --self --insider ``` diff --git a/docs/src/content/blog/031-state-backends.md b/docs/src/content/blog/031-state-backends.md index bc7012313..eede02376 100644 --- a/docs/src/content/blog/031-state-backends.md +++ b/docs/src/content/blog/031-state-backends.md @@ -6,30 +6,19 @@ tags: [squad, state-backends, git-notes, orphan-branch, two-layer, architecture] status: draft hero: "Squad now supports 4 state backends that keep .squad/ files out of your PRs. Choose local, orphan branch, or the two-layer architecture from the blog." --- - # State Backends — Keep Your PRs Clean - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - > _Squad now supports 4 state backends. Your PRs stay clean — just code._ - ## The Problem - Every time an agent makes a decision, writes to history, or logs a session, those changes end up as `.squad/` file modifications in your working branch. Open a PR and your reviewer sees 57 code changes buried under 40 decision logs, agent history entries, and session files. - Two completely different workflows sharing one branch: - **Code** → slow, human-gated, needs review approval -- **Squad state** → fast, autonomous, no human ever needs to review it - +- **Squad state** → fast, background-managed — no ceremony required ## The Fix - PR #1004 adds state backend support. One line in your config, and all mutable state goes somewhere else. - ```bash # The fastest path to clean PRs: squad init --state-backend two-layer ``` - ## Four Options | Backend | Where state goes | PRs clean? | Setup | @@ -39,65 +28,45 @@ squad init --state-backend two-layer | `two-layer` | Notes + orphan combined | ✅ | `--state-backend two-layer` | ## The Two-Layer Architecture - The `two-layer` option implements the architecture from [Tamir's blog post](https://www.tamirdresher.com/blog/2026/03/23/scaling-ai-part7b-git-notes): - - **Layer 1 (git notes):** Thin commit-scoped "why" annotations. Invisible in PR diffs. Attached to specific commits. - **Layer 2 (orphan branch):** Permanent state store. Decisions, histories, logs. The team's full diary. - **Ralph bridges the layers:** After a PR merges, Ralph promotes notes with `promote_to_permanent: true` to the orphan branch. Notes on rejected PRs are silently ignored. - This handles the three scenarios from the blog correctly: 1. **Rejected feature** — decision on a rejected PR is NOT promoted ✅ 2. **Universal truth** — routing change flagged with `promote_to_permanent` survives ✅ 3. **Valuable failure** — research flagged with `archive_on_close` is preserved ✅ - ## How It Works (Under the Hood) - The Squad coordinator (`squad.agent.md`) detects `stateBackend` from `.squad/config.json` at session start and adapts every agent spawn prompt: - - **Agents** receive backend-specific instructions for reading and writing state - **Scribe** receives backend-specific commit targets (orphan branch, note refs, or working branch) - **State Leak Guard** catches if an agent accidentally stages state files on the working branch - Static config (charters, team.md, routing.md) always stays on disk. Only mutable state (decisions, history, logs) moves to the configured backend. - ## Quick Start - ```bash # New project — set backend at init time squad init --state-backend two-layer - # Existing project — migrate with one config change # Edit .squad/config.json → add "stateBackend": "two-layer" git add .squad/config.json && git commit -m "config: use two-layer" ``` - For the full migration guide and troubleshooting, see the [State Backends feature docs](/docs/features/state-backends/). - ## Tested With Real Squads - We ran 12 E2E tests with real squad sessions — real team casting (Usual Suspects, Firefly universes), real agent spawns, real decisions recorded. All evidence is in [PR #1004](https://github.com/bradygaster/squad/pull/1004). - Key proof: - Git notes with `promote_to_permanent: true` written by agents ✅ - Orphan branch receives state commits from Scribe ✅ - Feature branch PRs show ONLY code changes, zero `.squad/` state ✅ - State persists across branch switches ✅ - ## Try It - Build from the PR branch: - ```bash git clone https://github.com/bradygaster/squad.git cd squad && git checkout feat/state-backend-global-996 npm install && npm run build ``` - Then init any repo with your preferred backend: - ```bash node /packages/squad-cli/dist/cli-entry.js init --state-backend two-layer ``` - We'd love feedback — especially on whether the init flow feels right and whether state actually persists across branch switches in your environment. diff --git a/docs/src/content/blog/watch-monitor.md b/docs/src/content/blog/watch-monitor.md index 2f4383302..5053931ef 100644 --- a/docs/src/content/blog/watch-monitor.md +++ b/docs/src/content/blog/watch-monitor.md @@ -4,40 +4,25 @@ date: 2026-03-30 author: "Brady" tags: [squad, ralph, watch, work-monitor, automation, execution] status: published -hero: "Ralph started as a label router that idled when the board was clear. Now he spawns Copilot sessions and actually does the work." +hero: "Ralph started as a label router that idled when the board was clear. Now he spawns Copilot sessions and moves approved work forward." --- - # From Triage Bot to Work Monitor - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - -> _Ralph started as a label router that idled when the board was clear. Now he spawns Copilot sessions and actually does the work._ - +> _Ralph started as a label router that idled when the board was clear. Now he spawns Copilot sessions and moves approved work forward._ ## What Changed - `squad watch` used to be a simple triage loop. Every N minutes, it would: - 1. Fetch open issues with the `squad` label 2. Route them to team members based on routing rules 3. Add labels like `squad:eecom` or `squad:gnc` 4. Idle when done - -That's it. Ralph was a label router — useful, but not autonomous. When the board cleared, Ralph just sat there waiting for humans to do the work. - +That's it. Ralph was a label router — useful, but limited. When the board cleared, Ralph just sat there waiting for humans to move the work forward. **Issue #708 changed that.** - With `--execute`, Ralph transforms from a triage bot into a full work monitor. He doesn't just label issues — he spawns Copilot CLI sessions to actually work on them. - ```bash squad watch --execute --interval 15 ``` - This one flag turns Ralph from a watcher into a worker. - ## The Unix Pipe Philosophy - The design follows the Unix philosophy: each flag is a composable feature that does one thing well. - - `--execute` → spawn Copilot sessions for actionable issues - `--monitor-teams` → scan Teams messages via WorkIQ - `--monitor-email` → scan email for alerts and action items @@ -46,26 +31,20 @@ The design follows the Unix philosophy: each flag is a composable feature that d - `--wave-dispatch` → parallel sub-task execution within issues - `--retro` → enforce retrospective checks (Fridays or >7 days) - `--decision-hygiene` → auto-merge decision inbox when >5 files - Each flag is opt-in. Existing `squad watch` behavior is unchanged — triage only, no execution. - ## Code Example: From Simple to Full Monitor - **Basic triage (original behavior):** ```bash squad watch ``` - **Add execution:** ```bash squad watch --execute ``` - **Add project board lifecycle:** ```bash squad watch --execute --board ``` - **Full monitor with all features:** ```bash squad watch --execute \ @@ -77,11 +56,8 @@ squad watch --execute \ --max-concurrent 2 \ --interval 15 ``` - ## Architecture of a Round - When all features are enabled, each round follows this cycle: - 1. **Self-pull**: `git fetch && git pull --ff-only` to stay current 2. **Scan**: Fetch open issues (two-pass if enabled: lightweight list → hydrate actionable only) 3. **Triage**: Label untriaged issues based on routing rules @@ -102,9 +78,7 @@ When all features are enabled, each round follows this cycle: - Retro: if it's Friday after 14:00 UTC or last retro was >7 days ago, spawn a retro session - Decision hygiene: if `.squad/decisions/inbox/` has >5 files, spawn a merge session 8. **Report**: Log round summary, sleep until next interval - ## Example Execution Output - ``` 🔄 Ralph — Round 1 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━ @@ -114,13 +88,10 @@ When all features are enabled, each round follows this cycle: ▶ [14:23:10] Executing #42 "Fix auth redirect bug" → gh copilot --message "Work on issue #42..." ✓ [14:25:43] #42 completed - ▶ [14:25:44] Executing #45 "Add retry logic" → gh copilot --message "Work on issue #45..." ✓ [14:28:20] #45 completed - ▶ [14:28:21] Executing #47 "Update docs" → gh copilot --message "Work on issue #47..." ✗ [14:58:21] #47 failed: Timed out after 30m - [14:58:22] Two-pass: 15 total → 3 actionable (hydrated) [14:58:23] Board: #42 → Done [14:58:23] Board: #45 → Done @@ -128,47 +99,36 @@ When all features are enabled, each round follows this cycle: ✓ [14:58:25] Email monitor scan complete [14:58:26] Round 1 complete — sleeping 15 minutes ``` - ## The Three Layers of Ralph | Layer | When | How | |-------|------|-----| | **In-session** | You're at the keyboard | "Ralph, go" — active loop while work exists | | **Local watchdog** | You're away but machine is on | `squad watch --execute` | -| **Cloud heartbeat** | Fully unattended | `squad-heartbeat.yml` GitHub Actions events | +| **Cloud heartbeat** | Event-driven | `squad-heartbeat.yml` GitHub Actions events | -The in-session loop is ephemeral — it lives only while the Copilot session is active. The local watchdog runs as a separate process and polls at your chosen interval. The cloud heartbeat is the fully unattended layer that triggers on GitHub events (issue close, PR merge, manual dispatch). +The in-session loop is ephemeral — it lives only while the Copilot session is active. The local watchdog runs as a separate process and polls at your chosen interval. The cloud heartbeat is the event-driven layer that triggers on GitHub events (issue close, PR merge, manual dispatch). ## Why This Matters - Before #708, Ralph was a coordinator. He routed work to team members but never picked up the tools himself. - Now, Ralph is a worker. He claims issues, posts comments, spawns Copilot sessions, manages the project board, scans Teams and email, and enforces governance checks. - This closes the gap between "someone triaged this issue" and "someone is working on this issue." Ralph doesn't just label the work — he starts it. - ## What's Next - The next iteration will add: - - **SubSquad discovery**: automatically detect `.squad/subsquads/` for routing across multiple codebases - **Channel routing**: route notifications to specific Teams channels based on work type - **Multi-machine coordination**: distribute work across multiple Ralph instances - Ralph is no longer just a triage bot. He's a work monitor — and he's just getting started. --- - **Try it:** ```bash squad watch --execute --interval 15 ``` - **Full feature set:** ```bash squad watch --execute --board --two-pass --monitor-teams --retro --decision-hygiene --max-concurrent 2 ``` --- - _PR #709 · Issue #708 · Shipped 2026-03-30_