@femtomc/mu-agent 26.2.99 → 26.2.101

package/prompts/skills/subagents/SKILL.md

@@ -9,6 +9,7 @@ description: "Orchestrates issue-driven subagent execution with heartbeat superv
 
 - [Purpose (what this skill is for)](#purpose-what-this-skill-is-for)
 - [Shared protocol dependency](#shared-protocol-dependency)
+- [HUD skill dependency](#hud-skill-dependency)
 - [When to use](#when-to-use)
 - [Success condition](#success-condition)
 - [Dispatch modes](#dispatch-modes)
@@ -45,6 +46,13 @@ Before orchestration begins, load that skill and enforce:
 
 Do not run subagent orchestration against alternate protocol tags.
 
+## HUD skill dependency
+
+Before emitting or mutating subagent HUD state, load **`hud`** and follow its canonical contract.
+
+- 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).
+
 ## When to use
 
 - Work is represented as issue-scoped deliverables with explicit outcomes.
@@ -98,7 +106,10 @@ mu forum read issue:<root-id> --limit 20 --pretty
 2. Choose exactly one action/primitive from `hierarchical-work-protocol`.
 3. Apply it.
 4. Verify (`get`, `children`, `ready`, `validate`).
-5. Post concise progress to forum.
+5. 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.
 6. Exit tick.
 
 Stop automation when `mu issues validate <root-id>` returns final.
@@ -114,7 +125,7 @@ For claimed issue `<issue-id>` under `<root-id>`:
    - directly solvable -> `complete`
 3. Apply primitive.
 4. Verify state.
-5. Post concise progress to `issue:<issue-id>`.
+5. Post progress to `issue:<issue-id>` focused on deliverable status, capability impact, and next step.
 
 Repeat bounded passes until issue closes.
 
@@ -138,7 +149,17 @@ mu heartbeats create \
   --title "hierarchical-work-v1 <root-id>" \
   --reason hierarchical_work_protocol_v1 \
   --every-ms 15000 \
-  --prompt "Use skills subagents and hierarchical-work-protocol for root <root-id>. Run exactly one bounded orchestration pass: claim/work one ready proto:hierarchical-work-v1 issue (or perform one orchestration action), verify state, and report status. Stop when 'mu issues validate <root-id>' is final."
+  --prompt "Use skills subagents, hud, and hierarchical-work-protocol 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. 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):
+
+```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.
 ```
 
 ### B) tmux fan-out (parallel workers)
@@ -148,7 +169,7 @@ 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 and hierarchical-work-protocol. Work issue ${issue_id} using hierarchical-work.protocol/v1. Claim first, then run one full control loop.' ; rc=\$?; echo __MU_DONE__:\$rc"
+    "cd '$PWD' && mu exec 'Use skills subagents, hud, and hierarchical-work-protocol. Work issue ${issue_id} using hierarchical-work.protocol/v1. Claim first, then run one full control loop.' ; rc=\$?; echo __MU_DONE__:\$rc"
 done
 ```
 
@@ -157,26 +178,28 @@ done
 Use HUD for user visibility. Truth still lives in issues/forum.
 
 ```text
-/mu subagents on
-/mu subagents prefix mu-sub-
-/mu subagents root <root-id>
-/mu subagents tag proto:hierarchical-work-v1
-/mu subagents mode operator
-/mu subagents refresh
-/mu subagents snapshot
+/mu hud on
+/mu hud status
+/mu hud snapshot
 ```
 
-Tool: `mu_subagents_hud`
+Tool: `mu_hud`
 
-- Actions: `status`, `snapshot`, `on`, `off`, `toggle`, `refresh`,
-  `set_prefix`, `set_root`, `set_tag`, `set_mode`, `set_refresh_interval`,
-  `set_stale_after`, `set_spawn_paused`, `update`, `spawn`
+- 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)
+- Example update:
+  - `{"action":"set","doc":{"v":1,"hud_id":"subagents","title":"Subagents HUD","scope":"mu-root-123","chips":[{"key":"health","label":"healthy","tone":"success"},{"key":"mode","label":"mode:operator","tone":"dim"},{"key":"paused","label":"paused:no","tone":"dim"}],"sections":[{"kind":"kv","title":"Queue","items":[{"key":"ready","label":"Ready","value":"3"},{"key":"active","label":"Active","value":"2"},{"key":"sessions","label":"Sessions","value":"2"}]},{"kind":"activity","title":"Activity","lines":["Spawned worker for mu-abc123","Posted ORCH_PASS update"]}],"actions":[{"id":"refresh","label":"Refresh","command_text":"/mu hud snapshot","kind":"secondary"}],"snapshot_compact":"HUD(subagents) · healthy · mode=operator · ready=3 · active=2","updated_at_ms":1771853115000,"metadata":{"spawn_mode":"operator","spawn_paused":false}}}`
 
 ## 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 concise progress, and exits.
+   - 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.

package/dist/extensions/hud-mode.d.ts

@@ -1,8 +0,0 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
-export type MuHudMode = "planning" | "subagents";
-export declare function getActiveHudMode(): MuHudMode | null;
-export declare function resetHudMode(): void;
-export declare function setActiveHudMode(mode: MuHudMode | null): void;
-export declare function clearHudMode(mode: MuHudMode): void;
-export declare function syncHudModeStatus(ctx: ExtensionContext): void;
-//# sourceMappingURL=hud-mode.d.ts.map

package/dist/extensions/hud-mode.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"hud-mode.d.ts","sourceRoot":"","sources":["../../src/extensions/hud-mode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;AAIjD,wBAAgB,gBAAgB,IAAI,SAAS,GAAG,IAAI,CAEnD;AAED,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI,CAE7D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAIlD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAK7D"}

package/dist/extensions/hud-mode.js

@@ -1,21 +0,0 @@
-let activeHudMode = null;
-export function getActiveHudMode() {
-    return activeHudMode;
-}
-export function resetHudMode() {
-    activeHudMode = null;
-}
-export function setActiveHudMode(mode) {
-    activeHudMode = mode;
-}
-export function clearHudMode(mode) {
-    if (activeHudMode === mode) {
-        activeHudMode = null;
-    }
-}
-export function syncHudModeStatus(ctx) {
-    if (!ctx.hasUI) {
-        return;
-    }
-    ctx.ui.setStatus("mu-hud-mode", activeHudMode ? `hud:${activeHudMode}` : undefined);
-}

package/dist/extensions/planning-ui.d.ts

@@ -1,4 +0,0 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-export declare function planningUiExtension(pi: ExtensionAPI): void;
-export default planningUiExtension;
-//# sourceMappingURL=planning-ui.d.ts.map

package/dist/extensions/planning-ui.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"planning-ui.d.ts","sourceRoot":"","sources":["../../src/extensions/planning-ui.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AA0gBpF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,QAuenD;AAED,eAAe,mBAAmB,CAAC"}