setup-zsl-superpowers

Files (14)

• SKILL.md
• domain.md
• issue-tracker-github.md
• issue-tracker-gitlab.md
• issue-tracker-hybrid.md
• issue-tracker-local.md
• project-board.md
• remote-env.md
• remote-skills-hook.sh
• set-status-options.sh · scripts/
• test_set_status_options.sh · scripts/tests/
• ship-style-direct.md
• ship-style-pr.md
• triage-labels.md

SKILL.md (first lines)

# Setup ZSL Superpowers

Scaffold the per-repo configuration that the engineering skills assume:

- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box)
- **Triage labels** — the strings used for the six canonical triage roles
- **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
- **Ship style** — how changes reach the default branch (pull request or direct push)
- **Project board** *(optional)* — a GitHub Projects v2 board whose `Status` column should mirror triage labels and tdd lifecycle
- **Remote agent environment** *(optional)* — the claude.ai Claude Code environment id the overnight loop (`/afk-fanout`, `/afk-worker`) schedules remote sessions into

This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.

## Process

### 1. Explore

Look at the current repo to understand its starting state. Read whatever exists; don't assume:

- `git remote -v` and `.git/config` — is this a GitHub repo? Which one?
- `AGENTS.md` and `CLAUDE.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either?
- `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root
- `docs/adr/` and any `src/*/docs/adr/` directories
- `docs/agents/` — does this skill's prior output already exist?
- `.scratch/` — sign that a local-markdown issue tracker convention is already in use

### 2. Present findings and ask

Summarise what's present and what's missing. Then walk the user through the decisions **one at a time** — present a section, get the user's answer, then move to the next. Don't dump them all at once. Sections A–D are core; E (project board) and F (remote agent environment) are optional.

Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.

**Section A — Issue tracker.**

> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-issues`, `triage`, `to-prd`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.

Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:

- **GitHub** — issues live in the repo's GitHub Issues (uses the `gh` CLI)
- **GitLab** — issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI)
- **Local markdown** — issues live as files under `.scratch/<NNN>-<feature-slug>/` in this repo (`<NNN>` is an auto-assigned 3-digit feature number; good for solo projects or repos without a remote)
- **Hybrid (local markdown + GitHub mirror)** — issues live in `.scratch/` as the source of truth, but each is mirrored to a thin linked GitHub issue so it can appear on a **project board** (Section E). Pick this when you want `.scratch/` ergonomics *and* a board — a board can only track GitHub-native objects, so plain local-markdown issues can't appear on one (see the coupling note below). Uses the [issue-tracker-hybrid.md](./issue-tracker-hybrid.md) seed.
- **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose

> **Tracker ↔ board coupling.** A GitHub Projects v2 board (Section E) tracks items by their GitHub node ID. **GitHub** and **GitLab**(*) trackers have native issues to put on a board; **Local markdown** issues are files with no node ID, so they **cannot** appear on a board directly. If the user wants both local-markdown and a board, that's exactly the **Hybrid** option — don't quietly skip Section E, offer the hybrid. (*GitLab boards are out of scope here; Section E is GitHub Projects v2.)

**Section B — Triage label vocabulary.**

> Explainer: When the `triage` skill processes an incoming issue, it moves it through a state machine — needs evaluation, waiting on reporter, ready for an AFK agent to pick up, ready for a human, a tracking container for sub-issues, or won't fix. To do that, it needs to apply labels (or the equivalent in your issue tracker) that match strings *you've actually configured*. If your repo already uses different label names (e.g. `bug:triage` instead of `needs-triage`), map them here so the skill applies the right ones instead of creating duplicates.

The six canonical roles:

- `needs-triage` — maintainer needs to evaluate
- `needs-info` — waiting on reporter
- `ready-for-agent` — fully specified, AFK-ready (an agent can pick it up with no human context)
- `ready-for-human` — needs human implementation
- `tracking` — container/parent issue (e.g. PRD) — work lives in sub-issues
- `wontfix` — will not be actioned

Default: each role's string equals its name. Ask the user if they want to override any. If their issue tracker has no existing labels, the defaults are fine.

**Section C — Domain docs.**

> Explainer: Some skills (`improve-codebase-architecture`, `diagnose`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.

Confirm the layout:

- **Single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Most repos are this.
- **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo).

**Section D — Ship style.**

> Explainer: When a skill like `tdd` finishes a change, it needs to know how to get that change to the default branch. Team projects almost always go through pull requests; solo projects often push direct. This affects whether the skill creates a feature branch, opens a PR with a closing keyword, or commits straight to the default branch and closes the issue explicitly.

- **Pull request** — every change goes through a PR. Skills create a feature branch, push, and open a PR with `Closes #<issue>` in the body. The human merges.
- **Direct push** — changes go straight to the default branch. Skills commit, push, and close the related issue explicitly.

