Setup developer skills

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).
• Code host — where changes (PRs/MRs/branches) live (docs/agents/code-host.md, created here).

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 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 freeform prose.

Then ask one more question, whatever the host: is there CI on changes, and how is its status read? The answer gates two behaviours — the orchestrator refuses to merge on red checks, and the reviewer skips its own install and test run when CI already reports green — so a wrong answer costs either a merged red build or a duplicated suite. Explore before asking (a .github/workflows/ or .gitlab-ci.yml in the repo is the answer most of the time) and confirm; where there is genuinely no CI on changes, record CI: none and the pipeline behaves exactly as it did before this question existed.

Write docs/agents/code-host.md from the matching template bundled in this skill folder (drop the HTML comment on the first line, and fill or delete the CI bullet per the answer above):

• code-host-github.md
• code-host-gitlab.md
• code-host-local.md

For Other, write the doc from scratch based on the user's description. It must answer, operation by operation, what the delivery skills will ask of it: change ref format · publish a change (draft) · change metadata (branch, head sha, state) · check out a change in a linked worktree (read-only review, and fix-that-pushes) · read the diff · read feedback / unresolved threads · post a review (inline + summary, the CLEAN convention) · mark ready · reply to a thread · comment on a change · merge (and whether unattended merge is supported at all) · issue auto-close on merge (yes/no) · CI on changes (none, or how to wait for the checks and how to read the ones recorded for a head sha). Anything the user's workflow cannot express (e.g. inline comments), record the degraded form the skills should use instead.

Idempotence: if docs/agents/code-host.md already exists, show its current host and content summary, and ask before rewriting.

3. Patch the issue tracker doc with Delivery operations

The /developer orchestrator and its workers drive the tracker through a fixed set of operations (read issue, enumerate children, check blocker, comment, label, close). Append the section that matches the tracker found in step 1 (drop the HTML comment on the first line):

• delivery-ops-github.md — native GitHub sub-issues (also instructs /to-tickets to create them)
• delivery-ops-gitlab.md — glab mechanics + Part of #<parent> markers
• delivery-ops-local.md — .scratch/ file conventions

For other trackers, write the ## Delivery operations section from scratch with the user: same operation list as above, in their tracker's terms (issue ref format included). Carry over the two requirements the bundled templates place on whatever splits a spec into tickets: children must be discoverable from the parent by a mechanic the pipeline can query, and each child must carry a ## Spec extract section with the parent's Implementation and Testing Decisions that apply to it, copied verbatim — that section is what lets a builder work from the ticket alone.

Idempotence: if a ## Delivery operations heading already exists in docs/agents/issue-tracker.md, replace that section instead of appending a duplicate. Same for the legacy heading ## Parent/child issues MUST be native sub-issues (written by older versions of this skill) — replace it with the new section.

4. Check the agents are available

The three worker agents ship with the plugin and are already loaded, namespaced as developer-skills:dispatcher, developer-skills:code-author and developer-skills:diff-reviewer:

• dispatcher — complexity triage (pinned sonnet, effort: low)
• code-author — implements / fixes (model chosen per sub-issue)
• diff-reviewer — review gate before auto-merge (pinned opus, effort: high)

If this skill's own name is not namespaced (it appears as /setup-developer-skills, not /developer-skills:setup-developer-skills), the plugin is not loaded and /developer will not find its workers. Stop and tell the user to install the plugin, then re-run this skill:

/plugin marketplace add sgomez/developer-skills
/plugin install developer-skills@sgomez

(Plugins load at session start — the user must restart the session after installing.)

5. Ensure the triage labels exist

/developer applies ready-for-human on escalation, and implement-issue lists work by ready-for-agent. Respect any label mapping in docs/agents/triage-labels.md. Mechanics per tracker:

• GitHub:

  gh label list --json name --jq '.[].name'
  gh label create ready-for-agent --description "Fully specified, an agent can pick it up" --color 0E8A16 2>/dev/null || true
  gh label create ready-for-human --description "Needs human attention" --color D93F0B 2>/dev/null || true
  

