/setup-repo-skills

name: setup-repo-skills
description: 'Use when the user wants one-time repository setup for tracker, triage labels, and domain conventions. Not for ongoing triage, issue creation, or multi-repo setup.'
disable-model-invocation: true

Setup repo skills

Contract

| Field | Bound contract | |---|---| | Trigger | One-time repository setup for tracker and domain conventions. | | Authority | Human-gated: previews the complete write set and its consequences, getting separate confirmation for each configuration section; otherwise reversible local: writes only `docs/agents/` config files and one steering-file edit; rollback is version control. No remote mutation. | | Side effect | Tracker, domain, label, and single steering-file configuration. Exactly four write targets: `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md`, and one steering-file edit. Nothing else is created or modified. | | Done | Dependent workflows can read complete repository-local configuration: every confirmed `docs/agents/` file exists with the chosen conventions, and the steering file carries the `## Agent skills` block naming them. |

Not for

• Ongoing triage, issue creation, or multi-repo setup.

Inputs

• Required: a repository working tree and a human present to confirm one section at a time.
• Optional: prior output under `docs/agents/` (updated in place); an existing steering file (`CLAUDE.md` or `AGENTS.md`); monorepo signals (they decide whether the multi-context domain layout is offered).

Procedure

1. **Preview and explore.** State the four write targets named in the contract and that nothing else changes. Then read the repository without mutating it: `git remote -v` (GitHub, GitLab, or none); whether a root `CLAUDE.md` or `AGENTS.md` exists and whether it already carries an `## Agent skills` block; root `CONTEXT.md` and `CONTEXT-MAP.md`; `docs/adr/` and any `src/*/docs/adr/`; prior output in `docs/agents/`; `.scratch/` (a local-markdown tracker may already be in use); monorepo signals: `pnpm-workspace.yaml`, a `workspaces` field in `package.json`, or a populated `packages/*` with its own `src/`. Record findings; assume nothing. **Done when:** findings are recorded.

2. **Section A: issue tracker.** Lead with the recommendation so the human can accept it in a word: GitHub when a remote points at GitHub, GitLab when it points at GitLab. Otherwise offer GitHub (`gh` CLI), GitLab (`glab` CLI), local markdown under `.scratch/`, or other. For other, ask for a one-paragraph workflow description and record it as freeform prose in `docs/agents/issue-tracker.md`. One section, one confirmed answer, then the next section. **Done when:** the tracker choice is confirmed.

3. **Section B: triage labels.** Ask exactly one question: keep the five default triage labels? The defaults, each string equal to its role name: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. On yes, write them as-is. On no, usually because the tracker already uses other names, collect the existing string for each role so the mapping reuses existing labels instead of creating duplicates. **Done when:** the label set is confirmed.

4. **Section C: domain docs.** Default single-context (one `CONTEXT.md` plus `docs/adr/` at the root); write it without a question. Offer multi-context (a root `CONTEXT-MAP.md` pointing at per-context `CONTEXT.md` files) only when step 1 found monorepo signals, and confirm that choice. **Done when:** the domain layout is confirmed.

5. **Show drafts for editing.** Present the `## Agent skills` steering block and the three `docs/agents/` drafts built from the seeds below. Nothing is written until the human approves the drafts. **Done when:** the human approves or declines the drafts.

Steering block (fill the three one-liners from the confirmed sections):

   ## Agent skills

   ### Issue tracker
   <one-line summary of where issues are tracked>. See `docs/agents/issue-tracker.md`.

   ### Triage labels
   <one-line summary of the label vocabulary>. See `docs/agents/triage-labels.md`.

   ### Domain docs
   <one-line summary: single-context or multi-context>. See `docs/agents/domain.md`.

`docs/agents/issue-tracker.md` seed for GitHub:

   # Issue tracker: GitHub

   Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations; it infers the repo from `git remote -v` inside a clone.

   - Create: `gh issue create --title "..." --body "..."` (heredoc for multi-line bodies)
   - Read: `gh issue view <number> --comments`, fetching labels
   - List: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'`, with `--label` and `--state` filters
   - Comment: `gh issue comment <number> --body "..."`
   - Labels: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
   - Close: `gh issue close <number> --comment "..."`

   PRs as a request surface: **no** (flip to yes in this file only if external PRs are triaged as feature requests). When yes, PRs run through the same labels and states via the `gh pr` equivalents: `gh pr view <number> --comments`, `gh pr diff <number>`, list open PRs keeping only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE`, and `gh pr comment` / `gh pr edit --add-label`/`--remove-label` / `gh pr close`. GitHub shares one number space across issues and PRs, so resolve a bare `#42` with `gh pr view 42`, falling back to `gh issue view 42`.

   - "Publish to the issue tracker": create a GitHub issue.
   - "Fetch the relevant ticket": `gh issue view <number> --comments`.

   Map and tickets: the map is a single issue labelled `effort:map` holding the Notes / Decisions-so-far / Fog body; each ticket is a child issue linked as a GitHub sub-issue, where sub-issues are unavailable, add the child to a task list in the map