claws-code 0.8.0

package/.claude/commands/claws-auto.md

@@ -0,0 +1,90 @@
+---
+name: claws-auto
+description: Autonomous orchestration loop. Plans, dispatches waves, audits between waves, self-corrects on failures, stops when goal met or budget exhausted.
+---
+
+## MANDATORY cold-start sequence — execute in order, no deliberation
+
+1. **Acknowledge in 1 line.** "Autonomous run: <one-sentence goal summary>." No more.
+2. **Do NOT enter plan mode.** This command acts immediately after internal planning.
+3. **Save start time.** Record `startedAt` as ISO timestamp.
+4. **Create progress doc first.** Write `.local/audits/<goal-slug>/PROGRESS.md` before the first spawn.
+5. **Dispatch WAVE 1 immediately after the progress doc is written.** No deliberation.
+6. **Monitor armed within 1 tool call of every spawn.** `monitor_arm_command` from each spawn response MUST be the very next tool call. No exceptions.
+
+See `[[Arm Monitor at spawn]]` memory. Violation is a sequencing bug.
+
+---
+
+# /claws-auto <goal>
+
+## What this does
+Autonomous orchestration loop. Internally runs `/claws-plan` logic, then dispatches waves of workers, audits between each wave, self-corrects failures, and loops until the goal is met or the time/wave budget is exhausted. Surfaces only genuine blockers as user questions.
+
+See skill: `.claude/skills/claws-auto-engine/SKILL.md` for the full loop spec.
+
+## Behavior
+
+### Boot sequence
+```
+1. slugify the goal → <goal-slug>
+2. mkdir -p .local/audits/<goal-slug>/
+3. write .local/audits/<goal-slug>/PROGRESS.md (header + Wave 1 plan)
+4. internal /claws-plan logic — read relevant files, decompose into waves
+5. dispatch Wave 1
+```
+
+### Wave dispatch protocol
+Each wave:
+1. Decide workers for this wave (max 4 concurrent)
+2. For each worker: `claws_worker(name=..., mission=..., detach=true)` → arm Monitor immediately
+3. Wait for all Monitors (all workers done)
+4. Run inter-wave audit (read logs, check test output, verify commits)
+5. Update `PROGRESS.md` with wave result
+6. If failures: attempt auto-recovery (spawn fix workers) — max 1 recovery wave per failure
+7. If goal met: write DONE section in `PROGRESS.md`, report to user, stop
+8. If budget exceeded: write BLOCKED section, surface to user, stop
+9. Otherwise: dispatch next wave
+
+### User surfacing
+Only stop to ask the user when:
+- A blocker cannot be resolved by a fix wave (e.g., missing credentials, ambiguous design decision)
+- A destructive action is required (force push, drop table, delete non-recoverable data)
+- Budget exhausted without goal completion
+
+For all other failures: attempt recovery autonomously.
+
+### Budget
+Default: 6 waves, 90 min wall-clock. After either limit, write the BLOCKED section and stop.
+
+## Mission discipline (enforced)
+
+Per `[[Compact missions]]`: every worker mission MUST be under 500 words. Cite file:line references instead of quoting code inline.
+
+Per `[[Don't put literal marker in mission]]`: never write the literal completion marker in mission body — paraphrase as "the standard Claws completion sentinel".
+
+Per `[[Tri-platform first]]`: every mission dispatched to workers that touch code MUST include a tri-platform constraint line: "this change must work identically on darwin, linux, and win32."
+
+## Hard rules
+
+- NEVER block on a read-only inter-wave audit — run it, don't wait for user
+- NEVER skip Monitor arming — the very next tool call after every spawn MUST be `Monitor(...)`
+- NEVER exceed 4 concurrent workers in a single wave
+- NEVER use Bash to run user's task — use `claws_exec` or `claws_worker`
+- ALWAYS write progress to `.local/audits/<goal-slug>/PROGRESS.md` between waves
+- ALWAYS pull `--rebase` from origin before workers push
+
+## Examples
+
+```
+/claws-auto ship the v0.8.0 release (docs + CI + npm pack dry-run)
+/claws-auto fix all TypeScript errors across the extension
+/claws-auto audit and resolve the 4 open bugs in .local/blueprints/v0714-bug-tracker.md
+/claws-auto write and green all missing tests for mcp_server.js
+```
+
+## When NOT to use
+
+For a single task (not a multi-wave goal), use `/claws-do`.
+For planning only (no execution), use `/claws-plan`.
+For human-in-the-loop goal tracking with checkpoints, use `/claws-goal`.

