Skip to content

Commit ea554fb

Browse files
tamirdresherCopilotCopilotbradygaster
authored
feat(gh-aw): add scheduled and evidence-triggered retrospectives (#2005)
* feat: add Squad retrospective workflow Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix: satisfy retrospective workflow gates Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * feat: add retrospective remediation handoff Closes #2005 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix: restore retrospective CI contracts Closes #2005 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <Copilot@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: Brady Gaster <41929050+bradygaster@users.noreply.github.com>
1 parent 2842cf8 commit ea554fb

28 files changed

Lines changed: 9451 additions & 285 deletions

‎.changeset/squad-retro-auto-implement.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
"@bradygaster/squad-cli": patch
3+
"@bradygaster/squad-sdk": patch
4+
---
5+
6+
Extend the standard gh-aw stack to six workflows. Retrospective action issues
7+
can opt into bounded ordinary-fix dispatch and independent retry reconciliation.
8+
The improvement worker requires an exact human approval comment, content
9+
revision and file scope; its final gate validates the actual patch. Both paths
10+
produce draft PRs with verified provenance, suppress all-state duplicates, and
11+
leave review and merge to humans. Report/proposal-only remains the default.
12+
13+
Duplicate suppression now also recognizes GitHub's native issue<->pull request
14+
link (the "Development" sidebar), not just a closing-keyword reference or the
15+
worker's own branch naming. A human-linked pull request -- open, merged, or
16+
closed unmerged, with no body text at all -- permanently excludes its issue
17+
from further auto-dispatch, at the receiver duplicate gate for both worker
18+
paths and at the retrospective's own reconciliation check before it dispatches.
19+
An incomplete or failed native lookup fails closed, the same as an incomplete
20+
REST pull-request scan.

‎.changeset/squad-retrospective-workflow.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
"@bradygaster/squad-cli": patch
3+
"@bradygaster/squad-sdk": patch
4+
---
5+
6+
Ship the shared Squad retrospective workflow and include it in the CLI and SDK
7+
gh-aw enlistment templates.

‎.github/agents.md‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,20 +23,33 @@ GitHub Agentic Workflows (`gh-aw`) are composable AI workflows triggered by slas
2323
gh aw add \
2424
bradygaster/squad/workflows/squad.md@dev \
2525
bradygaster/squad/workflows/squad-implement-worker.md@dev \
26+
bradygaster/squad/workflows/squad-review.md@dev \
2627
bradygaster/squad/workflows/squad-deps-worker.md@dev \
27-
bradygaster/squad/workflows/squad-review.md@dev
28+
bradygaster/squad/workflows/squad-retro.md@dev \
29+
bradygaster/squad/workflows/squad-improvement-worker.md@dev
2830
```
2931

3032
This command:
3133

32-
1. Fetches the Squad dispatcher, general and dependency workers, and advisory reviewer
34+
1. Fetches the Squad dispatcher, general and dependency workers, advisory reviewer, retrospective, and approval-gated improvement worker
3335
2. Compiles them into GitHub Actions–compatible workflows
3436
3. Adds the workflow sources and generated files to your repository's `.github/` directory
3537

3638
### Verify installation
3739

38-
After running the command, confirm the Squad, Squad Implement Worker, and Squad
39-
Review workflows appear in your repository's **Actions** tab.
40+
After running the command, confirm all six source/lock pairs exist and strict
41+
compilation succeeds: Squad, Implement Worker, Review, Deps Worker, Retro and
42+
Improvement Worker. The improvement worker is standard but dormant until an
43+
exact human approval is relayed through the dispatcher.
44+
45+
Retrospectives remain report/proposal-only by default. Ordinary auto-fixes need
46+
`"squadRetroAutoImplement": "allow"` in `.squad/config.json`. A proposal restricted
47+
to eligible Markdown paths under `.squad/skills/**` or `.squad/decisions/inbox/**`
48+
instead needs `/squad approve-improvement`, an `Approved-Revision:` hash and
49+
exact `Approved-Path:` lines. `/squad revoke-improvement` reserves the human's
50+
durable revocation without dispatching. Both workers open drafts, never merge
51+
or mark ready. See the [gh-aw guide](../docs/src/content/docs/guide/gh-aw.md)
52+
for revision calculation, caps and manual retry.
4053

4154
### Try your first command
4255

‎.github/workflows/squad-ci.yml‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -705,8 +705,13 @@ jobs:
705705
fi
706706
707707
# ── gh-aw strict compile gate ────────────────────────────────────────────
708-
# Compiles all four Squad-authored workflow sources with --strict against a
709-
# pinned compiler so the delivered stack is always proven compilable.
708+
# Compiles all six Squad-authored workflow sources with --strict against a
709+
# pinned compiler so the delivered stack is always proven compilable. All
710+
# six workflows, including squad-improvement-worker, are distributed by the
711+
# gh-aw-enlistment bootstrap skill/docs as part of the standard install --
712+
# squad-improvement-worker stays dormant (approval-gated) until a maintainer
713+
# authorizes a governance-scoped retrospective proposal, but it is not a
714+
# separate opt-in add-on.
710715
# Runs unconditionally on every PR / push so it can be used as a required
711716
# status check (check name: "Squad CI / gh-aw strict compile").
712717
#
@@ -749,15 +754,15 @@ jobs:
749754
cp -r workflows/. "$COMPILE_DIR/.github/workflows/"
750755
git -C "$COMPILE_DIR" init --quiet
751756
752-
- name: Compile all four workflows (--strict) and verify lock files
757+
- name: Compile all six workflows (--strict) and verify lock files
753758
# Failures accumulate rather than short-circuit so every result is
754759
# visible in one run. A compiler that exits 0 without emitting a lock
755760
# file is treated as failure — silent-success is a gate gap.
756761
run: |
757762
set -euo pipefail
758763
FAILED=0
759764
echo "### Compile results" >> "$GITHUB_STEP_SUMMARY"
760-
for WF in squad squad-implement-worker squad-review squad-deps-worker; do
765+
for WF in squad squad-implement-worker squad-review squad-deps-worker squad-retro squad-improvement-worker; do
761766
printf -- '--- Compiling %s ---\n' "$WF"
762767
if (cd "$COMPILE_DIR" && gh aw compile "$WF" --strict --approve --no-check-update 2>&1); then
763768
printf ' => OK\n'
@@ -770,7 +775,7 @@ jobs:
770775
done
771776
echo "" >> "$GITHUB_STEP_SUMMARY"
772777
echo "### Lock files" >> "$GITHUB_STEP_SUMMARY"
773-
for LOCK in squad.lock.yml squad-implement-worker.lock.yml squad-review.lock.yml squad-deps-worker.lock.yml; do
778+
for LOCK in squad.lock.yml squad-implement-worker.lock.yml squad-review.lock.yml squad-deps-worker.lock.yml squad-retro.lock.yml squad-improvement-worker.lock.yml; do
774779
if [ ! -f "$COMPILE_DIR/.github/workflows/$LOCK" ]; then
775780
echo "::error::$LOCK not emitted — compiler exited 0 without writing output"
776781
echo "❌ missing: \`$LOCK\`" >> "$GITHUB_STEP_SUMMARY"
@@ -786,4 +791,4 @@ jobs:
786791
exit 1
787792
fi
788793
echo "" >> "$GITHUB_STEP_SUMMARY"
789-
echo "**✅ All four workflows compiled, all four lock files emitted**" >> "$GITHUB_STEP_SUMMARY"
794+
echo "**✅ All six workflows compiled, all six lock files emitted**" >> "$GITHUB_STEP_SUMMARY"

‎.squad/skills/gh-aw-enlistment/SKILL.md‎

Lines changed: 34 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ tools:
1111
when: "Every step: preflight identity/auth, enabling Actions-created PRs, opening and watching the bootstrap PR."
1212
- name: "gh aw"
1313
description: "GitHub Agentic Workflows extension (github/gh-aw) — installs and strictly compiles the Squad workflow set."
14-
when: "Installing the four @dev workflows and compiling them into deterministic .lock.yml files."
14+
when: "Installing the six @dev workflows and compiling them into deterministic .lock.yml files."
1515
---
1616

1717
## Context
@@ -99,14 +99,16 @@ git switch -c chore/squad-gh-aw-bootstrap
9999
not part of the Squad set. `gh aw add` is additive; if you see it about to
100100
replace an unrelated workflow, **STOP**.
101101

102-
### 3. Install the four supported workflows — in order, dispatcher first
102+
### 3. Install the six supported workflows — in order, dispatcher first
103103

104104
```bash
105105
gh aw add \
106106
bradygaster/squad/workflows/squad.md@dev \
107107
bradygaster/squad/workflows/squad-implement-worker.md@dev \
108+
bradygaster/squad/workflows/squad-review.md@dev \
108109
bradygaster/squad/workflows/squad-deps-worker.md@dev \
109-
bradygaster/squad/workflows/squad-review.md@dev
110+
bradygaster/squad/workflows/squad-retro.md@dev \
111+
bradygaster/squad/workflows/squad-improvement-worker.md@dev
110112
```
111113

112114
Keep `squad.md` first: `gh aw add` discovers its worker/reviewer dependencies
@@ -115,8 +117,27 @@ creating duplicates. The installed top-level set is exactly:
115117

116118
- `squad.md` + `squad.lock.yml`
117119
- `squad-implement-worker.md` + `squad-implement-worker.lock.yml`
118-
- `squad-deps-worker.md` + `squad-deps-worker.lock.yml`
119120
- `squad-review.md` + `squad-review.lock.yml`
121+
- `squad-deps-worker.md` + `squad-deps-worker.lock.yml`
122+
- `squad-retro.md` + `squad-retro.lock.yml`
123+
- `squad-improvement-worker.md` + `squad-improvement-worker.lock.yml`
124+
125+
`squad-improvement-worker` is part of the standard, coherent install above —
126+
not a separate opt-in add-on. It stays dormant until a maintainer approves a
127+
governance-scoped retrospective proposal (see the gh-aw guide's retrospective
128+
auto-implementation section); installing it alongside the other five keeps the
129+
full stack consistent and avoids a second bootstrap pass later.
130+
131+
Report/proposal-only is the default. Ordinary fixes require the explicit
132+
`"squadRetroAutoImplement": "allow"` setting in `.squad/config.json`;
133+
five action issues and three dispatches per wakeup remain separate caps.
134+
An improvement requires `/squad approve-improvement`, `Approved-Revision:`
135+
and exact `Approved-Path:` lines from a human with write/maintain/admin access.
136+
The dispatcher sends nested issue and approval-comment IDs to the worker;
137+
manual retries use those same IDs. `/squad revoke-improvement` is reserved
138+
without dispatch and is rechecked before outputs. Draft PRs and human merge
139+
remain mandatory; closed-unmerged PRs never cause automatic replacements.
140+
See the guide for content-hash calculation and the one-retry recovery policy.
120141

121142
`@dev` is intentional — it tracks the branch where new modes and fixes land first.
122143

@@ -158,29 +179,29 @@ gh aw compile --strict
158179
This must run after any first-install approval and before committing. Success
159180
criteria:
160181

161-
- All four workflows compile successfully.
182+
- All six workflows compile successfully.
162183
- The **only** permitted warning is the known `squad.md` bot-trigger warning: it
163184
configures both slash-command and `github-actions[bot]` triggers, and the bot
164185
trigger is required for controlled worker-continuation dispatches.
165186
- **STOP** on any error, or on **any additional warning** beyond that single
166187
documented one.
167188

168-
### 6. Require all four source/lock pairs to exist
189+
### 6. Require all six source/lock pairs to exist
169190

170191
```bash
171-
for workflow in squad squad-implement-worker squad-deps-worker squad-review; do
192+
for workflow in squad squad-implement-worker squad-review squad-deps-worker squad-retro squad-improvement-worker; do
172193
test -f ".github/workflows/${workflow}.md" || { echo "MISSING ${workflow}.md"; exit 1; }
173194
test -f ".github/workflows/${workflow}.lock.yml" || { echo "MISSING ${workflow}.lock.yml"; exit 1; }
174195
done
175196
```
176197

177198
- **STOP** and rerun `gh aw compile --strict` if any `.lock.yml` is missing. Do not
178-
open or merge the bootstrap PR until all **eight** files exist and strict
199+
open or merge the bootstrap PR until all **twelve** files exist and strict
179200
compilation passes.
180201

181202
> On Windows PowerShell, the `for`/`test -f` loop above is POSIX. Use an
182203
> equivalent guard (e.g. `Test-Path`) or run it under Git Bash; the *logic* — all
183-
> eight files must exist — is what matters.
204+
> twelve files must exist — is what matters.
184205
185206
### 7. Inspect generated files, then stage only the documented surfaces
186207

@@ -256,8 +277,10 @@ git switch -c chore/squad-gh-aw-bootstrap
256277
gh aw add \
257278
bradygaster/squad/workflows/squad.md@dev \
258279
bradygaster/squad/workflows/squad-implement-worker.md@dev \
280+
bradygaster/squad/workflows/squad-review.md@dev \
259281
bradygaster/squad/workflows/squad-deps-worker.md@dev \
260-
bradygaster/squad/workflows/squad-review.md@dev
282+
bradygaster/squad/workflows/squad-retro.md@dev \
283+
bradygaster/squad/workflows/squad-improvement-worker.md@dev
261284

262285
# Safe-update report shows ONLY the two documented secrets + squad-init → approve once
263286
gh aw compile --strict --approve
@@ -321,4 +344,4 @@ gh pr merge --squash # auto-merge before human review. NEVER.
321344
- ❌ **Widening the default token.** Keep `default_workflow_permissions=read`.
322345
- ❌ **Auto-merging.** The bootstrap PR and the later Cast PR are both
323346
human-reviewed. `/squad cast` runs only after the bootstrap PR merges.
324-
- ❌ **Opening the PR before all eight files exist and strict compile passes.**
347+
- ❌ **Opening the PR before all twelve files exist and strict compile passes.**

‎README.md‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -565,8 +565,10 @@ If you use [GitHub Agentic Workflows](https://github.blog/changelog/2025-05-19-g
565565
gh aw add \
566566
bradygaster/squad/workflows/squad.md@dev \
567567
bradygaster/squad/workflows/squad-implement-worker.md@dev \
568+
bradygaster/squad/workflows/squad-review.md@dev \
568569
bradygaster/squad/workflows/squad-deps-worker.md@dev \
569-
bradygaster/squad/workflows/squad-review.md@dev
570+
bradygaster/squad/workflows/squad-retro.md@dev \
571+
bradygaster/squad/workflows/squad-improvement-worker.md@dev
570572
git add -- \
571573
.github/aw/ \
572574
.github/skills/ \
@@ -593,6 +595,32 @@ Review the complete generated diff before you commit:
593595

594596
`agentics-maintenance.yml` is a second installed workflow. Squad configures its created pull request safe output to expire after 14 days, so this workflow runs scheduled expiration cleanup and also exposes manual maintenance operations. To omit it, create `.github/workflows/aw.json` with `{"maintenance": false}` before installing. gh-aw then warns that expiration is disabled and removes the maintenance workflow.
595597

598+
#### Retrospective auto-implementation (opt-in behavior)
599+
600+
`squad-improvement-worker` installs as part of the standard six-workflow
601+
`gh aw add` command above — it is not a separate add-on. The two activation
602+
policies are separate: `squad-retro` can auto-dispatch `squad-implement-worker` on its
603+
own ordinary (non-proposal) action issues once you set
604+
`"squadRetroAutoImplement": "allow"` in `.squad/config.json` (only
605+
bot-authored retrospective issues with a valid `Action-Key:` qualify), and a
606+
maintainer can approve a governance-scoped retrospective proposal (paths
607+
under `.squad/skills/**` or `.squad/decisions/inbox/**` only) for automated
608+
implementation by commenting `/squad approve-improvement`, an
609+
`Approved-Revision:` content hash and one `Approved-Path:` line per approved
610+
file. The dispatcher forwards the issue and exact comment ID; the worker
611+
revalidates the human's permission, revision, revocations and actual patch.
612+
`/squad revoke-improvement` withdraws
613+
that authorization at any time — it is a reserved, read-only command open to
614+
any actor, and it emits no output of its own.
615+
616+
Report/proposal-only remains the default. Ordinary opt-in dispatch is capped at
617+
three per wake-up (five action issues per report), with one delayed retry and a
618+
durable human handoff after exhaustion. Both workers produce drafts only;
619+
open, merged and closed-unmerged linked PRs suppress automatic duplicates.
620+
Human review and merge are always required.
621+
622+
See [the gh-aw guide](https://bradygaster.github.io/squad/docs/guide/gh-aw/#retrospective-auto-implementation-opt-in) for the full authority model.
623+
596624
### Slash commands
597625

598626
| Command | What it does |
@@ -604,6 +632,9 @@ Review the complete generated diff before you commit:
604632
| `/squad retire <name>` | Remove a team member |
605633
| `/squad status` | Check current team |
606634
| `/squad implement` | Implement an issue or dispatch ready tasks from an epic |
635+
| `/squad retro` | Run the shared retrospective now; scheduled and evidence-driven wakeups use the same worker |
636+
| `/squad approve-improvement` | Authorize a governance-scoped retrospective proposal for `squad-improvement-worker` (write/maintain/admin only) |
637+
| `/squad revoke-improvement` | Withdraw a prior approval; reserved, read-only, open to anyone |
607638

608639
### Casting brief tip
609640

0 commit comments

Comments
 (0)