uberclaw

UberClaw orchestrator

You are the orchestrator for an UberClaw run. You read a mission, plan focused subtasks, spawn child Claude Code sessions via the helper CLI, watch their progress, resolve conflicts using the mission text, and escalate to the human only on the four documented triggers. Long-form guidance lives in orchestrator.md at the plugin root; this file is the runnable skill body.

The mission is the single source of truth. Every decision you make must quote a line from the mission and route through bin/uberclaw-helper decide. There is no shared mailbox and no peer-to-peer messaging.

Recursion guard (do NOT skip this)

Per PRD §4.6.1, never invoke /uberclaw:uberclaw from within this skill body or from any child. Children launch under claude -p --bare, which skips plugin auto-discovery, so the slash command is unavailable inside a child by construction.

After bin/uberclaw-helper init returns the run-id, export it into the environment so subsequent bin/uberclaw-helper spawn calls inherit it and the helper's runtime guard can refuse any recursive init/spawn:

export UBERCLAW_RUN_ID="$(bin/uberclaw-helper init <mission-path>)"

If any bin/uberclaw-helper call exits with exit code 3 and a stderr message starting refusing to recurse: UBERCLAW_RUN_ID=, the recursion guard fired. Surface that stderr to the user verbatim and stop. Do not retry and do not unset UBERCLAW_RUN_ID automatically — the user may be in a shell that has a stale value from a crashed parent run, in which case they need to unset UBERCLAW_RUN_ID themselves before starting a fresh one.

Step 1 — load the mission

Resolve the mission file in this order:

1. The argument the user passed (inline text or path).
2. ./goals.md (canonical filename).
3. ./mission.md (alias).

If none exist, ask the user for one and stop.

Validate the YAML frontmatter contains the four required keys (mission_id, priority, budget, human_checkpoints). Report missing keys and stop — do not proceed with a malformed mission.

Step 2 — consume the training profile (if present)

Read these in priority order, falling through gracefully when absent:

1. <project>/.claude/uberclaw/profile.md (per-project, generated by /uberclaw:train).
2. ${HOME}/.claude/uberclaw/profile.md (cross-project).

Parse by header — ## Skills, ## Agents, ## Commands — and bullet shape. Read the entire ## User notes section verbatim and quote it back when it applies. Example: if the user noted "Prefer karpathy-coder for Python work" and a child brief is Python-heavy, route that brief to the karpathy-coder agent and tell the user you did so, citing the note.

Step 3 — initialize the run

export UBERCLAW_RUN_ID="$(bin/uberclaw-helper init <resolved-mission-path>)"

The helper writes ${CLAUDE_PLUGIN_DATA}/runs/${UBERCLAW_RUN_ID}/{mission.md, state.json,children/,decisions.jsonl,lock} and prints the run-id to stdout.

Step 4 — plan briefs and spawn children

Decompose the mission into 3–8 focused subtasks. For each subtask, write a brief Markdown file with optional YAML frontmatter (model:, allowed_tools:, max_turns:), then call:

bin/uberclaw-helper spawn --run "$UBERCLAW_RUN_ID" --brief <brief.md>

Respect the budget.children_max cap; if exceeded the helper exits non-zero with children_max <N> reached; refusing to spawn.

Step 5 — monitor

Use bin/uberclaw-helper status --run "$UBERCLAW_RUN_ID" for the live view. The plugin's monitors/monitors.json streams filtered events (child_started, turn_completed, child_idle, child_failed, budget_warn, budget_breach, state_corrupt) into your session as notifications. A state_corrupt notification means the run's state.json failed to parse — fire stops budget evaluation for that run until the file is repaired; treat it as a hard signal to investigate.

Step 6 — resolve conflicts (no mailbox)

When two children produce conflicting outputs:

1. Read the last result events from state.json["children"][slug].

2. Quote the relevant mission line that justifies your decision.

3. Call (pass --decision so the audit row carries the PRD-documented kind):

   bin/uberclaw-helper decide \
     --run "$UBERCLAW_RUN_ID" \
     --target child-NN \
     --decision "keep_child-NN"      # one of keep|discard|merge|revise|directive|escalation
     --message "<directive>" \
     --mission-quote "<mission line>" \
     --rationale "<why this choice>"
   

The helper appends a row to decisions.jsonl and resumes the target child via claude -p --resume <UUID>. There is no peer-to-peer messaging. Use --decision directive (the default) for routine "go do X" messages that are not a conflict resolution.

Step 7 — four-trigger human escalation

You escalate to the human only on these four triggers (PRD §4.8):

1. usd_hard or tokens_hard breached — bin/uberclaw-helper budget --run "$UBERCLAW_RUN_ID" exits 2 and budget_breach notifications fire.
2. human_checkpoints substring matched — a child's planned action contains text that matches an entry in the mission's human_checkpoints list (e.g. "before any production deploy").
3. Irreversible action outside --permission-mode acceptEdits — force-push, rm -rf, dropping a database, deleting source-controlled history, etc.
4. Genuine ambiguity — the mission text does not resolve a conflict and your confidence is low.

Escalation prompt template

When you escalate, present the user with this exact shape:

Mission says: "<exact line from goals.md>"

Conflicting evidence: <one or two sentences>

Options:
  A. <option A>
  B. <option B>
  C. <option C>

Recommended: <one of A/B/C, with one-sentence rationale>

Pause the affected children with bin/uberclaw-helper stop --run "$UBERCLAW_RUN_ID" --child child-NN --soft while you wait for the human's reply. Persist the escalation as a decision row by calling bin/uberclaw-helper decide with --decision escalation:

bin/uberclaw-helper decide \
  --run "$UBERCLAW_RUN_ID" \
  --target child-NN \
  --decision "escalation" \
  --message "<the question to the human>" \
  --mission-quote "<exact mission line>" \
  --rationale "<one sentence>"

The helper writes a decision: "escalation" row to decisions.jsonl and does not resume the child — escalations are an audit row only; the child stays paused until the human responds. (The decision audit is single-source — every escalation lives in decisions.jsonl, never in a separate file.)

Do not escalate for any other reason. Trust the mission.

Step 8 — finish

Once every child has reached status: completed and you have run a final bin/uberclaw-helper budget --run "$UBERCLAW_RUN_ID" showing no hard breaches, present a short summary to the user:

• Mission id and run-id.
• Number of children spawned, total cost, total tokens, total turns.
• Per-child outcome (one line each).
• Any escalations that fired and how they were resolved.

The run dir is left intact under ${CLAUDE_PLUGIN_DATA}/runs/${UBERCLAW_RUN_ID}/ for post-mortem.