brain-dev 0.1.0

package/bin/lib/commands/plan.cjs

@@ -0,0 +1,451 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState, writeState } = require('../state.cjs');
+const { parseRoadmap } = require('../roadmap.cjs');
+const { loadTemplate, interpolate } = require('../templates.cjs');
+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');
+
+/**
+ * Find a phase directory under .brain/phases/ matching a phase number.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @returns {string|null} Path to phase directory, or null
+ */
+function findPhaseDir(brainDir, phaseNumber) {
+  const phasesDir = path.join(brainDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return null;
+
+  const padded = String(phaseNumber).padStart(2, '0');
+  const match = fs.readdirSync(phasesDir).find(d => d.startsWith(`${padded}-`));
+  return match ? path.join(phasesDir, match) : null;
+}
+
+/**
+ * Read CONTEXT.md content for a phase if it exists.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @returns {string|null}
+ */
+function readContext(brainDir, phaseNumber) {
+  const phaseDir = findPhaseDir(brainDir, phaseNumber);
+  if (!phaseDir) return null;
+
+  const contextPath = path.join(phaseDir, 'CONTEXT.md');
+  if (!fs.existsSync(contextPath)) return null;
+  return fs.readFileSync(contextPath, 'utf8');
+}
+
+/**
+ * Read research SUMMARY.md for a phase if it exists.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @returns {string|null}
+ */
+function readResearchSummary(brainDir, phaseNumber) {
+  const phaseDir = findPhaseDir(brainDir, phaseNumber);
+  if (!phaseDir) return null;
+
+  const summaryPath = path.join(phaseDir, 'SUMMARY.md');
+  if (!fs.existsSync(summaryPath)) return null;
+  return fs.readFileSync(summaryPath, 'utf8');
+}
+
+/**
+ * Generate the planner prompt for a single phase.
+ * @param {object} phase - Phase data from roadmap
+ * @param {string} brainDir
+ * @returns {{ prompt: string, output_dir: string }}
+ */
+function generatePlannerPrompt(phase, brainDir) {
+  const template = loadTemplate('planner');
+
+  const contextContent = readContext(brainDir, phase.number);
+  const researchContent = readResearchSummary(brainDir, phase.number);
+
+  const contextSection = contextContent
+    ? `**Context Decisions:**\n${contextContent}`
+    : '_No CONTEXT.md found. Consider running /brain:discuss first._';
+
+  const researchSection = researchContent
+    ? `**Research Summary:**\n${researchContent}`
+    : '_No research summary available._';
+
+  const padded = String(phase.number).padStart(2, '0');
+  const slug = phase.name.toLowerCase().replace(/\s+/g, '-');
+  const phaseDir = findPhaseDir(brainDir, phase.number);
+  const outputDir = phaseDir || path.join(brainDir, 'phases', `${padded}-${slug}`);
+
+  const prompt = interpolate(template, {
+    phase_number: phase.number,
+    phase_name: phase.name,
+    phase_goal: phase.goal,
+    phase_requirements: phase.requirements.join(', ') || 'None specified',
+    phase_depends_on: phase.dependsOn.length > 0 ? phase.dependsOn.join(', ') : 'None',
+    context_decisions: contextSection,
+    research_summary: researchSection,
+    output_dir: outputDir,
+    phase_number_padded: padded,
+    phase_slug: slug
+  });
+
+  return { prompt, output_dir: outputDir };
+}
+
+/**
+ * Generate a plan-checker prompt for validating an existing plan.
+ *
+ * @param {string} planContent - Content of the PLAN.md file
+ * @param {string} phaseRequirements - Phase requirements string
+ * @param {string} contextDecisions - Context decisions content
+ * @param {string} phaseGoal - Phase goal description
+ * @returns {string} Interpolated checker prompt
+ */
+function generateCheckerPrompt(planContent, phaseRequirements, contextDecisions, phaseGoal) {
+  const template = loadTemplate('plan-checker');
+  return interpolate(template, {
+    plan_content: planContent,
+    phase_requirements: phaseRequirements,
+    context_decisions: contextDecisions,
+    phase_goal: phaseGoal
+  });
+}
+
+/**
+ * Run the plan command.
+ *
+ * Default: Generate planner instructions for current phase.
+ * --phase N: Target specific phase.
+ * --all: Plan all unplanned phases sequentially.
+ * --check: Generate plan-checker instructions for existing plans.
+ *
+ * @param {string[]} args - CLI arguments
+ * @param {object} [opts] - Options (brainDir for testing)
+ * @returns {object} Structured result
+ */
+async function run(args = [], opts = {}) {
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const state = readState(brainDir);
+
+  if (!state) {
+    error("No brain state found. Run 'brain-dev init' first.");
+    return { error: 'no-state' };
+  }
+
+  const isAll = args.includes('--all');
+  const isCheck = args.includes('--check');
+  const isAdvocate = args.includes('--advocate');
+
+  if (isAll) {
+    return handleAll(brainDir, state);
+  }
+
+  if (isCheck) {
+    return handleCheck(args, brainDir, state);
+  }
+
+  if (isAdvocate) {
+    return handleAdvocate(args, brainDir, state);
+  }
+
+  return handleSingle(args, brainDir, state);
+}
+
+/**
+ * Handle single-phase planning.
+ */
+function handleSingle(args, brainDir, state) {
+  const phaseIdx = args.indexOf('--phase');
+  const phaseNumber = phaseIdx >= 0 ? parseInt(args[phaseIdx + 1], 10) : state.phase.current;
+
+  const roadmap = parseRoadmap(brainDir);
+  const phase = roadmap.phases.find(p => p.number === phaseNumber);
+
+  if (!phase) {
+    error(`Phase ${phaseNumber} not found in roadmap.`);
+    return { error: 'phase-not-found' };
+  }
+
+  const { prompt, output_dir } = generatePlannerPrompt(phase, brainDir);
+
+  // Get planner agent metadata and resolve model
+  const plannerAgent = getAgent('planner');
+  const model = resolveModel('planner', state);
+
+  // Log spawn event
+  logEvent(brainDir, phaseNumber, {
+    type: 'spawn',
+    agent: 'planner',
+    plan: 'all'
+  });
+
+  // Append checker loop instruction
+  const checkerInstruction = '\n\n> After plans are generated, plan-checker will validate. Be prepared for revision requests. Max 5 checker iterations before deadlock analysis.';
+  const fullPrompt = prompt + checkerInstruction;
+
+  // Update state: phase status = "planning"
+  state.phase.status = 'planning';
+  writeState(brainDir, state);
+
+  const result = {
+    action: 'spawn-planner',
+    phase: phaseNumber,
+    prompt: fullPrompt,
+    output_dir,
+    model,
+    checker_enabled: true,
+    max_checker_iterations: 5,
+    nextAction: '/brain:execute'
+  };
+
+  if (state.workflow && state.workflow.advocate !== false && !args.includes('--no-advocate')) {
+    result.advocate_enabled = true;
+    result.advocate_instruction = 'After plan-checker passes, run Devil\'s Advocate: brain-dev plan --advocate --phase ' + phaseNumber;
+  }
+
+  const humanLines = [
+    `[brain] Planner instructions generated for Phase ${phaseNumber}: ${phase.name}`,
+    `[brain] Output directory: ${output_dir}`,
+    `[brain] Model: ${model}`,
+    `[brain] Checker enabled: true`,
+    result.advocate_enabled ? `[brain] Advocate enabled: true` : '',
+    '',
+    fullPrompt
+  ].filter(Boolean);
+  output(result, humanLines.join('\n'));
+
+  return result;
+}
+
+/**
+ * Handle --check flag: generate plan-checker instructions for existing plans.
+ */
+function handleCheck(args, brainDir, state) {
+  const phaseIdx = args.indexOf('--phase');
+  const phaseNumber = phaseIdx >= 0 ? parseInt(args[phaseIdx + 1], 10) : state.phase.current;
+
+  const roadmap = parseRoadmap(brainDir);
+  const phase = roadmap.phases.find(p => p.number === phaseNumber);
+
+  if (!phase) {
+    error(`Phase ${phaseNumber} not found in roadmap.`);
+    return { error: 'phase-not-found' };
+  }
+
+  const phaseDir = findPhaseDir(brainDir, phaseNumber);
+  if (!phaseDir) {
+    error(`Phase ${phaseNumber} directory not found.`);
+    return { error: 'phase-dir-not-found' };
+  }
+
+  // Read existing plans
+  const files = fs.readdirSync(phaseDir);
+  const planFiles = files.filter(f => /^PLAN-\d+\.md$/.test(f)).sort();
+
+  if (planFiles.length === 0) {
+    error(`No plans found for phase ${phaseNumber}. Run '/brain:plan' first.`);
+    return { error: 'no-plans' };
+  }
+
+  // Read context for checker
+  const contextContent = readContext(brainDir, phaseNumber) || '_No context decisions._';
+  const phaseRequirements = phase.requirements.join(', ') || 'None specified';
+  const phaseGoal = phase.goal || 'No goal specified';
+
+  // Generate checker prompt for each plan
+  const planPrompts = planFiles.map(planFile => {
+    const planContent = fs.readFileSync(path.join(phaseDir, planFile), 'utf8');
+    const prompt = generateCheckerPrompt(planContent, phaseRequirements, contextContent, phaseGoal);
+    return { path: path.join(phaseDir, planFile), prompt };
+  });
+
+  // Get checker agent metadata
+  const checkerAgent = getAgent('plan-checker');
+  const model = resolveModel('plan-checker', state);
+
+  // Log event
+  logEvent(brainDir, phaseNumber, {
+    type: 'spawn',
+    agent: 'plan-checker',
+    plans: planFiles.length
+  });
+
+  const safetyValve = 'After 5 revision iterations, output deadlock analysis with both planner and checker perspectives for user to break tie.';
+
+  const result = {
+    action: 'spawn-checker',
+    plans: planPrompts,
+    max_iterations: 5,
+    model,
+    safety_valve: safetyValve
+  };
+
+  const humanLines = [
+    `[brain] Plan-checker instructions generated for Phase ${phaseNumber}`,
+    `[brain] Plans to check: ${planFiles.length}`,
+    `[brain] Model: ${model}`,
+    `[brain] Max iterations: 5`,
+    '',
+    safetyValve
+  ];
+  output(result, humanLines.join('\n'));
+
+  return result;
+}
+
+/**
+ * Infer phase type from phase name keywords.
+ * @param {string} phaseName
+ * @returns {string} 'scaffolding' | 'production' | 'standard'
+ */
+function inferPhaseType(phaseName) {
+  const lower = (phaseName || '').toLowerCase();
+  if (lower.includes('foundation') || lower.includes('scaffold')) return 'scaffolding';
+  if (lower.includes('production') || lower.includes('deploy') || lower.includes('verification')) return 'production';
+  return 'standard';
+}
+
+/**
+ * Handle --advocate flag: generate Devil's Advocate stress-test instructions.
+ */
+function handleAdvocate(args, brainDir, state) {
+  const phaseIdx = args.indexOf('--phase');
+  const phaseNumber = phaseIdx >= 0 ? parseInt(args[phaseIdx + 1], 10) : state.phase.current;
+
+  const roadmap = parseRoadmap(brainDir);
+  const phase = roadmap.phases.find(p => p.number === phaseNumber);
+
+  if (!phase) {
+    error(`Phase ${phaseNumber} not found in roadmap.`);
+    return { error: 'phase-not-found' };
+  }
+
+  const phaseDir = findPhaseDir(brainDir, phaseNumber);
+  if (!phaseDir) {
+    error(`Phase ${phaseNumber} directory not found.`);
+    return { error: 'phase-dir-not-found' };
+  }
+
+  // Read existing plans
+  const files = fs.readdirSync(phaseDir);
+  const planFiles = files.filter(f => /^PLAN-\d+\.md$/.test(f)).sort();
+
+  if (planFiles.length === 0) {
+    error(`No plans found for phase ${phaseNumber}. Run '/brain:plan' first.`);
+    return { error: 'no-plans' };
+  }
+
+  const phaseGoal = phase.goal || 'No goal specified';
+  const phaseType = inferPhaseType(phase.name);
+  const budget = (state.complexity && state.complexity.phase_overrides && state.complexity.phase_overrides[phaseNumber])
+    || getDefaultBudget(phaseType);
+
+  const advocateTemplate = loadTemplate('advocate');
+
+  const planPrompts = planFiles.map(planFile => {
+    const planContent = fs.readFileSync(path.join(phaseDir, planFile), 'utf8');
+    const { score } = estimateFromPlan(planContent);
+    const prompt = interpolate(advocateTemplate, {
+      plan_content: planContent,
+      phase_goal: phaseGoal,
+      complexity_score: String(score),
+      complexity_budget: String(budget)
+    });
+    return { path: path.join(phaseDir, planFile), prompt };
+  });
+
+  // Get plan-checker agent metadata (advocate is a mode, not a separate agent)
+  const checkerAgent = getAgent('plan-checker');
+  const model = resolveModel('plan-checker', state);
+  const maxIterations = checkerAgent.modes.advocate.max_iterations;
+
+  const padded = String(phaseNumber).padStart(2, '0');
+  const reportPath = path.join(phaseDir, `${padded}-ADVOCATE.md`);
+
+  // Log spawn event
+  logEvent(brainDir, phaseNumber, {
+    type: 'spawn',
+    agent: 'plan-checker',
+    mode: 'advocate',
+    plans: planFiles.length
+  });
+
+  const result = {
+    action: 'spawn-advocate',
+    plans: planPrompts,
+    max_iterations: maxIterations,
+    model,
+    report_path: reportPath
+  };
+
+  const humanLines = [
+    `[brain] Devil's Advocate instructions generated for Phase ${phaseNumber}`,
+    `[brain] Plans to stress-test: ${planFiles.length}`,
+    `[brain] Model: ${model}`,
+    `[brain] Max iterations: ${maxIterations}`,
+    `[brain] Report path: ${reportPath}`,
+    '',
+    'Run advocate on each plan. HIGH severity findings require plan revision before execution.'
+  ];
+  output(result, humanLines.join('\n'));
+
+  return result;
+}
+
+/**
+ * Handle --all flag: plan all unplanned phases.
+ */
+function handleAll(brainDir, state) {
+  const roadmap = parseRoadmap(brainDir);
+
+  // Find phases that are not complete and don't have existing PLAN.md files
+  const unplannedPhases = roadmap.phases.filter(p => {
+    if (p.status === 'Complete' || p.status === 'complete') return false;
+
+    // Check if phase directory has any PLAN-*.md files
+    const phaseDir = findPhaseDir(brainDir, p.number);
+    if (phaseDir) {
+      const files = fs.readdirSync(phaseDir);
+      const hasPlans = files.some(f => /^PLAN-\d+\.md$/.test(f));
+      if (hasPlans) return false;
+    }
+    return true;
+  });
+
+  const phaseInstructions = unplannedPhases.map(phase => {
+    const { prompt, output_dir } = generatePlannerPrompt(phase, brainDir);
+    return {
+      phase: phase.number,
+      name: phase.name,
+      prompt,
+      output_dir
+    };
+  });
+
+  // Update status to planning
+  state.phase.status = 'planning';
+  writeState(brainDir, state);
+
+  const result = {
+    action: 'spawn-planner-all',
+    phases: phaseInstructions,
+    instruction: 'Plan each phase sequentially (not in parallel). Complete one phase before starting the next.',
+    nextAction: '/brain:execute'
+  };
+
+  const humanLines = [
+    `[brain] Planning ${phaseInstructions.length} unplanned phase(s) sequentially:`,
+    ...phaseInstructions.map(p => `  - Phase ${p.phase}: ${p.name}`),
+    '',
+    'Execute each planner sequentially. Do not parallelize.'
+  ];
+  output(result, humanLines.join('\n'));
+
+  return result;
+}
+
+module.exports = { run, generateCheckerPrompt };

package/bin/lib/commands/progress.cjs

@@ -0,0 +1,167 @@
+'use strict';
+
+const path = require('node:path');
+const { readState } = require('../state.cjs');
+const { output, prefix, error } = require('../core.cjs');
+
+/**
+ * Determine the next action based on project and phase state.
+ * @param {object} state - brain.json state object
+ * @returns {string} Next action command
+ */
+function nextAction(state) {
+  // No project name -> need to create one
+  if (!state.project || !state.project.name) {
+    return '/brain:new-project';
+  }
+
+  const phase = state.phase || {};
+
+  // Check if all phases are done
+  const totalPhases = phase.total || (Array.isArray(phase.phases) ? phase.phases.length : 0);
+  if (phase.status === 'complete' || (totalPhases > 0 && phase.current > totalPhases)) {
+    return '/brain:complete';
+  }
+
+  // Route based on current phase status
+  switch (phase.status) {
+    case 'initialized':
+      return '/brain:new-project';
+    case 'pending':
+      return '/brain:discuss';
+    case 'discussing':
+    case 'discussed':
+      return '/brain:plan';
+    case 'planning':
+      return '/brain:execute';
+    case 'executing':
+      return '/brain:execute';
+    case 'executed':
+      return '/brain:verify';
+    case 'verifying':
+      return '/brain:verify';
+    case 'verified':
+      return '/brain:complete';
+    case 'verification-failed':
+      return '/brain:execute';
+    case 'complete':
+      return '/brain:complete';
+    default:
+      return '/brain:progress';
+  }
+}
+
+/**
+ * Run the progress command.
+ * @param {string[]} args - CLI arguments
+ * @param {object} [opts] - Options (brainDir for testing)
+ * @returns {object} Structured result for piping/testing
+ */
+async function run(args = [], opts = {}) {
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const state = readState(brainDir);
+
+  if (!state) {
+    error("No brain state found. Run 'brain-dev init' first.");
+    return { error: 'no-state' };
+  }
+
+  const verbose = args.includes('--verbose');
+  const phase = state.phase || {};
+  const phases = phase.phases || [];
+  const session = state.session || {};
+  const action = nextAction(state);
+
+  // Context warning heuristic
+  const estimatedUsage = session.estimatedUsage || 0;
+  const contextWarning = !session.contextWarningShown && estimatedUsage > 0.3;
+
+  if (verbose) {
+    // Full dashboard with all phases
+    const phaseDetails = phases.map((p, i) => {
+      // Handle both string ("Phase 1: Name") and object ({number, name, status}) formats
+      if (typeof p === 'string') {
+        const match = p.match(/Phase (\d+): (.+)/);
+        return {
+          number: match ? parseInt(match[1], 10) : i + 1,
+          name: match ? match[2] : p,
+          status: 'Pending',
+          plansTotal: 0,
+          plansDone: 0,
+          completion: 0
+        };
+      }
+      return {
+        number: p.number || i + 1,
+        name: p.name || 'Unknown',
+        status: p.status || 'Pending',
+        plansTotal: p.plans ? p.plans.total : 0,
+        plansDone: p.plans ? p.plans.done : 0,
+        completion: p.plans && p.plans.total > 0
+          ? Math.round((p.plans.done / p.plans.total) * 100)
+          : 0
+      };
+    });
+
+    // Human-readable table
+    const lines = [
+      prefix(`Project: ${state.project?.name || 'unnamed'}`),
+      prefix(`Phase ${phase.current} of ${phases.length}: ${phase.status}`),
+      prefix(`Next: ${action}`),
+      '',
+      '  #  Name            Status      Plans     Done',
+      '  -  ----            ------      -----     ----'
+    ];
+
+    for (const p of phaseDetails) {
+      const num = String(p.number || '?').padEnd(2);
+      const name = String(p.name || '').padEnd(15);
+      const status = String(p.status || 'Pending').padEnd(11);
+      const plans = String(p.plansTotal || 0).padEnd(9);
+      const pct = `${p.completion || 0}%`;
+      lines.push(`  ${num} ${name} ${status} ${plans} ${pct}`);
+    }
+
+    if (contextWarning) {
+      lines.push('');
+      lines.push(prefix('Warning: Context window usage is above 30%. Consider pausing with /brain:pause.'));
+    }
+
+    const result = {
+      verbose: true,
+      phase: { current: phase.current, total: phases.length, status: phase.status },
+      phases: phaseDetails,
+      nextAction: action,
+      contextWarning
+    };
+
+    output(result, lines.join('\n'));
+    return result;
+  }
+
+  // Short mode (default)
+  const totalPhases = phases.length || '?';
+  const currentPlan = phase.currentPlan || '?';
+  const totalPlans = phase.totalPlans || '?';
+
+  const lines = [
+    prefix(`Phase ${phase.current} of ${totalPhases}: ${phase.status} (Plan ${currentPlan} of ${totalPlans})`),
+    prefix(`Next: ${action}`)
+  ];
+
+  if (contextWarning) {
+    lines.push(prefix('Warning: Context window usage is above 30%. Consider pausing with /brain:pause.'));
+  }
+
+  const result = {
+    phase: { current: phase.current, total: totalPhases, status: phase.status },
+    status: phase.status,
+    nextAction: action,
+    contextWarning
+  };
+
+  output(result, lines.join('\n'));
+  return result;
+}
+
+module.exports = { run, nextAction };