developer-skills

developer-skills

Unattended spec delivery for Claude Code: you write specs, a pipeline of isolated agents implements every sub-issue — build → review → fix → merge — and pings you when it's done.

/developer <spec-issue>
        │
        ▼
   sub-issue's ## Complexity          ┌─────────────┐
   standard → sonnet ────────────────▶│ code-author │──▶ PR into
   complex  → opus                    │ (worktree)  │    agent/developer/spec-<N>
                                      └─────────────┘
                                            │ merge (no CI wait)
                                            ▼
                                  integration branch ◀── next sub-issue …
                                            │ all sub-issues in
                                            ▼
                    NEEDS_FIXES      ┌───────────────┐
        ┌──────────────────────────  │ diff-reviewer │  spec PR, reviewed
        ▼                            │    (opus)     │  whole
  ┌─────────────┐    re-review       └───────────────┘
  │ code-author │ ──────────────────▶       │ CLEAN
  │ (fix, ≤3×)  │                           ▼
  └─────────────┘                    merge into main (auto) or
                                     hand off ready-to-merge

• Configurable defaults — /setup-developer-skills asks how the pipeline should run in this repo and writes docs/agents/developer-defaults.md; per-run flags (--parallel/--sequential, --auto-merge/--no-auto-merge) override it. Factory defaults: parallel execution, manual merge.
• Orchestrated in code — the pipeline runs as a Claude Code dynamic workflow (skills/developer/workflow.js): dependency order, worker cap, fix cycles, checks gate and merges are the script's control flow, not a model re-reading a growing context on every worker result. Requires dynamic workflows enabled in /config.
• One integration branch, one whole-spec review — sub-issues are built from the tip of agent/developer/spec-<N> and merged into it with no review of their own; the spec PR into main is reviewed once, whole, and fixed by a single worker — the blocking findings and the [fix] ones the review asks for even when nothing blocks. Reviewed one PR at a time, sub-issues each grow their own copy of a shared helper and nobody sees how their screens interact. A single issue gets its own PR and its own review.
• Parallel by default, sequential on demand — up to three build and fix workers run at once, and a sub-issue starts the moment its Blocked by sub-issues are integrated; merge conflicts between sibling PRs are resolved one at a time by an extra worker (Sonnet, then Opus on a retry) before each (always serialized) merge. sequential delivers one sub-issue fully before the next, so each branches from a tip that already holds the previous one.
• Model-tiered — /to-tickets rates each sub-issue as it cuts the spec (a ## Complexity section: standard → sonnet, complex → opus; missing → sonnet), so no worker is spent scoring tickets; the fixer escalates one tier per fix cycle.
• Unattended with an escape hatch — max 3 review→fix cycles, then the sub-issue is labeled ready-for-human, commented on the spec, and the loop moves on. Push notification with the tally at the end.
• Human work waits, it does not stall — a ready-for-human sub-issue is never started, and what it blocks waits for a later run; the report lists both. Land the human's part as a PR into agent/developer/spec-<N> with Closes #<n> (or close a non-code task by hand) and re-run: the sub-issue counts as integrated. Sub-issues are closed as they integrate, so GitHub's sub-issue progress follows the run.
• Isolated — every worker runs in its own git worktree; the orchestrator never touches your checkout.
• Two-party by construction — the diff-reviewer posts COMMENT reviews only (the CLEAN summary is the pipeline's approval signal), and marking ready and merging stay with the orchestrator. No agent holds approval authority over agent-authored code.

By default /developer does not merge into main: the CLEAN spec PR is marked ready and handed to you (sub-issues are merged into the integration branch either way). Opt into merge: auto at setup (or pass --auto-merge) and it merges to main unattended when the reviewer verdict is CLEAN — the diff-reviewer (Opus) is then the only gate.

Claude Code only

developer-skills is a Claude Code plugin and runs only on Claude Code. The pipeline is built on Claude-specific pieces: the plugin's subagents (agents/*.md with model: and effort:), the dynamic workflow that orchestrates them, per-spawn model tiers, worktree isolation, the plugin's PreToolUse hooks and the push notification at the end. Other agentic tools — Cursor, Codex, Gemini or Antigravity — have no equivalent, and are not supported.

Install

The Claude Code plugin

Installs the skills, the two subagents and the hooks in one step:

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

Plugin components are namespaced: the skills appear as /developer-skills:developer, /developer-skills:setup-developer-skills, etc., and the agents as developer-skills:code-author and developer-skills:diff-reviewer.

Restart the session afterwards: plugins load at session start.

The next branch (early access)

Development lands on next before it's released. Point the marketplace at the branch instead of the default one — no checkout needed, same command on any machine:

/plugin marketplace add https://github.com/sgomez/developer-skills.git#next
/plugin install developer-skills@sgomez

Restart the session afterwards: plugins load at session start.

/plugin update will not update it. next carries one version for the whole cycle, so the installer sees nothing new and skips. To pick up new commits, uninstall and install again. A next build names itself in claude plugin list: its version is a pre-release of the release it's working toward (0.16.0-next and the like), never a bare number.

Go back to the published releases by re-adding the marketplace without the ref:

/plugin marketplace add sgomez/developer-skills

Contributors with a checkout have scripts/plugin-mode.sh for all of this — dev (this working tree, uncommitted edits included), next, prod, refresh, status.

Dependencies

This repo depends on mattpocock/skills (v1.1+) for spec authoring and repo configuration. Install the ones the pipeline needs with --skill:

npx skills add mattpocock/skills --skill setup-matt-pocock-skills,to-spec,to-tickets,tdd,grill-with-docs,grilling,domain-modeling,resolving-merge-conflicts,wayfinder,ask-matt

(or npx skills add mattpocock/skills and pick interactively / --skill '*' for everything.)

Setup (once per repo)

Two commands, in this order — the second builds on the first:

/setup-matt-pocock-skills    # 1. Matt's setup: issue tracker, triage labels, domain docs
/setup-developer-skills      # 2. this plugin: code host, delivery ops, agents, run defaults

The order is enforced, not just recommended: Matt's setup skill declares disable-model-invocation, so ours cannot run it for you — /setup-developer-skills refuses to start when the repo isn't configured yet (no docs/agents/issue-tracker.md) and asks you to run Matt's first.

/setup-developer-skills will:

1. Determine the code host (GitHub, GitLab, or local branches — anything else as freeform prose) and write its mechanics to docs/agents/code-host.md, with the CI mechanics in the deferred annex docs/agents/code-host-ci.md.
2. Patch docs/agents/issue-tracker.md with the pipeline's Delivery operations — how /developer reads issues, discovers children (native sub-issues on GitHub), checks blockers, comments, labels, and closes — and write docs/agents/issue-authoring.md, the rules /to-tickets follows when it creates children.
3. Check the two plugin agents are loaded: code-author, diff-reviewer.
4. Ensure the ready-for-agent / ready-for-human labels (or the tracker's equivalent) exist.
5. Ask for the repo's run defaults — parallel vs sequential execution, auto vs manual merge — and write them to docs/agents/developer-defaults.md.
6. Recommend the Claude Code settings the unattended run needs, for the project or globally, and list the entries an earlier version had you add that nothing uses any more (see below). It never edits your settings: you do.

Issues and code are independent axes: issues can live on GitHub, GitLab, local markdown under .scratch/ (all first-class), or anywhere you can describe (Jira, Linear, …); changes can live on GitHub PRs, GitLab MRs, or local branches. The skills carry the GitHub gh mechanics inline as the factory default and defer to the two docs for everything else. A local code host runs with merge: manual only.

Permissions (recommended)

/developer runs unattended, but the code-host writes it performs — posting reviews, marking PRs ready, commenting, merging — hit permission prompts by default. With nobody at the keyboard, one denial means the worker reports blocked and the sub-issue gets escalated instead of merged.

/setup-developer-skills recommends the rules below, adapted to your code host, and you add them yourself — it never writes a settings file. Pick the scope:

The GitHub rules (replace OWNER/REPO, or use repos/*/pulls/*/reviews* in the global file; GitLab is the same shape with the glab equivalents):