/setup-developer-skills

name: setup-developer-skills
description: Configure this repo for the /developer unattended spec-delivery pipeline — patches the issue tracker doc with the pipeline's Delivery operations, writes docs/agents/code-host.md and its phase annexes (GitHub, GitLab or local first-class; anything else as freeform), installs the dispatcher/code-author/diff-reviewer agents, ensures the triage labels exist, and asks for the run defaults written to docs/agents/developer-defaults.md. Requires /setup-matt-pocock-skills to have run first (refuses otherwise). Run once before first use of /developer.
disable-model-invocation: true

Setup Developer Skills

Scaffold the per-repo configuration that the `/developer` pipeline assumes. This builds **on top of** Matt Pocock's engineering skills setup — it does not replace it.

Two independent axes get configured, mirroring how the delivery skills read the repo:

• **Issue tracker** — where issues live (`docs/agents/issue-tracker.md`,

created by Matt's setup; this skill appends the pipeline's `## Delivery operations` section) plus its authoring annex (`docs/agents/issue-authoring.md`).

• **Code host** — where changes (PRs/MRs/branches) live

(`docs/agents/code-host.md`, created here) plus its CI annex (`docs/agents/code-host-ci.md`).

They may differ (issues in Linear, code on GitHub). **GitHub, GitLab and local are first-class** — templates ship with this skill. Anything else (Jira, Linear, Gitea…) is configured as freeform prose, exactly like Matt's setup handles "other" trackers.

**This skill is the only writer of these docs.** `/developer` and its workers read `AGENTS.md`, `CLAUDE.md` and everything under `docs/agents/` as instructions and never edit them — the one exception is `docs/agents/delivery-ledger.md`, which the harvest appends to because the dispatcher reads it back. So a doc that has drifted out of date is fixed here or by the human, and never as a side effect of a delivery run. Three things follow for this skill:

• **Update against the templates; leave the repo's own prose alone.** These

docs accumulate repo-specific text that no template contains — why a knob was set the way it was, a build trap, a test lane. Bring the *template* parts up to date and carry that text through untouched, even when a sentence in it looks stale. If something in it is now wrong, say so in the chat summary and let the user decide; correcting it is not what an update was asked to do.

• **A core file and its annexes, never one long file.** Every worker reads

`code-host.md` and `issue-tracker.md` **whole, in its first turn**, before looking at a line of code — so those two pay for their length once per worker per sub-issue. Mechanics used in only one phase of a job go in an annex, and the core links it with the phase that opens it spelled out: `code-host-ci.md` is opened only to wait for, read or classify a change's CI; `issue-authoring.md` only when issues are being created. Keep each core file **under ~100 lines**; when one grows past that, the fix is another annex, not a smaller font. This applies to the prose the repo adds later just as much as to the templates: a build trap or a test lane that belongs to one phase belongs in that phase's annex, or in the repo's own testing docs — not in the file every worker opens first. And a note about how the **harness** behaves — what the worktree sandbox does to a piped `gh`, which command shapes it refuses — is not a fact about this repo's code host at all: it is the same everywhere, it ships with the worker agents, and it does not belong in `code-host.md`. If you find one there, say so; the fix is an issue against the plugin, not a longer contract doc.

• **Prefer facts that do not rot.** When you write prose of your own into

these docs, describe how the repo works, not what some issue's state is today. A claim with a date on it goes out of date silently and invites the next session to "fix" it.

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

Process

1. Preconditions

• **Matt Pocock's setup must have run first**: check whether

`docs/agents/issue-tracker.md` exists. If it does not, **stop — scaffold nothing**. Matt's `setup-matt-pocock-skills` declares `disable-model-invocation: true`, so you cannot run it on the user's behalf; only the user can, as a slash command. Tell them:

> This repo isn't configured yet. Run `/setup-matt-pocock-skills` first > (namespaced as `/mattpocock-skills:setup-matt-pocock-skills` when > installed as a plugin), then re-run `/setup-developer-skills`.

If that skill isn't installed at all, point them at this repo's README for the install command instead.

• Read `docs/agents/issue-tracker.md` and note which tracker it describes

(GitHub / GitLab / local markdown / other) — step 3 patches it accordingly.

2. Determine the code host

Explore first: `git remote -v`.

• **No remote → Local, without asking.** A remote host is impossible

without a remote, so there is no decision to put to the user — announce the inference in one line ("No git remote — code host: local branches with a committed change file; reviews live in that file; `merge: auto` is unavailable, the pipeline always stops at ready-to-merge and you merge by hand") and continue. Only if the user objects to that announcement, fall through to **Other**.

• **Remote present → propose, and let the user confirm or override** (they

may track changes somewhere unexpected, e.g. Jira-driven review):

• Remote on `github.com` → **GitHub** — verify `gh auth status` succeeds.
• Remote on `gitlab.com` or a self-hosted GitLab → **GitLab** — verify

`glab auth status` succeeds.

• Anything else (or the user overrides) → **Other**: ask the user to

describe, in a paragraph, how changes are published, reviewed, and merged there; you will record it as fr