@femtomc/mu-agent 26.2.106 → 26.2.108

package/prompts/skills/subagents/SKILL.md

@@ -1,268 +1,118 @@
 ---
 name: subagents
-description: "Orchestrates issue-driven subagent execution with heartbeat supervision and tmux fan-out. Use when work should progress through durable parallel subagent loops."
+description: "Meta-skill for protocol-driven planning and execution. Routes to planning, protocol, execution, control-flow, and model-routing with mu_ui-first communication."
 ---
 
-# Subagents
+# subagents
 
-## Contents
+Use this meta-skill when work should run through the full multi-agent DAG stack.
 
-- [Purpose (what this skill is for)](#purpose-what-this-skill-is-for)
-- [Shared protocol dependency](#shared-protocol-dependency)
-- [Control-flow dependency](#control-flow-dependency)
-- [Model-routing dependency](#model-routing-dependency)
-- [HUD skill dependency](#hud-skill-dependency)
-- [tmux skill dependency](#tmux-skill-dependency)
-- [When to use](#when-to-use)
-- [Success condition](#success-condition)
-- [Dispatch modes](#dispatch-modes)
-- [Orchestration loops](#orchestration-loops)
-- [Bootstrap and queue targeting](#bootstrap-and-queue-targeting)
-- [Dispatch templates](#dispatch-templates)
-- [Subagents HUD](#subagents-hud)
-- [Evaluation scenarios](#evaluation-scenarios)
-- [Reconciliation](#reconciliation)
-- [Safety](#safety)
+## Subskills
 
-## Purpose (what this skill is for)
+- `planning` — build/refine issue DAGs and approval loops.
+- `protocol` — canonical DAG protocol contract and primitives.
+- `execution` — durable orchestration/supervision loop over the DAG.
+- `control-flow` — loop/termination overlays (`flow:*`) on top of protocol primitives.
+- `model-routing` — provider/model/thinking overlays (`route:*`) from live harness capabilities.
 
-Use this skill for **durable multi-agent orchestration**: work that must keep moving
-over time, not just one-shot execution.
+## Naming conventions
 
-This skill is execution-supervision focused:
+- Use `protocol` (not `orchestration`).
+- Use `execution` for execution/supervision workflows.
 
-- `mu heartbeats` / `mu cron` = orchestrator wake cadence
-- `tmux` + `mu exec` = parallel worker execution
-- subagents HUD = operator observability/control board
+## Recommended bundles
 
-Source of truth remains in `mu issues` + `mu forum`.
+- Planning bundle: `planning` + `protocol`
+- Execution bundle: `execution` + `protocol`
+- Policy overlays: add `control-flow` and/or `model-routing` as needed
 
-## Shared protocol dependency
+## Canonical mu_ui communication pattern
 
-This skill executes DAG work defined by **`orchestration`**.
-
-Before orchestration 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 (`orchestration` 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 (`orchestration` 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.
-
-## HUD skill dependency
-
-Before emitting or mutating subagent HUD state, load **`hud`** and follow its canonical contract.
-HUD usage is not optional for this skill.
-
-- Treat `hud` as source-of-truth for generic `mu_hud` actions, `HudDoc` shape, and rendering constraints.
-- This subagents skill defines orchestration-specific conventions only (for example `hud_id: "subagents"`, queue/activity semantics).
-
-## 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 subagents 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:
+Use `mu_ui` as the shared operator↔human surface during planning/execution passes.
 
 ```bash
-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
+/mu ui status
+/mu ui snapshot compact
+/mu ui snapshot multiline
 ```
 
-2. Choose exactly one action/primitive from `orchestration`.
-3. Apply it.
-4. Verify (`get`, `children`, `ready`, `validate`).
-5. Update `hud_id:"subagents"` (required) and emit a compact snapshot.
-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
-`orchestration` bootstrap template first.
-
-During orchestration, always scope queue reads with protocol tag:
-
-```bash
-mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty
+Status doc example (`ui:subagents`):
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:subagents",
+    "title": "Subagents execution status",
+    "summary": "ready=2 · active=1 · blocked=0",
+    "components": [
+      {
+        "kind": "key_value",
+        "id": "queue",
+        "title": "Queue",
+        "rows": [
+          { "key": "ready", "value": "2" },
+          { "key": "active", "value": "1" },
+          { "key": "blocked", "value": "0" }
+        ],
+        "metadata": {}
+      }
+    ],
+    "actions": [],
+    "revision": { "id": "subagents-status", "version": 3 },
+    "updated_at_ms": 1772060000000,
+    "metadata": {
+      "profile": {
+        "id": "subagents",
+        "variant": "status",
+        "snapshot": {
+          "compact": "ready=2 · active=1 · blocked=0",
+          "multiline": "ready: 2\nactive: 1\nblocked: 0"
+        }
+      }
+    }
+  }
+}
 ```
 
-## Dispatch templates
-
-### A) Heartbeat autopilot (preferred for supervision)
-
-```bash
-mu heartbeats create \
-  --title "hierarchical-work-v1 <root-id>" \
-  --reason orchestration_v1 \
-  --every-ms 15000 \
-  --prompt "Use skills subagents, orchestration, 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. 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."
+Interactive prompt example (`ui:subagents:handoff`):
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:subagents:handoff",
+    "title": "Execution handoff decision",
+    "components": [
+      { "kind": "text", "id": "question", "text": "Close root now?", "metadata": {} }
+    ],
+    "actions": [
+      {
+        "id": "close-root",
+        "label": "Close root",
+        "kind": "primary",
+        "payload": {},
+        "metadata": { "command_text": "/answer close-root" }
+      }
+    ],
+    "revision": { "id": "subagents-handoff", "version": 1 },
+    "updated_at_ms": 1772060005000,
+    "metadata": { "profile": { "id": "subagents-handoff", "variant": "interactive" } }
+  }
+}
 ```
 
-Reusable status-voice add-on for heartbeat prompts (copy/paste):
+Teardown/handoff uses explicit removes:
 
-```text
-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.
+```json
+{"action":"remove","ui_id":"ui:subagents:handoff"}
+{"action":"remove","ui_id":"ui:subagents"}
 ```
 
-### B) tmux fan-out (parallel workers)
-
-```bash
-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 3); do
-  session="mu-sub-${run_id}-${issue_id}"
-  tmux new-session -d -s "$session" \
-    "cd '$PWD' && mu exec 'Use skills subagents, orchestration, 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"
-done
-```
-
-## Subagents HUD
-
-HUD usage is required for this skill. Truth still lives in issues/forum.
-
-```text
-/mu hud on
-/mu hud status
-/mu hud snapshot
-```
-
-Tool: `mu_hud`
-
-- 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.
-
-## 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 `hud_id:"subagents"` ownership following the `hud` skill protocol.
-
-## Safety
+## Common patterns
 
-- 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.
+- **End-to-End Orchestration**: Route to `planning` to get a structured issue DAG, publish plan state in `ui:planning` (status) plus `ui:planning:approval` (interactive prompt) when needed, then route to `execution` to drive workers until DAG completion.
+- **DAG Recovery / Unblocking**: If a DAG stalls, route to `protocol` to inspect `mu issues ready` constraints, followed by a bounded `execution` pass to claim and manually unblock the stalled task.
+- **Differentiated Model Provisioning**: If different nodes need different abilities (for example specialized docs vs. complex refactoring), add `model-routing` to set `route:model-routing-v1` policies per issue. The `execution` worker shell will then launch the required model profiles based on those policies.

package/prompts/skills/{control-flow → subagents/control-flow}/SKILL.md

@@ -6,7 +6,7 @@ description: "Defines compositional control-flow policies for orchestration DAGs
 # control-flow
 
 Use this skill when work needs explicit loop/termination policy on top of the
-shared orchestration protocol.
+shared protocol.
 
 ## Contents
 
@@ -17,12 +17,12 @@ shared orchestration protocol.
 - [Transition table](#transition-table)
 - [Planning handoff contract](#planning-handoff-contract)
 - [Subagents/heartbeat execution contract](#subagentsheartbeat-execution-contract)
-- [HUD visibility and teardown](#hud-visibility-and-teardown)
+- [mu_ui visibility and handoff](#mu_ui-visibility-and-handoff)
 - [Evaluation scenarios](#evaluation-scenarios)
 
 ## Purpose
 
-Control-flow policies are overlays. They do not replace orchestration protocol
+Control-flow policies are overlays. They do not replace protocol
 semantics; they guide which protocol primitive to apply next.
 
 Examples:
@@ -34,10 +34,10 @@ Examples:
 
 Load these skills before applying control-flow policies:
 
-- `orchestration` (protocol primitives/invariants)
-- `subagents` (durable execution runtime)
+- `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)
 
 ## Core contract
 
@@ -128,29 +128,134 @@ Per orchestrator tick:
 4. Verify with:
    - `mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty`
    - `mu issues validate <root-id>`
-5. Post one concise ORCH_PASS update.
-6. If final: disable heartbeat program.
+5. Upsert control-flow visibility via `mu_ui` (`ui_id:"ui:subagents"` when orchestration is shared, or `ui_id:"ui:control-flow"` when standalone).
+6. Post one concise ORCH_PASS update.
+7. If final: disable heartbeat program.
 
 Reusable bounded heartbeat prompt fragment:
 
 ```text
-Use skills orchestration, control-flow, subagents, and hud.
+Use skills subagents, protocol, execution, control-flow, and mu.
 For root <root-id>, enforce flow:review-gated-v1 with spawn-per-attempt rounds.
-Run exactly one bounded control-flow transition pass, verify DAG state,
+Run exactly one bounded control-flow transition pass, keep control-flow visibility
+current via mu_ui (`ui:subagents` or `ui:control-flow`), verify DAG state,
 post one ORCH_PASS, and stop. If validate is final, disable the supervising
 heartbeat and report completion.
 ```
 
-## HUD visibility and teardown
+## mu_ui visibility and handoff
+
+Use `mu_ui` as the primary communication surface for active control-flow
+execution.
+
+- Publish control-flow status in one status-profile doc:
+  - shared orchestration: `ui_id:"ui:subagents"`
+  - standalone control-flow loop: `ui_id:"ui:control-flow"`
+- Set profile metadata for deterministic snapshots:
+  - `metadata.profile.id: "subagents"` or `"control-flow"`
+  - `metadata.profile.variant: "status"`
+  - `metadata.profile.snapshot.compact|multiline`
+- Keep status docs non-interactive (`actions: []`).
+- For user decisions (for example max-round escalation), publish a separate
+  interactive prompt doc (for example `ui_id:"ui:control-flow:escalation"`).
+- Update status docs each bounded pass before posting `ORCH_PASS`.
+- On completion or handoff, remove control-flow-owned docs with explicit
+  `mu_ui remove` actions. Prefer `remove` over `clear`.
+
+### Canonical status doc (`ui:control-flow`)
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:control-flow",
+    "title": "Control-flow status",
+    "summary": "policy=review-gated · round=2/3 · state=review_pending",
+    "components": [
+      {
+        "kind": "key_value",
+        "id": "policy",
+        "title": "Review gate",
+        "rows": [
+          { "key": "policy", "value": "flow:review-gated-v1" },
+          { "key": "round", "value": "2/3" },
+          { "key": "attempt", "value": "mu-attempt-2" },
+          { "key": "review", "value": "mu-review-2" },
+          { "key": "next", "value": "Run review_2" }
+        ],
+        "metadata": {}
+      }
+    ],
+    "actions": [],
+    "revision": { "id": "control-flow-status", "version": 5 },
+    "updated_at_ms": 1772067720000,
+    "metadata": {
+      "profile": {
+        "id": "control-flow",
+        "variant": "status",
+        "snapshot": {
+          "compact": "round=2/3 · state=review_pending",
+          "multiline": "policy: review-gated\nround: 2/3\nstate: review_pending\nnext: run review_2"
+        }
+      }
+    }
+  }
+}
+```
 
-HUD usage is not optional for active control-flow execution.
+### Canonical escalation prompt (`ui:control-flow:escalation`)
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:control-flow:escalation",
+    "title": "Review rounds exhausted",
+    "summary": "Need user decision after max failed review rounds.",
+    "components": [
+      {
+        "kind": "text",
+        "id": "question",
+        "text": "Max review rounds were reached. Should execution open another attempt or stop for manual intervention?",
+        "metadata": {}
+      }
+    ],
+    "actions": [
+      {
+        "id": "open-extra-round",
+        "label": "Open one extra round",
+        "kind": "primary",
+        "payload": {},
+        "metadata": { "command_text": "/answer open-extra-round" }
+      },
+      {
+        "id": "stop-and-handoff",
+        "label": "Stop and hand off",
+        "kind": "secondary",
+        "payload": {},
+        "metadata": { "command_text": "/answer stop-and-handoff" }
+      }
+    ],
+    "revision": { "id": "control-flow-escalation", "version": 1 },
+    "updated_at_ms": 1772067730000,
+    "metadata": {
+      "profile": {
+        "id": "control-flow-escalation",
+        "variant": "interactive"
+      }
+    }
+  }
+}
+```
 
-- If subagents HUD is already active, publish control-flow state in that HUD doc
-  (for example policy mode, round counters, escalation state).
-- If running control-flow standalone, own a dedicated `hud_id:"control-flow"` doc.
-- Update HUD state each bounded pass before reporting ORCH_PASS output.
+### Teardown / handoff
 
-- Follow the HUD ownership and teardown protocol from the `hud` skill when completing or handing off.
+```json
+{"action":"remove","ui_id":"ui:control-flow:escalation"}
+{"action":"remove","ui_id":"ui:control-flow"}
+```
 
 ## Evaluation scenarios