Squad

AI agent teams for any project. A team that grows with your code.

---

What is Squad?

Squad gives you an AI development team through GitHub Copilot. Describe what you're building. Get a team of specialists — frontend, backend, tester, lead — that live in your repo as files. They persist across sessions, learn your codebase, share decisions, and get better the more you use them.

It's not a chatbot wearing hats. Each team member runs in its own context, reads only its own knowledge, and writes back what it learned.

---

Quick Start

1. Create your project

mkdir my-project && cd my-project
git init

2. Install Squad

npx github:bradygaster/squad

3. Open Copilot and go

copilot

Select Squad (vX.Y.Z) from the /agents list, then:

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

Squad proposes a team — each member named from a persistent thematic cast. You say yes. They're ready.

---

Agents Work in Parallel — You Catch Up When You're Ready

Squad doesn't work on a human schedule. When you give a task, the coordinator launches every agent that can usefully start — simultaneously. Frontend, backend, tests, architecture — all at once.

You: "Team, build the login page"

  🏗️ Lead — analyzing requirements...          ⎤
  ⚛️ Frontend — building login form...          ⎥ all launched
  🔧 Backend — setting up auth endpoints...     ⎥ in parallel
  🧪 Tester — writing test cases from spec...   ⎥
  📋 Scribe — logging everything...             ⎦

When agents finish, the coordinator immediately chains follow-up work — tests reveal edge cases, the backend agent picks them up, no waiting for you to ask. If you step away, a breadcrumb trail is waiting when you get back:

• decisions.md — every decision any agent made, merged by Scribe
• orchestration-log/ — what was spawned, why, and what happened
• log/ — full session history, searchable

Knowledge compounds across sessions. Every time an agent works, it writes lasting learnings to its history.md. After a few sessions, agents know your conventions, your preferences, your architecture. They stop asking questions they've already answered.

	🌱 First session	🌿 After a few sessions	🌳 Mature project
⚛️ Frontend	Project structure, framework choice	Component library, routing, state patterns	Design system, perf patterns, a11y conventions
🔧 Backend	Stack, database, initial endpoints	Auth strategy, rate limiting, SQL preferences	Caching layers, migration patterns, monitoring
🏗️ Lead	Scope, team roster, first decisions	Architecture trade-offs, risk register	Full project history, tech debt map
🧪 Tester	Test framework, first test cases	Integration patterns, edge case catalog	Regression patterns, coverage gaps, CI pipeline
📋 Scribe	First session logged	Cross-team decisions propagated	Full searchable archive of every session and decision
🔄 Ralph	Board check after first batch	Auto-triage, CI monitoring	Continuous backlog processing, zero idle time

Each agent's knowledge is personal — stored in its own history.md. Team-wide decisions live in decisions.md, where every agent reads before working. The more you use Squad, the less context you have to repeat.

And it's all in git. Anyone who clones your repo gets the team — with all their accumulated knowledge.

---

How It Works

The Key Insight

Each agent gets its own context window. The coordinator is thin. Each agent loads only its charter + history. No shared bloat.

