# Bootstrap Issues

> Bootstrap a repo for parallel autonomous agents coordinated via a dependency-aware GitHub Issues queue - creates work-queue labels (lifecycle plus afk/hitl autonomy), a CI test gate, branch protection with self-merge, an agent issue template, a committed DESIGN.md design system for frontend repos, and the AGENTS.md/CLAUDE.md workflow docs. Use when the user wants to set up the parallel-agent / GitHub Issues flow in a repo, "bootstrap issues", port the agent workflow to a new repo, or invokes /bootstrap-issues.

- Skill: `chieaid24/bootstrap-issues` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add chieaid24/bootstrap-issues`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chieaid24/bootstrap-issues/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: chieaid24 (https://skillmd.com/u/chieaid24)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chieaid24/bootstrap-issues

---


# Bootstrap Issues

Bootstraps the parallel-agent + GitHub Issues workflow in the current repo so several agents (Claude Code or Codex CLI, interchangeably) can each grab an issue, work in an isolated worktree, and self-merge through a CI gate. Work is ordered by native GitHub `blocked-by` dependencies; agents consume the queue with `/start-next-issue` and add to it with `/spec`.

This skill makes **outward-facing changes to a GitHub repo** (creates labels, sets branch protection, enables auto-merge). Always present the plan and get explicit confirmation before applying them - see step 3.

## Preconditions

Check these first; stop with a clear message if any fail:
- Inside a git repo with a GitHub `origin` (`git remote get-url origin`).
- `gh` is authenticated (`gh auth status`).
- **`gh` >= 2.94.0** - the dependency-aware queue reads `blockedBy`/`stateReason` JSON fields that older `gh` cannot return, so `/start-next-issue` would silently compute the wrong ready set. Check `gh --version` and tell the user to upgrade if older.
- **`git` >= 2.13** - the claim CAS uses `--force-with-lease=<ref>:` with an empty expect ("ref must not exist"). Older `git` ignores the empty form, and two agents can claim the same issue. Check `git --version`.
- Capture `<owner>/<repo>`, the default branch, and the repo's visibility (the security-audit disclosure split - public fix PRs for low/medium vs private advisories for high/critical - turns on public vs private):
  ```bash
  gh repo view --json nameWithOwner,defaultBranchRef,visibility --jq '{repo: .nameWithOwner, branch: .defaultBranchRef.name, visibility: .visibility}'
  ```

## 1. Detect the stack

Choose the CI template from what's at the repo root (or the obvious project subdir):

| Marker file | Template | Test command |
|---|---|---|
| `package.json` | `templates/ci-node.yml` | `npm test` |
| `pyproject.toml` / `requirements.txt` | `templates/ci-python.yml` | `pytest` |
| `Cargo.toml` | `templates/ci-rust.yml` | `cargo test` |
| `go.mod` | `templates/ci-go.yml` | `go test ./...` |

If the test command or project dir is ambiguous (monorepo, tests in a subdir like `backend/`), ask the user. Every template names its job `test`, so the required status check is always `test` regardless of stack.

**Also detect frontend UI.** The repo has a frontend if any of these hold: a `package.json` depending on a UI framework (`react`, `vue`, `svelte`, `solid-js`, `@angular/core`, `next`, `nuxt`, `astro`, `remix`), or committed `*.html` / `*.css` / `*.jsx` / `*.tsx` / `*.svelte` / `*.vue` files, or a `public/` / `src/components` tree. If markers are absent but the stack could host UI (a Node app), ask whether a frontend is planned. A backend-only Go/Rust/Python service, CLI, or library has no frontend - this gates step 2.

## 2. Design system interview (frontend UI repos only)

If step 1 found no frontend and none is planned, **skip this step** and note it skipped. Otherwise the repo gets a committed `DESIGN.md` that binds every future UI change, so grill the user on the design system **now**, before the plan confirmation. This is a conversation only - no mutations yet.

- **If `/impeccable` is installed**, run `/impeccable teach`. It grills more thoroughly and writes `PRODUCT.md` + `DESIGN.md` (the same files it later consumes from the repo root). Then skip the bundled interview.
- **Otherwise**, run the bundled interview in `templates/design-interview.md` - a one-decision-at-a-time grill distilled from impeccable's shared design laws: register (brand vs product), color **strategy** in OKLCH, the theme **scene sentence**, a type scale (ratio >=1.25), spacing rhythm, motion (ease-out exponential, no bounce), the **absolute bans**, and the AI-slop **reflex test**. Push back on category-reflex answers ("fintech -> navy + gold") until the system isn't guessable from the domain.

Hold the resolved decisions. `DESIGN.md` is written from `templates/design-md.md` during Apply (step 4) and committed with the shareable files - it is **not** gitignored like `CLAUDE.md`/`AGENTS.md`, because every agent must share it.

## 3. Build the plan - present, then wait for confirmation

Summarize exactly what will change, then ask the user to confirm before applying anything outward-facing:
- **Files:** `.github/workflows/ci.yml` (chosen template), `.github/ISSUE_TEMPLATE/task.md`. **Frontend repos also:** `DESIGN.md` (committed) from the step-2 interview.
- **Labels:** lifecycle - `ready`, `in-progress`, `review`, `blocked`; autonomy - `afk`, `hitl`; `prd` for parent specs; `security` for audit-filed findings.
- **Docs:** ensure `CLAUDE.md` exists; gitignore `CLAUDE.md` + `AGENTS.md`; symlink `AGENTS.md -> CLAUDE.md`; append the **Parallel agent workflow** section (plus the **Frontend / UI work** clause for frontend repos).
- **Pre-commit hooks:** via the `setup-pre-commit` skill - a stack-aware hook (format -> lint -> test) that runs before every local commit, mirroring the CI `test` gate. Committed so every agent shares it.
- **GitHub config:** branch protection on `<default-branch>` requiring the `test` check, **no required reviews** (so an agent merges its own PR); enable auto-merge + delete-branch-on-merge; probe the security-advisories API (the audit's high/critical fixes need it) and warn if it is unavailable.

## 4. Apply (after confirmation)

**Order matters:** land the workflow on the default branch BEFORE enabling branch protection, or other branches deadlock on a `test` check that never runs.

1. **Workflow + issue template.** Copy the chosen `templates/ci-<stack>.yml` -> `.github/workflows/ci.yml`; set the `push:` branch to `<default-branch>`, add `working-directory` if the project lives in a subdir, and make the test run once (non-watch - e.g. vitest needs `-- --run`; pytest/cargo/go already exit). Copy `templates/issue-task.md` -> `.github/ISSUE_TEMPLATE/task.md`.

2. **Docs pattern.** If `CLAUDE.md` is missing, create a minimal one (title + one-line overview). Add `CLAUDE.md`, `AGENTS.md`, and `.worktrees/` to `.gitignore` (under a `# Claude Code` / `# Codex` heading; skip lines already present) - without the `.worktrees/` line every agent sees every *other* agent's lane as untracked files, which pollutes `git status` and invites a stray `git add -A` into a PR. Symlink: `ln -s CLAUDE.md AGENTS.md` (skip if it exists). Append `templates/workflow-section.md` to `CLAUDE.md`, replacing every `<default-branch>` with the real branch name. **Frontend repos:** also append `templates/workflow-frontend.md`, and - unless `/impeccable teach` already wrote it in step 2 - write the resolved design decisions to `DESIGN.md` at the repo root using `templates/design-md.md`.

