brain-dev 0.2.0 → 1.0.0

package/bin/lib/commands/new-task.cjs

@@ -0,0 +1,522 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseArgs } = require('node:util');
+const { readState, writeState } = require('../state.cjs');
+const { logEvent } = require('../logger.cjs');
+const { output, error, prefix } = require('../core.cjs');
+const { recordInvocation, estimateTokens } = require('../cost.cjs');
+
+async function run(args = [], opts = {}) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      research: { type: 'boolean', default: false },
+      light: { type: 'boolean', default: false },
+      continue: { type: 'boolean', default: false },
+      list: { type: 'boolean', default: false },
+      promote: { type: 'string' },
+      json: { type: 'boolean', default: false }
+    },
+    strict: false,
+    allowPositionals: true
+  });
+
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const state = readState(brainDir);
+
+  if (!state || !state.project?.initialized) {
+    error("Project not initialized. Run '/brain:new-project' first.");
+    return { error: 'not-initialized' };
+  }
+
+  // Handle --list
+  if (values.list) return handleList(brainDir, state);
+
+  // Handle --promote N
+  if (values.promote) {
+    const taskNum = parseInt(values.promote, 10);
+    if (isNaN(taskNum) || taskNum < 1) {
+      error("--promote requires a valid task number. Usage: brain-dev new-task --promote <N>");
+      return { error: 'invalid-task-number' };
+    }
+    return handlePromote(brainDir, state, taskNum);
+  }
+
+  // Handle --continue (resume current task)
+  if (values.continue) return handleContinue(brainDir, state);
+
+  // New task creation
+  const description = positionals.join(' ').trim();
+  if (!description) {
+    error("Usage: brain-dev new-task \"description\" [--research] [--light]");
+    return { error: 'no-description' };
+  }
+
+  return handleNewTask(brainDir, state, description, values);
+}
+
+function handleNewTask(brainDir, state, description, options) {
+  // Create task directory and metadata
+  const taskNum = (state.tasks?.count || 0) + 1;
+  const slug = description
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40) || 'task';
+
+  const taskDir = path.join(brainDir, 'tasks', `${String(taskNum).padStart(2, '0')}-${slug}`);
+  fs.mkdirSync(taskDir, { recursive: true });
+
+  const mode = options.light ? 'light' : 'standard';
+  const taskMeta = {
+    num: taskNum,
+    slug,
+    description,
+    created: new Date().toISOString(),
+    status: 'initialized',
+    mode,
+    research: options.research || false,
+    parent_phase: state.phase?.current || null,
+    promoted_to_phase: null,
+    completed: null
+  };
+
+  fs.writeFileSync(path.join(taskDir, 'task.json'), JSON.stringify(taskMeta, null, 2));
+
+  // Update state
+  state.tasks = state.tasks || { current: null, count: 0, active: [], history: [] };
+  state.tasks.current = taskNum;
+  state.tasks.count = taskNum;
+  state.tasks.active.push({ num: taskNum, slug, status: 'initialized', description });
+  writeState(brainDir, state);
+
+  logEvent(brainDir, 0, { type: 'task-init', task: taskNum, slug, description, mode });
+
+  // Determine first step
+  const firstStep = mode === 'light' ? 'plan' : 'discuss';
+
+  // Build step instructions
+  const steps = buildStepInstructions(taskNum, slug, taskDir, brainDir, mode, options.research, description);
+
+  const humanLines = [
+    prefix(`Task #${taskNum} created: ${description}`),
+    prefix(`Mode: ${mode}${options.research ? ' + research' : ''}`),
+    prefix(`Directory: .brain/tasks/${String(taskNum).padStart(2, '0')}-${slug}/`),
+    '',
+    prefix(`Pipeline: ${mode === 'light' ? 'plan -> execute -> commit' : 'discuss -> plan -> execute -> verify -> complete'}`),
+    '',
+    prefix(`Next step: ${firstStep}`),
+    '',
+    steps[firstStep]
+  ].join('\n');
+
+  const result = {
+    action: 'task-created',
+    task: taskMeta,
+    nextStep: firstStep,
+    taskDir,
+    steps,
+    instructions: steps[firstStep]
+  };
+
+  output(result, humanLines);
+  return result;
+}
+
+function buildStepInstructions(taskNum, slug, taskDir, brainDir, mode, research, description) {
+  const padded = String(taskNum).padStart(2, '0');
+  const steps = {};
+
+  // DISCUSS step
+  steps.discuss = [
+    `## Step 1: Discuss — Task #${taskNum}`,
+    '',
+    `Discuss the architectural approach for: "${description}"`,
+    '',
+    'Questions to explore:',
+    '1. What is the best approach for this task?',
+    '2. Are there existing patterns in the codebase to follow?',
+    '3. What are the risks or edge cases?',
+    '4. What dependencies does this have?',
+    '',
+    'After discussion, save decisions to:',
+    `\`${taskDir}/CONTEXT.md\``,
+    '',
+    'Then run: `npx brain-dev new-task --continue`'
+  ].join('\n');
+
+  // RESEARCH step (optional)
+  if (research) {
+    steps.research = [
+      `## Step 1.5: Research — Task #${taskNum}`,
+      '',
+      `Research the approach for: "${description}"`,
+      '',
+      'Focus on:',
+      '1. How does the existing codebase handle similar features?',
+      '2. What are the best practices for this type of change?',
+      '',
+      'Save findings to:',
+      `\`${taskDir}/RESEARCH.md\``,
+      '',
+      'Then run: `npx brain-dev new-task --continue`'
+    ].join('\n');
+  }
+
+  // PLAN step
+  steps.plan = [
+    `## Step 2: Plan — Task #${taskNum}`,
+    '',
+    `Create an execution plan for: "${description}"`,
+    '',
+    'Constraints:',
+    '- Max 3-4 tasks (this is a focused task, not a full phase)',
+    '- Target ~50% context budget',
+    '- Each task should be atomic and testable',
+    '- Include must_haves for verification',
+    '',
+    `Read context: \`${taskDir}/CONTEXT.md\` (if exists)`,
+    research ? `Read research: \`${taskDir}/RESEARCH.md\` (if exists)` : '',
+    '',
+    `Write plan to: \`${taskDir}/PLAN-1.md\``,
+    'Use standard Brain plan format with YAML frontmatter.',
+    '',
+    'Then run: `npx brain-dev new-task --continue`'
+  ].filter(Boolean).join('\n');
+
+  // EXECUTE step
+  steps.execute = [
+    `## Step 3: Execute — Task #${taskNum}`,
+    '',
+    `Execute the plan at: \`${taskDir}/PLAN-1.md\``,
+    '',
+    'Instructions:',
+    '- Follow the plan tasks sequentially',
+    '- Make atomic commits per task',
+    '- If a task fails, retry once then escalate',
+    '',
+    `Write summary to: \`${taskDir}/SUMMARY-1.md\``,
+    'Include: key files modified, decisions made, Self-Check status.',
+    '',
+    'Then run: `npx brain-dev new-task --continue`'
+  ].join('\n');
+
+  // VERIFY step
+  if (mode !== 'light') {
+    steps.verify = [
+      `## Step 4: Verify — Task #${taskNum}`,
+      '',
+      `Verify the execution results against must_haves in: \`${taskDir}/PLAN-1.md\``,
+      '',
+      'Verification levels:',
+      '1. EXISTS: Files exist and are non-empty',
+      '2. SUBSTANTIVE: Contains real implementation (no stubs)',
+      '3. WIRED: Properly imported and consumed',
+      '',
+      `Write results to: \`${taskDir}/VERIFICATION.md\``,
+      '',
+      'Then run: `npx brain-dev new-task --continue`'
+    ].join('\n');
+  }
+
+  // COMPLETE step
+  steps.complete = [
+    `## Step 5: Complete — Task #${taskNum}`,
+    '',
+    'Task completion options:',
+    '',
+    '**Option A: Keep as standalone task**',
+    '`npx brain-dev new-task --continue` (will auto-complete)',
+    '',
+    '**Option B: Promote to roadmap phase**',
+    `\`npx brain-dev new-task --promote ${taskNum}\``,
+    'This adds the task as a new phase in ROADMAP.md.',
+    '',
+    'Commit suggestion:',
+    `\`git add -A && git commit -m "feat(task-${padded}): ${slug}"\``
+  ].join('\n');
+
+  return steps;
+}
+
+function handleContinue(brainDir, state) {
+  const taskNum = state.tasks?.current;
+  if (!taskNum) {
+    error("No active task. Start one with: brain-dev new-task \"description\"");
+    return { error: 'no-active-task' };
+  }
+
+  // Find task directory
+  const tasksDir = path.join(brainDir, 'tasks');
+  if (!fs.existsSync(tasksDir)) {
+    error("No tasks directory found.");
+    return { error: 'no-tasks-dir' };
+  }
+
+  const padded = String(taskNum).padStart(2, '0');
+  const dirs = fs.readdirSync(tasksDir).filter(d => d.startsWith(padded + '-'));
+  if (dirs.length === 0) {
+    error(`Task #${taskNum} directory not found.`);
+    return { error: 'task-not-found' };
+  }
+
+  const taskDir = path.join(tasksDir, dirs[0]);
+  const taskMeta = JSON.parse(fs.readFileSync(path.join(taskDir, 'task.json'), 'utf8'));
+
+  // Determine current step based on what files exist
+  const hasContext = fs.existsSync(path.join(taskDir, 'CONTEXT.md'));
+  const hasResearch = fs.existsSync(path.join(taskDir, 'RESEARCH.md'));
+  const hasPlan = fs.existsSync(path.join(taskDir, 'PLAN-1.md'));
+  const hasSummary = fs.existsSync(path.join(taskDir, 'SUMMARY-1.md'));
+  const hasVerification = fs.existsSync(path.join(taskDir, 'VERIFICATION.md'));
+
+  const isLight = taskMeta.mode === 'light';
+  let nextStep;
+  let newStatus;
+
+  if (!hasContext && !isLight) {
+    nextStep = 'discuss';
+    newStatus = 'discussing';
+  } else if (taskMeta.research && !hasResearch) {
+    nextStep = 'research';
+    newStatus = 'researching';
+  } else if (!hasPlan) {
+    nextStep = 'plan';
+    newStatus = 'planning';
+  } else if (!hasSummary) {
+    nextStep = 'execute';
+    newStatus = 'executing';
+  } else if (!hasVerification && !isLight) {
+    nextStep = 'verify';
+    newStatus = 'verifying';
+  } else {
+    // All steps done — complete the task
+    return handleTaskComplete(brainDir, state, taskNum, taskDir, taskMeta);
+  }
+
+  // Update status
+  taskMeta.status = newStatus;
+  fs.writeFileSync(path.join(taskDir, 'task.json'), JSON.stringify(taskMeta, null, 2));
+
+  // Update state
+  state.tasks.active = state.tasks.active || [];
+  const activeIdx = state.tasks.active.findIndex(t => t.num === taskNum);
+  if (activeIdx >= 0) state.tasks.active[activeIdx].status = newStatus;
+  writeState(brainDir, state);
+
+  // Build step instructions
+  const steps = buildStepInstructions(
+    taskNum, taskMeta.slug, taskDir, brainDir,
+    taskMeta.mode, taskMeta.research, taskMeta.description
+  );
+
+  logEvent(brainDir, 0, { type: 'task-continue', task: taskNum, step: nextStep });
+
+  // Record cost for execute step
+  if (nextStep === 'execute' && hasPlan) {
+    try {
+      const planContent = fs.readFileSync(path.join(taskDir, 'PLAN-1.md'), 'utf8');
+      const inputTokens = estimateTokens(planContent);
+      recordInvocation(brainDir, {
+        agent: 'executor', phase: 0, plan: '01',
+        model: 'inherit', input_tokens: inputTokens, output_tokens: 0
+      });
+    } catch { /* non-fatal */ }
+  }
+
+  const humanLines = [
+    prefix(`Task #${taskNum}: ${taskMeta.description}`),
+    prefix(`Status: ${newStatus}`),
+    prefix(`Next step: ${nextStep}`),
+    '',
+    steps[nextStep]
+  ].join('\n');
+
+  output({
+    action: 'task-continue',
+    task: taskMeta,
+    nextStep,
+    instructions: steps[nextStep]
+  }, humanLines);
+
+  return { action: 'task-continue', task: taskMeta, nextStep };
+}
+
+function handleTaskComplete(brainDir, state, taskNum, taskDir, taskMeta) {
+  taskMeta.status = 'complete';
+  taskMeta.completed = new Date().toISOString();
+  fs.writeFileSync(path.join(taskDir, 'task.json'), JSON.stringify(taskMeta, null, 2));
+
+  // Move from active to history
+  state.tasks.active = state.tasks.active.filter(t => t.num !== taskNum);
+  state.tasks.history.push({
+    num: taskNum,
+    slug: taskMeta.slug,
+    description: taskMeta.description,
+    mode: taskMeta.mode,
+    completed: taskMeta.completed,
+    promoted_to_phase: null
+  });
+  state.tasks.current = null;
+  writeState(brainDir, state);
+
+  logEvent(brainDir, 0, { type: 'task-complete', task: taskNum, slug: taskMeta.slug });
+
+  const padded = String(taskNum).padStart(2, '0');
+  const humanLines = [
+    prefix(`Task #${taskNum} complete: ${taskMeta.description}`),
+    '',
+    prefix('Options:'),
+    prefix('  1. Keep as standalone task (done!)'),
+    prefix(`  2. Promote to roadmap phase: brain-dev new-task --promote ${taskNum}`),
+    '',
+    prefix(`Suggested commit: git add -A && git commit -m "feat(task-${padded}): ${taskMeta.slug}"`)
+  ].join('\n');
+
+  output({
+    action: 'task-complete',
+    task: taskMeta,
+    promote_command: `brain-dev new-task --promote ${taskNum}`
+  }, humanLines);
+
+  return { action: 'task-complete', task: taskMeta };
+}
+
+function handlePromote(brainDir, state, taskNum) {
+  // Guard: phases must exist for promotion
+  if (!state.phase || !Array.isArray(state.phase.phases)) {
+    error("Project phases not initialized. Run '/brain:new-project' first.");
+    return { error: 'no-phases' };
+  }
+
+  // Find the task
+  const tasksDir = path.join(brainDir, 'tasks');
+  if (!fs.existsSync(tasksDir)) {
+    error(`No tasks directory found. Create a task first: brain-dev new-task "description"`);
+    return { error: 'no-tasks-dir' };
+  }
+  const padded = String(taskNum).padStart(2, '0');
+  const dirs = fs.readdirSync(tasksDir).filter(d => d.startsWith(padded + '-'));
+
+  if (dirs.length === 0) {
+    error(`Task #${taskNum} not found.`);
+    return { error: 'task-not-found' };
+  }
+
+  const taskDir = path.join(tasksDir, dirs[0]);
+  const taskMeta = JSON.parse(fs.readFileSync(path.join(taskDir, 'task.json'), 'utf8'));
+
+  // Insert as a new phase after current phase
+  try {
+    const { parseRoadmap, insertPhase, writeRoadmap } = require('../roadmap.cjs');
+    const roadmapPath = path.join(brainDir, 'ROADMAP.md');
+
+    if (!fs.existsSync(roadmapPath)) {
+      error("No ROADMAP.md found. Cannot promote without a roadmap.");
+      return { error: 'no-roadmap' };
+    }
+
+    const roadmapData = parseRoadmap(brainDir);
+    const afterPhase = state.phase?.current || roadmapData.phases.length;
+
+    const updatedRoadmap = insertPhase(roadmapData, afterPhase, {
+      name: taskMeta.description,
+      goal: `Implement: ${taskMeta.description} (promoted from task #${taskNum})`,
+      requirements: taskMeta.requirements || [],
+      status: taskMeta.status === 'complete' ? 'Complete' : 'In Progress'
+    });
+
+    writeRoadmap(brainDir, updatedRoadmap);
+
+    // Find the newly inserted phase (it was not in the original roadmapData)
+    const newPhase = updatedRoadmap.phases.find(
+      p => !roadmapData.phases.some(op => op.number === p.number)
+    );
+
+    // Update task metadata
+    taskMeta.promoted_to_phase = newPhase ? newPhase.number : afterPhase;
+    fs.writeFileSync(path.join(taskDir, 'task.json'), JSON.stringify(taskMeta, null, 2));
+
+    // Update state
+    state.phase.total = updatedRoadmap.phases.length;
+    state.phase.phases.push({
+      number: taskMeta.promoted_to_phase,
+      name: taskMeta.description,
+      status: taskMeta.status === 'complete' ? 'complete' : 'pending',
+      goal: newPhase ? newPhase.goal : taskMeta.description
+    });
+
+    // Update history
+    const historyEntry = state.tasks.history.find(t => t.num === taskNum);
+    if (historyEntry) historyEntry.promoted_to_phase = taskMeta.promoted_to_phase;
+
+    writeState(brainDir, state);
+
+    logEvent(brainDir, 0, { type: 'task-promote', task: taskNum, phase: taskMeta.promoted_to_phase });
+
+    // Copy artifacts to phase directory
+    const phaseSlug = taskMeta.slug;
+    const phasePadded = Number.isInteger(taskMeta.promoted_to_phase)
+      ? String(taskMeta.promoted_to_phase).padStart(2, '0')
+      : String(taskMeta.promoted_to_phase).replace('.', '_');
+    const phaseDir = path.join(brainDir, 'phases', `${phasePadded}-${phaseSlug}`);
+    fs.mkdirSync(phaseDir, { recursive: true });
+
+    // Copy plan, summary, verification if they exist
+    for (const file of ['PLAN-1.md', 'SUMMARY-1.md', 'VERIFICATION.md', 'CONTEXT.md']) {
+      const src = path.join(taskDir, file);
+      if (fs.existsSync(src)) {
+        fs.copyFileSync(src, path.join(phaseDir, file));
+      }
+    }
+
+    const humanLines = [
+      prefix(`Task #${taskNum} promoted to Phase ${taskMeta.promoted_to_phase}`),
+      prefix(`Phase: ${taskMeta.description}`),
+      prefix(`Artifacts copied to: .brain/phases/${phasePadded}-${phaseSlug}/`),
+      prefix('ROADMAP.md updated')
+    ].join('\n');
+
+    output({ action: 'task-promoted', task: taskMeta, phase: newPhase }, humanLines);
+    return { action: 'task-promoted', task: taskMeta, phase: newPhase };
+
+  } catch (e) {
+    error(`Promotion failed: ${e.message}`);
+    return { error: 'promotion-failed', message: e.message };
+  }
+}
+
+function handleList(brainDir, state) {
+  const tasks = state.tasks || { active: [], history: [], count: 0 };
+
+  const lines = [prefix(`Tasks (${tasks.count} total)`)];
+
+  if (tasks.active.length > 0) {
+    lines.push('');
+    lines.push(prefix('Active:'));
+    for (const t of tasks.active) {
+      lines.push(prefix(`  #${t.num} ${t.slug} (${t.status})`));
+    }
+  }
+
+  if (tasks.history.length > 0) {
+    lines.push('');
+    lines.push(prefix('Completed:'));
+    for (const t of tasks.history.slice(-10)) {
+      const promoted = t.promoted_to_phase ? ` -> Phase ${t.promoted_to_phase}` : '';
+      lines.push(prefix(`  #${t.num} ${t.slug}${promoted}`));
+    }
+  }
+
+  if (tasks.count === 0) {
+    lines.push(prefix('  No tasks yet. Create one: brain-dev new-task "description"'));
+  }
+
+  const result = { action: 'task-list', tasks };
+  output(result, lines.join('\n'));
+  return result;
+}
+
+module.exports = { run };

package/bin/lib/commands/progress.cjs

@@ -29,7 +29,7 @@ function nextAction(state) {
     case 'initialized':
       return '/brain:new-project';
     case 'pending':
-      return '/brain:discuss';
+      return '/brain:story';
     case 'discussing':
     case 'discussed':
       return '/brain:plan';