@os-eco/overstory-cli 0.6.10 → 0.6.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/README.md +156 -272
  2. package/agents/lead.md +9 -0
  3. package/package.json +1 -1
  4. package/src/agents/hooks-deployer.test.ts +53 -0
  5. package/src/agents/hooks-deployer.ts +4 -4
  6. package/src/agents/manifest.test.ts +1 -0
  7. package/src/agents/overlay.test.ts +79 -0
  8. package/src/agents/overlay.ts +40 -2
  9. package/src/commands/completions.ts +3 -3
  10. package/src/commands/coordinator.ts +4 -4
  11. package/src/commands/group.ts +4 -4
  12. package/src/commands/mail.test.ts +63 -1
  13. package/src/commands/mail.ts +18 -1
  14. package/src/commands/merge.ts +2 -2
  15. package/src/commands/monitor.ts +2 -2
  16. package/src/commands/sling.test.ts +174 -27
  17. package/src/commands/sling.ts +95 -11
  18. package/src/commands/status.ts +1 -1
  19. package/src/commands/supervisor.ts +4 -4
  20. package/src/commands/trace.ts +2 -2
  21. package/src/config.test.ts +22 -0
  22. package/src/config.ts +12 -0
  23. package/src/doctor/agents.test.ts +1 -0
  24. package/src/doctor/config-check.test.ts +1 -0
  25. package/src/doctor/consistency.test.ts +1 -0
  26. package/src/doctor/databases.test.ts +1 -0
  27. package/src/doctor/dependencies.test.ts +1 -0
  28. package/src/doctor/ecosystem.test.ts +1 -0
  29. package/src/doctor/logs.test.ts +1 -0
  30. package/src/doctor/merge-queue.test.ts +1 -0
  31. package/src/doctor/structure.test.ts +1 -0
  32. package/src/doctor/version.test.ts +1 -0
  33. package/src/index.ts +7 -4
  34. package/src/types.ts +11 -0
  35. package/templates/overlay.md.tmpl +3 -1
package/README.md CHANGED
@@ -1,68 +1,40 @@
1
1
  # Overstory
2
2
 
