dual-brain 4.1.0 → 4.5.0

package/CLAUDE.md

@@ -1,7 +1,33 @@
 # Dual-Brain Orchestrator
 
+> Extension of data-tools by Steve Moraco. Requires replit-tools for full functionality.
+
 This project uses dual-provider orchestration. Config: `.claude/orchestrator.json`.
 
+## Ship Captain — Primary Workflow
+
+The preferred way to start any task:
+
+```bash
+npx dual-brain do "fix the auth bug and write tests"
+```
+
+Automatically: decomposes goal → selects agents via intent detection → executes →
+runs tests → quality gate → self-heals issues (2 retries) → creates branch → opens PR.
+
+**Flags:**
+- `--yolo` — skip confirmations (still runs tests/gate, never auto-merges)
+- `--careful` — confirm every step
+- `--plan-only` — preview the plan without executing
+- `--no-pr` — skip PR creation
+
+**Intent detection** routes goals automatically: `fix`/`add` → execute chain, `explore`/`understand` → search-then-execute chain, `review` → dual-brain review chain.
+
+**Resume an incomplete run:**
+```bash
+npx dual-brain resume
+```
+
 ## Tier Routing
 
 Route subagents by task complexity:
@@ -10,56 +36,96 @@ Route subagents by task complexity:
 - **Execute** (`model: "sonnet"`): Edits, tests, git ops. Return: files changed, tests run, edge cases.
 - **Think** (main session, Opus): Architecture, review, planning. Return: decision, alternatives, risks.
 
+The `enforce-tier` hook **blocks** severe mismatches in auto/balanced/quality-first profiles rather than just warning.
+
+## Agent Templates
+
+Pre-built specialist agents for common tasks:
+
+```bash
+npx dual-brain agents                    # list all templates
+```
+
+Templates include `explorer`, `fixer`, `reviewer`, `tester`, and more. Ship Captain selects the right template automatically based on intent detection.
+
+## Agent Chains
+
+Multi-step workflows that compose templates:
+
+```bash
+npx dual-brain chains                    # list all chains
+npx dual-brain do "explore auth then fix" # auto-selects explore-then-fix chain
+```
+
+Built-in chains: `explore-then-fix`, `test-and-fix`, `review-and-apply`.
+
 ## GPT Lane
 
 For isolated or parallel work, dispatch to GPT via Codex CLI:
 
-- `node .claude/hooks/gpt-work-dispatcher.mjs --task "..." --model gpt-5.4` — execution tasks
+- `npx dual-brain dispatch --task "..." --model gpt-5.4` — execution tasks
 
 ## Dual-Brain Collaboration
 
-Dual-brain is a multi-round conversation between Claude and GPT — not a single-shot dispatch.
+Think and review now auto-complete the full 2-round dialogue by default.
 
 **Think flow** (architecture decisions):
-1. Round 1: `node .claude/hooks/dual-brain-think.mjs --question "..."`
-   → GPT gives independent analysis
-2. You analyze the same question independently
-3. Round 2: `node .claude/hooks/dual-brain-think.mjs --question "..." --round 2 --claude-says "<your analysis>"`
-   → GPT responds to your points: agreements, pushback, refined recommendation
+
+```bash
+npx dual-brain think --question "should we use Redis?"
+# → GPT Round 1 → Claude analysis → GPT Round 2 → Synthesis
+```
+
+Use `--manual` to step through rounds yourself:
+1. Round 1: `npx dual-brain think --question "..." --manual`
+2. You analyze independently
+3. Round 2: `npx dual-brain think --question "..." --round 2 --claude-says "<your analysis>"`
 4. You synthesize both rounds into a final decision
 
 **Review flow** (code review):
-1. Round 1: `node .claude/hooks/dual-brain-review.mjs`
-   → GPT reviews the diff independently
-2. You review the same diff independently
-3. Round 2: `node .claude/hooks/dual-brain-review.mjs --round 2 --claude-review "<your findings>"`
-   → GPT confirms shared findings, acknowledges misses, disputes false positives
-4. You synthesize into a final review verdict
+
+```bash
+npx dual-brain review
+# → GPT Round 1 → Claude review → GPT Round 2 → Final verdict
+```
+
+Use `--manual` for the old step-by-step flow.
 
 ## Routing Rules
 
 1. Tasks under 3 min → Claude (Codex startup overhead not worth it)
