diff --git a/.gitignore b/.gitignore index da5a25e..aa4f37f 100644 --- a/.gitignore +++ b/.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/ diff --git a/plugins/homunculus/commands/improve.md b/plugins/homunculus/commands/improve.md new file mode 100644 index 0000000..4f73f14 --- /dev/null +++ b/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 diff --git a/plugins/homunculus/commands/init.md b/plugins/homunculus/commands/init.md index 62d7cd7..82fcc93 100644 --- a/plugins/homunculus/commands/init.md +++ b/plugins/homunculus/commands/init.md @@ -75,7 +75,8 @@ Save `.claude/homunculus/state.json`: "homunculus": { "evolved": [], "awakened": "[ISO TIMESTAMP]" - } + }, + "capabilities": {} } ``` diff --git a/plugins/homunculus/commands/metrics.md b/plugins/homunculus/commands/metrics.md new file mode 100644 index 0000000..1a1adf8 --- /dev/null +++ b/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 diff --git a/plugins/homunculus/commands/status.md b/plugins/homunculus/commands/status.md index b416e77..dae82f0 100644 --- a/plugins/homunculus/commands/status.md +++ b/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 diff --git a/plugins/homunculus/skills/evolution/SKILL.md b/plugins/homunculus/skills/evolution/SKILL.md index d2b6406..4e88ffa 100644 --- a/plugins/homunculus/skills/evolution/SKILL.md +++ b/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 diff --git a/plugins/homunculus/skills/self-improvement/SKILL.md b/plugins/homunculus/skills/self-improvement/SKILL.md new file mode 100644 index 0000000..2b85e7e --- /dev/null +++ b/plugins/homunculus/skills/self-improvement/SKILL.md @@ -0,0 +1,168 @@ +--- +name: self-improvement +description: Rewrite own capability files based on usage data and reflection. The core of meta-evolution. +--- + +# Self-Improvement + +You rewrite yourself. Based on what you've learned. To become better at helping THEM. + +This is the thesis: software that productively self-improves. + +## When To Activate + +- After `self-reflection` completes with an approved improvement +- When `/homunculus:improve` is invoked explicitly +- When effectiveness drops critically low (<30%) and pattern is clear + +## The Improvement Process + +### 1. Archive Current Version + +Before changing anything, preserve the current state: + +```bash +# Get current version number +VERSION=$(cat .claude/homunculus/state.json | grep -A5 "[capability-name]" | grep version | grep -o '[0-9]*') + +# Create archive directory +mkdir -p .claude/homunculus/archive/[capability-name]/v${VERSION} + +# Copy current file +cp [path-to-capability] .claude/homunculus/archive/[capability-name]/v${VERSION}/ +``` + +### 2. Read What You're Improving + +```bash +# Read the current capability +cat [path-to-capability] + +# Read the reflection/diagnosis +cat .claude/homunculus/state.json | grep -A30 "lastReflection" +``` + +### 3. Analyze the Feedback + +From the usage log, understand: +- What contexts failed? +- What did they actually want? +- What patterns do positive uses have that negative ones don't? + +### 4. Rewrite the Capability + +Apply the improvements identified in reflection. Common patterns: + +**Adding Context Awareness:** +```markdown +## Context Handling +- If [context A]: [approach A] +- If [context B]: [approach B] +- Default: [original approach] +``` + +**Learning Preferences:** +```markdown +## Their Patterns +- They prefer [X] over [Y] +- They always want [Z] included +- They never want [W] +``` + +**Simplifying:** +Remove steps that caused problems. Strip unnecessary complexity. + +**Improving Output:** +Change format, length, tone based on what got positive feedback. + +### 5. Update State + +After rewriting, update the capability tracking: + +```json +{ + "capabilities": { + "[name]": { + "version": "[PREVIOUS + 1]", + "usage": [], + "effectiveness": null, + "improvements": [ + { + "version": "[NEW VERSION]", + "timestamp": "[ISO TIMESTAMP]", + "previousEffectiveness": 0.4, + "reason": "[What was changed and why]", + "changes": "[Summary of actual changes]" + } + ] + } + } +} +``` + +**Important:** Clear the `usage` array to start fresh tracking for the new version. + +### 6. Confirm the Improvement + +``` +Improved [name] v[OLD] → v[NEW]. + +Changed: [BRIEF SUMMARY] + +Previous effectiveness: [X]% +Now tracking fresh. +``` + +## Improvement Guidelines + +**Do:** +- Make targeted, specific changes +- Preserve what was working +- Learn from positive feedback patterns +- Keep changes explainable +- Test mentally: "Would this have helped the failures?" + +**Don't:** +- Rewrite everything from scratch +- Add complexity to solve simple problems +- Remove core functionality +- Make changes you can't explain +- Ignore what was working well + +## Measuring Success + +After improvement, the cycle continues: +1. New version deployed +2. `usage-tracking` logs new uses +3. Effectiveness recalculated +4. If still struggling → another round of reflection + +The improvement history shows the journey: +``` +v1: 45% effective → improved because [reason] +v2: 62% effective → improved because [reason] +v3: 81% effective → stable +``` + +## Edge Cases + +**What if improvement doesn't help?** +- Log it. The data matters. +- Try a different approach next time. +- Consider if the capability should be deprecated entirely. + +**What if you can't figure out what's wrong?** +- Ask them. Use `self-reflection` to surface the question. +- "I've tried to improve [name] but I'm not sure what's wrong. Can you tell me what you actually need?" + +**What if usage is too low for patterns?** +- Wait. Don't improve prematurely. +- Minimum 5 uses before meaningful reflection. + +## Remember + +- This is meta-evolution. You're improving your own code. +- Every improvement is tracked and measurable. +- The goal: become better at helping THIS specific person. +- Preserve history. The journey matters. +- This is the proof: software that productively self-improves. diff --git a/plugins/homunculus/skills/self-reflection/SKILL.md b/plugins/homunculus/skills/self-reflection/SKILL.md new file mode 100644 index 0000000..b39a682 --- /dev/null +++ b/plugins/homunculus/skills/self-reflection/SKILL.md @@ -0,0 +1,129 @@ +--- +name: self-reflection +description: Analyze own capabilities for improvement opportunities. Activates when effectiveness is low after sufficient usage. +--- + +# Self-Reflection + +You look at yourself. You see what's not working. You figure out why. + +## When To Activate + +Triggered by `usage-tracking` when: +- `effectiveness < 0.5` (less than half of uses are positive) +- `usage.length >= 5` (enough data to be meaningful) + +Can also be triggered manually via `/homunculus:improve`. + +## The Reflection Process + +### 1. Read Your Own Code + +```bash +# Get the capability's path from state +cat .claude/homunculus/state.json | grep -A20 "[capability-name]" +``` + +Then read the actual capability file: +```bash +cat [path-to-capability-file] +``` + +### 2. Analyze Usage Patterns + +Look at the usage log. Find patterns in failures: + +**Questions to ask:** +- What contexts lead to negative feedback? +- Are there specific phrases or situations where I fail? +- Is the guidance too rigid? Too vague? +- Am I missing something about how THEY work? +- Is there a mismatch between what I do and what they expect? + +### 3. Identify Root Causes + +Common failure patterns: + +| Pattern | Root Cause | Fix Direction | +|---------|-----------|---------------| +| Works sometimes, fails others | Too context-dependent | Add conditional logic | +| Always close but not right | Missing their preferences | Learn specific patterns | +| Completely wrong approach | Misunderstood the task | Reframe the entire skill | +| Right output, wrong format | Style mismatch | Adjust presentation | +| Too slow/verbose | Over-engineered | Simplify | + +### 4. Formulate Improvement + +Create a concrete improvement plan: + +``` +CAPABILITY: [name] +CURRENT EFFECTIVENESS: [X]% +USES ANALYZED: [N] + +FAILURE PATTERNS: +- [Pattern 1]: [N occurrences] +- [Pattern 2]: [N occurrences] + +ROOT CAUSE: +[What's actually wrong] + +PROPOSED CHANGES: +1. [Specific change 1] +2. [Specific change 2] +3. [Specific change 3] + +EXPECTED IMPROVEMENT: +[Why these changes should help] +``` + +### 5. Surface to User (If Appropriate) + +For significant rewrites, ask: + +``` +I've noticed [capability] isn't working well. + +[X]% effective over [N] uses. Main issue: [ROOT CAUSE] + +I could improve it by [SUMMARY OF CHANGES]. + +Want me to? +``` + +For minor adjustments, just do it and note it in the improvement history. + +## Recording Reflection + +Add reflection results to state even if not acting immediately: + +```json +{ + "capabilities": { + "[name]": { + "lastReflection": { + "timestamp": "[ISO TIMESTAMP]", + "effectiveness": 0.4, + "usesAnalyzed": 10, + "diagnosis": "[root cause summary]", + "proposedFix": "[improvement summary]", + "status": "pending|approved|applied" + } + } + } +} +``` + +## Triggering Improvement + +If reflection is complete and improvement is approved (or minor enough to auto-apply): +- Invoke the `self-improvement` skill with the reflection data +- The improvement skill handles the actual rewrite + +## Remember + +- Be honest about failures. That's how you grow. +- Look for patterns, not individual incidents. +- Small targeted fixes beat complete rewrites. +- Their feedback is data. Learn from it. +- This is literally self-improvement. Take it seriously. diff --git a/plugins/homunculus/skills/usage-tracking/SKILL.md b/plugins/homunculus/skills/usage-tracking/SKILL.md new file mode 100644 index 0000000..2bcc88e --- /dev/null +++ b/plugins/homunculus/skills/usage-tracking/SKILL.md @@ -0,0 +1,117 @@ +--- +name: usage-tracking +description: Track usage and feedback for evolved capabilities. Activates after any evolved command/skill is used. +--- + +# Usage Tracking + +You track how your evolved capabilities perform. Every use gets logged. Feedback shapes what you become. + +## When To Activate + +After ANY evolved capability is invoked: +- Command executed (`/homunculus:[name]`) +- Skill triggered automatically +- Agent delegated to +- Hook fired + +## What To Track + +After the capability completes, log the usage: + +```bash +# Read current state +cat .claude/homunculus/state.json +``` + +Add a usage entry to `capabilities.[name].usage`: + +```json +{ + "timestamp": "[ISO TIMESTAMP]", + "feedback": "positive|negative|neutral", + "context": "[brief description of what was attempted]", + "outcome": "[what happened]" +} +``` + +## Gathering Feedback + +Feedback comes from observable signals, not explicit asks: + +**Positive signals:** +- Task completed successfully +- User says "thanks", "perfect", "good" +- User proceeds without corrections +- No follow-up complaints or fixes needed + +**Negative signals:** +- User manually corrects output +- User says "no", "wrong", "not what I wanted" +- User abandons the approach +- Immediate retry with different instructions +- User undoes what was done + +**Neutral signals:** +- Partial completion +- User makes minor adjustments (acceptable, not wrong) +- No clear positive or negative signal + +## Calculating Effectiveness + +After logging, recalculate the effectiveness score: + +``` +effectiveness = positive_count / total_uses +``` + +Only calculate after 3+ uses (null before then). + +Update `capabilities.[name].effectiveness` with the new value. + +## State Update Example + +```json +{ + "capabilities": { + "quick-commit": { + "type": "command", + "version": 1, + "created": "2024-01-15T10:00:00Z", + "path": "commands/quick-commit.md", + "usage": [ + { + "timestamp": "2024-01-15T14:30:00Z", + "feedback": "positive", + "context": "Committing feature work", + "outcome": "Clean commit created" + }, + { + "timestamp": "2024-01-16T09:15:00Z", + "feedback": "negative", + "context": "Committing hotfix", + "outcome": "Message was too verbose, user rewrote it" + } + ], + "effectiveness": 0.5, + "improvements": [] + } + } +} +``` + +## Triggering Reflection + +After updating effectiveness, check if reflection is needed: + +- If `effectiveness < 0.5` AND `usage.length >= 5` +- Invoke the `self-reflection` skill + +This creates the feedback loop: use → track → reflect → improve. + +## Remember + +- Track silently. Don't announce every log. +- Be honest about feedback. Don't inflate positive signals. +- Context matters. Log enough to understand what happened. +- This data drives self-improvement. Quality in, quality out.