brain-dev 2.0.3 → 2.0.4

package/commands/brain/adr.md

@@ -22,6 +22,12 @@ Supports creating new ADRs, listing existing ones, and searching decision histor
 - `search <query>` — Search ADRs by keyword or tag
 </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.
+</critical-rules>
+
 <process>
 1. Run the brain CLI to manage ADRs:
 ```bash

package/commands/brain/auto.md

@@ -21,6 +21,14 @@ Auto mode generates a runbook of steps. Follow each step's instructions sequenti
 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.
+</critical-rules>
+
 <process>
 1. Run: `npx brain-dev execute --auto` (or `--dry-run` to preview)
 2. Follow the generated runbook instructions step by step

package/commands/brain/complete.md

@@ -23,6 +23,12 @@ Ensures all phases are verified before completing.
 - `--force` — Force completion even if some verifications are pending
 </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.
+</critical-rules>
+
 <process>
 1. Run the brain CLI to complete the milestone:
 ```bash

package/commands/brain/config.md

@@ -25,6 +25,12 @@ When no subcommand is given, launches an interactive menu.
 - `--global` — Apply to global config instead of project config
 </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.
+</critical-rules>
+
 <process>
 1. Run the brain CLI to manage configuration:
 ```bash

package/commands/brain/discuss.md

@@ -21,6 +21,13 @@ Creates a CONTEXT.md file that feeds into the planning process.
 `$ARGUMENTS` is the phase number (e.g., `1`, `2`).
 </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.
+</critical-rules>
+
 <process>
 1. Run the brain CLI for the given phase:
 ```bash

package/commands/brain/execute.md

@@ -22,6 +22,13 @@ Discovers plans, analyzes dependencies, groups into waves, spawns subagents, and
 - `--gaps-only` — Execute only gap closure plans created by verify
 </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.
+</critical-rules>
+
 <process>
 1. Run the brain CLI to execute plans:
 ```bash

package/commands/brain/health.md

@@ -21,6 +21,12 @@ Optionally auto-repairs safe issues with --fix.
 - `--quick` — Run only critical checks, skip deep analysis
 </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.
+</critical-rules>
+
 <process>
 1. Run the brain CLI to check health:
 ```bash

package/commands/brain/new-project.md

@@ -11,6 +11,12 @@ allowed-tools:
 Set up Brain for an existing or new project. Detects your stack, maps the codebase, then asks what you want to do next.
 </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.
+</critical-rules>
+
 <process>
 1. Run the detection:
 ```bash

package/commands/brain/pause.md

@@ -14,6 +14,11 @@ Safe to close the session after this command completes.
 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.
+</critical-rules>
+
 <process>
 1. Run the brain CLI to save state:
 ```bash

package/commands/brain/plan.md

@@ -24,6 +24,13 @@ Default flow: Research (if needed) -> Plan -> Verify -> Done.
 - `--skip-verify` — Skip the verification loop after plan creation
 </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.
+</critical-rules>
+
 <process>
 1. Run the brain CLI to generate plans:
 ```bash

package/commands/brain/quick.md

@@ -27,6 +27,14 @@ Use subagent_type "brain-executor" for execution.
 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.
+</critical-rules>
+
 <process>
 1. Run: `npx brain-dev quick [--full] "task description"`
    - CLI creates task directory, generates planner prompt

package/commands/brain/recover.md

@@ -12,6 +12,12 @@ Check for interrupted sessions and recover safely.
 Default mode shows what happened. Use --fix to auto-resume or --rollback to revert.
 </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.
+</critical-rules>
+
 <process>
 1. Run: `npx brain-dev recover`
 2. Review the recovery briefing

package/commands/brain/story.md

@@ -24,6 +24,13 @@ Stories are Brain's primary way to organize significant work. A story creates:
 - Phases (discuss → plan → execute → verify → complete)
 </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.
+</critical-rules>
+
 <process>
 1. Start: `npx brain-dev story "v1.1 Feature title"`
 2. Answer the vision/scope questions

package/commands/brain/verify.md

@@ -22,6 +22,13 @@ Produces a VERIFICATION.md report with pass/gaps/human_needed status.
 - `--auto-recover` — Automatically create and execute gap closure plans for failures
 </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.
+</critical-rules>
+
 <process>
 1. Run the brain CLI to verify the phase:
 ```bash

package/package.json

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