╔══════════════════════════════════════════╗
  ║                                          ║
  ║   ██████  ██████   █████  ██ ██   ██     ║
  ║   ██   ██ ██   ██ ██   ██ ██ ███  ██     ║
  ║   ██████  ██████  ███████ ██ ██ █ ██     ║
  ║   ██   ██ ██   ██ ██   ██ ██ ██  ███     ║
  ║   ██████  ██   ██ ██   ██ ██ ██   ██     ║
  ║                                          ║
  ║   AI workflow orchestrator for           ║
  ║   Claude Code                            ║
  ║                                          ║
  ╚══════════════════════════════════════════╝

Brain turns Claude Code into a senior engineering team. It orchestrates 13 specialized AI agents through a structured lifecycle — from research to verified delivery — so you ship production-grade code, not prototypes.

39 commands 13 core + 22 specialist agents 10 hooks 1784 tests zero dependencies

The Problem

Claude Code is powerful but chaotic. You start building, lose context mid-session, forget what was decided, skip verification, and end up with code that works in demo but breaks in production. There's no structure, no audit trail, no enforcement.

The Solution

Brain adds structure without adding friction. Every step produces artifacts. Every decision is tracked. Every phase is verified before moving forward. And a hard pipeline gate prevents Claude from skipping steps.

/brain:new-project  →  Detects your stack, maps your codebase
/brain:story        →  Researches domain, creates roadmap with phases
/brain:discuss      →  Captures architectural decisions before coding
/brain:plan         →  Creates verified execution plans with TDD
/brain:execute      →  Builds with per-task commits and deviation handling
/brain:review       →  Two-stage review: spec compliance + code quality
/brain:verify       →  3-level verification against must-haves
/brain:complete     →  Advances to next phase with audit trail

Quick Start

npx brain-dev init

That's it. Brain detects your project (Laravel, Next.js, Django, FastAPI, Flask, Go, Python, Rails — 15+ frameworks), registers its agents, installs pipeline hooks, generates framework-specific stack commands, and is ready.

/brain:new-project           # Detect stack, map codebase
/brain:story "v1.0 MVP"     # Start a milestone with research + roadmap
/brain:progress              # Where am I? What's next?

Work Hierarchy

Brain provides four levels of work, from lightweight to comprehensive:

| Level | Commands | Pipeline | Duration | |-------|----------|----------|----------| | Quick | /brain:quick "fix bug" | plan → execute → review → commit | Minutes | | Task | /brain:new-task "add Stripe" | discuss → plan → execute → review → verify | Hours | | Story | /brain:story "v1.0 MVP" | research → requirements → roadmap → phases | Days/Weeks | | Project | /brain:new-project | detect → map → suggest next step | One-time |

Quick Tasks

Not everything needs a full phase. For small, focused work:

/brain:quick "fix the login redirect bug"         # plan → execute → review → commit
/brain:quick --full "add rate limiting to API"     # + verification gate

Significant Tasks

For features that need more than a quick fix but less than a full story:

/brain:new-task "add payment integration with Stripe"
/brain:new-task --light "fix auth redirect"       # Skip discuss + verify (research + review still mandatory)
/brain:new-task --continue                        # Resume current task
/brain:new-task --promote 1                       # Promote to roadmap phase

Stories

Stories are Brain's primary way to organize significant work. A story = a milestone.

/brain:story "v1.0 MVP"

Brain researches your domain with parallel agents, generates requirements with REQ-IDs, creates a phased roadmap, then guides execution phase by phase.

/brain:story --continue        # Resume current story step
/brain:story --list            # List all stories
/brain:story --complete        # Complete story, bump version
/brain:story --status          # Show story progress

How It Works

13 Core + Dynamic Specialist Agents

Brain doesn't use Claude as a single generalist. It orchestrates a team of specialists:

