GitHub Agentic Workflows integration

Squad ships a first-class integration with GitHub Agentic Workflows (gh aw). One slash command in an issue, and you get a custom AI team — delivered as a pull request you can review before merging.

This guide covers setup, every slash command, and daily usage patterns.

Quick start

Seven steps from zero to a validated, reviewable Squad bootstrap:

Agent action required: When a user asks an AI coding agent to install Squad Agentic Workflows, the agent must execute this entire block in the target repository — not merely paste the commands for the user. The block resolves the repository at runtime, installs and validates the workflows, and opens the human-reviewed bootstrap pull request. The agent stops at the pull request; a human reviews and merges it.

set -euo pipefail

# 1. Verify GitHub access, resolve this repo, and install gh-aw if needed
gh auth status
owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
default_branch="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
gh extension list | grep -q 'github/gh-aw' || gh extension install github/gh-aw

# 2. Allow GitHub Actions to create pull requests
gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \
  -f default_workflow_permissions=read \
  -F can_approve_pull_request_reviews=true

# 3. Create a bootstrap branch
git switch -c chore/squad-gh-aw-bootstrap

# 4. Add the complete Squad workflow set from the supported dev channel
SQUAD_WORKFLOW_REF="dev"
gh aw add \
  bradygaster/squad/workflows/squad.md@${SQUAD_WORKFLOW_REF} \
  bradygaster/squad/workflows/squad-implement-worker.md@${SQUAD_WORKFLOW_REF} \
  bradygaster/squad/workflows/squad-review.md@${SQUAD_WORKFLOW_REF} \
  bradygaster/squad/workflows/squad-deps-worker.md@${SQUAD_WORKFLOW_REF} \
  bradygaster/squad/workflows/squad-retro.md@${SQUAD_WORKFLOW_REF} \
  bradygaster/squad/workflows/squad-improvement-worker.md@${SQUAD_WORKFLOW_REF} \
  bradygaster/squad/workflows/squad-bootstrap.md@${SQUAD_WORKFLOW_REF}

# 5. On first install, review the safe-update report.
# If it contains only the documented Squad secrets and init action, approve it:
gh aw compile --strict --approve

# 6. Always run the final strict compile without approval
gh aw compile --strict

# Verify every supported workflow has a source and generated lockfile
for workflow in squad squad-implement-worker squad-review squad-deps-worker squad-retro squad-improvement-worker squad-bootstrap; do
  test -f ".github/workflows/${workflow}.md" || { echo "MISSING ${workflow}.md"; exit 1; }
  test -f ".github/workflows/${workflow}.lock.yml" || { echo "MISSING ${workflow}.lock.yml"; exit 1; }
done

# Verify every local runtime module referenced by those workflows was installed
for runtime_module in squad-cast-validator squad-bootstrap-validator squad-improvement-gate squad-retro-evidence squad-retro-provenance squad-implementation-provenance; do
  test -f ".github/workflows/shared/${runtime_module}.mjs" || {
    echo "MISSING shared/${runtime_module}.mjs"
    exit 1
  }
done

test -f ".github/workflows/shared/implementation-provenance-v1.schema.json" || {
  echo "MISSING shared/implementation-provenance-v1.schema.json"
  exit 1
}

