brain-dev 0.3.0 → 1.0.0

package/README.md

@@ -25,7 +25,8 @@ Claude Code is powerful but chaotic. You start building, lose context mid-sessio
 Brain adds structure without adding friction:
 
 ```
-/brain:new-project  →  Researches your domain with 6 parallel agents
+/brain:new-project  →  Detects your stack, maps your codebase
+/brain:story        →  Researches domain, creates roadmap with phases
 /brain:discuss      →  Captures architectural decisions before coding
 /brain:plan         →  Creates verified execution plans with TDD
 /brain:execute      →  Builds with per-task commits and deviation handling
@@ -44,10 +45,74 @@ npx brain-dev init
 That's it. Brain detects your project (Laravel, Next.js, Go, Python — any stack), registers its agents, and is ready.
 
 ```bash
-/brain:new-project     # Guided project setup with AI research
+/brain:new-project     # Detect project, map codebase, choose next step
+/brain:story "v1.0 MVP"  # Start a body of work with research + roadmap
 /brain:progress        # Where am I? What's next?
 ```
 
+## Work Hierarchy
+
+Brain provides four levels of work, from lightweight to comprehensive:
+
+```
+quick        →  plan → execute → commit                    (minutes)
+new-task     →  discuss → plan → execute → verify           (hours)
+story        →  research → requirements → roadmap → phases  (days/weeks)
+new-project  →  detect → map → suggest next step            (one-time setup)
+```
+
+## Stories
+
+Stories are Brain's primary way to organize significant work. A story = a milestone.
+
+```bash
+/brain:story "v1.0 MVP"
+```
+
+Brain researches your domain with 6 parallel agents, generates requirements with REQ-IDs, creates a phased roadmap, then guides execution phase by phase.
+
+```bash
+/brain:story --continue        # Resume current story step
+/brain:story --list            # List all stories
+/brain:story --complete        # Complete story, bump version
+/brain:story --status          # Show story progress
+```
+
+| Flag | What happens |
+|------|-------------|
+| Default | questions → research → requirements → roadmap → activate |
+| `--no-research` | Skip research (codebase already well-known) |
+| `--research` | Force research even if codebase mapped |
+
+Stories live in `.brain/stories/`. On activation, ROADMAP.md and REQUIREMENTS.md are copied to `.brain/` root for phase execution.
+
+## Significant Tasks
+
+For features that need more than a quick fix but less than a full story:
+
+```bash
+/brain:new-task "add payment integration with Stripe"
+```
+
+Brain runs the full pipeline: discuss → plan → execute → verify → complete.
+
+```bash
+/brain:new-task --research "add rate limiting"   # With light research
+/brain:new-task --light "fix auth redirect"       # Skip discuss + verify
+/brain:new-task --continue                        # Resume current task
+/brain:new-task --list                            # List all tasks
+/brain:new-task --promote 1                       # Adds task as a phase in ROADMAP.md
+```
+
+## Quick Tasks
+
+Not everything needs a full phase. For small, focused work:
+
+```bash
+/brain:quick "fix the login redirect bug"
+/brain:quick --full "add rate limiting to API"   # With plan checking + verification
+```
+
 ## How It Works
 
 Brain orchestrates **8 specialized agents**, each with a clear role:
@@ -69,14 +134,14 @@ Brain auto-detects your project on init:
 
 - **Multi-manifest**: Recognizes Laravel + Vue.js, Django + React, Go + npm — not just the first manifest found
 - **Workspace siblings**: Detects `myapp-mobile/`, `myapp-landing/` alongside `myapp/`
-- **Stack-aware questions**: Asks "I detected a Laravel (PHP) + Vue.js frontend. What do you want to do?" instead of generic "What are you building?"
+- **Stack-aware**: Asks "I detected a Laravel (PHP) + Vue.js frontend. What do you want to do?" instead of generic "What are you building?"
 
 ## Lifecycle
 
 ```
-init → new-project → discuss → plan → execute → verify → complete
-                         ↑                                    │
-                         └────────── next phase ──────────────┘
+init → new-project → story → discuss → plan → execute → verify → complete
+                       ↑                                             │
+                       └──────────── next story/phase ───────────────┘
 ```
 
 - **`/brain:pause`** and **`/brain:resume`** preserve session context across conversations
@@ -84,56 +149,20 @@ init → new-project → discuss → plan → execute → verify → complete
 - **`/brain:adr`** auto-creates architecture decision records
 - **`/brain:map`** generates deep codebase documentation
 - **`/brain:health`** self-diagnoses and auto-repairs
+- **`/brain:dashboard`** live monitoring with phase progress, cost, stuck detection
+- **`/brain:recover`** crash detection and recovery
 
-## Quick Tasks
+## Auto Mode
 
-Not everything needs a full phase. For small, focused work:
+Run phases autonomously without human intervention:
 
 ```bash