-2. Isolated tasks over 3 min → check balance: `node .claude/hooks/budget-balancer.mjs`
-3. High-risk decisions → dual-brain think
+2. Isolated tasks over 3 min → check balance: `npx dual-brain budget`
+3. High-risk decisions → dual-brain think (auto-triggered by hooks in auto mode)
 4. When a task spans tiers: think > execute > search
 
 ## Quality Gate
 
 Before ending a session with code changes:
-1. Run `node .claude/hooks/session-report.mjs`
-2. Run `node .claude/hooks/quality-gate.mjs`
+1. Run `npx dual-brain report`
+2. Run `npx dual-brain gate`
 
 Gate statuses: `pass` (safe to end), `issues_found` (fix first), `needs_human_review` (GPT unavailable).
 
+**Self-healing:** When Ship Captain is running, gate issues are automatically fixed and retried up to 2 times. Test failures are also auto-fixed (2 retries) before surfacing to the user.
+
+## Recovery
+
+```bash
+npx dual-brain doctor    # check system health and report issues
+npx dual-brain repair    # fix corrupt files, stale locks, re-register hooks
+npx dual-brain reset     # clear all state files (keeps config/hooks)
+npx dual-brain resume    # resume last incomplete Ship Captain run
+```
+
 ## Profiles
 
 Active profile controls routing posture, budgets, and quality gate behavior.
 Profile persists to `.claude/dual-brain.profile.json` (gitignored).
 
-- **auto** (default): Adapts routing based on task risk, provider health, and outcomes. Uses file-path risk classification and failure-loop detection to auto-escalate when needed.
-- **balanced**: Best model per tier, normal budgets, reviews at medium+ risk
-- **cost-saver**: Prefer cheaper models, lower budgets, skip GPT for non-critical
-- **quality-first**: Dual-brain for medium+ risk, higher budgets, stricter reviews
+- **auto** (default): Adapts routing based on task risk, provider health, and outcomes. Uses file-path risk classification and failure-loop detection to auto-escalate when needed. Blocks major tier mismatches.
+- **balanced**: Best model per tier, normal budgets, reviews at medium+ risk. Blocks major mismatches.
+- **cost-saver**: Prefer cheaper models, lower budgets, skip GPT for non-critical. Warns on major mismatches (does not block).
+- **quality-first**: Dual-brain for medium+ risk, higher budgets, stricter reviews. Blocks minor and major mismatches.
 
 Switch profiles: `npx dual-brain mode cost-saver`
 Check status: `npx dual-brain status`
@@ -81,32 +147,61 @@ Casual natural language → structured work. The vibe coding system translates i
 
 **Intent compiler** — decompose multi-task requests:
 ```bash
-node .claude/hooks/vibe-router.mjs "fix the login bug and also update the nav"
+npx dual-brain vibe "fix the login bug and also update the nav"
 ```
 Returns structured tasks with tier/risk classification, complexity level, quality gates, and wave strategy.
 
 **Plan generator** — Steve-style 3-part markdown plans:
 ```bash
-node .claude/hooks/plan-generator.mjs --utterance "..." [--write]
+npx dual-brain plan --utterance "..." [--write]
 ```
 Generates: (1) dependency-ordered task table, (2) user stories + edge cases, (3) questions with suggested answers. Pass `--write` to save to `.claude/plans/`.
 
 **Durable memory** — preferences persist across sessions:
 ```bash
-node .claude/hooks/vibe-memory.mjs                              # show state
-node .claude/hooks/vibe-memory.mjs --set preferences.risk_tolerance=careful
-node .claude/hooks/vibe-memory.mjs --threads                    # active work
-node .claude/hooks/vibe-memory.mjs --infer                      # preference suggestions
+npx dual-brain memory                              # show state
+npx dual-brain memory --set preferences.risk_tolerance=careful
+npx dual-brain memory --threads                    # active work
+npx dual-brain memory --infer                      # preference suggestions
 ```
 Tracks preferred profile, risk tolerance, active threads, and learns from usage patterns.
 
 ## Available Tools
 
