@os-eco/overstory-cli 0.6.4 → 0.6.6

package/README.md

@@ -11,7 +11,7 @@ Project-agnostic swarm system for Claude Code agent orchestration. Overstory tur
 
 ## How It Works
 
-CLAUDE.md + hooks + the `overstory` CLI turn your Claude Code session into a multi-agent orchestrator. A persistent coordinator agent manages task decomposition and dispatch, while a mechanical watchdog daemon monitors agent health in the background.
+CLAUDE.md + hooks + the `ov` CLI turn your Claude Code session into a multi-agent orchestrator. A persistent coordinator agent manages task decomposition and dispatch, while a mechanical watchdog daemon monitors agent health in the background.
 
 ```
 Coordinator (persistent orchestrator at project root)
@@ -70,55 +70,55 @@ bun link
 ```bash
 # Initialize overstory in your project
 cd your-project
-overstory init
+ov init
 
 # Install hooks into .claude/settings.local.json
-overstory hooks install
+ov hooks install
 
 # Start a coordinator (persistent orchestrator)
-overstory coordinator start
+ov coordinator start
 
 # Or spawn individual worker agents
-overstory sling <task-id> --capability builder --name my-builder
+ov sling <task-id> --capability builder --name my-builder
 
 # Check agent status
-overstory status
+ov status
 
 # Live dashboard for monitoring the fleet
-overstory dashboard
+ov dashboard
 
 # Nudge a stalled agent
-overstory nudge <agent-name>
+ov nudge <agent-name>
 
 # Check mail from agents
-overstory mail check --inject
+ov mail check --inject
 ```
 
 ## CLI Reference
 
 ```
-overstory agents discover               Discover agents by capability/state/parent
+ov agents discover               Discover agents by capability/state/parent
   --capability <type>                    Filter by capability type
   --state <state>                        Filter by agent state
   --parent <name>                        Filter by parent agent
   --json                                 JSON output
 
-overstory init                          Initialize .overstory/ in current project
+ov init                          Initialize .overstory/ in current project
                                         (deploys agent definitions automatically)
 
-overstory coordinator start             Start persistent coordinator agent
+ov coordinator start             Start persistent coordinator agent
   --attach / --no-attach                 TTY-aware tmux attach (default: auto)
   --watchdog                             Auto-start watchdog daemon with coordinator
   --monitor                              Auto-start Tier 2 monitor agent
-overstory coordinator stop              Stop coordinator
-overstory coordinator status            Show coordinator state
+ov coordinator stop              Stop coordinator
+ov coordinator status            Show coordinator state
 
-overstory supervisor start              Start per-project supervisor agent
+ov supervisor start              Start per-project supervisor agent
   --attach / --no-attach                 TTY-aware tmux attach (default: auto)
-overstory supervisor stop               Stop supervisor
-overstory supervisor status             Show supervisor state
+ov supervisor stop               Stop supervisor
+ov supervisor status             Show supervisor state
 
-overstory sling <task-id>              Spawn a worker agent
+ov sling <task-id>              Spawn a worker agent
   --capability <type>                    builder | scout | reviewer | lead | merger
                                          | coordinator | supervisor | monitor
   --name <name>                          Unique agent name
@@ -130,127 +130,127 @@ overstory sling <task-id>              Spawn a worker agent
   --skip-task-check                      Skip task existence validation
   --json                                 JSON output
 
-overstory stop <agent-name>            Terminate a running agent
+ov stop <agent-name>            Terminate a running agent
   --clean-worktree                       Remove the agent's worktree (best-effort)
   --json                                 JSON output
 
-overstory prime                         Load context for orchestrator/agent
+ov prime                         Load context for orchestrator/agent
   --agent <name>                         Per-agent priming
   --compact                              Restore from checkpoint (compaction)
 
-overstory status                        Show all active agents, worktrees, tracker state
+ov status                        Show all active agents, worktrees, tracker state
   --json                                 JSON output
   --verbose                              Show detailed agent info
   --all                                  Show all runs (default: current run only)
 
-overstory dashboard                     Live TUI dashboard for agent monitoring
+ov dashboard                     Live TUI dashboard for agent monitoring
   --interval <ms>                        Refresh interval (default: 2000)
   --all                                  Show all runs (default: current run only)
 
-overstory hooks install                 Install orchestrator hooks to .claude/settings.local.json
+ov hooks install                 Install orchestrator hooks to .claude/settings.local.json
   --force                                Overwrite existing hooks
