@femtomc/mu-agent 26.2.105 → 26.2.107

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

@@ -0,0 +1,363 @@
+---
+name: model-routing
+description: "Adds a model-selection overlay for issue DAG execution, recommending provider/model/thinking per issue from live harness capabilities."
+---
+
+# model-routing
+
+Use this skill when execution should choose different models for different issue
+kinds (for example code vs docs), while preserving protocol
+semantics.
+
+## Contents
+
+- [Purpose](#purpose)
+- [Required dependencies](#required-dependencies)
+- [Core contract](#core-contract)
+- [Quality profile policy (high-stakes orchestration)](#quality-profile-policy-high-stakes-orchestration)
+- [Overlay identity (`route:model-routing-v1`)](#overlay-identity-routemodel-routing-v1)
+- [Tag vocabulary](#tag-vocabulary)
+- [Recommendation packet contract](#recommendation-packet-contract)
+- [Selection algorithm (deterministic)](#selection-algorithm-deterministic)
+- [Transition table](#transition-table)
+- [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)
+- [Evaluation scenarios](#evaluation-scenarios)
+
+## Purpose
+
+Model-routing policies are overlays. They do not replace protocol
+semantics.
+
+Examples:
+- use a strong coding model for implementation leaves
+- use a stronger writing model for docs/synthesis leaves
+- choose lower-cost fast models for routine triage
+- escalate to deeper thinking for high-risk or complex nodes
+
+## Required dependencies
+
+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)
+- `control-flow` (optional; when loop/termination overlays are also active)
+
+## Core contract
+
+1. **Overlay, don’t fork protocol**
+   - Keep `hierarchical-work.protocol/v1` + `proto:hierarchical-work-v1`.
+   - Do not redefine `kind:*`, `ctx:*`, issue lifecycle semantics, or DAG validity.
+
+2. **Harness is source-of-truth**
+   - Drive recommendations from `mu control harness --json`.
+   - Only consider authenticated providers unless policy explicitly allows otherwise.
+
+3. **Recommend, then apply**
+   - Route decisions are explicit artifacts (forum packets + optional tags),
+     not hidden implicit behavior.
+
+4. **Non-blocking by default**
+   - Routing failure should degrade safely (fallback model / default model)
+     unless a hard requirement cannot be met.
+
+5. **Bounded pass per tick**
+   - One routing decision and one bounded mutation/action bundle per heartbeat pass.
+
+6. **Per-issue/session overrides preferred**
+   - Use `mu exec --provider/--model/--thinking` or `mu turn ...` overrides.
+   - Avoid changing workspace-global operator defaults for per-issue routing.
+
+## Quality profile policy (high-stakes orchestration)
+
+For protocol/runtime/schema/cross-adapter work, apply an explicit quality floor.
+Do not rely on implicit defaults.
+
+Recommended high-stakes profile:
+
+- provider: `openai-codex`
+- model: `gpt-5.3-codex`
+- thinking: `xhigh`
+
+Required guardrails:
+
+1. Always pass explicit `--provider --model --thinking` when launching workers.
+2. Do not use mini/fast profiles for root-close decisions, acceptance-signoff,
+   or architecture-contract issues unless the user explicitly requests it.
+3. If authenticated capability for the high-stakes profile is unavailable,
+   emit a `ROUTE_FALLBACK` packet that explains the downgrade rationale.
+
+## Overlay identity (`route:model-routing-v1`)
+
+- Tag scope root (or selected subtree root) with: `route:model-routing-v1`
+- Routing metadata remains orthogonal to `kind:*`, `ctx:*`, and `flow:*`.
+
+## Tag vocabulary
+
+Recommended routing tags (policy metadata):
+
+- Scope:
+  - `route:model-routing-v1`
+- Task family:
+  - `route:task:code`
+  - `route:task:docs`
+  - `route:task:research`
+  - `route:task:ops`
+  - `route:task:review`
+  - `route:task:synth`
+  - `route:task:general`
+- Depth intent:
+  - `route:depth:fast`
+  - `route:depth:balanced`
+  - `route:depth:deep`
+- Budget intent:
+  - `route:budget:low`
+  - `route:budget:balanced`
+  - `route:budget:premium`
+- Hard modality requirement:
+  - `route:modality:image` (omit for text-only)
+- Pin indicator:
+  - `route:pin` (exact provider/model comes from packet metadata)
+
+Notes:
+- Keep tags concise and stable.
+- Put detailed routing config in forum packets (not in tag strings).
+
+## Recommendation packet contract
+
+Post one `ROUTE_RECOMMENDATION` packet to `issue:<issue-id>` before launching work
+with a selected model.
+
+Suggested packet shape (JSON block inside forum message):
+
+```text
+ROUTE_RECOMMENDATION:
+{
+  "version": "route:model-routing-v1",
+  "issue_id": "<issue-id>",
+  "harness_fingerprint": "<sha256>",
+  "selected": {
+    "provider": "<provider>",
+    "model": "<model>",
+    "thinking": "<thinking-level>"
+  },
+  "alternates": [
+    { "provider": "<provider>", "model": "<model>", "thinking": "<thinking-level>" }
+  ],
+  "constraints": {
+    "task": "code|docs|research|ops|review|synth|general",
+    "depth": "fast|balanced|deep",
+    "budget": "low|balanced|premium",
+    "modality": "text|image",
+    "min_context_window": 0
+  },
+  "rationale": [
+    "provider authenticated",
+    "supports required thinking level",
+    "meets context/modality constraints",
+    "best score under budget/depth policy"
+  ],
+  "created_at_ms": 0
+}
+```
+
+Optional root-level packet for custom preferences:
+
+```text
+ROUTE_POLICY:
+{
+  "version": "route:model-routing-v1",
+  "quality_profiles": {
+    "orchestration_critical": {
+      "provider": "openai-codex",
+      "model": "gpt-5.3-codex",
+      "thinking": "xhigh"
+    }
+  },
+  "task_preferences": {
+    "code": [
+      { "provider": "openai-codex", "model": "gpt-5.3-codex", "thinking": "xhigh" }
+    ],
+    "docs": [
+      { "provider": "openrouter", "model": "google/gemini-3.1-pro-preview", "thinking": "high" }
+    ]
+  }
+}
+```
+
+If a preference entry is unavailable under current harness/auth state, skip it and
+continue deterministic fallback selection.
+
+## Selection algorithm (deterministic)
+
+### Inputs
+
+- Issue tags (`route:task:*`, `route:depth:*`, `route:budget:*`, `route:modality:image`, `route:pin`)
+- Optional `ROUTE_POLICY` and per-issue constraints from forum/body
+- Live harness snapshot (`mu control harness --json`)
+
+### Step 1: gather live capabilities
+
+```bash
+mu control harness --json --pretty
+```
+
+### Step 2: build candidate set
+
+1. Start from authenticated providers only.
+2. Flatten model entries across providers.
+3. Filter by hard requirements:
+   - required modality (`text` and optional `image`)
+   - minimum context window (if specified)
+   - pin requirement (`route:pin`) if specified
+4. Resolve target thinking from depth intent:
+   - `fast` -> `minimal`
+   - `balanced` -> `medium`
+   - `deep` -> `xhigh` if available, else `high`
+5. Clamp chosen thinking to model-supported `thinking_levels`.
+
+### Step 3: score candidates
+
+Use deterministic score components (example):
+
+- Hard-fit gates (must pass): auth, modality, context, thinking compatibility
+- Soft score:
+  - task preference match (`ROUTE_POLICY`/task family)
+  - reasoning/xhigh capability vs depth
+  - context headroom
+  - budget penalty from per-token cost
+
+Tie-breaker: lower estimated cost, then lexicographic `provider/model`.
+
+### Step 4: select + alternates
+
+- pick top candidate as `selected`
+- keep next N as `alternates` (recommended N=2)
+- post `ROUTE_RECOMMENDATION` packet
+
+### Step 5: apply selection
+
+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>."
+```
+
+For existing session turn:
+
+```bash
+mu turn --session-kind cp_operator --session-id <session-id> \
+  --provider <provider> --model <model> --thinking <thinking> \
+  --body "Continue issue <issue-id> with current routing selection."
+```
+
+## Transition table
+
+Given an executable issue under `route:model-routing-v1`:
+
+1. **No routing decision yet**
+   - action: compute recommendation + post `ROUTE_RECOMMENDATION` packet
+
+2. **Routing decision exists and still valid**
+   - action: execute issue using selected provider/model/thinking
+
+3. **Selected route fails at launch/runtime**
+   - action: choose next alternate, post `ROUTE_FALLBACK`, retry bounded once
+
+4. **All alternates exhausted**
+   - action: degrade to harness default model, post `ROUTE_DEGRADED`
+
+5. **Hard requirement unmet (no valid candidates)**
+   - action: create `kind:ask` node (`ctx:human`, `actor:user`) requesting
+     provider auth/config change or constraint relaxation
+
+## Planning handoff contract
+
+When planning a routed subtree:
+
+1. Tag policy scope with `route:model-routing-v1`.
+2. Tag executable nodes with task/depth/budget intent.
+3. Record any hard constraints (modality/context) in issue body or forum packet.
+4. Optionally add root `ROUTE_POLICY` preferences.
+5. Ensure DAG remains valid under `protocol` invariants:
+   - `mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty`
+   - `mu issues validate <root-id>`
+
+## Subagents/heartbeat execution contract
+
+Per orchestrator tick:
+
+1. Read tree + ready set + latest route packet on target issue.
+2. Read harness snapshot once per pass.
+3. Select one routing transition from the table above.
+4. Apply one bounded mutation bundle (recommend/fallback/ask/execute-start).
+5. Verify with:
+   - `mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty`
+   - `mu issues validate <root-id>`
+6. Update HUD state.
+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.
+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.
+If validate is final, disable the supervising heartbeat and report completion.
+```
+
+## Failure + fallback policy
+
+1. **Provider/model unavailable or auth drift**
+   - post `ROUTE_FALLBACK`
+   - move to next alternate
+
+2. **Thinking level unsupported for selected model**
+   - clamp to nearest supported lower level
+   - post rationale in fallback packet
+
+3. **No candidates satisfy hard constraints**
+   - create `kind:ask` escalation with clear options:
+     - authenticate provider X
+     - relax modality/context/depth constraint
+     - approve default-model execution
+
+4. **Auditability requirement**
+   - every route change emits forum packet (`ROUTE_RECOMMENDATION`,
+     `ROUTE_FALLBACK`, `ROUTE_DEGRADED`)
+
+## HUD visibility and teardown
+
+HUD usage is not optional 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.
+
+## Evaluation scenarios
+
+1. **Coding leaf selects deep coding model**
+   - Setup: `route:task:code`, `route:depth:deep`, authenticated coding provider.
+   - Expected: recommendation picks a deep reasoning coding model and starts work.
+
+2. **Docs leaf prefers writing model**
+   - Setup: `route:task:docs` with root `ROUTE_POLICY` preference for docs.
+   - Expected: recommendation uses preferred docs model when available, otherwise fallback.
+
+3. **Auth/provider drift fallback**
+   - Setup: selected provider becomes unauthenticated mid-run.
+   - Expected: `ROUTE_FALLBACK` packet and alternate selection in next bounded pass.
+
+4. **Hard requirement escalation**
+   - Setup: issue requires image input but no authenticated image-capable models.
+   - Expected: `kind:ask` node created; downstream remains blocked until user action.

package/prompts/skills/{planning → subagents/planning}/SKILL.md

@@ -3,7 +3,7 @@ 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."
 ---
 
-# Planning
+# planning
 
 Use this skill when the user asks for planning, decomposition, or a staged execution roadmap.
 
@@ -45,8 +45,8 @@ Before emitting or mutating planning HUD state, load **`hud`** and follow its ca
 
 ## Shared protocol dependency
 
-This skill plans DAGs for execution by `subagents`, so planning must follow the
-shared protocol in **`orchestration`**.
+This skill plans DAGs for execution by `execution`, so planning must follow the
+shared protocol in **`protocol`**.
 
 Before creating or reshaping DAG nodes, load that skill and use its canonical:
 
@@ -59,7 +59,12 @@ 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 orchestration protocol semantics.
+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
+`route:*` overlays plus route packets (for example `ROUTE_POLICY`) without
+changing protocol semantics.
 
 ## Core contract
 
@@ -71,6 +76,7 @@ without changing orchestration protocol semantics.
    - 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.
@@ -90,10 +96,10 @@ without changing orchestration protocol semantics.
 
 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 `subagents`), remove
+   - 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 `subagents` skill and offer to supervise subagents to execute the plan.
+   - Read the `execution` skill and offer to supervise execution to realize the plan.
 
 ## Suggested workflow
 
@@ -234,4 +240,5 @@ Required HUD updates during the loop:
 - 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.

package/prompts/skills/{orchestration → subagents/protocol}/SKILL.md

@@ -1,19 +1,17 @@
 ---
-name: orchestration
-description: "Defines the shared planning/execution orchestration protocol for issue-DAG work. Use when creating, validating, or executing protocol-driven DAG work."
+name: protocol
+description: "Defines the shared planning/execution protocol for issue-DAG work. Use when creating, validating, or executing protocol-driven DAG work."
 ---
 
-# orchestration
+# protocol
 
 Use this skill when work should flow through one shared protocol from planning to execution.
 
-This skill supersedes the previous `hierarchical-work-protocol` skill name.
-
 ## Contents
 
 - [Protocol identity](#protocol-identity)
 - [Canonical tags and node roles](#canonical-tags-and-node-roles)
-- [Control-flow overlays](#control-flow-overlays)
+- [Policy overlays](#policy-overlays)
 - [Protocol primitives](#protocol-primitives)
 - [Required invariants](#required-invariants)
 - [Planning handoff contract](#planning-handoff-contract)
@@ -26,7 +24,6 @@ This skill supersedes the previous `hierarchical-work-protocol` skill name.
 - Protocol ID: `hierarchical-work.protocol/v1`
 - Required issue tag on all protocol nodes: `proto:hierarchical-work-v1`
 
-This system does **not** use backward-compatibility aliases for older protocol names.
 Use only the protocol ID and tag above.
 
 ## Canonical tags and node roles
@@ -65,19 +62,24 @@ Node role rules:
    - Must include: `proto:hierarchical-work-v1`, `kind:ask`, `ctx:human`, `actor:user`
    - Must be non-executable (`node:agent` removed)
 
-## Control-flow overlays
+## Policy overlays
 
-Control-flow is layered on top of this protocol and should not redefine protocol
-primitives or `kind:*` semantics.
+Policy overlays are layered on top of this protocol and should not redefine
+protocol primitives or `kind:*` semantics.
 
-- Keep orchestration protocol tags/kinds as source-of-truth for structure.
-- Represent policy-specific behavior (for example review gates, retry rounds,
-  escalation thresholds) with `flow:*` tags/metadata.
-- Compile control-flow policy decisions into existing primitives (`spawn`, `fork`,
-  `expand`, `ask`, `complete`, `serial`) instead of introducing ad-hoc mutations.
+- Keep protocol tags/kinds as source-of-truth for structure.
+- Represent policy-specific behavior with overlay tags/metadata:
+  - loop/termination policy (for example review gates, retry rounds,
+    escalation thresholds): `flow:*`
+  - per-issue model/provider/thinking routing policy: `route:*`
+- Compile overlay decisions into existing primitives (`spawn`, `fork`, `expand`,
+  `ask`, `complete`, `serial`) and per-turn/per-session model overrides
+  (`mu exec` / `mu turn` with `--provider --model --thinking`) instead of
+  introducing ad-hoc mutations.
 
-Current compositional control-flow policy skill:
+Current compositional overlay skills:
 - `control-flow` (for example `flow:review-gated-v1` behavior)
+- `model-routing` (for example `route:model-routing-v1` behavior)
 
 ## Protocol primitives
 
@@ -187,7 +189,7 @@ mu issues dep <step-a> blocks <step-b>
 
 ## Planning handoff contract
 
-Before handoff from planning to subagent orchestration:
+Before handoff from planning to execution supervision:
 
 1. Root exists and is tagged `node:root`, `kind:root`, `proto:hierarchical-work-v1`.
 2. Every in-scope node carries `proto:hierarchical-work-v1`.
@@ -207,7 +209,7 @@ mu issues validate <root-id>
 Worker/orchestrator passes always choose one primitive at a time:
 
 1. `read_tree`
-2. Choose one primitive (`ask` | `expand` | `complete` | orchestration primitive)
+2. Choose one primitive (`ask` | `expand` | `complete` | protocol primitive)
 3. Apply
 4. Verify (`get`, `children`, `ready`, `validate`)
 5. Log human-facing progress to forum as a titled narrative update (context -> milestone moved -> impact -> overall progress -> next), using the reusable status-voice style from `heartbeats`
@@ -240,7 +242,7 @@ mu forum post issue:"$goal_id" -m "<goal brief + acceptance criteria>" --author
 
 1. **Planning-to-execution continuity**
    - Setup: a freshly planned DAG.
-   - Expected: all nodes satisfy protocol tag/kind/context rules and can be consumed by subagents without re-shaping.
+   - Expected: all nodes satisfy protocol tag/kind/context rules and can be consumed by `execution` without re-shaping.
 
 2. **Decomposition with synthesis fan-in**
    - Setup: worker expands a complex node.

package/prompts/skills/writing/SKILL.md

@@ -14,6 +14,7 @@ Use this skill when asked to write, edit, or review technical prose. This includ
 - [Common patterns by document type](#common-patterns-by-document-type)
 - [Editing and review workflow](#editing-and-review-workflow)
 - [Evaluation scenarios](#evaluation-scenarios)
+- [Quality bar](#quality-bar)
 
 ## Core contract