# Strict compilation validates gh-aw's source contract; also reject JSON-escaped
# operators inside emitted GitHub expressions, which GitHub rejects before jobs start.
if grep -nE '\$\{\{[^}]*\\u00(26|3[cCeE])' .github/workflows/*.lock.yml; then
  echo "Invalid JSON-escaped operator in compiled GitHub expression" >&2
  exit 1
fi

# 7. Commit the generated files and open the bootstrap PR
git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
git diff --cached --stat
test -z "$(git diff --cached --diff-filter=D --name-only)"
git commit -m "ci: add Squad agentic workflow"
git push -u origin HEAD
gh pr create \
  --base "$default_branch" \
  --title "ci: add Squad agentic workflow" \
  --body "Installs and strictly compiles the supported Squad GH-AW workflows."
gh pr edit --add-reviewer @copilot
gh pr checks --watch

The quick start uses the supported dev channel so the workflow-installation PR contains the complete seven-workflow set. For a repeatable upgrade, pin all seven entries to one reviewed commit as described in Upgrading the workflows.

Step 7 stages .github/skills/ because gh aw add installs the Squad skills alongside the workflows, and it deliberately does not stage .github/aw/logs/. Downloaded workflow logs are local diagnostic output — see ignoring downloaded logs before you commit.

The bootstrap PR installs the GitHub Agentic Workflow sources, their compiled GitHub Actions lockfiles, the Squad dispatcher and workers, shared assets, and the skills they use. The slash commands are not active from the bootstrap branch alone. After a human reviews and merges that PR into the default branch, the /squad command surface is live.

The merged installation automatically wakes squad-bootstrap. It analyzes the repository once and creates two linked, human-reviewable artifacts from one validated payload:

• a draft Cast PR on squad/bootstrap-cast; and
• [Research Proposals] Agent-discovered repo opportunities.

Review and merge the Cast PR, then rerun /squad triage on the linked issue to classify its existing bootstrap proposals. If a proposal needs deeper or newer evidence, use one of the issue’s focused /squad research ... commands first; that replaces the bootstrap research seed. Review the resulting plan and run /squad activate. The bootstrap journey ends when assignable implementation issues exist.

Prerequisites

Setup

Allow workflow-created pull requests

Squad opens pull requests through GitHub Actions. Enable this repository setting under Settings → Actions → General → Workflow permissions → Allow GitHub Actions to create and approve pull requests.

You can also enable it from the command line while keeping the default workflow token read-only:

owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \
  -f default_workflow_permissions=read \
  -F can_approve_pull_request_reviews=true

Resolve the repository identity at runtime as shown; do not hardcode an example owner or repository. Without this setting, Squad pushes the generated branch but falls back to an issue containing a link for you to create the pull request manually. A manually created pull request is authored by your account, and GitHub does not allow authors to approve their own pull requests.

Create a bootstrap branch

default_branch="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
git switch -c chore/squad-gh-aw-bootstrap

Keep the generated workflow install isolated on this branch until strict compilation and human review are complete.

Install the workflows

gh aw add \
  bradygaster/squad/workflows/squad.md@dev \
  bradygaster/squad/workflows/squad-implement-worker.md@dev \
  bradygaster/squad/workflows/squad-review.md@dev \
  bradygaster/squad/workflows/squad-deps-worker.md@dev \
  bradygaster/squad/workflows/squad-retro.md@dev \
  bradygaster/squad/workflows/squad-improvement-worker.md@dev \
  bradygaster/squad/workflows/squad-bootstrap.md@dev

Keep the dispatcher first. gh aw add discovers its general worker, dependency worker, reviewer, and retrospective dependencies while compiling it; the explicit entries then confirm the complete install surface without creating duplicates. Keep squad-bootstrap last because it is the dedicated post-install workflow, not a dispatcher dependency. The installed top-level workflow set is:

• squad.md and squad.lock.yml
• squad-implement-worker.md and squad-implement-worker.lock.yml
• squad-review.md and squad-review.lock.yml
• squad-deps-worker.md and squad-deps-worker.lock.yml
• squad-retro.md and squad-retro.lock.yml
• squad-improvement-worker.md and squad-improvement-worker.lock.yml
• squad-bootstrap.md and squad-bootstrap.lock.yml

The install must also contain these executable runtime resources:

• shared/squad-cast-validator.mjs
• shared/squad-bootstrap-validator.mjs
• shared/squad-improvement-gate.mjs
• shared/squad-retro-evidence.mjs
• shared/squad-retro-provenance.mjs

The dispatcher declares the complete transitive resource set because gh-aw installs it first, discovers the dependent workflows, and then skips the later explicit worker entries as duplicates. Without that root declaration, a strict compile can succeed while the installed workers fail before the agent starts.

squad-improvement-worker is part of this standard install, not a separate add-on — it stays dormant until a maintainer approves a governance-scoped retrospective proposal (see Retrospective auto-implementation below).

gh aw add also installs the Squad skills under .github/skills/, which is why the bootstrap commit stages that path alongside the workflows.

Branch note: @dev pulls from the latest development branch where new modes and fixes land first. Stay on @dev to get improvements as they ship. Once gh-aw support reaches stable, you can switch to @main or drop the ref entirely for the default branch.

This registers the Squad workflow in your repository’s agentic workflow configuration and compiles the workflow definitions into deterministic .lock.yml files. The supported bootstrap path still runs gh aw compile --strict explicitly before review so every installed source is validated together and the PR contains the exact generated lockfiles that passed.

Strict compilation is necessary but does not prove GitHub will accept every emitted expression. The verification step also scans the lockfiles for JSON-escaped operators such as \u0026 inside ${{ ... }}. If that scan finds anything, stop: GitHub rejects that workflow before any job starts, producing a failed run with no jobs or logs.

Review first-install safe updates

On a clean repository, gh aw add reports these expected safe-update changes:

• Restricted secrets: SQUAD_GITHUB_APP_PRIVATE_KEY and SQUAD_GITHUB_TOKEN
• Action: bradygaster/squad/.github/actions/squad-init

These are referenced names, not prerequisites. gh aw add lists the secrets the workflows reference so you can approve that surface — it is not asking you to supply them. Both secrets are optional, they need not exist, and you do not need to create either one to enlist a repository. Single-repo activation runs on the built-in github.token. Configure these only for cross-repo access or elevated permissions — see enhanced permissions with a GitHub App and PAT fallback.

Review the report before approving it. If it contains only those documented entries, complete the first-install approval with:

gh aw compile --strict --approve

Stop and investigate if the report contains any other secret or action.

This follow-up is only needed when the safe-update warning appears. It is not a substitute for the final strict compile below.

Strictly compile the installed workflows

gh aw compile --strict

Run this exact command after any required first-install approval and before committing. It must report all seven workflows succeeded. squad.md currently emits one known warning because both slash-command and github-actions[bot] triggers are configured; the bot trigger is required for controlled worker continuation dispatches. Any error or any additional warning is a stop condition.

Verify the complete source/lock surface:

for workflow in squad squad-implement-worker squad-review squad-deps-worker squad-retro squad-improvement-worker squad-bootstrap; do
  test -f ".github/workflows/${workflow}.md" || { echo "MISSING ${workflow}.md"; exit 1; }
  test -f ".github/workflows/${workflow}.lock.yml" || { echo "MISSING ${workflow}.lock.yml"; exit 1; }
done

for runtime_module in squad-cast-validator squad-bootstrap-validator squad-improvement-gate squad-retro-evidence squad-retro-provenance; do
  test -f ".github/workflows/shared/${runtime_module}.mjs" || {
    echo "MISSING shared/${runtime_module}.mjs"
    exit 1
  }
done

Open the bootstrap pull request

git add -- .gitattributes .github/aw/ .github/workflows/ .github/skills/
git diff --cached --stat
test -z "$(git diff --cached --diff-filter=D --name-only)"
git commit -m "ci: add Squad agentic workflow"
git push -u origin HEAD
gh pr create \
  --base "$default_branch" \
  --title "ci: add Squad agentic workflow" \
  --body "Installs and strictly compiles the supported Squad GH-AW workflows."
gh pr edit --add-reviewer @copilot
gh pr checks --watch

This stages the workflow sources and lockfiles, the gh-aw manifest and pinned state under .github/aw/, the installed skills, and .gitattributes. Review the complete generated diff in the bootstrap PR, address Copilot review feedback, and wait for required checks. Merge only after human approval.

gh aw add may also create .vscode/settings.json to enable Copilot for Markdown workflow files. The command above intentionally leaves that optional editor setting untracked. Delete it if you do not want the local setting, or stage it explicitly if your team wants to share it.

Troubleshooting: If the lock files are missing, rerun gh aw compile --strict. Do not open or merge the bootstrap PR until all seven source/lock pairs exist and strict compilation succeeds.

Downloaded workflow audit data is local diagnostic output and should not be committed. If a .gitignore is missing from .github/aw/logs/, add one there:

# Ignore all downloaded workflow logs
*

# But keep this file
!.gitignore

Once the bootstrap PR is merged into the default branch, the /squad slash command is live on your repo. Pushing the bootstrap branch or merely opening the PR does not activate the workflow.

Optional: pin a CLI version

Activation downloads a self-contained GitHub Release bundle; it does not install Squad from npm. Set a repository variable to select a specific standalone release:

Set it in Settings → Secrets and variables → Actions → Variables. A value without the leading v is accepted for compatibility with older configurations.

Optional: enhanced permissions with a GitHub App

By default the workflow uses the built-in github.token. For cross-repo access or elevated permissions, configure a GitHub App:

The workflow mints an installation token from these credentials at activation time.

Optional: PAT fallback

If you don’t want to use a GitHub App but need more than the default token, set a Personal Access Token:

Auth precedence: GitHub App token → SQUAD_GITHUB_TOKEN → github.token.

Supported-path validation checklist

Use this checklist for the initial bootstrap and after any workflow update:

If a work command auto-opens a Cast PR because no committed team exists, merge that PR and rerun the original command. Do not start a second Cast command.

Slash commands

Every command starts with /squad. Type it in an issue body, issue comment, or PR conversation comment. On a pull request, post the command in the Conversation tab. Inline code-review threads do not trigger Squad commands.

Commands are matched longest-prefix-first, so the most specific command string wins: /squad plan accept scope is not treated as /squad plan.

Implementation provenance

Every pull request created by the general implementation worker or dependency worker receives a Squad implementation provenance: comment using schema https://bradygaster.github.io/squad/schemas/implementation-provenance/v1. The pre-creation gate validates one strict provenance-record request and all replacement references. After the PR handler returns, a compiled safe-output script resolves the handler’s temporary ID to the actual PR number, re-fetches the created PR and replacement evidence, constructs the authoritative payload from GitHub runtime context, and posts the comment as github-actions[bot]. Consumers and merge-continuation/replacement checks accept provenance only from that bot-authored boundary. No "self" or unresolved temporary identifier is durable evidence. The general worker also keeps the existing standalone <!-- squad:implement issue={issue} run={run} --> marker unchanged for backward compatibility.

The dispatcher posts a bot-authored receipt before each worker dispatch. The worker verifies that receipt, the dispatcher Actions run, repository, run attempt, origin issue, selected worker, and deterministic session identifier before the agent starts. The implementation_session_id is minted by the dispatching squad or squad-retro run as squad-implementation-session/v1/{repository-id}/{dispatcher-run-id}. Treat it as opaque:

• Lifetime: one scheduling wave. All implementation and dependency workers dispatched by that run share the identifier.
• Retries and reruns: rerunning the same dispatcher run or worker preserves the identifier; workflow_run.run_attempt identifies the concrete rerun. A new /squad implement, retrospective reconciliation, or merge-refill dispatcher run starts a new session.
• Multiple pull requests: several PRs may share one session when a parent issue dispatches several ready leaf tasks. Session ID is not a PR ID.
• Replacement pull requests: replaces explicitly lists verified earlier PRs. Each referenced PR must exist in the same repository and carry one valid provenance comment for the same origin issue and session. Duplicate, malformed, nonexistent, or unrelated references fail closed.
• Multiple goals: origin_issue is the primary scheduling goal. goals lists every explicitly referenced issue and whether the PR closes or merely relates to it. A PR may have multiple goals, but it has one origin issue.
• Pull request reference: pull_request.number is always the actual positive integer returned by the PR handler.

Do not derive a missing session identifier from branch names, actors, timestamps, closing text, or textual similarity. A worker started directly by a human cannot mint an identity; it must have the exact bot-authored dispatcher receipt and matching Actions run. Missing provenance means the session is unknown. Consumers may continue to use the legacy implementation marker and closing references as their own explicit correlation sources, and may label branch correlation as inferred, but those sources do not manufacture a session ID.

Compatibility and cache behavior

Repositories upgrading from an older Squad workflow do not need to rewrite old pull requests. Recompile and commit the updated dispatcher, implementation worker, dependency worker, retrospective, shared validator, and schema together. Direct manual dispatches of either worker fail closed; use /squad implement or the retrospective relay so the dispatcher can create the authoritative receipt and bound session inputs.

Where you can use slash commands

For workflow dispatch, go to Actions → Squad → Run workflow and enter the command (for example cast or connect myorg/my-squad).

Retrospective lifecycle

squad-retro runs weekly, wakes every six hours to drain pending requests, and accepts authorized /squad retro relays. Review and implementation workers also send bounded early-evidence wakeups. A deterministic pre-agent gate, not the reasoning model, paginates durable workflow/review evidence, excludes the retro’s own runs and issues, deduplicates retries, and counts distinct run IDs or review revision SHAs.

A failure fingerprint combines the workflow name, the failing job name, and the first error line taken from a bounded excerpt of that job’s log. The head SHA is deliberately excluded so an identical failure matches across revisions. When no error line can be read, the gate records low-confidence evidence that can never qualify on its own, and a transient GitHub API failure produces a visible no-op with a diagnostic instead of a crash, leaving pending requests untouched. Malformed .squad/config.json values still fail the run visibly.

The defaults are two independent attempts within 168 hours and a 72-hour cooldown. Repositories may set squadRetroEarlyThreshold, squadRetroWindowHours, and squadRetroCooldownHours in .squad/config.json, or disable the workflow with "squadRetro": "deny". The full retrospective remains due every fixed 168 hours regardless of the configured evidence window; the six-hour schedule only drains evidence and pending requests between weekly runs. Requests suppressed by cooldown remain as structured comments on the bot-authored squad-retro-state issue; the periodic drain re-evaluates them and expires requests whose evidence aged out only when that kind’s collection is complete. Truncated failed-run collection preserves pending fail: requests; truncated pull-request collection preserves pending review: requests. Reports list these preserved requests separately from expired requests.

State discovery prefers the lowest-numbered open github-actions[bot]-authored issue carrying squad-retro-state. If none exists, a bounded fallback looks for an open issue from that same bot titled exactly Squad retrospective state. The explicit repair_state_label gate adds the missing label and no-ops instead of creating a duplicate; same-title human-authored issues are never trusted. An incomplete state-discovery scan also no-ops rather than risking a duplicate.

Reports and at most five owned action issues are automatic. Changes to .squad/**, .github/**, prompts, charters, routing, or governance remain human-reviewed proposals. The worker cannot edit files, create pull requests, merge, change permissions or secrets, or upgrade Squad.

Retrospective auto-implementation (opt-in)

The standard install contains all seven workflows, including the dormant improvement worker. Report/proposal-only remains the default. The lifecycle is diagnosis → durable action issue → worker → draft PR → human review/merge → later measurement of closure and recurrence. Retro never edits code, creates a PR, merges, marks ready or changes control-plane policy.

Ordinary fixes: explicitly set "squadRetroAutoImplement": "allow" in the existing .squad/config.json. Omission or "deny" disables automatic dispatch; "squadRetro": "deny" disables the entire retrospective. Only open github-actions[bot] action issues with an exact standalone Action-Key: and no squad-retro-proposal label qualify. Existing implementation exclusions for .squad, workflow/agent definitions, manifests and protected files are unchanged. Without opt-in, a human can comment /squad implement on an ordinary action.

The caps are five action issues per report, one report, and three ordinary dispatches per wake-up, independent of one another. A newly created action uses a deterministic unique temporary ID: queued create_issue → add_comment receipt → dispatch_workflow, with the identical quoted "#aw_..." target/input. Existing actions use verified real issue numbers. gh-aw resolves references in dependency order but does not make these writes transactional. A failed create can leave an unresolved dispatch; a failed comment can leave a dispatch without a receipt. The receiver rejects both before implementation. Queuing an output is not successful delivery.

Every receipt records Squad-Retro-Dispatch:, Action-Key: and Dispatch-Run:. The implementation worker verifies the immediate aw_context.workflow_id, repository/default branch, live Actions run/attempt, platform bot actor, live action issue and matching bot receipt. A root-workflow claim or prose marker alone is not provenance. Retro PRs carry their key plus a visible text fence containing <!-- squad:retro-action issue=N action-key=K -->; a bare HTML comment would be removed by the pinned sanitizer. Loop suppression requires independent BOT PR authorship, the exact marker/key, worker branch and trusted source action. Closed source issues still prove provenance after merge; unverifiable claims and labels alone never suppress review/failure evidence.

The six-hour drain reconciles action-owned handoffs even during report cooldown, with no fresh evidence, after report fingerprint resolution, or during a report collection outage. Incoming early requests during cooldown are preserved as durable pending comments. A sealed pre-agent plan constrains outputs; its candidate list is not model judgment. squadRetroAutoImplementRetryHours defaults to 48 (integer 1–720): at most one delayed retry follows the initial receipt. After the second attempt ages out with no PR, a one-time Squad-Retro-Dispatch-Abandoned: comment hands the action to a human. Receipt write outages cannot be counted as successful attempts; the action remains pending rather than pretending delivery succeeded.

Open, merged and closed-unmerged linked implementation PRs suppress automatic duplicates. Branch namespaces or issue-closing references identify links; a bounded incomplete PR scan refuses automation. Nothing reopens or mass-closes issues/PRs. Investigate the refusal and use a human-managed /squad implement or manual fix, not repeated retro-origin dispatches.

Approved improvements: governance findings are proposal-labeled action issues with exact Proposed-Path: lines. Only non-executable Markdown under .squad/skills/** or .squad/decisions/inbox/** is eligible, at most twenty files. Canonical decisions/history, charters, roster/routing/config/casting, .github/**, auth/permissions/secrets/protections, package self-upgrades and worker/gh-aw self-configuration (including their packaged skills) require a manual proposal. The actual am patch is checked with Git’s parser, exact approved paths, file modes and symlink checks; bundles, renames, copies and binary patches are refused. The worker’s .squad/ dot-folder exception only makes its two-path allowlist usable; it does not exempt manifest basenames or widen the ordinary worker.

First read the final published proposal and compute its content revision (example issue 123; this command only reads and prints a hash):

repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
gh api "repos/$repo/issues/123" | node .github/workflows/shared/squad-improvement-gate.mjs --revision

Then a human with live write, maintain or admin permission posts a new comment on that issue, substituting the printed hash and the exact proposed paths:

/squad approve-improvement
Approved-Revision: {64-character SHA-256}
Approved-Path: .squad/skills/some-skill/SKILL.md
Approved-Path: .squad/decisions/inbox/some-note.md

The hash binds the numbered issue’s title and complete body, with CRLF normalized. No quoted/fenced/indented command, edited approval, app/bot approval, missing permission/revision or scope mismatch is accepted. The existing dispatcher parses the command and runs its mutating collaborator authorization, then emits exactly one typed dispatch_workflow with nested inputs.issue_number and inputs.approval_comment_id. The worker is workflow_dispatch-only, never a second direct issue-comment listener. It independently fetches that exact comment and validates its human author/provenance, permissions, issue state, revision and scope, both before work and before safe outputs; it never substitutes a newer approval or treats a relay actor as an approver.

/squad revoke-improvement is a reserved no-dispatch route: a later human comment withdraws the referenced approval. Missing/edited/stale/revoked approvals require a fresh comment for the current content. Manual retries select Actions → Squad Improvement Worker → Run workflow, on the default branch, and supply the same issue_number and approval_comment_id (the numeric suffix of its #issuecomment-N URL). Retrying is not approval. Both workers remain draft-only; neither reviews its own output, marks ready nor merges.

Bounds and limitations: the evidence collector allows at most 720 API requests (700 original, ten cached PR reads and ten cached action provenance reads). Opt-in reconciliation adds at most 48: three action pages, five all-state PR pages and two comment pages for each of twenty candidates. Candidates rotate every six hours; an incomplete history requires human inspection. Live retro output checks add at most 14 reads; receiving ordinary-worker checks at most nine. Improvement authorization is bounded to fourteen reads per check, twice per worker run, plus two dispatcher checks. GitHub supplies no transaction covering a comment and a PR: revocation is checked immediately before safe outputs, not after publication; human review remains the final authority.

Casting a team

When you run /squad cast, the workflow follows these steps:

1. Brief resolution — evaluates the issue content and repo structure to decide what to build (see the casting brief below)
2. Repo analysis — scans languages, frameworks, CI/CD, testing, docs, and project structure
3. Team composition — selects roles (4–7 agents: a Lead, specialists, and at least one quality role)
4. Naming — uses descriptive role-based names by default (Lead, Frontend, Backend, Tester). If you request a themed universe in your brief, Squad picks character names from that universe instead — any universe works, not just the 15 built-in ones.
5. Scaffolding — replaces the disposable activation scaffold with the final charters, routing, registry, and a compact self-contained GH-AW coordinator
6. Deterministic validation — parses the final coordinator and team, checks every local path against the exact-case Cast payload/tree, and verifies registry, routing, charter, and generated-capability agreement
7. Pull request — opens a PR on a squad/cast-{repo} branch with the full team for review; a failed validation posts recovery guidance instead

The completion comment links the created Cast PR. Open that PR, mark it ready when it was created as a draft, request Copilot review, and wait for its checks. GitHub may require maintainer approval before application CI runs on a workflow-created branch; when the PR shows action_required, approve that workflow run from the checks view and wait for it to finish. Merge the Cast PR only after its generated files, review, and repository checks are complete.

The validator runs in the agent workspace immediately before the built-in safe-output request. gh-aw does not provide an independent post-agent hook that can conditionally authorize PR creation, so this is deterministic pre-output enforcement rather than a separate post-agent gate.

The casting brief

The casting brief is how you tell Squad what kind of team you want. It uses two signals:

• Issue signal — the title and body of the issue where you typed /squad cast
• Repo signal — your repository’s README, file structure, and CI/CD patterns

Squad resolves these with a priority cascade:

Example: writing a casting brief

Create an issue titled “Cast my team” with a body like this:

## Team spec

I need a team for a TypeScript monorepo with a React frontend and a
FastAPI backend. The frontend is the priority — we're behind on
accessibility and performance.

### Must-have roles
- Frontend specialist (React, a11y, performance)
- Backend engineer (Python, FastAPI, SQLAlchemy)
- Test engineer (Vitest for frontend, pytest for backend)

### Nice-to-have
- DevOps (GitHub Actions, Docker)

### Team size
5 agents maximum.

Then comment /squad cast on the same issue. Squad reads the brief, merges it with whatever it learns from scanning your repo, and produces a team that matches your spec.

What gets created

After merging the Squad PR, your repository contains:

.squad/
├── team.md                       # Full roster — names, roles, expertise
├── routing.md                    # Maps work domains to agents
├── agents/
│   └── {name}/charter.md         # Per-agent identity and rules (one per member)
├── casting/
│   ├── registry.json             # Name/universe mapping and status
│   ├── history.json              # Universe usage history
│   └── policy.json               # RAI policy (allowlisted universes)
└── decisions/                    # Team decisions (initially empty)

.github/agents/squad.agent.md    # Copilot custom agent definition
meet-the-squad.md                # Friendly team intro at the repo root

The squad.agent.md file registers your Squad as a custom Copilot agent. Once merged, you can @squad in Copilot Chat to talk to your team.

Naming modes

Squad supports three naming conventions for your team:

Descriptive (default)

When you don’t request a themed universe, agents get short functional names: Lead, Frontend, Backend, Tester, Security, Docs, etc. This is the default.

Built-in universes

Squad includes 15 pre-built fictional universes (The Usual Suspects, Star Wars, Futurama, Marvel, etc.) with pre-vetted character names. If you ask for themed names without specifying a universe, Squad auto-selects the best fit based on your team size and project type.

Custom universes

You can request any universe — it doesn’t have to be in the built-in list. Just say so in your casting brief or slash command:

/squad cast use Doctor Who characters

Squad allocates character names from its knowledge of the source material. Spoiler-safety rules still apply (names use early introductions, avoiding fate-revealing titles or epithets).

Re-casting with a different naming mode

You can switch naming modes at any time by re-casting:

/squad cast switch to Firefly universe
/squad cast use descriptive names instead

All agents are renamed and their files updated accordingly.

Research and planning

Squad’s SDLC commands let you go from an issue to a fully decomposed, agent-assigned backlog without leaving the issue thread.

Recommended lifecycle: research → plan → activate

For most work, use the clear three-step lifecycle:

/squad research
/squad plan
/squad activate

/squad research gathers evidence, /squad plan proposes a combined program and implementation plan for review, and /squad activate reviews and accepts the latest fast plan before creating its GitHub issues. Activation is a mutating command, so the actor needs write, maintain, or admin repository permission.

To activate one phase at a time, use /squad activate phase {N}. The existing /squad plan accept and /squad plan accept phase {N} commands remain supported as legacy aliases with identical behavior.

Granular lifecycle

research → triage → plan program → plan implementation → accept → activate
    │         │           │                │                │         │
    ▼         ▼           ▼                ▼                ▼         ▼
 findings  classify   initiatives/     PR-sized         approve   create
 posted    as work/   epics/           tasks            scope &   GitHub
           decision/  milestones                        impl      issues
           excluded

Each step is user-initiated — Squad proposes, you review and approve.

Lifecycle state tracking

After each command, Squad posts (or updates) a lifecycle state comment on the issue. This comment shows where you are, what just happened, and what to do next:

**Current state:** Triaged
**Last command:** `/squad triage` by @user at 2026-08-10
**Next action:** `/squad plan program` — create a program plan from triage dispositions
**Also available:** `/squad triage revise <feedback>` — adjust triage before planning

The Next action field tells you (or any agent reading the issue) the primary next command. Also available shows alternative valid commands at this point in the lifecycle. This means you never have to remember the state machine — the issue thread always shows what’s next.

Fast paths and compatibility aliases

You don’t have to use every step. Fast-path commands combine multiple stages:

/squad plan accept remains a backward-compatible alias for /squad activate.

What you give up with each fast path

/squad plan (skipping triage and separate scope review)

• Skips: /squad triage — no explicit classification of findings into work/decision/excluded before planning
• Skips: Separate /squad plan accept scope gate — the strategic structure (initiatives, epics, milestones) is never independently locked before task decomposition proceeds
• Risk: Scope may be broader or narrower than intended because exclusions were never explicitly classified. Triage is where you tell Squad “don’t plan that” — without it, Squad infers scope from research findings alone.
• Good for: Small, well-understood features where you already know the scope and trust Squad’s decomposition without a formal review gate.

/squad activate (skipping separate scope lock and implementation review)

• Skips: Separate /squad plan accept scope — you cannot review and approve strategic structure before decomposition runs
• Skips: Separate /squad plan accept implementation — the task breakdown goes directly to GitHub issue creation without a standalone review step
• Risk: GitHub issues are created immediately. If the plan needs revision, you’ll need to close issues manually. There is no undo.
• Good for: Small projects where one review pass is sufficient and you’re comfortable with immediate issue creation.

Use the granular commands when you need tighter review gates (large projects, cross-team coordination). Use the fast paths for smaller work where one review pass is enough.

Research

/squad research

Squad performs a deep analysis of your repository in context of the issue, then posts structured findings as a comment. This is the discovery phase — no issues or PRs are created.

No team yet? If you run /squad research (or any other work command) on a repo with no committed team, Squad automatically opens a Cast PR on the same issue, pauses your command for that run, and posts instructions to merge the Cast PR and rerun the original command. You don’t need to pre-cast on a separate issue — Squad handles it inline.

The research comment includes:

• Current state — architecture, patterns, dependency versions, code health
• Gap analysis — what’s missing or incomplete relative to the issue/goal
• Risk assessment — complexity and risk ratings per area
• Key findings — specific evidence with file paths and version numbers
• Online sources — a disclosure stating whether current online documentation was consulted (with the URLs fetched) or was unavailable (with the reason). When your repository’s gh-aw network policy permits outbound access, Squad consults authoritative primary documentation (official vendor docs and specifications) and cites the URLs; when access is unavailable it says so rather than implying it read a source.
• Recommendations — sequencing suggestions and things to avoid
• Next Step — tells you what to do next:
  • /squad triage — classify findings into work items, decisions, and exclusions (granular path)
  • /squad plan — skip triage and generate a combined plan directly (fast path)

You can focus the research with additional context:

/squad research focus on the authentication and authorization gaps
/squad research what's the current state of the test coverage?
/squad research use aspire.dev as the source of truth when building an Aspire app

Natural-language source-of-truth instructions like the third example are honored when that site is reachable under your network policy. Squad does not manage a domain allowlist — GitHub/gh-aw owns internet enablement and domain whitelisting through network.allowed in the workflow frontmatter, so to make a specific site reachable you widen your own gh-aw network policy there. Fetched web content is treated as untrusted evidence, never as instructions.

Research works on issues in any state (open or closed).

Triage

/squad triage

After research, triage classifies each finding into one of three dispositions:

Triage posts its classifications as a comment. To adjust:

/squad triage revise move the caching finding to "excluded" — we'll handle that next quarter

Plan program

/squad plan program

Creates a high-level program plan organized into initiatives, epics, and milestones. This is strategic structure — not yet PR-sized tasks.

Plan implementation

/squad plan implementation

Decomposes the program plan into PR-sized tasks with owners, sizes, dependencies, and acceptance criteria. The implementation plan is posted as a comment for review.

The plan comment includes:

• Phased issue breakdown with titles, owners, sizes, and dependencies
• Expandable details for each issue (scope, acceptance criteria, notes)
• A dependency graph showing what blocks what
• Execution notes and sequencing advice

Plan validate

/squad plan validate

Validates that a plan is ready for acceptance — checks for missing dependencies, unresolved decisions, and sizing gaps.

Plan accept scope

/squad plan accept scope

Approves the program plan scope (initiatives, epics, milestones). This locks the strategic structure before implementation decomposition proceeds.

Plan accept implementation

/squad plan accept implementation

Approves the implementation plan (PR-sized tasks, assignments, dependencies). After this, the plan is ready to activate.

Plan activate

/squad plan activate

Creates GitHub issues from the accepted plan with Squad labels (squad, squad:{agent-name}), acceptance criteria, dependency references, and phase assignments. Flat plans create one child issue per planned task directly under the originating issue; they do not add a duplicate epic. Dependencies use native blockedBy edges when the installed safe-output tool supports them, otherwise they remain explicit Depends On references in each issue body.

Labels are created automatically

You do not need to pre-create any label. Activation applies labels through the add-labels safe output, which is configured with allowed: [squad, "squad:*"] and create-if-missing: true, so squad and each squad:{agent} label is created the first time a run needs it. A fresh repository with zero Squad labels requires no manual label setup.

Two names, one operation. add-labels (hyphenated) is the configuration key in the workflow’s safe-outputs block — that is the spelling to search for in squad.md and the one the caps below apply to. add_labels (underscored) is the tool call the agent makes at run time, and it is the spelling that appears in activation summaries and incomplete reports. They refer to the same operation; this page uses whichever form matches the surface being described.

A label created this way receives gh-aw’s deterministic color and an empty description. That is expected on a fresh repository, not a failure. Labels that already exist are left as they are, and re-applying a label on a rerun is a no-op.

”Accepted” in an activation summary does not mean “applied”

Activation summaries report accepted operations, and that word is exact. Issue creation and labeling are gh-aw safe outputs: during the agent’s turn the run can only queue an operation against a target and observe that it was accepted. gh-aw applies the queued operations afterward, in a separate post-agent job. Nothing in the run reads labels back from GitHub.

So a correct summary says a label operation was accepted. It must not claim a label was applied, landed, verified, confirmed, or checked on the issue.

This vocabulary exists for a concrete reason. Labels do not ride along with issue creation: a label reaches an activated issue through exactly one route, an accepted add_labels operation targeting that issue. create-issue’s own labels: field never lands a label the activation run can claim, so it is never evidence that a label arrived. Labels therefore travel as separate add_labels calls, and “accepted” is the strongest thing the run can truthfully say about one.

Practical consequence: an accepted summary is strong evidence, not proof. To confirm what actually landed, read the issues themselves:

gh issue list --label squad --json number,title,labels

Activation is capped, and shortfalls are reported

A single activation run is bounded. The user-facing ceiling is 50 issues per activation run. Plan for that number.

The two underlying safe-output caps are set above that ceiling on purpose, so they are headroom rather than the limit you should size against:

max counts safe-output items (tool calls), not label names, and it is enforced at invocation and collection — neither enforcement fails the run.

Two different shortfalls are checked separately, and they are not interchangeable — the trigger, the wording, and the remedy differ:

Either one calls report_incomplete. This does not fail the run. The workflow run still concludes success, so gh run view --json conclusion is not a way to detect a truncated activation. The durable, user-visible signal is a tracking issue in your repository titled [aw] ... reported incomplete result, which gh-aw opens or updates:

gh issue list --search '"reported incomplete result" in:title' --state all

If a cap was actually reached, the report names which cap and lists the work items that did not fit, and recommends /squad plan activate phase {N} to continue in smaller batches. A cap is named only when it was observed — the workflow forbids offering a cap as a guessed explanation, so an incomplete report will not always attribute the shortfall to one.

Work items created in the same run are identified in that report by the temporary IDs the run minted — #aw_epic{K} and #aw_task{N} on the hierarchical path, #aw_ph{N} for a fast-path phase issue and #aw_wi{N} for a fast-path work item — rather than by issue number, because at that point creation is still deferred and no real number exists yet.

Do not read a green run as a complete activation. Check for that tracking issue.

Verifying an activation: the bindings block

Every phase and full activation artifact includes an Activation bindings: fenced JSON block — one entry per created or recognized task, built only from accepted operations. This is the most directly checkable surface Squad emits: a deterministic post-activation checker compares those bindings against the labels actually present on the issues.

You can do the same check by hand. Listing labels proves a label exists somewhere, but not that it landed on the right issue — so read the bindings out of the activation comment and compare them per issue:

# 1. Find the Activation bindings: block on the issue you activated
gh issue view {origin-issue} --json comments --jq '.comments[].body'

# 2. For each binding, compare its recorded issue and label against reality
gh issue view {issue} --json title,labels

# Broad sweep: every Squad-labeled issue at once
gh issue list --label squad --json number,title,labels

A binding whose label does not match the labels actually on that issue is the discrepancy the checker exists to catch.

Where an owner did not become a squad:{agent} label — a multi-owner epic, or an owner matching no roster name — the summary carries a required Non-roster agent values heading naming the value and the issue, and the matching binding records an omission reason. An omission is always reported explicitly, never left for you to infer.

Incremental phase acceptance

Instead of accepting an entire plan at once, you can accept and activate one phase at a time:

/squad plan accept implementation phase 1

This accepts Phase 1 and automatically creates its GitHub issues in a single step. After completing Phase 1 work, continue with:

/squad plan accept implementation phase 2

The accept command automatically activates the phase (creates issues) when all prior phases are already activated. This means you don’t need a separate /squad plan activate phase N command in the common case — accept does it all.

If you need to activate a phase separately (e.g., you accepted it earlier but skipped auto-activation), use:

/squad plan activate phase 1

Rules:

• Phases must be accepted in order (Phase 2 requires Phase 1 to be accepted first)
• Phases must be activated in order (Phase 2 requires Phase 1 to be activated first)
• Accept automatically activates when prior phases are ready (no separate activate needed)
• Each acceptance/activation posts a summary showing created issues and remaining phases
• Dependencies in later phases automatically reference issue numbers from earlier phases
• /squad plan accept implementation with no phase arg still accepts everything (backward compatible)
• /squad plan activate with no phase arg still activates everything (backward compatible)
• The same pattern works for the legacy fast path: /squad plan accept phase {N}

This is useful for large projects where you want to review and iterate between phases — ship Phase 1, learn from it, then decide whether to adjust Phase 2’s plan before accepting it.

Plan revise

/squad plan revise merge the two security issues into one and add a migration step

If the plan needs adjustments, revise it at any stage. Squad reads your feedback, modifies the current plan, and posts an updated comment. The revised plan supersedes the previous one.

Examples

Small project — recommended fast path (3 commands):

1. /squad research → Deep repo analysis
2. /squad plan     → Program + implementation plan for review
3. /squad activate → Accept the reviewed plan and create issues

If the plan needs changes, run /squad plan revise <feedback> before activation. /squad plan accept remains an equivalent legacy command.

Large project — granular lifecycle (7+ commands):

1. /squad research                       → Deep repo analysis
   Next step shown: "/squad triage" or "/squad plan"
2. /squad triage                         → Classify findings
   Next action: "/squad plan program"
   Also available: "/squad triage revise"
3. /squad triage revise move X to excluded → Adjust scope
   Next action: "/squad plan program"
4. /squad plan program                   → Strategic plan with milestones
   Next action: "/squad plan accept scope"
   Also available: "/squad plan program revise"
5. /squad plan accept scope              → Lock the program structure
   Next action: "/squad plan implementation"
6. /squad plan implementation            → PR-sized task decomposition
   Next action: "/squad plan validate"
   Also available: "/squad plan accept implementation"
7. /squad plan accept implementation phase 1  → Accept + auto-activate Phase 1
   (issues created immediately)
   Next action: "/squad plan accept implementation phase 2"
   /squad plan accept implementation phase 2  → Accept + auto-activate Phase 2
   ...
   — OR —
   /squad plan accept implementation     → Accept all at once
   Next action: "/squad plan activate"
8. /squad plan activate                  → Create GitHub issues (terminal)
   — only needed if step 7 used full accept without auto-activate —

At every step, the lifecycle state comment on the issue shows exactly what to do next — no need to memorize the command sequence.

Implementing issues

After /squad plan activate creates the implementation backlog, run:

/squad implement

Regular issues

On a regular issue, the main Squad workflow dispatches an isolated squad-implement-worker run. The worker:

1. Stops immediately if the issue is already closed
2. Checks that every issue listed in Depends on: is closed — posts a blocker comment and stops if any dependency is still open
3. Checks for an existing open PR whose branch starts with squad/implement-{N}- or whose body closes the issue — posts the PR URL and stops if one is found
4. Routes work to the squad member named by the squad:{member} label, or lets the Lead choose specialists when no label is present
5. Inspects the repository and implements the smallest complete change that satisfies every acceptance criterion
6. Runs the smallest existing build, test, and lint commands covering the change
7. Reviews the final diff against the issue acceptance criteria
8. Opens one focused pull request on branch squad/implement-{N}-{slug} that closes the issue

The main Squad workflow retains its narrow cast and planning permissions and cannot edit repository files. Only the implementation worker has edit tool access, and it delivers changes through gh-aw’s guarded create-pull-request safe output. Workflow, agent, and Squad configuration paths (.github/workflows/, .github/agents/, .github/aw/, .squad/) are prohibited from modification; files flagged as protected trigger a review request rather than a direct commit.

Epics

On an epic, Squad finds its open child issues through native sub-issue relationships and Parent: #N metadata. It then:

1. Excludes tasks with open dependencies
2. Excludes tasks that already have an open implementation pull request
3. Calculates available slots: max(0, 3 − active-implementation-count)
4. Dispatches one worker per selected ready child, up to three concurrent implementation PRs
5. Posts a summary listing dispatched, blocked, active, and deferred tasks

Each worker creates its own branch and pull request. When one of those pull requests merges, the worker resolves the parent epic and dispatches the main Squad workflow in implement mode. Squad then dispatches enough ready children to refill the three active slots. This continues until no open children remain, without requiring a third workflow.

Both workflows accept gh-aw’s propagated aw_context and allow the repository’s github-actions[bot] to pass the workflow-dispatch activation gate. Human slash commands retain the normal repository-role checks. The merge relay targets the repository’s default branch so deleting a merged implementation branch cannot prevent the continuation dispatch.

For example, an epic with ten independent tasks starts three workers. Each merge automatically starts one replacement, keeping three implementation pull requests active until the final task is dispatched. Dependencies may temporarily reduce the active count when no additional child is ready.

/squad implement remains available as a manual recovery command if a run is cancelled or an external change requires the epic to be reevaluated.

Repository setting: Pull-request delivery requires Settings → Actions → General → Workflow permissions → Allow GitHub Actions to create and approve pull requests.

Pull request CI: Pull requests created with the default GITHUB_TOKEN do not trigger other workflow runs. Set GH_AW_CI_TRIGGER_TOKEN to a suitable fine-grained PAT if implementation pull requests must start repository CI automatically.

Manual runs: From Actions → Squad → Run workflow, enter implement as the command and provide the target issue number.

/squad implement vs. assigning to the GitHub Copilot coding agent

These are two separate mechanisms. Understanding the difference helps you choose the right tool for each task.

Does /squad implement use the GitHub Copilot coding agent?

No. /squad implement dispatches the squad-implement-worker gh-aw workflow, which is a Copilot-powered agentic workflow running in the GitHub Actions sandbox. It does not assign issues to copilot-swe-agent[bot] or interact with the GitHub Copilot coding agent product in any way.

The @copilot entry in .squad/team.md (added by squad copilot) is a roster slot with copilot-auto-assign: false by default. No Squad workflow reads that flag to dispatch the coding agent. Auto-assignment is handled by a separate squad-issue-assign GitHub Actions workflow that watches for the squad:copilot label — it is entirely independent of /squad implement.

See Copilot coding agent for setup and capability profiles.

Review lifecycle

What happens during and after /squad implement

The implementation worker performs an internal self-review before opening a PR:

1. Dependency check — refuses to start if any Depends on: issue is open
2. Duplicate check — refuses to create a second PR if one already exists
3. Build / test / lint — runs the smallest existing commands covering the change
4. Diff review — the worker reviews its own final diff against the issue acceptance criteria before calling create-pull-request
5. Protected-file guard — changes to protected paths trigger a review request on the PR rather than a direct commit

After the PR is opened, squad-review provides an independent advisory review. You can start it in either of these ways:

• Manual: Comment /squad review on a same-repository pull request. The main Squad router relays the pull request number, current head SHA, and manual origin to the isolated reviewer workflow.
• Automatic: A same-repository pull request triggers review on ready_for_review and synchronize when it has recognized Squad or Copilot provenance. Fork pull requests are refused.

The reviewer classifies provenance in this priority order:

1. One validated <!-- squad:implement issue=... run=... --> worker marker and its matching squad/implement-* branch
2. A squad/implement-* branch when no marker-like text is present
3. Author copilot-swe-agent[bot] or a copilot/* branch when no marker-like text is present
4. Unattributed

Malformed higher-priority evidence fails closed instead of falling through to a weaker classification. Automatic review refuses unattributed pull requests; manual review can continue as Unattributed (manual). A Squad-Review-Head: <SHA> marker deduplicates review for an unchanged head, and per-PR concurrency cancels stale runs after a new push.

Advisory verdicts and reviewer independence

The reviewer can add a bounded summary comment, inline review comments, and exactly one pull request review. It returns:

• REQUEST_CHANGES for a concrete merge blocker, such as an acceptance-criteria violation, unsafe authority expansion, protected-file violation, missing test, or required-but-missing changeset
• COMMENT when findings are advisory or no merge blocker is established

The reviewer has no file-editing, issue-creation, pull-request-creation, remediation, merge, or APPROVE authority. Its verdict does not replace branch protection, required status checks, or a human reviewer’s approval. Human approval remains mandatory.

The lifecycle is:

/squad implement → implementation PR opened → advisory Squad review → human review + CI → merge → epic relay (next wave)

Advisory fast path

Because review is advisory, it is possible to merge without waiting for an automatic review or manually running /squad review. That fast path gives up an independent, head-SHA-specific check of the linked issue’s acceptance criteria, Squad routing and charter compliance, protected-file boundaries, focused tests, and changeset coverage. Your repository’s human approval and required checks still decide whether the pull request can merge.

Connect vs. Adopt

Squad supports two ways to bring in a team from another repository.

Connect: remote-managed

/squad connect myorg/shared-squad

Connect links your repo to an external squad source. Only a lightweight config pointer (.squad/config.json) is committed locally — the actual team files are fetched from the source repo at runtime.

Use Connect when:

• Your organization manages a centralized squad definition
• You want all repos to stay in sync with one source of truth
• Team updates in the source repo automatically propagate

What gets committed:

• .squad/config.json — pointer to the source ("mode": "connect")
• meet-the-squad.md — team intro with a note about external management

Trade-off: Local changes are overwritten on the next sync. To customize, disconnect by running /squad cast.

Adopt: copy and own

/squad adopt myorg/shared-squad

Adopt fetches the full squad definition from a source repo and commits it locally. After adoption, you own the files — there is no ongoing sync.

Use Adopt when:

• You want a starting point but plan to customize
• You’re forking a team for a new project with different needs
• You don’t want upstream changes to affect your repo

What gets committed:

• The entire .squad/ directory (cloned from source, adapted for your repo)
• .github/agents/squad.agent.md
• meet-the-squad.md
• .squad/config.json — records the adoption source ("mode": "adopt")

Trade-off: You get full control, but you won’t receive future updates from the source repo.

Side-by-side comparison

Iterating after the initial cast

Your squad isn’t frozen after the first cast. You can add, modify, and remove members at any time.

Add a member

/squad cast-member a security engineer focused on supply-chain attacks and SBOM

Squad allocates a character name from the existing universe, generates a charter, and opens a PR (or pushes to the existing Squad PR if you comment on one).

Modify a member

/squad cast-member rename EECOM to platform engineering and Kubernetes

This keeps the character name and identity but regenerates the charter with the new specialty.

Retire a member

/squad retire EECOM

The member’s charter moves to .squad/agents/_alumni/ and their registry entry is marked "status": "retired". Routing rules for their domain are flagged as unassigned.

Re-cast entirely

/squad cast

Running /squad cast again replaces the existing team with a fresh one based on a new analysis of the repo (and any casting brief you provide).

Context-aware mutations

When you comment /squad cast-member or /squad retire on a PR that already has the squad label and is on a squad/* branch, the changes are pushed to that branch as a follow-up PR — keeping all squad changes in one review thread.

Acknowledgment messages

When Squad starts processing a slash command, it posts a brief, mode-specific acknowledgment comment on the issue before doing work:

• /squad research → 🤖 Squad is researching this…
• /squad plan → 🤖 Squad is creating a plan…
• /squad plan accept implementation phase 1 → 🤖 Squad is creating implementation tasks…

This replaces the previous generic “processing” message with context about what Squad is actually doing.

How the workflow runs

Understanding the two-job architecture helps when debugging.

Job 1: Activation (unrestricted network)

The activation job runs with full network access:

1. Optionally mints a GitHub App installation token
2. Resolves SQUAD_CLI_VERSION (default v0.13.1) and downloads the matching standalone GitHub Release bundle with checksum verification — no npm install
3. Preserves a committed team with roster entries, or runs squad init --preset default --state-backend local when no usable team exists
4. Rejects npx-based MCP wiring and runs squad health --json
5. On success, uploads .squad/ and .github/agents/squad.agent.md as a one-day squad-state artifact

Job 2: Agent (network-restricted)

The agent job runs inside the gh aw sandbox with no outbound network:

1. Downloads the squad-state artifact from Job 1
2. Restores team files into the workspace
3. Executes the Squad coordinator using only the pre-generated files

The Squad CLI is never installed in the agent job — only the files it produced are used. Each run starts from the repository’s committed state: a merged Cast PR persists the complete team and casting files, while activation-only scaffold state and uncommitted runtime output do not carry over. User-facing changes persist through Squad’s guarded pull requests, issue comments, issues, and reviews.

Upgrading

Pin upgrades to one immutable 40-character Squad commit SHA. A bare gh aw add does not refresh files that are already installed, so use --force:

SQUAD_SHA="<40-character-commit-sha>"

gh aw add \
  bradygaster/squad/workflows/squad.md@${SQUAD_SHA} \
  bradygaster/squad/workflows/squad-implement-worker.md@${SQUAD_SHA} \
  bradygaster/squad/workflows/squad-review.md@${SQUAD_SHA} \
  bradygaster/squad/workflows/squad-deps-worker.md@${SQUAD_SHA} \
  bradygaster/squad/workflows/squad-retro.md@${SQUAD_SHA} \
  bradygaster/squad/workflows/squad-improvement-worker.md@${SQUAD_SHA} \
  bradygaster/squad/workflows/squad-bootstrap.md@${SQUAD_SHA} \
  --force

--force overwrites the installed source files. Save any local source customizations first, then reapply them before the final compile. Never customize generated .lock.yml files.

Existing local imports and resources are not guaranteed to refresh with the top-level files. Fetch every Squad shared import and resource at the same SHA:

mkdir -p .github/workflows/shared

for shared_file in \
  squad.md \
  squad-planning-ontology.md \
  squad-planning-policy.md \
  squad-cast-validator.mjs \
  squad-bootstrap-validator.mjs \
  squad-improvement-gate.mjs \
  squad-retro-evidence.mjs \
  squad-retro-provenance.mjs \
  builtins/scribe-charter.md \
  builtins/ralph-charter.md \
  builtins/rai-charter.md \
  builtins/fact-checker-charter.md; do
  mkdir -p ".github/workflows/shared/$(dirname "$shared_file")"
  curl --fail --silent --show-error --location \
    "https://raw.githubusercontent.com/bradygaster/squad/${SQUAD_SHA}/workflows/shared/${shared_file}" \
    --output ".github/workflows/shared/${shared_file}"
done

gh aw compile --strict

Confirm all seven source files and generated locks reference SQUAD_SHA, review the workflow diff, then commit them together. With gh-aw v0.87.10, do not use gh aw update for this immutable-pin flow: its stored source branch and cooldown can leave the installed sources at a different revision than the SHA you intend.

Use the complete upgrade block even when a failure appears limited to the first-run bootstrap workflow. Updating only squad-bootstrap.md can leave its validator or the rest of the workflow set at a different revision. The shared resource loop above explicitly refreshes squad-bootstrap-validator.mjs along with every other runtime dependency. Commit the refreshed sources, generated locks, and shared resources together. The default-branch push triggers bootstrap automatically; its push and branch gates intentionally reject other refs.

Troubleshooting

See also

• Squad README — project overview and local CLI usage
• Workflow definition — full slash command specification
• Implementation worker — isolated issue implementation workflow
• Bootstrap component — activation and artifact lifecycle