brain-dev 0.1.0

package/commands/brain/discuss.md

@@ -0,0 +1,35 @@
+---
+name: brain:discuss
+description: Capture implementation decisions for a phase
+argument-hint: "<phase>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Capture implementation decisions, constraints, and technical context for a specific phase before planning begins.
+Creates a CONTEXT.md file that feeds into the planning process.
+</objective>
+
+<context>
+`$ARGUMENTS` is the phase number (e.g., `1`, `2`).
+</context>
+
+<process>
+1. Run the brain CLI for the given phase:
+```bash
+npx brain-dev discuss $ARGUMENTS
+```
+
+2. The CLI will present implementation questions and trade-offs. Use AskUserQuestion to gather the user's preferences on each decision point.
+
+3. Review the generated CONTEXT.md to confirm all decisions are captured accurately.
+
+4. **Next step:** Run `/brain:plan $ARGUMENTS` to create execution plans informed by these decisions.
+</process>

package/commands/brain/execute.md

@@ -0,0 +1,38 @@
+---
+name: brain:execute
+description: Execute all plans in a phase with wave-based agents
+argument-hint: "<phase> [--gaps-only]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Execute all plans in a phase using wave-based parallel execution.
+Discovers plans, analyzes dependencies, groups into waves, spawns subagents, and collects results.
+</objective>
+
+<context>
+`$ARGUMENTS` contains the phase number and optional flags:
+- `--gaps-only` — Execute only gap closure plans created by verify
+</context>
+
+<process>
+1. Run the brain CLI to execute plans:
+```bash
+npx brain-dev execute $ARGUMENTS
+```
+
+2. The CLI groups plans into dependency-ordered waves and executes each wave in parallel via subagents. Monitor progress as each wave completes.
+
+3. Report results per wave: which plans succeeded, which failed, and any errors encountered.
+
+4. Verification runs automatically after execution. Review the verification output.
+
+5. **Next step:** If all verified, run `/brain:discuss {next_phase}` for the next phase. If gaps found, run `/brain:plan {phase} --gaps` to create fix plans.
+</process>

package/commands/brain/health.md

@@ -0,0 +1,33 @@
+---
+name: brain:health
+description: Diagnose issues and auto-repair
+argument-hint: "[--fix] [--quick]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+---
+<objective>
+Diagnose project health issues including broken references, missing files, inconsistent state, and configuration problems.
+Optionally auto-repairs safe issues with --fix.
+</objective>
+
+<context>
+`$ARGUMENTS` contains optional flags:
+- `--fix` — Automatically repair detected issues that are safe to fix
+- `--quick` — Run only critical checks, skip deep analysis
+</context>
+
+<process>
+1. Run the brain CLI to check health:
+```bash
+npx brain-dev health $ARGUMENTS
+```
+
+2. Review the diagnostic output. Report issues found grouped by severity (critical, warning, info).
+
+3. If `--fix` was used, confirm which issues were auto-repaired and which still need manual attention.
+</process>

package/commands/brain/map.md

@@ -0,0 +1,35 @@
+---
+name: brain:map
+description: Run codebase mapper with 4 focus agents
+argument-hint: "[--focus tech|arch|quality|concerns]"
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+  - Task
+---
+<objective>
+Spawn 4 mapper agents to analyze the codebase from different perspectives (tech, architecture, quality, concerns).
+Generates 7 documents in .brain/codebase/ including a security scan.
+</objective>
+
+<context>
+`$ARGUMENTS` contains optional flags:
+- `--focus tech` — Focus on technology stack and dependencies
+- `--focus arch` — Focus on architecture and patterns
+- `--focus quality` — Focus on code quality and test coverage
+- `--focus concerns` — Focus on risks, debt, and security concerns
+</context>
+
+<process>
+1. Run the brain CLI to map the codebase:
+```bash
+npx brain-dev map $ARGUMENTS
+```
+
+2. The CLI spawns 4 focus agents that analyze the codebase in parallel. Wait for all agents to complete.
+
+3. Review the generated documents in .brain/codebase/. Present a summary of key findings from each focus area, highlighting any security concerns.
+</process>

package/commands/brain/new-project.md

