dual-brain 0.1.0

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "dual-brain",
+  "version": "0.1.0",
+  "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
+  "type": "module",
+  "bin": {
+    "dual-brain": "bin/dual-brain.mjs"
+  },
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./profile": "./src/profile.mjs",
+    "./detect": "./src/detect.mjs",
+    "./decide": "./src/decide.mjs",
+    "./dispatch": "./src/dispatch.mjs",
+    "./playbook": "./src/playbook.mjs",
+    "./health": "./src/health.mjs",
+    "./repo": "./src/repo.mjs",
+    "./session": "./src/session.mjs",
+    "./decompose": "./src/decompose.mjs",
+    "./brief": "./src/brief.mjs",
+    "./redact": "./src/redact.mjs"
+  },
+  "keywords": [
+    "claude-code",
+    "orchestrator",
+    "model-routing",
+    "code-review",
+    "dual-brain",
+    "gpt",
+    "claude",
+    "ai-agent"
+  ],
+  "author": "joshfair2@gmail.com",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1xmint/dual-brain.git"
+  },
+  "scripts": {
+    "test": "node .claude/hooks/test-orchestrator.mjs",
+    "test:core": "node --test src/test.mjs",
+    "postinstall": "echo 'dual-brain installed. Run: dual-brain install (in your project) to set up hooks.'"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "src/profile.mjs",
+    "src/detect.mjs",
+    "src/decide.mjs",
+    "src/dispatch.mjs",
+    "src/playbook.mjs",
+    "src/health.mjs",
+    "src/repo.mjs",
+    "src/session.mjs",
+    "src/decompose.mjs",
+    "src/brief.mjs",
+    "src/redact.mjs",
+    "src/index.mjs",
+    "src/tui.mjs",
+    "src/install-hooks.mjs",
+    "src/update-check.mjs",
+    "bin/*.mjs",
+    "hooks/enforce-tier.mjs",
+    "hooks/cost-logger.mjs",
+    "hooks/cost-report.mjs",
+    "hooks/dual-brain-review.mjs",
+    "hooks/dual-brain-think.mjs",
+    "hooks/quality-gate.mjs",
+    "hooks/test-orchestrator.mjs",
+    "hooks/setup-wizard.mjs",
+    "hooks/health-check.mjs",
+    "hooks/install-git-hooks.mjs",
+    "hooks/session-report.mjs",
+    "hooks/budget-balancer.mjs",
+    "hooks/gpt-work-dispatcher.mjs",
+    "hooks/profiles.mjs",
+    "hooks/summary-checkpoint.mjs",
+    "hooks/decision-ledger.mjs",
+    "hooks/control-panel.mjs",
+    "hooks/risk-classifier.mjs",
+    "hooks/failure-detector.mjs",
+    "hooks/vibe-router.mjs",
+    "hooks/plan-generator.mjs",
+    "hooks/vibe-memory.mjs",
+    "hooks/wave-orchestrator.mjs",
+    "hooks/task-classifier.mjs",
+    "hooks/model-registry.mjs",
+    "hooks/auto-update-wrapper.mjs",
+    "hooks/head-guard.mjs",
+    "hooks/auto-update.sh",
+    "mcp-server/*.mjs",
+    "mcp-server/README.md",
+    "install.mjs",
+    "orchestrator.json",
+    "review-rules.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "README.md",
+    "LICENSE",
+    "playbooks/*.json",
+    "plugin.json",
+    "skills/*.md",
+    "agents/*.md",
+    "shell-hook.sh"
+  ]
+}

package/playbooks/debug.json

