claude-code-pilot 3.0.0 → 3.1.1

package/src/skills/content-hash-cache-pattern/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: content-hash-cache-pattern
+description: Cache expensive file processing results using SHA-256 content hashes — path-independent, auto-invalidating, with service layer separation.
+origin: ECC
+---
+
+# Content-Hash File Cache Pattern
+
+Cache expensive file processing results (PDF parsing, text extraction, image analysis) using SHA-256 content hashes as cache keys. Unlike path-based caching, this approach survives file moves/renames and auto-invalidates when content changes.
+
+## When to Activate
+
+- Building file processing pipelines (PDF, images, text extraction)
+- Processing cost is high and same files are processed repeatedly
+- Need a `--cache/--no-cache` CLI option
+- Want to add caching to existing pure functions without modifying them
+
+## Core Pattern
+
+### 1. Content-Hash Based Cache Key
+
+Use file content (not path) as the cache key:
+
+```python
+import hashlib
+from pathlib import Path
+
+_HASH_CHUNK_SIZE = 65536  # 64KB chunks for large files
+
+def compute_file_hash(path: Path) -> str:
+    """SHA-256 of file contents (chunked for large files)."""
+    if not path.is_file():
+        raise FileNotFoundError(f"File not found: {path}")
+    sha256 = hashlib.sha256()
+    with open(path, "rb") as f:
+        while True:
+            chunk = f.read(_HASH_CHUNK_SIZE)
+            if not chunk:
+                break
+            sha256.update(chunk)
+    return sha256.hexdigest()
+```
+
+**Why content hash?** File rename/move = cache hit. Content change = automatic invalidation. No index file needed.
+
+### 2. Frozen Dataclass for Cache Entry
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True, slots=True)
+class CacheEntry:
+    file_hash: str
+    source_path: str
+    document: ExtractedDocument  # The cached result
+```
+
+### 3. File-Based Cache Storage
+
+Each cache entry is stored as `{hash}.json` — O(1) lookup by hash, no index file required.
+
+```python
+import json
+from typing import Any
+
+def write_cache(cache_dir: Path, entry: CacheEntry) -> None:
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    cache_file = cache_dir / f"{entry.file_hash}.json"
+    data = serialize_entry(entry)
+    cache_file.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+
+def read_cache(cache_dir: Path, file_hash: str) -> CacheEntry | None:
+    cache_file = cache_dir / f"{file_hash}.json"
+    if not cache_file.is_file():
+        return None
+    try:
+        raw = cache_file.read_text(encoding="utf-8")
+        data = json.loads(raw)
+        return deserialize_entry(data)
+    except (json.JSONDecodeError, ValueError, KeyError):
+        return None  # Treat corruption as cache miss
+```
+
+### 4. Service Layer Wrapper (SRP)
+
+Keep the processing function pure. Add caching as a separate service layer.
+
+```python
+def extract_with_cache(
+    file_path: Path,
+    *,
+    cache_enabled: bool = True,
+    cache_dir: Path = Path(".cache"),
+) -> ExtractedDocument:
+    """Service layer: cache check -> extraction -> cache write."""
+    if not cache_enabled:
+        return extract_text(file_path)  # Pure function, no cache knowledge
+
+    file_hash = compute_file_hash(file_path)
+
+    # Check cache
+    cached = read_cache(cache_dir, file_hash)
+    if cached is not None:
+        logger.info("Cache hit: %s (hash=%s)", file_path.name, file_hash[:12])
+        return cached.document
+
+    # Cache miss -> extract -> store
+    logger.info("Cache miss: %s (hash=%s)", file_path.name, file_hash[:12])
+    doc = extract_text(file_path)
+    entry = CacheEntry(file_hash=file_hash, source_path=str(file_path), document=doc)
+    write_cache(cache_dir, entry)
+    return doc
+```
+
+## Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| SHA-256 content hash | Path-independent, auto-invalidates on content change |
+| `{hash}.json` file naming | O(1) lookup, no index file needed |
+| Service layer wrapper | SRP: extraction stays pure, cache is a separate concern |
+| Manual JSON serialization | Full control over frozen dataclass serialization |
+| Corruption returns `None` | Graceful degradation, re-processes on next run |
+| `cache_dir.mkdir(parents=True)` | Lazy directory creation on first write |
+
+## Best Practices
+
+- **Hash content, not paths** — paths change, content identity doesn't
+- **Chunk large files** when hashing — avoid loading entire files into memory
+- **Keep processing functions pure** — they should know nothing about caching
+- **Log cache hit/miss** with truncated hashes for debugging
+- **Handle corruption gracefully** — treat invalid cache entries as misses, never crash
+
+## Anti-Patterns to Avoid
+
+```python
+# BAD: Path-based caching (breaks on file move/rename)
+cache = {"/path/to/file.pdf": result}
+
+# BAD: Adding cache logic inside the processing function (SRP violation)
+def extract_text(path, *, cache_enabled=False, cache_dir=None):
+    if cache_enabled:  # Now this function has two responsibilities
+        ...
+
+# BAD: Using dataclasses.asdict() with nested frozen dataclasses
+# (can cause issues with complex nested types)
+data = dataclasses.asdict(entry)  # Use manual serialization instead
+```
+
+## When to Use
+
+- File processing pipelines (PDF parsing, OCR, text extraction, image analysis)
+- CLI tools that benefit from `--cache/--no-cache` options
+- Batch processing where the same files appear across runs
+- Adding caching to existing pure functions without modifying them
+
+## When NOT to Use
+
+- Data that must always be fresh (real-time feeds)
+- Cache entries that would be extremely large (consider streaming instead)
+- Results that depend on parameters beyond file content (e.g., different extraction configs)

package/src/skills/context-budget/SKILL.md

@@ -14,7 +14,7 @@ Analyze token overhead across every loaded component in a Claude Code session an
 - You've recently added many skills, agents, or MCP servers
 - You want to know how much context headroom you actually have
 - Planning to add more components and need to know if there's room
-- Running `/context-budget` command (this skill backs it)
+- Running `/ccp:context-budget` command (this skill backs it)
 
 ## How It Works
 
@@ -106,7 +106,7 @@ In verbose mode, additionally output per-file token counts, line-by-line breakdo
 
 **Basic audit**
 ```