@@ -0,0 +1,38 @@
+---
+name: brain:new-project
+description: Initialize a new project with guided questioning
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Start a new brain project through interactive questioning to establish scope, goals, and initial roadmap.
+Creates PROJECT.md, REQUIREMENTS.md, and ROADMAP.md with the gathered context.
+</objective>
+
+<context>
+No arguments required. The CLI handles interactive setup.
+</context>
+
+<process>
+1. Run the brain CLI to start the guided project creation flow:
+```bash
+npx brain-dev new-project
+```
+
+2. The CLI auto-detects whether this is a new or existing project:
+   - **New project (greenfield):** Asks vision-first questions about what you want to build
+   - **Existing project (brownfield):** Analyzes the codebase first, then asks context-aware questions about what to add/change. Also spawns mapper agents to deeply analyze the existing stack and architecture.
+
+3. Follow the interactive prompts and provide answers via AskUserQuestion.
+
+4. Review the generated files: PROJECT.md, REQUIREMENTS.md, and ROADMAP.md. Confirm the project structure looks correct.
+
+5. **Next step:** Run `/brain:discuss 1` to capture implementation decisions for the first phase.
+</process>

package/commands/brain/pause.md

@@ -0,0 +1,26 @@
+---
+name: brain:pause
+description: Save work state for session continuity
+allowed-tools:
+  - Read
+  - Bash
+---
+<objective>
+Save the current work state to .continue-here.md so work can be restored in a future session.
+Safe to close the session after this command completes.
+</objective>
+
+<context>
+No arguments required. Captures current session state automatically.
+</context>
+
+<process>
+1. Run the brain CLI to save state:
+```bash
+npx brain-dev pause $ARGUMENTS
+```
+
+2. Confirm that .continue-here.md was created with the current phase, pending tasks, and context.
+
+3. Inform the user it is safe to close the session. To restore later, use `/brain:resume`.
+</process>

package/commands/brain/plan.md

@@ -0,0 +1,38 @@
+---
+name: brain:plan
+description: Create verified execution plans for a phase
+argument-hint: "<phase> [--research] [--gaps] [--skip-verify]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Create detailed, executable PLAN.md files for a roadmap phase with integrated research, planning, and checker verification.
+Default flow: Research (if needed) -> Plan -> Verify -> Done.
+</objective>
+
+<context>
+`$ARGUMENTS` contains the phase number and optional flags:
+- `--research` — Force re-research even if RESEARCH.md exists
+- `--gaps` — Gap closure mode: reads VERIFICATION.md and creates fix plans
+- `--skip-verify` — Skip the verification loop after plan creation
+</context>
+
+<process>
+1. Run the brain CLI to generate plans:
+```bash
+npx brain-dev plan $ARGUMENTS
+```
+
+2. The CLI researches domain context, creates step-by-step plans, and verifies them against requirements. It iterates until plans pass verification or max iterations are reached.
+
+3. Review the generated PLAN.md files. Confirm the plans cover all phase requirements and the checker passed.
+
+4. **Next step:** Run `/brain:execute $ARGUMENTS` to execute the plans with wave-based agents.
+</process>

package/commands/brain/progress.md

@@ -0,0 +1,28 @@
+---
+name: brain:progress
+description: Show project status and next action
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+<objective>
+Display current project status including phase progress, pending tasks, and recommended next action.
+Read-only command with no side effects.
+</objective>
+
+<context>
+No arguments required. Reads project state automatically.
+</context>
+
+<process>
+1. Run the brain CLI to check progress:
+```bash
+npx brain-dev progress
+```
+
+2. Review the output: current phase, plan completion percentages, blockers, and suggested next command.
+
+3. Present a summary to the user showing where the project stands and what to do next.
+</process>

package/commands/brain/quick.md

