homunculus-code 0.1.0

package/bin/init.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+// homunculus init — Set up a self-evolving AI assistant in your project
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+const CORE_DIR = path.join(__dirname, '..', 'core');
+const COMMANDS_DIR = path.join(__dirname, '..', 'commands');
+
+const YES_MODE = process.argv.includes('--yes') || process.argv.includes('-y');
+
+let rl;
+if (!YES_MODE) {
+  rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+}
+
+function ask(question, defaultVal) {
+  if (YES_MODE) return Promise.resolve(process.env[`HOMUNCULUS_${question.replace(/[^A-Z]/gi, '_').toUpperCase()}`] || defaultVal || '');
+  return new Promise(resolve => {
+    const suffix = defaultVal ? ` (${defaultVal})` : '';
+    rl.question(`${question}${suffix}: `, answer => {
+      resolve(answer.trim() || defaultVal || '');
+    });
+  });
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyFile(src, dest) {
+  if (fs.existsSync(src)) {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function copyDir(src, dest) {
+  ensureDir(dest);
+  if (!fs.existsSync(src)) return;
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function replaceTemplateVars(content, vars) {
+  let result = content;
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
+  }
+  return result;
+}
+
+async function main() {
+  console.log('');
+  console.log('  \x1b[1mHomunculus\x1b[0m — Self-evolving AI Assistant');
+  console.log('  A seed that grows into your own AI assistant.');
+  console.log('');
+
+  const projectDir = process.cwd();
+
+  // Check if already initialized
+  if (fs.existsSync(path.join(projectDir, 'homunculus'))) {
+    console.log('  \x1b[33m!\x1b[0m homunculus/ already exists. Re-running will skip existing files.');
+    console.log('');
+  }
+
+  // Gather info
+  const projectName = await ask('  Project name', path.basename(projectDir));
+  const purpose = await ask('  What is this project\'s main goal?', 'My evolving AI assistant');
+
+  console.log('');
+  console.log('  Select areas you want your AI to improve in:');
+  console.log('');
+
+  const goalOptions = [
+    { key: '1', name: 'code_quality', label: 'Code Quality', desc: 'Ship fewer bugs, better tests' },
+    { key: '2', name: 'productivity', label: 'Productivity', desc: 'Complete tasks faster' },
+    { key: '3', name: 'debugging', label: 'Debugging', desc: 'Faster root cause analysis' },
+    { key: '4', name: 'documentation', label: 'Documentation', desc: 'Keep docs up to date' },
+    { key: '5', name: 'automation', label: 'Automation', desc: 'Automate repetitive work' },
+    { key: '6', name: 'learning', label: 'Continuous Learning', desc: 'Stay up to date with tools and patterns' },
+  ];
+
+  for (const opt of goalOptions) {
+    console.log(`    ${opt.key}. ${opt.label} — ${opt.desc}`);
+  }
+  console.log('');
+
+  const selectedStr = await ask('  Select areas (enter numbers, e.g. 1,2,5)', '1,2');
+  const selectedKeys = selectedStr.split(/[,\s]+/).map(s => s.trim()).filter(Boolean);
+  const selectedGoals = goalOptions.filter(o => selectedKeys.includes(o.key));
+  if (selectedGoals.length === 0) selectedGoals.push(goalOptions[0], goalOptions[1]);
+
+  console.log('');
+
+  const vars = {
+    PROJECT_NAME: projectName,
+    PROJECT_PURPOSE: purpose
+  };
+
+  // Generate architecture.yaml from selected goals
+  function generateArchitecture(goals, rootPurpose) {
+    let yaml = `# architecture.yaml — Your goal tree\n`;
+    yaml += `# Goals are stable. Implementations evolve.\n`;
+    yaml += `# See: https://github.com/JavanC/Homunculus\n\n`;
+    yaml += `version: "1.0"\n\n`;
+    yaml += `root:\n`;
+    yaml += `  purpose: "${rootPurpose}"\n\n`;
+    yaml += `  goals:\n`;
+
+    const goalTemplates = {
+      code_quality: {
+        purpose: 'Ship fewer bugs, write more maintainable code',
+        goals: {
+          testing: { purpose: 'Every change has tests', realized_by: '# will evolve' },
+          review: { purpose: 'Catch issues before merge', realized_by: '# will evolve' }
+        },
+        metrics: [{ name: 'test_pass_rate', healthy: '> 90%' }]
+      },
+      productivity: {
+        purpose: 'Complete tasks faster with fewer iterations',
+        goals: {
+          task_completion: { purpose: 'Finish tasks in fewer cycles', realized_by: '# will evolve' },
+          tool_mastery: { purpose: 'Use the right tool on first try', realized_by: '# will evolve' }
+        },
+        metrics: [{ name: 'avg_iterations_per_task', healthy: 'decreasing trend' }]
+      },
+      debugging: {
+        purpose: 'Find and fix bugs faster',
+        goals: {
+          root_cause: { purpose: 'Identify root causes, not symptoms', realized_by: '# will evolve' },
+          diagnosis_tools: { purpose: 'Use the right debugging approach', realized_by: '# will evolve' }
+        },
+        metrics: [{ name: 'avg_debug_time', healthy: 'decreasing trend' }]
+      },
+      documentation: {
+        purpose: 'Keep documentation accurate and up to date',
+        goals: {
+          api_docs: { purpose: 'API docs match implementation', realized_by: '# will evolve' },
+          decision_records: { purpose: 'Document why, not just what', realized_by: '# will evolve' }
+        },
+        metrics: [{ name: 'doc_freshness', healthy: '< 1 week behind code' }]
+      },
+      automation: {
+        purpose: 'Automate repetitive work',
+        goals: {
+          ci_cd: { purpose: 'Automated build, test, deploy', realized_by: '# will evolve' },
+          workflows: { purpose: 'Common sequences as one command', realized_by: '# will evolve' }
+        },
+        metrics: [{ name: 'manual_steps_per_deploy', healthy: '< 3' }]
+      },
+      learning: {
+        purpose: 'Stay up to date with tools and best practices',
+        goals: {
+          tool_updates: { purpose: 'Track and adopt useful updates', realized_by: '# will evolve' },
+          pattern_discovery: { purpose: 'Find better ways to do things', realized_by: '# will evolve' }
+        },
+        metrics: [{ name: 'patterns_adopted_per_month', healthy: '> 2' }]
+      }
+    };
+
+    for (const goal of goals) {
+      const tmpl = goalTemplates[goal.name];
+      if (!tmpl) continue;
+      yaml += `    ${goal.name}:\n`;
+      yaml += `      purpose: "${tmpl.purpose}"\n`;
+      if (tmpl.metrics) {
+        yaml += `      metrics:\n`;
+        for (const m of tmpl.metrics) {
+          yaml += `        - name: ${m.name}\n`;
+          yaml += `          healthy: "${m.healthy}"\n`;
+        }
+      }
+      if (tmpl.goals) {
+        yaml += `      goals:\n`;
+        for (const [subName, sub] of Object.entries(tmpl.goals)) {
+          yaml += `        ${subName}:\n`;
+          yaml += `          purpose: "${sub.purpose}"\n`;
+          yaml += `          realized_by: ${sub.realized_by}\n`;
+        }
+      }
+      yaml += `\n`;
+    }
+
+    yaml += `    # Add more goals as your system evolves...\n`;
+    return yaml;
+  }
+
+  // 1. Create directory structure
+  const dirs = [
+    'homunculus/instincts/personal',
+    'homunculus/instincts/archived',
+    'homunculus/evolved/skills',
+    'homunculus/evolved/agents',
+    'homunculus/evolved/evals',
+    'homunculus/experiments',
+    'scripts',
+    '.claude/rules',
+    '.claude/commands'
+  ];
+
+  for (const dir of dirs) {
+    ensureDir(path.join(projectDir, dir));
+  }
+  console.log('  \x1b[32m✓\x1b[0m Created homunculus/ directory structure');
+
+  // 2. Generate architecture.yaml from selected goals
+  const archDest = path.join(projectDir, 'architecture.yaml');
+  if (!fs.existsSync(archDest)) {
+    const archContent = generateArchitecture(selectedGoals, purpose);
+    fs.writeFileSync(archDest, archContent);
+    console.log(`  \x1b[32m✓\x1b[0m Created architecture.yaml with ${selectedGoals.length} goals: ${selectedGoals.map(g => g.label).join(', ')}`);
+  } else {
+    console.log('  \x1b[33m-\x1b[0m architecture.yaml already exists, skipping');
+  }
+
+  // 3. Copy CLAUDE.md template (append if exists)
+  const claudeDest = path.join(projectDir, 'CLAUDE.md');
+  if (!fs.existsSync(claudeDest)) {
+    const template = fs.readFileSync(
+      path.join(TEMPLATES_DIR, 'CLAUDE.md.template'), 'utf8'
+    );
+    fs.writeFileSync(claudeDest, replaceTemplateVars(template, vars));
+    console.log('  \x1b[32m✓\x1b[0m Created CLAUDE.md');
+  } else {
+    console.log('  \x1b[33m-\x1b[0m CLAUDE.md already exists, skipping');
+  }
+
+  // 4. Copy evolution rules
+  const rulesDest = path.join(projectDir, '.claude', 'rules', 'evolution-system.md');
+  if (!fs.existsSync(rulesDest)) {
+    copyFile(
+      path.join(TEMPLATES_DIR, 'rules', 'evolution-system.md'),
+      rulesDest
+    );
+    console.log('  \x1b[32m✓\x1b[0m Created .claude/rules/evolution-system.md');
+  }
+
+  // 5. Copy core scripts
+  if (fs.existsSync(CORE_DIR)) {
+    copyDir(CORE_DIR, path.join(projectDir, 'scripts'));
+    console.log('  \x1b[32m✓\x1b[0m Copied evolution scripts to scripts/');
+  }
+
+  // 6. Copy slash commands
+  if (fs.existsSync(COMMANDS_DIR)) {
+    copyDir(COMMANDS_DIR, path.join(projectDir, '.claude', 'commands'));
+    console.log('  \x1b[32m✓\x1b[0m Copied slash commands to .claude/commands/');
+  }
+
+  // 7. Configure Claude Code hooks (if settings exist)
+  const settingsPath = path.join(projectDir, '.claude', 'settings.json');
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {}
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PostToolUse) {
+    settings.hooks.PostToolUse = [{
+      type: "command",
+      command: "bash scripts/observe.sh post",
+      description: "Homunculus: observe tool usage"
+    }];
+    ensureDir(path.join(projectDir, '.claude'));
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    console.log('  \x1b[32m✓\x1b[0m Configured Claude Code observation hook');
+  }
+
+  // 8. Create .gitignore additions
+  const gitignorePath = path.join(projectDir, '.gitignore');
+  const gitignoreEntries = [
+    '',
+    '# Homunculus runtime data',
+    'homunculus/observations.jsonl*',
+    'data/hook-profile*',
+    'data/auto-learn-cooldown.json'
+  ].join('\n');
+
+  if (fs.existsSync(gitignorePath)) {
+    const existing = fs.readFileSync(gitignorePath, 'utf8');
+    if (!existing.includes('Homunculus runtime')) {
+      fs.appendFileSync(gitignorePath, '\n' + gitignoreEntries + '\n');
+      console.log('  \x1b[32m✓\x1b[0m Updated .gitignore');
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, gitignoreEntries.trim() + '\n');
+    console.log('  \x1b[32m✓\x1b[0m Created .gitignore');
+  }
+
+  console.log('');
+  console.log('  \x1b[1m\x1b[32mDone!\x1b[0m Your assistant is ready to evolve.');
+  console.log('');
+  console.log('  Next steps:');
+  console.log('  1. Edit \x1b[1marchitecture.yaml\x1b[0m to define your goals');
+  console.log('  2. Use Claude Code normally — the system observes automatically');
+  console.log('  3. Run \x1b[1mclaude "/eval-skill"\x1b[0m to check evolution progress');
+  console.log('');
+
+  if (rl) rl.close();
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/commands/eval-skill.md

@@ -0,0 +1,48 @@
+---
+disable-model-invocation: true
+---
+# /eval-skill — Evaluate an Evolved Skill
+
+Run scenario-based tests on a skill to measure its quality.
+
+## Steps
+
+1. List eval specs: `ls homunculus/evolved/evals/*.eval.yaml 2>/dev/null`
+2. If user specified a skill name, use that eval spec; otherwise let user choose
+3. Read the skill file (`homunculus/evolved/skills/<name>.md`) and its eval spec
+
+## Evaluation
+
+For each scenario, act as a **developer who doesn't know the answer** — only reference the skill document. Then compare against expected_behavior and anti_patterns.
+
+## Results
+
+| Result | Condition |
+|--------|-----------|
+| **PASS** | Skill guides all expected behaviors, no anti-patterns triggered |
+| **PARTIAL** | Skill guides some expected behaviors, or misses important details |
+| **FAIL** | Skill fails to guide correct behavior, or would cause anti-patterns |
+| **GAP** | Scenario knowledge is completely absent from skill |
+
+## Report Format
+
+```
+🔬 Skill Eval: <name> v<version>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Scenario                Result   Notes
+──────────────────────────────────────
+<scenario.name>         PASS     -
+<scenario.name>         PARTIAL  Missing X
+<scenario.name>         FAIL     Would cause Y
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Pass rate: X/Y (Z%)
+Grade: ⭐⭐⭐⭐⭐ (>= 90)
+```
+
+## After Evaluation
+
+- Update `last_eval` and `pass_rate` in the eval spec
+- Append result to `homunculus/evolved/evals/history.jsonl`
+- Suggest improvements for FAIL/PARTIAL/GAP scenarios

package/commands/evolve.md

@@ -0,0 +1,67 @@
+---
+disable-model-invocation: true
+---
+# /evolve — Converge Instincts into Skills
+
+Analyze existing instincts and find patterns that can be aggregated into higher-level skills.
+
+## Modes
+
+- Default → **Interactive mode** (manual confirmation)
+- `--auto` → **Auto mode** (for nightly agent, no confirmation needed)
+
+## Interactive Mode
+
+### Steps
+
+1. Read all instincts from `homunculus/instincts/personal/`
+2. Group by trigger/topic similarity
+3. Analyze groups:
+   - **2+ instincts with similar triggers** → Skill candidate
+   - **High confidence (≥0.7) workflow combos** → Command candidate
+4. Present candidates for user confirmation
+5. Generate to `homunculus/evolved/`
+
+### Report
+
+```
+Evolution Analysis
+━━━━━━━━━━━━━━━━━━
+Instincts: N total
+Groups: M
+
+Skill candidates:
+  1. <name> (source: N instincts, avg confidence: 0.X)
+  2. ...
+
+Select items to evolve (enter numbers) or 'all':
+```
+
+## Auto Mode (--auto)
+
+For nightly agent. Runs the full pipeline: evolve → eval → improve.
+
+1. **Evolve**: Auto-select candidates with avg confidence ≥ 0.7
+2. **Eval**: Run scenario tests on all skills with eval specs
+3. **Improve**: Auto-improve skills below 100% (max 3 rounds)
+   - Rollback if score regresses
+
+## Skill Format
+
+```yaml
+name: <skill name>
+description: <description>
+trigger: <unified trigger>
+steps:
+  - <step 1>
+  - <step 2>
+source_instincts:
+  - <source instinct filename>
+confidence: <average confidence>
+created: <ISO timestamp>
+```
+
+## Notes
+- Source instincts are NOT deleted (preserved for history)
+- Each evolution tracked via git
+- Evolved skill confidence inherited from source instincts

package/commands/improve-skill.md

@@ -0,0 +1,50 @@
+---
+disable-model-invocation: true
+---
+# /improve-skill — Auto-Improve an Evolved Skill
+
+Iteratively improve a skill until its eval passes, using an eval → improve loop.
+
+## Flow
+
+```
+┌─── Round 1 ──────────────────────────┐
+│  1. /eval-skill → baseline score      │
+│  2. Analyze FAIL/PARTIAL/GAP          │
+│  3. Modify skill file                 │
+│  4. Bump version +0.1                 │
+│  5. Re-eval                           │
+│  6. Compare scores:                   │
+│     ├─ Improved (≥5pp)  → next round  │
+│     ├─ Noise (<5pp)     → stop        │
+│     └─ Regressed (≤-5pp) → rollback   │
+└──────────────────────────────────────┘
+         ↓ (max 5 rounds)
+```
+
+## Steps
+
+1. Verify target skill and eval spec exist
+2. Run initial eval, record baseline score
+3. **Improve loop** (max 5 rounds):
+   a. Analyze failing scenarios
+   b. Modify skill file:
+      - FAIL → fix incorrect info or add missing rules
+      - PARTIAL → add detail
+      - GAP → add new section
+   c. Increment version (1.1 → 1.2 → 1.3...)
+   d. Re-eval
+   e. Compare scores (apply noise tolerance: 5pp)
+4. Output improvement report
+
+## Regression Detection
+
+If a previously passing scenario now fails:
+- Mark as **REGRESSION**
+- Must fix regression before continuing
+- If unable to fix, rollback to previous version
+
+## Notes
+- Only modify the skill file, never the eval spec (tests stay fixed)
+- All intermediate versions tracked via git
+- Score delta < 5pp = statistical noise, not real improvement

package/core/evaluate-session.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// evaluate-session.js — Extract instincts from session observations
+// Part of the Homunculus evolution pipeline
+//
+// Flow:
+// 1. Read observations.jsonl, analyze tool usage patterns
+// 2. Determine if session is worth extracting (enough activity)
+// 3. Use Claude CLI to extract behavioral patterns as instincts
+// 4. Write instincts to homunculus/instincts/personal/
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Configuration — adapt these to your setup
+const BASE_DIR = process.env.HOMUNCULUS_BASE || process.cwd();
+const HOMUNCULUS_DIR = path.join(BASE_DIR, 'homunculus');
+const INSTINCTS_DIR = path.join(HOMUNCULUS_DIR, 'instincts', 'personal');
+const OBS_FILE = path.join(HOMUNCULUS_DIR, 'observations.jsonl');
+
+// Extraction thresholds (auto-tunable)
+const CONFIG = {
+  min_messages: parseInt(process.env.HOMUNCULUS_MIN_MESSAGES || '10'),
+  min_tool_repeats: parseInt(process.env.HOMUNCULUS_MIN_TOOL_REPEATS || '5'),
+  daily_limit: parseInt(process.env.HOMUNCULUS_DAILY_LIMIT || '3')
+};
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function getDateString() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function log(...args) {
+  process.stderr.write('[evaluate-session] ' + args.join(' ') + '\n');
+}
+
+// Count today's extractions to respect daily limit
+function getTodayExtractions() {
+  const today = getDateString();
+  try {
+    const files = fs.readdirSync(INSTINCTS_DIR);
+    return files.filter(f => {
+      const content = fs.readFileSync(path.join(INSTINCTS_DIR, f), 'utf8');
+      return content.includes(today);
+    }).length;
+  } catch {
+    return 0;
+  }
+}
+
+// Analyze observations to find patterns
+function analyzeObservations() {
+  if (!fs.existsSync(OBS_FILE)) {
+    log('No observations file found');
+    return null;
+  }
+
+  const lines = fs.readFileSync(OBS_FILE, 'utf8').trim().split('\n').filter(Boolean);
+  if (lines.length < CONFIG.min_messages) {
+    log(`Only ${lines.length} observations (need ${CONFIG.min_messages}), skipping`);
+    return null;
+  }
+
+  // Count tool usage
+  const toolCounts = {};
+  for (const line of lines) {
+    try {
+      const obs = JSON.parse(line);
+      const tool = obs.tool || 'unknown';
+      toolCounts[tool] = (toolCounts[tool] || 0) + 1;
+    } catch {}
+  }
+
+  // Find high-frequency tools
+  const frequentTools = Object.entries(toolCounts)
+    .filter(([_, count]) => count >= CONFIG.min_tool_repeats)
+    .sort((a, b) => b[1] - a[1]);
+
+  if (frequentTools.length === 0) {
+    log('No high-frequency tool patterns found, skipping');
+    return null;
+  }
+
+  return {
+    total_observations: lines.length,
+    frequent_tools: frequentTools,
+    tool_counts: toolCounts
+  };
+}
+
+// Extract instinct using Claude CLI
+function extractInstinct(analysis) {
+  const toolSummary = analysis.frequent_tools
+    .map(([tool, count]) => `${tool}: ${count} times`)
+    .join(', ');
+
+  const prompt = `Based on this session's tool usage patterns, extract ONE behavioral instinct that would be useful to remember for future sessions.
+
+Tool usage: ${toolSummary}
+Total observations: ${analysis.total_observations}
+
+Write the instinct as a markdown file with this format:
+
+---
+name: descriptive-kebab-case-name
+category: one of [coding, debugging, workflow, communication, tool-usage]
+confidence: 0.7
+extracted: "${getDateString()}"
+source: "session observation"
+---
+
+## Pattern
+[Describe the behavioral pattern in 1-2 sentences]
+
+## When to Apply
+[When should this pattern be used]
+
+## Anti-Patterns
+[What to avoid]
+
+IMPORTANT: Only output the markdown content, nothing else.`;
+
+  try {
+    const result = execSync(
+      `claude -p "${prompt.replace(/"/g, '\\"')}" --model claude-sonnet-4-6 --max-budget-usd 0.50`,
+      { encoding: 'utf8', timeout: 30000 }
+    );
+
+    // Extract name from frontmatter
+    const nameMatch = result.match(/name:\s*(.+)/);
+    if (!nameMatch) return null;
+
+    const name = nameMatch[1].trim().replace(/[^a-z0-9-]/g, '-');
+    const filename = `${name}.md`;
+    const filepath = path.join(INSTINCTS_DIR, filename);
+
+    if (fs.existsSync(filepath)) {
+      log(`Instinct ${filename} already exists, skipping`);
+      return null;
+    }
+
+    ensureDir(INSTINCTS_DIR);
+    fs.writeFileSync(filepath, result.trim() + '\n');
+    log(`Extracted instinct: ${filename}`);
+    return filename;
+  } catch (err) {
+    log(`Extraction failed: ${err.message}`);
+    return null;
+  }
+}
+
+// Main
+function main() {
+  // Check daily limit
+  const todayCount = getTodayExtractions();
+  if (todayCount >= CONFIG.daily_limit) {
+    log(`Daily limit reached (${todayCount}/${CONFIG.daily_limit}), skipping`);
+    return;
+  }
+
+  const analysis = analyzeObservations();
+  if (!analysis) return;
+
+  const result = extractInstinct(analysis);
+  if (result) {
+    log(`Successfully extracted: ${result}`);
+  }
+}
+
+main();