Fix Overstory multi-agent setup and add quick reference docs

- Update agent models from gpt-5.3-codex to claude-compatible names (opus for coordinator/lead, sonnet for builder/scout/reviewer/merger, haiku for monitor) - Switch runtime from codex to claude (codex requires interactive TTY, incompatible with tmux-based agent spawning) - Add Overstory ecosystem links to AGENTS.md and CLAUDE.md - Add docs/overstory_quick_reference.md with startup, monitoring, and CLI commands - Sync seeds issue state Co-Authored-By: Claude Opus 4.6 <[email protected]>
2026-10-30 09:22:03 +00:00 · 2026-03-06 13:12:46 -05:00
1 parent 46ffff577b
commit ca31abf33e
@@ -3,7 +3,7 @@
 	"agents": {
 		"scout": {
 			"file": "scout.md",
-			"model": "gpt-5.3-codex",
+			"model": "sonnet",
 			"tools": [
 				"Read",
 				"Glob",
@@ -21,7 +21,7 @@
 		},
 		"builder": {
 			"file": "builder.md",
-			"model": "gpt-5.3-codex",
+			"model": "sonnet",
 			"tools": [
 				"Read",
 				"Write",
@@ -40,7 +40,7 @@
 		},
 		"reviewer": {
 			"file": "reviewer.md",
-			"model": "gpt-5.3-codex",
+			"model": "sonnet",
 			"tools": [
 				"Read",
 				"Glob",
@@ -58,7 +58,7 @@
 		},
 		"lead": {
 			"file": "lead.md",
-			"model": "gpt-5.3-codex",
+			"model": "opus",
 			"tools": [
 				"Read",
 				"Write",
@@ -78,7 +78,7 @@
 		},
 		"merger": {
 			"file": "merger.md",
-			"model": "gpt-5.3-codex",
+			"model": "sonnet",
 			"tools": [
 				"Read",
 				"Write",
@@ -96,7 +96,7 @@
 		},
 		"coordinator": {
 			"file": "coordinator.md",
-			"model": "gpt-5.3-codex",
+			"model": "opus",
 			"tools": [
 				"Read",
 				"Glob",
@@ -116,7 +116,7 @@
 		},
 		"monitor": {
 			"file": "monitor.md",
-			"model": "gpt-5.3-codex",
+			"model": "haiku",
 			"tools": [
 				"Read",
 				"Glob",
@@ -48,7 +48,7 @@ logging:
  verbose: false
  redactSecrets: true
 runtime:
-  default: codex
+  default: claude
  shellInitDelayMs: 0
  pi:
    provider: anthropic
@@ -1,6 +1,6 @@
-{"id":"SeedPass-9139","title":"TUI v2 Phase A: selection lifecycle","status":"in_progress","type":"task","priority":1,"createdAt":"2026-03-03T19:26:55.152Z","updatedAt":"2026-03-03T19:27:28.991Z","description":"Implement Phase A from docs/tui_v2_integration_execution_plan_2026-03-02.md: remove startup auto-selection, introduce a neutral inspector empty-state, and ensure deterministic selection transitions across the profile tree, grid, and inspector. Acceptance: TUI v2 launches with nothing selected, inspector stays empty until the user selects a node or row, and selection changes never leave stale detail in the inspector. Cover the behavior with interaction tests in src/tests/test_tui_v2_textual_interactions.py."}
-{"id":"SeedPass-9285","title":"TUI v2 Phase B: hierarchy tree + collapse","status":"open","type":"task","priority":1,"createdAt":"2026-03-03T19:26:57.067Z","updatedAt":"2026-03-03T19:26:57.067Z","description":"Deliver Phase B of docs/tui_v2_integration_execution_plan_2026-03-02.md. Build a real left-pane hierarchy that models fingerprints, managed users, and agents with expand/collapse behavior, and wire selection so the grid scope and ribbon respond to the active node. Add a sidebar collapse toggle with persistence so collapsing and expanding retains context. Tests: extend textual interaction/action-matrix suites to cover expand/collapse and scope updates."}
-{"id":"SeedPass-dbb2","title":"TUI v2 Phase C: ribbon + action strip rebuild","status":"open","type":"task","priority":1,"createdAt":"2026-03-03T19:26:58.813Z","updatedAt":"2026-03-03T19:26:58.813Z","description":"Execute Phase C from docs/tui_v2_integration_execution_plan_2026-03-02.md by rebuilding the top ribbon with fingerprint/profile counts, entry stats, filter summary, and sync timestamp plus a compact bottom action strip that separates global and context actions. Remove verbose default hints and ensure both regions remain readable at the target resolution (2256x1504) and in compact terminals. Update TUI interaction tests and capture screenshots/artifacts showing the new layout."}
+{"id":"SeedPass-9139","title":"TUI v2 Phase A: selection lifecycle","status":"closed","type":"task","priority":1,"createdAt":"2026-03-03T19:26:55.152Z","updatedAt":"2026-03-06T18:10:23.299Z","description":"Implement Phase A from docs/tui_v2_integration_execution_plan_2026-03-02.md: remove startup auto-selection, introduce a neutral inspector empty-state, and ensure deterministic selection transitions across the profile tree, grid, and inspector. Acceptance: TUI v2 launches with nothing selected, inspector stays empty until the user selects a node or row, and selection changes never leave stale detail in the inspector. Cover the behavior with interaction tests in src/tests/test_tui_v2_textual_interactions.py.","closedAt":"2026-03-06T18:10:23.299Z"}
+{"id":"SeedPass-9285","title":"TUI v2 Phase B: hierarchy tree + collapse","status":"closed","type":"task","priority":1,"createdAt":"2026-03-03T19:26:57.067Z","updatedAt":"2026-03-06T18:10:23.348Z","description":"Deliver Phase B of docs/tui_v2_integration_execution_plan_2026-03-02.md. Build a real left-pane hierarchy that models fingerprints, managed users, and agents with expand/collapse behavior, and wire selection so the grid scope and ribbon respond to the active node. Add a sidebar collapse toggle with persistence so collapsing and expanding retains context. Tests: extend textual interaction/action-matrix suites to cover expand/collapse and scope updates.","closedAt":"2026-03-06T18:10:23.348Z"}
+{"id":"SeedPass-dbb2","title":"TUI v2 Phase C: ribbon + action strip rebuild","status":"closed","type":"task","priority":1,"createdAt":"2026-03-03T19:26:58.813Z","updatedAt":"2026-03-06T18:10:23.392Z","description":"Execute Phase C from docs/tui_v2_integration_execution_plan_2026-03-02.md by rebuilding the top ribbon with fingerprint/profile counts, entry stats, filter summary, and sync timestamp plus a compact bottom action strip that separates global and context actions. Remove verbose default hints and ensure both regions remain readable at the target resolution (2256x1504) and in compact terminals. Update TUI interaction tests and capture screenshots/artifacts showing the new layout.","closedAt":"2026-03-06T18:10:23.392Z"}
 {"id":"SeedPass-95c5","title":"port TORCH memories over to os-eco and clean up repo in preperation of using the new agent swarm system.","status":"in_progress","type":"task","priority":2,"createdAt":"2026-03-03T19:39:38.333Z","updatedAt":"2026-03-03T20:57:45.886Z"}
 {"id":"SeedPass-3ecd","title":"Overstory parallel swarm smoke test","status":"in_progress","type":"task","priority":3,"createdAt":"2026-03-03T21:57:06.329Z","updatedAt":"2026-03-03T21:57:16.348Z","description":"Smoke run to validate multi-agent parallel execution, tmux sessions, and monitoring commands. No production code changes required."}
 {"id":"SeedPass-0806","title":"Overstory mail collaboration smoke after codex patch","status":"in_progress","type":"task","priority":2,"createdAt":"2026-03-04T01:45:50.381Z","updatedAt":"2026-03-04T01:45:58.388Z","description":"Verify >=2 agents can exchange ov mail in worktrees after codex runtime add-dir patch"}
@@ -1,5 +1,14 @@
 # Repository Guidelines

+## Overstory Ecosystem
+This project is part of the **Overstory** multi-agent development ecosystem. When asked to "update Overstory" or work on the ecosystem, these are the relevant repositories:
+
+- **[Overstory](https://github.com/jayminwest/overstory)** — The coordinator. Orchestrates multi-agent workflows across worktrees.
+- **[Mulch](https://github.com/jayminwest/mulch)** — Structured expertise/memory system for agents.
+- **[Canopy](https://github.com/jayminwest/canopy)** — Prompt management system for agents.
+- **[Seeds](https://github.com/jayminwest/seeds)** — Git-native issue tracker for agents.
+- **[os-eco](https://github.com/jayminwest/os-eco)** — The entire Overstory ecosystem (meta-repo/docs).
+
 This project is written in **Python**. Follow these instructions when working with the code base.

 ## Installation Quickstart for AI Agents
@@ -1,5 +1,14 @@
 # SeedPass Agent Guide

+## Overstory Ecosystem
+This project is part of the **Overstory** multi-agent development ecosystem. When asked to "update Overstory" or work on the ecosystem, these are the relevant repositories:
+
+- **[Overstory](https://github.com/jayminwest/overstory)** — The coordinator. Orchestrates multi-agent workflows across worktrees.
+- **[Mulch](https://github.com/jayminwest/mulch)** — Structured expertise/memory system for agents.
+- **[Canopy](https://github.com/jayminwest/canopy)** — Prompt management system for agents.
+- **[Seeds](https://github.com/jayminwest/seeds)** — Git-native issue tracker for agents.
+- **[os-eco](https://github.com/jayminwest/os-eco)** — The entire Overstory ecosystem (meta-repo/docs).
+
 ## Planning & Strategy
 Consult these first to align with current objectives:
 - **[Dev Control Center](docs/dev_control_center.md)**: Current priorities.
@@ -0,0 +1,137 @@
+# Overstory Quick Reference
+
+## Prerequisites
+
+Start a tmux server before launching any agents:
+
+```bash
+tmux new-session -d -s base
+```
+
+## Starting the Coordinator
+
+```bash
+ov coordinator start
+```
+
+This spawns the coordinator agent in a tmux session. It runs at the project root and orchestrates all other agents (leads, builders, scouts, reviewers, mergers).
+
+### Attach to the Coordinator Session
+
+```bash
+tmux attach -t overstory-SeedPass-coordinator
+```
+
+Detach without stopping: `Ctrl+b` then `d`
+
+### Stop the Coordinator
+
+```bash
+ov coordinator stop
+```
+
+## Monitoring
+
+### Status (snapshot)
+
+```bash
+ov status
+```
+
+Shows all active agents, their states, worktrees, and PIDs.
+
+### Dashboard (live TUI)
+
+```bash
+ov dashboard
+```
+
+Live-updating view of all agents. `Ctrl+C` to exit.
+
+### Coordinator Status
+
+```bash
+ov coordinator status
+```
+
+Shows coordinator-specific info: session ID, PID, uptime, watchdog/monitor state.
+
+### Event Feed (real-time log stream)
+
+```bash
+ov feed
+```
+
+Unified real-time event stream across all agents.
+
+## Agent Inspection
+
+```bash
+ov inspect <agent-name>    # Deep inspection of a single agent
+ov logs                     # Query logs across agents
+ov trace <agent-or-task>    # Chronological event timeline
+ov errors                   # Aggregated error view
+ov replay                   # Interleaved chronological replay
+```
+
+## Health Check
+
+```bash
+ov doctor
+```
+
+Runs diagnostics on the Overstory setup: config, databases, agents, dependencies, consistency.
+
+## Cleanup
+
+```bash
+ov clean --sessions       # Wipe sessions.db
+ov clean --worktrees      # Remove worktrees + kill tmux sessions
+ov clean --agents         # Remove agent identity files
+ov clean --all            # Nuclear: wipe everything
+```
+
+## Mail System
+
+```bash
+ov mail check                           # Check for unread messages
+ov mail list [--from <agent>] [--unread] # List messages
+ov mail read <id>                        # Read a message
+ov mail send --to <agent> --subject "..." --body "..." --type dispatch
+```
+
+## Costs & Metrics
+
+```bash
+ov costs       # Token/cost analysis
+ov metrics     # Session metrics
+```
+
+## Configuration
+
+Config file: `.overstory/config.yaml`
+
+Key settings:
+- `runtime.default: claude` — CLI runtime (options: claude, codex, pi, copilot, gemini). Note: `codex` does not work with tmux.
+- `agents.maxConcurrent: 25` — max simultaneous agents
+- `agents.maxDepth: 2` — hierarchy depth limit
+- `project.canonicalBranch: beta` — branch agents merge into
+
+Agent definitions: `.overstory/agent-defs/`
+Agent manifest: `.overstory/agent-manifest.json`
+
+## Ecosystem Tools
+
+| Tool | CLI | Purpose |
+|---|---|---|
+| [Overstory](https://github.com/jayminwest/overstory) | `ov` | Multi-agent coordinator |
+| [Mulch](https://github.com/jayminwest/mulch) | `mulch` / `ml` | Agent expertise/memory |
+| [Canopy](https://github.com/jayminwest/canopy) | `cn` | Prompt management |
+| [Seeds](https://github.com/jayminwest/seeds) | `sd` | Git-native issue tracking |
+| [os-eco](https://github.com/jayminwest/os-eco) | — | Ecosystem meta-repo |
+
+## Updating Tools
+
+```bash
+bun update -g @os-eco/overstory-cli @os-eco/mulch-cli @os-eco/canopy-cli @os-eco/seeds-cli
+```