brain-dev 2.1.0 → 2.2.1

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

package/bin/lib/commands/plan.cjs

@@ -8,7 +8,7 @@ const { loadTemplate, interpolate, loadTemplateWithOverlay } = require('../templ
 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 { output, error, success, pipelineGate } = require('../core.cjs');
 const { generateExpertise, getDetectedFramework } = require('../stack-expert.cjs');
 
 /**
@@ -317,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/verify.cjs

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

package/bin/lib/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

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

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/nextjs/planner-overlay.md

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

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

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

package/bin/templates/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.1.0",
+  "version": "2.2.1",
   "description": "AI-powered development workflow orchestrator",
   "author": "halilcosdu",
   "license": "MIT",