diff --git a/docs/src/content/docs/features/directives.md b/docs/src/content/docs/features/directives.md index 6097ab3ca..c79a67f09 100644 --- a/docs/src/content/docs/features/directives.md +++ b/docs/src/content/docs/features/directives.md @@ -26,8 +26,6 @@ Directives are team rules that persist across sessions. When you say "always" or A directive is a preference, rule, or constraint the team remembers across sessions. When you say "always do X" or "never do Y", Squad captures it as a directive, writes it to the decisions inbox, and the Scribe merges it into `.squad/decisions.md` — the team's permanent memory. -## How Directives Work - 1. **Signal Word Detection** — The coordinator listens for: "always", "never", "from now on", "remember to", "don't", "make sure to". 2. **Capture** — Directive is written to `.squad/decisions/inbox/{timestamp}-{brief-slug}.md`. 3. **Scribe Merge** — Scribe consolidates inbox files into `decisions.md` during the next coordination cycle. diff --git a/docs/src/content/docs/features/gitlab-issues.md b/docs/src/content/docs/features/gitlab-issues.md index b982327e9..cec713dd3 100644 --- a/docs/src/content/docs/features/gitlab-issues.md +++ b/docs/src/content/docs/features/gitlab-issues.md @@ -162,7 +162,7 @@ For the full command reference, see the [official GitLab CLI documentation](http - You don't need to assign issues to specific agents — Squad routes based on domain expertise. - If `glab` isn't authenticated, Squad will tell you. Run `glab auth login` first. - MR descriptions include `Closes #N` so merging automatically closes the linked issue, just like on GitHub. -- See [GitLab Issues Walkthrough](../tour-gitlab-issues.md) for a step-by-step tour. +- See the [GitLab Issues feature page](./gitlab-issues.md) for the full reference. ## Sample Prompts diff --git a/docs/src/content/docs/features/notifications.md b/docs/src/content/docs/features/notifications.md index f07fd20f5..728a9c1b6 100644 --- a/docs/src/content/docs/features/notifications.md +++ b/docs/src/content/docs/features/notifications.md @@ -19,12 +19,6 @@ Your squad sends you instant messages when they need input, hit an error, or com ## How It Works -Your squad can send you instant messages when they need your input. Leave your terminal, get pinged on your phone. - ---- - -## How It Works - Squad ships zero notification infrastructure. Instead, it uses **skills** — reusable knowledge files — to teach agents when and how to ping you. You bring your own notification delivery by configuring an MCP notification server in your Copilot environment. The flow: diff --git a/docs/src/content/docs/features/parallel-execution.md b/docs/src/content/docs/features/parallel-execution.md index 4cb0d3c71..846b842af 100644 --- a/docs/src/content/docs/features/parallel-execution.md +++ b/docs/src/content/docs/features/parallel-execution.md @@ -26,8 +26,6 @@ Squad launches independent work in parallel by default — multiple agents work Squad runs agents in parallel whenever possible. The fan-out pattern launches all independent agents simultaneously, waits for results, then proceeds — no sequential bottlenecks unless data dependencies or reviewer gates require them. -## How Parallel Execution Works - When the coordinator receives work: 1. **Dependency Analysis** — Check if tasks have data dependencies (A needs output from B). diff --git a/docs/src/content/docs/features/plugins.md b/docs/src/content/docs/features/plugins.md index 2160b1195..889e5d094 100644 --- a/docs/src/content/docs/features/plugins.md +++ b/docs/src/content/docs/features/plugins.md @@ -19,12 +19,6 @@ Plugins are community-curated bundles of agent templates, skills, and best pract ## What Are Plugins? -Your Squad can discover and install **plugins** — curated collections of agent templates, skills, and instructions from community repositories. Plugins solve recurring problems: Azure cloud development, React patterns, security hardening, testing strategies, and more. - ---- - -## What Are Plugins? - Plugins are **community-curated bundles** of reusable knowledge. Each plugin contains: - **Agent templates** — specialized role charters for common needs (e.g., "AWS DevOps", "Python Data Science") diff --git a/docs/src/content/docs/features/prd-mode.md b/docs/src/content/docs/features/prd-mode.md index 42417d95b..d4f912b71 100644 --- a/docs/src/content/docs/features/prd-mode.md +++ b/docs/src/content/docs/features/prd-mode.md @@ -19,12 +19,6 @@ Give Squad a product requirements document and the Lead breaks it into prioritiz ## How to Use -Give Squad a product requirements document. The Lead agent breaks it into work items, assigns them to the team, and tracks progress. - ---- - -## How to Use - Paste a PRD directly into the chat: ``` diff --git a/docs/src/content/docs/features/routing.md b/docs/src/content/docs/features/routing.md index 352862650..a48c69602 100644 --- a/docs/src/content/docs/features/routing.md +++ b/docs/src/content/docs/features/routing.md @@ -26,8 +26,6 @@ The coordinator routes work to the right agent using named routing (explicit), d The coordinator decides who handles each piece of work using a three-layer routing system: named routing (explicit assignments), domain routing (pattern matching), and skill-aware routing (capability checking). The goal: get work to the right agent without manual triage overhead. -## Routing Strategies - ### 1. Named Routing You explicitly name who should do the work: @@ -76,7 +74,7 @@ Work tagged with authentication routes to Backend or Lead based on task type (im Default assignments for common patterns. -## Routing Table +## Routes | Pattern | Owner | Reason | |---------|-------|--------| diff --git a/docs/src/content/docs/features/streams.md b/docs/src/content/docs/features/streams.md index 0b2cf6b46..bc6bd219f 100644 --- a/docs/src/content/docs/features/streams.md +++ b/docs/src/content/docs/features/streams.md @@ -1,4 +1,4 @@ -# Squad SubSquads +# Streams > Scale Squad across multiple Codespaces by partitioning work into labeled SubSquads. diff --git a/docs/src/content/docs/features/team-setup.md b/docs/src/content/docs/features/team-setup.md index eb1ec7fe3..f71c50ca2 100644 --- a/docs/src/content/docs/features/team-setup.md +++ b/docs/src/content/docs/features/team-setup.md @@ -30,8 +30,6 @@ When you first run Squad in a repository, it doesn't impose a team — it propos By default, Squad uses the **CastingEngine** to assign agent names from fictional universes (The Usual Suspects, Ocean's Eleven, etc.). The LLM proposes roles and team composition; the engine allocates curated character names, personalities, and backstories from the selected universe. Use `squad init --roles` to opt into the base role catalog (Lead, Backend, Frontend, Tester) instead of universe casting. -## How Init Works - 1. **Discovery** — Squad scans your repository: language distribution, file structure, test frameworks, dependencies, existing workflows. 2. **Proposal** — Based on what it finds, Squad proposes a team roster with 3-7 members and their roles. 3. **Confirmation** — You review the proposal and can accept as-is, add members, remove members, or change roles. diff --git a/docs/src/content/docs/features/worktrees.md b/docs/src/content/docs/features/worktrees.md index 2d67cb8bc..30f0c3d82 100644 --- a/docs/src/content/docs/features/worktrees.md +++ b/docs/src/content/docs/features/worktrees.md @@ -19,8 +19,6 @@ Squad supports git worktrees with two strategies: **worktree-local** (each workt ## What Are Worktrees? -## What Are Worktrees? - Git worktrees let you check out multiple branches simultaneously: ```bash diff --git a/docs/src/content/docs/guide.md b/docs/src/content/docs/guide.md deleted file mode 100644 index b694cff21..000000000 --- a/docs/src/content/docs/guide.md +++ /dev/null @@ -1,564 +0,0 @@ -# Squad — Product Guide - -## What is Squad? - -Squad gives you an AI development team through GitHub Copilot. You describe what you're building. Squad proposes a team of specialists — lead, frontend, backend, tester — that live in your repo as files. Each agent runs in its own context window, reads its own knowledge, and writes back what it learned. They persist across sessions, share decisions, and get better the more you use them. - -It is not a chatbot wearing hats. Each team member is spawned as a real sub-agent with its own tools, its own memory, and its own area of expertise. - ---- - -## Which CLI should I use? - -**Use GitHub Copilot CLI for day-to-day work.** It's the recommended interface for interacting with your Squad — full agent spawning, model selection, and conversational access to all features. - -**Use Squad CLI for setup and operations:** -- Initial setup: `squad init` -- Build from config: `squad build` -- Diagnostics: `squad doctor` -- Interactive shell: `squad shell` -- Continuous triage: `squad triage --interval 10` -- Watch mode: `squad watch` -- Aspire dashboard: `squad aspire` -- Export/import: `squad export` and `squad import` -- Plugin management: `squad plugin install ` - -**Common workflow:** -```bash -# Terminal 1: Run continuous triage (Squad CLI) -squad triage --interval 10 - -# Terminal 2: Work with your team (GitHub Copilot CLI) -gh copilot -> @squad what issues are ready to work? -``` - -Both CLIs read and write the same `.squad/` directory, so state stays synchronized. For more details, see [FAQ: Which CLI should I use?](guide/faq.md#which-cli-should-i-use) and [Client Compatibility Matrix](scenarios/client-compatibility.md). - ---- - -## Supported platforms - -Squad works across multiple interfaces — GitHub Copilot CLI, VS Code, Squad CLI, SDK, and the Copilot Coding Agent. Pick the one that fits your workflow: - -- **GitHub Copilot CLI** — Day-to-day conversational work with your squad (recommended) -- **VS Code** — Same experience, editor-integrated -- **Squad CLI** — Setup, diagnostics, monitoring (`squad init`, `squad doctor`, `squad watch`) -- **SDK** — Build tools on top of Squad with `squad.config.ts` -- **Copilot Coding Agent** — Autonomous issue processing via `@copilot` - -**Multi-platform support:** Squad also works with Azure DevOps (work items, PRs via `az boards`/`az repos`), GitLab Issues, and Microsoft Planner through pluggable platform adapters. See [Enterprise Platforms](features/enterprise-platforms.md) for details. - -Not sure which to use? See [Choose your interface](get-started/choose-your-interface.md) for a complete comparison and decision tree. - ---- - -## Installation - -```bash -npm install -g @bradygaster/squad-cli -``` - -**Requirements:** -- Node.js 20+ (LTS) -- GitHub Copilot (CLI, VS Code, Visual Studio, or Coding Agent) -- A git repository (Squad stores team state in `.squad/`) -- **`gh` CLI** — required for GitHub Issues, PRs, Ralph, and Project Boards ([install](https://cli.github.com/)) - -Running `squad init` creates the `.squad/` directory structure, copies `squad.agent.md` into `.github/agents/`, and installs GitHub Actions workflows into `.github/workflows/`. Your team is created at runtime when you first talk to Squad. - -**Note:** When you select Squad from the agent picker, you'll see the version number in the name (e.g., "Squad (v0.8.25)"). This helps you confirm which version is installed. - -### GitHub CLI authentication - -Squad uses the `gh` CLI for all GitHub API operations — issues, PRs, labels, project boards, and Ralph's work monitoring. You must authenticate before using any of these features. - -**Quick start:** - -```bash -gh auth login -``` - -Choose **GitHub.com**, **HTTPS**, and authenticate with your browser or a Personal Access Token (PAT Classic). - -**Verify it worked:** - -```bash -gh auth status -``` - -**Additional scopes** — some features require scopes beyond the default: - -| Feature | Required scope | Command | -|---------|---------------|---------| -| Issues, PRs, Ralph | `repo` (included by default) | — | -| Project Boards | `project` | `gh auth refresh -s project` | - -The `gh auth refresh` command adds scopes to your existing token — it takes about 10 seconds and you only need to do it once. - -**Troubleshooting:** - -- **"gh: command not found"** — Install the GitHub CLI from https://cli.github.com/ -- **"HTTP 401" or "authentication required"** — Run `gh auth login` to re-authenticate -- **Project board commands fail** — Run `gh auth refresh -s project` to add the `project` scope -- **"Resource not accessible by integration"** — Your token may lack the `repo` scope. Re-authenticate with a PAT Classic that has `repo` and `project` scopes - ---- - -## How teams form (init mode) - -When you open Copilot and select **Squad** for the first time in a repo, there's no team yet. Squad enters Init Mode: - -1. **Squad identifies you** via `git config user.name` and uses your name in conversation. -2. **You describe your project** — language, stack, what it does. -3. **Squad casts a team** — agents get names from a single fictional universe (e.g., Apollo 13 / NASA Mission Control, The Usual Suspects, Ocean's Eleven). The universe is selected deterministically based on team size, project shape, and what's been used before. Names are persistent identifiers — they don't change the agent's behavior or voice. -4. **Squad proposes the team:** - -``` -🏗️ FLIGHT — Lead Scope, decisions, code review -⚛️ RETRO — Frontend Dev React, UI, components -🔧 GNC — Backend Dev APIs, database, services -🧪 TELMU — Tester Tests, quality, edge cases -📋 Scribe — (silent) Memory, decisions, session logs -``` - -5. **You confirm** — say "yes", adjust roles, add someone, or just give a task (which counts as implicit yes). - -Squad then creates the `.squad/` directory structure with charters, histories, routing rules, casting state, and ceremony config. Each agent's `history.md` is seeded with your project description and tech stack so they have day-1 context. - -### What gets created - -``` -.squad/ -├── team.md # Roster — who's on the team -├── routing.md # Who handles what -├── ceremonies.md # Team meeting definitions -├── decisions.md # Shared brain — team decisions -├── decisions/inbox/ # Drop-box for parallel decision writes -├── casting/ -│ ├── policy.json # Universe allowlist and capacity -│ ├── registry.json # Persistent agent name registry -│ └── history.json # Universe usage history -├── agents/ -│ ├── {name}/ -│ │ ├── charter.md # Identity, expertise, boundaries -│ │ └── history.md # What they know about YOUR project -│ └── scribe/ -│ └── charter.md # Silent memory manager -├── skills/ # Shared skill files (SKILL.md) -├── orchestration-log/ # Per-spawn log entries -└── log/ # Session history -``` - -**Commit this folder.** Anyone who clones your repo gets the team — with all their accumulated knowledge. - ---- - -## Talking to your team (routing) - -How you phrase your message determines who works on it. - -### Name an agent directly - -``` -> FLIGHT, fix the error handling in the API -``` - -Squad spawns FLIGHT specifically. - -### Say "team" for parallel fan-out - -``` -> Team, build the login page -``` - -Squad spawns multiple agents simultaneously — frontend builds the UI, backend sets up endpoints, tester writes test cases from the spec, all at once. - -### General requests - -``` -> Add input validation to the form -``` - -Squad checks `routing.md`, picks the best match, and may launch anticipatory agents (e.g., tester writes validation test cases while the implementer builds). - -### Quick questions — no spawn - -``` -> What port does the server run on? -``` - -Squad answers directly without spawning an agent. - -### Example prompts to try - -| You say | What happens | -|---------|-------------| -| `"RETRO, set up the project structure"` | RETRO (Frontend) scaffolds the project | -| `"Team, build the user dashboard"` | Multiple agents launch in parallel | -| `"Where are we?"` | Squad gives a quick status from recent logs | -| `"Run a retro"` | Lead facilitates a retrospective ceremony | -| `"I need a DevOps person"` | A new agent joins, named from the same universe | -| `"Always use single quotes in TypeScript"` | Captured as a directive to `decisions.md` | - ---- - -## Response modes - -Squad automatically picks the right response speed based on your request complexity. Direct answers take seconds, full agent spawns take longer but deliver deeper reasoning and parallel work. You don't control the mode — Squad routes based on what the task needs. - -→ [Full guide: Response Modes](features/response-modes.md) - ---- - -## SDK-first mode - -Define your team in TypeScript instead of maintaining markdown files manually. Write a `squad.config.ts` with type-safe builder functions, and `squad build` generates the `.squad/` governance markdown. - -```typescript -import { defineSquad, defineTeam, defineAgent, defineRouting } from '@bradygaster/squad-sdk'; - -export default defineSquad({ - team: defineTeam({ - name: 'Core Squad', - description: 'The main engineering team', - members: ['@edie', '@mcmanus'], - }), - agents: [ - defineAgent({ - name: 'edie', - role: 'TypeScript Engineer', - model: 'claude-sonnet-4', - capabilities: [{ name: 'type-system', level: 'expert' }], - }), - ], - routing: defineRouting({ - rules: [{ pattern: 'feature-*', agents: ['@edie'], tier: 'standard' }], - defaultAgent: '@coordinator', - }), -}); -``` - -**Get started:** - -```bash -squad init --sdk # New project with SDK config -squad migrate --to sdk # Convert existing .squad/ to TypeScript -squad build # Generate .squad/ from config -squad build --check # Validate in CI without writing -``` - -Builder functions: `defineTeam()`, `defineAgent()`, `defineRouting()`, `defineCeremony()`, `defineHooks()`, `defineCasting()`, `defineTelemetry()`, `defineSkill()`, `defineSquad()`. - -→ [Full guide: SDK-First Mode](sdk-first-mode.md) - ---- - -## Casting system - -Squad names agents from fictional universes — Apollo 13 / NASA Mission Control (the default), The Usual Suspects, Breaking Bad, Star Trek, and others. The universe is selected deterministically based on team size and project shape. - -Casting is **persistent** — once an agent receives a name, it keeps that name across sessions. The casting registry lives in `.squad/casting/registry.json`. You control which universes are available through a policy allowlist and can set per-universe capacity limits. - -In SDK-first mode, configure casting with `defineCasting()`: - -```typescript -defineCasting({ - allowlistUniverses: ['Apollo 13', 'Breaking Bad'], - overflowStrategy: 'generic', - capacity: { 'Apollo 13': 8 }, -}); -``` - -When a universe runs out of names, the overflow strategy determines what happens: `reject` (error), `generic` (use a functional name), or `rotate` (move to the next universe). - ---- - -## Skills system - -Skills are reusable knowledge patterns that agents load on demand. They live in `.squad/skills/{name}/SKILL.md` and teach agents how to handle specific tasks — branching workflows, deployment strategies, testing patterns, or domain expertise. - -Skills have a confidence lifecycle: `low` → `medium` → `high`, and track their source: `manual` (you wrote it), `observed` (agent saw a pattern), `earned` (validated through use), or `extracted` (imported from another project). - -In SDK-first mode, define skills with `defineSkill()`: - -```typescript -defineSkill({ - name: 'git-workflow', - description: 'Squad branching model and PR conventions', - domain: 'workflow', - confidence: 'high', - source: 'manual', - content: ` - ## Patterns - - Branch from dev: squad/{issue-number}-{slug} - - PRs target dev, not main - `, -}); -``` - -Skills accumulate as you work. After a few sessions, your team has a knowledge base tailored to your codebase. - -→ [Full guide: Skills](features/skills.md) - ---- - -## Ceremonies - -Ceremonies are structured team meetings. Squad ships with two default ceremonies — Design Review (triggers before multi-agent work) and Retrospective (triggers after failures). You can trigger ceremonies manually, create custom ones, or disable them. Configuration lives in `.squad/ceremonies.md`. - -In SDK-first mode, define ceremonies with `defineCeremony()`: - -```typescript -defineCeremony({ - name: 'standup', - trigger: 'schedule', - schedule: '0 9 * * 1-5', - participants: ['@edie', '@mcmanus'], - agenda: 'Yesterday / Today / Blockers', -}); -``` - -→ [Full guide: Ceremonies](features/ceremonies.md#ceremonies) - ---- - -## Ralph — work monitor - -Ralph triages your issue backlog, assigns work to agents, and keeps the board moving. Activate Ralph when you have open issues, and he reports every 3–5 rounds. - -``` -> Ralph, start monitoring -``` - -**CLI commands:** -- `squad triage` — run a single triage pass -- `squad triage --interval 10` — continuous triage every 10 minutes -- `squad watch` — Ralph watchdog mode (monitors and auto-restarts) - -The `squad-heartbeat` workflow runs Ralph on a schedule — your squad triages issues between sessions. - -**Note:** `squad ralph` is a legacy alias. New projects should use `squad triage`. - -→ [Full guide: Ralph — Work Monitor](features/ralph.md#ralph--work-monitor) - ---- - -## Memory system - -Squad's memory is layered — personal agent histories, shared team decisions, and reusable skills. Knowledge compounds over sessions. After a few sessions, agents stop asking questions they've already answered. Mature projects carry full architecture knowledge and decision history. - -→ [Full guide: Memory System](features/memory.md) - ---- - -## Plugin marketplace - -Extend your squad with community plugins — reusable collections of skills, ceremonies, and directives. - -```bash -squad plugin install github/my-org/my-extension -squad plugin list -squad plugin remove my-extension -``` - -Plugins let you add domain expertise (Azure infrastructure patterns), workflow templates (client-delivery processes), or testing ceremonies without modifying Squad core. Build your own and share them. - -→ [Full guide: Plugins](features/plugins.md) | [Marketplace](features/marketplace.md) - ---- - -## SubSquads (streams) - -Break large teams into focused SubSquads — smaller groups that work independently on different features or domains. SubSquads maintain their own routing and task queues while sharing the parent squad's decisions and memory. - -```bash -squad subsquads -``` - -→ [Full guide: Streams](features/streams.md) - ---- - -## Export and import - -Export creates a portable snapshot of your entire team — agents, knowledge, skills. Import brings that snapshot into another repo. Squad handles collision detection and splits imported knowledge into portable learnings and project-specific context automatically. - -```bash -squad export --out my-team.json -squad import my-team.json -squad import my-team.json --force # Archive existing agents first -``` - -→ [Full guide: Export and Import](features/export-import.md#export--import) - ---- - -## GitHub Issues mode - -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. - -→ [Full guide: GitHub Issues Mode](features/github-issues.md#github-issues-mode) - ---- - -## PRD mode - -Paste your product requirements document directly into Squad. The Lead agent decomposes the spec into discrete work items, assigns them to the right agents, and the team works in parallel. Specs become trackable tasks automatically. - -→ [Full guide: PRD Mode](features/prd-mode.md#prd-mode) - ---- - -## Human team members - -Not every team member needs to be an AI agent. Add humans to the roster for decisions that require a real person — design sign-off, security review, product approval. Squad pauses when work is routed to a human and reminds you if they haven't responded. - -→ [Full guide: Human Team Members](features/human-team-members.md#human-team-members) - ---- - -## Notifications - -Your squad can notify you when they need input — send instant pings to Teams, Discord, iMessage, or any webhook. Agents trigger notifications when they're blocked, need a decision, hit an error, or complete important work. - -**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#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). - ---- - -## Multi-platform support - -Squad works with more than GitHub. Pluggable platform adapters let you use: - -- **GitHub** — Issues, PRs, Project Boards (via `gh` CLI) -- **Azure DevOps** — Work items, repos, PRs (via `az boards`/`az repos` CLI) -- **GitLab** — Issues and merge requests -- **Microsoft Planner** — Hybrid work-item tracking (via Microsoft Graph API) - -Configure cross-project ADO support in `.squad/config.json` — work items can live in a different org/project than the repo. - -→ [Full guide: Enterprise Platforms](features/enterprise-platforms.md) | [GitLab Issues](features/gitlab-issues.md) - ---- - -## Upgrading - -Already have Squad installed? Update to the latest version: - -```bash -npm install -g @bradygaster/squad-cli@latest -``` - -Run `squad doctor` to validate your setup after upgrading: - -```bash -squad doctor -``` - -Doctor runs 9 checks — Node.js version, `gh` CLI auth, `.squad/` directory structure, team state, and more. It reports issues with clear fix instructions. - -**Migrating from `.ai-team/` to `.squad/`:** - -```bash -squad migrate --from ai-team -``` - -This renames `.ai-team/` to `.squad/` and updates all internal references. - ---- - -## Context budget - -Each agent runs in its own context window. Real numbers: - -| What | Tokens | % of 200K window | -|------|--------|-------------------| -| Coordinator (squad.agent.md) | ~13,200 | 6.6% | -| Agent at Week 1 (charter + seed history + decisions) | ~1,250 | 0.6% | -| Agent at Week 4 (+ 15 learnings, 8 decisions) | ~3,300 | 1.7% | -| Agent at Week 12 (+ 50 learnings, 47 decisions) | ~9,000 | 4.5% | -| **Remaining for actual work** | **~187,000** | **93%+** | - -The coordinator uses 6.6% of its window. A 12-week veteran agent uses 4.5% — but in **its own window**, not yours. Fan out to 5 agents and you get ~1M tokens of total reasoning capacity across all windows. - ---- - -## Known limitations - -- **Experimental** — file formats and APIs may change between versions. -- **Silent success bug** — approximately 7–10% of background agent spawns complete all their file writes but return no text response. This is a platform-level issue. Squad detects it by checking the filesystem for work product and reports what it finds. Work is not lost. -- **Platform latency** — response times depend on the Copilot platform. Complex multi-agent tasks take 40–60 seconds. Simple questions are answered in 2–3 seconds. -- **Node 20+** — requires a Node.js LTS release (v20.0.0 or later). -- **GitHub Copilot required** — Squad works across Copilot hosts (CLI, VS Code, Visual Studio, Coding Agent). -- **First session is the least capable** — agents improve as they accumulate history. Give it a few sessions before judging. - ---- - -## Adding and removing team members - -### Adding - -``` -> I need a DevOps person -``` - -Squad allocates a name from the current universe, generates a charter and history seeded with project context, and adds them to the roster. Immediately productive. - -### Removing - -``` -> Remove the designer — we're past that phase -``` - -Agents are never deleted. Their charter and history move to `.squad/agents/_alumni/`. Knowledge is preserved. If you need them back later, they remember everything. - ---- - -## Reviewer protocol - -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. - -→ [Full guide: Reviewer Protocol](features/reviewer-protocol.md#reviewer-rejection-protocol) - ---- - -## File ownership - -Squad maintains a clear ownership model: - -| What | Owner | Safe to edit? | -|------|-------|--------------| -| `.github/agents/squad.agent.md` | Squad (overwritten on upgrade) | No — your changes will be lost | -| `.squad/` | You and your team | Yes — this is your team's state | -| `squad.config.ts` | You | Yes — your SDK-first config | -| Everything else | You | Yes | - ---- - -## Quick reference - -| Command | What it does | -|---------|-------------| -| `squad init` | Initialize Squad in the current repo | -| `squad init --sdk` | Initialize with SDK-first TypeScript config | -| `squad init --global` | Initialize a personal squad (cross-project) | -| `squad build` | Generate `.squad/` from `squad.config.ts` | -| `squad build --check` | Validate generated files match disk (for CI) | -| `squad doctor` | Run 9 setup validation checks | -| `squad shell` | Enter the interactive shell | -| `squad triage` | Run a single triage pass | -| `squad triage --interval 10` | Continuous triage every 10 minutes | -| `squad watch` | Ralph watchdog mode | -| `squad export` | Export team to `squad-export.json` | -| `squad import ` | Import team from export file | -| `squad import --force` | Import, archiving existing agents | -| `squad plugin install ` | Install a plugin from the marketplace | -| `squad plugin list` | List installed plugins | -| `squad migrate --to sdk` | Convert existing squad to SDK-first config | -| `squad migrate --from ai-team` | Migrate from `.ai-team/` to `.squad/` | -| `squad subsquads` | Manage SubSquads | -| `squad status` | Show team status and global config | -| `squad --version` | Show installed version | -| `squad --help` | Show help | diff --git a/docs/src/content/docs/guide/personal-squad.md b/docs/src/content/docs/guide/personal-squad.md index 36f4e1676..e4c8aecc5 100644 --- a/docs/src/content/docs/guide/personal-squad.md +++ b/docs/src/content/docs/guide/personal-squad.md @@ -323,4 +323,4 @@ We're building in the open. If something feels off, [open an issue](https://gith - [**Your First Session**](../get-started/first-session.md) — The full walkthrough from zero to fan-out - [**Solo Dev Scenario**](../scenarios/solo-dev.md) — Squad for one-person teams -- [**Tips & Tricks**](tips-and-tricks.md) — Patterns that work +- [**Tips & Tricks**](./tips-and-tricks.md) — Patterns that work diff --git a/docs/src/content/docs/sample-prompts.md b/docs/src/content/docs/sample-prompts.md deleted file mode 100644 index b3a73fee5..000000000 --- a/docs/src/content/docs/sample-prompts.md +++ /dev/null @@ -1,412 +0,0 @@ -# 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/private-repos.md b/docs/src/content/docs/scenarios/private-repos.md index 47d06b5d6..71d46cb94 100644 --- a/docs/src/content/docs/scenarios/private-repos.md +++ b/docs/src/content/docs/scenarios/private-repos.md @@ -16,12 +16,6 @@ Squad runs entirely in your Copilot session. Nothing leaves your machine except ## 1. Where Squad Runs -Squad runs entirely in your Copilot session. Nothing leaves your machine except what Copilot already does. - ---- - -## 1. Where Squad Runs - Squad is a **local agent** that runs in your GitHub Copilot CLI session. It doesn't phone home. It doesn't send data to a Squad server. It doesn't use external APIs. When you run: diff --git a/docs/src/content/docs/tips-and-tricks.md b/docs/src/content/docs/tips-and-tricks.md deleted file mode 100644 index 2583e55bb..000000000 --- a/docs/src/content/docs/tips-and-tricks.md +++ /dev/null @@ -1,640 +0,0 @@ -# Tips and Tricks for Managing Your Squad - -> **Quick Start Prompts:** -> `"Team, build the login feature — include UI, API endpoints, and tests"` -> `"Always use TypeScript strict mode and named exports"` -> `"Ralph, start monitoring — handle the backlog while I work on urgent tasks"` -> `"What did the team accomplish last session?"` - -Real patterns from using Squad effectively. These are techniques that work. - ---- - -## Effective Prompt Patterns - -### 1. Be Specific About Scope - -Good prompts describe the boundary, not just the task. - -``` -❌ "Build the auth system" -✅ "Build JWT authentication for login/logout/refresh. Sessions stored in Redis. - Passwords hashed with bcrypt. No OAuth yet — that's phase 2." -``` - -The second one tells the team: what's in, what's out, what's coming. Agents don't have to guess or ask. - -### 2. Name the Team Roster in Your Spec - -If you need specialized agents, say so in the prompt. - -``` -I'm building a data pipeline that: -- Reads CSV files and validates schema (Backend handles I/O) -- Transforms data with custom rules (Data Specialist handles logic) -- Loads into PostgreSQL with migration tracking (Backend handles schema) -- Generates reports as HTML dashboards (Frontend handles UI) - -I need Backend, a Data Specialist (who knows ETL patterns), and Frontend. -Set up the team and start with the data validation layer. -``` - -This creates exactly the team you need instead of defaulting to the generic roster. - -### 3. Use "Team" When Parallel Work Matters - -``` -> Team, build the login page. -``` - -This spawns frontend (UI), backend (endpoints), tester (test cases), and lead (architecture) — all at once. They divide the work naturally. - -For sequential work, name the agent: - -``` -> Dallas (Frontend), build the dashboard layout first. -> When you're done, Kane (Backend) will add the data binding. -``` - -### 4. Stack Decisions in Your Prompt - -Decisions made early prevent agents from asking questions later. - -``` -> Here are the rules for this sprint: -> - Always use TypeScript strict mode -> - Component file names are PascalCase, never kebab-case -> - All exports are named (no default exports) -> - React hooks only, no class components -> -> Frontend team, build the form components. These rules are permanent. -``` - -These go into `decisions.md` automatically. Future agents read them before working. - -### 5. Use Bullet Points for Multi-Part Tasks - -Agents process lists better than paragraphs. - -``` -❌ "We need to update the user model to include profile fields like bio and avatar - and we should also add validation for those fields and write tests." - -✅ "Update the user model: - - Add bio (string, 500 char max) - - Add avatar (string, URL) - - Add phoneNumber (string, optional, E.164 format) - - Validate all fields - - Write test cases for validation edge cases" -``` - ---- - -## When to Use Direct Commands vs Team Requests - -### Use Direct Commands (Name an Agent) - -When the work is **sequential** or **highly specialized**. - -``` -> Keaton, review this PR for architectural fit. -``` - -| Use Case | Example | Why | -|----------|---------|-----| -| Code review | "Keaton, review the auth endpoints" | Only the lead does design review | -| Specialized skill | "Felix, optimize the database queries" | The performance expert works alone | -| Fix a specific mistake | "Dallas, fix the button styling" | Don't spawn the whole team for one file | -| Unblock someone | "Kane, help Lambert debug the test failure" | Point conversation between two agents | - -### Use Team Requests (Say "Team") - -When the work is **parallel** or **cross-functional**. - -``` -> Team, build the checkout flow. -``` - -| Use Case | Example | Why | -|----------|---------|-----| -| New feature | "Team, build the search feature" | Frontend, backend, tests all start together | -| Sprint planning | "Team, plan the next two weeks" | Lead scopes, backend estimates, tester defines test cases | -| Problem-solving | "Team, we have a performance problem — investigate" | Frontend measures, backend profiles, infra checks caching | -| Iteration round | "Team, fix the feedback from the design review" | Multiple people can tackle different issues in parallel | - -### Use General Requests (No Name) - -When you don't care who handles it, or when it's context-dependent. - -``` -> Add error logging to the API. -``` - -Squad routes this intelligently. Could be backend, could be ops, depends on team. - ---- - -## Getting the Most Out of Parallel Work - -### 1. Wait for Work to Complete Before Following Up - -Squad agents chain their own work. When you give a task, **don't interrupt**. - -``` -You: "Team, build the login page." - [Squad spawns frontend, backend, tester, lead] - [Frontend finishes UI, backend finishes endpoints, tester writes test cases] - - [Test failures show up → backend picks them up automatically] - [Tester finds edge cases → backend fixes them → tester re-runs] - - [5 minutes later, everything is done] -``` - -If you jump in after 2 minutes with "Did you test the form submission?", you break the chain. Let it finish. - -### 2. Check the Work Log, Not the Output - -When agents finish a batch, read the logs, not the code. - -``` -> What did the team just do? -``` - -This asks Scribe to summarize. You'll see: -- What was built -- What decisions were made -- What's left to do -- What surprised them - -Much faster than reading 5 agent outputs. - -### 3. Run Ralph When the Board is Full - -If you have a backlog of issues or PRs, let Ralph process them. - -``` -> Ralph, go -``` - -Ralph will: -1. Triage untriaged issues -2. Assign to team members -3. Spawn agents to work through them -4. Report progress every 3-5 rounds -5. Keep going until the board is clear - -You can keep using the team for urgent work while Ralph grinds through the backlog. - -### 4. Use Parallel Decision-Making - -Agents can write decisions in parallel (they go to `/decisions/inbox/`). Scribe merges them. - -``` -You: "Frontend team, decide on component structure. - Backend team, decide on API versioning. - Both write your decisions to decisions.md. Don't wait for each other." - -[Frontend writes decision about component structure] -[Backend writes decision about API versioning] -[Both decisions merge automatically via Scribe] -[Every agent reads both before the next task] -``` - -This prevents "we decided different things" surprises. - ---- - -## Tips for Working with Ralph (Work Monitor) - -### 1. Activate Ralph When You Have Backlog - -Ralph is most useful when you have open issues. - -``` -> 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 Ralph on event-based triggers (issue close, PR merge, manual dispatch). For persistent polling when you're away from the keyboard, use `squad watch` locally. - -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. - ---- - -## 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.** - -### 2. Use User Directives for "Never Again" Lessons - -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. -``` - ---- - -## Common Pitfalls and How to Avoid Them - -### Pitfall 1: Vague Scope = Agents Ask Questions Instead of Building - -**Problem:** "Build the API" — unclear what endpoints, what data model, what auth. - -**Solution:** Be specific. Agents will ask if unclear, but clarity upfront saves rounds. - -``` -✅ "Build a REST API for a recipe app. Endpoints: /recipes (list, create), - /recipes/:id (get, update, delete), /recipes/:id/ingredients (list, add). - Auth via JWT. Database: PostgreSQL." -``` - -### Pitfall 2: Interrupting Parallel Work - -**Problem:** You give a task to the team, then jump in after 2 minutes with a follow-up question. - -**Solution:** Let parallel work finish. Squad agents chain automatically. Your interruption breaks the chain. - -``` -❌ You: "Team, build the checkout page" - [2 minutes later] - You: "Did you test the payment flow yet?" - -✅ You: "Team, build the checkout page" - [Wait for them to finish] - You: "What did you build?" -``` - -### Pitfall 3: Forgetting That Decisions Persist - -**Problem:** You set a rule in session 1, forget about it, contradict it in session 5. - -**Solution:** Read `decisions.md` at the start of every session, or ask Scribe: - -``` -> Scribe, remind me of the permanent rules. -``` - -### Pitfall 4: Not Using Ralph on a Full Backlog - -**Problem:** You have 10 open issues, but you keep working on small tasks manually. - -**Solution:** Use Ralph for the backlog, stay focused on urgent work. - -``` -> Ralph, start monitoring. I'm going to focus on the payment bug. -``` - -Ralph handles the backlog, you handle the critical path. - -### Pitfall 5: Too Many Agents at Once - -**Problem:** You spawn a huge team and context gets confusing. - -**Solution:** Start small. 4-5 agents is a good team. Add specialists only when needed. - -``` -✅ "Start with Lead, Frontend, Backend, Tester. If we need DevOps later, we'll add them." - -❌ "I want Lead, Frontend, Backend, Tester, DevOps, Data Engineer, Designer, and a Scribe." -``` - -### Pitfall 6: Lost Work Because You Didn't Commit `.ai-team/` - -**Problem:** You deleted the repo and lost all your team knowledge. - -**Solution:** **Commit `.ai-team/` to git.** It's permanent team memory. - -```bash -git add .ai-team/ -git commit -m "Add squad team state" -git push -``` - -Now anyone who clones the repo gets your team with all their learned knowledge. - -### Pitfall 7: Agents Stuck on the Same Mistake - -**Problem:** An agent keeps making the same error even though you fixed it in session 3. - -**Solution:** The decision might not be in `decisions.md`. Add it. - -``` -> Agent keeps importing with `require` instead of `import`. -> Here's the rule: Always use ES6 import/export syntax. -``` - -This goes to `decisions.md`. Next time that agent works, they'll read it. - -### Pitfall 8: Ralph Running Out of Work Too Quietly - -**Problem:** Ralph finishes all the work but doesn't tell you, so you think he's still working. - -**Solution:** Ralph reports every 3-5 rounds. If you don't see a report in a while, ask: - -``` -> Ralph, status -``` - -Ralph will check once and report. If the board is empty, you know you're done. - ---- - -## Advanced Patterns - -### Pattern 1: Decision First, Implementation Second - -Before any agent writes code, the team agrees on the design. - -``` -> Team, design the user model. Don't code yet. -> Frontend, what fields do you need? Backend, what do you need to persist? -> Tester, what are the validation edge cases? -> Write your decisions to decisions.md. - -[Team agrees on the design] - -> Team, now build it. -``` - -This prevents "we built different things" surprises. - -### Pattern 2: Run Two Parallel Teams on One Repo - -If you have a large project, you can run one team on one feature, another team on another. - -``` -Squad 1: "Team A, build the admin dashboard. You own features/admin/." -Squad 2: "Team B, build the mobile app. You own features/mobile/." - -[Both teams work in parallel] -[Shared decisions in .ai-team/decisions.md prevent conflicts] -``` - -Requires good routing rules and clear ownership, but it works. - -### Pattern 3: Spike → Decision → Build - -For hard problems, do a spike first. - -``` -> Keaton (Lead), do a spike on authentication patterns for this stack. -> Spend 30 minutes exploring. Write your findings to a decision. - -[Keaton researches, writes decision about auth strategy] - -> Team, now build the auth system using the strategy Keaton decided. -``` - -This prevents agents from building the wrong thing. - -### Pattern 4: Post-Mortem Decisions - -When something goes wrong, capture the lesson. - -``` -> The API is returning user passwords in the response. This was a mistake. -> Here's the rule going forward: Never include password fields in API responses. -``` - -This prevents it from happening again. - ---- - -## Prompts You Can Copy - -### Getting Started - -``` -I'm building [brief description]. Set up the team. -Stack: [language, framework, database] -Key requirements: -- [requirement 1] -- [requirement 2] -- [requirement 3] -``` - -### Asking for Status - -``` -What did the team accomplish last session? Any blockers? -``` - -### Parallel Work on Different Features - -``` -Team, I want you to work on two things in parallel: - -Feature A (Frontend + Backend): -- [spec] - -Feature B (Backend + Tester): -- [spec] - -Divide the team. Start both immediately. -``` - -### Spike Before Building - -``` -Keaton, do a 20-minute spike on [problem]. -Research [specific areas]. -Write a decision with your recommendation. -When you're done, tell me what you learned. -``` - -### Closing a Phase - -``` -Team, we're closing the MVP phase. -Keaton, what's the current architecture? -Kane, what's left to do on the backend? -Dallas, what UX work is pending? -Lambert, what tests are missing? - -Write your summary to history.md. -``` - ---- - -## Session Flow Template - -A typical high-performing session: - -1. **Start:** Open Copilot, say "Team" or name an agent -2. **Set context:** Describe the work (scope, decisions, rules) -3. **Parallel execution:** Let agents work (don't interrupt) -4. **Check logs:** Ask Scribe what happened while you were reading code -5. **Next round:** Based on what Scribe told you, give follow-up work or start Ralph -6. **Wrap up:** Ask Ralph for status, commit `.ai-team/`, go home - -**Time to productive work: usually < 2 minutes.** - ---- - -## Reference: Who Does What - -When you're unsure who to ask: - -| Task | Ask | Why | -|------|-----|-----| -| Architecture review | Lead (Keaton) | Design decisions are the lead's job | -| Fix a feature | The assigned agent | They know the context | -| Debug a test | Tester + Backend | Usually a logic error or missing setup | -| Design decision | Team (parallel) | All perspectives needed | -| Code review | Lead | Final arbiter | -| What happened last session? | Scribe | Scribe tracks everything | -| What's on the backlog? | Ralph | Ralph monitors the board | -| New decision | Any agent can propose, Scribe merges | Decisions are shared | -| Edit decisions.md | You or Scribe | Plain markdown, editable anytime | - diff --git a/docs/src/content/docs/tour-first-session.md b/docs/src/content/docs/tour-first-session.md deleted file mode 100644 index 9fcbe9a54..000000000 --- a/docs/src/content/docs/tour-first-session.md +++ /dev/null @@ -1,273 +0,0 @@ -# First Session Walkthrough - -A step-by-step tour of your first time using Squad. Follow along in your terminal. - ---- - -## 1. Install Squad - -Start with a git repo (new or existing): - -```bash -mkdir my-app && cd my-app -git init -npm install -g @bradygaster/squad-cli -squad init -``` - -You'll see: - -``` -✅ Squad installed. - .github/agents/squad.agent.md — coordinator agent - .github/workflows/ — 5 GitHub workflows (heartbeat, triage, CI, etc.) - .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 (pulled from `git config user.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. Names come from a fictional universe — the exact universe depends on your project shape and history. Here's what it might look like: - -``` -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 - -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 - -You can 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 `.ai-team/` directory structure (team roster, routing rules, casting state, ceremony config, agent charters and histories — all seeded with your project context). 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 -🔧 Dallas — creating GET /api/recipes endpoint -🧪 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. - - List returns paginated results - - Empty database returns empty array - - Invalid cursor returns 400 - - 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, you can check status: - -``` -> Where are we? -``` - -This is a Direct mode response — no agent spawn, just the coordinator reading 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 Task — Watch Decisions Accumulate - -Give a follow-up task: - -``` -> Now add a search feature. Users should be able to search -> recipes by ingredient name. -``` - -Squad sees this involves multiple domains and 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. - ---- - -## 8. Set a Directive - -You notice something you want to standardize: - -``` -> Always use Zod for API input validation -``` - -Squad captures this as a directive — no agent spawn needed: - -``` -📌 Captured. All API input validation must use Zod. -``` - -This is written to `decisions.md` via the inbox. 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 everything — charters, histories, casting state, skills, and decisions. You can import it into another repo later: - -```bash -cd ../other-project -npm install -g @bradygaster/squad-cli -squad init -squad import ../my-app/squad-export.json -``` - ---- - -## What to Try Next - -- **Add a team member:** `"I need a DevOps person"` -- **Run a ceremony:** `"Run a design review before we start the auth system"` -- **Direct an agent:** `"Lambert, run the test suite and tell me what's failing"` -- **Remove someone:** `"Remove the designer — we don't need them anymore"` -- **Connect to issues:** `"Connect to myorg/myrepo"` (see [GitHub Issues Walkthrough](tour-github-issues.md)) - ---- - -## Tips - -- **First session is the slowest.** Agents have no history yet. After 2–3 sessions, they know your conventions and stop asking questions they've answered before. -- **Commit `.ai-team/`.** It's your team's brain. Anyone who clones gets the team with all their knowledge. -- **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/tour-github-issues.md b/docs/src/content/docs/tour-github-issues.md deleted file mode 100644 index aff55a708..000000000 --- a/docs/src/content/docs/tour-github-issues.md +++ /dev/null @@ -1,199 +0,0 @@ -# GitHub Issues Walkthrough - -A step-by-step tour of Squad's GitHub Issues workflow. This connects your team to a real repository's issue tracker so agents can pick up issues, create branches, open PRs, and handle review feedback. - -**Prerequisite:** The `gh` CLI must be installed and authenticated (`gh auth login`). - ---- - -## 1. Connect to a Repository - -Tell Squad which repo to track: - -``` -> Connect to myorg/recipe-app -``` - -Squad stores the issue source in team state: - -``` -✅ Issue source stored: myorg/recipe-app - Using gh CLI for issue tracking. -``` - -From now on, Squad can read issues from that repo and create branches and PRs against it. - ---- - -## 2. View the Backlog - -Ask to see open issues: - -``` -> Show the backlog -``` - -Squad pulls open issues via `gh` and displays them: - -``` -┌─────┬──────────────────────────────────────────┬───────────┬────────────┐ -│ # │ Title │ Labels │ Assignee │ -├─────┼──────────────────────────────────────────┼───────────┼────────────┤ -│ 12 │ Add ingredient search │ feature │ — │ -│ 15 │ Fix pagination on recipe list │ bug │ — │ -│ 18 │ Add user profile page │ feature │ — │ -│ 21 │ Rate limiting on API endpoints │ security │ — │ -│ 23 │ Mobile responsive layout │ ui │ — │ -└─────┴──────────────────────────────────────────┴───────────┴────────────┘ -5 open issues -``` - ---- - -## 3. Work on an Issue - -Pick an issue for an agent to work on: - -``` -> Work on #12 -``` - -Squad reads the issue details, routes it to the right agent, and kicks off the workflow: - -``` -🔧 Dallas — picking up #12 (Add ingredient search) - -Dallas is reading the issue and starting work. -``` - -Behind the scenes, the agent: - -1. **Creates a branch** — named descriptively based on the issue (e.g., `12-add-ingredient-search`) -2. **Does the implementation work** — writes code, tests, whatever the issue requires -3. **Opens a PR** — linked back to issue #12, with a description of what was done - -When the agent finishes: - -``` -🔧 Dallas — Completed #12 (Add ingredient search) - Branch: 12-add-ingredient-search - PR: #24 opened — "Add ingredient search (#12)" - Files changed: - - src/routes/recipes.ts (added search endpoint) - - src/models/recipe.ts (added text index) - - test/search.test.ts (6 test cases) -``` - ---- - -## 4. Multiple Issues in Parallel - -You can assign multiple issues at once: - -``` -> Work on #15 and #23 -``` - -``` -🔧 Dallas — picking up #15 (Fix pagination on recipe list) -⚛️ Ripley — picking up #23 (Mobile responsive layout) -📋 Scribe — logging session -``` - -Each agent creates its own branch and works independently. If your repo supports worktrees, Squad can work on multiple branches simultaneously. - ---- - -## 5. Handle Review Feedback - -After a PR is open, reviewers may leave comments. When you see feedback: - -``` -> There's review feedback on PR #24 -``` - -Squad routes the review to the agent who opened the PR: - -``` -🔧 Dallas — reading review comments on PR #24 - -Dallas is addressing the feedback now. -``` - -The agent reads the review comments, makes the requested changes, and pushes new commits to the same branch: - -``` -🔧 Dallas — Addressed review feedback on PR #24 - - Added input sanitization for search query (reviewer concern) - - Added test case for SQL injection attempt - - Pushed 2 new commits to 12-add-ingredient-search -``` - ---- - -## 6. Merge Completed Work - -When the PR is approved and ready: - -``` -> Merge PR #24 -``` - -``` -✅ PR #24 merged — "Add ingredient search (#12)" - Issue #12 closed. - Branch 12-add-ingredient-search deleted. -``` - -The issue is closed automatically when the PR merges (if the PR body includes `Closes #12`). - ---- - -## 7. Check Remaining Work - -After merging, see what's left: - -``` -> What's left? -``` - -Squad refreshes the backlog: - -``` -┌─────┬──────────────────────────────────────────┬───────────┬────────────┐ -│ # │ Title │ Labels │ Assignee │ -├─────┼──────────────────────────────────────────┼───────────┼────────────┤ -│ 15 │ Fix pagination on recipe list │ bug │ Dallas │ -│ 18 │ Add user profile page │ feature │ — │ -│ 21 │ Rate limiting on API endpoints │ security │ — │ -│ 23 │ Mobile responsive layout │ ui │ Ripley │ -└─────┴──────────────────────────────────────────┴───────────┴────────────┘ -4 open issues (2 in progress) -``` - ---- - -## Full Workflow at a Glance - -``` -Connect → "connect to myorg/recipe-app" -Browse → "show the backlog" -Assign → "work on #12" - └─ Agent creates branch, implements, opens PR -Review → "there's review feedback on PR #24" - └─ Agent reads comments, pushes fixes -Merge → "merge PR #24" - └─ PR merged, issue closed -Status → "what's left?" - └─ Updated backlog -``` - ---- - -## Tips - -- **You don't pick the agent.** Squad routes the issue to the agent whose expertise matches the issue's domain. A bug in the API goes to the backend agent. A UI issue goes to the frontend agent. -- **Agents name branches sensibly.** Branch names include the issue number and a slugified title, so they're easy to find in `git branch`. -- **PRs link to issues.** The PR description includes a `Closes #N` reference so merging automatically closes the issue. -- **Review feedback is incremental.** When you tell Squad about review feedback, the agent pushes new commits to the existing branch — no force-pushes, no new PRs. -- **Check `decisions.md` after issue work.** Agents often record decisions while working on issues (e.g., "chose cursor pagination" or "added text index for search"). These decisions carry forward to future issues. diff --git a/docs/src/content/docs/tour-gitlab-issues.md b/docs/src/content/docs/tour-gitlab-issues.md deleted file mode 100644 index 4d955b89d..000000000 --- a/docs/src/content/docs/tour-gitlab-issues.md +++ /dev/null @@ -1,236 +0,0 @@ -# GitLab Issues Walkthrough - -> **🧪 Experimental.** GitLab Issues Mode is new. Commands, behavior, and integration details may change. [Feedback welcome.](https://github.com/bradygaster/squad/issues) - -A step-by-step tour of Squad's GitLab Issues workflow. This connects your team to a GitLab repository's issue tracker so agents can pick up issues, create branches, open Merge Requests, and handle review feedback. - -**Prerequisite:** The [`glab` CLI](https://docs.gitlab.com/cli/issue/) (official GitLab CLI) must be installed and authenticated (`glab auth login`). - ---- - -## 1. Connect to a Repository - -Tell Squad which GitLab repo to track: - -``` -> Connect to GitLab at https://gitlab.example.com/acme/recipe-app -``` - -Squad stores the issue source in team state: - -``` -✅ Issue source stored: https://gitlab.example.com/acme/recipe-app (GitLab) - Using glab CLI for issue tracking. -``` - -From now on, Squad can read issues from that repo and create branches and MRs against it. - ---- - -## 2. View the Backlog - -Ask to see open issues: - -``` -> Show the backlog -``` - -Squad pulls open issues via `glab issue list` (open by default) and displays them: - -``` -┌─────┬──────────────────────────────────────────┬───────────┬────────────┐ -│ # │ Title │ Labels │ Assignee │ -├─────┼──────────────────────────────────────────┼───────────┼────────────┤ -│ 12 │ Add ingredient search │ feature │ — │ -│ 15 │ Fix pagination on recipe list │ bug │ — │ -│ 18 │ Add user profile page │ feature │ — │ -│ 21 │ Rate limiting on API endpoints │ security │ — │ -│ 23 │ Mobile responsive layout │ ui │ — │ -└─────┴──────────────────────────────────────────┴───────────┴────────────┘ -5 open issues -``` - ---- - -## 3. Work on an Issue - -Pick an issue for an agent to work on: - -``` -> Work on #12 -``` - -Squad reads the issue details, routes it to the right agent, and kicks off the workflow: - -``` -🔧 Dallas — picking up #12 (Add ingredient search) - -Dallas is reading the issue and starting work. -``` - -Behind the scenes, the agent: - -1. **Creates a branch** — named descriptively based on the issue (e.g., `12-add-ingredient-search`) -2. **Does the implementation work** — writes code, tests, whatever the issue requires -3. **Opens a Merge Request** — linked back to issue #12, with a description of what was done - -When the agent finishes: - -``` -🔧 Dallas — Completed #12 (Add ingredient search) - Branch: 12-add-ingredient-search - MR: !24 opened — "Add ingredient search (#12)" - Files changed: - - src/routes/recipes.ts (added search endpoint) - - src/models/recipe.ts (added text index) - - test/search.test.ts (6 test cases) -``` - ---- - -## 4. Multiple Issues in Parallel - -You can assign multiple issues at once: - -``` -> Work on #15 and #23 -``` - -``` -🔧 Dallas — picking up #15 (Fix pagination on recipe list) -⚛️ Ripley — picking up #23 (Mobile responsive layout) -📋 Scribe — logging session -``` - -Each agent creates its own branch and works independently. If your repo supports worktrees, Squad can work on multiple branches simultaneously. - ---- - -## 5. Handle Review Feedback - -After an MR is open, reviewers may leave comments. When you see feedback: - -``` -> There's review feedback on MR !24 -``` - -Squad routes the review to the agent who opened the MR: - -``` -🔧 Dallas — reading review comments on MR !24 - -Dallas is addressing the feedback now. -``` - -The agent reads the review comments, makes the requested changes, and pushes new commits to the same branch: - -``` -🔧 Dallas — Addressed review feedback on MR !24 - - Added input sanitization for search query (reviewer concern) - - Added test case for SQL injection attempt - - Pushed 2 new commits to 12-add-ingredient-search -``` - ---- - -## 6. Merge Completed Work - -When the MR is approved and ready: - -``` -> Merge MR !24 -``` - -``` -✅ MR !24 merged — "Add ingredient search (#12)" - Issue #12 closed. - Branch 12-add-ingredient-search deleted. -``` - -The issue is closed automatically when the MR merges (if the MR body includes `Closes #12`). - ---- - -## 7. Check Remaining Work - -After merging, see what's left: - -``` -> What's left? -``` - -Squad refreshes the backlog: - -``` -┌─────┬──────────────────────────────────────────┬───────────┬────────────┐ -│ # │ Title │ Labels │ Assignee │ -├─────┼──────────────────────────────────────────┼───────────┼────────────┤ -│ 15 │ Fix pagination on recipe list │ bug │ Dallas │ -│ 18 │ Add user profile page │ feature │ — │ -│ 21 │ Rate limiting on API endpoints │ security │ — │ -│ 23 │ Mobile responsive layout │ ui │ Ripley │ -└─────┴──────────────────────────────────────────┴───────────┴────────────┘ -4 open issues (2 in progress) -``` - ---- - -## Full Workflow at a Glance - -``` -Connect → "connect to GitLab at https://gitlab.example.com/acme/recipe-app" -Browse → "show the backlog" -Assign → "work on #12" - └─ Agent creates branch, implements, opens MR -Review → "there's review feedback on MR !24" - └─ Agent reads comments, pushes fixes -Merge → "merge MR !24" - └─ MR merged, issue closed -Status → "what's left?" - └─ Updated backlog -``` - ---- - -## Installing the GitLab CLI - -The `glab` CLI is the official GitLab command-line tool. It's required for all GitLab Issues Mode operations. - -### Install - -| Platform | Command | -|----------|---------| -| macOS (Homebrew) | `brew install glab` | -| Windows (WinGet) | `winget install GLab.GLab` | -| Windows (Scoop) | `scoop install glab` | -| Linux (apt) | See [GitLab CLI docs](https://docs.gitlab.com/cli/issue/) | -| From source | `go install gitlab.com/gitlab-org/cli/cmd/glab@main` | - -### Authenticate - -```bash -glab auth login -``` - -Choose your GitLab instance (gitlab.com or self-managed), select HTTPS, and authenticate via browser or a Personal Access Token. - -### Verify - -```bash -glab auth status -``` - -You should see your username and the instance you're connected to. - -For more details, see the [official GitLab CLI documentation](https://docs.gitlab.com/cli/issue/). - ---- - -## Tips - -- **You don't pick the agent.** Squad routes the issue to the agent whose expertise matches the issue's domain. A bug in the API goes to the backend agent. A UI issue goes to the frontend agent. -- **Agents name branches sensibly.** Branch names include the issue number and a slugified title, so they're easy to find in `git branch`. -- **MRs link to issues.** The MR description includes a `Closes #N` reference so merging automatically closes the issue. -- **Review feedback is incremental.** When you tell Squad about review feedback, the agent pushes new commits to the existing branch — no force-pushes, no new MRs. -- **Check `decisions.md` after issue work.** Agents often record decisions while working on issues (e.g., "chose cursor pagination" or "added text index for search"). These decisions carry forward to future issues. -- **Self-managed GitLab works too.** The `glab` CLI supports self-managed GitLab instances. Run `glab auth login` and select your instance URL during setup. diff --git a/test/docs-build.test.ts b/test/docs-build.test.ts index aeb51d790..4376c72fe 100644 --- a/test/docs-build.test.ts +++ b/test/docs-build.test.ts @@ -6,7 +6,8 @@ import { describe, it, expect, beforeAll, afterAll } from 'vitest'; import { readdirSync, readFileSync, existsSync, rmSync } from 'node:fs'; import { execSync } from 'node:child_process'; -import { join, basename } from 'node:path'; +import { join, basename, relative } from 'node:path'; +import { NAV_SECTIONS, STANDALONE_PAGES } from '../docs/src/navigation'; const DOCS_DIR = join(process.cwd(), 'docs'); const CONTENT_DIR = join(DOCS_DIR, 'src', 'content'); @@ -364,3 +365,139 @@ describe('Docs Build Script (Astro)', () => { expect(html).toContain('id="search-modal"'); }); }); + +// --- P0 Docs Quality Checks (TDD red phase — these SHOULD fail on current code) --- + +/** Recursively collect all .md files under a directory */ +function getAllContentDocsRecursive(dir: string): string[] { + const entries = readdirSync(dir, { withFileTypes: true }); + const files: string[] = []; + for (const entry of entries) { + const fullPath = join(dir, entry.name); + if (entry.isDirectory()) { + files.push(...getAllContentDocsRecursive(fullPath)); + } else if (entry.name.endsWith('.md')) { + files.push(fullPath); + } + } + return files; +} + +/** Extract a page title from YAML frontmatter `title:` or the first `# ` heading */ +function getPageTitle(filepath: string): string | null { + const content = readFileSync(filepath, 'utf-8'); + const fmMatch = content.match(/^---\s*\n[\s\S]*?^title:\s*["']?([^"'\n]+?)["']?\s*$/m); + if (fmMatch) return fmMatch[1].trim(); + const h1Match = content.match(/^#\s+(.+)/m); + return h1Match ? h1Match[1].trim() : null; +} + +describe('P0 docs quality checks', () => { + + it('no markdown file has duplicate H2 headings', () => { + const allFiles = getAllContentDocsRecursive(DOCS_CONTENT_DIR); + const failures: string[] = []; + + for (const file of allFiles) { + const content = readFileSync(file, 'utf-8'); + const h2Lines = content.split('\n') + .filter(line => /^## /.test(line)) + .map(line => line.trim()); + + const seen = new Set(); + const dupes = new Set(); + for (const h2 of h2Lines) { + if (seen.has(h2)) dupes.add(h2); + seen.add(h2); + } + + if (dupes.size > 0) { + const rel = relative(DOCS_CONTENT_DIR, file).replace(/\\/g, '/'); + failures.push(`${rel}: ${[...dupes].join(', ')}`); + } + } + + expect(failures, `Duplicate H2 headings found:\n${failures.join('\n')}`).toHaveLength(0); + }); + + it('all content pages are wired into navigation.ts', () => { + // Pages that exist but aren't wired into navigation.ts yet (intentional) + const KNOWN_ORPHANS: string[] = [ + 'features/built-in-roles', + 'features/context-hygiene', + 'features/cost-tracking', + 'features/issue-templates', + 'get-started/choose-your-interface', + 'guide/build-autonomous-agent', + 'guide/faq', + 'guide/github-auth-setup', + 'reference/api-reference', + 'reference/vscode-troubleshooting', + ]; + + const navSlugs = new Set(); + for (const section of NAV_SECTIONS) { + for (const item of section.items) { + navSlugs.add(item.slug); + } + } + for (const page of STANDALONE_PAGES) { + navSlugs.add(page.slug); + } + + const allFiles = getAllContentDocsRecursive(DOCS_CONTENT_DIR); + const orphans: string[] = []; + + for (const file of allFiles) { + const rel = relative(DOCS_CONTENT_DIR, file).replace(/\\/g, '/').replace(/\.md$/, ''); + if (rel.endsWith('/index') || rel === 'index') continue; + if (KNOWN_ORPHANS.includes(rel)) continue; + + if (!navSlugs.has(rel)) { + orphans.push(rel); + } + } + + expect(orphans, `Orphan pages not in navigation.ts:\n${orphans.join('\n')}`).toHaveLength(0); + }); + + it('navigation titles roughly match their page titles', () => { + // Stylistic choices where short nav titles differ from descriptive page titles + const KNOWN_MISMATCHES: string[] = [ + 'features/labels', + 'features/plugins', + 'features/notifications', + 'reference/config', + 'scenarios/monorepo', + 'scenarios/cross-org-auth', + 'scenarios/team-state-storage', + ]; + + const allNavItems = [ + ...NAV_SECTIONS.flatMap(s => s.items), + ...STANDALONE_PAGES, + ]; + const mismatches: string[] = []; + + const significantWords = (s: string) => + s.toLowerCase().replace(/[^a-z0-9\s]/g, '').split(/\s+/).filter(w => w.length >= 3); + + for (const item of allNavItems) { + if (KNOWN_MISMATCHES.includes(item.slug)) continue; + const filePath = join(DOCS_CONTENT_DIR, `${item.slug}.md`); + if (!existsSync(filePath)) continue; + const pageTitle = getPageTitle(filePath); + if (!pageTitle) continue; + + const navWords = significantWords(item.title); + const pageWords = significantWords(pageTitle); + const overlap = navWords.filter(w => pageWords.includes(w)); + + if (overlap.length === 0 && navWords.length > 0) { + mismatches.push(`Nav "${item.title}" → Page "${pageTitle}" (${item.slug})`); + } + } + + expect(mismatches, `Nav/page title mismatches:\n${mismatches.join('\n')}`).toHaveLength(0); + }); +});