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.

Your Squad team lives entirely inside a .squad/ directory committed to your git repository. There are no external services, no syncing required, and no accounts to manage — just markdown files that travel with your code. Each agent on the team has two files: a charter.md that defines its identity, role, and voice, and a history.md that accumulates what it has learned specifically about your project. When you clone the repo, you get the full team — names, knowledge, and all.

​
Team Composition

team.md is the team roster. It lists every active member, their role, and a brief description. The coordinator reads this file to know who is available for dispatch. Each agent lives under .squad/agents/{name}/, containing: 
.squad/
└── agents/
    ├── flight/
    │   ├── charter.md   # Identity, role, expertise, voice
    │   └── history.md   # What Flight knows about YOUR project
    ├── eecom/
    │   ├── charter.md
    │   └── history.md
    └── scribe/
        └── charter.md   # The silent memory manager

​
Charter structure

Here is a real charter from the Squad project itself — the flight agent who owns architecture and product direction: 
# Flight — Lead

> Architecture patterns that compound — decisions that make future features easier.

## Identity

- **Name:** Flight
- **Role:** Lead
- **Expertise:** Product vision, architecture, code review, trade-offs
- **Style:** Decisive. Opinionated when it matters. Sees the whole picture.

## What I Own

- Product direction and architectural decisions
- Code review and quality gates
- Scope and trade-off analysis
- Reviewer rejection enforcement

## How I Work

- Architecture decisions compound — every choice should make future features easier
- Proposal-first: meaningful changes need docs/proposals/ before code
- Silent success mitigation is real — enforce RESPONSE ORDER in spawn templates
- Reviewer rejection lockout: if I reject, original author is locked out

## Boundaries

**I handle:** Architecture, product direction, code review, scope decisions, trade-offs.

**I don't handle:** Implementation details, test writing, docs, distribution, security audits.

## Model

Preferred: auto
A charter captures four things: role (the agent’s function on the team), expertise (specific domains and technologies), voice/tone (how the agent communicates), and ownership areas (what the agent is responsible for and what it explicitly does not touch).

​
Routing

routing.md maps categories of work to specific agents. The coordinator reads this file and uses it to decide which agents to spawn when you give a task. Here is an excerpt from a real routing.md: 
# Routing Rules

## Work Type → Agent

| Work Type | Agent | Examples |
|-----------|-------|---------|
| Core runtime | EECOM 🔧 | CopilotClient, adapter, session pool, tools module |
| Prompt architecture | Procedures 🧠 | Agent charters, spawn templates, coordinator logic |
| Type system | CONTROL 👩‍💻 | Discriminated unions, generics, tsconfig, strict mode |
| Tests & quality | FIDO 🧪 | Test coverage, Vitest, edge cases, CI/CD, quality gates |
| Docs & messaging | PAO 📣 | README, API docs, getting-started, demos |
| Architecture & review | Flight 🏗️ | Product direction, architectural decisions, code review |
| Security & PII | RETRO 🔒 | Hook design, PII filters, security review, compliance |
| Aspire & observability | Telemetry 🔭 | Aspire dashboard, OTLP integration, Docker telemetry |

## Routing Principles

1. **Eager by default** — spawn agents who could usefully start work in parallel.
2. **Scribe always runs** after substantial work, always as background. Never blocks.
3. **Quick facts → coordinator answers directly.** Don't spawn for trivial questions.
4. **"Team, ..." → fan-out.** Spawn all relevant agents in parallel.
The coordinator uses routing entries to dispatch work without requiring you to address agents by name. You can say “Team, build the login page” and the coordinator matches that request to the relevant routing rules and spawns the appropriate agents simultaneously.

​
Agent History

history.md is what an agent has learned about your specific project. It is written by the Scribe agent after sessions and accumulates over time — conventions you follow, architectural decisions you have made, preferences you have expressed, patterns that are specific to your codebase. After a few sessions, agents stop asking questions they have already answered. They know your test framework, your naming conventions, your deployment targets, your coding style. This context does not reset between sessions because it lives in a file.
Commit .squad/ to git. Anyone who clones your repository gets the full team with all accumulated knowledge — the same named agents, the same history, the same routing rules. New contributors are immediately working with an informed team rather than starting from scratch.

