PaperclipOrg
Claude Agent Skill · by Affaan M

Continuous Learning V2

Continuous-learning-v2 is an instinct-based learning system that automatically observes Claude Code sessions through hooks, extracts atomic learned behaviors wi

Install
Terminal · npx
$npx skills add https://github.com/affaan-m/everything-claude-code --skill continuous-learning-v2
Works with Paperclip

How Continuous Learning V2 fits into a Paperclip company.

Continuous Learning V2 drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md365 lines
Expand
---name: continuous-learning-v2description: Instinct-based learning system that observes sessions via hooks, creates atomic instincts with confidence scoring, and evolves them into skills/commands/agents. v2.1 adds project-scoped instincts to prevent cross-project contamination.origin: ECCversion: 2.1.0--- # Continuous Learning v2.1 - Instinct-Based Architecture An advanced learning system that turns your Claude Code sessions into reusable knowledge through atomic "instincts" - small learned behaviors with confidence scoring. **v2.1** adds **project-scoped instincts** — React patterns stay in your React project, Python conventions stay in your Python project, and universal patterns (like "always validate input") are shared globally. ## When to Activate - Setting up automatic learning from Claude Code sessions- Configuring instinct-based behavior extraction via hooks- Tuning confidence thresholds for learned behaviors- Reviewing, exporting, or importing instinct libraries- Evolving instincts into full skills, commands, or agents- Managing project-scoped vs global instincts- Promoting instincts from project to global scope ## What's New in v2.1 | Feature | v2.0 | v2.1 ||---------|------|------|| Storage | Global (~/.claude/homunculus/) | Project-scoped (projects/<hash>/) || Scope | All instincts apply everywhere | Project-scoped + global || Detection | None | git remote URL / repo path || Promotion | N/A | Project → global when seen in 2+ projects || Commands | 4 (status/evolve/export/import) | 6 (+promote/projects) || Cross-project | Contamination risk | Isolated by default | ## What's New in v2 (vs v1) | Feature | v1 | v2 ||---------|----|----|| Observation | Stop hook (session end) | PreToolUse/PostToolUse (100% reliable) || Analysis | Main context | Background agent (Haiku) || Granularity | Full skills | Atomic "instincts" || Confidence | None | 0.3-0.9 weighted || Evolution | Direct to skill | Instincts -> cluster -> skill/command/agent || Sharing | None | Export/import instincts | ## The Instinct Model An instinct is a small learned behavior: ```yaml---id: prefer-functional-styletrigger: "when writing new functions"confidence: 0.7domain: "code-style"source: "session-observation"scope: projectproject_id: "a1b2c3d4e5f6"project_name: "my-react-app"--- # Prefer Functional Style ## ActionUse functional patterns over classes when appropriate. ## Evidence- Observed 5 instances of functional pattern preference- User corrected class-based approach to functional on 2025-01-15``` **Properties:**- **Atomic** -- one trigger, one action- **Confidence-weighted** -- 0.3 = tentative, 0.9 = near certain- **Domain-tagged** -- code-style, testing, git, debugging, workflow, etc.- **Evidence-backed** -- tracks what observations created it- **Scope-aware** -- `project` (default) or `global` ## How It Works ```Session Activity (in a git repo)      |      | Hooks capture prompts + tool use (100% reliable)      | + detect project context (git remote / repo path)      v+---------------------------------------------+|  projects/<project-hash>/observations.jsonl  ||   (prompts, tool calls, outcomes, project)   |+---------------------------------------------+      |      | Observer agent reads (background, Haiku)      v+---------------------------------------------+|          PATTERN DETECTION                   ||   * User corrections -> instinct             ||   * Error resolutions -> instinct            ||   * Repeated workflows -> instinct           ||   * Scope decision: project or global?       |+---------------------------------------------+      |      | Creates/updates      v+---------------------------------------------+|  projects/<project-hash>/instincts/personal/ ||   * prefer-functional.yaml (0.7) [project]   ||   * use-react-hooks.yaml (0.9) [project]     |+---------------------------------------------+|  instincts/personal/  (GLOBAL)               ||   * always-validate-input.yaml (0.85) [global]||   * grep-before-edit.yaml (0.6) [global]     |+---------------------------------------------+      |      | /evolve clusters + /promote      v+---------------------------------------------+|  projects/<hash>/evolved/ (project-scoped)   ||  evolved/ (global)                           ||   * commands/new-feature.md                  ||   * skills/testing-workflow.md               ||   * agents/refactor-specialist.md            |+---------------------------------------------+``` ## Project Detection The system automatically detects your current project: 1. **`CLAUDE_PROJECT_DIR` env var** (highest priority)2. **`git remote get-url origin`** -- hashed to create a portable project ID (same repo on different machines gets the same ID)3. **`git rev-parse --show-toplevel`** -- fallback using repo path (machine-specific)4. **Global fallback** -- if no project is detected, instincts go to global scope Each project gets a 12-character hash ID (e.g., `a1b2c3d4e5f6`). A registry file at `~/.claude/homunculus/projects.json` maps IDs to human-readable names. ## Quick Start ### 1. Enable Observation Hooks Add to your `~/.claude/settings.json`. **If installed as a plugin** (recommended): ```json{  "hooks": {    "PreToolUse": [{      "matcher": "*",      "hooks": [{        "type": "command",        "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh"      }]    }],    "PostToolUse": [{      "matcher": "*",      "hooks": [{        "type": "command",        "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh"      }]    }]  }}``` **If installed manually** to `~/.claude/skills`: ```json{  "hooks": {    "PreToolUse": [{      "matcher": "*",      "hooks": [{        "type": "command",        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"      }]    }],    "PostToolUse": [{      "matcher": "*",      "hooks": [{        "type": "command",        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"      }]    }]  }}``` ### 2. Initialize Directory Structure The system creates directories automatically on first use, but you can also create them manually: ```bash# Global directoriesmkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects} # Project directories are auto-created when the hook first runs in a git repo``` ### 3. Use the Instinct Commands ```bash/instinct-status     # Show learned instincts (project + global)/evolve              # Cluster related instincts into skills/commands/instinct-export     # Export instincts to file/instinct-import     # Import instincts from others/promote             # Promote project instincts to global scope/projects            # List all known projects and their instinct counts``` ## Commands | Command | Description ||---------|-------------|| `/instinct-status` | Show all instincts (project-scoped + global) with confidence || `/evolve` | Cluster related instincts into skills/commands, suggest promotions || `/instinct-export` | Export instincts (filterable by scope/domain) || `/instinct-import <file>` | Import instincts with scope control || `/promote [id]` | Promote project instincts to global scope || `/projects` | List all known projects and their instinct counts | ## Configuration Edit `config.json` to control the background observer: ```json{  "version": "2.1",  "observer": {    "enabled": false,    "run_interval_minutes": 5,    "min_observations_to_analyze": 20  }}``` | Key | Default | Description ||-----|---------|-------------|| `observer.enabled` | `false` | Enable the background observer agent || `observer.run_interval_minutes` | `5` | How often the observer analyzes observations || `observer.min_observations_to_analyze` | `20` | Minimum observations before analysis runs | Other behavior (observation capture, instinct thresholds, project scoping, promotion criteria) is configured via code defaults in `instinct-cli.py` and `observe.sh`. ## File Structure ```~/.claude/homunculus/+-- identity.json           # Your profile, technical level+-- projects.json           # Registry: project hash -> name/path/remote+-- observations.jsonl      # Global observations (fallback)+-- instincts/|   +-- personal/           # Global auto-learned instincts|   +-- inherited/          # Global imported instincts+-- evolved/|   +-- agents/             # Global generated agents|   +-- skills/             # Global generated skills|   +-- commands/           # Global generated commands+-- projects/    +-- a1b2c3d4e5f6/       # Project hash (from git remote URL)    |   +-- project.json    # Per-project metadata mirror (id/name/root/remote)    |   +-- observations.jsonl    |   +-- observations.archive/    |   +-- instincts/    |   |   +-- personal/   # Project-specific auto-learned    |   |   +-- inherited/  # Project-specific imported    |   +-- evolved/    |       +-- skills/    |       +-- commands/    |       +-- agents/    +-- f6e5d4c3b2a1/       # Another project        +-- ...``` ## Scope Decision Guide | Pattern Type | Scope | Examples ||-------------|-------|---------|| Language/framework conventions | **project** | "Use React hooks", "Follow Django REST patterns" || File structure preferences | **project** | "Tests in `__tests__`/", "Components in src/components/" || Code style | **project** | "Use functional style", "Prefer dataclasses" || Error handling strategies | **project** | "Use Result type for errors" || Security practices | **global** | "Validate user input", "Sanitize SQL" || General best practices | **global** | "Write tests first", "Always handle errors" || Tool workflow preferences | **global** | "Grep before Edit", "Read before Write" || Git practices | **global** | "Conventional commits", "Small focused commits" | ## Instinct Promotion (Project -> Global) When the same instinct appears in multiple projects with high confidence, it's a candidate for promotion to global scope. **Auto-promotion criteria:**- Same instinct ID in 2+ projects- Average confidence >= 0.8 **How to promote:** ```bash# Promote a specific instinctpython3 instinct-cli.py promote prefer-explicit-errors # Auto-promote all qualifying instinctspython3 instinct-cli.py promote # Preview without changespython3 instinct-cli.py promote --dry-run``` The `/evolve` command also suggests promotion candidates. ## Confidence Scoring Confidence evolves over time: | Score | Meaning | Behavior ||-------|---------|----------|| 0.3 | Tentative | Suggested but not enforced || 0.5 | Moderate | Applied when relevant || 0.7 | Strong | Auto-approved for application || 0.9 | Near-certain | Core behavior | **Confidence increases** when:- Pattern is repeatedly observed- User doesn't correct the suggested behavior- Similar instincts from other sources agree **Confidence decreases** when:- User explicitly corrects the behavior- Pattern isn't observed for extended periods- Contradicting evidence appears ## Why Hooks vs Skills for Observation? > "v1 relied on skills to observe. Skills are probabilistic -- they fire ~50-80% of the time based on Claude's judgment." Hooks fire **100% of the time**, deterministically. This means:- Every tool call is observed- No patterns are missed- Learning is comprehensive ## Backward Compatibility v2.1 is fully compatible with v2.0 and v1:- Existing global instincts in `~/.claude/homunculus/instincts/` still work as global instincts- Existing `~/.claude/skills/learned/` skills from v1 still work- Stop hook still runs (but now also feeds into v2)- Gradual migration: run both in parallel ## Privacy - Observations stay **local** on your machine- Project-scoped instincts are isolated per project- Only **instincts** (patterns) can be exported — not raw observations- No actual code or conversation content is shared- You control what gets exported and promoted ## Related - [ECC-Tools GitHub App](https://github.com/apps/ecc-tools) - Generate instincts from repo history- Homunculus - Community project that inspired the v2 instinct-based architecture (atomic observations, confidence scoring, instinct evolution pipeline)- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) - Continuous learning section --- *Instinct-based learning: teaching Claude your patterns, one project at a time.*