brain-dev 2.0.5 → 2.1.0

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 { 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);

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

@@ -3,6 +3,22 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { output, prefix } = require('../core.cjs');
 
+/**
+ * Read installed version from brain.json or package.json fallback.
+ * @param {string} brainDir
+ * @returns {string}
+ */
+function getInstalledVersion(brainDir) {
+  try {
+    const state = JSON.parse(fs.readFileSync(path.join(brainDir, 'brain.json'), 'utf8'));
+    if (state.version && state.version !== 'unknown') return state.version;
+  } catch {}
+  try {
+    return require(path.join(__dirname, '..', '..', '..', 'package.json')).version;
+  } catch {}
+  return 'unknown';
+}
+
 async function run(args = [], opts = {}) {
   const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
 
@@ -13,12 +29,14 @@ async function run(args = [], opts = {}) {
     cache = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
   } catch {}
 
+  const installed = cache?.installed || getInstalledVersion(brainDir);
+
   if (!cache || !cache.update_available) {
     const lines = [
       prefix('You are on the latest version.'),
-      prefix(`Installed: ${cache?.installed || 'unknown'}`)
+      prefix(`Installed: ${installed}`)
     ];
-    output({ action: 'up-to-date', installed: cache?.installed || 'unknown' }, lines.join('\n'));
+    output({ action: 'up-to-date', installed }, lines.join('\n'));
     return { action: 'up-to-date' };
   }
 

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/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/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/package.json

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