Squad Agents

Overview

Squad gives you an AI development team through GitHub Copilot. Describe what you're building and get a team of specialists — frontend, backend, tester, lead — that live in your repo as files. Each team member runs in its own context, reads only its own knowledge, writes back what it learned, and persists across sessions.

Instructions

Installation

npm install -g @bradygaster/squad-cli

Initialize in Your Project

cd your-project
git init  # if not already a repo
squad init

This creates .squad/team.md in your project root.

Authenticate GitHub

gh auth login
gh auth status  # verify: "Logged in to github.com"

Launch with Copilot

copilot --agent squad --yolo

Then describe your project to generate the team:

I'm starting a new project. Set up the team.
Here's what I'm building: a recipe sharing app with React and Node.

Core Commands

Command	Description
squad init	Scaffold Squad in the current directory
squad upgrade	Update Squad-owned files; never touches team state
squad status	Show active squad and status
squad triage	Watch issues and auto-triage to team members
squad doctor	Diagnose setup issues
squad nap	Compress, prune, archive context
squad export	Export squad to portable JSON snapshot
squad import <file>	Import squad from export file

Inter-Agent Communication

Agents communicate through shared files in .squad/:

.squad/
├── team.md           # Team composition and roles
├── decisions/        # Shared decision log (architecture records)
├── context/          # Per-member private context
└── handoffs/         # Task handoff documents

Decision records capture architectural choices. Handoffs pass work between agents with structured context (endpoints, schemas, notes).

Context Hygiene

squad nap           # Standard compression
squad nap --deep    # Aggressive pruning
squad nap --dry-run # Preview what would change

Examples

Example 1: Full-Stack Web App Team

A developer initializes Squad for a recipe-sharing application:

cd ~/projects/recipe-app
npm init -y && git init
npm install -g @bradygaster/squad-cli
squad init
copilot --agent squad --yolo

Prompt: "Build a recipe sharing app with React frontend and Express API. I need auth, CRUD for recipes, and image uploads."

Squad creates 4 team members:

• Chef (Lead) — architecture decisions, task breakdown, coordinates others
• Plater (Frontend) — React components, routing, styling with Tailwind
• Saucier (Backend) — Express routes, PostgreSQL models, auth with JWT
• Taster (Tester) — Jest unit tests, Playwright E2E tests, edge cases

Chef breaks the project into GitHub issues and assigns them. Saucier builds the API endpoints and writes a handoff: POST /api/recipes accepts {title, ingredients[], steps[], image} with Bearer auth. Plater picks up the handoff and builds the recipe form. Taster writes tests against both.

Example 2: Research and Documentation Team

A team lead uses Squad for a technical research project:

cd ~/projects/llm-benchmark-report
git init && squad init
copilot --agent squad --yolo

Prompt: "Research and write a comprehensive report on LLM inference optimization techniques. Cover quantization, KV-cache, speculative decoding, and batching strategies."

Squad creates:

• Scout (Researcher) — gathers papers, benchmarks, and implementations
• Analyst — processes benchmark data, creates comparison tables
• Scribe (Writer) — produces the report with proper citations
• Editor (Reviewer) — fact-checks claims, ensures consistency

Scout logs a decision record: "Focus on open-weight models (Llama 3, Mistral) for reproducible benchmarks." Analyst creates comparison tables showing throughput vs. latency tradeoffs. Scribe drafts each section. Editor reviews for accuracy and flags unsupported claims. The final report lives in docs/report.md with all sources cited.

Guidelines

• Start small with 2-3 team members and add specialists as the project grows
• Give each agent a well-defined scope to avoid overlapping work
• Use the decisions/ directory for architectural choices to prevent conflicts
• Enable auto-triage with squad triage --interval 5 to keep work flowing
• Run squad export regularly to create snapshots for backup and sharing
• Use squad nap periodically to keep context fresh and within limits
• Run squad doctor if GitHub integration or agent communication breaks
• See GitHub Repository for full documentation