feat(workflows): add Squad implementation mode - #1682
Conversation
🟡 Impact Analysis — PR #1682Risk tier: 🟡 MEDIUM 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (1 file)
root (3 files)
tests (1 file)
This report is generated automatically for every PR. See #733 for details. |
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 9 commits — consider squashing before review |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | Changeset skipped via skip-changelog label |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | 0 active Copilot thread(s) resolved (3 outdated skipped) |
| ❌ | CI passing | 9 check(s) still running |
Files Changed (5 files, +458 −17)
| File | +/− |
|---|---|
README.md |
+9 −2 |
docs/src/content/docs/guide/gh-aw.md |
+109 −13 |
test/gh-aw-implement-workflow.test.ts |
+68 −0 |
workflows/squad-implement-worker.md |
+177 −0 |
workflows/squad.md |
+95 −2 |
Total: +458 −17
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
There was a problem hiding this comment.
Pull request overview
Adds a new /squad implement execution mode to the reusable gh-aw Squad workflow, introducing a private worker workflow that performs issue-scoped implementation and delivers changes via guarded PR creation, plus documentation updates for installation and usage.
Changes:
- Extend
workflows/squad.mdwith Implement Mode, including manualissue_numberinput and a boundeddispatch-workflowsafe output. - Add a new private
workflows/squad-implement-worker.mdworkflow to implement a single issue with concurrency control and PR delivery viacreate-pull-request. - Update README and gh-aw guide docs to install/compile both workflows and document
/squad implementbehavior for regular issues and epics.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| workflows/squad.md | Adds /squad implement mode spec, manual issue targeting, and worker dispatch safe-output. |
| workflows/squad-implement-worker.md | Introduces a private implementation worker workflow with PR delivery safe-outputs and operational guardrails. |
| README.md | Updates installation instructions and command list to include /squad implement. |
| docs/src/content/docs/guide/gh-aw.md | Documents installing both workflows and adds /squad implement usage/troubleshooting guidance. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| allowed-files: | ||
| - "*" | ||
| - "app/**" |
There was a problem hiding this comment.
Removed the root wildcard and replaced it with explicit root file extensions, known project directories, a source-branch allowlist, and protected-file review.
| Compiling resolves both workflow definitions and their shared imports into | ||
| deterministic `.lock.yml` files. These lock files are what GitHub Actions | ||
| actually executes. |
There was a problem hiding this comment.
Updated the wording to “GitHub Actions runs these lock files.”
| gh aw add bradygaster/squad/workflows/squad.md@dev | ||
| gh aw compile | ||
| git add .github/workflows/ && git commit -m "Add Squad workflow" && git push | ||
| git add .github/workflows/ .gitattributes && git commit -m "Add Squad workflow" && git push |
There was a problem hiding this comment.
Updated the copyable commit messages to use the plural “workflows.”
|
Hey — this needs a rebase onto |
…instructions Root cause: the compression PR (bradygaster#1682) removed shared/planning-ontology.md and shared/planning-policy.md from the imports: list, then compensated with five runtime `cat .github/workflows/shared/planning-*.md` instructions. These instructions imply a workspace file exists at runtime, which is not how gh-aw imports work — imported content is inlined into the prompt before execution. Changes: - workflows/squad.md: add shared/planning-ontology.md and shared/planning-policy.md back to imports: alongside shared/squad.md - workflows/squad.md: replace all five fragile runtime cat instructions with a note that the content is already available via imports - test/gh-aw-quality.test.ts: add regression suite 'gh-aw: prompt budget & planning import regression' with 4 tests: * planning-ontology.md is in imports list * planning-policy.md is in imports list * no runtime cat of planning files remains * combined prompt (workflow + all imports) is under 100 KB gh-aw ceiling Measurements: squad.md: 32,196 bytes shared/squad.md: 6,688 bytes shared/planning-ontology.md: 15,231 bytes shared/planning-policy.md: 3,910 bytes Combined: 58,025 bytes (56.7 KB) Headroom: 44,375 bytes (43.3 KB under 100 KB ceiling) All 28 gh-aw quality tests pass. Closes bradygaster#1684 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e5d9bcc6-d667-485b-bccb-738bd9842102
Closes bradygaster#1681 - Add /squad implement dispatch for regular issues and ready epic tasks - Isolate repository edits in a private implementation worker workflow - Guard dependency handling, duplicate PR detection, concurrency, and PR file scope - Document installation, permissions, execution waves, and CI token behavior - gh aw compile squad-implement-worker --strict --approve - gh aw compile squad --strict --approve - npm run lint:docs - The new worker reuses SQUAD_GITHUB_APP_PRIVATE_KEY and SQUAD_GITHUB_TOKEN only through the existing shared Squad bootstrap - The main workflow remains read-only and dispatches a private worker through a bounded safe output - Worker changes are restricted by allowed source branches, allowed files, protected-file review, and one PR per run Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2587b35f-a675-4bf1-a761-265efc31cc23
Closes bradygaster#1681 ## Summary - Split the README staging example into an explicit path-scoped command - Avoid the repository security scanner's unsafe git add pattern ## Test Plan - npm run lint:docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2587b35f-a675-4bf1-a761-265efc31cc23
Part of bradygaster#1681 - Move the gh-aw package manifest under workflows/ - Install only the Squad dispatcher, worker, and shared dependencies - Avoid importing unrelated repository agents and skills - npx vitest run test/gh-aw-implement-workflow.test.ts - npm run lint:docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2587b35f-a675-4bf1-a761-265efc31cc23
Part of bradygaster#1681 - Install both workflow sources in one gh aw add invocation - Preserve dependency order without importing unrelated package artifacts - Remove the overly broad repository package manifest - Remote gh aw add with both workflow references - npx vitest run test/gh-aw-implement-workflow.test.ts - npm run lint:docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2587b35f-a675-4bf1-a761-265efc31cc23
Part of bradygaster#1681 ## Summary - Use the workflow-specific worker dispatch tool instead of the generic safe output - Require a numeric issue input for every selected child - Prevent malformed placeholder dispatches from failing the safe-output job ## Test Plan - gh aw compile squad --strict --approve - npx vitest run test/gh-aw-implement-workflow.test.ts - Two worker runs completed successfully in tamirdresher/my-new-cli-mock Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2587b35f-a675-4bf1-a761-265efc31cc23
- Relay merged implementation PRs through the existing worker to the Squad dispatcher - Refill a maximum of three active epic implementation slots automatically - Document rolling continuation and add structural regression coverage - gh aw compile squad and squad-implement-worker --strict --approve --no-emit - npx vitest run test/gh-aw-implement-workflow.test.ts - npm run lint:docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2587b35f-a675-4bf1-a761-265efc31cc23
## Summary - Allow github-actions bot activation for the two-workflow implementation chain - Propagate gh-aw context into both workflow dispatch targets - Document and test workflow-to-workflow activation ## Test Plan - gh aw compile squad and squad-implement-worker --strict --approve --no-emit - npx vitest run test/gh-aw-implement-workflow.test.ts - npm run lint:docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2587b35f-a675-4bf1-a761-265efc31cc23
## Summary - Pin the merge-triggered Squad relay to the repository default branch - Avoid dispatch failures after merged implementation branches are deleted - Cover and document the ref selection ## Test Plan - gh aw compile squad and squad-implement-worker --strict --approve --no-emit - npx vitest run test/gh-aw-implement-workflow.test.ts - npm run lint:docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2587b35f-a675-4bf1-a761-265efc31cc23
## Summary - Restore the restricted implementation worker allowlist after rebasing - Keep root-level source files supported without permitting arbitrary files ## Test Plan - npx vitest run test/gh-aw-implement-workflow.test.ts - npm run lint:docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2587b35f-a675-4bf1-a761-265efc31cc23
678f01f to
2432600
Compare
bradygaster
left a comment
There was a problem hiding this comment.
✅ FIDO Quality Gate — APPROVE
Commit: 8a6b84c0 | Scope: workflows/squad-implement-worker.md + test/gh-aw-implement-workflow.test.ts (2 files, exactly as expected)
Findings
Least-capability base override removal — Dropping allowed-base-branches: ["squad/*"] is correct gh-aw semantics: omission locks PR targets to the repository default branch, which is strictly less permissive than an explicit squad-branch override. allowed-branches: ["squad/implement-*"] (source restriction) is preserved unchanged.
Tests — 51/51 pass in isolated worktree (test/gh-aw-quality.test.ts 44 + test/gh-aw-implement-workflow.test.ts 7). Both new assertions validated: absence of allowed-base-branches and add-comment target: "*" present in dispatcher and worker.
Build — npm run build exits clean. TypeScript compile + postbuild pass.
CI — All 15 checks pass. Scope Boundary skip is expected for this PR type.
Atomic Plan Activate markers — ATOMIC CONTRACT, report_incomplete, never noop, and idempotent via title match all confirmed present in workflows/squad.md.
Non-blocking note
The add-comment regex asserts YAML key order (max before target). This is a mild brittleness: a future key reorder would break the test without changing runtime semantics. FIDO to track; does not block this PR.
Fix available — cherry-pick requiredPR #1682 is a cross-repository fork (head: What was fixed and why Removed Two structural tests were also added to
Fix location Commit To apply All 7 tests pass after the change. No other files were modified. |
…ut (#1697) test/gh-aw-quality.test.ts's compiled-workflow-contract test copied workflows/ into a bare workflows/ dir inside the ephemeral test git repo, then ran gh aw compile workflows/squad.md --strict. Since #1682 added safe-outputs.dispatch-workflow (workflows: [squad-implement-worker]) to workflows/squad.md, gh aw v0.85.4's dispatch-workflow validation now resolves its expected .github/workflows/ location relative to the compiled file, assuming the standard <root>/.github/workflows/<file>.md depth. Because this repo's source lives one level shallower, at <root>/workflows/<file>.md, gh aw's resolution lands one directory too high (confirmed empirically against both the test workspace and the real repo root), so it can never find squad-implement-worker and fails --strict compilation. This is the sole cause of dev's vitest red status since 2026-08-12T23:39. Fix: mirror the real downstream deployment layout inside the test workspace instead - copy workflows/ into <workspace>/.github/workflows/ and compile .github/workflows/squad.md, matching exactly how docs/src/content/docs/guide/gh-aw.md documents real installs via gh aw add owner/squad/workflows/squad-implement-worker.md@dev owner/squad/workflows/squad.md@dev (both files land side-by-side in the consumer's .github/workflows/). Verified this placement in an isolated compile outside any repo/worktree - dispatch-workflow resolves and compile succeeds with exit 0. This also changes the compiled runtime-import placeholder paths from bare shared/planning-ontology.md to .github/workflows/shared/planning-ontology.md, which is gh-aw's genuine, repo-root-relative behavior for that layout (reproduced in the same isolated compile) - updated the two literal assertions to match. Added a 20s test timeout since gh aw compile can exceed vitest's 5s default under full-suite parallel load. workflows/squad.md, workflows/squad-implement-worker.md, and #1682's dispatch-workflow feature are completely untouched. Co-authored-by: tamirdresher_microsoft <tamirdresher_microsoft@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
dev's git history was orphaned on 2026-07-13 (root commit 4c5772c, 196 commits) and no longer shares a common ancestor with main (root commit f4830e4, 1722 commits). This silently blocked promotion: `git merge-base dev main` fails outright and PR bradygaster#1698 (dev -> main) is unmergeable as a result. The v0.11.0 promotion (2026-06-29) predates the reset, which is why it succeeded and this one cannot. This merges upstream/main into dev with --allow-unrelated-histories to give the two branches a real common ancestor again, so future dev -> main promotions work through normal fast-forward/merge mechanics instead of hitting this dead end. Conflict resolution policy (277 add/add conflicts, all resolved in dev's favor): - dev is the live 0.12.0 release line; main is 44 days stale. - Verified the one main-only code fix, bradygaster#1415 (`tools: ['*']` in .github/agents/squad.agent.md), is already present on dev, so taking dev's side loses no code. - All conflicts resolved via `git checkout --ours` (dev) + `git add`. - Verified afterward: package.json / packages/squad-cli/package.json / packages/squad-sdk/package.json still read 0.12.0; CHANGELOG.md still holds the `## [0.12.0] - 2026-08-12` entry; test/gh-aw-quality .test.ts still holds the bradygaster#1697 `.github/workflows` layout fix; workflows/squad.md and workflows/squad-implement-worker.md still hold the bradygaster#1682 feature. Non-conflicting content that arrived from main (~60 files): - Restored (content lost in the July reset): 7 docs pages under docs/src/content/{blog,docs}/ and 5 .squad/decisions/inbox/*.md decision records. The 5 decision files matched a gitignore pattern for new `git add` but were mechanically staged fine via the merge itself (already-tracked-on-main content merges at the object level and isn't filtered by .gitignore), so all 12 were kept. - 6 agent history.md / decisions.md files auto-merged cleanly (three-way, non-conflicting) and are kept as-is: they interleave older content from main with dev's newer entries, recovering more history lost in the reset. - Dropped: 48 .changeset/*.md files that arrived from main. They are already consumed into CHANGELOG.md's 0.12.0 entry; re-adding them risks tripping the Changeset Drift check for content that's already released. .changeset/ after this merge contains exactly what dev had (README.md, config.json, max-reasoning-effort.md). Net effect verified via `git diff --cached --stat`: only 18 files show a real diff versus dev's tip (the 12 restored files + 6 auto-merged history files); all 275 conflict resolutions and all 48 changeset removals are no-ops against dev's existing tree. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
What
Adds
/squad implementto the reusable gh-aw integration. Regular issues dispatch a dedicated Squad implementation worker that validates dependencies, routes through the assigned Squad member, implements the acceptance criteria, and opens a focused pull request. Epic issues dispatch up to three ready child tasks while skipping blocked tasks and tasks with existing implementation PRs.Why
The current planning lifecycle ends after
/squad plan activatecreates issues. Users still need a separate coding-agent flow to begin implementation. This closes that gap without requiring a persistent Copilot coding-agent token.Closes #1681
How
The main
squad.mdworkflow remains read-only and gains a boundeddispatch-workflowsafe output. The new dispatch-onlysquad-implement-worker.mdworkflow owns repository edits and PR delivery. It uses issue-scoped concurrency, dependency and duplicate guards, asquad/implement-*branch allowlist, an explicit file allowlist, and protected-file review.The dispatcher calls the generated workflow-specific
squad_implement_workertool and forbids the generic dispatch tool or missing issue inputs. This was hardened from live canary evidence after a generic empty dispatch caused the first safe-output job to fail while its two valid worker dispatches still succeeded.Automatic epic continuation
The existing two-workflow design now progresses epic waves automatically without adding a third workflow. gh-aw does not allow slash_command and pull_request triggers in the same workflow, so the existing worker listens for merged squad/implement-* pull requests. It resolves the child issue's parent epic and dispatches squad.md with command: implement and the epic issue number.
The dispatcher calculates ^Gvailable slots = max(0, 3 - active implementation PRs) immediately before fan-out and starts only enough ready children to refill those slots. /squad implement remains the manual recovery path for cancelled runs or external changes.
Users can install both workflows in one command, with the worker first so the dispatcher compiles against an existing target:
Reusable workflow sources live under
workflows/, so generated.lock.ymlfiles are intentionally not committed to this source repository. Both workflows were compiled in a consumer-style.github/workflows/layout.End-to-end canary evidence
Validated in
tamirdresher/my-new-cli-mockusing the exact PR branch:Automatic continuation canary evidence
Validated rolling continuation with epic #27 and four independent children:
pull_request: closed: https://github.com/tamirdresher/my-new-cli-mock/actions/runs/31500075020squad.mdworkflow on the default branch: https://github.com/tamirdresher/my-new-cli-mock/actions/runs/31500509283The canary also exposed and fixed two integration details before this update: gh-aw workflow-dispatch membership requires
aw_contextplus trustedgithub-actions[bot]activation, and a PR-triggered relay must settarget-refto the repository default branch because merged branches may be deleted.Security Review
SQUAD_GITHUB_APP_PRIVATE_KEYandSQUAD_GITHUB_TOKENworkflows/shared/squad.mdauthentication bootstrapcreate-pull-requestWhy a separate worker workflow
The separate
squad-implement-workerworkflow is intentional. gh-aw does not allow an agentic workflow to dispatch itself, sosquad.mdcannot fan out parallel implementation runs using only its own workflow definition.Keeping implementation in
squad.mdwould support a single issue, but it would prevent epic fan-out and require the main workflow to receive repository edit access for every Squad command. The dedicated worker keepssquad.mdread-only, gives edit access only to implementation runs, and lets each ready child issue create an independent branch and pull request.The tradeoff is that users install and compile two workflow sources, handled through the single
gh aw addcommand above. If epic fan-out is not desirable for the upstream integration, the alternative is to keep single-issue implementation insquad.mdand remove worker dispatch.PR Readiness Checklist
Branch & Commit
devdevBuild & Test
gh aw compile squad-implement-worker --strict --approvegh aw compile squad --strict --approvenpx vitest run test/gh-aw-implement-workflow.test.tsnpm run lint:docsChangeset
Docs
Exports
Breaking Changes
Existing installations must add and compile
squad-implement-worker.mdbefore updatingsquad.md. Existing slash commands remain unchanged.Waivers
None.