brain-dev 1.0.1 → 1.1.0

package/README.md

@@ -136,6 +136,17 @@ Brain auto-detects your project on init:
 - **Workspace siblings**: Detects `myapp-mobile/`, `myapp-landing/` alongside `myapp/`
 - **Stack-aware**: Asks "I detected a Laravel (PHP) + Vue.js frontend. What do you want to do?" instead of generic "What are you building?"
 
+## Stack Expertise
+
+Brain automatically provides technology-specific guidance to all agents based on your detected stack:
+
+- **15+ frameworks built-in**: Laravel, Next.js, React Native, Express, Django, Rails, Vue.js, NestJS, Flutter, Spring Boot, FastAPI, Astro, SvelteKit, and more
+- **3-layer expertise**: Static patterns + project-specific codebase analysis + Context7 live documentation
+- **Role-aware**: Planner gets file structure guidance, executor gets CLI commands and anti-patterns, verifier gets convention checks
+- **Any technology works**: Unknown frameworks automatically use Context7 for latest documentation
+
+No configuration needed — Brain detects your stack and injects expertise into every pipeline stage.
+
 ## Lifecycle
 
 ```

package/bin/lib/commands/execute.cjs

@@ -9,6 +9,7 @@ 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');
 
 /**
  * Find a phase directory under .brain/phases/ matching a phase number.
@@ -354,7 +355,8 @@ async function run(args = [], opts = {}) {
     plan_content: planContent,
     phase: phaseMatch ? phaseMatch[1].trim() : String(phaseNumber),
     plan_number: planNumMatch ? planNumMatch[1].trim() : String(targetPlan.num),
-    subsystem: phaseMatch ? phaseMatch[1].trim() : String(phaseNumber)
+    subsystem: phaseMatch ? phaseMatch[1].trim() : String(phaseNumber),
+    stack_expertise: generateExpertise(brainDir, 'executor')
   });
 
   // Append orchestration instructions to prompt

package/bin/lib/commands/plan.cjs

@@ -9,6 +9,7 @@ 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');
 
 /**
  * Find a phase directory under .brain/phases/ matching a phase number.
@@ -90,7 +91,8 @@ function generatePlannerPrompt(phase, brainDir) {
     research_summary: researchSection,
     output_dir: outputDir,
     phase_number_padded: padded,
-    phase_slug: slug
+    phase_slug: slug,
+    stack_expertise: generateExpertise(brainDir, 'planner')
   });
 
   return { prompt, output_dir: outputDir };

package/bin/lib/commands/quick.cjs

@@ -7,6 +7,7 @@ const { loadTemplate, interpolate } = require('../templates.cjs');
 const { resolveModel } = require('../agents.cjs');
 const { logEvent } = require('../logger.cjs');
 const { output, error, success } = require('../core.cjs');
+const { generateExpertise } = require('../stack-expert.cjs');
 
 /**
  * Generate a URL-safe slug from a description.
@@ -163,7 +164,8 @@ function handleInit(args, brainDir, state) {
     research_summary: '_Quick mode: no research phase._',
     output_dir: taskDir,
     phase_number_padded: String(nextNum).padStart(3, '0'),
-    phase_slug: slug
+    phase_slug: slug,
+    stack_expertise: generateExpertise(brainDir, 'executor')
   });
 
   const quickConstraints = [
@@ -249,7 +251,8 @@ function handleExecute(args, brainDir, state) {
     plan_content: planContent,
     phase: `Q${taskNum}`,
     plan_number: '1',
-    subsystem: `quick-${taskNum}`
+    subsystem: `quick-${taskNum}`,
+    stack_expertise: generateExpertise(brainDir, 'executor')
   });
 
   const model = resolveModel('executor', state);

package/bin/lib/context.cjs

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { estimateTokens } = require('./tokens.cjs');
+const { generateExpertise } = require('./stack-expert.cjs');
 
 // Token budgets per agent type
 const CONTEXT_BUDGETS = {
@@ -17,6 +18,7 @@ const CONTEXT_BUDGETS = {
 const PRIORITY_TIERS = {
   P0_PLAN: 0,
   P1_STATE: 1,
+  P1_5_STACK_EXPERTISE: 1.5,
   P2_PHASE_CONTEXT: 2,
   P3_PRIOR_SUMMARIES: 3,
   P4_RESEARCH: 4,
@@ -157,6 +159,14 @@ function buildContextManifest(brainDir, phaseDir, planNum) {
     required: true
   });
 
+  // P1.5: Stack Expertise (required, synthetic - handled separately)
+  manifest.push({
+    tier: PRIORITY_TIERS.P1_5_STACK_EXPERTISE,
+    label: 'Stack Expertise',
+    path: '__SYNTHETIC_STACK_EXPERTISE__',
+    required: true
+  });
+
   // P2: Phase CONTEXT.md decisions (required)
   if (phaseDir) {
     manifest.push({
@@ -255,7 +265,7 @@ function detectStaleContext(manifest, referenceTimestamp) {
   const staleFiles = [];
 
   for (const entry of manifest) {
-    if (entry.path === '__SYNTHETIC_PRIOR_SUMMARIES__') continue;
+    if (entry.path === '__SYNTHETIC_PRIOR_SUMMARIES__' || entry.path === '__SYNTHETIC_STACK_EXPERTISE__') continue;
     try {
       const stat = fs.statSync(entry.path);
       if (stat.mtime.getTime() > refTime) {
@@ -300,7 +310,10 @@ function assembleTaskContext(brainDir, phaseDir, planNum, opts) {
     let content;
     let sectionHeader;
 
-    if (entry.path === '__SYNTHETIC_PRIOR_SUMMARIES__') {
+    if (entry.path === '__SYNTHETIC_STACK_EXPERTISE__') {
+      content = generateExpertise(brainDir, agentType);
+      sectionHeader = '## Stack Expertise';
+    } else if (entry.path === '__SYNTHETIC_PRIOR_SUMMARIES__') {
       content = collectPriorSummaries(phaseDir, planNum);
       sectionHeader = '## Prior Plan Results';
     } else {

package/bin/lib/stack-expert.cjs

@@ -0,0 +1,308 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readDetection } = require('./story-helpers.cjs');
+
+// Knowledge base: language → framework → expertise rules
+// NOT hardcoded content — generates guidance from PATTERNS
+const STACK_PATTERNS = {
+  // Language-level patterns
+  languages: {
+    php: { testFramework: 'PHPUnit', packageManager: 'composer', naming: 'PSR-4 namespacing, snake_case for DB columns' },
+    javascript: { testFramework: 'Jest/Vitest', packageManager: 'npm/yarn', naming: 'camelCase functions, PascalCase components' },
+    typescript: { testFramework: 'Jest/Vitest', packageManager: 'npm/yarn', naming: 'camelCase, PascalCase types, interfaces prefixed with I optional' },
+    python: { testFramework: 'pytest', packageManager: 'pip/poetry', naming: 'snake_case everywhere, PascalCase classes' },
+    go: { testFramework: 'go test', packageManager: 'go mod', naming: 'camelCase private, PascalCase exported' },
+    ruby: { testFramework: 'RSpec/Minitest', packageManager: 'bundler', naming: 'snake_case methods, PascalCase classes' },
+    rust: { testFramework: 'cargo test', packageManager: 'cargo', naming: 'snake_case, PascalCase types' },
+    java: { testFramework: 'JUnit', packageManager: 'maven/gradle', naming: 'camelCase methods, PascalCase classes' },
+    swift: { testFramework: 'XCTest', packageManager: 'SPM', naming: 'camelCase, PascalCase types' },
+    kotlin: { testFramework: 'JUnit/Kotest', packageManager: 'gradle', naming: 'camelCase, PascalCase classes' }
+  },
+
+  // 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'
+    },
+    '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'
+    },
+    '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'
+    },
+    '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'
+    },
+    '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'
+    },
+    'Rails': {
+      structure: 'app/models, app/controllers, config/routes.rb, db/migrate',
+      keyCommands: 'rails generate, rails db:migrate, rails server',
+      patterns: 'ActiveRecord, RESTful routes, concerns, service objects',
+      antiPatterns: 'Fat models (extract services), callbacks abuse, N+1 (use includes)',
+      testing: 'RSpec + FactoryBot, system tests with Capybara'
+    },
+    'Vue.js': {
+      structure: 'src/components, src/views, src/stores (Pinia), src/router',
+      keyCommands: 'npm run dev, npm run build',
+      patterns: 'Composition API, Pinia stores, Vue Router, SFC (Single File Components)',
+      antiPatterns: 'Options API in new code, mutating props, watchers for everything',
+      testing: 'Vitest + Vue Test Utils'
+    },
+    'NestJS': {
+      structure: 'src/modules/<name>/, <name>.controller.ts, <name>.service.ts, <name>.module.ts',
+      keyCommands: 'nest generate, nest start --watch',
+      patterns: 'Dependency injection, decorators, guards, interceptors, pipes',
+      antiPatterns: 'Business logic in controllers, skipping DTOs, circular dependencies',
+      testing: 'Jest with @nestjs/testing, e2e with supertest'
+    },
+    'Flutter': {
+      structure: 'lib/screens, lib/widgets, lib/models, lib/services',
+      keyCommands: 'flutter run, flutter build, flutter test',
+      patterns: 'BLoC/Provider/Riverpod state management, Widget composition, Navigator 2.0',
+      antiPatterns: 'Deep widget trees (extract widgets), setState everywhere, blocking UI thread',
+      testing: 'flutter_test, widget tests, integration_test'
+    },
+    'Spring Boot': {
+      structure: 'src/main/java/com/example/, controllers/, services/, repositories/',
+      keyCommands: 'mvn spring-boot:run, ./gradlew bootRun',
+      patterns: '@RestController, @Service, @Repository, JPA entities, @Autowired',
+      antiPatterns: 'Field injection (use constructor), business logic in controllers, N+1 JPA',
+      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'
+    },
+    'Astro': {
+      structure: 'src/pages, src/components, src/layouts, public/',
+      keyCommands: 'npm run dev, astro build',
+      patterns: 'Islands architecture, .astro components, content collections, SSG by default',
+      antiPatterns: 'Client-side JS when static works, large island components, ignoring content collections',
+      testing: 'Vitest for logic, Playwright for E2E'
+    },
+    'SvelteKit': {
+      structure: 'src/routes, src/lib, src/lib/components',
+      keyCommands: 'npm run dev, npm run build',
+      patterns: 'File-based routing, load functions, stores, form actions',
+      antiPatterns: 'Client-side fetching in load functions, reactive statements abuse',
+      testing: 'Vitest + @testing-library/svelte, Playwright'
+    }
+  }
+};
+
+/**
+ * Generate role-specific technology expertise from 3 layers.
+ * @param {string} brainDir
+ * @param {string} [role='general'] - 'planner' | 'executor' | 'verifier' | 'general'
+ * @returns {string} Markdown expertise block for template injection
+ */
+function generateExpertise(brainDir, role = 'general') {
+  const detection = readDetection(brainDir);
+  if (!detection) return '';
+
+  const sections = [];
+  const stack = detection.stack || {};
+  const lang = stack.language || stack.primary?.language;
+  const framework = stack.framework || stack.primary?.framework;
+  const frontend = stack.frontend;
+  const features = detection.features || [];
+
+  sections.push('## Stack Expertise');
+  sections.push('');
+
+  // Language guidance
+  const langInfo = lang ? STACK_PATTERNS.languages[lang.toLowerCase()] : null;
+  if (langInfo) {
+    sections.push(`### Language: ${lang}`);
+    sections.push(`- Test framework: ${langInfo.testFramework}`);
+    sections.push(`- Package manager: ${langInfo.packageManager}`);
+    sections.push(`- Naming: ${langInfo.naming}`);
+    sections.push('');
+  }
+
+  // Primary framework guidance
+  const fwInfo = framework ? findFrameworkPattern(framework) : null;
+  if (fwInfo) {
+    sections.push(`### Framework: ${framework}`);
+    sections.push(`- **File structure:** ${fwInfo.structure}`);
+    sections.push(`- **Key commands:** ${fwInfo.keyCommands}`);
+    sections.push(`- **Patterns to follow:** ${fwInfo.patterns}`);
+    sections.push(`- **Anti-patterns to AVOID:** ${fwInfo.antiPatterns}`);
+    sections.push(`- **Testing:** ${fwInfo.testing}`);
+    sections.push('');
+  }
+
+  // Frontend framework (multi-stack)
+  if (frontend?.framework) {
+    const frontendInfo = findFrameworkPattern(frontend.framework);
+    if (frontendInfo) {
+      sections.push(`### Frontend: ${frontend.framework}`);
+      sections.push(`- **Structure:** ${frontendInfo.structure}`);
+      sections.push(`- **Patterns:** ${frontendInfo.patterns}`);
+      sections.push(`- **Anti-patterns:** ${frontendInfo.antiPatterns}`);
+      if (frontend.css) sections.push(`- **CSS:** ${frontend.css}`);
+      if (frontend.bundler) sections.push(`- **Bundler:** ${frontend.bundler}`);
+      sections.push('');
+    }
+  }
+
+  // Feature-specific guidance
+  if (features.length > 0) {
+    sections.push(`### Detected Features`);
+    sections.push(`This project already has: ${features.join(', ')}`);
+    sections.push('When modifying these features, extend existing patterns rather than rebuilding.');
+    sections.push('');
+  }
+
+  // Workspace siblings
+  if (detection.workspace?.siblings?.length > 0) {
+    sections.push(`### Related Projects`);
+    for (const s of detection.workspace.siblings) {
+      sections.push(`- **${s.name}:** ${s.stack?.framework || s.stack?.language || 'unknown'}`);
+    }
+    sections.push('Consider API contract compatibility when modifying shared interfaces.');
+    sections.push('');
+  }
+
+  // LAYER 2: Codebase analysis (project-specific patterns)
+  const codebaseDir = path.join(brainDir, 'codebase');
+  if (fs.existsSync(codebaseDir)) {
+    const conventionsPath = path.join(codebaseDir, 'CONVENTIONS.md');
+    const stackPath = path.join(codebaseDir, 'STACK.md');
+
+    if (fs.existsSync(conventionsPath)) {
+      const conventions = fs.readFileSync(conventionsPath, 'utf8');
+      const excerpt = conventions.slice(0, 2000); // Keep concise
+      sections.push('### Project-Specific Conventions (from codebase analysis)');
+      sections.push(excerpt);
+      sections.push('');
+    }
+
+    if (role === 'planner' && fs.existsSync(stackPath)) {
+      const stackAnalysis = fs.readFileSync(stackPath, 'utf8');
+      const excerpt = stackAnalysis.slice(0, 1500);
+      sections.push('### Existing Stack Details');
+      sections.push(excerpt);
+      sections.push('');
+    }
+  }
+
+  // LAYER 3: Context7 live documentation queries
+  if (framework || lang) {
+    sections.push(generateContext7Queries(brainDir));
+  }
+
+  // Unknown framework: Context7 becomes PRIMARY (not fallback)
+  if (!fwInfo && (framework || lang)) {
+    sections.push(`### ${framework || lang} Project`);
+    sections.push(`IMPORTANT: No built-in patterns for ${framework || lang}.`);
+    sections.push('You MUST use Context7 to look up framework conventions BEFORE writing code:');
+    sections.push(`1. Use resolve-library-id to find "${framework || lang}"`);
+    sections.push('2. Query for: file structure, naming conventions, testing patterns');
+    sections.push('3. Follow the retrieved conventions strictly');
+    sections.push('');
+  }
+
+  // Role-specific guidance
+  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');
+    sections.push('');
+  } 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');
+    sections.push('');
+  } 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('');
+  }
+
+  return sections.join('\n');
+}
+
+/**
+ * Find a framework pattern by name (case-insensitive, partial match).
+ * @param {string} name - Framework name to look up
+ * @returns {object|null} Framework pattern object or null
+ */
+function findFrameworkPattern(name) {
+  // Case-insensitive, partial match
+  for (const [key, value] of Object.entries(STACK_PATTERNS.frameworks)) {
+    if (key.toLowerCase() === name.toLowerCase() ||
+        name.toLowerCase().includes(key.toLowerCase())) {
+      return value;
+    }
+  }
+  return null;
+}
+
+/**
+ * Generate Context7 lookup instructions for the detected stack.
+ * @param {string} brainDir
+ * @returns {string} Context7 query instructions
+ */
+function generateContext7Queries(brainDir) {
+  const detection = readDetection(brainDir);
+  if (!detection) return '';
+
+  const framework = detection.stack?.framework || detection.stack?.primary?.framework;
+  const lang = detection.stack?.language || detection.stack?.primary?.language;
+
+  if (!framework && !lang) return '';
+
+  const lines = [];
+  lines.push('### Live Documentation (Context7)');
+  lines.push('If Context7 MCP is available, query for latest docs:');
+  if (framework) {
+    lines.push(`1. resolve-library-id: "${framework}"`);
+    lines.push(`2. query-docs with the resolved ID for task-relevant topics`);
+  }
+  if (lang && lang !== 'javascript' && lang !== 'typescript') {
+    lines.push(`- Also check: "${lang} standard library" for core patterns`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+module.exports = {
+  generateExpertise,
+  generateContext7Queries,
+  findFrameworkPattern,
+  STACK_PATTERNS
+};

package/bin/lib/state.cjs

@@ -4,7 +4,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const CURRENT_SCHEMA = 'brain/v1';
-const CURRENT_VERSION = '1.0.0';
+const CURRENT_VERSION = '1.1.0';
 
 /**
  * Atomic write: write to temp file, then rename.

package/bin/templates/executor.md

@@ -1,5 +1,14 @@
 # Executor Agent Instructions
 
+## Technology Context
+{{stack_expertise}}
+
+When implementing, follow the framework patterns above:
+- Place files in the correct framework directories
+- Use framework-specific naming conventions
+- Avoid the listed anti-patterns
+- Write tests using the detected test framework
+
 ## Plan to Execute
 
 **Plan file:** {{plan_path}}

package/bin/templates/planner.md

@@ -2,6 +2,12 @@
 
 You are a planner agent creating execution plans for **Phase {{phase_number}}: {{phase_name}}**.
 
+## Technology Context
+{{stack_expertise}}
+
+When creating plans, ensure tasks follow the framework patterns above.
+File paths, naming, and testing approach must match the detected stack.
+
 ## Phase Context
 
 **Goal:** {{phase_goal}}

package/bin/templates/verifier.md

@@ -1,5 +1,14 @@
 # Verifier Agent Instructions
 
+## Technology Context
+{{stack_expertise}}
+
+During verification, check:
+- Files are in correct framework directories
+- Naming follows framework conventions
+- No anti-patterns from the list above
+- Tests use the correct test framework
+
 ## Phase Must-Haves
 
 {{must_haves}}

package/package.json

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