@os-eco/overstory-cli 0.6.9 → 0.6.11

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,223 +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
-
-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
-  --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` (2186 tests across 77 files, colocated with source)
-- **External CLIs**: `bd` (beads) or `sd` (seeds), `mulch`, `git`, `tmux` — invoked as subprocesses
+## 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`, `--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.
 
-## Development
-
-```bash
-# Run tests (2186 tests across 77 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
 
@@ -322,7 +205,7 @@ overstory/
     config.ts                     Config loader + validation
     errors.ts                     Custom error types
     json.ts                       Standardized JSON envelope helpers
-    commands/                     One file per CLI subcommand (30 commands)
+    commands/                     One file per CLI subcommand (32 commands)
       agents.ts                   Agent discovery and querying
       coordinator.ts              Persistent orchestrator lifecycle
       supervisor.ts               Team lead management
@@ -343,9 +226,9 @@ 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 (9 check modules)
+      doctor.ts                   Health check runner (10 check modules)
       inspect.ts                  Deep per-agent inspection
       spec.ts                     Task spec management
       errors.ts                   Aggregated error view
@@ -353,6 +236,8 @@ overstory/
       stop.ts                     Agent termination
       costs.ts                    Token/cost analysis
       metrics.ts                  Session metrics
+      ecosystem.ts                os-eco tool dashboard
+      upgrade.ts                  npm version upgrades
       completions.ts              Shell completion generation (bash/zsh/fish)
     agents/                       Agent lifecycle management
       manifest.ts                 Agent registry (load + query)
@@ -367,7 +252,7 @@ overstory/
     watchdog/                     Tiered health monitoring (daemon, triage, health)
     logging/                      Multi-format logger + sanitizer + reporter + color control
     metrics/                      SQLite metrics + transcript parsing
-    doctor/                       Health check modules (9 checks)
+    doctor/                       Health check modules (10 checks)
     insights/                     Session insight analyzer for auto-expertise
     tracker/                      Pluggable task tracker (beads + seeds backends)
     mulch/                        mulch CLI wrapper
@@ -376,10 +261,21 @@ overstory/
   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.
+
+```
+▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  overstory   orchestration
+▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  canopy      prompts
+▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  seeds       issues
+▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  mulch       expertise
+```
+
+## Contributing
 
----
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
-Inspired by: https://github.com/steveyegge/gastown/
+## License
+
+MIT

package/agents/builder.md

@@ -14,8 +14,8 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 - **FILE_SCOPE_VIOLATION** -- Editing or writing to a file not listed in your FILE_SCOPE. Read any file for context, but only modify scoped files.
 - **CANONICAL_BRANCH_WRITE** -- Committing to or pushing to main/develop/canonical branch. You commit to your worktree branch only.
 - **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.
+- **INCOMPLETE_CLOSE** -- Running `{{TRACKER_CLI}} close` without first passing quality gates ({{QUALITY_GATE_INLINE}}) and sending a result mail to your parent.
+- **MISSING_WORKER_DONE** -- Closing a {{TRACKER_NAME}} 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 `ml record` loses knowledge for future agents.
 
 ## overlay
