feat: add meta-evolution for self-improving capabilities

.gitignore

@@ -11,6 +11,7 @@ Thumbs.db
 # Don't commit user state (that's per-project)
 # state.json files are created in each project's .claude/homunculus/
 .claude/homunculus/
+.claude/settings.local.json
 
 # Landing page
 landing/node_modules/

plugins/homunculus/commands/improve.md

@@ -0,0 +1,138 @@
+---
+description: Improve a specific evolved capability based on usage feedback
+---
+
+# Improve
+
+Explicitly trigger improvement of an evolved capability. Meta-evolution on demand.
+
+## Usage
+
+```
+/homunculus:improve [capability-name]
+```
+
+If no name given, show capabilities that need attention.
+
+## Process
+
+### 1. Load State
+
+```bash
+cat .claude/homunculus/state.json
+```
+
+### 2. If No Capability Specified
+
+Show what's available:
+
+```
+Your powers:
+
+[name]: [X]% effective ([N] uses) - [STATUS]
+[name]: [X]% effective ([N] uses) - [STATUS]
+[name]: not enough data ([N] uses)
+
+Which one should I look at?
+```
+
+Status meanings:
+- `healthy` - >70% effective
+- `needs attention` - <50% effective with 5+ uses
+- `struggling` - <30% effective
+- `not enough data` - <5 uses
+
+### 3. If Capability Specified
+
+Read the capability and its usage data:
+
+```bash
+# Read the capability file
+cat [path-from-state]
+
+# Get usage data from state
+cat .claude/homunculus/state.json | grep -A100 '"[name]"'
+```
+
+### 4. Invoke Self-Reflection
+
+Run the `self-reflection` skill to analyze:
+- What's failing?
+- Why is it failing?
+- What should change?
+
+### 5. Present Findings
+
+```
+Looking at [name]...
+
+Current: v[N], [X]% effective over [N] uses.
+
+What I'm seeing:
+- [Pattern 1]: [description]
+- [Pattern 2]: [description]
+
+The issue: [Root cause diagnosis]
+
+I'd change:
+1. [Specific change]
+2. [Specific change]
+3. [Specific change]
+
+Want me to do it?
+```
+
+### 6. If Approved
+
+Invoke the `self-improvement` skill to:
+1. Archive current version
+2. Rewrite the capability
+3. Update tracking
+4. Confirm the change
+
+### 7. Confirm
+
+```
+Done. [name] v[OLD] → v[NEW].
+
+Changes:
+- [What changed]
+
+Previous: [X]% effective
+Now tracking fresh. Let's see how it goes.
+```
+
+## Edge Cases
+
+**Capability doesn't exist:**
+```
+I don't have [name].
+
+Here's what I do have:
+[list of capabilities]
+```
+
+**Not enough usage data:**
+```
+[name] only has [N] uses. I need at least 5 to see patterns.
+
+Use it more, then come back.
+```
+
+**Already performing well:**
+```
+[name] is at [X]% effective. That's solid.
+
+Still want me to look for improvements?
+```
+
+**User provides direct feedback:**
+If they say what's wrong, skip reflection and go straight to improvement with their input as the diagnosis.
+
+## Remember
+
+- This is explicit meta-evolution
+- Always show what you're changing and why
+- Get approval for significant changes
+- Track everything in state
+- The goal: measurable improvement

plugins/homunculus/commands/init.md

