Skip to content

docs: concepts banner removal, nav restructure, build test sync (WS-B) #1571

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bradygaster merged 1 commit into from
Aug 3, 2026
Merged

docs: concepts banner removal, nav restructure, build test sync (WS-B) #1571

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 49 additions & 71 deletions docs/src/content/docs/concepts/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,71 +1,49 @@
# Architecture

> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.

How Squad works — one page, no handwaving.

---

## System diagram

```
User request
↓
Coordinator (routing engine)
↓
Spawns agents in parallel
↓
Agents read memory (.squad/) → work → write results
↓
Scribe merges decisions, Ralph tracks issues
↓
Results returned to user
```

---

## Components

### Coordinator

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.

### Agents

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.

### Memory (.squad/)

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.

### Routing

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.

### Scribe

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`.

### Ralph

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.

---

## What happens when you say "Team, build X"?

1. **Coordinator reads the request** and checks `.squad/routing.md` for decomposition rules.
2. **Coordinator spawns multiple agents in parallel** — one for frontend, one for backend, one for tests, etc.
3. **Each agent reads `.squad/decisions.md`** and their own history (`agents/{name}/history.md`), then works independently.
4. **Agents write results** to their history files and propose decisions.
5. **Scribe merges all decisions** into `.squad/decisions.md`.
6. **Coordinator returns labeled results** to you, tagged with each agent's name.

---

## Learn more

- [**Your Team**](./your-team.md) — How agents form, specialize, and work together
- [**Work routing**](../features/routing.md) — How the coordinator decides which agents to spawn
- [**Memory and knowledge**](memory-and-knowledge.md) — How decisions, skills, and history persist
- [**Parallel work**](parallel-work.md) — How agents work simultaneously without conflicts
# Architecture
How Squad works — one page, no handwaving.

---
## System diagram
```
User request
↓
Coordinator (routing engine)
↓
Spawns agents in parallel
↓
Agents read memory (.squad/) → work → write results
↓
Scribe merges decisions, Ralph tracks issues
↓
Results returned to user
```

---
## Components
### Coordinator
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.
### Agents
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.
### Memory (.squad/)
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.
### Routing
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.
### Scribe
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`.
### Ralph
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.

---
## What happens when you say "Team, build X"?
1. **Coordinator reads the request** and checks `.squad/routing.md` for decomposition rules.
2. **Coordinator spawns multiple agents in parallel** — one for frontend, one for backend, one for tests, etc.
3. **Each agent reads `.squad/decisions.md`** and their own history (`agents/{name}/history.md`), then works independently.
4. **Agents write results** to their history files and propose decisions.
5. **Scribe merges all decisions** into `.squad/decisions.md`.
6. **Coordinator returns labeled results** to you, tagged with each agent's name.

---
## Learn more
- [**Your Team**](./your-team.md) — How agents form, specialize, and work together
- [**Work routing**](../features/routing.md) — How the coordinator decides which agents to spawn
- [**Memory and knowledge**](memory-and-knowledge.md) — How decisions, skills, and history persist
- [**Parallel work**](parallel-work.md) — How agents work simultaneously without conflicts
64 changes: 1 addition & 63 deletions docs/src/content/docs/concepts/github-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,21 @@
# GitHub Integration

> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.


Squad plugs directly into your GitHub workflow — issues become branches, branches become PRs, PRs become merged code. No context-switching, no copy-paste, no ticket juggling. Just tell your squad what to build and watch the commits roll in.

---

## Try This

```
Connect to myorg/myrepo and show me the backlog
```

```
Work on issue #42
```

```
Ralph, go — process the backlog until it's clear
```

---

## How It Works

The lifecycle is simple: **connect → backlog → work → PR → merge**.

