docs(gh-aw): correct credentials guidance and document activation fixes - #1973
Merged
Conversation
The bootstrap procedure listed SQUAD_GITHUB_APP_PRIVATE_KEY and SQUAD_GITHUB_TOKEN as a setup-time item with no statement that they need not exist. The clarification sat ~95 lines downstream in an "Optional:" section a reader following the numbered path never reaches before deciding whether they are blocked. Two independent agents read that passage and concluded a PAT was a prerequisite for enlisting a fresh repo. It is not. The correction now lands inline at the point of misreading, and is mirrored byte-identically into the three gh-aw-enlistment SKILL.md copies (outside the bounded allowlist block). Also documents four merged activation fixes that shipped with zero docs changes, traceable to workflows/squad.md on dev: - #1959 label auto-provisioning (squad.md:113-115, 1307, 1931-1945, 2004) — add-labels create-if-missing auto-creates squad/squad:{agent}; auto-provisioned labels get a deterministic color and empty description, which is expected and not a failure. - #1961 bounded caps (squad.md:111, 121, 1997, 1999) — create-issue 75, add_labels 110; the two shortfall paths are kept distinct; report_incomplete does NOT fail the run, so the durable signal is the [aw] ... reported incomplete result tracking issue, not the run conclusion. A cap is named only when observed. - #1963 accepted-vs-applied (squad.md:1392, 2058-2081) — defines accepted, states what a summary must not claim, and explains why the distinction exists (create-issue labels: silently drops missing names). - #1962 temporary IDs — documented only where user-observable: shortfall reports identify items by #aw_epic{K}/#aw_task{N}/#aw_wi{N}. Adds the Activation bindings: JSON block as the checkable verification surface, and updates the stale troubleshooting row that predated #1961. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
|
Contributor
🟠 Impact Analysis — PR #1973Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (1 file)
root (1 file)
squad-cli (1 file)
squad-sdk (1 file)
squad-state (1 file)
This report is generated automatically for every PR. See #733 for details. |
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 4 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 file found |
| ✅ | Scope clean | |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | 2 active Copilot thread(s) resolved (2 outdated skipped) |
| ✅ | CI passing | All checks passing |
Files Changed (5 files, +175 −2)
| File | +/− |
|---|---|
.changeset/1973-gh-aw-enlistment-credentials.md |
+6 −0 |
.squad/skills/gh-aw-enlistment/SKILL.md |
+8 −0 |
docs/src/content/docs/guide/gh-aw.md |
+145 −2 |
packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md |
+8 −0 |
packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md |
+8 −0 |
Total: +175 −2
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
🏗️ Architectural Review
Automated architectural review — informational only. |
Copilot stopped reviewing on behalf of
bradygaster due to an error
September 1, 2026 17:31
The changelog gate's SDK_CLI_PATH_REGEX (squad-ci.yml:273) matches ^packages/squad-(sdk|cli)/templates/, not just src/ — template edits ship as scaffolding and are covered deliberately. Both packages distribute the gh-aw-enlistment skill, so both take a patch bump. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Note
Copilot was unable to run its full agentic suite in this review.
Copilot review overview
Review tier: Lite
Findings: 4
New issues introduced by this change (4)
| Severity | Finding |
|---|---|
 |
