@os-eco/overstory-cli 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaymin West
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,381 @@
+# 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)
+
+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.
+
+> **⚠️ 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.
+
+## 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.
+
+```
+Coordinator (persistent orchestrator at project root)
+  --> Supervisor (per-project team lead, depth 1)
+        --> Workers: Scout, Builder, Reviewer, Merger (depth 2)
+```
+
+### Agent Types
+
+| 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 |
+
+### Key Architecture
+
+- **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
+
+## Requirements
+
+- [Bun](https://bun.sh) (v1.0+)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+- git
+- tmux
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/jayminwest/overstory.git
+cd overstory
+
+# Install dev dependencies
+bun install
+
+# Link the CLI globally
+bun link
+```
+
+## Quick Start
+
+```bash
+# Initialize overstory in your project
+cd your-project
+overstory init
+
+# Install hooks into .claude/settings.local.json
+overstory hooks install
+
+# Start a coordinator (persistent orchestrator)
+overstory coordinator start
+
+# Or spawn individual worker agents
+overstory sling <task-id> --capability builder --name my-builder
+
+# Check agent status
+overstory status
+
+# Live dashboard for monitoring the fleet
+overstory dashboard
+
+# Nudge a stalled agent
+overstory nudge <agent-name>
+
+# Check mail from agents
+overstory mail check --inject
+```
+
+## CLI Reference
+
+```
+overstory 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
+                                        (deploys agent definitions automatically)
+
+overstory 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
+
+overstory 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
+
+overstory 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)
+  --json                                 JSON output
+
+overstory 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
+  --agent <name>                         Per-agent priming
+  --compact                              Restore from checkpoint (compaction)
+
+overstory 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
+  --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
+  --force                                Overwrite existing hooks
+overstory hooks uninstall               Remove orchestrator hooks
+overstory hooks status                  Check if hooks are installed
+
+overstory 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)
+  --agent <name>  --inject  --json
+  --debounce <ms>                        Skip if checked within window
+
+overstory 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
+
+overstory 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
+
+overstory 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
+  --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
+
+overstory log <event>                   Log a hook event
+overstory 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
+
+overstory trace                         View agent/bead timeline
+  --agent <name>                         Filter by agent
+  --run <id>                             Filter by run
+
+overstory 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
+  --json                                 JSON output
+  --category <name>                      Run a specific check category only
+
+overstory 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
+  --body <content>                       Spec content (or pipe via stdin)
+
+overstory 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
+  --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
+  --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
+  --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
+  --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
+
+overstory 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**: Zero runtime dependencies — only Bun built-in APIs
+- **Database**: SQLite via `bun:sqlite` (WAL mode for concurrent access)
+- **Linting**: Biome (formatter + linter)
+- **Testing**: `bun test` (2087 tests across 75 files, colocated with source)
+- **External CLIs**: `bd` (beads) or `sd` (seeds), `mulch`, `git`, `tmux` — invoked as subprocesses
+
+## Development
+
+```bash
+# Run tests (2087 tests across 75 files)
+bun test
+
+# Run a single test
+bun test src/config.test.ts
+
+# Lint + format check
+biome check .
+
+# Type check
+tsc --noEmit
+
+# All quality gates
+bun test && biome check . && tsc --noEmit
+```
+
+### Versioning
+
+Version is maintained in two places that must stay in sync:
+
+1. `package.json` — `"version"` field
+2. `src/index.ts` — `VERSION` constant
+
+Use the bump script to update both:
+
+```bash
+bun run version:bump <major|minor|patch>
+```
+
+Git tags are created automatically by GitHub Actions when a version bump is pushed to `main`.
+
+## Project Structure
+
+```
+overstory/
+  src/
+    index.ts                      CLI entry point (command router)
+    types.ts                      Shared types and interfaces
+    config.ts                     Config loader + validation
+    errors.ts                     Custom error types
+    commands/                     One file per CLI subcommand (30 commands)
+      agents.ts                   Agent discovery and querying
+      coordinator.ts              Persistent orchestrator lifecycle
+      supervisor.ts               Team lead management
+      dashboard.ts                Live TUI dashboard (ANSI, zero deps)
+      hooks.ts                    Orchestrator hooks management
+      sling.ts                    Agent spawning
+      group.ts                    Task group batch tracking
+      nudge.ts                    Agent nudging
+      mail.ts                     Inter-agent messaging
+      monitor.ts                  Tier 2 monitor management
+      merge.ts                    Branch merging
+      status.ts                   Fleet status overview
+      prime.ts                    Context priming
+      init.ts                     Project initialization
+      worktree.ts                 Worktree management
+      watch.ts                    Watchdog daemon
+      log.ts                      Hook event logging
+      logs.ts                     NDJSON log query
+      feed.ts                     Unified real-time event stream
+      run.ts                      Orchestration run lifecycle
+      trace.ts                    Agent/bead timeline viewing
+      clean.ts                    Worktree/session cleanup
+      doctor.ts                   Health check runner (9 check modules)
+      inspect.ts                  Deep per-agent inspection
+      spec.ts                     Task spec management
+      errors.ts                   Aggregated error view
+      replay.ts                   Interleaved event replay
+      stop.ts                     Agent termination
+      costs.ts                    Token/cost analysis
+      metrics.ts                  Session metrics
+      completions.ts              Shell completion generation (bash/zsh/fish)
+    agents/                       Agent lifecycle management
+      manifest.ts                 Agent registry (load + query)
+      overlay.ts                  Dynamic CLAUDE.md overlay generator
+      identity.ts                 Persistent agent identity (CVs)
+      checkpoint.ts               Session checkpoint save/restore
+      lifecycle.ts                Handoff orchestration
+      hooks-deployer.ts           Deploy hooks + tool enforcement
+    worktree/                     Git worktree + tmux management
+    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
+    metrics/                      SQLite metrics + transcript parsing
+    doctor/                       Health check modules (9 checks)
+    insights/                     Session insight analyzer for auto-expertise
+    tracker/                      Pluggable task tracker (beads + seeds backends)
+    mulch/                        mulch CLI wrapper
+    e2e/                          End-to-end lifecycle tests
+  agents/                         Base agent definitions (.md, 8 roles)
+  templates/                      Templates for overlays and hooks
+```
+
+## License
+
+MIT
+
+---
+
+Inspired by: https://github.com/steveyegge/gastown/

