brain-dev 2.1.0 → 2.2.0

package/bin/lib/commands/discuss.cjs

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

package/bin/lib/commands/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/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/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/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.0",
   "description": "AI-powered development workflow orchestrator",
   "author": "halilcosdu",
   "license": "MIT",