@@ -0,0 +1,49 @@
+{
+  "name": "debug",
+  "description": "Structured bug resolution: reproduce, isolate, hypothesize root cause, fix minimally, verify with tests",
+  "matchIntents": ["debug", "fix"],
+  "steps": [
+    {
+      "id": "reproduce",
+      "title": "Reproduce the Failure",
+      "goal": "Find the failing code path. Identify the error message, stack trace, or unexpected behavior being reported. Locate the relevant source files, the entry point where the failure originates, and any existing tests that exercise this path. Confirm you understand the expected vs actual behavior.",
+      "tier": "search",
+      "consensus": false,
+      "output": { "kind": "analysis", "required": true }
+    },
+    {
+      "id": "isolate",
+      "title": "Isolate the Root Cause",
+      "goal": "Narrow down the root cause to a specific file, function, or line range. Trace the data flow from the failing callsite back to where the incorrect value or state originates. Check recent git changes to this code path. Identify the single most likely source of the problem before moving on.",
+      "tier": "search",
+      "consensus": false,
+      "output": { "kind": "analysis", "required": true }
+    },
+    {
+      "id": "hypothesize",
+      "title": "Form a Root Cause Hypothesis",
+      "goal": "Based on the isolated evidence, form a clear hypothesis about why the bug occurs. Consider: edge cases not handled, race conditions or ordering issues, incorrect assumptions about inputs or state, stale or shared mutable state, off-by-one errors, or API contract mismatches. State your hypothesis explicitly and explain what evidence supports it.",
+      "tier": "think",
+      "consensus": false,
+      "output": { "kind": "analysis", "required": true }
+    },
+    {
+      "id": "fix",
+      "title": "Implement the Minimal Fix",
+      "goal": "Implement the smallest change that fixes the bug according to the hypothesis. Do not refactor surrounding code, rename things, or improve unrelated areas. If a regression test for this bug does not exist, add one. The fix should be easy to review and easy to revert if wrong.",
+      "tier": "execute",
+      "consensus": false,
+      "gate": { "type": "diff-review", "requiredWhen": "high-risk" },
+      "output": { "kind": "patch", "required": true }
+    },
+    {
+      "id": "verify",
+      "title": "Verify Fix and Check for Regressions",
+      "goal": "Run the full test suite. Confirm the bug is no longer reproducible. Confirm no previously passing tests now fail. If regressions are found, determine whether they are related to the fix or pre-existing. Summarize: the root cause in one sentence, the fix applied, and the test evidence that the bug is resolved.",
+      "tier": "execute",
+      "consensus": false,
+      "gate": { "type": "test", "requiredWhen": "always" },
+      "output": { "kind": "summary", "required": true }
+    }
+  ]
+}

package/playbooks/refactor.json

@@ -0,0 +1,57 @@
+{
+  "name": "refactor",
+  "description": "Safe, verified refactoring: map callers, lock invariants, plan steps, apply, test, and confirm behavior preservation",
+  "matchIntents": ["refactor"],
+  "steps": [
+    {
+      "id": "understand",
+      "title": "Map the Target Code",
+      "goal": "Map the target code: find all callers and call sites, direct and transitive dependencies, existing tests that cover it, and any observable side effects. Document the current behavior contract — what it accepts, what it returns, what it mutates, and what errors it may throw.",
+      "tier": "search",
+      "consensus": false,
+      "output": { "kind": "analysis", "required": true }
+    },
+    {
+      "id": "invariants",
+      "title": "Identify Behavioral Invariants",
+      "goal": "Based on the code map, identify the behavioral invariants that MUST be preserved through the refactor: public API surface (function signatures, exported names), return types and shapes, error handling contracts, ordering guarantees, and any side effects callers depend on. This list is the acceptance criterion for the refactor.",
+      "tier": "think",
+      "consensus": false,
+      "output": { "kind": "checklist", "required": true }
+    },
+    {
+      "id": "plan",
+      "title": "Design the Refactor",
+      "goal": "Design the refactoring as a sequence of small, independently verifiable steps. For each step, describe: what changes, what stays the same, and how to verify it didn't break anything. Avoid big-bang rewrites. Each step should leave the codebase in a working state.",
+      "tier": "think",
+      "consensus": true,
+      "gate": { "type": "approval", "requiredWhen": "always" },
+      "output": { "kind": "plan", "required": true }
+    },
+    {
+      "id": "apply",
+      "title": "Apply the Refactoring",
+      "goal": "Implement the refactoring changes following the approved plan. Make minimal edits — do not improve unrelated code, fix unrelated bugs, or change formatting outside the target. Preserve all invariants identified in the invariants step. Commit or stage changes step by step if the plan has multiple stages.",
+      "tier": "execute",
+      "consensus": false,
+      "output": { "kind": "patch", "required": true }
+    },
+    {
+      "id": "verify",
+      "title": "Run Tests and Fix Regressions",
+      "goal": "Run the full existing test suite. For any failures, determine whether they are real regressions (the refactor broke behavior) or expected test updates (tests were asserting on internal structure that legitimately changed). Fix real regressions immediately. Update tests only where the old test was testing implementation detail, not behavior.",
+      "tier": "execute",
+      "consensus": false,
+      "gate": { "type": "test", "requiredWhen": "always" },
+      "output": { "kind": "test", "required": true }
+    },
+    {
+      "id": "confirm",
+      "title": "Confirm Behavior Preservation",
+      "goal": "Review the final diff against the invariants checklist. Confirm each invariant is still satisfied. Summarize: what structural changes were made, what behavioral aspects are provably unchanged, and whether there are any remaining risks or follow-up tasks.",
+      "tier": "think",
+      "consensus": false,
+      "output": { "kind": "summary", "required": true }
+    }
+  ]
+}

