brain-dev 0.1.0 → 0.1.2

package/README.md

@@ -85,6 +85,27 @@ init → new-project → discuss → plan → execute → verify → complete
 - **`/brain:map`** generates deep codebase documentation
 - **`/brain:health`** self-diagnoses and auto-repairs
 
+## Quick Tasks
+
+Not everything needs a full phase. For small, focused work:
+
+```bash
+/brain:quick "fix the login redirect bug"
+```
+
+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.
+
 ## State Machine
 
 Brain tracks progress through a deterministic state machine:
@@ -124,6 +145,7 @@ No supply chain risk. No transitive vulnerabilities. No `node_modules` bloat.
 | `/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 |
 
 ### Session
 | Command | Description |

package/bin/brain-tools.cjs

@@ -162,6 +162,10 @@ async function main() {
       await require('./lib/commands/config.cjs').run(args.slice(1), path.join(process.cwd(), '.brain'));
       break;
 
+    case 'update':
+      await require('./lib/commands/update.cjs').run(args.slice(1));
+      break;
+
     case 'health':
       await require('./lib/commands/health.cjs').run(args.slice(1));
       break;

package/bin/lib/commands/discuss.cjs

@@ -125,7 +125,7 @@ function handleAnalyze(args, brainDir, state) {
     phase_number: phaseNumber,
     phase_name: phase.name,
     phase_goal: phase.goal,
-    phase_requirements: phase.requirements.join(', ') || 'None specified',
+    phase_requirements: (Array.isArray(phase.requirements) ? phase.requirements.join(', ') : '') || 'None specified',
     research_section: researchSection
   });
 

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

@@ -83,7 +83,7 @@ function buildBrownfieldQuestions(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.framework || s.stack.language})`).join(', ');
+    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?`;
   }
 
@@ -692,7 +692,7 @@ function buildCodebaseContext(detection) {
     lines.push('');
     lines.push('### Related Projects in Workspace');
     for (const sib of workspace.siblings) {
-      lines.push(`- **${sib.name}:** ${sib.stack.framework || sib.stack.language}`);
+      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.');

package/bin/lib/commands/plan.cjs

@@ -84,7 +84,7 @@ function generatePlannerPrompt(phase, brainDir) {
     phase_number: phase.number,
     phase_name: phase.name,
     phase_goal: phase.goal,
-    phase_requirements: phase.requirements.join(', ') || 'None specified',
+    phase_requirements: (Array.isArray(phase.requirements) ? phase.requirements.join(', ') : '') || 'None specified',
     phase_depends_on: phase.dependsOn.length > 0 ? phase.dependsOn.join(', ') : 'None',
     context_decisions: contextSection,
     research_summary: researchSection,
@@ -253,7 +253,7 @@ function handleCheck(args, brainDir, state) {
 
   // Read context for checker
   const contextContent = readContext(brainDir, phaseNumber) || '_No context decisions._';
-  const phaseRequirements = phase.requirements.join(', ') || 'None specified';
+  const phaseRequirements = (Array.isArray(phase.requirements) ? phase.requirements.join(', ') : '') || 'None specified';
   const phaseGoal = phase.goal || 'No goal specified';
 
   // Generate checker prompt for each plan

package/bin/lib/commands/update.cjs

@@ -0,0 +1,148 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState, writeState, migrateState } = require('../state.cjs');
+const { detectPlatform } = require('../platform.cjs');
+const { packagePath, registerClaudeHooks, registerAgents, registerCommands, cleanupLegacySkills } = require('../init.cjs');
+const { output, error, success, prefix } = require('../core.cjs');
+
+/**
+ * Copy hook scripts from package to .brain/hooks/.
+ * Preserves executable permissions.
+ * @param {string} brainDir
+ */
+function copyHooks(brainDir) {
+  const hooksDir = path.join(brainDir, 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+
+  const hookFiles = ['bootstrap.sh', 'statusline.sh', 'post-tool-use.sh'];
+  for (const file of hookFiles) {
+    const src = packagePath('hooks', file);
+    if (fs.existsSync(src)) {
+      const dest = path.join(hooksDir, file);
+      fs.copyFileSync(src, dest);
+      try { fs.chmodSync(dest, 0o755); } catch { /* skip on unsupported FS */ }
+    }
+  }
+}
+
+/**
+ * Update .brain/.gitignore with current patterns.
+ * @param {string} brainDir
+ */
+function updateGitignore(brainDir) {
+  const content = [
+    '*.tmp',
+    '*.lock',
+    'storm/fragments/',
+    'storm/events.jsonl',
+    ''
+  ].join('\n');
+  fs.writeFileSync(path.join(brainDir, '.gitignore'), content, 'utf8');
+}
+
+/**
+ * Run the update command.
+ * Updates tool files (hooks, agents, commands) while preserving project state.
+ *
+ * brain-dev update          → Update tool files + migrate state
+ * brain-dev update --check  → Only check version, don't update
+ *
+ * @param {string[]} args
+ * @param {object} [opts]
+ */
+async function run(args = [], opts = {}) {
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const cwd = opts.cwd || process.cwd();
+
+  // 1. Validate .brain/ exists
+  if (!fs.existsSync(brainDir)) {
+    error("No brain project found. Run 'npx brain-dev init' first.");
+    return { error: 'no-project' };
+  }
+
+  // 2. Read current state
+  const state = readState(brainDir);
+  if (!state) {
+    error("Corrupted brain.json. Run 'npx brain-dev init --force' to reset.");
+    return { error: 'corrupted-state' };
+  }
+
+  // 3. Get versions
+  const installedVersion = state.version || '0.0.0';
+  const packageVersion = require(path.join(__dirname, '..', '..', '..', 'package.json')).version;
+
+  // --check mode
+  if (args.includes('--check')) {
+    const upToDate = installedVersion === packageVersion;
+    const msg = upToDate
+      ? `brain-dev v${installedVersion} is up to date.`
+      : `Update available: v${installedVersion} → v${packageVersion}. Run: npx brain-dev update`;
+
+    output({
+      action: 'version-check',
+      installed: installedVersion,
+      package: packageVersion,
+      upToDate
+    }, prefix(msg));
+
+    return { action: 'version-check', installed: installedVersion, package: packageVersion, upToDate };
+  }
+
+  // 4. Backup state before update
+  const backupPath = path.join(brainDir, 'brain.json.pre-update');
+  try {
+    fs.copyFileSync(path.join(brainDir, 'brain.json'), backupPath);
+  } catch (e) {
+    error(`Could not backup brain.json: ${e.message}`);
+    return { error: 'backup-failed' };
+  }
+
+  // 5. Ensure required directories exist
+  const requiredDirs = ['hooks', 'debug', 'specs', 'codebase'];
+  for (const dir of requiredDirs) {
+    fs.mkdirSync(path.join(brainDir, dir), { recursive: true });
+  }
+
+  // 6. Update hook scripts
+  copyHooks(brainDir);
+
+  // 7. Platform-specific updates
+  const platform = detectPlatform({ cwd });
+  if (platform === 'claude-code') {
+    registerClaudeHooks(cwd);
+    cleanupLegacySkills(cwd);
+    registerCommands(cwd);
+    registerAgents(cwd);
+  }
+
+  // 8. Migrate state (adds new fields, preserves all existing data)
+  const migrated = migrateState(state);
+  writeState(brainDir, migrated);
+
+  // 9. Update .gitignore
+  updateGitignore(brainDir);
+
+  // 10. Report
+  const isUpgrade = installedVersion !== packageVersion;
+  const msg = isUpgrade
+    ? `Updated brain-dev v${installedVersion} → v${packageVersion}. State preserved. Backup: brain.json.pre-update`
+    : `brain-dev v${packageVersion} tool files refreshed. State preserved.`;
+
+  success(msg);
+
+  const result = {
+    action: 'updated',
+    from: installedVersion,
+    to: packageVersion,
+    backup: backupPath,
+    statePreserved: true,
+    nextAction: '/brain:progress'
+  };
+
+  output(result, '');
+  return result;
+}
+
+module.exports = { run };

package/bin/lib/commands.cjs

@@ -180,6 +180,15 @@ const COMMANDS = [
   },
 
   // Meta
+  {
+    name: 'update',
+    description: 'Update tool files while preserving project state',
+    usage: 'brain-dev update [--check]',
+    group: 'Meta',
+    implemented: true,
+    needsState: false,
+    args: '  --check  Only check for new version, don\'t update'
+  },
   {
     name: 'health',
     description: 'Run health diagnostics and auto-repair safe issues',

package/bin/lib/init.cjs

@@ -307,4 +307,4 @@ async function run(args = []) {
   console.log(prefix('Next: /brain:new-project to start planning'));
 }
 
-module.exports = { run };
+module.exports = { run, packagePath, registerClaudeHooks, registerAgents, registerCommands, cleanupLegacySkills };

package/commands/brain/update.md

@@ -0,0 +1,22 @@
+---
+name: brain:update
+description: Update brain tool files while preserving project state
+allowed-tools:
+  - Read
+  - Bash
+---
+<objective>
+Update brain's hooks, agents, and commands to the latest version without losing project state (brain.json, phases, roadmap, etc.).
+</objective>
+
+<process>
+1. Run: `npx brain-dev@latest update`
+2. Brain will:
+   - Backup brain.json to brain.json.pre-update
+   - Update hook scripts (.brain/hooks/)
+   - Update agent definitions (.claude/agents/)
+   - Update command files (.claude/commands/brain/)
+   - Migrate brain.json schema (add new fields, preserve existing)
+   - Regenerate STATE.md
+3. All project data is preserved: phases, plans, roadmap, research, quick tasks.
+</process>

package/hooks/bootstrap.sh

@@ -34,7 +34,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:progress, /brain:pause, /brain:resume, /brain:help, /brain:health, /brain:storm, /brain:adr, /brain:phase, /brain:config, /brain:map',
+    'Commands: /brain:new-project, /brain:discuss, /brain:plan, /brain:execute, /brain:verify, /brain:complete, /brain:quick, /brain:progress, /brain:pause, /brain:resume, /brain:help, /brain:health, /brain:update, /brain:storm, /brain:adr, /brain:phase, /brain:config, /brain:map',
     '',
     '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.1.0",
+  "version": "0.1.2",
   "description": "AI-powered development workflow orchestrator",
   "author": "halilcosdu",
   "license": "MIT",