[squad] Cast your Squad — The Usual Suspects for gh-aw - #53493
Conversation
Replace default init scaffold with a 6-member team (Keaton, Fenster, McManus, Hockney, Verbal, Kujan) from The Usual Suspects universe, tailored to the gh-aw compiler/CLI project. Adds team.md, charters, routing.md, casting registry/history, and meet-the-squad.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
✅ Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. Test Quality Sentinel skipped.
|
|
✅ Ponytail Reviewer completed successfully!
|
|
✅ PR Code Quality Reviewer completed the code quality review.
|
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅
|
Comment MemoryNote This comment is managed by comment memory.It stores persistent context for this thread in the code block at the top of this comment.
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Request changes
This install drops a large, self-contained agent governance system into a repo that already has strict agent/runtime rules, and the two are not reconciled. The most serious problems are contradictory sources of truth and direct gh-based GitHub write flows that are incompatible with gh-aw’s safe-output execution model.
Blocking themes
- The new coordinator is effectively a second top-level policy engine, but it is not integrated with this repository’s existing
AGENTS.md/skill contract. - Several documented issue/PR workflows assume direct authenticated
ghmutations, while this repo’s production agent runtime requires safe-output tools for writes and explicitly forbids some GitHub operations. - Because those assumptions are embedded in the installed instructions, the generated team would fail in the environment it is supposed to run in.
🔎 Code quality review by PR Code Quality Reviewer · gpt54 · 26.8 AIC · ⌖ 10.3 AIC · ⊞ 4.5K
Comment /review to run again
| **⚠️ CRITICAL RULE: You are a DISPATCHER, not a DOER. Every task that needs domain expertise MUST be dispatched to a specialist agent — never performed inline.** | ||
|
|
||
| **DISPATCH MECHANISM (detect once per session, then use consistently):** | ||
| - **Copilot App:** `create_session` tool → sub-sessions for commit-producing work (preferred when available) |
There was a problem hiding this comment.
This installs a second governance stack that overlaps the repo’s existing AGENTS.md contract, so follow-on agents can receive contradictory instructions about ownership, validation, and GitHub operations and behave unpredictably.
💡 Why this is blocking
The new
squad.agent.md prompt declares itself the authoritative coordinator for the repository, routes work through its own .squad/* state machine, and tells spawned agents to ignore repo-local conventions in favor of Squad’s rules. This repo already has a mandatory workflow in AGENTS.md/skills (for example required validation targets, report_progress, and a hard ban on gh aw run). Shipping both systems in parallel means future sessions can choose different instruction sources and produce inconsistent or invalid automation changes.
Please either integrate Squad with the existing gh-aw skill/ruleset or explicitly gate/disable one coordinator so there is a single source of truth for agent behavior in this repository.
| Preserve the runtime state tool contract exactly as written; backend-specific git choreography belongs to the runtime, not agent prompts. | ||
|
|
||
| **Full Spawn Template** (inline charter/history/decisions as needed): | ||
|
|
There was a problem hiding this comment.
The coordinator prompt is telling agents to run authenticated GitHub mutations directly with gh, which will break in this repository because our runtime contract only permits GitHub writes through safe-output tools.
💡 Why this is blocking
In multiple places the new instructions route issue/PR lifecycle work through
gh pr create, gh issue list, and similar direct CLI mutations. That conflicts with the repo’s top-level policy for cloud agents: reads may use gh, but writes and completion signaling must go through safeoutputs, and gh aw run/workflow triggering is explicitly forbidden. If this merges as-is, the installed team will be instructed to use a write path that is unavailable or disallowed in production, so a large part of the advertised automation will fail at runtime.
Please rewrite the GitHub-operation guidance to distinguish reads from writes and map every write action to the appropriate safe-output tool or mark it unsupported in this environment.
| 4. **Re-review required** — Rai must issue 🟢 or 🟡 before work can ship | ||
|
|
||
| ### Background Mode (Default) | ||
|
|
There was a problem hiding this comment.
This prompt hard-codes gh auth status/authenticated gh as a prerequisite for issue mode, which makes the installed workflow incompatible with our agent sandbox where gh writes are intentionally unavailable.
💡 Why this is blocking
The repo’s execution environment is explicit: reads can use
gh, but cloud agents must not depend on authenticated gh for writes, and unavailable permissions are a normal case. Requiring gh auth status as a gate means the coordinator will refuse to operate in the same environment this repository actually targets, even when the task could be completed with safe outputs or by degrading gracefully.
At minimum, the guidance here needs an environment-aware branch for gh-aw’s sandboxed runtime so the team doesn’t dead-end on auth checks that are expected to fail.
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs and /developer-security — requesting changes on two actionable issues; the rest is positive.
📋 Key Themes & Highlights
Key Themes
- Overly broad tool grant —
tools: ["*"]on the coordinator agent grants every available runtime tool. Given the coordinator is explicitly a dispatcher (the agent says it may NOT do domain work itself), the grant should be scoped to orchestration tools only. - State integration gap — 150 new files add a parallel state system (
.squad/) with no documentation of how it relates to gh-aw's existing CI, lock files, or branch conventions. .first-rungeneration artifact — the file appears to lack a trailing newline in the patch, making the timestamp and the next diff header appear on one line. Worth verifying the committed content is clean.
Positive Highlights
- ✅ Structured Reviewer Rejection Protocol with lockout semantics is well-thought-out and prevents revision loops
- ✅ RAI reviewer (Rai) is non-blocking by default with a clear 5-second cap — good performance discipline
- ✅ State backend abstraction (
local/orphan/two-layer) is forwards-compatible - ✅ Graceful degradation table for platform differences (CLI vs VS Code) is thorough
- ✅ The Eager Execution exception for Init Mode Phase 1 (requires user confirmation before any file write) is the right guardrail
Note: the diff was truncated at 3000 lines (PR has 17,710 additions across 150 files). Skill selection used the standard heuristic: all-new files →
/grill-with-docsprimary.
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · sonnet46 · 64 AIC · ⌖ 11.4 AIC · ⊞ 7.8K
Comment /matt to run again
| <!-- SQUAD_COORDINATOR_CANARY_HEAD_b7d2 --> | ||
|
|
||
| <!-- version: 0.11.0 --> | ||
|
|
There was a problem hiding this comment.
[/developer-security] tools: ["*"] grants the Squad coordinator unrestricted access to every tool available in the runtime — including file writes, shell execution, and any MCP-connected service. This is the most permissive grant possible.
💡 Suggested scope restriction
The coordinator is explicitly designed as a dispatcher, not a doer. Consider scoping tools to what orchestration actually requires:
tools:
- read_file
- list_files
- create_session
- task
- skill
- ask_userOr document why ["*"] is required — the inline "work inline (last resort fallback)" note suggests a narrower allowlist aligns with intent.
@copilot please address this.
|
|
||
| - All meaningful changes require team consensus | ||
| - Document architectural decisions here | ||
| - Keep history focused on work, decisions focused on direction |
There was a problem hiding this comment.
[/grill-with-docs] .squad/ adds a parallel state management system (decisions.md, inbox/, log/, history.md) that lives alongside gh-aw's existing workflow state. The interaction between these two state systems isn't documented — e.g., does Squad's Scribe commit .squad/decisions.md changes as normal git commits on feature branches, or via the orphan/two-layer backend? Without a brief ADR or CONTEXT.md note, it's unclear how this system integrates with gh-aw's existing CI and locking conventions.
💡 Suggested addition
Add a short note in .squad/decisions.md (or a new docs/adr/squad-state-integration.md) covering:
- Which
stateBackendgh-aw recommends for this repo - Whether
.squad/mutable state files are committed to the main branch or an orphan branch - How this interacts with
make recompile/ lock files
@copilot please address this.
| @@ -0,0 +1 @@ | |||
| 2026-08-17T21:00:36.370Z | |||
There was a problem hiding this comment.
[/grill-with-docs] The .squad/.first-run file contains a raw timestamp with no newline and no separator between it and the next diff hunk. This appears to be a generation artifact — the file content is 2026-08-17T21:00:36.370Z immediately followed by diff --git .... If this file is committed as-is, it's corrupt.
💡 Details
In the diff at line 1113:
+2026-08-17T21:00:36.370Zdiff --git a/.squad/agents/Rai/charter.md ...
The .first-run file should contain only the timestamp on its own line. This looks like the patch was generated without a trailing newline, causing the next diff header to appear on the same line. Verify the committed file content is correct before merging.
@copilot please address this.
There was a problem hiding this comment.
Ponytail pass (over-engineering only) on the 150-file scaffold this PR commits.
Two exact-duplicate files found (see inline comments): .squad/casting/policy.json / .squad/templates/casting-policy.json and .squad/ceremonies.md / .squad/templates/ceremonies.md are byte-identical — same content shipped twice instead of one being generated from the other at init time.
Beyond the flagged instances, several other .squad/agents/*/charter.md and .squad/agents/*/history.md files are near-identical boilerplate (>85-97% similarity) that could likely be templated rather than duplicated per-agent, but I limited inline comments to the two provable exact duplicates.
net: -108 lines possible.
Generated by ✂️ Ponytail Reviewer for #53493 · auto · 70 AIC · ⌖ 5.05 AIC · ⊞ 7.3K
Comment /ponytail to run again
| "DC Universe": 18, | ||
| "Futurama": 12 | ||
| } | ||
| } |
There was a problem hiding this comment.
L1-39: delete: byte-identical duplicate of .squad/templates/casting-policy.json. Load the template at init time instead of shipping two copies.
| At round start, call Test-RetroOverdue (see skill retro-enforcement). If overdue, run this ceremony before the work queue. | ||
|
|
||
| **Why GitHub Issues, not markdown:** | ||
| Production data: 0% completion across 6 retros using markdown checklists, 100% after switching to GitHub Issues. |
There was a problem hiding this comment.
L1-69: delete: byte-identical duplicate of .squad/templates/ceremonies.md. Copy from the template during init instead of committing both.
There was a problem hiding this comment.
Pull request overview
Adds a generated Squad configuration for gh-aw, including specialist agents, routing, policies, templates, and automation.
Changes:
- Defines the Usual Suspects–themed team and agent charters.
- Adds Squad governance, memory, casting, and ceremony state.
- Bundles reusable workflow, skill, and script templates.
Show a summary per file
| File | Description |
|---|---|
.github/agents/squad.agent.md |
Adds Squad coordinator |
meet-the-squad.md |
Documents the cast |
.squad/team.md |
Defines team roster |
.squad/routing.md |
Maps work domains |
.squad/config.json |
Initializes Squad config |
.squad/decisions.md |
Initializes decision log |
.squad/ceremonies.md |
Configures ceremonies |
.squad/.first-run |
Records initialization |
.squad/casting/registry.json |
Registers cast members |
.squad/casting/policy.json |
Configures casting |
.squad/casting/history.json |
Records casting history |
.squad/identity/now.md |
Records current focus |
.squad/identity/wisdom.md |
Initializes team wisdom |
.squad/memory/config.json |
Configures memory |
.squad/memory/index.json |
Initializes memory index |
.squad/memory/audit.jsonl |
Initializes memory audit |
.squad/rai/policy.md |
Defines RAI policy |
.squad/rai/audit-trail.md |
Initializes RAI audit |
.squad/fact-checker/policy.md |
Defines verification policy |
.squad/fact-checker/audit-trail.md |
Initializes verification audit |
.squad/agents/keaton/charter.md |
Defines lead role |
.squad/agents/fenster/charter.md |
Defines compiler role |
.squad/agents/mcmanus/charter.md |
Defines CI role |
.squad/agents/hockney/charter.md |
Defines testing role |
.squad/agents/verbal/charter.md |
Defines documentation role |
.squad/agents/kujan/charter.md |
Defines security role |
.squad/agents/scribe/charter.md |
Defines logging role |
.squad/agents/scribe/history.md |
Seeds Scribe context |
.squad/agents/ralph/charter.md |
Defines Ralph role |
.squad/agents/ralph/history.md |
Seeds Ralph context |
.squad/agents/Rai/charter.md |
Defines RAI reviewer |
.squad/agents/Rai/history.md |
Seeds Rai context |
.squad/agents/fact-checker/charter.md |
Defines Fact Checker |
.squad/agents/fact-checker/history.md |
Seeds verifier context |
.squad/templates/workflows/squad-release.yml |
Adds release workflow |
.squad/templates/workflows/squad-promote.yml |
Adds promotion workflow |
.squad/templates/workflows/squad-preview.yml |
Adds preview validation |
.squad/templates/workflows/squad-insider-release.yml |
Adds insider releases |
.squad/templates/workflows/squad-docs.yml |
Adds docs deployment |
.squad/templates/workflows/squad-ci.yml |
Adds Squad CI |
.squad/templates/workflow-wiring-appendix-a-code-reviewer.md |
Documents reviewer wiring |
.squad/templates/skills/windows-compatibility/SKILL.md |
Adds Windows guidance |
.squad/templates/skills/test-discipline/SKILL.md |
Adds testing guidance |
.squad/templates/skills/squad-help/SKILL.md |
Adds Squad help |
.squad/templates/skills/squad-conventions/SKILL.md |
Adds Squad conventions |
.squad/templates/skills/session-recovery/SKILL.md |
Adds session recovery |
.squad/templates/skills/reviewer-protocol/SKILL.md |
Adds reviewer protocol |
.squad/templates/skills/retro-enforcement/SKILL.md |
Adds retro enforcement |
.squad/templates/skills/reskill/SKILL.md |
Adds reskilling process |
.squad/templates/skills/ralph-two-pass-scan/SKILL.md |
Adds efficient issue scans |
.squad/templates/skills/project-conventions/SKILL.md |
Adds convention template |
.squad/templates/skills/pr-screenshots/SKILL.md |
Adds screenshot guidance |
.squad/templates/skills/personal-squad/SKILL.md |
Adds personal agents |
.squad/templates/skills/notification-routing/SKILL.md |
Adds notification routing |
.squad/templates/skills/nap/SKILL.md |
Adds context cleanup |
.squad/templates/skills/model-selection/SKILL.md |
Adds model selection |
.squad/templates/skills/humanizer/SKILL.md |
Adds response-tone guidance |
.squad/templates/skills/history-hygiene/SKILL.md |
Adds history guidance |
.squad/templates/skills/github-multi-account/SKILL.md |
Adds account switching |
.squad/templates/skills/fact-checking/SKILL.md |
Adds fact-checking method |
.squad/templates/skills/error-recovery/SKILL.md |
Adds recovery patterns |
.squad/templates/skills/economy-mode/SKILL.md |
Adds economy mode |
.squad/templates/skills/docs-standards/SKILL.md |
Adds documentation standards |
.squad/templates/skills/distributed-mesh/sync-mesh.sh |
Adds Unix mesh sync |
.squad/templates/skills/distributed-mesh/sync-mesh.ps1 |
Adds Windows mesh sync |
.squad/templates/skills/distributed-mesh/mesh.json.example |
Adds mesh example |
.squad/templates/skills/coordinator-source-of-truth/SKILL.md |
Defines state ownership |
.squad/templates/skills/coordinator-response-mode/SKILL.md |
Defines response modes |
.squad/templates/skills/client-compatibility/SKILL.md |
Adds client adaptation |
.squad/templates/skills/cli-wiring/SKILL.md |
Adds CLI wiring guidance |
.squad/templates/skills/ci-validation-gates/SKILL.md |
Adds CI safeguards |
.squad/templates/skills/agent-conduct/SKILL.md |
Defines agent conduct |
.squad/templates/skills/agent-collaboration/SKILL.md |
Defines collaboration |
.squad/templates/skill.md |
Adds skill template |
.squad/templates/scripts/notes/write-note.ps1 |
Adds note writer |
.squad/templates/scripts/notes/fetch.ps1 |
Adds note fetcher |
.squad/templates/scribe-charter.md |
Adds Scribe template |
.squad/templates/schedule.json |
Adds heartbeat schedule |
.squad/templates/run-output.md |
Defines run output |
.squad/templates/routing.md |
Adds routing template |
.squad/templates/roster.md |
Adds roster template |
.squad/templates/raw-agent-output.md |
Defines raw output |
.squad/templates/ralph-instructions.md |
Defines Ralph execution |
.squad/templates/rai-policy.md |
Adds RAI policy template |
.squad/templates/rai-charter.md |
Adds Rai template |
.squad/templates/prd-intake.md |
Adds PRD intake |
.squad/templates/plugin-marketplace.md |
Adds plugin guidance |
.squad/templates/package.json |
Sets CommonJS mode |
.squad/templates/orchestration-log.md |
Defines orchestration logs |
.squad/templates/multi-agent-format.md |
Defines artifact format |
.squad/templates/mcp-config.md |
Documents MCP setup |
.squad/templates/machine-capabilities.md |
Documents capability routing |
.squad/templates/identity/wisdom.md |
Adds wisdom template |
.squad/templates/identity/now.md |
Adds focus template |
.squad/templates/history.md |
Adds history template |
.squad/templates/fact-checker-policy.md |
Adds verifier policy template |
.squad/templates/fact-checker-charter.md |
Adds verifier charter template |
.squad/templates/copilot-instructions.md |
Adds coding-agent instructions |
.squad/templates/copilot-agent.md |
Documents coding-agent integration |
.squad/templates/constraint-tracking.md |
Adds constraint tracking |
.squad/templates/client-compatibility-reference.md |
Adds compatibility reference |
.squad/templates/charter.md |
Adds charter template |
.squad/templates/ceremony-reference.md |
Defines ceremony schema |
.squad/templates/ceremonies.md |
Adds ceremony template |
.squad/templates/casting/Futurama.json |
Adds Futurama names |
.squad/templates/casting-registry.json |
Adds registry template |
.squad/templates/casting-policy.json |
Adds casting policy template |
.squad/templates/casting-history.json |
Adds casting history template |
.squad/templates/after-agent-reference.md |
Defines post-agent flow |
Review details
💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.
Suppressed comments (1)
.squad/templates/workflow-wiring-appendix-a-code-reviewer.md:89
- The enforcement-rule example again sends rejected work back to the locked-out author. Coordinators generated from this walkthrough will violate the mandatory reviewer protocol; route feedback to a different revision agent.
- Files reviewed: 149/150 changed files
- Comments generated: 29
- Review effort level: Balanced
| auth_flag="" | ||
| if [ "$auth" = "bearer" ]; then | ||
| token_var="$(echo "${squad}" | tr '[:lower:]-' '[:upper:]_')_TOKEN" | ||
| [ -n "${!token_var:-}" ] && auth_flag="--header \"Authorization: Bearer ${!token_var}\"" | ||
| fi | ||
|
|
||
| eval curl --silent --fail $auth_flag "$source" -o "$target/SUMMARY.md" 2>/dev/null \ | ||
| || echo "# ${squad} — unavailable ($(date))" > "$target/SUMMARY.md" |
| - uses: actions/checkout@v4 | ||
| with: | ||
| fetch-depth: 0 | ||
|
|
||
| - uses: actions/setup-node@v4 |
| if: ${{ inputs.dry_run == 'false' }} | ||
| run: | | ||
| git checkout preview | ||
| git merge origin/dev --no-commit --no-ff -X theirs || true |
| Log "Push conflict — fetch-first retry..." DarkYellow | ||
|
|
||
| # Force-fetch: overwrite local ref with current remote state | ||
| git -C $repo fetch $Remote "${nsRef}:${nsRef}" 2>&1 | Out-Null |
|
|
||
| # ── Fetch notes ───────────────────────────────────────────────────────────── | ||
| Log "Fetching notes from $Remote..." | ||
| $output = git -C $repo fetch $Remote "refs/notes/*:refs/notes/*" 2>&1 |
| - name: Validate version consistency | ||
| run: | | ||
| VERSION=$(node -e "console.log(require('./package.json').version)") | ||
| if ! grep -q "## \[$VERSION\]" CHANGELOG.md 2>/dev/null; then |
| - name: Validate version consistency | ||
| run: | | ||
| VERSION=$(node -e "console.log(require('./package.json').version)") | ||
| if ! grep -q "## \[$VERSION\]" CHANGELOG.md 2>/dev/null; then |
| run: | | ||
| git checkout preview | ||
| VERSION=$(node -e "console.log(require('./package.json').version)") | ||
| if ! grep -q "## \[$VERSION\]" CHANGELOG.md 2>/dev/null; then |
| run: | | ||
| gh release create "${{ steps.version.outputs.insider_tag }}" \ | ||
| --title "${{ steps.version.outputs.insider_tag }}" \ | ||
| --notes "This is an insider/development build of Squad. Install with:\`\`\`bash\nnpm install -g @bradygaster/squad-cli@${{ steps.version.outputs.insider_tag }}\n\`\`\`\n\n**Note:** Insider builds may be unstable and are intended for early adopters and testing only." \ |
| Use the squad branch convention: | ||
| ``` | ||
| squad/{issue-number}-{kebab-case-slug} | ||
| ``` | ||
| Example: `squad/42-fix-login-validation` |
|
🎉 This pull request is included in a new release. Release: |
🕵️ Your Squad is cast
Universe: The Usual Suspects
Repo analysis: gh-aw is a Go CLI extension (
gh aw, ~2,850 Go files) compiling Markdown+YAML frontmatter agentic workflows into GitHub Actions, with a compiler (pkg/parser,pkg/cli), custom Actions (actions/), a large linters package, extensive Starlight docs, and a Copilot skill library.Team
Plus always-on: Scribe, Ralph, Rai, Fact Checker.
What's included
.squad/team.md, per-agent charters,.squad/routing.md.squad/casting/registry.json+history.jsonmeet-the-squad.mdwith rationale.github/agents/squad.agent.mdMerge this PR to activate your team. After merging, return to the originating issue and rerun
/squad statusto verify.Closes #53489
Add this agentic workflow to your repo
To install this agentic workflow, run