```
Connect repo → Show backlog → Assign issues → Agent branches + implements
↓
Expand All @@ -46,13 +35,9 @@ Connect repo → Show backlog → Assign issues → Agent branches + imple
**Prerequisite:** Install and authenticate the `gh` CLI (`gh auth login`). Squad uses it for all GitHub operations.

---

## Working with your team

Squad is built for mixed teams — humans set direction, AI agents execute and report back. The Lead agent bridges between them, routing work and surfacing decisions when a human needs to act.

### Humans in the lifecycle

The following is **one example** of how a mixed team might divide responsibilities. Your team decides its own process — use [ceremonies](../features/ceremonies.md) and [directives](../features/human-team-members.md) to shape the workflow that fits.

| Stage | Who acts | What happens |
Expand All @@ -64,17 +49,12 @@ The following is **one example** of how a mixed team might divide responsibiliti
| **Merge** | Human or Ralph | Squash-merge, branch cleanup, issue closed |

This is a starting point. Define your own checkpoints by configuring [ceremonies](../features/ceremonies.md) and capturing [directives](../features/human-team-members.md).

For details on how work routes to humans, see [Human team members](../features/human-team-members.md).

For ceremony details, see [Ceremonies](../features/ceremonies.md).

For agent anatomy and how each team member (AI, human, @copilot) is structured, see [your-team.md](your-team.md).

---

## Label Taxonomy

Labels aren't just tags — they're Squad's **state machine**. Five namespaces drive workflow automation, routing, and lifecycle tracking.

| Namespace | Purpose | Example Values | Mutual Exclusivity |
Expand All @@ -88,16 +68,12 @@ Labels aren't just tags — they're Squad's **state machine**. Five namespaces d
Within `go:`, `release:`, `type:`, and `priority:`, applying a second label **auto-removes** the first. The `squad:{member}` namespace allows multiple labels for collaborative work.

### How Labels Drive Automation

Labels power four automation layers:

1. **Enforcement** — `label-enforcement.yml` watches for changes and removes duplicates within a namespace.
2. **Sync** — Cross-namespace cascading: `go:no` → auto-adds `release:backlog`; `priority:p0` → ensures `go:yes`.
3. **Triage** — Ralph uses labels to route work: `squad:fenster` → Fenster picks it up; no `squad:*` + `type:bug` → routes based on `routing.md`.
4. **Heartbeat** — `squad-heartbeat.yml` runs every 30 minutes, auto-triaging unassigned issues and escalating stale research.

### State Machine Flow

```mermaid
graph TD
A["New issue"] --> B["squad label"]
Expand All @@ -112,19 +88,14 @@ graph TD
I -->|No| H
J --> K["Issue closed"]
```

Labels are created automatically during `init` or `upgrade`. Add custom labels with:

```bash
gh label create "squad:designer" --color "0366d6" --description "Work assigned to Designer"
```

---

## Ralph — Work Monitor

Ralph is a built-in squad member who tracks the work queue, monitors CI status, and keeps the team moving. He's always on the roster — no casting required.

### Talking to Ralph

| You say | What happens |
Expand Down Expand Up @@ -153,34 +124,26 @@ Ralph **never stops on his own while work remains** — he keeps cycling until t
|-------|------|-----|
| **In-session** | You're at the keyboard | `"Ralph, go"` — active loop |
| **Local watchdog** | You're AFK but machine is on | `squad watch --interval 10` |
| **Cloud heartbeat** | Fully unattended | `squad-heartbeat.yml` GitHub Actions events |
| **Cloud heartbeat** | Event-driven | `squad-heartbeat.yml` GitHub Actions events |

The heartbeat workflow (`squad-heartbeat.yml`) is installed during `init` or `upgrade`. It runs on issue close, PR merge, and manual dispatch. Edit the workflow in `.github/workflows/squad-heartbeat.yml` to customize triggers. For periodic polling without events, use `squad watch` locally.

**PAT requirement:** Ralph needs `gh` CLI authenticated with a Classic PAT (scopes: `repo` and `project`). The default `GITHUB_TOKEN` doesn't have sufficient scopes.

---

## PRD Mode

Got a product spec? Hand it to Squad and the Lead decomposes it into prioritized, dependency-tracked work items.

```
Read the PRD at docs/product-spec.md and break it into work items
```

The Lead agent:
1. Decomposes the spec into discrete work items (WI-1, WI-2, etc.)
2. Assigns priorities: P0 (must-have), P1 (important), P2 (nice-to-have)
3. Routes items to agents based on domain expertise
4. Tracks dependencies — won't start WI-4 if it depends on WI-2

Independent items run in parallel. When requirements change, give Squad the updated PRD — the Lead diffs against existing items and adjusts the backlog without undoing completed work.

---

## Project Boards

Squad integrates with GitHub Projects V2 for visual workflow tracking. **Labels are the source of truth** — boards are one-way projections that visualize the state machine.

| Board Column | Label State |
Expand All @@ -192,83 +155,58 @@ Squad integrates with GitHub Projects V2 for visual workflow tracking. **Labels
| **Done** | Issue closed |

Board sync runs on label changes, issue close, PR merge, and a 30-minute schedule. Dragging an issue on the board triggers a webhook that applies the corresponding label.

**Status:** Label-based state machine is fully implemented. Automated board sync workflows are in development for v0.4.0. You can use `gh project` commands now — full automation is coming.

---

## Notifications

Your squad pings you when they need input, hit an error, or finish work. Squad uses MCP-based notification servers — you bring your own delivery channel.

See the [Notifications Guide](../features/notifications.md) for [platform setup](../features/notifications.md#quick-start-teams-simplest-path) (Teams, Discord, iMessage, webhooks), [trigger configuration](../features/notifications.md#what-triggers-a-notification), and [sample MCP configs](../features/notifications.md#sample-mcp-configs).

---

## Tips

- You don't need to assign issues to agents — Squad routes based on domain expertise defined in charters and `routing.md`.
- If `gh` isn't authenticated, Squad will tell you. Run `gh auth login` first.
- Use `priority:p0` to fast-track critical items — it auto-sets `go:yes`.
- Combine PRD mode with GitHub Issues to auto-create issues from work items.
- Ralph's in-session loop is session-scoped — state resets between sessions. Use `squad watch` or the heartbeat for persistent monitoring.

---

## Sample Prompts

```
connect to bradygaster/squad and show me the backlog
```

Links Squad to a GitHub repo and displays all open issues.

```
work on all issues labeled "bug"
```

Processes multiple bug issues in parallel — each gets its own branch and PR.

```
mark issue #42 as approved for v0.4.0
```

Applies `go:yes` and `release:v0.4.0` labels, removing any conflicting labels.

```
Ralph, go — start monitoring and process the backlog until it's clear
```

Activates Ralph's self-chaining loop to continuously triage, assign, and process work.

```
read the PRD at docs/product-spec.md and break it into work items
```

Ingests a product spec and creates a prioritized, dependency-tracked backlog.

```
there's review feedback on PR #24
```

The author agent reads review comments and pushes fixes to the existing branch.

```
list all p0 features approved for the next release
```

Queries issues with `priority:p0 + type:feature + go:yes + release:{current milestone}`.

```
squad watch --interval 5
```

Starts persistent local polling — checks GitHub every 5 minutes for new work and triages automatically.

---

## See Also

- [Your Team](./your-team.md) — How work routes to the right agent
- [Work Routing](../features/routing.md) — Domain routing and agent assignment
- [Parallel Work](./parallel-work.md) — Multi-agent parallel execution on batched issues
Loading
Loading