# Dev Orchestrator

> Default task orchestrator for all development and investigation work. Classifies tasks, decomposes into parallel workstreams if appropriate, and routes execution through the recipe runner. Replaces ultrathink-orchestrator.

- Skill: `rysweet/dev-orchestrator-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add rysweet/dev-orchestrator-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rysweet/dev-orchestrator-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: rysweet (https://skillmd.com/u/rysweet)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/rysweet/dev-orchestrator-2

---


# Dev Orchestrator Skill

## Workflow Graph

```mermaid
flowchart TD
    A[User Request] --> B{Classify Task}
    B -->|Q&A| C[analyzer agent]
    B -->|Operations| D[builder agent]
    B -->|Development| E{Recursion Guard}
    B -->|Investigation| E

    E -->|BLOCKED| F[derive-recursion-guard emits BLOCKED:*]
    F --> G["execute-single-fallback-blocked-{development,investigation}"]
    G --> R1_BLOCKED[Round 1 result]

    E -->|ALLOWED| H{Decompose Workstreams}
    H -->|"1 workstream<br/>(default-workflow or investigation-workflow)"| I[Execute recipe]
    H -->|N workstreams| J[multitask parallel]
    I --> R1[Round 1 result]
    J --> R1

    R1_BLOCKED --> REFLECT
    R1 --> REFLECT{Reflect on Round 1}
    REFLECT -->|ACHIEVED| SUM[Summarize]
    REFLECT -->|PARTIAL / NOT_ACHIEVED| K[Execute Round 2]
    K --> REFLECT2{Reflect on Round 2}
    REFLECT2 -->|ACHIEVED| SUM
    REFLECT2 -->|PARTIAL / NOT_ACHIEVED| L[Execute Round 3 - final]
    L --> REFLECT_FINAL[Final Reflect]
    REFLECT_FINAL --> VAL{Outside-In Testing Validation}
    REFLECT --> VAL

    VAL --> SUM
    SUM --> DONE[Complete Session + Cleanup]

    %% Adaptive error recovery path
    R1 -.->|empty result| DET[detect-execution-gap]
    DET --> FILE_BUG[file-routing-bug]
    FILE_BUG --> ADAPT{Adaptive Recipe}
    ADAPT -->|Investigation| INV_RECIPE[investigation-workflow]
    ADAPT -->|Development| DEV_RECIPE[default-workflow]
    INV_RECIPE --> REFLECT
    DEV_RECIPE --> REFLECT

    C --> DONE
    D --> DONE
```

## Purpose

This is the **default orchestrator** for all non-trivial development and investigation tasks
in amplihack. It replaces the `ultrathink-orchestrator` skill.

## Development Routing Invariant

Development classification always routes to `default-workflow`; model-provided recipe fields do not override that invariant.

Hybrid decompositions route each workstream by its own normalized classification.

This invariant is enforced by the Rust orchestration helper before workstream execution. Prompt instructions guide the model, but model-emitted `recipe` values are not trusted for Development workstreams.

When a user asks you to build, implement, fix, investigate, or create anything non-trivial,
this skill ensures:

1. **Task is classified** — Q&A / Operations / Investigation / Development
2. **Goal is formulated** — clear success criteria identified
3. **Workstreams detected** — parallel tasks split automatically
4. **Recipe runner used** — code-enforced workflow execution
5. **Outcome verified** — reflection confirms goal achievement

## How It Works

```
User request
     │
     ▼
[Classify] ──→ Q&A ──────────────────→ analyzer agent (technical/code questions)
     │
     ├──────→ Ops ────────────────────→ builder agent
     │
     └──→ Development / Investigation
             │
         [Recursion guard] (AMPLIHACK_SESSION_DEPTH vs AMPLIHACK_MAX_DEPTH=3)
             │         │
           ALLOWED   BLOCKED → [derive-recursion-guard prints BLOCKED:* to stderr]
                                    ↓
                  [execute-single-fallback-blocked-development]
                  [execute-single-fallback-blocked-investigation]
                                    ↓
                           [Execute round 1 (single-session)]
             │
         [Decompose]
             │         │
             1 ws     N ws ──→ [multitask parallel] + tree context in env
             │
         [Execute round 1]
             │
         [Reflect] ──→ ACHIEVED ──→ [Summarize]
             │
           PARTIAL/NOT_ACHIEVED
             │
         [Execute round 2]
             │
         [Reflect] ──→ ACHIEVED ──→ [Summarize]
             │
           PARTIAL/NOT_ACHIEVED
             │
         [Execute round 3 (final)]
             │
         [Final reflect + Summarize]
