@femtomc/mu-agent 26.2.101 → 26.2.103

package/prompts/skills/mu/SKILL.md

@@ -11,9 +11,10 @@ run focused execution loops, and hand off to specialized skills when needed.
 ## Contents
 
 - [Core contract](#core-contract)
+- [CLI capability map](#cli-capability-map)
 - [Default bounded investigation loop](#default-bounded-investigation-loop)
-- [Common mutation patterns](#common-mutation-patterns)
-- [Session and serve surfaces](#session-and-serve-surfaces)
+- [Common mutation and diagnostics patterns](#common-mutation-and-diagnostics-patterns)
+- [Session, serve, and one-shot surfaces](#session-serve-and-one-shot-surfaces)
 - [Durable automation handoff](#durable-automation-handoff)
 - [Evaluation scenarios](#evaluation-scenarios)
 - [Escalation map](#escalation-map)
@@ -25,25 +26,66 @@ run focused execution loops, and hand off to specialized skills when needed.
    - 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.
+   - Use `mu` command surfaces for state reads/writes (`issues`, `forum`, `memory`, `events`, `control`, `store`, `session`).
    - 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**
+4. **Prefer self-discovery when uncertain**
+   - Run `mu --help` and `mu <command> --help` instead of guessing flags/subcommands.
+   - Use `mu guide` for the canonical in-CLI workflow map.
+
+5. **Keep work reversible and explicit**
    - Prefer small, composable steps.
    - State assumptions and blockers clearly.
 
+## CLI capability map
+
+Use these command groups as the source of truth for current capabilities:
+
+- Orientation + summaries:
+  - `mu --help`
+  - `mu guide`
+  - `mu status --pretty`
+- Work graph + coordination:
+  - `mu issues <subcmd>`
+  - `mu forum <subcmd>`
+- Context retrieval + traces:
+  - `mu memory <search|timeline|stats|index ...>`
+  - `mu events <list|trace ...>`
+- Control-plane + operator config:
+  - `mu control status`
+  - `mu control harness`
+  - `mu control identities`
+  - `mu control operator <...>`
+  - `mu control config <get|set|unset ...>`
+  - `mu control reload`
+  - `mu control diagnose-operator`
+- Session/runtime surfaces:
+  - `mu serve`, `mu stop`
+  - `mu session [list|config|<id>]`
+  - `mu turn ...`
+  - `mu exec ...`
+- Durable automation:
+  - `mu heartbeats <...>`
+  - `mu cron <...>`
+- Store forensics + replay:
+  - `mu store <paths|ls|tail ...>`
+  - `mu replay <id|path>`
+- Provider auth:
+  - `mu login [<provider>] [--list] [--logout]`
+
 ## 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 forum topics --prefix issue: --limit 20 --pretty
 mu memory search --query "<topic>" --limit 20
+mu events list --limit 20 --pretty
 mu store tail events --limit 20 --pretty
 ```
 
@@ -52,37 +94,54 @@ Then inspect concrete targets:
 ```bash
 mu issues get <id> --pretty
 mu forum read issue:<id> --limit 20 --pretty
+mu memory timeline --issue-id <id> --order desc --limit 40 --pretty
 ```
 
-## Common mutation patterns
+## Common mutation and diagnostics patterns
 
 Issue/forum lifecycle:
 
 ```bash
+mu issues claim <id> --pretty
 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:
+Control-plane lifecycle and config:
 
 ```bash
 mu control status --pretty
+mu control harness --pretty
 mu control identities --all --pretty
+mu control config get --pretty
+mu control operator get --pretty
 mu control reload
 ```
 
-Store forensics:
+Targeted config/operator updates:
+
+```bash
+mu control config set control_plane.operator.enabled false
+mu control config set control_plane.memory_index.every_ms 120000
+mu control operator set openai-codex gpt-5.3-codex high
+mu control diagnose-operator --limit 40 --pretty
+```
+
+Store forensics and run replay:
 
 ```bash
+mu store paths --pretty
 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
+mu store tail cp_operator_turns --limit 20 --pretty
+mu replay <issue-id-or-log-path>
 ```
 
-## Session and serve surfaces
+## Session, serve, and one-shot surfaces
 
 Primary interactive surface:
 
@@ -93,9 +152,17 @@ mu serve
 Session follow-ups/handoffs:
 
 ```bash
-mu session list --json --pretty
+mu session list --kind all --all-workspaces --limit 50 --json --pretty
 mu session <session-id>
 mu turn --session-kind operator --session-id <session-id> --body "<follow-up>"
+mu session config get --session-id <session-id>
+mu session config set-thinking --session-id <session-id> --thinking minimal
+```
+
+One-shot prompt (no durable session):
+
+```bash
+mu exec --message "<task>" --json
 ```
 
 In attached terminal operator chat, `/mu` helpers are available (`/mu events`, `/mu hud ...`, `/mu help`).
@@ -110,8 +177,8 @@ 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.
+then `hud` for canonical HUD behavior, 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`.
 
@@ -119,20 +186,21 @@ For wall-clock schedules (one-shot, interval, cron-expression), use `crons`.
 
 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.
+   - Expected: gather scoped evidence first (`mu status`, `issues`, `forum`, `memory`/`events`), then perform minimal write and verify 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).
+   - Prompt: messaging channel stopped responding.
+   - Expected: inspect `mu control status`, `harness`, identities, adapter audit/outbox logs; then apply smallest reversible fix (`config set`, relink, `reload`) and verify.
 
-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.
+3. **Session continuity + scope-safe config**
+   - Prompt: continue prior operator thread with model/thinking tweaks.
+   - Expected: use `mu session list` + `mu session <id>`/`mu turn`; when needed, apply `mu session config ...` (session-scoped) instead of mutating global defaults.
 
 ## Escalation map
 
 - Historical context retrieval and index maintenance: **`memory`**
 - Planning/decomposition and DAG review: **`planning`**
+- HUD contract/state updates across surfaces: **`hud`**
 - Shared DAG semantics for planning + execution: **`hierarchical-work-protocol`**
 - Durable multi-agent orchestration: **`subagents`**
 - Recurring bounded automation scheduling: **`heartbeats`**
@@ -142,3 +210,4 @@ For wall-clock schedules (one-shot, interval, cron-expression), use `crons`.
   - **`setup-discord`**
   - **`setup-telegram`**
   - **`setup-neovim`**
+- Technical writing/docs polish: **`writing`**

package/prompts/skills/planning/SKILL.md

@@ -117,12 +117,13 @@ Tool contract (preferred when tools are available):
     - `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":{"phase":"investigating","waiting_on_user":false,"confidence":"medium"}}}`
+  - `{"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"}`
 

package/prompts/skills/setup-telegram/SKILL.md

@@ -21,8 +21,6 @@ Goal: get Telegram bot ingress and reply delivery working with minimal user-side
 - Public webhook base URL reachable by Telegram (for example `https://mu.example.com`)
 - Telegram bot token (from BotFather)
 
-Optional (agent can usually discover):
-- Bot username
 
 ## Agent-first workflow
 
@@ -47,18 +45,10 @@ mu control identities --all --pretty
 
 If no running server is available, ask user to start `mu serve` in another terminal before reload/route checks.
 
-### 2) Generate webhook secret and discover bot username
+### 2) Generate webhook secret
 
 Generate a strong webhook secret (do not expose it in final summaries).
 
-If outbound network is available, discover bot username:
-
-```bash
-curl -sS "https://api.telegram.org/bot<bot-token>/getMe"
-```
-
-Extract `result.username` when present.
-
 ### 3) Configure Telegram webhook (agent does this when possible)
 
 Set webhook to `https://<public-base>/webhooks/telegram` with secret token:
@@ -78,7 +68,6 @@ Use this canonical patch snippet (preserves unrelated keys):
 ```bash
 export MU_TELEGRAM_WEBHOOK_SECRET='<TELEGRAM_WEBHOOK_SECRET>'
 export MU_TELEGRAM_BOT_TOKEN='<TELEGRAM_BOT_TOKEN>'
-export MU_TELEGRAM_BOT_USERNAME='<TELEGRAM_BOT_USERNAME_OR_EMPTY>'
 config_path="$(mu control status --json | python3 -c 'import json,sys; print(json.load(sys.stdin)["config_path"])')"
 
 python3 - "$config_path" <<'PY'
@@ -98,8 +87,6 @@ adapters = cp.setdefault("adapters", {})
 telegram = adapters.setdefault("telegram", {})
 telegram["webhook_secret"] = os.environ["MU_TELEGRAM_WEBHOOK_SECRET"]
 telegram["bot_token"] = os.environ["MU_TELEGRAM_BOT_TOKEN"]
-username = os.environ.get("MU_TELEGRAM_BOT_USERNAME", "").strip()
-telegram["bot_username"] = username or None
 
 path.parent.mkdir(parents=True, exist_ok=True)
 path.write_text(json.dumps(data, indent=2) + "\n")
@@ -107,8 +94,7 @@ PY
 ```
 
 Replace placeholder values with secrets from the user.
-If bot username is unknown, leave `MU_TELEGRAM_BOT_USERNAME` empty.
-Then `unset MU_TELEGRAM_WEBHOOK_SECRET MU_TELEGRAM_BOT_TOKEN MU_TELEGRAM_BOT_USERNAME` after patching.
+Then `unset MU_TELEGRAM_WEBHOOK_SECRET MU_TELEGRAM_BOT_TOKEN` after patching.
 
 ### 5) Reload and verify
 
@@ -160,9 +146,9 @@ Ask user to send `/mu status` (or plain status text) and verify response deliver
    - Inputs: agent cannot reach `api.telegram.org`.
    - Expected: skill hands user exact `setWebhook` command, resumes after confirmation, and still completes local config/reload verification.
 
-3. **Unknown bot username fallback**
-   - Inputs: `getMe` unavailable or username omitted.
-   - Expected: config stores `bot_username: null` (or omitted equivalent), adapter still activates, and identity link can proceed from audit chat id.
+3. **Token+secret only configuration**
+   - Inputs: valid bot token + webhook secret, no username discovery step.
+   - Expected: adapter activates and identity link can proceed from audit chat id.
 
 ## Safety requirements
 

package/prompts/skills/subagents/SKILL.md

@@ -192,8 +192,9 @@ Tool: `mu_hud`
   - 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":{"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}}}`
+  - `{"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":{"style_preset":"subagents","spawn_mode":"operator","spawn_paused":false}}}`
 
 ## Evaluation scenarios
 

package/prompts/skills/writing/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: writing
+description: "Crafts clear, precise technical documentation. Use when writing or reviewing docs, PR descriptions, error messages, READMEs, API references, or any technical prose."
+---
+
+# writing
+
+Use this skill when asked to write, edit, or review technical prose. This includes documentation, READMEs, PR descriptions, error messages, comments, API references, and commit messages.
+
+## Contents
+
+- [Core contract](#core-contract)
+- [Writing workflows](#writing-workflows)
+- [Common patterns by document type](#common-patterns-by-document-type)
+- [Editing and review workflow](#editing-and-review-workflow)
+- [Evaluation scenarios](#evaluation-scenarios)
+
+## Core contract
+
+1. **Audience first**
+   - Identify the reader's baseline knowledge before writing.
+   - Write for the busiest reader who needs this information.
+   - Honor their time: front-load the essential information.
+
+2. **Clarity over style**
+   - One idea per sentence. Complex concepts deserve their own space.
+   - Active voice: "The system returns an error" not "An error is returned by the system."
+   - Precise terminology: use the same word for the same concept throughout.
+   - Concrete over abstract: "200ms latency" beats "fast performance."
+
+3. **Structure for scanability**
+   - Headings should communicate the document structure without reading prose.
+   - Lists for parallel items (bullets for unordered, numbers for sequences).
+   - Code blocks and tables over prose descriptions.
+   - Inverted pyramid: conclusion, supporting details, background.
+
+4. **Actionability**
+   - Imperative for procedures: "Run the migration" not "The migration should be run."
+   - Explicit consequences: state what happens if the user does X.
+   - Anticipate failure modes in troubleshooting sections.
+
+5. **Accessibility**
+   - Plain language: avoid Latin abbreviations, buzzwords, metaphor-heavy descriptions.
+   - Sentence length: average 15-20 words. Vary rhythm but never confuse length with sophistication.
+   - Context for jargon: define domain-specific terms on first use or link to definitions.
+
+6. **Verify by reading aloud**
+   - Awkward phrasing surfaces when spoken.
+   - Test instructions by following them exactly as written.
+   - Delete mercilessly: if a sentence doesn't inform or direct, cut it.
+
+## Writing workflows
+
+### A) Documentation from scratch
+
+1. **Identify the audience and goal**
+   - Who will read this? What do they know? What must they do after reading?
+
+2. **Outline the structure**
+   - Opening paragraph: what this document covers and why it matters.
+   - Body: group related concepts, sequence procedures in order of execution.
+   - Closing: next steps, related resources, or troubleshooting.
+
+3. **Draft with constraints**
+   - Maximum 25 words per sentence on average.
+   - Active voice for all instructions.
+   - Code examples for any behavior described.
+
+4. **Review against the contract**
+   - Scan test: can a reader grasp structure from headings alone?
+   - Action test: can a reader execute procedures without asking questions?
+   - Deletion pass: remove sentences that don't inform or direct.
+
+### B) PR/commit description
+
+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)
+
+Keep under 80 characters per line in the summary. Body wraps at 72 characters.
+
+### C) Error messages
+
+1. **State what happened** (not what didn't)
+2. **Explain why** (the root cause, if known)
+3. **Provide the fix** (concrete next step, not generic advice)
+4. **Include identifiers** (error codes, relevant IDs, log locations)
+
+Example:
+```
+Error: Connection refused to database 'prod-db' on port 5432.
+Cause: The database service is not running or firewall blocks port 5432.
+Fix: Start the service with 'sudo systemctl start postgresql' or verify firewall rules.
+Log: See /var/log/postgresql/postgresql-14-main.log for details.
+```
+
+## Common patterns by document type
+
+### README.md
+
+Structure:
+1. One-line description of what this is
+2. Installation/usage (minimal working example)
+3. Key features (bullet list)
+4. Configuration/options
+5. Contributing/troubleshooting links
+
+### API documentation
+
+Per endpoint:
+- Purpose (one sentence)
+- HTTP method and path
+- Parameters (name, type, required, description)
+- Request/response examples
+- Error codes and meanings
+
+### Inline code comments
+
+- **Why**, not what: explain intent, not obvious behavior.
+- Non-obvious side effects or assumptions.
+- TODO/FIXME with issue references, not vague notes.
+- Public APIs: docstrings with parameters, returns, raises.
+
+### Configuration docs
+
+- Default values explicitly stated.
+- Units for all numeric values (ms, bytes, percent).
+- Validation constraints (min/max, allowed values).
+- Impact of changing the value (what breaks, what improves).
+
+## Editing and review workflow
+
+When reviewing existing prose:
+
+1. **Structural audit**
+   - Does the outline serve the reader's goal?
+   - Are headings descriptive? Is sequencing logical?
+
+2. **Sentence-level edits**
+   - Convert passive to active voice.
+   - Replace vague quantifiers ("some", "many") with specifics.
+   - Break long sentences (\> 25 words) into two.
+
+3. **Accuracy check**
+   - Verify all code examples execute as written.
+   - Confirm version numbers, paths, and URLs are current.
+   - Check that error messages match actual output.
+
+4. **Final polish**
+   - Read aloud for awkward rhythm.
+   - Consistent formatting (punctuation in lists, code fences with languages).
+   - Spelling and grammar (but prioritize clarity over grammatical perfection).
+
+## Evaluation scenarios
+
+1. **Drafting documentation for a new feature**
+   - Prompt: user asks for docs for a feature they've implemented.
+   - Expected: skill identifies audience, structures around user goals not implementation details, includes working examples, and ends with verification steps.
+
+2. **Reviewing a PR description**
+   - Prompt: user shares a draft PR description for feedback.
+   - Expected: skill checks for imperative summary line, clear what/why/how structure, and explicit breaking change notice if applicable.
+
+3. **Improving error messages**
+   - Prompt: user shares error handling code or current error text.
+   - Expected: skill transforms vague messages into specific what/why/fix format with actionable next steps and relevant identifiers.
+
+4. **Editing README for clarity**
+   - Prompt: user asks for help with a project's README.
+   - Expected: skill restructures for inverted pyramid, adds minimal working example, replaces feature paragraphs with scannable lists, and ensures installation steps are complete and ordered.
+
+## Quality bar
+
+- Every sentence earns its place: informs or directs.
+- No sentence requires a second reading to understand.
+- A reader can act on instructions without asking clarifying questions.
+- Code examples execute without modification.
+- A skim reader grasps the document's purpose and structure.