run-orchestrator

What this skill does

> **AI-consumed reference.** Optimized for Claude to read during execution.
> Human-readable explanation: see [docs/architecture/HIERARCHICAL_PLANNING.md](../../../docs/architecture/HIERARCHICAL_PLANNING.md)
> or [docs/getting-started/](../../../docs/getting-started/) depending on topic.


# Run Orchestrator

For complex features / multi-file changes requiring TDD. NOT for: bug fixes (use the `bugfix-quick` **skill** via the Skill tool — it is NOT an agent), quick edits (direct).

## Step 0 — Escalation Check (precondition, v3.7.2+)

Before creating run-state.json, screen the task description for project-level scope via the bridge heuristic in `rules/workflow/run-plan-bridge.md`. The 8-trigger rubric (multi_feature, multi_week, shipping_scope, scale_words, cross_session, user_explicit, word_count, scope_verbs) sums to a weight; if weight ≥ 3 AND no plan tree exists (`.claude/plans/active.json` missing), emit this 3-option prompt:

```
Your task scores ≥3 on the escalation heuristic — multi-feature / multi-session scope.
Options:
  plan    — bootstrap /aura-frog:plan first (writes pending-plan-bootstrap.json)
  deep    — proceed with normal Deep flow (escalation_declined: true recorded)
  details — show breakdown of which signals fired, re-ask
```

**Honour the answer:**

- `plan` → write `.claude/cache/pending-plan-bootstrap.json` (schema below) and invoke `/aura-frog:plan`. Do NOT proceed to Step 0b until the plan returns.
- `deep` (or legacy alias `proceed`) → set `escalation_declined: true` in the run-state when it's created. Continue.
- `details` → render which signals fired with weights, then re-ask.

**Skip the prompt when:**

- `.claude/plans/active.json` exists → fall through to Step 1 (plan_anchored / plan_idle states from `run-plan-bridge.md` apply).
- `AF_ESCALATION_DISABLED=true` env var is set.
- Task description has an override prefix: `task:` (force task mode, skip ask) or `project:` (force project mode, skip ask + write scratch file).
- Force prefixes `must do:` / `just do:` / `exactly:` are present (these bypass the entire bridge per the bridge rule).

### pending-plan-bootstrap.json schema

```json
{
  "schema_version": 1,
  "from_run_id": "auth-260511",
  "mission_seed": "<verbatim user task description>",
  "feature_seeds": ["auth", "billing", "dashboard"],
  "created_at": "2026-05-11T16:00:00Z",
  "trigger_weight": 5,
  "signals_fired": ["multi_feature", "shipping_scope", "scope_verbs"]
}
```

`feature_seeds` are extracted as comma-or-plus-separated noun phrases from the task; the plan command interview-confirms before minting Feature nodes. The file is deleted by `commands/plan.md` after consumption.

## Step 0b — Create the Run State (MANDATORY, BEFORE ANY OTHER WORK)

The moment you decide a `/run` invocation will use this orchestrator, write the initial state file. **Do NOT proceed without it.** Without the file, `/run status`, `/run resume`, and `/run handoff` cannot work — they all read from this file.

```bash
# Generate run-id: ticket prefix (JIRA-123) or short-name + YYMMDD (auth-260424)
RUN_ID="<derived from task or ticket>"
mkdir -p ".claude/logs/runs/${RUN_ID}"
```

Then write `.claude/logs/runs/${RUN_ID}/run-state.json` with this skeleton:

```json
{
  "run_id": "<RUN_ID>",
  "task": "<verbatim user task>",
  "status": "in_progress",
  "complexity": "<Quick|Standard|Deep|Project — from agent-detector>",
  "flow": "<direct|bugfix|refactor|test|feature-standard|feature-deep|security|review|deploy|quality>",
  "started_at": "<ISO 8601 UTC>",
  "current_phase": 1,
  "current_step": "<bugfix steps: investigate|test-red|fix-green|verify · otherwise omit>",
  "active_agent": "<lead|architect|frontend|… — read by scripts/statusline.sh>",
  "phases": {},
  "agents": [],
  "deliverables": [],
  "observations": [],
  "approvals": [],
  "tokens_used": 0
}
```

**Keep `current_phase` / `current_step` / `active_agent` in sync with reality** — `scripts/statusline.sh` reads them on every prompt to render the status bar. Stale values mean the user sees "P1 / lead" while you're actually executing P3 work via `architect`.

**Announce to user transparently:**

