diff --git a/docs/src/content/docs/guide.md b/docs/src/content/docs/guide.md index 246809f77..37884535a 100644 --- a/docs/src/content/docs/guide.md +++ b/docs/src/content/docs/guide.md @@ -1,6 +1,6 @@ # Squad — Product Guide -## What Is Squad? +## What is Squad? Squad gives you an AI development team through GitHub Copilot. You describe what you're building. Squad proposes a team of specialists — lead, frontend, backend, tester — that live in your repo as files. Each agent runs in its own context window, reads its own knowledge, and writes back what it learned. They persist across sessions, share decisions, and get better the more you use them. @@ -14,10 +14,14 @@ It is not a chatbot wearing hats. Each team member is spawned as a real sub-agen **Use Squad CLI for setup and operations:** - Initial setup: `squad init` +- Build from config: `squad build` - Diagnostics: `squad doctor` +- Interactive shell: `squad shell` - Continuous triage: `squad triage --interval 10` +- Watch mode: `squad watch` - Aspire dashboard: `squad aspire` - Export/import: `squad export` and `squad import` +- Plugin management: `squad plugin install ` **Common workflow:** ```bash @@ -33,16 +37,18 @@ Both CLIs read and write the same `.squad/` directory, so state stays synchroniz --- -## Supported Platforms +## Supported platforms Squad works across multiple interfaces — GitHub Copilot CLI, VS Code, Squad CLI, SDK, and the Copilot Coding Agent. Pick the one that fits your workflow: - **GitHub Copilot CLI** — Day-to-day conversational work with your squad (recommended) - **VS Code** — Same experience, editor-integrated - **Squad CLI** — Setup, diagnostics, monitoring (`squad init`, `squad doctor`, `squad watch`) -- **SDK** — Build tools on top of Squad +- **SDK** — Build tools on top of Squad with `squad.config.ts` - **Copilot Coding Agent** — Autonomous issue processing via `@copilot` +**Multi-platform support:** Squad also works with Azure DevOps (work items, PRs via `az boards`/`az repos`), GitLab Issues, and Microsoft Planner through pluggable platform adapters. See [Enterprise Platforms](features/enterprise-platforms.md) for details. + Not sure which to use? See [Choose your interface](get-started/choose-your-interface.md) for a complete comparison and decision tree. --- @@ -50,20 +56,26 @@ Not sure which to use? See [Choose your interface](get-started/choose-your-inter ## Installation ```bash -npx github:bradygaster/squad +npm install -g @bradygaster/squad-cli +``` + +Or run without installing: + +```bash +npx @bradygaster/squad-cli init ``` **Requirements:** - Node.js 20+ (LTS) - GitHub Copilot (CLI, VS Code, Visual Studio, or Coding Agent) -- A git repository (Squad stores team state in `.ai-team/`) +- A git repository (Squad stores team state in `.squad/`) - **`gh` CLI** — required for GitHub Issues, PRs, Ralph, and Project Boards ([install](https://cli.github.com/)) -This copies `squad.agent.md` into `.github/agents/`, installs 10 GitHub Actions workflows into `.github/workflows/`, and adds templates to `.ai-team-templates/`. Your actual team (`.ai-team/`) is created at runtime when you first talk to Squad. +Running `squad init` creates the `.squad/` directory structure, copies `squad.agent.md` into `.github/agents/`, and installs GitHub Actions workflows into `.github/workflows/`. Your team is created at runtime when you first talk to Squad. -**Note:** When you select Squad from the agent picker, you'll see the version number in the name (e.g., "Squad (v0.3.0)"). This helps you confirm which version is installed. +**Note:** When you select Squad from the agent picker, you'll see the version number in the name (e.g., "Squad (v0.8.25)"). This helps you confirm which version is installed. -### GitHub CLI Authentication +### GitHub CLI authentication Squad uses the `gh` CLI for all GitHub API operations — issues, PRs, labels, project boards, and Ralph's work monitoring. You must authenticate before using any of these features. @@ -83,7 +95,7 @@ gh auth status **Additional scopes** — some features require scopes beyond the default: -| Feature | Required Scope | Command | +| Feature | Required scope | Command | |---------|---------------|---------| | Issues, PRs, Ralph | `repo` (included by default) | — | | Project Boards | `project` | `gh auth refresh -s project` | @@ -99,31 +111,31 @@ The `gh auth refresh` command adds scopes to your existing token — it takes ab --- -## How Teams Form (Init Mode) +## How teams form (init mode) When you open Copilot and select **Squad** for the first time in a repo, there's no team yet. Squad enters Init Mode: 1. **Squad identifies you** via `git config user.name` and uses your name in conversation. 2. **You describe your project** — language, stack, what it does. -3. **Squad casts a team** — agents get names from a single fictional universe (e.g., The Usual Suspects, Alien, Ocean's Eleven). The universe is selected deterministically based on team size, project shape, and what's been used before. Names are persistent identifiers — they don't change the agent's behavior or voice. +3. **Squad casts a team** — agents get names from a single fictional universe (e.g., Apollo 13 / NASA Mission Control, The Usual Suspects, Ocean's Eleven). The universe is selected deterministically based on team size, project shape, and what's been used before. Names are persistent identifiers — they don't change the agent's behavior or voice. 4. **Squad proposes the team:** ``` -🏗️ Ripley — Lead Scope, decisions, code review -⚛️ Dallas — Frontend Dev React, UI, components -🔧 Kane — Backend Dev APIs, database, services -🧪 Lambert — Tester Tests, quality, edge cases +🏗️ FLIGHT — Lead Scope, decisions, code review +⚛️ RETRO — Frontend Dev React, UI, components +🔧 GNC — Backend Dev APIs, database, services +🧪 TELMU — Tester Tests, quality, edge cases 📋 Scribe — (silent) Memory, decisions, session logs ``` 5. **You confirm** — say "yes", adjust roles, add someone, or just give a task (which counts as implicit yes). -Squad then creates the `.ai-team/` directory structure with charters, histories, routing rules, casting state, and ceremony config. Each agent's `history.md` is seeded with your project description and tech stack so they have day-1 context. +Squad then creates the `.squad/` directory structure with charters, histories, routing rules, casting state, and ceremony config. Each agent's `history.md` is seeded with your project description and tech stack so they have day-1 context. ### What gets created ``` -.ai-team/ +.squad/ ├── team.md # Roster — who's on the team ├── routing.md # Who handles what ├── ceremonies.md # Team meeting definitions @@ -148,17 +160,17 @@ Squad then creates the `.ai-team/` directory structure with charters, histories, --- -## Talking to Your Team (Routing) +## Talking to your team (routing) How you phrase your message determines who works on it. ### Name an agent directly ``` -> Ripley, fix the error handling in the API +> FLIGHT, fix the error handling in the API ``` -Squad spawns Ripley specifically. +Squad spawns FLIGHT specifically. ### Say "team" for parallel fan-out @@ -188,7 +200,7 @@ Squad answers directly without spawning an agent. | You say | What happens | |---------|-------------| -| `"Dallas, set up the project structure"` | Dallas (Frontend) scaffolds the project | +| `"RETRO, set up the project structure"` | RETRO (Frontend) scaffolds the project | | `"Team, build the user dashboard"` | Multiple agents launch in parallel | | `"Where are we?"` | Squad gives a quick status from recent logs | | `"Run a retro"` | Lead facilitates a retrospective ceremony | @@ -197,7 +209,7 @@ Squad answers directly without spawning an agent. --- -## Response Modes +## Response modes Squad automatically picks the right response speed based on your request complexity. Direct answers take seconds, full agent spawns take longer but deliver deeper reasoning and parallel work. You don't control the mode — Squad routes based on what the task needs. @@ -205,7 +217,140 @@ Squad automatically picks the right response speed based on your request complex --- -## Memory System +## SDK-first mode + +Define your team in TypeScript instead of maintaining markdown files manually. Write a `squad.config.ts` with type-safe builder functions, and `squad build` generates the `.squad/` governance markdown. + +```typescript +import { defineSquad, defineTeam, defineAgent, defineRouting } from '@bradygaster/squad-sdk'; + +export default defineSquad({ + team: defineTeam({ + name: 'Core Squad', + description: 'The main engineering team', + members: ['@edie', '@mcmanus'], + }), + agents: [ + defineAgent({ + name: 'edie', + role: 'TypeScript Engineer', + model: 'claude-sonnet-4', + capabilities: [{ name: 'type-system', level: 'expert' }], + }), + ], + routing: defineRouting({ + rules: [{ pattern: 'feature-*', agents: ['@edie'], tier: 'standard' }], + defaultAgent: '@coordinator', + }), +}); +``` + +**Get started:** + +```bash +squad init --sdk # New project with SDK config +squad migrate --to sdk # Convert existing .squad/ to TypeScript +squad build # Generate .squad/ from config +squad build --check # Validate in CI without writing +``` + +Builder functions: `defineTeam()`, `defineAgent()`, `defineRouting()`, `defineCeremony()`, `defineHooks()`, `defineCasting()`, `defineTelemetry()`, `defineSkill()`, `defineSquad()`. + +→ [Full guide: SDK-First Mode](sdk-first-mode.md) + +--- + +## Casting system + +Squad names agents from fictional universes — Apollo 13 / NASA Mission Control (the default), The Usual Suspects, Breaking Bad, Star Trek, and others. The universe is selected deterministically based on team size and project shape. + +Casting is **persistent** — once an agent receives a name, it keeps that name across sessions. The casting registry lives in `.squad/casting/registry.json`. You control which universes are available through a policy allowlist and can set per-universe capacity limits. + +In SDK-first mode, configure casting with `defineCasting()`: + +```typescript +defineCasting({ + allowlistUniverses: ['Apollo 13', 'Breaking Bad'], + overflowStrategy: 'generic', + capacity: { 'Apollo 13': 8 }, +}); +``` + +When a universe runs out of names, the overflow strategy determines what happens: `reject` (error), `generic` (use a functional name), or `rotate` (move to the next universe). + +--- + +## Skills system + +Skills are reusable knowledge patterns that agents load on demand. They live in `.squad/skills/{name}/SKILL.md` and teach agents how to handle specific tasks — branching workflows, deployment strategies, testing patterns, or domain expertise. + +Skills have a confidence lifecycle: `low` → `medium` → `high`, and track their source: `manual` (you wrote it), `observed` (agent saw a pattern), `earned` (validated through use), or `extracted` (imported from another project). + +In SDK-first mode, define skills with `defineSkill()`: + +```typescript +defineSkill({ + name: 'git-workflow', + description: 'Squad branching model and PR conventions', + domain: 'workflow', + confidence: 'high', + source: 'manual', + content: ` + ## Patterns + - Branch from dev: squad/{issue-number}-{slug} + - PRs target dev, not main + `, +}); +``` + +Skills accumulate as you work. After a few sessions, your team has a knowledge base tailored to your codebase. + +→ [Full guide: Skills](features/skills.md) + +--- + +## Ceremonies + +Ceremonies are structured team meetings. Squad ships with two default ceremonies — Design Review (triggers before multi-agent work) and Retrospective (triggers after failures). You can trigger ceremonies manually, create custom ones, or disable them. Configuration lives in `.squad/ceremonies.md`. + +In SDK-first mode, define ceremonies with `defineCeremony()`: + +```typescript +defineCeremony({ + name: 'standup', + trigger: 'schedule', + schedule: '0 9 * * 1-5', + participants: ['@edie', '@mcmanus'], + agenda: 'Yesterday / Today / Blockers', +}); +``` + +→ [Full guide: Ceremonies](features/ceremonies.md#ceremonies) + +--- + +## Ralph — work monitor + +Ralph triages your issue backlog, assigns work to agents, and keeps the board moving. Activate Ralph when you have open issues, and he reports every 3–5 rounds. + +``` +> Ralph, start monitoring +``` + +**CLI commands:** +- `squad triage` — run a single triage pass +- `squad triage --interval 10` — continuous triage every 10 minutes +- `squad watch` — Ralph watchdog mode (monitors and auto-restarts) + +The `squad-heartbeat` workflow runs Ralph on a schedule — your squad triages issues between sessions. + +**Note:** `squad ralph` is a legacy alias. New projects should use `squad triage`. + +→ [Full guide: Ralph — Work Monitor](features/ralph.md#ralph--work-monitor) + +--- + +## Memory system Squad's memory is layered — personal agent histories, shared team decisions, and reusable skills. Knowledge compounds over sessions. After a few sessions, agents stop asking questions they've already answered. Mature projects carry full architecture knowledge and decision history. @@ -213,15 +358,49 @@ Squad's memory is layered — personal agent histories, shared team decisions, a --- -## Export and Import +## Plugin marketplace + +Extend your squad with community plugins — reusable collections of skills, ceremonies, and directives. + +```bash +squad plugin install github/my-org/my-extension +squad plugin list +squad plugin remove my-extension +``` + +Plugins let you add domain expertise (Azure infrastructure patterns), workflow templates (client-delivery processes), or testing ceremonies without modifying Squad core. Build your own and share them. + +→ [Full guide: Plugins](features/plugins.md) | [Marketplace](features/marketplace.md) + +--- + +## SubSquads (streams) + +Break large teams into focused SubSquads — smaller groups that work independently on different features or domains. SubSquads maintain their own routing and task queues while sharing the parent squad's decisions and memory. + +```bash +squad subsquads +``` + +→ [Full guide: Streams](features/streams.md) + +--- + +## Export and import Export creates a portable snapshot of your entire team — agents, knowledge, skills. Import brings that snapshot into another repo. Squad handles collision detection and splits imported knowledge into portable learnings and project-specific context automatically. +```bash +squad export --out my-team.json +squad import my-team.json +squad import my-team.json --force # Archive existing agents first +``` + → [Full guide: Export and Import](features/export-import.md#export--import) --- -## GitHub Issues Mode +## GitHub Issues mode Squad integrates with GitHub Issues for issue-driven development. Connect to a repo, view the backlog, assign issues to agents, and Squad handles branch creation, implementation, PR creation, and review feedback. Agents link work to issues automatically. @@ -229,7 +408,7 @@ Squad integrates with GitHub Issues for issue-driven development. Connect to a r --- -## PRD Mode +## PRD mode Paste your product requirements document directly into Squad. The Lead agent decomposes the spec into discrete work items, assigns them to the right agents, and the team works in parallel. Specs become trackable tasks automatically. @@ -237,7 +416,7 @@ Paste your product requirements document directly into Squad. The Lead agent dec --- -## Human Team Members +## Human team members Not every team member needs to be an AI agent. Add humans to the roster for decisions that require a real person — design sign-off, security review, product approval. Squad pauses when work is routed to a human and reminds you if they haven't responded. @@ -255,11 +434,18 @@ See [Notifications Guide](features/notifications.md#quick-start-teams-simplest-p --- -## Ceremonies +## Multi-platform support -Ceremonies are structured team meetings. Squad ships with two default ceremonies — Design Review (triggers before multi-agent work) and Retrospective (triggers after failures). You can trigger ceremonies manually, create custom ones, or disable them. Configuration lives in `.ai-team/ceremonies.md`. +Squad works with more than GitHub. Pluggable platform adapters let you use: -→ [Full guide: Ceremonies](features/ceremonies.md#ceremonies) +- **GitHub** — Issues, PRs, Project Boards (via `gh` CLI) +- **Azure DevOps** — Work items, repos, PRs (via `az boards`/`az repos` CLI) +- **GitLab** — Issues and merge requests +- **Microsoft Planner** — Hybrid work-item tracking (via Microsoft Graph API) + +Configure cross-project ADO support in `.squad/config.json` — work items can live in a different org/project than the repo. + +→ [Full guide: Enterprise Platforms](features/enterprise-platforms.md) | [GitLab Issues](features/gitlab-issues.md) --- @@ -268,16 +454,28 @@ Ceremonies are structured team meetings. Squad ships with two default ceremonies Already have Squad installed? Update to the latest version: ```bash -npx github:bradygaster/squad upgrade +npm install -g @bradygaster/squad-cli@latest +``` + +Run `squad doctor` to validate your setup after upgrading: + +```bash +squad doctor ``` -This overwrites `squad.agent.md` and `.ai-team-templates/` with the latest versions. It **never touches `.ai-team/`** — your team's knowledge, decisions, casting state, and skills are safe. +Doctor runs 9 checks — Node.js version, `gh` CLI auth, `.squad/` directory structure, team state, and more. It reports issues with clear fix instructions. + +**Migrating from `.ai-team/` to `.squad/`:** + +```bash +squad migrate --from ai-team +``` -Smart upgrade detects your installed version, reports what changed, and runs any needed migrations (e.g., creating `.ai-team/skills/` if it didn't exist). Migrations are additive and idempotent — safe to re-run. +This renames `.ai-team/` to `.squad/` and updates all internal references. --- -## Context Budget +## Context budget Each agent runs in its own context window. Real numbers: @@ -293,7 +491,7 @@ The coordinator uses 6.6% of its window. A 12-week veteran agent uses 4.5% — b --- -## Known Limitations +## Known limitations - **Experimental** — file formats and APIs may change between versions. - **Silent success bug** — approximately 7–10% of background agent spawns complete all their file writes but return no text response. This is a platform-level issue. Squad detects it by checking the filesystem for work product and reports what it finds. Work is not lost. @@ -304,7 +502,7 @@ The coordinator uses 6.6% of its window. A 12-week veteran agent uses 4.5% — b --- -## Adding and Removing Team Members +## Adding and removing team members ### Adding @@ -320,11 +518,11 @@ Squad allocates a name from the current universe, generates a charter and histor > Remove the designer — we're past that phase ``` -Agents are never deleted. Their charter and history move to `.ai-team/agents/_alumni/`. Knowledge is preserved. If you need them back later, they remember everything. +Agents are never deleted. Their charter and history move to `.squad/agents/_alumni/`. Knowledge is preserved. If you need them back later, they remember everything. --- -## Reviewer Protocol +## Reviewer protocol Agents with review authority can reject work. On rejection, the original author is locked out and a different agent must handle the revision. This prevents the common failure mode where an agent keeps fixing its own work in circles. @@ -332,27 +530,41 @@ Agents with review authority can reject work. On rejection, the original author --- -## File Ownership +## File ownership Squad maintains a clear ownership model: | What | Owner | Safe to edit? | |------|-------|--------------| | `.github/agents/squad.agent.md` | Squad (overwritten on upgrade) | No — your changes will be lost | -| `.ai-team-templates/` | Squad (overwritten on upgrade) | No | -| `.ai-team/` | You and your team | Yes — this is your team's state | +| `.squad/` | You and your team | Yes — this is your team's state | +| `squad.config.ts` | You | Yes — your SDK-first config | | Everything else | You | Yes | --- -## Quick Reference +## Quick reference | Command | What it does | |---------|-------------| -| `npx github:bradygaster/squad` | Install Squad in the current repo | -| `npx github:bradygaster/squad upgrade` | Update Squad-owned files to latest | -| `npx github:bradygaster/squad export` | Export team to `squad-export.json` | -| `npx github:bradygaster/squad import ` | Import team from export file | -| `npx github:bradygaster/squad import --force` | Import, archiving existing agents | -| `npx github:bradygaster/squad --version` | Show installed version | -| `npx github:bradygaster/squad --help` | Show help | +| `squad init` | Initialize Squad in the current repo | +| `squad init --sdk` | Initialize with SDK-first TypeScript config | +| `squad init --global` | Initialize a personal squad (cross-project) | +| `squad build` | Generate `.squad/` from `squad.config.ts` | +| `squad build --check` | Validate generated files match disk (for CI) | +| `squad doctor` | Run 9 setup validation checks | +| `squad shell` | Enter the interactive shell | +| `squad triage` | Run a single triage pass | +| `squad triage --interval 10` | Continuous triage every 10 minutes | +| `squad watch` | Ralph watchdog mode | +| `squad export` | Export team to `squad-export.json` | +| `squad import ` | Import team from export file | +| `squad import --force` | Import, archiving existing agents | +| `squad plugin install ` | Install a plugin from the marketplace | +| `squad plugin list` | List installed plugins | +| `squad migrate --to sdk` | Convert existing squad to SDK-first config | +| `squad migrate --from ai-team` | Migrate from `.ai-team/` to `.squad/` | +| `squad subsquads` | Manage SubSquads | +| `squad status` | Show team status and global config | +| `squad --version` | Show installed version | +| `squad --help` | Show help | diff --git a/docs/src/content/docs/guide/faq.md b/docs/src/content/docs/guide/faq.md index 00279363b..c7ad1b7ad 100644 --- a/docs/src/content/docs/guide/faq.md +++ b/docs/src/content/docs/guide/faq.md @@ -205,7 +205,7 @@ Nothing breaks! `squad init` is **idempotent** — it's safe to run multiple tim **What it does:** - Checks if `.squad/` exists; if yes, does nothing -- Copies missing templates from `.ai-team-templates/` to `.squad/` +- Copies missing templates to `.squad/` - Updates `.github/workflows/` with Squad Actions (skips existing files) - Adds `.github/agents/squad.agent.md` if missing diff --git a/docs/src/content/docs/tips-and-tricks.md b/docs/src/content/docs/tips-and-tricks.md index d375d33e0..dbbdc21df 100644 --- a/docs/src/content/docs/tips-and-tricks.md +++ b/docs/src/content/docs/tips-and-tricks.md @@ -289,14 +289,14 @@ Ralph handles the backlog, you handle the critical path. ❌ "I want Lead, Frontend, Backend, Tester, DevOps, Data Engineer, Designer, and a Scribe." ``` -### Pitfall 6: Lost Work Because You Didn't Commit `.ai-team/` +### Pitfall 6: Lost work because you didn't commit `.squad/` **Problem:** You deleted the repo and lost all your team knowledge. -**Solution:** **Commit `.ai-team/` to git.** It's permanent team memory. +**Solution:** **Commit `.squad/` to git.** It's permanent team memory. ```bash -git add .ai-team/ +git add .squad/ git commit -m "Add squad team state" git push ``` @@ -358,7 +358,7 @@ Squad 1: "Team A, build the admin dashboard. You own features/admin/." Squad 2: "Team B, build the mobile app. You own features/mobile/." [Both teams work in parallel] -[Shared decisions in .ai-team/decisions.md prevent conflicts] +[Shared decisions in .squad/decisions.md prevent conflicts] ``` Requires good routing rules and clear ownership, but it works. @@ -456,7 +456,7 @@ A typical high-performing session: 3. **Parallel execution:** Let agents work (don't interrupt) 4. **Check logs:** Ask Scribe what happened while you were reading code 5. **Next round:** Based on what Scribe told you, give follow-up work or start Ralph -6. **Wrap up:** Ask Ralph for status, commit `.ai-team/`, go home +6. **Wrap up:** Ask Ralph for status, commit `.squad/`, go home **Time to productive work: usually < 2 minutes.** diff --git a/docs/src/navigation.ts b/docs/src/navigation.ts index 64dd7a034..6b5d2b05a 100644 --- a/docs/src/navigation.ts +++ b/docs/src/navigation.ts @@ -29,6 +29,8 @@ export const NAV_SECTIONS: NavSection[] = [ { title: 'Sample Prompts', slug: 'guide/sample-prompts' }, { title: 'Personal Squad', slug: 'guide/personal-squad' }, { title: 'Interactive Shell', slug: 'guide/shell' }, + { title: 'Extensibility', slug: 'guide/extensibility' }, + { title: 'Building Extensions', slug: 'guide/building-extensions' }, { title: 'Contributing', slug: 'guide/contributing' }, { title: 'Contributors', slug: 'guide/contributors' }, ],