Using Squad in This Repository

Squad is a multi-agent team orchestrator for GitHub Copilot. It composes specialist AI agents into a coordinated team that lives in your repository, then drives planning and execution through structured workflows.

Getting started

GitHub Agentic Workflows (gh-aw) are composable AI workflows triggered by slash commands in GitHub issues. Squad uses them to orchestrate multi-agent planning and execution directly inside your repository.

Prerequisites

• GitHub CLI (gh) installed and authenticated — install guide
• gh aw extension available (ships with recent gh versions; run gh aw --help to verify)

Install the Squad workflows

Agent action required: If a user asks you to install or set up Squad Agentic Workflows, execute the complete seven-step quick start in their repository. Do not only quote or run the gh aw add command below. The supported path verifies that GitHub Issues are enabled (and enables them when the authenticated user has repository administration permission), configures workflow-created pull requests, installs and validates the complete generated artifact set, commits it on an isolated branch, and opens a human-reviewed bootstrap PR. If disabled Issues cannot be enabled, stop before installation and ask a repository administrator to enable them. /squad commands use issue comments, and bootstrap creates a research/proposals issue. Stop at the bootstrap PR; the human merges it. /squad slash commands become active only after that merge reaches the repository's default branch. The installation PR is a manual trust boundary: its PR-controlled workflow cannot mint a trusted Squad verdict. After merge, require the Cast PR (automatically opened, or manually opened from a signed fallback issue when GITHUB_TOKEN cannot create it) to pass the deterministic relay's native Squad Review / review job, which is authoritative only when it validates the exact trusted automatic run from the base-controlled pull_request_target workflow. Authoritative merge enforcement requires a source-bound required-workflow or equivalent ruleset. Where source binding is unavailable, treat the context as advisory and continue to require an independent human approving review. The relay requires no separate PAT, GitHub App, private key, secret, environment, or external service.

The quick start installs this workflow set:

SQUAD_SHA="<40-character-commit-sha>"  # explicit, maintainer-approved; never `commits/dev`
gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
rm -f .github/skills/agentic-workflows/SKILL.md

The removal is intentional: gh-aw v0.91.5 generates that generic tool-owned router, which loads mutable prompts from the current github/gh-aw repository. It is not Squad-owned or bound to SQUAD_SHA. Keep the exact .github/skills/gh-aw-enlistment/SKILL.md installed by Squad. This repository routes gh-aw work directly through the agentic-workflows-dev specialist in .squad/routing.md, with the local agentic-workflow-designer and gh-aw-reliability skills for design and contract validation. None depends on the deleted router. Retaining a rewritten or pinned copy would make Squad the owner of a forked generic gh-aw prompt router and its upstream corpus; removal preserves the package boundary without vendoring or synchronizing that mutable scaffold.

This command:

1. Fetches the Squad dispatcher, general and dependency workers, independent reviewer with a required-check gate, retrospective, and approval-gated improvement worker
2. Compiles them into GitHub Actions–compatible workflows
3. Adds the workflow sources and generated files to your repository's .github/ directory

Verify installation

After running the command, confirm all eight source/lock pairs exist and strict compilation succeeds: Squad, Implement Worker, Review, Deps Worker, Retro and Improvement Worker, plus the dedicated Bootstrap and Command Router workflows. The improvement worker is standard but dormant until an exact human approval is relayed through the dispatcher. Bootstrap wakes after the installation lands on the default branch and normally creates the linked draft Cast PR and research-proposals issue; if can_approve_pull_request_reviews is false (the recommended setting), GITHUB_TOKEN cannot open that PR, so Bootstrap instead opens a bot-authored fallback issue with a signed provenance record and a ready-to-click compare URL for a human to open the PR manually — Squad Review verifies that record before treating the manual PR as trusted (see the gh-aw guide for the exact conditions).

