aw-ecc 1.4.21

package/skills/content-engine/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: content-engine
+description: Create platform-native content systems for X, LinkedIn, TikTok, YouTube, newsletters, and repurposed multi-platform campaigns. Use when the user wants social posts, threads, scripts, content calendars, or one source asset adapted cleanly across platforms.
+origin: ECC
+---
+
+# Content Engine
+
+Turn one idea into strong, platform-native content instead of posting the same thing everywhere.
+
+## When to Activate
+
+- writing X posts or threads
+- drafting LinkedIn posts or launch updates
+- scripting short-form video or YouTube explainers
+- repurposing articles, podcasts, demos, or docs into social content
+- building a lightweight content plan around a launch, milestone, or theme
+
+## First Questions
+
+Clarify:
+- source asset: what are we adapting from
+- audience: builders, investors, customers, operators, or general audience
+- platform: X, LinkedIn, TikTok, YouTube, newsletter, or multi-platform
+- goal: awareness, conversion, recruiting, authority, launch support, or engagement
+
+## Core Rules
+
+1. Adapt for the platform. Do not cross-post the same copy.
+2. Hooks matter more than summaries.
+3. Every post should carry one clear idea.
+4. Use specifics over slogans.
+5. Keep the ask small and clear.
+
+## Platform Guidance
+
+### X
+- open fast
+- one idea per post or per tweet in a thread
+- keep links out of the main body unless necessary
+- avoid hashtag spam
+
+### LinkedIn
+- strong first line
+- short paragraphs
+- more explicit framing around lessons, results, and takeaways
+
+### TikTok / Short Video
+- first 3 seconds must interrupt attention
+- script around visuals, not just narration
+- one demo, one claim, one CTA
+
+### YouTube
+- show the result early
+- structure by chapter
+- refresh the visual every 20-30 seconds
+
+### Newsletter
+- deliver one clear lens, not a bundle of unrelated items
+- make section titles skimmable
+- keep the opening paragraph doing real work
+
+## Repurposing Flow
+
+Default cascade:
+1. anchor asset: article, video, demo, memo, or launch doc
+2. extract 3-7 atomic ideas
+3. write platform-native variants
+4. trim repetition across outputs
+5. align CTAs with platform intent
+
+## Deliverables
+
+When asked for a campaign, return:
+- the core angle
+- platform-specific drafts
+- optional posting order
+- optional CTA variants
+- any missing inputs needed before publishing
+
+## Quality Gate
+
+Before delivering:
+- each draft reads natively for its platform
+- hooks are strong and specific
+- no generic hype language
+- no duplicated copy across platforms unless requested
+- the CTA matches the content and audience