package/playbooks/security-audit.json

@@ -0,0 +1,57 @@
+{
+  "name": "security-audit",
+  "description": "Systematic security review: inventory, threat model, vulnerability scan, ranked findings, remediation plan",
+  "matchIntents": ["security"],
+  "steps": [
+    {
+      "id": "inventory",
+      "title": "Inventory Security-Sensitive Files",
+      "goal": "Identify all security-sensitive files in the codebase: auth modules, secret storage, .env files, API key usage, token handling, encryption routines, and permission checks. List each file with a one-line note on its security role.",
+      "tier": "search",
+      "consensus": false,
+      "output": { "kind": "checklist", "required": true }
+    },
+    {
+      "id": "threat-model",
+      "title": "Threat Model",
+      "goal": "Analyze the attack surface of this codebase. Identify threat actors (external users, internal users, third-party services), attack vectors (inputs, APIs, files, network), and trust boundaries. Categorize threats using STRIDE (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege) or a similar framework. Produce a structured threat model.",
+      "tier": "think",
+      "consensus": true,
+      "gate": { "type": "risk", "requiredWhen": "always" },
+      "output": { "kind": "analysis", "required": true }
+    },
+    {
+      "id": "vulnerability-scan",
+      "title": "Vulnerability Scan",
+      "goal": "Check the identified security-sensitive files for common vulnerabilities: hardcoded secrets or API keys, SQL injection, cross-site scripting (XSS), cross-site request forgery (CSRF), insecure deserialization, path traversal, missing or insufficient input validation, and improper error handling that leaks internals. List each finding with file, line reference, and a brief description.",
+      "tier": "search",
+      "consensus": false,
+      "output": { "kind": "checklist", "required": true }
+    },
+    {
+      "id": "exploitability-rank",
+      "title": "Exploitability Ranking",
+      "goal": "Rank the findings from the vulnerability scan by exploitability and impact using CVSS-style severity (Critical, High, Medium, Low). For each finding, estimate attack complexity and potential blast radius. Filter out false positives and explain your reasoning. Produce a ranked list with severity labels.",
+      "tier": "think",
+      "consensus": true,
+      "gate": { "type": "risk", "requiredWhen": "always" },
+      "output": { "kind": "analysis", "required": true }
+    },
+    {
+      "id": "remediation-plan",
+      "title": "Remediation Plan",
+      "goal": "For each confirmed vulnerability, propose a specific fix: name the exact file and line range, describe the code change needed, and explain why it closes the vulnerability. Prioritize fixes by severity (Critical first). Where a fix introduces new risk, call it out.",
+      "tier": "think",
+      "consensus": false,
+      "output": { "kind": "plan", "required": true }
+    },
+    {
+      "id": "summary",
+      "title": "Risk Assessment Summary",
+      "goal": "Produce a final risk assessment: total counts by severity (Critical/High/Medium/Low), top 3 priorities that must be addressed before the next release, and an estimate of residual risk after all proposed fixes are applied. Keep it concise — this is the executive summary.",
+      "tier": "think",
+      "consensus": false,
+      "output": { "kind": "summary", "required": true }
+    }
+  ]
+}

package/playbooks/security.json