3
- [![CI](https://img.shields.io/github/actions/workflow/status/jayminwest/overstory/ci.yml?branch=main)](https://github.com/jayminwest/overstory/actions/workflows/ci.yml)
4
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
- [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
6
- [![GitHub release](https://img.shields.io/github/v/release/jayminwest/overstory)](https://github.com/jayminwest/overstory/releases)
3
+ Multi-agent orchestration for Claude Code.
7
4
 
8
- 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.
5
+ [![npm](https://img.shields.io/npm/v/@os-eco/overstory-cli)](https://www.npmjs.com/package/@os-eco/overstory-cli)
6
+ [![CI](https://github.com/jayminwest/overstory/actions/workflows/ci.yml/badge.svg)](https://github.com/jayminwest/overstory/actions/workflows/ci.yml)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
9
8
 
10
- > **⚠️ 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.
9
+ 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.
11
10
 
12
- ## How It Works
13
-
14
- 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.
15
-
16
- ```
17
- Coordinator (persistent orchestrator at project root)
18
- --> Supervisor (per-project team lead, depth 1)
19
- --> Workers: Scout, Builder, Reviewer, Merger (depth 2)
20
- ```
21
-
22
- ### Agent Types
11
+ > **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.
23
12
 
24
- | Agent | Role | Access |
25
- |-------|------|--------|
26
- | **Coordinator** | Persistent orchestrator — decomposes objectives, dispatches agents, tracks task groups | Read-only |
27
- | **Supervisor** | Per-project team lead — manages worker lifecycle, handles nudge/escalation | Read-only |
28
- | **Scout** | Read-only exploration and research | Read-only |
29
- | **Builder** | Implementation and code changes | Read-write |
30
- | **Reviewer** | Validation and code review | Read-only |
31
- | **Lead** | Team coordination, can spawn sub-workers | Read-write |
32
- | **Merger** | Branch merge specialist | Read-write |
33
- | **Monitor** | Tier 2 continuous fleet patrol — ongoing health monitoring | Read-only |
13
+ ## Install
34
14
 
35
- ### Key Architecture
15
+ Requires [Bun](https://bun.sh) v1.0+, [Claude Code](https://docs.anthropic.com/en/docs/claude-code), git, and tmux.
36
16
 
37
- - **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.
38
- - **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.)
39
- - **Worktrees**: Each agent gets an isolated git worktree — no file conflicts between agents
40
- - **Merge**: FIFO merge queue (SQLite-backed) with 4-tier conflict resolution
41
- - **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
42
- - **Tool Enforcement**: PreToolUse hooks mechanically block file modifications for non-implementation agents and dangerous git operations for all agents
43
- - **Task Groups**: Batch coordination with auto-close when all member issues complete
44
- - **Session Lifecycle**: Checkpoint save/restore for compaction survivability, handoff orchestration for crash recovery
45
- - **Token Instrumentation**: Session metrics extracted from Claude Code transcript JSONL files
17
+ ```bash
18
+ bun install -g @os-eco/overstory-cli
19
+ ```
46
20
 
47
- ## Requirements
21
+ Or try without installing:
48
22
 
49
- - [Bun](https://bun.sh) (v1.0+)
50
- - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
51
- - git
52
- - tmux
23
+ ```bash
24
+ npx @os-eco/overstory-cli --help
25
+ ```
53
26
 
54
- ## Installation
27
+ ### Development
55
28
 
56
29
  ```bash
57
- # Clone the repository
58
30
  git clone https://github.com/jayminwest/overstory.git
59
31
  cd overstory
60
-
61
- # Install dev dependencies
62
32
  bun install
33
+ bun link # Makes 'ov' available globally
63
34
 
64
- # Link the CLI globally
65
- bun link
35
+ bun test # Run all tests
36
+ bun run lint # Biome check
37
+ bun run typecheck # tsc --noEmit
66
38
  ```
67
39
 
68
40
  ## Quick Start
@@ -94,233 +66,134 @@ ov nudge <agent-name>
94
66
  ov mail check --inject
95
67
  ```
96
68
 
97
- ## CLI Reference
98
-
99
- ```
100
- ov agents discover Discover agents by capability/state/parent
101
- --capability <type> Filter by capability type
102
- --state <state> Filter by agent state
103
- --parent <name> Filter by parent agent
104
- --json JSON output
105
-
106
- ov init Initialize .overstory/ in current project
107
- (deploys agent definitions automatically)
108
- --yes, -y Skip interactive prompts
109
- --name <name> Set project name (default: auto-detect)
110
-
111
- ov coordinator start Start persistent coordinator agent
112
- --attach / --no-attach TTY-aware tmux attach (default: auto)
113
- --watchdog Auto-start watchdog daemon with coordinator
114
- --monitor Auto-start Tier 2 monitor agent
115
- ov coordinator stop Stop coordinator
116
- ov coordinator status Show coordinator state
117
-
118
- ov supervisor start Start per-project supervisor agent
119
- --attach / --no-attach TTY-aware tmux attach (default: auto)
120
- ov supervisor stop Stop supervisor
121
- ov supervisor status Show supervisor state
122
-
123
- ov sling <task-id> Spawn a worker agent
124
- --capability <type> builder | scout | reviewer | lead | merger
125
- | coordinator | supervisor | monitor
126
- --name <name> Unique agent name
127
- --spec <path> Path to task spec file
128
- --files <f1,f2,...> Exclusive file scope
129
- --parent <agent-name> Parent (for hierarchy tracking)
130
- --depth <n> Current hierarchy depth
131
- --skip-scout Skip scout phase (passed to lead overlay)
132
- --skip-task-check Skip task existence validation
133
- --json JSON output
134
-
135
- ov stop <agent-name> Terminate a running agent
136
- --clean-worktree Remove the agent's worktree (best-effort)
137
- --json JSON output
138
-
139
- ov prime Load context for orchestrator/agent
140
- --agent <name> Per-agent priming
141
- --compact Restore from checkpoint (compaction)
142
-
143
- ov status Show all active agents, worktrees, tracker state
144
- --json JSON output
145
- --verbose Show detailed agent info
146
- --all Show all runs (default: current run only)
147
-
148
- ov dashboard Live TUI dashboard for agent monitoring
149
- --interval <ms> Refresh interval (default: 2000)
150
- --all Show all runs (default: current run only)
151
-
152
- ov hooks install Install orchestrator hooks to .claude/settings.local.json
153
- --force Overwrite existing hooks
154
- ov hooks uninstall Remove orchestrator hooks
155
- ov hooks status Check if hooks are installed
156
-
157
- ov mail send Send a message
158
- --to <agent> --subject <text> --body <text>
159
- --to @all | @builders | @scouts ... Broadcast to group addresses
160
- --type <status|question|result|error>
161
- --priority <low|normal|high|urgent> (urgent/high auto-nudges recipient)
162
-
163
- ov mail check Check inbox (unread messages)
164
- --agent <name> --inject --json
165
- --debounce <ms> Skip if checked within window
166
-
167
- ov mail list List messages with filters
168
- --from <name> --to <name> --unread
169
-
170
- ov mail read <id> Mark message as read
171
- ov mail reply <id> --body <text> Reply in same thread
172
-
173
- ov nudge <agent> [message] Send a text nudge to an agent
174
- --from <name> Sender name (default: orchestrator)
175
- --force Skip debounce check
176
- --json JSON output
177
-
178
- ov group create <name> Create a task group for batch tracking
179
- ov group status <name> Show group progress
180
- ov group add <name> <issue-id> Add issue to group
181
- ov group list List all groups
182
-
183
- ov merge Merge agent branches into canonical
184
- --branch <name> Specific branch
185
- --all All completed branches
186
- --into <branch> Target branch (default: session-branch.txt > canonicalBranch)
187
- --dry-run Check for conflicts only
188
-
189
- ov worktree list List worktrees with status
190
- ov worktree clean Remove completed worktrees
191
- --completed Only finished agents
192
- --all Force remove all
193
- --force Delete even if branches are unmerged
194
-
195
- ov monitor start Start Tier 2 monitor agent
196
- ov monitor stop Stop monitor agent
197
- ov monitor status Show monitor state
198
-
199
- ov log <event> Log a hook event
200
- ov watch Start watchdog daemon (Tier 0)
201
- --interval <ms> Health check interval
202
- --background Run as background process
203
- ov run list List orchestration runs
204
- ov run show <id> Show run details
205
- ov run complete <id> Mark a run complete
206
-
207
- ov trace View agent/bead timeline
208
- --agent <name> Filter by agent
209
- --run <id> Filter by run
210
-
211
- ov clean Clean up worktrees, sessions, artifacts
212
- --completed Only finished agents
213
- --all Force remove all
214
- --run <id> Clean a specific run
215
-
216
- ov doctor Run health checks on overstory setup
217
- --json JSON output
218
- --category <name> Run a specific check category only
219
- --fix Auto-fix fixable issues
220
-
221
- ov ecosystem Show os-eco tool versions and health
222
- --json JSON output
223
-
224
- ov upgrade Upgrade overstory to latest npm version
225
- --check Compare versions without installing
226
- --all Upgrade all 4 ecosystem tools
227
- --json JSON output
228
-
229
- ov inspect <agent> Deep per-agent inspection
230
- --json JSON output
231
- --follow Polling mode (refreshes periodically)
232
- --interval <ms> Refresh interval for --follow
233
- --no-tmux Skip tmux capture
234
- --limit <n> Limit events shown
235
-
236
- ov spec write <task-id> Write a task specification
237
- --body <content> Spec content (or pipe via stdin)
238
-
239
- ov errors Aggregated error view across agents
240
- --agent <name> Filter by agent
241
- --run <id> Filter by run
242
- --since <ts> --until <ts> Time range filter
243
- --limit <n> --json
244
-
245
- ov replay Interleaved chronological replay
246
- --run <id> Filter by run
247
- --agent <name> Filter by agent(s)
248
- --since <ts> --until <ts> Time range filter
249
- --limit <n> --json
250
-
251
- ov feed [options] Unified real-time event stream across agents
252
- --follow, -f Continuously poll for new events
253
- --interval <ms> Polling interval (default: 2000)
254
- --agent <name> --run <id> Filter by agent or run
255
- --json JSON output
256
-
257
- ov logs [options] Query NDJSON logs across agents
258
- --agent <name> Filter by agent
259
- --level <level> Filter by log level (debug|info|warn|error)
260
- --since <ts> --until <ts> Time range filter
261
- --follow Tail logs in real time
262
- --json JSON output
263
-
264
- ov costs Token/cost analysis and breakdown
265
- --live Show real-time token usage for active agents
266
- --self Show cost for current orchestrator session
267
- --agent <name> Filter by agent
268
- --run <id> Filter by run
269
- --by-capability Group by capability type
270
- --last <n> --json
271
-
272
- ov metrics Show session metrics
273
- --last <n> Last N sessions
274
- --json JSON output
275
-
276
- Global Flags:
277
- --quiet, -q Suppress non-error output
278
- --timing Print command execution time to stderr
279
- --completions <shell> Generate shell completions (bash, zsh, fish)
280
- ```
281
-
282
- ## Tech Stack
283
-
284
- - **Runtime**: Bun (TypeScript directly, no build step)
285
- - **Dependencies**: Minimal runtime — `chalk` (color output), `commander` (CLI framework), core I/O via Bun built-in APIs
286
- - **Database**: SQLite via `bun:sqlite` (WAL mode for concurrent access)
287
- - **Linting**: Biome (formatter + linter)
288
- - **Testing**: `bun test` (2241 tests across 79 files, colocated with source)
289
- - **External CLIs**: `bd` (beads) or `sd` (seeds), `mulch`, `git`, `tmux` — invoked as subprocesses
69
+ ## Commands
70
+
71
+ Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--timing`. ANSI colors respect `NO_COLOR`.
72
+
73
+ ### Core Workflow
74
+
75
+ | Command | Description |
76
+ |---------|-------------|
77
+ | `ov init` | Initialize `.overstory/` in current project (`--yes`, `--name`) |
78
+ | `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`) |
79
+ | `ov stop <agent-name>` | Terminate a running agent (`--clean-worktree`, `--json`) |
80
+ | `ov prime` | Load context for orchestrator/agent (`--agent`, `--compact`) |
81
+ | `ov spec write <task-id>` | Write a task specification (`--body`) |
82
+
83
+ ### Coordination
84
+
85
+ | Command | Description |
86
+ |---------|-------------|
87
+ | `ov coordinator start` | Start persistent coordinator agent (`--attach`/`--no-attach`, `--watchdog`, `--monitor`) |
88
+ | `ov coordinator stop` | Stop coordinator |
89
+ | `ov coordinator status` | Show coordinator state |
90
+ | `ov supervisor start` | Start per-project supervisor agent (`--attach`/`--no-attach`) |
91
+ | `ov supervisor stop` | Stop supervisor |
92
+ | `ov supervisor status` | Show supervisor state |
93
+
94
+ ### Messaging
95
+
96
+ | Command | Description |
97
+ |---------|-------------|
98
+ | `ov mail send` | Send a message (`--to`, `--subject`, `--body`, `--type`, `--priority`) |
99
+ | `ov mail check` | Check inbox — unread messages (`--agent`, `--inject`, `--debounce`, `--json`) |
100
+ | `ov mail list` | List messages with filters (`--from`, `--to`, `--unread`) |
101
+ | `ov mail read <id>` | Mark message as read |
102
+ | `ov mail reply <id>` | Reply in same thread (`--body`) |
103
+ | `ov nudge <agent> [message]` | Send a text nudge to an agent (`--from`, `--force`, `--json`) |
104
+
105
+ ### Task Groups
106
+
107
+ | Command | Description |
108
+ |---------|-------------|
109
+ | `ov group create <name>` | Create a task group for batch tracking |
110
+ | `ov group status <name>` | Show group progress |
111
+ | `ov group add <name> <issue-id>` | Add issue to group |
112
+ | `ov group list` | List all groups |
113
+
114
+ ### Merge
115
+
116
+ | Command | Description |
117
+ |---------|-------------|
118
+ | `ov merge` | Merge agent branches into canonical (`--branch`, `--all`, `--into`, `--dry-run`, `--json`) |
119
+
120
+ ### Observability
121
+
122
+ | Command | Description |
123
+ |---------|-------------|
124
+ | `ov status` | Show all active agents, worktrees, tracker state (`--json`, `--verbose`, `--all`) |
125
+ | `ov dashboard` | Live TUI dashboard for agent monitoring (`--interval`, `--all`) |
126
+ | `ov inspect <agent>` | Deep per-agent inspection (`--follow`, `--interval`, `--no-tmux`, `--limit`, `--json`) |
127
+ | `ov trace` | View agent/task timeline (`--agent`, `--run`, `--since`, `--until`, `--limit`, `--json`) |
128
+ | `ov errors` | Aggregated error view across agents (`--agent`, `--run`, `--since`, `--until`, `--limit`, `--json`) |
129
+ | `ov replay` | Interleaved chronological replay (`--run`, `--agent`, `--since`, `--until`, `--limit`, `--json`) |
130
+ | `ov feed` | Unified real-time event stream (`--follow`, `--interval`, `--agent`, `--run`, `--json`) |
131
+ | `ov logs` | Query NDJSON logs across agents (`--agent`, `--level`, `--since`, `--until`, `--follow`, `--json`) |
132
+ | `ov costs` | Token/cost analysis and breakdown (`--live`, `--self`, `--agent`, `--run`, `--by-capability`, `--last`, `--json`) |
133
+ | `ov metrics` | Show session metrics (`--last`, `--json`) |
134
+ | `ov run list` | List orchestration runs (`--last`, `--json`) |
135
+ | `ov run show <id>` | Show run details |
136
+ | `ov run complete` | Mark current run as completed |
137
+
138
+ ### Infrastructure
139
+
140
+ | Command | Description |
141
+ |---------|-------------|
142
+ | `ov hooks install` | Install orchestrator hooks to `.claude/settings.local.json` (`--force`) |
143
+ | `ov hooks uninstall` | Remove orchestrator hooks |
144
+ | `ov hooks status` | Check if hooks are installed |
145
+ | `ov worktree list` | List worktrees with status |
146
+ | `ov worktree clean` | Remove completed worktrees (`--completed`, `--all`, `--force`) |
147
+ | `ov watch` | Start watchdog daemon — Tier 0 (`--interval`, `--background`) |
148
+ | `ov monitor start` | Start Tier 2 monitor agent |
149
+ | `ov monitor stop` | Stop monitor agent |
150
+ | `ov monitor status` | Show monitor state |
151
+ | `ov log <event>` | Log a hook event (`--agent`) |
152
+ | `ov clean` | Clean up worktrees, sessions, artifacts (`--completed`, `--all`, `--run`) |
153
+ | `ov doctor` | Run health checks on overstory setup (`--category`, `--fix`, `--json`) |
154
+ | `ov ecosystem` | Show os-eco tool versions and health (`--json`) |
155
+ | `ov upgrade` | Upgrade overstory to latest npm version (`--check`, `--all`, `--json`) |
156
+ | `ov agents discover` | Discover agents by capability/state/parent (`--capability`, `--state`, `--parent`, `--json`) |
157
+ | `ov completions <shell>` | Generate shell completions (bash, zsh, fish) |
158
+
159
+ ## Architecture
160
+
161
+ 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.
290
162
 
291
- ## Development
292
-
293
- ```bash
294
- # Run tests (2241 tests across 79 files)
295
- bun test
296
-
297
- # Run a single test
298
- bun test src/config.test.ts
299
-
300
- # Lint + format check
301
- biome check .
163
+ ## How It Works
302
164
 
303
- # Type check
304
- tsc --noEmit
165
+ 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.
305
166
 
306
- # All quality gates
307
- bun test && biome check . && tsc --noEmit
167
+ ```
168
+ Coordinator (persistent orchestrator at project root)
169
+ --> Supervisor (per-project team lead, depth 1)
170
+ --> Workers: Scout, Builder, Reviewer, Merger (depth 2)
308
171
  ```
309
172
 
310
- ### Versioning
311
-
312
- Version is maintained in two places that must stay in sync:
313
-
314
- 1. `package.json` — `"version"` field
315
- 2. `src/index.ts` — `VERSION` constant
173
+ ### Agent Types
316
174
 
317
- Use the bump script to update both:
175
+ | Agent | Role | Access |
176
+ |-------|------|--------|
177
+ | **Coordinator** | Persistent orchestrator — decomposes objectives, dispatches agents, tracks task groups | Read-only |
178
+ | **Supervisor** | Per-project team lead — manages worker lifecycle, handles nudge/escalation | Read-only |
179
+ | **Scout** | Read-only exploration and research | Read-only |
180
+ | **Builder** | Implementation and code changes | Read-write |
181
+ | **Reviewer** | Validation and code review | Read-only |
182
+ | **Lead** | Team coordination, can spawn sub-workers | Read-write |
183
+ | **Merger** | Branch merge specialist | Read-write |
184
+ | **Monitor** | Tier 2 continuous fleet patrol — ongoing health monitoring | Read-only |
318
185
 
319
- ```bash
320
- bun run version:bump <major|minor|patch>
321
- ```
186
+ ### Key Architecture
322
187
 
323
- Git tags, npm publishing, and GitHub releases are handled automatically by the `publish.yml` workflow when a version bump is pushed to `main`.
188
+ - **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.
189
+ - **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.)
190
+ - **Worktrees**: Each agent gets an isolated git worktree — no file conflicts between agents
191
+ - **Merge**: FIFO merge queue (SQLite-backed) with 4-tier conflict resolution
192
+ - **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
193
+ - **Tool Enforcement**: PreToolUse hooks mechanically block file modifications for non-implementation agents and dangerous git operations for all agents
194
+ - **Task Groups**: Batch coordination with auto-close when all member issues complete
195
+ - **Session Lifecycle**: Checkpoint save/restore for compaction survivability, handoff orchestration for crash recovery
196
+ - **Token Instrumentation**: Session metrics extracted from Claude Code transcript JSONL files
324
197
 
325
198
  ## Project Structure
326
199
 
@@ -353,7 +226,7 @@ overstory/
353
226
  logs.ts NDJSON log query
354
227
  feed.ts Unified real-time event stream
355
228
  run.ts Orchestration run lifecycle
356
- trace.ts Agent/bead timeline viewing
229
+ trace.ts Agent/task timeline viewing
357
230
  clean.ts Worktree/session cleanup
358
231
  doctor.ts Health check runner (10 check modules)
359
232
  inspect.ts Deep per-agent inspection
@@ -388,10 +261,21 @@ overstory/
388
261
  templates/ Templates for overlays and hooks
389
262
  ```
390
263
 
391
- ## License
264
+ ## Part of os-eco
392
265
 
393
- MIT
266
+ Overstory is part of the [os-eco](https://github.com/jayminwest/os-eco) AI agent tooling ecosystem.
267
+
268
+ ```
269
+ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ overstory orchestration
270
+ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ canopy prompts
271
+ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ seeds issues
272
+ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ mulch expertise
273
+ ```
274
+
275
+ ## Contributing
394
276
 
395
- ---
277
+ Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
396
278
 
397
- Inspired by: https://github.com/steveyegge/gastown/
279
+ ## License
280
+
281
+ MIT
package/agents/lead.md CHANGED
@@ -2,6 +2,15 @@
2
2
 
3
3
  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.
4
4
 
5
+ ## dispatch-overrides
6
+
7
+ Your overlay may contain a **Dispatch Overrides** section with directives from your coordinator. These override the default workflow:
8
+
9
+ - **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.
10
+ - **MAX AGENTS**: Limits the number of sub-workers you may spawn. Plan your decomposition to fit within this budget.
11
+
12
+ Always check your overlay for dispatch overrides before following the default three-phase workflow. If no overrides section exists, follow the standard playbook.
13
+
5
14
  ## cost-awareness
6
15
 
7
16
  **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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@os-eco/overstory-cli",
3
- "version": "0.6.10",
3
+ "version": "0.6.11",
4
4
  "description": "Multi-agent orchestration for Claude Code — spawn worker agents in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution",
5
5
  "author": "Jaymin West",
6
6
  "license": "MIT",
package/src/agents/hooks-deployer.test.ts CHANGED
@@ -820,6 +820,59 @@ describe("deployHooks", () => {
820
820
  expect(parsed.hooks.CustomEvent).toHaveLength(1);
821
821
  expect(parsed.hooks.CustomEvent[0].hooks[0].command).toBe("echo custom-event-hook");
822
822
  });
823
+
824
+ test("SessionStart hook includes mail check command with agent name", async () => {
825
+ const worktreePath = join(tempDir, "worktree");
826
+ await deployHooks(worktreePath, "my-agent");
827
+
828
+ const outputPath = join(worktreePath, ".claude", "settings.local.json");
829
+ const content = await Bun.file(outputPath).text();
830
+ const parsed = JSON.parse(content);
831
+
832
+ const sessionStart = parsed.hooks.SessionStart;
833
+ const allCommands = sessionStart.flatMap((entry: { hooks: { command: string }[] }) =>
834
+ entry.hooks.map((h) => h.command),
835
+ );
836
+ const mailCheckCmd = allCommands.find((cmd: string) =>
837
+ cmd.includes("ov mail check --inject --agent my-agent"),
838
+ );
839
+ expect(mailCheckCmd).toBeDefined();
840
+ });
841
+
842
+ test("SessionStart template entry has both prime and mail check hooks", async () => {
843
+ const worktreePath = join(tempDir, "worktree");
844
+ await deployHooks(worktreePath, "test-agent");
845
+
846
+ const outputPath = join(worktreePath, ".claude", "settings.local.json");
847
+ const content = await Bun.file(outputPath).text();
848
+ const parsed = JSON.parse(content);
849
+
850
+ const sessionStart = parsed.hooks.SessionStart;
851
+ const allCommands = sessionStart.flatMap((entry: { hooks: { command: string }[] }) =>
852
+ entry.hooks.map((h) => h.command),
853
+ );
854
+ const hasPrime = allCommands.some((cmd: string) => cmd.includes("ov prime --agent"));
855
+ const hasMailCheck = allCommands.some((cmd: string) => cmd.includes("ov mail check --inject"));
856
+ expect(hasPrime).toBe(true);
857
+ expect(hasMailCheck).toBe(true);
858
+ });
859
+
860
+ test("SessionStart mail check command includes PATH_PREFIX", async () => {
861
+ const worktreePath = join(tempDir, "worktree");
862
+ await deployHooks(worktreePath, "path-test");
863
+
864
+ const outputPath = join(worktreePath, ".claude", "settings.local.json");
865
+ const content = await Bun.file(outputPath).text();
866
+ const parsed = JSON.parse(content);
867
+
868
+ const sessionStart = parsed.hooks.SessionStart;
869
+ const allCommands = sessionStart.flatMap((entry: { hooks: { command: string }[] }) =>
870
+ entry.hooks.map((h) => h.command),
871
+ );
872
+ const mailCheckCmd = allCommands.find((cmd: string) => cmd.includes("ov mail check --inject"));
873
+ expect(mailCheckCmd).toBeDefined();
874
+ expect(mailCheckCmd).toContain(PATH_PREFIX);
875
+ });
823
876
  });
824
877
 
825
878
  describe("isOverstoryHookEntry", () => {
package/src/agents/hooks-deployer.ts CHANGED
@@ -20,13 +20,13 @@ const NON_IMPLEMENTATION_CAPABILITIES = new Set([
20
20
 
21
21
  /**
22
22
  * Capabilities that coordinate work and need git add/commit for syncing
23
- * beads, mulch, and other metadata — but must NOT git push.
23
+ * tasks, mulch, and other metadata — but must NOT git push.
24
24
  */
25
25
  const COORDINATION_CAPABILITIES = new Set(["coordinator", "supervisor", "monitor"]);
26
26
 
27
27
  /**
28
28
  * Additional safe Bash prefixes for coordination capabilities.
29
- * Allows git add/commit for beads sync, mulch records, etc.
29
+ * Allows git add/commit for task sync, mulch records, etc.
30
30
  * git push remains blocked via DANGEROUS_BASH_PATTERNS.
31
31
  */
32
32
  const COORDINATION_SAFE_PREFIXES = ["git add", "git commit"];
@@ -295,7 +295,7 @@ function buildBashGuardScript(agentName: string): string {
295
295
  "if echo \"$CMD\" | grep -qE 'git\\s+checkout\\s+-b\\s'; then",
296
296
  ` BRANCH=$(echo "$CMD" | sed 's/.*git\\s*checkout\\s*-b\\s*\\([^ ]*\\).*/\\1/');`,
297
297
  ` if ! echo "$BRANCH" | grep -qE '^overstory/${agentName}/'; then`,
298
- ` echo '{"decision":"block","reason":"Branch must follow overstory/${agentName}/{bead-id} convention"}';`,
298
+ ` echo '{"decision":"block","reason":"Branch must follow overstory/${agentName}/{task-id} convention"}';`,
299
299
  " exit 0;",
300
300
  " fi;",
301
301
  "fi;",
@@ -512,7 +512,7 @@ export function getCapabilityGuards(capability: string, qualityGates?: QualityGa
512
512
  );
513
513
  guards.push(...toolGuards);
514
514
 
515
- // Coordination capabilities get git add/commit whitelisted for beads/mulch sync
515
+ // Coordination capabilities get git add/commit whitelisted for task/mulch sync
516
516
  const extraSafe = COORDINATION_CAPABILITIES.has(capability)
517
517
  ? [...COORDINATION_SAFE_PREFIXES, ...gatePrefixes]
518
518
  : gatePrefixes;
package/src/agents/manifest.test.ts CHANGED
@@ -522,6 +522,7 @@ describe("resolveModel", () => {
522
522
  staggerDelayMs: 1000,
523
523
  maxDepth: 2,
524
524
  maxSessionsPerRun: 0,
525
+ maxAgentsPerLead: 5,
525
526
  },
526
527
  worktrees: { baseDir: ".overstory/worktrees" },
527
528
  taskTracker: { backend: "auto", enabled: false },