package/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/skills/context-budget/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: context-budget
+description: Audits Claude Code context window consumption across agents, skills, MCP servers, and rules. Identifies bloat, redundant components, and produces prioritized token-savings recommendations.
+origin: ECC
+---
+
+# Context Budget
+
+Analyze token overhead across every loaded component in a Claude Code session and surface actionable optimizations to reclaim context space.
+
+## When to Use
+
+- Session performance feels sluggish or output quality is degrading
+- 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)
+
+## How It Works
+
+### Phase 1: Inventory
+
+Scan all component directories and estimate token consumption:
+
+**Agents** (`agents/*.md`)
+- Count lines and tokens per file (words × 1.3)
+- Extract `description` frontmatter length
+- Flag: files >200 lines (heavy), description >30 words (bloated frontmatter)
+
+**Skills** (`skills/*/SKILL.md`)
+- Count tokens per SKILL.md
+- Flag: files >400 lines
+- Check for duplicate copies in `.agents/skills/` — skip identical copies to avoid double-counting
+
+**Rules** (`rules/**/*.md`)
+- Count tokens per file
+- Flag: files >100 lines
+- Detect content overlap between rule files in the same language module
+
+**MCP Servers** (`.mcp.json` or active MCP config)
+- Count configured servers and total tool count
+- Estimate schema overhead at ~500 tokens per tool
+- Flag: servers with >20 tools, servers that wrap simple CLI commands (`gh`, `git`, `npm`, `supabase`, `vercel`)
+
+**CLAUDE.md** (project + user-level)
+- Count tokens per file in the CLAUDE.md chain
+- Flag: combined total >300 lines
+
+### Phase 2: Classify
+
+Sort every component into a bucket:
+
+| Bucket | Criteria | Action |
+|--------|----------|--------|
+| **Always needed** | Referenced in CLAUDE.md, backs an active command, or matches current project type | Keep |
+| **Sometimes needed** | Domain-specific (e.g. language patterns), not referenced in CLAUDE.md | Consider on-demand activation |
+| **Rarely needed** | No command reference, overlapping content, or no obvious project match | Remove or lazy-load |
+
+### Phase 3: Detect Issues
+
+Identify the following problem patterns:
+
+- **Bloated agent descriptions** — description >30 words in frontmatter loads into every Task tool invocation
+- **Heavy agents** — files >200 lines inflate Task tool context on every spawn
+- **Redundant components** — skills that duplicate agent logic, rules that duplicate CLAUDE.md
+- **MCP over-subscription** — >10 servers, or servers wrapping CLI tools available for free
+- **CLAUDE.md bloat** — verbose explanations, outdated sections, instructions that should be rules
+
+### Phase 4: Report
+
+Produce the context budget report:
+
+```
+Context Budget Report
+═══════════════════════════════════════
+
+Total estimated overhead: ~XX,XXX tokens
+Context model: Claude Sonnet (200K window)
+Effective available context: ~XXX,XXX tokens (XX%)
+
+Component Breakdown:
+┌─────────────────┬────────┬───────────┐
+│ Component       │ Count  │ Tokens    │
+├─────────────────┼────────┼───────────┤
+│ Agents          │ N      │ ~X,XXX    │
+│ Skills          │ N      │ ~X,XXX    │
+│ Rules           │ N      │ ~X,XXX    │
+│ MCP tools       │ N      │ ~XX,XXX   │
+│ CLAUDE.md       │ N      │ ~X,XXX    │
+└─────────────────┴────────┴───────────┘
+
+⚠ Issues Found (N):
+[ranked by token savings]
+
+Top 3 Optimizations:
+1. [action] → save ~X,XXX tokens
+2. [action] → save ~X,XXX tokens
+3. [action] → save ~X,XXX tokens
+
+Potential savings: ~XX,XXX tokens (XX% of current overhead)
+```
+
+In verbose mode, additionally output per-file token counts, line-by-line breakdown of the heaviest files, specific redundant lines between overlapping components, and MCP tool list with per-tool schema size estimates.
+
+## Examples
+
+**Basic audit**
+```
+User: /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)
+```
+
+**Verbose mode**
+```
+User: /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
+```
+
+**Pre-expansion check**
+```
+User: I want to add 5 more MCP servers, do I have room?
+Skill: Current overhead 33% → adding 5 servers (~50 tools) would add ~25,000 tokens → pushes to 45% overhead
+       Recommendation: remove 2 CLI-replaceable servers first to stay under 40%
+```
+
+## Best Practices
+
+- **Token estimation**: use `words × 1.3` for prose, `chars / 4` for code-heavy files
+- **MCP is the biggest lever**: each tool schema costs ~500 tokens; a 30-tool server costs more than all your skills combined
+- **Agent descriptions are loaded always**: even if the agent is never invoked, its description field is present in every Task tool context
+- **Verbose mode for debugging**: use when you need to pinpoint the exact files driving overhead, not for regular audits
+- **Audit after changes**: run after adding any agent, skill, or MCP server to catch creep early