package/.claude/commands/claws-bin.md

@@ -0,0 +1,28 @@
+---
+name: claws-bin
+description: View or change the worker binary used for spawns (multi-account / alias support).
+---
+
+# /claws-bin [<binary-name> | reset]
+
+Sets or reports the binary used by `claws_worker` / `claws_fleet` /
+`claws_dispatch_subworker` to spawn worker terminals. Useful for teams using
+multiple Claude accounts via shell aliases.
+
+## Usage
+
+- `/claws-bin claude-neu` → sets worker binary to `claude-neu`. Persists in
+  `.claws/claude-bin` (gitignored). Takes effect immediately — next spawn uses it.
+- `/claws-bin reset` → clears the file, reverts to default (`claude`) or
+  `CLAWS_CLAUDE_BIN` env var if set.
+- `/claws-bin` (no arg) → reports current binary and source (file/env/default).
+
+## How to act
+
+1. If user passed `<binary-name>` → call `claws_set_bin(name: "<name>")`,
+   confirm in chat with the returned message.
+2. If user passed `reset` → call `claws_set_bin()` (no args), confirm.
+3. If no arg → call `claws_get_bin()`, show result.
+
+This is a single MCP tool call. No deliberation, no pre-verification. Trust the
+result.

package/.claude/commands/claws-cleanup.md

@@ -0,0 +1,28 @@
+---
+name: claws-cleanup
+description: Close all worker terminals after a fleet run. Leaves user-created terminals untouched.
+---
+
+# /claws-cleanup
+
+## What this does
+Finds all terminals with worker-style names (prefixed with "worker-") and closes them via `claws_close`. Confirms the count with the user if there are any before proceeding. Idempotent — safe to run multiple times.
+
+## Behavior
+- Call `claws_list` to enumerate all terminals
+- Identify terminals whose name starts with "worker-" or matches ones you created this session
+- If 0 found: "Nothing to clean up — terminal panel is already clear."
+- If N found: confirm "Close N worker terminals? (Y to proceed)" then call `claws_close` for each
+- Call `claws_list` again to confirm removal
+- Report: "Closed N terminals. Your terminals are untouched."
+
+## Examples
+```
+/claws-cleanup
+clean up all worker terminals
+close everything after the fleet run
+```
+
+## When NOT to use
+Do not use to close specific terminals by ID — call `claws_close(id=N)` directly.
+Do not use if you want to close ALL terminals including user ones — that requires explicit confirmation.

package/.claude/commands/claws-do.md