Default: pull request, unless the user specifies otherwise.

**Section E — Project board sync (optional, GitHub only).**

> Explainer: If you're using GitHub Projects v2 to track your issues on a board — or want to start — the `triage`, `to-issues`, and `tdd` skills can update a card's `Status` column whenever they change the issue's lifecycle (e.g. triaged to `ready-for-agent` → Status `Ready`; `tdd` starts work → `In progress`; PR opened → `In review`). Without this, the board stays static and you have to drag cards across columns manually. The skill can wire up either an existing board or create a fresh one. Skip this section if you don't want a project board, or if you'd rather wire the sync up via GitHub Actions yourself.

> **Requires a GitHub-native tracker.** A board tracks items by GitHub node ID, so this section only applies when Section A chose **GitHub** or **Hybrid (local markdown + GitHub mirror)**. If Section A chose plain **Local markdown**, there are no GitHub objects to track — don't silently skip the board the user asked for; go back and offer the **Hybrid** tracker, which mirrors each `.scratch/` issue to a GitHub issue precisely so it can land on a board. In hybrid mode the board tracks the **mirror issue**, and the skills resolve that issue's number from the `.scratch/` file's `github:` frontmatter before each Status update.

If the user opts in, walk them through:

1. **Identify or create the project.** Ask whether an existing Projects v2 board should be wired up, or whether to create a new one.

   - **Existing board.** Ask for the project URL (e.g. `https://github.com/users/<owner>/projects/<number>` or `https://github.com/orgs/<org>/projects/<number>`) or an `owner/number` pair. Parse out the owner and number.
   - **New board.** Ask for a title (default: the repo name). Determine the owner — for org-owned repos default to the org; for user repos default to the user — and confirm before creating. Then:
     ```bash
     gh project create --owner <owner> --title "<title>" --format json
     ```
     Capture the returned `number`, `url`, and node ID. Two follow-ups, both optional but worth offering:
     - **Link the repo** so issue/PR pickers know about the board: `gh project link <number> --owner <owner> --repo <owner>/<repo>`.
     - **Enable built-in workflows** at `<url>/workflows` — at minimum **Auto-add to project** (filter `repo:<owner>/<repo> is:issue,pr is:open`) and **Auto-close issue** (so closing an issue lands its card on `Done` without the skills having to). These workflows can't yet be toggled via `gh`; point the user at the URL.

2. **Fetch the project's structure.** Run:
   ```bash
   gh project view <number> --owner <owner> --format json
   gh project field-list <number> --owner <owner> --format json
   ```
   Capture the project's node ID (`PVT_…`), find the single-select field named `Status` (or whatever the user calls their lifecycle column — confirm with them), and capture its field ID (`PVTSSF_…`) and option IDs.

3. **Customise Status options if needed.** New projects ship with `Todo` / `In Progress` / `Done`. These skills work best with five canonical options — `Backlog`, `Ready`, `In progress`, `In review`, `Done` — because they map cleanly onto the triage and tdd lifecycle. Compare the option list from step 2 against the canonical five. If any are missing, ask the user which approach they'd prefer:

   - **Replace** the Status options with the canonical five (recommended for new boards, or older boards with no cards yet).

     > **Deterministic gate.** The `updateProjectV2Field` mutation has exactly one correct shape and the obvious prose drifts — the current GitHub GraphQL schema **rejects** a `projectId` argument on `UpdateProjectV2FieldInput` (`InputObject 'UpdateProjectV2FieldInput' doesn't accept argument 'projectId'`), so a hand-typed mutation that includes it fails mid-setup. Resolve and run the bundled script, which carries the correct mutation (it prints `optionId optionName` per option so you can capture the new IDs without a second `field-list`):
     >
     > ```bash
     > SSO=$({ ls "$PWD"/skills/*/setup-zsl-superpowers/scripts/set-status-options.sh 2>/dev/null
     >         ls "$HOME/.claude/skills/setup-zsl-superpowers/scripts/set-status-options.sh" 2>/dev/null
     >         ls -d "$HOME"/.claude/plugins/cache/zsl-superpowers/zsl/*/skills/*/setup-zsl-superpowers/scripts/set-status-options.sh 2>/dev/null | sort -Vr; } | head -1)
     > if [ -n "$SSO" ]; then
     >   bash "$SSO" <PVTSSF_…>      # the Status field ID from step 2
     > else
     >   echo "zsl-gate: set-status-options.sh unresolved — run the mutation by hand per the Fallback below"

From ZunoSmartLabs/zsl-superpowers, MIT.

More from ZunoSmartLabs/zsl-superpowers