brain-dev 0.3.0 → 1.0.0

package/bin/lib/commands.cjs

@@ -20,12 +20,12 @@ const COMMANDS = [
   },
   {
     name: 'new-project',
-    description: 'Start a new project with guided questioning',
-    usage: 'brain-dev new-project [--answers <json>] [--synthesize] [--generate-roadmap] [--finalize]',
+    description: 'Detect and map project, suggest next step',
+    usage: 'brain-dev new-project [--answers <json>]',
     group: 'Setup',
     implemented: true,
     needsState: true,
-    args: '  --answers <json>      Provide user answers as JSON\n  --synthesize           Spawn synthesis agent\n  --generate-roadmap     Generate REQUIREMENTS.md and ROADMAP.md\n  --finalize             Finalize project setup\n  --project-name <name>  Project name (used with --finalize)'
+    args: '  --answers <json>      Provide user answers as JSON (goal and name)'
   },
   {
     name: 'help',
@@ -65,6 +65,15 @@ const COMMANDS = [
     needsState: true,
     args: '  --full            Enable plan checking + verification\n  --execute --task N  Execute task N\n  --verify --task N   Verify task N (--full only)\n  --complete --task N Complete and commit task N'
   },
+  {
+    name: 'story',
+    description: 'Start a body of work with research, requirements, and roadmap',
+    usage: 'brain-dev story "title" [--continue] [--list] [--complete]',
+    group: 'Lifecycle',
+    implemented: true,
+    needsState: true,
+    args: '  "title"        Story title (optionally with version: "v1.1 Feature")\n  --continue     Resume current story step\n  --list         List all stories\n  --complete     Complete current story\n  --status       Show story progress\n  --research     Force research phase\n  --no-research  Skip research'
+  },
   {
     name: 'new-task',
     description: 'Create a significant task with full pipeline',

package/bin/lib/state.cjs

@@ -4,7 +4,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const CURRENT_SCHEMA = 'brain/v1';
-const CURRENT_VERSION = '0.9.0';
+const CURRENT_VERSION = '1.0.0';
 
 /**
  * Atomic write: write to temp file, then rename.
@@ -181,6 +181,11 @@ function migrateState(data) {
     migrated.tasks = { current: null, count: 0, active: [], history: [] };
   }
 
+  // v1.0.0 fields (story system)
+  if (!migrated.stories) {
+    migrated.stories = { current: null, count: 0, active: [], history: [] };
+  }
+
   return migrated;
 }
 
@@ -341,6 +346,14 @@ function generateStateMd(state) {
     lines.push(`- Completed: ${state.tasks.history ? state.tasks.history.length : 0}`);
   }
 
+  if (state.stories && state.stories.active && state.stories.active.length > 0) {
+    lines.push('');
+    lines.push('## Active Stories');
+    for (const s of state.stories.active) {
+      lines.push(`- ${s.version}: ${s.title} (${s.status})`);
+    }
+  }
+
   lines.push('## Blockers');
 
   if (Array.isArray(blockers) && blockers.length > 0) {
@@ -468,6 +481,12 @@ function createDefaultState(platform) {
       count: 0,
       active: [],
       history: []
+    },
+    stories: {
+      current: null,
+      count: 0,
+      active: [],
+      history: []
     }
   };
 }

package/bin/lib/story-helpers.cjs

@@ -0,0 +1,439 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * 6 research focus areas for new-project research phase.
+ * Each area spawns a dedicated researcher agent.
+ * @type {Array<{name: string, file: string, area: string, description: string}>}
+ */
+const RESEARCH_AREAS = [
+  { name: 'stack-researcher', file: 'stack.md', area: 'Technology Stack & Ecosystem', description: 'technology stack, frameworks, libraries, and ecosystem tools' },
+  { name: 'architecture-researcher', file: 'architecture.md', area: 'Architecture Patterns', description: 'architecture patterns, project structure, and design decisions' },
+  { name: 'pitfalls-researcher', file: 'pitfalls.md', area: 'Pitfalls & Anti-patterns', description: 'common pitfalls, anti-patterns, and mistakes to avoid' },
+  { name: 'security-researcher', file: 'security.md', area: 'Security & Compliance', description: 'security requirements, compliance needs, and vulnerability prevention' },
+  { name: 'competitive-researcher', file: 'competitive.md', area: 'Competitive Analysis', description: 'competitive landscape, similar products, and differentiation opportunities' },
+  { name: 'testing-researcher', file: 'testing.md', area: 'Testing Strategy', description: 'testing approach, coverage targets, and quality assurance strategy' }
+];
+
+/**
+ * Core vision-first questions for greenfield (new) projects.
+ * Each question includes AskUserQuestion-compatible options as guidance templates.
+ * @type {Array<{id: string, text: string, header: string, multiSelect?: boolean, options: Array<{label: string, description: string}>}>}
+ */
+const CORE_QUESTIONS = [
+  {
+    id: 'vision',
+    text: 'What are you building? Describe the core idea in 1-2 sentences.',
+    header: 'Project Type',
+    options: [
+      { label: 'Web Application', description: 'Full-stack web app with frontend and backend' },
+      { label: 'API / Backend Service', description: 'REST/GraphQL API or microservice' },
+      { label: 'CLI Tool', description: 'Command-line tool or developer utility' },
+      { label: 'Mobile App', description: 'iOS/Android or cross-platform mobile application' }
+    ]
+  },
+  {
+    id: 'users',
+    text: 'Who is it for? Who are the primary users?',
+    header: 'Target Users',
+    options: [
+      { label: 'Developers', description: 'Software engineers and technical users' },
+      { label: 'End Users', description: 'Non-technical consumers or business users' },
+      { label: 'Internal Team', description: 'Internal tools for your organization' },
+      { label: 'B2B Customers', description: 'Business clients and enterprise users' }
+    ]
+  },
+  {
+    id: 'features',
+    text: 'What must it do? List the 3-5 most critical features.',
+    header: 'Core Features',
+    multiSelect: true,
+    options: [
+      { label: 'Auth & Users', description: 'User registration, login, roles, permissions' },
+      { label: 'CRUD & Data', description: 'Create, read, update, delete operations with database' },
+      { label: 'Real-time', description: 'WebSocket, live updates, notifications' },
+      { label: 'Integrations', description: 'Third-party APIs, payment, email, etc.' }
+    ]
+  },
+  {
+    id: 'constraints',
+    text: 'Any constraints? (tech stack preferences, timeline, budget, existing codebase)',
+    header: 'Constraints',
+    options: [
+      { label: 'Existing Codebase', description: 'Adding to or extending an existing project' },
+      { label: 'Specific Stack', description: 'Must use a particular language/framework' },
+      { label: 'Tight Timeline', description: 'MVP or deadline-driven development' },
+      { label: 'No Constraints', description: 'Flexible on technology and timeline' }
+    ]
+  }
+];
+
+/**
+ * Build brownfield (existing project) questions dynamically from detection results.
+ * @param {object} detection - Detection result from detectProject()
+ * @returns {Array} AskUserQuestion-compatible question specs
+ */
+function buildBrownfieldQuestions(detection) {
+  const { stack, features, summary, workspace } = detection;
+
+  // Question 1: Vision/Goal - context-aware with workspace
+  let visionText = `I detected a ${summary}. What do you want to do?`;
+  if (workspace && workspace.siblings.length > 0) {
+    const sibNames = workspace.siblings.map(s => `${s.name} (${s.stack ? (s.stack.framework || s.stack.language || 'unknown') : 'unknown'})`).join(', ');
+    visionText = `I detected a ${summary}. I also found ${workspace.siblings.length} related project(s): ${sibNames}. What do you want to do?`;
+  }
+
+  const visionQuestion = {
+    id: 'vision',
+    text: visionText,
+    header: 'Goal',
+    options: [
+      { label: 'Add New Feature', description: 'Build something new on top of the existing codebase' },
+      { label: 'Refactor / Improve', description: 'Improve architecture, performance, or code quality' },
+      { label: 'Fix & Stabilize', description: 'Fix bugs, add tests, improve reliability' },
+      { label: 'Scale & Optimize', description: 'Performance optimization, scaling, infrastructure' }
+    ]
+  };
+
+  // Question 2: Users - same as greenfield but context-aware text
+  const usersQuestion = {
+    id: 'users',
+    text: 'Who are the current or target users of this project?',
+    header: 'Target Users',
+    options: [
+      { label: 'Developers', description: 'Software engineers and technical users' },
+      { label: 'End Users', description: 'Non-technical consumers or business users' },
+      { label: 'Internal Team', description: 'Internal tools for your organization' },
+      { label: 'B2B Customers', description: 'Business clients and enterprise users' }
+    ]
+  };
+
+  // Question 3: Features/Priorities - dynamically built from detection
+  const featureOptions = [];
+  // Add detected features as "extend" options (max 2)
+  for (const feat of features.slice(0, 2)) {
+    featureOptions.push({ label: `Extend ${feat}`, description: `Build on existing ${feat} capability` });
+  }
+  // Fill remaining slots with generic options (total max 4)
+  const genericFeatureOpts = [
+    { label: 'New Feature', description: 'Something not yet in the codebase' },
+    { label: 'Testing & Quality', description: 'Improve test coverage and code quality' },
+    { label: 'Performance', description: 'Optimize speed, memory, or resource usage' },
+    { label: 'Documentation', description: 'Improve docs, README, API documentation' }
+  ];
+  for (const opt of genericFeatureOpts) {
+    if (featureOptions.length >= 4) break;
+    featureOptions.push(opt);
+  }
+
+  const featuresText = features.length > 0
+    ? `I found these capabilities: ${features.join(', ')}. What's the next priority?`
+    : 'What are the most important features or improvements?';
+
+  const featuresQuestion = {
+    id: 'features',
+    text: featuresText,
+    header: 'Priorities',
+    multiSelect: true,
+    options: featureOptions
+  };
+
+  // Question 4: Constraints - stack-aware (use primary stack)
+  const primary = stack.primary || stack;
+  const stackLabel = primary.framework || (primary.language ? primary.language.charAt(0).toUpperCase() + primary.language.slice(1) : 'current stack');
+  const constraintsText = primary.framework
+    ? `The project uses ${primary.framework}${primary.language ? ` (${primary.language})` : ''}. Any additional constraints?`
+    : 'Any constraints? (timeline, budget, compatibility)';
+
+  const constraintsQuestion = {
+    id: 'constraints',
+    text: constraintsText,
+    header: 'Constraints',
+    options: [
+      { label: `Keep ${stackLabel}`, description: 'Stay within the existing technology choices' },
+      { label: 'Allow Migration', description: 'Open to changing frameworks or libraries' },
+      { label: 'Tight Timeline', description: 'MVP or deadline-driven development' },
+      { label: 'No Constraints', description: 'Flexible on approach' }
+    ]
+  };
+
+  return [visionQuestion, usersQuestion, featuresQuestion, constraintsQuestion];
+}
+
+/**
+ * Read detection.json from .brain/ directory.
+ * @param {string} brainDir - Path to the .brain directory
+ * @returns {object|null} Parsed detection data, or null if not found/invalid
+ */
+function readDetection(brainDir) {
+  try {
+    const detPath = path.join(brainDir, 'detection.json');
+    if (!fs.statSync(detPath).isFile()) return null;
+    const content = fs.readFileSync(detPath, 'utf8');
+    const data = JSON.parse(content);
+    if (!data || typeof data !== 'object' || !data.type) return null;
+    // Ensure stack.primary exists for safe access
+    if (data.stack && !data.stack.primary) {
+      data.stack.primary = { language: data.stack.language || null, framework: data.stack.framework || null, runtime: data.stack.runtime || null, dependencies: data.stack.dependencies || [] };
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build codebase context string for brownfield researcher prompts.
+ * Formats detected stack, features, and workspace info into a markdown section.
+ * @param {object} detection - Detection result from detectProject()
+ * @returns {string} Markdown-formatted codebase context
+ */
+function buildCodebaseContext(detection) {
+  const { stack, features, signals, workspace } = detection;
+  const primary = stack.primary || stack;
+  const lines = [
+    '',
+    '## Existing Codebase Context',
+    '',
+    'This is NOT a greenfield project. An existing codebase was detected:',
+  ];
+
+  if (primary.framework) {
+    lines.push(`- **Primary Stack:** ${primary.framework}${primary.language ? ` (${primary.language})` : ''}`);
+  } else if (primary.language) {
+    lines.push(`- **Language:** ${primary.language}`);
+  }
+
+  // Frontend stack (when separate from primary, e.g., Laravel + Vue.js)
+  if (stack.frontend) {
+    const feParts = [stack.frontend.framework, stack.frontend.bundler, stack.frontend.css].filter(Boolean).join(' + ');
+    if (feParts) {
+      lines.push(`- **Frontend:** ${feParts}`);
+    }
+  }
+
+  if (features.length > 0) {
+    lines.push(`- **Existing features:** ${features.join(', ')}`);
+  }
+
+  if (signals.codeFiles > 0) {
+    lines.push(`- **Size:** ${signals.codeFiles} source files`);
+  }
+
+  if (signals.commitCount > 0) {
+    lines.push(`- **History:** ${signals.commitCount} commits`);
+  }
+
+  const deps = primary.dependencies || [];
+  if (deps.length > 0) {
+    lines.push(`- **Key dependencies:** ${deps.slice(0, 5).join(', ')}`);
+  }
+
+  // Workspace siblings
+  if (workspace && workspace.siblings.length > 0) {
+    lines.push('');
+    lines.push('### Related Projects in Workspace');
+    for (const sib of workspace.siblings) {
+      lines.push(`- **${sib.name}:** ${sib.stack ? (sib.stack.framework || sib.stack.language || 'unknown') : 'unknown'}`);
+    }
+    lines.push('');
+    lines.push('Consider how this project integrates with sibling projects.');
+  }
+
+  lines.push('');
+  lines.push('**IMPORTANT:** Research should focus on EXTENDING/IMPROVING this existing codebase, not starting from scratch.');
+  lines.push('Consider compatibility with the existing stack and patterns.');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate PROJECT.md content from user answers, marking unknowns as TBD.
+ * Optionally includes an existing codebase section for brownfield projects.
+ * @param {object} answers - User answers (vision, users, features, constraints)
+ * @param {object} [detection] - Detection result for brownfield projects
+ * @returns {string} PROJECT.md markdown content
+ */
+function generateProjectMd(answers, detection) {
+  const tbd = (val) => {
+    if (!val) return 'TBD';
+    if (Array.isArray(val)) return val.join(', ') || 'TBD';
+    if (typeof val !== 'string') return String(val);
+    const lower = val.toLowerCase().trim();
+    if (lower === "i don't know yet" || lower === 'idk' || lower === 'not sure' || lower === 'tbd') {
+      return 'TBD';
+    }
+    return val;
+  };
+
+  const lines = [
+    '# Project',
+    '',
+    '## Vision',
+    tbd(answers.vision),
+    '',
+    '## Users',
+    tbd(answers.users),
+    '',
+    '## Features',
+    tbd(answers.features),
+    '',
+    '## Constraints',
+    tbd(answers.constraints),
+    ''
+  ];
+
+  // Add existing codebase section for brownfield projects
+  if (detection && detection.type === 'brownfield') {
+    const primary = detection.stack.primary || detection.stack;
+    lines.push('## Existing Codebase');
+    if (primary.framework) {
+      lines.push(`- **Stack:** ${primary.framework}${primary.language ? ` (${primary.language})` : ''}`);
+    } else if (primary.language) {
+      lines.push(`- **Language:** ${primary.language}`);
+    }
+    if (detection.stack.frontend) {
+      const feParts = [detection.stack.frontend.framework, detection.stack.frontend.bundler, detection.stack.frontend.css].filter(Boolean).join(' + ');
+      if (feParts) lines.push(`- **Frontend:** ${feParts}`);
+    }
+    if (detection.features.length > 0) {
+      lines.push(`- **Features:** ${detection.features.join(', ')}`);
+    }
+    if (detection.signals.codeFiles > 0) {
+      lines.push(`- **Size:** ${detection.signals.codeFiles} source files`);
+    }
+    if (detection.signals.commitCount > 0) {
+      lines.push(`- **Commits:** ${detection.signals.commitCount}`);
+    }
+    lines.push(`- **Status:** Active development`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate REQUIREMENTS.md content with hierarchical IDs grouped by category.
+ * Creates categories from user features and research summary content.
+ * @param {string[]} features - List of feature strings extracted from PROJECT.md
+ * @param {string} summaryContent - Content of the research SUMMARY.md
+ * @returns {{requirementsMd: string, categories: Array}} Generated markdown and category data
+ */
+function generateRequirementsMd(features, summaryContent) {
+  // Create categories from features and summary
+  const categories = [];
+
+  // Category 1: Core features (from user's feature list)
+  if (features.length > 0) {
+    const reqIds = features.map((_, i) => `1.${i + 1}`);
+    categories.push({
+      name: 'Core Features',
+      goal: 'Implement the primary functionality',
+      reqIds,
+      items: features.map((f, i) => ({ id: `1.${i + 1}`, text: f }))
+    });
+  }
+
+  // Category 2: Infrastructure (from research summary)
+  const infraItems = [];
+  if (summaryContent.includes('Stack') || summaryContent.includes('stack')) {
+    infraItems.push({ id: '2.1', text: 'Setup recommended technology stack' });
+  }
+  if (summaryContent.includes('Architecture') || summaryContent.includes('architecture')) {
+    infraItems.push({ id: '2.2', text: 'Implement recommended architecture patterns' });
+  }
+  if (infraItems.length > 0) {
+    categories.push({
+      name: 'Infrastructure',
+      goal: 'Setup project infrastructure and architecture',
+      reqIds: infraItems.map(i => i.id),
+      items: infraItems
+    });
+  }
+
+  // Category 3: Quality (testing + security from summary)
+  const qualityItems = [];
+  if (summaryContent.includes('Testing') || summaryContent.includes('testing')) {
+    qualityItems.push({ id: '3.1', text: 'Implement testing strategy' });
+  }
+  if (summaryContent.includes('Security') || summaryContent.includes('security')) {
+    qualityItems.push({ id: '3.2', text: 'Implement security requirements' });
+  }
+  if (qualityItems.length > 0) {
+    categories.push({
+      name: 'Quality & Security',
+      goal: 'Ensure quality and security standards',
+      reqIds: qualityItems.map(i => i.id),
+      items: qualityItems
+    });
+  }
+
+  // Fallback: if no categories created, make a default one
+  if (categories.length === 0) {
+    categories.push({
+      name: 'Setup',
+      goal: 'Initialize the project',
+      reqIds: ['1.1'],
+      items: [{ id: '1.1', text: 'Project initialization' }]
+    });
+  }
+
+  // Generate markdown
+  const lines = ['# Requirements', ''];
+
+  for (const cat of categories) {
+    lines.push(`## ${cat.name}`);
+    lines.push('');
+    for (const item of cat.items) {
+      lines.push(`- **${item.id}** ${item.text}`);
+    }
+    lines.push('');
+  }
+
+  return { requirementsMd: lines.join('\n'), categories };
+}
+
+/**
+ * Extract features list from PROJECT.md content.
+ * Parses lines under the "## Features" heading that start with list markers.
+ * @param {string} content - Full PROJECT.md content
+ * @returns {string[]} Array of feature strings
+ */
+function extractFeatures(content) {
+  const featSection = extractSection(content, 'Features');
+  if (!featSection) return [];
+
+  // Split by lines starting with - or numbered items
+  return featSection
+    .split('\n')
+    .map(l => l.replace(/^[-*\d.)\s]+/, '').trim())
+    .filter(l => l.length > 0);
+}
+
+/**
+ * Extract a markdown section's content by heading name.
+ * Looks for "## heading" and returns text until the next "## " or end of content.
+ * @param {string} content - Full markdown content
+ * @param {string} heading - Section heading to find (without the ## prefix)
+ * @returns {string} Trimmed section content, or empty string if not found
+ */
+function extractSection(content, heading) {
+  const regex = new RegExp(`## ${heading}\\s*\\n([\\s\\S]*?)(?=\\n## |$)`);
+  const match = content.match(regex);
+  return match ? match[1].trim() : '';
+}
+
+module.exports = {
+  RESEARCH_AREAS,
+  CORE_QUESTIONS,
+  buildBrownfieldQuestions,
+  readDetection,
+  buildCodebaseContext,
+  generateProjectMd,
+  generateRequirementsMd,
+  extractFeatures,
+  extractSection
+};

package/commands/brain/story.md

@@ -0,0 +1,35 @@
+---
+name: brain:story
+description: Start a body of work with research, requirements, roadmap, and phased execution
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+---
+<objective>
+Start a new story (milestone) — a cohesive body of work with multiple phases.
+Brain researches the domain, generates requirements, creates a roadmap, then guides execution.
+</objective>
+
+<context>
+Stories are Brain's primary way to organize significant work. A story creates:
+- Research (6 parallel domain researchers)
+- Requirements (hierarchical REQ-IDs)
+- Roadmap (phased execution plan)
+- Phases (discuss → plan → execute → verify → complete)
+</context>
+
+<process>
+1. Start: `npx brain-dev story "v1.1 Feature title"`
+2. Answer the vision/scope questions
+3. Save answers: `npx brain-dev story --answers '{"vision":"...","users":"...","features":"...","constraints":"..."}'`
+4. Continue through steps: `npx brain-dev story --continue` (repeat until story is active)
+5. Work on phases: `/brain:discuss`, `/brain:plan`, `/brain:execute`, `/brain:verify`, `/brain:complete`
+6. Complete story: `npx brain-dev story --complete`
+7. List stories: `npx brain-dev story --list`
+</process>

package/hooks/bootstrap.sh

@@ -48,7 +48,7 @@ try {
     'Phase: ' + (data.phase && data.phase.current || 0) + ' (' + (data.phase && data.phase.status || 'initialized') + ')',
     'Next: ' + (data.nextAction || '/brain:new-project'),
     '',
-    'Commands: /brain:new-project, /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:storm, /brain:adr, /brain:phase, /brain:config, /brain:map, /brain:recover, /brain:dashboard, /brain:auto (or execute --auto)',
+    '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: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]',

package/package.json

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