@femtomc/mu-agent 26.2.107 → 26.2.109

package/prompts/skills/subagents/execution/SKILL.md

@@ -12,7 +12,7 @@ This skill is execution-supervision focused:
 
 - `mu heartbeats` / `mu cron` = orchestrator wake cadence
 - `tmux` + `mu exec` = parallel worker execution
-- subagents HUD = operator observability/control board
+- `mu_ui` status + prompt docs = operator↔human communication surface
 
 Source of truth remains in `mu issues` + `mu forum`.
 
@@ -22,7 +22,7 @@ Source of truth remains in `mu issues` + `mu forum`.
 - [Control-flow dependency](#control-flow-dependency)
 - [Model-routing dependency](#model-routing-dependency)
 - [Model quality defaults for orchestration](#model-quality-defaults-for-orchestration)
-- [HUD skill dependency](#hud-skill-dependency)
+- [mu_ui communication dependency](#mu_ui-communication-dependency)
 - [tmux skill dependency](#tmux-skill-dependency)
 - [When to use](#when-to-use)
 - [Success condition](#success-condition)
@@ -30,7 +30,7 @@ Source of truth remains in `mu issues` + `mu forum`.
 - [Orchestration loops](#orchestration-loops)
 - [Bootstrap and queue targeting](#bootstrap-and-queue-targeting)
 - [Dispatch templates](#dispatch-templates)
-- [Execution HUD (subagents profile)](#execution-hud-subagents-profile)
+- [Execution UI (subagents profile)](#execution-ui-subagents-profile)
 - [Evaluation scenarios](#evaluation-scenarios)
 - [Reconciliation](#reconciliation)
 - [Safety](#safety)
@@ -92,13 +92,20 @@ Operational rules:
 5. Helper shell workflows must fail fast with actionable usage text whenever
    required provider/model/thinking args are missing.
 
-## HUD skill dependency
+## mu_ui communication dependency
 
-Before emitting or mutating subagent HUD state, load **`hud`** and follow its canonical contract.
-HUD usage is not optional for this skill.
+Before publishing execution visibility or user prompts, use **`mu_ui`** as the
+primary communication surface.
 
-- Treat `hud` as source-of-truth for generic `mu_hud` actions, `HudDoc` shape, and rendering constraints.
-- This execution skill defines orchestration-specific conventions only (for example `hud_id: "subagents"`, queue/activity semantics).
+- 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
 
@@ -161,7 +168,8 @@ 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. Update `hud_id:"subagents"` (required) and emit a compact snapshot.
+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
@@ -210,7 +218,7 @@ 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-4be265df openai-codex gpt-5.3-codex xhigh
+example: ./orch-heartbeat.sh mu-root-1234 openai-codex gpt-5.3-codex xhigh
 USAGE
   exit 64
 fi
@@ -219,7 +227,7 @@ 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 hud 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. 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."
+  --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):
@@ -244,7 +252,7 @@ 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-4be265df openai-codex gpt-5.3-codex xhigh 3
+example: ./orch-fanout.sh mu-root-1234 openai-codex gpt-5.3-codex xhigh 3
 USAGE
   exit 64
 fi
@@ -253,33 +261,137 @@ 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 hud. Work issue ${issue_id} using hierarchical-work.protocol/v1. 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"
+    "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 HUD (subagents profile)
+## Execution UI (subagents profile)
 
-HUD usage is required for this skill. Truth still lives in issues/forum.
+Use `mu_ui` for active execution communication. Truth still lives in issues/forum.
 
 ```text
-/mu hud on
-/mu hud status
-/mu hud snapshot
+/mu ui status
+/mu ui snapshot compact
+/mu ui snapshot multiline
 ```
 
-Tool: `mu_hud`
+### Canonical status update (`ui:subagents`)
+
+```json
+{
+  "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`)
+
+```json
+{
+  "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"
+      }
+    }
+  }
+}
+```
 
-- Canonical contract: see skill `hud`
-- Actions: `status`, `snapshot`, `on`, `off`, `toggle`, `set`, `update`, `replace`, `remove`, `clear`
-- Subagents convention: maintain a HUD doc with `hud_id: "subagents"`
-- Suggested subagents doc structure:
-  - chips: health, mode, paused
-  - sections: queue counts + recent activity lines
-  - actions: refresh/spawn command hooks (if desired)
-  - metadata: include `style_preset:"subagents"` for consistent renderer emphasis
-- Example update:
-  - `{"action":"set", "doc": {"hud_id":"subagents", ...}}` (see `hud` skill for exact shape)
-- Follow the HUD ownership and teardown protocol from `hud` skill for completion and handoff.
+### 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.
+
+```json
+{"action":"remove","ui_id":"ui:subagents:handoff"}
+{"action":"remove","ui_id":"ui:subagents"}
+```
 
 ## Evaluation scenarios
 
@@ -305,7 +417,8 @@ Tool: `mu_hud`
 - 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 `hud_id:"subagents"` ownership following the `hud` skill protocol.
+- Tear down/handoff execution-owned `ui_id`s (at minimum `ui:subagents`) with
+  explicit `mu_ui remove` actions.
 
 ## Safety
 

package/prompts/skills/subagents/model-routing/SKILL.md

@@ -23,7 +23,7 @@ semantics.
 - [Planning handoff contract](#planning-handoff-contract)
 - [Subagents/heartbeat execution contract](#subagentsheartbeat-execution-contract)
 - [Failure + fallback policy](#failure--fallback-policy)
-- [HUD visibility and teardown](#hud-visibility-and-teardown)
+- [mu_ui visibility and handoff](#mu_ui-visibility-and-handoff)
 - [Evaluation scenarios](#evaluation-scenarios)
 
 ## Purpose
@@ -44,7 +44,7 @@ Load these skills before applying model-routing policies:
 - `protocol` (protocol primitives/invariants)
 - `execution` (durable execution runtime)
 - `heartbeats` and/or `crons` (scheduler clock)
-- `hud` (required visibility/handoff surface)
+- `mu` (for `/mu ui` inspection commands and communication checks)
 - `control-flow` (optional; when loop/termination overlays are also active)
 
 ## Core contract
@@ -245,7 +245,7 @@ For one-shot execution:
 
 ```bash
 mu exec --provider <provider> --model <model> --thinking <thinking> \
-  "Use skills subagents, protocol, execution, model-routing, and hud. Work issue <issue-id>."
+  "Use skills subagents, protocol, execution, model-routing, and mu. Work issue <issue-id> and keep routing visibility current via mu_ui."
 ```
 
 For existing session turn:
@@ -299,18 +299,19 @@ Per orchestrator tick:
 5. Verify with:
    - `mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty`
    - `mu issues validate <root-id>`
-6. Update HUD state.
+6. Upsert routing visibility via `mu_ui` (`ui_id:"ui:subagents"` when orchestration is shared, or `ui_id:"ui:model-routing"` when standalone).
 7. Post one concise `ORCH_PASS` status update.
 8. If root is final, disable supervising heartbeat.
 
 Reusable heartbeat prompt fragment:
 
 ```text
-Use skills subagents, protocol, execution, model-routing, and hud.
+Use skills subagents, protocol, execution, model-routing, and mu.
 For root <root-id>, enforce route:model-routing-v1.
 Run exactly one bounded routing/orchestration transition pass: compute or validate
 one issue's model recommendation from live `mu control harness` capabilities,
-apply one action, verify DAG state, post one ORCH_PASS, then stop.
+apply one action, keep route status current via mu_ui (`ui:subagents` or
+`ui:model-routing`), verify DAG state, post one ORCH_PASS, then stop.
 If validate is final, disable the supervising heartbeat and report completion.
 ```
 
@@ -334,15 +335,147 @@ If validate is final, disable the supervising heartbeat and report completion.
    - every route change emits forum packet (`ROUTE_RECOMMENDATION`,
      `ROUTE_FALLBACK`, `ROUTE_DEGRADED`)
 
-## HUD visibility and teardown
+## mu_ui visibility and handoff
 
-HUD usage is not optional for active model-routing execution.
+Use `mu_ui` as the primary communication surface for active model-routing
+execution.
 
-- If subagents HUD is active, publish routing state there (selected model,
-  alternates remaining, last fallback reason).
-- If running model-routing standalone, own `hud_id:"model-routing"`.
-- Update HUD each bounded pass before ORCH_PASS output.
-- Follow `hud` skill ownership/teardown protocol on completion or handoff.
+- Publish routing status in one status-profile doc:
+  - shared orchestration: `ui_id:"ui:subagents"`
+  - standalone model-routing loop: `ui_id:"ui:model-routing"`
+- Set status profile metadata for deterministic snapshots:
+  - `metadata.profile.id: "subagents"` or `"model-routing"`
+  - `metadata.profile.variant: "status"`
+  - `metadata.profile.snapshot.compact|multiline`
+- Keep status docs non-interactive (`actions: []`).
+- For user decisions (for example hard-constraint escalation), publish a separate
+  interactive prompt doc (for example `ui_id:"ui:model-routing:escalation"`).
+- Update routing status docs each bounded pass before posting `ORCH_PASS`.
+- On completion or handoff, remove model-routing-owned docs with explicit
+  `mu_ui remove` actions. Prefer `remove` over `clear`.
+
+### Canonical status doc (`ui:model-routing`)
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:model-routing",
+    "title": "Model-routing status",
+    "summary": "issue=<issue-id> · selected=openai-codex/gpt-5.3-codex/xhigh · alternates=2",
+    "components": [
+      {
+        "kind": "key_value",
+        "id": "route",
+        "title": "Current route",
+        "rows": [
+          { "key": "policy", "value": "route:model-routing-v1" },
+          { "key": "issue", "value": "<issue-id>" },
+          { "key": "selected", "value": "openai-codex/gpt-5.3-codex/xhigh" },
+          { "key": "alternates", "value": "2" },
+          { "key": "next", "value": "Launch worker with explicit overrides" }
+        ],
+        "metadata": {}
+      },
+      {
+        "kind": "list",
+        "id": "recent",
+        "title": "Recent routing events",
+        "items": [
+          {
+            "id": "e1",
+            "label": "ROUTE_RECOMMENDATION posted",
+            "detail": "selected openai-codex/gpt-5.3-codex/xhigh"
+          },
+          {
+            "id": "e2",
+            "label": "fallback budget",
+            "detail": "openrouter/google/gemini-3.1-pro-preview/high"
+          }
+        ],
+        "metadata": {}
+      }
+    ],
+    "actions": [],
+    "revision": { "id": "model-routing-status", "version": 7 },
+    "updated_at_ms": 1772069500000,
+    "metadata": {
+      "profile": {
+        "id": "model-routing",
+        "variant": "status",
+        "snapshot": {
+          "compact": "selected=openai-codex/gpt-5.3-codex/xhigh · alternates=2",
+          "multiline": "issue: <issue-id>\nselected: openai-codex/gpt-5.3-codex/xhigh\nalternates: 2\nnext: launch worker"
+        }
+      }
+    }
+  }
+}
+```
+
+### Canonical escalation prompt (`ui:model-routing:escalation`)
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:model-routing:escalation",
+    "title": "Routing escalation required",
+    "summary": "No authenticated model satisfies image + deep reasoning constraints.",
+    "components": [
+      {
+        "kind": "text",
+        "id": "question",
+        "text": "Routing is blocked by missing provider capability. Should execution wait for provider auth or run with degraded constraints?",
+        "metadata": {}
+      },
+      {
+        "kind": "list",
+        "id": "options",
+        "title": "Choices",
+        "items": [
+          { "id": "opt-auth", "label": "Pause and authenticate provider" },
+          { "id": "opt-degrade", "label": "Proceed with degraded route" }
+        ],
+        "metadata": {}
+      }
+    ],
+    "actions": [
+      {
+        "id": "wait-for-auth",
+        "label": "Wait for provider auth",
+        "kind": "primary",
+        "payload": {},
+        "metadata": { "command_text": "/answer wait-for-auth" }
+      },
+      {
+        "id": "approve-degraded-route",
+        "label": "Approve degraded route",
+        "kind": "secondary",
+        "payload": {},
+        "metadata": { "command_text": "/answer approve-degraded-route" }
+      }
+    ],
+    "revision": { "id": "model-routing-escalation", "version": 1 },
+    "updated_at_ms": 1772069510000,
+    "metadata": {
+      "profile": {
+        "id": "model-routing-escalation",
+        "variant": "interactive"
+      }
+    }
+  }
+}
+```
+
+### Teardown / handoff
+
+```json
+{"action":"remove","ui_id":"ui:model-routing:escalation"}
+{"action":"remove","ui_id":"ui:model-routing"}
+```
 
 ## Evaluation scenarios