docs/src/content/docs/guide/gh-aw.md — The docs refer to the same safe-output operation as both add-labels (hyphen) and add_labels… |
|
docs/src/content/docs/guide/gh-aw.md — The docs refer to the same safe-output operation as both add-labels (hyphen) and add_labels… |
|
docs/src/content/docs/guide/gh-aw.md — These Markdown tables have an extra leading | on each row (|| ...), which will render as an… |
|
docs/src/content/docs/guide/gh-aw.md — These Markdown tables have an extra leading | on each row (|| ...), which will render as an… |
What changed in this PR
Documentation updates clarifying gh aw add enlistment output (referenced secrets vs required setup) and expanding guidance on activation behavior, labels, and incomplete results.
Changes:
- Clarify that listed secrets are referenced names (optional), and document auth precedence.
- Explain why
.github/skills/is staged while.github/aw/logs/is not. - Document activation semantics: auto-created labels, “accepted” vs “applied”, safe-output caps, and troubleshooting signals.
| File | Description |
|---|---|
| packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md | Adds clarification about referenced secrets and auth precedence during enlistment. |
| packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md | Same enlistment clarification for the CLI template copy. |
| .squad/skills/gh-aw-enlistment/SKILL.md | Same enlistment clarification for the repo-local skill copy. |
| docs/src/content/docs/guide/gh-aw.md | Adds staging guidance, secret clarification, and extensive activation/labeling/incomplete-run documentation. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…laim
Addresses review findings A-D on the activation section.
A. The cap table presented 75 as "issues created in one run", which would
lead a reader to size for 75. squad.md:105-107 states the actual
ceiling is 50 issues per activation run; 75 is 50 worst-case plus 25
bounded margin, and 110 covers both readings of the add-labels worst
case (50 calls / 100 label names). Now states the 50-issue ceiling as
the user-facing number and presents 75/110 as underlying headroom,
preserving the workflow's statement that `max` counts safe-output
items (tool calls), not label names.
B. Rescoped the label-evidence claim to the workflow's own epistemic
scope (squad.md:2059-2060): `create-issue`'s `labels:` field never
lands a label the activation run can claim. Dropped the generalized
assertion about GitHub API behavior. Note: "silently drops names the
repository lacks" is verbatim shipped prose at squad.md:2060 — the
scoping concern is upstream in the workflow, flagged rather than
propagated here.
C. Added the fast-path phase temporary ID `#aw_ph{N}` (squad.md:1289),
which was missing from the documented identifier set.
D. Listing labels proves a label exists, not that it landed on the right
issue. Added a per-issue verification path: read the Activation
bindings: block from the origin issue's comments, then compare each
binding against `gh issue view {issue} --json title,labels`.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
The newly added enlistment guidance uses “PAT” without defining it or tying it back to SQUAD_GITHUB_TOKEN, which can reintroduce setup ambiguity in the exact section meant to prevent misreads.
Review tier: Lite
Findings: 2
Pre-existing issues (2)
| Severity | Finding |
|---|---|
|
docs/src/content/docs/guide/gh-aw.md — The docs refer to the same safe-output operation as both add-labels (hyphen) and add_labels… View comment |
|
docs/src/content/docs/guide/gh-aw.md — The docs refer to the same safe-output operation as both add-labels (hyphen) and add_labels… View comment |
Issues resolved since last review (2)
| Severity | Finding |
|---|---|
|
docs/src/content/docs/guide/gh-aw.md — These Markdown tables have an extra leading | on each row (|| ...), which will render as an… View resolved comment |
|
docs/src/content/docs/guide/gh-aw.md — These Markdown tables have an extra leading | on each row (|| ...), which will render as an… View resolved comment |
Suppressed comments (3)
Previously missed (3) — in code that hasn't changed since the last review.
.squad/skills/gh-aw-enlistment/SKILL.md:138
- The enlistment skill uses the acronym "PAT" here without defining it, and it doesn’t tie the precedence rule back to the actual secret name (
SQUAD_GITHUB_TOKEN) that users see in the safe-update report. This can be confusing for first-time setup.
> `github.token`. Configure them only for cross-repo access or elevated
> permissions. Auth precedence: GitHub App token, then the PAT, then
> `github.token`. Never block an enlistment waiting for a credential.
packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md:138
- The enlistment skill uses the acronym "PAT" here without defining it, and it doesn’t tie the precedence rule back to the actual secret name (
SQUAD_GITHUB_TOKEN) that users see in the safe-update report. This can be confusing for first-time setup.
> `github.token`. Configure them only for cross-repo access or elevated
> permissions. Auth precedence: GitHub App token, then the PAT, then
> `github.token`. Never block an enlistment waiting for a credential.
packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md:138
- The enlistment skill uses the acronym "PAT" here without defining it, and it doesn’t tie the precedence rule back to the actual secret name (
SQUAD_GITHUB_TOKEN) that users see in the safe-update report. This can be confusing for first-time setup.
> `github.token`. Configure them only for cross-repo access or elevated
> permissions. Auth precedence: GitHub App token, then the PAT, then
> `github.token`. Never block an enlistment waiting for a credential.
Review flagged the two spellings as inconsistent. Audited every occurrence: all six are already correct for their surface. The hyphenated add-labels is the safe-outputs configuration key (squad.md:113) and is what the caps apply to; the underscored add_labels is the run-time tool call (squad.md:1294) and is what appears in summaries and incomplete reports. Rather than collapse them to one spelling, which would make one of the two surfaces unsearchable, this states the distinction explicitly at first joint mention. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
The enlistment SKILL mirrors use “the PAT” without naming SQUAD_GITHUB_TOKEN, which is a small but concrete ambiguity in the newly added credential guidance.
Review tier: Lite
Findings: None
Issues resolved since last review (4)
| Severity | Finding |
|---|---|
|
docs/src/content/docs/guide/gh-aw.md — These Markdown tables have an extra leading | on each row (|| ...), which will render as an… View resolved comment |
|
docs/src/content/docs/guide/gh-aw.md — These Markdown tables have an extra leading | on each row (|| ...), which will render as an… View resolved comment |
|
docs/src/content/docs/guide/gh-aw.md — The docs refer to the same safe-output operation as both add-labels (hyphen) and add_labels… View resolved comment |
|
docs/src/content/docs/guide/gh-aw.md — The docs refer to the same safe-output operation as both add-labels (hyphen) and add_labels… View resolved comment |
Suppressed comments (3)
Previously missed (3) — in code that hasn't changed since the last review.
.squad/skills/gh-aw-enlistment/SKILL.md:138
- The auth-precedence sentence uses “the PAT” without naming which secret that refers to, even though this section just introduced two secret names. Using the exact secret name (
SQUAD_GITHUB_TOKEN) makes the precedence unambiguous and avoids readers looking for a third credential.
> `github.token`. Configure them only for cross-repo access or elevated
> permissions. Auth precedence: GitHub App token, then the PAT, then
> `github.token`. Never block an enlistment waiting for a credential.
packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md:138
- The auth-precedence sentence uses “the PAT” without naming which secret that refers to, even though this section just introduced two secret names. Using the exact secret name (
SQUAD_GITHUB_TOKEN) makes the precedence unambiguous and avoids readers looking for a third credential.
> `github.token`. Configure them only for cross-repo access or elevated
> permissions. Auth precedence: GitHub App token, then the PAT, then
> `github.token`. Never block an enlistment waiting for a credential.
packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md:138
- The auth-precedence sentence uses “the PAT” without naming which secret that refers to, even though this section just introduced two secret names. Using the exact secret name (
SQUAD_GITHUB_TOKEN) makes the precedence unambiguous and avoids readers looking for a third credential.
> `github.token`. Configure them only for cross-repo access or elevated
> permissions. Auth precedence: GitHub App token, then the PAT, then
> `github.token`. Never block an enlistment waiting for a credential.
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.
Unblocks the fresh-repo E4 validation run (#1958), which is held idle waiting on this.
All four recently-merged activation fixes shipped with zero
docs/changes (verified per-commit:fa5cc26c#1965,9e3f6b34#1966,fb58f26d#1967,a47bdb89#1964). Keyword counts in the guide before this PR:create-if-missing0,add-labels0,temporary0,truncat0,capacity0.1. Credentials defect (highest value)
The bootstrap procedure listed
SQUAD_GITHUB_APP_PRIVATE_KEYandSQUAD_GITHUB_TOKENas a setup-time item with no statement that they need not exist. The clarification lived ~95 lines downstream under an "Optional:" heading a reader following the numbered path has no reason to have reached yet.This is a placement problem, not a contradiction — the two passages were already consistent. But two independent agents read the procedure top-to-bottom and concluded a PAT was a prerequisite for enlisting a fresh repo. It is not.
The correction now lands inline at the point of misreading: these are names
gh aw addreports as referenced for approval, they need not exist, and single-repo activation runs on the built-ingithub.token. Forward links to the auth-precedence sections are additive, not the fix.Mirrored byte-identically into all three
gh-aw-enlistment/SKILL.mdcopies, placed outside the<!-- allowlist-start -->/<!-- allowlist-end -->block so the bounded token/bullet assertions are untouched.test/gh-aw-enlistment-skill.test.tspasses 19/19, including mirror parity.2. The four merged fixes
Every behavioral claim traces to prose in
workflows/squad.mdondev:113-115,1307,1931-1945,2004add-labels(allowed: [squad, "squad:*"],create-if-missing: true) auto-creates labels; a fresh repo needs no manual setup111(75),121(110),1997,1999report_incomplete, the tracking issue1392,2058-20811997Accuracy traps deliberately honored
These sentences are awkward on purpose; the simpler wording would be false.
report_incompletedoes not fail the run.squad.md:1997— the run still concludessuccess. The guide says plainly thatgh run view --json conclusionis not how you detect truncation, and names the[aw] ... reported incomplete resulttracking issue as the durable signal.created < declared) and Step 2e (labeled < activated) have different triggers, messages, and remedies. Presented as a two-row table.squad.md:1999forbids offering a cap as a guessed cause, so the guide explicitly says an incomplete report will not always attribute the shortfall to a cap.proper labelstoSquad labels.Falsifiability
Per the review bar — each claim is checkable against real
ghoutput, not prose:gh issue list --search '"reported incomplete result" in:title' --state allgh issue list --label squad --json number,title,labelsActivation bindings:JSON block (squad.md:2022,2050-2054) is documented as the checkable verification surface, since a deterministic post-activation checker compares it against actual labels.3. Nits
Quick-start now forward-references the
.github/aw/logs/guidance before the stage-and-commit step, and "Install the workflows" explains why.github/skills/appears in the stage command.Validation
test/gh-aw-enlistment-skill.test.ts— 19/19 passworkflows/files touched, so theSOURCE_GROWTH_BUDGET_KBsize guard is not implicated (884 bytes of headroom left untouched)packages/*/src/changes — templates only, so no changeset. Confirmingchangelog-gateagrees.workflow-wiring-*drift surfaced by the build was reverted before staging; diff is exactly 4 files, zero deletionsPublishing
.github/workflows/squad-docs.ymltriggers on push todevormain, filtered to thedocs/path — it is merge-triggered, not PR-triggered. The site republishes automatically once this merges; no manual step.squad-docs-links.ymlisworkflow_dispatchonly.Do not merge without Brady's approval.