@femtomc/mu-agent 26.2.98 → 26.2.100

package/prompts/skills/planning/SKILL.md

@@ -1,12 +1,22 @@
 ---
 name: planning
-description: Investigate first, use the planning HUD as the user-facing status channel, then propose and refine a concrete issue DAG until approved.
+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
 
 Use this skill when the user asks for planning, decomposition, or a staged execution roadmap.
 
+## Contents
+
+- [Planning HUD is required](#planning-hud-is-required)
+- [Shared protocol dependency](#shared-protocol-dependency)
+- [Core contract](#core-contract)
+- [Suggested workflow](#suggested-workflow)
+- [Effective HUD usage heuristics](#effective-hud-usage-heuristics)
+- [Evaluation scenarios](#evaluation-scenarios)
+- [Quality bar](#quality-bar)
+
 ## Planning HUD is required
 
 For this skill, the planning HUD is the primary status/communication surface.
@@ -22,16 +32,30 @@ Default per-turn HUD loop:
 2. Synchronize checklist items and `root_issue_id` with the issue DAG.
 3. Emit `snapshot` (`compact` or `multiline`) and reflect it in your response.
 
+## Shared protocol dependency
+
+This skill plans DAGs for execution by `subagents`, so planning must follow the
+shared protocol in **`hierarchical-work-protocol`**.
+
+Before creating or reshaping DAG nodes, load that skill and use its canonical:
+
+- protocol identity/tag (`hierarchical-work.protocol/v1`, `proto:hierarchical-work-v1`)
+- node kinds and context tags
+- invariants for executable vs non-executable nodes
+- planning handoff contract
+
+Do not invent alternate protocol names or tag schemas.
+
 ## Core contract
 
 1. **Investigate first**
    - Read relevant code/docs/state before proposing work.
    - Avoid speculative plans when evidence is cheap to gather.
 
-2. **Materialize the plan in mu issues**
-   - Create a root planning issue and concrete child issues.
-   - Encode dependencies so the DAG reflects execution order.
-   - Add clear titles, scope, acceptance criteria, and role tags.
+2. **Materialize the plan in mu issues using the shared protocol**
+   - 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.
 
 3. **Drive communication through the planning HUD**
    - Treat HUD state as the canonical short status line for planning.
@@ -108,18 +132,39 @@ Also inspect repo files directly (read/bash) for implementation constraints.
 ### B) Draft DAG in mu-issue
 
 ```bash
-# 1) Create root planning issue
-mu issues create "<Goal>" --body "<scope + success criteria>" --tag node:root --pretty
-
-# 2) Create child work items
-mu issues create "<Subtask A>" --parent <root-id> --priority 2 --pretty
-mu issues create "<Subtask B>" --parent <root-id> --priority 2 --pretty
+# 1) Create protocol root container
+root_json="$(mu issues create "<Goal>" \
+  --body "<scope + success criteria>" \
+  --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
+
+# 2) Create executable child work nodes
+mu issues create "<Subtask A>" \
+  --parent "$root_id" \
+  --body "<acceptance criteria>" \
+  --tag kind:spawn \
+  --tag ctx:clean \
+  --tag proto:hierarchical-work-v1 \
+  --priority 2 --pretty
+
+mu issues create "<Subtask B>" \
+  --parent "$root_id" \
+  --body "<acceptance criteria>" \
+  --tag kind:fork \
+  --tag ctx:inherit \
+  --tag proto:hierarchical-work-v1 \
+  --priority 2 --pretty
 
 # 3) Add dependency edges where needed
 mu issues dep <child-a-id> blocks <child-b-id>
 
-# 4) Validate ready set
-mu issues ready --root <root-id> --pretty
+# 4) Validate ready set + protocol scope
+mu issues ready --root "$root_id" --tag proto:hierarchical-work-v1 --pretty
+mu issues validate "$root_id"
 ```
 
 ### C) Plan presentation template
@@ -134,7 +179,8 @@ mu issues ready --root <root-id> --pretty
 ### D) Revision loop
 
 - Apply feedback with `mu issues update` / `mu issues dep` / additional issues.
-- Re-run `mu issues ready --root <root-id> --pretty`.
+- Re-run `mu issues ready --root <root-id> --tag proto:hierarchical-work-v1 --pretty`.
+- Validate protocol-root status via `mu issues validate <root-id>`.
 - Present a concise diff of what changed and why.
 - Update HUD each turn so phase/waiting/next/blocker/confidence match the latest state.
 
@@ -158,9 +204,24 @@ Required HUD updates during the loop:
 - Adjust `confidence` as evidence quality changes (`low` when assumptions are unresolved).
 - Customize checklist steps once scope is understood; check them off as milestones complete.
 
+## Evaluation scenarios
+
+1. **Initial decomposition request**
+   - Prompt: user asks for a staged roadmap.
+   - Expected: investigation pass runs first, root + child issues are created with `proto:hierarchical-work-v1`, HUD shows `phase=drafting` and `waiting_on_user=false` until first review checkpoint.
+
+2. **Feedback-driven replan**
+   - Prompt: user requests scope change after first DAG draft.
+   - Expected: dependency/issue updates are applied, concise change diff is presented, HUD transitions through `reviewing`/`waiting_user` with updated `next_action`.
+
+3. **Blocked-by-missing-input planning turn**
+   - Prompt: required architecture constraint is unknown.
+   - Expected: plan captures explicit assumption gap, HUD uses `phase=blocked` or `waiting_user` (as appropriate), and asks one concrete unblock question.
+
 ## Quality bar
 
 - Every issue should be actionable and testable.
+- DAG nodes must satisfy `hierarchical-work.protocol/v1` before execution handoff.
 - Keep tasks small enough to complete in one focused pass.
 - Explicitly call out uncertain assumptions for user confirmation.
 - Prefer reversible plans and incremental checkpoints.

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

@@ -0,0 +1,141 @@
+---
+name: setup-discord
+description: "Sets up the Discord messaging adapter with agent-first config, reload, verification, and identity linking steps. Use when onboarding or repairing Discord channel integration."
+---
+
+# setup-discord
+
+Use this skill when the user asks to set up Discord messaging for `mu`.
+
+Goal: get Discord `/mu` ingress working with minimal user effort outside the terminal.
+
+## Required user-provided inputs
+
+- Public webhook base URL reachable by Discord (for example `https://mu.example.com`)
+- Discord app **Signing Secret**
+
+## 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 API 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 server reload/route checks fail because no server is running, ask the user to start `mu serve` in another terminal, then continue.
+
+### 2) Minimal user actions in Discord Developer Portal
+
+Ask the user to do only these actions:
+
+1. Create/select a Discord application.
+2. Set Interactions endpoint URL to:
+   - `https://<public-base>/webhooks/discord`
+3. Create an application command named `mu` in the target guild/server.
+4. Ensure the app is installed in the target guild.
+5. Provide the app `signing_secret`.
+
+### 3) Agent patches mu config
+
+Use this canonical patch snippet (preserves unrelated keys):
+
+```bash
+export MU_DISCORD_SIGNING_SECRET='<DISCORD_SIGNING_SECRET>'
+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", {})
+discord = adapters.setdefault("discord", {})
+discord["signing_secret"] = os.environ["MU_DISCORD_SIGNING_SECRET"]
+
+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, then `unset MU_DISCORD_SIGNING_SECRET` after patching.
+
+### 4) Reload and verify channel capability
+
+```bash
+mu control reload
+mu control status --json --pretty
+curl -sS http://localhost:3000/api/control-plane/channels | jq '.channels[] | select(.channel=="discord")'
+```
+
+Verify:
+- `configured: true`
+- `active: true` (when server is running)
+- route `/webhooks/discord`
+
+### 5) Identity linking with audit-assisted ID discovery
+
+Preferred flow:
+1. Ask user to run one Discord `/mu` command.
+2. Extract `actor_id` + `channel_tenant_id` from adapter audit.
+3. Link as operator.
+
+```bash
+mu store tail cp_adapter_audit --limit 50 --json \
+  | jq -r '[.[] | select(.channel=="discord")] | last | "actor=\(.actor_id) tenant=\(.channel_tenant_id)"'
+
+mu control link --channel discord --actor-id <actor-id> --tenant-id <tenant-id> --role operator
+mu control identities --pretty
+```
+
+If audit data is missing, ask user for Discord user id + guild id directly.
+
+### 6) Smoke 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 run `/mu status` and confirm ingress ACK behavior.
+
+## Evaluation scenarios
+
+1. **Happy path onboarding**
+   - Inputs: valid public base URL, `signing_secret`, running `mu serve`.
+   - Expected: Discord channel reports `configured=true` and `active=true`; `/mu status` gets an ACK/response flow.
+
+2. **Invalid signing secret**
+   - Inputs: Discord app configured with one secret, `mu` config has another.
+   - Expected: inbound interactions are denied with deterministic audit reason; skill routes user to correct secret + reload + smoke.
+
+3. **Audit-assisted link fallback**
+   - Inputs: command ingress works but no identity linked yet.
+   - Expected: skill derives `actor_id`/`channel_tenant_id` from audit, links operator identity, verifies with `mu control identities --pretty`.
+
+## Notes and caveats
+
+- Discord setup requires only `signing_secret` in current config contract.
+- Keep troubleshooting reason-code oriented (signature/timestamp/payload errors from adapter audit).
+- Keep user asks minimal: dashboard actions + one test command.

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

@@ -0,0 +1,141 @@
+---
+name: setup-neovim
+description: "Sets up the mu.nvim messaging channel with agent-first config, reload, verification, and identity linking steps. Use when onboarding or repairing Neovim channel integration."
+---
+
+# setup-neovim
+
+Use this skill when the user asks to set up the Neovim messaging channel (`mu.nvim`).
+
+Goal: get `:Mu ...` working against `mu` control-plane with minimal user-side editor actions.
+
+## Required user-provided inputs
+
+- Confirmation that `mu.nvim` is installed (or permission for the agent to provide install snippet)
+- Neovim-side place to set shared secret (`shared_secret` option or `MU_NEOVIM_SHARED_SECRET` env)
+
+## 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 API 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 exists for reload/capability checks, ask user to run `mu serve` in another terminal.
+
+### 2) Generate and set a shared secret (agent)
+
+Generate a strong shared secret, then patch config with this canonical snippet
+(preserves unrelated keys):
+
+```bash
+export MU_NEOVIM_SHARED_SECRET='<NEOVIM_SHARED_SECRET>'
+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", {})
+neovim = adapters.setdefault("neovim", {})
+neovim["shared_secret"] = os.environ["MU_NEOVIM_SHARED_SECRET"]
+
+path.parent.mkdir(parents=True, exist_ok=True)
+path.write_text(json.dumps(data, indent=2) + "\n")
+PY
+```
+
+Replace `<NEOVIM_SHARED_SECRET>` with the generated secret, then `unset MU_NEOVIM_SHARED_SECRET`.
+
+### 3) Reload and verify channel capability
+
+```bash
+mu control reload
+mu control status --json --pretty
+curl -sS http://localhost:3000/api/control-plane/channels | jq '.channels[] | select(.channel=="neovim")'
+```
+
+Verify:
+- `configured: true`
+- `active: true` (when server is running)
+- route `/webhooks/neovim`
+
+### 4) Provide minimal user editor steps
+
+Ask user to do only these actions in Neovim:
+
+1. Set the same shared secret in `mu.nvim` config (or env var `MU_NEOVIM_SHARED_SECRET`).
+2. Ensure plugin points at the running server (default server discovery is fine if available).
+3. Run:
+   - `:Mu channels`
+   - `:Mu link`
+   - `:Mu status`
+
+` :Mu link` is the preferred identity binding path for Neovim.
+
+### 5) Optional agent-side identity link fallback
+
+If `:Mu link` is unavailable, derive actor/tenant from adapter audit after one Neovim request,
+then link via control-plane API:
+
+```bash
+mu store tail cp_adapter_audit --limit 50 --json \
+  | jq -r '[.[] | select(.channel=="neovim")] | last | "actor=\(.actor_id) tenant=\(.channel_tenant_id)"'
+
+curl -sS -X POST http://localhost:3000/api/control-plane/identities/link \
+  -H 'content-type: application/json' \
+  -d '{"channel":"neovim","actor_id":"<actor-id>","tenant_id":"<tenant-id>","role":"operator"}'
+```
+
+### 6) Smoke and forensics
+
+```bash
+mu control status --pretty
+mu control identities --all --pretty
+mu store tail cp_adapter_audit --limit 20 --pretty
+```
+
+Confirm `:Mu status` returns a valid response in-editor.
+
+## Evaluation scenarios
+
+1. **Happy path with `:Mu link`**
+   - Inputs: matching shared secret in server + plugin, running `mu serve`.
+   - Expected: `:Mu channels` lists neovim as active; `:Mu link` succeeds; `:Mu status` returns valid response.
+
+2. **Shared-secret mismatch**
+   - Inputs: plugin secret differs from `control_plane.adapters.neovim.shared_secret`.
+   - Expected: neovim requests are rejected with deterministic auth reason; skill rotates/re-syncs secret and revalidates.
+
+3. **Manual identity-link fallback**
+   - Inputs: `:Mu link` unavailable in plugin version.
+   - Expected: skill extracts actor/tenant from adapter audit and links via control-plane API; identity appears in `mu control identities --all --pretty`.
+
+## Safety and UX requirements
+
+- Do not expose full shared secret in final user-facing summaries.
+- Keep user asks limited to in-editor actions only.
+- If failures occur, cite exact reason codes and next smallest recovery step.

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

@@ -0,0 +1,159 @@
+---
+name: setup-slack
+description: "Sets up the Slack messaging adapter with agent-first config, reload, verification, and identity linking steps. Use when onboarding or repairing Slack channel integration."
+---
+
+# setup-slack
+
+Use this skill when the user asks to set up Slack messaging for `mu`.
+
+Goal: get `/mu ...` working end-to-end in Slack, with the agent doing all local setup and asking the user only for Slack-console actions/secrets the agent cannot perform.
+
+## Contents
+
+- [Required user-provided inputs](#required-user-provided-inputs)
+- [Agent-first workflow](#agent-first-workflow)
+- [Evaluation scenarios](#evaluation-scenarios)
+- [Safety and UX requirements](#safety-and-ux-requirements)
+
+## Required user-provided inputs
+
+- Public webhook base URL reachable by Slack (for example `https://mu.example.com`)
+- Slack app **Signing Secret**
+- Slack app **Bot User OAuth Token** (`xoxb-...`) for outbound replies/media
+
+## 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 API 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 when reload/route checks are attempted, ask the user to run `mu serve` in another terminal, then continue.
+
+### 2) Drive user through Slack console steps (minimal ask)
+
+Ask the user to do only these actions in Slack API UI:
+
+1. Create/install a Slack app in target workspace.
+2. Configure request URL for all inbound surfaces to:
+   - `https://<public-base>/webhooks/slack`
+3. Enable at least:
+   - Slash command `/mu`
+   - Event Subscriptions (`app_mention`)
+   - Interactivity
+4. Ensure bot scopes include:
+   - `app_mentions:read`
+   - `chat:write`
+   - `files:read`
+   - `files:write`
+5. Return `signing_secret` and `bot_token` to the agent.
+
+### 3) Agent patches mu config (do not ask user to edit JSON)
+
+Use this canonical patch snippet (preserves unrelated keys):
+
+```bash
+export MU_SLACK_SIGNING_SECRET='<SLACK_SIGNING_SECRET>'
+export MU_SLACK_BOT_TOKEN='<SLACK_BOT_TOKEN>'
+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", {})
+slack = adapters.setdefault("slack", {})
+slack["signing_secret"] = os.environ["MU_SLACK_SIGNING_SECRET"]
+slack["bot_token"] = os.environ["MU_SLACK_BOT_TOKEN"]
+
+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, then `unset MU_SLACK_SIGNING_SECRET MU_SLACK_BOT_TOKEN` after patching.
+
+### 4) Reload and verify adapter status
+
+```bash
+mu control reload
+mu control status --json --pretty
+curl -sS http://localhost:3000/api/control-plane/channels | jq '.channels[] | select(.channel=="slack")'
+```
+
+Verify:
+- `configured: true`
+- `active: true` (when server is running)
+- route `/webhooks/slack`
+
+### 5) Identity link with least user effort
+
+Preferred flow:
+1. Ask user to send one Slack turn (for example `/mu status`).
+2. Extract actor + tenant IDs from audit.
+3. Link identity as operator.
+
+```bash
+mu store tail cp_adapter_audit --limit 50 --json \
+  | jq -r '[.[] | select(.channel=="slack")] | last | "actor=\(.actor_id) tenant=\(.channel_tenant_id)"'
+
+mu control link --channel slack --actor-id <actor-id> --tenant-id <tenant-id> --role operator
+mu control identities --pretty
+```
+
+If audit rows are unavailable, ask user for Slack IDs (`U...` user id, `T...` workspace id).
+
+### 6) Smoke test + forensic confirmation
+
+```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 run `/mu status` again and confirm response delivery.
+
+## Evaluation scenarios
+
+1. **Happy path onboarding**
+   - Inputs: valid public base URL, `signing_secret`, `bot_token`, running `mu serve`.
+   - Expected: `/api/control-plane/channels` reports Slack `configured=true` and `active=true`; Slack `/mu status` returns a response.
+
+2. **Signature validation failure**
+   - Inputs: wrong `signing_secret` configured.
+   - Expected: inbound command is rejected; `cp_adapter_audit` shows deterministic signature/timestamp reason code; skill proposes secret rotation and reload as next step.
+
+3. **Outbound token missing/invalid**
+   - Inputs: webhook ingress works but `bot_token` missing or invalid.
+   - Expected: ingress may ACK but delivery fails; `cp_outbox`/adapter audit expose concrete failure reason; skill guides user to update token and re-run smoke test.
+
+## Safety and UX requirements
+
+- Never expose secrets in chat logs unnecessarily; redact in summaries.
+- Do not overwrite unrelated `config.json` fields.
+- Keep the user ask short and sequential (one external-console step at a time).
+- If setup fails, report concrete reason codes from audit/outbox and propose the next smallest recovery step.