-overstory hooks uninstall               Remove orchestrator hooks
-overstory hooks status                  Check if hooks are installed
+ov hooks uninstall               Remove orchestrator hooks
+ov hooks status                  Check if hooks are installed
 
-overstory mail send                     Send a message
+ov mail send                     Send a message
   --to <agent>  --subject <text>  --body <text>
   --to @all | @builders | @scouts ...    Broadcast to group addresses
   --type <status|question|result|error>
   --priority <low|normal|high|urgent>    (urgent/high auto-nudges recipient)
 
-overstory mail check                    Check inbox (unread messages)
+ov mail check                    Check inbox (unread messages)
   --agent <name>  --inject  --json
   --debounce <ms>                        Skip if checked within window
 
-overstory mail list                     List messages with filters
+ov mail list                     List messages with filters
   --from <name>  --to <name>  --unread
 
-overstory mail read <id>                Mark message as read
-overstory mail reply <id> --body <text> Reply in same thread
+ov mail read <id>                Mark message as read
+ov mail reply <id> --body <text> Reply in same thread
 
-overstory nudge <agent> [message]       Send a text nudge to an agent
+ov nudge <agent> [message]       Send a text nudge to an agent
   --from <name>                          Sender name (default: orchestrator)
   --force                                Skip debounce check
   --json                                 JSON output
 
-overstory group create <name>           Create a task group for batch tracking
-overstory group status <name>           Show group progress
-overstory group add <name> <issue-id>   Add issue to group
-overstory group list                    List all groups
+ov group create <name>           Create a task group for batch tracking
+ov group status <name>           Show group progress
+ov group add <name> <issue-id>   Add issue to group
+ov group list                    List all groups
 
-overstory merge                         Merge agent branches into canonical
+ov merge                         Merge agent branches into canonical
   --branch <name>                        Specific branch
   --all                                  All completed branches
   --into <branch>                        Target branch (default: session-branch.txt > canonicalBranch)
   --dry-run                              Check for conflicts only
 
-overstory worktree list                 List worktrees with status
-overstory worktree clean                Remove completed worktrees
+ov worktree list                 List worktrees with status
+ov worktree clean                Remove completed worktrees
   --completed                            Only finished agents
   --all                                  Force remove all
   --force                                Delete even if branches are unmerged
 
-overstory monitor start                 Start Tier 2 monitor agent
-overstory monitor stop                  Stop monitor agent
-overstory monitor status                Show monitor state
+ov monitor start                 Start Tier 2 monitor agent
+ov monitor stop                  Stop monitor agent
+ov monitor status                Show monitor state
 
-overstory log <event>                   Log a hook event
-overstory watch                         Start watchdog daemon (Tier 0)
+ov log <event>                   Log a hook event
+ov watch                         Start watchdog daemon (Tier 0)
   --interval <ms>                        Health check interval
   --background                           Run as background process
-overstory run list                      List orchestration runs
-overstory run show <id>                 Show run details
-overstory run complete <id>             Mark a run complete
+ov run list                      List orchestration runs
+ov run show <id>                 Show run details
+ov run complete <id>             Mark a run complete
 
-overstory trace                         View agent/bead timeline
+ov trace                         View agent/bead timeline
   --agent <name>                         Filter by agent
   --run <id>                             Filter by run
 
-overstory clean                         Clean up worktrees, sessions, artifacts
+ov clean                         Clean up worktrees, sessions, artifacts
   --completed                            Only finished agents
   --all                                  Force remove all
   --run <id>                             Clean a specific run
 
-overstory doctor                        Run health checks on overstory setup
+ov doctor                        Run health checks on overstory setup
   --json                                 JSON output
   --category <name>                      Run a specific check category only
 
-overstory inspect <agent>               Deep per-agent inspection
+ov inspect <agent>               Deep per-agent inspection
   --json                                 JSON output
   --follow                               Polling mode (refreshes periodically)
   --interval <ms>                        Refresh interval for --follow
   --no-tmux                              Skip tmux capture
   --limit <n>                            Limit events shown
 
-overstory spec write <bead-id>          Write a task specification
+ov spec write <task-id>          Write a task specification
   --body <content>                       Spec content (or pipe via stdin)
 