```

**Session tree enforcement** (prevents infinite recursion):

- Each subprocess inherits `AMPLIHACK_TREE_ID`, `AMPLIHACK_SESSION_DEPTH`, `AMPLIHACK_MAX_DEPTH`
- Depth >= 3: recursion guard blocks sub-workstream spawning, adapts to single-session
- Max 10 concurrent sessions per tree; extras queue in FIFO order
- State tracked in `/tmp/amplihack-session-trees/{tree_id}.json`

## Activation

This skill auto-activates for development and investigation keywords. It is also the
**default behavior** per CLAUDE.md — invoke it for any non-trivial task.

The `UserPromptSubmit` hook reinforces this by injecting a classification prompt
that instructs Claude to invoke `Skill(skill="dev-orchestrator")` for dev/investigation tasks.

## Execution Instructions

**YOUR NEXT ACTION after reading this skill MUST include a Bash tool call that
executes the recipe runner.** If your runtime requires a `report_intent` call
(e.g. Copilot CLI), emit it **in parallel** with the Bash launch — both tool
calls in the same response. The constraint is that no
_other_ substantive action (reading files, calling TodoWrite, invoking Agent,
or typing a response) may precede or replace the Bash launch.

If you find yourself doing anything else instead of launching the recipe
runner, you are bypassing the workflow. Stop. Go back. Run the recipe runner.

Development and Investigation tasks have exactly ONE execution path: the
recipe runner. There is no "Option B." There is no "I'll follow the steps
manually." There is no "Let me just quickly..." The recipe runner IS the
workflow. Skipping it means skipping the 23-step process, the recursion
guards, the goal verification, and the quality gates that exist for a reason.

A PostToolUse hook monitors every tool call after this skill activates. If
it detects 3 tool calls without recipe runner evidence, it will fire a hard
WARNING. Do not wait for the warning — run the recipe runner immediately.

When this skill is activated:

### REQUIRED: Execute via Recipe Runner — IMMEDIATELY

Your next tool call(s) must include the recipe runner launch (alongside
`report_intent` if your runtime requires it).

#### Default: Direct Execution (Rust recipe-runner-rs via CLI)

Use the Rust `recipe-runner-rs` through the `amplihack recipe run` CLI:

```bash
cd /path/to/repo && env -u CLAUDECODE \
  AMPLIHACK_HOME=/path/to/amplihack \
  amplihack recipe run amplifier-bundle/recipes/smart-orchestrator.yaml \
    -c task_description="TASK_DESCRIPTION_HERE" \
    -c repo_path="." \
    --verbose
```

**Key points:**

- `amplihack recipe run` — invokes Rust `recipe-runner-rs`; no Python runner or wrapper needed
- `-c key=value` — passes context variables (equivalent to `user_context` dict)
- `--verbose` — streams recipe-runner stderr live so you see nested step activity
- The recipe runner manages its own child processes (agent sessions, bash steps) as direct subprocesses

This is the preferred execution mode for most scenarios. It is simpler, has
no external dependencies beyond the Rust binary, works on all platforms,
and makes output capture straightforward.

For tmux durable execution, environment variables, error recovery strategies,
fallback recipes, and enforcement details, see [reference.md](./reference.md).

## Task Type Classification

| Type          | Keywords                                                       | Action                                              |
| ------------- | -------------------------------------------------------------- | --------------------------------------------------- |
| Q&A           | "what is", "explain", "how does", "how do I", "quick question" | Respond directly                                    |
| Operations    | "clean up", "delete", "git status", "run command"              | builder agent (direct execution, no workflow steps) |
| Investigation | "investigate", "analyze", "understand", "explore"              | investigation-workflow                              |
| Development   | "implement", "build", "create", "add", "fix", "refactor"       | `default-workflow` through smart-orchestrator       |
| Hybrid\*      | Both investigation + development keywords                      | Decomposed into investigation + dev workstreams     |

\* Hybrid is not a distinct task_type — the orchestrator classifies as Development and decomposes into multiple workstreams (one investigation, one development).

## Workstream Decomposition Examples

| Request                                  | Workstreams                             |
| ---------------------------------------- | --------------------------------------- |
| "implement JWT auth"                     | 1: auth (default-workflow)              |
| "build a webui and an api"               | 2: api + webui (parallel)               |
| "add logging and add metrics"            | 2: logging + metrics (parallel)         |
| "investigate auth system then add OAuth" | 2: investigate + implement (sequential) |
| "fix bug in payment flow"                | 1: bugfix (default-workflow)            |

## Override Options

**Single workstream override**: Pass `force_single_workstream: "true"` in the
recipe user_context to prevent automatic parallel decomposition regardless of
task structure. This is a programmatic option (not directly settable from `/dev`):

```bash
amplihack recipe run amplifier-bundle/recipes/smart-orchestrator.yaml \
  -c task_description="TASK_DESCRIPTION_HERE" \
  -c repo_path="." \
  -c force_single_workstream="true"