| Agent | Role | What It Does | |-------|------|-------------| | Researcher | Investigation | Analyzes technology, architecture, security, testing | | Synthesizer | Consolidation | Merges parallel research into actionable recommendations | | Planner | Architecture | Creates execution plans with dependency graphs and wave assignments | | Checker | Validation | Validates plans across 8 quality dimensions | | Executor | Implementation | Builds with TDD, atomic commits, and checkpoint protocol | | Reviewer | Code Quality | Reviews for DRY, over-engineering, framework best practices | | Spec Reviewer | Compliance | Verifies implementation matches plan requirements exactly | | Verifier | Verification | 3-level depth checks: exists, substantive, wired | | Debugger | Debugging | 4-phase scientific method with hypothesis tracking | | Mapper | Analysis | Deep codebase analysis (stack, architecture, quality) | | Test Generator | Testing | Generates tests from plan requirements and implementation summaries | | Requirements Generator | Requirements | Generates structured requirements with acceptance criteria from research | | Roadmap Architect | Roadmap | Creates strategically-phased roadmap with dependency analysis |

State Machine

Brain tracks progress through a deterministic state machine with 21 statuses and strict transition rules:

pending → discussing → discussed → planning → planned → executing → executed
                                                            ↓
                                              reviewing → reviewed → verifying → verified → complete

Every command knows what comes next. /brain:progress always tells you the right next step. Dangerous regressions (like going from verified back to discussing) are hard-blocked.

Pipeline Enforcement (4-Layer Defense)

Brain doesn't just suggest the next step — it enforces it with four hard layers:

1. Prompt injection — user-prompt-submit.sh injects <HARD-GATE> reminders when review is pending
2. CLI gates — requirePassedReview() blocks completion without status: passed in REVIEW.md — no --force bypass
3. Git commit hook — pre-tool-use.sh blocks git commit during post-execution phases without passed review
4. State machine — executed→verifying transition removed; review step cannot be skipped at FSM level

Code review is mandatory in every pipeline (quick, light, standard, story). Claude cannot bypass it.

Stack Intelligence System

Brain auto-detects your stack and generates technology-specific specialist agents:

• 9 frameworks with specialist agents: Laravel (Eloquent Expert, Artisan Specialist), Next.js (App Router Expert, RSC Specialist), Django (ORM Expert, DRF Specialist), FastAPI, React Native (Navigation Expert, Expo Specialist), NestJS, Vue.js, Express, SvelteKit
• 15+ frameworks detected: + Flask, Rails, Flutter, Spring Boot, Astro, and more
• Auto-generated specialists: brain-dev init creates .claude/agents/brain-stack-*.md for your framework
• Enrichment command: /brain:enrich generates specialist agents + stack profile with Context7 MCP docs
• Stack profile: .brain/stack/profile.json stores capabilities, Context7 ID, and agent list
• 3-layer expertise: Static patterns + specialist agents + Context7 live documentation
• Infrastructure detection: Docker, CI/CD, monorepo tools, Python ecosystem
• Stack commands: Auto-generates /stack:* commands (e.g., /stack:migrate, /stack:test)

/brain:detect                  # Re-scan project stack and infrastructure
/brain:detect --json           # Machine-readable detection output

Deep Research System

Brain enforces research depth before planning with a scored gate:

• Research Scorer — 7-dimension quality scoring: word depth, section structure, version specificity, source credibility, risk awareness, actionable recommendations, code examples
• Research Gate — mandatory depth check before planning with 3 adaptive profiles:
  • quick (threshold: 25) — bug fixes, small changes
  • standard (threshold: 45) — features, refactors
  • deep (threshold: 65) — major features, migrations, security
• Micro-Research — executors can trigger on-demand focused investigation mid-task via brain-researcher agent

Research that doesn't meet the threshold is sent back for deepening. No shallow analysis passes through to planning.

Plan Quality Scoring

Plans are scored on 6 dimensions before execution:

