baro-ai 0.18.0 → 0.20.0

package/README.md

@@ -40,7 +40,10 @@ baro --model opus "Complex architecture redesign"
 # Disable model routing (use opus everywhere)
 baro --no-model-routing "Build entire app"
 
-# Resume interrupted execution
+# Dry run - generate plan without executing
+baro --dry-run "Add REST API"
+
+# Resume interrupted execution (or execute a dry-run plan)
 baro --resume
 
 # Specify working directory
@@ -66,13 +69,42 @@ baro --cwd ~/projects/myapp "Add REST API"
 - **Build detection** — auto-detects project type (Cargo, npm, Go, Python, Make) and runs builds during review
 - **Git coordination** — mutex-protected commits, auto-push with retry, pull --rebase, conflict detection
 - **Branch per run** — creates `baro/<name>` branch, keeps main clean
+- **Dry run** — `--dry-run` generates plan and saves to `prd.json` without executing, then `--resume` to run it
 - **Resume** — detects `prd.json` and resumes incomplete executions
 - **PR creation** — creates GitHub PR with stories table, stats, time saved, and review summary
 - **Configurable parallelism** — `--parallel N` to limit concurrent story execution
 - **Story timeout** — `--timeout SECONDS` kills stuck agents (default: 10 minutes)
 - **Time saved** — shows parallel speedup vs sequential execution
-- **System notifications** — terminal bell + OS notification (macOS/Linux) when done
+- **System notifications** — terminal bell + OS notification (macOS/Linux/Windows) when done
 - **Retry logic** — failed stories retry automatically (configurable per story)
+- **Interactive settings** — configure model, parallelism, timeout, context, and planner on the welcome screen with Tab/arrow keys
+- **Project config** — `.barorc` file in project root sets defaults (no CLI flags needed)
+- **Session lock** — prevents multiple baro instances from running in the same directory
+
+## Config file
+
+Create a `.barorc` in your project root to set defaults:
+
+```json
+{
+  "model": "routed",
+  "parallel": 3,
+  "timeout": 600,
+  "skipContext": false,
+  "planner": "claude"
+}
+```
+
+All fields are optional. CLI flags override `.barorc`, and interactive changes on the welcome screen override both.
+
+| Field | Values | Default |
+|-------|--------|---------|
+| `model` | `"routed"`, `"opus"`, `"sonnet"`, `"haiku"` | `"routed"` |
+| `parallel` | `0` (unlimited) or any number | `0` |
+| `timeout` | seconds per story | `600` |
+| `skipContext` | `true` / `false` | `false` |
+| `planner` | `"claude"`, `"openai"` | `"claude"` |
+| `dryRun` | `true` / `false` | `false` |
 
 ## Options
 
@@ -88,21 +120,90 @@ Options:
   --no-model-routing           Use opus for everything (disables routing)
   --parallel <N>               Max concurrent stories, 0 = unlimited (default: 0)
   --timeout <seconds>          Story timeout in seconds (default: 600)
-  --resume                     Resume from existing prd.json
+  --dry-run                    Generate plan only, save to prd.json, do not execute
+  --resume                     Resume from existing prd.json (also runs dry-run plans)
+  --skip-context               Skip CLAUDE.md auto-generation
   --cwd <path>                 Working directory (default: current)
