brain-dev 2.2.1 → 2.3.1

package/agents/brain-reviewer.md

@@ -0,0 +1,22 @@
+---
+name: brain-reviewer
+description: Code quality reviewer — DRY, over-engineering, framework best practices, style consistency
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+model: inherit
+---
+
+You are a code reviewer agent for the Brain workflow system.
+
+You will receive:
+- A SUMMARY of executed work (changed files, key decisions)
+- Technology context (framework patterns, anti-patterns, project conventions)
+- An output path for your review
+
+Your job: Review the changed files for quality issues using confidence-based filtering (>=80% only). Focus on bugs, over-engineering, DRY violations, and framework convention adherence.
+
+Read the changed files fully. Compare with existing project files for style consistency.
+Write your findings to REVIEW.md at the specified output path.

package/bin/brain-tools.cjs

@@ -178,6 +178,10 @@ async function main() {
       await require('./lib/commands/update.cjs').run(args.slice(1));
       break;
 
+    case 'review':
+      await require('./lib/commands/review.cjs').run(args.slice(1));
+      break;
+
     case 'upgrade':
       await require('./lib/commands/upgrade.cjs').run(args.slice(1), {
         brainDir: path.join(process.cwd(), '.brain')

package/bin/lib/agents.cjs

@@ -6,7 +6,7 @@
  * Constant registry with discovery and validation functions.
  */
 
-const MAX_AGENTS = 8;
+const MAX_AGENTS = 9;
 
 const AGENTS = {
   researcher: {
@@ -59,6 +59,13 @@ const AGENTS = {
     model: 'inherit',
     description: 'Combines findings from parallel research agents into a unified SUMMARY.md'
   },
+  reviewer: {
+    template: 'reviewer',
+    inputs: ['summary_content', 'changed_files', 'stack_expertise'],
+    outputs: ['REVIEW.md'],
+    model: 'inherit',
+    description: 'Reviews code quality: DRY, over-engineering, framework best practices, project style consistency'
+  },
   mapper: {
     template: 'mapper',
     inputs: ['focus', 'codebase_root'],

package/bin/lib/commands/new-task.cjs

@@ -206,7 +206,7 @@ function buildStepInstructions(taskNum, slug, taskDir, brainDir, mode, research,
   // VERIFY step
   if (mode !== 'light') {
     steps.verify = [
-      `## Step 4: Verify — Task #${taskNum}`,
+      `## Step 5: Verify — Task #${taskNum}`,
       '',
       `Verify the execution results against must_haves in: \`${taskDir}/PLAN-1.md\``,
       '',
@@ -221,9 +221,32 @@ function buildStepInstructions(taskNum, slug, taskDir, brainDir, mode, research,
     ].join('\n');
   }
 
+  // REVIEW step
+  if (mode !== 'light') {
+    steps.review = [
+      `## Step 4: Review — Task #${taskNum}`,
+      '',
+      `Run code review on executed work before verification.`,
+      '',
+      'Run: `npx brain-dev review`',
+      '',
+      'Brain will spawn a reviewer agent that checks:',
+      '- Code quality and DRY (no unnecessary abstractions)',
+      '- Framework best practices',
+      '- Over-engineering detection',
+      '- Project code style consistency',
+      '- Confidence-based filtering (only real issues, ≥80%)',
+      '',
+      'MANDATORY: Do NOT skip review because changes seem "small" or "trivial".',
+      'There are ZERO valid reasons to skip this step.',
+      '',
+      'Then run: `npx brain-dev new-task --continue`'
+    ].join('\n');
+  }
+
   // COMPLETE step
   steps.complete = [
-    `## Step 5: Complete — Task #${taskNum}`,
+    `## Step 6: Complete — Task #${taskNum}`,
     '',
     'Task completion options:',
     '',
@@ -276,6 +299,7 @@ function handleContinue(brainDir, state) {
   const hasResearch = fs.existsSync(path.join(taskDir, 'RESEARCH.md'));
   const hasPlan = fs.existsSync(path.join(taskDir, 'PLAN-1.md'));
   const hasSummary = fs.existsSync(path.join(taskDir, 'SUMMARY-1.md'));
+  const hasReview = fs.existsSync(path.join(taskDir, 'REVIEW.md'));
   const hasVerification = fs.existsSync(path.join(taskDir, 'VERIFICATION.md'));
 
   const isLight = taskMeta.mode === 'light';
@@ -294,6 +318,9 @@ function handleContinue(brainDir, state) {
   } else if (!hasSummary) {
     nextStep = 'execute';
     newStatus = 'executing';
+  } else if (!hasReview && !isLight) {
+    nextStep = 'review';
+    newStatus = 'reviewing';
   } else if (!hasVerification && !isLight) {
     nextStep = 'verify';
     newStatus = 'verifying';

package/bin/lib/commands/progress.cjs

@@ -49,7 +49,13 @@ function nextAction(state) {
     case 'executing':
       return '/brain:execute';
     case 'executed':
+      return '/brain:review';
+    case 'reviewing':
+      return '/brain:review';
+    case 'reviewed':
       return '/brain:verify';
+    case 'review-failed':
+      return '/brain:review';
     case 'verifying':
       return '/brain:verify';
     case 'verified':

package/bin/lib/commands/review.cjs

@@ -0,0 +1,173 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState, writeState } = require('../state.cjs');
+const { loadTemplateWithOverlay, interpolate } = require('../templates.cjs');
+const { getAgent, resolveModel } = require('../agents.cjs');
+const { logEvent } = require('../logger.cjs');
+const { output, error, prefix, pipelineGate } = require('../core.cjs');
+const { generateExpertise, getDetectedFramework } = require('../stack-expert.cjs');
+
+/**
+ * Find the phase directory for a given phase number.
+ */
+function findPhaseDir(brainDir, phaseNumber) {
+  const phasesDir = path.join(brainDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return null;
+  const padded = String(phaseNumber).padStart(2, '0');
+  const match = fs.readdirSync(phasesDir).find(d => d.startsWith(`${padded}-`));
+  return match ? path.join(phasesDir, match) : null;
+}
+
+/**
+ * Read the latest SUMMARY file from a phase directory.
+ */
+function readLatestSummary(phaseDir) {
+  if (!phaseDir || !fs.existsSync(phaseDir)) return null;
+  const files = fs.readdirSync(phaseDir)
+    .filter(f => f.toUpperCase().startsWith('SUMMARY'))
+    .sort();
+  if (files.length === 0) return null;
+  return fs.readFileSync(path.join(phaseDir, files[files.length - 1]), 'utf8');
+}
+
+/**
+ * Run the review command.
+ * @param {string[]} args
+ * @param {object} [opts]
+ */
+async function run(args = [], opts = {}) {
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const state = readState(brainDir);
+
+  if (!state) {
+    error("No brain state found. Run 'brain-dev init' first.");
+    return { error: 'no-state' };
+  }
+
+  // Handle --result flag (called after reviewer agent completes)
+  const resultIdx = args.indexOf('--result');
+  if (resultIdx >= 0) {
+    return handleResult(brainDir, state, args);
+  }
+
+  const phaseIdx = args.indexOf('--phase');
+  const phaseNumber = phaseIdx >= 0 ? parseInt(args[phaseIdx + 1], 10) : state.phase.current;
+
+  const phaseDir = findPhaseDir(brainDir, phaseNumber);
+  if (!phaseDir) {
+    error(`Phase ${phaseNumber} directory not found.`);
+    return { error: 'phase-dir-not-found' };
+  }
+
+  // Read latest summary
+  const summaryContent = readLatestSummary(phaseDir);
+  if (!summaryContent) {
+    error(`No SUMMARY file found for phase ${phaseNumber}. Run /brain:execute first.`);
+    return { error: 'no-summary' };
+  }
+
+  // Build reviewer prompt
+  const framework = getDetectedFramework(brainDir);
+  const template = loadTemplateWithOverlay('reviewer', framework);
+  const reviewPath = path.join(phaseDir, 'REVIEW.md');
+
+  const prompt = interpolate(template, {
+    stack_expertise: generateExpertise(brainDir, 'reviewer'),
+    summary_content: summaryContent,
+    output_path: reviewPath,
+    phase: String(phaseNumber),
+    plan_number: 'all'
+  });
+
+  // Get reviewer agent metadata
+  const reviewerAgent = getAgent('reviewer');
+  const model = resolveModel('reviewer', state);
+
+  // Log spawn event
+  logEvent(brainDir, phaseNumber, {
+    type: 'spawn',
+    agent: 'reviewer',
+    phase: phaseNumber
+  });
+
+  // Update state
+  state.phase.status = 'reviewing';
+  writeState(brainDir, state);
+
+  const result = {
+    action: 'spawn-reviewer',
+    phase: phaseNumber,
+    prompt,
+    model,
+    outputPath: reviewPath,
+    nextAction: '/brain:verify'
+  };
+
+  const humanLines = [
+    prefix(`Code review for Phase ${phaseNumber}`),
+    prefix(`Model: ${model}`),
+    prefix(`Output: ${reviewPath}`),
+    '',
+    'IMPORTANT: Use the Agent tool (subagent_type: "brain-reviewer") to spawn the reviewer.',
+    'Do NOT review the code yourself. The reviewer agent has framework-specific expertise.',
+    '',
+    'After the reviewer agent completes, run: npx brain-dev review --result --phase ' + phaseNumber,
+    'This finalizes the review status and advances the pipeline.',
+    '',
+    prompt
+  ];
+
+  output(result, humanLines.join('\n'));
+  return result;
+}
+
+/**
+ * Handle --result flag: finalize review status based on REVIEW.md.
+ * Called after reviewer agent writes REVIEW.md.
+ */
+function handleResult(brainDir, state, args) {
+  const phaseIdx = args.indexOf('--phase');
+  const phaseNumber = phaseIdx >= 0 ? parseInt(args[phaseIdx + 1], 10) : state.phase.current;
+
+  const phaseDir = findPhaseDir(brainDir, phaseNumber);
+  const reviewPath = phaseDir ? path.join(phaseDir, 'REVIEW.md') : null;
+
+  if (!reviewPath || !fs.existsSync(reviewPath)) {
+    error('No REVIEW.md found. Run /brain:review first to spawn the reviewer agent.');
+    return { error: 'no-review' };
+  }
+
+  // Parse review status from frontmatter
+  const content = fs.readFileSync(reviewPath, 'utf8');
+  const statusMatch = content.match(/^status:\s*(passed|needs-work|critical)/m);
+  const reviewStatus = statusMatch ? statusMatch[1] : 'passed';
+
+  if (reviewStatus === 'critical') {
+    state.phase.status = 'review-failed';
+    writeState(brainDir, state);
+    error('Review found critical issues. Fix them and re-run /brain:review.');
+    output({ action: 'review-failed', phase: phaseNumber, status: reviewStatus }, '');
+    return { action: 'review-failed', phase: phaseNumber };
+  }
+
+  state.phase.status = 'reviewed';
+  writeState(brainDir, state);
+
+  const result = {
+    action: 'review-complete',
+    phase: phaseNumber,
+    status: reviewStatus,
+    nextAction: '/brain:verify'
+  };
+
+  output(result, [
+    prefix(`Review complete: ${reviewStatus}`),
+    pipelineGate(`npx brain-dev verify --phase ${phaseNumber}`)
+  ].join('\n'));
+
+  return result;
+}
+
+module.exports = { run };

package/bin/lib/commands.cjs

@@ -92,6 +92,15 @@ const COMMANDS = [
     needsState: true,
     args: '  --plan <id>  Specific plan to execute (e.g. 01-02)'
   },
+  {
+    name: 'review',
+    description: 'Code review after execution',
+    usage: 'brain-dev review [--phase <n>]',
+    group: 'Lifecycle',
+    implemented: true,
+    needsState: true,
+    args: '  --phase <n>  Phase to review'
+  },
   {
     name: 'verify',
     description: 'Run verification checks on completed work',

package/bin/lib/stack-expert.cjs

@@ -345,6 +345,25 @@ function generateExpertise(brainDir, role = 'general') {
       }
     }
     sections.push('');
+  } else if (role === 'reviewer' && fwInfo) {
+    sections.push('### Reviewer Guidance');
+    sections.push(`- Check code follows ${framework} conventions`);
+    if (fwInfo.antiPatterns) {
+      sections.push(`- Scan for anti-patterns: ${fwInfo.antiPatterns}`);
+    }
+    if (fwInfo.patterns) {
+      sections.push(`- Verify patterns used: ${fwInfo.patterns}`);
+    }
+    sections.push('- Compare naming with existing project files');
+    sections.push('- Flag over-engineering: unnecessary abstractions, premature optimization');
+    if (fwInfo.verificationRules) {
+      sections.push('');
+      sections.push(`### ${framework} Review Checklist`);
+      for (const rule of fwInfo.verificationRules) {
+        sections.push(`- [ ] ${rule}`);
+      }
+    }
+    sections.push('');
   } else {
     // Generic role guidance (no framework info or general role)
     if (role === 'planner') {

package/bin/lib/state.cjs

@@ -512,6 +512,7 @@ function today() {
 const VALID_PHASE_STATUSES = [
   'initialized', 'pending', 'mapped', 'ready', 'discussing', 'discussed',
   'planning', 'planned', 'executing', 'executed',
+  'reviewing', 'reviewed', 'review-failed',
   'verifying', 'verified', 'verification-failed',
   'partial', 'failed', 'paused', 'complete'
 ];

package/bin/templates/reviewer.md

@@ -0,0 +1,111 @@
+# Code Reviewer Agent
+
+## Technology Context
+{{stack_expertise}}
+
+## Review Scope
+
+Review the code changes from the latest execution. Changed files are listed in the SUMMARY below.
+
+{{summary_content}}
+
+## Review Criteria (Priority Order)
+
+### 1. Critical Issues (MUST fix before verify)
+- **Bugs**: Logic errors, unhandled edge cases, race conditions
+- **Security**: SQL injection, XSS, auth bypass, secrets in code
+- **Data loss**: Missing transactions, unchecked deletes, no rollback
+
+### 2. Quality Issues (SHOULD fix)
+- **Over-engineering**: Abstractions for things used once, premature optimization, unnecessary design patterns
+  - Rule: If code is used in ONE place, inline it. Don't create a helper/utility/service for single use.
+  - Rule: If a simple `if/else` works, don't use Strategy Pattern.
+  - Rule: 3 similar lines are better than a premature abstraction.
+  - Rule: Don't add features, refactor code, or make "improvements" beyond what was asked.
+- **DRY violations**: Same logic in multiple places (>5 lines duplicated)
+  - Only flag if the duplication is >5 lines AND in the same module/feature scope
+  - Cross-module duplication is acceptable if coupling would be worse
+- **Test quality**: Tests that don't assert behavior, tests that test implementation details
+  - Good: `assert.equal(result.status, 'success')`
+  - Bad: `assert.equal(mockFn.callCount, 3)` (tests implementation, not behavior)
+- **Error handling**: Missing error handling at system boundaries (user input, external APIs)
+  - Do NOT add error handling for internal code or impossible scenarios
+
+### 3. Style Issues (NICE to fix)
+- **Naming**: Inconsistent with existing project code style
+- **Formatting**: Inconsistent indentation, bracket style
+- **Comments**: Obvious comments that add no value, or missing comments on complex logic
+
+## Review Method
+
+1. Read the SUMMARY above to get list of changed/created files
+2. For each file listed in key-files, read the FULL content
+3. Compare naming/style with existing project files (read 2-3 similar existing files for comparison)
+4. Check against framework patterns from Technology Context above
+5. Only report issues with confidence >= 80%
+
+## Confidence-Based Filtering
+
+For each issue found, assign a confidence level:
+- **95-100%**: Definite bug or security issue — always report
+- **80-94%**: High confidence quality issue — report
+- **60-79%**: Possible issue — skip (don't waste time on maybes)
+- **<60%**: Opinion/preference — skip
+
+ONLY include issues with confidence >= 80% in the review output.
+
+## Output: REVIEW.md
+
+Write results to `{{output_path}}`:
+
+### YAML Frontmatter
+
+```yaml
+---
+phase: {{phase}}
+plan: {{plan_number}}
+status: passed | needs-work | critical
+issues_count: 0
+critical_count: 0
+quality_count: 0
+style_count: 0
+reviewed_files: []
+---
+```
+
+### Per-Issue Format
+
+```markdown
+### [CRITICAL|QUALITY|STYLE] Issue: {title}
+**Confidence:** {80-100}%
+**File:** {path}
+**Lines:** {range}
+**Problem:** {1-2 sentence description}
+**Fix:** {concrete fix suggestion — not vague advice}
+```
+
+### Status Determination
+- **passed**: 0 critical issues, ≤2 quality issues — code is good to verify
+- **needs-work**: 0 critical issues, 3+ quality issues — fix before proceeding
+- **critical**: 1+ critical issues — MUST fix, do not proceed
+
+## What NOT to Review
+- Do NOT suggest adding docstrings/comments to code you didn't write
+- Do NOT suggest refactoring code outside the changed files
+- Do NOT suggest type annotations if the project doesn't use them
+- Do NOT suggest error handling for internal code paths that can't fail
+- Do NOT flag style preferences that aren't in the project's existing conventions
+- Do NOT suggest "improvements" beyond what was asked — avoid scope creep
+- When in doubt, the existing project code style WINS over your preferences
+
+## Output Marker
+
+When review is complete:
+
+```
+## REVIEW COMPLETE
+
+**Status:** [passed | needs-work | critical]
+**Issues:** [N total: X critical, Y quality, Z style]
+**Files reviewed:** [count]
+```

package/commands/brain/review.md

@@ -0,0 +1,42 @@
+---
+name: brain:review
+description: Run code review on executed work before verification
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+---
+<objective>
+Review code quality after execution and before verification. Checks DRY, over-engineering,
+framework best practices, and project code style consistency using confidence-based filtering.
+</objective>
+
+<critical-rules>
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev review` FIRST — before reading code, before analyzing, before suggesting fixes
+2. READ the full output — it spawns brain-reviewer agent with framework-specific expertise
+3. FOLLOW the nextAction field — copy the exact command, do not modify it
+4. If output shows an ERROR: follow the recovery path in the output, do NOT debug manually
+5. If output shows a CHECKPOINT: use AskUserQuestion, do NOT pick options yourself
+
+ZERO EXCEPTIONS — REVIEW IS ALWAYS MANDATORY:
+- "Changes are minimal" → STILL review. Small changes cause big bugs.
+- "Only 2 files changed" → STILL review. Every file matters.
+- "This is trivial" → STILL review. You don't decide what's trivial, the reviewer agent does.
+- "I can see the code is fine" → STILL review. You are not the reviewer. The pipeline is.
+- NEVER say "skipping review" for any reason. There is no valid reason to skip.
+
+CONSEQUENCE OF SKIPPING: Pipeline tracks state, creates audit trails, spawns specialized agents,
+and injects framework-specific expertise. Skipping it means: no state tracking, no audit trail,
+no specialized agents, no framework guidance, potential data loss in .brain/ state.
+</critical-rules>
+
+<process>
+1. Run: `npx brain-dev review [--phase N]`
+2. Spawn brain-reviewer agent with the provided prompt
+3. Review REVIEW.md output
+4. If critical issues: re-execute fixes, then re-review
+5. If passed or needs-work (≤2 issues): proceed to /brain:verify
+</process>

package/hooks/bootstrap.sh

@@ -64,7 +64,7 @@ try {
     'Phase: ' + (data.phase && data.phase.current || 0) + ' (' + (data.phase && data.phase.status || 'initialized') + ')',
     'Next: ' + (data.nextAction || '/brain:new-project'),
     '',
-    'Commands: /brain:new-project, /brain:story, /brain:discuss, /brain:plan, /brain:execute, /brain:verify, /brain:complete, /brain:quick, /brain:new-task, /brain:progress, /brain:pause, /brain:resume, /brain:help, /brain:health, /brain:update, /brain:upgrade, /brain:storm, /brain:adr, /brain:phase, /brain:config, /brain:map, /brain:recover, /brain:dashboard, /brain:auto (or execute --auto)',
+    'Commands: /brain:new-project, /brain:story, /brain:discuss, /brain:plan, /brain:execute, /brain:review, /brain:verify, /brain:complete, /brain:quick, /brain:new-task, /brain:progress, /brain:pause, /brain:resume, /brain:help, /brain:health, /brain:update, /brain:upgrade, /brain:storm, /brain:adr, /brain:phase, /brain:config, /brain:map, /brain:recover, /brain:dashboard, /brain:auto (or execute --auto)',
     '',
     'PIPELINE RULES (NON-NEGOTIABLE):',
     '',
@@ -89,6 +89,11 @@ try {
     '6. STATE: Run /brain:progress before suggesting next steps.',
     '   For /brain:update, always use: npx brain-dev@latest update',
     '   NEVER run brain-dev init after an update.',
+    '',
+    '7. REVIEW IS MANDATORY: After execute, ALWAYS run /brain:review before /brain:verify.',
+    '   NEVER skip review because changes seem "small", "trivial", or "minimal".',
+    '   You do NOT decide what needs review. The reviewer agent decides.',
+    '   There are ZERO valid reasons to skip the review step.',
     '--- End Brain Context ---'
   ];
   console.log(lines.join('\n'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brain-dev",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "description": "AI-powered development workflow orchestrator",
   "author": "halilcosdu",
   "license": "MIT",