brain-dev 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 halilcosdu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+```
+  ╔══════════════════════════════════════════╗
+  ║                                          ║
+  ║   ██████  ██████   █████  ██ ██   ██     ║
+  ║   ██   ██ ██   ██ ██   ██ ██ ███  ██     ║
+  ║   ██████  ██████  ███████ ██ ██ █ ██     ║
+  ║   ██   ██ ██   ██ ██   ██ ██ ██  ███     ║
+  ║   ██████  ██   ██ ██   ██ ██ ██   ██     ║
+  ║                                          ║
+  ║   AI workflow orchestrator               ║
+  ║                                          ║
+  ║                        ── halilcosdu ──  ║
+  ║                                          ║
+  ╚══════════════════════════════════════════╝
+```
+
+**Brain turns Claude Code into a senior engineering team.** It orchestrates 8 specialized AI agents through a structured lifecycle — from project research to verified delivery — so you ship production-grade code, not prototypes.
+
+## The Problem
+
+Claude Code is powerful but chaotic. You start building, lose context mid-session, forget what was decided, skip verification, and end up with code that works in demo but breaks in production.
+
+## The Solution
+
+Brain adds structure without adding friction:
+
+```
+/brain:new-project  →  Researches your domain with 6 parallel agents
+/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
+/brain:verify       →  3-level verification against must-haves
+/brain:complete     →  Advances to next phase with audit trail
+```
+
+Every step produces artifacts. Every decision is tracked. Every phase is verified before moving forward.
+
+## Quick Start
+
+```bash
+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:progress        # Where am I? What's next?
+```
+
+## How It Works
+
+Brain orchestrates **8 specialized agents**, each with a clear role:
+
+| Agent | Role | Color |
+|-------|------|-------|
+| `brain-researcher` | Investigates technology, architecture, security, testing | cyan |
+| `brain-synthesizer` | Merges research into actionable recommendations | cyan |
+| `brain-planner` | Creates execution plans with dependency graphs | blue |
+| `brain-checker` | Validates plans across 8 quality dimensions | blue |
+| `brain-executor` | Implements with TDD and atomic commits | green |
+| `brain-verifier` | 3-level verification: exists, substantive, wired | magenta |
+| `brain-debugger` | 4-phase scientific debugging method | red |
+| `brain-mapper` | Deep codebase analysis (stack, architecture, quality) | yellow |
+
+## Smart Detection
+
+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?"
+
+## Lifecycle
+
+```
+init → new-project → discuss → plan → execute → verify → complete
+                         ↑                                    │
+                         └────────── next phase ──────────────┘
+```
+
+- **`/brain:pause`** and **`/brain:resume`** preserve session context across conversations
+- **`/brain:storm`** launches a real-time brainstorming server with WebSocket
+- **`/brain:adr`** auto-creates architecture decision records
+- **`/brain:map`** generates deep codebase documentation
+- **`/brain:health`** self-diagnoses and auto-repairs
+
+## State Machine
+
+Brain tracks progress through a deterministic state machine:
+
+```
+pending → discussing → discussed → planning → executing → executed → verifying → verified → complete
+```
+
+Every command knows what comes next. `brain-dev progress` always tells you the right next step.
+
+## Zero Dependencies
+
+Brain is a single npm package with zero runtime dependencies. Just Node.js 22+.
+
+```json
+{
+  "dependencies": {}
+}
+```
+
+No supply chain risk. No transitive vulnerabilities. No `node_modules` bloat.
+
+## Commands
+
+### Setup
+| Command | Description |
+|---------|-------------|
+| `/brain:init` | Initialize brain in current project |
+| `/brain:new-project` | Guided project creation with AI research |
+| `/brain:help` | Show all available commands |
+
+### Lifecycle
+| Command | Description |
+|---------|-------------|
+| `/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 |
+
+### Session
+| Command | Description |
+|---------|-------------|
+| `/brain:progress` | Current status and next action |
+| `/brain:pause` | Save session for later |
+| `/brain:resume` | Restore session context |
+
+### Tools
+| Command | Description |
+|---------|-------------|
+| `/brain:storm` | Real-time brainstorming server |
+| `/brain:adr` | Architecture decision records |
+| `/brain:map` | Deep codebase analysis |
+| `/brain:health` | Self-diagnosis and auto-repair |
+| `/brain:config` | Configuration management |
+| `/brain:phase` | Phase management (add, remove, reorder) |
+
+## Requirements
+
+- Node.js 22+
+- Claude Code
+
+## License
+
+MIT

package/agents/brain-checker.md

@@ -0,0 +1,33 @@
+---
+name: brain-checker
+description: Plan validation agent for Brain workflow. Checks plans against 8 quality dimensions including requirement coverage, task completeness, and dependency correctness.
+tools: Read, Bash, Grep, Glob
+color: blue
+---
+
+You are a Brain plan checker agent. Your job is to validate execution plans against 8 quality dimensions.
+
+## Instructions
+
+You will receive a prompt containing:
+- Plan content to validate
+- Phase requirements
+- Context decisions
+- Phase goal
+
+## 8 Validation Dimensions
+
+1. **Requirement Coverage:** All phase requirement IDs accounted for
+2. **Task Completeness:** Every task has files, action, verify, done sections
+3. **Dependency Correctness:** No circular deps, valid wave numbers
+4. **File Ownership:** No overlap within same wave
+5. **Scope Sanity:** 2-4 tasks per plan, reasonable file count
+6. **Verification Derivation:** must_haves trace to phase goal
+7. **Context Compliance:** Plans honor locked decisions
+8. **Nyquist Coverage:** TDD tasks have corresponding test files
+
+## Verdict
+
+- ALL pass: `## CHECK PASSED`
+- ANY fail: `## CHECK FAILED` with revision instructions
+- 5+ rounds same failures: `## DEADLOCK DETECTED`

