execution

name	execution
description	Runs issue-driven execution supervision with heartbeat orchestration and tmux fan-out. Use when work should progress through durable parallel execution loops.

execution

Use this skill for durable multi-agent orchestration: work that must keep moving over time, not just one-shot execution.

This skill is execution-supervision focused:

• mu heartbeats / mu cron = orchestrator wake cadence
• tmux + mu exec = parallel worker execution
• mu_ui status + prompt docs = operator↔human communication surface

Source of truth remains in mu issues + mu forum.

Contents

• Shared protocol dependency
• Control-flow dependency
• Model-routing dependency
• Model quality defaults for orchestration
• mu_ui communication dependency
• tmux skill dependency
• When to use
• Success condition
• Dispatch modes
• Orchestration loops
• Bootstrap and queue targeting
• Dispatch templates
• Execution UI (subagents profile)
• Evaluation scenarios
• Reconciliation
• Safety

Shared protocol dependency

This skill executes DAG work defined by protocol.

Before execution begins, load that skill and enforce:

• Protocol ID/tag: hierarchical-work.protocol/v1 + proto:hierarchical-work-v1
• Canonical node kinds, context tags, and invariants
• Primitive semantics (read_tree, claim, spawn, fork, ask, expand, complete, serial)

Do not run subagent orchestration against alternate protocol tags.

Control-flow dependency

When a subtree declares explicit loop/termination policy (for example flow:review-gated-v1), load control-flow and apply policy transitions as an overlay on orchestration primitives.

• Keep DAG structure protocol-valid (protocol remains source-of-truth).
• Compile control-flow decisions into protocol primitives (spawn, expand, ask, complete, serial), not ad-hoc mutations.

Model-routing dependency

When a subtree declares per-issue model/provider/thinking policy (for example route:model-routing-v1), load model-routing and apply routing transitions as an overlay on orchestration primitives.

• Keep DAG structure protocol-valid (protocol remains source-of-truth).
• Drive recommendations from live harness capabilities (mu control harness --json).
• Apply route selections with per-turn/per-session overrides (mu exec/mu turn --provider --model --thinking) instead of mutating workspace-global defaults.
• Emit auditable route packets (ROUTE_RECOMMENDATION, ROUTE_FALLBACK, ROUTE_DEGRADED) in forum topics.

Model quality defaults for orchestration

When executing protocol/runtime/schema/cross-adapter DAGs, enforce an explicit high-quality model profile unless the user overrides it.

Default high-quality profile:

• provider: openai-codex
• model: gpt-5.3-codex
• thinking: xhigh

Operational rules:

1. Worker launches must pass explicit --provider --model --thinking.
2. Do not use mini/fast profiles for close/validate/signoff passes.
3. If you must downgrade, post a ROUTE_FALLBACK packet with rationale and expected risk/tradeoff before continuing.
4. Keep profile policy in model-routing (ROUTE_POLICY) so skills can update behavior without extension-code changes.
5. Helper shell workflows must fail fast with actionable usage text whenever required provider/model/thinking args are missing.

mu_ui communication dependency

Before publishing execution visibility or user prompts, use mu_ui as the primary communication surface.

• Use one status doc at ui_id:"ui:subagents" for queue/worker visibility.
• Encode status profile metadata with:
  • metadata.profile.id: "subagents"
  • metadata.profile.variant: "status"
  • metadata.profile.snapshot.compact|multiline for deterministic snapshots.
• Keep status docs non-interactive (actions: []); publish user prompts in a separate interactive ui_id (for example ui:subagents:handoff).
• Use /mu ui status and /mu ui snapshot [compact|multiline] to verify live communication state during orchestration passes.

tmux skill dependency

Before spawning/inspecting worker sessions, load tmux and follow its canonical session lifecycle and bounded send/capture protocol.

• Treat tmux as source-of-truth for session ownership, completion markers, and teardown.
• This execution skill defines orchestration semantics and queue policy.

When to use

• Work is represented as issue-scoped deliverables with explicit outcomes.
• Dependencies may unblock over time.
• You want unattended progress between manual check-ins.

Success condition

• Each executable issue is claimed, worked, and closed with an explicit outcome.
• Results are posted in issue:<id> forum topics.
• Root completion is validated via mu issues validate <root-id>.

Dispatch modes

1) Heartbeat dispatch (orchestrator cadence)

Use when you want orchestration to continue over time.

Each heartbeat tick runs one bounded orchestration pass:

1. Read queue/tree state.
2. Select one protocol primitive/action.
3. Apply one bounded action.
4. Verify state + log progress.
5. Exit.

Heartbeat dispatch is the orchestrator clock. It should supervise/advance the graph, not run unbounded worker sessions.

2) tmux dispatch (parallel workers)

Use when several ready leaves should execute concurrently now.

Spawn one tmux session per ready issue. Each worker claims one issue, executes one full issue loop, then exits.

Orchestration loops

Orchestrator heartbeat tick loop

For root <root-id>:

1. Inspect queue and local protocol state:

mu issues get <root-id> --pretty
mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty
mu forum read issue:<root-id> --limit 20 --pretty

2. Choose exactly one action/primitive from protocol.
3. Apply it.
4. Verify (get, children, ready, validate).
5. Upsert ui_id:"ui:subagents" via mu_ui (required) and keep the status snapshot current.
6. Post a human-facing ORCH_PASS update to forum:
   • start with a short title that captures status in plain language
   • follow with one concise paragraph covering: project objective context, milestone moved this pass, impact, overall progress, and next high-level step
   • include queue/worker/drift internals only when diagnosing blocker/anomaly.
7. Exit tick.

Stop automation when mu issues validate <root-id> returns final.

Worker issue loop (single issue pass)

For claimed issue <issue-id> under <root-id>:

1. Run read_tree.
2. Choose one primitive:
   • route policy present and no valid route decision -> apply one model-routing transition
   • missing input -> ask
   • needs decomposition -> expand
   • directly solvable -> complete
3. Apply primitive.
4. Verify state.
5. Post progress to issue:<issue-id> focused on deliverable status, capability impact, and next step.

Repeat bounded passes until issue closes.

Bootstrap and queue targeting

If root DAG does not yet exist, create it using the protocol bootstrap template first.

During orchestration, always scope queue reads with protocol tag:

mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty

Dispatch templates

A) Heartbeat autopilot (preferred for supervision)

root_id="${1:-}"
provider="${2:-}"
model="${3:-}"
thinking="${4:-}"

if [ -z "$root_id" ] || [ -z "$provider" ] || [ -z "$model" ] || [ -z "$thinking" ]; then
  cat >&2 <<'USAGE'
usage: ./orch-heartbeat.sh <root-id> <provider> <model> <thinking>
example: ./orch-heartbeat.sh mu-root-1234 openai-codex gpt-5.3-codex xhigh
USAGE
  exit 64
fi

mu heartbeats create \
  --title "hierarchical-work-v1 ${root_id}" \
  --reason orchestration_v1 \
  --every-ms 15000 \
  --prompt "Use skills subagents, protocol, execution, control-flow, model-routing, and mu for root ${root_id}. Run exactly one bounded orchestration pass: inspect the proto:hierarchical-work-v1 queue, perform exactly one corrective orchestration action (including in_progress-without-worker drift recovery) or claim/work-start one ready issue, then verify state. Maintain operator↔human communication via mu_ui in this pass: keep ui:subagents updated as a status-profile doc (metadata.profile.id=subagents, metadata.profile.variant=status) and, when user input is required, publish a separate interactive ui_id doc with action metadata.command_text. If flow:* policy tags are present, apply one control-flow transition from the control-flow skill in this pass. If route:* policy tags are present, apply one model-routing transition from the model-routing skill in this pass using live `mu control harness` capabilities and per-turn provider/model/thinking overrides. If route:* policy tags are absent, use the high-quality orchestration profile (openai-codex / gpt-5.3-codex / xhigh) for any execution launch in this pass. Any execution launch in this pass must pass explicit overrides: --provider ${provider} --model ${model} --thinking ${thinking}; if this tuple cannot be used, stop and post BLOCKED with remediation options. Report human-facing progress as a titled status note plus one concise paragraph that explains project context, milestone moved, impact, overall progress, and next high-level step; avoid low-level orchestration internals unless diagnosing a blocker/anomaly. Post a matching ORCH_PASS update to issue:${root_id}. Stop when 'mu issues validate ${root_id}' is final."

Reusable status-voice add-on for heartbeat prompts (copy/paste):

Write each ORCH_PASS as a human status note, not operator telemetry.
Use a short plain-language title + one concise paragraph covering:
project objective, milestone moved this pass, impact/precondition,
overall progress, and next high-level step.
Keep queue/worker/session internals out unless diagnosing a blocker.

B) tmux fan-out (parallel workers)

root_id="${1:-}"
provider="${2:-}"
model="${3:-}"
thinking="${4:-}"
limit="${5:-3}"

if [ -z "$root_id" ] || [ -z "$provider" ] || [ -z "$model" ] || [ -z "$thinking" ]; then
  cat >&2 <<'USAGE'
usage: ./orch-fanout.sh <root-id> <provider> <model> <thinking> [limit]
example: ./orch-fanout.sh mu-root-1234 openai-codex gpt-5.3-codex xhigh 3
USAGE
  exit 64
fi

run_id="$(date +%Y%m%d-%H%M%S)"
for issue_id in $(mu issues ready --root "$root_id" --tag proto:hierarchical-work-v1 --json | jq -r '.[].id' | head -n "$limit"); do
  session="mu-sub-${run_id}-${issue_id}"
  tmux new-session -d -s "$session" \
    "cd '$PWD' && mu exec --provider '$provider' --model '$model' --thinking '$thinking' 'Use skills subagents, protocol, execution, control-flow, model-routing, and mu. Work issue ${issue_id} using hierarchical-work.protocol/v1. Keep ui:subagents current via mu_ui status-profile updates and publish separate interactive ui_id docs for user decisions. If flow:* policy tags are present, apply the control-flow overlay before selecting the next primitive. If route:* policy tags are present, apply the model-routing overlay using live harness capabilities before selecting the next primitive. Claim first, then run one full control loop.' ; rc=\$?; echo __MU_DONE__:\$rc"
