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
                                                            ↓
                  Merge PR  ←  Review feedback  ←  Agent opens PR

Prerequisite: Install and authenticate the gh CLI (gh auth login). Squad uses it for all GitHub operations.

Label Taxonomy

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

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

graph TD
    A["New issue"] --> B["squad label"]
    B --> C["Triage"]
    C --> D["Lead assigns<br/>go:* + type:* + priority:*"]
    D --> E["go:yes →<br/>squad:{member} assigned"]
    E --> F["Agent works"]
    F --> G["Draft PR"]
    G --> H["Review"]
    H --> I{Approved?}
    I -->|Yes| J["Merge"]
    I -->|No| H
    J --> K["Issue closed"]

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

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

What Ralph Monitors

Ralph never stops on his own while work remains — he keeps cycling until the board clears, you say “idle”, or the session ends. Every 3–5 rounds he posts a status update and keeps going.

Three Layers of Ralph

The heartbeat workflow (squad-heartbeat.yml) is installed during init or upgrade. It runs every 30 minutes by default, on issue close, on PR merge, and on manual dispatch. Edit the cron schedule in .github/workflows/squad-heartbeat.yml to fit your cadence.

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

The flow:

1. Skill (human-notification) tells agents when to ping
2. Agent invokes your configured MCP server
3. MCP server (Teams, Discord, iMessage, webhook) delivers the message

Configure in .vscode/mcp.json or .copilot/mcp-config.json. See the MCP setup section in Portability & Extensions for configuration details.

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.