package/skills/context-engineering/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: context-engineering
+description: Curates the right task context at the right time. Use when starting work, switching tasks, debugging context drift, or when output quality drops because the agent is missing or overloaded with information.
+origin: ECC
+---
+
+# Context Engineering
+
+## Overview
+
+Better context beats louder instructions.
+This skill keeps the active context focused, ordered, and scoped to the current decision so the agent follows the right rules without drowning in irrelevant files.
+
+## When to Use
+
+- starting a new feature, bug, or review pass
+- switching from one subsystem or stage to another
+- output quality degrades or the agent starts ignoring conventions
+- the repo is large and only a small part is relevant
+- multiple possible standards or artifacts could apply
+
+**When NOT to use**
+
+- the task is tiny and already has a clear, narrow input set
+
+## Workflow
+
+1. Establish the context hierarchy.
+   Load in this order:
+   - repo rules and stage contracts
+   - approved planning artifacts or stage outputs
+   - org standards, baseline profiles, and `.aw_rules`
+   - relevant source files and diffs
+   - runtime evidence, logs, test output, screenshots
+   - conversation history
+2. Pack only what the current stage needs.
+   Planning needs specs and boundaries.
+   Build needs concrete file scope and validation targets.
+   Review needs evidence first.
+   Investigation needs failure signals first.
+3. Remove context that no longer serves the current task.
+   Old branches of thought, unrelated files, and stale runtime output are noise once the decision moves on.
+4. Repack at stage transitions.
+   A good context pack for `plan` is not the same as one for `build`, `test`, or `review`.
+5. Detect drift early.
+   If the agent starts guessing, inventing APIs, or broadening scope, stop and rebuild the context pack instead of pushing forward with bad state.
+6. Record the current anchors.
+   Name the source-of-truth files and evidence the current work depends on.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll just load everything." | Too much context reduces focus and increases wrong pattern matching. |
+| "Conversation history is enough." | History is the weakest context layer when repo rules or artifacts disagree. |
+| "The agent should infer the convention." | If the convention matters, load it explicitly. |
+| "I can keep the same context pack across all stages." | Different stages need different information density and order. |
+
+## Red Flags
+
+- the agent cites stale artifacts after the stage changed
+- unrelated files keep reappearing in reasoning or edits
+- errors are discussed without the exact failing output loaded
+- repo rules are overridden by conversation memory
+
+## Verification
+
+After repacking context, confirm:
+
+- [ ] the highest-priority rules are loaded first
+- [ ] only stage-relevant files and evidence are active
+- [ ] stale or contradictory context was removed or named
+- [ ] the source-of-truth inputs are explicit
+- [ ] the agent can explain the current task using the packed context only

package/skills/continuous-agent-loop/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: continuous-agent-loop
+description: Patterns for continuous autonomous agent loops with quality gates, evals, and recovery controls.
+origin: ECC
+---
+
+# Continuous Agent Loop
+
+This is the v1.8+ canonical loop skill name. It supersedes `autonomous-loops` while keeping compatibility for one release.
+
+## Loop Selection Flow
+
+```text
+Start
+  |
+  +-- Need strict CI/PR control? -- yes --> continuous-pr
+  |                                    
+  +-- Need RFC decomposition? -- yes --> rfc-dag
+  |
+  +-- Need exploratory parallel generation? -- yes --> infinite
+  |
+  +-- default --> sequential
+```
+
+## Combined Pattern
+
+Recommended production stack:
+1. RFC decomposition (`ralphinho-rfc-pipeline`)
+2. quality gates (`plankton-code-quality` + `/quality-gate`)
+3. eval loop (`eval-harness`)
+4. session persistence (`nanoclaw-repl`)
+
+## Failure Modes
+
+- loop churn without measurable progress
+- repeated retries with same root cause
+- merge queue stalls
+- cost drift from unbounded escalation
+
+## Recovery
+
+- freeze loop
+- run `/harness-audit`
+- reduce scope to failing unit
+- replay with explicit acceptance criteria

