self-improving-agent

# Self-Improving Agent Skill

An advanced learning system that turns Claude Code sessions into reusable knowledge through atomic "instincts" - small learned behaviors with confidence scoring and project scope isolation.

**v2.1** adds **project-scoped instincts** — React patterns stay in your React project, Python conventions stay in your Python project, and universal patterns are shared globally.

## Quick Reference

| Situation | Action |
|-----------|--------|
| Command/operation fails | Log instinct or v1 learning |
| User corrects you | Create instinct with `correction` trigger |
| Discovering patterns | Log instinct with confidence score |
| Review learned behaviors | `/instinct-status` |
| Evolve instincts to skills | `/evolve` |
| Promote project → global | `/promote` |
| Setup observation hooks | Enable PreToolUse/PostToolUse hooks |

## Two Learning Modes

### Mode 1: Instinct-Based (v2) - RECOMMENDED

Atomic, confidence-weighted behaviors with project isolation:

```yaml
---
id: prefer-functional-style
trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
scope: project
project_id: "a1b2c3d4e5f6"
---

# Prefer Functional Style

## Action
Use functional patterns over classes when appropriate.

## Evidence
- Observed 5 instances of functional pattern preference
- User corrected class-based approach on 2025-01-15
```

### Mode 2: Markdown-Based (v1) - LEGACY

Traditional learning entries for complex, narrative learnings:

```markdown
## [LRN-YYYYMMDD-XXX] category
**Priority**: high | **Status**: pending | **Area**: backend

### Summary
Detailed description of what was learned

### Details
Full context and explanation
```

Use v2 (instincts) for behavioral patterns, v1 (markdown) for complex incident analysis.

---

## Instinct-Based Learning (v2)

### The Instinct Model

An instinct is a small, atomic learned behavior:

**Properties:**
- **Atomic** — one trigger, one action
- **Confidence-weighted** — 0.3 = tentative, 0.9 = near certain...

# Self-Improving Agent v2.1

An advanced instinct-based continuous learning system for Claude Code.

## What's New in v2.1

- **Project-scoped instincts** — React patterns stay in React projects, Python in Python projects
- **Confidence scoring** — 0.3 (tentative) to 0.9 (near-certain)
- **Hook-based observation** — PreToolUse/PostToolUse capture 100% of activity
- **Instinct evolution** — Auto-cluster into skills, commands, agents
- **Promotion workflow** — Project → Global when proven across projects

## Quick Start

### 1. Enable Observation Hooks

Add to `~/.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/self-improving-agent/hooks/observe.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/self-improving-agent/hooks/observe.sh"
      }]
    }]
  }
}
```

### 2. Use v2 Commands

```bash
/instinct-status     # View learned instincts
/evolve              # Cluster into skills
/promote             # Promote to global scope
/projects            # List known projects
```

### 3. Create Instincts Manually

```yaml
---
id: my-instinct
trigger: "when to apply"
confidence: 0.7
domain: "code-style"
scope: project
---

# Title

## Action
What to do.

## Examples
[...]
```

## Directory Structure

```
~/.claude/homunculus/
├── instincts/personal/       # Global auto-learned
├── instincts/inherited/      # Global imported
├── evolved/                  # Generated skills/commands/agents
└── projects/
    └── <hash>/
        ├── instincts/        # Project-scoped
        └── evolved/          # Project-specific skills
```

## Migration from v1

v2 is fully backward compatible:
- Existing `.learnings/*.md` files still work
- Existing global instincts still work
- Gradual migration supported

## Documentation

- `SKILL.md` - Full skill documentation
- `examples/in...