brain-dev 2.0.6 → 2.2.0

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 } = require('../core.cjs');
+const { output, error, success, pipelineGate } = require('../core.cjs');
 const { generateExpertise } = require('../stack-expert.cjs');
 
 /**
@@ -230,8 +230,8 @@ function handleSave(args, brainDir, state) {
     nextAction: '/brain:plan'
   };
 
-  success("Context captured. Run /brain:plan to create execution plans.");
-  output(result, '');
+  success("Context captured.");
+  output(result, pipelineGate(`npx brain-dev plan --phase ${phaseNumber}`));
 
   return result;
 }

package/bin/lib/commands/execute.cjs

@@ -3,13 +3,13 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { readState, writeState } = require('../state.cjs');
-const { loadTemplate, interpolate } = require('../templates.cjs');
+const { loadTemplate, interpolate, loadTemplateWithOverlay } = require('../templates.cjs');
 const { getAgent, resolveModel } = require('../agents.cjs');
 const { logEvent } = require('../logger.cjs');
 const { output, error } = require('../core.cjs');
 const { recordInvocation, estimateTokens } = require('../cost.cjs');
 const { acquireLock, releaseLock } = require('../lock.cjs');
-const { generateExpertise } = require('../stack-expert.cjs');
+const { generateExpertise, getDetectedFramework } = require('../stack-expert.cjs');
 
 /**
  * Find a phase directory under .brain/phases/ matching a phase number.
@@ -347,8 +347,9 @@ async function run(args = [], opts = {}) {
   const spotCheckInstruction = 'After completing all tasks, the orchestrator will verify SUMMARY.md, file existence, and commit count.';
   const debuggerSpawnInstruction = 'If auto-retry fails, a debugger agent will be spawned with the error context.';
 
-  // Load executor template and interpolate
-  const template = loadTemplate('executor');
+  // Load executor template with framework overlay
+  const framework = getDetectedFramework(brainDir);
+  const template = loadTemplateWithOverlay('executor', framework);
   const prompt = interpolate(template, {
     plan_path: targetPlan.path,
     summary_path: summaryPath,

package/bin/lib/commands/plan.cjs

@@ -4,12 +4,12 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { readState, writeState } = require('../state.cjs');
 const { parseRoadmap } = require('../roadmap.cjs');
-const { loadTemplate, interpolate } = require('../templates.cjs');
+const { loadTemplate, interpolate, loadTemplateWithOverlay } = require('../templates.cjs');
 const { getAgent, resolveModel } = require('../agents.cjs');
 const { logEvent } = require('../logger.cjs');
 const { estimateFromPlan, getDefaultBudget, checkBudget } = require('../complexity.cjs');
-const { output, error, success } = require('../core.cjs');
-const { generateExpertise } = require('../stack-expert.cjs');
+const { output, error, success, pipelineGate } = require('../core.cjs');
+const { generateExpertise, getDetectedFramework } = require('../stack-expert.cjs');
 
 /**
  * Find a phase directory under .brain/phases/ matching a phase number.
@@ -157,7 +157,8 @@ function getAlternatives(tech) {
  * @returns {{ prompt: string, output_dir: string }}
  */
 function generatePlannerPrompt(phase, brainDir) {
-  const template = loadTemplate('planner');
+  const framework = getDetectedFramework(brainDir);
+  const template = loadTemplateWithOverlay('planner', framework);
 
   const contextContent = readContext(brainDir, phase.number);
   const researchContent = readResearchSummary(brainDir, phase.number);
@@ -316,7 +317,8 @@ function handleSingle(args, brainDir, state) {
     `[brain] Checker enabled: true`,
     result.advocate_enabled ? `[brain] Advocate enabled: true` : '',
     '',
-    fullPrompt
+    fullPrompt,
+    pipelineGate(`npx brain-dev execute --phase ${phaseNumber}`)
   ].filter(Boolean);
   output(result, humanLines.join('\n'));
 

package/bin/lib/commands/story.cjs

@@ -8,12 +8,46 @@ const { output, error, prefix } = require('../core.cjs');
 const { logEvent } = require('../logger.cjs');
 const { loadTemplate, interpolate } = require('../templates.cjs');
 const { getAgent, resolveModel } = require('../agents.cjs');
+const { generateExpertise } = require('../stack-expert.cjs');
 const {
   RESEARCH_AREAS, CORE_QUESTIONS, buildBrownfieldQuestions,
   readDetection, buildCodebaseContext, generateProjectMd,
   generateRequirementsMd, extractFeatures, extractSection
 } = require('../story-helpers.cjs');
 
+/**
+ * Get research areas with optional framework-specific additions.
+ * @param {Array} baseAreas - Default RESEARCH_AREAS
+ * @param {object|null} detection - Detection result
+ * @returns {Array} Research areas (may include framework-specific one)
+ */
+function getResearchAreas(baseAreas, detection) {
+  const areas = [...baseAreas];
+  const framework = detection?.stack?.primary?.framework || detection?.stack?.framework;
+  if (!framework) return areas;
+
+  const fwLower = framework.toLowerCase().replace(/[^a-z]/g, '-');
+
+  // Add framework-specific research area
+  areas.push({
+    name: `${framework} Patterns`,
+    area: `${framework} best practices`,
+    description: `${framework}-specific patterns, conventions, ecosystem tools, and common pitfalls`,
+    file: `${fwLower}-patterns.md`
+  });
+
+  // Enrich architecture area with framework context
+  const archIdx = areas.findIndex(a => a.area && a.area.toLowerCase().includes('architecture'));
+  if (archIdx >= 0) {
+    areas[archIdx] = {
+      ...areas[archIdx],
+      description: `${framework} architecture patterns and ${areas[archIdx].description}`
+    };
+  }
+
+  return areas;
+}
+
 async function run(args = [], opts = {}) {
   const { values, positionals } = parseArgs({
     args,
@@ -317,8 +351,12 @@ function stepResearch(brainDir, storyDir, storyMeta, state) {
   const researchDir = path.join(storyDir, 'research');
   fs.mkdirSync(researchDir, { recursive: true });
 
-  // Build researcher agent prompts
-  const agents = RESEARCH_AREAS.map(area => {
+  // Build researcher agent prompts with framework-aware areas
+  const detection = readDetection(brainDir);
+  const researchAreas = getResearchAreas(RESEARCH_AREAS, detection);
+  const stackContext = generateExpertise(brainDir, 'general');
+
+  const agents = researchAreas.map(area => {
     const agentDef = getAgent('researcher');
     const model = resolveModel('researcher', state);
     return {
@@ -330,6 +368,7 @@ function stepResearch(brainDir, storyDir, storyMeta, state) {
       prompt: [
         `# Research Focus: ${area.area}`,
         '',
+        stackContext ? `## Stack Context\n${stackContext}\n` : '',
         `You are a ${area.description} researcher.`,
         '',
         '## Project Context',
@@ -346,7 +385,6 @@ function stepResearch(brainDir, storyDir, storyMeta, state) {
   });
 
   // Check brownfield and build mapper agents if codebase not yet mapped
-  const detection = readDetection(brainDir);
   const isBrownfield = detection && detection.type === 'brownfield';
   const codebaseDir = path.join(brainDir, 'codebase');
   const codebaseMapped = fs.existsSync(codebaseDir) &&

package/bin/lib/commands/verify.cjs

@@ -3,14 +3,14 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { readState, writeState, atomicWriteSync } = require('../state.cjs');
-const { loadTemplate, interpolate } = require('../templates.cjs');
+const { loadTemplate, interpolate, loadTemplateWithOverlay } = require('../templates.cjs');
 const { getAgent, resolveModel } = require('../agents.cjs');
 const { logEvent } = require('../logger.cjs');
 const { output, error, success } = require('../core.cjs');
 const antiPatterns = require('../anti-patterns.cjs');
 const { buildDebuggerSpawnInstructions } = require('./execute.cjs');
 const { isPathWithinRoot } = require('../security.cjs');
-const { generateExpertise } = require('../stack-expert.cjs');
+const { generateExpertise, getDetectedFramework } = require('../stack-expert.cjs');
 
 /**
  * Find a phase directory under .brain/phases/ matching a phase number.
@@ -255,8 +255,9 @@ async function run(args = [], opts = {}) {
     key_links: combinedMustHaves.key_links.length
   });
 
-  // Load verifier template and interpolate
-  const template = loadTemplate('verifier');
+  // Load verifier template with framework overlay
+  const framework = getDetectedFramework(brainDir);
+  const template = loadTemplateWithOverlay('verifier', framework);
   const mustHavesFormatted = [
     '**Truths:**',
     ...combinedMustHaves.truths.map(t => `- ${t}`),

package/bin/lib/core.cjs

@@ -59,4 +59,21 @@ function success(msg) {
   console.log(`${tag} ${msg}`);
 }
 
-module.exports = { isTTY, output, prefix, error, success };
+/**
+ * Generate a pipeline gate marker for command output.
+ * This is a visual signal telling Claude the exact next command to run.
+ * @param {string} nextCommand - The exact command to run next
+ * @returns {string}
+ */
+function pipelineGate(nextCommand) {
+  return [
+    '',
+    '--- PIPELINE GATE ---',
+    `NEXT COMMAND (mandatory): ${nextCommand}`,
+    'Do NOT skip this command. Do NOT improvise. Do NOT start coding.',
+    'Copy and run the command above.',
+    '--- END GATE ---'
+  ].join('\n');
+}
+
+module.exports = { isTTY, output, prefix, error, success, pipelineGate };

package/bin/lib/stack-expert.cjs

@@ -24,39 +24,76 @@ const STACK_PATTERNS = {
   // Framework-level patterns (file structure, key concepts)
   frameworks: {
     'Laravel': {
-      structure: 'app/Models, app/Http/Controllers, routes/api.php, database/migrations',
-      keyCommands: 'php artisan make:model, make:controller, make:migration, migrate',
-      patterns: 'Eloquent ORM, Form Requests for validation, Resource controllers, Middleware',
-      antiPatterns: 'N+1 queries (use eager loading), fat controllers (use Services/Actions), raw SQL in controllers',
-      testing: 'Feature tests in tests/Feature, Unit tests in tests/Unit, use RefreshDatabase trait'
+      structure: 'app/Models, app/Http/Controllers, app/Http/Requests, app/Services, routes/api.php, database/migrations',
+      keyCommands: 'php artisan make:model -mf, make:controller --api, make:migration, make:request, make:resource, migrate, test',
+      patterns: 'Eloquent ORM, Form Requests for validation, API Resources for serialization, Resource controllers, Middleware, Service classes for business logic, Action classes for single-purpose operations',
+      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',
+      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: {
+        unit: "public function test_user_can_be_created(): void {\n    $user = User::factory()->create(['email' => 'test@example.com']);\n    $this->assertDatabaseHas('users', ['email' => 'test@example.com']);\n}",
+        integration: "$response = $this->postJson('/api/users', ['name' => 'Test', 'email' => 'test@example.com']);\n$response->assertStatus(201)->assertJsonStructure(['data' => ['id', 'name', 'email']]);"
+      }
     },
     'Next.js': {
-      structure: 'app/ (App Router), components/, lib/, public/, app/api/ for routes',
-      keyCommands: 'npx next dev, next build, next start',
-      patterns: 'Server Components by default, use client for interactivity, Server Actions, Route Handlers',
-      antiPatterns: 'useEffect for data fetching (use Server Components), client-side state for server data, large client bundles',
-      testing: 'Jest + React Testing Library, or Vitest, test in __tests__/ or *.test.tsx'
+      structure: 'app/ (App Router), app/api/ for Route Handlers, components/, lib/, public/',
+      keyCommands: 'npx next dev, next build, next start, next lint',
+      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',
+      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: {
+        unit: "import { render, screen } from '@testing-library/react';\nimport Page from './page';\n\ntest('renders heading', () => {\n  render(<Page />);\n  expect(screen.getByRole('heading')).toBeInTheDocument();\n});",
+        integration: "const response = await fetch('/api/users', { method: 'POST', body: JSON.stringify({name: 'Test'}) });\nexpect(response.status).toBe(201);"
+      }
     },
     'React Native': {
-      structure: 'app/ (Expo Router) or src/screens, components/, hooks/, services/',
-      keyCommands: 'npx expo start, expo prebuild, eas build',
-      patterns: 'Functional components + hooks, React Navigation/Expo Router, AsyncStorage, StyleSheet',
-      antiPatterns: 'Inline styles (use StyleSheet), heavy computation on JS thread, large FlatList without optimization',
-      testing: 'Jest + React Native Testing Library, detox for E2E'
+      structure: 'app/ (Expo Router) or src/screens, components/, hooks/, services/, assets/',
+      keyCommands: 'npx expo start, expo prebuild, eas build, npx jest',
+      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',
+      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: {
+        unit: "import { render, screen } from '@testing-library/react-native';\nimport { Button } from './Button';\n\ntest('renders button text', () => {\n  render(<Button title='Press me' />);\n  expect(screen.getByText('Press me')).toBeTruthy();\n});",
+        integration: "const { getByTestId, getByText } = render(<LoginScreen />);\nfireEvent.changeText(getByTestId('email-input'), 'test@example.com');\nfireEvent.press(getByText('Login'));"
+      }
     },
     'Express': {
-      structure: 'routes/, middleware/, controllers/, models/',
-      keyCommands: 'node server.js, npm start',
-      patterns: 'Router middleware chain, error handling middleware, async/await handlers',
-      antiPatterns: 'Callback hell, no error middleware, sync operations blocking event loop',
-      testing: 'Jest/Mocha + supertest for HTTP assertions'
+      structure: 'routes/, middleware/, controllers/, models/, validators/',
+      keyCommands: 'node server.js, npm start, npm test',
+      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',
+      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: {
+        unit: "const request = require('supertest');\nconst app = require('../app');\n\ntest('GET /api/users returns 200', async () => {\n  const res = await request(app).get('/api/users');\n  expect(res.status).toBe(200);\n});",
+        integration: "const res = await request(app).post('/api/users').send({name: 'Test', email: 'test@example.com'});\nexpect(res.status).toBe(201);\nexpect(res.body.data).toHaveProperty('id');"
+      }
     },
     'Django': {
-      structure: 'apps/<name>/models.py, views.py, urls.py, templates/',
-      keyCommands: 'python manage.py runserver, makemigrations, migrate, createsuperuser',
-      patterns: 'Class-based views, Django ORM, Forms/Serializers, middleware',
-      antiPatterns: 'N+1 queries (use select_related/prefetch_related), logic in views (use services)',
-      testing: 'pytest-django or TestCase, factory_boy for fixtures'
+      structure: 'apps/<name>/models.py, views.py, urls.py, serializers.py, admin.py, templates/',
+      keyCommands: 'python manage.py runserver, makemigrations, migrate, createsuperuser, test, shell',
+      patterns: 'Class-based views, Django ORM, DRF Serializers, ModelViewSet, middleware, signals, management commands',
+      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',
+      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: {
+        unit: "from django.test import TestCase\nfrom .models import User\n\nclass UserModelTest(TestCase):\n    def test_create_user(self):\n        user = User.objects.create(email='test@example.com')\n        self.assertEqual(user.email, 'test@example.com')",
+        integration: "from rest_framework.test import APITestCase\n\nclass UserAPITest(APITestCase):\n    def test_create_user(self):\n        response = self.client.post('/api/users/', {'email': 'test@example.com'})\n        self.assertEqual(response.status_code, 201)"
+      }
     },
     'Rails': {
       structure: 'app/models, app/controllers, config/routes.rb, db/migrate',
@@ -94,11 +131,19 @@ const STACK_PATTERNS = {
       testing: 'JUnit 5 + Mockito, @SpringBootTest, @WebMvcTest'
     },
     'FastAPI': {
-      structure: 'app/main.py, app/routers/, app/models/, app/schemas/',
-      keyCommands: 'uvicorn app.main:app --reload',
-      patterns: 'Pydantic models, dependency injection, async/await, path operations',
-      antiPatterns: 'Sync database calls in async endpoints, no Pydantic validation, global state',
-      testing: 'pytest + httpx AsyncClient'
+      structure: 'app/main.py, app/routers/, app/models/, app/schemas/, app/dependencies.py, app/crud/',
+      keyCommands: 'uvicorn app.main:app --reload, pytest, alembic upgrade head',
+      patterns: 'Pydantic models for validation, Depends() for dependency injection, async/await, path operations, background tasks, lifespan events',
+      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',
+      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: {
+        unit: "from httpx import AsyncClient, ASGITransport\nfrom app.main import app\n\nasync def test_read_users():\n    async with AsyncClient(transport=ASGITransport(app=app), base_url='http://test') as ac:\n        response = await ac.get('/users')\n    assert response.status_code == 200",
+        integration: "async def test_create_user(client: AsyncClient):\n    response = await client.post('/users', json={'email': 'test@example.com'})\n    assert response.status_code == 201\n    assert response.json()['email'] == 'test@example.com'"
+      }
     },
     'Astro': {
       structure: 'src/pages, src/components, src/layouts, public/',
@@ -235,26 +280,90 @@ function generateExpertise(brainDir, role = 'general') {
     sections.push('');
   }
 
-  // Role-specific guidance
-  if (role === 'planner') {
+  // Role-specific deep guidance with framework-specific content
+  if (role === 'planner' && fwInfo) {
     sections.push('### Planner Guidance');
     sections.push('- Ensure task file paths match framework directory structure');
     sections.push('- Include test tasks using the detected test framework');
     sections.push('- Set must_haves that reference framework conventions');
+    if (fwInfo.planningHints) {
+      sections.push('');
+      sections.push(`### ${framework} Planning Rules`);
+      for (const hint of fwInfo.planningHints) {
+        sections.push(`- ${hint}`);
+      }
+    }
+    if (fwInfo.migration) {
+      sections.push(`- Migration commands: ${fwInfo.migration}`);
+    }
+    if (fwInfo.testExamples) {
+      sections.push('');
+      sections.push(`### Example must_haves for ${framework}`);
+      sections.push('```yaml');
+      sections.push('truths:');
+      if (fwInfo.verificationRules) {
+        for (const rule of fwInfo.verificationRules.slice(0, 3)) {
+          sections.push(`  - "${rule}"`);
+        }
+      }
+      sections.push('```');
+    }
     sections.push('');
-  } else if (role === 'executor') {
+  } else if (role === 'executor' && fwInfo) {
     sections.push('### Executor Guidance');
     sections.push('- Use framework CLI commands (listed above) to scaffold where possible');
     sections.push('- Follow naming conventions strictly');
     sections.push('- AVOID all listed anti-patterns');
     sections.push('- Write tests in the detected test framework');
+    if (fwInfo.commonBugs) {
+      sections.push('');
+      sections.push(`### Common ${framework} Bugs to Avoid`);
+      for (const [i, bug] of fwInfo.commonBugs.split(', ').entries()) {
+        sections.push(`${i + 1}. ${bug}`);
+      }
+    }
+    if (fwInfo.testExamples) {
+      sections.push('');
+      sections.push(`### Example Test (${framework})`);
+      sections.push('```');
+      sections.push(fwInfo.testExamples.unit);
+      sections.push('```');
+    }
     sections.push('');
-  } else if (role === 'verifier') {
+  } else if (role === 'verifier' && fwInfo) {
     sections.push('### Verifier Guidance');
     sections.push('- Verify files are in correct framework directories');
     sections.push('- Check naming follows detected conventions');
     sections.push('- Scan for anti-patterns from the list above');
     sections.push('- Verify tests use the correct test framework');
+    if (fwInfo.verificationRules) {
+      sections.push('');
+      sections.push(`### ${framework} Verification 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') {
+      sections.push('### Planner Guidance');
+      sections.push('- Ensure task file paths match framework directory structure');
+      sections.push('- Include test tasks using the detected test framework');
+      sections.push('- Set must_haves that reference framework conventions');
+    } else if (role === 'executor') {
+      sections.push('### Executor Guidance');
+      sections.push('- Use framework CLI commands (listed above) to scaffold where possible');
+      sections.push('- Follow naming conventions strictly');
+      sections.push('- AVOID all listed anti-patterns');
+      sections.push('- Write tests in the detected test framework');
+    } else if (role === 'verifier') {
+      sections.push('### Verifier Guidance');
+      sections.push('- Verify files are in correct framework directories');
+      sections.push('- Check naming follows detected conventions');
+      sections.push('- Scan for anti-patterns from the list above');
+      sections.push('- Verify tests use the correct test framework');
+    }
     sections.push('');
   }
 
@@ -312,9 +421,29 @@ function generateContext7Queries(detectionOrBrainDir) {
   return lines.join('\n');
 }
 
+/**
+ * Get the detected framework name mapped to overlay directory name.
+ * @param {string} brainDir
+ * @returns {string|null} Overlay directory name (e.g., 'laravel', 'nextjs') or null
+ */
+function getDetectedFramework(brainDir) {
+  const detection = readDetection(brainDir);
+  if (!detection?.stack?.primary?.framework && !detection?.stack?.framework) return null;
+  const fw = (detection.stack.primary?.framework || detection.stack.framework).toLowerCase();
+  const map = {
+    'laravel': 'laravel', 'next.js': 'nextjs', 'react native': 'react-native',
+    'express': 'express', 'django': 'django', 'fastapi': 'fastapi',
+    'rails': 'rails', 'vue.js': 'vuejs', 'nestjs': 'nestjs',
+    'flutter': 'flutter', 'spring boot': 'spring-boot', 'sveltekit': 'sveltekit',
+    'astro': 'astro'
+  };
+  return map[fw] || null;
+}
+
 module.exports = {
   generateExpertise,
   generateContext7Queries,
   findFrameworkPattern,
+  getDetectedFramework,
   STACK_PATTERNS
 };

package/bin/lib/templates.cjs

@@ -45,4 +45,22 @@ function resolvePath(obj, dotPath) {
   return current;
 }
 
-module.exports = { loadTemplate, interpolate };
+/**
+ * Load a template with optional framework-specific overlay appended.
+ * Overlay files live in bin/templates/overlays/{framework}/{name}-overlay.md.
+ * @param {string} name - Template name (without .md)
+ * @param {string|null} framework - Framework overlay directory name (e.g., 'laravel', 'nextjs')
+ * @returns {string} Template content with overlay appended (if exists)
+ */
+function loadTemplateWithOverlay(name, framework) {
+  let template = loadTemplate(name);
+  if (framework) {
+    const overlayPath = path.join(TEMPLATES_DIR, 'overlays', framework, `${name}-overlay.md`);
+    if (fs.existsSync(overlayPath)) {
+      template += '\n\n' + fs.readFileSync(overlayPath, 'utf8');
+    }
+  }
+  return template;
+}
+
+module.exports = { loadTemplate, interpolate, loadTemplateWithOverlay };

package/bin/templates/executor.md

@@ -242,3 +242,15 @@ Include sections:
 - On successful completion of all tasks: `## EXECUTION COMPLETE`
 - On failure after retry: `## EXECUTION FAILED`
 - On checkpoint (user input needed): `## CHECKPOINT REACHED`
+
+## Pipeline Enforcement Reminders
+
+**EXECUTION FAILED:** When you output this marker:
+- The orchestrator will handle recovery (debugger agent or re-execution)
+- Do NOT start debugging manually. Do NOT skip to the next plan.
+- Follow the "Suggested actions" field ONLY.
+
+**CHECKPOINT REACHED:** When you output this marker:
+- STOP all implementation work immediately
+- The user MUST be asked via AskUserQuestion — do NOT pick an option yourself
+- Checkpoints exist because a HUMAN decision is required. Never skip them.

package/bin/templates/overlays/laravel/executor-overlay.md

@@ -0,0 +1,31 @@
+## Laravel-Specific Execution Rules
+
+### Migrations
+- Always create migration before model: `php artisan make:migration create_X_table`
+- Use `php artisan make:model -mf` to scaffold model + migration + factory together
+- Test migration rollback: `php artisan migrate:rollback --step=1`
+- Never modify existing migrations in production — create new ones
+
+### Eloquent
+- Use query scopes for reusable queries: `scopeActive`, `scopeVerified`
+- Never use raw SQL in controllers — use Eloquent or Query Builder
+- Always eager-load relationships: `User::with('posts')->get()` to prevent N+1
+- Use `$fillable` or `$guarded` on every model — never leave mass assignment unprotected
+
+### Controllers
+- Use API Resource Controllers: `php artisan make:controller UserController --api`
+- Validate with Form Requests, not inline: `php artisan make:request StoreUserRequest`
+- Return API Resources for JSON: `return new UserResource($user)`
+- Keep controllers thin — extract business logic to Service or Action classes
+
+### Queue Jobs
+- Always implement `ShouldQueue` for background tasks
+- Use `$tries` and `$backoff` properties for retry strategy
+- Implement `failed()` method for error handling
+- Never use `resolve()` in job constructor — serialize only IDs
+
+### Testing
+- Use `RefreshDatabase` trait for database tests
+- Use factories for test data: `User::factory()->create()`
+- Assert database state: `$this->assertDatabaseHas('users', ['email' => ...])`
+- Use `actingAs($user)` for authenticated requests

package/bin/templates/overlays/laravel/planner-overlay.md

@@ -0,0 +1,33 @@
+## Laravel-Specific Planning
+
+### Task Ordering
+1. **Database first**: Migrations and models before controllers
+2. **Validation second**: Form Requests before controller logic
+3. **API last**: Resources and routes after business logic
+4. **Tests throughout**: Each task should include its test
+
+### Standard Feature Pattern
+For each new feature, plan these tasks in order:
+1. Migration + Model + Factory
+2. Form Request (validation rules)
+3. Service/Action class (business logic)
+4. Controller (thin, delegates to service)
+5. API Resource (JSON serialization)
+6. Route registration + middleware
+7. Feature test
+
+### must_haves Template for Laravel
+```yaml
+truths:
+  - "Migration creates {table} with all required columns"
+  - "Model has $fillable for mass-assignable fields"
+  - "Form Request validates all user input with correct rules"
+  - "Controller delegates to Service, returns API Resource"
+  - "Feature test covers happy path and validation errors"
+artifacts:
+  - path: "database/migrations/xxxx_create_{table}_table.php"
+  - path: "app/Models/{Model}.php"
+  - path: "app/Http/Requests/{StoreModel}Request.php"
+  - path: "app/Http/Controllers/{Model}Controller.php"
+  - path: "tests/Feature/{Model}Test.php"
+```

package/bin/templates/overlays/laravel/verifier-overlay.md

@@ -0,0 +1,28 @@
+## Laravel-Specific Verification
+
+### Migration Checks
+- [ ] Migration file exists for every new model
+- [ ] Migration has both `up()` and `down()` methods
+- [ ] Foreign key constraints defined with `->constrained()`
+- [ ] Indexes added for frequently queried columns
+
+### Model Checks
+- [ ] `$fillable` or `$guarded` property set
+- [ ] Relationships defined (hasMany, belongsTo, etc.)
+- [ ] Factory exists in `database/factories/`
+
+### Controller Checks
+- [ ] Form Request used for validation (not inline `$request->validate()`)
+- [ ] API Resource used for JSON responses
+- [ ] No business logic in controller (delegated to Service/Action)
+
+### Route Checks
+- [ ] Route registered in `routes/api.php` or `routes/web.php`
+- [ ] Route uses middleware for authentication/authorization
+- [ ] RESTful naming convention followed
+
+### Test Checks
+- [ ] Feature test exists in `tests/Feature/`
+- [ ] Uses `RefreshDatabase` trait
+- [ ] Factory used for test data
+- [ ] HTTP assertions used (`assertStatus`, `assertJson`, etc.)

package/bin/templates/overlays/nextjs/executor-overlay.md

@@ -0,0 +1,24 @@
+## Next.js-Specific Execution Rules
+
+### App Router
+- Server Components are the default — only add `"use client"` when you need interactivity
+- Use `loading.tsx` for Suspense boundaries on async pages
+- Use `error.tsx` for error boundaries
+- Place shared layouts in `layout.tsx` at each route segment
+
+### Data Fetching
+- Fetch data in Server Components, not in client useEffect
+- Use Server Actions for mutations (form submissions, data writes)
+- Cache fetch results with `next.revalidate` or `cache: 'force-cache'`
+- Use `generateStaticParams()` for static generation of dynamic routes
+
+### API Route Handlers
+- Export named functions matching HTTP methods: `GET`, `POST`, `PUT`, `DELETE`
+- Use `NextRequest` and `NextResponse` types
+- Place in `app/api/` directory
+
+### Testing
+- Use `@testing-library/react` for component tests
+- Mock `next/navigation` hooks in tests
+- Test Server Components as async functions
+- Use `render()` + `screen.getByRole()` pattern

package/bin/templates/overlays/nextjs/verifier-overlay.md

@@ -0,0 +1,21 @@
+## Next.js-Specific Verification
+
+### Route Structure
+- [ ] Page components exist in `app/` directory structure
+- [ ] `loading.tsx` exists for pages with async data fetching
+- [ ] `error.tsx` exists for route segments with error-prone operations
+- [ ] `layout.tsx` exists for shared navigation/headers
+
+### Component Checks
+- [ ] Client components have `"use client"` directive at top
+- [ ] Server Components do NOT use hooks (useState, useEffect)
+- [ ] No `useEffect` for data fetching in server-renderable pages
+
+### API Route Checks
+- [ ] Route Handlers export correct HTTP method functions
+- [ ] Responses use `NextResponse.json()` format
+- [ ] Error responses return appropriate status codes
+
+### Metadata
+- [ ] Pages export `metadata` or `generateMetadata()` for SEO
+- [ ] Dynamic routes have `generateStaticParams()` if applicable

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

@@ -0,0 +1,28 @@
+## React Native-Specific Execution Rules
+
+### Platform Handling
+- Use `Platform.OS` or `Platform.select()` for platform-specific code
+- Create `.ios.tsx` and `.android.tsx` files for complex platform differences
+- Always test on both iOS and Android (or document platform limitations)
+
+### Navigation
+- Define navigation structure before building screens
+- Use typed navigation with `RootStackParamList`
+- Handle deep linking configuration early
+
+### Performance
+- Use `FlatList` with `keyExtractor` and `getItemLayout` for long lists
+- Avoid inline functions in render — use `useCallback`
+- Use `React.memo()` for pure components
+- Move heavy computation off the JS thread with `InteractionManager`
+
+### Styling
+- Always use `StyleSheet.create()` — never inline style objects
+- Use `Dimensions` or `useWindowDimensions` for responsive layouts
+- Test on different screen sizes
+
+### Testing
+- Use `@testing-library/react-native` for component tests
+- Mock native modules with `jest.mock()`
+- Test user interactions with `fireEvent`
+- Include platform-specific test cases

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

@@ -0,0 +1,20 @@
+## React Native-Specific Verification
+
+### Platform Checks
+- [ ] Platform-specific code uses `Platform.OS` or `Platform.select()`
+- [ ] No web-only APIs used (`document`, `window`, `localStorage`)
+- [ ] Assets imported with `require()` for local files
+
+### Component Checks
+- [ ] `FlatList` has `keyExtractor` and optimized rendering
+- [ ] `StyleSheet.create()` used (no inline style objects)
+- [ ] Navigation screens registered in navigator configuration
+
+### Performance Checks
+- [ ] No inline arrow functions in JSX render (use `useCallback`)
+- [ ] Heavy lists use `FlatList` not `ScrollView` with `.map()`
+- [ ] Images have explicit dimensions
+
+### Testing Checks
+- [ ] Component tests use `@testing-library/react-native`
+- [ ] Native modules properly mocked in jest setup

package/bin/templates/planner.md

@@ -196,6 +196,12 @@ If you cannot create a valid plan after **2 attempts** (e.g., checker keeps reje
 
 Do NOT produce incomplete or low-quality plans. Blocking with clear information is better than a plan that will fail during execution.
 
+**When PLANNING BLOCKED is output:**
+- Ask the user for the missing information using AskUserQuestion
+- Do NOT attempt to force a plan through
+- Do NOT rewrite requirements yourself
+- Wait for user input, then re-run /brain:plan
+
 ## Enriched SUMMARY.md
 
 After each plan executes, the executor creates a SUMMARY.md with:

package/bin/templates/verifier.md

@@ -220,3 +220,10 @@ When verification is complete, output:
 **Gaps:** [count of failed must_haves, or "none"]
 **Human items:** [count of items needing human verification, or "none"]
 ```
+
+## Pipeline Enforcement
+
+**When gaps_found or partial:**
+- Run `/brain:execute` with `--gaps-only` flag to fix specific gaps
+- Do NOT manually fix the files — the executor agent has the context to fix gaps properly
+- Do NOT skip to `/brain:complete` with unresolved gaps

package/commands/brain/adr.md

@@ -23,9 +23,16 @@ Supports creating new ADRs, listing existing ones, and searching decision histor
 </context>
 
 <critical-rules>
-- ALWAYS use `npx brain-dev adr` to manage ADRs. Never manually create ADR files in .brain/adrs/.
-- The CLI assigns sequential IDs, applies the template, and tracks status lifecycle.
-- Manual ADR creation can cause ID conflicts and missing metadata.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev adr $ARGUMENTS` 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>

package/commands/brain/auto.md

@@ -22,11 +22,16 @@ Each step tells you which agent to spawn and what prompt to use.
 </context>
 
 <critical-rules>
-- ALWAYS run `npx brain-dev execute --auto` to start. Never manually chain brain commands as a substitute.
-- Follow the generated runbook EXACTLY — each step tells you which command to run.
-- DO NOT skip steps or reorder them — the runbook respects phase dependencies.
-- On error, follow the error recovery decision tree in the runbook — do not improvise.
-- ALWAYS run `npx brain-dev execute --auto --stop` when done or on failure.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev execute --auto` 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>

package/commands/brain/complete.md

@@ -24,9 +24,16 @@ Ensures all phases are verified before completing.
 </context>
 
 <critical-rules>
-- ALWAYS run `npx brain-dev complete` FIRST. Never manually create git tags or archive files.
-- DO NOT skip the completion audit — it verifies all phases passed before archiving.
-- DO NOT mark phases as complete without running this command — it updates state, creates audit trails, and generates release notes.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev complete $ARGUMENTS` 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>

package/commands/brain/config.md

@@ -26,9 +26,16 @@ When no subcommand is given, launches an interactive menu.
 </context>
 
 <critical-rules>
-- ALWAYS use `npx brain-dev config` to change settings. Never manually edit brain.json config fields.
-- The CLI validates values against the schema — manual edits can set invalid values that break the pipeline.
-- Use `config docs` to see available settings before making changes.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev config $ARGUMENTS` 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>

package/commands/brain/discuss.md

@@ -22,10 +22,16 @@ Creates a CONTEXT.md file that feeds into the planning process.
 </context>
 
 <critical-rules>
-- ALWAYS run `npx brain-dev discuss` FIRST. Never skip discussion and go straight to planning.
-- DO NOT assume you know the right approach — the discuss step surfaces gray areas that cause rework later.
-- DO NOT write CONTEXT.md manually — the CLI provides the discuss template with stack-specific guidance.
-- Decisions made here feed directly into planning. Skipping discuss = plans based on assumptions.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev discuss $ARGUMENTS` 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>

package/commands/brain/execute.md

@@ -23,10 +23,16 @@ Discovers plans, analyzes dependencies, groups into waves, spawns subagents, and
 </context>
 
 <critical-rules>
-- ALWAYS run `npx brain-dev execute` FIRST. Never manually implement plan tasks yourself.
-- DO NOT read PLAN.md files and execute them manually — the CLI handles agent spawning, wave ordering, and progress tracking.
-- DO NOT skip to verification without running execute — the executor agent creates SUMMARY.md files that the verifier needs.
-- If execution fails, follow the EXECUTION FAILED output — do not improvise a fix outside the pipeline.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev execute $ARGUMENTS` 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>

package/commands/brain/health.md

@@ -22,9 +22,16 @@ Optionally auto-repairs safe issues with --fix.
 </context>
 
 <critical-rules>
-- ALWAYS run `npx brain-dev health` FIRST. Never manually fix hooks, templates, or state files.
-- The CLI knows which repairs are safe (auto-repairable) vs which need manual intervention.
-- DO NOT manually edit .brain/brain.json to fix health issues — use `--fix` flag instead.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev health $ARGUMENTS` 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>

package/commands/brain/new-project.md

@@ -12,9 +12,16 @@ Set up Brain for an existing or new project. Detects your stack, maps the codeba
 </objective>
 
 <critical-rules>
-- ALWAYS run `npx brain-dev new-project` FIRST. Never manually create PROJECT.md or edit brain.json project fields.
-- The CLI detects your stack, maps workspace siblings, and sets up detection.json — manual setup misses this.
-- ALWAYS use AskUserQuestion for the goal question — do not print options as text.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev new-project` 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>

package/commands/brain/new-task.md

@@ -22,20 +22,19 @@ Examples: "add payment integration", "refactor auth to JWT", "fix ATS rescoring
 </context>
 
 <critical-rules>
-NEVER skip the pipeline. Even if the fix seems obvious:
-- DO NOT start debugging, coding, or investigating before running `npx brain-dev new-task "description"`
-- DO NOT "just fix it" and skip discuss/plan/verify steps
-- The pipeline exists to catch edge cases, ensure test coverage, and create audit trails
-- A "quick fix" that skips pipeline often misses root causes or introduces regressions
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev new-task "description"` 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
 
-If the user describes a BUG:
-1. First run `npx brain-dev new-task "fix: description of bug"` to create the task
-2. The discuss step IS the investigation — use it to understand root cause
-3. The plan step defines the fix + tests
-4. The execute step implements with TDD
-5. The verify step confirms the fix works
+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.
 
-If the task seems too small for full pipeline, suggest `/brain:quick` instead. But NEVER skip pipeline silently.
+BUG WORKFLOW: User describes bug → `npx brain-dev new-task "fix: description"` → discuss (root cause) → plan (fix + tests) → execute (TDD) → verify → complete.
+If too small for full pipeline, suggest `/brain:quick` instead. NEVER skip pipeline silently.
 </critical-rules>
 
 <process>

package/commands/brain/pause.md

@@ -15,8 +15,16 @@ No arguments required. Captures current session state automatically.
 </context>
 
 <critical-rules>
-- ALWAYS run `npx brain-dev pause` to save state. Never manually write continue-here.md or edit session files.
-- The CLI captures decisions, plan state, and active work context that manual saves miss.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev pause` 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>

package/commands/brain/plan.md

@@ -25,10 +25,16 @@ Default flow: Research (if needed) -> Plan -> Verify -> Done.
 </context>
 
 <critical-rules>
-- ALWAYS run `npx brain-dev plan` FIRST. Never write PLAN.md files manually.
-- DO NOT skip the plan-checker verification loop — it catches requirement gaps and file ownership conflicts.
-- DO NOT proceed to execute without running plan — plans contain must_haves that the verifier checks against.
-- If planning fails, use `/brain:discuss` to clarify requirements — do not force a plan through.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev plan $ARGUMENTS` 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>

package/commands/brain/quick.md

@@ -28,11 +28,16 @@ Use subagent_type "brain-verifier" for verification (--full mode only).
 </agents>
 
 <critical-rules>
-- ALWAYS run `npx brain-dev quick` FIRST. Never skip the CLI and code directly.
-- Even quick tasks go through plan → execute → commit. The CLI generates the planner/executor prompts.
-- DO NOT manually write code without first having a plan from the CLI.
-- Follow the `nextAction` field in each CLI output — do not guess the next step.
-- If the task needs discussion or verification, use `/brain:new-task` instead.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev quick "description"` 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>

package/commands/brain/recover.md

@@ -13,9 +13,16 @@ Default mode shows what happened. Use --fix to auto-resume or --rollback to reve
 </objective>
 
 <critical-rules>
-- ALWAYS run `npx brain-dev recover` FIRST. Never manually edit brain.json, delete lock files, or reset state.
-- Manual state edits can corrupt the project — the CLI validates consistency before making changes.
-- Review the recovery briefing before choosing --fix or --rollback.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev recover` 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>

package/commands/brain/story.md

@@ -25,10 +25,16 @@ Stories are Brain's primary way to organize significant work. A story creates:
 </context>
 
 <critical-rules>
-- ALWAYS run `npx brain-dev story` FIRST. Never manually create research, requirements, or roadmap files.
-- DO NOT skip the research phase — it uses 6 parallel researchers that find pitfalls you'd miss manually.
-- DO NOT start coding before the story is fully activated (research → requirements → roadmap → activate).
-- After each step, run `npx brain-dev story --continue` — do not guess the next step.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev story "title"` 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>

package/commands/brain/verify.md

@@ -23,10 +23,16 @@ Produces a VERIFICATION.md report with pass/gaps/human_needed status.
 </context>
 
 <critical-rules>
-- ALWAYS run `npx brain-dev verify` FIRST. Never manually check must_haves yourself.
-- DO NOT declare work "done" or "verified" without running the verify command — it performs 3-level checks (exists, substantive, wired) that catch issues manual review misses.
-- DO NOT skip verification to save time — unverified work creates technical debt and regressions.
-- If verification finds gaps, use `/brain:plan --gaps` to create fix plans — do not manually patch.
+PIPELINE ENFORCEMENT (NON-NEGOTIABLE):
+1. Run `npx brain-dev verify $ARGUMENTS` 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>

package/hooks/bootstrap.sh

@@ -66,14 +66,29 @@ try {
     '',
     '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)',
     '',
-    'Instructions for Claude:',
-    '- When user types /brain:<command>, run: npx brain-dev <command> [args]',
-    '- EXCEPTION: For /brain:update, always run: npx brain-dev@latest update (the @latest is critical to avoid stale npx cache)',
-    '- Read output carefully and FOLLOW the step instructions. Do not skip steps or improvise.',
-    '- Use /brain:progress to check current state before suggesting next steps.',
-    '- NEVER run brain-dev init after an update. Updates are backward compatible.',
-    '- NEVER start coding/debugging before running the brain command. The pipeline IS the process.',
-    '- When user describes a bug or task, FIRST run the appropriate brain command (new-task, quick, story), THEN follow its output.',
+    'PIPELINE RULES (NON-NEGOTIABLE):',
+    '',
+    '1. ENTRY: When user describes ANY work (bug, feature, task), run the brain command FIRST.',
+    '   Do NOT read code, run git, or analyze before running: npx brain-dev <command>',
+    '   If you catch yourself analyzing: STOP, run the CLI, restart with CLI context.',
+    '',
+    '2. FOLLOW: When brain command outputs, find the nextAction field.',
+    '   Copy the exact command verbatim. Do NOT interpret, modify, or skip it.',
+    '   Human text is EXPLANATION. The nextAction field is the INSTRUCTION.',
+    '',
+    '3. NEVER ESCAPE: If you see EXECUTION FAILED, PLANNING BLOCKED, or gaps_found:',
+    '   Follow the recovery instructions in that output ONLY.',
+    '   Do NOT start debugging manually. Do NOT exit the pipeline.',
+    '',
+    '4. CHECKPOINTS: If you see CHECKPOINT REACHED:',
+    '   Use AskUserQuestion to ask the user. Do NOT pick an option yourself.',
+    '',
+    '5. AGENTS: When output says to spawn an agent (brain-planner, brain-executor):',
+    '   Use the Agent tool with the specified subagent_type. Do NOT execute the prompt yourself.',
+    '',
+    '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.',
     '--- End Brain Context ---'
   ];
   console.log(lines.join('\n'));

package/package.json

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