@@ -0,0 +1,38 @@
+{
+  "name": "security-audit",
+  "description": "Structured security audit workflow: inventory, threat model, vulnerability scan, remediation plan",
+  "matchIntents": ["security"],
+  "steps": [
+    {
+      "id": "inventory",
+      "title": "Asset Inventory",
+      "goal": "Identify all security-sensitive files, endpoints, auth flows, and secret storage locations in the codebase",
+      "tier": "search",
+      "output": { "kind": "analysis", "required": true }
+    },
+    {
+      "id": "threat-model",
+      "title": "Threat Model",
+      "goal": "Map attack surfaces identified in inventory to STRIDE threat categories; call out critical trust boundaries and privilege escalation paths",
+      "tier": "think",
+      "consensus": true,
+      "output": { "kind": "analysis", "required": true }
+    },
+    {
+      "id": "vuln-scan",
+      "title": "Vulnerability Scan",
+      "goal": "Review each high-risk file from inventory for concrete vulnerabilities: injection, insecure defaults, secret leakage, broken auth, missing input validation",
+      "tier": "execute",
+      "output": { "kind": "findings", "required": true }
+    },
+    {
+      "id": "remediation-plan",
+      "title": "Remediation Plan",
+      "goal": "Produce a prioritised remediation plan: severity, affected file/line, recommended fix, and estimated effort for each finding",
+      "tier": "think",
+      "consensus": true,
+      "gate": "human-review",
+      "output": { "kind": "plan", "required": true }
+    }
+  ]
+}

package/playbooks/test-gen.json

@@ -0,0 +1,48 @@
+{
+  "name": "test-gen",
+  "description": "Targeted test generation: analyze behavior, design test cases, write tests, run them, and report coverage gaps",
+  "matchIntents": ["test"],
+  "steps": [
+    {
+      "id": "analyze",
+      "title": "Analyze Target Behavior",
+      "goal": "Identify the target code's observable behavior: all inputs and their valid ranges, outputs and their shapes, side effects (writes, network calls, mutations), error paths and what triggers them, and edge cases implied by the logic. Check existing test coverage to avoid duplicating what already exists.",
+      "tier": "search",
+      "consensus": false,
+      "output": { "kind": "analysis", "required": true }
+    },
+    {
+      "id": "design",
+      "title": "Design the Test Cases",
+      "goal": "Choose the appropriate test strategy: unit tests for isolated logic, integration tests for module boundaries, or end-to-end tests for full flows. Enumerate the specific test cases to write: happy path scenarios, edge cases (empty input, max values, nulls), error and exception paths, and boundary value cases. Justify the strategy choice based on what will give the most signal per test.",
+      "tier": "think",
+      "consensus": false,
+      "output": { "kind": "plan", "required": true }
+    },
+    {
+      "id": "generate",
+      "title": "Write the Tests",
+      "goal": "Write the tests following the design plan. Match the existing test framework, file naming conventions, describe/it or test() structure, assertion style, and helper patterns already used in this project. Each test should have a clear name that describes the scenario, not the implementation. Do not test internal state — test observable behavior.",
+      "tier": "execute",
+      "consensus": false,
+      "output": { "kind": "test", "required": true }
+    },
+    {
+      "id": "run",
+      "title": "Run Tests and Fix Test Bugs",
+      "goal": "Run the newly generated tests. If any fail, determine whether the failure is a bug in the test (wrong assertion, bad setup, incorrect expectation) or a real bug in the code under test. Fix test bugs only — do not change production code here unless a genuine pre-existing bug is discovered (if so, note it and leave it for a separate fix step). Ensure all generated tests pass.",
+      "tier": "execute",
+      "consensus": false,
+      "gate": { "type": "test", "requiredWhen": "always" },
+      "output": { "kind": "test", "required": true }
+    },
+    {
+      "id": "coverage",
+      "title": "Coverage Summary and Gap Analysis",
+      "goal": "Summarize the test coverage added: how many new test cases, which behaviors are now verified, and which code paths are exercised. Identify remaining gaps: behaviors that are hard to test (external dependencies, time-dependent logic, non-determinism) and explain why. Recommend follow-up tests if any critical paths remain untested.",
+      "tier": "think",
+      "consensus": false,
+      "output": { "kind": "summary", "required": true }
+    }
+  ]
+}

package/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "dual-brain",
+  "version": "7.1.4",
+  "description": "Dual-provider AI orchestration — smart routing between Claude and OpenAI",
+  "skills": [
+    { "name": "go", "description": "Route and dispatch a task", "file": "skills/go.md" },
+    { "name": "status", "description": "Show provider health and budget", "file": "skills/status.md" },
+    { "name": "think", "description": "Dual-brain architecture discussion", "file": "skills/think.md" },
+    { "name": "review", "description": "Dual-brain code review", "file": "skills/review.md" }
+  ],
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Edit|Write|NotebookEdit|Bash", "command": "node hooks/head-guard.mjs" },
+      { "matcher": "Agent", "command": "node hooks/enforce-tier.mjs" }
+    ]
+  },
+  "agents": [
+    { "name": "researcher", "file": "agents/researcher.md" },
+    { "name": "implementer", "file": "agents/implementer.md" },
+    { "name": "verifier", "file": "agents/verifier.md" }
+  ]
+}

