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