package/agents/builder.md

@@ -0,0 +1,137 @@
+## propulsion-principle
+
+Read your assignment. Execute immediately. Do not ask for confirmation, do not propose a plan and wait for approval, do not summarize back what you were told. Start working within your first tool call.
+
+## cost-awareness
+
+Every mail message and every tool call costs tokens. Be concise in communications -- state what was done, what the outcome is, any caveats. Do not send multiple small status messages when one summary will do.
+
+## failure-modes
+
+These are named failures. If you catch yourself doing any of these, stop and correct immediately.
+
+- **PATH_BOUNDARY_VIOLATION** -- Writing to any file outside your worktree directory. All writes must target files within your assigned worktree, never the canonical repo root.
+- **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.
+- **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.
+
+## 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.
+
+## 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 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.
+- If tests fail, fix them. If you cannot fix them, report the failure via mail with `--type error`.
+
+## communication-protocol
+
+- 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>" \
+    --body "<your question>" --type question
+  ```
+- Send `error` messages when something is broken:
+  ```bash
+  overstory 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.
+
+## 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.
+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 "..." \
+     --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>" \
+     --body "Completed implementation for <task-id>. Quality gates passed." \
+     --type worker_done --agent $OVERSTORY_AGENT_NAME
+   ```
+7. Run `{{TRACKER_CLI}} close <task-id> --reason "<summary of implementation>"`.
+8. Exit. Do NOT idle, wait for instructions, or continue working. Your task is complete.
+
+## intro
+
+# Builder Agent
+
+You are a **builder agent** in the overstory swarm system. Your job is to implement changes according to a spec. You write code, run tests, and deliver working software.
+
+## role
+
+You are an implementation specialist. Given a spec and a set of files you own, you build the thing. You write clean, tested code that passes quality gates. You work within your file scope and commit to your worktree branch only.
+
+## capabilities
+
+### Tools Available
+- **Read** -- read any file in the codebase
+- **Write** -- create new files (within your FILE_SCOPE only)
+- **Edit** -- modify existing files (within your FILE_SCOPE only)
+- **Glob** -- find files by name pattern
+- **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)
+  - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} close` ({{TRACKER_NAME}} task management)
+  - `mulch prime`, `mulch record`, `mulch query` (expertise)
+  - `overstory mail send`, `overstory 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`
+- **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
+
+## 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.
+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.
+   - 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
+   ```
+6. **Commit your work** to your worktree branch:
+   ```bash
+   git add <your-scoped-files>
+   git commit -m "<concise description of what you built>"
+   ```
+7. **Report completion:**
+   ```bash
+   {{TRACKER_CLI}} close <task-id> --reason "<summary of implementation>"
+   ```
+8. **Send result mail** if your parent or coordinator needs details:
+   ```bash
+   overstory mail send --to <parent> --subject "Build complete: <topic>" \
+     --body "<what was built, tests passing, any notes>" --type result
+   ```