@@ -0,0 +1,82 @@
+---
+name: claws-do
+description: Universal verb — classifies any task into the right execution shape and runs it.
+---
+
+## MANDATORY cold-start sequence — execute in order, no deliberation
+
+1. **Acknowledge in 1 line.** "Got it — <one-sentence task summary>." No more.
+2. **Do NOT enter plan mode.** This is an ACTION command. If the task is complex
+   enough to need a plan, redirect to `/claws-plan` and stop.
+3. **Do NOT call TodoWrite for the task itself.** This command makes ONE MCP call.
+4. **Do NOT pre-verify the sidecar, Monitor, or hooks.** Guaranteed by
+   SessionStart in v0.7.13+. Trust the system.
+5. **Monitor arming is time-critical.** `monitor_arm_command` from the spawn
+   response MUST be your very next tool call after spawn returns. Any tool call
+   between spawn and Monitor arm is a sequencing bug — abort what you were
+   doing and arm the Monitor first.
+
+Classify and act. The routing tree below handles the rest.
+
+---
+
+# /claws-do <task>
+
+## What this does
+Classifies the user's request into one of four execution buckets and routes it to the right MCP tool. Never falls back to the Bash tool. Never manually boots a worker via terminal send sequences.
+
+## Routing decision tree
+
+Classify the request BEFORE creating anything:
+
+**Bucket 1 — One-shot shell command**
+Signals: "run npm test", "build the project", "git status", any single shell invocation needing output + exitCode.
+Action: `claws_exec(command="<cmd>", timeout_ms=120000)` — read output and exitCode, report to user. Done.
+
+**Bucket 2 — Single autonomous Claude task** (default when ambiguous)
+Signals: "fix the auth bug", "refactor X", "audit Y", "write tests for Z", any mission-shaped task.
+Action:
+```
+claws_worker(
+  name="worker-<short-slug>",
+  mission="<full mission text ending with: print __CLAWS_DONE__ when done. go.>",
+  complete_marker="__CLAWS_DONE__",
+  timeout_ms=600000
+)
+```
+After spawn, arm the per-worker Monitor using `monitor_arm_command` from the response. Wait for the Monitor notification. Then `claws_close` the terminal.
+
+**Bucket 3 — Independent parallel tasks**
+Signals: "run lint AND test AND typecheck", "audit modules A, B, C in parallel", explicit concurrency.
+Action:
+```
+claws_fleet(workers=[
+  {name:"worker-lint", mission:"...print MARK_LINT_OK when done. go."},
+  {name:"worker-test", mission:"...print MARK_TEST_OK when done. go."},
+], detach=true)
+```
+Arm one Monitor per `terminal_id` from the fleet response. Wait for all. Close all.
+
+**Bucket 4 — Coordinated multi-stage with sub-decomposition**
+Signals: "5-worker audit then synthesize", explicit "wave" or "army" terminology, N sub-workers + a coordinator.
+Action: spawn a LEAD via `claws_worker` whose mission uses `claws_wave_create` + `claws_dispatch_subworker` calls internally.
+
+## Hard rules
+
+- NEVER use the Bash tool to run the user's task — use `claws_exec` or `claws_worker`
+- NEVER manually sequence `claws_create` + `claws_send` to boot a Claude worker — `claws_worker` handles it
+- NEVER skip arming the Monitor after spawn — `monitor_arm_command` MUST be the very next
+  tool call after spawn; any intervening call is a sequencing bug
+- NEVER leave terminals open — auto-close on marker is the default
+- NEVER use raw socket node -e fallbacks — if MCP tools are absent, tell the user to reload VS Code
+
+## Examples
+```
+/claws-do run npm test
+/claws-do fix the failing test in auth.test.ts
+/claws-do run lint, test, and typecheck in parallel
+/claws-do launch a 4-worker audit wave with a LEAD
+```
+
+## When NOT to use
+For status, use /claws-status. For cleanup, use /claws-cleanup. For install issues, use /claws-fix.

package/.claude/commands/claws-fix.md

@@ -0,0 +1,40 @@
+---
+name: claws-fix
+description: Diagnose and auto-repair a broken Claws installation in one command.
+---
+
+## MANDATORY — read before running
+
+1. **Acknowledge in 1 line.** "Running Claws repair script." No more.
+2. **Do NOT enter plan mode.** This is a single Bash call.
+3. **Run the repair script via Bash — one call, no sub-steps. No worker spawn.**
+
+---
+
+# /claws-fix
+
+## What this does
+Runs `$CLAWS_DIR/scripts/fix.sh` which checks every piece of the install chain — extension bundle, editor symlink, `.mcp.json`, socket liveness, shell hooks — auto-repairs what it can, and reports what still needs a VS Code reload or Claude Code restart. All repair logic lives in the script so new checks activate on the next `git pull`.
+
+## Behavior
+- Run this single shell command:
+  ```bash
+  CLAWS_DIR="${CLAWS_DIR:-$HOME/.claws-src}"
+  bash "$CLAWS_DIR/scripts/fix.sh" "$(pwd)"
+  ```
+- Do not break into multiple steps — let the script's `[check] ✓ / → / ✗` output speak
+- If the script prints "All checks passed":
+  > Everything is wired up. Activate: (1) Reload VS Code, (2) Restart Claude Code in this project.
+- If the script reports unresolved issues:
+  > Some issues need manual attention. Run /claws-report to bundle diagnostics for a GitHub issue.
+
+## Examples
+```
+/claws-fix
+claws tools aren't showing up
+fix the claws installation
+```
+
+## When NOT to use
+If Claws is working but you want to update it, use /claws-update.
+If you need a shareable diagnostic file, use /claws-report.