-User: /context-budget
+User: /ccp:context-budget
 Skill: Scans setup → 16 agents (12,400 tokens), 28 skills (6,200), 87 MCP tools (43,500), 2 CLAUDE.md (1,200)
        Flags: 3 heavy agents, 14 MCP servers (3 CLI-replaceable)
        Top saving: remove 3 MCP servers → -27,500 tokens (47% overhead reduction)
@@ -114,7 +114,7 @@ Skill: Scans setup → 16 agents (12,400 tokens), 28 skills (6,200), 87 MCP tool
 
 **Verbose mode**
 ```
-User: /context-budget --verbose
+User: /ccp:context-budget --verbose
 Skill: Full report + per-file breakdown showing planner.md (213 lines, 1,840 tokens),
        MCP tool list with per-tool sizes, duplicated rule lines side by side
 ```

package/src/skills/continuous-learning-v2/SKILL.md

@@ -112,7 +112,7 @@ Session Activity (in a git repo)
 |   * grep-before-edit.yaml (0.6) [global]     |
 +---------------------------------------------+
       |
-      | /evolve clusters + /promote
+      | /ccp:evolve clusters + /promote
       v
 +---------------------------------------------+
 |  projects/<hash>/evolved/ (project-scoped)   |
@@ -201,7 +201,7 @@ mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,sk
 
 ```bash
 /instinct-status     # Show learned instincts (project + global)
-/evolve              # Cluster related instincts into skills/commands
+/ccp: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
@@ -213,7 +213,7 @@ mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,sk
 | Command | Description |
 |---------|-------------|
 | `/instinct-status` | Show all instincts (project-scoped + global) with confidence |
-| `/evolve` | Cluster related instincts into skills/commands, suggest promotions |
+| `/ccp: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 |
@@ -306,7 +306,7 @@ python3 instinct-cli.py promote
 python3 instinct-cli.py promote --dry-run
 ```
 
-The `/evolve` command also suggests promotion candidates.
+The `/ccp:evolve` command also suggests promotion candidates.
 
 ## Confidence Scoring
 

package/src/skills/continuous-learning-v2/agents/observer.md

@@ -154,7 +154,7 @@ An instinct should be promoted from project-scoped to global when:
 2. Each instance has confidence **>= 0.8**
 3. The domain is in the global-friendly list (security, general-best-practices, workflow)
 
-Promotion is handled by the `instinct-cli.py promote` command or the `/evolve` analysis.
+Promotion is handled by the `instinct-cli.py promote` command or the `/ccp:evolve` analysis.
 
 ## Important Guidelines
 

package/src/skills/cost-aware-llm-pipeline/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: cost-aware-llm-pipeline
+description: Cost optimization patterns for LLM API usage — model routing by task complexity, budget tracking, retry logic, and prompt caching.
+origin: ECC
+---
+
+# Cost-Aware LLM Pipeline
+
+Patterns for controlling LLM API costs while maintaining quality. Combines model routing, budget tracking, retry logic, and prompt caching into a composable pipeline.
+
+## When to Activate
+
+- Building applications that call LLM APIs (Claude, GPT, etc.)
+- Processing batches of items with varying complexity
+- Need to stay within a budget for API spend
+- Optimizing cost without sacrificing quality on complex tasks
+
+## Core Concepts
+
+### 1. Model Routing by Task Complexity
+
+Automatically select cheaper models for simple tasks, reserving expensive models for complex ones.
+
+```python
+MODEL_SONNET = "claude-sonnet-4-6"
+MODEL_HAIKU = "claude-haiku-4-5-20251001"
+
+_SONNET_TEXT_THRESHOLD = 10_000  # chars
+_SONNET_ITEM_THRESHOLD = 30     # items
+
+def select_model(
+    text_length: int,
+    item_count: int,
+    force_model: str | None = None,
+) -> str:
+    """Select model based on task complexity."""
+    if force_model is not None:
+        return force_model
+    if text_length >= _SONNET_TEXT_THRESHOLD or item_count >= _SONNET_ITEM_THRESHOLD:
+        return MODEL_SONNET  # Complex task
+    return MODEL_HAIKU  # Simple task (3-4x cheaper)
+```
+
+### 2. Immutable Cost Tracking
+
+Track cumulative spend with frozen dataclasses. Each API call returns a new tracker — never mutates state.
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True, slots=True)
+class CostRecord:
+    model: str
+    input_tokens: int
+    output_tokens: int
+    cost_usd: float
+
+@dataclass(frozen=True, slots=True)
+class CostTracker:
+    budget_limit: float = 1.00
+    records: tuple[CostRecord, ...] = ()
+
+    def add(self, record: CostRecord) -> "CostTracker":
+        """Return new tracker with added record (never mutates self)."""
+        return CostTracker(
+            budget_limit=self.budget_limit,
+            records=(*self.records, record),
+        )
+
+    @property
+    def total_cost(self) -> float:
+        return sum(r.cost_usd for r in self.records)
+
+    @property
+    def over_budget(self) -> bool:
+        return self.total_cost > self.budget_limit
+```
+
+### 3. Narrow Retry Logic
+
+Retry only on transient errors. Fail fast on authentication or bad request errors.
+
+```python
+from anthropic import (
+    APIConnectionError,
+    InternalServerError,
+    RateLimitError,
+)
+
+_RETRYABLE_ERRORS = (APIConnectionError, RateLimitError, InternalServerError)
+_MAX_RETRIES = 3
+
+def call_with_retry(func, *, max_retries: int = _MAX_RETRIES):
+    """Retry only on transient errors, fail fast on others."""
+    for attempt in range(max_retries):
+        try:
+            return func()
+        except _RETRYABLE_ERRORS:
+            if attempt == max_retries - 1:
+                raise
+            time.sleep(2 ** attempt)  # Exponential backoff
+    # AuthenticationError, BadRequestError etc. → raise immediately
+```
+
+### 4. Prompt Caching
+
+Cache long system prompts to avoid resending them on every request.
+
+```python
+messages = [
+    {
+        "role": "user",
+        "content": [
+            {
+                "type": "text",
+                "text": system_prompt,
+                "cache_control": {"type": "ephemeral"},  # Cache this
+            },
+            {
+                "type": "text",
+                "text": user_input,  # Variable part
+            },
+        ],
+    }
+]
+```
+
+## Composition
+
+Combine all four techniques in a single pipeline function:
+
+```python
+def process(text: str, config: Config, tracker: CostTracker) -> tuple[Result, CostTracker]:
+    # 1. Route model
+    model = select_model(len(text), estimated_items, config.force_model)
+
+    # 2. Check budget
+    if tracker.over_budget:
+        raise BudgetExceededError(tracker.total_cost, tracker.budget_limit)
+
+    # 3. Call with retry + caching
+    response = call_with_retry(lambda: client.messages.create(
+        model=model,
+        messages=build_cached_messages(system_prompt, text),
+    ))
+
+    # 4. Track cost (immutable)
+    record = CostRecord(model=model, input_tokens=..., output_tokens=..., cost_usd=...)
+    tracker = tracker.add(record)
+
+    return parse_result(response), tracker
+```
+
+## Pricing Reference (2025-2026)
+
+| Model | Input ($/1M tokens) | Output ($/1M tokens) | Relative Cost |
+|-------|---------------------|----------------------|---------------|
+| Haiku 4.5 | $0.80 | $4.00 | 1x |
+| Sonnet 4.6 | $3.00 | $15.00 | ~4x |
+| Opus 4.5 | $15.00 | $75.00 | ~19x |
+
+## Best Practices
+
+- **Start with the cheapest model** and only route to expensive models when complexity thresholds are met
+- **Set explicit budget limits** before processing batches — fail early rather than overspend
+- **Log model selection decisions** so you can tune thresholds based on real data
+- **Use prompt caching** for system prompts over 1024 tokens — saves both cost and latency
+- **Never retry on authentication or validation errors** — only transient failures (network, rate limit, server error)
+
+## Anti-Patterns to Avoid
+
+- Using the most expensive model for all requests regardless of complexity
+- Retrying on all errors (wastes budget on permanent failures)
+- Mutating cost tracking state (makes debugging and auditing difficult)
+- Hardcoding model names throughout the codebase (use constants or config)
+- Ignoring prompt caching for repetitive system prompts
+
+## When to Use
+
+- Any application calling Claude, OpenAI, or similar LLM APIs
+- Batch processing pipelines where cost adds up quickly
+- Multi-model architectures that need intelligent routing
+- Production systems that need budget guardrails

