@katyella/legio 0.1.0 → 0.1.2

package/README.md

@@ -4,35 +4,26 @@
   <img src="assets/legio-mascot.png" alt="Legio mascot" width="400">
 </p>
 
+[![npm](https://img.shields.io/npm/v/@katyella/legio)](https://www.npmjs.com/package/@katyella/legio)
 [![CI](https://img.shields.io/github/actions/workflow/status/katyella/legio/ci.yml?branch=main)](https://github.com/katyella/legio/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node](https://img.shields.io/badge/Node-%E2%89%A522-green)](https://nodejs.org)
 [![GitHub release](https://img.shields.io/github/v/release/katyella/legio)](https://github.com/katyella/legio/releases)
 
-Built on [Overstory](https://github.com/jayminwest/overstory).
-
 **Turn one Claude Code session into a multi-agent fleet.**
 
-Claude Code is powerful — but it works one task at a time, sequentially. One agent, one context window, one thread of execution.
-
-Legio changes that. It spawns specialized agents in isolated git worktrees, coordinates them through a typed SQLite messaging system, and merges their work back automatically with tiered conflict resolution. Your session becomes the orchestrator. The agents do the work in parallel.
-
-> **Warning: Agent swarms are not a universal solution.** Do not deploy Legio 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.
-
-## Why Legio?
+Claude Code is powerful — but it works one task at a time. One agent, one context window, one thread of execution.
 
-**The problem:** Claude Code runs a single agent in a single session. Ten files across three subsystems means sequential work — one change at a time, in one context window, with no parallelism.
+Legio changes that. It spawns specialized agents in isolated git worktrees, coordinates them through a typed SQLite messaging system, and merges their work back automatically. Your session becomes the orchestrator. The agents do the work in parallel.
 
-**The solution:** A fleet of specialized agents, each with its own worktree, file scope, and tmux session. A coordinator decomposes the objective. Leads break it into tasks. Builders implement. Reviewers validate. Mergers integrate. All in parallel.
+- **Parallel execution** — 5-10 agents working simultaneously, each in its own tmux session
+- **Conflict-free isolation** — every agent in its own git worktree with exclusive file ownership
+- **Structured coordination** — typed SQLite mail system with protocol-level message types, not ad-hoc prompts
+- **Automatic merge pipeline** — FIFO queue with 4-tier conflict resolution
+- **Real-time visibility** — browser dashboard shows every agent's status, cost, and output live
+- **Tiered health monitoring** — mechanical watchdog catches stalls and crashes before you do
 
-**The payoff:**
-
-- Parallel execution — 5-10 agents working simultaneously
-- Conflict-free isolation — every agent in its own git worktree with exclusive file ownership
-- Structured coordination — typed SQLite mail system, not ad-hoc prompts
-- Automatic merge pipeline — FIFO queue with 4-tier conflict resolution
-- Real-time visibility — browser dashboard shows every agent status, cost, and output live
-- Tiered health monitoring — mechanical watchdog catches stalls and crashes
+> **Heads up:** Multi-agent swarms burn through tokens fast — a single session can push the limits of a 20x Max Claude subscription.
 
 ## See It in Action
 
@@ -43,20 +34,24 @@ Legio changes that. It spawns specialized agents in isolated git worktrees, coor
 </p>
 
 <p align="center">
-  <img src="assets/gateway-chat.png" alt="Gateway Chat — conversational planning interface" width="800">
+  <img src="assets/inspect.png" alt="Inspect — deep per-agent inspection" width="800">
   <br>
-  <em>Gateway Chat: natural language interface for planning and task decomposition</em>
+  <em>Inspect: deep dive into any agent's activity, tool calls, and terminal output</em>
 </p>
 
 <p align="center">
-  <img src="assets/inspect.png" alt="Inspect — deep per-agent inspection" width="800">
+  <img src="assets/costs.png" alt="Costs — token usage and cost breakdown" width="800">
   <br>
-  <em>Inspect: deep dive into any agent's activity, tool calls, and terminal output</em>
+  <em>Costs: token usage by model, per-agent breakdown, and daily cost trends</em>
 </p>
 
-## Quick Start
+<p align="center">
+  <img src="assets/tasks.png" alt="Tasks — issue tracking kanban board" width="800">
+  <br>
+  <em>Tasks: kanban board with issue tracking, priority filters, and dispatch controls</em>
+</p>
 
-The fastest way to get started:
+## Quick Start
 
 ```bash
 cd your-project
@@ -71,41 +66,9 @@ legio doctor
 legio down
 ```
 
-Or step by step:
-
-```bash
-# Initialize legio in your project
-legio init
-
-# Install hooks into .claude/settings.local.json
-legio hooks install
-
-# Start the web UI server (daemon mode)
-legio server start --daemon
-
-# Start a coordinator (persistent orchestrator)
-legio coordinator start
-
-# Or spawn individual worker agents
-# Task IDs come from beads: run `bd ready` to find available work, or `bd create` to create new tasks
-legio sling <task-id> --capability builder --name my-builder
-
-# Check agent status
-legio status
-
-# Live TUI dashboard for monitoring the fleet
-legio dashboard
-
-# Nudge a stalled agent
-legio nudge <agent-name>
-
-# Check mail from agents
-legio mail check --inject
-```
-
 ## How It Works
 
-CLAUDE.md + hooks + the `legio` 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.
+CLAUDE.md + hooks + the `legio` CLI turn your Claude Code session into a multi-agent orchestrator. A persistent coordinator manages task decomposition and dispatch, while a mechanical watchdog daemon monitors agent health.
 
 ```
 Coordinator (persistent orchestrator at project root)
@@ -113,66 +76,22 @@ Coordinator (persistent orchestrator at project root)
         --> Workers: Scout, Builder, Reviewer, Merger (depth 2)
 ```
 
-### Agent Types
-
-| Agent | Role | Access |
-|-------|------|--------|
-| **Coordinator** | Persistent orchestrator — decomposes objectives, dispatches agents, tracks task groups | Read-only |
-| **Lead** | Team coordination, can spawn sub-workers | Read-write |
-| **Gateway** | Planning companion — analyzes codebase, decomposes objectives into issues, bridges human intent and agent work | Read-only |
-| **Scout** | Read-only exploration and research | Read-only |
-| **Builder** | Implementation and code changes | Read-write |
-| **Reviewer** | Validation and code review | Read-only |
-| **Merger** | Branch merge specialist | Read-write |
-| **Supervisor** | Per-project team lead — manages worker lifecycle, handles nudge/escalation | Read-only |
-| **CTO** | Strategic technical leadership | Read-only |
-| **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
-- **Web UI**: Browser-based dashboard with real-time WebSocket updates — agent monitoring, mail, terminal access, cost tracking, and setup wizard
-- **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
-
-## Web UI
-
-Legio includes a browser-based dashboard for real-time fleet monitoring. Start it with `legio server start` or `legio up`.
-
-**Views:**
-
-| View | Description |
-|------|-------------|
-| **Dashboard** | Agent status, mail feed, merge queue, system metrics |
-| **Costs** | Token usage and cost breakdown |
-| **Tasks** | Beads issue tracking and status |
-| **Chat** | Task-based conversations grouped by issue |
-| **Setup** | Initialization wizard and configuration |
-| **Gateway Chat** | Gateway agent conversation interface |
-| **Inspect** | Deep per-agent inspection |
-| **Task Detail** | Task overview with agents and communication tabs |
-
-**Tech:** Preact + HTM + Tailwind CSS, WebSocket for real-time updates, zero build step.
+**Agent types:** Coordinator, Lead, Gateway, Supervisor, Scout, Builder, Reviewer, Merger, Monitor, CTO — each with defined access levels (read-only vs read-write) and hierarchy constraints. See [docs/architecture.md](docs/architecture.md) for details.
 
-## Requirements
+## Key Features
 
-- [Node.js](https://nodejs.org) (v22+)
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
-- git
-- tmux
-- [bd (beads)](https://github.com/jayminwest/beads) — issue tracking CLI
-- [mulch](https://github.com/jayminwest/mulch) — structured expertise management CLI
+- **Messaging system** — SQLite-backed typed mail with protocol messages (`worker_done`, `merge_ready`, `dispatch`, `escalation`), broadcast groups (`@all`, `@builders`), and auto-nudge on high priority
+- **Merge pipeline** — FIFO queue with 4-tier conflict resolution, from fast-forward through AI-assisted merge
+- **Web dashboard** — Real-time agent monitoring, mail feed, cost tracking, terminal access, and setup wizard via browser UI (Preact + HTM, zero build step)
+- **Health monitoring** — Tier 0 mechanical daemon (tmux/pid liveness), Tier 1 AI-assisted failure triage, Tier 2 continuous monitor agent
+- **Tool enforcement** — PreToolUse hooks mechanically block dangerous operations per agent role
+- **Task groups** — Batch coordination with auto-close when all member issues complete
+- **Session lifecycle** — Checkpoint save/restore for compaction survivability, crash recovery handoffs
 
 ## Installation
 
 ```bash
-npm install -g legio
+npm install -g @katyella/legio
 ```
 
 ### From Source
@@ -184,366 +103,25 @@ npm install
 npm link
 ```
 
-## CLI Reference
-
-### Bootstrap
-
-```
-legio up                            Start everything (init + server + coordinator)
-  --port <n>                             Server port (default: 4173)
-  --host <addr>                          Server host (default: 127.0.0.1)
-  --no-open                              Skip opening browser
-  --force                                Reinitialize even if .legio/ exists
-  --json                                 JSON output
-
-legio down                          Stop everything (coordinator + server)
-  --json                                 JSON output
-```
-
-### Core Workflow
-
-```
-legio init                          Initialize .legio/ in current project
-                                        (deploys agent definitions automatically)
-
-legio 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
-  --json                                 JSON output
-
-legio prime                         Load context for orchestrator/agent
-  --agent <name>                         Per-agent priming
-  --compact                              Restore from checkpoint (compaction)
-
-legio spec write <bead-id>          Write a task specification
-  --body <content>                       Spec content (or pipe via stdin)
-
-legio 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
-```
-
-### Server
-
-```
-legio server start                  Start the web UI server
-  --port <n>                             Server port (default: 4173)
-  --host <addr>                          Server host (default: 127.0.0.1)
-  --open                                 Open browser on start
-  --daemon                               Run as background process
-legio server stop                   Stop the server daemon
-legio server status                 Show server state
-```
-
-### Coordination Agents
-
-```
-legio 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
-legio coordinator stop              Stop coordinator
-legio coordinator status            Show coordinator state
-
-legio supervisor start              Start per-project supervisor agent
-  --task <bead-id>                       Bead task ID (required)
-  --name <name>                          Unique name (required)
-  --parent <agent>                       Parent agent (default: coordinator)
-  --depth <n>                            Hierarchy depth (default: 1)
-  --attach / --no-attach                 TTY-aware tmux attach (default: auto)
-legio supervisor stop               Stop supervisor
-legio supervisor status             Show supervisor state
-
-legio monitor start                 Start Tier 2 monitor agent
-legio monitor stop                  Stop monitor agent
-legio monitor status                Show monitor state
-```
-
-### Messaging
-
-```
-legio 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)
-
-legio mail check                    Check inbox (unread messages)
-  --agent <name>  --inject  --json
-  --debounce <ms>                        Skip if checked within window
-
-legio mail list                     List messages with filters
-  --from <name>  --to <name>  --unread
-
-legio mail read <id>                Mark message as read
-legio mail reply <id> --body <text> Reply in same thread
-
-legio nudge <agent> [message]       Send a text nudge to an agent
-  --from <name>                          Sender name (default: orchestrator)
-  --force                                Skip debounce check
-  --json                                 JSON output
-```
-
-### Merge & Groups
-
-```
-legio 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
-
-legio group create <name>           Create a task group for batch tracking
-legio group status <name>           Show group progress
-legio group add <name> <issue-id>   Add issue to group
-legio group list                    List all groups
-```
-
-### Monitoring & Observability
-
-```
-legio status                        Show all active agents, worktrees, beads state
-  --json  --verbose
-
-legio dashboard                     Live TUI dashboard for agent monitoring
-  --interval <ms>                        Refresh interval (default: 2000)
-
-legio inspect <agent>               Deep per-agent inspection
-  --json  --follow  --interval <ms>  --no-tmux  --limit <n>
-
-legio trace                         View agent/bead timeline
-  --agent <name>  --run <id>
-  --since <ts>  --until <ts>  --limit <n>  --json
-
-legio feed [options]                Unified real-time event stream across agents
-  --follow, -f  --interval <ms>
-  --agent <name>  --run <id>  --json
-
-legio errors                        Aggregated error view across agents
-  --agent <name>  --run <id>
-  --since <ts>  --until <ts>  --limit <n>  --json
-
-legio replay                        Interleaved chronological replay
-  --run <id>  --agent <name>
-  --since <ts>  --until <ts>  --limit <n>  --json
-
-legio logs [options]                Query NDJSON logs across agents
-  --agent <name>  --level <level>
-  --since <ts>  --until <ts>  --follow  --json
-
-legio costs                         Token/cost analysis and breakdown
-  --live  --agent <name>  --run <id>
-  --by-capability  --last <n>  --json
-
-legio metrics                       Show session metrics
-  --last <n>  --json
-
-legio run list                      List orchestration runs
-legio run show <id>                 Show run details
-legio run complete                  Mark current run complete
-```
-
-### Infrastructure
-
-```
-legio hooks install                 Install orchestrator hooks to .claude/settings.local.json
-  --force                                Overwrite existing hooks
-legio hooks uninstall               Remove orchestrator hooks
-legio hooks status                  Check if hooks are installed
-
-legio worktree list                 List worktrees with status
-legio worktree clean                Remove completed worktrees
-  --completed  --all
-
-legio watch                         Start watchdog daemon (Tier 0)
-  --interval <ms>  --background
-
-legio doctor                        Run health checks on legio setup
-  --json  --category <name>
-
-legio clean                         Clean up worktrees, sessions, artifacts
-  --all  --mail  --sessions  --metrics
-  --logs  --worktrees  --branches
-  --agents  --specs  --json
+## Requirements
 
-legio log <event>                   Log a hook event (called by hooks)
+- [Node.js](https://nodejs.org) (v22+)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+- git
+- tmux
+- [bd (beads)](https://github.com/steveyegge/beads) — issue tracking CLI
+- [mulch](https://github.com/jayminwest/mulch) — structured expertise management CLI (`npm install -g @os-eco/mulch-cli`)
 
-Global Flags:
-  --quiet, -q                            Suppress non-error output
-  --completions <shell>                  Generate shell completions (bash, zsh, fish)
-```
+## Documentation
 
-## REST API
-
-When the server is running, a full REST API is available at `http://localhost:4173/api/`:
-
-| Endpoint | Description |
-|----------|-------------|
-| `GET /api/status` | Overall project status |
-| `GET /api/health` | Server health check |
-| `GET /api/agents` | List all agents |
-| `GET /api/agents/active` | Active agents only |
-| `GET /api/agents/:name` | Agent details |
-| `GET /api/agents/:name/inspect` | Deep inspection data |
-| `GET /api/agents/:name/events` | Agent events |
-| `POST /api/agents/:name/chat` | Send chat message to agent |
-| `GET /api/agents/:name/chat/history` | Agent chat history |
-| `POST /api/agents/spawn` | Spawn agent from UI |
-| `POST /api/coordinator/chat` | Send chat message to coordinator |
-| `GET /api/coordinator/chat/history` | Coordinator chat history |
-| `POST /api/gateway/chat` | Send chat message to gateway |
-| `GET /api/gateway/chat/history` | Gateway chat history |
-| `GET /api/chat/unified/history` | Unified chat timeline |
-| `POST /api/chat/transcript-sync` | Sync transcript data |
-| `GET /api/ideas` | Ideas list |
-| `POST /api/ideas` | Create idea |
-| `PUT /api/ideas/:id` | Update idea |
-| `DELETE /api/ideas/:id` | Delete idea |
-| `POST /api/ideas/:id/dispatch` | Dispatch idea to agents |
-| `POST /api/ideas/:id/backlog` | Move idea to backlog |
-| `GET /api/mail` | All messages |
-| `GET /api/mail/unread` | Unread messages |
-| `GET /api/mail/conversations` | Thread grouping |
-| `POST /api/mail/send` | Send a message |
-| `GET /api/events` | Tool events |
-| `GET /api/events/errors` | Error events |
-| `GET /api/metrics` | Session metrics |
-| `GET /api/runs` | All runs |
-| `GET /api/runs/active` | Active run |
-| `GET /api/issues` | Beads issues |
-| `GET /api/merge-queue` | Merge queue status |
-| `POST /api/terminal/send` | Send keys to tmux pane |
-| `GET /api/terminal/capture` | Capture pane output |
-| `POST /api/setup/init` | Initialize legio from UI |
-| `GET /api/setup/status` | Setup status |
-| `GET /api/audit` | Query audit trail |
-| `WS /ws` | WebSocket for real-time updates |
-
-## Tech Stack
-
-- **Runtime**: Node/tsx (TypeScript directly, no build step)
-- **Node.js**: v22+ (required for `better-sqlite3`)
-- **Dependencies**: `better-sqlite3` (SQLite), `tsx` (TypeScript execution), `ws` (WebSocket server)
-- **Database**: SQLite via `better-sqlite3` (WAL mode for concurrent access)
-- **Web UI**: Preact + HTM + Tailwind CSS (zero build step, served from `src/server/public/`)
-- **Linting**: Biome (formatter + linter)
-- **Testing**: `vitest` (stores, server) + `playwright` (e2e)
-- **External CLIs**: `bd` (beads), `mulch`, `git`, `tmux` — invoked as subprocesses
+- [CLI Reference](docs/cli.md) — full command reference with all flags
+- [REST API](docs/api.md) — server endpoints and WebSocket
+- [Architecture](docs/architecture.md) — tech stack, agent types, project structure
 
 ## Development
 
 ```bash
-# Run core tests
-npm test
-
-# Run store/server tests (vitest)
-npm run test:server
-
-# Run e2e tests (playwright)
-npm run test:e2e
-
-# Run a single test file
-npx vitest run src/config.test.ts
-
-# Lint + format check
-npx biome check .
-
-# Type check
-tsc --noEmit
-
-# All quality gates
-npm test && npx 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
-
-Version bumps are handled by the GitHub Actions `workflow_dispatch` workflow. Do not bump versions manually.
-
-## Project Structure
-
-```
-legio/
-  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 (34 commands)
-      up.ts                       Bootstrap full stack
-      down.ts                     Shutdown full stack
-      server.ts                   Web UI server lifecycle
-      agents.ts                   Agent discovery and querying
-      coordinator.ts              Persistent orchestrator lifecycle
-      gateway.ts                  Gateway agent 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
-      costs.ts                    Token/cost analysis
-      metrics.ts                  Session metrics
-      completions.ts              Shell completion generation (bash/zsh/fish)
-    server/                       Web UI server
-      routes.ts                   REST API routes
-      websocket.ts                WebSocket real-time updates
-      audit-store.ts              SQLite audit trail
-      public/                     Frontend (Preact + HTM + Tailwind)
-        views/                    UI views (command, chat, dashboard, etc.)
-        components/               Reusable UI components
-        lib/                      Client-side state, API, WebSocket
-    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
-    beads/                        bd CLI wrapper + molecules
-    mulch/                        mulch CLI wrapper
-    e2e/                          End-to-end lifecycle tests
-  agents/                         Base agent definitions (.md, 10 roles)
-
-  templates/                      Templates for overlays and hooks
+npm test && npm run lint && npm run typecheck
 ```
 
 ## License
@@ -552,4 +130,5 @@ MIT
 
 ---
 
-Inspired by: https://github.com/steveyegge/gastown/
+Adopted from [Overstory](https://github.com/jayminwest/overstory).
+

package/agents/builder.md

@@ -16,10 +16,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`
-  - `npm run test:unit` (run unit tests for your scoped files)
-  - `npm run lint` (lint and format check via biome)
-  - `npx biome check --write` (auto-fix lint/format issues)
-  - `npm run typecheck` (type checking via tsc)
+  - Project test, lint, and typecheck commands (see Quality Gates in your overlay)
   - `bd show`, `bd close` (beads task management)
   - `mulch prime`, `mulch record`, `mulch query` (expertise)
   - `legio mail send`, `legio mail check` (communication)
@@ -49,12 +46,7 @@ You receive mail automatically. Do not call `legio mail check` in loops or on a
    - 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
-   npm run test:unit     # Unit tests must pass
-   npm run lint          # Lint and format must be clean
-   npm run typecheck     # No TypeScript errors
-   ```
+5. **Run quality gates** as specified in your overlay's Quality Gates section (tests, lint, and any other configured gates).
 6. **Commit your work** to your worktree branch:
    ```bash
    git add <your-scoped-files>
@@ -77,7 +69,7 @@ You receive mail automatically. Do not call `legio mail check` in loops or on a
 - **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 `npm run test:unit`, `npm run lint`, and `npm run typecheck` pass.
+- **Run quality gates before closing.** Do not report completion unless tests, lint, and typecheck pass (commands are in your overlay).
 - If tests fail, fix them. If you cannot fix them, report the failure via mail with `--type error`.
 
 ## Communication Protocol
@@ -107,7 +99,7 @@ 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 `bd close` without first passing quality gates (`npm run test:unit`, `npm run lint`, `npm run typecheck`) and sending a result mail to your parent.
+- **INCOMPLETE_CLOSE** -- Running `bd close` without first passing quality gates (tests, lint, and any other configured gates) 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.
 
@@ -117,9 +109,7 @@ Every mail message and every tool call costs tokens. Be concise in mail bodies -
 
 ## Completion Protocol
 
-1. Run `npm run test:unit` -- unit tests must pass.
-2. Run `npm run lint` -- lint and formatting must be clean.
-3. Run `npm run typecheck` -- no TypeScript errors.
+1. Run the project's quality gate commands (tests, lint, and any other configured gates) as specified in your overlay.
 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:
    ```bash

package/agents/cto.md

@@ -48,8 +48,8 @@ Before forming opinions, gather raw facts from the system.
    ```
 
 3. **Read architectural files:**
-   - `CLAUDE.md`, `README.md`, `package.json`, `tsconfig.json`, `biome.json`
-   - Key source files: `src/index.ts`, `src/types.ts`, `src/config.ts`
+   - `CLAUDE.md`, `README.md`, and the project's package/build configuration files
+   - Key source entry points and type definitions
    - Any files flagged by mulch as hot (edited 3+ times recently)
 
 4. **Analyze git history for patterns:**