Gh Aw Enlistment

Context

Use this skill when a user wants to enlist a repository into Squad through GitHub Agentic Workflows (gh aw) — e.g. "set up Squad agentic workflows", "enlist this repo in Squad", or "install Squad gh-aw workflows". The end state is the /squad slash command being live on the repo, delivered as a human-reviewed bootstrap pull request — never an auto-merge.

This skill operationalizes the supported bootstrap path. It does not summarize it: each step below is a gate with explicit success evidence and STOP conditions. The authoritative source is docs/src/content/docs/guide/gh-aw.md (mirrored at https://bradygaster.github.io/squad/docs/guide/gh-aw/). If that guide and this skill ever disagree, the guide wins — re-read it before proceeding.

GitHub Issues are a hard prerequisite: /squad commands arrive as issue comments, and the merged bootstrap creates a research/proposals issue. Detect and enable Issues before creating the bootstrap branch or installing workflows, so the install cannot produce a PR whose post-merge bootstrap is unable to complete.

Portability contract: resolve every target repository identifier (owner, repo, default branch) at runtime. Never hardcode a placeholder like {owner}/{repo}. Resolve the supported Squad channel once to a 40-character commit SHA, then use that one immutable revision for the complete package.

Idempotency contract: the bootstrap is re-runnable. Never clobber existing workflows, prefer detecting prior state over duplicating it, and stop clearly on any unsafe or ambiguous condition rather than guessing.

Patterns

Run these steps in order. Treat every "STOP" as a hard halt: report the exact condition and wait for a human decision — do not work around it.

0. Preflight — verify before you touch anything

# gh is authenticated
gh auth status

# Prove the exact package-capable compiler version before creating artifacts
# gh-aw-exact-version-start
required_gh_aw_version="v0.91.5"
gh_aw_version_output="$(gh aw --version 2>&1)" || gh_aw_version_output=""
gh_aw_version="$(printf '%s\n' "${gh_aw_version_output}" | awk 'END {print $NF}')"

if [ "${gh_aw_version}" != "${required_gh_aw_version}" ]; then
  echo "Installing exact supported gh-aw ${required_gh_aw_version}."
  gh extension remove gh-aw >/dev/null 2>&1 || true
  gh extension install --pin "${required_gh_aw_version}" github/gh-aw
  gh_aw_version_output="$(gh aw --version 2>&1)" || {
    echo "STOP: gh-aw version could not be verified after clean installation." >&2
    exit 1
  }
  gh_aw_version="$(printf '%s\n' "${gh_aw_version_output}" | awk 'END {print $NF}')"
fi

test "${gh_aw_version}" = "${required_gh_aw_version}" || {
  echo "STOP: required gh-aw v0.91.5, but found ${gh_aw_version:-unavailable} after clean installation." >&2
  exit 1
}
# gh-aw-exact-version-end

# Capture repository identity and default branch AT RUNTIME
owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
default_branch="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
echo "Repo: ${owner_repo}  Default branch: ${default_branch}"

# Git state must be understood and clean enough to isolate the install
git status --short

Portability — compiler check: use the equivalent PowerShell commands to capture both output streams from gh aw --version. On any mismatch, remove github/gh-aw, cleanly install the exact v0.91.5 pin, and verify both streams again. Stop before branch creation or file generation unless that second check proves exactly v0.91.5; never select a newer release.

• STOP if gh auth status is not logged in, or is logged in as the wrong identity for this repo (see the gh-auth-isolation skill to operate as a specific account without switching the global default).
• STOP if owner_repo or default_branch cannot be resolved.
• STOP if exact gh-aw v0.91.5 cannot be proven after the clean pinned reinstall. Do not create a branch or generate repository files.
• STOP if the working tree has unrelated uncommitted changes you cannot account for — the bootstrap must land as an isolated, reviewable change.
• Confirm Copilot is enabled for the repository where checkable; the activation run and the requested @copilot review both depend on it.

1. Require GitHub Issues, then allow Actions-created PRs with a read-only token

Check the REST API's has_issues field first. If Issues are disabled, enable them before touching the install:

issues_enabled="$(gh api "repos/${owner_repo}" --jq '.has_issues')"
if [ "${issues_enabled}" != "true" ]; then
  echo "GitHub Issues are disabled; enabling them before workflow installation."
  if ! gh api --method PATCH "repos/${owner_repo}" \
    -F has_issues=true --silent; then
    echo "STOP: GitHub Issues are disabled and could not be enabled." >&2
    echo "A repository administrator must enable Settings > General > Features > Issues, then rerun enlistment." >&2
    exit 1
  fi
fi

test "$(gh api "repos/${owner_repo}" --jq '.has_issues')" = "true" || {
  echo "STOP: GitHub Issues must be enabled before installing Squad workflows." >&2
  exit 1
}

Reading .has_issues is non-mutating. Updating it through PATCH /repos/{owner}/{repo} requires repository administration permission. If the PATCH fails, STOP before branch creation or gh aw add and ask an administrator to enable Settings → General → Features → Issues. Do not continue with a bootstrap PR that cannot complete after merge.

Squad also opens PRs through GitHub Actions. Enable that without widening the default workflow token:

gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \
  -f default_workflow_permissions=read \
  -F can_approve_pull_request_reviews=false

can_approve_pull_request_reviews is a single, combined GitHub toggle: it does not just govern whether GITHUB_TOKEN can submit an approving review — the same switch also gates whether GITHUB_TOKEN is permitted to create pull requests at all (GitHub returns the literal error "GitHub Actions is not permitted to create or approve pull requests" for both operations; they cannot be separated via job-level permissions: alone). GitHub's own API reference calls enabling it a security risk, so Squad keeps it false for least privilege and never relies on GITHUB_TOKEN to self-approve.

With it false, the bootstrap job's own github.rest.pulls.create call will fail with that exact error. Squad's bootstrap workflow catches only that specific error and falls back automatically: it still pushes the squad/bootstrap-cast branch (the Cast PR's own branch — distinct from the chore/squad-gh-aw-bootstrap branch you create by hand in step 2 below), then opens (or, on a rerun, reuses) a tracking issue containing a ready-to-click GitHub compare URL (.../compare/<base>...squad/bootstrap-cast?expand=1&title=...) so a human can open the PR manually in one click. Any other pull-request creation error (for example, a PR that already exists) still fails the job normally — only this one documented, exact permission error is treated as expected. Every bootstrap and Cast PR, whichever way it is opened, still requires an independent human (or @copilot) approving review before merge. Keep default_workflow_permissions=read; do not set it to write.

2. Isolate the install on a bootstrap branch (preserve existing workflows)

git switch -c chore/squad-gh-aw-bootstrap

• If the branch already exists (a re-run), switch to it instead of recreating it.
• Never overwrite an existing .github/workflows/*.md or *.lock.yml that is not part of the Squad set. gh aw add is additive; if you see it about to replace an unrelated workflow, STOP.

3. Install the native package at an explicit, maintainer-approved revision

SQUAD_SHA must be supplied by the caller before this step — a specific, already-reviewed 40-character commit SHA. Never derive it by resolving the dev branch's current tip: dev is a continuously moving integration branch, so resolving it at install time installs whatever happens to be on it at that exact moment, with no maintainer vetting of that specific revision. Obtain the current supported revision from the Squad maintainers or the project's published release guidance, then set it once:

# SQUAD_SHA="<40-character commit SHA supplied by the maintainers>"
: "${SQUAD_SHA:?STOP: set SQUAD_SHA to an explicit, maintainer-approved 40-character Squad commit SHA before installing.}"
[[ "${SQUAD_SHA}" =~ ^[0-9a-f]{40}$ ]] || {
  echo "STOP: SQUAD_SHA must be the exact 40-character commit SHA, not a branch name or shortened hash." >&2
  exit 1
}
gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
rm -f .github/skills/agentic-workflows/SKILL.md

The nested workflows/aw.yml is the only supported distribution registration. It isolates package auto-discovery from unrelated repository skills and agents, and installs exactly eight workflows, seventeen runtime resources, and one gh-aw-enlistment skill at the same resolved revision:

• squad.md + squad.lock.yml
• squad-implement-worker.md + squad-implement-worker.lock.yml
• squad-review.md + squad-review.lock.yml
• squad-deps-worker.md + squad-deps-worker.lock.yml
• squad-retro.md + squad-retro.lock.yml
• squad-improvement-worker.md + squad-improvement-worker.lock.yml
• squad-bootstrap.md + squad-bootstrap.lock.yml
• squad-command-router.md + squad-command-router.lock.yml

squad-improvement-worker is part of the standard, coherent install above — not a separate opt-in add-on. It stays dormant until a maintainer approves a governance-scoped retrospective proposal (see the gh-aw guide's retrospective auto-implementation section); installing it alongside the other seven keeps the full stack consistent and avoids a second bootstrap pass later.

gh-aw v0.91.5 also materializes .github/skills/agentic-workflows/SKILL.md. That generic tool-owned router is not part of the Squad package and directs agents to mutable prompts from the current github/gh-aw repository rather than the pinned Squad revision. Remove that exact file after every gh aw add. Keep .github/skills/gh-aw-enlistment/SKILL.md: it is the one Squad-owned skill and the verifier requires its exact package bytes. Do not adopt or vendor the rest of gh-aw's generic scaffold.

Report/proposal-only is the default. Ordinary fixes require the explicit "squadRetroAutoImplement": "allow" setting in .squad/config.json; five action issues and three dispatches per wake-up remain separate caps. An improvement requires /squad approve-improvement, Approved-Revision: and exact Approved-Path: lines from a human with write/maintain/admin access. The dispatcher sends nested issue and approval-comment IDs to the worker; manual retries use those same IDs. /squad revoke-improvement is reserved without dispatch and is rechecked before outputs. Draft PRs and human merge remain mandatory; closed-unmerged PRs never cause automatic replacements. See the guide for content-hash calculation and the one-retry recovery policy.

SQUAD_SHA is supplied explicitly by the caller, never resolved from dev's moving tip; the install itself only ever installs that one immutable, already-approved revision.

4. Review the first-install safe-update report — approve ONLY the documented entries

On a clean repo, gh aw add reports these expected safe updates and nothing else:

<!-- allowlist-start -->

• Restricted secrets: SQUAD_GITHUB_APP_PRIVATE_KEY and SQUAD_GITHUB_TOKEN
• Action: bradygaster/squad/.github/actions/squad-init

<!-- allowlist-end -->

These are referenced names, not prerequisites. gh aw add lists the secrets the workflows reference so you can approve that surface — it is not asking you to supply them. Both secrets are optional, they need not exist, and neither is required to enlist a repository. Single-repo activation runs on the built-in 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.

If — and only if — the report contains exactly those documented entries, complete the one-time approval:

gh aw compile --strict --approve   # first install only, when the safe-update warning appears

• STOP if the report lists any other secret or any other action. Do not approve. Report the unexpected entry verbatim and wait for a human.
• This --approve step is only the first-install unblock. It is not a substitute for the final strict compile in the next step.

5. Always run the final strict compile WITHOUT --approve

node .github/workflows/shared/squad-install-verifier.mjs --materialize-runtime
gh aw compile --strict
node .github/workflows/shared/squad-install-verifier.mjs \
  --verify-install \
  --source-revision "${SQUAD_SHA}" \
  --strict-compile

This must run after any first-install approval and before committing. Success criteria:

• All eight workflows compile successfully.
• With gh-aw v0.91.5, require exactly two warnings, one occurrence of each exact diagnostic header below (including its workflow path):

<!-- compile-warning-allowlist-start -->

.github/workflows/squad-review.md: warning: pull_request_target is a very dangerous trigger.
.github/workflows/squad.md: warning: Both slash_command and bots triggers are configured. If a bot listed in bots: posts a comment that starts with the slash command text (e.g., /command-name), it will trigger the workflow and occupy the concurrency slot, potentially blocking simultaneous manual invocations. To ensure the workflow only runs on explicit user commands, remove the 'bots:' field.

<!-- compile-warning-allowlist-end -->

The native review advisory includes the compiler's standard explanation and Security Lab link. The following guard-policy dry-run lines are informational, not another warning. The bot-trigger warning is expected because github-actions[bot] enables controlled worker-continuation dispatches.

Accept the native review advisory only while all existing controls remain: same-repository head restriction, base-controlled workflow source, checkout: false agent path, API-only inspection, exact run/head/attempt guard, least-privilege jobs, advisory verdict, and independent human approval. pull_request_target is not generally safe; this narrow exception neither weakens those controls nor authorizes PR-head execution.

STOP on any error, or on any additional warning beyond these two exact documented diagnostics. Also STOP if either warning is missing, duplicated, changed, or attributed to another path, if the summary is not Compiled 8 workflows: 8 succeeded, 2 warnings, or if any required control is absent. Do not suppress warnings or use --approve to bypass this gate.