@@ -0,0 +1,51 @@
+---
+name: brain:quick
+description: Execute quick tasks without full phase ceremony
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Agent
+  - AskUserQuestion
+---
+<objective>
+Execute a quick, atomic task with plan → execute → (optional verify) → commit.
+Bypasses the full discuss → plan → execute → verify lifecycle.
+</objective>
+
+<context>
+Quick tasks live in `.brain/quick/` separate from planned phases.
+Use `--full` flag for plan checking + verification.
+</context>
+
+<agents>
+Use subagent_type "brain-planner" for planning.
+Use subagent_type "brain-executor" for execution.
+Use subagent_type "brain-verifier" for verification (--full mode only).
+</agents>
+
+<process>
+1. Run: `npx brain-dev quick [--full] "task description"`
+   - CLI creates task directory, generates planner prompt
+   - Spawn brain-planner agent with the provided prompt
+   - Wait for planner to complete
+
+2. Run: `npx brain-dev quick --execute --task N`
+   - CLI generates executor prompt from the plan
+   - Spawn brain-executor agent with the provided prompt
+   - Wait for executor to complete
+
+3. (Only with --full) Run: `npx brain-dev quick --verify --task N`
+   - CLI generates verifier prompt
+   - Spawn brain-verifier agent
+   - Wait for verification
+
+4. Run: `npx brain-dev quick --complete --task N`
+   - CLI outputs STATE.md update instructions and commit file list
+   - Update STATE.md and commit artifacts
+
+Follow the `nextAction` field in each CLI output to know the next command.
+</process>

package/commands/brain/resume.md

@@ -0,0 +1,28 @@
+---
+name: brain:resume
+description: Restore work from previous session
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+<objective>
+Restore work state from .continue-here.md and re-establish context for continued work.
+Picks up exactly where the previous session left off.
+</objective>
+
+<context>
+No arguments required. Reads the most recent saved state automatically.
+</context>
+
+<process>
+1. Run the brain CLI to restore state:
+```bash
+npx brain-dev resume
+```
+
+2. Review the restored context: active phase, in-progress plans, and what was happening when the session was paused.
+
+3. Present a summary to the user and suggest the next action to continue work seamlessly.
+</process>

package/commands/brain/storm.md

@@ -0,0 +1,30 @@
+---
+name: brain:storm
+description: Launch visual brainstorming server
+argument-hint: "[topic] [--stop] [--port <port>]"
+allowed-tools:
+  - Read
+  - Bash
+---
+<objective>
+Start a WebSocket-based brainstorming server with an interactive browser interface.
+Sessions are stored in .brain/storm/ for later reference.
+</objective>
+
+<context>
+`$ARGUMENTS` contains optional topic and flags:
+- `[topic]` — Seed the session with an initial brainstorming topic
+- `--stop` — Stop a running brainstorming server
+- `--port <port>` — Use a specific port for the server
+</context>
+
+<process>
+1. Run the brain CLI to start (or stop) the brainstorming server:
+```bash
+npx brain-dev storm $ARGUMENTS
+```
+
+2. If starting: the CLI launches the server and opens the browser. Report the URL to the user.
+
+3. If `--stop` was used: confirm the server was shut down. Session data remains in .brain/storm/.
+</process>

package/commands/brain/verify.md

@@ -0,0 +1,39 @@
+---
+name: brain:verify
+description: Verify completed work against must-haves
+argument-hint: "<phase> [--auto-recover]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Run 3-level verification of completed phase work against defined must-have requirements and acceptance criteria.
+Produces a VERIFICATION.md report with pass/gaps/human_needed status.
+</objective>
+
+<context>
+`$ARGUMENTS` contains the phase number and optional flags:
+- `--auto-recover` — Automatically create and execute gap closure plans for failures
+</context>
+
+<process>
+1. Run the brain CLI to verify the phase:
+```bash
+npx brain-dev verify $ARGUMENTS
+```
+
+2. The CLI checks all completed work against phase requirements at 3 levels. Review the VERIFICATION.md report.
+
+3. Report the outcome:
+   - **pass** — All requirements met. Proceed to next phase.
+   - **gaps** — Some requirements unmet. Fix plans needed.
+   - **human_needed** — Issues requiring manual intervention.
+
+4. **Next step:** If gaps found, run `/brain:plan $ARGUMENTS --gaps` to create fix plans. If all passed, run `/brain:complete` to archive the milestone.
+</process>

