developer-skills

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

/developer <spec-issue>
        │
        ▼
   ┌────────────┐  complexity tier    ┌─────────────┐
   │ dispatcher │ ───────────────────▶│ code-author │──▶ draft PR
   │  (sonnet)  │    sonnet/opus      │ (worktree)  │
   └────────────┘                     └─────────────┘
                                            │
                                            ▼
                    NEEDS_FIXES      ┌───────────────┐
        ┌──────────────────────────  │ diff-reviewer │
        ▼                            │    (opus)     │
  ┌─────────────┐    re-review       └───────────────┘
  │ code-author │ ──────────────────▶       │ CLEAN
  │ (fix, ≤3×)  │                           ▼
  └─────────────┘                    merge (auto) or hand
                                     off ready-to-merge,
                                     next sub-issue …

• 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.
• Parallel by default, sequential on demand — independent sub-issues
  (per Blocked by order) are built concurrently in waves; merge conflicts
  between sibling PRs are resolved by an extra opus fix worker before each
  (always serialized) merge. sequential delivers one sub-issue fully before
  the next — with auto-merge, each PR then branches from a main that
  already contains the previous one, so merges never conflict.
• Model-tiered — a dispatcher agent scores each sub-issue
  (trivial/standard → sonnet, complex → opus); 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.
• 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: a CLEAN PR is marked ready and
handed to you, with the wrap-up listing the merge queue in dependency
order. Opt into merge: auto at setup (or pass --auto-merge) and it
merges PRs to main unattended when the reviewer verdict is CLEAN —
the diff-reviewer (Opus) is then the only gate.

Claude Code first

The full pipeline runs only on Claude Code. The skills follow the
cross-agent SKILL.md convention, but everything that makes the pipeline
work is Claude-specific: the subagent definitions (agents/*.md frontmatter
with model:/effort:), the Agent-tool orchestration with per-spawn model
override and worktree isolation, and the push notification at the end.
Other agentic tools (Cursor, Codex, etc.) use different agent file formats
and have no equivalent of these primitives.

The worker agents and skills (not the orchestration) also run on
Google Antigravity — see Antigravity below.

Install

The Claude Code plugin

Installs the skills and the three subagents 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:dispatcher and friends.

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.
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.
3. Check the three plugin agents are loaded: dispatcher, 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. If you pick auto-merge, it offers to
   pre-approve the needed CLI permissions (see below) so the unattended
   merge doesn't die on a permission prompt.

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 offers to write this configuration for you (the
merge rules only when you chose merge: auto), adapted to your code host —
split across two files because they are read from different scopes.
Expect a permission prompt when it writes them — .claude/ settings are
protected paths, so your approval at that prompt is the authorization (on
a denial, the skill prints the blocks for you to paste by hand). The
GitHub version by hand (replace OWNER/REPO; GitLab is the same shape
with the glab equivalents):

.claude/settings.json (shared, committable — pre-approves the gh
calls; explicit allow rules resolve before the auto-mode classifier runs):

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

.claude/settings.local.json (still per-project, but gitignored —
this rule embeds <plugin-root>, the plugin's install path on this
machine, which would break for teammates if committed; put it in
~/.claude/settings.json instead if you'd rather allow the bundled script
once for every project):

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

• permissions.allow pre-approves exactly the writes the pipeline needs:
  the reviews API (the diff-reviewer posts the inline review) and
  gh pr ready (the orchestrator flips the PR out of draft),
  gh pr comment (fix-pr replies to threads, escalation comments),
  gh pr merge (the orchestrator's auto-merge), and cleanup-worktrees.sh
  (the wrap-up sweep).

Scoping the reviews-API rule to your repo (rather than gh api:*) keeps the
blast radius small; the ready/comment/merge rules are gh-subcommand-scoped
and safe to allow globally in ~/.claude/settings.json if you prefer.

Antigravity

The Antigravity CLI (agy) imports Claude Code plugins natively, so the
whole repo installs straight from GitHub — skills and agents included:

agy plugin install https://github.com/sgomez/developer-skills

It clones the repo into ~/.gemini/config/plugins/developer-skills and
converts the Claude-format agents/*.md and skills/ on load. Reinstall to
update; agy plugin list / agy plugin uninstall developer-skills to manage.

Caveats: all five skills are imported, including the /developer
orchestrator, and Antigravity does have worktree isolation for agents. What
it lacks is per-spawn model tiers and effort: — subagents run on
Antigravity's own models, so the dispatcher's sonnet/opus triage
doesn't steer which model builds each sub-issue. The unattended loop is
best-effort outside Claude Code.

Requirements

• A configured issue tracker and code host (/setup-developer-skills writes
  both docs). First-class: GitHub (gh CLI
  authenticated), GitLab (glab CLI
  authenticated), and local (markdown issues under .scratch/, changes
  as local branches — no remote needed). Other trackers/hosts work as
  freeform configuration.
• Claude Code with subagents and worktree isolation (any recent version).
• git ≥ 2.31. Workers run in linked worktrees and check they are really in
  one — via git rev-parse --path-format=absolute — before checking anything
  out. Without that flag the check cannot tell a worktree from a subdirectory
  of your own checkout, and a worker can detach your HEAD.

Usage

/developer <spec-issue>           # deliver every open sub-issue (repo defaults)
/developer <spec-issue> --sequential --auto-merge
                                  # per-run overrides of the repo defaults
/developer <issue>                # plain issue (no sub-issues) → deliver just it
/developer <spec> <subissue>      # deliver one specific sub-issue
/implement-issue 42               # manual: issue → branch → TDD → draft PR
/review-pr 42                     # manual: review a PR, post inline comments
/fix-pr 42                        # manual: address unresolved review threads

The intended loop: write specs with /grill-with-docs (or /wayfinder when
the plan is too big for one session) + /to-spec + /to-tickets, then hand
each spec to /developer and go write the next one.

The division of labour: Matt's skills plan (grilling → spec → tickets,
with you in the loop) and offer a hands-on endpoint (/implement +
/code-review on your current branch). This pipeline is the AFK
counterpart of that endpoint: /developer launches isolated agents in
clean contexts to build (implement-issue), review (review-pr) and
validate each ticket unattended, gated by the CLEAN verdict instead of by
you. (Not sure which skill fits? /ask-matt.)

What's in the box

.claude-plugin/
  plugin.json               # plugin manifest
  marketplace.json          # lets you /plugin marketplace add sgomez/developer-skills
agents/                     # subagents, auto-loaded by the plugin route
  dispatcher.md             # complexity triage — pinned sonnet, effort: low
  code-author.md            # builder/fixer — model chosen per sub-issue
  diff-reviewer.md          # merge gate — pinned opus, effort: high
skills/
  developer/                # orchestrator: spec loop, fix cycles, merge policy
    LOCAL-HOST.md           # read only when the host/tracker is local
    MERGE-FIX.md            # read at the first merge conflict
    WRAP-UP.md              # read once, when the loop ends
  implement-issue/          # issue → branch → TDD → checks → draft PR
  review-pr/                # diff review → inline review → verdict
  fix-pr/                   # address review threads → push → reply
  setup-developer-skills/   # one-time repo setup (incl. run-defaults template)
    code-host-*.md          # code-host templates (github / gitlab / local)
    delivery-ops-*.md       # issue-tracker Delivery operations templates