3. **Pre-commit hooks.** Invoke the **`setup-pre-commit`** skill for the same stack detected in step 1. It installs a format -> lint -> test pre-commit hook (Husky for JS/TS, the `pre-commit` framework for Python, a tracked `.githooks/` script for Rust/Go), verifies it, **commits its own files**, and records the per-clone activation command in the docs (Husky needs none; Python `pre-commit install`; Rust/Go `git config core.hooksPath .githooks`). Keep the hook's test command consistent with the CI workflow's so the local gate mirrors the `test` check. If the repo has no test/lint tooling, the skill omits those steps and says so.

4. **Labels - inline, never a committed script:**
   ```bash
   # Lifecycle
   gh label create ready       --color 0E8A16 --description "Refined and queued; grabbable once its blockers are completed" --force
   gh label create in-progress --color FBCA04 --description "Claimed (assignee) and being worked"                           --force
   gh label create review      --color 1D76DB --description "PR open, awaiting review/merge"                                --force
   gh label create blocked     --color B60205 --description "Escalated to a human (abandoned blocker, or CI failed 3x)"     --force
   # Autonomy - exactly one per work issue
   gh label create afk         --color C2E0C6 --description "Fully autonomous: an agent implements, tests, and merges it"   --force
   gh label create hitl        --color D93F0B --description "Human in the loop required; the autonomous worker skips it"    --force
   # Parent spec - carries neither autonomy label
   gh label create prd         --color 5319E7 --description "Product requirements document; parent of work slice issues"    --force
   # Security audit - a fallback finding the audit could not fix in-run; its fix PR must stay neutral
   gh label create security    --color EE0701 --description "Filed by a security audit; keep the fix PR neutral (no exploit detail)" --force
   ```