| Dimension | Weight | What It Checks | |-----------|--------|----------------| | Coverage | 20 | Are all requirements addressed? | | Task Completeness | 20 | Do tasks have behavior, action, verify, done? | | Dependency Soundness | 15 | Are file dependencies consistent? | | TDD Presence | 15 | Do tasks specify test behaviors? | | Scope Control | 15 | Within bounds (≤8 files, 2-4 tasks)? | | Specificity | 15 | Are file paths explicit, not vague? |

Cross-plan analysis detects files modified in multiple plans (merge conflict risk).

Wave-Aware Execution

Plans with wave: N in frontmatter are grouped. Independent plans in the same wave run in parallel worktrees/subagents:

/brain:execute                    # Wave-aware: parallel plans spawn parallel executors

Closed-Loop Test Feedback

The executor receives live test status from .brain/.test-bridge.json:

• all-passing → continue
• minor-failures (<20%) → continue with caution
• concerning (20-50%) → review failures
• critical (>50%) → STOP and fix

Post-Execution Quality Gate

Before phase completion, an execution audit scores results:

• Plan completion (30%) — all plans have summaries
• Self-check (25%) — summaries contain "Self-Check: PASSED"
• File existence (25%) — key files referenced in summaries exist on disk
• Must-haves (20%) — plan truths addressed

Auto Mode

Run phases autonomously without human intervention:

/brain:auto                     # Start autonomous execution
/brain:auto --dry-run           # Preview runbook without executing
/brain:auto --stop              # Stop auto mode, release lock
/brain:auto --phase 3           # Start from a specific phase

Auto mode chains: discuss → plan → execute → review → verify → complete → next phase, with:

• Budget limits and cost projection
• Stuck detection and timeout tiers
• Error recovery decision tree
• Loop detection (same step fails 3x → stop)

Monitoring & Observability

Dashboard

/brain:dashboard                # TUI dashboard in terminal
/brain:dashboard --browser      # Open web dashboard in browser (WebSocket real-time)
/brain:dashboard --watch        # Auto-refresh TUI every 3 seconds
/brain:dashboard --json         # Machine-readable output
/brain:dashboard --stop         # Stop running web dashboard server

Shows phase progress, cost tracking, timeout status, lock state, and recent events. Web dashboard pushes live state updates over WebSocket every 2 seconds.

Cost Tracking

Brain tracks token usage and estimates cost per agent, per phase:

/brain:progress --cost          # Show budget status
/brain:config set budget.ceiling_usd 50  # Set spending ceiling
/brain:config set budget.mode hard-stop  # Block when exceeded

Three budget modes: warn (default), pause, hard-stop.

Stuck Detection

Multi-source progress detection with configurable timeout tiers:

| Tier | Default | What Happens | |------|---------|-------------| | Soft | 20 min | Warning: "Consider wrapping up" | | Idle | 5 min no progress | Alert: "Agent may be stuck" | | Hard | 45 min | Force: "Commit WIP and stop" |

Two-Stage Review

Brain's review system runs two independent passes:

/brain:review                  # Both passes: spec compliance + code quality
/brain:review --spec-only      # Only check: does implementation match plan?
/brain:review --quality-only   # Only check: DRY, patterns, best practices

Pass 1 — Spec Compliance: The spec-reviewer agent extracts every must_have from plans and verifies each one against the implementation. Produces SPEC-REVIEW.md with PASS/FAIL/PARTIAL per requirement.

Pass 2 — Code Quality: The reviewer agent checks for DRY violations, over-engineering, anti-patterns, and framework best practices. Produces REVIEW.md.

Git Worktree Isolation

Execute phases in isolated git worktrees to prevent unfinished work from contaminating your main branch:

/brain:execute --worktree      # Execute in isolated worktree branch

Brain creates a brain/phase-* branch, executes in the worktree, and merges back on successful completion.

Test Generation

Automatically generate tests from plan requirements and implementation:

/brain:add-tests               # Generate tests for current phase
/brain:add-tests --phase 3     # Generate tests for specific phase

