Skip to content

feat(workflows): add Squad implementation mode - #1682

Merged
bradygaster merged 9 commits into
bradygaster:devfrom
tamirdresher:feat/squad-implement
Aug 12, 2026
Merged

feat(workflows): add Squad implementation mode#1682
bradygaster merged 9 commits into
bradygaster:devfrom
tamirdresher:feat/squad-implement

Conversation

@tamirdresher

@tamirdresher tamirdresher commented Aug 11, 2026

Copy link
Copy Markdown
Collaborator

What

Adds /squad implement to 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 activate creates 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.md workflow remains read-only and gains a bounded dispatch-workflow safe output. The new dispatch-only squad-implement-worker.md workflow owns repository edits and PR delivery. It uses issue-scoped concurrency, dependency and duplicate guards, a squad/implement-* branch allowlist, an explicit file allowlist, and protected-file review.

The dispatcher calls the generated workflow-specific squad_implement_worker tool 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:

gh aw add \
  bradygaster/squad/workflows/squad-implement-worker.md@dev \
  bradygaster/squad/workflows/squad.md@dev

Reusable workflow sources live under workflows/, so generated .lock.yml files 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-mock using the exact PR branch:

Automatic continuation canary evidence

Validated rolling continuation with epic #27 and four independent children:

The canary also exposed and fixed two integration details before this update: gh-aw workflow-dispatch membership requires aw_context plus trusted github-actions[bot] activation, and a PR-triggered relay must set target-ref to the repository default branch because merged branches may be deleted.

Security Review

  • New restricted secret references: SQUAD_GITHUB_APP_PRIVATE_KEY and SQUAD_GITHUB_TOKEN
  • Both are reused only by the existing workflows/shared/squad.md authentication bootstrap
  • No new external actions, secret destinations, or redirects were introduced
  • The main workflow retains read-only repository permissions
  • Repository editing is isolated to the dispatch-only worker and delivered through create-pull-request
  • The worker cannot modify Squad state, agent definitions, gh-aw state, or workflow files

Why a separate worker workflow

The separate squad-implement-worker workflow is intentional. gh-aw does not allow an agentic workflow to dispatch itself, so squad.md cannot fan out parallel implementation runs using only its own workflow definition.

Keeping implementation in squad.md would 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 keeps squad.md read-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 add command above. If epic fan-out is not desirable for the upstream integration, the alternative is to keep single-issue implementation in squad.md and remove worker dispatch.


⚠️ Quick Check

  • No SDK or CLI source files changed; no changeset is required

PR Readiness Checklist

Branch & Commit

  • Branch created from dev
  • Branch is up to date with dev
  • Diff contains only intended workflow, test, and documentation changes
  • PR is not a draft

Build & Test

  • gh aw compile squad-implement-worker --strict --approve
  • gh aw compile squad --strict --approve
  • npx vitest run test/gh-aw-implement-workflow.test.ts
  • npm run lint:docs
  • Full repository CI passed
  • Live two-child epic fan-out and duplicate rerun passed

Changeset

  • Not required because package source and exports are unchanged

Docs

  • README integration section updated
  • gh-aw guide updated with setup, usage, permissions, CI behavior, and troubleshooting

Exports

  • N/A — no SDK modules changed

Breaking Changes

Existing installations must add and compile squad-implement-worker.md before updating squad.md. Existing slash commands remain unchanged.

Waivers

None.

Copilot AI lite review requested due to automatic review settings August 11, 2026 04:22
@github-actions

github-actions Bot commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

🟡 Impact Analysis — PR #1682

Risk tier: 🟡 MEDIUM

📊 Summary

Metric Count
Files changed 5
Files added 2
Files modified 3
Files deleted 0
Modules touched 3

🎯 Risk Factors

  • 5 files changed (≤5 → LOW)
  • 3 modules touched (2-4 → MEDIUM)

📦 Modules Affected

docs (1 file)
  • docs/src/content/docs/guide/gh-aw.md
root (3 files)
  • README.md
  • workflows/squad-implement-worker.md
  • workflows/squad.md
tests (1 file)
  • test/gh-aw-implement-workflow.test.ts

This report is generated automatically for every PR. See #733 for details.

@github-actions

github-actions Bot commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 2432600

PR Scope: 🔧 Infrastructure

⚠️ 3 item(s) to address before review

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.

@tamirdresher tamirdresher added the skip-changelog Skip changelog enforcement for this PR label Aug 11, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.md with Implement Mode, including manual issue_number input and a bounded dispatch-workflow safe output.
  • Add a new private workflows/squad-implement-worker.md workflow to implement a single issue with concurrency control and PR delivery via create-pull-request.
  • Update README and gh-aw guide docs to install/compile both workflows and document /squad implement behavior 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.

Comment on lines +41 to +43
allowed-files:
- "*"
- "app/**"

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the root wildcard and replaced it with explicit root file extensions, known project directories, a source-branch allowlist, and protected-file review.

Comment on lines +89 to +91
Compiling resolves both workflow definitions and their shared imports into
deterministic `.lock.yml` files. These lock files are what GitHub Actions
actually executes.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the wording to “GitHub Actions runs these lock files.”

Comment thread README.md Outdated
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

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the copyable commit messages to use the plural “workflows.”

Copy link
Copy Markdown
Owner

Hey — this needs a rebase onto dev after the recent prompt architecture fixes (73520de). The conflicts are in workflows/squad.md and docs/src/content/docs/guide/gh-aw.md. The worker workflow and test files need to be re-added (they show as modify/delete conflicts since they're new in this PR). Happy to help if needed!

pull Bot pushed a commit to nagyist/squad that referenced this pull request Aug 12, 2026
…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
Copilot and others added 9 commits August 12, 2026 07:17
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

@bradygaster bradygaster left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Copy link
Copy Markdown
Owner

Fix available — cherry-pick required

PR #1682 is a cross-repository fork (head: tamirdresher/squad). The reviewed fix was committed to bradygaster/squad and cannot be pushed to the fork head without credentials for tamirdresher/squad.

What was fixed and why

Removed allowed-base-branches: ["squad/*"] from workflows/squad-implement-worker.md's create-pull-request safe-output block. That entry was unnecessary and semantically undesirable: it granted the worker permission to override the PR base to any squad/* branch. Omitting it is the least-privilege choice — PRs target the repository default branch automatically. The allowed-branches: ["squad/implement-*"] source-branch restriction is preserved unchanged.

Two structural tests were also added to test/gh-aw-implement-workflow.test.ts to guard this going forward:

  • worker source branch remains squad/implement-*; allowed-base-branches is absent
  • add-comment.target: "*" is present in both dispatcher and worker

Fix location

Commit 8a6b84c0fec7e74d0e4448d26487fb392ac4a829 on bradygaster/squad:feat/squad-implement

To apply

git fetch https://github.com/bradygaster/squad.git feat/squad-implement
git cherry-pick 8a6b84c0fec7e74d0e4448d26487fb392ac4a829

All 7 tests pass after the change. No other files were modified.

@bradygaster
bradygaster merged commit 385241c into bradygaster:dev Aug 12, 2026
16 checks passed
tamirdresher added a commit that referenced this pull request Aug 13, 2026
…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>
shantanusharma pushed a commit to shantanusharma/squad that referenced this pull request Aug 15, 2026
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

skip-changelog Skip changelog enforcement for this PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(gh-aw): add /squad implement execution mode

3 participants