git:20261007.ecb5a32 to git:20261007.bd0da28

---

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**,

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 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:

```bash

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:

```bash

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):

```bash

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 primary checkout's absolute path (`git rev-parse --show-toplevel`) |

| `label` | the escalation label from `triage-labels.md` (`ready-for-human` by default) |

| `date` | today, `YYYY-MM-DD` |

The workflow runs in the background; say in one line that it is running and

that `/workflows` shows its progress, then end your turn. **Do not poll.** Its

completion notification brings the result object; then go to step 4.

Never run a step of the pipeline yourself while the workflow runs — no

builds, reviews, merges or conflict resolution in this context. If the user

asks for something the workflow is already doing, say so.

**Interrupted** (the session was stopped, or the workflow failed midway):

within the same session, relaunch with the same `scriptPath` and `args` plus

`resumeFromRunId` — completed agents return their cached results. In a new

session, run `/developer <spec>` again: the plan asks the code host which

sub-issues already have a PR, and resumes each at review or at the fix cycle

instead of rebuilding it.

**A conflict on the human's own merge** (`merge: manual`, usually the spec PR

against a `main` that moved):

never resolve it here. Have them abort the half-merge (`git merge --abort`),

then launch the workflow with the same `args` plus `mergeFix: <PR>` — it runs

only the merge-fix job and its cleanup — and tell them to retry the merge

when it reports.

## 4. Report

Read `WRAP-UP.md` and follow it: push notification, chat summary, escalation

questions, the human's merge queue, proposed doc changes, execution report.

## Rules

- **The agent docs are read-only to this pipeline.** `AGENTS.md`,

`CLAUDE.md`, `CONTEXT-MAP.md`, `docs/adr/` and `docs/agents/` are

instructions the run obeys. The exceptions are step 1's commit of edits

the human already made and the harvest's append to

`docs/agents/delivery-ledger.md`. Anything else the run learns is

*proposed* in the report.

- Never run `git checkout`, `git pull` or any state-changing git command

here, except step 1's scoped commit+push.

- If the Workflow tool is not available, stop and say so: dynamic workflows

must be enabled (`/config`), and in `-p` mode allowed (`Workflow` in the

permission allow-list). There is no in-context fallback.