docs(gh-aw): ship advisory review

[bradygaster]

Summary

• put the gh aw add dispatcher first and include the implementation worker plus advisory reviewer across every consumer install surface
• document /squad review triggers, provenance priority, SHA deduplication, advisory verdicts, reviewer independence, mandatory human approval, and the advisory fast-path tradeoff
• add regression coverage for install ordering, the six-file source/lock output, and stale review-gap language

Install result

The dispatcher-first command installs these top-level pairs:

• squad.md + squad.lock.yml
• squad-implement-worker.md + squad-implement-worker.lock.yml
• squad-review.md + squad-review.lock.yml

Validation

• remote gh aw add smoke produced the exact six-file set
• strict gh-aw compile passed for reviewer and implementation worker; dispatcher compiled with its existing slash-command/bot warning
• install/documentation contract checks and TypeScript syntax check passed
• npm test, docs build, ESLint, and package build could not run because the mandated proxy lacks locked vitest@4.1.11 and satteri@0.10.5; manifests and lockfiles are unchanged

Working as PAO (DevRel).

Closes #1736

[github-actions]

🟡 Impact Analysis — PR #1874

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	6
Files added	0
Files modified	6
Files deleted	0
Modules touched	4

🎯 Risk Factors

• 6 files changed (6-20 → MEDIUM)
• 4 modules touched (2-4 → MEDIUM)

📦 Modules Affected

ci-workflows (1 file)

• .github/agents.md

docs (2 files)

• docs/demo-agentic-sdlc-walkthrough.md
• docs/src/content/docs/guide/gh-aw.md

root (2 files)

• README.md
• workflows/shared/squad.md

tests (1 file)

• test/gh-aw-review-workflow.test.ts

---

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

[github-actions]

🛫 PR Readiness Check

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

PR Scope: 🔧 Infrastructure

⚠️ 3 item(s) to address before review

Status	Check	Details
❌	Single commit	2 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	No source files changed — changeset not required
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	0 active Copilot thread(s) resolved (2 outdated skipped)
❌	CI passing	10 check(s) still running

Files Changed (6 files, +176 −43)

File	+/−
.github/agents.md	+10 −6
README.md	+5 −2
docs/demo-agentic-sdlc-walkthrough.md	+1 −1
docs/src/content/docs/guide/gh-aw.md	+71 −32
test/gh-aw-review-workflow.test.ts	+85 −1
workflows/shared/squad.md	+4 −1

Total: +176 −43

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[Copilot]

🟡 Changes recommended

There are documentation inconsistencies around whether gh aw compile is required vs only needed for troubleshooting/safe-update-mode approval, which could confuse installers across the different install surfaces.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Updates the gh-aw installation and documentation surfaces to ship and describe the new advisory /squad review workflow alongside the dispatcher and implementation worker, and adds regression tests to keep install ordering and documentation assertions consistent over time.

Changes:

• Updates all “consumer install surfaces” to a consistent gh aw add ordering: dispatcher first, then implement worker, then advisory reviewer.
• Replaces the “review gap” documentation with the actual advisory review lifecycle, provenance rules, verdict semantics, and “human approval remains mandatory” guidance.
• Adds tests to enforce the three-workflow install order across docs/README/shared bootstrap and to validate the six-file source/lock output.

File summaries

File	Description
workflows/shared/squad.md	Updates distribution bootstrap comments to reflect the three-workflow install sequence.
test/gh-aw-review-workflow.test.ts	Adds install-surface/order regression checks and validates install produces complete source+lock pairs.
README.md	Updates the installation snippet to include the advisory reviewer in the gh aw add list.
docs/src/content/docs/guide/gh-aw.md	Updates install instructions and fully documents the advisory review lifecycle and semantics.
docs/demo-agentic-sdlc-walkthrough.md	Updates demo prerequisite to reference the new multi-workflow install path.
.github/agents.md	Updates agent-facing installation docs to include dispatcher + worker + reviewer.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.