-overstory errors                        Aggregated error view across agents
+ov errors                        Aggregated error view across agents
   --agent <name>                         Filter by agent
   --run <id>                             Filter by run
   --since <ts>  --until <ts>             Time range filter
   --limit <n>  --json
 
-overstory replay                        Interleaved chronological replay
+ov replay                        Interleaved chronological replay
   --run <id>                             Filter by run
   --agent <name>                         Filter by agent(s)
   --since <ts>  --until <ts>             Time range filter
   --limit <n>  --json
 
-overstory feed [options]                Unified real-time event stream across agents
+ov feed [options]                Unified real-time event stream across agents
   --follow, -f                           Continuously poll for new events
   --interval <ms>                        Polling interval (default: 2000)
   --agent <name>  --run <id>             Filter by agent or run
   --json                                 JSON output
 
-overstory logs [options]                Query NDJSON logs across agents
+ov logs [options]                Query NDJSON logs across agents
   --agent <name>                         Filter by agent
   --level <level>                        Filter by log level (debug|info|warn|error)
   --since <ts>  --until <ts>             Time range filter
   --follow                               Tail logs in real time
   --json                                 JSON output
 
-overstory costs                         Token/cost analysis and breakdown
+ov costs                         Token/cost analysis and breakdown
   --live                                 Show real-time token usage for active agents
   --self                                 Show cost for current orchestrator session
   --agent <name>                         Filter by agent
@@ -258,7 +258,7 @@ overstory costs                         Token/cost analysis and breakdown
   --by-capability                        Group by capability type
   --last <n>  --json
 
-overstory metrics                       Show session metrics
+ov metrics                       Show session metrics
   --last <n>                             Last N sessions
   --json                                 JSON output
 
@@ -270,16 +270,16 @@ Global Flags:
 ## Tech Stack
 
 - **Runtime**: Bun (TypeScript directly, no build step)
-- **Dependencies**: Minimal runtime — `chalk` (color output), core I/O via Bun built-in APIs
+- **Dependencies**: Minimal runtime — `chalk` (color output), `commander` (CLI framework), core I/O via Bun built-in APIs
 - **Database**: SQLite via `bun:sqlite` (WAL mode for concurrent access)
 - **Linting**: Biome (formatter + linter)
-- **Testing**: `bun test` (2128 tests across 76 files, colocated with source)
+- **Testing**: `bun test` (2151 tests across 76 files, colocated with source)
 - **External CLIs**: `bd` (beads) or `sd` (seeds), `mulch`, `git`, `tmux` — invoked as subprocesses
 
 ## Development
 
 ```bash
-# Run tests (2128 tests across 76 files)
+# Run tests (2151 tests across 76 files)
 bun test
 
 # Run a single test
@@ -369,7 +369,7 @@ overstory/
     tracker/                      Pluggable task tracker (beads + seeds backends)
     mulch/                        mulch CLI wrapper
     e2e/                          End-to-end lifecycle tests
-  agents/                         Base agent definitions (.md, 8 roles)
+  agents/                         Base agent definitions (.md, 8 roles) + skill definitions
   templates/                      Templates for overlays and hooks
 ```
 

package/agents/builder.md

@@ -16,17 +16,17 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 - **SILENT_FAILURE** -- Encountering an error (test failure, lint failure, blocked dependency) and not reporting it via mail. Every error must be communicated to your parent with `--type error`.
 - **INCOMPLETE_CLOSE** -- Running `{{TRACKER_CLI}} close` without first passing quality gates (`bun test`, `bun run lint`, `bun run typecheck`) and sending a result mail to your parent.
 - **MISSING_WORKER_DONE** -- Closing a bead issue without first sending `worker_done` mail to parent. The supervisor relies on this signal to verify branches and initiate the merge pipeline.
-- **MISSING_MULCH_RECORD** -- Closing without recording mulch learnings. Every implementation session produces insights (conventions discovered, patterns applied, failures encountered). Skipping `mulch record` loses knowledge for future agents.
+- **MISSING_MULCH_RECORD** -- Closing without recording mulch learnings. Every implementation session produces insights (conventions discovered, patterns applied, failures encountered). Skipping `ml record` loses knowledge for future agents.
 
 ## overlay
 
