You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 01093e0
Browse filesBrowse the repository at this point in the historyBrowse files
> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
4
+
5
+
How Squad works — one page, no handwaving.
6
+
7
+
---
8
+
9
+
## System diagram
10
+
11
+
```
12
+
User request
13
+
↓
14
+
Coordinator (routing engine)
15
+
↓
16
+
Spawns agents in parallel
17
+
↓
18
+
Agents read memory (.squad/) → work → write results
19
+
↓
20
+
Scribe merges decisions, Ralph tracks issues
21
+
↓
22
+
Results returned to user
23
+
```
24
+
25
+
---
26
+
27
+
## Components
28
+
29
+
### Coordinator
30
+
31
+
The coordinator is Squad's routing engine. It reads your request, checks routing rules in `.squad/routing.md`, and decides which agents to spawn. If you say "team," it decomposes the work and launches multiple agents in parallel. If you name an agent, it routes directly to them.
32
+
33
+
### Agents
34
+
35
+
Each agent is a specialist with a charter, role, and persistent memory. Agents are spawned as independent subprocesses with their own context windows and tools. They read `.squad/decisions.md` and their own history before working, then write results back. Agents never see each other's conversations — the coordinator orchestrates coordination.
36
+
37
+
### Memory (.squad/)
38
+
39
+
All team state lives in `.squad/`. This includes the roster (`team.md`), routing rules (`routing.md`), decisions (`decisions.md`), agent charters and histories (`agents/`), and ceremony schedules (`ceremonies.md`). Agents read this before every spawn. You own these files — edit them anytime.
40
+
41
+
### Routing
42
+
43
+
Routing rules in `.squad/routing.md` define which agent handles which work. The coordinator reads these rules before spawning. You can override routing by naming an agent directly in your request.
44
+
45
+
### Scribe
46
+
47
+
The Scribe is a silent agent that tracks decisions and logs sessions. Every team has a Scribe. You never talk to them directly — they work in the background, merging decisions from all agents into `.squad/decisions.md`.
48
+
49
+
### Ralph
50
+
51
+
Ralph is the work monitor. He watches your GitHub or GitLab issues, tracks work in progress, and alerts the team when something is ready. Every team has a Ralph. He's silent unless you ask him for status.
52
+
53
+
---
54
+
55
+
## What happens when you say "Team, build X"?
56
+
57
+
1.**Coordinator reads the request** and checks `.squad/routing.md` for decomposition rules.
58
+
2.**Coordinator spawns multiple agents in parallel** — one for frontend, one for backend, one for tests, etc.
59
+
3.**Each agent reads `.squad/decisions.md`** and their own history (`agents/{name}/history.md`), then works independently.
60
+
4.**Agents write results** to their history files and propose decisions.
61
+
5.**Scribe merges all decisions** into `.squad/decisions.md`.
62
+
6.**Coordinator returns labeled results** to you, tagged with each agent's name.
63
+
64
+
---
65
+
66
+
## Learn more
67
+
68
+
-[**Work routing**](../features/routing) — How the coordinator decides which agents to spawn
69
+
-[**Memory and knowledge**](memory-and-knowledge) — How decisions, skills, and history persist
70
+
-[**Parallel work**](parallel-work) — How agents work simultaneously without conflicts
const result =awaitcoordinator.route('Build a login page');
54
+
```
55
+
56
+
**Use for:** Building tools on Squad, custom integrations, advanced automation.
57
+
58
+
---
59
+
60
+
## Decision table
61
+
62
+
|**Your goal**|**Use**|
63
+
|---------------|---------|
64
+
| Try Squad quickly |**Copilot agent** — no install |
65
+
| Work in the terminal |**CLI**|
66
+
| Work in VS Code |**Copilot agent**|
67
+
| Automate repetitive tasks |**CLI** or **SDK**|
68
+
| Build custom tooling |**SDK**|
69
+
| CI/CD integration |**CLI** or **SDK**|
70
+
71
+
---
72
+
73
+
## Can I use multiple modes?
74
+
75
+
Yes. Your `.squad/` directory is the source of truth. CLI, Copilot agent, and SDK all read and write the same files. You can switch between modes anytime.
76
+
77
+
Example workflow:
78
+
1. Use **Copilot agent** to form your team and do exploratory work
79
+
2. Use **CLI** (`squad watch`) to monitor issues in the background
80
+
3. Use **SDK** to build a custom deployment script that spawns agents
81
+
82
+
All three modes share the same memory and decisions.
**Scribe** and **Ralph** are always on every roster — you don't manage them.
76
+
75
77
Look right? Say yes, add someone, or change a role.
76
78
(Or just give me a task to start!)
77
79
```
@@ -86,7 +88,7 @@ Say "yes" or skip straight to a task (which is implicit confirmation):
86
88
> Yes. Dallas, set up the Express server with basic routing.
87
89
```
88
90
89
-
Squad creates the `.squad/` directory structure — team roster, routing rules, casting state, ceremony config, agent charters, and histories — all seeded with your project context.
91
+
Squad creates the `.squad/` directory structure — team roster, routing rules, casting state, ceremony config, agent charters, and histories — all seeded with your project context. Each agent spawns to do their work.
90
92
91
93
### What's inside .squad/?
92
94
@@ -177,7 +179,7 @@ At any point, check status:
177
179
> Where are we?
178
180
```
179
181
180
-
This is a Direct mode response — no agent spawn, just the coordinator reading recent logs:
182
+
The coordinator reads recent logs:
181
183
182
184
```
183
185
Last session: Recipe listing page (15 minutes ago)
@@ -274,7 +276,7 @@ squad export
274
276
5 agents, 3 skills, 6 decisions
275
277
```
276
278
277
-
This snapshot contains everything — charters, histories, casting state, skills, and decisions. Import into another repo anytime:
279
+
This snapshot contains charters, histories, casting state, skills, and decisions. Import into another repo anytime:
> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
4
+
5
+
Your first 5 minutes with Squad. Prove it works before you learn anything.
6
+
7
+
---
8
+
9
+
## Prerequisites
10
+
11
+
-**Node.js 20+** — Check with `node --version`
12
+
-**Git repository** — New or existing
13
+
14
+
---
15
+
16
+
## Install
17
+
18
+
```bash
19
+
npm install --save-dev @bradygaster/squad-cli
20
+
```
21
+
22
+
Then initialize:
23
+
24
+
```bash
25
+
npx squad init
26
+
```
27
+
28
+
You'll see:
29
+
30
+
```
31
+
✅ Squad installed.
32
+
.github/agents/squad.agent.md — coordinator agent
33
+
.squad/templates/ — 11 template files
34
+
35
+
Open GitHub Copilot and select Squad from the agent list.
36
+
```
37
+
38
+
---
39
+
40
+
## Validate
41
+
42
+
Check that Squad created your team directory:
43
+
44
+
```bash
45
+
ls .squad/
46
+
```
47
+
48
+
You should see: `team.md`, `routing.md`, `decisions.md`, `agents/`, and more.
49
+
50
+
Confirm Squad is ready:
51
+
52
+
```bash
53
+
npx squad status
54
+
```
55
+
56
+
---
57
+
58
+
## Try it
59
+
60
+
Open GitHub Copilot in your terminal or VS Code. Select **Squad** from the agent list (`/agent Squad` in CLI or `/agents` in VS Code).
61
+
62
+
Say something simple:
63
+
64
+
```
65
+
> I'm building a task management app with React and Node.js.
66
+
> Users can create, update, and delete tasks.
67
+
```
68
+
69
+
Squad forms your team and responds with agent names and roles. Say yes, or just give your first task:
70
+
71
+
```
72
+
> Team, create a basic Express server with a /health endpoint.
73
+
```
74
+
75
+
Squad spawns agents and does the work.
76
+
77
+
---
78
+
79
+
## What just happened?
80
+
81
+
Squad read your description, formed a team of specialists, wrote their charters to `.squad/agents/`, and coordinated parallel work. Check `.squad/decisions.md` to see what they decided.
82
+
83
+
---
84
+
85
+
## Next steps
86
+
87
+
[**Your first session**](first-session) — Step-by-step walkthrough of parallel work, decisions, and memory.
0 commit comments