homunculus-code 0.3.4 → 0.4.1

package/README.md

@@ -160,23 +160,23 @@ Homunculus — Self-evolving AI Assistant
 ✓ Created homunculus/ directory structure
 ✓ Added evolution rules
 ✓ Copied evolution scripts
-✓ Added slash commands (/hm-setup, /hm-night, /hm-status)
+✓ Added slash commands (/hm-goal, /hm-night, /hm-status)
 ✓ Configured observation hook
 
 Done! Homunculus is installed.
 
 Next steps:
   1. Run claude to open Claude Code
-  2. Type /hm-setup to define your goals (AI-guided)
+  2. Type /hm-goal to define your goals (AI-guided)
   3. Type /hm-night to run your first evolution cycle
 ```
 
 ### 2. Define Your Goals
 
-Open Claude Code and type `/hm-setup`. Claude will have a short conversation with you to understand your project and goals, then generate your `architecture.yaml` automatically.
+Open Claude Code and type `/hm-goal`. Claude will have a short conversation with you to understand your project and goals, then generate your `architecture.yaml` automatically.
 
 ```
-> /hm-setup
+> /hm-goal
 
 Claude: What kind of project is this?
 You:    A SaaS app for team collaboration
@@ -215,7 +215,7 @@ The observation hook watches your usage automatically. As patterns emerge:
 ```
 /hm-night       Run an evolution cycle
 /hm-status      Check evolution progress
-/hm-setup       Refine your goals anytime
+/hm-goal       Refine your goals anytime
 /eval-skill     Evaluate a specific skill
 /improve-skill  Auto-improve a skill
 /evolve         Converge instincts into skills

package/bin/init.js

@@ -76,7 +76,7 @@ This project uses Homunculus for goal-driven evolution.
 - **Goal Tree**: \`architecture.yaml\` — defines goals, metrics, and health checks
 - **Instincts**: \`homunculus/instincts/personal/\` — auto-extracted patterns
 - **Skills**: \`homunculus/evolved/skills/\` — tested, versioned knowledge
-- **Commands**: \`/hm-setup\` (define goals) | \`/hm-night\` (evolution cycle) | \`/hm-status\` (dashboard)
+- **Commands**: \`/hm-goal\` (define goals) | \`/hm-night\` (evolution cycle) | \`/hm-status\` (dashboard)
 `;
 
   if (fs.existsSync(claudeDest)) {
@@ -106,7 +106,7 @@ This project uses Homunculus for goal-driven evolution.
   // 5. Copy slash commands
   if (fs.existsSync(COMMANDS_DIR)) {
     copyDir(COMMANDS_DIR, path.join(projectDir, '.claude', 'commands'));
-    console.log('  \x1b[32m✓\x1b[0m Added slash commands (/hm-setup, /hm-night, /hm-status)');
+    console.log('  \x1b[32m✓\x1b[0m Added slash commands (/hm-goal, /hm-night, /hm-status)');
   }
 
   // 6. Configure Claude Code hooks
@@ -157,7 +157,7 @@ This project uses Homunculus for goal-driven evolution.
   console.log('');
   console.log('  Next steps:');
   console.log('    1. Run \x1b[1mclaude\x1b[0m to open Claude Code');
-  console.log('    2. Type \x1b[1m/hm-setup\x1b[0m to define your goals (AI-guided)');
+  console.log('    2. Type \x1b[1m/hm-goal\x1b[0m to define your goals (AI-guided)');
   console.log('    3. Type \x1b[1m/hm-night\x1b[0m to run your first evolution cycle');
   console.log('');
 }

package/commands/{hm-setup.md → hm-goal.md}

@@ -1,25 +1,67 @@
-# /hm-setup — Set Up Your Goal Tree
+# /hm-goal — View or Define Your Goal Tree
 
-Guide the user through defining their goals and generate `architecture.yaml`.
+If `architecture.yaml` exists, display the current goal tree and ask if changes are needed.
+If it doesn't exist, guide the user through creating one.
 
 **Always communicate in English** regardless of user's global Claude settings.
 
 ## Behavior
 