​
Adding a New Team Member

1

Use squad init (recommended)

Run squad init at any time. It is idempotent — it adds new members without modifying existing agent files or history.
squad init
Use --preset default for a fully-configured squad without the interactive walkthrough.
2

Use SDK-first mode

Define new agents in squad.config.ts and regenerate:
// squad.config.ts
import { defineSquad, defineTeam, defineAgent } from '@bradygaster/squad-sdk';

export default defineSquad({
  team: defineTeam({ name: 'Platform Squad', members: ['@edie', '@mcmanus'] }),
  agents: [
    defineAgent({ name: 'edie', role: 'TypeScript Engineer', model: 'claude-sonnet-4' }),
    defineAgent({ name: 'mcmanus', role: 'DevRel', model: 'claude-haiku-4.5' }),
  ],
});
Then run squad build to generate the markdown files.
3

Add manually

Create the directory and files directly:
mkdir -p .squad/agents/myagent
touch .squad/agents/myagent/charter.md
touch .squad/agents/myagent/history.md
Write the charter following the structure above, then add the agent to .squad/team.md and a routing entry in .squad/routing.md.

​
Agent Roles

Roles affect how the casting engine assigns names and how the coordinator routes work. The built-in roles are:

lead

Product vision, architecture, code review, scope and trade-off analysis. The coordinator.

developer

Implementation. Writes production code across whatever stack the project uses.

tester

Test coverage, edge cases, CI/CD validation, quality gates, adversarial testing.

scribe

Silent memory manager. Writes history files, logs decisions, archives session output. Always runs in background mode.

reviewer

Code review. Reviewer rejection authority — if a reviewer rejects, the original author is locked out.

security

Hook design, PII filters, security review, compliance, secret management.

designer

Interaction design, copy, spacing, affordances, UX gates, brand, design system.

devops

Build pipelines, CI/CD, infrastructure, deployment automation, and operational tooling.

prompt-engineer

Prompt architecture, spawn templates, coordinator logic, and agent persona design.
Roles are used by the casting engine when assigning names from a universe and by the routing engine when selecting agents for a task. See the Casting guide for details on how roles map to names.

​
Personal Squad

You can maintain a personal squad that travels across all your projects — handy for freelancers, consultants, or anyone who wants consistent agent personalities regardless of which repository they are working in. 
# Initialize a personal squad in ~/.squad/
squad init --global

# Upgrade your personal squad
squad upgrade --global

# Check which squad is active
squad status
Personal squads live at ~/.squad/ and are activated when no project-level .squad/ directory is found. Project-level squads always take precedence.

​
Parallel Execution

When you address the team, the coordinator launches every relevant agent simultaneously rather than sequentially. Work that can be done in parallel gets done in parallel: 
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...             ⎦
The coordinator respects routing principles: agents who can usefully start immediately are spawned without waiting for upstream agents to finish. The tester, for example, can start writing test cases from requirements at the same time the developer is writing the implementation.

​
Inspectability

Squad keeps a complete audit trail of what happened in each session:
Every decision any agent makes is written to .squad/decisions/. The Scribe consolidates these into a shared decisions.md that all agents read at the start of sessions. This is the team’s shared memory — a log of every architectural choice, convention adopted, and direction set.
Records what was spawned, why it was spawned, what routing rule matched, and what happened. If you want to understand why the coordinator dispatched a particular combination of agents, this is where to look.
Full session history, searchable. Every message exchange with every agent is archived here. Sessions are written incrementally so you never lose context even if a session ends unexpectedly.
Everything is plain text and git-trackable. You can grep it, git log it, diff it across branches, and review it in any editor.

Build docs developers (and LLMs) love

Get started for freeTalk to us