package/skills/continuous-learning/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: continuous-learning
+description: Automatically extract reusable patterns from Claude Code sessions and save them as learned skills for future use.
+origin: ECC
+---
+
+# Continuous Learning Skill
+
+Automatically evaluates Claude Code sessions on end to extract reusable patterns that can be saved as learned skills.
+
+## When to Activate
+
+- Setting up automatic pattern extraction from Claude Code sessions
+- Configuring the Stop hook for session evaluation
+- Reviewing or curating learned skills in `~/.claude/skills/learned/`
+- Adjusting extraction thresholds or pattern categories
+- Comparing v1 (this) vs v2 (instinct-based) approaches
+
+## How It Works
+
+This skill runs as a **Stop hook** at the end of each session:
+
+1. **Session Evaluation**: Checks if session has enough messages (default: 10+)
+2. **Pattern Detection**: Identifies extractable patterns from the session
+3. **Skill Extraction**: Saves useful patterns to `~/.claude/skills/learned/`
+
+## Configuration
+
+Edit `config.json` to customize:
+
+```json
+{
+  "min_session_length": 10,
+  "extraction_threshold": "medium",
+  "auto_approve": false,
+  "learned_skills_path": "~/.claude/skills/learned/",
+  "patterns_to_detect": [
+    "error_resolution",
+    "user_corrections",
+    "workarounds",
+    "debugging_techniques",
+    "project_specific"
+  ],
+  "ignore_patterns": [
+    "simple_typos",
+    "one_time_fixes",
+    "external_api_issues"
+  ]
+}
+```
+
+## Pattern Types
+
+| Pattern | Description |
+|---------|-------------|
+| `error_resolution` | How specific errors were resolved |
+| `user_corrections` | Patterns from user corrections |
+| `workarounds` | Solutions to framework/library quirks |
+| `debugging_techniques` | Effective debugging approaches |
+| `project_specific` | Project-specific conventions |
+
+## Hook Setup
+
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "matcher": "*",
+      "hooks": [{
+        "type": "command",
+        "command": "~/.claude/skills/continuous-learning/evaluate-session.sh"
+      }]
+    }]
+  }
+}
+```
+
+## Why Stop Hook?
+
+- **Lightweight**: Runs once at session end
+- **Non-blocking**: Doesn't add latency to every message
+- **Complete context**: Has access to full session transcript
+
+## Related
+
+- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) - Section on continuous learning
+- `/learn` command - Manual pattern extraction mid-session
+
+---
+
+## Comparison Notes (Research: Jan 2025)
+
+### vs Homunculus
+
+Homunculus v2 takes a more sophisticated approach:
+
+| Feature | Our Approach | Homunculus v2 |
+|---------|--------------|---------------|
+| Observation | Stop hook (end of session) | PreToolUse/PostToolUse hooks (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 |
+
+**Key insight from homunculus:**
+> "v1 relied on skills to observe. Skills are probabilistic—they fire ~50-80% of the time. v2 uses hooks for observation (100% reliable) and instincts as the atomic unit of learned behavior."
+
+### Potential v2 Enhancements
+
+1. **Instinct-based learning** - Smaller, atomic behaviors with confidence scoring
+2. **Background observer** - Haiku agent analyzing in parallel
+3. **Confidence decay** - Instincts lose confidence if contradicted
+4. **Domain tagging** - code-style, testing, git, debugging, etc.
+5. **Evolution path** - Cluster related instincts into skills/commands
+
+See: `docs/continuous-learning-v2-spec.md` for full spec.

package/skills/continuous-learning/config.json

@@ -0,0 +1,18 @@
+{
+  "min_session_length": 10,
+  "extraction_threshold": "medium",
+  "auto_approve": false,
+  "learned_skills_path": "~/.claude/skills/learned/",
+  "patterns_to_detect": [
+    "error_resolution",
+    "user_corrections",
+    "workarounds",
+    "debugging_techniques",
+    "project_specific"
+  ],
+  "ignore_patterns": [
+    "simple_typos",
+    "one_time_fixes",
+    "external_api_issues"
+  ]
+}