package/hooks/bootstrap.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# Brain SessionStart hook -- injects project context into Claude Code
+# Registered in .claude/settings.json during brain-dev init
+
+BRAIN_DIR="${CLAUDE_PROJECT_DIR:-.}/.brain"
+
+# Clean stale bridge file from previous session
+rm -f "$BRAIN_DIR/.context-bridge.json"
+
+# Pre-project state
+if [ ! -f "$BRAIN_DIR/brain.json" ]; then
+  echo "[brain] Ready. No project yet. Run /brain:new-project to begin."
+  exit 0
+fi
+
+# Get status and format for context injection
+# Use npx to ensure brain-dev is found regardless of install method
+STATUS=$(npx brain-dev status --json 2>/dev/null)
+
+if [ $? -ne 0 ] || [ -z "$STATUS" ]; then
+  echo "[brain] Warning: Could not read project state."
+  exit 0
+fi
+
+# Format output for Claude Code context (target: 500-800 tokens)
+echo "$STATUS" | node -e "
+const fs = require('fs');
+try {
+  const raw = fs.readFileSync('/dev/stdin', 'utf8');
+  const data = JSON.parse(raw);
+  const lines = [
+    '--- Brain Context ---',
+    'Project: ' + (data.project && data.project.name || 'unnamed'),
+    'Phase: ' + (data.phase && data.phase.current || 0) + ' (' + (data.phase && data.phase.status || 'initialized') + ')',
+    'Next: ' + (data.nextAction || '/brain:new-project'),
+    '',
+    'Commands: /brain:new-project, /brain:discuss, /brain:plan, /brain:execute, /brain:verify, /brain:complete, /brain:quick, /brain:progress, /brain:pause, /brain:resume, /brain:help, /brain:health, /brain:storm, /brain:adr, /brain:phase, /brain:config, /brain:map',
+    '',
+    'Instructions for Claude:',
+    '- When user types /brain:<command>, run: npx brain-dev <command> [args]',
+    '- Read output and present results. Follow any instructions in output.',
+    '- Use /brain:progress to check current state before suggesting next steps.',
+    '--- End Brain Context ---'
+  ];
+  console.log(lines.join('\n'));
+} catch(e) {
+  console.log('[brain] Ready. Run /brain:progress for status.');
+}
+" 2>/dev/null
+
+# Quick health check: auto-repair safe issues silently
+if [ -f "$BRAIN_DIR/brain.json" ]; then
+  npx brain-dev health --quick 2>/dev/null
+fi

package/hooks/post-tool-use.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# hooks/post-tool-use.sh
+# PostToolUse hook for Claude Code - reads bridge file and injects context warnings
+# Does NOT receive context_window data - reads from bridge file written by StatusLine
+
+BRAIN_DIR="${CLAUDE_PROJECT_DIR:-.}/.brain"
+BRIDGE="$BRAIN_DIR/.context-bridge.json"
+
+# If bridge file doesn't exist, exit silently (normal early in session)
+if [ ! -f "$BRIDGE" ]; then
+  exit 0
+fi
+
+# Use node -e to read bridge file and check level (no jq dependency)
+node -e "
+  const fs = require('fs');
+  try {
+    const bridge = JSON.parse(fs.readFileSync('$BRIDGE', 'utf8'));
+    const level = bridge.level;
+    const pct = bridge.context_remaining_pct;
+
+    if (level === 'critical') {
+      const output = {
+        hookSpecificOutput: {
+          hookEventName: 'PostToolUse',
+          additionalContext: '[brain] CRITICAL: Context at ' + pct + '% remaining. Consider running /brain:pause to save state and continue in a fresh session.'
+        }
+      };
+      console.log(JSON.stringify(output));
+    } else if (level === 'warning') {
+      const output = {
+        hookSpecificOutput: {
+          hookEventName: 'PostToolUse',
+          additionalContext: '[brain] WARNING: Context at ' + pct + '% remaining. Start wrapping up current task.'
+        }
+      };
+      console.log(JSON.stringify(output));
+    }
+    // normal level: no output needed
+  } catch {
+    // Bridge file unreadable/corrupt - exit silently
+  }
+" 2>/dev/null
+
+exit 0

package/hooks/statusline.sh