Reads PLAN must_haves, SUMMARY implementation details, and VERIFICATION results. Detects your test framework (Jest/Vitest/pytest/PHPUnit) and generates targeted test files.

Assumption Surfacing

Surface hidden assumptions before planning to prevent costly mid-phase pivots:

/brain:assumptions             # Surface assumptions for current phase
/brain:assumptions --phase 3   # Surface assumptions for specific phase

Covers: implementation approach, dependencies/prerequisites, scope boundaries, and risk areas.

Audit & Auto-Fix

/brain:audit                   # Audit milestone integration
/brain:audit --auto-fix        # Find gaps and auto-generate remediation phases
/brain:audit --phase 3         # Audit a single phase

When --auto-fix finds gaps (missing review, missing verification, orphan requirements), it automatically inserts targeted remediation phases into the roadmap.

Session Management

/brain:pause                    # Save session state for later
/brain:resume                   # Restore session context
/brain:recover                  # Detect and recover from crashes
/brain:health                   # Self-diagnosis and auto-repair

Brain handles context window pressure, session crashes, and stale locks automatically. The bootstrap.sh hook restores context on every new session.

Additional Tools

| Command | Description | |---------|-------------| | /brain:storm | Real-time brainstorming server with WebSocket | | /brain:design | Collaborative design server — component canvas with WebSocket | | /brain:adr | Architecture Decision Records — auto-created from discussions | | /brain:map | Deep codebase analysis (stack, architecture, quality) | | /brain:debug | Standalone debugging with 4-phase scientific method | | /brain:detect | Re-scan project stack, Python deps, Docker, CI/CD, monorepo | | /brain:uat | User Acceptance Testing — conversational criteria verification | | /brain:ship | Generate PR descriptions from verified phase artifacts | | /brain:todo | Extract and track TODOs from codebase | | /brain:config | 47 settings across 10 categories |

Plugin System

Extend Brain with custom commands, agents, and hooks:

.brain/plugins/
└── my-plugin/
    ├── plugin.json            # { name, version, commands, agents, hooks }
    ├── commands/
    │   └── my-command.cjs     # Custom command handler
    └── templates/
        └── my-agent.md        # Custom agent template

Plugin commands are namespaced (my-plugin:my-command) and automatically registered in the command and agent registries.

Configuration

Brain has three model profiles for cost optimization:

/brain:config set agents.profile quality    # Best models everywhere
/brain:config set agents.profile balanced   # Quality for planning, efficient for checking
/brain:config set agents.profile budget     # Minimize token cost

Key settings:

/brain:config set mode interactive          # Ask before major decisions
/brain:config set mode auto                 # Full autonomy
/brain:config set depth standard            # Standard verification
/brain:config set depth thorough            # Deep verification
/brain:config set enforcement.level hard    # Strict pipeline enforcement

Export and import configuration across projects:

/brain:config export > brain-config.json
/brain:config import brain-config.json

All Commands

Setup

| Command | Description | |---------|-------------| | /brain:init | Initialize brain in current project | | /brain:new-project | Detect project, map codebase, suggest next step | | /brain:detect | Re-scan project stack, framework, and infrastructure | | /brain:enrich | Generate specialist agents + stack profile with Context7 docs | | /brain:update | Update brain-dev to latest version | | /brain:upgrade | Version upgrade with hook migration |

Lifecycle

| Command | Description | |---------|-------------| | /brain:story | Start a milestone with research, requirements, roadmap | | /brain:discuss | Capture architectural decisions before coding | | /brain:assumptions | Surface assumptions before planning | | /brain:plan | Create verified execution plans with TDD | | /brain:execute | Build according to plans with atomic commits (--worktree for isolation) | | /brain:review | Two-stage review: spec compliance + code quality | | /brain:verify | 3-level verification against must-haves | | /brain:complete | Mark phase or milestone done, advance | | /brain:auto | Autonomous execution across phases |

Tasks