> "Detected: `<complexity>` complexity → `<flow>` flow. State file: `.claude/logs/runs/${RUN_ID}/run-state.json`. Say `deep` to escalate, `quick` to downgrade, or proceed."

For Deep runs, follow with the per-phase team announcement (see §5-Phase Workflow below): builder / reviewers / gate / dispatching-now. For Standard/Quick, one line: `🛠 Dispatching <agent> (<mode> / single-agent inline).`

This step is non-negotiable. If you skip it, /run status will show nothing and the user loses observability.

### Step 0c — Feature linking (v3.7.3+)

After writing run-state.json, register the run against its feature if anchored:

**Path A — `/run feature: FEAT-X <task>` prefix:**

```bash
bash "${CLAUDE_PLUGIN_ROOT}/scripts/plans/link-run.sh" link "${RUN_ID}" "<FEATURE_ID>" --status in_progress
# If a specific task is anchored, add: --anchor TASK-NNNNN
```

This writes both sides of the run ↔ feature link:
1. `run-state.json` gets `feature_id`, `feature_slug`, `feature_linked_at` (and `anchor.task_id` if `--anchor` passed)
2. The feature's `feature.md` gets a row in its `## Runs` table (creates the section if absent)

**Path B — Existing `active.json#active.task` set:**

The Run ↔ Plan bridge (Step 1) already anchors via `active.task`. After Step 1 confirms an anchor, also call link-run.sh so the feature.md side stays in sync.

**Path C — `/run resume <FEATURE_ID>`:**

```bash
bash "${CLAUDE_PLUGIN_ROOT}/scripts/plans/link-run.sh" list "<FEATURE_ID>"
```

Surface every row to the user; prompt to pick one (or auto-resume if only one is `in_progress`). Then `/run resume <run-id>` continues normally.

**On Phase 5 (Finalize) — update the link:**

```bash
bash "${CLAUDE_PLUGIN_ROOT}/scripts/plans/link-run.sh" link "${RUN_ID}" "${FEATURE_ID}" --status done
```

Same idempotent helper — overwrites the existing row with the new status. No duplicate entries.

---

## Step 0.5 — Scaffold Phase-1 Deliverables (MANDATORY for Standard/Deep)

Run-state.json tracks metadata; **the real deliverables are markdown files on disk**. Before announcing Phase 1, scaffold the Phase-1 documents so the work has a place to land:

```bash
bash "${CLAUDE_PLUGIN_ROOT}/scripts/workflow/scaffold-phase-deliverables.sh" "${RUN_ID}" 1
```

This creates (idempotent — never overwrites):

```toon
phase1_files[4]{filename,purpose}:
  REQUIREMENTS.md,User stories + acceptance criteria + scope
  TECH_SPEC.md,AI-readable TOON: architecture + files + APIs + risks
  TECH_SPEC_CONFLUENCE.md,Human-readable spec for Confluence / PRs
  DESIGN_DECISIONS.md,Low-level design choices + tradeoffs
```

**On each phase transition**, re-invoke the scaffold for the next phase:

```bash
bash "${CLAUDE_PLUGIN_ROOT}/scripts/workflow/scaffold-phase-deliverables.sh" "${RUN_ID}" <next_phase>
```

Phase mapping the scaffold creates:

```toon
scaffold_map[5]{phase,files}:
  1,"REQUIREMENTS · TECH_SPEC · TECH_SPEC_CONFLUENCE · DESIGN_DECISIONS"
  2,"TEST_PLAN · TEST_CASES"
  3,"IMPLEMENTATION_NOTES · FILES_CHANGED"
  4,"CODE_REVIEW · REFACTOR_LOG"
  5,"QA_REPORT · IMPLEMENTATION_SUMMARY · CHANGELOG_ENTRY"
```

**Skip Step 0.5 only for Quick/direct-edit runs** — those don't have phase deliverables. Bugfix/refactor/test/feature runs all use it.

**Gate enforcement** (per `rules/workflow/workflow-deliverables.md`): before showing a Phase N approval gate, verify the Phase N files exist AND have non-template content. Files that still match the template byte-for-byte mean the work wasn't done — block the gate and prompt the user to fill them in.

---

## Pre-Execution (Phase 1 setup)

1. agent-detector → select lead, complexity, model
2. **Apply context-economy** — locate before Read, use Glob/Grep first, slice large files with `offset`+`limit`, delegate broad exploration to Explore subagent. See `rules/core/context-economy.md`. **If you hit `overloaded_e