-You are helping the user set up Homunculus — a self-evolving AI assistant. Your job is to understand their project and goals, then generate a goal tree.
+### Mode Detection
+
+Check if `architecture.yaml` exists in the project root.
+
+- **Exists** → Show Mode
+- **Doesn't exist** → Create Mode
+
+---
+
+## Show Mode (architecture.yaml exists)
+
+### Step 1: Read and display
+
+Read `architecture.yaml` and present the goal tree visually:
+
+```
+🎯 Your Goal Tree
+├── code_quality — Ship fewer bugs
+│   ├── testing — Every change has tests
+│   │   └── realized_by: skills/tdd-workflow.md ✓
+│   └── review — Catch issues before merge
+│       └── realized_by: # will evolve ○
+├── productivity — Move faster
+│   └── debugging — Find root causes faster
+│       └── realized_by: agents/debugger.md ✓
+└── knowledge — Stay current
+    └── tool_updates — Track useful updates
+        └── realized_by: # will evolve ○
+
+3 goals / 5 sub-goals
+2 implemented (✓) / 3 waiting to evolve (○)
+```
+
+### Step 2: Ask
+
+> "Want to add, remove, or change any goals?"
+
+- If yes → make the changes, update `architecture.yaml`
+- If no → done
+
+---
+
+## Create Mode (no architecture.yaml)
 
 **CRITICAL: Ask ONE question at a time. Wait for the answer before asking the next. Never batch multiple questions in one message.**
 
 ### Step 1: Ask about the project (ONE question)
 
-Start with:
 > "What kind of project is this? (e.g., web app, CLI tool, API, personal project)"
 
 Wait for answer.
 
 ### Step 2: Ask about pain points (ONE question)
 
-Based on their answer, ask:
+Based on their answer:
 > "What do you spend the most time on that you wish was better? (e.g., debugging, testing, deployment, keeping up with updates)"
 
 Wait for answer.
@@ -30,7 +72,7 @@ Based on their answer, ask ONE more targeted question. Examples:
 - "If your AI assistant could fix one thing overnight, what would it be?"
 - "What breaks most often in your workflow?"
 
-Adapt this question based on what they already told you. Wait for answer.
+Adapt based on what they already told you. Wait for answer.
 
 ### Step 4: Propose goals
 
@@ -68,15 +110,15 @@ Write the file using the Write tool.
 ```
 ✅ architecture.yaml created with N goals!
 
-Your system is ready to evolve. Use Claude Code normally —
-patterns will be auto-extracted. Run /hm-night anytime to
-trigger an evolution cycle.
+Your system is ready to evolve. Run /hm-night to start
+your first evolution cycle.
 ```
 
 ## Rules
 
-- **ONE question per message. Never ask two questions at once.**
+- **ONE question per message in Create Mode. Never ask two questions at once.**
 - Keep the whole setup under 5 back-and-forth messages
 - Generate PRACTICAL goals, not abstract ones
 - Don't overwhelm — 3-5 top-level goals is ideal
-- Goals can always be refined later with `/hm-setup` again
+- In Show Mode, show realized_by status (✓ = file exists, ○ = not yet)
+- Goals can always be refined by running `/hm-goal` again

package/commands/hm-night.md

@@ -1,12 +1,29 @@
 # /hm-night — Run One Evolution Cycle
 
-Run the full evolution pipeline: health check → instincts → skills → research → report.
+Run the full evolution pipeline: health check → evolve → research → report.
 
 **Always communicate in English** regardless of user's global Claude settings.
 
+## Core Principle
+
+**Goals are stable. Implementations are diverse.** When suggesting improvements, consider ALL implementation types — not just skills:
+
+| Type | When to suggest |
+|------|----------------|
+| Skill | Behavioral knowledge Claude should follow |
+| Agent | Task needs specialized model/tools/prompt |
+| Hook | Should trigger automatically on events |
+| Script | Automation that runs independently |
+| Rule | Claude Code behavioral constraint |
+| Command | Workflow the user triggers manually |
+| Cron/LaunchAgent | Needs to run on a schedule |
+| MCP | Needs external service integration |
+
+Always pick the **right tool for the job**, not default to skills.
+
 ## Behavior
 
-You are the Homunculus nightly evolution agent. Run through all 5 phases systematically.
+Run through all 5 phases systematically.
 
 ### Phase 1: Health Check
 
@@ -18,71 +35,91 @@ You are the Homunculus nightly evolution agent. Run through all 5 phases systema
    [1/5] Health Check
          code_quality:    ✅ healthy (tests passing)
          productivity:    ⚠️ no health check defined