+  --with-critic                Enable live Critic — reviews each agent turn
+                               against acceptance criteria via `claude --model haiku`
+                               and injects corrective feedback (default: off)
+  --critic-model <name>        Model for the Critic (default: haiku)
+  --no-librarian               Disable cross-agent runtime memory (default: on)
+  --no-sentry                  Disable file-touch conflict detector (default: on)
+  --with-surgeon               Enable adaptive DAG: drop / replace failing stories
+                               at level boundaries instead of stalling (default: off)
+  --surgeon-use-llm            Use `claude --model …` for richer Surgeon replans
+                               (default: deterministic skip-only)
+  --surgeon-model <name>       Model for Surgeon when --surgeon-use-llm is on
+                               (default: opus)
   -h, --help                   Print help
 ```
 
+### Phase 2/3/4 observers (Mozaik bus)
+
+baro 0.19+ runs every story through a TypeScript Mozaik orchestrator.
+Stories on the same DAG level run truly in parallel and observers can
+react to one another's bus events:
+
+- **Librarian** (default ON) — when one agent reads a file or runs grep,
+  later agents in the run see the digest in their prompt and skip the
+  redundant exploration. Measurable token savings on multi-story runs.
+- **Sentry** (default ON) — flags overlapping Edit/Write tool calls
+  across concurrent stories.
+- **Critic** (`--with-critic`, default OFF) — Haiku evaluator reviews
+  each agent turn against acceptance criteria; on a fail verdict, an
+  inline corrective message lands as the agent's next turn so it
+  self-corrects before commit.
+- **Surgeon** (`--with-surgeon`, default OFF) — when a story fails its
+  retry budget, a ReplanItem is emitted on the bus and the Conductor
+  recomputes the DAG at the next level boundary. The simplest mode just
+  drops failing stories so dependents unblock; with `--surgeon-use-llm`
+  Opus proposes splits, prerequisite inserts, or dependency rewires.
+
 ## Requirements
 
 - [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli) installed and authenticated
-- macOS (arm64/x64) or Linux (x64/arm64)
-- Node.js 18+ (only if using `--planner openai`)
+- macOS (arm64/x64), Linux (x64/arm64), or Windows (x64)
+- **Node.js 20+** (orchestrator runtime)
 - `gh` CLI (optional, for automatic PR creation)
 
+> **Windows note:** Windows 10+ is required. For best TUI experience, use [Windows Terminal](https://aka.ms/terminal) or another modern terminal emulator.
+
 ## Architecture
 
-Rust binary distributed via npm. TUI built with ratatui, async execution with tokio, one Claude CLI process per story.
+Rust binary distributed via npm. TUI built with ratatui, async execution
+with tokio. Each `baro` invocation spawns the bundled TypeScript
+[Mozaik](https://github.com/jigjoy-ai/mozaik) orchestrator as a
+subprocess; the orchestrator owns story execution and emits typed
+events into a shared `AgenticEnvironment` bus. Each story is one
+`claude` CLI subprocess (auth inherits from your Claude CLI session —
+no API key needed).
+
+The orchestrator is itself a Mozaik agentic environment: there is no
+imperative `run()` method, no top-level `Promise.all` loop. The
+**Conductor** is a state machine that reacts to typed bus events
+(`RunStartRequest` → `LevelComputeRequest` → `StorySpawnRequest` →
+`StoryResult` → `LevelCompleted` → …). Spawning a story, evaluating a
+turn, and replanning the DAG are all reactions, not steps in a loop.
+
+Ten participants share that bus:
+
+| Participant     | Role                                                              |
+| --------------- | ----------------------------------------------------------------- |
+| `Conductor`     | Orchestration state machine — drives the run by reacting          |
+| `StoryFactory`  | Spawns Story Agents on each `StorySpawnRequest`                   |
+| `StoryAgent`    | Runs one story via Claude CLI, with retries and timeout           |
+| `Librarian`     | Cross-agent memory — indexes outputs of exploration tools         |
+| `Sentry`        | Flags overlapping file writes across concurrent stories           |
+| `Critic`        | Per-turn acceptance-criteria evaluator (opt-in: `--with-critic`)  |
+| `Surgeon`       | Emits DAG replans when a story fails terminally (opt-in: `--with-surgeon`) |
+| `Operator`      | Bridges external user commands (TUI, web UI) into bus events      |
+| `Auditor`       | JSONL log of every event on the bus                               |
+| `Cartographer`  | Translates bus events into UI frames for the Rust TUI             |
+
+The bus is open. New participants — CI deployers, Slack notifiers,
+external ticket triggers — are subscribers and emitters with no changes
+to the orchestrator.
 
 ## License