-- `node .claude/hooks/vibe-router.mjs "..."` — decompose casual requests into structured work
-- `node .claude/hooks/plan-generator.mjs --utterance "..."` — generate execution plans
-- `node .claude/hooks/vibe-memory.mjs` — persistent preferences and work threads
-- `node .claude/hooks/cost-report.mjs` — activity and cost estimates
-- `node .claude/hooks/health-check.mjs` — verify system health
-- `node .claude/hooks/budget-balancer.mjs` — provider balance status
-- `node .claude/hooks/decision-ledger.mjs` — routing outcome insights
-- `node .claude/hooks/test-orchestrator.mjs` — run self-tests (40 tests)
+All commands available via `npx dual-brain <command>`:
+
+**Primary workflow:**
+- `npx dual-brain do "..."` — Ship Captain: goal → plan → execute → gate → PR
+- `npx dual-brain resume` — resume last incomplete run
+
+**Collaboration:**
+- `npx dual-brain think --question "..."` — dual-brain think (auto 2-round; `--manual` for step-by-step)
+- `npx dual-brain review` — dual-brain code review (auto 2-round; `--manual` for step-by-step)
+- `npx dual-brain dispatch --task "..."` — dispatch work to GPT
+
+**Vibe coding:**
+- `npx dual-brain vibe "..."` — decompose casual requests into structured work
+- `npx dual-brain plan --utterance "..."` — generate execution plans
+- `npx dual-brain memory` — persistent preferences and work threads
+
+**Agents and chains:**
+- `npx dual-brain agents` — list agent templates
+- `npx dual-brain chains` — list agent chains
+
+**Quality and reporting:**
+- `npx dual-brain gate` — run quality gate
+- `npx dual-brain report` — generate session report
+- `npx dual-brain cost` — activity and cost estimates
+- `npx dual-brain ledger` — routing outcome insights
+
+**Profiles and config:**
+- `npx dual-brain mode <profile>` — switch profile
+- `npx dual-brain status` — current profile and provider health
+- `npx dual-brain budget` — provider balance status
+
+**Recovery:**
+- `npx dual-brain doctor` — check system health and report issues
+- `npx dual-brain repair` — fix corrupt files, stale locks, re-register hooks
+- `npx dual-brain reset` — clear all state files (keeps config/hooks)
+- `npx dual-brain health` — verify all hooks and dependencies
+- `npx dual-brain test` — run self-tests (78 tests)

package/README.md

@@ -1,5 +1,10 @@
 # Dual-Brain Orchestrator
 