5. **Commit + land the workflow.** Stage the shareable files (`.github/`, plus `DESIGN.md` for a frontend repo), commit (`chore: add agentic-issues CI + issue template`), and push so `ci.yml` reaches `<default-branch>` (direct push as owner, or open + merge a bootstrap PR - the PR carries the workflow so its own `test` check can run). The pre-commit hook files (step 3) were already committed by that skill; `CLAUDE.md`/`AGENTS.md` are gitignored and stay local, but `DESIGN.md` is committed so every agent shares it.

6. **Branch protection + auto-merge.** Probe the Administration scope by enabling auto-merge:
   ```bash
   gh api -X PATCH repos/<owner>/<repo> -F allow_auto_merge=true -F delete_branch_on_merge=true -F allow_squash_merge=true
   ```
   - **403** -> the PAT lacks **Administration: write**. Skip protection, warn the user, and print the manual UI steps (Settings -> Branches: require the `test` status check, 0 required reviews; Settings -> General -> Pull Requests: allow auto-merge + auto-delete branches).
   - **Success** -> set protection. Write the body to a temp file in `$TMPDIR`, apply, then delete it:
     ```bash
     printf '%s' '{"required_status_checks":{"strict":false,"contexts":["test"]},"enforce_admins":false,"required_pull_request_reviews":null,"restrictions":null}' > "$TMPDIR/ai-prot.json"
     gh api -X PUT repos/<owner>/<repo>/branches/<default-branch>/protection --input "$TMPDIR/ai-prot.json"
     rm -f "$TMPDIR/ai-prot.json"
     ```

