brain-dev 2.2.0 → 2.3.0

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/discuss.cjs

@@ -5,7 +5,7 @@ const path = require('node:path');
 const { readState, writeState, atomicWriteSync } = require('../state.cjs');
 const { parseRoadmap } = require('../roadmap.cjs');
 const { loadTemplate, interpolate } = require('../templates.cjs');
-const { output, error, success, pipelineGate } = require('../core.cjs');
+const { output, error, success, prefix, pipelineGate } = require('../core.cjs');
 const { generateExpertise } = require('../stack-expert.cjs');
 
 /**
@@ -230,8 +230,11 @@ function handleSave(args, brainDir, state) {
     nextAction: '/brain:plan'
   };
 
-  success("Context captured.");
-  output(result, pipelineGate(`npx brain-dev plan --phase ${phaseNumber}`));
+  const humanLines = [
+    prefix('Context captured.'),
+    pipelineGate(`npx brain-dev plan --phase ${phaseNumber}`)
+  ].join('\n');
+  output(result, humanLines);
 
   return result;
 }

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,29 @@ 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%)',
+      '',
+      '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 +296,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 +315,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/verify.cjs

@@ -504,12 +504,12 @@ function handleLogRecovery(args, logRecoveryIdx, brainDir, state) {
     ? parseInt(args[phaseIdx + 1], 10)
     : state.phase.current;
 
-  logEvent(brainDir, phaseNumber, event);
-
   if (!event || typeof event !== 'object') {
     error('--log-recovery requires a JSON object, not null/primitive');
     return { error: 'invalid-json' };
   }
+
+  logEvent(brainDir, phaseNumber, event);
   output({ action: 'recovery-logged', event }, `[brain] Recovery event logged: ${event.type || 'unknown'}`);
   return { action: 'recovery-logged', event };
 }

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

@@ -30,7 +30,7 @@ const STACK_PATTERNS = {
       antiPatterns: 'N+1 queries (use eager loading with/load), fat controllers (extract to Services/Actions), raw SQL in controllers, logic in models (use Services), not using Form Requests for validation',
       testing: 'Feature tests in tests/Feature, Unit tests in tests/Unit, use RefreshDatabase trait, factories for test data',
       migration: 'php artisan make:migration create_X_table, php artisan migrate, php artisan migrate:rollback',
-      commonBugs: 'N+1 query on relationships (use ->with()), mass assignment vulnerability (use $fillable), missing foreign key constraints, not using transactions for multi-table writes, queue job serialization with deleted models',
+      commonBugs: ['N+1 query on relationships (use ->with())', 'Mass assignment vulnerability (use $fillable)', 'Missing foreign key constraints', 'Not using transactions for multi-table writes', 'Queue job serialization with deleted models'],
       verificationRules: ['Migrations exist for all new models', '.env.example has all required keys', 'Routes registered in routes/api.php or routes/web.php', 'Form Requests validate all user input', 'API Resources used for JSON responses', 'Factories exist for all models'],
       planningHints: ['Plan migration tasks BEFORE model/controller tasks', 'Each model needs: migration, model, factory, controller, request, resource, test', 'Group related migrations in same plan', 'Include seeder tasks for test data'],
       testExamples: {
@@ -44,7 +44,7 @@ const STACK_PATTERNS = {
       patterns: 'Server Components by default, use client directive for interactivity, Server Actions for mutations, Route Handlers for API, Metadata API for SEO, Suspense for loading states',
       antiPatterns: 'useEffect for data fetching (use Server Components), client-side state for server data, large client bundles, not using loading.tsx/error.tsx, fetching in client when server component suffices',
       testing: 'Jest + React Testing Library, or Vitest, test in __tests__/ or *.test.tsx',
-      commonBugs: 'Hydration mismatch (server vs client render difference), importing server-only code in client components, not handling loading/error states, stale cache in fetch(), middleware running on every request',
+      commonBugs: ['Hydration mismatch (server vs client render difference)', 'Importing server-only code in client components', 'Not handling loading/error states', 'Stale cache in fetch()', 'Middleware running on every request'],
       verificationRules: ['Page components exist in app/ directory', 'loading.tsx exists for async pages', 'error.tsx exists for error boundaries', 'API Route Handlers use correct HTTP method exports', 'Client components have "use client" directive', 'Metadata exported for SEO pages'],
       planningHints: ['Plan layout components before page components', 'Server Components first, add "use client" only when needed', 'Plan API Route Handlers separate from page components', 'Include loading.tsx and error.tsx for each route group'],
       testExamples: {
@@ -58,7 +58,7 @@ const STACK_PATTERNS = {
       patterns: 'Functional components + hooks, React Navigation/Expo Router, AsyncStorage, StyleSheet.create, Platform.select for platform-specific code',
       antiPatterns: 'Inline styles (use StyleSheet.create), heavy computation on JS thread, large FlatList without getItemLayout/keyExtractor, not using Platform.OS for platform checks, synchronous storage calls',
       testing: 'Jest + React Native Testing Library, detox for E2E',
-      commonBugs: 'Platform-specific rendering not tested on both OS, keyboard covering inputs (use KeyboardAvoidingView), memory leaks from unsubscribed listeners, navigation state persistence issues, StatusBar behavior differences iOS vs Android',
+      commonBugs: ['Platform-specific rendering not tested on both OS', 'Keyboard covering inputs (use KeyboardAvoidingView)', 'Memory leaks from unsubscribed listeners', 'Navigation state persistence issues', 'StatusBar behavior differences iOS vs Android'],
       verificationRules: ['Platform-specific code uses Platform.OS or Platform.select', 'FlatList has keyExtractor and getItemLayout', 'Navigation screens registered in navigator', 'Assets imported correctly (require() for local)', 'No web-only APIs used (document, window)'],
       planningHints: ['Plan shared components before screen-specific ones', 'Consider both iOS and Android in task descriptions', 'Plan navigation structure before individual screens', 'Include platform-specific testing tasks'],
       testExamples: {
@@ -72,7 +72,7 @@ const STACK_PATTERNS = {
       patterns: 'Router middleware chain, error handling middleware, async/await with express-async-errors, request validation with Joi/Zod, controller-service separation',
       antiPatterns: 'Callback hell, no error middleware, sync operations blocking event loop, not validating request body, try/catch in every route (use express-async-errors)',
       testing: 'Jest/Mocha + supertest for HTTP assertions',
-      commonBugs: 'Unhandled promise rejections crashing server, missing error middleware (must have 4 params), route order matters (specific before generic), CORS misconfiguration, not closing DB connections on shutdown',
+      commonBugs: ['Unhandled promise rejections crashing server', 'Missing error middleware (must have 4 params: err, req, res, next)', 'Route order matters (specific before generic)', 'CORS misconfiguration', 'Not closing DB connections on shutdown'],
       verificationRules: ['Error handling middleware exists (4 params: err, req, res, next)', 'Routes validate input before processing', 'Async handlers properly catch errors', 'CORS configured for production origins', 'Graceful shutdown handler exists'],
       planningHints: ['Plan middleware before routes', 'Error handling middleware is a separate task at the end', 'Group related routes in same router file', 'Plan validation schemas alongside route handlers'],
       testExamples: {
@@ -87,7 +87,7 @@ const STACK_PATTERNS = {
       antiPatterns: 'N+1 queries (use select_related/prefetch_related), logic in views (use services), not using serializers for validation, raw SQL without parameterization',
       testing: 'pytest-django or TestCase, factory_boy for fixtures',
       migration: 'python manage.py makemigrations, python manage.py migrate, python manage.py migrate <app> zero (rollback)',
-      commonBugs: 'Circular imports between apps, migration conflicts in teams, not using select_related causing N+1, signals firing during tests unexpectedly, timezone-naive datetime comparisons',
+      commonBugs: ['Circular imports between apps', 'Migration conflicts in teams', 'Not using select_related causing N+1', 'Signals firing during tests unexpectedly', 'Timezone-naive datetime comparisons'],
       verificationRules: ['Migrations created for all model changes', 'URLs registered in app urls.py and included in root urls.py', 'Admin registered for all models', 'Serializers validate all user input', 'Permissions set on views'],
       planningHints: ['Plan models and migrations before views', 'Each app should be self-contained', 'Plan serializers alongside models', 'Include admin registration tasks', 'Plan management commands for data operations'],
       testExamples: {
@@ -137,7 +137,7 @@ const STACK_PATTERNS = {
       antiPatterns: 'Sync database calls in async endpoints, no Pydantic validation, global mutable state, not using Depends() for shared logic, blocking the event loop',
       testing: 'pytest + httpx AsyncClient',
       migration: 'alembic init, alembic revision --autogenerate -m "description", alembic upgrade head',
-      commonBugs: 'Mixing sync/async database drivers, Pydantic v2 model_validator vs v1 validator, circular imports in routers, not closing DB connections in lifespan, CORS middleware order matters',
+      commonBugs: ['Mixing sync/async database drivers', 'Pydantic v2 model_validator vs v1 validator', 'Circular imports in routers', 'Not closing DB connections in lifespan', 'CORS middleware order matters'],
       verificationRules: ['Pydantic schemas exist for all request/response models', 'Dependencies use Depends() injection', 'Async endpoints use async database driver', 'Alembic migrations exist for schema changes', 'Error handlers return consistent JSON format'],
       planningHints: ['Plan Pydantic schemas before routers', 'Plan database models with Alembic migrations', 'Group related endpoints in same router', 'Plan dependency injection for shared resources (DB, auth)'],
       testExamples: {
@@ -318,7 +318,8 @@ function generateExpertise(brainDir, role = 'general') {
     if (fwInfo.commonBugs) {
       sections.push('');
       sections.push(`### Common ${framework} Bugs to Avoid`);
-      for (const [i, bug] of fwInfo.commonBugs.split(', ').entries()) {
+      const bugs = Array.isArray(fwInfo.commonBugs) ? fwInfo.commonBugs : fwInfo.commonBugs.split(', ');
+      for (const [i, bug] of bugs.entries()) {
         sections.push(`${i + 1}. ${bug}`);
       }
     }
@@ -344,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/overlays/nextjs/planner-overlay.md

@@ -0,0 +1,30 @@
+## Next.js-Specific Planning
+
+### Task Ordering
+1. **Layouts first**: Create layout.tsx before page components
+2. **Server Components first**: Default to Server Components, add "use client" only when needed
+3. **API Routes separate**: Plan Route Handlers as distinct tasks from pages
+4. **Error boundaries**: Include loading.tsx and error.tsx for each route group
+
+### Standard Feature Pattern
+For each new route/feature, plan these tasks:
+1. Layout component (if new route group)
+2. Page component (Server Component by default)
+3. Loading state (loading.tsx)
+4. Error boundary (error.tsx)
+5. API Route Handler (if needed)
+6. Client components (only for interactivity)
+7. Tests
+
+### must_haves Template for Next.js
+```yaml
+truths:
+  - "Page renders correctly as Server Component"
+  - "loading.tsx shows skeleton/spinner during data fetch"
+  - "error.tsx catches and displays errors gracefully"
+  - "No useEffect used for data fetching (Server Component handles it)"
+artifacts:
+  - path: "app/{route}/page.tsx"
+  - path: "app/{route}/loading.tsx"
+  - path: "app/{route}/error.tsx"
+```

package/bin/templates/overlays/react-native/planner-overlay.md

@@ -0,0 +1,27 @@
+## React Native-Specific Planning
+
+### Task Ordering
+1. **Navigation first**: Define navigation structure before screens
+2. **Shared components**: Plan reusable components before screen-specific ones
+3. **Platform handling**: Consider both iOS and Android in each task
+4. **Performance**: Plan FlatList optimization tasks alongside data display tasks
+
+### Standard Feature Pattern
+For each new screen/feature, plan these tasks:
+1. Navigation registration (add to navigator)
+2. Screen component with StyleSheet
+3. Shared sub-components (if needed)
+4. Platform-specific adjustments (Platform.OS checks)
+5. Tests (component + interaction)
+
+### must_haves Template for React Native
+```yaml
+truths:
+  - "Screen renders correctly on both iOS and Android"
+  - "Navigation to/from screen works with correct params"
+  - "StyleSheet.create used (no inline styles)"
+  - "FlatList has keyExtractor for list screens"
+artifacts:
+  - path: "app/{screen}.tsx or src/screens/{Screen}.tsx"
+  - path: "components/{Component}.tsx"
+```

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,35 @@
+---
+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 contains step-by-step instructions specific to this project's stack
+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
+
+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):',
     '',

package/package.json

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