+> **Part of the [data-tools](https://github.com/stevemoraco) ecosystem by Steve Moraco**
+> 
+> dual-brain extends data-tools/replit-tools with dual-provider AI orchestration.
+> Best experienced with replit-tools installed for persistent auth, session management, and container survival.
+
 One command. Both brains. Auto-detected. Auto-configured. Default profile: **auto**.
 
 Dual-provider orchestration for Claude Code across Claude and OpenAI subscriptions. Routes search to cheap models, execution to mid-tier, thinking to the most capable. Dispatches work to GPT via Codex CLI. Dual-brain analysis for high-risk decisions.
@@ -36,10 +41,10 @@ npx -y dual-brain
 
 ## How it works
 
-**Two advisory hooks** are registered in `.claude/settings.json` and fire on each tool use. They detect and recommend — they do not execute actions without user confirmation:
+**Two enforcement hooks** are registered in `.claude/settings.json` and fire on each tool use:
 
-- **enforce-tier.mjs** (PreToolUse on Agent): Classifies tasks, recommends the correct model tier, detects duplicates, suggests cross-provider routing
-- **cost-logger.mjs** (PostToolUse on all tools): Logs usage to daily rotated files for cost tracking
+- **enforce-tier.mjs** (PreToolUse on Agent): Classifies tasks, assigns the correct model tier, detects duplicates, suggests cross-provider routing. **Blocks severe mismatches** — in auto/balanced/quality-first profiles, major tier mismatches return a hard block rather than a warning.
+- **cost-logger.mjs** (PostToolUse on all tools): Logs usage to daily rotated files for cost tracking.
 
 **Three tiers route work by complexity:**
 
@@ -49,7 +54,28 @@ npx -y dual-brain
 | Execute | Sonnet | GPT-5.4 | edits, tests, git ops |
 | Think | Opus | GPT-5.5 | architecture, review, planning |
 
-**Dual-brain** is recommended automatically for high-risk decisions — hooks detect the risk level and suggest dual-brain analysis, where both providers think on the same problem independently.
+**Dual-brain** is triggered automatically for high-risk decisions — hooks detect the risk level and initiate dual-brain analysis, where both providers think on the same problem independently. Think and review now run the full 2-round dialogue automatically in one command.
+
+**Intent detection** — the Ship Captain reads your natural language goal and routes it to the right chain automatically: `fix` → execute, `explore`/`understand` → search-then-execute, `review` → dual-brain review.
+
+**Self-healing** — gate issues and test failures are automatically retried up to 2 times before surfacing to the user.
+
+## Ship Captain — Intent to PR
+
+One command does everything:
+
+```bash
+npx dual-brain do "fix the auth bug and write tests"
+```
+
+Automatically: decomposes goal → selects agents → executes → runs tests →
+quality gate → self-heals issues (2 retries) → creates branch → opens PR.
+
+Flags:
+- `--yolo` — skip confirmations (still tests/gates, never merges)
+- `--careful` — confirm every step
+- `--plan-only` — preview without executing
+- `--no-pr` — skip PR creation
 
 ## Vibe Coding
 
@@ -57,10 +83,10 @@ Speak naturally. The orchestrator handles the structure.
 
 ```bash
 # Decompose a casual request into structured work
-node .claude/hooks/vibe-router.mjs "fix the login bug and also update the nav"
+npx dual-brain vibe "fix the login bug and also update the nav"
 
 # Generate a Steve-style execution plan
-node .claude/hooks/plan-generator.mjs --utterance "refactor the auth flow" --write
+npx dual-brain plan --utterance "refactor the auth flow" --write
 
 # Switch profiles with natural language
 npx dual-brain mode "go aggressive"
@@ -68,40 +94,163 @@ npx dual-brain mode "be careful"
 npx dual-brain mode "cheap"
 
 # Check persistent preferences and work threads
-node .claude/hooks/vibe-memory.mjs --threads
+npx dual-brain memory --threads
 ```
 
 The vibe-router splits multi-task requests, classifies risk, assigns tiers, and recommends quality gates. The plan-generator produces 3-part plans (dependency-ordered tasks, user stories, questions with suggested answers). Vibe-memory learns your preferences over time.
 
+## Automatic Collaboration
+
+Think and review now auto-complete the full 2-round dialogue:
+
+```bash
+npx dual-brain think --question "should we use Redis?"
+# → GPT Round 1 → Claude analysis → GPT Round 2 → Synthesis
+```
+
+Use `--manual` to step through rounds yourself (old behavior).
+
+## Agent Templates and Chains
+
+Pre-built specialist agents and opinionated multi-step workflows:
+
+```bash
+npx dual-brain agents                          # list all templates
+npx dual-brain chains                          # list all chains
+npx dual-brain do "explore auth then fix bug"  # auto-selects explore-then-fix chain
+```
+
+Templates include: `explorer`, `fixer`, `reviewer`, `tester`, and more. Chains compose templates into end-to-end workflows — `explore-then-fix`, `test-and-fix`, `review-and-apply`.
+
+## Commands
+
+### Primary workflow
+
+```bash
+npx dual-brain do "..."           # Ship Captain: goal → PR in one command
+npx dual-brain do "..." --yolo    # Skip confirmations
+npx dual-brain do "..." --careful # Confirm every step
+npx dual-brain do "..." --plan-only  # Preview plan without executing
+npx dual-brain do "..." --no-pr   # Skip PR creation
+npx dual-brain resume             # Resume last incomplete run
+```
+
+### Collaboration
+
+```bash
+npx dual-brain think --question "..."   # Dual-brain think (auto 2-round)
+npx dual-brain review                   # Dual-brain code review (auto 2-round)
+npx dual-brain dispatch --task "..."    # Dispatch task to GPT
+```
+
+### Vibe coding
+
+```bash
+npx dual-brain vibe "..."              # Decompose casual request
+npx dual-brain plan --utterance "..."  # Generate execution plan
+npx dual-brain memory                  # Show preferences and threads
+```
+
+### Agents and chains
+
+```bash
+npx dual-brain agents    # List agent templates
+npx dual-brain chains    # List agent chains
+```
+
+### Quality and reporting
+
+```bash
+npx dual-brain gate      # Run quality gate
+npx dual-brain report    # Session report
+npx dual-brain cost      # Activity and cost estimates
+npx dual-brain ledger    # Routing outcome insights
+```
+
+### Profiles and config
+
+```bash
+npx dual-brain mode cost-saver   # Switch profile
+npx dual-brain status            # Current profile and provider health
+npx dual-brain budget            # Provider balance status
+```
+
+### Recovery
+
+```bash
+npx dual-brain doctor    # Check system health and report issues
+npx dual-brain repair    # Fix corrupt files, stale locks, re-register hooks
+npx dual-brain reset     # Clear all state files (keeps config/hooks)
+npx dual-brain health    # Verify all hooks and dependencies
+```
+
+### Install
+
+```bash
+npx -y dual-brain              # detect, configure, install
+npx dual-brain --force          # overwrite all config
+npx dual-brain --dry-run        # detect only, don't write
+npx dual-brain --json           # output detection as JSON
+npx dual-brain --help           # show help
+npx dual-brain --uninstall      # remove hooks and clean state
+```
+
+## Profiles
+
+The active profile controls routing posture, budgets, and quality gate behavior. Default: **auto**.
+
+```bash
+npx dual-brain mode cost-saver   # switch profile
+npx dual-brain status            # check current profile and provider health
+```
+
+- **auto** (default): Adapts routing based on task risk, provider health, and outcomes. Auto-escalates tier on repeated failures. Blocks major tier mismatches.
+- **balanced**: Best model per tier, normal budgets, reviews at medium+ risk.
+- **cost-saver**: Prefer cheaper models, lower budgets, skip GPT for non-critical work. Warns on major mismatches (does not block).
+- **quality-first**: Dual-brain for medium+ risk, higher budgets, stricter reviews. Blocks both minor and major mismatches.
+
+## Troubleshooting
+
+**Hooks not firing** — Run `npx dual-brain doctor`. Check that `.claude/settings.json` has the hook entries. Run `npx dual-brain repair` to re-register.
+
+**Codex/GPT features unavailable** — Run `codex --version` and `codex login`. If Codex CLI isn't installed: `npm i -g @openai/codex`. Re-run `npx dual-brain` to detect.
+
+**Auth expired** — Run `claude login` for Claude, `codex login` for OpenAI. Re-run `npx dual-brain` to re-detect.
+
+**Duplicate warnings every time** — Normal during agent waves (3+ agents in 90s). The system auto-suppresses. If persistent with single agents, check for identical task descriptions.
+
+**Budget warnings too aggressive/too lenient** — Switch profile: `npx dual-brain mode cost-saver` or `npx dual-brain mode quality-first`. Or set custom limits with `npx dual-brain budget <session$> [daily$]`.
+
+**Corrupt state / weird behavior** — Run `npx dual-brain repair` for automatic fixes, or `npx dual-brain reset --force` to wipe all state files.
+
+**Multiple Claude Code sessions** — State files may have brief write conflicts. Each session tracks independently. Use a single session for best results.
+
+**Incomplete run** — Use `npx dual-brain resume` to continue where Ship Captain left off.
+
+**Uninstall** — `npx dual-brain --uninstall` removes hooks from settings.json and cleans state files.
+
 ## Scripts
 
 | Script | Purpose |
 |--------|---------|
+| `hooks/ship-captain.mjs` | End-to-end executor: goal → plan → execute → gate → PR |
+| `hooks/agent-templates.mjs` | Pre-built specialist agent templates |
+| `hooks/agent-chains.mjs` | Multi-step agent workflows (explore-then-fix, etc.) |
 | `hooks/vibe-router.mjs` | Decompose casual language into structured work orders |
 | `hooks/plan-generator.mjs` | Generate Steve-style 3-part execution plans |
 | `hooks/vibe-memory.mjs` | Persistent preferences, work threads, preference inference |
 | `hooks/cost-report.mjs` | Activity & cost estimates by model tier |
-| `hooks/dual-brain-review.mjs` | Send git diff to GPT for independent review |
-| `hooks/dual-brain-think.mjs` | Dual-perspective analysis on architecture decisions |
+| `hooks/dual-brain-review.mjs` | Dual-brain code review (auto 2-round) |
+| `hooks/dual-brain-think.mjs` | Dual-perspective analysis on architecture decisions (auto 2-round) |
 | `hooks/quality-gate.mjs` | Sensitivity-scored quality gate with review artifacts |
 | `hooks/budget-balancer.mjs` | Provider balance and routing recommendations |
 | `hooks/gpt-work-dispatcher.mjs` | Dispatch execution tasks to GPT via Codex CLI |
 | `hooks/session-report.mjs` | Session-end summary: activity, compliance, quality |
 | `hooks/health-check.mjs` | Verify all hooks and dependencies are working |
-| `hooks/test-orchestrator.mjs` | Self-test harness (40 tests) |
+| `hooks/test-orchestrator.mjs` | Self-test harness (78 tests) |
 | `hooks/setup-wizard.mjs` | Interactive config (optional — for custom plans) |
 | `hooks/install-git-hooks.mjs` | Git pre-commit hook for quality gate |
 
-## CLI options
-
-```bash
-npx -y dual-brain              # detect, configure, install
-npx dual-brain --force          # overwrite all config
-npx dual-brain --dry-run        # detect only, don't write
-npx dual-brain --json           # output detection as JSON
-npx dual-brain --help           # show help
-```
-
 ## Customize
 
 After install, edit these files:
@@ -110,24 +259,20 @@ After install, edit these files:
 - `review-rules.md` — project-specific rules for GPT code review
 - `settings.json` — hook registrations (auto-generated, safe to extend)
 
-## Profiles
-
-The active profile controls routing posture, budgets, and quality gate behavior. Default: **auto**.
-
-```bash
-npx dual-brain mode cost-saver   # switch profile
-npx dual-brain status            # check current profile and provider health
-```
-
-- **auto** (default): Adapts routing based on task risk, provider health, and outcomes. Auto-escalates tier on repeated failures.
-- **balanced**: Best model per tier, normal budgets, reviews at medium+ risk.
-- **cost-saver**: Prefer cheaper models, lower budgets, skip GPT for non-critical work.
-- **quality-first**: Dual-brain for medium+ risk, higher budgets, stricter reviews.
-
 ## Requirements
 
 - Node 20+
 - Claude Code (any subscription tier)
 - Codex CLI (optional) — `npm i -g @openai/codex && codex login`
+- replit-tools (recommended on Replit) — `npx -y replit-tools` — provides persistent auth, session management, and container survival
 
 Works with any subscription combination. Without OpenAI, GPT features gracefully degrade — all work routes through Claude.
+On Replit, replit-tools is strongly recommended — dual-brain's persistent state features depend on it.
+
+## Credits
+
+Built as an extension of **data-tools** by [Steve Moraco](https://github.com/stevemoraco).
+
+data-tools/replit-tools provides the foundation: persistent state across container restarts,
+multi-terminal session management, auto-updating scripts, and SSH key persistence.
+dual-brain adds dual-provider orchestration on top.