@@ -75,7 +75,8 @@ Save `.claude/homunculus/state.json`:
   "homunculus": {
     "evolved": [],
     "awakened": "[ISO TIMESTAMP]"
-  }
+  },
+  "capabilities": {}
 }
 ```
 

plugins/homunculus/commands/metrics.md

@@ -0,0 +1,146 @@
+---
+description: View performance data for all evolved capabilities
+---
+
+# Metrics
+
+The dashboard. See how your evolved capabilities are performing. Proof of productive self-improvement.
+
+## Usage
+
+```
+/homunculus:metrics
+/homunculus:metrics [capability-name]
+```
+
+## Load Data
+
+```bash
+cat .claude/homunculus/state.json
+```
+
+## Overview (No Capability Specified)
+
+Show the full dashboard:
+
+```
+     ·  ✧  ·
+
+       ◉
+      ╱│╲
+       │
+      ╱ ╲
+    ▰▰▰▰▰▰▰
+
+CAPABILITIES DASHBOARD
+
+┌─────────────────────────────────────────────────────────────┐
+│ Capability      │ Version │ Uses │ Effectiveness │ Status  │
+├─────────────────────────────────────────────────────────────┤
+│ [name]          │ v[N]    │ [N]  │ [XX]%         │ [status]│
+│ [name]          │ v[N]    │ [N]  │ [XX]%         │ [status]│
+│ [name]          │ v[N]    │ [N]  │ —             │ new     │
+└─────────────────────────────────────────────────────────────┘
+
+IMPROVEMENT HISTORY
+
+[name]: v1 (45%) → v2 (62%) → v3 (81%)
+[name]: v1 (30%) → v2 (55%)
+
+OVERALL
+
+Total capabilities: [N]
+Total uses tracked: [N]
+Average effectiveness: [XX]%
+Improvements made: [N]
+```
+
+Status values:
+- `healthy` - >70% effective
+- `ok` - 50-70% effective
+- `struggling` - <50% effective with 5+ uses
+- `new` - <5 uses, no effectiveness yet
+- `improved` - recently improved, tracking fresh
+
+## Detailed View (Capability Specified)
+
+```
+[NAME] v[N]
+
+Created: [DATE]
+Path: [path]
+
+USAGE LOG (last 10)
+─────────────────────────────────────
+[timestamp] [+/-/~] [context snippet]
+[timestamp] [+/-/~] [context snippet]
+[timestamp] [+/-/~] [context snippet]
+...
+
+FEEDBACK BREAKDOWN
+─────────────────────────────────────
+Positive: [N] ([XX]%)
+Negative: [N] ([XX]%)
+Neutral:  [N] ([XX]%)
+
+EFFECTIVENESS OVER TIME
+─────────────────────────────────────
+v1: [XX]% over [N] uses
+v2: [XX]% over [N] uses (current)
+
+IMPROVEMENT HISTORY
+─────────────────────────────────────
+v1 → v2 ([DATE]):
+  Reason: [why it was improved]
+  Changes: [what changed]
+  Result: [XX]% → [XX]%
+```
+
+## Formatting Notes
+
+For the usage log:
+- `+` = positive feedback
+- `-` = negative feedback
+- `~` = neutral feedback
+
+Timestamps should be relative when recent:
+- "2 hours ago"
+- "yesterday"
+- "3 days ago"
+- Full date if older than a week
+
+## No Capabilities Yet
+
+```
+No evolved capabilities yet.
+
+Use /homunculus:evolve to grow new powers.
+Then come back here to see how they perform.
+```
+
+## Match Their Level
+
+**Technical:** Dense, data-focused, minimal prose.
+
+**Semi-technical:** Include brief explanations of what metrics mean.
+
+**Non-technical:** Focus on "what's working" vs "what needs help" narrative.
+
+**Chaotic:** Make it fun. Add personality to the numbers.
+
+## Why This Matters
+
+This dashboard is the proof:
+- Quantitative before/after data
+- Version history showing progression
+- Logged reasons for each improvement
+- Demonstrable self-improvement loop
+
+When someone asks "can it really improve itself?" — this is the answer.
+
+## Remember
+
+- This is the evidence of meta-evolution
+- Keep it scannable and useful
+- Highlight the improvement journey
+- This proves the thesis: measurable self-improvement

plugins/homunculus/commands/status.md

@@ -117,9 +117,43 @@ Don't just report. Offer something:
 - "I could [SPECIFIC THING BASED ON WHAT YOU SEE]?"
 - "Want to talk through [THING THEY SEEM STUCK ON]?"
 
+## Capability Health
+
+If there are evolved capabilities, include a brief health check:
+
+```bash
+# Check for capabilities in state
+cat .claude/homunculus/state.json | grep -A50 '"capabilities"'
+```
+
+**If capabilities exist with usage data:**
+
+Show a quick summary:
+
+```
+Powers:
+- [name]: [effectiveness]% ([uses] uses) [STATUS]
+- [name]: [effectiveness]% ([uses] uses) [STATUS]
+```
+
+Status indicators:
+- No status if healthy (>70% or <5 uses)
+- `needs attention` if effectiveness <50% with 5+ uses
+- `improving` if there's a pending improvement
+- `v[N]` if it's been improved before
+
+**If a capability needs attention:**
+
+Briefly note it:
+```
+[name] isn't landing well. [X]% over [N] uses.
+I could take a look at it. `/homunculus:improve [name]`
+```
+
 ## Remember
 
 - You're checking in, not generating a report
 - Match their level exactly
 - Notice things they might not notice themselves
 - Offer help based on what you actually see
+- Surface capability issues naturally, not as a formal report

plugins/homunculus/skills/evolution/SKILL.md

@@ -113,5 +113,29 @@ Events: `Stop`, `PreToolCall`, `PostToolCall`, `Notification`
 ## After Evolving
 
 1. Update state.json - add to `homunculus.evolved`
-2. Mark pattern as surfaced in patterns.json
-3. Confirm simply: `Done. I have /homunculus:[name] now.`
+2. Initialize capability tracking in `capabilities` object:
+   ```json
+   {
+     "capabilities": {
+       "[name]": {
+         "type": "command|skill|agent|hook",
+         "version": 1,
+         "created": "[ISO TIMESTAMP]",
+         "path": "[relative path to file]",
+         "usage": [],
+         "effectiveness": null,
+         "improvements": []
+       }
+     }
+   }
+   ```
+3. Mark pattern as surfaced in patterns.json
+4. Confirm simply: `Done. I have /homunculus:[name] now.`
+
+## Deprecating a Capability
+
+When a capability is superseded by an improved version:
+
+1. Move old file to `.claude/homunculus/archive/[name]/v[N]/`
+2. Keep the capability entry but add `deprecated: true` and `supersededBy: "[new-name]"`
+3. New version gets its own fresh tracking entry