@agent-deck/cli 2.1.0 → 2.1.1

package/dist/muse-skills/agent-deck-playbooks/SKILL.md

@@ -7,7 +7,6 @@ description: Use when a task matches a bound-deck playbook trigger, or when the
 
 1. On task match: check `triggers` on `get_bound_deck`, then `get_playbook` before improvising. Playbook bodies live on the deck — do not mirror them into local skills.
 
-<!-- Self-improvement blocks below are verbatim from GLOBAL_BODY in packages/cli/src/agent-harness.ts (NOT-427); keep in sync. -->
 
 **When the user corrects your output** (the write trigger — no need to have called `get_playbook` earlier in the session):
 

package/dist/muse-skills/agent-deck-run/SKILL.md

@@ -1,19 +1,36 @@
 ---
 name: agent-deck-run
-description: Use when delegating a task to a local coding session on a named deck: brief it, launch it detached with agent-deck run, monitor it, review the result against the goal, and resume it with feedback until done.
+description: "Use when delegating a task to a local coding session on a named deck: brief it, launch it detached with agent-deck run, monitor it, review the result against the goal, and resume it with feedback until done."
 ---
 
 # Agent Deck run (orchestrator)
 
 You are the caller of a session, not the session. Follow the five steps below.
 
-## Prerequisite
+## 0. Check prerequisites first
 
-You must be able to run shell commands on the machine where the coding tool is signed in; otherwise stop and tell the human you cannot use this skill.
+You must be able to run shell commands on the machine where the coding tool is signed in; otherwise stop and tell the human you cannot use this skill. Then check, read-only, before writing any brief:
+
+```sh
+agent-deck --version      # >= 2.1.0
+agent-deck status         # Status: running
+agent-deck deck list      # the deck the user named exists
+claude auth status        # or: codex login status | cursor-agent status | muse --version
+```
+
+If anything fails, stop and tell the human exactly what is missing and how to fix it (the `agent-deck-setup` skill lists the fixes). Do not start a run that will fail midway.
+
+Bind the working folder once; `run` refuses an unbound folder ("No deck assigned in <dir>: run `agent-deck use <deck>` there first"):
+
+```sh
+cd <dir> && agent-deck use <deck> --client <client>
+```
+
+Leave the user's uncommitted changes alone; use a separate git worktree or branch when the repo is dirty.
 
 ## 1. Write the brief
 
-Write the brief to a file. It must state the goal, the constraints, the definition of done, what the session must not do, and the tool profile the brief owner chose. Never put secrets in the brief.
+Write the brief to a file. It must state the goal, the constraints, the definition of done, what the session must not do, and the tool profile the brief owner chose, and "if unclear, end your turn with the question". For code changes, the definition of done includes committing and pushing a named branch. Keep the user's decisions; label any number you had to assume as an assumption. Never put secrets in the brief.
 
 ## 2. Launch detached
 
@@ -25,11 +42,11 @@ agent-deck run <deck> --client <client> --cwd <dir> --prompt-file <brief-file> -
 
 Supported `--client` values are `claude`, `codex`, `cursor`, `muse`; `agent-deck run --help` lists the clients. The examples use `claude`; substitute your client. Read the `runId`, pid, and log path from the `run <runId> detached: pid <pid> log <path>` line. If the launch fails closed on a deck binding mismatch, stop and report to the human instead of rebinding.
 
-For per-client flags, resume ids, tool mappings, and trust behavior, see [docs/DELEGATION.md](../../docs/DELEGATION.md).
+For per-client flags, resume ids, tool mappings, and trust behavior, see `docs/DELEGATION.md` in the agent-deck repository.
 
 ## 3. Monitor
 
-Poll until the state leaves `running`. Suggested poll interval: 30 seconds (unconfirmed — no measured run durations yet; NOT-429 operator runs will justify the value against `run status --json` durations).
+Poll until the state leaves `running`. Poll every 30 seconds: read-only runs typically take about 1–3 minutes, so a 30-second cadence catches the end within one interval without busy-polling.
 
 ```sh
 agent-deck run status <runId>
@@ -39,11 +56,11 @@ agent-deck run log <runId> --tail 50
 agent-deck run list
 ```
 
-Read the `state` field (`running|ended|error|died`), the `sessionId`, and the log path. Stop rule: on `died` or `error`, stop polling, read the tail of the log for the failure, and report to the human.
+Log lines look like `<ts> text|tool|result|end ...`; a finished run ends with `result success sessionId=<id> <final text>` and `end sessionId=<id>`. Read `text` lines for questions; answer from verified facts or ask the human. Read the `state` field (`running|ended|error|died`), the `sessionId`, and the log path. Stop rule: on `died` or `error`, stop polling, read the tail of the log for the failure, and report to the human.
 
 ## 4. Review
 
-Judge the session's output against the goal and definition of done from step 1, not against the session's own summary. If it meets the goal, report to the human and stop.
+Judge the session's output against the goal and definition of done from step 1, not against the session's own summary: open the real files, diff, tickets, or PR yourself. For code work, verify it landed: `git ls-remote origin <branch>` matches the session's commit. If it meets the goal, report to the human and stop.
 
 ## 5. Resume with feedback
 
