@femtomc/mu-agent 26.2.97 → 26.2.99

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

@@ -0,0 +1,171 @@
+---
+name: setup-telegram
+description: "Sets up the Telegram messaging adapter with agent-first webhook, config, reload, verification, and identity linking steps. Use when onboarding or repairing Telegram channel integration."
+---
+
+# setup-telegram
+
+Use this skill when the user asks to set up Telegram messaging for `mu`.
+
+Goal: get Telegram bot ingress and reply delivery working with minimal user-side actions.
+
+## Contents
+
+- [Required user-provided inputs](#required-user-provided-inputs)
+- [Agent-first workflow](#agent-first-workflow)
+- [Evaluation scenarios](#evaluation-scenarios)
+- [Safety requirements](#safety-requirements)
+
+## Required user-provided inputs
+
+- 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
+
+### 0) Verify local prerequisites (agent)
+
+```bash
+command -v mu >/dev/null && echo "mu: ok"
+command -v python3 >/dev/null && echo "python3: ok (required for config patching)"
+command -v curl >/dev/null && echo "curl: ok (required for Telegram API + channel checks)"
+command -v jq >/dev/null && echo "jq: ok (required for filtered JSON checks)"
+```
+
+If any required command is missing, stop and ask the user to install it before proceeding.
+
+### 1) Preflight local state
+
+```bash
+mu control status --pretty
+mu store paths --pretty
+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
+
+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:
+
+```bash
+curl -sS "https://api.telegram.org/bot<bot-token>/setWebhook" \
+  --data-urlencode "url=https://<public-base>/webhooks/telegram" \
+  --data-urlencode "secret_token=<webhook-secret>"
+```
+
+If the agent cannot reach Telegram APIs from its environment, give user this exact command and continue once they confirm success.
+
+### 4) Patch mu config
+
+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'
+import json
+import os
+import sys
+from pathlib import Path
+
+path = Path(sys.argv[1])
+if path.exists():
+    data = json.loads(path.read_text())
+else:
+    data = {"version": 1, "control_plane": {}}
+
+cp = data.setdefault("control_plane", {})
+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")
+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.
+
+### 5) Reload and verify
+
+```bash
+mu control reload
+mu control status --json --pretty
+curl -sS http://localhost:3000/api/control-plane/channels | jq '.channels[] | select(.channel=="telegram")'
+```
+
+Verify:
+- `configured: true`
+- `active: true` (with running server)
+- route `/webhooks/telegram`
+
+### 6) Identity link using audit-derived chat id
+
+Preferred flow:
+1. Ask user to send one message to the bot.
+2. Extract latest Telegram audit row.
+3. Link actor chat id to tenant `telegram-bot`.
+
+```bash
+mu store tail cp_adapter_audit --limit 50 --json \
+  | jq -r '[.[] | select(.channel=="telegram")] | last | "actor=\(.actor_id)"'
+
+mu control link --channel telegram --actor-id <chat-id> --tenant-id telegram-bot --role operator
+mu control identities --pretty
+```
+
+If audit is unavailable, ask user for the chat id explicitly.
+
+### 7) Smoke + delivery checks
+
+```bash
+mu control status --pretty
+mu store tail cp_adapter_audit --limit 20 --pretty
+mu store tail cp_outbox --limit 20 --pretty
+```
+
+Ask user to send `/mu status` (or plain status text) and verify response delivery.
+
+## Evaluation scenarios
+
+1. **Happy path with API reachability**
+   - Inputs: valid bot token, reachable public webhook base URL, working `setWebhook` call.
+   - Expected: Telegram channel reports `configured=true` + `active=true`; inbound message gets reply.
+
+2. **Network-restricted agent environment**
+   - 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.
+
+## Safety requirements
+
+- Treat bot token and webhook secret as sensitive; do not echo full values in summaries.
+- Keep user prompts focused on the few actions the agent cannot do (BotFather + optional network-restricted webhook call).
+- Report concrete reason codes when attachment/media delivery fails.

package/prompts/skills/subagents/SKILL.md

@@ -1,27 +1,53 @@
 ---
 name: subagents
-description: Orchestrate issue-driven subagent work with heartbeat supervision and tmux worker fan-out.
+description: "Orchestrates issue-driven subagent execution with heartbeat supervision and tmux fan-out. Use when work should progress through durable parallel subagent loops."
 ---
 
 # Subagents
 
+## Contents
+
+- [Purpose (what this skill is for)](#purpose-what-this-skill-is-for)
+- [Shared protocol dependency](#shared-protocol-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)
+
 ## Purpose (what this skill is for)
 
-Use this skill for **durable multi-agent orchestration**: work that must keep moving over time, not just one-shot execution.
+Use this skill for **durable multi-agent orchestration**: work that must keep moving
+over time, not just one-shot execution.
 
-This skill combines `mu` primitives into one orchestration model:
+This skill is execution-supervision focused:
 
-- `mu issues` = executable DAG, dependencies, lifecycle state
-- `mu forum` = durable task/result packets
 - `mu heartbeats` / `mu cron` = orchestrator wake cadence
 - `tmux` + `mu exec` = parallel worker execution
-- subagents HUD = observability/control board
+- subagents HUD = operator observability/control board
+
+Source of truth remains in `mu issues` + `mu forum`.
+
+## Shared protocol dependency
+
+This skill executes DAG work defined by **`hierarchical-work-protocol`**.
 
-Protocol truth lives in **issues + forum**. HUD/tmux are execution and visibility surfaces.
+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.
 
 ## When to use
 
-- Work can be represented as issue-scoped deliverables with explicit outcomes.
+- Work is represented as issue-scoped deliverables with explicit outcomes.
 - Dependencies may unblock over time.
 - You want unattended progress between manual check-ins.
 
@@ -35,152 +61,45 @@ Protocol truth lives in **issues + forum**. HUD/tmux are execution and visibilit
 
 ### 1) Heartbeat dispatch (orchestrator cadence)
 
-Use when you want the orchestration loop to keep running over time.
+Use when you want orchestration to continue over time.
 
-Each heartbeat tick should run **one bounded control-loop pass**:
+Each heartbeat tick runs **one bounded orchestration pass**:
 
 1. Read queue/tree state.
-2. Choose one primitive (`ask`, `expand`, `complete`, etc.).
-3. Apply one action.
+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.
+Heartbeat dispatch is the orchestrator clock. It should supervise/advance the graph,
+not run unbounded worker sessions.
 
 ### 2) tmux dispatch (parallel workers)
 
-Use when multiple ready leaves should execute concurrently now.
-
-Spawn one tmux session per ready issue. Each worker should claim one issue, run one full issue loop, then exit.
-
-## Protocol: `subagents.protocol/v1` (how the skill executes)
-
-### Primitive: `read_tree`
-
-Before every mutation, inspect root + local node state:
-
-```bash
-mu issues get <issue-id> --pretty
-mu issues children <issue-id> --pretty
-mu issues ready --root <root-id> --tag proto:subagents-v1 --pretty
-mu forum read issue:<issue-id> --limit 20 --pretty
-```
-
-### Primitive: `claim`
-
-Claim before doing work on an executable issue:
-
-```bash
-mu issues claim <issue-id>
-mu forum post issue:<issue-id> -m "START: <plan for this pass>" --author operator
-```
-
-### Primitive: `spawn` (clean-context child)
-
-Create independent child tasks with scoped context:
-
-```bash
-child_json="$(mu issues create "<title>" \
-  --parent <issue-id> \
-  --body "<prompt + acceptance criteria>" \
-  --tag proto:subagents-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
-```
-
-Use dependencies to control timing:
-
-```bash
-mu issues dep <blocker-id> blocks <child-id>
-```
-
-### Primitive: `fork` (inherited-context child)
-
-Create analysis/synthesis children that depend on sibling outputs.
-Before creation, summarize dependency results from `mu forum read issue:<dep-id>`.
-Then create with `kind:fork` + `ctx:inherit`.
+Use when several ready leaves should execute concurrently now.
 
-### Primitive: `ask` (human input node)
+Spawn one tmux session per ready issue. Each worker claims one issue, executes one
+full issue loop, then exits.
 
-Represent user questions as first-class nodes:
+## Orchestration loops
 
-```bash
-ask_json="$(mu issues create "Question: <question>" \
-  --parent <issue-id> \
-  --tag proto:subagents-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
-```
-
-If downstream work depends on the answer:
-
-```bash
-mu issues dep <ask-id> blocks <child-id>
-```
-
-### Primitive: `complete`
-
-Always write a result packet, then close the issue:
-
-```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 needed (`failure`, `needs_work`, `skipped`).
-
-### Primitive: `expand`
-
-When decomposition is needed:
-
-1. Create child work nodes via `spawn` / `fork`.
-2. Create one synthesis child (`kind:synth`, `ctx:inherit`) blocked by all child work nodes.
-3. Close current node with `mu issues close <issue-id> --outcome expanded`.
+### Orchestrator heartbeat tick loop
 
-This encodes decompose→synthesize as explicit DAG nodes.
-
-### Primitive: `serial`
+For root `<root-id>`:
 
-Encode ordered execution with dependency edges:
+1. Inspect queue and local protocol state:
 
 ```bash
-mu issues dep <step-a> blocks <step-b>
+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
 ```
 
-## Required invariants
-
-- **Read-before-act-verify:** every write is followed by a re-read.
-- **Claim-before-work:** claim executable issues before file/work execution.
-- **Scoped authority:** mutate only current issue + descendants.
-- **Container hygiene:** remove `node:agent` from non-executable root/ask/container nodes.
-- **Idempotent logging:** forum updates should be append-only and resumable.
-- **Explicit outcomes:** every executable issue closes with concrete outcome.
-
-## Control loops
-
-### Orchestrator heartbeat tick loop (bounded)
-
-For root `<root-id>`:
-
-1. `read_tree` at root/selected node
-2. Choose exactly one primitive to apply
-3. Apply it
-4. Verify state (`mu issues get`, `children`, `ready`, `validate`)
-5. Post concise progress to forum
-6. Exit tick
+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.
+6. Exit tick.
 
 Stop automation when `mu issues validate <root-id>` returns final.
 
@@ -188,34 +107,26 @@ Stop automation when `mu issues validate <root-id>` returns final.
 
 For claimed issue `<issue-id>` under `<root-id>`:
 
-1. `read_tree`
+1. Run `read_tree`.
 2. Choose one primitive:
    - missing input -> `ask`
    - needs decomposition -> `expand`
    - directly solvable -> `complete`
-3. Apply primitive
-4. Verify state
-5. Post concise progress to `issue:<issue-id>`
+3. Apply primitive.
+4. Verify state.
+5. Post concise progress to `issue:<issue-id>`.
+
+Repeat bounded passes until issue closes.
 
-Repeat until issue closes.
+## Bootstrap and queue targeting
 
-## Bootstrap template
+If root DAG does not yet exist, create it using the
+`hierarchical-work-protocol` bootstrap template first.
+
+During orchestration, always scope queue reads with protocol tag:
 
 ```bash
-root_json="$(mu issues create "Root: <goal>" --tag node:root --tag proto:subagents-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 proto:subagents-v1 \
-  --tag kind:goal \
-  --tag ctx:clean \
-  --priority 2 \
-  --json)"
-goal_id="$(echo "$goal_json" | jq -r '.id')"
-
-mu forum post issue:"$goal_id" -m "<goal brief + acceptance criteria>" --author operator
+mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty
 ```
 
 ## Dispatch templates
@@ -224,32 +135,32 @@ mu forum post issue:"$goal_id" -m "<goal brief + acceptance criteria>" --author
 
 ```bash
 mu heartbeats create \
-  --title "subagents-v1 <root-id>" \
-  --reason subagents_protocol_v1 \
+  --title "hierarchical-work-v1 <root-id>" \
+  --reason hierarchical_work_protocol_v1 \
   --every-ms 15000 \
-  --prompt "Use skill subagents for root <root-id>. Run exactly one bounded orchestration pass: claim/work one ready proto:subagents-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 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."
 ```
 
 ### 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:subagents-v1 --json | jq -r '.[].id' | head -n 3); do
+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 'Work issue ${issue_id} using subagents.protocol/v1. Claim first, then run one full control loop.' ; rc=\$?; echo __MU_DONE__:\$rc"
+    "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"
 done
 ```
 
 ## Subagents HUD
 
-Use HUD to communicate with your user for visibility. Truth should still live entirely in issues/forum.
+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:subagents-v1
+/mu subagents tag proto:hierarchical-work-v1
 /mu subagents mode operator
 /mu subagents refresh
 /mu subagents snapshot
@@ -257,13 +168,29 @@ Use HUD to communicate with your user for visibility. Truth should still live en
 
 Tool: `mu_subagents_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`
+- 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`
+
+## 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.
+
+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.
 
 ## 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:subagents-v1`.
+- Convert unresolved gaps into new child issues tagged `proto:hierarchical-work-v1`.
 - Tear down temporary tmux sessions.
 
 ## Safety