@femtomc/mu-agent 26.2.107 → 26.2.108

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
 

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

@@ -1,47 +1,66 @@
 ---
 name: planning
-description: "Builds and refines issue-DAG plans using the planning HUD and approval loops. Use when the user asks for planning, decomposition, sequencing, or plan review."
+description: "Builds and refines issue-DAG plans using mu_ui status/prompt docs and approval loops. Use when the user asks for planning, decomposition, sequencing, or plan review."
 ---
 
 # planning
 
-Use this skill when the user asks for planning, decomposition, or a staged execution roadmap.
+Use this skill when the user asks for planning, decomposition, or a staged
+execution roadmap.
 
 ## Contents
 
-- [Planning HUD is required](#planning-hud-is-required)
-- [HUD skill dependency](#hud-skill-dependency)
+- [Planning communication contract (mu_ui-first)](#planning-communication-contract-mu_ui-first)
+- [mu_ui communication dependency](#mu_ui-communication-dependency)
 - [Shared protocol dependency](#shared-protocol-dependency)
 - [Core contract](#core-contract)
 - [Suggested workflow](#suggested-workflow)
-- [Effective HUD usage heuristics](#effective-hud-usage-heuristics)
+- [Planning UI canonical docs](#planning-ui-canonical-docs)
+- [Effective mu_ui usage heuristics](#effective-mu_ui-usage-heuristics)
 - [Evaluation scenarios](#evaluation-scenarios)
 - [Quality bar](#quality-bar)
 
-## Planning HUD is required
+## Planning communication contract (mu_ui-first)
 
-For this skill, the planning HUD is the primary status/communication surface.
-HUD usage is not optional for planning turns.
+For this skill, `mu_ui` is the primary operator↔human communication surface.
 
-- Keep HUD state in sync with real planning progress.
-- Update HUD before and after each major planning turn.
-- Use `waiting_on_user`, `next_action`, and `blocker` to communicate exactly what the user needs to do.
-- Include a HUD snapshot in user-facing planning updates.
-- Teardown/handoff HUD state explicitly when planning ends or transitions to another HUD-owning skill.
+- Keep one status doc at `ui_id:"ui:planning"` during active planning turns.
+- Keep status docs non-interactive (`actions: []`).
+- Publish user-decision prompts in a separate interactive doc (for example
+  `ui_id:"ui:planning:approval"`) with `action.metadata.command_text`.
+- Update planning UI docs before and after each major planning turn.
+- Keep status-profile metadata current:
+  - `metadata.profile.id: "planning"`
+  - `metadata.profile.variant: "status"`
+  - `metadata.profile.snapshot.compact|multiline`
+- Teardown or hand off planning-owned docs explicitly when planning completes.
 
-Default per-turn HUD loop:
+Default per-turn planning UI loop:
 
-1. Emit a fresh `planning` HUD doc (`mu_hud` action `set` or `update`) with current `phase`, `waiting_on_user`, `next_action`, `blocker`, and `confidence` in sections/metadata.
-2. Keep checklist progress and root issue linkage synchronized with the live issue DAG.
-3. Emit `snapshot` (`compact` or `multiline`) and reflect it in your response.
+1. Upsert `ui:planning` with current `phase`, `waiting_on_user`,
+   `next_action`, `blocker`, and `confidence`.
+2. Keep checklist progress and root-issue linkage synchronized with the live DAG.
+3. If user input is needed, upsert `ui:planning:approval` with concrete choices.
+4. Use `mu_ui` snapshot/status output in user-facing planning updates.
 
+## mu_ui communication dependency
 
-## HUD skill dependency
+Before publishing planning visibility or user prompts, use **`mu_ui`** and the
+`/mu ui` command surface.
 
-Before emitting or mutating planning HUD state, load **`hud`** and follow its canonical contract.
+- Tool: `mu_ui`
+- Actions: `status`, `snapshot`, `set`, `update`, `replace`, `remove`, `clear`
+- Operator commands:
+  - `/mu ui status`
+  - `/mu ui snapshot compact`
+  - `/mu ui snapshot multiline`
+  - `/mu ui interact [ui_id [action_id]]`
 
-- Treat `hud` as source-of-truth for generic `mu_hud` actions, `HudDoc` shape, and rendering constraints.
-- This planning skill defines planning-specific conventions only (for example `hud_id: "planning"`, planning phases, checklist semantics).
+If behavior is unclear, inspect implementation/tests before guessing:
+
+- `packages/agent/src/extensions/ui.ts`
+- `packages/agent/test/ui_extension.test.ts`
+- `docs/mu-ui.md`
 
 ## Shared protocol dependency
 
@@ -50,16 +69,17 @@ shared protocol in **`protocol`**.
 
 Before creating or reshaping DAG nodes, load that skill and use its canonical:
 
-- protocol identity/tag (`hierarchical-work.protocol/v1`, `proto:hierarchical-work-v1`)
+- protocol identity/tag (`hierarchical-work.protocol/v1`,
+  `proto:hierarchical-work-v1`)
 - node kinds and context tags
 - invariants for executable vs non-executable nodes
 - planning handoff contract
 
 Do not invent alternate protocol names or tag schemas.
 
-If the user asks for explicit loop/termination behavior (for example review-gated
-retry rounds), load **`control-flow`** and encode policy via `flow:*` overlays
-without changing protocol semantics.
+If the user asks for explicit loop/termination behavior (for example
+review-gated retry rounds), load **`control-flow`** and encode policy via
+`flow:*` overlays without changing protocol semantics.
 
 If the user asks for per-issue model/provider/thinking recommendations based on
 live harness capabilities, load **`model-routing`** and encode policy via
@@ -73,21 +93,26 @@ changing protocol semantics.
    - Avoid speculative plans when evidence is cheap to gather.
 
 2. **Materialize the plan in mu issues using the shared protocol**
-   - Create root and child issues that comply with `hierarchical-work.protocol/v1`.
+   - Create root and child issues that comply with
+     `hierarchical-work.protocol/v1`.
    - Encode dependencies so the DAG reflects execution order and synth fan-in.
    - Add clear titles, scope, acceptance criteria, and protocol tags.
-   - When model specialization is required, attach explicit `route:*` intent tags/constraints to executable nodes.
-
-3. **Drive communication through the planning HUD**
-   - Load `hud` and use its canonical `mu_hud`/`HudDoc` contract.
-   - Treat HUD state as the canonical short status line for planning.
-   - Keep `phase`, `waiting_on_user`, `next_action`, `blocker`, and `confidence` current.
-   - Ensure HUD state and your natural-language response never contradict each other.
+   - When model specialization is required, attach explicit `route:*`
+     intent tags/constraints to executable nodes.
+
+3. **Drive communication through mu_ui**
+   - Keep `ui:planning` current as the canonical short planning status.
+   - Keep `phase`, `waiting_on_user`, `next_action`, `blocker`, and
+     `confidence` current in doc metadata/components.
+   - Keep status docs non-interactive; isolate user decisions in separate
+     interactive docs.
+   - Ensure UI doc state and natural-language responses never contradict each
+     other.
 
 4. **Present the plan to the user**
    - Summarize goals, sequencing, risks, and tradeoffs.
    - Include issue IDs so the user can reference exact nodes.
-   - Include a HUD snapshot line.
+   - Include one compact planning UI snapshot line.
 
 5. **Iterate until user approval**
    - Treat user feedback as first-class constraints.
@@ -95,11 +120,13 @@ changing protocol semantics.
    - Do not begin broad execution until the user signals satisfaction.
 
 6. **After user approval, ask user about next steps**
-   - On user acceptance of the plan, teardown planning HUD ownership.
-   - If handing off to another HUD-owning skill (for example `execution`), remove
-     `hud_id:"planning"` and keep HUD on for the next skill.
-   - If no next HUD-owning skill starts immediately, remove planning doc and turn HUD off.
-   - Read the `execution` skill and offer to supervise execution to realize the plan.
+   - Remove resolved interactive planning docs (for example
+     `ui:planning:approval`).
+   - If handing off to `execution`, remove or replace `ui:planning` so
+     ownership is unambiguous.
+   - If no immediate follow-on skill starts, remove planning docs explicitly.
+   - Read the `execution` skill and offer to supervise execution to realize the
+     plan.
 
 ## Suggested workflow
 
@@ -112,42 +139,19 @@ mu forum read user:context --limit 50 --pretty
 mu memory search --query "<topic>" --limit 30
 ```
 
-Bootstrap HUD immediately (interactive operator session):
+Inspect active planning UI state:
 
 ```text
-/mu hud on
-/mu hud status
-/mu hud snapshot
+/mu ui status
+/mu ui snapshot compact
 ```
 
-Tool contract (preferred when tools are available):
-
-- Canonical contract: see skill `hud`
-- Tool: `mu_hud`
-- Actions: `status`, `snapshot`, `on`, `off`, `toggle`, `set`, `update`, `replace`, `remove`, `clear`
-- Planning convention: maintain a HUD doc with `hud_id: "planning"`
-- Suggested planning doc structure:
-  - `title`: `Planning HUD`
-  - chips: `phase:<...>`, `steps:<done>/<total>`, `waiting:<yes|no>`, `conf:<low|medium|high>`
-  - sections:
-    - `kv` status block (`phase`, `root`, `waiting_on_user`, `confidence`, `next_action`, `blocker`)
-    - `checklist` block for plan milestones
-  - actions: include useful follow-ups (for example, `snapshot`)
-  - metadata: include `style_preset:"planning"` for consistent renderer emphasis without repeating style hints
-
-Example tool calls:
-- Turn HUD on:
-  - `{"action":"on"}`
-- Set/replace planning doc after investigation pass:
-  - `{"action":"set","doc":{"v":1,"hud_id":"planning","title":"Planning HUD","scope":"mu-root-123","chips":[{"key":"phase","label":"phase:investigating","tone":"dim"},{"key":"steps","label":"steps:1/4","tone":"accent"},{"key":"waiting","label":"waiting:no","tone":"dim"},{"key":"confidence","label":"conf:medium","tone":"accent"}],"sections":[{"kind":"kv","title":"Status","items":[{"key":"phase","label":"phase","value":"investigating"},{"key":"root","label":"root","value":"mu-root-123"},{"key":"waiting","label":"waiting_on_user","value":"no"},{"key":"confidence","label":"confidence","value":"medium"},{"key":"next","label":"next_action","value":"Draft root DAG"},{"key":"blocker","label":"blocker","value":"(none)"}]},{"kind":"checklist","title":"Checklist","items":[{"id":"1","label":"Investigate relevant code/docs/state","done":true},{"id":"2","label":"Create root + child issue DAG","done":false},{"id":"3","label":"Present plan + tradeoffs","done":false},{"id":"4","label":"Refine until approved","done":false}]}],"actions":[{"id":"snapshot","label":"Snapshot","command_text":"/mu hud snapshot","kind":"secondary"}],"snapshot_compact":"HUD(plan) · phase=investigating · steps=1/4 · waiting=no · conf=medium","updated_at_ms":1771853115000,"metadata":{"style_preset":"planning","phase":"investigating","waiting_on_user":false,"confidence":"medium"}}}`
-- Human-facing status line:
-  - `{"action":"snapshot","snapshot_format":"compact"}`
-
-If HUD behavior is unclear, inspect implementation/tests before guessing:
-- `packages/agent/src/extensions/hud.ts`
-- `packages/agent/test/hud_tool.test.ts`
-
-Also inspect repo files directly (read/bash) for implementation constraints.
+Tool checks (when tools are available):
+
+```json
+{"action":"status"}
+{"action":"snapshot","snapshot_format":"compact"}
+```
 
 ### B) Draft DAG in mu-issue
 
@@ -194,7 +198,7 @@ mu issues validate "$root_id"
 - Proposed issue DAG (IDs + titles + ordering)
 - Risks and mitigations
 - Open questions for user approval
-- HUD snapshot (compact line)
+- Planning UI snapshot (compact line)
 
 ### D) Revision loop
 
@@ -202,43 +206,188 @@ mu issues validate "$root_id"
 - Re-run `mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty`.
 - Validate protocol-root status via `mu issues validate <root-id>`.
 - Present a concise diff of what changed and why.
-- Update HUD each turn so phase/waiting/next/blocker/confidence match the latest state.
+- Keep planning UI docs aligned with latest state each turn.
+
+Required UI updates during the loop:
+
+- Re-emit `ui:planning` with current `phase`, checklist progress,
+  `waiting_on_user`, `next_action`, and `blocker` after each meaningful
+  planning step.
+- Use `{"action":"snapshot","snapshot_format":"compact"}` for concise
+  user-facing snapshot lines.
+- Keep `revision.version` and `updated_at_ms` monotonic across updates.
+- On plan completion/handoff, remove planning-owned docs explicitly with
+  `mu_ui remove`.
+
+## Planning UI canonical docs
+
+Use these as copy/paste templates for planning communication.
+
+### Canonical status doc (`ui:planning`)
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:planning",
+    "title": "Planning status",
+    "summary": "phase=investigating · steps=1/4 · waiting=no · conf=medium",
+    "components": [
+      {
+        "kind": "key_value",
+        "id": "status",
+        "title": "Status",
+        "rows": [
+          { "key": "phase", "value": "investigating" },
+          { "key": "root", "value": "mu-root-123" },
+          { "key": "waiting", "value": "no" },
+          { "key": "confidence", "value": "medium" },
+          { "key": "next", "value": "Draft root DAG" },
+          { "key": "blocker", "value": "(none)" }
+        ],
+        "metadata": {}
+      },
+      {
+        "kind": "list",
+        "id": "checklist",
+        "title": "Checklist",
+        "items": [
+          { "id": "c1", "label": "Investigate relevant code/docs/state", "detail": "done" },
+          { "id": "c2", "label": "Create root + child issue DAG", "detail": "pending" },
+          { "id": "c3", "label": "Present plan + tradeoffs", "detail": "pending" },
+          { "id": "c4", "label": "Refine until approved", "detail": "pending" }
+        ],
+        "metadata": {}
+      }
+    ],
+    "actions": [],
+    "revision": { "id": "planning-status", "version": 3 },
+    "updated_at_ms": 1772069100000,
+    "metadata": {
+      "phase": "investigating",
+      "waiting_on_user": false,
+      "confidence": "medium",
+      "profile": {
+        "id": "planning",
+        "variant": "status",
+        "snapshot": {
+          "compact": "phase=investigating · steps=1/4 · waiting=no · conf=medium",
+          "multiline": "phase: investigating\nsteps: 1/4\nwaiting_on_user: no\nconfidence: medium\nnext_action: Draft root DAG"
+        }
+      }
+    }
+  }
+}
+```
 
-Required HUD updates during the loop:
+### Canonical approval prompt (`ui:planning:approval`)
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:planning:approval",
+    "title": "Plan approval",
+    "summary": "Need user decision before execution handoff.",
+    "components": [
+      {
+        "kind": "text",
+        "id": "question",
+        "text": "Approve this plan for execution, or request one targeted revision?",
+        "metadata": {}
+      },
+      {
+        "kind": "list",
+        "id": "options",
+        "title": "Choices",
+        "items": [
+          { "id": "opt-approve", "label": "Approve and move to execution" },
+          { "id": "opt-revise", "label": "Request one revision" }
+        ],
+        "metadata": {}
+      }
+    ],
+    "actions": [
+      {
+        "id": "approve-plan",
+        "label": "Approve plan",
+        "kind": "primary",
+        "payload": {},
+        "metadata": { "command_text": "/answer approve-plan" }
+      },
+      {
+        "id": "request-revision",
+        "label": "Request revision",
+        "kind": "secondary",
+        "payload": { "reason": "<reason>" },
+        "metadata": { "command_text": "/answer request-revision {{reason}}" }
+      }
+    ],
+    "revision": { "id": "planning-approval", "version": 1 },
+    "updated_at_ms": 1772069110000,
+    "metadata": {
+      "profile": {
+        "id": "planning-approval",
+        "variant": "interactive"
+      }
+    }
+  }
+}
+```
+
+### Teardown / handoff semantics
 
-- Re-emit the `planning` HUD doc with current `phase`, checklist progress, `waiting_on_user`, `next_action`, and `blocker` after each meaningful planning step.
-- Use `{"action":"snapshot","snapshot_format":"compact"}` for concise user-facing HUD lines.
-- Keep `updated_at_ms` monotonic across updates so latest doc wins deterministically.
-- On plan completion/handoff, remove `hud_id:"planning"` and apply handoff/off semantics from the `hud` skill.
+- Remove resolved decision prompts immediately.
+- Remove or replace `ui:planning` when planning ends or execution takes over.
+- Prefer `remove` over `clear` to avoid deleting docs owned by other skills.
+
+```json
+{"action":"remove","ui_id":"ui:planning:approval"}
+{"action":"remove","ui_id":"ui:planning"}
+```
 
-## Effective HUD usage heuristics
+## Effective mu_ui usage heuristics
 
-- Keep one canonical planning doc (`hud_id: "planning"`) and refresh it whenever planning state changes.
-- Keep `updated_at_ms` monotonic so deterministic dedupe/ordering always keeps the latest planning state.
-- Use explicit, concise status fields (`phase`, `waiting_on_user`, `next_action`, `blocker`, `confidence`) in sections/metadata.
-- Keep `next_action` as one concrete action, not a paragraph.
-- Customize checklist steps once scope is understood; mark them complete as milestones land.
+- Keep one canonical status doc (`ui:planning`) and refresh it whenever planning
+  state changes.
+- Keep `revision.version` and `updated_at_ms` monotonic so replay/reconnect
+  keeps the newest state deterministically.
+- Keep status docs non-interactive; place user decisions in separate interactive
+  docs.
+- Keep `next_action` to one concrete action, not a paragraph.
+- Keep approval prompts decision-shaped with explicit command-text actions.
 
 ## Evaluation scenarios
 
 1. **Initial decomposition request**
    - Prompt: user asks for a staged roadmap.
-   - Expected: investigation pass runs first, root + child issues are created with `proto:hierarchical-work-v1`, HUD shows `phase=drafting` and `waiting_on_user=false` until first review checkpoint.
+   - Expected: investigation pass runs first, root + child issues are created
+     with `proto:hierarchical-work-v1`, and `ui:planning` reflects
+     `phase=drafting`, `waiting_on_user=false`.
 
 2. **Feedback-driven replan**
    - Prompt: user requests scope change after first DAG draft.
-   - Expected: dependency/issue updates are applied, concise change diff is presented, HUD transitions through `reviewing`/`waiting_user` with updated `next_action`.
+   - Expected: dependency/issue updates are applied, concise change diff is
+     presented, and planning UI transitions through `reviewing` and
+     `waiting_on_user` states.
 
 3. **Blocked-by-missing-input planning turn**
    - Prompt: required architecture constraint is unknown.
-   - Expected: plan captures explicit assumption gap, HUD uses `phase=blocked` or `waiting_user` (as appropriate), and asks one concrete unblock question.
+   - Expected: plan captures explicit assumption gap, `ui:planning` shows
+     blocked/waiting status, and an interactive planning prompt asks one concrete
+     unblock decision.
 
 ## Quality bar
 
 - Every issue should be actionable and testable.
-- DAG nodes must satisfy `hierarchical-work.protocol/v1` before execution handoff.
+- DAG nodes must satisfy `hierarchical-work.protocol/v1` before execution
+  handoff.
 - Keep tasks small enough to complete in one focused pass.
 - Explicitly call out uncertain assumptions for user confirmation.
 - Prefer reversible plans and incremental checkpoints.
-- If `model-routing` is in scope, route intent/constraints are explicit and non-conflicting.
-- HUD state must be fresh, accurate, and aligned with user-visible status updates.
+- If `model-routing` is in scope, route intent/constraints are explicit and
+  non-conflicting.
+- Planning UI state must be fresh, accurate, and aligned with user-visible
+  status updates.

package/prompts/skills/writing/SKILL.md

@@ -36,7 +36,7 @@ Use this skill when asked to write, edit, or review technical prose. This includ
    - Inverted pyramid: conclusion, supporting details, background.
 
 4. **Actionability**
-   - Imperative for procedures: "Run the migration" not "The migration should be run."
+   - Imperative for procedures: "Run the command" not "The command should be run."
    - Explicit consequences: state what happens if the user does X.
    - Anticipate failure modes in troubleshooting sections.
 
@@ -77,7 +77,7 @@ Use this skill when asked to write, edit, or review technical prose. This includ
 1. **What changed** (imperative, present tense)
 2. **Why it changed** (context, motivation)
 3. **How to verify** (testing steps, expected outcomes)
-4. **Breaking changes** (if any, with migration path)
+4. **Breaking changes** (if any, with explicit adoption guidance)
 
 Keep under 80 characters per line in the summary. Body wraps at 72 characters.