Retrospectives remain report/proposal-only by default. Ordinary auto-fixes need "squadRetroAutoImplement": "allow" in .squad/config.json. A proposal restricted to eligible Markdown paths under .squad/skills/** or .squad/decisions/inbox/** instead needs /squad approve-improvement, an Approved-Revision: hash and exact Approved-Path: lines. /squad revoke-improvement reserves the human's durable revocation without dispatching. Both workers open drafts, never merge or mark ready. See the gh-aw guide for revision calculation, caps and manual retry.

Try your first command

1. Create a new issue describing what you want to build.
2. Post a comment on that issue:

   /squad cast

3. Squad generates a specialist team tailored to your project and opens a PR with the .squad/ directory.

Usage modes

Once installed, Squad supports two interaction modes:

This guide focuses on the gh-aw approach — the primary mode for agent-driven work. Everything below assumes you've completed the installation steps above.

Where the team lives

.squad/
├── team.md              # Roster, roles, capabilities
├── routing.md           # Work-type → agent mapping
├── decisions.md         # Architectural decisions log
├── casting/
│   └── registry.json    # Agent registry
└── agents/
    └── {name}/
        └── charter.md   # Agent identity, constraints, skills

Slash Commands — Complete Reference

All commands are issued as comments on a GitHub issue. Prefix: /squad.

Team Management

Planning Workflow

The Planning Lifecycle

State Machine

idle
  → researching        (/squad research)
  → triaging           (/squad triage)
  → program_planning   (/squad plan program)
  → implementation_planning  (/squad plan implementation)
  → validating         (/squad plan validate)
  → scope_accepted     (/squad plan accept scope)
  → impl_accepted      (/squad plan accept implementation)
  → activated          (/squad plan activate)

Stage-by-Stage Reference

Idempotency note: Research, triage, plans, and validation can be re-run safely — each re-run replaces the previous artifact. Acceptance and activation are one-way transitions.

Fast Paths vs Granular Commands

Fast path — fewer steps, less control

/squad plan            → generates program + implementation in one pass
/squad plan accept     → accepts scope + implementation + activates

Use when: the intent is clear, the scope is small-to-medium, and you trust the decomposition without intermediate review.

Granular path — more control, full auditability

/squad research
/squad triage
/squad plan program
/squad plan implementation
/squad plan validate
/squad plan accept scope
/squad plan accept implementation
/squad plan activate

Use when: scope is large or ambiguous, you need stakeholder sign-off at each stage, or you want to revise intermediate artifacts before proceeding.

You can mix: use /squad plan for the fast program+implementation pass, then review and /squad plan accept scope and /squad plan accept implementation separately.

What Gets Created in the Repo

.squad/ directory

Created by /squad cast. Contains team state, agent charters, routing rules, and configuration. Delivered as a PR — never committed directly to the default branch.

Labels

• squad — applied to all Squad-managed issues and PRs
• squad:{agent-name} — assigns ownership to a specific team member

Issues

Created during /squad plan activate:

• Epics — high-level work items with sub-issues
• Tasks — PR-sized implementation units linked to epics
• Hierarchy uses GitHub sub-issues when available

Milestones

Created during activation to group epics by delivery phase.

Comments

Structured planning artifacts are posted as human-readable issue comments. gh-aw appends a validated Structured data: JSON block for programmatic identification.

Pull requests

• /squad cast → PR with .squad/ scaffolding
• /squad cast-member → PR adding a new agent
• /squad retire → PR removing an agent

Planning Policy

Squad's planning behavior is configurable through policy profiles.

Built-in Profiles

Selecting a Profile

Add a policy directive line to the issue body:

Squad-Policy: lean

Use a plain visible line — not an HTML comment. gh-aw strips HTML comments from issue bodies before the agent sees them, so a commented directive is silently ignored.

Or configure at the repo level in .squad/planning-policy.md with YAML frontmatter.

Priority Order

1. Issue body (Squad-Policy: ...) — highest
2. Repository file (.squad/planning-policy.md)
3. Profile name (built-in)
4. Default — fallback

Safe-Output Constraints

GitHub Agentic Workflows enforce output limits per run to prevent runaway mutations.

Implications

• All mutations are explicitly declared — no surprise side effects
• If a plan produces more than 20 tasks, activation will create the first 20; re-run to continue
• Allowed branch patterns for PRs: squad/*
• Allowed file patterns for PRs: .squad/**, .github/agents/squad.agent.md, meet-the-squad.md
• Labels [squad] are applied automatically to all created issues and PRs

Structured Data for Programmatic Access

Every planning artifact uses the gh-aw safe-output data envelope:

{
  "squad_artifact": "research",
  "schema_version": "1",
  "origin_issue": 123,
  "phases": []
}

gh-aw appends the envelope as a Structured data: fenced JSON block. phases is empty except on phase-state artifacts, where it contains the accumulated phase numbers. Paginate all comments, parse the JSON, match the current origin_issue and desired squad_artifact, then take the newest match.

HTML comments are not Squad state: gh-aw removes them from compiled prompts and sanitized safe-output bodies. See the planning ontology §4 for the complete artifact registry.