| Command | Description | |---------|-------------| | /brain:quick | Quick task — skip the ceremony | | /brain:new-task | Significant task — full pipeline | | /brain:todo | Extract and track TODOs from codebase | | /brain:add-tests | Generate tests from plan requirements |

Phase Management

| Command | Description | |---------|-------------| | /brain:phase | List, peek, remove, reorder phases | | /brain:audit | Integration checker + milestone audit (--auto-fix for gap closure) | | /brain:uat | User Acceptance Testing | | /brain:ship | Generate PR from verified phase |

Session

| Command | Description | |---------|-------------| | /brain:progress | Current status and next action | | /brain:pause | Save session for later | | /brain:resume | Restore session context | | /brain:recover | Detect and recover from crashes | | /brain:health | Self-diagnosis and auto-repair | | /brain:dashboard | Live monitoring dashboard (--browser for web, --watch for auto-refresh) |

Tools

| Command | Description | |---------|-------------| | /brain:storm | Real-time brainstorming server | | /brain:design | Collaborative design server with WebSocket | | /brain:adr | Architecture decision records | | /brain:map | Deep codebase analysis | | /brain:debug | Standalone debugging sessions | | /brain:config | Configuration management | | /brain:remove | Remove phase or task |

v3 → v4 Migration Guide

Breaking Changes

| Area | v3 Behavior | v4 Behavior | |------|------------|------------| | Error handling | process.exit(1) with string messages | Structured BrainError classes with error codes | | State transitions | Soft warnings for invalid transitions | Hard-blocked with FatalError (use --force to override) | | Phase status | Some aliases accepted (in progress) | Canonical lowercase only (executing) — auto-migrated | | State writes | Direct fs.writeFileSync | atomicWriteSync prevents corruption on crash | | Agent count | 9 agents | 13 agents (added test-generator, spec-reviewer, requirements-generator, roadmap-architect) | | Config system | Basic key/value | 47 settings, 10 categories, cross-field validation |

How to Upgrade

# Update to latest version
npx brain-dev upgrade

# Re-run detection with new capabilities (Python, Docker, CI/CD, monorepo)
/brain:detect

# Regenerate hooks and commands
/brain:init --force

Error Envelope Format (v4+)

All errors now return structured envelopes:

{
  "ok": false,
  "error": {
    "code": "PHASE_INVALID_STATUS",
    "message": "Invalid phase status: 'foo'",
    "recovery": "Use --force flag to override"
  }
}

--force Flag

v6.4+ enforces code review unconditionally. --force only bypasses phase-order validation and research gates — it cannot bypass review or verify gates:

brain-dev execute --force               # Skip phase order validation
brain-dev plan --force                  # Skip research gate

Tutorial: Build Your First Feature

A step-by-step walkthrough of the brain lifecycle.

1. Initialize

npx brain-dev init
# Output:
#   [brain] Created .brain/ directory
#   [brain] Platform: claude-code
#   [brain] Registered SessionStart hook
#   [brain] Registered brain commands
#   [brain] Generated 3 stack commands for Next.js
#   [brain] Committed: chore: initialize brain

2. Detect & Map Your Project

/brain:new-project
# Brain detects your stack (e.g., "Next.js (typescript) with Testing, Tailwind CSS")
# Detects infrastructure: Docker, GitHub Actions CI, Turborepo monorepo
# Maps your codebase structure and suggests next step

3. Start a Story

/brain:story "v1.0 User Authentication"
# Brain runs parallel research agents → generates requirements → creates phased roadmap
# You'll see: REQUIREMENTS.md with REQ-IDs, ROADMAP.md with phases

4. Surface Assumptions

/brain:assumptions
# Lists assumptions about implementation approach, dependencies, scope, and risks
# Review and validate before planning begins

5. Discuss Decisions

/brain:discuss
# Brain asks about architectural decisions for the current phase
# e.g., "JWT or session-based auth? What token expiry?"
# Decisions saved to CONTEXT.md for planner reference