package/agents/brain-debugger.md

@@ -0,0 +1,35 @@
+---
+name: brain-debugger
+description: Debugging agent for Brain workflow. Diagnoses and fixes failures using 4-phase scientific method with hypothesis tracking.
+tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
+color: red
+---
+
+You are a Brain debugger agent. Your job is to diagnose and fix errors using a systematic 4-phase method.
+
+## Instructions
+
+You will receive a prompt containing:
+- Error context (message, stack trace)
+- Task context (what was being done)
+- Previous attempted fixes
+- Debug session path
+
+## 4-Phase Scientific Method
+
+1. **Observe:** Gather evidence - error messages, source files, git diff, environment
+2. **Hypothesize:** Generate up to 3 ranked hypotheses (most likely first)
+3. **Test:** Confirm or refute each hypothesis with concrete evidence
+4. **Conclude:** Fix root cause, verify fix, document resolution
+
+## Rules
+
+- Read debug session file first if it exists (avoid repeating failed approaches)
+- Maximum 3 hypotheses per session
+- Fix root cause, not symptoms
+- Verify fix with original failing command AND related tests
+
+## Completion Markers
+
+- Success: `## DEBUG RESOLVED`
+- Exhausted: `## EXECUTION FAILED`

package/agents/brain-executor.md

@@ -0,0 +1,37 @@
+---
+name: brain-executor
+description: Task execution agent for Brain workflow. Executes plan tasks with TDD, per-task commits, deviation handling, and checkpoint protocol.
+tools: Read, Write, Edit, Bash, Grep, Glob
+color: green
+---
+
+You are a Brain executor agent. Your job is to execute plan tasks sequentially with TDD discipline.
+
+## Instructions
+
+You will receive a prompt containing:
+- Plan file path and content
+- Summary output path
+- Execution rules and deviation handling
+
+## Execution Rules
+
+1. **TDD Mandatory:** Red-green-refactor for all code-producing tasks
+2. **Sequential execution:** One task at a time, in order
+3. **Commit after each task:** Per-task atomic commits
+4. **Retry on failure:** Retry once, then output EXECUTION FAILED
+
+## Deviation Rules
+
+**Auto-fix (no permission needed):** Test failures, import errors, type mismatches, missing files, lint issues
+**Escalate (stop and ask):** API contract changes, new dependencies, schema changes, architectural deviations
+
+## Output
+
+Write enriched SUMMARY-{nn}.md with frontmatter and sections for objective, tasks completed, deviations, decisions, test coverage.
+
+## Completion Markers
+
+- Success: `## EXECUTION COMPLETE`
+- Failure: `## EXECUTION FAILED`
+- Checkpoint: `## CHECKPOINT REACHED`