graph TB
    U["🧑‍💻 You"] -->|"Team, build the login page"| C["GitHub Copilot"]

    subgraph team [" 🏢 The Team "]
        direction LR
        A["🏗️ Lead"]
        K["⚛️ Frontend"]
        R["🔧 Backend"]
        T["🧪 Tester"]
    end

    C -->|spawns| A
    C -->|spawns| K
    C -->|spawns| R
    C -->|spawns| T
    C -.->|silent| S["📋 Scribe"]
    C -.->|monitors| RL["🔄 Ralph"]

    subgraph memory [" 🧠 Shared Memory "]
        direction LR
        D["decisions.md"]
        L["log/"]
    end

    A & K & R & T -->|read & write| D
    S -->|merges & logs| D
    S -->|writes| L

    A -->|learns| HA["history.md"]
    K -->|learns| HK["history.md"]
    R -->|learns| HR["history.md"]
    T -->|learns| HT["history.md"]

    style U fill:#000,color:#fff,stroke:#333
    style C fill:#000,color:#fff,stroke:#333
    style A fill:#000,color:#fff,stroke:#333
    style K fill:#000,color:#fff,stroke:#333
    style R fill:#000,color:#fff,stroke:#333
    style T fill:#000,color:#fff,stroke:#333
    style S fill:#000,color:#fff,stroke:#333
    style D fill:#000,color:#fff,stroke:#333
    style L fill:#000,color:#fff,stroke:#333
    style HA fill:#000,color:#fff,stroke:#333
    style HK fill:#000,color:#fff,stroke:#333
    style HR fill:#000,color:#fff,stroke:#333
    style HT fill:#000,color:#fff,stroke:#333
    style team fill:none,stroke:#fff,stroke-width:2px,stroke-dasharray:5 5
    style memory fill:none,stroke:#fff,stroke-width:2px,stroke-dasharray:5 5

Loading

Context Window Budget

Real numbers. No hand-waving.

Both Claude Sonnet 4 and Claude Opus 4 have a 200K token standard context window. Each agent runs in its own window, so the coordinator is the only shared overhead.

What	Tokens	% of 200K context	When
Coordinator (squad.agent.md)	~13,200	6.6%	Every message
Agent at Week 1 (charter + seed history + decisions)	~1,250	0.6%	When spawned
Agent at Week 4 (+ 15 learnings, 8 decisions)	~3,300	1.7%	When spawned
Agent at Week 12 (+ 50 learnings, 47 decisions)	~9,000	4.5%	When spawned
Remaining for actual work	~187,000	93%+	Always

The coordinator uses 6.6% of context. A 12-week veteran agent uses 4.5% — but in its own window, not yours. That leaves 93%+ of the coordinator's context for reasoning about your code, and each spawned agent gets nearly its entire 200K window for the actual task. Fan out to 5 agents and you're working with ~1M tokens of total reasoning capacity — without paying for a larger model.

Memory Architecture

Layer	What	Who writes	Who reads
charter.md	Identity, expertise, voice	Squad (at init)	The agent itself
history.md	Project-specific learnings	Each agent, after every session	That agent only
decisions.md	Team-wide decisions	Any agent	All agents
log/	Session history	Scribe	Anyone (searchable archive)

---

What Gets Created

.ai-team/
├── team.md              # Roster — who's on the team
├── routing.md           # Routing — who handles what
├── decisions.md         # Shared brain — team decisions
├── casting/
│   ├── policy.json      # Casting configuration
│   ├── registry.json    # Persistent name registry
│   └── history.json     # Universe usage history
├── agents/
│   ├── {name}/          # Each agent gets a persistent cast name
│   │   ├── charter.md   # Identity, expertise, voice
│   │   └── history.md   # What they know about YOUR project
│   ├── {name}/
│   │   ├── charter.md
│   │   └── history.md
│   └── scribe/
│       └── charter.md   # Silent memory manager
└── log/                 # Session history

Commit this folder. Your team persists. Names persist. Anyone who clones gets the team — with the same cast.

---

Growing the Team

Adding Members

> I need a DevOps person.

Squad generates a new agent, seeds them with project context and existing decisions. Immediately productive.

Removing Members

> Remove the designer — we're past that phase.

Agents aren't deleted. Their charter and history move to .ai-team/agents/_alumni/. Knowledge preserved, nothing lost. If you need them back later, they remember everything.

---

Reviewer Protocol

Team members with review authority (Tester, Lead) can reject work. On rejection, the reviewer may require:

• A different agent handles the revision (not the original author)
• A new specialist is spawned for the task

The Coordinator enforces this. No self-review of rejected work.

---

What's New in v0.3.0