6. Plan

/brain:plan
# Creates PLAN-01.md with tasks, dependencies, must_haves
# Plan checker validates across 8 dimensions
# Advocate challenges weak points

7. Execute

/brain:execute
# Executor builds according to plan with per-task commits
# Each task: implement → test → commit
# SUMMARY-01.md documents what was done

# Optional: execute in isolated worktree
/brain:execute --worktree

8. Review

/brain:review
# Pass 1: Spec compliance — does implementation match plan?
# Pass 2: Code quality — DRY, patterns, best practices
# SPEC-REVIEW.md + REVIEW.md with findings

9. Verify

/brain:verify
# 3-level verification: exists → substantive → wired
# VERIFICATION.md with pass/fail per must_have

10. Complete

/brain:complete
# Marks phase done, advances to next phase
# /brain:progress shows what's next

Lifecycle Diagram

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  new-project │────>│    story     │────>│ assumptions  │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                                │
                                        ┌──────▼──────┐
                                        │   discuss    │
                                        └──────┬──────┘
                                                │
                    ┌─────────────┐     ┌──────▼──────┐
                    │   complete   │<────│    plan      │
                    └──────┬──────┘     └──────┬──────┘
                           │                    │
                    ┌──────▼──────┐     ┌──────▼──────┐
                    │   verify     │<────│   execute    │
                    └──────┬──────┘     └──────┬──────┘
                           │                    │
                           │            ┌──────▼──────┐
                           │<───────────│   review     │
                           │            └─────────────┘

Architecture

Modular State Management

Brain's state engine is decomposed into focused modules:

| Module | Responsibility | |--------|---------------| | state-io.cjs | Atomic read/write with crash protection | | state-migration.cjs | Schema versioning and additive migrations | | state-transitions.cjs | Phase status validation with transition rules | | state-md.cjs | Human-readable STATE.md generation | | state-defaults.cjs | Default state creation and constants | | state.cjs | Backward-compatible re-export facade | | session-memory.cjs | Semantic memory: decisions, entities, patterns | | research-scorer.cjs | 7-dimension research quality scoring | | research-gate.cjs | Mandatory research depth gate | | plan-scorer.cjs | 6-dimension plan quality scoring | | test-feedback.cjs | Closed-loop test result analysis | | wave-planner.cjs | Wave-aware parallel execution planner | | execution-audit.cjs | Post-execution quality gate |

Dynamic Command Loading

Commands declare a handler field in the registry. The CLI dispatches directly to the handler module. 39 commands across 6 categories: Setup, Lifecycle, Tasks, Phase Management, Session, Tools.

Platform

Brain is currently Claude Code-exclusive, with deep integration via settings.json hooks and shell scripts.

Project Structure

.brain/                          # Brain state directory
├── brain.json                   # State machine + configuration
├── STATE.md                     # Human-readable state summary
├── detection.json               # Stack detection cache
├── REQUIREMENTS.md              # Requirements with REQ-IDs
├── ROADMAP.md                   # Phased execution roadmap
├── metrics.json                 # Cost tracking ledger
├── phases/                      # Phase artifacts
│   └── 01-setup/
│       ├── PLAN-01.md           # Execution plan
│       ├── SUMMARY-01.md        # Execution results
│       ├── SPEC-REVIEW.md       # Spec compliance review
│       ├── REVIEW.md            # Code quality review
│       └── VERIFICATION.md      # Verification results
├── stories/                     # Milestone archives
├── designs/                     # Design server outputs
├── plugins/                     # Installed plugins
├── debug/                       # Debug sessions
├── logs/                        # JSONL event logs
└── audits/                      # Audit reports

Zero Dependencies

Brain is a single npm package with zero runtime dependencies. Just Node.js 22+.

{
  "dependencies": {}
}

No supply chain risk. No transitive vulnerabilities. No node_modules bloat.

Requirements

• Node.js 22+
• Claude Code (Anthropic's CLI)

License

MIT