package/.claude/commands/claws-goal.md

@@ -0,0 +1,111 @@
+---
+name: claws-goal
+description: Goal tracker (Codex / Claude Code agent loop pattern). Breaks a goal into subtasks, tracks progress, asks the user before destructive actions.
+---
+
+## MANDATORY cold-start sequence — execute in order, no deliberation
+
+1. **Acknowledge in 1 line.** "Goal received: <one-sentence summary>." No more.
+2. **Do NOT enter plan mode.** Classify immediately and create the root task.
+3. **Classify the goal** — one of: bug-fix, feature, refactor, release, audit, docs. State it in one sentence.
+4. **Create root task** — `TaskCreate` with the goal as title.
+5. **Decompose into 3–7 subtasks** — create each via `TaskCreate` with the root as parent.
+6. **Ask 0–2 clarifying questions** if scope is genuinely ambiguous, then begin the first subtask.
+
+Do not deliberate. Classify, decompose, begin.
+
+---
+
+# /claws-goal <goal description>
+
+## What this does
+Human-in-the-loop goal tracker. Breaks a high-level goal into 3–7 subtasks via `TaskCreate`, tracks completion via `TaskUpdate`, surfaces clarifying questions when blocked, and always asks the user before taking destructive actions. This is the human-checkpointed alternative to `/claws-auto`.
+
+See skill: `.claude/skills/claws-goal-tracker/SKILL.md` for breakdown heuristics and task-status protocol.
+
+## Behavior
+
+### Step 1 — Root task + decomposition
+```
+TaskCreate(title="<goal>", description="root goal", status="in_progress")
+TaskCreate(title="Subtask 1: ...", parent_id=<root>, status="pending")
+TaskCreate(title="Subtask 2: ...", parent_id=<root>, status="pending")
+...
+```
+Print the task tree to the user. Then ask 0–2 clarifying questions (if any). Then start Subtask 1.
+
+### Step 2 — Execute subtasks in order
+For each subtask:
+1. `TaskUpdate(id=<id>, status="in_progress")`
+2. Execute the work (read files, make edits, run `claws_exec` for shell ops)
+3. Verify: tests pass, no type errors after `.ts` edits
+4. `TaskUpdate(id=<id>, status="completed")`
+5. Report to user: "Subtask N done — <one-sentence summary>."
+6. Pause for user confirmation before proceeding if the subtask made destructive or user-visible changes (commits, file deletions, API calls)
+
+### Step 3 — Blocked subtask protocol
+If a subtask cannot proceed without information or a decision:
+1. `TaskUpdate(id=<id>, status="blocked", notes="<specific question>")`
+2. Surface the question to the user with context
+3. Wait for user answer before resuming
+
+### Step 4 — Goal completion
+When all subtasks are `completed`:
+1. `TaskUpdate(id=<root>, status="completed")`
+2. Print summary: "Goal complete. <N> subtasks done. What changed: ..."
+3. If commits were made, show `git log --oneline -N`
+
+## Clarifying questions — when and how many
+
+Ask clarifying questions ONLY when:
+- Scope genuinely cannot be inferred from the goal text + codebase
+- Two valid approaches exist with meaningfully different outcomes
+
+Never ask:
+- Questions answerable by reading the code
+- Questions about style, formatting, or conventions (follow existing patterns)
+- More than 2 questions at once
+
+Format: numbered list, each question in one sentence. After user answers, begin work immediately.
+
+## Destructive action gate
+
+Before any of these, stop and ask for explicit confirmation:
+- `git push --force` or `git reset --hard`
+- Deleting files that are not obviously temporary
+- Dropping or truncating data
+- Publishing to npm or VS Code Marketplace
+
+For non-destructive actions (edits, new files, commits to local branch), proceed without asking.
+
+## Hard rules
+
+- NEVER skip `TaskUpdate` — every subtask transitions `pending → in_progress → completed|blocked`
+- NEVER take destructive actions without user confirmation
+- NEVER exceed 7 subtasks — if the goal needs more, ask the user to break it into two goals
+- ALWAYS show the task tree before starting work
+- ALWAYS report completion of each subtask before moving to the next
+
+## Examples
+
+```
+/claws-goal add WebSocket transport to Claws (Phase 3)
+/claws-goal fix the 4 bugs in .local/blueprints/v0714-bug-tracker.md
+/claws-goal get the extension test suite to 100% green
+/claws-goal prepare Claws 0.8.0 for marketplace publish
+```
+
+## Difference from /claws-auto
+
+| `/claws-auto` | `/claws-goal` |
+|---------------|--------------|
+| Fully autonomous | Human-in-the-loop |
+| Asks user only when blocked | Reports after each subtask |
+| Wave-based dispatch | Sequential subtask execution |
+| Best for: long runs you walk away from | Best for: guided work you want to review |
+
+## When NOT to use
+
+For fully autonomous execution, use `/claws-auto`.
+For planning only (no execution), use `/claws-plan`.
+For a single task, use `/claws-do`.

