docs: require Issues before gh-aw installation

.changeset/gh-aw-issues-prerequisite.md

@@ -0,0 +1,6 @@
+---
+"@bradygaster/squad-cli": patch
+"@bradygaster/squad-sdk": patch
+---
+
+Require GitHub Issues to be enabled before installing Squad Agentic Workflows, and fail closed when the authenticated user cannot update the repository setting.

.github/agents.md

@@ -23,10 +23,15 @@ GitHub Agentic Workflows (`gh-aw`) are composable AI workflows triggered by slas
 > Agentic Workflows, execute the complete
 > [seven-step quick start](../docs/src/content/docs/guide/gh-aw.md#quick-start)
 > in their repository. Do not only quote or run the `gh aw add` command below.
-> The supported path configures workflow-created pull requests, installs and
-> validates the complete generated artifact set, commits it on an isolated
-> branch, and opens a human-reviewed bootstrap PR. Stop at that PR; the human
-> merges it. `/squad` slash commands become active only after that merge reaches
+> The supported path verifies that GitHub Issues are enabled (and enables them
+> when the authenticated user has repository administration permission),
+> configures workflow-created pull requests, installs and validates the complete
+> generated artifact set, commits it on an isolated branch, and opens a
+> human-reviewed bootstrap PR. If disabled Issues cannot be enabled, stop before
+> installation and ask a repository administrator to enable them. `/squad`
+> commands use issue comments, and bootstrap creates a research/proposals issue.
+> Stop at the bootstrap PR; the human merges it.
+> `/squad` slash commands become active only after that merge reaches
 > the repository's default branch.
 
 The quick start installs this workflow set:

.squad-templates/skills/gh-aw-enlistment/SKILL.md

@@ -7,8 +7,8 @@ source: "Operationalized from the authoritative Squad gh-aw guide (docs/src/cont
 triggers: [set up Squad agentic workflows, enlist this repo in Squad, enlist my repository in Squad, install Squad gh-aw workflows, install Squad agentic workflows, add Squad gh aw workflows, bootstrap Squad in this repo, onboard this repo to Squad, set up /squad slash commands, gh aw add squad]
 tools:
   - name: "gh"
-    description: "GitHub CLI — repo identity, Actions permissions, PR creation, review request, and check watching."
-    when: "Every step: preflight identity/auth, enabling Actions-created PRs, opening and watching the bootstrap PR."
+    description: "GitHub CLI — repo identity, Issues and Actions settings, PR creation, review request, and check watching."
+    when: "Every step: preflight identity/auth, requiring Issues, enabling Actions-created PRs, opening and watching the bootstrap PR."
   - name: "gh aw"
     description: "GitHub Agentic Workflows extension (github/gh-aw) — installs and strictly compiles the Squad workflow set."
     when: "Installing the seven @dev workflows and compiling them into deterministic .lock.yml files."
@@ -28,6 +28,12 @@ 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 repository identifier (owner, repo, default
 branch) **at runtime**. Never hardcode a placeholder like `{owner}/{repo}`. The only
 fixed identifier is the Squad source itself — `bradygaster/squad/workflows/...@dev` —
@@ -73,10 +79,37 @@ git status --short
 - Confirm Copilot is enabled for the repository where checkable; the activation
   run and the requested `@copilot` review both depend on it.
 
-### 1. Allow Actions-created PRs while keeping the default token read-only
+### 1. Require GitHub Issues, then allow Actions-created PRs with a read-only token
 
-Squad opens PRs through GitHub Actions. Enable that **without** widening the
-default workflow token:
+Check the REST API's `has_issues` field first. If Issues are disabled, enable
+them before touching the install:
+
+```bash
+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:
 
 ```bash
 gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \
@@ -295,6 +328,21 @@ gh pr checks --watch
 owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
 default_branch="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
 
+issues_enabled="$(gh api "repos/${owner_repo}" --jq '.has_issues')"
+if [ "${issues_enabled}" != "true" ]; then
+  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
+}
+
 gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \
   -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true
 
@@ -353,6 +401,9 @@ gh pr merge --squash                # auto-merge before human review. NEVER.
 
 - ❌ **Hardcoding repository identifiers.** Always resolve `owner/repo` and the
   default branch at runtime with `gh repo view`.
