Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bradygaster/squad/llms.txt

Use this file to discover all available pages before exploring further.

Squad is a coordination layer on top of GitHub Copilot that gives each agent an isolated context, a persistent identity, and access to shared memory. Agents are not separate AI models — they are distinct configurations of Copilot, each loaded with its own role definition, project history, and accumulated knowledge. The coordination layer handles routing work to the right agent, recording every decision in a shared log, and persisting state between sessions so the team grows more capable over time. Everything lives in your repository as plain text files, committed to git.

​
Agents

Every agent on your team is defined by two files inside .squad/agents/{name}/:
  • charter.md — the agent’s permanent identity: its role, areas of expertise, preferred working style, and voice. Think of this as the job description that never changes.
  • history.md — what the agent has learned about your specific project: your conventions, your architecture, your preferences, your past decisions. This file grows with every session.
Agents read only their own files. A frontend agent cannot read the backend agent’s history, and vice versa. This isolation prevents context bleed, keeps each specialist sharply focused, and ensures that agents build deep project-specific expertise rather than a blurry averaged understanding.
Knowledge compounds. After a few sessions, agents stop asking questions they’ve already answered. A backend agent that has learned your database schema won’t ask which ORM you use. A frontend agent that has seen your component library won’t propose alternatives. The longer you work with your team, the faster they move.

​
The Team Roster

Two files at the root of .squad/ define the structure of your team:
  • team.md — the roster. It lists every member of the team, their roles, and their current status. The coordinator reads this file to know who is available and what each person is responsible for.
  • routing.md — the dispatch table. It maps work patterns (e.g., testing, documentation, core-runtime) to specific agents. When a task arrives, the coordinator consults routing.md to decide who should handle it. A defaultAgent handles anything that doesn’t match a specific pattern, and a fallback strategy handles edge cases.
Together, these two files give you full control over how work flows through your team without touching any code.

​
Casting

Squad gives agents memorable names drawn from fictional universes — characters from films like The Usual Suspects and Ocean’s Eleven. Names are assigned by the CastingEngine using a deterministic algorithm: the same team configuration always produces the same cast. If you delete your registry and re-run squad init with the same config, you get the same names back. Cast metadata is stored in three files under .squad/casting/: 
.squad/casting/
├── policy.json      # Which universes are allowed, overflow strategy
├── registry.json    # The persistent name-to-role mapping
└── history.json     # Which universes have been used, in what order
The allowlistUniverses setting in your squad.config.ts (or casting/policy.json) controls which fictional universes are eligible. An overflowStrategy of "generic" means that if the team grows beyond the available characters in a universe, agents fall back to generic names rather than breaking. Names are not cosmetic. They provide psychological distinctness — it’s easier to say “ask Fenster to review this” than “ask the Core Dev agent to review this.” They also make the team feel stable across sessions, which encourages teams to think of their agents as persistent collaborators rather than throwaway tools. For more details, see the Casting guide.

​
Skills

Skills are compressed, reusable learnings stored as markdown files in .squad/skills/. A skill captures domain-specific knowledge that is too general to belong in one agent’s history.md but too specific to ship in every agent’s charter. The SkillRegistry matches skills to tasks using trigger keywords and agent role affinity:
  • Trigger matching — each skill declares a list of keyword triggers. When a task description contains those keywords, the skill’s relevance score increases.
  • Role affinity — skills can declare which agent roles they are most useful for. An agent with a matching role gets an affinity bonus when the registry scores that skill.
Skills travel with the team. When you export a squad snapshot with squad export, skills are included in the archive. When you import a squad with squad import, skills are restored alongside agents, routing rules, and decisions. This makes skill libraries portable — you can build up a knowledge base on one project and carry it to the next. For more details, see the Skills guide.

​
Decisions