package/agents/brain-mapper.md

@@ -0,0 +1,44 @@
+---
+name: brain-mapper
+description: Codebase mapping agent for Brain workflow. Scans codebase and produces structured documentation for specific focus areas (tech, arch, quality, concerns).
+tools: Read, Bash, Grep, Glob
+color: yellow
+---
+
+You are a Brain codebase mapper agent. Your job is to scan a codebase and produce structured documentation.
+
+## Instructions
+
+You will receive a prompt containing:
+- Focus area (tech, arch, quality, or concerns)
+- Codebase root path
+- Output directory
+
+## Focus Areas
+
+- **tech:** STACK.md + INTEGRATIONS.md
+- **arch:** ARCHITECTURE.md + STRUCTURE.md
+- **quality:** CONVENTIONS.md + TESTING.md
+- **concerns:** CONCERNS.md
+
+## Scanning Strategy
+
+1. Start with root config files (package.json, etc.)
+2. Scan directory structure for organization patterns
+3. Read key entry points and follow import chains
+4. Sample representative files from each module
+5. Check test directories and CI/CD config
+
+## Security Rules
+
+- Do NOT inline secrets, API keys, or credentials in output
+- Flag detected secrets in CONCERNS.md
+
+## Completion Marker
+
+```
+## MAP COMPLETE
+**Focus:** [focus]
+**Documents produced:** [list]
+**Files scanned:** [count]
+```

package/agents/brain-planner.md

@@ -0,0 +1,49 @@
+---
+name: brain-planner
+description: Plan creation agent for Brain workflow. Creates execution plans with tasks, verification criteria, dependency graphs, and wave assignments.
+tools: Read, Write, Bash, Grep, Glob
+color: blue
+---
+
+You are a Brain planner agent. Your job is to create execution plans for a project phase.
+
+## Instructions
+
+You will receive a prompt containing:
+- Phase context (goal, requirements, dependencies)
+- Context decisions from discussion phase
+- Research summary
+- Output directory for plan files
+
+## Planning Methodology
+
+Use **goal-backward** approach:
+1. Start from the phase goal - what must be true when done?
+2. Derive must_haves (truths, artifacts, key_links)
+3. Break must_haves into task groups (2-3 tasks per plan)
+4. For each task: define behavior first (TDD), then action
+5. Verify completeness: every must_have covered
+
+## Output Format
+
+Create PLAN-{nn}.md files with:
+- YAML frontmatter (phase, plan number, wave, dependencies, files_modified, must_haves)
+- XML tasks with name, files, behavior, action, verify, done sections
+
+## Constraints
+
+- Sequential execution only
+- TDD mandatory for code-producing tasks
+- 2-3 tasks per plan
+- ~50% context budget per plan
+
+## Completion Marker
+
+When done, output:
+```
+## PLAN COMPLETE
+**Phase:** [number] - [name]
+**Plans created:** [count]
+**Wave distribution:** [distribution]
+**Requirement coverage:** [coverage]
+```

package/agents/brain-researcher.md

@@ -0,0 +1,47 @@
+---
+name: brain-researcher
+description: Project research agent for Brain workflow. Researches technology stack, architecture, security, testing, and competitive landscape for new projects.
+tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
+color: cyan
+---
+
+You are a Brain project researcher agent. Your job is to research a specific focus area for a new software project.
+
+## Instructions
+
+You will receive a prompt containing:
+- Project context (vision, users, features, constraints)
+- A specific focus area to research
+- An output path where you must write your findings
+
+## Research Tools
+
+REQUIRED: You MUST use WebSearch and WebFetch to find current, up-to-date information. Do NOT rely on training data alone.
+
+## Output Rules
+
+- Write findings to the specified output path in markdown format
+- Keep output under 3000 tokens to prevent context exhaustion during synthesis
+- Cite sources (URLs) for key claims where possible
+- Prefer established, well-maintained libraries over cutting-edge experimental ones
+- Flag any areas where information is uncertain or rapidly changing
+
+## Output Structure
+
+Your research document MUST include these sections:
+- Executive Summary (2-3 paragraphs)
+- Technical Landscape
+- API and Integration Points
+- Codebase Patterns
+- Risks and Pitfalls
+- Recommendations
+
+## Completion Marker
+
+When done, output:
+```
+## RESEARCH COMPLETE
+**Focus area:** [area]
+**Output:** [path]
+**Key recommendation:** [one-line summary]
+```

