@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/skills/connections-optimizer/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: connections-optimizer
+description: Reorganize the user's X and LinkedIn network with review-first pruning, add/follow recommendations, and channel-specific warm outreach drafted in the user's real voice. Use when the user wants to clean up following lists, grow toward current priorities, or rebalance a social graph around higher-signal relationships.
+origin: ECC
+---
+
+# Connections Optimizer
+
+Reorganize the user's network instead of treating outbound as a one-way prospecting list.
+
+This skill handles:
+
+- X following cleanup and expansion
+- LinkedIn follow and connection analysis
+- review-first prune queues
+- add and follow recommendations
+- warm-path identification
+- Apple Mail, X DM, and LinkedIn draft generation in the user's real voice
+
+## When to Activate
+
+- the user wants to prune their X following
+- the user wants to rebalance who they follow or stay connected to
+- the user says "clean up my network", "who should I unfollow", "who should I follow", "who should I reconnect with"
+- outreach quality depends on network structure, not just cold list generation
+
+## Required Inputs
+
+Collect or infer:
+
+- current priorities and active work
+- target roles, industries, geos, or ecosystems
+- platform selection: X, LinkedIn, or both
+- do-not-touch list
+- mode: `light-pass`, `default`, or `aggressive`
+
+If the user does not specify a mode, use `default`.
+
+## Tool Requirements
+
+### Preferred
+
+- `x-api` for X graph inspection and recent activity
+- `lead-intelligence` for target discovery and warm-path ranking
+- `social-graph-ranker` when the user wants bridge value scored independently of the broader lead workflow
+- Exa / deep research for person and company enrichment
+- `brand-voice` before drafting outbound
+
+### Fallbacks
+
+- browser control for LinkedIn analysis and drafting
+- browser control for X if API coverage is constrained
+- Apple Mail or Mail.app drafting via desktop automation when email is the right channel
+
+## Safety Defaults
+
+- default is review-first, never blind auto-pruning
+- X: prune only accounts the user follows, never followers
+- LinkedIn: treat 1st-degree connection removal as manual-review-first
+- do not auto-send DMs, invites, or emails
+- emit a ranked action plan and drafts before any apply step
+
+## Platform Rules
+
+### X
+
+- mutuals are stickier than one-way follows
+- non-follow-backs can be pruned more aggressively
+- heavily inactive or disappeared accounts should surface quickly
+- engagement, signal quality, and bridge value matter more than raw follower count
+
+### LinkedIn
+
+- API-first if the user actually has LinkedIn API access
+- browser workflow must work when API access is missing
+- distinguish outbound follows from accepted 1st-degree connections
+- outbound follows can be pruned more freely
+- accepted 1st-degree connections should default to review, not auto-remove
+
+## Modes
+
+### `light-pass`
+
+- prune only high-confidence low-value one-way follows
+- surface the rest for review
+- generate a small add/follow list
+
+### `default`
+
+- balanced prune queue
+- balanced keep list
+- ranked add/follow queue
+- draft warm intros or direct outreach where useful
+
+### `aggressive`
+
+- larger prune queue
+- lower tolerance for stale non-follow-backs
+- still review-gated before apply
+
+## Scoring Model
+
+Use these positive signals:
+
+- reciprocity
+- recent activity
+- alignment to current priorities
+- network bridge value
+- role relevance
+- real engagement history
+- recent presence and responsiveness
+
+Use these negative signals:
+
+- disappeared or abandoned account
+- stale one-way follow
+- off-priority topic cluster
+- low-value noise
+- repeated non-response
+- no follow-back when many better replacements exist
+
+Mutuals and real warm-path bridges should be penalized less aggressively than one-way follows.
+
+## Workflow
+
+1. Capture priorities, do-not-touch constraints, and selected platforms.
+2. Pull the current following / connection inventory.
+3. Score prune candidates with explicit reasons.
+4. Score keep candidates with explicit reasons.
+5. Use `lead-intelligence` plus research surfaces to rank expansion candidates.
+6. Match the right channel:
+   - X DM for warm, fast social touch points
+   - LinkedIn message for professional graph adjacency
+   - Apple Mail draft for higher-context intros or outreach
+7. Run `brand-voice` before drafting messages.
+8. Return a review pack before any apply step.
+
+## Review Pack Format
+
+```text
+CONNECTIONS OPTIMIZER REPORT
+============================
+
+Mode:
+Platforms:
+Priority Set:
+
+Prune Queue
+- handle / profile
+  reason:
+  confidence:
+  action:
+
+Review Queue
+- handle / profile
+  reason:
+  risk:
+
+Keep / Protect
+- handle / profile
+  bridge value:
+
+Add / Follow Targets
+- person
+  why now:
+  warm path:
+  preferred channel:
+
+Drafts
+- X DM:
+- LinkedIn:
+- Apple Mail:
+```
+
+## Outbound Rules
+
+- Default email path is Apple Mail / Mail.app draft creation.
+- Do not send automatically.
+- Choose the channel based on warmth, relevance, and context depth.
+- Do not force a DM when an email or no outreach is the right move.
+- Drafts should sound like the user, not like automated sales copy.
+
+## Related Skills
+
+- `brand-voice` for the reusable voice profile
+- `social-graph-ranker` for the standalone bridge-scoring and warm-path math
+- `lead-intelligence` for weighted target and warm-path discovery
+- `x-api` for X graph access, drafting, and optional apply flows
+- `content-engine` when the user also wants public launch content around network moves