package/.claude/commands/claws-help.md

@@ -0,0 +1,54 @@
+---
+name: claws-help
+description: Complete reference for Claws slash commands and MCP tools.
+---
+
+## MANDATORY — read before running
+
+1. **Acknowledge in 1 line.** No more.
+2. **Do NOT enter plan mode.** This command prints reference content, not spawns workers.
+3. **Do NOT pre-verify the sidecar, Monitor, or hooks.** Not needed here.
+
+---
+
+# /claws-help
+
+## What this does
+Prints the complete Claws command and tool reference. Use this when you want to know what's available and how to use it.
+
+## Commands (8 total)
+
+| Command | Description |
+|---|---|
+| `/claws` | Master: show live terminal dashboard or forward a task |
+| `/claws-do <task>` | Universal verb: classify and execute any task |
+| `/claws-help` | This reference |
+| `/claws-status` | Dashboard of active terminals with lifecycle state |
+| `/claws-cleanup` | Close all worker terminals after a fleet run |
+| `/claws-update` | Pull latest Claws and re-run installer |
+| `/claws-fix` | Diagnose and auto-repair a broken installation |
+| `/claws-report` | Bundle diagnostics into a shareable bug report |
+
+## MCP Tools (available via tool use)
+
+| Tool | Description |
+|---|---|
+| `claws_worker` | Spawn a single Claude Code worker with auto-boot |
+| `claws_fleet` | Spawn N parallel workers; returns terminal_ids immediately |
+| `claws_dispatch_subworker` | Dispatch a sub-worker from within a Wave LEAD |
+| `claws_exec` | Run a one-shot shell command; returns output + exitCode |
+| `claws_list` | List all active terminals |
+| `claws_create` | Create a terminal (wrapped or unwrapped) |
+| `claws_send` | Send text into a terminal |
+| `claws_read_log` | Read pty log from a wrapped terminal |
+| `claws_close` | Close a terminal |
+| `claws_drain_events` | Block-wait for pub/sub events (use in LEAD workers) |
+| `claws_lifecycle_plan` | Log a lifecycle plan (required gate before create) |
+
+## User mental model
+
+**5 daily commands**: `/claws-do` for tasks, `/claws` for status, `/claws-status` for details, `/claws-cleanup` after fleet runs, `/claws-help` when lost.
+
+**3 system commands**: `/claws-update` to update, `/claws-fix` when broken, `/claws-report` to file a bug.
+
+**Power users**: call MCP tools directly. Claws is just terminals over a Unix socket — bend it however you want.