• Per-Agent Model Selection — Cost-first routing: code work gets standard-tier models (claude-sonnet-4.5), non-code tasks use fast/cheap models (claude-haiku-4.5). 16-model catalog with fallback chains.
• Ralph — Work Monitor — Built-in squad member that autonomously processes backlogs. Self-chaining work loop: scan GitHub → spawn agents → collect results → repeat.
• @copilot Coding Agent — GitHub's Copilot agent as a squad member. Three-tier capability profile. Auto-assign with workflow.
• Universe Expansion — 14 → 20 casting universes (Succession, Severance, Lord of the Rings, Attack on Titan, Doctor Who, Monty Python)
• Milestones Rename — "Sprints" → "Milestones" (GitHub-native alignment)
• Test Growth — 92 → 118 tests
• Emoji Fixes — Test suite encoding standardized

---

What's New in v0.2.0

• Export & Import CLI — Portable team snapshots for moving squads between repos
• GitHub Issues Mode — Issue-driven development with gh CLI integration
• PRD Mode — Product requirements decomposition into work items
• Human Team Members — Mixed AI/human teams with routing
• Skills System — Earned knowledge with confidence lifecycle
• Tiered Response Modes — Direct/Lightweight/Standard/Full response depth
• Smart Upgrade — Version-aware upgrades with migrations

---

Issue Assignment & Triage

Squad integrates with GitHub Issues. Label an issue with squad to trigger triage, or assign directly to a member with squad:{name}.

How It Works

1. Label an issue squad — the Lead auto-triages it: reads the issue, determines who should handle it, applies the right squad:{member} label, and comments with triage notes.

2. squad:{member} label applied — the assigned member picks up the issue in their next Copilot session (or automatically if Copilot coding agent is enabled).

3. Reassign — remove the current squad:* label and add a different member's label.

Labels

Labels are auto-created from your team roster via the sync-squad-labels workflow:

Label	Purpose
squad	Triage inbox — Lead reviews and assigns
squad:{name}	Assigned to a specific squad member
squad:copilot	Assigned to @copilot for autonomous coding agent work

Labels sync automatically when .ai-team/team.md changes, or you can trigger the workflow manually.

Workflows

Squad installs three GitHub Actions workflows:

Workflow	Trigger	What it does
sync-squad-labels.yml	Push to .ai-team/team.md, manual	Creates/updates squad:* labels from roster
squad-triage.yml	squad label added to issue	Lead triages and assigns squad:{member} label
squad-issue-assign.yml	squad:{member} label added	Acknowledges assignment, queues for member

Prerequisites

• GitHub Actions must be enabled on the repository
• The GITHUB_TOKEN needs issues: write and contents: read permissions
• For @copilot auto-assign: a classic PAT with repo scope stored as COPILOT_ASSIGN_TOKEN repo secret (see setup guide)
• For automated issue work: Copilot coding agent must be enabled on the repo

Session Awareness

The coordinator checks for open squad:{member} issues at session start and will mention them: "Hey {user}, {AgentName} has an open issue — #42: Fix auth endpoint timeout. Want them to pick it up?"

---

Install

npx github:bradygaster/squad

See Quick Start for the full walkthrough.

Upgrade

Already have Squad? Update Squad-owned files to the latest version without touching your team state:

npx github:bradygaster/squad upgrade

This overwrites squad.agent.md, .ai-team-templates/, and squad workflow files in .github/workflows/. It never touches .ai-team/ — your team's knowledge, decisions, and casting are safe.

---

Known Limitations

• Experimental — API and file formats may change between versions
• Node 22+ — requires Node.js 22.0.0 or later (engines field enforced)
• GitHub Copilot CLI — Squad runs on GitHub Copilot; no other runtimes are supported
• Knowledge grows with use — the first session is the least capable; agents improve as they accumulate history

---

Status

🟣 Experimental — v0.3.0. Contributors welcome.

Conceived by @bradygaster.