```

**To force single-workstream execution without modifying recipe context:**
Set `AMPLIHACK_MAX_DEPTH=0` before running `/dev`. This causes the recursion guard
to block parallel spawning and fall back to single-session mode for all tasks:

```bash
export AMPLIHACK_MAX_DEPTH=0  # set in your shell first
/dev build a webui and an api  # then invoke /dev in your agent session
```

Note: The env var must be set in your shell before starting the agent session — it
cannot be prefixed inline on the `/dev` command. This affects all depth checks, not
just parallel workstream spawning.

## Canonical Sources

- **Recipe**: `amplifier-bundle/recipes/smart-orchestrator.yaml`
- **Parallel execution**: native `amplihack orch` / `amplihack multitask` commands
- **Development workflow**: `amplifier-bundle/recipes/default-workflow.yaml`
- **Investigation workflow**: `amplifier-bundle/recipes/investigation-workflow.yaml`
- **CLAUDE.md**: Defines this as the default orchestrator

## Relationship to Other Skills

| Skill                     | Relationship                                         |
| ------------------------- | ---------------------------------------------------- |
| `ultrathink-orchestrator` | Deprecated — redirects here                          |
| `default-workflow`        | Called by this orchestrator for single dev tasks     |
| `investigation-workflow`  | Called by this orchestrator for research tasks       |
| `multitask`               | Called by this orchestrator for parallel workstreams |
| `work-delegator`          | Orthogonal — for backlog-driven delegation           |

## Entry Points

- **Primary**: `/dev <task description>`
- **Auto-activation**: Via CLAUDE.md default behavior + hook injection
- **Legacy**: `/ultrathink <task>` (deprecated alias → redirects to `/dev`)

## Status Signal Reference

The orchestrator uses two status signal formats:

### Execution status (from builder agents)

Appears at the end of round execution steps:

- `STATUS: COMPLETE` — the round's work is fully done
- `STATUS: CONTINUE` — more work remains after this round
- `STATUS: PARTIAL` — the final round (round 3) reached partial completion
- `STATUS: DEPTH_LIMITED` — (legacy, no longer emitted; use BLOCKED path instead)

### Goal status (from reviewer agents)

Appears at the end of reflection steps:

- `GOAL_STATUS: ACHIEVED` — all success criteria met, task is done
- `GOAL_STATUS: PARTIAL -- [description]` — some criteria met, more work needed
- `GOAL_STATUS: NOT_ACHIEVED -- [reason]` — goal not met, another round needed

The goal-seeking loop uses GOAL_STATUS signals to decide whether to run round 2 or 3.

**BLOCKED path (recursion guard)**: When multi-workstream spawning is blocked
by the depth limit, the orchestrator adapts to single-session execution:

1. `derive-recursion-guard` — classifies the guard result and prints the
   reason to stderr (`BLOCKED:registration_failed`, `BLOCKED:unknown`). There
   is no separate announcement step; the classification *is* the announcement.
2. `execute-single-fallback-blocked-development` or
   `execute-single-fallback-blocked-investigation` — executes the full task as
   a single builder agent session. The step chosen depends on the workstream's
   classification, which is why there are two.

Both live in `amplifier-bundle/recipes/smart-execute-routing.yaml`.

Note the scope of this path: it handles a run that is **already executing** and
is refused when it tries to descend further. It does not apply when
`amplihack recipe run` is itself invoked at the ceiling — there the guard
refuses before any recipe starts, and the correct response is to complete the
work inline rather than to launch a recipe (the refusal message says so).

A leftover `AMPLIHACK_SESSION_DEPTH` in a surviving shell does **not** wedge
you: an inherited depth that nothing corroborates — no tree id, no live
orchestrator ancestor — is discarded and the run starts a fresh tree at depth 0
(issue #1326).