Squads
Squads are isolated team sandboxes where multiple agents collaborate under a shared constitution. Each squad has its own workspace, tickets, and rules defined in a SQUAD.md file.
Why Use Squads?
- Isolation — Each squad has its own sandbox environment
- Shared context — Agents in a squad share the same workspace
- Team rules — SQUAD.md defines roles, workflows, and policies
- Organization — Group related agents by function or project
Create a Squad
ayo squad create support-team -a @triager,@responder,@escalator
This creates:
~/.local/share/ayo/sandboxes/squads/support-team/
├── SQUAD.md # Team constitution
├── workspace/ # Shared workspace
└── .tickets/ # Squad-specific tickets
The SQUAD.md Constitution
Every squad has a SQUAD.md that defines how the team operates:
# Customer Support Squad
## Mission
Provide fast, accurate, empathetic customer support.
## Roles
### @triager
- Categorize incoming messages: billing, technical, general, spam
- Assign priority 1-5 (1=urgent)
- Route to @responder or @escalator based on complexity
### @responder
- Handle routine inquiries (priority 3-5)
- Use templates from /workspace/templates/
- Escalate if issue requires account access
### @escalator
- Handle complex issues (priority 1-2)
- Has elevated permissions for account lookup
- Coordinate with internal teams via notes
## Workflow
1. @triager processes incoming messages
2. Creates tickets with category, priority, and routing
3. @responder or @escalator picks up assigned tickets
4. Response drafted → ticket closed
## Policies
- Response time: urgent < 1hr, important < 4hr
- Escalate any legal or security issues immediately
- Never share customer data in logs
This constitution is automatically injected into every agent's context when they work within the squad.
Start a Squad
ayo squad start support-team
This spins up the squad's sandbox environment.
Work Within a Squad
Send work to a specific agent in the squad:
cat messages.json | ayo @triager --squad support-team "Process these"
List Squads
ayo squad list
View Squad Details
ayo squad show support-team
Example: Document Processing Squad
# Create the squad
ayo squad create doc-team -a @classifier,@extractor,@validator,@filer
# Edit the constitution
$EDITOR ~/.local/share/ayo/sandboxes/squads/doc-team/SQUAD.md
SQUAD.md:
# Document Processing Squad
## Roles
### @classifier
- Identify document type: invoice, contract, receipt, correspondence
- Route to @extractor with type metadata
### @extractor
- Extract key fields based on document type
- Invoice: vendor, amount, date, line items
- Contract: parties, terms, dates, obligations
### @validator
- Check extracted data for completeness
- Verify amounts and dates are reasonable
- Flag anomalies for human review
### @filer
- Organize documents into appropriate directories
- Naming convention: {type}_{date}_{vendor}.pdf
## Workflow
classifier → extractor → validator → filer
Shared Workspace
Agents in a squad share a /workspace directory. Use it for:
- Templates and reference documents
- Intermediate outputs between agents
- Shared configuration files