package/.claude/commands/claws-plan.md

@@ -0,0 +1,103 @@
+---
+name: claws-plan
+description: Context engineering for a user's task. Reads relevant code, audits dependencies, identifies risks, produces a structured plan doc.
+---
+
+## MANDATORY cold-start sequence — execute in order, no deliberation
+
+1. **Acknowledge in 1 line.** "Planning: <one-sentence task summary>." No more.
+2. **Do NOT enter plan mode.** Output is a structured text plan, not an interactive plan session.
+3. **Do NOT dispatch workers.** Planning only — zero action taken. Reading files and writing one plan doc is the entire job.
+4. **Do NOT call TodoWrite.** This command produces one output: a `.local/plans/<slug>-<date>.md` file.
+5. **Read before proposing.** Every referenced file must be read before it appears in the plan. No speculation.
+
+---
+
+# /claws-plan <task description>
+
+## What this does
+Context engineering: reads the codebase relevant to the user's task, audits dependencies and risks, then writes a structured plan document to `.local/plans/<slug>-YYYY-MM-DD.md`. The plan is the deliverable — no code is written, no workers are spawned.
+
+## Behavior
+
+### Step 1 — Classify the task
+Determine scope from the task description:
+- What files are likely touched? (search for symbols, filenames, or patterns the task mentions)
+- What features/modules are involved?
+- Is this a bug fix, a new feature, a refactor, a release task, or an audit?
+
+### Step 2 — Clarify if needed
+If the scope is ambiguous, ask 1–3 targeted clarifying questions before proceeding. Questions must be specific and actionable:
+- "Which transport layer — Unix socket or WebSocket?"
+- "Should this change the install.sh path, the VS Code extension, or both?"
+- Do NOT ask vague questions like "Can you tell me more?"
+Cap at 3 questions. If scope is clear, skip to Step 3.
+
+### Step 3 — Read relevant code
+Read every file likely touched by the task. For each file:
+- Identify the relevant functions, classes, or blocks (cite `file.ts:line`)
+- Note existing patterns the plan must match
+- Flag anything that looks like a dependency on another module
+
+### Step 4 — Write the plan doc
+Output to `.local/plans/<slug>-<date>.md` with these sections:
+
+```markdown
+# Plan: <task description>
+**Date**: YYYY-MM-DD  **Status**: DRAFT
+
+## Objective
+One paragraph: what success looks like.
+
+## Scope
+Files and modules in scope. Files explicitly out of scope.
+
+## Phased steps
+### Phase 1 — <name>
+- [ ] Step (file.ts:line — what changes and why)
+
+### Phase 2 — <name>
+...
+
+## Risk register
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|-----------|
+| ...  | ...        | ...    | ...       |
+
+## Dependencies
+- External: npm packages, VS Code APIs used
+- Internal: modules that must not break
+
+## Test plan
+- [ ] Unit test: <what>
+- [ ] Integration test: <what>
+- [ ] Manual smoke: <what>
+
+## Open questions
+- [ ] <question that needs user or codebase answer before phase N>
+```
+
+### Step 5 — Surface to user
+Print the plan (inline in chat) and note where the file was saved. End with: "Run `/claws-do '<task>'` or `/claws-auto '<task>'` to execute."
+
+## Hard rules
+
+- NEVER propose a change without first reading the relevant file
+- ALWAYS cite `file:line` for every referenced function or pattern
+- NEVER over-engineer — if 1 file change solves it, don't propose 5
+- NEVER create worker terminals — this command is read-only + write-one-file
+- If the `.local/plans/` directory does not exist, create it silently
+
+## Examples
+
+```
+/claws-plan add a --quiet flag to claws_exec that suppresses pty echo
+/claws-plan fix the autoclose regression from commit e960601
+/claws-plan design the WebSocket transport for Phase 3
+/claws-plan audit why workers miss __CLAWS_DONE__ on Windows
+```
+
+## When NOT to use
+
+To execute a plan, use `/claws-auto` (autonomous) or `/claws-do` (single action).
+To track a multi-step goal with human checkpoints, use `/claws-goal`.

