orchestrate-dev

Files (8)

• SKILL.md
• evals.json · evals/
• trigger-evals.json · evals/
• capability-gating.md · references/
• early-start.md · references/
• sequential-fallback.md · references/
• task-graph.md · references/
• worker-health.md · references/

SKILL.md (first lines)

# orchestrate-dev

Turn one user objective into a task graph, run it, integrate it, and deliver **one PR**.

Role contract: [`core/roles/orchestrator.md`](../../../core/roles/orchestrator.md). Policies inherited, never restated here: [`core/policies/safety.md`](../../../core/policies/safety.md), [`core/policies/git.md`](../../../core/policies/git.md), [`core/policies/validation.md`](../../../core/policies/validation.md), [`core/policies/delivery.md`](../../../core/policies/delivery.md).

## The two separations that make this work

| Separation | Meaning |
|---|---|
| Objective ≠ task | The user asked for one thing. It is *executed* as several. |
| Work unit ≠ delivery unit | A task ends at **commit + handoff**. Only the objective ends at a PR. |
| Role ≠ provider | A task needs an implementer; whichever harness is available plays that role. |

**Validation tier: 2 (integration).** This skill runs the integration gates. Tier 1 belongs to `worker-dev`; Tier 3 belongs to CI via `pr-dev`.

## Step 0 — decide whether to orchestrate at all

Orchestration has real cost: branches, worktrees, state files, an integration pass. Do not pay it for a small change.

Fall through to `start-dev` (single worker + delivery) when **all** of these hold:

- one coherent change, plausibly one commit or a short series;
- one write scope — no two independent areas of the tree;
- no ordering constraint between sub-parts;
- no separate specialist pass genuinely needed (tests written alongside is not a second task).

Orchestrate when **any** of these hold:

- the request names several deliverables ("do these four things", a plan file, a review doc);
- parts touch disjoint areas and could progress independently;
- a real dependency exists (schema before API before UI);
- a distinct role is genuinely needed after implementation (security review of new auth, perf review of a hot path);
- the change is large enough that one combined-diff review at the end is materially better than reviewing it as it is written.

Say which way you decided and why, in one sentence, before doing anything else. If you fall through, invoke `start-dev` and stop.

**The hand-off is one-directional.** `start-dev` has its own routing test that
can send multi-part work here; this fall-through is the opposite direction, and
the two must never bounce. When you delegate, say so explicitly:

> Not orchestration — single scope, no ordering constraint. Handing to
> `start-dev` as a simple task; the orchestration decision is already made, do
> not route back.

Once you have delegated, you are done: do not re-evaluate, do not re-enter, and
do not accept the same request back. If `start-dev` ever returns it, treat that
as a routing bug and finish the work on the simple path rather than looping.

## Step 1 — resolve the objective

| Input | Resolution |
|---|---|
| Free text | Slugify into an objective id (`^[a-z0-9][a-z0-9-]*$`) |
| Spec/plan file | Read it; the file is the source of tasks |
| Issue number | `gh issue view N --json title,body` |
| Existing objective id | **Resume** — go to Step 9 |

Always check for an existing objective first — this is the resume path:

```bash
S=skills/dev-workflow/_shared/scripts/objective-state.sh
bash $S active   # active objective id, or empty + exit 1 when there is none
bash $S list
```

`active` is what other skills use to tell whether an objective is already in
flight — `start-dev` calls it to suppress PR creation for work that belongs to
an objective. If it returns an id you did not expect, resolve that before
starting a second objective.

## Step 2 — inspect the repository, load its rules

Read `CLAUDE.md` / `AGENTS.md`, the repo's own rules files, and the test/lint commands actually defined (`Makefile`, `package.json` scripts, `pyproject.toml`). You are about to hand these commands to workers; guessing them wastes every worker's run.

## Step 3 — check capabilities before you promise concurrency

```bash
jq -r '.platforms | to_entries[] | "\(.key): subagents=\(.value.capabilities.subagents.status) parallel=\(.value.capabilities.parallel_subagents.status) worktrees=\(.value.capabilities.worktree_isolation.status)"' \
  core/capabilities/platforms.json
```

Read the entry for the platform you are running on. Then pick a mode:

| `subagents` | `parallel_subagents` | Mode |
|---|---|---|
| native | native | **Concurrent** — dispatch independent tasks together |
| native | unsupported/partial | **Serialized dispatch** — one subagent at a time |
| unsupported | — | **Sequential** — see [`references/sequential-fallback.md`](references/sequential-fallback.md) |

If the registry is missing or the platform has no entry, assume **sequential** and say so. Never claim parallelism you did not verify. Full rules: [`references/capability-gating.md`](references/capability-gating.md).

## Step 4 — build the task graph

Decompose into tasks with **disjoint write scopes**. Two tasks that may write the same file are not parallel — either merge them into one task or make one depend on the other. Method and worked examples: [`references/task-graph.md`](references/task-graph.md).

```bash
S=skills/dev-workflow/_shared/scripts/objective-state.sh
bash $S init auth-system --title "Implement authentication system"
bash $S task-add auth-system --role implementer  --scope 'src/auth/**'   --title "Auth core"
bash $S task-add auth-system --role implementer  --scope 'src/api/**'    --title "API routes"
bash $S task-add auth-system --role test-engineer --scope 'tests/auth/**' \
       --depends-on task-001,task-002 --title "Integration tests"
bash $S validate auth-system
```

`validate` fails when two concurrent tasks share write scope. Fix the graph, do not override it.

Assign roles from [`core/roles/README.md`](../../../core/roles/README.md). Reviewer roles are read-only — a reviewer task produces findings, and the **integrator** applies fixes unless you explicitly create a fix task.

## Step 5 — select providers

Provider is metadata, never identity: it appears in `task.provider`, never in a branch name or a path. Default is `current` — the harness you are already running in. Only route a role elsewhere when that provider is genuinely available and configured. **Never require a second AI subscription for the objective to complete.**

## Step 6 — create branches and worktrees

```
main
└── objective/<id>              ← integration branch, cut from base_branch

From Tamircohen28/tamirs-superpowers, MIT.

More from Tamircohen28/tamirs-superpowers