From 01093e04bb47405d1e9f2f00ac8214e238c3605f Mon Sep 17 00:00:00 2001 From: Dina Berry Date: Mon, 9 Mar 2026 07:06:11 -0700 Subject: [PATCH] docs: comprehensive new-user experience improvements Add 4 new docs pages and update 3 existing: - New: five-minute-start.md (5-minute quickstart) - New: architecture.md (how Squad works) - New: choosing-your-path.md (CLI vs SDK vs Copilot) - New: glossary.md (key terms reference) - Update: troubleshooting.md (common errors table) - Update: first-session.md (jargon definitions) - Update: navigation.ts (sidebar entries) Closes #301 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../src/content/docs/concepts/architecture.md | 70 +++++++++++++++ .../docs/get-started/choosing-your-path.md | 82 +++++++++++++++++ .../content/docs/get-started/first-session.md | 16 ++-- .../docs/get-started/five-minute-start.md | 87 +++++++++++++++++++ docs/src/content/docs/reference/glossary.md | 39 +++++++++ .../content/docs/scenarios/troubleshooting.md | 12 +++ docs/src/navigation.ts | 4 + test/docs-build.test.ts | 9 +- 8 files changed, 309 insertions(+), 10 deletions(-) create mode 100644 docs/src/content/docs/concepts/architecture.md create mode 100644 docs/src/content/docs/get-started/choosing-your-path.md create mode 100644 docs/src/content/docs/get-started/five-minute-start.md create mode 100644 docs/src/content/docs/reference/glossary.md diff --git a/docs/src/content/docs/concepts/architecture.md b/docs/src/content/docs/concepts/architecture.md new file mode 100644 index 000000000..991891e3b --- /dev/null +++ b/docs/src/content/docs/concepts/architecture.md @@ -0,0 +1,70 @@ +# Architecture + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +How Squad works — one page, no handwaving. + +--- + +## System diagram + +``` +User request + ↓ +Coordinator (routing engine) + ↓ +Spawns agents in parallel + ↓ +Agents read memory (.squad/) → work → write results + ↓ +Scribe merges decisions, Ralph tracks issues + ↓ +Results returned to user +``` + +--- + +## Components + +### Coordinator + +The coordinator is Squad's routing engine. It reads your request, checks routing rules in `.squad/routing.md`, and decides which agents to spawn. If you say "team," it decomposes the work and launches multiple agents in parallel. If you name an agent, it routes directly to them. + +### Agents + +Each agent is a specialist with a charter, role, and persistent memory. Agents are spawned as independent subprocesses with their own context windows and tools. They read `.squad/decisions.md` and their own history before working, then write results back. Agents never see each other's conversations — the coordinator orchestrates coordination. + +### Memory (.squad/) + +All team state lives in `.squad/`. This includes the roster (`team.md`), routing rules (`routing.md`), decisions (`decisions.md`), agent charters and histories (`agents/`), and ceremony schedules (`ceremonies.md`). Agents read this before every spawn. You own these files — edit them anytime. + +### Routing + +Routing rules in `.squad/routing.md` define which agent handles which work. The coordinator reads these rules before spawning. You can override routing by naming an agent directly in your request. + +### Scribe + +The Scribe is a silent agent that tracks decisions and logs sessions. Every team has a Scribe. You never talk to them directly — they work in the background, merging decisions from all agents into `.squad/decisions.md`. + +### Ralph + +Ralph is the work monitor. He watches your GitHub or GitLab issues, tracks work in progress, and alerts the team when something is ready. Every team has a Ralph. He's silent unless you ask him for status. + +--- + +## What happens when you say "Team, build X"? + +1. **Coordinator reads the request** and checks `.squad/routing.md` for decomposition rules. +2. **Coordinator spawns multiple agents in parallel** — one for frontend, one for backend, one for tests, etc. +3. **Each agent reads `.squad/decisions.md`** and their own history (`agents/{name}/history.md`), then works independently. +4. **Agents write results** to their history files and propose decisions. +5. **Scribe merges all decisions** into `.squad/decisions.md`. +6. **Coordinator returns labeled results** to you, tagged with each agent's name. + +--- + +## Learn more + +- [**Work routing**](../features/routing) — How the coordinator decides which agents to spawn +- [**Memory and knowledge**](memory-and-knowledge) — How decisions, skills, and history persist +- [**Parallel work**](parallel-work) — How agents work simultaneously without conflicts diff --git a/docs/src/content/docs/get-started/choosing-your-path.md b/docs/src/content/docs/get-started/choosing-your-path.md new file mode 100644 index 000000000..16eacec5e --- /dev/null +++ b/docs/src/content/docs/get-started/choosing-your-path.md @@ -0,0 +1,82 @@ +# 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 030e70479..6c62bbebc 100644 --- a/docs/src/content/docs/get-started/first-session.md +++ b/docs/src/content/docs/get-started/first-session.md @@ -48,7 +48,7 @@ Start the Copilot CLI: copilot ``` -Select **Squad** from the `/agent` list (CLI) or `/agents` (VS Code). Squad greets you by name (pulled from `git config user.name`): +Select **Squad** from the `/agent` list (CLI) or `/agents` (VS Code). Squad greets you by name: ``` Hey Brady, what are you building? @@ -61,7 +61,7 @@ Describe your project: > post recipes, search by ingredient, and save favorites. ``` -Squad proposes a team. Names come from a fictional universe — the exact universe depends on your project shape and history: +Squad proposes a team. The coordinator analyzes your description and suggests specialists: ``` Here's your team: @@ -72,6 +72,8 @@ Here's your team: 🧪 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!) ``` @@ -86,7 +88,7 @@ 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. +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/? @@ -177,7 +179,7 @@ At any point, check status: > Where are we? ``` -This is a Direct mode response — no agent spawn, just the coordinator reading recent logs: +The coordinator reads recent logs: ``` Last session: Recipe listing page (15 minutes ago) @@ -274,7 +276,7 @@ squad export 5 agents, 3 skills, 6 decisions ``` -This snapshot contains everything — charters, histories, casting state, skills, and decisions. Import into another repo anytime: +This snapshot contains charters, histories, casting state, skills, and decisions. Import into another repo anytime: ```bash cd ../other-project @@ -286,8 +288,8 @@ squad import ../my-app/squad-export.json ## Tips -- **First session is the slowest.** Agents have no history yet. After 2–3 sessions, they know your conventions and stop asking repeated questions. -- **Commit `.squad/`.** It's your team's brain. Anyone who clones the repo gets the team with all their knowledge. +- **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. - **Name an agent for focused work.** `"Dallas, fix the login bug"` sends work to one specific agent. - **Directives are sticky.** Once captured, they persist across all future sessions. diff --git a/docs/src/content/docs/get-started/five-minute-start.md b/docs/src/content/docs/get-started/five-minute-start.md new file mode 100644 index 000000000..29667ea95 --- /dev/null +++ b/docs/src/content/docs/get-started/five-minute-start.md @@ -0,0 +1,87 @@ +# 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. diff --git a/docs/src/content/docs/reference/glossary.md b/docs/src/content/docs/reference/glossary.md new file mode 100644 index 000000000..7a5ef32f9 --- /dev/null +++ b/docs/src/content/docs/reference/glossary.md @@ -0,0 +1,39 @@ +# Glossary + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +Key terms defined in one sentence each. Alphabetical order. + +--- + +**Agent** — A specialist AI team member with a role, charter, and persistent memory that handles specific types of work. + +**Casting** — The process of forming your team by proposing agents, confirming roles, and writing their charters to `.squad/`. + +**Ceremony** — A scheduled team event like retrospectives, reviews, or planning sessions defined in `.squad/ceremonies.md`. + +**Coordinator** — Squad's routing engine that reads your request, checks routing rules, and spawns the right agents. + +**Decisions** — Architectural choices, conventions, and directives captured in `.squad/decisions.md` that all agents read before working. + +**Directive** — A persistent rule or convention you give the team (like "Always use Zod for validation") that gets written to `decisions.md`. + +**History** — Each agent's memory of past work, stored in `.squad/agents/{name}/history.md` and read before every spawn. + +**Memory** — All persistent team state stored in the `.squad/` directory, including roster, routing rules, decisions, and agent histories. + +**Ralph** — The silent work monitor agent that watches your GitHub or GitLab issues and tracks work in progress. + +**Routing** — Rules in `.squad/routing.md` that define which agent handles which type of work, read by the coordinator before spawning. + +**Scribe** — The silent agent that tracks decisions and logs sessions, merging proposals from all agents into `.squad/decisions.md`. + +**Skill** — A reusable capability stored in `.squad/skills/` that agents can learn and execute. + +**Spawn** — The act of starting an agent as an independent subprocess with its own context window, tools, and memory. + +**Squad** — Your AI development team, coordinated through the Squad framework. + +**.squad/ directory** — The root directory containing all team state: roster, routing, decisions, agent charters and histories, and ceremony config. + +**Team** — The collection of agents working on your project, defined in `.squad/team.md`. diff --git a/docs/src/content/docs/scenarios/troubleshooting.md b/docs/src/content/docs/scenarios/troubleshooting.md index 921dc617f..913e4c3c2 100644 --- a/docs/src/content/docs/scenarios/troubleshooting.md +++ b/docs/src/content/docs/scenarios/troubleshooting.md @@ -4,6 +4,18 @@ Common issues and fixes for Squad installation and usage. --- +## Quick fixes + +| Error | Cause | Fix | +|-------|-------|-----| +| `squad: command not found` | Squad CLI not installed or not in PATH | Run `npm install -g @bradygaster/squad-cli` or use `npx @bradygaster/squad-cli` | +| `No .squad/ directory found` | Not in a git repo or Squad not initialized | Run `git init` then `npx squad init` | +| `Cannot find agent "{name}"` | Agent doesn't exist in `.squad/agents/` | Check `.squad/team.md` for roster, or re-run casting | +| `gh: command not found` | GitHub CLI not installed | Install from [cli.github.com](https://cli.github.com/) then `gh auth login` | +| `Node.js version error` | Node.js version below v20 | Upgrade Node.js to v20+ (see below) | + +--- + ## `npx github:bradygaster/squad` appears to hang **Problem:** Running the install command shows a frozen npm spinner. Nothing happens. diff --git a/docs/src/navigation.ts b/docs/src/navigation.ts index 56d5a88dd..5e975ec0b 100644 --- a/docs/src/navigation.ts +++ b/docs/src/navigation.ts @@ -14,7 +14,9 @@ export const NAV_SECTIONS: NavSection[] = [ title: 'Get Started', dir: 'get-started', items: [ + { title: 'Quick start', slug: 'get-started/five-minute-start' }, { title: 'Installation', slug: 'get-started/installation' }, + { title: 'Choose your path', slug: 'get-started/choosing-your-path' }, { title: 'Your First Session', slug: 'get-started/first-session' }, { title: 'Migration Guide', slug: 'get-started/migration' }, ], @@ -78,6 +80,7 @@ export const NAV_SECTIONS: NavSection[] = [ { title: 'SDK Integration', slug: 'reference/integration' }, { title: 'Tools & Hooks', slug: 'reference/tools-and-hooks' }, { title: 'Config', slug: 'reference/config' }, + { title: 'Glossary', slug: 'reference/glossary' }, ], }, { @@ -115,6 +118,7 @@ export const NAV_SECTIONS: NavSection[] = [ title: 'Concepts', dir: 'concepts', items: [ + { title: 'Architecture', slug: 'concepts/architecture' }, { title: 'Your Team', slug: 'concepts/your-team' }, { title: 'Memory & Knowledge', slug: 'concepts/memory-and-knowledge' }, { title: 'Parallel Work', slug: 'concepts/parallel-work' }, diff --git a/test/docs-build.test.ts b/test/docs-build.test.ts index 5a14ce65f..a1982bdd8 100644 --- a/test/docs-build.test.ts +++ b/test/docs-build.test.ts @@ -15,16 +15,18 @@ 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 = ['installation', 'first-session', 'five-minute-start', 'choosing-your-path', 'migration']; const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell']; -const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks']; +const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks', 'glossary']; const EXPECTED_SCENARIOS = [ 'issue-driven-dev', 'existing-repo', 'ci-cd-integration', 'solo-dev', 'monorepo', 'team-of-humans', ]; +const EXPECTED_CONCEPTS = ['architecture', 'your-team', 'memory-and-knowledge', 'parallel-work', 'github-workflow', 'portability']; + // Blog posts are discovered dynamically to avoid breaking tests when posts change const EXPECTED_BLOG = existsSync(BLOG_CONTENT_DIR) ? readdirSync(BLOG_CONTENT_DIR) @@ -43,7 +45,7 @@ function getMarkdownFiles(section: string): string[] { } function getAllMarkdownFiles(): string[] { - const sections = ['get-started', 'guide', 'reference', 'scenarios']; + const sections = ['get-started', 'guide', 'reference', 'scenarios', 'concepts']; const allFiles: string[] = []; for (const section of sections) { allFiles.push(...getMarkdownFiles(section)); @@ -169,6 +171,7 @@ describe('Docs Build Script (Astro)', () => { ...EXPECTED_GUIDES.map(n => ({ dir: 'guide', name: n })), ...EXPECTED_REFERENCE.map(n => ({ dir: 'reference', name: n })), ...EXPECTED_SCENARIOS.map(n => ({ dir: 'scenarios', name: n })), + ...EXPECTED_CONCEPTS.map(n => ({ dir: 'concepts', name: n })), ]; for (const { dir, name } of allExpected) { const htmlPath = join(DIST_DIR, 'docs', dir, name, 'index.html');