| v1 | v2 | |----|-----| | Skills try to observe (unreliable) | Hooks observe (100%) | | Analysis in main context | Analysis in background agent (Haiku) | | Evolves big chunks (commands/skills) | Evolves instincts first, clusters into bigger things | | No sharing | Export/import instincts |

The Instinct Model

An instinct is a small learned behavior:

---
trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
---

# Prefer Functional Style

## Action
Use functional patterns over classes.

## Evidence
Observed 5 instances of functional pattern preference.

Instincts are:

• Atomic — one trigger, one action
• Confidence-weighted — 0.3 = tentative, 0.9 = near certain
• Domain-tagged — code-style, testing, git, debugging, etc.

The Growth Path

Session Start
     ↓
Observer agent runs (background, Haiku)
     ↓
Observations → Instincts (auto-approved)
     ↓
Instincts cluster around a domain
     ↓
User runs /homunculus:evolve
     ↓
Bigger structures emerge:
  - Command (if user-invoked)
  - Skill (if auto-triggered)
  - Agent (if needs isolation/depth)

Fully automatic except evolution. You just work. It learns.

Architecture

File Structure

plugins/homunculus/
├── .claude-plugin/
│   └── plugin.json           # v2.0.0
├── hooks/
│   └── hooks.json            # Observation capture
├── scripts/
│   ├── observe.sh            # Captures prompts and tool use
│   ├── on_stop.sh            # Updates session count
│   └── test-homunculus.sh    # Test suite
├── agents/
│   └── observer.md           ...