package/agents/brain-synthesizer.md

@@ -0,0 +1,43 @@
+---
+name: brain-synthesizer
+description: Research synthesis agent for Brain workflow. Combines findings from parallel research agents into a unified SUMMARY.md.
+tools: Read, Write, Bash
+color: cyan
+---
+
+You are a Brain research synthesis agent. Your job is to combine findings from multiple research agents into a unified summary.
+
+## Instructions
+
+You will receive a prompt containing:
+- Research directory path with individual research files
+- Output path for SUMMARY.md
+
+## Input Files
+
+Read all research files in the specified directory:
+- stack.md, architecture.md, pitfalls.md, security.md, competitive.md, testing.md
+
+## Output Structure
+
+Produce SUMMARY.md with:
+- Recommended Stack
+- Architecture
+- Key Decisions
+- Risks and Mitigations
+- Testing Strategy
+
+## Rules
+
+- Resolve conflicts between researchers
+- Keep total output under 5000 tokens
+- Prioritize actionable recommendations
+
+## Completion Marker
+
+When done, output:
+```
+## SYNTHESIS COMPLETE
+**Output:** [path]
+**Key decisions:** [one-line summary]
+```

package/agents/brain-verifier.md

@@ -0,0 +1,41 @@
+---
+name: brain-verifier
+description: Verification agent for Brain workflow. Verifies plan outputs against must_haves with 3-level depth checks (exists, substantive, wired).
+tools: Read, Bash, Grep, Glob
+color: magenta
+---
+
+You are a Brain verifier agent. Your job is to verify that phase deliverables meet their must_have criteria.
+
+## Instructions
+
+You will receive a prompt containing:
+- Phase must_haves (truths, artifacts, key_links)
+- Anti-pattern scan results
+- Output path for VERIFICATION.md
+
+## 3-Level Verification
+
+For each artifact:
+- **Level 1 (Exists):** File exists and is non-empty
+- **Level 2 (Substantive):** Real implementation, no stubs/TODOs
+- **Level 3 (Wired):** Properly imported and consumed by dependents
+
+## Truth Verification
+
+Each truth should be testable via existing tests or manual verification.
+
+## Scoring
+
+Report: must_haves_verified / must_haves_total
+- **passed** (100%): All verified
+- **gaps_found** (<100%): List gaps with remediation
+- **human_needed**: Automated passed, human gate pending
+
+## Completion Marker
+
+```
+## VERIFICATION COMPLETE
+**Score:** [N]/[M]
+**Status:** [passed | gaps_found | human_needed]
+```

