brains

BRAINS

Brainstorm Research Architect Implement Nurture Secure

A structured, multi-LLM development workflow plugin for Claude Code. Guides complex tasks through a three-phase pipeline, with optional multi-model debate and review at each stage.

Why three phases, just-in-time grooming, and per-phase review? See docs/why-brains.md for the design rationale — why forced brainstorming, sequential phases, focused teammate context, and star-chamber gating reduce token spend and rework compared to unstructured LLM coding.

How It Works

BRAINS encodes a three-phase methodology for tackling complex software tasks:

1. brains — Phase 1: interactive research, question-driven questionnaire, and RFC 2119 ADR production with auto-generated architecture diagrams. Default mode: --parallel with star-chamber review.
2. map — Phase 2: high-level plan generation (stub-level, not implementation-specific), with beads-based task tracking using brains:-prefixed labels.
3. implement — Phase 3: launches a fresh Claude Code teammate per plan-phase via agent-teams (preferred) or tmux. Each teammate grooms its tasks, executes them with fresh subagents, then runs nurture and secure reviews.

Each phase chains into the next via a user-approval gate — or, with --autopilot, skips those gates and runs hands-off from phase 1 through phase 3, stopping only on a brains:needs-human escalation. The nurture, secure, and diagram skills remain user-invocable for standalone use on any codebase.

For changes that only edit documents (prose, not code), /brains:document provides an abbreviated fast path that skips planning, teammate orchestration, and the nurture+secure passes — reviewing the final document(s) directly with the star-chamber council instead. It is a terminal alternate route: it ends after inline edits, council review, and its own commit, and never enters phases 2 (map) or 3 (implement). It is auto-invoked from phase 1 when a change is document-only and eligible, or requested explicitly via --document-mode. See Document mode.

See docs/diagrams.md for rendered examples of all five diagram types (flowchart, state, c4, er, sequence) — including the pipeline itself as a flowchart and a C4 context diagram of the plugin's components.

Prerequisites

Required:

• Claude Code — the plugin host

Required for multi-LLM modes (parallel, debate):

• uv — Python package manager
• star-chamber — multi-LLM council (PyPI, invoked via uvx star-chamber)
• Provider configuration at ~/.config/star-chamber/providers.json

Required for phase 3 (/brains:implement): either

• tmux installed, OR
• Claude Code agent-teams enabled (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings; Claude Code v2.1.32+)

Strongly recommended:

• beads — authoritative task tracker. Falls back to TaskCreate / TaskUpdate (tmux mode) or agent-teams' built-in task list (agent-teams mode) with degraded functionality.

Optional:

• Node.js ≥ 18.19 — powers the BRAINS! visual companion server (phase 1) and the mmdc fallback renderer for brains:diagram (Mermaid types only).
• podman or Docker — required for /brains:setup --with-kroki, which runs a local yuzutech/kroki gateway paired with the yuzutech/kroki-mermaid companion on a user-defined network. This is the preferred diagram renderer and the only path that supports --type c4 (Structurizr DSL); for Mermaid types, brains:diagram falls back to mmdc and then to source-only.

Installation

From GitHub:

# 1. Register the marketplace (one-time)
claude plugin marketplace add --github Epiphytic/brains

# 2. Install the plugin
claude plugin install brains@brains-marketplace

From a local clone:

# 1. Register the marketplace (one-time)
claude plugin marketplace add /path/to/brains

# 2. Install the plugin
claude plugin install brains@brains-marketplace

After installing, run /brains:setup --global to install dependencies and configure LLM providers, then /brains:setup --local in each project for project-specific settings. Add --with-kroki to either invocation to pull and run a local Kroki container as the diagram renderer — undo later with --without-kroki.