package/.agent/skills/content-engine/SKILL.md

@@ -0,0 +1,131 @@
+---
+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
+
+Build platform-native content without flattening the author's real voice into platform slop.
+
+## 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, docs, or internal notes into public content
+- building a launch sequence or ongoing content system around a product, insight, or narrative
+
+## Non-Negotiables
+
+1. Start from source material, not generic post formulas.
+2. Adapt the format for the platform, not the persona.
+3. One post should carry one actual claim.
+4. Specificity beats adjectives.
+5. No engagement bait unless the user explicitly asks for it.
+
+## Source-First Workflow
+
+Before drafting, identify the source set:
+- published articles
+- notes or internal memos
+- product demos
+- docs or changelogs
+- transcripts
+- screenshots
+- prior posts from the same author
+
+If the user wants a specific voice, build a voice profile from real examples before writing.
+Use `brand-voice` as the canonical workflow when voice consistency matters across more than one output.
+
+## Voice Handling
+
+`brand-voice` is the canonical voice layer.
+
+Run it first when:
+
+- there are multiple downstream outputs
+- the user explicitly cares about writing style
+- the content is launch, outreach, or reputation-sensitive
+
+Reuse the resulting `VOICE PROFILE` here instead of rebuilding a second voice model.
+If the user wants Affaan / ECC voice specifically, still treat `brand-voice` as the source of truth and feed it the best live or source-derived material available.
+
+## Hard Bans
+
+Delete and rewrite any of these:
+- "In today's rapidly evolving landscape"
+- "game-changer", "revolutionary", "cutting-edge"
+- "here's why this matters" unless it is followed immediately by something concrete
+- ending with a LinkedIn-style question just to farm replies
+- forced casualness on LinkedIn
+- fake engagement padding that was not present in the source material
+
+## Platform Adaptation Rules
+
+### X
+
+- open with the strongest claim, artifact, or tension
+- keep the compression if the source voice is compressed
+- if writing a thread, each post must advance the argument
+- do not pad with context the audience does not need
+
+### LinkedIn
+
+- expand only enough for people outside the immediate niche to follow
+- do not turn it into a fake lesson post unless the source material actually is reflective
+- no corporate inspiration cadence
+- no praise-stacking, no "journey" filler
+
+### Short Video
+
+- script around the visual sequence and proof points
+- first seconds should show the result, problem, or punch
+- do not write narration that sounds better on paper than on screen
+
+### YouTube
+
+- show the result or tension early
+- organize by argument or progression, not filler sections
+- use chaptering only when it helps clarity
+
+### Newsletter
+
+- open with the point, conflict, or artifact
+- do not spend the first paragraph warming up
+- every section needs to add something new
+
+## Repurposing Flow
+
+1. Pick the anchor asset.
+2. Extract 3 to 7 atomic claims or scenes.
+3. Rank them by sharpness, novelty, and proof.
+4. Assign one strong idea per output.
+5. Adapt structure for each platform.
+6. Strip platform-shaped filler.
+7. Run the quality gate.
+
+## Deliverables
+
+When asked for a campaign, return:
+- a short voice profile if voice matching matters
+- the core angle
+- platform-native drafts
+- posting order only if it helps execution
+- gaps that must be filled before publishing
+
+## Quality Gate
+
+Before delivering:
+- every draft sounds like the intended author, not the platform stereotype
+- every draft contains a real claim, proof point, or concrete observation
+- no generic hype language remains
+- no fake engagement bait remains
+- no duplicated copy across platforms unless requested
+- any CTA is earned and user-approved
+
+## Related Skills
+
+- `brand-voice` for source-derived voice profiles
+- `crosspost` for platform-specific distribution
+- `x-api` for sourcing recent posts and publishing approved X output

package/.agent/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/.agent/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    │
+└─────────────────┴────────┴───────────┘
+
+WARNING: 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/.agent/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