package/.claude/commands/claws-report.md

@@ -0,0 +1,29 @@
+---
+name: claws-report
+description: Bundle logs and diagnostics into a shareable file for bug reports.
+---
+
+# /claws-report
+
+## What this does
+Runs `scripts/report.sh` which captures OS info, Claws source state, extension state, socket status, MCP handshake test, shell hook state, recent install logs, and VS Code extension host logs — all into a single redacted text file you can attach to a GitHub issue.
+
+## Behavior
+- Run from the project root where the issue is occurring:
+  ```bash
+  bash ~/.claws-src/scripts/report.sh "$(pwd)"
+  ```
+- The file path is printed at the top of the output (e.g. `~/claws-report-<timestamp>.txt`)
+- The report redacts `$HOME` paths and strips 32+ character tokens — review before sharing
+- Tell the user the file path and offer to help write a GitHub issue title
+
+## Examples
+```
+/claws-report
+generate a diagnostic report
+something is broken — help me file a bug
+```
+
+## When NOT to use
+If Claws is not installed at all, nothing to report — point to the install docs.
+If the issue is just an outdated version, use /claws-update first.

package/.claude/commands/claws-status.md

@@ -0,0 +1,37 @@
+---
+name: claws-status
+description: Show a live dashboard of all active Claws terminals and their lifecycle state.
+---
+
+## MANDATORY — read before running
+
+1. **Acknowledge in 1 line.** No more.
+2. **Do NOT enter plan mode.** This command prints reference content, not spawns workers.
+3. **Do NOT pre-verify the sidecar, Monitor, or hooks.** Not needed here.
+
+---
+
+# /claws-status
+
+## What this does
+Calls `claws_list` and formats all active terminals as a readable table. Optionally reads `.claws/lifecycle-state.json` to add a lifecycle status column. Quick health check before starting orchestration work.
+
+## Behavior
+- Call `claws_list` to get all terminals
+- Read `.claws/lifecycle-state.json` if it exists (best-effort, ignore if missing)
+- Format as a table with columns: ID | Name | Wrapped | Age | Lifecycle State
+- Report total counts: N terminals, N wrapped
+- If no terminals: "No active terminals. Claws is connected and idle."
+- If socket absent: "Claws socket not found. Reload VS Code to activate."
+
+## Examples
+```
+/claws-status
+what terminals are open?
+show me the terminal dashboard
+```
+
+## When NOT to use
+To run a task or spawn a worker, use /claws-do.
+To close terminals, use /claws-cleanup.
+To diagnose a broken install, use /claws-fix.

package/.claude/commands/claws-update.md

@@ -0,0 +1,32 @@
+---
+name: claws-update
+description: Update Claws to the latest version by running the upstream update script.
+---
+
+# /claws-update
+
+## What this does
+Pulls the latest Claws source and re-runs the installer. All update logic lives in `$CLAWS_DIR/scripts/update.sh` — new migration steps added to that script activate automatically without re-installing this command.
+
+## Behavior
+- Run this single shell command (do not break into steps):
+  ```bash
+  CLAWS_DIR="${CLAWS_DIR:-$HOME/.claws-src}"
+  bash "$CLAWS_DIR/scripts/update.sh" "$(pwd)"
+  ```
+- Let the script print its own status — do not interleave commentary
+- After the script finishes, tell the user exactly:
+  > Update complete. Two things to activate:
+  > 1. Reload VS Code — Cmd+Shift+P → Developer: Reload Window
+  > 2. Restart Claude Code in this project so the new `.mcp.json` is picked up.
+
+## Examples
+```
+/claws-update
+update claws to the latest version
+pull the newest claws
+```
+
+## When NOT to use
+If MCP tools are missing (not just outdated), use /claws-fix first.
+If you want a full diagnostic bundle, use /claws-report.