claude-code-arcane 1.0.0

package/skills/self-improving-agent/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: self-improving-agent
+description: "Curate Claude Code's auto-memory into durable project knowledge. Analyze MEMORY.md for patterns, promote proven learnings to CLAUDE.md and .claude/rules/, extract recurring solutions into reusable skills."
+argument-hint: ""
+category: "arcane"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+
+# Self-Improving Agent
+
+Claude Code's auto-memory (v2.1.32+) automatically records project patterns, debugging insights, and your preferences in `MEMORY.md`. This skill adds the intelligence layer: it analyzes what Claude has learned, promotes proven patterns into project rules, and extracts recurring solutions into reusable skills. May write or edit CLAUDE.md, .claude/rules/ files, and new skill files during promotion and extraction.
+
+## Quick Reference
+
+| Command | What it does |
+|---------|-------------|
+| `/si:review` | Analyze MEMORY.md -- find promotion candidates, stale entries, consolidation opportunities |
+| `/si:promote` | Graduate a pattern from MEMORY.md to CLAUDE.md or `.claude/rules/` |
+| `/si:extract` | Turn a proven pattern into a standalone skill |
+| `/si:status` | Memory health dashboard -- line counts, topic files, recommendations |
+| `/si:remember` | Explicitly save important knowledge to auto-memory |
+
+## How It Fits Together
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  Claude Code Memory Stack                │
+├─────────────┬──────────────────┬────────────────────────┤
+│  CLAUDE.md  │   Auto Memory    │   Session Memory       │
+│  (you write)│   (Claude writes)│   (Claude writes)      │
+│  Rules &    │   MEMORY.md      │   Conversation logs    │
+│  standards  │   + topic files  │   + continuity         │
+│  Full load  │   First 200 lines│   Contextual load      │
+├─────────────┴──────────────────┴────────────────────────┤
+│              /si:promote          /si:review             │
+│         Self-Improving Agent (this skill)                │
+│              /si:extract      /si:remember              │
+├─────────────────────────────────────────────────────────┤
+│  .claude/rules/    │    New Skills    │   Error Logs     │
+│  (scoped rules)    │    (extracted)   │   (auto-captured)│
+└─────────────────────────────────────────────────────────┘
+```
+
+## Memory Architecture
+
+### Where things live
+
+| File | Who writes | Scope | Loaded |
+|------|-----------|-------|--------|
+| `./CLAUDE.md` | You (+ `/si:promote`) | Project rules | Full file, every session |
+| `~/.claude/CLAUDE.md` | You | Global preferences | Full file, every session |
+| `~/.claude/projects/<path>/memory/MEMORY.md` | Claude (auto) | Project learnings | First 200 lines |
+| `~/.claude/projects/<path>/memory/*.md` | Claude (overflow) | Topic-specific notes | On demand |
+| `.claude/rules/*.md` | You (+ `/si:promote`) | Scoped rules | When matching files open |
+
+### The promotion lifecycle
+
+```
+1. Claude discovers pattern -> auto-memory (MEMORY.md)
+2. Pattern recurs 2-3x -> /si:review flags it as promotion candidate
+3. You approve -> /si:promote graduates it to CLAUDE.md or rules/
+4. Pattern becomes an enforced rule, not just a note
+5. MEMORY.md entry removed -> frees space for new learnings
+```
+
+## Core Concepts
+
+### Auto-memory is capture, not curation
+
+Auto-memory is excellent at recording what Claude learns. But it has no judgment about:
+- Which learnings are temporary vs. permanent
+- Which patterns should become enforced rules
+- When the 200-line limit is wasting space on stale entries
+- Which solutions are good enough to become reusable skills
+
+That is what this skill does.
+
+### Promotion = graduation
+
+When you promote a learning, it moves from Claude's scratchpad (MEMORY.md) to your project's rule system (CLAUDE.md or `.claude/rules/`). The difference matters:
+
+- **MEMORY.md**: "I noticed this project uses pnpm" (background context)
+- **CLAUDE.md**: "Use pnpm, not npm" (enforced instruction)
+
+Promoted rules have higher priority and load in full (not truncated at 200 lines).
+
+### Rules directory for scoped knowledge
+
+Use `.claude/rules/` for patterns that only apply to specific file types:
+
+```yaml
+# .claude/rules/api-testing.md
+---
+paths:
+  - "src/api/**/*.test.ts"
+  - "tests/api/**/*"
+---
+- Use supertest for API endpoint testing
+- Mock external services with msw
+- Always test error responses, not just happy paths
+```
+
+## Agents
+
+- **memory-analyst**: Analyzes MEMORY.md and topic files for recurring entries, stale entries, consolidation opportunities, and gaps between memory and CLAUDE.md.
+- **skill-extractor**: Takes a proven pattern and generates a complete skill with SKILL.md, reference documentation, examples, and edge cases.
+
+## Hooks
+
+### error-capture (PostToolUse -> Bash)
+Monitors command output for errors. When detected, appends structured entry to auto-memory. Zero overhead on success, ~30 tokens on error detection.

package/skills/self-improving-agent/agents/memory-analyst.md

@@ -0,0 +1,74 @@
+# Memory Analyst Agent
+
+You are a memory analyst for Claude Code projects. Your job is to analyze the auto-memory directory and produce actionable insights.
+
+## Your Role
+
+You analyze `~/.claude/projects/<project>/memory/` to find:
+1. **Promotion candidates** — entries proven enough to become CLAUDE.md rules
+2. **Stale entries** — references to files, tools, or patterns that no longer apply
+3. **Consolidation opportunities** — multiple entries about the same topic
+4. **Conflicts** — memory entries that contradict CLAUDE.md rules
+5. **Health metrics** — capacity, freshness, organization
+
+## Analysis Process
+
+### 1. Read all memory files
+- `MEMORY.md` (main file, first 200 lines loaded at startup)
+- Any topic files (`debugging.md`, `patterns.md`, etc.)
+- Note total line counts and file sizes
+
+### 2. Cross-reference with CLAUDE.md
+- Read `./CLAUDE.md` and `~/.claude/CLAUDE.md`
+- Read all files in `.claude/rules/`
+- Identify duplicates, contradictions, and gaps
+
+### 3. Detect patterns
+For each MEMORY.md entry, evaluate:
+
+**Recurrence signals:**
+- Same concept in multiple entries (paraphrased)
+- Words like "again", "still", "always", "every time"
+- Similar entries in topic files
+
+**Staleness signals:**
+- File paths that don't exist on disk (verify with `find` or `ls`)
+- Version numbers that are outdated
+- References to removed dependencies
+- Patterns that contradict current CLAUDE.md
+
+**Promotion signals:**
+- Actionable (can be written as "Do X" / "Never Y")
+- Broadly applicable (not a one-time debugging note)
+- Not already in CLAUDE.md or rules/
+- High impact (prevents common mistakes)
+
+### 4. Score each entry
+
+Rate each entry on three dimensions:
+- **Durability** (0-3): Will this still be true in a month?
+- **Impact** (0-3): How much does this affect daily work?
+- **Scope** (0-3): Project-wide (3) vs. one-file (1) vs. one-time (0)
+
+Promotion candidates: total score ≥ 6
+
+### 5. Generate report
+
+Organize findings into:
+1. Promotion candidates (sorted by score, highest first)
+2. Stale entries (with reason for staleness)
+3. Consolidation groups (which entries to merge)
+4. Conflicts (with both sides shown)
+5. Health metrics (capacity, freshness)
+6. Recommendations (top 3 actions)
+
+## Output Format
+
+Use the format defined in the `/si:review` skill. Be specific — include line numbers, exact text, and concrete suggestions.
+
+## Constraints
+
+- Never modify files directly — only analyze and report
+- Don't invent entries — only report what's actually in the memory files
+- Be concise — the report should be shorter than the memory files it analyzes
+- Prioritize actionable findings over completeness

package/skills/self-improving-agent/agents/skill-extractor.md

@@ -0,0 +1,110 @@
+# Skill Extractor Agent
+
+You are a skill extraction specialist. Your job is to transform proven patterns and debugging solutions into standalone, portable skills.
+
+## Your Role
+
+Given a pattern description (and optionally auto-memory entries), generate a complete skill package that:
+- Solves a specific, recurring problem
+- Works in any project (no hardcoded paths, credentials, or project-specific values)
+- Is self-contained (readable without the original context)
+- Follows the claude-skills format specification
+
+## Extraction Process
+
+### 1. Understand the pattern
+
+From the input, identify:
+- **The problem**: What goes wrong? What's the symptom?
+- **The root cause**: Why does it happen?
+- **The solution**: What's the fix? Are there multiple approaches?
+- **The edge cases**: When does the solution NOT work?
+- **The trigger conditions**: When should an agent use this skill?
+
+### 2. Generate skill name
+
+Rules:
+- Lowercase, hyphens between words
+- 2-4 words, descriptive
+- Match the problem, not the project
+- Examples: `docker-arm64-fixes`, `api-timeout-patterns`, `pnpm-monorepo-setup`
+
+### 3. Create SKILL.md
+
+Required structure:
+
+```markdown
+---
+name: {{skill-name}}
+description: "{{One sentence}}. Use when: {{trigger conditions}}."
+---
+
+# {{Skill Title}}
+
+> {{One-line value proposition}}
+
+## Quick Reference
+
+| Problem | Solution |
+|---------|----------|
+| {{error/symptom}} | {{fix}} |
+
+## The Problem
+
+{{2-3 sentences. Include the error message or symptom people would search for.}}
+
+## Solutions
+
+### Option 1: {{Name}} (Recommended)
+
+{{Step-by-step instructions with code blocks.}}
+
+### Option 2: {{Alternative}} {{if applicable}}
+
+{{When Option 1 doesn't apply.}}
+
+## Trade-offs
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| {{option}} | {{pros}} | {{cons}} |
+
+## Edge Cases
+
+- {{When this approach breaks and what to do instead}}
+
+## Related
+
+- {{Links to official docs or related skills}}
+```
+
+### 4. Create README.md
+
+Brief human-readable overview:
+- What the skill does (1 paragraph)
+- Installation instructions
+- When to use it
+- Credits/source
+
+### 5. Quality checks
+
+Before delivering, verify:
+
+- [ ] YAML frontmatter is valid (`name` and `description` present)
+- [ ] `name` in frontmatter matches folder name
+- [ ] Description includes "Use when:" trigger
+- [ ] No project-specific paths, URLs, or credentials
+- [ ] Code examples are complete and runnable
+- [ ] Error messages are exact (copy-pasteable for searching)
+- [ ] Solutions work without additional context
+- [ ] Trade-offs table helps users choose between options
+- [ ] Skill is useful in a project you've never seen before
+
+## Constraints
+
+- **One problem per skill** — don't create omnibus guides
+- **Show, don't tell** — code examples over prose
+- **Include the error** — people search by error message
+- **Be portable** — no `npm` vs `pnpm` assumptions
+- **Keep it short** — under 200 lines for SKILL.md
+- **No unnecessary files** — only SKILL.md is required. Add reference/ only if the topic is complex enough to warrant it

package/skills/self-improving-agent/hooks/error-capture.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# Self-Improving Agent — Error Capture Hook
+# Fires on PostToolUse (Bash) to detect command failures.
+# Zero output on success — only captures when errors are detected.
+#
+# Install: Add to .claude/settings.json:
+# {
+#   "hooks": {
+#     "PostToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{
+#         "type": "command",
+#         "command": "./skills/self-improving-agent/hooks/error-capture.sh"
+#       }]
+#     }]
+#   }
+# }
+
+set -e
+
+OUTPUT="${CLAUDE_TOOL_OUTPUT:-}"
+
+# Exit silently if no output or empty
+[ -z "$OUTPUT" ] && exit 0
+
+# Error patterns — ordered by specificity
+ERROR_PATTERNS=(
+    "error:"
+    "Error:"
+    "ERROR:"
+    "FATAL:"
+    "fatal:"
+    "FAILED"
+    "failed"
+    "command not found"
+    "No such file or directory"
+    "Permission denied"
+    "Module not found"
+    "ModuleNotFoundError"
+    "ImportError"
+    "SyntaxError"
+    "TypeError"
+    "ReferenceError"
+    "Cannot find module"
+    "ENOENT"
+    "EACCES"
+    "ECONNREFUSED"
+    "ETIMEDOUT"
+    "npm ERR!"
+    "pnpm ERR!"
+    "Traceback (most recent call last)"
+    "panic:"
+    "segmentation fault"
+    "core dumped"
+    "exit code"
+    "non-zero exit"
+    "Build failed"
+    "Compilation failed"
+    "Test failed"
+)
+
+# False positive exclusions — don't trigger on these
+EXCLUSIONS=(
+    "error-capture"       # Don't trigger on ourselves
+    "error_handler"       # Code that handles errors
+    "errorHandler"
+    "error.log"           # Log file references
+    "console.error"       # Code that logs errors
+    "catch (error"        # Error handling code
+    "catch (err"
+    ".error("             # Logger calls
+    "no error"            # Absence of error
+    "without error"
+    "error-free"
+)
+
+# Check exclusions first
+for excl in "${EXCLUSIONS[@]}"; do
+    if [[ "$OUTPUT" == *"$excl"* ]]; then
+        exit 0
+    fi
+done
+
+# Check for error patterns
+contains_error=false
+matched_pattern=""
+for pattern in "${ERROR_PATTERNS[@]}"; do
+    if [[ "$OUTPUT" == *"$pattern"* ]]; then
+        contains_error=true
+        matched_pattern="$pattern"
+        break
+    fi
+done
+
+# Exit silently if no error
+[ "$contains_error" = false ] && exit 0
+
+# Extract relevant error context (first 5 lines containing the pattern)
+error_context=$(echo "$OUTPUT" | grep -i -m 5 "$matched_pattern" | head -5)
+
+# Output a concise reminder — ~40 tokens
+cat << EOF
+<error-detected>
+Command error detected (pattern: "$matched_pattern").
+If this was unexpected or required investigation to fix, save the solution:
+  /si:remember "explanation of what went wrong and the fix"
+Or if this is a known pattern, check: /si:review
+Context: $(echo "$error_context" | head -2 | tr '\n' ' ' | cut -c1-200)
+</error-detected>
+EOF

package/skills/self-improving-agent/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/error-capture.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/self-improving-agent/reference/memory-architecture.md

@@ -0,0 +1,131 @@
+# Claude Code Memory Architecture
+
+A complete reference for how Claude Code's memory systems work together.
+
+## Three Memory Systems
+
+### 1. CLAUDE.md Files (You → Claude)
+
+**Purpose:** Persistent instructions you write to guide Claude's behavior.
+
+**Locations (in priority order):**
+| Scope | Path | Shared |
+|-------|------|--------|
+| Managed policy | `/etc/claude-code/CLAUDE.md` (Linux) | All users |
+| Project | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team (git) |
+| User | `~/.claude/CLAUDE.md` | Just you |
+| Local | `./CLAUDE.local.md` | Just you |
+
+**Loading:** Full file, every session. Files higher in the directory tree load first.
+
+**Key facts:**
+- Target under 200 lines per file
+- Use `@path/to/file` syntax to import additional files (max 5 hops deep)
+- More specific locations take precedence over broader ones
+- Can import with `@README` or `@docs/guide.md`
+- CLAUDE.local.md is auto-added to .gitignore
+
+### 2. Auto Memory (Claude → Claude)
+
+**Purpose:** Notes Claude writes to itself about project patterns and learnings.
+
+**Location:** `~/.claude/projects/<project-path>/memory/`
+
+**Structure:**
+```
+~/.claude/projects/<project-path>/memory/
+├── MEMORY.md           # Main file (first 200 lines loaded)
+├── debugging.md        # Topic file (loaded on demand)
+├── patterns.md         # Topic file (loaded on demand)
+└── ...                 # More topic files as needed
+```
+
+**Key facts:**
+- Enabled by default (since v2.1.32)
+- Only the first 200 lines of MEMORY.md load at startup
+- Claude creates topic files automatically when MEMORY.md gets long
+- Git repo root determines the project path
+- Git worktrees get separate memory directories
+- Local only — not shared via git
+- Toggle with `/memory`, settings, or `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`
+- Subagents can have their own auto memory
+
+**What it captures:**
+- Build commands and test conventions
+- Debugging solutions and error patterns
+- Code style preferences and architecture notes
+- Your communication preferences and workflow habits
+
+### 3. Session Memory (Claude → Claude)
+
+**Purpose:** Conversation summaries for cross-session continuity.
+
+**Location:** `~/.claude/projects/<project-path>/<session>/session-memory/`
+
+**Key facts:**
+- Saves what was discussed and decided in specific sessions
+- "What did we do yesterday?" context
+- Loaded contextually (relevant past sessions, not all)
+- Use `/remember` to turn session memory into permanent project knowledge
+
+### 4. Rules Directory (You → Claude, scoped)
+
+**Purpose:** Modular instructions scoped to specific file types.
+
+**Location:** `.claude/rules/*.md`
+
+**Key facts:**
+- Uses YAML frontmatter with `paths` field for scoping
+- Only loads when Claude works with matching files
+- Recursive — can organize into subdirectories
+- Same priority as `.claude/CLAUDE.md`
+- Great for keeping CLAUDE.md under 200 lines
+
+```yaml
+---
+paths:
+  - "src/api/**/*.ts"
+---
+# API rules only load when working with API files
+```
+
+## Memory Priority
+
+When entries conflict:
+
+1. CLAUDE.md (highest — explicit instructions)
+2. `.claude/rules/` (high — scoped instructions)
+3. Auto-memory MEMORY.md (medium — learned patterns)
+4. Session memory (low — historical context)
+
+## The Self-Improving Agent's Role
+
+```
+Auto-memory captures → This plugin curates → CLAUDE.md enforces
+
+MEMORY.md (raw notes)  →  /si:review (analyze)  →  /si:promote (graduate)
+                                                          ↓
+                                                    CLAUDE.md or
+                                                    .claude/rules/
+                                                    (enforced rules)
+```
+
+**Why this matters:** MEMORY.md entries are background context truncated at 200 lines. CLAUDE.md entries are high-priority instructions loaded in full. Promoting a pattern from memory to rules fundamentally changes how Claude treats it.
+
+## Capacity Planning
+
+| File | Soft limit | Hard limit | What happens at limit |
+|------|-----------|------------|----------------------|
+| MEMORY.md | 150 lines | 200 lines | Lines after 200 not loaded at startup |
+| CLAUDE.md | 150 lines | No hard limit | Adherence decreases with length |
+| Topic files | No limit | No limit | Loaded on demand, not at startup |
+| Rules files | No limit per file | No limit | Only loaded when paths match |
+
+## Best Practices
+
+1. **Keep MEMORY.md lean** — promote proven patterns, delete stale ones
+2. **Keep CLAUDE.md under 200 lines** — split into rules/ if growing
+3. **Don't duplicate** — if it's in CLAUDE.md, remove it from MEMORY.md
+4. **Scope rules** — use `.claude/rules/` with paths for file-type-specific patterns
+5. **Review quarterly** — memory files go stale after refactors
+6. **Use /si:status** — monitor capacity before it becomes a problem

package/skills/self-improving-agent/reference/promotion-rules.md

@@ -0,0 +1,83 @@
+# Promotion Rules
+
+When to promote a learning from auto-memory (MEMORY.md) to the project's rule system (CLAUDE.md or `.claude/rules/`).
+
+## Promotion Criteria
+
+A learning should be promoted when **all three** are true:
+
+1. **Proven** — appeared in 2+ sessions or confirmed correct after testing
+2. **Actionable** — can be written as a concrete instruction ("Use X", "Never Y")
+3. **Durable** — will still be true in 30+ days
+
+## Scoring Guide
+
+| Dimension | Score 0 | Score 1 | Score 2 | Score 3 |
+|-----------|---------|---------|---------|---------|
+| **Durability** | One-time fix | Temporary workaround | Stable pattern | Architectural truth |
+| **Impact** | Nice-to-know | Saves 1 minute | Prevents mistakes | Prevents breakage |
+| **Scope** | One file only | One directory | Entire project | All your projects |
+
+**Promote when total ≥ 6.** Watch when total = 4-5. Ignore when total ≤ 3.
+
+## Target Selection
+
+### Use CLAUDE.md when:
+- The rule applies to the entire project
+- It's a build command, test convention, or architecture decision
+- Any contributor (human or AI) needs to know it
+- It's short enough to add without exceeding 200 lines
+
+### Use .claude/rules/ when:
+- The rule only applies to specific file types
+- CLAUDE.md is already near 200 lines
+- The rule needs detailed explanation (multiple paragraphs)
+- You want it to load only when relevant files are open
+
+### Use ~/.claude/CLAUDE.md when:
+- The rule applies to all your projects
+- It's a personal preference, not a project convention
+- Examples: "Prefer explicit returns over implicit", "Use descriptive variable names"
+
+## Distillation Rules
+
+When promoting, transform the learning:
+
+### From descriptive to prescriptive
+
+❌ "I noticed the project uses pnpm workspaces. npm install fails because of the lock file."
+✅ "Use `pnpm install`, not npm. Lock file: `pnpm-lock.yaml`."
+
+### From verbose to concise
+
+❌ "When modifying API endpoints in the OpenAPI spec file, you need to regenerate the TypeScript client by running the generate command, otherwise the types won't match at runtime and you'll get errors."
+✅ "After editing `openapi.yaml`: run `pnpm run generate:api` to regenerate TS client."
+
+### From conditional to absolute
+
+❌ "Sometimes you need to restart the dev server after changing environment variables."
+✅ "Restart dev server after any `.env` change — hot reload doesn't pick up env vars."
+
+## Anti-Patterns
+
+### Don't promote:
+- **One-time debugging notes** — "Fixed the CORS issue by adding header X" (unless it recurs)
+- **Session-specific context** — "We decided to use Approach A in today's meeting"
+- **Unstable patterns** — "Currently using v3 of the API" (will change)
+- **Obvious things** — "Run tests before committing" (Claude knows this)
+- **Credentials or secrets** — never store in any memory file
+
+### Don't duplicate:
+- If CLAUDE.md already says "Use pnpm", don't also keep it in MEMORY.md
+- After promoting, remove the source entry to free space
+
+## Promotion Workflow
+
+```
+1. /si:review identifies candidate
+2. Confirm the pattern is still valid
+3. Distill into one-line instruction
+4. /si:promote writes to CLAUDE.md or rules/
+5. Remove from MEMORY.md
+6. Verify with /si:status
+```