-         knowledge:       ✅ healthy
+         ai_news:         ○ not implemented yet
    ```
 
-### Phase 2: Scan Instincts
+### Phase 2: Scan Evolved Assets
 
-1. Count files in `homunculus/instincts/personal/` and `homunculus/instincts/archived/`
-2. If instincts exist, check for pruning candidates (run `node scripts/prune-instincts.js` if it exists)
-3. Report count and any archival suggestions
-   ```
-   [2/5] Instincts
-         12 active / 5 archived
-         △ 2 candidates for archival (low confidence)
-   ```
+Check ALL evolved artifacts, not just skills:
 
-### Phase 3: Eval Skills
+1. **Instincts**: Count in `homunculus/instincts/personal/` and `archived/`
+2. **Skills**: Count in `homunculus/evolved/skills/`, run evals if specs exist
+3. **Agents**: Count in `homunculus/evolved/agents/`
+4. **Scripts**: Check `scripts/` for automation
+5. **Hooks**: Check `.claude/settings.json` for configured hooks
+6. **Commands**: Check `.claude/commands/` for slash commands
+7. **Rules**: Check `.claude/rules/` for behavioral rules
 
-1. List files in `homunculus/evolved/skills/`
-2. For each skill, check if an eval spec exists in `homunculus/evolved/evals/`
-3. If eval specs exist, run `/eval-skill` on each
-4. Report pass rates
-   ```
-   [3/5] Skills
-         ✓ tdd-workflow: 100% (8/8 scenarios)
-         △ debugging-patterns: 85% (6/7) — needs improvement
-   ```
+Report:
+```
+[2/5] Evolved Assets
+      Instincts:  12 active / 5 archived
+      Skills:     2 (all 100% eval)
+      Agents:     1 (debugger)
+      Hooks:      3 configured
+      Commands:   6 available
+      Rules:      2 active
+```
+
+If skills have eval specs, run `/eval-skill` and report pass rates.
 
-### Phase 4: Research
+### Phase 3: Research & Suggest
 
-1. Check Claude Code version
-2. Scan `architecture.yaml` for goals with no `realized_by` — these are opportunities
-3. Look for goals with failing health checks — these need attention
-4. Suggest improvements:
+1. Scan `architecture.yaml` for goals where `realized_by` is empty or `# will evolve`
+2. For each unimplemented goal, suggest the **most appropriate implementation type**:
    ```
-   [4/5] Research
-         ✓ Claude Code v2.1.81
-         △ 2 goals have no implementation yet
-         → Suggestion: code_quality.review could use a pre-commit hook
+   [3/5] Research
+         Goals without implementation:
+
+         ai_news → Suggestion: a SCRIPT that fetches from RSS/APIs
+                   + a CRON job to run it daily
+                   (not a skill — this needs to run independently)
+
+         code_review → Suggestion: a HOOK on pre-commit
+                       (not a skill — should be automated, not behavioral)
+
+         debugging → Suggestion: an AGENT with specialized tools
+                     (not a script — needs AI reasoning)
    ```
 
+3. For goals with failing health checks, suggest fixes using the right implementation type
+
+### Phase 4: Act (if possible)
+
+If there are simple improvements that can be made right now:
+- Prune outdated instincts (`node scripts/prune-instincts.js --apply`)
+- Improve failing skills (`/improve-skill`)
+- Create a suggested script or hook if straightforward
+
+Report what was done.
+
 ### Phase 5: Report
 
 Generate a summary report and save to `homunculus/reports/YYYY-MM-DD.md`:
 
 ```
 [5/5] Evolution Report — 2026-03-22
-┌──────────────────────────────────────────┐
-│  Goals:      5 (3 healthy, 2 need work)  │
-│  Instincts:  12 active / 5 archived      │
-│  Skills:     3 (2 at 100%, 1 at 85%)     │
-│                                          │
-│  Actions taken:                          │
-│  - Pruned 2 outdated instincts           │
-│  - Improved debugging-patterns to v1.2   │
-│                                          │
-│  Suggestions:                            │
-│  - Add health check to productivity goal │
-│  - Review could use a pre-commit hook    │
-└──────────────────────────────────────────┘
+┌──────────────────────────────────────────────┐
+│  Goals:       5 (2 healthy, 1 new, 2 todo)   │
+│  Assets:      2 skills, 1 agent, 3 hooks     │
+│  Instincts:   12 active / 5 archived         │
+│                                              │
+│  Actions taken:                              │
+│  - Pruned 2 outdated instincts               │
+│  - Created scripts/fetch-news.sh             │
+│                                              │
+│  Suggestions:                                │
+│  - code_review: add pre-commit hook          │
+│  - debugging: create specialized agent       │
+│  - Add health checks to 2 goals             │
+└──────────────────────────────────────────────┘
 ```
 
-## Important
+## Rules
 
+- **Don't default to skills for everything** — match implementation to the goal's nature
 - Actually RUN health check commands (don't just read them)
 - Actually RUN eval-skill if eval specs exist (don't skip)
-- If a skill fails eval, attempt `/improve-skill` (max 2 rounds)
 - Save the report to `homunculus/reports/`
-- Be concise — this should feel like a progress dashboard, not an essay
-- If the system is fresh (no instincts/skills), give encouraging guidance
+- Be concise — dashboard style, not essay
+- If fresh system: suggest the FIRST concrete implementation to build (pick the easiest win)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homunculus-code",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "description": "A self-evolving AI assistant that grows smarter every night",
   "bin": {
     "homunculus-code": "./bin/cli.js"