7. **Security-advisories capability (the audit's high/critical path).** The `security-audit` skill files high/critical findings as private advisories and develops each fix in the advisory's temporary private fork, so the base repo needs the security-advisories API. Probe it read-only:
   ```bash
   gh api "repos/<owner>/<repo>/security-advisories?per_page=1" >/dev/null
   ```
   - **Success** -> advisories are available; nothing to do.
   - **403/404** -> the repo cannot file advisories yet. On a **public** repo enable it under Settings -> Advanced Security -> **private vulnerability reporting**; on a **private** repo that toggle needs GitHub Advanced Security. Warn the user and print the step. Until then the audit's high/critical fixes fall back to advisory-only, with a human opening the private fork by hand.

   Bootstrap only guarantees the base repo can file advisories. It cannot pre-enable Actions in a fork that does not exist yet, so the private fork's own CI is the audit's concern, not bootstrap's.

## 5. Clean up

Remove every one-shot artifact created during bootstrap - the temp protection JSON and any scratch files. **Never leave a `setup-labels.sh` or similar in the repo.** Confirm `.github/` contains only `workflows/ci.yml` and `ISSUE_TEMPLATE/task.md`.

## 6. Report

State what changed, anything skipped (e.g. branch protection when the scope was missing + the manual steps; the design interview for a backend-only repo), whether a `DESIGN.md` was written, whether the security-advisories API is available (or the manual step to enable it), the pre-commit hook installed and its per-clone activation command (if any), and how the queue runs from here:

- **Fill the queue:** `/spec` - grill the idea -> update docs -> route by scope: publish a PRD with child slices for large features, or go straight to one or a few issues for small changes. Both reconcile against the open graph and label each issue `afk` or `hitl`.
- **Work the queue:** point each agent at `/start-next-issue` - it self-loops, grabbing the most-blocking ready **`afk`** issue, working it to a green-CI merge, then taking the next. `hitl` issues wait for you.
- **Review the queue:** `/catch-up` - reports what shipped, which lanes stalled, and which `hitl` issues are sitting on a human decision.

## Notes

- The job name `test` is the required-check context across every stack - keep it `test`.
- **Idempotent:** re-running skips existing labels (`--force` upserts), an existing `AGENTS.md` symlink, `.gitignore` lines already present, an existing `DESIGN.md` (don't overwrite a design system already in the repo - offer to re-run the interview instead), and (via `setup-pre-commit`) any pre-commit config files that already exist.
- **`DESIGN.md` is the binding design system.** Committed and shared (not gitignored), auto-loaded by `/impeccable` from the repo root, and every future frontend agent must conform to it - the appended **Frontend / UI work** docs point UI work at it.
- **`.github/ISSUE_TEMPLATE/task.md` is the per-repo source of truth for issue shape.** `/spec` reads it when filing issues (stripping frontmatter + comments, then applying labels as flags), so agent-filed and human-filed (web UI) issues come out identically shaped. Keep repo-specific gates - the `DESIGN.md` conformance line, branch-naming - in this template, **not** duplicated inside `/spec`; `templates/issue-task.md` here is only the seed, and the repo copy is expected to diverge with those specifics.
- **GitHub-only** (uses `gh`). For repos hosted elsewhere, only the docs + templates apply.
- Owner direct-pushes to the protected branch bypass the check (`enforce_admins=false`); agents go through PRs and hit the gate.
- **`afk`/`hitl` gate autonomy; `ready` gates refinement.** Orthogonal: a fully specified `hitl` issue is still `ready`. `/start-next-issue` requires `ready` **and** `afk`, so `hitl` never enters the ready set - a human works it, or relabels it `afk` once its decision is settled. Autonomy is a label rather than a body field because the ready set is a mechanical read that can't parse prose.
- The dependency queue (`blocked-by` edges, the `ready`/`completed` rule, the autonomy labels, the `refs/claims/*` claim CAS) is described in `templates/workflow-section.md` and consumed by `/start-next-issue`. Keep all four skills (`bootstrap-issues`, `/spec`, `/start-next-issue`, `/catch-up`) in agreement on those conventions.
- **`security-audit` feeds this queue too.** Its remediation phase opens auto-merging fix PRs (low/medium) straight against the `test` gate, files high/critical as private advisories with fixes in temporary private forks, and falls back to a `security`-labelled issue when an in-run fix cannot be verified. Bootstrap provisions what that needs: the `security` label, the advisories capability, and the `pull_request` CI trigger so a fix-PR branch runs `test`. When a worker takes a `security` issue it keeps the PR neutral (see `templates/workflow-section.md`). Keep this skill in agreement with `security-audit`'s `REMEDIATION.md`.