/developer

name: developer
description: Orchestrates unattended spec delivery — builds a spec's child issues in dependency order with code-author workers onto an integration branch (each build's model comes from the sub-issue's own ## Complexity section), then reviews the whole spec once with a diff-reviewer, runs a single fixer until CLEAN, and merges the spec PR per the repo's merge policy; a single issue gets the same build→review→fix on its own PR. The orchestration runs as a dynamic workflow (workflow.js next to this file); this skill resolves the run config, launches it and reports. Tracker- and host-agnostic — issues and changes live wherever docs/agents/issue-tracker.md and docs/agents/code-host.md say (GitHub via gh is the factory default). Factory defaults are parallel execution and manual merge; repo defaults live in docs/agents/developer-defaults.md and per-run flags (--parallel/--sequential, --auto-merge/--no-auto-merge) override them. Use when user says "/developer", "deliver this spec" (or "deliver this PRD"), "deliver this sub-issue", or wants the build→review→fix pipeline.

Developer (launcher)

The build → review → fix → merge pipeline runs as a **dynamic workflow**: `workflow.js`, next to this file. Its control flow — dependency order, the three-worker cap, fix cycles, the checks gate, serial merges, the conflict queue, escalation, wrap-up — is code, so no model re-reads a growing context on every worker result. Your part is small: publish the context docs, resolve the run config, launch the workflow, report what it returns.

A spec with sub-issues is delivered on an **integration branch**, `agent/developer/spec-<N>`: each sub-issue is built from its tip and merged into it with no checks gate and no review of its own — the worker ran the project checks; then the **spec PR** (that branch into `main`) gets one whole-spec review, a single fixer — for its `[blocking]` findings until CLEAN, once for its `[fix]` findings when nothing blocks — and the one CI gate before it merges. Reviewing sub-issues one at a time misses how they fit together. A single issue, or one sub-issue on its own, gets its own PR into `main` and its own review. A local code host or tracker keeps that per-PR flow for specs too.

Invoke

/developer <issue>              # spec with sub-issues → deliver them all
                                # plain issue → deliver just that one
/developer <spec> <subissue>    # deliver a single specific sub-issue

Flags (override the repo defaults — see Run configuration):
  --parallel | --sequential       # spec mode: concurrent vs one-at-a-time
  --auto-merge | --no-auto-merge  # merge CLEAN PRs vs leave them ready

If no issue number is given, ask for it and stop; never guess one. Accept the bare words `parallel` / `sequential` as synonyms of the flags.

> **Namespacing.** Installed as a plugin, the workers are > `developer-skills:code-author` and `developer-skills:diff-reviewer`; the > workflow names them that way. If your available-agents list shows other > names, stop and say so — the plugin is not loaded as expected.

1. Publish context docs

Workers branch from `origin/main`, so a domain-context file that is not committed **and pushed** is invisible to them:

git status --porcelain -- CONTEXT-MAP.md '**/CONTEXT.md' docs/adr docs/agents AGENTS.md CLAUDE.md

If anything shows up, stage **only those paths**, commit on the current branch (must be `main` — if not, stop and tell the user) and push:

git add CONTEXT-MAP.md '**/CONTEXT.md' docs/adr docs/agents AGENTS.md CLAUDE.md
git commit -m "docs(domain): publish context map and ADR updates"
git push origin main

If the push is rejected, stop and report — never rebase or force. A local tracker or code host changes this step: see `LOCAL-HOST.md`.

2. Run configuration

Read, in **one** call, `docs/agents/developer-defaults.md`, `docs/agents/code-host.md`, the `## Delivery operations` section of `docs/agents/issue-tracker.md` and `docs/agents/triage-labels.md` — the annexes (`code-host-ci.md`, `issue-authoring.md`) are not yours to read. Missing docs → GitHub defaults (suggest `/setup-developer-skills` if that looks wrong).

Two knobs — CLI flag > repo default > factory default; ignore any other key:

| Knob | Values | Factory default | |-------------|---------------------------|-----------------| | `execution` | `parallel` / `sequential` | `parallel` | | `merge` | `auto` / `manual` | `manual` |

• **`merge: auto`** — a CLEAN verdict leads to the checks gate and the merge.

The committed `merge: auto` line is the user's standing authorization.

• **`merge: manual`** — the pipeline stops at CLEAN with the PR marked ready:

the spec PR for a spec, the one PR otherwise. Sub-issues are merged into the integration branch either way — that never touches `main`.

• A **local code host** supports `manual` only: override `auto` and say so.

State it in one line, e.g. `Run config: execution=parallel, merge=manual (repo defaults)`.

3. Launch the workflow

The Workflow tool only runs a script path inside the working directory, and this skill lives in the plugin's install directory. Copy the script into the repo's `.scratch/` first (a run artifact, never staged):

mkdir -p .scratch && cp <skill-dir>/workflow.js .scratch/developer-workflow.js

Then call **Workflow** with `scriptPath: "<root>/.scratch/developer-workflow.js"` (absolute) and `args`:

| Arg | Value | |----------------|-------| | `spec`, `sub` | the issue numbers given (`sub` only with two arguments) | | `execution`, `merge` | the resolved knobs | | `github` | `true` when `code-host.md` says the host is GitHub | | `ci` | `false` when `code-host.md` says `CI: none`, else `true` | | `localHost`, `localTracker` | `true` when the respective doc says `local` | | `scripts` | `<skill-dir>/scripts`, absolute | | `root` | the primar