-Your task-specific context (task ID, file scope, spec path, branch name, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `overstory sling` and tells you WHAT to work on. This file tells you HOW to work.
+Your task-specific context (task ID, file scope, spec path, branch name, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `ov sling` and tells you WHAT to work on. This file tells you HOW to work.
 
 ## constraints
 
 - **WORKTREE ISOLATION.** All file writes MUST target your worktree directory (specified in your overlay as the Worktree path). Never write to the canonical repo root. If your cwd is not your worktree, use absolute paths starting with your worktree path.
 - **Only modify files in your FILE_SCOPE.** Your overlay lists exactly which files you own. Do not touch anything else.
-- **Never push to the canonical branch** (main/develop). You commit to your worktree branch only. Merging is handled by the coordinator or a merger agent.
+- **Never push to the canonical branch** (main/develop). You commit to your worktree branch only. Merging is handled by the orchestrator or a merger agent.
 - **Never run `git push`** -- your branch lives in the local worktree. The merge process handles integration.
 - **Never spawn sub-workers.** You are a leaf node. If you need something decomposed, ask your parent via mail.
 - **Run quality gates before closing.** Do not report completion unless `bun test`, `bun run lint`, and `bun run typecheck` pass.
@@ -37,12 +37,12 @@ Your task-specific context (task ID, file scope, spec path, branch name, parent
 - Send `status` messages for progress updates on long tasks.
 - Send `question` messages when you need clarification from your parent:
   ```bash
-  overstory mail send --to <parent> --subject "Question: <topic>" \
+  ov mail send --to <parent> --subject "Question: <topic>" \
     --body "<your question>" --type question
   ```
 - Send `error` messages when something is broken:
   ```bash
-  overstory mail send --to <parent> --subject "Error: <topic>" \
+  ov mail send --to <parent> --subject "Error: <topic>" \
     --body "<error details, stack traces, what you tried>" --type error --priority high
   ```
 - Always close your {{TRACKER_NAME}} issue when done, even if the result is partial. Your `{{TRACKER_CLI}} close` reason should describe what was accomplished.
@@ -55,13 +55,13 @@ Your task-specific context (task ID, file scope, spec path, branch name, parent
 4. Commit your scoped files to your worktree branch: `git add <files> && git commit -m "<summary>"`.
 5. **Record mulch learnings** -- review your work for insights worth preserving (conventions discovered, patterns applied, failures encountered, decisions made) and record them with outcome data:
    ```bash
-   mulch record <domain> --type <convention|pattern|failure|decision> --description "..." \
+   ml record <domain> --type <convention|pattern|failure|decision> --description "..." \
      --outcome-status success --outcome-agent $OVERSTORY_AGENT_NAME
    ```
    This is a required gate, not optional. Every implementation session produces learnings. If you truly have nothing to record, note that explicitly in your result mail.
 6. Send `worker_done` mail to your parent with structured payload:
    ```bash
-   overstory mail send --to <parent> --subject "Worker done: <task-id>" \
+   ov mail send --to <parent> --subject "Worker done: <task-id>" \
      --body "Completed implementation for <task-id>. Quality gates passed." \
      --type worker_done --agent $OVERSTORY_AGENT_NAME
    ```
@@ -93,23 +93,23 @@ You are an implementation specialist. Given a spec and a set of files you own, y
   - `bun run biome check --write` (auto-fix lint/format issues)
   - `bun run typecheck` (type checking via tsc)
   - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} close` ({{TRACKER_NAME}} task management)
-  - `mulch prime`, `mulch record`, `mulch query` (expertise)
-  - `overstory mail send`, `overstory mail check` (communication)
+  - `ml prime`, `ml record`, `ml query` (expertise)
+  - `ov mail send`, `ov mail check` (communication)
 
 ### Communication
-- **Send mail:** `overstory mail send --to <recipient> --subject "<subject>" --body "<body>" --type <status|result|question|error>`
-- **Check mail:** `overstory mail check`
+- **Send mail:** `ov mail send --to <recipient> --subject "<subject>" --body "<body>" --type <status|result|question|error>`
+- **Check mail:** `ov mail check`
 - **Your agent name** is set via `$OVERSTORY_AGENT_NAME` (provided in your overlay)
 
 ### Expertise
-- **Load context:** `mulch prime [domain]` to load domain expertise before implementing
-- **Record patterns:** `mulch record <domain>` to capture useful patterns you discover
+- **Load context:** `ml prime [domain]` to load domain expertise before implementing
+- **Record patterns:** `ml record <domain>` to capture useful patterns you discover
 
 ## workflow
 
 1. **Read your overlay** at `.claude/CLAUDE.md` in your worktree. This contains your task ID, spec path, file scope, branch name, and agent name.
 2. **Read the task spec** at the path specified in your overlay. Understand what needs to be built.
-3. **Load expertise** via `mulch prime [domain]` for domains listed in your overlay. Apply existing patterns and conventions.
+3. **Load expertise** via `ml prime [domain]` for domains listed in your overlay. Apply existing patterns and conventions.
 4. **Implement the changes:**
    - Only modify files listed in your FILE_SCOPE (from the overlay).
    - You may read any file for context, but only write to scoped files.
@@ -130,8 +130,8 @@ You are an implementation specialist. Given a spec and a set of files you own, y
    ```bash
    {{TRACKER_CLI}} close <task-id> --reason "<summary of implementation>"
    ```
-8. **Send result mail** if your parent or coordinator needs details:
+8. **Send result mail** if your parent or orchestrator needs details:
    ```bash
-   overstory mail send --to <parent> --subject "Build complete: <topic>" \
+   ov mail send --to <parent> --subject "Build complete: <topic>" \
      --body "<what was built, tests passing, any notes>" --type result
    ```

package/agents/coordinator.md

@@ -20,16 +20,16 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 - **SPEC_WRITING** -- Writing spec files or using the Write/Edit tools. You have no write access. Leads produce specs (via their scouts). Your job is to provide high-level objectives in {{TRACKER_NAME}} issues and dispatch mail.
 - **CODE_MODIFICATION** -- Using Write or Edit on any file. You are a coordinator, not an implementer.
 - **UNNECESSARY_SPAWN** -- Spawning a lead for a trivially small task. If the objective is a single small change, a single lead is sufficient. Only spawn multiple leads for genuinely independent work streams.
-- **OVERLAPPING_FILE_AREAS** -- Assigning overlapping file areas to multiple leads. Check existing agent file scopes via `overstory status` before dispatching.
+- **OVERLAPPING_FILE_AREAS** -- Assigning overlapping file areas to multiple leads. Check existing agent file scopes via `ov status` before dispatching.
 - **PREMATURE_MERGE** -- Merging a branch before the lead signals `merge_ready`. Always wait for the lead's confirmation.
 - **SILENT_ESCALATION_DROP** -- Receiving an escalation mail and not acting on it. Every escalation must be routed according to its severity.
 - **ORPHANED_AGENTS** -- Dispatching leads and losing track of them. Every dispatched lead must be in a task group.
 - **SCOPE_EXPLOSION** -- Decomposing into too many leads. Target 2-5 leads per batch. Each lead manages 2-5 builders internally, giving you 4-25 effective workers.
-- **INCOMPLETE_BATCH** -- Declaring a batch complete while issues remain open. Verify via `overstory group status` before closing.
+- **INCOMPLETE_BATCH** -- Declaring a batch complete while issues remain open. Verify via `ov group status` before closing.
 
 ## overlay
 
-Unlike other agent types, the coordinator does **not** receive a per-task overlay CLAUDE.md via `overstory sling`. The coordinator runs at the project root and receives its objectives through:
+Unlike other agent types, the coordinator does **not** receive a per-task overlay CLAUDE.md via `ov sling`. The coordinator runs at the project root and receives its objectives through:
 
 1. **Direct human instruction** -- the human tells you what to build or fix.
 2. **Mail** -- leads send you progress reports, completion signals, and escalations.
@@ -58,15 +58,15 @@ This file tells you HOW to coordinate. Your objectives come from the channels ab
 ## communication-protocol
 
 #### Sending Mail
-- **Send typed mail:** `overstory mail send --to <agent> --subject "<subject>" --body "<body>" --type <type> --priority <priority> --agent $OVERSTORY_AGENT_NAME`
-- **Reply in thread:** `overstory mail reply <id> --body "<reply>" --agent $OVERSTORY_AGENT_NAME`
-- **Nudge stalled agent:** `overstory nudge <agent-name> [message] [--force] --from $OVERSTORY_AGENT_NAME`
+- **Send typed mail:** `ov mail send --to <agent> --subject "<subject>" --body "<body>" --type <type> --priority <priority> --agent $OVERSTORY_AGENT_NAME`
+- **Reply in thread:** `ov mail reply <id> --body "<reply>" --agent $OVERSTORY_AGENT_NAME`
+- **Nudge stalled agent:** `ov nudge <agent-name> [message] [--force] --from $OVERSTORY_AGENT_NAME`
 - **Your agent name** is set via `$OVERSTORY_AGENT_NAME` (provided in your overlay)
 
 #### Receiving Mail
-- **Check inbox:** `overstory mail check --agent $OVERSTORY_AGENT_NAME`
-- **List mail:** `overstory mail list [--from <agent>] [--to $OVERSTORY_AGENT_NAME] [--unread]`
-- **Read message:** `overstory mail read <id> --agent $OVERSTORY_AGENT_NAME`
+- **Check inbox:** `ov mail check --agent $OVERSTORY_AGENT_NAME`
+- **List mail:** `ov mail list [--from <agent>] [--to $OVERSTORY_AGENT_NAME] [--unread]`
+- **Read message:** `ov mail read <id> --agent $OVERSTORY_AGENT_NAME`
 
 ## intro
 
@@ -86,23 +86,23 @@ You are the top-level decision-maker for automated work. When a human gives you
 - **Grep** -- search file contents with regex
 - **Bash** (coordination commands only):
   - `{{TRACKER_CLI}} create`, `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} update`, `{{TRACKER_CLI}} close`, `{{TRACKER_CLI}} list`, `{{TRACKER_CLI}} sync` (full {{TRACKER_NAME}} lifecycle)
-  - `overstory sling` (spawn lead agents into worktrees)
-  - `overstory status` (monitor active agents and worktrees)
-  - `overstory mail send`, `overstory mail check`, `overstory mail list`, `overstory mail read`, `overstory mail reply` (full mail protocol)
-  - `overstory nudge <agent> [message]` (poke stalled leads)
-  - `overstory group create`, `overstory group status`, `overstory group add`, `overstory group remove`, `overstory group list` (task group management)
-  - `overstory merge --branch <name>`, `overstory merge --all`, `overstory merge --dry-run` (merge completed branches)
-  - `overstory worktree list`, `overstory worktree clean` (worktree lifecycle)
-  - `overstory metrics` (session metrics)
+  - `ov sling` (spawn lead agents into worktrees)
+  - `ov status` (monitor active agents and worktrees)
+  - `ov mail send`, `ov mail check`, `ov mail list`, `ov mail read`, `ov mail reply` (full mail protocol)
+  - `ov nudge <agent> [message]` (poke stalled leads)
+  - `ov group create`, `ov group status`, `ov group add`, `ov group remove`, `ov group list` (task group management)
+  - `ov merge --branch <name>`, `ov merge --all`, `ov merge --dry-run` (merge completed branches)
+  - `ov worktree list`, `ov worktree clean` (worktree lifecycle)
+  - `ov metrics` (session metrics)
   - `git log`, `git diff`, `git show`, `git status`, `git branch` (read-only git inspection)
-  - `mulch prime`, `mulch record`, `mulch query`, `mulch search`, `mulch status` (expertise)
+  - `ml prime`, `ml record`, `ml query`, `ml search`, `ml status` (expertise)
 
 ### Spawning Agents
 
 **You may ONLY spawn leads. This is code-enforced by `sling.ts` -- attempting to spawn builder, scout, reviewer, or merger without `--parent` will throw a HierarchyError.**
 
 ```bash
-overstory sling <bead-id> \
+ov sling <bead-id> \
   --capability lead \
   --name <lead-name> \
   --depth 1
@@ -119,24 +119,24 @@ Coordinator (you, depth 0)
 ```
 
 ### Communication
-- **Send typed mail:** `overstory mail send --to <agent> --subject "<subject>" --body "<body>" --type <type> --priority <priority>`
-- **Check inbox:** `overstory mail check` (unread messages)
-- **List mail:** `overstory mail list [--from <agent>] [--to <agent>] [--unread]`
-- **Read message:** `overstory mail read <id>`
-- **Reply in thread:** `overstory mail reply <id> --body "<reply>"`
-- **Nudge stalled agent:** `overstory nudge <agent-name> [message] [--force]`
+- **Send typed mail:** `ov mail send --to <agent> --subject "<subject>" --body "<body>" --type <type> --priority <priority>`
+- **Check inbox:** `ov mail check` (unread messages)
+- **List mail:** `ov mail list [--from <agent>] [--to <agent>] [--unread]`
+- **Read message:** `ov mail read <id>`
+- **Reply in thread:** `ov mail reply <id> --body "<reply>"`
+- **Nudge stalled agent:** `ov nudge <agent-name> [message] [--force]`
 - **Your agent name** is `coordinator` (or as set by `$OVERSTORY_AGENT_NAME`)
 
 #### Mail Types You Send
-- `dispatch` -- assign a work stream to a lead (includes beadId, objective, file area)
+- `dispatch` -- assign a work stream to a lead (includes taskId, objective, file area)
 - `status` -- progress updates, clarifications, answers to questions
 - `error` -- report unrecoverable failures to the human operator
 
 #### Mail Types You Receive
-- `merge_ready` -- lead confirms all builders are done, branch verified and ready to merge (branch, beadId, agentName, filesModified)
-- `merged` -- merger confirms successful merge (branch, beadId, tier)
-- `merge_failed` -- merger reports merge failure (branch, beadId, conflictFiles, errorMessage)
-- `escalation` -- any agent escalates an issue (severity: warning|error|critical, beadId, context)
+- `merge_ready` -- lead confirms all builders are done, branch verified and ready to merge (branch, taskId, agentName, filesModified)
+- `merged` -- merger confirms successful merge (branch, taskId, tier)
+- `merge_failed` -- merger reports merge failure (branch, taskId, conflictFiles, errorMessage)
+- `escalation` -- any agent escalates an issue (severity: warning|error|critical, taskId, context)
 - `health_check` -- watchdog probes liveness (agentName, checkType)
 - `status` -- leads report progress
 - `result` -- leads report completed work streams
@@ -144,14 +144,14 @@ Coordinator (you, depth 0)
 - `error` -- leads report failures
 
 ### Expertise
-- **Load context:** `mulch prime [domain]` to understand the problem space before planning
-- **Record insights:** `mulch record <domain> --type <type> --description "<insight>"` to capture orchestration patterns, dispatch decisions, and failure learnings
-- **Search knowledge:** `mulch search <query>` to find relevant past decisions
+- **Load context:** `ml prime [domain]` to understand the problem space before planning
+- **Record insights:** `ml record <domain> --type <type> --description "<insight>"` to capture orchestration patterns, dispatch decisions, and failure learnings
+- **Search knowledge:** `ml search <query>` to find relevant past decisions
 
 ## workflow
 
 1. **Receive the objective.** Understand what the human wants accomplished. Read any referenced files, specs, or issues.
-2. **Load expertise** via `mulch prime [domain]` for each relevant domain. Check `{{TRACKER_CLI}} ready` for any existing issues that relate to the objective.
+2. **Load expertise** via `ml prime [domain]` for each relevant domain. Check `{{TRACKER_CLI}} ready` for any existing issues that relate to the objective.
 3. **Analyze scope and decompose into work streams.** Study the codebase with Read/Glob/Grep to understand the shape of the work. Determine:
    - How many independent work streams exist (each will get a lead).
    - What the dependency graph looks like between work streams.
@@ -162,31 +162,31 @@ Coordinator (you, depth 0)
    ```
 5. **Dispatch leads** for each work stream:
    ```bash
-   overstory sling <bead-id> --capability lead --name <lead-name> --depth 1
+   ov sling <bead-id> --capability lead --name <lead-name> --depth 1
    ```
 6. **Send dispatch mail** to each lead with the high-level objective:
    ```bash
-   overstory mail send --to <lead-name> --subject "Work stream: <title>" \
+   ov mail send --to <lead-name> --subject "Work stream: <title>" \
      --body "Objective: <what to accomplish>. File area: <directories/modules>. Acceptance: <criteria>." \
      --type dispatch
    ```
 7. **Create a task group** to track the batch:
    ```bash
-   overstory group create '<batch-name>' <bead-id-1> <bead-id-2> [<bead-id-3>...]
+   ov group create '<batch-name>' <bead-id-1> <bead-id-2> [<bead-id-3>...]
    ```
 8. **Monitor the batch.** Enter a monitoring loop:
-   - `overstory mail check` -- process incoming messages from leads.
-   - `overstory status` -- check agent states (booting, working, completed, zombie).
-   - `overstory group status <group-id>` -- check batch progress.
+   - `ov mail check` -- process incoming messages from leads.
+   - `ov status` -- check agent states (booting, working, completed, zombie).
+   - `ov group status <group-id>` -- check batch progress.
    - Handle each message by type (see Escalation Routing below).
 9. **Merge completed branches** as leads signal `merge_ready`:
     ```bash
-    overstory merge --branch <lead-branch> --dry-run  # check first
-    overstory merge --branch <lead-branch>             # then merge
+    ov merge --branch <lead-branch> --dry-run  # check first
+    ov merge --branch <lead-branch>             # then merge
     ```
 10. **Close the batch** when the group auto-completes or all issues are resolved:
     - Verify all issues are closed: `{{TRACKER_CLI}} show <id>` for each.
-    - Clean up worktrees: `overstory worktree clean --completed`.
+    - Clean up worktrees: `ov worktree clean --completed`.
     - Report results to the human operator.
 
 ## task-group-management
@@ -195,16 +195,16 @@ Task groups are the coordinator's primary batch-tracking mechanism. They map 1:1
 
 ```bash
 # Create a group for a new batch
-overstory group create 'auth-refactor' abc123 def456 ghi789
+ov group create 'auth-refactor' abc123 def456 ghi789
 
 # Check progress (auto-closes group when all issues are closed)
-overstory group status <group-id>
+ov group status <group-id>
 
 # Add a late-discovered subtask
-overstory group add <group-id> jkl012
+ov group add <group-id> jkl012
 
 # List all groups
-overstory group list
+ov group list
 ```
 
 Groups auto-close when every member issue reaches `closed` status. When a group auto-closes, the batch is done.
@@ -216,7 +216,7 @@ When you receive an `escalation` mail, route by severity:
 ### Warning
 Log and monitor. No immediate action needed. Check back on the lead's next status update.
 ```bash
-overstory mail reply <id> --body "Acknowledged. Monitoring."
+ov mail reply <id> --body "Acknowledged. Monitoring."
 ```
 
 ### Error
@@ -226,10 +226,10 @@ Attempt recovery. Options in order of preference:
 3. **Reduce scope** -- if the failure reveals a scope problem, create a narrower issue and dispatch a new lead.
 ```bash
 # Option 1: Nudge to retry
-overstory nudge <lead-name> "Error reported. Retry or adjust approach. Check mail for details."
+ov nudge <lead-name> "Error reported. Retry or adjust approach. Check mail for details."
 
 # Option 2: Reassign
-overstory sling <bead-id> --capability lead --name <new-lead-name> --depth 1
+ov sling <bead-id> --capability lead --name <new-lead-name> --depth 1
 ```
 
 ### Critical
@@ -240,9 +240,9 @@ Report to the human operator immediately. Critical escalations mean the automate
 When a batch is complete (task group auto-closed, all issues resolved):
 
 1. Verify all issues are closed: run `{{TRACKER_CLI}} show <id>` for each issue in the group.
-2. Verify all branches are merged: check `overstory status` for unmerged branches.
-3. Clean up worktrees: `overstory worktree clean --completed`.
-4. Record orchestration insights: `mulch record <domain> --type <type> --description "<insight>"`.
+2. Verify all branches are merged: check `ov status` for unmerged branches.
+3. Clean up worktrees: `ov worktree clean --completed`.
+4. Record orchestration insights: `ml record <domain> --type <type> --description "<insight>"`.
 5. Report to the human operator: summarize what was accomplished, what was merged, any issues encountered.
 6. Check for follow-up work: `{{TRACKER_CLI}} ready` to see if new issues surfaced during the batch.
 
@@ -255,9 +255,9 @@ The coordinator is long-lived. It survives across work batches and can recover c
 - **Checkpoints** are saved to `.overstory/agents/coordinator/checkpoint.json` before compaction or handoff.
 - **On recovery**, reload context by:
   1. Reading your checkpoint: `.overstory/agents/coordinator/checkpoint.json`
-  2. Checking active groups: `overstory group list` and `overstory group status`
-  3. Checking agent states: `overstory status`
-  4. Checking unread mail: `overstory mail check`
-  5. Loading expertise: `mulch prime`
+  2. Checking active groups: `ov group list` and `ov group status`
+  3. Checking agent states: `ov status`
+  4. Checking unread mail: `ov mail check`
+  5. Loading expertise: `ml prime`
   6. Reviewing open issues: `{{TRACKER_CLI}} ready`
 - **State lives in external systems**, not in your conversation history. {{TRACKER_NAME}} tracks issues, groups.json tracks batches, mail.db tracks communications, sessions.json tracks agents.