done

Execution UI (subagents profile)

Use mu_ui for active execution communication. Truth still lives in issues/forum.

/mu ui status
/mu ui snapshot compact
/mu ui snapshot multiline

Canonical status update (ui:subagents)

{
  "action": "set",
  "doc": {
    "v": 1,
    "ui_id": "ui:subagents",
    "title": "Subagents execution status",
    "summary": "workers=2 · ready=3 · blocked=1",
    "components": [
      {
        "kind": "key_value",
        "id": "queue",
        "title": "Queue",
        "rows": [
          { "key": "ready", "value": "3" },
          { "key": "active", "value": "2" },
          { "key": "blocked", "value": "1" },
          { "key": "next", "value": "Validate final synth issue" }
        ],
        "metadata": {}
      },
      {
        "kind": "list",
        "id": "activity",
        "title": "Recent activity",
        "items": [
          { "id": "a1", "label": "Renderer work completed", "detail": "channel render updates merged" },
          { "id": "a2", "label": "Docs pass in progress", "detail": "execution docs update running" }
        ],
        "metadata": {}
      }
    ],
    "actions": [],
    "revision": { "id": "subagents-status", "version": 12 },
    "updated_at_ms": 1772067300000,
    "metadata": {
      "profile": {
        "id": "subagents",
        "variant": "status",
        "snapshot": {
          "compact": "workers=2 · ready=3 · blocked=1",
          "multiline": "workers: 2\nready: 3\nblocked: 1\nnext: validate synth issue"
        }
      }
    }
  }
}

Canonical user prompt (ui:subagents:handoff)

{
  "action": "set",
  "doc": {
    "v": 1,
    "ui_id": "ui:subagents:handoff",
    "title": "Execution handoff decision",
    "summary": "Need user confirmation before final close.",
    "components": [
      {
        "kind": "text",
        "id": "question",
        "text": "Should execution close the root now or open a follow-up issue?",
        "metadata": {}
      },
      {
        "kind": "list",
        "id": "options",
        "title": "Choices",
        "items": [
          { "id": "opt-close", "label": "Close root now" },
          { "id": "opt-followup", "label": "Create follow-up issue first" }
        ],
        "metadata": {}
      }
    ],
    "actions": [
      {
        "id": "close-root",
        "label": "Close root",
        "kind": "primary",
        "payload": {},
        "metadata": { "command_text": "/answer close-root" }
      },
      {
        "id": "create-followup",
        "label": "Create follow-up",
        "kind": "secondary",
        "payload": { "title": "Document remaining follow-up gaps" },
        "metadata": { "command_text": "/answer followup {{title}}" }
      }
    ],
    "revision": { "id": "subagents-handoff", "version": 1 },
    "updated_at_ms": 1772067310000,
    "metadata": {
      "profile": {
        "id": "subagents-handoff",
        "variant": "interactive"
      }
    }
  }
}

Teardown / handoff semantics

• Remove execution-owned interactive docs when the question is resolved.
• Remove or replace ui:subagents when execution completes or hands off.
• Prefer remove over clear so other skills keep their docs intact.

{"action":"remove","ui_id":"ui:subagents:handoff"}
{"action":"remove","ui_id":"ui:subagents"}

Evaluation scenarios

1. Heartbeat bounded-orchestration tick

   • Setup: root issue with multiple ready leaves tagged proto:hierarchical-work-v1.
   • Expected: one heartbeat tick performs exactly one bounded orchestration action, verifies state, posts a high-level titled narrative status update, and exits.

2. tmux fan-out on ready leaves

   • Setup: at least three independent ready issues under one root.
   • Expected: one worker session per issue is spawned, each worker claims before work, and each writes START/RESULT packets to issue:<id>.

3. Human-question blocking flow (ask)

   • Setup: worker encounters missing critical input.
   • Expected: skill applies protocol ask semantics, creates a human-input node, and downstream work remains blocked until the answer issue closes.

4. Model-routing overlay with fallback

   • Setup: ready issue tagged route:model-routing-v1 and selected model fails at launch.
   • Expected: one bounded pass emits ROUTE_FALLBACK, selects alternate/provider fallback deterministically, and continues execution without violating DAG protocol rules.

Reconciliation

• Run mu issues validate <root-id> before declaring completion.
• Merge synth-node outputs into one final user-facing result.
• Convert unresolved gaps into new child issues tagged proto:hierarchical-work-v1.
• Tear down temporary tmux sessions.
• Tear down/handoff execution-owned ui_ids (at minimum ui:subagents) with explicit mu_ui remove actions.

Safety

• Prefer small, reversible child issues.
• Keep child prompts explicit about deliverables + acceptance criteria.
• Pause spawning while queue semantics are unclear.
• Never overwrite unrelated files across shards.