package/src/skills/design-system/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: design-system
+description: Use this skill to generate or audit design systems, check visual consistency, and review PRs that touch styling.
+origin: ECC
+---
+
+# Design System — Generate & Audit Visual Systems
+
+## When to Use
+
+- Starting a new project that needs a design system
+- Auditing an existing codebase for visual consistency
+- Before a redesign — understand what you have
+- When the UI looks "off" but you can't pinpoint why
+- Reviewing PRs that touch styling
+
+## How It Works
+
+### Mode 1: Generate Design System
+
+Analyzes your codebase and generates a cohesive design system:
+
+```
+1. Scan CSS/Tailwind/styled-components for existing patterns
+2. Extract: colors, typography, spacing, border-radius, shadows, breakpoints
+3. Research 3 competitor sites for inspiration (via browser MCP)
+4. Propose a design token set (JSON + CSS custom properties)
+5. Generate DESIGN.md with rationale for each decision
+6. Create an interactive HTML preview page (self-contained, no deps)
+```
+
+Output: `DESIGN.md` + `design-tokens.json` + `design-preview.html`
+
+### Mode 2: Visual Audit
+
+Scores your UI across 10 dimensions (0-10 each):
+
+```
+1. Color consistency — are you using your palette or random hex values?
+2. Typography hierarchy — clear h1 > h2 > h3 > body > caption?
+3. Spacing rhythm — consistent scale (4px/8px/16px) or arbitrary?
+4. Component consistency — do similar elements look similar?
+5. Responsive behavior — fluid or broken at breakpoints?
+6. Dark mode — complete or half-done?
+7. Animation — purposeful or gratuitous?
+8. Accessibility — contrast ratios, focus states, touch targets
+9. Information density — cluttered or clean?
+10. Polish — hover states, transitions, loading states, empty states
+```
+
+Each dimension gets a score, specific examples, and a fix with exact file:line.
+
+### Mode 3: AI Slop Detection
+
+Identifies generic AI-generated design patterns:
+
+```
+- Gratuitous gradients on everything
+- Purple-to-blue defaults
+- "Glass morphism" cards with no purpose
+- Rounded corners on things that shouldn't be rounded
+- Excessive animations on scroll
+- Generic hero with centered text over stock gradient
+- Sans-serif font stack with no personality
+```
+
+## Examples
+
+**Generate for a SaaS app:**
+```
+/design-system generate --style minimal --palette earth-tones
+```
+
+**Audit existing UI:**
+```
+/design-system audit --url http://localhost:3000 --pages / /pricing /docs
+```
+
+**Check for AI slop:**
+```
+/design-system slop-check
+```