package/review-rules.md

@@ -0,0 +1,17 @@
+# Review Rules
+
+Project-specific rules for GPT code review. Edit these for your repo.
+
+## Examples (replace with your own)
+
+### Framework & Tooling
+- Must use [your framework], not [alternative]
+- Must use [your package manager]
+- Must use [your database approach]
+
+### Code Patterns
+- Use [your utility function] for [specific math/formatting]
+- Import helpers from [canonical module path]
+
+### Domain Rules
+- [Your domain-specific invariants here]

package/shell-hook.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# dual-brain shell integration
+# Add to .bashrc with one command:
+#   dual-brain shell-hook >> ~/.bashrc
+# Or source directly:
+#   source /path/to/shell-hook.sh
+
+# Quick alias
+alias db='dual-brain'
+
+# Show session manager on new interactive terminal.
+# Skipped when:
+#   - not a TTY (non-interactive shell, CI, pipes)
+#   - DUAL_BRAIN_LOADED already set (prevents double-launch in nested shells)
+#   - DUAL_BRAIN_SKIP=1 (user opt-out)
+#   - DATA_TOOLS_LOADED or CLAUDE_MENU_LOADED is set (data-tools is managing the shell)
+if [ -t 1 ] \
+  && [ -z "$DUAL_BRAIN_LOADED" ] \
+  && [ -z "$DUAL_BRAIN_SKIP" ] \
+  && [ -z "$DATA_TOOLS_LOADED" ] \
+  && [ -z "$CLAUDE_MENU_LOADED" ]; then
+  export DUAL_BRAIN_LOADED=1
+  if command -v dual-brain &>/dev/null; then
+    dual-brain
+  fi
+fi

package/skills/go.md

@@ -0,0 +1,22 @@
+---
+name: go
+description: Route and dispatch a task through dual-brain
+arguments:
+  - name: task
+    description: The task description to route
+    required: true
+  - name: dry-run
+    description: Show routing without executing
+    required: false
+  - name: files
+    description: Comma-separated file paths for risk classification
+    required: false
+---
+
+Run `dual-brain go` with the provided arguments. Execute:
+
+```bash
+dual-brain go [--dry-run] [--files <files>] "<task>"
+```
+
+Report the routing decision (provider, model, tier) and dispatch result to the user.

package/skills/review.md

@@ -0,0 +1,19 @@
+---
+name: review
+description: Dual-brain code review — two-round Claude + GPT review of the current diff
+arguments: []
+---
+
+Run the dual-brain review flow (2 rounds) on the current git diff:
+
+**Round 1** — get GPT's independent review:
+```bash
+node hooks/dual-brain-review.mjs
+```
+
+Review the same diff independently, then run **Round 2** — share your findings and get GPT's response:
+```bash
+node hooks/dual-brain-review.mjs --round 2 --claude-review "<your findings>"
+```
+
+Synthesize both rounds into a final review verdict: shared findings, unique catches from each side, and any items that need human attention.

package/skills/status.md

@@ -0,0 +1,13 @@
+---
+name: status
+description: Show provider health, budget pressure, and enforcement status
+arguments: []
+---
+
+Run `dual-brain status` and report the results to the user:
+
+```bash
+dual-brain status
+```
+
+Show provider health (Claude, OpenAI), current budget pressure for each provider, active profile, and enforcement status.

package/skills/think.md

@@ -0,0 +1,22 @@
+---
+name: think
+description: Dual-brain architecture discussion — two-round Claude + GPT analysis
+arguments:
+  - name: question
+    description: The architecture question or decision to analyze
+    required: true
+---
+
+Run the dual-brain think flow (2 rounds) using the provided question:
+
+**Round 1** — get GPT's independent analysis:
+```bash
+node hooks/dual-brain-think.mjs --question "<question>"
+```
+
+Analyze the same question independently, then run **Round 2** — share your analysis and get GPT's response:
+```bash
+node hooks/dual-brain-think.mjs --question "<question>" --round 2 --claude-says "<your analysis>"
+```
+
+Synthesize both rounds into a final decision, noting agreements, disagreements, and the chosen recommendation.