+- ❌ **Installing while GitHub Issues are disabled.** `/squad` commands and the
+  bootstrap research/proposals issue require Issues. Enable them first, or stop
+  before installation if repository administration permission is unavailable.
 - ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only
   `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path.
 - ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`,

README.md

@@ -561,7 +561,31 @@ If you use [GitHub Agentic Workflows](https://github.blog/changelog/2025-05-19-g
 
 <!-- cspell:ignore agentics -->
 
+Squad requires GitHub Issues: slash commands are issue comments, and the merged
+bootstrap creates a research/proposals issue. Follow the
+[supported seven-step quick start](docs/src/content/docs/guide/gh-aw.md#quick-start),
+which checks and enables Issues before installation when the authenticated user
+has repository administration permission, and stops before creating a bootstrap
+PR when an administrator must enable them.
+
 ```bash
+set -euo pipefail
+
+owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
+issues_enabled="$(gh api "repos/${owner_repo}" --jq '.has_issues')"
+if [ "${issues_enabled}" != "true" ]; then
+  if ! gh api --method PATCH "repos/${owner_repo}" \
+    -F has_issues=true --silent; then
+    echo "STOP: A repository administrator must enable Settings > General > Features > Issues." >&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
+}
+
 gh aw add \
   bradygaster/squad/workflows/squad.md@dev \
   bradygaster/squad/workflows/squad-implement-worker.md@dev \

docs/src/content/docs/guide/gh-aw.md

@@ -33,7 +33,23 @@ owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
 default_branch="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
 gh extension list | grep -q 'github/gh-aw' || gh extension install github/gh-aw
 
-# 2. Allow GitHub Actions to create pull requests
+# 2. Require GitHub Issues, then allow GitHub Actions to create pull requests
+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 this quick start." >&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
+}
+
 gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \
   -f default_workflow_permissions=read \
   -F can_approve_pull_request_reviews=true
@@ -104,6 +120,15 @@ contains the complete seven-workflow set. For a repeatable upgrade, pin all
 seven entries to one reviewed commit as described in
 [Upgrading the workflows](#upgrading-the-workflows).
 
+Step 2 deliberately checks Issues before creating the bootstrap branch or
+installing any workflow. Squad commands are issue comments, and the merged
+bootstrap creates a research/proposals issue; without Issues, the installation
+PR could merge but the bootstrap journey could not complete. Reading
+`.has_issues` is safe for normal repository access. Enabling it through
+`PATCH /repos/{owner}/{repo}` requires repository administration permission. If
+that update fails, stop before installation and ask an administrator to enable
+**Settings → General → Features → Issues**, then rerun the quick start.
+
 > Step 7 stages `.github/skills/` because `gh aw add` installs the Squad skills
 > alongside the workflows, and it deliberately does not stage `.github/aw/logs/`.
 > Downloaded workflow logs are local diagnostic output — see [ignoring downloaded
@@ -136,13 +161,43 @@ issues exist.
 | Requirement | Details |
 |-------------|---------|
 | GitHub repo with Copilot | Copilot must be enabled for the repository |
+| GitHub Issues | Required for `/squad` issue comments and the bootstrap research/proposals issue; a repository administrator must be available to enable Issues if they are disabled |
 | `gh` CLI | [Install the GitHub CLI](https://cli.github.com/) and authenticate with `gh auth login` |
 | `gh aw` extension | `gh extension install github/gh-aw` |
 
 ---
 
 ## Setup
 
+### Enable GitHub Issues
+
+Squad receives commands through issue comments, and `squad-bootstrap` creates a
+research/proposals issue after the workflow-installation PR merges. Check the
+repository setting and enable it before installing any workflows:
+
+```bash
+owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
+issues_enabled="$(gh api "repos/${owner_repo}" --jq '.has_issues')"
+
+if [ "${issues_enabled}" != "true" ]; then
+  if ! gh api --method PATCH "repos/${owner_repo}" \
+    -F has_issues=true --silent; then
+    echo "STOP: A repository administrator must enable Settings > General > Features > Issues." >&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
+}
+```
+
+The GET is non-mutating, and the conditional PATCH makes this safe to rerun.
+Changing `has_issues` requires repository administration permission. If the
+PATCH fails, do not continue to `gh aw add`: have an administrator enable Issues
+in repository settings, then rerun the supported quick start.
+
 ### Allow workflow-created pull requests
 
 Squad opens pull requests through GitHub Actions. Enable this repository setting
@@ -384,6 +439,7 @@ Use this checklist for the initial bootstrap and after any workflow update:
 
 | Stage | Action | Expected evidence |
 |-------|--------|-------------------|
+| Repository readiness | Confirm `.has_issues` is `true`; if it is `false`, enable it before installing workflows | GitHub Issues are available for `/squad` comments and the bootstrap research/proposals issue; insufficient administration permission stops the install before a bootstrap PR is created |
 | Install | Run the seven-workflow `gh aw add` command on a bootstrap branch | All seven `.md`/`.lock.yml` pairs exist, with shared imports, `.github/aw/`, installed skills, and `.gitattributes` included in the diff |
 | Compile | Review any first-install safe-update report, approve only the documented entries, then run `gh aw compile --strict` without approval | All seven workflows succeed, only documented warnings remain, and all fourteen source/lock files exist |
 | Bootstrap review | Open the PR, request `@copilot`, wait for checks, and merge only after human approval | The default branch receives the complete generated install as one human-reviewable change |

packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md

@@ -7,8 +7,8 @@ source: "Operationalized from the authoritative Squad gh-aw guide (docs/src/cont
 triggers: [set up Squad agentic workflows, enlist this repo in Squad, enlist my repository in Squad, install Squad gh-aw workflows, install Squad agentic workflows, add Squad gh aw workflows, bootstrap Squad in this repo, onboard this repo to Squad, set up /squad slash commands, gh aw add squad]
 tools:
   - name: "gh"
-    description: "GitHub CLI — repo identity, Actions permissions, PR creation, review request, and check watching."
-    when: "Every step: preflight identity/auth, enabling Actions-created PRs, opening and watching the bootstrap PR."
+    description: "GitHub CLI — repo identity, Issues and Actions settings, PR creation, review request, and check watching."
+    when: "Every step: preflight identity/auth, requiring Issues, enabling Actions-created PRs, opening and watching the bootstrap PR."
   - name: "gh aw"
     description: "GitHub Agentic Workflows extension (github/gh-aw) — installs and strictly compiles the Squad workflow set."
     when: "Installing the seven @dev workflows and compiling them into deterministic .lock.yml files."
@@ -28,6 +28,12 @@ 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 repository identifier (owner, repo, default
 branch) **at runtime**. Never hardcode a placeholder like `{owner}/{repo}`. The only
 fixed identifier is the Squad source itself — `bradygaster/squad/workflows/...@dev` —
@@ -73,10 +79,37 @@ git status --short
 - Confirm Copilot is enabled for the repository where checkable; the activation
   run and the requested `@copilot` review both depend on it.
 
-### 1. Allow Actions-created PRs while keeping the default token read-only
+### 1. Require GitHub Issues, then allow Actions-created PRs with a read-only token
 
-Squad opens PRs through GitHub Actions. Enable that **without** widening the
-default workflow token:
+Check the REST API's `has_issues` field first. If Issues are disabled, enable
+them before touching the install:
+
+```bash
+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:
 
 ```bash
 gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \
@@ -295,6 +328,21 @@ gh pr checks --watch
 owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
 default_branch="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
 
+issues_enabled="$(gh api "repos/${owner_repo}" --jq '.has_issues')"
+if [ "${issues_enabled}" != "true" ]; then
+  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
+}
+
 gh api --method PUT "repos/${owner_repo}/actions/permissions/workflow" \
   -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true
 
@@ -353,6 +401,9 @@ gh pr merge --squash                # auto-merge before human review. NEVER.
 
 - ❌ **Hardcoding repository identifiers.** Always resolve `owner/repo` and the
   default branch at runtime with `gh repo view`.
+- ❌ **Installing while GitHub Issues are disabled.** `/squad` commands and the
+  bootstrap research/proposals issue require Issues. Enable them first, or stop
+  before installation if repository administration permission is unavailable.
 - ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only
   `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path.
 - ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`,