@@ -0,0 +1,130 @@
+#!/bin/bash
+# hooks/statusline.sh
+# StatusLine script for Claude Code - displays brain status with context bar
+# Receives session JSON on stdin with context_window data
+# Writes bridge file for PostToolUse to read
+
+BRAIN_DIR="${CLAUDE_PROJECT_DIR:-.}/.brain"
+BRIDGE="$BRAIN_DIR/.context-bridge.json"
+BRIDGE_TMP="$BRIDGE.tmp"
+
+# Guard: if brain.json doesn't exist, output minimal status and exit
+if [ ! -f "$BRAIN_DIR/brain.json" ]; then
+  echo "brain | not initialized"
+  exit 0
+fi
+
+# Read stdin
+input=$(cat)
+
+# Use node -e to parse data, write bridge file, and output status line
+# No jq dependency - consistent with bootstrap.sh pattern
+node -e "
+  const fs = require('fs');
+
+  const input = (() => {
+    try { return JSON.parse(process.argv[1] || '{}'); }
+    catch { return {}; }
+  })();
+
+  // Extract context window data
+  const cw = input.context_window || {};
+  const usedPct = cw.used_percentage;
+  const remainPct = cw.remaining_percentage;
+
+  // Read brain.json for project name and thresholds
+  let projectName = 'brain';
+  let warningThreshold = 35;
+  let criticalThreshold = 25;
+  let phaseCurrent = '';
+  let phaseStatus = '';
+
+  try {
+    const brain = JSON.parse(fs.readFileSync('$BRAIN_DIR/brain.json', 'utf8'));
+    projectName = (brain.project && brain.project.name) || 'brain';
+    if (brain.monitoring) {
+      warningThreshold = brain.monitoring.warning_threshold || 35;
+      criticalThreshold = brain.monitoring.critical_threshold || 25;
+    }
+    if (brain.phase) {
+      phaseCurrent = brain.phase.current || '';
+      phaseStatus = brain.phase.status || '';
+    }
+  } catch {}
+
+  // Determine level
+  let level = 'normal';
+  let remainInt = null;
+  let message = '';
+  let suggestion = '';
+  let autoPause = false;
+
+  if (remainPct != null && !isNaN(remainPct)) {
+    remainInt = Math.round(remainPct);
+    if (remainInt <= criticalThreshold) {
+      level = 'critical';
+      message = 'Context at ' + remainInt + '% remaining - CRITICAL';
+      suggestion = 'Run /brain:pause to save state and continue in a fresh session';
+      autoPause = true;
+    } else if (remainInt <= warningThreshold) {
+      level = 'warning';
+      message = 'Context at ' + remainInt + '% remaining';
+      suggestion = 'Start wrapping up current task';
+    } else {
+      message = 'Context at ' + remainInt + '% remaining';
+      suggestion = '';
+    }
+  }
+
+  // Write bridge file atomically (tmp then rename)
+  if (remainInt !== null) {
+    const bridge = JSON.stringify({
+      context_remaining_pct: remainInt,
+      level: level,
+      message: message,
+      suggestion: suggestion,
+      auto_pause_suggested: autoPause,
+      last_updated: new Date().toISOString()
+    }, null, 2);
+    try {
+      fs.writeFileSync('$BRIDGE_TMP', bridge, 'utf8');
+      fs.renameSync('$BRIDGE_TMP', '$BRIDGE');
+    } catch {}
+  }
+
+  // Build status bar
+  let usedInt = usedPct != null ? Math.round(usedPct) : null;
+  let bar = '[----------] ---%';
+
+  if (usedInt !== null && remainInt !== null) {
+    const barLen = 10;
+    const filled = Math.round((usedInt / 100) * barLen);
+    const empty = barLen - filled;
+    const barStr = '#'.repeat(filled) + '-'.repeat(empty);
+
+    // ANSI colors based on remaining percentage
+    let colorStart = '';
+    let colorEnd = '\x1b[0m';
+
+    if (remainInt <= criticalThreshold) {
+      colorStart = '\x1b[5;31m'; // blinking red
+    } else if (remainInt < 35) {
+      colorStart = '\x1b[31m';   // red
+    } else if (remainInt <= 50) {
+      colorStart = '\x1b[33m';   // yellow
+    } else {
+      colorStart = '\x1b[32m';   // green
+    }
+
+    bar = colorStart + '[' + barStr + '] ' + usedInt + '%' + colorEnd;
+  }
+
+  // Phase display
+  let phaseDisplay = '';
+  if (phaseCurrent) {
+    phaseDisplay = ' | P' + phaseCurrent + (phaseStatus ? ': ' + phaseStatus : '');
+  }
+
+  // Output status line to stdout
+  process.stdout.write(projectName + phaseDisplay + ' | ' + bar);
+" "$input" 2>/dev/null || echo "brain | ---"