@os-eco/overstory-cli 0.6.10 → 0.7.0

package/README.md

@@ -1,68 +1,40 @@
 # Overstory
 
-[![CI](https://img.shields.io/github/actions/workflow/status/jayminwest/overstory/ci.yml?branch=main)](https://github.com/jayminwest/overstory/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
-[![GitHub release](https://img.shields.io/github/v/release/jayminwest/overstory)](https://github.com/jayminwest/overstory/releases)
+Multi-agent orchestration for Claude Code.
 
-Project-agnostic swarm system for Claude Code agent orchestration. Overstory turns a single Claude Code session into a multi-agent team by spawning worker agents in git worktrees via tmux, coordinating them through a custom SQLite mail system, and merging their work back with tiered conflict resolution.
+[![npm](https://img.shields.io/npm/v/@os-eco/overstory-cli)](https://www.npmjs.com/package/@os-eco/overstory-cli)
+[![CI](https://github.com/jayminwest/overstory/actions/workflows/ci.yml/badge.svg)](https://github.com/jayminwest/overstory/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-> **⚠️ Warning: Agent swarms are not a universal solution.** Do not deploy Overstory without understanding the risks of multi-agent orchestration — compounding error rates, cost amplification, debugging complexity, and merge conflicts are the normal case, not edge cases. Read [STEELMAN.md](STEELMAN.md) for a full risk analysis and the [Agentic Engineering Book](https://github.com/jayminwest/agentic-engineering-book) ([web version](https://jayminwest.com/agentic-engineering-book)) before using this tool in production.
+Overstory turns a single Claude Code session into a multi-agent team by spawning worker agents in git worktrees via tmux, coordinating them through a custom SQLite mail system, and merging their work back with tiered conflict resolution.
 
-## How It Works
-
-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)
-  --> Supervisor (per-project team lead, depth 1)
-        --> Workers: Scout, Builder, Reviewer, Merger (depth 2)
-```
-
-### Agent Types
+> **Warning: Agent swarms are not a universal solution.** Do not deploy Overstory without understanding the risks of multi-agent orchestration — compounding error rates, cost amplification, debugging complexity, and merge conflicts are the normal case, not edge cases. Read [STEELMAN.md](STEELMAN.md) for a full risk analysis and the [Agentic Engineering Book](https://github.com/jayminwest/agentic-engineering-book) ([web version](https://jayminwest.com/agentic-engineering-book)) before using this tool in production.
 
-| Agent | Role | Access |
-|-------|------|--------|
-| **Coordinator** | Persistent orchestrator — decomposes objectives, dispatches agents, tracks task groups | Read-only |
-| **Supervisor** | Per-project team lead — manages worker lifecycle, handles nudge/escalation | Read-only |
-| **Scout** | Read-only exploration and research | Read-only |
-| **Builder** | Implementation and code changes | Read-write |
-| **Reviewer** | Validation and code review | Read-only |
-| **Lead** | Team coordination, can spawn sub-workers | Read-write |
-| **Merger** | Branch merge specialist | Read-write |
-| **Monitor** | Tier 2 continuous fleet patrol — ongoing health monitoring | Read-only |
+## Install
 
-### Key Architecture
+Requires [Bun](https://bun.sh) v1.0+, [Claude Code](https://docs.anthropic.com/en/docs/claude-code), git, and tmux.
 
-- **Agent Definitions**: Two-layer system — base `.md` files define the HOW (workflow), per-task overlays define the WHAT (task scope). Base definition content is injected into spawned agent overlays automatically.
-- **Messaging**: Custom SQLite mail system with typed protocol — 8 message types (`worker_done`, `merge_ready`, `dispatch`, `escalation`, etc.) for structured agent coordination, plus broadcast messaging with group addresses (`@all`, `@builders`, etc.)
-- **Worktrees**: Each agent gets an isolated git worktree — no file conflicts between agents
-- **Merge**: FIFO merge queue (SQLite-backed) with 4-tier conflict resolution
-- **Watchdog**: Tiered health monitoring — Tier 0 mechanical daemon (tmux/pid liveness), Tier 1 AI-assisted failure triage, Tier 2 monitor agent for continuous fleet patrol
-- **Tool Enforcement**: PreToolUse hooks mechanically block file modifications for non-implementation agents and dangerous git operations for all agents
-- **Task Groups**: Batch coordination with auto-close when all member issues complete
-- **Session Lifecycle**: Checkpoint save/restore for compaction survivability, handoff orchestration for crash recovery
-- **Token Instrumentation**: Session metrics extracted from Claude Code transcript JSONL files
+```bash
+bun install -g @os-eco/overstory-cli
+```
 
-## Requirements
+Or try without installing:
 
-- [Bun](https://bun.sh) (v1.0+)
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
-- git
-- tmux
+```bash
+npx @os-eco/overstory-cli --help
+```
 
-## Installation
+### Development
 
 ```bash
-# Clone the repository
 git clone https://github.com/jayminwest/overstory.git
 cd overstory
-
-# Install dev dependencies
 bun install
+bun link              # Makes 'ov' available globally
 
-# Link the CLI globally
-bun link
+bun test              # Run all tests
+bun run lint          # Biome check
+bun run typecheck     # tsc --noEmit
 ```
 
 ## Quick Start
@@ -94,233 +66,134 @@ ov nudge <agent-name>
 ov mail check --inject
 ```
 
-## CLI Reference
-
-```
-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
-
-ov init                          Initialize .overstory/ in current project
-                                        (deploys agent definitions automatically)
-  --yes, -y                              Skip interactive prompts
-  --name <name>                          Set project name (default: auto-detect)
-
-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
-ov coordinator stop              Stop coordinator
-ov coordinator status            Show coordinator state
-
-ov supervisor start              Start per-project supervisor agent
-  --attach / --no-attach                 TTY-aware tmux attach (default: auto)
-ov supervisor stop               Stop supervisor
-ov supervisor status             Show supervisor state
-
-ov sling <task-id>              Spawn a worker agent
-  --capability <type>                    builder | scout | reviewer | lead | merger
-                                         | coordinator | supervisor | monitor
-  --name <name>                          Unique agent name
-  --spec <path>                          Path to task spec file
-  --files <f1,f2,...>                    Exclusive file scope
-  --parent <agent-name>                  Parent (for hierarchy tracking)
-  --depth <n>                            Current hierarchy depth
-  --skip-scout                           Skip scout phase (passed to lead overlay)
-  --skip-task-check                      Skip task existence validation
-  --json                                 JSON output
-
-ov stop <agent-name>            Terminate a running agent
-  --clean-worktree                       Remove the agent's worktree (best-effort)
-  --json                                 JSON output
-
-ov prime                         Load context for orchestrator/agent
-  --agent <name>                         Per-agent priming
-  --compact                              Restore from checkpoint (compaction)
-
-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)
-
-ov dashboard                     Live TUI dashboard for agent monitoring
-  --interval <ms>                        Refresh interval (default: 2000)
-  --all                                  Show all runs (default: current run only)
-
-ov hooks install                 Install orchestrator hooks to .claude/settings.local.json
-  --force                                Overwrite existing hooks
-ov hooks uninstall               Remove orchestrator hooks
-ov hooks status                  Check if hooks are installed
-
-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)
-
-ov mail check                    Check inbox (unread messages)
-  --agent <name>  --inject  --json
-  --debounce <ms>                        Skip if checked within window
-
-ov mail list                     List messages with filters
-  --from <name>  --to <name>  --unread
-
-ov mail read <id>                Mark message as read
-ov mail reply <id> --body <text> Reply in same thread
-
-ov nudge <agent> [message]       Send a text nudge to an agent
-  --from <name>                          Sender name (default: orchestrator)
-  --force                                Skip debounce check
-  --json                                 JSON output
-
-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
-
-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
-
-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
-
-ov monitor start                 Start Tier 2 monitor agent
-ov monitor stop                  Stop monitor agent
-ov monitor status                Show monitor state
-
-ov log <event>                   Log a hook event
-ov watch                         Start watchdog daemon (Tier 0)
-  --interval <ms>                        Health check interval
-  --background                           Run as background process
-ov run list                      List orchestration runs
-ov run show <id>                 Show run details
-ov run complete <id>             Mark a run complete
-
-ov trace                         View agent/bead timeline
-  --agent <name>                         Filter by agent
-  --run <id>                             Filter by run
-
-ov clean                         Clean up worktrees, sessions, artifacts
-  --completed                            Only finished agents
-  --all                                  Force remove all
-  --run <id>                             Clean a specific run
-
-ov doctor                        Run health checks on overstory setup
-  --json                                 JSON output
-  --category <name>                      Run a specific check category only
-  --fix                                  Auto-fix fixable issues
-
-ov ecosystem                     Show os-eco tool versions and health
-  --json                                 JSON output
-
-ov upgrade                       Upgrade overstory to latest npm version
-  --check                                Compare versions without installing
-  --all                                  Upgrade all 4 ecosystem tools
-  --json                                 JSON output
-
-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
-
-ov spec write <task-id>          Write a task specification
-  --body <content>                       Spec content (or pipe via stdin)
-
-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
-
-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
-
-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
-
-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
-
-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
-  --run <id>                             Filter by run
-  --by-capability                        Group by capability type
-  --last <n>  --json
-
-ov metrics                       Show session metrics
-  --last <n>                             Last N sessions
-  --json                                 JSON output
-
-Global Flags:
-  --quiet, -q                            Suppress non-error output
-  --timing                               Print command execution time to stderr
-  --completions <shell>                  Generate shell completions (bash, zsh, fish)
-```
-
-## Tech Stack
-
-- **Runtime**: Bun (TypeScript directly, no build step)
-- **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` (2241 tests across 79 files, colocated with source)
-- **External CLIs**: `bd` (beads) or `sd` (seeds), `mulch`, `git`, `tmux` — invoked as subprocesses
-
-## Development
+## Commands
+
+Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--timing`. ANSI colors respect `NO_COLOR`.
+
+### Core Workflow
+
+| Command | Description |
+|---------|-------------|
+| `ov init` | Initialize `.overstory/` in current project (`--yes`, `--name`) |
+| `ov sling <task-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--runtime`, `--json`) |
+| `ov stop <agent-name>` | Terminate a running agent (`--clean-worktree`, `--json`) |
+| `ov prime` | Load context for orchestrator/agent (`--agent`, `--compact`) |
+| `ov spec write <task-id>` | Write a task specification (`--body`) |
+
+### Coordination
+
+| Command | Description |
+|---------|-------------|
+| `ov coordinator start` | Start persistent coordinator agent (`--attach`/`--no-attach`, `--watchdog`, `--monitor`) |
+| `ov coordinator stop` | Stop coordinator |
+| `ov coordinator status` | Show coordinator state |
+| `ov supervisor start` | Start per-project supervisor agent (`--attach`/`--no-attach`) |
+| `ov supervisor stop` | Stop supervisor |
+| `ov supervisor status` | Show supervisor state |
+
+### Messaging
+
+| Command | Description |
+|---------|-------------|
+| `ov mail send` | Send a message (`--to`, `--subject`, `--body`, `--type`, `--priority`) |
+| `ov mail check` | Check inbox — unread messages (`--agent`, `--inject`, `--debounce`, `--json`) |
+| `ov mail list` | List messages with filters (`--from`, `--to`, `--unread`) |
+| `ov mail read <id>` | Mark message as read |
+| `ov mail reply <id>` | Reply in same thread (`--body`) |
+| `ov nudge <agent> [message]` | Send a text nudge to an agent (`--from`, `--force`, `--json`) |
+
+### Task Groups
+
+| Command | Description |
+|---------|-------------|
+| `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 |
+
+### Merge
+
+| Command | Description |
+|---------|-------------|
+| `ov merge` | Merge agent branches into canonical (`--branch`, `--all`, `--into`, `--dry-run`, `--json`) |
+
+### Observability
+
+| Command | Description |
+|---------|-------------|
+| `ov status` | Show all active agents, worktrees, tracker state (`--json`, `--verbose`, `--all`) |
+| `ov dashboard` | Live TUI dashboard for agent monitoring (`--interval`, `--all`) |
+| `ov inspect <agent>` | Deep per-agent inspection (`--follow`, `--interval`, `--no-tmux`, `--limit`, `--json`) |
+| `ov trace` | View agent/task timeline (`--agent`, `--run`, `--since`, `--until`, `--limit`, `--json`) |
+| `ov errors` | Aggregated error view across agents (`--agent`, `--run`, `--since`, `--until`, `--limit`, `--json`) |
+| `ov replay` | Interleaved chronological replay (`--run`, `--agent`, `--since`, `--until`, `--limit`, `--json`) |
+| `ov feed` | Unified real-time event stream (`--follow`, `--interval`, `--agent`, `--run`, `--json`) |
+| `ov logs` | Query NDJSON logs across agents (`--agent`, `--level`, `--since`, `--until`, `--follow`, `--json`) |
+| `ov costs` | Token/cost analysis and breakdown (`--live`, `--self`, `--agent`, `--run`, `--by-capability`, `--last`, `--json`) |
+| `ov metrics` | Show session metrics (`--last`, `--json`) |
+| `ov run list` | List orchestration runs (`--last`, `--json`) |
+| `ov run show <id>` | Show run details |
+| `ov run complete` | Mark current run as completed |
+
+### Infrastructure
+
+| Command | Description |
+|---------|-------------|
+| `ov hooks install` | Install orchestrator hooks to `.claude/settings.local.json` (`--force`) |
+| `ov hooks uninstall` | Remove orchestrator hooks |
+| `ov hooks status` | Check if hooks are installed |
+| `ov worktree list` | List worktrees with status |
+| `ov worktree clean` | Remove completed worktrees (`--completed`, `--all`, `--force`) |
+| `ov watch` | Start watchdog daemon — Tier 0 (`--interval`, `--background`) |
+| `ov monitor start` | Start Tier 2 monitor agent |
+| `ov monitor stop` | Stop monitor agent |
+| `ov monitor status` | Show monitor state |
+| `ov log <event>` | Log a hook event (`--agent`) |
+| `ov clean` | Clean up worktrees, sessions, artifacts (`--completed`, `--all`, `--run`) |
+| `ov doctor` | Run health checks on overstory setup (`--category`, `--fix`, `--json`) |
+| `ov ecosystem` | Show os-eco tool versions and health (`--json`) |
+| `ov upgrade` | Upgrade overstory to latest npm version (`--check`, `--all`, `--json`) |
+| `ov agents discover` | Discover agents by capability/state/parent (`--capability`, `--state`, `--parent`, `--json`) |
+| `ov completions <shell>` | Generate shell completions (bash, zsh, fish) |
+
+## Architecture
+
+Overstory uses CLAUDE.md overlays and PreToolUse hooks to turn Claude Code sessions into orchestrated agents. Each agent runs in an isolated git worktree via tmux. Inter-agent messaging is handled by a custom SQLite mail system (WAL mode, ~1-5ms per query) with typed protocol messages and broadcast support. A FIFO merge queue with 4-tier conflict resolution merges agent branches back to canonical. A tiered watchdog system (Tier 0 mechanical daemon, Tier 1 AI-assisted triage, Tier 2 monitor agent) ensures fleet health. See [CLAUDE.md](CLAUDE.md) for full technical details.
 
-```bash
-# Run tests (2241 tests across 79 files)
-bun test
-
-# Run a single test
-bun test src/config.test.ts
-
-# Lint + format check
-biome check .
+## How It Works
 
-# Type check
-tsc --noEmit
+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.
 
-# All quality gates
-bun test && biome check . && tsc --noEmit
+```
+Coordinator (persistent orchestrator at project root)
+  --> Supervisor (per-project team lead, depth 1)
+        --> Workers: Scout, Builder, Reviewer, Merger (depth 2)
 ```
 
-### Versioning
-
-Version is maintained in two places that must stay in sync:
-
-1. `package.json` — `"version"` field
-2. `src/index.ts` — `VERSION` constant
+### Agent Types
 
-Use the bump script to update both:
+| Agent | Role | Access |
+|-------|------|--------|
+| **Coordinator** | Persistent orchestrator — decomposes objectives, dispatches agents, tracks task groups | Read-only |
+| **Supervisor** | Per-project team lead — manages worker lifecycle, handles nudge/escalation | Read-only |
+| **Scout** | Read-only exploration and research | Read-only |
+| **Builder** | Implementation and code changes | Read-write |
+| **Reviewer** | Validation and code review | Read-only |
+| **Lead** | Team coordination, can spawn sub-workers | Read-write |
+| **Merger** | Branch merge specialist | Read-write |
+| **Monitor** | Tier 2 continuous fleet patrol — ongoing health monitoring | Read-only |
 
-```bash
-bun run version:bump <major|minor|patch>
-```
+### Key Architecture
 
-Git tags, npm publishing, and GitHub releases are handled automatically by the `publish.yml` workflow when a version bump is pushed to `main`.
+- **Agent Definitions**: Two-layer system — base `.md` files define the HOW (workflow), per-task overlays define the WHAT (task scope). Base definition content is injected into spawned agent overlays automatically.
+- **Messaging**: Custom SQLite mail system with typed protocol — 8 message types (`worker_done`, `merge_ready`, `dispatch`, `escalation`, etc.) for structured agent coordination, plus broadcast messaging with group addresses (`@all`, `@builders`, etc.)
+- **Worktrees**: Each agent gets an isolated git worktree — no file conflicts between agents
+- **Merge**: FIFO merge queue (SQLite-backed) with 4-tier conflict resolution
+- **Watchdog**: Tiered health monitoring — Tier 0 mechanical daemon (tmux/pid liveness), Tier 1 AI-assisted failure triage, Tier 2 monitor agent for continuous fleet patrol
+- **Tool Enforcement**: PreToolUse hooks mechanically block file modifications for non-implementation agents and dangerous git operations for all agents
+- **Task Groups**: Batch coordination with auto-close when all member issues complete
+- **Session Lifecycle**: Checkpoint save/restore for compaction survivability, handoff orchestration for crash recovery
+- **Token Instrumentation**: Session metrics extracted from Claude Code transcript JSONL files
 
 ## Project Structure
 
@@ -353,7 +226,7 @@ overstory/
       logs.ts                     NDJSON log query
       feed.ts                     Unified real-time event stream
       run.ts                      Orchestration run lifecycle
-      trace.ts                    Agent/bead timeline viewing
+      trace.ts                    Agent/task timeline viewing
       clean.ts                    Worktree/session cleanup
       doctor.ts                   Health check runner (10 check modules)
       inspect.ts                  Deep per-agent inspection
@@ -377,21 +250,30 @@ overstory/
     mail/                         SQLite mail system (typed protocol, broadcast)
     merge/                        FIFO queue + conflict resolution
     watchdog/                     Tiered health monitoring (daemon, triage, health)
-    logging/                      Multi-format logger + sanitizer + reporter + color control
+    logging/                      Multi-format logger + sanitizer + reporter + color control + shared theme/format
     metrics/                      SQLite metrics + transcript parsing
     doctor/                       Health check modules (10 checks)
     insights/                     Session insight analyzer for auto-expertise
+    runtimes/                     AgentRuntime abstraction (registry + adapters)
     tracker/                      Pluggable task tracker (beads + seeds backends)
-    mulch/                        mulch CLI wrapper
+    mulch/                        mulch client (programmatic API + CLI wrapper)
     e2e/                          End-to-end lifecycle tests
   agents/                         Base agent definitions (.md, 8 roles) + skill definitions
   templates/                      Templates for overlays and hooks
 ```
 
-## License
+## Part of os-eco
 
-MIT
+Overstory is part of the [os-eco](https://github.com/jayminwest/os-eco) AI agent tooling ecosystem.
 
----
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jayminwest/os-eco/main/branding/logo.png" alt="os-eco" width="444" />
+</p>
 
-Inspired by: https://github.com/steveyegge/gastown/
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT

package/agents/lead.md

@@ -1,6 +1,15 @@
 ## propulsion-principle
 
-Read your assignment. Assess complexity. For simple tasks, start implementing immediately. For moderate tasks, write a spec and spawn a builder. For complex tasks, spawn scouts and create issues. Do not ask for confirmation, do not propose a plan and wait for approval. Start working within your first tool calls.
+Read your assignment. Assess complexity. For simple tasks, start implementing immediately. For moderate tasks, write a spec and spawn a builder. For complex tasks, spawn scouts and mail the coordinator to create issues. Do not ask for confirmation, do not propose a plan and wait for approval. Start working within your first tool calls.
+
+## dispatch-overrides
+
+Your overlay may contain a **Dispatch Overrides** section with directives from your coordinator. These override the default workflow:
+
+- **SKIP REVIEW**: Do not spawn a reviewer. Self-verify by reading the builder diff and running quality gates. This is appropriate for simple or well-tested changes.
+- **MAX AGENTS**: Limits the number of sub-workers you may spawn. Plan your decomposition to fit within this budget.
+
+Always check your overlay for dispatch overrides before following the default three-phase workflow. If no overrides section exists, follow the standard playbook.
 
 ## cost-awareness
 
@@ -30,6 +39,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 - **INCOMPLETE_CLOSE** -- Running `{{TRACKER_CLI}} close` before all subtasks are complete or accounted for, or without sending `merge_ready` to the coordinator.
 - **REVIEW_SKIP** -- Sending `merge_ready` for complex tasks without independent review. For complex multi-file changes, always spawn a reviewer. For simple/moderate tasks, self-verification (reading the diff + quality gates) is acceptable.
 - **MISSING_MULCH_RECORD** -- Closing without recording mulch learnings. Every lead session produces orchestration insights (decomposition strategies, coordination patterns, failures encountered). Skipping `ml record` loses knowledge for future agents.
+- **WORKTREE_ISSUE_CREATE** -- Running `{{TRACKER_CLI}} create` in a worktree. Issues created on worktree branches are lost when worktrees are cleaned up. Mail the coordinator to create issues on main instead.
 
 ## overlay
 
@@ -46,6 +56,7 @@ Your task-specific context (task ID, spec path, hierarchy depth, agent name, whe
 - **Never push to the canonical branch.** Commit to your worktree branch. Merging is handled by the coordinator.
 - **Do not spawn more workers than needed.** Start with the minimum. You can always spawn more later. Target 2-5 builders per lead.
 - **Review before merge for complex tasks.** For simple/moderate tasks, the lead may self-verify by reading the diff and running quality gates.
+- **Never create issues in worktrees.** Running `{{TRACKER_CLI}} create` in a worktree creates issues on the worktree branch, which are lost on cleanup. If you need to file a follow-up issue, mail the coordinator with the issue details (title, type, priority, description) and the coordinator will create it on main.
 
 ## communication-protocol
 
@@ -53,6 +64,9 @@ Your task-specific context (task ID, spec path, hierarchy depth, agent name, whe
 - **To your workers:** Send `status` messages with clarifications or answers to their questions.
 - **Monitoring cadence:** Check mail and `ov status` regularly, especially after spawning workers.
 - When escalating to the coordinator, include: what failed, what you tried, what you need.
+- **Requesting issue creation:** When you discover follow-up work that needs tracking, mail the coordinator:
+  `ov mail send --to coordinator --subject "create-issue: <title>" --body "type: <task|bug>, priority: <1-4>, description: <details>" --type status`
+  The coordinator will create the issue on main and may reply with the issue ID.
 
 ## intro
 
@@ -75,7 +89,7 @@ You are primarily a coordinator, but you can also be a doer for simple tasks. Yo
 - **Bash:**
   - `git add`, `git commit`, `git diff`, `git log`, `git status`
 {{QUALITY_GATE_CAPABILITIES}}
-  - `{{TRACKER_CLI}} create`, `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} close`, `{{TRACKER_CLI}} update` (full {{TRACKER_NAME}} management)
+  - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} close`, `{{TRACKER_CLI}} update` ({{TRACKER_NAME}} management — read, update, close)
   - `{{TRACKER_CLI}} sync` (sync {{TRACKER_NAME}} with git)
   - `ml prime`, `ml record`, `ml query`, `ml search` (expertise)
   - `ov sling` (spawn sub-workers)
@@ -155,8 +169,8 @@ Delegate exploration to scouts so you can focus on decomposition and planning.
 
    Single scout example:
    ```bash
-   {{TRACKER_CLI}} create --title="Scout: explore <area> for <objective>" --type=task --priority=2
-   ov sling <scout-bead-id> --capability scout --name <scout-name> \
+   ov sling <parent-task-id> --capability scout --name <scout-name> \
+     --skip-task-check \
      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
    ov mail send --to <scout-name> --subject "Explore: <area>" \
      --body "Investigate <what to explore>. Report: file layout, existing patterns, types, dependencies." \
@@ -166,16 +180,16 @@ Delegate exploration to scouts so you can focus on decomposition and planning.
    Parallel scouts example:
    ```bash
    # Scout 1: implementation files
-   {{TRACKER_CLI}} create --title="Scout: explore implementation for <objective>" --type=task --priority=2
-   ov sling <scout1-bead-id> --capability scout --name <scout1-name> \
+   ov sling <parent-task-id> --capability scout --name <scout1-name> \
+     --skip-task-check \
      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
    ov mail send --to <scout1-name> --subject "Explore: implementation" \
      --body "Investigate implementation files: <files>. Report: patterns, types, dependencies." \
      --type dispatch
 
    # Scout 2: tests and interfaces
-   {{TRACKER_CLI}} create --title="Scout: explore tests/types for <objective>" --type=task --priority=2
-   ov sling <scout2-bead-id> --capability scout --name <scout2-name> \
+   ov sling <parent-task-id> --capability scout --name <scout2-name> \
+     --skip-task-check \
      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
    ov mail send --to <scout2-name> --subject "Explore: tests and interfaces" \
      --body "Investigate test files and type definitions: <files>. Report: test patterns, type contracts." \
@@ -195,17 +209,14 @@ Write specs from scout findings and dispatch builders.
    - File scope (which files the builder owns -- non-overlapping)
    - Context (relevant types, interfaces, existing patterns from scout findings)
    - Dependencies (what must be true before this work starts)
-7. **Create {{TRACKER_NAME}} issues** for each subtask:
-   ```bash
-   {{TRACKER_CLI}} create --title="<subtask title>" --priority=P1 --desc="<spec summary>"
-   ```
-8. **Spawn builders** for parallel tasks:
+7. **Spawn builders** for parallel tasks:
    ```bash
-   ov sling <bead-id> --capability builder --name <builder-name> \
+   ov sling <parent-task-id> --capability builder --name <builder-name> \
      --spec .overstory/specs/<bead-id>.md --files <scoped-files> \
+     --skip-task-check \
      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
    ```
-9. **Send dispatch mail** to each builder:
+8. **Send dispatch mail** to each builder:
    ```bash
    ov mail send --to <builder-name> --subject "Build: <task>" \
      --body "Spec: .overstory/specs/<bead-id>.md. Begin immediately." --type dispatch
@@ -239,10 +250,9 @@ Review is a quality investment. For complex, multi-file changes, spawn a reviewe
 
     To spawn a reviewer:
     ```bash
-    {{TRACKER_CLI}} create --title="Review: <builder-task-summary>" --type=task --priority=P1
-    ov sling <review-bead-id> --capability reviewer --name review-<builder-name> \
-      --spec .overstory/specs/<builder-bead-id>.md --parent $OVERSTORY_AGENT_NAME \
-      --depth <current+1>
+    ov sling <parent-task-id> --capability reviewer --name review-<builder-name> \
+      --spec .overstory/specs/<builder-bead-id>.md --skip-task-check \
+      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
     ov mail send --to review-<builder-name> \
       --subject "Review: <builder-task>" \
       --body "Review the changes on branch <builder-branch>. Spec: .overstory/specs/<builder-bead-id>.md. Run quality gates and report PASS or FAIL." \