Repository navigation
docs(gh-aw): fix setup guide contradictions and sync enlistment guidance - #2153
Merged
Merged
Conversation
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| Status | Check | Details |
|---|---|---|
| ✅ | Single commit | 1 commit — clean history |
| ✅ | Not in draft | Ready for review |
| ❌ | Branch up to date | dev is 2 commit(s) ahead — rebase recommended |
| ❌ | 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 | Merge status unknown — GitHub is still computing |
| ❌ | Copilot threads resolved | 4 unresolved Copilot thread(s) — fix and resolve before merging |
| ✅ | CI passing | All checks passing |
Files Changed (9 files, +262 −60)
| File | +/− |
|---|---|
.squad-templates/skills/gh-aw-enlistment/SKILL.md |
+23 −3 |
docs/src/content/docs/guide/gh-aw.md |
+143 −42 |
packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md |
+23 −3 |
packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md |
+23 −3 |
templates/skills/gh-aw-enlistment/SKILL.md |
+23 −3 |
test/gh-aw-enlistment-skill.test.ts |
+1 −1 |
test/standalone-release-workflow.test.ts |
+2 −1 |
workflows/skills/gh-aw-enlistment/SKILL.md |
+23 −3 |
workflows/squad-workflows.manifest.json |
+1 −1 |
Total: +262 −60
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
🟠 Impact Analysis — PR #2153Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (1 file)
root (3 files)
squad-cli (1 file)
squad-sdk (1 file)
templates (1 file)
tests (2 files)
This report is generated automatically for every PR. See #733 for details. |
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The GraphQL mutation can replace existing reviewers, and the clean-tree guard overlooks untracked files.
4 open findings
What changed in this PR
Clarifies GH-AW setup permissions, verification, bootstrap recovery, and Copilot review guidance while synchronizing enlistment templates and tests.
Changes:
- Documents least-privilege and automatic-PR profiles.
- Uses manifest-backed installation verification and GraphQL review requests.
- Synchronizes enlistment guidance, manifest digest, and contract tests.
| File | Description |
|---|---|
docs/src/content/docs/guide/gh-aw.md |
Revises the public setup journey and recovery guidance. |
.squad-templates/skills/gh-aw-enlistment/SKILL.md |
Updates canonical Copilot-review instructions. |
templates/skills/gh-aw-enlistment/SKILL.md |
Synchronizes the root template mirror. |
packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md |
Synchronizes the CLI template mirror. |
packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md |
Synchronizes the SDK template mirror. |
workflows/skills/gh-aw-enlistment/SKILL.md |
Synchronizes the workflow-package mirror. |
workflows/squad-workflows.manifest.json |
Refreshes the enlistment-skill digest. |
test/gh-aw-enlistment-skill.test.ts |
Updates the renamed section boundary. |
test/standalone-release-workflow.test.ts |
Updates review-request documentation assertions. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| pr_node_id="$(gh pr view --json id --jq '.id')" | ||
| gh api graphql -f query=' | ||
| mutation($pr: ID!) { | ||
| requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) { |
| pr_node_id="$(gh pr view --json id --jq '.id')" | ||
| gh api graphql -f query=' | ||
| mutation($pr: ID!) { | ||
| requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) { |
| # 3. Create a bootstrap branch. Safe to run again: require a clean, | ||
| # understood tree, and reuse the branch if a prior run already created it | ||
| # instead of failing on an ordinary rerun. | ||
| git diff --quiet && git diff --cached --quiet || { |
Comment on lines
+704
to
+705
| expect(ghAwGuide).toContain('requestReviewsByLogin'); | ||
| expect(ghAwGuide).toContain('copilot-pull-request-reviewer'); |
Resolve a set of contradictions/unreliable instructions in the public Agentic Workflows setup guide (docs/src/content/docs/guide/gh-aw.md): - Clarify the Profile A (least-privilege, recommended) Actions permission setting and what remains manual under it; add an explicit opt-in Profile B (automatic PR creation) section with its coupled security tradeoff instead of silently enabling it. - Remove unconditional safe-update approval from the executable quick start; approval now requires verifying the report contains exactly SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, and bradygaster/squad/.github/actions/squad-init, otherwise stop. - Replace the broken `gh pr edit --add-reviewer @copilot` with a verified Copilot-as-Bot GraphQL requestReviewsByLogin/botLogins request plus a manual UI fallback (both quick-start and full-steps flows). - Make SQUAD_SHA discovery immutable: remove prose claiming quick start resolves dev automatically; require a maintainer-approved SHA. - Make quick start rerunnable/safe: validate a clean working tree and reuse an existing bootstrap branch instead of failing. - Replace the incomplete 7/8-workflow, 5/17-runtime-resource inventory loop with the manifest-backed squad-install-verifier.mjs --verify-install check (8 workflows / 17 shared runtime resources). - Correct the least-privilege fallback lifecycle: bootstrap opens/ reuses a signed fallback issue, a human opens the Cast PR, and Squad Bootstrap must be manually re-dispatched to create the linked research-proposal issue; make this explicit in the quick-start outcome narrative. - Align the /squad implement and troubleshooting prose with the Profile A/B framing so it no longer recommends disabling PR creation while also claiming automatic implementation PRs. Sync the canonical enlistment guidance (.squad-templates/skills/gh-aw-enlistment/SKILL.md) and its 4 mirrors with the same Copilot-as-Bot GraphQL reviewer-request fix (verified via scripts/sync-templates.mjs --sync), and regenerate workflows/squad-workflows.manifest.json's enlistment-skill digest via squad-install-verifier.mjs --write-source. Update the two directly-related documentation contract tests: - test/gh-aw-enlistment-skill.test.ts: match the renamed Profile A heading used as a test slice boundary. - test/standalone-release-workflow.test.ts: assert the new requestReviewsByLogin/copilot-pull-request-reviewer approach instead of the removed --add-reviewer command. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
bradygaster
force-pushed
the
bradygaster-docs-gh-aw-setup-guide
branch
from
October 2, 2026 19:41
ab28051 to
e287566
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Fixes a set of contradictions and unreliable instructions in the public Agentic Workflows setup guide (
docs/src/content/docs/guide/gh-aw.md) so a new user gets one coherent, safe, end-to-end setup journey, and synchronizes the directly-related canonical enlistment guidance (.squad-templates/skills/gh-aw-enlistment/SKILL.md+ its 4 mirror copies) and the documentation contract tests that assert on this content.Why
The guide is the public setup path. It previously contained several contradictions/unreliable instructions that could cause unsafe approval, failed Copilot review requests, missing bootstrap artifacts, or a setup that silently loses the human-review boundary:
gh pr edit --add-reviewer @copilot, which does not reliably request Copilot as a reviewer (Copilot resolves as a Bot; the working mechanism is GraphQLrequestReviews(... botIds: ...)/requestReviewsByLogin(... botLogins: ...)).SQUAD_SHAautomatically (it should require an immutable, maintainer-approved SHA)./squad implementand troubleshooting sections) recommended disabling PR creation while also claiming automatic implementation PRs, without explaining the profile boundary.How
default_workflow_permissions=read/can_approve_pull_request_reviews=false, with an explicit "what remains manual" callout — and a clearly separate, opt-in Profile B (automatic PR creation) section that discloses its coupled security tradeoff instead of silently enabling it.SQUAD_GITHUB_APP_PRIVATE_KEY,SQUAD_GITHUB_TOKEN, andbradygaster/squad/.github/actions/squad-init; anything else stops the flow. Final compile stays plaingh aw compile --strict.gh pr edit --add-reviewer @copilotoccurrences (quick start and full steps) with the verified GraphQLrequestReviewsByLogin/botLogins: ["copilot-pull-request-reviewer"]snippet plus a manual GitHub UI fallback.dev" claim;SQUAD_SHAis now documented as an immutable, maintainer-approved prerequisite.squad-install-verifier.mjs --verify-install --source-revision "${SQUAD_SHA}" --strict-compile, and completed the human-readable resource list to the full 17 entries (includingsquad-command-router,squad-review-guard,squad-command-contract) where a list is still shown./squad implementrepository-setting callout and the troubleshooting row with the Profile A/B framing so they no longer contradict each other..squad-templates/skills/gh-aw-enlistment/SKILL.md) and propagated it to its 4 mirror copies using the repo's ownscripts/sync-templates.mjs --synctool (not manual copies), then regeneratedworkflows/squad-workflows.manifest.json's enlistment-skill digest viasquad-install-verifier.mjs --write-source.test/gh-aw-enlistment-skill.test.ts(renamed Profile A heading used as a slice boundary) andtest/standalone-release-workflow.test.ts(assert the new GraphQL approach instead of the removed--add-reviewercommand).No product/workflow behavior changes were required — this PR is docs + enlistment guidance + directly-related contract tests only, consistent with the surgical scope requested.
skip-changelogapplies (docs/enlistment-guidance/test-only change)PR Readiness Checklist
Branch & Commit
dev(notmain)dev(rebased ontoorigin/devimmediately before push; base SHAf65ade928c6cd2a2906ce5517a6f491024793adf)git diff --cached --stat— 9 files, no unintended deletions)Build & Test
npm run buildpassesnpm testpasses for the directly-related suites (see below); fullnpm testwas not run to completion due to its long runtime — see Waiversnpm run lintpasses (type check clean)npm run lint:eslintpasses (0 errors; pre-existing warnings only, none in touched files)npm run lint:docspasses (markdownlint + cspell, 0 issues)Validation commands and results:
Changeset
skip-changelogapplies (no user-facing SDK/CLI behavior change; docs + enlistment skill + test content only)Docs
docs/src/content/docs/guide/gh-aw.md) updated directly; this is the primary target of the PRExports
Breaking Changes
None.
Waivers
Waived: "
npm testpasses (all tests green)" for the full suite — reason: the complete vitest suite's runtime exceeded what was practical to run to completion in this session; the 7 test files directly related to this change (900 tests) were run to completion and pass, and a fullnpm run lint:eslint/npm run lintpass surfaced no errors introduced by this change. A maintainer may re-runnpx vitest runin full before merge if additional confidence is desired. Approved by: self-attested per docs-devrel charter scope (surgical, docs/enlistment/test-only change with no source behavior touched); recommend Lead/Quality sign-off before merge.Closes: N/A (no linked issue — originated from an explicit task assignment to the docs-devrel owner)