diff --git a/.squad/agents/pao/charter.md b/.squad/agents/pao/charter.md index aa4d55841..fb387c39d 100644 --- a/.squad/agents/pao/charter.md +++ b/.squad/agents/pao/charter.md @@ -26,6 +26,8 @@ - **DOCS-TEST SYNC (hard rule):** When adding new docs pages (guides, blog posts), update the corresponding test assertions in test/docs-build.test.ts in the SAME commit. Stale test assertions that block CI are a docs team failure. - **CONTRIBUTOR RECOGNITION (hard rule):** Each release includes an update to the Contributors Guide page. No contribution goes unappreciated. - **DOC-IMPACT REVIEW (hard rule):** Review every PR for documentation impact. If a change affects user-facing behavior, ensure corresponding docs are updated or flag the gap. +- **CONTENT DISCIPLINE (hard rule):** Before writing new content, search existing docs for coverage of the same topic. Link to the canonical page instead of duplicating setup steps, config blocks, or explanations. Each concept should live in exactly one place β€” other pages reference it. When reviewing docs, flag duplication and unnecessary growth. +- **DEEP LINKING (hard rule):** When linking between docs pages, use the most specific anchor available (e.g., `guides/mcp/#authentication-errors`) rather than just the page URL. If a heading or section anchor exists for the target content, link to it. ## Boundaries diff --git a/.squad/agents/pao/history.md b/.squad/agents/pao/history.md index 6aa088090..6182cc15e 100644 --- a/.squad/agents/pao/history.md +++ b/.squad/agents/pao/history.md @@ -54,4 +54,6 @@ Added distributed-mesh.md to features/ β€” covers the three zones (local, remote Added "Skill scope" section to distributed-mesh.md to document zero-code skill boundaries. Pattern: explicitly state what the skill produces (config files, decision entries, pointers to templates) and what it does NOT produce (code, tests, custom scripts). Rationale: deterministic skills prevent agents from generating unnecessary implementations when pre-built templates exist. This documentation pattern should apply to other zero-code skills β€” helps agents understand when to copy templates vs. generate code. Position: after technical comparison sections, before "What We're NOT Building" or closing content. πŸ“Œ Team update (2026-03-14T22-01-14Z): Distributed mesh integrated with deterministic skill pattern β€” decided by Procedures, PAO, Flight, Network +### Teams MCP Documentation Audit (v0.8.26) +Audited Teams MCP integration documentation per #258. Key findings: (1) All path references used placeholder `path/to/*.js` without clarifying these require actual MCP server implementations; (2) Link to `microsoft/IF-MCP-Server-for-Microsoft-Teams` was misleading β€” that repo is actually a Court Listener demo, not a general Teams server; (3) No example code exists in Squad codebase; (4) Community member benleane83 published working reference implementation at https://gist.github.com/benleane83/f37b5bc1ed3d00e320ba48886109b82a. Fixes applied: replaced placeholder paths with `/absolute/path/to/*.js` format, removed broken Microsoft Teams MCP reference, added link to community gist, clarified users must download/create MCP servers, updated all MCP config examples in notifications.md, mcp.md, and portability.md. Pattern reinforced: external tool integrations require explicit "where to get it" guidance, not assumptions about bundled code. diff --git a/README.md b/README.md index 9ca47ce3e..ad5da73e8 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ squad init **βœ“ Validate:** Check that `.squad/team.md` was created in your project. -**Or use npx (no install):** `npx @bradygaster/squad-cli` β€” see [Migration Guide](docs/get-started/migration.md) if upgrading from an older version. +**Or use npx (no install):** `npx @bradygaster/squad-cli` β€” see [Migration Guide](https://bradygaster.github.io/squad/docs/get-started/migration/) if upgrading from an older version. ### 3. Authenticate with GitHub (for Issues, PRs, and Ralph) @@ -49,16 +49,13 @@ gh auth login ### 4. Open Copilot and go -**Recommended:** start Copilot with `--yolo`. - ``` -copilot --yolo +copilot --agent squad --yolo ``` -> **Why use `--yolo`?** Squad makes many tool calls in a typical session. Without it, Copilot will prompt you to approve each one. +> **Why `--yolo`?** Squad makes many tool calls in a typical session. Without it, Copilot will prompt you to approve each one. -**In the GitHub Copilot CLI**, type `/agent` and select **Squad**. -**In VS Code**, type `/agents` and select **Squad**. +**In VS Code**, open Copilot Chat and select the **Squad** agent. Then: @@ -245,7 +242,7 @@ export default defineSquad({ }); ``` -Run `squad build` to generate all the markdown. See the [SDK-First Mode Guide](docs/sdk-first-mode.md) for full documentation. +Run `squad build` to generate all the markdown. See the [SDK-First Mode Guide](docs/src/content/docs/sdk-first-mode.md) for full documentation. --- diff --git a/docs/src/content/docs/concepts/github-workflow.md b/docs/src/content/docs/concepts/github-workflow.md index 905f1f44b..1a91df261 100644 --- a/docs/src/content/docs/concepts/github-workflow.md +++ b/docs/src/content/docs/concepts/github-workflow.md @@ -175,18 +175,7 @@ Board sync runs on label changes, issue close, PR merge, and a 30-minute schedul Your squad pings you when they need input, hit an error, or finish work. Squad uses MCP-based notification servers β€” you bring your own delivery channel. -The flow: -1. **Skill** (`human-notification`) tells agents when to ping -2. **Agent** invokes your configured MCP server -3. **MCP server** (Teams, Discord, iMessage, webhook) delivers the message - -| Trigger | Example | -|---------|---------| -| Blocked on input | "Keaton needs your decision on the API approach" | -| Error hit | "McManus got an auth error β€” needs credentials" | -| Work complete | "Fenster finished the test suite β€” 142 tests passing" | - -Configure in `.vscode/mcp.json` or `.copilot/mcp-config.json`. See the [MCP setup section in Portability & Extensions](portability.md) for configuration details. +See the [Notifications Guide](../features/notifications.md) for [platform setup](../features/notifications.md#quick-start-teams-simplest-path) (Teams, Discord, iMessage, webhooks), [trigger configuration](../features/notifications.md#what-triggers-a-notification), and [sample MCP configs](../features/notifications.md#sample-mcp-configs). --- diff --git a/docs/src/content/docs/concepts/memory-and-knowledge.md b/docs/src/content/docs/concepts/memory-and-knowledge.md index 27643cfa2..4b985840d 100644 --- a/docs/src/content/docs/concepts/memory-and-knowledge.md +++ b/docs/src/content/docs/concepts/memory-and-knowledge.md @@ -210,6 +210,27 @@ Skills export and import with your team. Move a trained team to a new repo, and --- +## Knowledge persistence + +Not all knowledge in `.squad/` lasts forever. When files grow large, Squad compacts them to keep performance fast. Here's what persists and what gets summarized: + +| What | File | Compacted? | Where old content goes | Who reads it | +|------|------|-----------|----------------------|-------------| +| Personal history | `history.md` | Yes, at ~12 KB | `history-archive.md` (preserved, read-only) | Owning agent | +| Shared decisions | `decisions.md` | Yes, when large | `decisions-archive.md` (preserved, not loaded) | All agents | +| Skills | `skills/{name}/SKILL.md` | Never | Grows indefinitely | All agents | +| Directives | In `decisions.md` | With decisions | Archived with decisions | All agents | +| Wisdom | `identity/wisdom.md` | Never | Permanent | All agents | +| Casting registry | `casting/registry.json` | Never | Permanent | Coordinator | +| Session logs | `log/*.md` | Never edited | Append-only archive | Read-only | +| Orchestration logs | `orchestration-log/*.md` | Never edited | Append-only archive | Read-only | + +Knowledge that needs to survive compaction belongs in **skills**. Reusable patterns, code conventions, and technical techniques live here because they grow without limits. Team rules and preferences go in directives (stored in `decisions.md`) β€” they persist through compaction cycles because directives are preserved when decisions get summarized. + +> πŸ’‘ **Where to store permanent knowledge:** Put reusable patterns and techniques in `.squad/skills/`. Put team rules and preferences in directives (they persist in `decisions.md`). For org-wide knowledge that multiple teams need, use [upstream inheritance](/features/upstream-inheritance) to share a skills library. + +--- + ## Tips - **Commit `.squad/`** β€” anyone who clones the repo gets the team with all their accumulated knowledge. diff --git a/docs/src/content/docs/concepts/portability.md b/docs/src/content/docs/concepts/portability.md index 4636e1fde..457109c97 100644 --- a/docs/src/content/docs/concepts/portability.md +++ b/docs/src/content/docs/concepts/portability.md @@ -236,7 +236,7 @@ MCP (Model Context Protocol) servers extend Squad with external services. Agents "mcpServers": { "github": { "command": "node", - "args": ["/path/to/github-mcp.js"], + "args": ["/absolute/path/to/github-mcp.js"], "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN" } diff --git a/docs/src/content/docs/features/enterprise-platforms.md b/docs/src/content/docs/features/enterprise-platforms.md index ca51877ae..a842b4dfd 100644 --- a/docs/src/content/docs/features/enterprise-platforms.md +++ b/docs/src/content/docs/features/enterprise-platforms.md @@ -102,18 +102,7 @@ All fields are optional. Omitted fields use the defaults shown above. Squad uses the Azure CLI for ADO authentication β€” **no Personal Access Tokens (PATs) needed.** Run `az login` once, and Squad agents use your authenticated session for all operations. -Alternatively, if the Azure DevOps MCP server is configured in your environment, Squad will use it automatically for richer API access. Add it to `.copilot/mcp-config.json`: - -```json -{ - "mcpServers": { - "azure-devops": { - "command": "npx", - "args": ["-y", "@azure/devops-mcp-server"] - } - } -} -``` +Alternatively, if the Azure DevOps MCP server is configured in your environment, Squad will use it automatically for richer API access. See [MCP Setup Guide](./mcp.md#mcp-configuration-files) for configuration instructions. Squad prefers MCP tools when available, falling back to `az` CLI when not. diff --git a/docs/src/content/docs/features/mcp.md b/docs/src/content/docs/features/mcp.md index 4f78b4804..071111f68 100644 --- a/docs/src/content/docs/features/mcp.md +++ b/docs/src/content/docs/features/mcp.md @@ -19,13 +19,7 @@ MCP (Model Context Protocol) servers extend Squad with external services β€” Git ## What MCP Means for Squad -**MCP (Model Context Protocol) servers extend your Squad environment.** Agents use MCP tools to send notifications, query GitHub, monitor deployments, integrate with Trello, and more. This guide walks you through configuring MCP services step-by-step. - ---- - -## What MCP Means for Squad - -MCP bridges Squad agents and external services. When your agents work, they can call any MCP-exposed tool β€” send notifications, check project status, update boards, or fetch live data. You define which services are available; agents discover and use them automatically. +MCP bridges Squad agents and external services. Agents use MCP tools to send notifications, query GitHub, monitor deployments, integrate with Trello, and more. You define which services are available; agents discover and use them automatically. --- @@ -72,7 +66,7 @@ Paste this base structure: "mcpServers": { "github": { "command": "node", - "args": ["path/to/github-mcp.js"], + "args": ["/absolute/path/to/github-mcp.js"], "env": { "GITHUB_TOKEN": "your-github-token-here" } @@ -81,7 +75,7 @@ Paste this base structure: } ``` -Replace `path/to/github-mcp.js` with the actual path to your MCP server script. The `env` object passes environment variables to the server. +Replace `/absolute/path/to/github-mcp.js` with the actual path to your MCP server script. The `env` object passes environment variables to the server. ### Step 3: Add your GitHub token @@ -145,7 +139,7 @@ Click **"Edit in settings.json"** to see the raw configuration: "copilot.mcp.servers": { "github": { "command": "node", - "args": ["path/to/github-mcp.js"], + "args": ["/absolute/path/to/github-mcp.js"], "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" } @@ -153,7 +147,7 @@ Click **"Edit in settings.json"** to see the raw configuration: } ``` -The `${env:GITHUB_TOKEN}` syntax reads from your shell environment. +The `${env:GITHUB_TOKEN}` syntax reads from your shell environment. Replace `/absolute/path/to/github-mcp.js` with the actual path to your MCP server script. ### Step 4: Add environment variables @@ -182,7 +176,7 @@ Most Squad installs come with GitHub MCP pre-configured. Here's what it looks li "mcpServers": { "github": { "command": "node", - "args": ["/path/to/github-mcp.js"], + "args": ["/absolute/path/to/github-mcp.js"], "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN" } @@ -191,6 +185,8 @@ Most Squad installs come with GitHub MCP pre-configured. Here's what it looks li } ``` +Replace `/absolute/path/to/github-mcp.js` with the actual path to your GitHub MCP server script. + ### VS Code: `.vscode/settings.json` ```json @@ -198,7 +194,7 @@ Most Squad installs come with GitHub MCP pre-configured. Here's what it looks li "copilot.mcp.servers": { "github": { "command": "node", - "args": ["/path/to/github-mcp.js"], + "args": ["/absolute/path/to/github-mcp.js"], "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" } @@ -207,14 +203,14 @@ Most Squad installs come with GitHub MCP pre-configured. Here's what it looks li } ``` +Replace `/absolute/path/to/github-mcp.js` with the actual path to your GitHub MCP server script. + **What it does:** -- List issues, PRs, and branches in your repo +- List issues, PRs, and branches - Create, update, and search issues -- Fetch commit history and diff info +- Fetch commit history and diffs - Post and edit PR comments -Agents automatically discover these tools and use them during work. - --- ## Example: Trello MCP @@ -228,14 +224,23 @@ Trello MCP lets agents interact with your Trello boards β€” create cards, move t 3. Click "Tokens" and generate a new token (grant read/write permissions) 4. Copy the **Token** -### Step 2: Add to `.copilot/mcp-config.json` +### Step 2: Add to your MCP config +Add the Trello server configuration (see [MCP Configuration Files](#mcp-configuration-files) for CLI vs VS Code): + +| Variable | How to Get It | +|----------|---------------| +| `TRELLO_API_KEY` | Visit https://trello.com/app-key | +| `TRELLO_TOKEN` | Click "Tokens" on the API key page, generate with read/write permissions | +| `TRELLO_BOARD_ID` | Open any card, get ID from URL: `trello.com/c/{{CARD_ID}}/{{BOARD_ID}}/` | + +**Config template:** ```json { "mcpServers": { "trello": { "command": "node", - "args": ["/path/to/trello-mcp.js"], + "args": ["/absolute/path/to/trello-mcp.js"], "env": { "TRELLO_API_KEY": "your-api-key", "TRELLO_TOKEN": "your-token", @@ -246,6 +251,8 @@ Trello MCP lets agents interact with your Trello boards β€” create cards, move t } ``` +Replace `/absolute/path/to/trello-mcp.js` with the actual path to your Trello MCP server script. + Find your **board ID** by opening any card on Trello and looking at the URL: `trello.com/c/{{CARD_ID}}/{{BOARD_ID}}/`. ### Step 3: Test it @@ -262,20 +269,15 @@ Agents will now automatically propose Trello tasks for tracking work items. ## Example: Aspire Dashboard MCP (Deployment Monitoring) -For projects using .NET Aspire, the Aspire Dashboard MCP lets agents monitor deployments, check service health, and log errors. - -### Step 1: Start Aspire Dashboard - -Your project should have a dashboard running (usually `http://localhost:18888`). - -### Step 2: Configure MCP +For .NET Aspire projects, configure the Aspire Dashboard MCP for deployment monitoring: +**Config template:** ```json { "mcpServers": { "aspire": { "command": "node", - "args": ["/path/to/aspire-mcp.js"], + "args": ["/absolute/path/to/aspire-mcp.js"], "env": { "ASPIRE_URL": "http://localhost:18888", "ASPIRE_API_KEY": "optional-api-key" @@ -285,6 +287,8 @@ Your project should have a dashboard running (usually `http://localhost:18888`). } ``` +Replace `/absolute/path/to/aspire-mcp.js` with the actual path to your Aspire MCP server script. + ### Step 3: Use it Agents can now ask: @@ -320,9 +324,9 @@ Agents don't need special setup to discover tools. Here's the flow: 1. **Verify the command path:** ```bash - ls -la /path/to/mcp-server.js + ls -la /absolute/path/to/mcp-server.js ``` - The file must exist and be executable. + The file must exist and be executable. Replace `/absolute/path/to/mcp-server.js` with your actual MCP server path. 2. **Verify Node.js is installed:** ```bash @@ -366,9 +370,9 @@ Agents don't need special setup to discover tools. Here's the flow: 3. **Test the MCP server directly:** ```bash - node /path/to/mcp-server.js + node /absolute/path/to/mcp-server.js ``` - It should start without errors. If it crashes, there's a server-side issue. + It should start without errors. If it crashes, there's a server-side issue. Replace `/absolute/path/to/mcp-server.js` with your actual MCP server path. ### Authentication Errors @@ -414,13 +418,13 @@ Agents don't need special setup to discover tools. Here's the flow: "mcpServers": { "github": { "command": "node", - "args": ["/path/to/github-mcp.js"], + "args": ["/absolute/path/to/github-mcp.js"], "lazy": true } } } ``` - This starts the server only when its first tool is called. + This starts the server only when its first tool is called. Replace `/absolute/path/to/github-mcp.js` with your actual MCP server path. --- diff --git a/docs/src/content/docs/features/notifications.md b/docs/src/content/docs/features/notifications.md index 3f3392f4b..56ad6aa75 100644 --- a/docs/src/content/docs/features/notifications.md +++ b/docs/src/content/docs/features/notifications.md @@ -1,4 +1,4 @@ -# Squad Pings You +# Squad pings you > ⚠️ **Experimental** β€” Squad is alpha software. APIs, commands, and behavior may change between releases. @@ -38,7 +38,7 @@ This means Squad works with any notification service. Pick your favorite messagi ## Quick Start: Teams (Simplest Path) -### Option A: Teams Incoming Webhook (No Auth Setup) +### Teams Incoming Webhook Teams webhooks are the fastest setup β€” just a URL. @@ -52,14 +52,23 @@ Teams webhooks are the fastest setup β€” just a URL. - Give it a name (e.g., "Squad Notifications") - Copy the webhook URL -3. **Configure Squad:** - - Create or edit `.vscode/mcp.json` in your workspace: +3. **Get the MCP server:** + + You need to create or download a Teams webhook MCP server. You have options: + + - **Community reference implementation:** [benleane83's teams-webhook-mcp.js](https://gist.github.com/benleane83/f37b5bc1ed3d00e320ba48886109b82a) β€” a working, production-ready implementation + - **Build your own:** Use the reference as a starting point and customize for your needs + - **Search MCP marketplace:** Look for Teams-compatible MCP servers at https://mcpmarket.com + +4. **Configure Squad:** + + Create or edit `.vscode/mcp.json` in your workspace: ```json { "mcpServers": { "notifications": { "command": "node", - "args": ["path/to/teams-webhook-mcp.js"], + "args": ["/absolute/path/to/teams-webhook-mcp.js"], "env": { "TEAMS_WEBHOOK_URL": "https://outlook.webhook.office.com/webhookb2/..." } @@ -67,48 +76,13 @@ Teams webhooks are the fastest setup β€” just a URL. } } ``` + + Replace `/absolute/path/to/teams-webhook-mcp.js` with the actual path to your downloaded or created MCP server script. -4. **Use it:** +5. **Use it:** - Start a Squad session with `copilot squad` - When an agent needs input, your Teams channel lights up -### Option B: Microsoft's Official Teams MCP Server (Full Auth) - -For integration with your Azure tenant and full Teams API access: - -1. **Register an Azure AD app:** - - Go to https://portal.azure.com β†’ "Azure Active Directory" β†’ "App registrations" - - New registration: name it "Squad Notifications" - - Copy the **Application (client) ID** - -2. **Set up credentials:** - - "Certificates & secrets" β†’ "New client secret" - - Copy the secret value - -3. **Grant permissions:** - - "API permissions" β†’ "Add a permission" β†’ "Microsoft Graph" - - Add `Chat.Send`, `ChannelMessage.Send` - - Grant admin consent - -4. **Configure Squad:** - - Install Microsoft's Teams MCP server: https://github.com/microsoft/IF-MCP-Server-for-Microsoft-Teams - - Configure in `.vscode/mcp.json`: - ```json - { - "mcpServers": { - "teams": { - "command": "node", - "args": ["path/to/teams-mcp.js"], - "env": { - "AZURE_CLIENT_ID": "your-client-id", - "AZURE_CLIENT_SECRET": "your-secret", - "AZURE_TENANT_ID": "your-tenant-id" - } - } - } - } - ``` - --- ## Quick Start: iMessage (Mac Only) @@ -121,7 +95,7 @@ iMessage is built into macOS. If you're on a Mac, this is the fastest personal s - System allows Copilot to control Messages (grant permission when prompted) 2. **Install the iMessage MCP server:** - - Get it from https://mcpmarket.com/server/imessage + - Search https://mcpmarket.com for "imessage" or compatible MCP servers - Follow its setup steps 3. **Configure Squad:** @@ -131,7 +105,7 @@ iMessage is built into macOS. If you're on a Mac, this is the fastest personal s "mcpServers": { "imessage": { "command": "node", - "args": ["path/to/imessage-mcp.js"], + "args": ["/absolute/path/to/imessage-mcp.js"], "env": { "IMESSAGE_TARGET": "your-phone-number-or-email" } @@ -139,6 +113,8 @@ iMessage is built into macOS. If you're on a Mac, this is the fastest personal s } } ``` + + Replace `/absolute/path/to/imessage-mcp.js` with the actual path to your downloaded MCP server script. 4. **Test:** - Start a Squad session @@ -212,7 +188,7 @@ For any HTTP endpoint (custom service, Zapier, IFTTT, etc.): "mcpServers": { "notifications": { "command": "node", - "args": ["path/to/webhook-mcp.js"], + "args": ["/absolute/path/to/webhook-mcp.js"], "env": { "WEBHOOK_URL": "https://your-service.com/notify" } @@ -220,6 +196,8 @@ For any HTTP endpoint (custom service, Zapier, IFTTT, etc.): } } ``` + + Replace `/absolute/path/to/webhook-mcp.js` with the actual path to your MCP server script. 3. **Your endpoint receives POST:** ```json @@ -402,7 +380,7 @@ Below are complete, copy-pasteable `.copilot/mcp-config.json` examples for each "mcpServers": { "notifications": { "command": "node", - "args": ["path/to/teams-webhook-mcp.js"], + "args": ["/absolute/path/to/teams-webhook-mcp.js"], "env": { "TEAMS_WEBHOOK_URL": "https://outlook.webhook.office.com/webhookb2/YOUR_WEBHOOK_URL_HERE" } @@ -411,7 +389,10 @@ Below are complete, copy-pasteable `.copilot/mcp-config.json` examples for each } ``` -**Setup:** Get your webhook URL from Teams channel settings (right-click channel β†’ Manage β†’ Connectors β†’ Incoming Webhook). +**Setup:** +1. Get your webhook URL from Teams channel settings (right-click channel β†’ Manage β†’ Connectors β†’ Incoming Webhook) +2. Download a Teams webhook MCP server (see [community reference implementation](https://gist.github.com/benleane83/f37b5bc1ed3d00e320ba48886109b82a)) +3. Replace `/absolute/path/to/teams-webhook-mcp.js` with the actual path to your MCP server script --- @@ -422,7 +403,7 @@ Below are complete, copy-pasteable `.copilot/mcp-config.json` examples for each "mcpServers": { "notifications": { "command": "node", - "args": ["path/to/imessage-mcp.js"], + "args": ["/absolute/path/to/imessage-mcp.js"], "env": { "IMESSAGE_TARGET": "+1234567890" } @@ -431,7 +412,10 @@ Below are complete, copy-pasteable `.copilot/mcp-config.json` examples for each } ``` -Replace `+1234567890` with your phone number or email address registered in iCloud. +**Setup:** +1. Download an iMessage MCP server from https://mcpmarket.com +2. Replace `/absolute/path/to/imessage-mcp.js` with the actual path to your MCP server script +3. Replace `+1234567890` with your phone number or email address registered in iCloud --- @@ -442,7 +426,7 @@ Replace `+1234567890` with your phone number or email address registered in iClo "mcpServers": { "notifications": { "command": "node", - "args": ["path/to/discord-webhook-mcp.js"], + "args": ["/absolute/path/to/discord-webhook-mcp.js"], "env": { "DISCORD_WEBHOOK_URL": "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN" } @@ -451,7 +435,10 @@ Replace `+1234567890` with your phone number or email address registered in iClo } ``` -**Setup:** In Discord, right-click channel β†’ Edit Channel β†’ Integrations β†’ Webhooks β†’ New Webhook β†’ copy the URL. +**Setup:** +1. In Discord, right-click channel β†’ Edit Channel β†’ Integrations β†’ Webhooks β†’ New Webhook β†’ copy the URL +2. Download or create a Discord webhook MCP server (see mcp-notifications package or build your own) +3. Replace `/absolute/path/to/discord-webhook-mcp.js` with the actual path to your MCP server script --- @@ -462,7 +449,7 @@ Replace `+1234567890` with your phone number or email address registered in iClo "mcpServers": { "notifications": { "command": "node", - "args": ["path/to/webhook-mcp.js"], + "args": ["/absolute/path/to/webhook-mcp.js"], "env": { "WEBHOOK_URL": "https://your-service.com/notify", "WEBHOOK_AUTH_HEADER": "Authorization: Bearer YOUR_API_KEY", @@ -473,7 +460,10 @@ Replace `+1234567890` with your phone number or email address registered in iClo } ``` -Your endpoint receives POST requests with agent name, message, and context. +**Setup:** +1. Create or download a generic webhook MCP server +2. Replace `/absolute/path/to/webhook-mcp.js` with the actual path to your MCP server script +3. Your endpoint receives POST requests with agent name, message, and context --- diff --git a/docs/src/content/docs/features/upstream-inheritance.md b/docs/src/content/docs/features/upstream-inheritance.md index 9e769da48..d6288a92e 100644 --- a/docs/src/content/docs/features/upstream-inheritance.md +++ b/docs/src/content/docs/features/upstream-inheritance.md @@ -2,126 +2,87 @@ > ⚠️ **Experimental** β€” Squad is alpha software. APIs, commands, and behavior may change between releases. +Upstream inheritance lets you declare external Squad sources (from repositories, local directories, or exports) and automatically inherit their context at session start. Share practices across teams, organizations, and projects without duplicating configuration. -Upstream inheritance allows you to declare external Squad sourcesβ€”from other repositories, local directories, or exportsβ€”and automatically inherit their context (skills, decisions, wisdom, casting policy, routing) at session start. This enables knowledge sharing across teams, organizations, and projects without duplicating Squad configuration. +## How it works -## Why Upstream Inheritance Matters +At session start, the coordinator reads all declared upstreams from `upstream.json` and makes their context available to every agent: -When you have multiple teams using Squad in an organization, you need a way to share common practices, agent definitions, and decision-making frameworks. Upstream inheritance solves this without creating dependency trees: - -- **Org-level guidance** flows down to team repos and individual projects -- **Platform team standards** propagate to all consuming teams -- **Shared methodologies** scale across client projects or service offerings -- **Domain models** stay consistent across multiple services - -Instead of copying configuration, you point to itβ€”and at session start, the coordinator reads all declared upstreams and makes their context available to every spawned agent. - -## Core Concepts +- **Skills** β€” `.squad/skills/*/SKILL.md` +- **Decisions** β€” `.squad/decisions.md` +- **Wisdom** β€” `.squad/identity/wisdom.md` +- **Casting policy** β€” `.squad/casting/policy.json` +- **Routing** β€” `.squad/routing.md` -### Three Source Types +**Resolution order:** Later entries override earlier ones. Layer upstreams from org β†’ team β†’ repo, with each level adding or overriding as needed. -Upstreams can come from three places: +**Source types:** -| Type | Example | Use Case | +| Type | Example | Use case | |------|---------|----------| -| **local** | `../org-practices/.squad/` | Sibling repo on disk, shared drive, monorepo package | -| **git** | `https://github.com/acme/platform-squad.git` | Public org repository or private team repo (with proper credentials) | +| **local** | `../org-practices/.squad/` | Sibling repo, shared drive, monorepo package | +| **git** | `https://github.com/acme/platform-squad.git` | Public/private team repo (with credentials) | | **export** | `./exports/squad-export.json` | Snapshot for offline use or version pinning | -### Hierarchy and Resolution +## Quick start -Squad follows a **closest-wins** principle: +**Local upstream:** +```bash +squad upstream add ../org-practices/.squad +squad upstream list +# org-practices β†’ local: /path/to/org-practices/.squad (never synced) ``` -Org-level upstream - ↓ -Team-level upstream - ↓ -Repository config (local upstream.json) - ↓ -My agent instance -``` - -The resolver reads upstreams in the order they appear in `upstream.json`, and **later entries override earlier ones** for the same content type. This means you can layer upstreams from org β†’ team β†’ repo, with each level adding or overriding as needed. - -### What Gets Inherited - -When you add an upstream, the coordinator reads all of these from its `.squad/` directory: - -- **Skills** β€” all `.squad/skills/*/SKILL.md` files -- **Decisions** β€” `.squad/decisions.md` -- **Wisdom** β€” `.squad/identity/wisdom.md` -- **Casting Policy** β€” `.squad/casting/policy.json` -- **Routing** β€” `.squad/routing.md` - -If a resource doesn't exist in an upstream, it's skipped (no error). This allows upstreams to provide partial context. -## Getting Started - -### Quick Start: Local Upstream - -If you have a sibling repository with Squad configuration: +**Git upstream:** ```bash -# Add a local upstream from a nearby directory -squad upstream add ../org-practices/.squad - -# The coordinator infers the name: "org-practices" +squad upstream add https://github.com/acme/platform-squad.git --name platform --ref main +squad upstream sync platform ``` -Check it: +**Export snapshot:** ```bash -squad upstream list -# Output: -# org-practices β†’ local: /path/to/org-practices/.squad (never synced) +squad export-config --output ./exports/snapshot.json +squad upstream add ./exports/snapshot.json --name snapshot ``` -The coordinator reads from this path **live** at session startβ€”no sync needed. +## Troubleshooting -### Quick Start: Git Upstream +### Git clone or sync fails -For a remote repository: +Ensure the URL is correct and you have access. For private repos, use SSH (`git@github.com:owner/repo.git`) with your SSH key in ssh-agent, or use a GitHub PAT with `https://[PAT]@github.com/owner/repo.git`. -```bash -# Add from a public GitHub repo -squad upstream add https://github.com/acme/platform-squad.git --name platform +### Local upstream not found -# Or specify a branch -squad upstream add https://github.com/acme/platform-squad.git --name platform --ref develop -``` +Verify the path exists: `ls ../shared/.squad`. Use absolute paths if relative paths fail. -On first add, Squad clones the repo to `.squad/_upstream_repos/platform`. Keep this directory in `.gitignore`: +### Agents don't see inherited context ```bash -# Already done by squad upstream add -cat .gitignore -# .squad/_upstream_repos/ -``` +# Verify upstreams are configured +squad upstream list -Update it later: +# Sync and validate sources +squad upstream sync -```bash -squad upstream sync platform +# Restart your session (resolution happens at session start) ``` -Or sync all: +For git upstreams, check `.squad/_upstream_repos/{name}` exists. + +### Cached clone out of date ```bash -squad upstream sync +squad upstream sync ``` -### Quick Start: Export Snapshot +Then start a new session. -For offline or pinned versions: +### Conflicting upstreams -```bash -# Export an existing Squad config -squad export-config --output ./exports/snapshot.json - -# Add it as an upstream -squad upstream add ./exports/snapshot.json --name snapshot -``` +Later entries in `upstream.json` override earlier ones. Check order with `squad upstream list`. Reorder with `remove` + `add` if needed. ## CLI Reference @@ -364,358 +325,82 @@ Build a user-facing display for session start greeting. **Usage:** Shown in the session greeting to confirm what upstreams are available. -## End-to-End Scenarios - -### Scenario 1: Platform Team at Scale - -**Setting:** Your organization has a platform team that defines shared agent definitions, decisions, and casting policy for all product teams. - -**Structure:** -``` -acme/ - platform-squad (platform team repo) - .squad/ - decisions.md (org-level decisions) - casting/policy.json (standard casting) - skills/ - platform-engineer/SKILL.md - backend-engineer/SKILL.md - product-a (product team repo) - .squad/ - upstream.json - [other files] - product-b (product team repo) - .squad/ - upstream.json - [other files] -``` - -**Setup in product-a:** - -```bash -cd product-a - -# Add platform team's Squad as upstream -squad upstream add https://github.com/acme/platform-squad.git \ - --name platform \ - --ref main - -# Optionally add product-specific decisions -# (platform decisions are already inherited) -``` - -**What happens at session start:** -1. Coordinator reads `.squad/upstream.json` in product-a -2. Resolves `platform` β†’ clones/pulls from GitHub -3. Loads platform's decisions, casting policy, and skills -4. When an agent spawns, it has access to platform's casting rules and decision framework -5. Product team can override by adding their own skills or decisions - -**Benefit:** The platform team updates their practices in one place; all product teams see the changes at their next session start (after `squad upstream sync`). - -### Scenario 2: Open-Source Framework with Community Plugins - -**Setting:** You maintain an open-source framework. Community members contribute agent skills and methodologies. You want them to inherit your framework's core practices without forking. - -**Structure:** -``` -acme-framework (public repo) - .squad/ - decisions.md (framework principles) - skills/ - framework-engineer/SKILL.md - wisdom.md (philosophy) - routing.md (traffic rules) - -community-plugin-a (contributor repo) - .squad/ - upstream.json (points to acme-framework) - skills/ - plugin-specialization/SKILL.md - [other files] - -community-plugin-b (contributor repo) - .squad/ - upstream.json (points to acme-framework) - skills/ - plugin-other/SKILL.md - [other files] -``` - -**Setup in community-plugin-a:** - -```bash -squad upstream add https://github.com/acme/acme-framework.git \ - --name framework -``` - -**What happens:** -1. Plugin developers inherit framework's decisions, wisdom, and core skills -2. Their own skills layer on top -3. When the framework publishes new principles, plugins see them at next sync -4. Plugins can add or override routing without touching the framework - -**Benefit:** Framework governance scales across a community; contributors stay aligned without central control. +## Use cases -### Scenario 3: Consultancy Methodology Across Client Projects +### Shared practices across teams -**Setting:** You're a consultancy. All client projects should follow your engagement methodology (decisions, casting, methodologies). Each project has unique domain skills. +**Problem:** Multiple teams need consistent agent definitions, decisions, and casting policy without duplicating configuration. -**Structure:** -``` -consultancy-methodology (internal repo) - .squad/ - decisions.md (client engagement decision framework) - casting/policy.json (role definitions) - wisdom.md (consulting philosophy) - routing.md (internal routing rules) - -client-a-project (client repo) - .squad/ - upstream.json (points to methodology) - skills/ - client-a-domain-expert/SKILL.md - [other files] - -client-b-project (client repo) - .squad/ - upstream.json (points to methodology) - skills/ - client-b-domain-expert/SKILL.md - [other files] -``` - -**Setup in client-a-project:** +**Solution:** Create a central Squad repo (platform-squad) with shared context. Product teams add it as an upstream. ```bash -squad upstream add https://github.internal/consultancy/methodology.git \ - --name consultancy \ - --ref main +# In platform-squad repo +.squad/ + decisions.md + casting/policy.json + skills/ + platform-engineer/SKILL.md + backend-engineer/SKILL.md + +# In product-a repo +squad upstream add https://github.com/acme/platform-squad.git --name platform --ref main ``` -(Or use SSH/PAT for private repos.) - -**What happens:** -1. Every agent spawned in the client project inherits consultancy's methodology -2. Client-specific skills (domain expertise) are layered on top -3. Consultancy updates methodology; all active projects pull at next sync -4. Each client project remains independent (no shared git history) - -**Benefit:** Quality control at scale; consistent methodology; easy knowledge transfer. +**Outcome:** Platform team updates practices once. All product teams inherit changes at next `squad upstream sync`. Product teams can layer their own skills or override decisions as needed. -### Scenario 4: Multi-Team Shared Domain Model +**Also works for:** +- Open-source frameworks with community plugins +- Consultancy methodology across client projects -**Setting:** Three teams work on different services that share a domain model (e.g., user, order, payment). You want a single source of truth for how to work with that model. - -**Structure:** -``` -shared-domain (shared repo, not a full product) - .squad/ - skills/ - domain-modeler/SKILL.md (DDD practices) - database-engineer/SKILL.md (schema design) - decisions.md (data governance) - routing.md (domain event routing) - -user-service (team repo) - .squad/ - upstream.json (points to shared-domain) - [business logic] +--- -order-service (team repo) - .squad/ - upstream.json (points to shared-domain) - [business logic] +### Domain consistency across services -payment-service (team repo) - .squad/ - upstream.json (points to shared-domain) - [business logic] -``` +**Problem:** Multiple microservices share a domain model (user, order, payment). You need a single source of truth for how agents work with that model. -**Setup in user-service:** +**Solution:** Create a shared-domain repo with domain-specific skills and decisions. Each service adds it as an upstream. ```bash +# In shared-domain repo +.squad/ + skills/ + domain-modeler/SKILL.md + database-engineer/SKILL.md + decisions.md + routing.md + +# In user-service, order-service, payment-service repos squad upstream add https://github.com/acme/shared-domain.git --name domain ``` -**What happens:** -1. All agents spawned across the three services have access to shared domain skills -2. If domain conventions change, the shared-domain repo is updated once -3. Each team pulls the change independently -4. Services stay decoupled (no cross-repo deployments) - -**Benefit:** DDD governance; single source of truth; isolation with consistency. - -### Scenario 5: Post-Acquisition Engineering Convergence - -**Setting:** After acquiring another company, you need to converge engineering practices across two organizations. They have different frameworks, but you want a unified way forward without forcing a rewrite. +**Outcome:** All agents across services understand the domain model. Domain conventions change once; each service pulls independently. Services stay decoupled with consistency. -**Structure:** -``` -acme-unified-practices (new shared repo) - .squad/ - decisions.md (merged decision framework) - casting/policy.json (unified roles) - skills/ - acme-engineer/SKILL.md (original practices) - acquired-engineer/SKILL.md (acquired practices) - routing.md (unified routing) +--- -acme-product (original product repo) - .squad/ - upstream.json (points to unified-practices) - [business logic] +### Multi-team scaling patterns -acquired-product (acquired product repo) - .squad/ - upstream.json (points to unified-practices) - [business logic] -``` +**Problem:** Post-acquisition, migration, or enterprise modernization requires coordinating practices across teams with different histories. -**Setup in acquired-product:** +**Solution:** Create a unified practices or playbook repo. All teams add it as an upstream. ```bash +# In acme-unified-practices repo (post-acquisition example) +.squad/ + decisions.md # Merged decision framework + casting/policy.json # Unified roles + skills/ + acme-engineer/SKILL.md + acquired-engineer/SKILL.md + +# In both original and acquired product repos squad upstream add https://github.com/acme/acme-unified-practices.git --name unified ``` -**What happens:** -1. Both products inherit the merged practices -2. Agents understand both organizations' traditions (skills for both) -3. Decisions reflect the merged framework -4. Teams can work independently while being culturally aligned - -**Benefit:** Smooth integration without painful rewrites; shared culture; gradual convergence. - -### Scenario 6: Enterprise Application Modernization - -**Setting:** You're migrating a monolith to microservices. You want to maintain architectural consistency across new services while honoring legacy patterns. - -**Structure:** -``` -modernization-playbook (central guidance repo) - .squad/ - decisions.md (architecture decisions, API patterns) - skills/ - microservice-engineer/SKILL.md (cloud-native practices) - legacy-translator/SKILL.md (backward compatibility) - wisdom.md (migration philosophy) - routing.md (inter-service routing) - -legacy-monolith (old codebase) - .squad/ - upstream.json (points to playbook) - [monolith code] - -billing-service (new microservice) - .squad/ - upstream.json (points to playbook) - [business logic] - -inventory-service (new microservice) - .squad/ - upstream.json (points to playbook) - [business logic] - -shipping-service (new microservice) - .squad/ - upstream.json (points to playbook) - [business logic] -``` - -**Setup in billing-service:** - -```bash -squad upstream add https://github.com/acme/modernization-playbook.git \ - --name playbook -``` - -**What happens:** -1. All new services inherit architectural guidance -2. The legacy monolith inherits it too (preparing for extraction) -3. Playbook defines how services communicate, handle transactions, manage state -4. When a pattern is learned, it goes into the playbook once; all services benefit - -**Benefit:** Architectural coherence; faster service extraction; knowledge base grows with the migration. - -## Troubleshooting - -### Git Clone or Sync Fails - -**Problem:** `git clone` times out or fails with authentication errors. - -**Solutions:** -- Ensure the URL is correct: `https://github.com/owner/repo.git` -- For private repos, use SSH (`git@github.com:owner/repo.git`) and ensure your SSH key is in ssh-agent -- Or use a GitHub PAT with `https://[PAT]@github.com/owner/repo.git` (less secure; prefer SSH) -- Check network: `git clone --depth 1 --branch main ` from the command line first -- If `squad upstream sync` fails, cached clone is stale; run again later - -### Local Upstream Not Found - -**Problem:** `squad upstream add ../shared/.squad` fails with "Cannot determine source type". - -**Solutions:** -- Ensure the path exists: `ls -la ../shared/.squad` -- Ensure it contains a `.squad/` directory (not a `.squad` file) -- Use absolute path if relative paths are ambiguous: `squad upstream add /full/path/to/shared/.squad` -- Verify the other repo is actually a Squad repo (has `.squad/` directory) - -### Export File Invalid - -**Problem:** `squad upstream add ./export.json` fails or doesn't load skills. - -**Solutions:** -- Verify the file is valid JSON: `jq . ./export.json` -- Ensure it was created by `squad export-config` (has the right schema) -- Check that skills array is present: `jq .skills ./export.json` -- If manually created, the structure should be: - ```json - { - "version": "1.0", - "skills": ["", "", ...], - "casting": { "policy": { ... } } - } - ``` - -### Agents Don't See Inherited Context - -**Problem:** Spawned agents don't have access to upstream skills/decisions. +**Outcome:** Teams work independently while culturally aligned. Agents understand both traditions. Gradual convergence without painful rewrites. -**Solutions:** -- Verify upstreams are configured: `squad upstream list` -- Verify sources are reachable: `squad upstream sync` (should not warn) -- Check the session display when you start the session (should show `πŸ“‘ Inherited context:`) -- For git upstreams, ensure they've been cloned: check `.squad/_upstream_repos/{name}` -- For local upstreams, ensure the path still exists -- Restart your session (upstream resolution happens at session start) - -### Cached Clone Gets Out of Date - -**Problem:** You know the upstream repo changed, but agents still see old content. - -**Solution:** -```bash -squad upstream sync -``` - -For all upstreams: -```bash -squad upstream sync -``` - -This updates git clones and validates local/export paths. Then start a new session. - -### Order Matters - -**Problem:** Upstream A and Upstream B define conflicting decisions or skills. - -**Note:** Later entries in `upstream.json` override earlier ones. The resolver reads in order and the last definition wins. - -**Solution:** -Order matters. Check `squad upstream list` to see the order, and use `remove` + `add` to reorder if needed. - ---- +**Also works for:** +- Monolith-to-microservices modernization (playbook defines architecture patterns) +- Multi-geo teams converging on shared standards ## Next Steps diff --git a/docs/src/content/docs/get-started/choose-your-interface.md b/docs/src/content/docs/get-started/choose-your-interface.md new file mode 100644 index 000000000..006c49b5d --- /dev/null +++ b/docs/src/content/docs/get-started/choose-your-interface.md @@ -0,0 +1,174 @@ +# Choose your interface + +> ⚠️ **Experimental** β€” Squad is alpha software. APIs, commands, and behavior may change between releases. + + +Squad works across multiple interfaces. Pick the one that fits your workflow. + +--- + +## Try this: + +```bash +# Day-to-day work with your squad +copilot --agent squad + +# Setup and diagnostics +squad init +squad doctor +``` + +--- + +## What are the ways to use Squad? + +Squad runs in multiple modes and across multiple platforms: + +### GitHub Copilot CLI (`copilot` command) + +The conversational terminal interface. Powered by the GitHub Copilot CLI, this is the recommended way to work with Squad day-to-day. + +```bash +copilot --agent squad +``` + +Reads `.squad/` and uses `squad.agent.md` to coordinate your team. Full feature set β€” sub-agent spawning, per-spawn model selection, background execution, SQL tools, parallel fan-out. + +### VS Code (GitHub Copilot in the editor) + +Squad works identically in VS Code through GitHub Copilot. Same `.squad/` directory, same agents, same decisions. Full file access, parallel execution, MCP tool inheritance. See [Squad in VS Code](../features/vscode.md) for details. + +### Squad CLI (`squad` command) + +The Squad CLI provides setup, diagnostics, and automation commands. Not conversational β€” use this for installation, validation, and operational tasks. + +```bash +# Setup +squad init + +# Validation +squad doctor + +# Monitoring +squad watch + +# Observability +squad aspire +``` + +See [CLI Reference](../reference/cli.md) for all commands. + +### Interactive shell (`squad start` / `squad shell`) + +REPL mode for conversational interaction directly via the Squad CLI. Enter `squad` with no arguments to start a persistent shell session. See [Interactive Shell Guide](../guide/shell.md). + +This works, but **GitHub Copilot CLI is recommended** β€” richer agent experience, better tools, full MCP integration. + +### SDK (`@bradygaster/squad-sdk`) + +Programmatic access for building tools on top of Squad. Typed APIs, routing config, agent lifecycle hooks. + +```bash +npm install @bradygaster/squad-sdk +``` + +```typescript +import { resolveSquad, loadConfig, SquadCoordinator } from '@bradygaster/squad-sdk'; +``` + +See [SDK Reference](../reference/sdk.md) for the complete API. + +### Copilot Coding Agent (`@copilot`) + +Autonomous GitHub bot that picks up labeled issues and opens draft PRs. Works across your entire organization without human intervention. Issue gets labeled β†’ agent picks it up β†’ PR gets opened β†’ human reviews. + +See [Copilot Coding Agent](../features/copilot-coding-agent.md) for setup. + +--- + +## Which should I use? + +| You want to... | Use | Why | +|----------------|-----|-----| +| **Work with your squad day-to-day** | **GitHub Copilot CLI** or **VS Code** | Conversational interface, full agent spawning, parallel execution. Most natural way to collaborate with your team. | +| **Set up Squad in a new repo** | **Squad CLI** (`squad init`) | One command initializes `.squad/` directory and all configuration. | +| **Check if Squad is working** | **Squad CLI** (`squad doctor`) | Validates directory structure, agents, configuration integrity. | +| **Monitor work 24/7** | **Squad CLI** (`squad watch`) | Persistent polling for new issues, auto-triage, agent assignment. | +| **View OpenTelemetry traces** | **Squad CLI** (`squad aspire`) | Launches Aspire dashboard for observability. | +| **Process issues autonomously** | **Copilot Coding Agent** | GitHub Actions workflow watches for labeled issues and dispatches `@copilot`. | +| **Build tools on top of Squad** | **SDK** | Typed APIs, configuration loading, agent lifecycle hooks. | + +--- + +## Feature availability matrix + +Not every feature works everywhere. Here's what's available where: + +| Feature | GitHub Copilot CLI | VS Code | Squad CLI | SDK | +|---------|:------------------:|:-------:|:---------:|:---:| +| Agent spawning | βœ… | βœ… | βœ… (via shell) | βœ… | +| Ralph / work monitoring | βœ… | βœ… | βœ… (`squad watch`) | βœ… | +| Per-spawn model selection | βœ… | ⚠️ (session model only) | βœ… | βœ… | +| Background execution | βœ… | ⚠️ (parallel sync) | βœ… | βœ… | +| SQL tool | βœ… | ❌ | βœ… | βœ… | +| Aspire dashboard | ❌ | ❌ | βœ… | ❌ | +| `squad doctor` diagnostics | ❌ | ❌ | βœ… | βœ… | +| Issue assignment to `@copilot` | ❌ | ❌ | βœ… (setup) | ❌ | + +**Legend:** +- βœ… Fully supported +- ⚠️ Limited or constrained +- ❌ Not available + +For a detailed breakdown of VS Code constraints and CLI parity, see [Client Compatibility Matrix](../scenarios/client-compatibility.md). + +--- + +## Common workflows + +### "I use GitHub Copilot CLI for everything" + +```bash +# Terminal 1: Work with Squad +copilot --agent squad + +# Let Squad call `squad` commands when needed (doctor, watch, aspire) +``` + +This is the recommended workflow. The CLI automatically invokes Squad CLI commands when needed. + +### "I run squad watch in one terminal and use GitHub Copilot CLI in another" + +```bash +# Terminal 1: Monitoring (persistent) +squad watch --interval 10 + +# Terminal 2: Work with Squad +copilot --agent squad +``` + +Keep Ralph monitoring issues in the background while you work conversationally. + +### "I use VS Code with Copilot for coding and Squad CLI for setup" + +```bash +# One-time setup +squad init +squad doctor + +# Open VS Code, select Squad from agent picker +# Same .squad/ directory, same team +``` + +Initialize with CLI, work in VS Code. + +--- + +## See also + +- [Installation](installation.md) β€” Install Squad CLI, SDK, or use in VS Code +- [First Session](first-session.md) β€” Get started with your first Squad conversation +- [Client Compatibility Matrix](../scenarios/client-compatibility.md) β€” Full feature comparison across platforms +- [CLI Reference](../reference/cli.md) β€” All Squad CLI commands +- [Squad in VS Code](../features/vscode.md) β€” VS Code-specific guidance +- [SDK Reference](../reference/sdk.md) β€” Programmatic API diff --git a/docs/src/content/docs/get-started/installation.md b/docs/src/content/docs/get-started/installation.md index 65d916532..8747014d3 100644 --- a/docs/src/content/docs/get-started/installation.md +++ b/docs/src/content/docs/get-started/installation.md @@ -100,6 +100,12 @@ The SDK gives you typed configuration, routing, model selection, and the full ag --- +## Not sure which interface to use? + +See [Choose your interface](choose-your-interface.md) for a complete breakdown of GitHub Copilot CLI, VS Code, Squad CLI, SDK, and the Copilot Coding Agent. + +--- + ### Personal squad (cross-project) Want the same agents across all your projects? diff --git a/docs/src/content/docs/get-started/migration.md b/docs/src/content/docs/get-started/migration.md index d09459217..d4df114e0 100644 --- a/docs/src/content/docs/get-started/migration.md +++ b/docs/src/content/docs/get-started/migration.md @@ -27,7 +27,7 @@ | `npx github:bradygaster/squad` | `npx @bradygaster/squad-cli` | | `@bradygaster/create-squad` | `@bradygaster/squad-cli` | | `.ai-team/` directory | `.squad/` directory | -| v0.5.4 (beta) | v0.8.18 | +| v0.5.4 (beta) | v0.8.x (latest) | --- @@ -37,7 +37,7 @@ Never used Squad before? Start here. ### Prerequisites -- Node.js 18 or later +- Node.js 20 or later - npm 9 or later - A GitHub account with [GitHub Copilot](https://github.com/features/copilot) enabled - `gh` CLI authenticated (`gh auth status` should show you logged in) @@ -99,10 +99,21 @@ This is the biggest jump. The codebase was rewritten in TypeScript, the `.squad/ npm uninstall -g @bradygaster/create-squad ``` -3. **Install v0.8.18:** +3. **Install the latest version:** + **Global (recommended):** ```bash - npm install -g @bradygaster/squad-cli@0.8.18 + npm install -g @bradygaster/squad-cli@latest + ``` + + **Local (project dependency):** + ```bash + npm install --save-dev @bradygaster/squad-cli@latest + ``` + + **npx (no install):** + ```bash + npx @bradygaster/squad-cli@latest ``` 4. **Remove the old `.squad/` directory:** @@ -156,10 +167,19 @@ This is the biggest jump. The codebase was rewritten in TypeScript, the `.squad/ If you're already on any v0.8.x release, this is a simple update. +**Global:** ```bash npm install -g @bradygaster/squad-cli@latest ``` +**Local:** +```bash +npm install --save-dev @bradygaster/squad-cli@latest +``` + +**npx:** +If you use `npx`, no update needed β€” it always pulls the latest version. + Verify the version: ```bash @@ -295,10 +315,10 @@ If you run Squad in GitHub Actions or another CI/CD system, update your workflow ```yaml - uses: actions/setup-node@v4 with: - node-version: '18' + node-version: '20' - name: Install Squad - run: npm install -g @bradygaster/squad-cli@0.8.18 + run: npm install -g @bradygaster/squad-cli@latest - name: Run Squad run: squad doctor && squad status @@ -309,9 +329,9 @@ If you run Squad in GitHub Actions or another CI/CD system, update your workflow ### Key CI/CD Notes - Set `GITHUB_TOKEN` as an environment variable. Squad requires it for GitHub Copilot operations. -- Pin to a specific version (`@0.8.18`) in CI to avoid surprise upgrades. -- If you use `npx`, use `npx @bradygaster/squad-cli@0.8.18` with a pinned version. -- Node.js 18+ is required. Update your workflow's `setup-node` action if needed. +- Pin to a specific version (e.g., `@0.8.22`) in CI to avoid surprise upgrades. +- If you use `npx`, use `npx @bradygaster/squad-cli@0.8.22` with a pinned version. +- Node.js 20+ is required. Update your workflow's `setup-node` action if needed. --- @@ -342,7 +362,7 @@ import { Squad } from '@bradygaster/squad-sdk'; ### API Notes - The SDK is now fully typed (TypeScript strict mode). -- Some methods were renamed or reorganized. Check the [SDK documentation](sdk/) for the current API surface. +- Some methods were renamed or reorganized. Check the [SDK documentation](../reference/sdk.md) for the current API surface. - If you were relying on internal/undocumented APIs, those have changed. Stick to the documented public API. --- @@ -428,13 +448,13 @@ Clear the npx cache and retry: ```bash npx clear-npx-cache -npx @bradygaster/squad-cli@0.8.18 +npx @bradygaster/squad-cli@latest ``` Or install globally to bypass npx caching entirely: ```bash -npm install -g @bradygaster/squad-cli@0.8.18 +npm install -g @bradygaster/squad-cli@latest ``` ### Wrong version installed @@ -449,7 +469,7 @@ If it shows an old version: ```bash npm uninstall -g @bradygaster/squad-cli -npm install -g @bradygaster/squad-cli@0.8.18 +npm install -g @bradygaster/squad-cli@latest ``` ### Team roster gone after upgrade @@ -473,27 +493,27 @@ Common causes: - Missing `.squad/` directory β€” run `squad init`. - Missing `GITHUB_TOKEN` β€” see [GITHUB_TOKEN issues](#github_token-issues) above. -- Node.js too old β€” upgrade to Node.js 18+. +- Node.js too old β€” upgrade to Node.js 20+. - Corrupted `.squad/` files β€” back up, remove, and reinitialize. ### Node.js version too old -Squad requires Node.js 18 or later. Check your version: +Squad requires Node.js 20 or later. Check your version: ```bash node --version ``` -If below 18, upgrade via [nodejs.org](https://nodejs.org/) or your preferred version manager: +If below 20, upgrade via [nodejs.org](https://nodejs.org/) or your preferred version manager: ```bash # nvm -nvm install 18 -nvm use 18 +nvm install 20 +nvm use 20 # fnm -fnm install 18 -fnm use 18 +fnm install 20 +fnm use 20 ``` --- diff --git a/docs/src/content/docs/guide.md b/docs/src/content/docs/guide.md index 6c2b66bd6..246809f77 100644 --- a/docs/src/content/docs/guide.md +++ b/docs/src/content/docs/guide.md @@ -35,14 +35,15 @@ Both CLIs read and write the same `.squad/` directory, so state stays synchroniz ## Supported Platforms -Squad is designed for **GitHub Copilot CLI** and ships with full support. **VS Code is now fully supported with zero code changes** β€” agents work identically on both 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: -**Current state:** -- βœ… **GitHub Copilot CLI** β€” fully supported. This is the recommended interface for day-to-day work. Uses the stable `task` tool for sub-agent spawning, per-spawn model selection, and background mode. -- βœ… **VS Code Copilot** β€” fully supported (v0.4.0+). VS Code uses `runSubagent` for parallel execution and supports full `.ai-team/` read/write. See [Client Compatibility Matrix](scenarios/client-compatibility.md) for details. -- ❌ **Other platforms** β€” JetBrains IDEs and other runtimes are untested. GitHub.com web-based Copilot is untested. +- **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 +- **Copilot Coding Agent** β€” Autonomous issue processing via `@copilot` -For a detailed feature comparison across platforms (model selection, background execution, file access, etc.), see [Client Compatibility Matrix](scenarios/client-compatibility.md). +Not sure which to use? See [Choose your interface](get-started/choose-your-interface.md) for a complete comparison and decision tree. --- @@ -198,176 +199,49 @@ Squad answers directly without spawning an agent. ## Response Modes -Not every request needs the full agent machinery. Squad uses tiered response modes to balance speed and depth: +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. -| Mode | Approximate Time | What Happens | When Used | -|------|-------------------|-------------|-----------| -| **Direct** | ~2–3s | Coordinator answers from memory/context β€” no agent spawned | Quick factual questions, status checks | -| **Lightweight** | ~8–12s | Agent spawned with reduced overhead (no charter/history/decisions reads) | Simple tasks with known inputs | -| **Standard** | ~25–35s | Full agent spawn with charter, history, and decisions | Most work requests | -| **Full** | ~40–60s | Multi-agent parallel spawn with design review ceremony | Complex multi-domain tasks | - -The coordinator selects the mode automatically. You don't need to specify it. More complex tasks naturally take longer because more agents are working in parallel and reading more context. +β†’ [Full guide: Response Modes](features/response-modes.md) --- ## Memory System -Squad's memory is layered. Knowledge grows with use. - -### Personal memory: `history.md` - -Each agent has its own `history.md` in `.ai-team/agents/{name}/`. After every session, agents append what they learned β€” architecture decisions, conventions, user preferences, key file paths. This file is read only by that agent. - -After a few sessions, agents stop asking questions they've already answered. - -### Shared memory: `decisions.md` - -Team-wide decisions live in `.ai-team/decisions.md`. Every agent reads this before working. Decisions are captured in three ways: - -1. **From agent work** β€” agents write decisions to `.ai-team/decisions/inbox/{name}-{slug}.md` -2. **From user directives** β€” when you say "always use..." or "never do..." -3. **Scribe merges** β€” the Scribe agent consolidates inbox entries into the canonical file, deduplicates, and propagates updates to affected agents - -### Skills: `.ai-team/skills/` - -Skill files (`SKILL.md`) encode reusable knowledge. They come in two varieties: - -- **Starter skills** β€” bundled at init (e.g., squad conventions) -- **Earned skills** β€” written by agents from real work, with a confidence lifecycle: `low β†’ medium β†’ high` - -Agents read relevant skill files before working on a task. +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. -### How memory compounds - -| Stage | What agents know | -|-------|-----------------| -| 🌱 First session | Project description, tech stack, user name | -| 🌿 After a few sessions | Conventions, component patterns, API design, test strategies | -| 🌳 Mature project | Full architecture, tech debt map, regression patterns, performance conventions | +β†’ [Full guide: Memory System](features/memory.md) --- ## Export and Import -### Export your squad - -```bash -npx github:bradygaster/squad export -``` - -Creates `squad-export.json` β€” a portable snapshot of your entire team: agents, casting state, skills, and accumulated knowledge. - -Use this to: -- Back up your team before major changes -- Share a trained team with a colleague -- Move a team to a different repo - -### Import a squad - -```bash -npx github:bradygaster/squad import squad-export.json -``` - -Imports the snapshot into the current repo. Squad handles collision detection β€” if agents with the same names already exist, it warns you. +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. -Use `--force` to archive existing agents and replace them: - -```bash -npx github:bradygaster/squad import squad-export.json --force -``` - -During import, agent histories are split into **portable knowledge** (general learnings that transfer) and **project-specific learnings** (which stay context-tagged). This means imported agents bring their skills without assuming your project works the same way. +β†’ [Full guide: Export and Import](features/export-import.md#export--import) --- ## GitHub Issues Mode -Squad integrates with GitHub Issues via the `gh` CLI for issue-driven development. +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. -### Connect to a repository - -``` -> Connect to myorg/myrepo -``` - -Squad stores the issue source and makes the repository's issues available to the team. - -### View the backlog - -``` -> Show the backlog -``` - -Squad displays open issues in a table format. - -### Assign an issue to an agent - -``` -> Work on #12 -``` - -The appropriate agent picks up the issue. What happens next: - -1. Agent creates a branch with a descriptive name based on the issue -2. Agent does the implementation work -3. Agent opens a PR linked to the issue - -### Handle PR review feedback - -``` -> There's review feedback on PR #3 -``` - -The relevant agent reads the review comments and addresses them. - -### Merge completed work - -``` -> Merge it -``` - -The PR is merged and the linked issue is closed. - -### Check remaining work - -``` -> What's left? -``` - -Squad refreshes the backlog and shows remaining open issues. +β†’ [Full guide: GitHub Issues Mode](features/github-issues.md#github-issues-mode) --- ## PRD Mode -If you have a product requirements document, paste the spec directly: - -``` -> Here's what we're building: -> -> [paste your PRD or spec here] -``` +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. -The Lead agent decomposes the spec into discrete work items. These become trackable tasks that Squad distributes across the team. Each work item gets assigned to the agent best suited for it, and the team works them in parallel where possible. +β†’ [Full guide: PRD Mode](features/prd-mode.md#prd-mode) --- ## Human Team Members -Not every team member needs to be an AI agent. You can add human team members to the roster: - -``` -> Add Sarah as a human team member β€” she handles design reviews -``` - -Human team members appear in the roster with a distinct badge. When work is routed to a human: - -- **Squad pauses** and tells you a human needs to act -- **Stale reminders** trigger if the human hasn't responded after a configurable period -- Humans can serve as **reviewers** in the reviewer protocol +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. -This is useful for teams where certain decisions (design sign-off, security review, product approval) require a real person. +β†’ [Full guide: Human Team Members](features/human-team-members.md#human-team-members) --- @@ -377,54 +251,15 @@ Your squad can notify you when they need input β€” send instant pings to Teams, **Setup is quick:** Configure an MCP notification server (takes 5 minutes), and agents automatically know when to ping you. -See [Notifications Guide](features/notifications.md) for platform-specific setup and examples. For MCP configuration details, see [MCP Setup Guide](features/mcp.md). +See [Notifications Guide](features/notifications.md#quick-start-teams-simplest-path) for platform-specific setup and examples. For MCP configuration details, see [MCP Setup Guide](features/mcp.md#step-by-step-cli-setup). --- ## Ceremonies -Ceremonies are structured team meetings. Squad ships with two default 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 `.ai-team/ceremonies.md`. -### Design Review (automatic) - -**Triggers before** multi-agent tasks involving 2+ agents modifying shared systems. The Lead facilitates, spawning each relevant agent to get their perspective on interfaces, risks, and contracts before work begins. - -``` -> Team, rebuild the authentication system - -πŸ“‹ Design Review completed β€” facilitated by Ripley - Decisions: 3 | Action items: 4 - Agreed on JWT format, session storage strategy, and endpoint contracts -``` - -### Retrospective (automatic) - -**Triggers after** build failures, test failures, or reviewer rejections. The Lead facilitates a focused root-cause analysis. - -``` -πŸ“‹ Retrospective completed β€” facilitated by Ripley - Decisions: 2 | Action items: 3 - Root cause: missing null check in API response parser -``` - -### Manual ceremonies - -You can trigger any ceremony on demand: - -``` -> Run a retro -> Run a design meeting before we start -``` - -You can also create, disable, or skip ceremonies: - -``` -> Add a ceremony for code reviews -> Disable retros -> Skip the design review for this task -``` - -Ceremony configuration lives in `.ai-team/ceremonies.md`. +β†’ [Full guide: Ceremonies](features/ceremonies.md#ceremonies) --- @@ -491,14 +326,9 @@ Agents are never deleted. Their charter and history move to `.ai-team/agents/_al ## Reviewer Protocol -Agents with review authority (typically Tester and Lead) can **reject** work. On rejection: - -1. The original author is **locked out** β€” they cannot revise their own rejected work. -2. A **different agent** must handle the revision. -3. If the revision is also rejected, the revision author is locked out too, and a third agent must take over. -4. If all eligible agents are locked out, Squad escalates to you. +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. -This prevents the common failure mode where an agent keeps "fixing" its own work in circles. +β†’ [Full guide: Reviewer Protocol](features/reviewer-protocol.md#reviewer-rejection-protocol) --- diff --git a/docs/src/content/docs/sample-prompts.md b/docs/src/content/docs/sample-prompts.md index 328152efe..b3a73fee5 100644 --- a/docs/src/content/docs/sample-prompts.md +++ b/docs/src/content/docs/sample-prompts.md @@ -1,925 +1,412 @@ -# Sample Prompts - -Ready-to-use prompts that show what Squad can do. Each one describes a project, the kind of team it needs, and what makes it interesting as a Squad demo. - -Copy any prompt below, open Copilot, select **Squad**, and paste it in. - ---- - -## Quick Builds - -These are small enough that a team can ship them in a single session. Good for seeing parallel fan-out, fast iteration, and agents that don't step on each other. - ---- - -### 1. CLI Pomodoro Timer - -``` -I'm building a cross-platform CLI pomodoro timer in Python. It should support: -- Configurable work/break intervals with sensible defaults (25/5/15) -- A persistent stats tracker that logs completed sessions to a local JSON file -- Desktop notifications on macOS, Windows, and Linux -- A "focus mode" that blocks a configurable list of domains by writing to /etc/hosts (with undo on break) -- A --report flag that prints weekly stats as a table - -Set up the team. I want this done fast β€” everyone works at once. -``` - -**What it demonstrates:** Parallel fan-out on a small, well-scoped project. Backend handles the timer and host-blocking logic, a systems agent handles cross-platform notifications, the tester writes test cases from the spec while implementation is in flight. - ---- - -### 2. Markdown Static Site Generator - -``` -I want a zero-dependency static site generator in Node.js. It takes a folder of markdown files, converts them to HTML using a single built-in template, generates an index page with links to all pages, and outputs everything to a dist/ folder. It should support front matter (title, date, tags), generate tag index pages, and include an RSS feed. No frameworks, no bundlers β€” just fs, path, and a markdown parser we write ourselves. - -Set up the team and start building. -``` - -**What it demonstrates:** Tight collaboration between agents who own different parts of the pipeline (parser, template engine, RSS generator, file I/O). The tester can write test cases from the spec immediately while the others build. Decisions about front matter format propagate via decisions.md. - ---- - -### 3. Retro Snake Game - -``` -Build a browser-based Snake game using vanilla HTML, CSS, and JavaScript. No frameworks. Requirements: -- Canvas-based rendering at 60fps -- Arrow key and WASD controls -- Score tracking with localStorage high scores -- Progressive speed increase every 5 points -- A retro CRT-style visual effect using CSS filters -- Mobile support via touch swipe controls -- Sound effects using the Web Audio API - -Start building immediately β€” I want to play this in 20 minutes. -``` - -**What it demonstrates:** A game where frontend, audio, and input handling can all be built in parallel. The tester writes Playwright tests for keyboard input, scoring, and game-over conditions while the game is being built. Fast iteration β€” agents can see each other's output and adjust. - ---- - -### 4. Turn-by-Turn Text Adventure Engine - -``` -Build a text-based adventure game engine in TypeScript. The engine should: -- Load worlds from JSON files that define rooms, items, NPCs, and transitions -- Support a command parser that handles: go [direction], look, take [item], use [item] on [target], talk to [npc], inventory -- Include a sample adventure with at least 10 rooms, 5 items, 3 NPCs, and 2 puzzles -- Support save/load game state to JSON -- Run in the terminal via Node.js with colored output (chalk) -- Include a "narrator voice" system where room descriptions vary based on items in inventory or previous actions - -Build the engine and the sample adventure at the same time. The content writer and the engine builder should work in parallel. -``` - -**What it demonstrates:** A natural split between engine (parser, state machine, I/O) and content (world design, narrative, puzzles). These two streams can run fully in parallel. The tester writes test cases for command parsing and state transitions from the spec alone. Decisions about data format are shared and respected across streams. - ---- - -### 5. Arcane Duel β€” A Card Battle Game - -``` -Build a strategic card duel game inspired by Magic: The Gathering, playable in the browser. Two players take turns drawing from a shared deck and playing cards onto a battlefield. Requirements: -- 30+ unique cards across 4 categories: Attack, Defense, Spell, Trap -- Each card has: name, mana cost, power, toughness (if creature), effect text -- Turn phases: Draw β†’ Main (play cards, activate abilities) β†’ Combat (declare attackers/blockers, resolve damage) β†’ End -- Mana system: 1 mana gained per turn, max 10. Some cards generate bonus mana. -- Stack-based spell resolution: spells and traps can be played in response to other spells -- Health points: each player starts at 20 HP, wins when opponent reaches 0 -- AI opponent with basic strategy (prioritize removal, protect low HP, bluff traps) -- Visual battlefield using HTML/CSS grid layout showing each player's field, hand, graveyard -- Card hover preview with full art and effect text - -I want one agent designing the card set and balance, another building the game engine and rules, another building the UI, and someone testing the combat math. Go. -``` - -**What it demonstrates:** Deep parallelism with interdependent design. The card designer and engine builder must share data format decisions early (via decisions.md). The UI agent can scaffold the battlefield while cards are still being designed. The tester validates combat resolution math from the rules spec. This is a project where the Scribe's decision propagation is critical β€” when the card designer decides on mana curve, the engine and AI both need to know. - ---- - -### Squad Blog Engine (Meta Demo) - -``` -Build a static blog engine that renders markdown blog posts into beautiful HTML pages. -No frameworks β€” just HTML, CSS, and vanilla JavaScript. - -Input: markdown files from a docs/blog/ directory. Each file has YAML frontmatter -(title, date, author, wave, tags, status, hero). - -Output: -- An index page listing all posts, sorted by date, with title, hero text, author, and tags -- Individual post pages with clean typography, syntax-highlighted code blocks, and responsive tables -- A tag index page that groups posts by tag -- Wave navigation: "← Previous Wave | Next Wave β†’" links on each post -- Dark mode toggle (CSS custom properties, saved to localStorage) -- RSS feed (feed.xml) - -Design direction: -- Clean, modern, developer-focused. Think GitHub's blog meets a personal dev blog. -- Monospace headings, proportional body text -- Code blocks with a dark theme and copy-to-clipboard button -- Mobile responsive β€” single column on small screens -- Fast. No JavaScript required for reading β€” JS only for dark mode toggle and copy button. -- Hero section on the index page with the blog title and a one-liner about the project. - -The markdown parser should handle: headings, paragraphs, lists, code blocks (fenced), -inline code, bold, italic, links, images, blockquotes, horizontal rules, and tables. - -Build the parser, the template engine, the RSS generator, and the static file output. -Put the output in a dist/ folder. Include a build script that can be run with -`node build.js` to regenerate the site. - -Set up the team and build it. I want to see this running in one session. -``` - -**What it demonstrates:** The ultimate meta-demo β€” Squad builds the tool that publishes Squad's own progress story. Input is markdown files Squad already writes (wave completion posts in `docs/blog/`). Parser, templating, RSS, and responsive CSS can all be built in parallel. The finished product is visual (screenshots well), functional (actually renders real content), and narratively perfect: "Squad built this to tell you about itself." - ---- - -## Mid-Size Projects - -These need real coordination. Agents make architectural decisions, share them, and build on each other's work across multiple rounds. - ---- - -### 6. Cloud-Native E-Commerce Store - -``` -Build an event-driven e-commerce store with these services: -- Product Catalog API (Node.js/Express, PostgreSQL) β€” CRUD for products with categories and search -- Order Service (Node.js) β€” accepts orders asynchronously via a message queue, validates inventory, processes payment stubs, emits order-status events -- Notification Service β€” listens for order events, sends email confirmations (stub/log) -- API Gateway β€” routes requests, handles auth (JWT), rate limiting -- Message queue: use RabbitMQ (or an in-memory stub for local dev) -- Frontend: React SPA with product grid, cart, checkout flow - -Each service should be independently deployable with its own Dockerfile. Include a docker-compose.yml that brings up the entire system. The order flow must be fully asynchronous β€” the checkout endpoint returns 202 Accepted immediately, and order status is polled or pushed via WebSocket. - -Set up a team. I want each service owned by a different agent. Let them coordinate on API contracts and event schemas early, then build in parallel. -``` - -**What it demonstrates:** True microservice parallelism. Each service agent works independently after agreeing on contracts (shared via decisions.md). The tester writes integration tests for the order flow end-to-end. Agents must share event schema decisions early β€” Scribe propagation matters. The API gateway agent can scaffold while downstream services are being built. - ---- - -### 7. Playwright-Tested Dashboard App - -``` -Build a project management dashboard using React + TypeScript with a Node.js/Express backend. Features: -- Kanban board with drag-and-drop (columns: Backlog, In Progress, Review, Done) -- Task creation with title, description, assignee, priority, due date -- Filtering by assignee, priority, and status -- Real-time updates via WebSocket (when one user moves a card, others see it) -- User auth with login/signup (JWT, bcrypt) -- SQLite database with Drizzle ORM - -Testing requirements (critical β€” this is the demo): -- Full Playwright test suite covering: - - Login flow (valid credentials, invalid credentials, session persistence) - - Task CRUD (create, edit, delete, verify persistence after refresh) - - Drag-and-drop (move task between columns, verify state update) - - Filtering (apply filters, verify correct tasks shown, clear filters) - - Real-time sync (open two browser contexts, move card in one, verify update in other) -- Generate Gherkin feature files (.feature) for every user story FIRST, then implement Playwright step definitions -- Tests must be runnable with `npx playwright test` and produce an HTML report - -Set up the team. I want the Gherkin specs and Playwright tests written from requirements BEFORE the implementation starts, then updated as the real UI takes shape. -``` - -**What it demonstrates:** Test-first parallel development. The tester writes Gherkin feature files and Playwright test skeletons immediately from the requirements β€” no waiting for implementation. Frontend and backend build in parallel. Once the UI exists, the tester updates tests to match actual selectors. This shows Squad's anticipatory work pattern at its best: tests and implementation converge without blocking each other. - ---- - -### 8. GitHub Copilot Extension - -``` -Build a GitHub Copilot Chat extension using the Copilot Extensions SDK (https://github.com/copilot-extensions). The extension should: -- Act as a "Code Reviewer" agent that users can invoke via @code-reviewer in Copilot Chat -- Accept a GitHub repo URL or PR number as input -- Fetch the diff (via GitHub API) and analyze it for: - - Security issues (SQL injection, XSS, hardcoded secrets, insecure deserialization) - - Performance concerns (N+1 queries, unbounded loops, missing pagination) - - Style violations (configurable rules loaded from a .code-reviewer.yml in the target repo) -- Return structured feedback as a Copilot Chat response with file-level annotations -- Include a Blackbeard-style SSE streaming response handler per the SDK patterns -- Deploy as a Vercel serverless function -- Include a manifest file for registering as a GitHub App - -Read the Copilot Extensions SDK docs and examples carefully. One agent should own the SDK integration and streaming protocol, another should own the analysis engine, another should own the GitHub API integration. Set up the team. -``` - -**What it demonstrates:** Agents that need to read external documentation and build to an SDK's patterns. The SDK integration agent and the analysis engine agent work in parallel β€” one handles the protocol, the other handles the logic. They agree on the interface contract via decisions.md. Shows Squad working with real-world APIs and deployment targets. - ---- - -### 9. .NET Aspire Cloud-Native App - -``` -Build a cloud-native application using .NET Aspire. Read https://learn.microsoft.com/en-us/dotnet/aspire/ for the Aspire programming model. - -The app is a real-time weather dashboard: -- AppHost project orchestrating all services -- Frontend: Blazor Server dashboard showing current conditions and 5-day forecast for saved cities -- Weather API service: wraps OpenWeatherMap API with caching (Redis via Aspire integration) -- User Preferences service: stores saved cities per user (PostgreSQL via Aspire integration) -- Background Worker: refreshes cached weather data every 15 minutes for all saved cities (uses Aspire Worker template) -- Service-to-service communication via Aspire service discovery (no hardcoded URLs) -- Health checks and OpenTelemetry tracing via Aspire defaults - -I want the team organized by Aspire integration: -- One agent owns the AppHost and service discovery wiring -- One agent owns the Redis caching integration -- One agent owns the PostgreSQL data layer -- One agent owns the Blazor frontend -- One agent owns the background worker -- The tester validates that services discover each other and data flows end-to-end - -Set up the team. Each agent should understand their specific Aspire integration deeply. -``` - -**What it demonstrates:** Agents specialized by infrastructure integration rather than traditional roles. Each agent is an expert in one Aspire component. The AppHost agent coordinates wiring while service agents build independently. Decisions about service names and connection strings propagate through decisions.md. Shows Squad handling a .NET-specific ecosystem with genuine infrastructure concerns. - ---- - -## Large Projects - -These push coordination, memory, and team size. Multiple rounds of work, cross-cutting decisions, and agents that need to remember what happened earlier. - ---- - -### 10. Legacy .NET-to-Azure Migration - -``` -I have a legacy .NET Framework application that needs to be migrated to Azure. Clone these two repos to start: - -1. https://github.com/bradygaster/ProductCatalogApp β€” ASP.NET MVC (.NET Framework) web app with: - - Product catalog with shopping cart functionality - - WCF service (SOAP) for product data access - - In-memory product repository - - Order submission to MSMQ (Message Queue) - - jQuery-based frontend - -2. https://github.com/bradygaster/IncomingOrderProcessor β€” Windows Service that: - - Monitors MSMQ for incoming orders - - Processes and logs orders from the queue - - Runs continuously as a background service - -The migration target: -- ProductCatalogApp β†’ ASP.NET Core MVC (.NET 10) or Blazor on Azure App Service - - Replace WCF SOAP service with ASP.NET Core Web API (REST) - - Keep in-memory repository initially, but structure for Azure SQL migration - - Replace MSMQ with Azure Service Bus queues - - Modernize frontend (keep MVC or migrate to Blazor) -- IncomingOrderProcessor β†’ Azure Functions (.NET 8) with Service Bus trigger - - Convert Windows Service to serverless function - - Trigger on Service Bus queue messages - - Maintain same order processing logic -- Shared models β†’ .NET 10 class library used by both services -- Infrastructure: Bicep templates for App Service, Function App, Service Bus namespace and queue -- CI/CD: GitHub Actions workflows for both services -- Local dev: docker-compose or Aspire for running everything locally - -Migration rules: -- Preserve all business logic β€” orders must flow identically -- WCF SOAP contracts become REST APIs with the same data structures -- MSMQ queue becomes Azure Service Bus queue with compatible message format -- The Windows Service becomes a Service Bus-triggered Azure Function -- All services must work locally before Azure deployment - -I need a migration team: one agent for the web app migration, one for the WCF-to-API conversion, one for the Windows Service-to-Functions migration, one for shared models, one for Azure infrastructure (Bicep), one for CI/CD, and a tester who validates that orders flow end-to-end correctly. Set up the team and start with the migration plan. -``` - -**What it demonstrates:** The most realistic Squad scenario β€” migrating actual legacy .NET Framework code to modern Azure. The team must understand existing WCF patterns, MSMQ messaging, Windows Services, and translate them to Azure-native equivalents (REST APIs, Service Bus, Functions). Shows true enterprise migration challenges: agents analyze unfamiliar code, preserve business logic while modernizing infrastructure, coordinate on message formats and shared models, and validate behavioral equivalence across the migration. - ---- - -### 11. Multiplayer Space Trading Game - -``` -Build a multiplayer space trading game playable in the browser. Think Elite Dangerous meets a browser game. - -Game systems: -- Galaxy map: procedurally generated star systems (50+) with stations, connected by trade routes -- Economy: each station buys/sells commodities (fuel, ore, food, tech, luxuries) at dynamic prices driven by supply/demand -- Ships: 3 tiers (shuttle, freighter, cruiser) with cargo capacity, fuel range, and hull strength -- Trading: buy low, sell high. Prices shift based on player activity and random events -- Combat: simple turn-based encounters with pirates or other players at jump points -- Multiplayer: WebSocket-based real-time. Players see each other on the galaxy map. Chat. PvP opt-in. -- Persistence: player state (credits, cargo, location, ship) saved to PostgreSQL -- Frontend: Canvas-based galaxy map, HTML/CSS panels for station UI, trading, inventory - -Tech stack: Node.js backend, PostgreSQL, WebSocket (ws), vanilla HTML/CSS/Canvas frontend. - -I want one agent on the economy/trading engine, one on the galaxy generator and map rendering, one on combat mechanics, one on multiplayer/networking, one on the frontend UI panels, and the tester. The economy designer and galaxy generator can work simultaneously β€” they just need to agree on the star system data format early. Go. -``` - -**What it demonstrates:** A complex game with 6+ agents, each owning a distinct game system that must interoperate. Data format decisions (star system schema, ship stats, commodity definitions) are shared early and respected across all agents. The economy and galaxy agents work in parallel from turn 1. Combat and multiplayer can scaffold independently. The tester writes test cases for trade math, combat resolution, and economy simulation before implementation is final. - ---- - -### 12. AI Recipe App with Image Recognition - -``` -Build a recipe app where users can photograph ingredients and get recipe suggestions. Tech stack: React Native (Expo) frontend, Python FastAPI backend, SQLite. - -Features: -- Camera capture: user photographs ingredients on a counter -- Image analysis: send photo to a vision model (use OpenAI's GPT-4 Vision API) to identify ingredients -- Recipe matching: match identified ingredients against a recipe database (seed with 50+ recipes) -- Recipe display: ingredients list (highlighting what you have vs. what you need), step-by-step instructions, estimated time -- Favorites: save recipes, rate them, add notes -- Shopping list: auto-generate a list of missing ingredients -- Dietary filters: vegetarian, vegan, gluten-free, dairy-free - -I want one agent on the React Native frontend, one on the FastAPI backend and database, one on the vision/AI integration, one curating the recipe database and seed data, and the tester writing API tests and mocking the vision responses. Set up the team. -``` - -**What it demonstrates:** Cross-platform mobile + backend + AI integration. The recipe curator and the AI integration agent can work simultaneously β€” one builds the database, the other figures out the vision API interface. They agree on the ingredient taxonomy via decisions.md. The tester mocks vision API responses to write deterministic tests before the real integration exists. Shows Squad handling AI/ML service integrations. - ---- - -### 13. DevOps Pipeline Builder - -``` -Build a self-service DevOps platform where teams can define their CI/CD pipelines through a web UI. Tech stack: React frontend, Go backend, PostgreSQL, Docker. - -Features: -- Pipeline designer: drag-and-drop UI for composing pipeline stages (build, test, deploy, notify) -- Stage templates: pre-built stages for common tasks (npm build, Docker build, Helm deploy, Slack notify) -- Pipeline execution: stages run as Docker containers orchestrated by the Go backend -- Live logs: stream build output to the browser via SSE -- Pipeline-as-code: export/import pipelines as YAML (compatible with GitHub Actions syntax) -- Secrets management: encrypted storage for API keys, registry credentials -- Execution history: searchable log of all pipeline runs with status, duration, artifacts - -I need a frontend agent for the drag-and-drop pipeline designer, a backend agent for the execution engine, a Docker/infrastructure agent for container orchestration, a security agent for secrets management, and a tester. Set up the team. -``` - -**What it demonstrates:** Agents with very different expertise domains (UI drag-and-drop, container orchestration, cryptography) working on a single product. The execution engine and pipeline designer can be built in parallel once they agree on the pipeline data model. The security agent works independently on secrets encryption. Shows Squad handling infrastructure-heavy projects. - ---- - -### 14. Roguelike Dungeon Crawler - -``` -Build a browser-based roguelike dungeon crawler. Procedurally generated dungeons, permadeath, turn-based combat. - -Requirements: -- Dungeon generation: procedural rooms + corridors using BSP or cellular automata, 10 floors with increasing difficulty -- Character: warrior/mage/rogue classes with unique abilities (3 each), health/mana/stamina stats -- Combat: turn-based, grid-positioned. Melee, ranged, and AoE attacks. Enemy AI that flanks, retreats when low HP, and uses abilities -- Items: weapons, armor, potions, scrolls. Random loot tables per floor. Item identification system (unidentified scrolls/potions until used) -- Fog of war: tile-based visibility using raycasting from player position -- Rendering: HTML5 Canvas with tilemap. 16x16 or 32x32 pixel art style (use simple colored squares if no art assets) -- Permadeath: when you die, it's over. High score table with character name, class, floor reached, cause of death -- Save system: save-on-exit only (no save scumming). LocalStorage. - -I want one agent on dungeon generation, one on combat + enemy AI, one on items + loot tables, one on rendering + fog of war, and the tester. These can all build simultaneously as long as they agree on the tile/entity data model. Start building. -``` - -**What it demonstrates:** Game systems that are independently buildable but share a common data model. Dungeon generation, combat, items, and rendering are four parallel streams that converge on a shared entity/tile format. The early decision on data model (via decisions.md) enables full parallelism. The tester validates combat math, loot distribution, and fog of war calculations from specs. - ---- - -### 15. Real-Time Collaborative Whiteboard - -``` -Build a real-time collaborative whiteboard app using React Flow for the node/shape editor. Think Miro or Excalidraw but simpler. Tech stack: React + TypeScript + React Flow frontend, Node.js backend, WebSocket. - -Features: -- Built on React Flow (https://reactflow.dev/) for drag-and-drop node-based editing -- Shape library: rectangles, circles, text nodes, sticky notes, arrows/edges connecting shapes -- Drag-and-drop: users can drag shapes from a palette onto the canvas, drag to reposition, drag handles to resize -- Color picker, stroke width, fill color, background color per shape -- Connect shapes with arrows (React Flow edges) β€” drag from one shape to another -- Select multiple shapes (bounding box selection), move/delete/style as a group -- Real-time sync: multiple users see each other's cursors and edits via WebSocket -- Rooms: shareable URL creates a room, anyone with the link can join -- Undo/redo per user (each user has their own undo stack) -- Export to PNG and SVG (React Flow has built-in export utilities) -- Persistence: save canvas state (nodes, edges, viewport) to PostgreSQL, auto-save every 30 seconds - -I want a frontend agent owning the React Flow integration and drag-and-drop interactions, a networking agent owning the WebSocket sync and conflict resolution (CRDT or OT for canvas state), a backend agent owning rooms and persistence, and a tester writing Playwright tests for multi-user drag-and-drop scenarios. Set up the team and build it. -``` - -**What it demonstrates:** A project where the networking/sync agent and the frontend agent must closely coordinate on the React Flow data model (nodes, edges, viewport state). The frontend agent leverages React Flow's built-in drag-and-drop and handles, while the networking agent syncs changes across users. The backend agent can work independently on rooms and persistence. The tester writes multi-context Playwright tests (two browsers in one test) to validate real-time drag-and-drop sync β€” a direct showcase of Playwright's multi-page testing and React Flow's powerful node-based editor capabilities. - ---- - -### 16. Multiplayer Dice Roller β€” Bar Games PWA - -``` -Build a mobile-first Progressive Web App for rolling dice with friends at a bar. The vibe: tapping your phone on a virtual green velvet table, realistic 3D dice tumbling across the screen. Tech stack: React + TypeScript, Three.js (or React Three Fiber), Node.js + WebSocket backend, PostgreSQL. - -Features: -- Mobile-first responsive design: works perfectly on phones, tablets, and desktop -- PWA: installable on home screen, works offline (cached dice rolls when disconnected, sync when back online) -- Double-tap gesture: tap the screen twice anywhere to roll the dice β€” they bounce and tumble realistically across a green velvet table -- 3D dice physics: use Three.js or React Three Fiber for realistic dice with physics simulation (gravity, bounce, spin, settle) -- Customizable dice: choose number of dice (1-10), die type (d6, d10, d12, d20), color schemes -- Real-time multiplayer: - - Create a room with a shareable 6-digit code or QR code - - Friends join the same room via code or QR scan - - Everyone sees everyone's rolls in real-time with player names - - Room chat for banter and trash talk -- Game modes with score tracking: - - Freeroll: just roll, no rules, all rolls logged - - Yahtzee: automated scoring, tracks categories, end-of-game leaderboard - - Liar's Dice: player declarations, challenge system, elimination rounds - - Custom: define your own scoring rules (high roll wins, sum target, etc.) -- Score history: view roll history for the session, replay animations, export session log as JSON -- Sound effects: dice clatter, table bounce (mute toggle) -- Haptic feedback on mobile: vibrate on roll, on settle -- Night mode: dark UI with brighter dice for late-night bar sessions - -I want one agent on the Three.js 3D dice rendering and physics, one agent on the mobile PWA setup and touch gesture handling, one agent on the real-time multiplayer backend (rooms, WebSocket, score sync), one agent on game logic (different game modes, scoring rules, turn management), and a tester writing mobile Playwright tests for touch gestures and multiplayer roll sync. Set up the team and build it. -``` - -**What it demonstrates:** A mobile-first project where agents specialize by concern: 3D graphics, touch UX, real-time networking, and game logic. The 3D agent and the gesture agent must coordinate on the tap-to-roll trigger and animation states. The game logic and networking agents share data models for scores and turns. The PWA requirements (offline support, install prompt) and mobile testing (touch events, multi-device Playwright tests) showcase Squad handling production mobile app concerns. This is also a fun, visual demo β€” you can actually play dice games with the finished product. - ---- - -## Feature Showcases - -These prompts are designed to exercise Squad's advanced features β€” export/import, skills, ceremonies, PRD mode, GitHub Issues, human team members, and more. Each one is a real project where the feature shows up naturally. - ---- - -### 17. Cross-Platform Habit Tracker β€” Portable Squad - -``` -I built a CLI habit tracker with a Squad last month in another repo. I exported the squad with `npx github:bradygaster/squad export` and I have the squad-export.json file ready. - -Import it into this repo with `npx github:bradygaster/squad import squad-export.json`. - -Now let's build a cross-platform habit tracker with a React Native (Expo) frontend and a Node.js backend: -- Daily habit check-ins with streaks, miss tracking, and weekly summaries -- Habit categories (health, learning, productivity) with custom icons -- Push notification reminders at user-configured times -- SQLite local-first storage with optional cloud sync (Supabase) -- Charts: streak heatmap (GitHub-style), weekly completion rate, category breakdown -- Widget support for iOS and Android home screens - -The team should already know my preferences from the last project. Start building. -``` - -**What it demonstrates:** Export/import in action. The squad arrives with earned preferences and skills from a previous project β€” coding style, testing patterns, communication style. The user doesn't re-explain anything. The team picks up where it left off, in a brand new repo. This is the "holy crap, it remembers me" moment. - ---- - -### 18. Open Source Contribution Dashboard β€” GitHub Issues + Skills - -``` -Pull issues from bradygaster/squad. Show me the open issues and let me pick which ones to work on. - -While we're at it, the team should build skills as they go β€” if someone figures out a pattern for testing CLI installers or working with the Copilot Extensions SDK, write it down as a skill so the team gets better over time. -``` - -**What it demonstrates:** GitHub Issues Mode β€” connecting to a real repo, listing the backlog, and letting the user pick issues for agents to claim. Each issue flows through the full lifecycle: branch, implement, PR. The skills instruction shows how agents earn reusable SKILL.md files as they work, building team competence that persists across sessions. - ---- - -### 19. Event-Driven Inventory System β€” PRD + Ceremonies - -``` -Here's the PRD at docs/inventory-prd.md β€” it describes an event-driven inventory management system for a small warehouse operation. - -Before the team starts building, run a design review. I want the Lead to decompose the PRD into work items first, then the team should discuss architecture choices (event sourcing vs. CRUD, message broker selection, data model) before anyone writes code. - -Tech constraints from the PRD: -- Node.js services, PostgreSQL, Redis for event streaming -- REST API for external integrations, WebSocket for real-time dashboard -- Barcode scanner input via serial port (node-serialport) -- Audit log for every inventory mutation -``` - -**What it demonstrates:** PRD Mode and Ceremonies working together. The PRD gets ingested and decomposed into work items by the Lead. A design review ceremony runs before implementation β€” agents align on architecture, surface trade-offs, and make shared decisions. The ceremony creates alignment that prevents rework. This is how a real team operates: read the spec, discuss, then build. - ---- - -### 20. Developer Portfolio Site β€” Human Team Member + Tiered Responses - -``` -I'm building a developer portfolio site. Add my teammate Sarah as Designer β€” she'll handle visual direction, color palette, and layout decisions. The rest of the team builds it: - -- Next.js static site with MDX blog posts -- Project showcase with live demo embeds (CodeSandbox/StackBlitz) -- Interactive terminal-style "about me" section (type commands, get responses) -- Dark/light theme with system preference detection -- Lighthouse score targets: 100 performance, 100 accessibility -- Contact form with Resend for email delivery -- RSS feed and open graph meta tags for social sharing - -When work needs Sarah's design input, pause and ask her. Don't guess on visual decisions. -``` - -**What it demonstrates:** Human team members and tiered response modes. Adding Sarah as Designer puts a real person on the roster β€” when work routes to her domain (color choices, layout, typography), Squad pauses and asks for her input instead of guessing. Meanwhile, the tiered response system handles the spectrum: quick questions get instant answers (Direct mode), config tweaks get lightweight edits, and the full build fans out across multiple agents (Full mode). The team adapts its effort to the task size automatically. - ---- - -### 21. API Client SDK Generator β€” Skills + Smart Upgrade - -``` -Before we start, run `npx github:bradygaster/squad` to make sure we're on the latest version. - -Now build an SDK generator that takes an OpenAPI 3.1 spec and produces typed client libraries: -- TypeScript SDK with fetch-based HTTP client, Zod runtime validation, and full JSDoc -- Python SDK with httpx, Pydantic models, and type hints -- Auto-generated test suites for both SDKs (mock server from the spec) -- CLI tool: `sdkgen generate --spec api.yaml --lang typescript --output ./sdk/` -- Watch mode: re-generate when the spec file changes -- Changelog diff: when the spec changes, output a human-readable summary of what changed in the API - -Each language generator is a plugin. The architecture should make adding a Go or Rust generator later trivial. - -As the team works, they should write skills for patterns they discover β€” OpenAPI parsing edge cases, code generation techniques, test mocking strategies. These should be reusable on future SDK projects. -``` - -**What it demonstrates:** Smart upgrade and skills. Running `npx github:bradygaster/squad` in an existing repo detects version differences and migrates β€” the team gets new capabilities without losing any state. As agents build the SDK generator, they write SKILL.md files for patterns they discover (OpenAPI parsing quirks, code generation idioms). Those skills persist and inform future work β€” the next time this squad tackles an API project, it arrives with earned expertise. - ---- - -### 22. Community Recipe Book β€” GitHub Issues + Human Team + History Summarization - -``` -Pull issues from our-org/community-recipes. These are feature requests from our users for a community recipe sharing platform. - -Add my teammate Alex as Content Lead β€” they'll review recipe data models and taxonomy decisions. When there's a question about how to categorize cuisines or structure ingredient lists, ask Alex. - -The platform: -- Next.js app with Prisma + PostgreSQL -- User-submitted recipes with rich text editor (Tiptap) -- Ingredient parser that handles natural language ("2 large eggs, beaten" β†’ structured data) -- Dietary tags with smart detection (scan ingredients for common allergens) -- Recipe scaling (adjust servings, recalculate quantities) -- Social features: favorites, collections, comments, user profiles -- Full-text search with filters (cuisine, dietary, cook time, difficulty) - -We've been working on this for a few sessions now. The Scribe should summarize older history entries to keep things compact β€” we don't need the play-by-play from three sessions ago, just the decisions and learnings. -``` - -**What it demonstrates:** Three features in one natural workflow. GitHub Issues Mode pulls real user requests from the backlog. A human team member (Alex) owns content decisions β€” the team pauses for their input on taxonomy and data modeling. History summarization keeps the team's memory compact after multiple sessions: the Scribe progressively summarizes older entries, archiving the originals so nothing is lost but the working context stays lean. This is what a mature, multi-session project looks like. - ---- - -### 23. IoT Dashboard β€” Full Ceremony Lifecycle + PRD + Export - -``` -Here's the PRD at specs/iot-dashboard.md β€” it describes a real-time IoT sensor dashboard for a small manufacturing floor. - -Run a design review before building. After the first milestone ships, run a retro β€” I want the team to reflect on what worked and what didn't. - -Requirements from the PRD: -- React dashboard with real-time sensor charts (Recharts + WebSocket) -- Node.js ingestion service accepting MQTT messages from sensors -- TimescaleDB for time-series storage with automatic data retention policies -- Alert rules engine: threshold alerts, rate-of-change alerts, dead sensor detection -- Multi-tenant: each manufacturing client sees only their sensors -- Historical data export to CSV and JSON - -When we're done, export the squad β€” I want to bring this team's knowledge to our next IoT project. -``` - -**What it demonstrates:** The full ceremony lifecycle plus PRD Mode and export. A design review ceremony runs before the team touches code β€” agents align on architecture for a complex real-time system. After the first milestone, a retro ceremony captures what worked and what to improve. PRD Mode structures the entire build around a spec document. When the project wraps, `npx github:bradygaster/squad export` captures everything the team learned β€” MQTT patterns, time-series strategies, alert engine design β€” as a portable snapshot ready for the next project. - ---- - -## v0.2.0 Feature Prompts - -Quick prompts that exercise specific v0.2.0 features. Use these to try out individual capabilities without building a full project. - ---- - -### Export & Import - -``` -Export this squad so I can use it in another repo. -``` - -``` -npx github:bradygaster/squad export -``` - -``` -Import the squad from my previous project: npx github:bradygaster/squad import squad-export.json -``` - -``` -Export just the team state β€” I want to send the snapshot to a colleague starting a similar project. -``` - -``` -I imported a squad from another repo. Show me what the team remembers from the previous project. -``` - ---- - -### GitHub Issues - -``` -Connect to our GitHub repo and pull the open issues. Show me the backlog. -``` - -``` -Which issues are highest priority? Let the Lead triage and assign them to the right agents. -``` - -``` -Work issue #42 β€” the Lead should break it down and assign the right agent. Create a branch, implement, and open a PR. -``` - -``` -Show me all issues the team has completed this session. Summarize what was done for each one. -``` - -``` -Close issue #15 and merge the PR β€” the tester confirmed it passes. -``` - ---- - -### PRD Mode - -``` -Here's our PRD at docs/product-requirements.md β€” ingest it and decompose it into work items. -``` - -``` -Show me the work items from the PRD. Which ones are ready to start and which are blocked? -``` - -``` -The PRD has been updated β€” re-read docs/product-requirements.md and flag any new or changed requirements. -``` - -``` -Map the PRD work items to team members. Who owns what? -``` - ---- - -### Human Team Members - -``` -Add my teammate Jordan as Designer β€” they'll handle visual direction and UX decisions. -``` - -``` -Remove the human designer from the team β€” we're past the design phase. -``` - -``` -When work involves database schema decisions, route it to Alex instead of having the AI decide. -``` - -``` -Show me the team roster. Which members are AI and which are human? -``` - -``` -The frontend needs a color palette. Pause and ask Jordan β€” don't guess on visual decisions. -``` - ---- - -### Skills - -``` -What skills has the team earned so far? Show me the full skill inventory. -``` - -``` -Show me the confidence levels for the frontend agent's skills. Which ones are mature? -``` - -``` -The backend agent figured out a caching pattern that works well. Write it as a skill so the team remembers it. -``` - -``` -Which skills have decayed? Are there any the team should refresh by practicing again? -``` - ---- - -### Ceremonies - -``` -Run a retro β€” I want the team to reflect on what worked and what didn't this sprint. -``` - -``` -Before we start building, run a design review. The Lead should present the architecture and the team should challenge it. -``` - -``` -Run a standup β€” each agent reports what they did, what they're doing next, and any blockers. -``` - -``` -Create a custom ceremony called "Demo Day" where each agent presents what they built and the team gives feedback. -``` - -``` -Schedule a retro after every third session automatically. -``` - ---- - -## v0.3.0 Feature Prompts - -Quick prompts that exercise specific v0.3.0 features. Use these to try out individual capabilities. - ---- - -### Ralph β€” Work Monitor - -``` -Enable Ralph to watch the team's work. Start monitoring background task execution. -``` - -``` -Check Ralph's status β€” show me what the team is currently working on and task queue depth. -``` - -``` -Ralph, configure idle-watch mode. Alert me if an agent hasn't made progress for more than 10 minutes. -``` - -``` -Scope Ralph's monitoring to just the backend agent. Ignore frontend for now. -``` - -``` -Show me Ralph's activity log for the past hour β€” what tasks completed, what failed, what's queued? -``` - ---- - -### Per-Agent Model Selection - -``` -Override the model for the backend agent β€” use Claude Opus for complex database design instead of the default. -``` - -``` -Run this feature with a cheaper model to save costs. Use GPT-4 Mini for the frontend work. -``` - -``` -Bump the Lead's model to Claude Opus for this session. We need better reasoning for architecture decisions. -``` - -``` -The frontend agent just used Haiku for the styling work. Show me what model was used. -``` - -``` -Set up model rotation: use Opus for design reviews, Sonnet for implementation, Haiku for tests. -``` - ---- - -### @copilot Coding Agent - -``` -Add @copilot to the team as the coding specialist. Auto-assign code generation and refactoring to them. -``` - -``` -Configure @copilot to handle all TypeScript work. Route TypeScript issues directly to them. -``` - -``` -Show me @copilot's capabilities. What can they do and what do they need human review on? -``` - -``` -@copilot just finished the component refactor. Review their work before I merge. -``` - -``` -Remove @copilot from the team. We're doing code review manually going forward. -``` - ---- - -### Labels & Triage - -``` -Add priority labels to all open issues. What's critical vs. nice-to-have? -``` - -``` -Show me the triage status for issue #42. Who said what about the verdict? -``` - -``` -Change the verdict on issue #8 from "blocked" to "ready-to-start" β€” the dependency is resolved. -``` - -``` -Tag issues for the v1.0 release. Show me what's targeted for the next milestone. -``` - -``` -Set priority: mark frontend bugs as P1, documentation updates as P3. -``` - ---- - -### Directives - -``` -Set a coding style preference: prefer functional components over class components in React. -``` - -``` -Add a scope constraint: don't touch authentication logic without explicit approval from the Lead. -``` - -``` -Set a process rule: all pull requests must have a code review before merging. -``` - -``` -Show me the team's current directives. What rules are we following? -``` - -``` -Update the documentation preference: use JSDoc for all public functions with @param and @return tags. -``` - ---- - -### Parallel Execution - -``` -Start these three tasks in parallel: implement the API endpoint, write tests, and update docs. -``` - -``` -Run this work in sync mode β€” I want real-time output instead of background execution. -``` - -``` -Check the status of my background agents. Which tasks completed and which are still running? -``` - -``` -The frontend and backend agents are working in parallel. Show me their progress separately. -``` - -``` -Cancel the background task for the database migration β€” we're taking a different approach. -``` - ---- - -### Reviewer Protocol - -``` -Request a code review from Alex before this PR merges. They're our database expert. -``` - -``` -The reviewer rejected my changes. Show me their feedback and what needs to be fixed. -``` - -``` -Reassign the PR review to Jordan β€” the original reviewer is busy with another task. -``` - -``` -I've addressed the review feedback. Re-request approval from the reviewer. -``` - -``` -Show me all PRs waiting for review. Who's blocking and when did they last respond? -``` - ---- - -### Worktree Awareness - -``` -I'm working in a git worktree. Update the team root path so commands run in the right directory. -``` - -``` -Switch to a different worktree strategy β€” we're rotating who works on what branch. -``` - -``` -Show me the team root location. Confirm we're pointing at the right working directory. -``` - -``` -The worktree was deleted. Recover the team state and pick a new working directory. -``` - -``` -I need to work on multiple features in parallel using worktrees. Help me set up the team for that workflow. -``` +# Sample Prompts + +Ready-to-use prompts for Squad. Copy any prompt, open Copilot, select **Squad**, and paste it in. + +--- + +## Quick Builds + +Small projects that ship in a single session. Good for parallel fan-out and fast iteration. + +--- + +### 1. CLI Pomodoro Timer + +``` +I'm building a cross-platform CLI pomodoro timer in Python: +- Configurable work/break intervals (25/5/15 defaults) +- Persistent stats tracker (local JSON) +- Desktop notifications (macOS, Windows, Linux) +- Focus mode: blocks domains via /etc/hosts (with undo) +- --report flag for weekly stats table + +Set up the team. I want this done fast β€” everyone works at once. +``` + +**What it demonstrates:** +- Parallel fan-out on a small, well-scoped project +- Backend handles timer logic while systems agent tackles cross-platform notifications +- Tester writes test cases from spec while implementation is in flight + +--- + +### 2. Markdown Static Site Generator + +``` +Zero-dependency static site generator in Node.js: markdownβ†’HTML with built-in template, generates index page, outputs to dist/. Support front matter (title, date, tags), tag index pages, RSS feed. No frameworks β€” just fs, path, and a custom markdown parser. + +Set up the team and start building. +``` + +**What it demonstrates:** +- Agents own distinct pipeline components (parser, template engine, RSS, file I/O) +- Tester writes test cases from spec while others build in parallel +- Front matter format decisions propagate via decisions.md + +--- + +### 3. Retro Snake Game + +``` +Browser Snake game (vanilla HTML/CSS/JS, no frameworks): +- Canvas rendering at 60fps +- Arrow keys and WASD controls +- Score tracking with localStorage high scores +- Progressive speed increase every 5 points +- Retro CRT-style CSS filters +- Mobile: touch swipe controls +- Sound effects via Web Audio API + +Start building β€” I want to play in 20 minutes. +``` + +**What it demonstrates:** +- Frontend, audio, and input handling built in parallel +- Tester writes Playwright tests while game is under construction +- Fast iteration with visible progress across agents + +--- + +### 4. Turn-by-Turn Text Adventure Engine + +``` +Text-based adventure engine in TypeScript: +- Load worlds from JSON (rooms, items, NPCs, transitions) +- Command parser: go [dir], look, take [item], use [item] on [target], talk to [npc], inventory +- Sample adventure: 10 rooms, 5 items, 3 NPCs, 2 puzzles +- Save/load game state to JSON +- Terminal via Node.js with colored output (chalk) +- Narrator voice: descriptions vary by inventory/actions + +Build engine and sample adventure simultaneously. Content writer and engine builder work in parallel. +``` + +**What it demonstrates:** +- Natural split between engine logic and content creation +- Both streams run fully in parallel with shared data format decisions +- Tester writes test cases from spec before implementation completes + +--- + +### 5. Arcane Duel β€” A Card Battle Game + +``` +Strategic card duel game (browser, inspired by MTG): +- 30+ cards across 4 types: Attack, Defense, Spell, Trap (with mana cost, power, toughness, effects) +- Turn phases: Draw β†’ Main β†’ Combat β†’ End +- Mana system: +1 per turn (max 10), some cards generate bonus mana +- Stack-based spell resolution +- HP: 20 each, win at 0 +- AI opponent with basic strategy +- HTML/CSS grid battlefield showing fields, hands, graveyards +- Card hover preview + +One agent designs cards/balance, another builds engine/rules, another builds UI, tester validates combat math. Go. +``` + +**What it demonstrates:** +- Deep parallelism requiring early data format alignment via decisions.md +- UI scaffolding proceeds while card design is underway +- Scribe's decision propagation becomes critical (mana curve affects engine and AI) + +--- + +### Squad Blog Engine (Meta Demo) + +``` +Static blog engine rendering markdown posts to HTML (no frameworks): + +Input: docs/blog/ markdown with YAML frontmatter (title, date, author, wave, tags, status, hero). + +Output: +- Index page: posts sorted by date, with title/hero/author/tags +- Post pages: clean typography, syntax-highlighted code, responsive tables +- Tag index grouping posts by tag +- Wave navigation: ← Previous | Next β†’ links +- Dark mode toggle (CSS custom properties, localStorage) +- RSS feed (feed.xml) + +Design: Clean, modern, developer-focused. Monospace headings, proportional body. Dark code blocks with copy button. Mobile responsive. Fast β€” no JS for reading (JS only for dark mode and copy). + +Build parser, template engine, RSS generator, static output (dist/). Include `node build.js` script. Set up team and build in one session. +``` + +**What it demonstrates:** +- Meta-demo where Squad builds its own publishing tool +- All components (parser, templating, RSS, CSS) build in parallel +- Finished product is visual, functional, and self-documenting + +--- + +## Mid-Size Projects + +Real coordination needed. Agents make architectural decisions, share them, and build across multiple rounds. + +--- + +### 6. Cloud-Native E-Commerce Store + +``` +Build an event-driven e-commerce store: +- Product Catalog API (Node.js/Express, PostgreSQL) β€” CRUD + search +- Order Service (Node.js) β€” async processing via message queue, payment stubs, events +- Notification Service β€” listens for order events, emails confirmations +- API Gateway β€” auth (JWT), rate limiting +- RabbitMQ or in-memory stub for local dev +- React SPA: product grid, cart, checkout + +Each service with its own Dockerfile. Include docker-compose.yml. Orders return 202 Accepted, status polled/pushed via WebSocket. + +Set up a team. One agent per service. Coordinate on API contracts and event schemas early, then build in parallel. +``` + +**What it demonstrates:** +- True microservice parallelism with contract-first coordination +- Event schema decisions must propagate early via Scribe +- API gateway scaffolds while downstream services build independently + +--- + +### 7. Playwright-Tested Dashboard App + +``` +Build a project management dashboard (React + TypeScript, Node.js/Express): +- Kanban board with drag-and-drop (Backlog, In Progress, Review, Done) +- Task creation: title, description, assignee, priority, due date +- Filtering by assignee, priority, status +- Real-time updates via WebSocket +- User auth: login/signup (JWT, bcrypt) +- SQLite + Drizzle ORM + +Full Playwright test suite covering login, CRUD, drag-and-drop, filtering, real-time sync (two browser contexts). Write Gherkin feature files FIRST, then implement Playwright step definitions. Runnable with `npx playwright test`. + +Set up the team. Write Gherkin specs and test skeletons before implementation starts, update as UI takes shape. +``` + +**What it demonstrates:** +- Test-first development with Gherkin specs written before implementation +- Frontend and backend build in parallel while tests scaffold +- Anticipatory work pattern: tests and implementation converge without blocking + +--- + +### 8. GitHub Copilot Extension + +``` +Build a GitHub Copilot Chat extension (Copilot Extensions SDK): +- Act as @code-reviewer agent +- Accept GitHub repo URL or PR number +- Fetch diff via GitHub API, analyze for security (SQL injection, XSS, secrets), performance (N+1 queries), style violations (configurable .code-reviewer.yml) +- Return structured feedback with file-level annotations +- Blackbeard-style SSE streaming response +- Deploy as Vercel serverless function +- Include GitHub App manifest + +Read SDK docs carefully. One agent owns SDK integration/streaming, another owns analysis engine, another owns GitHub API. Set up the team. +``` + +**What it demonstrates:** +- Agents read external SDK docs and build to prescribed patterns +- SDK integration and analysis engine work in parallel with shared interface contract +- Real-world API integration with deployment considerations + +--- + +### 9. .NET Aspire Cloud-Native App + +``` +Build a cloud-native app with .NET Aspire (read https://learn.microsoft.com/en-us/dotnet/aspire/): +- AppHost orchestrating all services +- Blazor Server dashboard: current conditions + 5-day forecast for saved cities +- Weather API service: wraps OpenWeatherMap with Redis caching +- User Preferences service: stores cities (PostgreSQL) +- Background Worker: refreshes cache every 15 minutes +- Service discovery via Aspire (no hardcoded URLs) +- Health checks and OpenTelemetry tracing + +Team organized by Aspire integration: AppHost/discovery, Redis caching, PostgreSQL, Blazor frontend, background worker. Tester validates service discovery and end-to-end data flow. Set up the team. +``` + +**What it demonstrates:** +- Agents specialized by infrastructure component rather than traditional roles +- AppHost coordinates wiring while service agents build independently +- Infrastructure decisions (service names, connection strings) propagate via decisions.md + +--- + +## Large Projects + +Complex coordination, memory, and team size. Multiple rounds, cross-cutting decisions, agents remember earlier work. + +--- + +### 10. Legacy .NET-to-Azure Migration + +``` +Migrate legacy .NET Framework to Azure. Clone: +1. https://github.com/bradygaster/ProductCatalogApp β€” ASP.NET MVC with WCF SOAP, in-memory repo, MSMQ orders +2. https://github.com/bradygaster/IncomingOrderProcessor β€” Windows Service monitoring MSMQ + +Target: +- ProductCatalogApp β†’ ASP.NET Core/.NET 10 or Blazor on App Service. WCFβ†’REST API, MSMQβ†’Service Bus +- IncomingOrderProcessor β†’ Azure Functions with Service Bus trigger +- Shared models β†’ .NET 10 class library +- Infrastructure: Bicep for App Service, Function App, Service Bus +- CI/CD: GitHub Actions +- Local dev: docker-compose or Aspire + +Preserve all business logic. SOAPβ†’REST with same data structures, MSMQβ†’Service Bus compatible format. + +Team: web app migration, WCF-to-API, Windows Service-to-Functions, shared models, Azure infrastructure, CI/CD, tester. Start with migration plan. +``` + +**What it demonstrates:** +- Realistic enterprise migration from legacy .NET Framework to modern Azure +- Agents analyze unfamiliar code and translate to Azure-native patterns +- Business logic preservation while modernizing infrastructure (WCFβ†’REST, MSMQβ†’Service Bus) + +--- + +### 11. Multiplayer Space Trading Game + +``` +Build multiplayer space trading game (browser-based): +- Galaxy: 50+ procedural star systems with stations, trade routes +- Economy: dynamic commodity prices (fuel, ore, food, tech, luxuries) driven by supply/demand +- Ships: 3 tiers with cargo capacity, fuel range, hull strength +- Trading: buy low, sell high. Prices shift with player activity and events +- Combat: turn-based encounters with pirates/players +- Multiplayer: WebSocket real-time. Players see each other, chat, PvP opt-in +- Persistence: PostgreSQL (credits, cargo, location, ship) +- Frontend: Canvas galaxy map, HTML/CSS panels for station/trading/inventory + +Tech: Node.js, PostgreSQL, WebSocket, vanilla HTML/CSS/Canvas. + +One agent per system: economy/trading, galaxy generator/map, combat, multiplayer/networking, frontend UI, tester. Economy and galaxy work simultaneously β€” agree on star system data format early. Go. +``` + +**What it demonstrates:** +- Complex game with 6+ agents owning distinct but interoperating systems +- Data format decisions shared early and respected across all agents +- Economy and galaxy agents work in parallel from turn 1 + +--- + +### 12. AI Recipe App with Image Recognition + +``` +Build recipe app with image recognition (React Native Expo, Python FastAPI, SQLite): +- Camera: photograph ingredients +- Image analysis: GPT-4 Vision to identify ingredients +- Recipe matching: match against database (50+ recipes) +- Recipe display: ingredients (have vs. need), instructions, time +- Favorites: save, rate, notes +- Shopping list: auto-generate missing ingredients +- Dietary filters: vegetarian, vegan, gluten-free, dairy-free + +One agent: React Native frontend. One: FastAPI backend + DB. One: vision/AI integration. One: recipe curation/seed data. Tester: API tests with mocked vision responses. Set up team. +``` + +**What it demonstrates:** +- Cross-platform mobile + backend + AI integration in one project +- Recipe curator and AI integration agent work simultaneously with shared taxonomy +- Tester mocks vision API responses for deterministic testing before real integration + +--- + +### 13. DevOps Pipeline Builder + +``` +Build self-service DevOps platform (React, Go, PostgreSQL, Docker): +- Pipeline designer: drag-and-drop UI composing stages (build, test, deploy, notify) +- Stage templates: npm build, Docker build, Helm deploy, Slack notify +- Pipeline execution: stages run as Docker containers (Go orchestration) +- Live logs: stream to browser via SSE +- Pipeline-as-code: export/import YAML (GitHub Actions compatible) +- Secrets management: encrypted storage +- Execution history: searchable logs with status, duration, artifacts + +Team: frontend (drag-and-drop), backend (execution engine), Docker/infrastructure, security (secrets), tester. Set up team. +``` + +**What it demonstrates:** +- Agents with diverse expertise (UI, containers, cryptography) on one product +- Execution engine and pipeline designer build in parallel with shared data model +- Security agent works independently on secrets encryption + +--- + +### 14. Roguelike Dungeon Crawler + +``` +Build browser-based roguelike dungeon crawler: +- Dungeons: procedural rooms/corridors (BSP or cellular automata), 10 floors, scaling difficulty +- Character: warrior/mage/rogue with unique abilities (3 each), health/mana/stamina +- Combat: turn-based, grid-positioned. Enemy AI flanks, retreats at low HP +- Items: weapons, armor, potions, scrolls. Random loot tables. Unidentified items until used +- Fog of war: tile-based visibility with raycasting +- Rendering: Canvas with tilemap (16x16 or 32x32 colored squares) +- Permadeath: high score table with name, class, floor, cause of death +- Save: save-on-exit only (LocalStorage) + +One agent per: dungeon gen, combat + AI, items + loot, rendering + fog of war, tester. All build simultaneously with shared tile/entity data model. Start building. +``` + +**What it demonstrates:** +- Four independently buildable systems converging on shared data model +- Early data model decision via decisions.md enables full parallelism +- Tester validates game math from specs while systems are under construction + +--- + +### 15. Real-Time Collaborative Whiteboard + +``` +Build real-time collaborative whiteboard using React Flow (React + TypeScript, Node.js, WebSocket): +- Built on React Flow (https://reactflow.dev/) +- Shapes: rectangles, circles, text, sticky notes, arrows/edges +- Drag-and-drop from palette, reposition, resize (handles) +- Color picker, stroke width, fill/background per shape +- Multi-select (bounding box), group operations +- Real-time sync: cursor + edits via WebSocket +- Rooms: shareable URL +- Undo/redo per user +- Export: PNG and SVG +- Persistence: PostgreSQL (nodes, edges, viewport), auto-save every 30s + +Frontend agent: React Flow + drag-and-drop. Networking: WebSocket sync + conflict resolution. Backend: rooms + persistence. Tester: Playwright multi-user drag-and-drop tests. Set up team. +``` + +**What it demonstrates:** +- Networking and frontend agents coordinate closely on React Flow data model +- Frontend leverages React Flow's built-in features while networking syncs across users +- Tester writes multi-context Playwright tests for real-time sync validation + +--- + +### 16. Multiplayer Dice Roller β€” Bar Games PWA + +``` +Build mobile-first PWA dice roller (React + TypeScript, Three.js/React Three Fiber, Node.js + WebSocket, PostgreSQL): +- Mobile-first responsive, PWA installable, works offline +- Double-tap to roll: realistic 3D dice with physics (Three.js) +- Customizable: 1-10 dice, die types (d6, d10, d12, d20), colors +- Multiplayer: rooms with 6-digit code or QR, real-time roll sync, chat +- Game modes: Freeroll, Yahtzee (auto-scoring), Liar's Dice, custom rules +- Score history: roll log, replay animations, export JSON +- Sound effects, haptic feedback, night mode + +One agent: 3D dice/physics. One: PWA/gesture handling. One: multiplayer backend (rooms, WebSocket, scores). One: game logic. Tester: mobile Playwright for touch + multiplayer. Set up team. +``` + +**What it demonstrates:** +- Mobile-first project with agents specialized by concern (3D, touch, networking, logic) +- 3D and gesture agents coordinate on tap-to-roll triggers and animation states +- PWA requirements and mobile testing showcase production mobile app concerns + +--- + +## Advanced Features + +For detailed guidance on advanced features like export/import, GitHub Issues integration, ceremonies, PRD mode, human team members, and skills, see [Tips and Tricks](tips-and-tricks.md). + diff --git a/docs/src/content/docs/scenarios/client-compatibility.md b/docs/src/content/docs/scenarios/client-compatibility.md index d9d577376..29585bdf0 100644 --- a/docs/src/content/docs/scenarios/client-compatibility.md +++ b/docs/src/content/docs/scenarios/client-compatibility.md @@ -1,5 +1,7 @@ # Copilot Client Compatibility Matrix +> **Quick answer:** Not sure which interface to use? See [Choose your interface](../get-started/choose-your-interface.md) for a concise decision tree and comparison. + Squad runs on multiple Copilot surfaces β€” each with its own agent spawning mechanism, tool set, and constraints. This document maps Squad's core capabilities across CLI, VS Code, JetBrains, and GitHub.com to help you understand what works where. ## Quick Reference diff --git a/docs/src/content/docs/scenarios/release-process.md b/docs/src/content/docs/scenarios/release-process.md index df101f4e1..9674a6ada 100644 --- a/docs/src/content/docs/scenarios/release-process.md +++ b/docs/src/content/docs/scenarios/release-process.md @@ -22,66 +22,41 @@ Complete step-by-step guide for Squad maintainers: three-branch model (dev/previ 4. [Merging Back to Dev](#merging-back-to-dev) 5. [Full Release Lifecycle](#full-release-lifecycle) 6. [Branch Protection Rules](#branch-protection-rules) -7. [Testing the Guard Workflow](#testing-the-guard-workflow) -8. [Troubleshooting](#troubleshooting) -9. [Sample Prompts](#sample-prompts) +7. [Troubleshooting](#troubleshooting) +8. [Sample Prompts](#sample-prompts) --- ## Branch Model Overview -Squad uses a **three-branch model** for release safety: - | Branch | Purpose | Who Commits | Guard Active? | Files Allowed | |--------|---------|------------|---------------|---------------| | **dev** | Development β€” all work happens here | All team members | ❌ No | Everything (`.ai-team/`, team-docs, etc.) | | **preview** | Staging/testing β€” validated product only | Release coordinator | βœ… Yes | Distribution files only (`.ai-team/` blocked) | | **main** | Production β€” release source for `npx` | Release coordinator | βœ… Yes | Distribution files only (`.ai-team/` blocked) | -**Key principle:** `.ai-team/` (team state) and internal `team-docs/` (except blog) never leave dev. When code ships, it ships clean. - --- ## Preview Build Workflow -Purpose: Create a staging environment to test the full release before pushing to production. - ### Step 1: Create the Preview Branch -Start on `dev` and ensure you have the latest commits: - ```bash git checkout dev git pull origin dev -``` - -Create a preview branch (or reset if it exists): - -```bash git checkout -b preview 2>/dev/null || git checkout preview git reset --hard dev ``` ### Step 2: Remove Forbidden Files (Guard Enforcement) -Before pushing to `preview`, remove forbidden paths that the guard workflow will block: +Remove forbidden paths: ```bash -# Remove .ai-team/ (keep local copy via .gitignore) git rm --cached -r .ai-team/ - -# Remove team-docs/ git rm --cached -r team-docs/ ``` -If nothing was removed, that's fine: - -```bash -git status -# On branch preview -# nothing to commit, working tree clean -``` - If there are changes: ```bash @@ -91,37 +66,7 @@ git push -f origin preview ### Step 3: Review and Test -Verify your release PR is ready for merge by checking CI status in GitHub. Ensure all tests pass and code review is complete: - -```bash -# View PR status -gh pr view --web -``` - -Expected output: βœ… All checks pass and PR is approved. - -If checks fail, review the logs and fix any issues. - -### Step 4: Test on Preview - -Push test branches off `preview` and create PRs back to `preview` to validate the release: - -```bash -# Create a feature branch off preview -git checkout -b test/release-validation -echo "# Release validation" > RELEASE_TEST.md -git add RELEASE_TEST.md -git commit -m "test: release validation" -git push -u origin test/release-validation -``` - -Create a PR via `gh`: - -```bash -gh pr create --base preview --title "Release validation test" --body "Validate preview build." -``` - -The guard checks this PR. If it passes, your preview branch is clean. +Verify CI status passes and code review is complete. Push test branches off `preview` to validate the release; if guard passes, your preview branch is clean. --- @@ -129,102 +74,56 @@ The guard checks this PR. If it passes, your preview branch is clean. ### Creating a PR (Feature Work on Dev) -When a feature is complete on `dev`, create a PR for review: - ```bash git checkout -b feature/my-feature # ... make changes ... git add . git commit -m "feat: my new feature" git push -u origin feature/my-feature -``` - -Create the PR: - -```bash gh pr create --base dev --title "feat: my new feature" --body "Description of changes" ``` ### Reviewing a PR -Reviewers use the GitHub UI or `gh` CLI: - -```bash -# View open PRs -gh pr list --base dev - -# Review a specific PR -gh pr view 123 --web -``` - -Comments, approvals, and change requests flow through GitHub. No special commands needed. +Use GitHub UI or `gh` CLI to view and review PRs. ### Merging a PR to Dev -Once approved, merge to `dev`: - ```bash gh pr merge 123 --merge --auto -``` - -This squash-merges the PR and deletes the feature branch. To keep history with merge commits: - -```bash -gh pr merge 123 --create-branch-off-target --auto -``` - -After merge, update your local dev: - -```bash -git checkout dev -git pull origin dev +git checkout dev && git pull origin dev ``` --- ## Merging Back to Dev -After a release ships from `main`, sync changes back to `dev` (for docs updates, changelog, version bumps made during release): +After a release ships from `main`, sync changes back to `dev`: ### Step 1: Create a Sync PR -On your `dev` branch: - ```bash git checkout dev git pull origin dev git checkout -b chore/sync-from-main -``` - -Merge `main` into the sync branch: - -```bash git merge main --no-ff --no-edit ``` -This brings all production commits back to dev, preserving the release tag and history. - ### Step 2: Resolve Conflicts (if any) -If conflicts exist, resolve them: +If conflicts exist: ```bash -git status -# Lists conflicted files +git status # Lists conflicted files git add . git commit -m "chore: resolve merge conflicts from main" ``` -### Step 3: Push and Create PR +### Step 3: Push and Merge ```bash git push -u origin chore/sync-from-main gh pr create --base dev --title "chore: sync from main" --body "Bring production changes back to dev" -``` - -### Step 4: Merge Back - -```bash gh pr merge --merge --auto git checkout dev && git pull origin dev ``` @@ -233,49 +132,28 @@ git checkout dev && git pull origin dev ## Full Release Lifecycle -Complete journey from feature work to production tag. - ### Phase 1: Preparation (on `dev`) -**Time:** Before release day. All features complete, all tests passing. - 1. **Update CHANGELOG.md:** -```bash -# Edit CHANGELOG.md with new version entry -# Format: ## [X.Y.Z] β€” YYYY-MM-DD -# Sections: Added, Changed, Community, Deprecated, Removed, Fixed -nano CHANGELOG.md -``` - -Example entry: - ```markdown ## [0.4.0] β€” 2026-02-15 ### Added - MCP tool discovery and integration - Plugin marketplace support -- Notification system (Trello, Teams, GitHub) -- 11 new universes (Futurama, Seinfeld, The Office, etc.) -- Branch protection guard (squad-main-guard.yml) ### Changed -- VS Code support now fully compatible (zero code changes) -- Agent progress signals with [MILESTONE] markers -- Universe count: 20 β†’ 31 +- VS Code support now fully compatible ### Community -- @csharpfritz: MCP tool discovery (#11), user docs (#16) -- @spboyer: VS Code compatibility (#17) +- @csharpfritz: MCP tool discovery (#11) ``` 2. **Update version in package.json:** ```bash -# Edit version field -nano package.json -# "version": "0.4.0" +nano package.json # Set "version": "0.4.0" ``` 3. **Commit to dev:** @@ -288,33 +166,11 @@ git push origin dev ### Phase 2: Preview Build (on `preview`) -**Time:** Release day morning. Validate all files before shipping. - -Follow [Preview Build Workflow](#preview-build-workflow) above. Summary: - -```bash -git checkout preview -git reset --hard origin/dev -git rm --cached -r .ai-team/ 2>/dev/null -git rm --cached -r team-docs/ 2>/dev/null -git commit -m "chore: remove forbidden paths for preview" 2>/dev/null -git push -f origin preview -# Wait for guard workflow to pass -``` - -Check GitHub Actions: - -```bash -gh run list --branch preview --status completed --limit 1 -``` - -Expected: βœ… All checks pass. +Follow [Preview Build Workflow](#preview-build-workflow). ### Phase 3: Merge to Main (on `main`) -**Time:** Release day afternoon, after preview validation. - -1. **Create a release PR to main:** +1. **Create a release PR:** ```bash git checkout main @@ -336,12 +192,8 @@ gh pr create --base main --title "Release v0.4.0" --body "Final release PR. Guar gh pr merge --merge --auto ``` -The guard validates that only distribution-safe files reach `main`. - ### Phase 4: Tag the Release (on `main`) -**Time:** After merge to `main`. This triggers the release workflow. - ```bash git checkout main git pull origin main @@ -349,30 +201,19 @@ git tag -a v0.4.0 -m "Release v0.4.0: MCP integration, Plugin marketplace, Notif git push origin v0.4.0 ``` -Tag format: `vX.Y.Z` (semantic versioning). The version MUST match `package.json` version. +Tag format: `vX.Y.Z` (must match `package.json` version). ### Phase 5: Verify the Release -The tag push triggers `.github/workflows/release.yml`: +Monitor the release workflow: ```bash -# Monitor the release workflow gh run list --workflow release.yml --status in_progress gh run list --workflow release.yml --status completed --limit 1 ``` -Check what the workflow does: - -1. Runs full test suite -2. Creates a GitHub Release with notes -3. Validates that only distribution files were shipped - -If the workflow fails, see [Troubleshooting](#troubleshooting). - ### Phase 6: Sync Back to Dev -After release, bring version/changelog updates back to dev: - ```bash git checkout dev git pull origin dev @@ -387,36 +228,22 @@ git pull origin dev ## Branch Protection Rules -The repository enforces protection rules on `main` and `preview` to prevent accidental shipping of forbidden files. - -### What's Protected - | Branch | Rule | Effect | |--------|------|--------| | `main` | Require PR review | All PRs require at least 1 approval | | `main` | Require status checks to pass | Tests must pass before merge allowed | | `preview` | Require status checks to pass | Tests must pass before merge allowed | - -## File Integrity - -Always verify before pushing to main or preview that you have not accidentally included team runtime state files (.squad/, .ai-team/, etc.). These files should only exist on dev branches. - --- ## Troubleshooting ### Issue: Forbidden Files Detected in PR -**Problem:** You accidentally committed `.ai-team/` or other team state files to your PR. - -**Prevention:** Use `.gitignore` rules and verify `git status` before pushing: +Use `.gitignore` rules and verify `git status` before pushing: ```bash -# Check what will be committed git status - -# If you see .ai-team/ or similar, remove it: git rm --cached -r .ai-team/ git commit -m "chore: remove runtime state files" git push @@ -426,21 +253,14 @@ git push ### Issue: SSH Hangs During Push -**Symptom:** `git push` hangs indefinitely. - -**Cause:** SSH authentication timeout or network issue. - **Fix:** ```bash -# Try with HTTP instead (if you have auth configured) +# Try HTTP instead git remote set-url origin https://github.com/bradygaster/squad.git git push origin -# Or explicitly use SSH with a shorter timeout -GIT_SSH_COMMAND="ssh -v" git push origin - -# If still stuck, check your SSH key +# Or test SSH ssh -T git@github.com ``` @@ -448,23 +268,11 @@ ssh -T git@github.com ### Issue: .ai-team/ Files Keep Getting Committed -**Symptom:** `.ai-team/` shows as untracked but somehow appears in commits. - -**Cause:** Files were previously tracked (added with `git add -f` before `.gitignore` was updated). - -**Fix:** Remove tracked copies permanently (one time per repo): +**Fix:** ```bash -# Remove .ai-team/ from git tracking git rm --cached -r .ai-team/ - -# Verify .gitignore has .ai-team/ -grep ".ai-team" .gitignore - -# If not, add it -echo ".ai-team/" >> .gitignore - -# Commit +grep ".ai-team" .gitignore || echo ".ai-team/" >> .gitignore git add .gitignore git commit -m "chore: ensure .ai-team/ is untracked" git push origin dev @@ -474,11 +282,7 @@ git push origin dev ### Issue: Missing Workflows in .github/workflows/ -**Symptom:** Other Squad workflows are missing or accidentally deleted. - -**Cause:** Workflows not installed during Squad init, or accidentally deleted. - -**Fix:** Re-run upgrade to restore workflows: +**Fix:** ```bash npx github:bradygaster/squad upgrade @@ -487,141 +291,67 @@ git commit -m "chore: restore Squad workflows" git push origin dev ``` -Available Squad workflows: -- `squad-heartbeat.yml` β€” Ralph's periodic triage and labeling -- `squad-issue-assign.yml` β€” Auto-assign labeled issues -- `squad-label-enforce.yml` β€” Enforce label namespace integrity -- `squad-triage.yml` β€” Triage unlabeled issues -- `sync-squad-labels.yml` β€” Sync static label definitions - --- ### Issue: GitHub Release Not Created After Tag -**Symptom:** Tag pushed but no GitHub Release appears. - -**Cause:** Release workflow failed, or release already exists for that tag. - **Fix:** ```bash -# Check workflow status gh run list --workflow release.yml --status completed --limit 1 +gh run view # Check details -# View the latest run details -gh run view - -# If the workflow failed, check logs -gh run view --log - -# If no release exists, create manually -gh release create v0.4.0 --title "v0.4.0" \ - --notes-file CHANGELOG.md - -# To set as prerelease (for 0.x versions) -gh release create v0.4.0 --title "v0.4.0" --prerelease \ - --notes-file CHANGELOG.md +# Create manually if needed +gh release create v0.4.0 --title "v0.4.0" --notes-file CHANGELOG.md --prerelease ``` --- ## Sample Prompts -Use these with Kobayashi or in Copilot sessions to guide release work. - ### To Prepare for Release ``` -Kobayashi, prepare v0.4.0 for release: -1. Update CHANGELOG.md with the new version entry -2. Update version in package.json -3. Commit both changes to dev branch - -Use these features as the new entry: -- MCP tool discovery and integration -- Plugin marketplace support -- Notification system -- 11 new universes -- Branch protection guard +Kobayashi, prepare v0.4.0: update CHANGELOG.md and package.json version, commit to dev ``` ### To Build a Preview ``` -Kobayashi, build a preview branch: -1. Create preview branch from dev -2. Remove .ai-team/ and team-docs/ (except blog) -3. Commit the removal -4. Push to origin -5. Wait for guard workflow to pass -6. Confirm the guard result +Kobayashi, build a preview branch from dev, remove forbidden files, push to origin, and confirm the guard passes ``` ### To Tag a Release ``` -Kobayashi, tag the release: -1. Checkout main -2. Create and push tag v0.4.0 -3. Verify the release workflow starts -4. Report when it completes +Kobayashi, checkout main, create and push tag v0.4.0, verify the release workflow starts, and report when it completes ``` ### To Sync After Release ``` -Kobayashi, sync main back to dev: -1. Create a chore/sync-from-main branch -2. Merge main into it -3. Create and merge PR back to dev -4. Confirm dev is up to date +Kobayashi, create a chore/sync-from-main branch, merge main into it, create and merge PR back to dev, and confirm dev is up to date ``` ### To Test the Guard ``` -Kobayashi, test the guard workflow: -1. Create a test branch test/guard-ai-team-block -2. Add .ai-team/agents/test/history.md with dummy content -3. Commit and push -4. Create PR to main -5. Report the guard result (should fail) -6. Remove the file and push again -7. Report the final guard result (should pass) -8. Clean up the branch +Kobayashi, test the guard workflow by creating a test branch with .ai-team/ content, creating a PR to main (should fail), removing the file (should pass), and cleaning up ``` ### To Fix a Blocked PR ``` -Kobayashi, fix this blocked PR: -1. Fetch the current PR state -2. Remove all .ai-team/ and team-docs/ files -3. Commit the removal -4. Push to update the PR -5. Wait for guard to pass +Kobayashi, fetch the current PR state, remove all .ai-team/ and team-docs/ files, commit, push to update the PR, and wait for guard to pass ``` --- ## Key Files Reference -- **Release workflow:** `.github/workflows/release.yml` (if it exists) +- **Release workflow:** `.github/workflows/release.yml` - **Changelog:** `CHANGELOG.md` -- **Distribution config:** `package.json` (version, files array) -- **Ignore rules:** `.gitignore`, `.npmignore`, `.gitattributes` -- **Branch protection settings:** GitHub repo Settings β†’ Branches -- **Distributed via:** `npx github:bradygaster/squad` - ---- - -## Tips - -- **Preview is your staging environment.** Test everything there before merging to main. -- **Guard is your safety net.** Let it block forbidden filesβ€”it's preventing distribution corruption. -- **`.ai-team/` never leaves dev.** It's runtime state, not product. -- **Tag from main only.** This is your single source of truth for releases. -- **Version in package.json must match git tag.** Keep them in sync. -- **Communicate releases.** Update team.md, decisions.md, and CHANGELOG.md before shipping. -- **Use `gh` CLI for everything.** It's faster and more reliable than web UI for scripting. +- **Version:** `package.json` +- **Ignore rules:** `.gitignore`, `.npmignore` +- **Branch protection:** GitHub repo Settings β†’ Branches diff --git a/docs/src/content/docs/sdk-first-mode.md b/docs/src/content/docs/sdk-first-mode.md index eaad7131e..72a22a7d2 100644 --- a/docs/src/content/docs/sdk-first-mode.md +++ b/docs/src/content/docs/sdk-first-mode.md @@ -6,6 +6,24 @@ Squad now supports **SDK-First Mode**: define your team in TypeScript with full --- +## What gets generated + +Running `squad build` generates these files: + +| File | Condition | Contains | +|------|-----------|----------| +| `.squad/team.md` | Always | Team roster, member list, project context | +| `.squad/routing.md` | If `routing` defined | Routing rules and default agent | +| `.squad/agents/{name}/charter.md` | For each agent | Agent role, model, tools, capabilities | +| `.squad/ceremonies.md` | If `ceremonies` defined | Ceremony schedule and agenda | + +**Protected files** (never overwritten): +- `.squad/decisions.md` / `.squad/decisions-archive.md` +- `.squad/agents/*/history.md` +- `.squad/orchestration-log/*` + +--- + ## What is SDK-First Mode? In SDK-First Mode: @@ -17,18 +35,7 @@ In SDK-First Mode: This replaces manual `.squad/team.md`, `.squad/routing.md`, and agent charters with a single source of truth in code. ---- - -## Which Mode Should I Use? - -| Scenario | Command | What You Get | -|----------|---------|-------------| -| New project, want simplicity | `squad init` | Markdown-only `.squad/` directory | -| New project, want type safety | `squad init --sdk` | `.squad/` + `squad.config.ts` with typed builders | -| Existing squad, want to upgrade | `squad migrate --to sdk` | Keeps your team, generates typed config | -| SDK squad, want to simplify | `squad migrate --to markdown` | Removes config, keeps markdown | - -**Start with markdown.** It's simpler, requires no build step, and works great for most projects. **Upgrade to SDK** when you want type-safe configuration, IDE autocomplete, and the ability to define skills and ceremonies in TypeScript. +**When to use SDK mode:** For a comparison of SDK-first mode versus CLI mode, see the [Getting started guide](/guide#how-teams-form-init-mode). --- @@ -97,40 +104,15 @@ This generates: --- -## Starting a New SDK-First Project +## Start a new SDK-first project ```bash squad init --sdk ``` -This generates: -- `.squad/` directory with all standard markdown files (team.md, routing.md, agent charters, etc.) -- `squad.config.ts` at your project root using the `defineSquad()` builder syntax - -Your `squad.config.ts` is the source of truth. Edit it, then run `squad build` to regenerate `.squad/`. - -### What Gets Generated - -```typescript -import { - defineSquad, - defineTeam, - defineAgent, -} from '@bradygaster/squad-sdk'; - -export default defineSquad({ - version: '1.0.0', - team: defineTeam({ - name: 'my-project', - members: ['scribe'], - }), - agents: [ - defineAgent({ name: 'scribe', role: 'scribe', description: 'Scribe', status: 'active' }), - ], -}); -``` +This generates `.squad/` markdown files and a `squad.config.ts` at your project root using the `defineSquad()` builder syntax. Your TypeScript config is the source of truth β€” edit it, then run `squad build` to regenerate `.squad/`. -Without `--sdk`, `squad init` creates a markdown-only squad β€” no config file, no build step needed. +For the full team initialization flow, see [How teams form (Init Mode)](/guide#how-teams-form-init-mode) in the getting started guide. --- @@ -177,9 +159,37 @@ This replaces the old `squad upgrade --migrate-directory` command. --- -## Builder Functions +## Builder functions -Each builder accepts a configuration object, validates it at runtime, and returns the typed value. The pattern mirrors `defineConfig()` β€” identity-passthrough with runtime safety. +Each builder accepts a configuration object, validates it at runtime, and returns the typed value. + +### Common types reference + +All builders share these core patterns: + +```typescript +// Base types used across multiple builders +interface AgentCapability { + readonly name: string; + readonly level: 'expert' | 'proficient' | 'basic'; +} + +interface RoutingRule { + readonly pattern: string; + readonly agents: readonly string[]; + readonly tier?: 'direct' | 'lightweight' | 'standard' | 'full'; + readonly priority?: number; +} + +// Lifecycle and status +type AgentStatus = 'active' | 'inactive' | 'retired'; +type FallbackBehavior = 'ask' | 'default-agent' | 'coordinator'; +type OverflowStrategy = 'reject' | 'generic' | 'rotate'; +type ConfidenceLevel = 'low' | 'medium' | 'high'; +type SkillSource = 'manual' | 'observed' | 'earned' | 'extracted'; +``` + +--- ### `defineTeam(config)` @@ -194,17 +204,6 @@ const team = defineTeam({ }); ``` -**Type:** - -```typescript -interface TeamDefinition { - readonly name: string; - readonly description?: string; - readonly projectContext?: string; - readonly members: readonly string[]; -} -``` - | Field | Type | Required | Notes | |-------|------|----------|-------| | `name` | string | βœ… | Team name (non-empty) | @@ -233,25 +232,6 @@ const edie = defineAgent({ }); ``` -**Type:** - -```typescript -interface AgentDefinition { - readonly name: string; - readonly role: string; - readonly charter?: string; - readonly model?: string; - readonly tools?: readonly string[]; - readonly capabilities?: readonly AgentCapability[]; - readonly status?: 'active' | 'inactive' | 'retired'; -} - -interface AgentCapability { - readonly name: string; - readonly level: 'expert' | 'proficient' | 'basic'; -} -``` - | Field | Type | Required | Notes | |-------|------|----------|-------| | `name` | string | βœ… | Unique identifier (kebab-case, no `@`) | @@ -259,13 +239,8 @@ interface AgentCapability { | `charter` | string | ❌ | Character description or link to charter | | `model` | string | ❌ | Model preference (e.g., `"claude-sonnet-4"`, `"claude-haiku-4.5"`) | | `tools` | string[] | ❌ | Allowed tools (e.g., `["grep", "edit", "view"]`) | -| `capabilities` | object[] | ❌ | Capability list with proficiency levels | -| `status` | enum | ❌ | Lifecycle: `'active'` (default), `'inactive'`, `'retired'` | - -**Capability Levels:** -- `expert` β€” core competency -- `proficient` β€” strong knowledge -- `basic` β€” foundational +| `capabilities` | `AgentCapability[]` | ❌ | Capability list with proficiency levels (see Common Types) | +| `status` | `AgentStatus` | ❌ | Lifecycle: `'active'` (default), `'inactive'`, `'retired'` | --- @@ -285,33 +260,13 @@ const routing = defineRouting({ }); ``` -**Type:** - -```typescript -interface RoutingDefinition { - readonly rules: readonly RoutingRule[]; - readonly defaultAgent?: string; - readonly fallback?: 'ask' | 'default-agent' | 'coordinator'; -} - -interface RoutingRule { - readonly pattern: string; - readonly agents: readonly string[]; - readonly tier?: 'direct' | 'lightweight' | 'standard' | 'full'; - readonly priority?: number; -} -``` - -**Routing Tiers:** -- `direct` β€” skip ceremony, execute immediately -- `lightweight` β€” quick handoff, minimal overhead -- `standard` β€” normal workflow with decision checkpoints -- `full` β€” maximum governance, review gates +| Field | Type | Required | Notes | +|-------|------|----------|-------| +| `rules` | `RoutingRule[]` | βœ… | Pattern-based routing rules (see Common Types) | +| `defaultAgent` | string | ❌ | Fallback agent ref | +| `fallback` | `FallbackBehavior` | ❌ | `'ask'`, `'default-agent'`, or `'coordinator'` | -**Fallback Behavior:** -- `ask` β€” ask the user for routing direction -- `default-agent` β€” use the `defaultAgent` -- `coordinator` β€” delegate to the Squad coordinator +**Routing tiers:** `direct` (skip ceremony), `lightweight` (quick handoff), `standard` (normal workflow), `full` (maximum governance). --- @@ -329,19 +284,6 @@ const standup = defineCeremony({ }); ``` -**Type:** - -```typescript -interface CeremonyDefinition { - readonly name: string; - readonly trigger?: string; - readonly schedule?: string; - readonly participants?: readonly string[]; - readonly agenda?: string; - readonly hooks?: readonly string[]; -} -``` - | Field | Type | Required | Notes | |-------|------|----------|-------| | `name` | string | βœ… | Ceremony name | @@ -367,18 +309,6 @@ const hooks = defineHooks({ }); ``` -**Type:** - -```typescript -interface HooksDefinition { - readonly allowedWritePaths?: readonly string[]; - readonly blockedCommands?: readonly string[]; - readonly maxAskUser?: number; - readonly scrubPii?: boolean; - readonly reviewerLockout?: boolean; -} -``` - | Field | Type | Required | Notes | |-------|------|----------|-------| | `allowedWritePaths` | string[] | ❌ | Glob patterns (e.g., `["src/**", "docs/**"]`) | @@ -404,20 +334,11 @@ const casting = defineCasting({ }); ``` -**Type:** - -```typescript -interface CastingDefinition { - readonly allowlistUniverses?: readonly string[]; - readonly overflowStrategy?: 'reject' | 'generic' | 'rotate'; - readonly capacity?: Readonly>; -} -``` - -**Overflow Strategies:** -- `reject` β€” refuse to cast if universe is at capacity -- `generic` β€” use a generic persona -- `rotate` β€” cycle through available universes +| Field | Type | Required | Notes | +|-------|------|----------|-------| +| `allowlistUniverses` | string[] | ❌ | Permitted fictional universes | +| `overflowStrategy` | `OverflowStrategy` | ❌ | `'reject'`, `'generic'`, or `'rotate'` | +| `capacity` | `Record` | ❌ | Max agents per universe | --- @@ -435,18 +356,6 @@ const telemetry = defineTelemetry({ }); ``` -**Type:** - -```typescript -interface TelemetryDefinition { - readonly enabled?: boolean; - readonly endpoint?: string; - readonly serviceName?: string; - readonly sampleRate?: number; - readonly aspireDefaults?: boolean; -} -``` - | Field | Type | Required | Notes | |-------|------|----------|-------| | `enabled` | boolean | ❌ | Master on/off switch (default: `false`) | @@ -481,13 +390,13 @@ const gitWorkflow = defineSkill({ | Field | Type | Required | Description | |-------|------|----------|-------------| -| `name` | `string` | βœ… | Unique skill name (kebab-case) | -| `description` | `string` | βœ… | What this skill teaches | -| `domain` | `string` | βœ… | Category (e.g., 'orchestration', 'testing') | -| `confidence` | `'low' \| 'medium' \| 'high'` | β€” | Skill maturity level | -| `source` | `'manual' \| 'observed' \| 'earned' \| 'extracted'` | β€” | How the skill was learned | -| `content` | `string` | βœ… | The skill body (patterns, examples) | -| `tools` | `SkillTool[]` | β€” | MCP tools relevant to this skill | +| `name` | string | βœ… | Unique skill name (kebab-case) | +| `description` | string | βœ… | What this skill teaches | +| `domain` | string | βœ… | Category (e.g., 'orchestration', 'testing') | +| `confidence` | `ConfidenceLevel` | ❌ | `'low'`, `'medium'`, or `'high'` | +| `source` | `SkillSource` | ❌ | `'manual'`, `'observed'`, `'earned'`, or `'extracted'` | +| `content` | string | βœ… | The skill body (patterns, examples) | +| `tools` | `SkillTool[]` | ❌ | MCP tools relevant to this skill | Skills defined in `squad.config.ts` are generated to `.squad/skills/{name}/SKILL.md` when you run `squad build`. @@ -513,34 +422,19 @@ export default defineSquad({ }); ``` -**Type:** - -```typescript -interface SquadSDKConfig { - readonly version?: string; - readonly team: TeamDefinition; - readonly agents: readonly AgentDefinition[]; - readonly routing?: RoutingDefinition; - readonly ceremonies?: readonly CeremonyDefinition[]; - readonly hooks?: HooksDefinition; - readonly casting?: CastingDefinition; - readonly telemetry?: TelemetryDefinition; -} -``` - --- -## `squad build` Command +## `squad build` command Compile TypeScript Squad definitions into `.squad/` markdown. -### Usage +**Usage:** ```bash squad build [options] ``` -### Flags +**Flags:** | Flag | What it does | |------|-------------| @@ -548,65 +442,22 @@ squad build [options] | `--dry-run` | Show what would be generated without writing | | `--watch` | Rebuild on `.ts` file changes (coming soon) | -### Examples - -**Rebuild all generated files:** +**Examples:** ```bash +# Rebuild all generated files squad build -``` -**Validate that generated files match disk:** - -```bash +# Validate that generated files match disk (useful in CI/CD) squad build --check -``` -This is useful in CI/CD to ensure the config is in sync: - -```yaml -# .github/workflows/squad-check.yml -- name: Check Squad config - run: squad build --check -``` - -**Preview changes before writing:** - -```bash +# Preview changes before writing squad build --dry-run ``` -Output: -``` -ℹ️ Dry run β€” would generate 6 file(s): - - create .squad/team.md - create .squad/routing.md - create .squad/agents/edie/charter.md - create .squad/agents/mcmanus/charter.md - create .squad/ceremonies.md - overwrite .squad/hooks.md -``` - -### Generated Files - -`squad build` generates: - -| File | Condition | Contains | -|------|-----------|----------| -| `.squad/team.md` | Always | Team roster, member list, project context | -| `.squad/routing.md` | If `routing` defined | Routing rules and default agent | -| `.squad/agents/{name}/charter.md` | For each agent | Agent role, model, tools, capabilities | -| `.squad/ceremonies.md` | If `ceremonies` defined | Ceremony schedule and agenda | - -**Protected files** β€” never overwritten: -- `.squad/decisions.md` / `.squad/decisions-archive.md` -- `.squad/agents/*/history.md` -- `.squad/orchestration-log/*` - --- -## Config Discovery +## Config discovery `squad build` discovers your config in this order: @@ -614,18 +465,13 @@ Output: 2. `squad.config.ts` β€” Alternative location 3. `squad.config.js` β€” JavaScript fallback -The config must export one of: -- **`export default config`** β€” default export -- **`export { config }`** β€” named export -- **`export { squadConfig }`** β€” alias +The config must export: `export default config` (default export), `export { config }` (named export), or `export { squadConfig }` (alias). --- ## Validation -All builders perform runtime validation with typed error messages. - -If validation fails: +All builders perform runtime validation with typed error messages. Example: ```typescript defineAgent({ @@ -635,27 +481,6 @@ defineAgent({ // BuilderValidationError: [defineAgent] "role" must be a non-empty string ``` -Validation is: -- **Runtime** β€” catches errors at build time, not runtime -- **Typed** β€” assertions narrow TypeScript types -- **Descriptive** β€” error messages include field path and expected type -- **No dependencies** β€” no Zod, JSON Schema, or external validators - ---- - -## Migration Guide: From Manual to SDK-First - -### Before (manual `.squad/team.md`) - -```markdown -# Squad Team β€” Core Squad - -## Members - -| Name | Role | Charter | -|------|------|---------| -| Edie | TypeScript Engineer | `.squad/agents/edie/charter.md` | -``` You manually maintain this file and agent charters. diff --git a/docs/src/content/docs/tips-and-tricks.md b/docs/src/content/docs/tips-and-tricks.md index 9eea3e5ec..d375d33e0 100644 --- a/docs/src/content/docs/tips-and-tricks.md +++ b/docs/src/content/docs/tips-and-tricks.md @@ -207,181 +207,21 @@ This prevents "we decided different things" surprises. ## Tips for Working with Ralph (Work Monitor) -### 1. Activate Ralph When You Have Backlog +Ralph excels at grinding through backlogs while you focus on urgent work. Activate him when you have open issues, let him report every 3-5 rounds, and check his status before wrapping up. The heartbeat workflow means your squad triages issues between sessions. -Ralph is most useful when you have open issues. +**Best tip:** Give Ralph scope constraints if you need to pause certain work (e.g., `"Ralph, scope: just issues"` when you don't want PRs merged yet). -``` -> Ralph, start monitoring -``` - -Ralph will: -- Check GitHub Issues for untriaged work -- Ask the Lead to triage -- Assign issues to team members -- Spawn agents to work through them -- Report every 3 rounds - -### 2. Give Ralph a Scope If Needed - -By default, Ralph monitors issues, PRs, and CI. - -``` -> Ralph, scope: just issues -``` - -Useful when: -- You're in the middle of a PR and don't want Ralph to merge it yet -- You only care about triaging issues, not closing them -- You want to focus on one type of work - -### 3. Ralph Reports Automatically Every 3-5 Rounds - -Don't ask for status β€” Ralph tells you. - -``` -πŸ”„ Ralph: Round 3 complete. - βœ… 2 issues closed, 1 PR merged - πŸ“‹ 3 items remaining: #42, #45, PR #12 - Continuing... (say "Ralph, idle" to stop) -``` - -When you see this, you can: -- Let Ralph keep working (he will) -- Say "Ralph, idle" to stop -- Jump in with a different task -- Check a specific issue - -### 4. Use Ralph Between Sessions - -The `squad-heartbeat` workflow runs every 30 minutes (or on your schedule). - -Ralph will: -- Triage new issues -- Assign them to team members -- Trigger `@copilot` if you have the coding agent enabled - -This means your squad works even when you're not at the keyboard. - -### 5. Check Ralph's Status Before Wrapping Up - -``` -> Ralph, status -``` - -Ralph does one check and reports: - -``` -πŸ“Š Board Status: - πŸ”΄ Untriaged: 0 issues need triage - 🟑 In Progress: 1 issue assigned, 0 draft PRs - 🟒 Ready: 0 PRs approved - βœ… Done: 7 issues closed this session -``` - -If the board is clean, you can wrap up. If there's work, start Ralph for the next session. +β†’ [Full Ralph guide](features/ralph.md#ralph--work-monitor) --- ## Managing Decisions and Team Memory -### 1. Set Permanent Rules Early - -The first or second session, establish conventions. - -``` -> Here are the permanent rules for this team: -> - Always use TypeScript strict mode -> - Component naming: PascalCase (never kebab-case) -> - All exports are named exports (no defaults) -> - Test coverage must be > 80% -> - PR must have at least one review before merge -``` - -These go to `decisions.md`. Every agent reads them before working. **You only have to say them once.** +Set permanent rules early so agents read them before every task β€” you only say them once. When agents disagree, check `decisions.md` for missing decisions. When agents make mistakes, turn the lesson into a directive (`"Never commit environment variables to git"`). Scribe handles decision merging automatically. -### 2. Use User Directives for "Never Again" Lessons +**Best tip:** Archive outdated decisions in a "Superseded" section so agents ignore them. Check agent `history.md` files when they seem lost β€” they might be missing context that was learned in previous sessions. -When an agent makes a mistake, turn it into a directive. - -``` -> Never use inline styles. Use CSS classes instead. -> Always validate user input on the backend, not just the frontend. -> Never commit environment variables to git. -``` - -These get stored as directives and agents follow them automatically in future sessions. - -### 3. Check decisions.md When Agents Disagree - -If Frontend does something one way and Backend does it another way, the decision is usually missing. - -``` -Agent A: "I used kebab-case for the file names" -Agent B: "I used PascalCase for the file names" - -[You check .ai-team/decisions.md] -[No decision about file naming conventions] - -> Here's the permanent rule: all component files are PascalCase. -``` - -Now it's in the shared brain. Next agent to work on components will see this. - -### 4. Archive Outdated Decisions - -When a decision no longer applies, move it to a "Superseded" section. - -You can edit `.ai-team/decisions.md` directly: - -```markdown -## Superseded Decisions - -- **File naming (v1)**: "All files kebab-case" β€” SUPERSEDED by PascalCase convention in v2 -- **API versioning (v1)**: "Use URL paths for versioning" β€” SUPERSEDED by headers-based versioning - -## Active Decisions -... -``` - -Agents know to ignore "Superseded" sections. - -### 5. Let Scribe Handle Decision Merging - -Agents write decisions to `/decisions/inbox/`, Scribe merges them into `/decisions.md`. - -You don't have to manually merge. Just ask: - -``` -> Scribe, merge pending decisions -``` - -Scribe will: -- Read all files in `/decisions/inbox/` -- Merge them into the canonical `decisions.md` -- Deduplicate overlaps -- Clean up the inbox - -This happens automatically in mature teams, but you can force it anytime. - -### 6. Personal History Files Build Over Time - -Each agent's `.ai-team/agents/{name}/history.md` grows with every session. Check it when an agent seems lost. - -``` -[Dallas's history shows] -- React expertise: hooks, context, performance patterns -- Knowledge of routing: react-router v6 -- Knows about the design system: established in session 3 -- Familiar with the component structure: 50+ components in src/components/ -``` - -If an agent keeps asking "where are the components?", their history might not have the right info. Edit it directly or remind them: - -``` -> Dallas, your last 5 sessions were all in the same component library. -> Check your history.md for the path. -``` +β†’ [Full memory guide](features/memory.md) --- diff --git a/test/docs-build.test.ts b/test/docs-build.test.ts index 8fee82f68..5d9adcee8 100644 --- a/test/docs-build.test.ts +++ b/test/docs-build.test.ts @@ -15,7 +15,7 @@ const BLOG_CONTENT_DIR = join(CONTENT_DIR, 'blog'); const DIST_DIR = join(DOCS_DIR, 'dist'); // Expected content directories in src/content/docs/ -const EXPECTED_GET_STARTED = ['installation', 'first-session']; +const EXPECTED_GET_STARTED = ['choose-your-interface', 'first-session', 'installation', 'migration']; const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell', 'faq'];