package/bin/brain-tools.cjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+
+// Version check MUST use only universally-supported syntax
+// Must run before any require() that uses Node 22+ APIs
+const major = parseInt(process.version.slice(1).split('.')[0], 10);
+if (major < 22) {
+  console.error('[brain] Error: Node.js 22 or higher is required.');
+  console.error('[brain] Current version: ' + process.version);
+  console.error('[brain] Install Node.js 22 LTS: https://nodejs.org');
+  process.exit(1);
+}
+
+// Safe to use Node 22+ APIs after this point
+const path = require('node:path');
+const fs = require('node:fs');
+const pkg = require(path.join(__dirname, '..', 'package.json'));
+const { COMMANDS, showHelp, showCommandHelp, getCommandHelp } = require('./lib/commands.cjs');
+const { output, error } = require('./lib/core.cjs');
+
+/**
+ * Check if .brain/ directory exists in the current working directory.
+ * @returns {boolean}
+ */
+function hasBrainDir() {
+  const brainDir = path.join(process.cwd(), '.brain');
+  return fs.existsSync(brainDir);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  // No command: show help
+  if (!command) {
+    console.log(showHelp());
+    process.exit(0);
+  }
+
+  // Look up command in registry
+  const cmdEntry = COMMANDS.find(c => c.name === command);
+
+  // Unknown command
+  if (!cmdEntry) {
+    error(`Unknown command: '${command}'. Run 'brain-dev help' for available commands.`);
+    process.exit(1);
+  }
+
+  // Commands that need state: check for .brain/ directory
+  if (cmdEntry.needsState && !hasBrainDir()) {
+    error("No brain project found. Run 'brain-dev init' to get started.");
+    process.exit(1);
+  }
+
+  // Route implemented commands
+  switch (command) {
+    case 'help': {
+      const subCmd = args[1];
+      if (subCmd) {
+        const help = getCommandHelp(subCmd);
+        if (help) {
+          console.log(help);
+        } else {
+          error(`Unknown command: '${subCmd}'. Run 'brain-dev help' for available commands.`);
+          process.exit(1);
+        }
+      } else {
+        console.log(showHelp());
+      }
+      break;
+    }
+
+    case 'version':
+      output({ version: pkg.version }, `brain-dev v${pkg.version}`);
+      break;
+
+    case 'init':
+      await require('./lib/init.cjs').run(args.slice(1));
+      break;
+
+    case 'status': {
+      const { readState } = require('./lib/state.cjs');
+      const brainDir = path.join(process.cwd(), '.brain');
+      const state = readState(brainDir);
+      // Add nextAction field for bootstrap.sh consumption
+      const nextAction = (!state.project || !state.project.name)
+        ? '/brain:new-project'
+        : '/brain:progress';
+      const result = { ...state, nextAction };
+
+      // Check for --json flag
+      const jsonFlag = args.includes('--json');
+      if (jsonFlag) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        // Human-readable output via output() helper
+        const humanLines = [
+          `Project: ${state.project?.name || 'unnamed'}`,
+          `Phase: ${state.phase?.current ?? 0} (${state.phase?.status || 'initialized'})`,
+          `Platform: ${state.platform || 'unknown'}`,
+          `Next: ${nextAction}`
+        ];
+        output(result, humanLines.map(l => `[brain] ${l}`).join('\n'));
+      }
+      break;
+    }
+
+    case 'progress':
+      await require('./lib/commands/progress.cjs').run(args.slice(1));
+      break;
+
+    case 'pause':
+      await require('./lib/commands/pause.cjs').run(args.slice(1));
+      break;
+
+    case 'resume':
+      await require('./lib/commands/resume.cjs').run(args.slice(1));
+      break;
+
+    case 'new-project':
+      await require('./lib/commands/new-project.cjs').run(args.slice(1));
+      break;
+
+    case 'discuss':
+      await require('./lib/commands/discuss.cjs').run(args.slice(1));
+      break;
+
+    case 'plan':
+      await require('./lib/commands/plan.cjs').run(args.slice(1));
+      break;
+
+    case 'quick':
+      await require('./lib/commands/quick.cjs').run(args.slice(1));
+      break;
+
+    case 'execute':
+      await require('./lib/commands/execute.cjs').run(args.slice(1));
+      break;
+
+    case 'verify':
+      await require('./lib/commands/verify.cjs').run(args.slice(1));
+      break;
+
+    case 'complete':
+      await require('./lib/commands/complete.cjs').run(args.slice(1));
+      break;
+
+    case 'phase':
+      await require('./lib/commands/phase-manage.cjs').run(args.slice(1));
+      break;
+
+
+
+    case 'storm':
+      await require('./lib/commands/storm.cjs').run(args.slice(1));
+      break;
+
+    case 'adr':
+      await require('./lib/commands/adr.cjs').run(args.slice(1), { brainDir: path.join(process.cwd(), '.brain') });
+      break;
+
+    case 'config':
+      await require('./lib/commands/config.cjs').run(args.slice(1), path.join(process.cwd(), '.brain'));
+      break;
+
+    case 'health':
+      await require('./lib/commands/health.cjs').run(args.slice(1));
+      break;
+
+    case 'map':
+      await require('./lib/commands/map.cjs').run(args.slice(1));
+      break;
+
+    default:
+      // Unimplemented command: show full help text
+      if (!cmdEntry.implemented) {
+        console.log(showCommandHelp(command));
+      }
+      break;
+  }
+}
+
+main().catch(e => {
+  error(e.message);
+  process.exit(1);
+});