@@ -53,13 +70,13 @@ Resume the same session with a feedback brief that quotes the gap found in step
 agent-deck run <deck> --client <client> --cwd <dir> --prompt-file <feedback-file> --tools readonly --resume <sessionId> --detach
 ```
 
-Repeat steps 3-5 until the goal is met or a round cap is hit (placeholder: 3 feedback rounds, unconfirmed — awaiting owner confirmation per NOT-429), then report to the human.
+Repeat steps 3-5 until the goal is met, for at most 3 feedback rounds. If the goal is still not met after round 3, stop and bring the blocker to the human instead of resuming again.
 
 ### Corrections from a delegated run
-- The party that observed and made the correction files it: the orchestrator files `propose_playbook_patch` on its own bound deck <TBD: owner confirms who files>; the delegated session files only when a human corrects it directly.
+- The party that observed and made the correction files it: the orchestrator files `propose_playbook_patch` on its own bound deck; the delegated session files only when a human corrects it directly.
 - Evidence quotes the review gap as `user_feedback_excerpt` plus `runId`, `sessionId`, tool profile, and log path; no secrets in evidence.
 - Clearly general lesson: `update` with `add_item` (or `create` when no playbook covers it); not yet general: `signal_only`.
-- Cross-deck: `create`/`signal_only` land on the caller's bound deck and `get_playbook` reads only that deck (`packages/backend/src/mcp-tools/register.ts:758`, `packages/backend/src/routes/playbooks.ts:185`), so for a playbook on another deck file `signal_only` with the ids above.
+- Cross-deck: `create`/`signal_only` land on the caller's bound deck and `get_playbook` reads only that deck, so for a playbook on another deck file `signal_only` with the ids above.
 
 ## Hard rules
 

package/dist/muse-skills/agent-deck-setup/SKILL.md

@@ -9,9 +9,11 @@ Treat setup as three separate layers: daemon health, host transport, then folder
 
 1. Run `agent-deck status` and check `http://127.0.0.1:1110/health` (or `<mcp-url>/health`
    from `.agent-deck/use.json` if present).
-2. If the daemon is down, tell the user to run:
-   - `npm i -g agent-deck`
-   - `agent-deck start --daemon`
+2. If agent-deck is missing, older than 2.1.0 (`agent-deck --version`), or the daemon is down, tell the user to run the matching fix:
+   - Not installed (macOS, Node.js 20+, npm): `npx @agent-deck/cli@latest install`, then `export PATH="$HOME/.local/bin:$PATH"` (managed install: launcher in `~/.local/bin`, versions under `~/.agent-deck/`).
+   - Outdated: `agent-deck upgrade` (`agent-deck upgrade --check` reports whether one is available).
+   - Daemon down: `agent-deck start --daemon`.
+   - `agent-deck doctor` prints any harness repair as `agent-deck setup --client <client>`; run it, then restart that host.
 3. If the daemon is healthy but MCP tools are unavailable, repair the host transport:
    - **Codex:** verify the Agent Deck plugin is installed, enabled, and current. Its bundled
      `.mcp.json` must run `agent-deck mcp-launch`; reload or start a new task after changing
@@ -22,7 +24,9 @@ Treat setup as three separate layers: daemon health, host transport, then folder
      that host.
 4. Check the folder assignment reported by `agent-deck status`. If it is missing or legacy,
    tell the user to run `agent-deck use <deck>` in that folder, then reload or retry MCP.
-5. Once transport and assignment are valid, use the session skill and require
+5. For delegation (`agent-deck run`), the client CLI must also be installed and signed in. Check `claude auth status`, `codex login status`, `cursor-agent status`, or `muse --version`; if missing, point the user to the official install docs ([Claude Code](https://docs.anthropic.com/en/docs/claude-code/setup), [Codex](https://developers.openai.com/codex/cli), [Cursor CLI](https://cursor.com/docs/cli/installation); muse per its distribution) and its sign-in (`claude`, `codex login`, `cursor-agent login`, `muse login`).
+6. If no deck exists (`agent-deck deck list`), the user creates one in the dashboard (`agent-deck open` → My Decks) or imports one: `agent-deck import <file>.agent-deck.json`.
+7. Once transport and assignment are valid, use the session skill and require
    `get_session_binding` followed by `get_bound_deck`.
-6. Do not invent credentials, ports, or shell install pipelines. Keep guidance read-only;
+8. Do not invent credentials, ports, or shell install pipelines. Keep guidance read-only;
    the user executes install and setup commands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-deck/cli",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Local MCP proxy — decks of tools, keys, and self-improving playbooks",
   "license": "MIT",
   "bin": {
@@ -40,8 +40,8 @@
     "prepublishOnly": "node ../../scripts/pre-publish-check.mjs && npm run build"
   },
   "dependencies": {
-    "@agent-deck/backend": "^2.1.0",
-    "@agent-deck/shared": "^2.1.0",
+    "@agent-deck/backend": "^2.1.1",
+    "@agent-deck/shared": "^2.1.1",
     "@anthropic-ai/claude-agent-sdk": "^0.3.296"
   },
   "devDependencies": {