@femtomc/mu-agent 26.2.98 → 26.2.100

package/prompts/skills/heartbeats/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: heartbeats
+description: "Runs heartbeat-program lifecycle workflows for durable operator wake loops, bounded tick prompts, and diagnostics. Use when scheduling, tuning, or repairing recurring automation."
+---
+
+# heartbeats
+
+Use this skill when the user asks to schedule, inspect, tune, or debug `mu heartbeats` automation.
+
+## Contents
+
+- [Core contract](#core-contract)
+- [Preflight checks](#preflight-checks)
+- [Heartbeat lifecycle workflow](#heartbeat-lifecycle-workflow)
+- [Prompt design for bounded ticks](#prompt-design-for-bounded-ticks)
+- [Diagnostics and recovery](#diagnostics-and-recovery)
+- [Evaluation scenarios](#evaluation-scenarios)
+
+## Core contract
+
+1. **One bounded pass per wake**
+   - Heartbeats should run one small control-loop pass, verify, and exit.
+   - Avoid unbounded prompts that try to complete an entire project in one wake.
+
+2. **CLI-first lifecycle control**
+   - Create/update/trigger/enable/disable via `mu heartbeats ...` commands.
+   - Do not hand-edit `heartbeats.jsonl`.
+
+3. **Read -> mutate -> verify**
+   - Inspect current heartbeat state first.
+   - After mutation, re-read with `list/get` and run a trigger smoke test.
+
+4. **Reason-coded automation**
+   - Use clear `--reason` values so wake and scheduler intent is auditable.
+
+## Preflight checks
+
+```bash
+mu status --pretty
+mu control status --pretty
+mu control identities --all --pretty
+mu heartbeats list --limit 20 --pretty
+```
+
+If user expects channel delivery (for example Telegram/Slack), verify operator identities
+are linked for the target channel before treating heartbeat execution as broken.
+
+## Heartbeat lifecycle workflow
+
+### 1) Inspect existing programs
+
+```bash
+mu heartbeats list --limit 20 --pretty
+mu heartbeats get <program-id> --pretty
+```
+
+Use `--json --pretty` when you need full records.
+
+### 2) Create a periodic heartbeat
+
+```bash
+mu heartbeats create \
+  --title "<descriptive title>" \
+  --prompt "<bounded control-loop instruction>" \
+  --every-ms 15000 \
+  --reason <reason_code>
+```
+
+Notes:
+- Omit `--every-ms` to use the default cadence (15000ms).
+- `--every-ms 0` creates event-driven mode (no periodic timer).
+
+### 3) Update cadence/prompt/enabled state
+
+```bash
+mu heartbeats update <program-id> --every-ms 300000
+mu heartbeats update <program-id> --prompt "<revised bounded instruction>"
+mu heartbeats enable <program-id>
+mu heartbeats disable <program-id>
+```
+
+### 4) Trigger smoke pass
+
+```bash
+mu heartbeats trigger <program-id> --reason smoke_test
+```
+
+Then verify state and recent effects:
+
+```bash
+mu heartbeats get <program-id> --pretty
+mu store tail events --limit 30 --pretty
+mu store tail cp_operator_turns --limit 30 --pretty
+```
+
+### 5) Remove obsolete programs
+
+```bash
+mu heartbeats delete <program-id>
+```
+
+## Prompt design for bounded ticks
+
+Use prompts that explicitly constrain each wake to one bounded pass.
+
+Good pattern:
+- inspect queue/state
+- do exactly one action
+- verify
+- summarize progress
+- exit
+
+Example bounded prompt:
+
+```text
+Review ready issues under root <root-id>. Perform exactly one bounded step:
+claim/work one ready issue (or report blocked), verify state, post concise progress,
+then exit.
+```
+
+For hierarchical DAG execution, pair this skill with:
+- `planning`
+- `hierarchical-work-protocol`
+- `subagents`
+
+For wall-clock scheduling semantics (`at`, `every`, `cron`), use `crons`.
+
+## Diagnostics and recovery
+
+If heartbeat automation appears stalled:
+
+1. Confirm program exists and is enabled:
+
+```bash
+mu heartbeats list --enabled true --limit 50 --pretty
+mu heartbeats get <program-id> --pretty
+```
+
+2. Force a manual trigger to isolate scheduler cadence issues:
+
+```bash
+mu heartbeats trigger <program-id> --reason manual_recovery_test
+```
+
+3. Inspect runtime artifacts:
+
+```bash
+mu store tail heartbeats --limit 20 --pretty
+mu store tail events --limit 50 --pretty
+mu store tail cp_operator_turns --limit 50 --pretty
+mu store tail cp_outbox --limit 30 --pretty
+```
+
+4. Apply smallest recovery action:
+- tighten or loosen `--every-ms`
+- simplify prompt scope
+- disable noisy/obsolete programs
+- relink channel identity when delivery is missing
+
+## Evaluation scenarios
+
+1. **Periodic progress heartbeat**
+   - Setup: heartbeat created with bounded control-loop prompt and `--every-ms 15000`.
+   - Expected: each wake performs one bounded pass and exits; no unbounded run behavior.
+
+2. **Event-driven heartbeat mode**
+   - Setup: heartbeat created/updated with `--every-ms 0`.
+   - Expected: no periodic timer firing; manual/explicit triggers still execute correctly.
+
+3. **Stall recovery via trigger + audit**
+   - Setup: user reports no visible progress from heartbeat.
+   - Expected: manual trigger works, events/operator-turn logs reveal root cause, and one minimal config change resolves progression.

package/prompts/skills/hierarchical-work-protocol/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: hierarchical-work-protocol
+description: "Defines the shared hierarchical planning/work issue-DAG protocol used by planning and subagents. Use when creating, validating, or executing protocol-driven DAG work."
+---
+
+# hierarchical-work-protocol
+
+Use this skill when work should flow through one shared protocol from planning to execution.
+
+## Contents
+
+- [Protocol identity](#protocol-identity)
+- [Canonical tags and node roles](#canonical-tags-and-node-roles)
+- [Protocol primitives](#protocol-primitives)
+- [Required invariants](#required-invariants)
+- [Planning handoff contract](#planning-handoff-contract)
+- [Execution loop contract](#execution-loop-contract)
+- [Minimal bootstrap template](#minimal-bootstrap-template)
+- [Evaluation scenarios](#evaluation-scenarios)
+
+## Protocol identity
+
+- 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
+
+Use this controlled tag vocabulary:
+
+- Protocol scope:
+  - `proto:hierarchical-work-v1`
+- Node kind:
+  - `kind:root` (root container)
+  - `kind:goal` (top-level executable objective under root)
+  - `kind:spawn` (independent executable child)
+  - `kind:fork` (context-inheriting executable child)
+  - `kind:synth` (synthesis executable child)
+  - `kind:ask` (human-input node)
+- Context mode:
+  - `ctx:clean` (independent context)
+  - `ctx:inherit` (depends on upstream outputs)
+  - `ctx:human` (user input required)
+- Actor marker:
+  - `actor:user` for human question nodes
+
+Node role rules:
+
+1. Root container node
+   - Must include: `node:root`, `kind:root`, `proto:hierarchical-work-v1`
+   - Must be non-executable (`node:agent` removed)
+
+2. Executable work nodes (`kind:goal|spawn|fork|synth`)
+   - Must include: `proto:hierarchical-work-v1`
+   - Must include exactly one `kind:*` from the executable set
+   - Must include one `ctx:*` tag (`ctx:clean` or `ctx:inherit`)
+   - Must remain executable (`node:agent` present)
+
+3. Human input nodes (`kind:ask`)
+   - Must include: `proto:hierarchical-work-v1`, `kind:ask`, `ctx:human`, `actor:user`
+   - Must be non-executable (`node:agent` removed)
+
+## Protocol primitives
+
+### `read_tree`
+
+Read current node + local neighborhood before every mutation:
+
+```bash
+mu issues get <issue-id> --pretty
+mu issues children <issue-id> --pretty
+mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty
+mu forum read issue:<issue-id> --limit 20 --pretty
+```
+
+### `claim`
+
+Claim executable work before execution:
+
+```bash
+mu issues claim <issue-id>
+mu forum post issue:<issue-id> -m "START: <plan for this pass>" --author operator
+```
+
+### `spawn`
+
+Create independent executable child work:
+
+```bash
+child_json="$(mu issues create "<title>" \
+  --parent <issue-id> \
+  --body "<prompt + acceptance criteria>" \
+  --tag proto:hierarchical-work-v1 \
+  --tag kind:spawn \
+  --tag ctx:clean \
+  --priority 2 \
+  --json)"
+child_id="$(echo "$child_json" | jq -r '.id')"
+mu forum post issue:"$child_id" -m "<task packet>" --author operator
+```
+
+### `fork`
+
+Create context-inheriting executable child work:
+
+1. Summarize dependency outputs from `mu forum read issue:<dep-id>`.
+2. Create child with tags `kind:fork` + `ctx:inherit` + `proto:hierarchical-work-v1`.
+
+### `ask`
+
+Create explicit human-input nodes:
+
+```bash
+ask_json="$(mu issues create "Question: <question>" \
+  --parent <issue-id> \
+  --tag proto:hierarchical-work-v1 \
+  --priority 1 \
+  --json)"
+ask_id="$(echo "$ask_json" | jq -r '.id')"
+mu issues update "$ask_id" \
+  --remove-tag node:agent \
+  --add-tag kind:ask \
+  --add-tag ctx:human \
+  --add-tag actor:user
+mu forum post issue:"$ask_id" \
+  -m "QUESTION: <question>\nOPTIONS: <list or free-form>\nReply in this topic, then close this issue." \
+  --author operator
+```
+
+### `complete`
+
+Close executable work with explicit result packets:
+
+```bash
+mu forum post issue:<issue-id> -m "RESULT:\n<result>" --author operator
+mu issues close <issue-id> --outcome success
+```
+
+Use explicit non-success outcomes when required (`failure`, `needs_work`, `skipped`).
+
+### `expand`
+
+Encode decomposition as first-class graph transitions:
+
+1. Create child work nodes via `spawn` and/or `fork`.
+2. Create one synthesis child tagged `kind:synth`, `ctx:inherit`, `proto:hierarchical-work-v1`.
+3. Block synthesis on all created children (`mu issues dep <child> blocks <synth>`).
+4. Close expanded node with `mu issues close <issue-id> --outcome expanded`.
+
+### `serial`
+
+Encode ordered execution explicitly with dependency edges:
+
+```bash
+mu issues dep <step-a> blocks <step-b>
+```
+
+## Required invariants
+
+- Read-before-act-verify for every mutation.
+- Claim-before-work on executable nodes.
+- Scoped authority: mutate only current issue and descendants.
+- Non-executable containers/questions must not retain `node:agent`.
+- Forum updates are append-only and resumable (`START`/`RESULT` packets).
+- Every executable issue closes with explicit outcome.
+- `mu issues validate <root-id>` must pass before declaring completion.
+
+## Planning handoff contract
+
+Before handoff from planning to subagent orchestration:
+
+1. Root exists and is tagged `node:root`, `kind:root`, `proto:hierarchical-work-v1`.
+2. Every in-scope node carries `proto:hierarchical-work-v1`.
+3. Every node has exactly one `kind:*` tag.
+4. Non-executable nodes (`kind:root`, `kind:ask`) have `node:agent` removed.
+5. Executable nodes (`kind:goal|spawn|fork|synth`) include `ctx:*` and acceptance criteria.
+6. Dependency edges encode required ordering and synth fan-in.
+7. Ready set sanity check succeeds:
+
+```bash
+mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty
+mu issues validate <root-id>
+```
+
+## Execution loop contract
+
+Worker/orchestrator passes always choose one primitive at a time:
+
+1. `read_tree`
+2. Choose one primitive (`ask` | `expand` | `complete` | orchestration primitive)
+3. Apply
+4. Verify (`get`, `children`, `ready`, `validate`)
+5. Log concise progress to forum
+6. Exit bounded pass
+
+## Minimal bootstrap template
+
+```bash
+root_json="$(mu issues create "Root: <goal>" \
+  --tag node:root \
+  --tag kind:root \
+  --tag proto:hierarchical-work-v1 \
+  --json)"
+root_id="$(echo "$root_json" | jq -r '.id')"
+mu issues update "$root_id" --remove-tag node:agent
+
+goal_json="$(mu issues create "Goal execution" \
+  --parent "$root_id" \
+  --tag kind:goal \
+  --tag ctx:clean \
+  --tag proto:hierarchical-work-v1 \
+  --priority 2 \
+  --json)"
+goal_id="$(echo "$goal_json" | jq -r '.id')"
+
+mu forum post issue:"$goal_id" -m "<goal brief + acceptance criteria>" --author operator
+```
+
+## Evaluation scenarios
+
+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.
+
+2. **Decomposition with synthesis fan-in**
+   - Setup: worker expands a complex node.
+   - Expected: spawn/fork children plus one synth child are created, dependencies block synth until all children finish, parent closes as `expanded`.
+
+3. **Human-input interruption**
+   - Setup: missing external decision during execution.
+   - Expected: `kind:ask` node is created, marked non-executable, downstream nodes are blocked on the ask node, execution resumes after answer issue closes.

package/prompts/skills/memory/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: memory
+description: "Runs cross-store memory retrieval and index maintenance workflows with bounded filters and timeline anchors. Use when querying historical context or repairing memory index health."
+---
+
+# memory
+
+Use this skill when the user asks for historical context lookup, timeline reconstruction,
+or memory index diagnostics.
+
+## Contents
+
+- [Core contract](#core-contract)
+- [Preflight checks](#preflight-checks)
+- [Query workflows](#query-workflows)
+- [Index maintenance workflows](#index-maintenance-workflows)
+- [Diagnostics and recovery](#diagnostics-and-recovery)
+- [Evaluation scenarios](#evaluation-scenarios)
+
+## Core contract
+
+1. **Bounded queries first**
+   - Start with narrow filters and explicit `--limit`.
+   - Expand scope only when needed.
+
+2. **Use the memory CLI surface**
+   - Use `mu memory search|timeline|stats|index ...`.
+   - Do not manually inspect/parse store files first unless memory commands fail.
+
+3. **Read -> refine -> verify**
+   - Run an initial query, inspect quality, refine filters, then confirm result relevance.
+
+4. **Index-aware behavior**
+   - `search/timeline/stats` auto-heal missing indexes when possible.
+   - Use explicit index status/rebuild commands for deterministic maintenance.
+
+## Preflight checks
+
+```bash
+mu status --pretty
+mu memory --help
+mu memory index status --pretty
+```
+
+Optional source inventory:
+
+```bash
+mu memory stats --pretty
+```
+
+## Query workflows
+
+### 1) Search for relevant context
+
+```bash
+mu memory search --query "<topic>" --limit 20
+```
+
+Refine with anchors/filters as needed:
+
+```bash
+mu memory search \
+  --query "<topic>" \
+  --issue-id <issue-id> \
+  --run-id <run-id> \
+  --source events \
+  --limit 30 --pretty
+```
+
+### 2) Reconstruct timeline around an anchor
+
+Timeline requires at least one anchor (for example `--issue-id`, `--run-id`,
+`--session-id`, `--conversation-key`, `--topic`, or `--channel`):
+
+```bash
+mu memory timeline --issue-id <issue-id> --order desc --limit 40 --pretty
+```
+
+### 3) Gather source-level memory stats
+
+```bash
+mu memory stats --pretty
+mu memory stats --source events --json --pretty
+```
+
+Useful for identifying dominant sources, recency gaps, and text-volume skew.
+
+## Index maintenance workflows
+
+### 1) Inspect index health
+
+```bash
+mu memory index status --pretty
+```
+
+### 2) Rebuild full index
+
+```bash
+mu memory index rebuild --pretty
+```
+
+### 3) Rebuild selected sources
+
+```bash
+mu memory index rebuild --sources issues,forum,events --pretty
+```
+
+Use targeted rebuilds when one source is stale/corrupted.
+
+## Diagnostics and recovery
+
+If memory results are missing or low quality:
+
+1. Verify index and rebuild if needed:
+
+```bash
+mu memory index status --pretty
+mu memory index rebuild --pretty
+```
+
+2. Re-run query with explicit anchors:
+
+```bash
+mu memory search --query "<topic>" --issue-id <issue-id> --limit 30 --pretty
+mu memory timeline --run-id <run-id> --order desc --limit 50 --pretty
+```
+
+3. Validate source coverage:
+
+```bash
+mu memory stats --pretty
+```
+
+4. Apply smallest correction:
+- tighten/expand filters
+- adjust anchors (`issue_id`, `run_id`, `session_id`, `topic`, channel metadata)
+- rebuild selected sources only
+
+Compatibility note:
+- `mu context ...` remains an alias to `mu memory ...`.
+
+## Evaluation scenarios
+
+1. **Issue-scoped context retrieval**
+   - Setup: user asks for prior decisions on one issue.
+   - Expected: `search` + `timeline` with `--issue-id` produce coherent, bounded context summary.
+
+2. **Missing-index auto-heal and explicit rebuild**
+   - Setup: index file missing/stale.
+   - Expected: query path auto-heals missing index when possible; explicit `index rebuild` restores healthy status deterministically.
+
+3. **Channel/session forensic lookup**
+   - Setup: user asks what happened in a specific conversation/session.
+   - Expected: anchored filters (`--session-id`/`--conversation-key`/`--channel`) recover relevant chronology without unrelated noise.

package/prompts/skills/mu/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: mu
+description: "Runs core mu operator workflows for bounded investigation, CLI-first state operations, and session handoffs. Use when general mu execution or state-management guidance is needed."
+---
+
+# mu
+
+Use this skill for day-to-day operator work in `mu`: inspect state, mutate state safely,
+run focused execution loops, and hand off to specialized skills when needed.
+
+## Contents
+
+- [Core contract](#core-contract)
+- [Default bounded investigation loop](#default-bounded-investigation-loop)
+- [Common mutation patterns](#common-mutation-patterns)
+- [Session and serve surfaces](#session-and-serve-surfaces)
+- [Durable automation handoff](#durable-automation-handoff)
+- [Evaluation scenarios](#evaluation-scenarios)
+- [Escalation map](#escalation-map)
+
+## Core contract
+
+1. **Investigate first**
+   - Prefer cheap evidence over assumptions.
+   - Start with bounded queries (`--limit`, scoped filters), then drill into specific entities.
+
+2. **CLI-first state operations**
+   - Read/mutate `issues`, `forum`, `memory`, and `control-plane` via `mu` CLI commands.
+   - Avoid hand-editing JSONL runtime journals for normal operations.
+
+3. **Read -> act -> verify loop**
+   - Before writes: inspect relevant current state.
+   - After writes: re-read to confirm effect.
+
+4. **Keep work reversible and explicit**
+   - Prefer small, composable steps.
+   - State assumptions and blockers clearly.
+
+## Default bounded investigation loop
+
+```bash
+mu status --pretty
+mu issues list --status open --limit 20 --pretty
+mu issues ready --limit 20 --pretty
+mu forum read user:context --limit 20 --pretty
+mu memory search --query "<topic>" --limit 20
+mu store tail events --limit 20 --pretty
+```
+
+Then inspect concrete targets:
+
+```bash
+mu issues get <id> --pretty
+mu forum read issue:<id> --limit 20 --pretty
+```
+
+## Common mutation patterns
+
+Issue/forum lifecycle:
+
+```bash
+mu issues update <id> --status in_progress --pretty
+mu forum post issue:<id> -m "START: <plan>" --author operator
+mu forum post issue:<id> -m "RESULT: <summary>" --author operator
+mu issues close <id> --outcome success --pretty
+```
+
+Control-plane lifecycle:
+
+```bash
+mu control status --pretty
+mu control identities --all --pretty
+mu control reload
+```
+
+Store forensics:
+
+```bash
+mu store ls --pretty
+mu store tail cp_commands --limit 20 --pretty
+mu store tail cp_outbox --limit 20 --pretty
+mu store tail cp_adapter_audit --limit 20 --pretty
+```
+
+## Session and serve surfaces
+
+Primary interactive surface:
+
+```bash
+mu serve
+```
+
+Session follow-ups/handoffs:
+
+```bash
+mu session list --json --pretty
+mu session <session-id>
+mu turn --session-kind operator --session-id <session-id> --body "<follow-up>"
+```
+
+In attached terminal operator chat, `/mu` helpers are available (`/mu events`, `/mu plan`, `/mu subagents`, `/mu help`).
+
+## Durable automation handoff
+
+Use heartbeat/cron programs for recurring or unattended progression:
+
+```bash
+mu heartbeats --help
+mu cron --help
+```
+
+When work is multi-step and issue-graph driven, use `planning` to shape the DAG,
+then `hierarchical-work-protocol` to keep DAG semantics consistent, then
+`subagents` for durable execution.
+For recurring bounded automation loops, use `heartbeats`.
+For wall-clock schedules (one-shot, interval, cron-expression), use `crons`.
+
+## Evaluation scenarios
+
+1. **Bounded investigation before mutation**
+   - Prompt: user asks for status + targeted change.
+   - Expected: skill gathers scoped evidence first (`mu status`, `issues`, `forum`, `memory`), then performs minimal write and verifies post-state.
+
+2. **Control-plane diagnostics loop**
+   - Prompt: user reports messaging channel stopped responding.
+   - Expected: skill inspects `mu control status`, identities, and adapter audit/outbox logs, then proposes smallest reversible recovery step (`reload`, relink, or config fix).
+
+3. **Session handoff continuity**
+   - Prompt: user asks to continue prior operator thread.
+   - Expected: skill inspects `mu session list`, resumes by ID, and keeps follow-up actions scoped to the resumed session context.
+
+## Escalation map
+
+- Historical context retrieval and index maintenance: **`memory`**
+- Planning/decomposition and DAG review: **`planning`**
+- Shared DAG semantics for planning + execution: **`hierarchical-work-protocol`**
+- Durable multi-agent orchestration: **`subagents`**
+- Recurring bounded automation scheduling: **`heartbeats`**
+- Wall-clock scheduling workflows: **`crons`**
+- Messaging adapter onboarding:
+  - **`setup-slack`**
+  - **`setup-discord`**
+  - **`setup-telegram`**
+  - **`setup-neovim`**