-/brain:quick "fix the login redirect bug"
+/brain:execute --auto          # Start autonomous execution
+/brain:execute --auto --dry-run  # Preview without executing
+/brain:execute --auto --stop     # Stop running auto session
 ```
 
-Brain creates a plan, executes it, and commits — all in one flow. No discuss, no research, no ceremony.
-
-```bash
-/brain:quick --full "add rate limiting to API"   # With plan checking + verification
-```
-
-| Mode | What happens |
-|------|-------------|
-| Default | plan → execute → commit |
-| `--full` | plan → check → execute → verify → commit |
-
-Quick tasks live in `.brain/quick/`, separate from phases. Tracked in STATE.md.
-
-## Significant Tasks
-
-For features that need more than a quick fix but less than a new project:
-
-```bash
-/brain:new-task "add payment integration with Stripe"
-```
-
-Brain runs the full pipeline: discuss → plan → execute → verify → complete.
-
-```bash
-/brain:new-task --research "add rate limiting"   # With light research
-/brain:new-task --light "fix auth redirect"       # Skip discuss + verify
-/brain:new-task --continue                        # Resume current task
-/brain:new-task --list                            # List all tasks
-```
-
-After completion, promote to your roadmap:
-
-```bash
-/brain:new-task --promote 1    # Adds task as a phase in ROADMAP.md
-```
-
-| Mode | Pipeline |
-|------|----------|
-| Standard | discuss → plan → execute → verify → complete |
-| `--light` | plan → execute → commit |
-| `--research` | discuss → research → plan → execute → verify → complete |
+Auto mode chains: discuss → plan → execute → verify → complete → next phase, with budget limits, stuck detection, and crash recovery built in.
 
 ## State Machine
 
@@ -163,19 +192,21 @@ No supply chain risk. No transitive vulnerabilities. No `node_modules` bloat.
 | Command | Description |
 |---------|-------------|
 | `/brain:init` | Initialize brain in current project |
-| `/brain:new-project` | Guided project creation with AI research |
+| `/brain:new-project` | Detect project, map codebase, suggest next step |
 | `/brain:help` | Show all available commands |
 
 ### Lifecycle
 | Command | Description |
 |---------|-------------|
+| `/brain:story` | Start a body of work with research, requirements, roadmap |
 | `/brain:discuss` | Capture architectural decisions |
 | `/brain:plan` | Create verified execution plans |
 | `/brain:execute` | Build according to plans with TDD |
 | `/brain:verify` | 3-level verification against must-haves |
 | `/brain:complete` | Mark phase done, advance to next |
 | `/brain:quick` | Quick task — skip the ceremony |
-| `/brain:new-task` | Significant task — full pipeline without a new project |
+| `/brain:new-task` | Significant task — full pipeline |
+| `/brain:phase` | Phase management (add, remove, reorder) |
 
 ### Session
 | Command | Description |
@@ -183,6 +214,8 @@ No supply chain risk. No transitive vulnerabilities. No `node_modules` bloat.
 | `/brain:progress` | Current status and next action |
 | `/brain:pause` | Save session for later |
 | `/brain:resume` | Restore session context |
+| `/brain:recover` | Detect and recover from crashes |
+| `/brain:dashboard` | Live monitoring dashboard |
 
 ### Tools
 | Command | Description |
@@ -192,7 +225,6 @@ No supply chain risk. No transitive vulnerabilities. No `node_modules` bloat.
 | `/brain:map` | Deep codebase analysis |
 | `/brain:health` | Self-diagnosis and auto-repair |
 | `/brain:config` | Configuration management |
-| `/brain:phase` | Phase management (add, remove, reorder) |
 
 ## Requirements
 

package/bin/brain-tools.cjs

@@ -132,6 +132,10 @@ async function main() {
       await require('./lib/commands/quick.cjs').run(args.slice(1));
       break;
 
+    case 'story':
+      await require('./lib/commands/story.cjs').run(args.slice(1));
+      break;
+
     case 'new-task':
       await require('./lib/commands/new-task.cjs').run(args.slice(1));
       break;