diff --git a/docs/src/content/docs/get-started/choose-your-interface.md b/docs/src/content/docs/get-started/choose-your-interface.md index a0c1d9a07..6ab6cd55f 100644 --- a/docs/src/content/docs/get-started/choose-your-interface.md +++ b/docs/src/content/docs/get-started/choose-your-interface.md @@ -1,178 +1,120 @@ -# 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`) - -> ⚠️ **Deprecated:** The interactive shell is no longer recommended. Use [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) instead for a richer agent experience. -> -> ```bash -> copilot --agent squad -> ``` - -REPL mode for conversational interaction directly via the Squad CLI. Enter `squad` with no arguments to start a persistent shell session. - -### 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 | Interactive shell | SDK | -|---------|:------------------:|:-------:|:---------:|:--------:|:---:| -| Agent spawning | ✅ | ✅ | ✅ | ⚠️ (deprecated) | ✅ | -| 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 +# Choose your interface +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. +### 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`) +Background GitHub automation that picks up labeled issues and opens draft PRs. Works across your organization with human-defined guardrails. 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 approved issues in the background** | **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 | ✅ | ✅ | ✅ | ✅ | +| 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/choosing-your-path.md b/docs/src/content/docs/get-started/choosing-your-path.md deleted file mode 100644 index 16eacec5e..000000000 --- a/docs/src/content/docs/get-started/choosing-your-path.md +++ /dev/null @@ -1,82 +0,0 @@ -# Choose your path - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - -CLI, Copilot agent, or SDK? Pick the right mode for your workflow. - ---- - -## Three modes - -### CLI mode - -Install Squad globally or per-project, then use terminal commands to initialize, route work, and manage your team. - -```bash -npm install -g @bradygaster/squad-cli -squad init -squad status -squad watch -``` - -**Use for:** Terminal workflows, automation scripts, CI/CD integration. - ---- - -### Copilot agent mode - -Talk to Squad in GitHub Copilot CLI or VS Code. Squad is built-in as an agent. Your `.squad/` directory works identically to CLI mode. - -```bash -copilot -> /agent Squad - -Squad: Hey Brady, what are you building? -``` - -**Use for:** Conversational workflows, exploratory work, VS Code users. - ---- - -### SDK mode - -Write TypeScript code that spawns agents, routes work, and coordinates teams programmatically. Full access to Squad's internals. - -```bash -npm install @bradygaster/squad-sdk -``` - -```typescript -import { Coordinator } from '@bradygaster/squad-sdk'; - -const coordinator = new Coordinator(); -const result = await coordinator.route('Build a login page'); -``` - -**Use for:** Building tools on Squad, custom integrations, advanced automation. - ---- - -## Decision table - -| **Your goal** | **Use** | -|---------------|---------| -| Try Squad quickly | **Copilot agent** — no install | -| Work in the terminal | **CLI** | -| Work in VS Code | **Copilot agent** | -| Automate repetitive tasks | **CLI** or **SDK** | -| Build custom tooling | **SDK** | -| CI/CD integration | **CLI** or **SDK** | - ---- - -## Can I use multiple modes? - -Yes. Your `.squad/` directory is the source of truth. CLI, Copilot agent, and SDK all read and write the same files. You can switch between modes anytime. - -Example workflow: -1. Use **Copilot agent** to form your team and do exploratory work -2. Use **CLI** (`squad watch`) to monitor issues in the background -3. Use **SDK** to build a custom deployment script that spawns agents - -All three modes share the same memory and decisions. diff --git a/docs/src/content/docs/get-started/first-session.md b/docs/src/content/docs/get-started/first-session.md index 6c62bbebc..447e0a983 100644 --- a/docs/src/content/docs/get-started/first-session.md +++ b/docs/src/content/docs/get-started/first-session.md @@ -1,95 +1,65 @@ # Your First Session - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - A step-by-step walkthrough from install to parallel fan-out. Follow along in your terminal. --- - ## Try this: - ```bash mkdir my-app && cd my-app && git init -squad +squad init ``` - Then tell your team what you're building. --- - ## 1. Install Squad - Start with a git repo — new or existing: - ```bash mkdir my-app && cd my-app git init -squad +squad init ``` - You'll see: - ``` ✅ Squad installed. .github/agents/squad.agent.md — coordinator agent .squad/templates/ — 11 template files - Open GitHub Copilot and select Squad from the agent list. ``` --- - ## 2. Open Copilot — Your Team Forms - Start the Copilot CLI: - ```bash copilot ``` - Select **Squad** from the `/agent` list (CLI) or `/agents` (VS Code). Squad greets you by name: - ``` Hey Brady, what are you building? ``` - Describe your project: - ``` > I'm building a recipe sharing app with React and Node.js. Users can > post recipes, search by ingredient, and save favorites. ``` - Squad proposes a team. The coordinator analyzes your description and suggests specialists: - ``` Here's your team: - 🏗️ Hicks — Lead Scope, decisions, code review ⚛️ Ripley — Frontend Dev React, UI, components 🔧 Dallas — Backend Dev Node.js, APIs, database 🧪 Lambert — Tester Tests, quality, edge cases 📋 Scribe — (silent) Memory, decisions, session logs - **Scribe** and **Ralph** are always on every roster — you don't manage them. - Look right? Say yes, add someone, or change a role. (Or just give me a task to start!) ``` --- - ## 3. Confirm and Give Your First Task - Say "yes" or skip straight to a task (which is implicit confirmation): - ``` > Yes. Dallas, set up the Express server with basic routing. ``` - Squad creates the `.squad/` directory structure — team roster, routing rules, casting state, ceremony config, agent charters, and histories — all seeded with your project context. Each agent spawns to do their work. - ### What's inside .squad/? | File/Directory | Purpose | @@ -104,30 +74,22 @@ Squad creates the `.squad/` directory structure — team roster, routing rules, | `templates/` | Format reference files for docs, PRDs, charters | **You own these files.** Edit them anytime — change roles, add routing rules, fix decisions. Squad reads them before every spawn. - **Commit `.squad/` to version control.** It's your team's brain. Anyone who clones the repo gets the team with all their knowledge. - Then it spawns Dallas: ``` 🔧 Dallas — setting up Express server with routing - Dallas is on it — building the Express server now. ``` --- - ## 4. Parallel Fan-Out — The Launch Table - Now give a bigger task to see parallel work: - ``` > Team, build the recipe listing page. We need an API endpoint > that returns recipes and a React component that displays them. ``` - Squad decomposes the work and launches agents simultaneously: - ``` 🏗️ Hicks — reviewing requirements, defining API contract ⚛️ Ripley — building RecipeList component @@ -135,28 +97,21 @@ Squad decomposes the work and launches agents simultaneously: 🧪 Lambert — writing test cases from requirements 📋 Scribe — logging session ``` - All five agents are working at the same time in separate context windows. The tester writes test cases from the requirements *while* the implementation is being built — no waiting. --- - ## 5. Results Labeled by Agent - When agents finish, you see results tagged with each agent's identity: - ``` 🏗️ Hicks — Defined API contract: GET /api/recipes returns { recipes: [{ id, title, ingredients, prepTime }] }. Decided on cursor-based pagination for large result sets. - ⚛️ Ripley — Built RecipeList component at src/components/RecipeList.tsx. Uses React Query for data fetching. Card layout with title, prep time, and ingredient count. - 🔧 Dallas — Created GET /api/recipes endpoint at src/routes/recipes.ts. Connected to MongoDB. Supports ?cursor= pagination per Hicks' spec. Also added GET /api/recipes/:id for detail view (proactive). - 🧪 Lambert — Wrote 8 test cases in test/recipes.test.ts: 📌 Proactive: Written from requirements while Dallas was building. May need adjustment once implementation is final. @@ -166,128 +121,94 @@ When agents finish, you see results tagged with each agent's identity: - Detail endpoint returns 404 for missing recipe [+4 more] ``` - Behind the scenes, the Scribe merged decisions from each agent into `decisions.md` and logged the session. --- - ## 6. Ask "Where Are We?" — Instant Status - At any point, check status: - ``` > Where are we? ``` - The coordinator reads recent logs: - ``` Last session: Recipe listing page (15 minutes ago) - Who worked: - Hicks defined the API contract (cursor pagination) - Ripley built RecipeList component - Dallas created recipes endpoint + detail endpoint - Lambert wrote 8 test cases - Key decisions: - Cursor-based pagination for recipe lists - React Query for frontend data fetching - MongoDB as database - 3 decisions in decisions.md, 4 agent history entries updated. ``` --- - ## 7. Follow-Up — Watch Decisions Accumulate - Give a follow-up task: - ``` > Now add a search feature. Users should be able to search > recipes by ingredient name. ``` - Squad fans out again: - ``` 🔧 Dallas — adding search endpoint with ingredient filtering ⚛️ Ripley — building search UI with ingredient input 🧪 Lambert — writing search test cases 📋 Scribe — logging session ``` - After completion, check decisions: - ``` > Show me the decisions ``` - ``` ### 2025-07-15: Cursor-based pagination for recipe lists **By:** Hicks **What:** All list endpoints use cursor-based pagination **Why:** Scales better than offset pagination for growing datasets - ### 2025-07-15: React Query for data fetching **By:** Ripley **What:** All API calls use React Query with stale-while-revalidate **Why:** Built-in caching, refetching, and loading states - ### 2025-07-15: Full-text search via MongoDB text index **By:** Dallas **What:** Search uses $text index on recipe title and ingredients array **Why:** Native MongoDB capability, no external search service needed ``` - -Every agent reads these decisions before working. As the list grows, the team self-aligns — agents respect each other's architectural choices without you repeating them. +Every agent reads these decisions before working. As the list grows, the team retains context so you don't need to restate architectural choices. --- - ## 8. Set a Directive - You notice something you want to standardize: - ``` > Always use Zod for API input validation ``` - Squad captures it — no agent spawn needed: - ``` 📌 Captured. All API input validation must use Zod. ``` - This gets written to `decisions.md`. Every agent will see it in their next spawn. --- - ## 9. Export Your Squad - After a productive session, export your team for portability: - ```bash squad export ``` - ``` ✅ Exported to squad-export.json 5 agents, 3 skills, 6 decisions ``` - This snapshot contains charters, histories, casting state, skills, and decisions. Import into another repo anytime: - ```bash cd ../other-project -squad +squad init squad import ../my-app/squad-export.json ``` --- - ## Tips - - **First session is slowest.** Agents have no history yet. After 2–3 sessions, they know your conventions. - **Commit `.squad/`** — your team's brain. Anyone who clones the repo gets the full team. - **Say "team" for big tasks.** The word "team" triggers parallel fan-out across multiple agents. @@ -295,9 +216,7 @@ squad import ../my-app/squad-export.json - **Directives are sticky.** Once captured, they persist across all future sessions. --- - ## What to Try Next - - [**Your Team**](../concepts/your-team.md) — How agents form, specialize, and collaborate - [**Memory & Knowledge**](../concepts/memory-and-knowledge.md) — Decisions, skills, and persistent context - [**Existing Repo Scenario**](../scenarios/existing-repo.md) — Bring Squad into a project that's already in flight diff --git a/docs/src/content/docs/get-started/five-minute-start.md b/docs/src/content/docs/get-started/five-minute-start.md index 29667ea95..17a82f966 100644 --- a/docs/src/content/docs/get-started/five-minute-start.md +++ b/docs/src/content/docs/get-started/five-minute-start.md @@ -1,87 +1,58 @@ -# Quick start - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - -Your first 5 minutes with Squad. Prove it works before you learn anything. - ---- - -## Prerequisites - -- **Node.js 20+** — Check with `node --version` -- **Git repository** — New or existing - ---- - -## Install - -```bash -npm install --save-dev @bradygaster/squad-cli -``` - -Then initialize: - -```bash -npx squad init -``` - -You'll see: - -``` -✅ Squad installed. - .github/agents/squad.agent.md — coordinator agent - .squad/templates/ — 11 template files - -Open GitHub Copilot and select Squad from the agent list. -``` - ---- - -## Validate - -Check that Squad created your team directory: - -```bash -ls .squad/ -``` - -You should see: `team.md`, `routing.md`, `decisions.md`, `agents/`, and more. - -Confirm Squad is ready: - -```bash -npx squad status -``` - ---- - -## Try it - -Open GitHub Copilot in your terminal or VS Code. Select **Squad** from the agent list (`/agent Squad` in CLI or `/agents` in VS Code). - -Say something simple: - -``` -> I'm building a task management app with React and Node.js. -> Users can create, update, and delete tasks. -``` - -Squad forms your team and responds with agent names and roles. Say yes, or just give your first task: - -``` -> Team, create a basic Express server with a /health endpoint. -``` - -Squad spawns agents and does the work. - ---- - -## What just happened? - -Squad read your description, formed a team of specialists, wrote their charters to `.squad/agents/`, and coordinated parallel work. Check `.squad/decisions.md` to see what they decided. - ---- - -## Next steps - -[**Your first session**](first-session) — Step-by-step walkthrough of parallel work, decisions, and memory. +# Quick start +Your first 5 minutes with Squad. Prove it works before you learn anything. + +--- +## Prerequisites +- **Node.js 20+** — Check with `node --version` +- **Git repository** — New or existing + +--- +## Install +```bash +npm install --save-dev @bradygaster/squad-cli +``` +Then initialize: +```bash +npx squad init +``` +You'll see: +``` +✅ Squad installed. + .github/agents/squad.agent.md — coordinator agent + .squad/templates/ — 11 template files +Open GitHub Copilot and select Squad from the agent list. +``` + +--- +## Validate +Check that Squad created your team directory: +```bash +ls .squad/ +``` +You should see: `team.md`, `routing.md`, `decisions.md`, `agents/`, and more. +Confirm Squad is ready: +```bash +npx squad status +``` + +--- +## Try it +Open GitHub Copilot in your terminal or VS Code. Select **Squad** from the agent list (`/agent Squad` in CLI or `/agents` in VS Code). +Say something simple: +``` +> I'm building a task management app with React and Node.js. +> Users can create, update, and delete tasks. +``` +Squad forms your team and responds with agent names and roles. Say yes, or just give your first task: +``` +> Team, create a basic Express server with a /health endpoint. +``` +Squad spawns agents and moves the work forward. + +--- +## What just happened? +Squad read your description, formed a team of specialists, wrote their charters to `.squad/agents/`, and coordinated parallel work. Check `.squad/decisions.md` to see what they decided. + +--- +## Next steps +[**Your first session**](first-session) — Step-by-step walkthrough of parallel work, decisions, and memory. diff --git a/docs/src/content/docs/get-started/installation.md b/docs/src/content/docs/get-started/installation.md index d6496bb06..9442932c9 100644 --- a/docs/src/content/docs/get-started/installation.md +++ b/docs/src/content/docs/get-started/installation.md @@ -1,66 +1,44 @@ # Installation - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - - Three ways to get Squad running. Pick the one that fits. --- - ## Try this: - ```bash npm install -g @bradygaster/squad-cli -squad +squad --version ``` - That's it. You're in. --- - ## 1. CLI (Recommended) - The CLI is the fastest way to use Squad from any terminal. - ### Global install - ```bash npm install -g @bradygaster/squad-cli ``` - Now use it anywhere: - ```bash squad init squad status squad watch ``` - ### One-off with npx - No install needed — run the latest version directly: - ```bash npx @bradygaster/squad-cli init npx @bradygaster/squad-cli status ``` - ### Verify - ```bash squad --version ``` - ### Update - ```bash npm install -g @bradygaster/squad-cli@latest ``` --- - ## Which method should I use? - Pick based on what you're doing: | **You want to...** | **Use** | **Why** | @@ -73,76 +51,38 @@ Pick based on what you're doing: Can't decide? → Start with **CLI**. You can always add VS Code or the SDK later. Your `.squad/` directory works identically everywhere. --- - ## 2. VS Code - Squad works in VS Code through GitHub Copilot. Your `.squad/` directory works identically in both CLI and VS Code — same agents, same decisions, same memory. - > **Tip:** Initialize your team with the CLI (`squad`), then open the project in VS Code to keep working with the same squad. --- - ## 3. SDK - Building your own tooling on top of Squad? Install the SDK as a project dependency: - ```bash npm install @bradygaster/squad-sdk ``` - Then import what you need: - ```typescript import { defineConfig, loadConfig, resolveSquad } from '@bradygaster/squad-sdk'; ``` - The SDK gives you typed configuration, routing, model selection, and the full agent lifecycle API. See the [SDK Reference](../reference/sdk.md) for details. --- - -### Personal squad (cross-project) - -Want the same agents across all your projects? - -```bash -squad init --global -``` - -This creates your personal squad directory — a personal team root that any project can inherit from. See [Upstream Inheritance](../features/upstream-inheritance.md) for details. - -**Personal squad location by platform:** - -| Platform | Path | -|----------|------| -| Linux | `~/.config/squad/` | -| macOS | `~/Library/Application Support/squad/` | -| Windows | `%APPDATA%\squad\` | - ---- - ## First-Time Setup - After installing, initialize Squad in your project: - ```bash cd your-project squad init ``` - This creates: - ``` .github/agents/squad.agent.md — coordinator agent .squad/ — team state directory ``` - ### Configuration (optional) - For typed configuration, create a `squad.config.ts` at your project root: - ```typescript import { defineConfig } from '@bradygaster/squad-sdk'; - export default defineConfig({ team: { name: 'my-squad', @@ -151,107 +91,32 @@ export default defineConfig({ }, }); ``` - `defineConfig()` gives you full autocomplete and validation. But you don't need it to get started — Squad works out of the box with sensible defaults. --- - ## Troubleshooting - ### `squad: command not found` - -Your npm global bin directory isn't in your PATH. Follow these steps: - -**1. Confirm the package is installed:** - +Your npm global bin isn't in your PATH. Fix: ```bash +# Check if installed npm list -g @bradygaster/squad-cli +# If installed but not found, check PATH: +echo $PATH | grep npm # macOS/Linux +echo %PATH% | findstr npm # Windows ``` - -If it's not listed, re-run `npm install -g @bradygaster/squad-cli`. - -**2. Find your npm global bin directory:** - -```bash -npm prefix -g -``` - -This prints the directory where npm installs global packages (e.g. `/usr/local`, `~/.npm-global`, or `C:\Users\\AppData\Roaming\npm`). The `squad` binary lives in the `bin/` subdirectory on macOS/Linux, or directly in that directory on Windows. - -**3. Add it to your PATH:** - -
-macOS / Linux - -Add this line to your shell profile (`~/.bashrc`, `~/.zshrc`, or `~/.profile`): - -```bash -export PATH="$(npm prefix -g)/bin:$PATH" -``` - -Then reload your shell using the command for the shell you use: - -```bash -# Bash -source ~/.bashrc -``` - -```bash -# Zsh -source ~/.zshrc -``` - -
- -
-Windows (PowerShell) - -Run this in PowerShell to permanently add the npm global directory to your user PATH. It reads only the **User**-scoped PATH (not the merged process PATH) and skips the append if the entry is already present, so repeated runs won't duplicate entries or copy Machine-level paths into your User PATH: - -```powershell -$npmPrefix = (npm prefix -g).Trim() -$userPath = [Environment]::GetEnvironmentVariable("PATH", "User") -if (-not (($userPath -split ';') -contains $npmPrefix)) { - $newUserPath = if ([string]::IsNullOrEmpty($userPath)) { $npmPrefix } else { $userPath.TrimEnd(';') + ";" + $npmPrefix } - [Environment]::SetEnvironmentVariable("PATH", $newUserPath, "User") -} -``` - -Then **restart your terminal** for the change to take effect. - -
- -:::note -If you use a Node version manager like [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm), `npm prefix -g` points to a version-specific directory that changes when you switch Node versions. Rather than hardcoding it in your PATH, let the version manager manage your PATH (it adds the active version's bin directory automatically), and make sure its shell initialization runs in your profile. -::: - -**4. Verify it works:** - -```bash -squad --version -``` - ### `Cannot find .squad/ directory` - -Run `squad init` in your project root, or `squad init --global` for a personal squad. - +Run `squad init` in your project root to create your Squad files. ### Version mismatch between CLI and SDK - Update both: - ```bash npm install -g @bradygaster/squad-cli@latest npm install @bradygaster/squad-sdk@latest ``` --- - ## Ready to Learn? - New to Squad? Check out [**Tamir's Squad Skills Workshop**](https://github.com/tamirdresher/squad-skills/tree/main/workshop) for hands-on learning and practical patterns. --- - ## Next Steps - → [Your First Session](first-session.md) diff --git a/docs/src/navigation.ts b/docs/src/navigation.ts index 986799bc9..792a779cf 100644 --- a/docs/src/navigation.ts +++ b/docs/src/navigation.ts @@ -88,6 +88,7 @@ export const NAV_SECTIONS: NavSection[] = [ title: 'Guides', dir: 'guide', items: [ + { title: 'Choose Your Interface', slug: 'get-started/choose-your-interface' }, { title: 'Tips & Tricks', slug: 'guide/tips-and-tricks' }, { title: 'Sample Prompts', slug: 'guide/sample-prompts' }, { title: 'Recipes', slug: 'cookbook/recipes' },