• GitLab: same pair via glab label create --name ready-for-agent --description "..." --color "#0E8A16" (and ready-for-human with #D93F0B); glab label list first.

• Local markdown: nothing to create — the roles are Status: line values, defined by convention in the tracker doc.

• Other: whatever the tracker doc's Delivery operations say "apply a triage label" means; if labels must pre-exist there, remind the user to create the two above.

6. Choose the run defaults

Ask the user two questions (AskUserQuestion, one call, both questions):

1. Execution — should /developer build independent sub-issues in parallel waves (recommended: faster; sibling-PR conflicts are resolved by merge-fix workers) or sequentially (one sub-issue fully delivered before the next)?

2. Merge — when the review verdict is CLEAN, should /developer merge the PR to main automatically, or mark it ready and leave the merge to a human (recommended)? Be explicit that auto means unattended merges to main with the opus diff-reviewer as the only gate, and that with manual the sub-issues stay open until the human merges, so dependent sub-issues wait for those merges.

   Skip this question when the code host is local — merge: auto is unsupported there (the code-host doc says why); record merge: manual and tell the user.

Write the answers to docs/agents/developer-defaults.md from the template developer-defaults.md (drop the HTML comment on the first line, set the two values in the fenced block).

Idempotence: if the file already exists, show the current values, ask the two questions with the current values as the recommended options, and rewrite the file.

Regardless of the merge choice, the pipeline's code-host writes will hit permission prompts — and with nobody at the keyboard a single denial escalates the sub-issue instead of delivering it. Offer to add the allowlist and the auto-mode context, split across two files because they are read from different scopes (merge with existing content in both):

• .claude/settings.json (shared, committable) — the permissions.allow rules for the host CLI. Narrow allow rules (fixed subcommands) resolve before the auto-mode classifier and keep the review / mark-ready / comment writes from being classified. The merge is the exception: in auto mode the classifier re-evaluates the pipeline's unattended gh pr merge as a "merge without human approval" pattern and denies it even when gh pr merge is allow-listed. That single command is handled deterministically by this plugin's PreToolUse hook (hooks/approve-merge.sh) — it grants a PreToolUse allow, which runs before the classifier, and fires only in merge: auto repos. The gh pr merge allow rule below still spares a prompt when the pipeline runs outside auto mode.
• .claude/settings.local.json (per-project too, but gitignored) — the allow rule for the bundled cleanup script: it embeds this machine's absolute plugin path, which would break for teammates if committed. A user who prefers configuring once may put it in ~/.claude/settings.json instead (the plugin path is the same for all their projects).

Write permissions rules only — never an autoMode block.

Expect a permission prompt on these writes. .claude/ settings files are protected paths: no allow rule pre-approves writing them. Show the user the exact JSON before writing; their approval at the prompt is the authorization. If the write is denied, do not retry or route around it — print the blocks and the target file paths and have the user paste them in.

GitHub (replace OWNER/REPO from git remote -v) — in .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(gh pr ready:*)",
      "Bash(gh pr comment:*)",
      "Bash(gh pr merge:*)",
      "Bash(gh api repos/OWNER/REPO/pulls/*/reviews*)"
    ]
  }
}

and in .claude/settings.local.json, with <plugin-root> resolved to this plugin's installed location (the directory two levels above this SKILL.md):

{
  "permissions": {
    "allow": [
      "Bash(bash <plugin-root>/skills/developer/scripts/cleanup-worktrees.sh:*)"
    ]
  }
}

Drop the merge rule when the user chose merge: manual (the ready/comment/review rules still save prompts during review and fix cycles).

GitLab: the analogous rules — "Bash(glab mr update:*)", "Bash(glab mr note:*)", "Bash(glab mr merge:*)", "Bash(glab api projects/*/merge_requests/*)" — plus the same cleanup-worktrees.sh rule in .claude/settings.local.json.

Local / Other: no merge or review-posting rules apply (local never auto-merges and its review is a committed file; for other hosts derive the allowlist from the commands recorded in docs/agents/code-host.md) — but still offer the cleanup-worktrees.sh rule: the wrap-up's --sweep is a pattern-matched worktree removal, exactly the shape the auto-mode classifier denies, and local runs hit it like any other.

7. Report

Summarise what was set up — tracker, code host, chosen defaults — and remind the user of the flow:

1. Grill/discuss a feature → /to-spec publishes the spec (PRD) issue.
2. /to-tickets <spec> breaks it into child issues discoverable by the pipeline (native sub-issues on GitHub; the tracker doc's equivalent elsewhere) with Blocked by ordering.
3. /developer <spec> delivers them all unattended — triage → build → review → fix cycles → merge per the chosen policy — and sends a push notification when done.

If they chose merge: auto, warn them explicitly: /developer will merge PRs to main unattended when the review verdict is CLEAN. If they chose manual (or the host forces it), remind them the wrap-up summary lists the ready-to-merge PRs in dependency order, and that per-run flags (--auto-merge, --sequential, …) override the defaults.