@@ -29,7 +29,7 @@ Your task-specific context (task ID, file scope, spec path, branch name, parent
 - **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.
+- **Run quality gates before closing.** Do not report completion unless {{QUALITY_GATE_INLINE}} pass.
 - If tests fail, fix them. If you cannot fix them, report the failure via mail with `--type error`.
 
 ## communication-protocol
@@ -49,9 +49,7 @@ Your task-specific context (task ID, file scope, spec path, branch name, parent
 
 ## completion-protocol
 
-1. Run `bun test` -- all tests must pass.
-2. Run `bun run lint` -- lint and formatting must be clean.
-3. Run `bun run typecheck` -- no TypeScript errors.
+{{QUALITY_GATE_STEPS}}
 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
@@ -88,10 +86,7 @@ You are an implementation specialist. Given a spec and a set of files you own, y
 - **Grep** -- search file contents with regex
 - **Bash:**
   - `git add`, `git commit`, `git diff`, `git log`, `git status`
-  - `bun test` (run tests)
-  - `bun run lint` (lint and format check via biome)
-  - `bun run biome check --write` (auto-fix lint/format issues)
-  - `bun run typecheck` (type checking via tsc)
+{{QUALITY_GATE_CAPABILITIES}}
   - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} close` ({{TRACKER_NAME}} task management)
   - `ml prime`, `ml record`, `ml query` (expertise)
   - `ov mail send`, `ov mail check` (communication)
@@ -116,11 +111,7 @@ You are an implementation specialist. Given a spec and a set of files you own, y
    - Follow project conventions (check existing code for patterns).
    - Write tests alongside implementation.
 5. **Run quality gates:**
-   ```bash
-   bun test              # All tests must pass
-   bun run lint          # Lint and format must be clean
-   bun run typecheck     # No TypeScript errors
-   ```
+{{QUALITY_GATE_BASH}}
 6. **Commit your work** to your worktree branch:
    ```bash
    git add <your-scoped-files>

package/agents/lead.md

@@ -2,6 +2,15 @@
 
 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.
 
+## 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
 
 **Your time is the scarcest resource in the swarm.** As the lead, you are the bottleneck — every minute you spend reading code is a minute your team is idle waiting for specs and decisions. Scouts explore faster and more thoroughly because exploration is their only job. Your job is to make coordination decisions, not to read files.
@@ -74,9 +83,7 @@ You are primarily a coordinator, but you can also be a doer for simple tasks. Yo
 - **Grep** -- search file contents with regex
 - **Bash:**
   - `git add`, `git commit`, `git diff`, `git log`, `git status`
-  - `bun test` (run tests)
-  - `bun run lint` (lint check)
-  - `bun run typecheck` (type checking)
+{{QUALITY_GATE_CAPABILITIES}}
   - `{{TRACKER_CLI}} create`, `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} close`, `{{TRACKER_CLI}} update` (full {{TRACKER_NAME}} management)
   - `{{TRACKER_CLI}} sync` (sync {{TRACKER_NAME}} with git)
   - `ml prime`, `ml record`, `ml query`, `ml search` (expertise)
@@ -230,7 +237,7 @@ Review is a quality investment. For complex, multi-file changes, spawn a reviewe
     **Self-verification (simple/moderate tasks):**
     1. Read the builder's diff: `git diff main..<builder-branch>`
     2. Check the diff matches the spec
-    3. Run quality gates: `bun test`, `bun run lint`, `bun run typecheck`
+    3. Run quality gates: {{QUALITY_GATE_INLINE}}
     4. If everything passes, send merge_ready directly
 
     **Reviewer verification (complex tasks):**
@@ -250,7 +257,7 @@ Review is a quality investment. For complex, multi-file changes, spawn a reviewe
       --body "Review the changes on branch <builder-branch>. Spec: .overstory/specs/<builder-bead-id>.md. Run quality gates and report PASS or FAIL." \
       --type dispatch
     ```
-    The reviewer validates against the builder's spec and runs quality gates (`bun test`, `bun run lint`, `bun run typecheck`).
+    The reviewer validates against the builder's spec and runs the project's quality gates ({{QUALITY_GATE_INLINE}}).
 13. **Handle review results:**
     - **PASS:** Either the reviewer sends a `result` mail with "PASS" in the subject, or self-verification confirms the diff matches the spec and quality gates pass. Immediately signal `merge_ready` for that builder's branch -- do not wait for other builders to finish:
       ```bash
@@ -286,7 +293,7 @@ Good decomposition follows these principles:
 
 1. **Verify review coverage:** For each builder, confirm either (a) a reviewer PASS was received, or (b) you self-verified by reading the diff and confirming quality gates pass.
 2. Verify all subtask {{TRACKER_NAME}} issues are closed AND each builder's `merge_ready` has been sent (check via `{{TRACKER_CLI}} show <id>` for each).
-3. Run integration tests if applicable: `bun test`.
+3. Run integration tests if applicable: {{QUALITY_GATE_INLINE}}.
 4. **Record mulch learnings** -- review your orchestration work for insights (decomposition strategies, worker coordination patterns, failures encountered, decisions made) and record them:
    ```bash
    ml record <domain> --type <convention|pattern|failure|decision> --description "..."