Every decision any agent makes is appended to .squad/decisions.md. This file is the team’s shared brain — the single source of truth for what has been decided, why, and by whom. All agents can read decisions.md. No agent can unilaterally override a previous decision without appending a new entry. The log is append-only in practice, which means your decision history is auditable, reversible, and always visible in git blame. This design solves a real problem in multi-agent systems: without a shared memory of decisions, agents drift. They re-litigate solved problems, contradict each other on conventions, or silently override choices made in earlier sessions. With decisions.md, the whole team stays aligned across sessions, across agents, and across engineers who may join or leave the project.

​
Ceremonies

.squad/ceremonies.md configures sprint rituals that keep the team synchronized across longer timelines. Ceremonies include:
  • Stand-ups — brief check-ins on what each agent worked on, what’s next, and whether there are blockers
  • Retrospectives — end-of-sprint reviews that feed learnings back into agent history files
  • Planning — scoping new work against the team’s current capacity and priorities
Ceremonies are optional and configurable. They are most useful for teams running Squad in watch mode or on long-running projects where context continuity across days or weeks matters.

​
Watch Mode (Ralph)

Ralph is Squad’s automated triage and dispatch agent. When you run squad triage (aliases: watch, loop), Ralph polls GitHub Issues on a configurable interval, builds a context snapshot of the issue list and current team state, and dispatches agents to work on actionable items. 
# Monitor for issues (triage only — no execution)
squad triage

# Monitor and auto-execute against actionable issues
squad triage --execute --interval 5

# With custom agent runner and Copilot flags
squad triage --execute \
  --agent-cmd "agency copilot" \
  --copilot-flags "--yolo --autopilot --mcp mail --agent squad" \
  --auth-user myaccount
With --execute, Ralph spawns full Copilot sessions to work on issues — it doesn’t just label them. Ralph uses an agent-delegated selection pattern: rather than deciding which issue to work on itself, Ralph builds a rich context file and passes it to the agent, which then decides intelligently under the team’s routing rules, review gates, and escalation policy. Watch mode includes a four-tier error recovery system (circuit breaker reset → auth reprobe → git pull → 30-minute backoff) and supports multiple state persistence backends (git-notes, orphan-branch) so that watch state survives process restarts. Check on a running watch instance at any time: 
squad triage --health
For the full reference, see Watch Mode.

​
Session Persistence

If an agent crashes mid-task or a session is forcibly interrupted, Squad resumes from the last checkpoint on the next run. Sessions are stored in .squad/sessions/. The checkpoint system means you never lose context mid-task — you pick up exactly where you left off. The .squad/log/ directory holds full session history as a searchable archive. You can review what happened in any previous session, which agents were active, what decisions were recorded, and what output was produced.

​
.squad/ directory structure

Here is the complete layout of a fully initialized Squad directory: 
.squad/
├── team.md              # Roster — who's on the team
├── routing.md           # Routing — who handles what
├── decisions.md         # Shared brain — team decisions
├── ceremonies.md        # Sprint ceremonies config
├── casting/
│   ├── policy.json      # Casting configuration
│   ├── registry.json    # Persistent name registry
│   └── history.json     # Universe usage history
├── agents/
│   ├── {name}/
│   │   ├── charter.md   # Identity, expertise, voice
│   │   └── history.md   # What they know about YOUR project
│   └── scribe/
│       └── charter.md   # Silent memory manager
├── skills/              # Compressed learnings from work
├── identity/
│   ├── now.md           # Current team focus
│   └── wisdom.md        # Reusable patterns
└── log/                 # Session history (searchable archive)
Commit this folder. Your team persists. Names persist. Anyone who clones your repository gets the full team — with all their accumulated knowledge and the same cast.

Agents & Teams

Deep-dive into agent charters, history files, team rosters, and routing rules.

Casting

How the CastingEngine assigns names, which universes are supported, and how to customize casting policy.

Skills

Build reusable skill libraries, import and export them, and tune trigger matching for your domain.

Watch Mode

Run Ralph continuously, configure dispatch strategies, set overnight windows, and monitor health.

Build docs developers (and LLMs) love

Get started for freeTalk to us