clawpowers 1.0.0

package/skills/content-pipeline/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: content-pipeline
+description: Write technical content, humanize it for natural voice, format for the target platform, and publish. Activate when creating blog posts, documentation, social media content, or newsletters.
+version: 1.0.0
+requires:
+  tools: [bash, curl]
+  runtime: false
+metrics:
+  tracks: [content_pieces_published, engagement_scores, revision_cycles, publish_time]
+  improves: [humanization_quality, platform_formatting, tone_calibration]
+---
+
+# Content Pipeline
+
+## When to Use
+
+Apply this skill when:
+
+- Writing technical blog posts or articles
+- Creating documentation for public consumption
+- Drafting social media content (Twitter/X, LinkedIn, Hacker News)
+- Writing newsletters or announcements
+- Creating README files for public repositories
+- Producing technical tutorials or guides
+
+**Skip when:**
+- Writing internal docs (no humanization step needed)
+- Pure code comments (different register entirely)
+- Short Slack/Teams messages (too much overhead for too little output)
+
+## Core Methodology
+
+### Stage 1: Write (Technical Draft)
+
+Write for accuracy first, voice second. The technical draft should be:
+
+- **Complete** — all required information is present
+- **Accurate** — facts, code samples, and commands are verified
+- **Structured** — uses headers, lists, and code blocks appropriately
+- **Dense** — every sentence carries information; no filler
+
+**Technical draft goals:**
+- Code examples compile and run
+- Commands produce the described output
+- Version numbers and API names are current and accurate
+- Links work
+
+**Structure template for technical blog post:**
+```markdown
+# [Concrete, specific title — no clickbait]
+
+## The Problem
+[What pain does the reader have? Why does this matter?]
+
+## The Solution
+[What you built/discovered/solved — the payoff]
+
+## How It Works
+[Technical explanation with code examples]
+
+## [Additional Implementation Sections]
+[Step-by-step if it's a tutorial; depth if it's an analysis]
+
+## Conclusion
+[1-2 sentences: what the reader can do now that they couldn't before]
+```
+
+**Structure template for documentation:**
+```markdown
+# [Feature/Component Name]
+
+## Overview
+[One paragraph: what this is and when to use it]
+
+## Quick Start
+[Minimal working example — 5 lines max]
+
+## Configuration
+[All options, with types, defaults, and descriptions]
+
+## Examples
+[2-3 realistic use cases with full code]
+
+## Reference
+[Complete API/parameter reference]
+
+## Troubleshooting
+[Common errors and their solutions]
+```
+
+### Stage 2: Humanize
+
+The technical draft sounds like documentation. Published content must sound like a person.
+
+**The problem:** LLM-generated text has a recognizable voice: over-hedged, passive, verbose, and full of transition phrases that signal nothing.
+
+**Banned patterns (remove every instance):**
+```
+"Delve into"
+"It's worth noting that"
+"In the realm of"
+"Let's explore"
+"Dive deep"
+"In conclusion"
+"In summary"
+"Seamlessly"
+"Leverage" (when "use" works)
+"Game-changer"
+"Groundbreaking"
+"Revolutionary"
+"Powerful" (unqualified)
+"Robust" (unqualified)
+"Ultimately"
+"Furthermore"
+"Moreover"
+"That being said"
+"At the end of the day"
+"It's important to note"
+```
+
+**Humanization checklist:**
+- [ ] Active voice: "The function returns X" not "X is returned by the function"
+- [ ] Specific claims: "37% faster" not "significantly faster"
+- [ ] No filler intros: Start with the substance, not "In this post, we will..."
+- [ ] Conversational where appropriate: Short sentences. Fragments when they land better.
+- [ ] Concrete examples from real use, not "imagine a world where..."
+- [ ] First person when sharing genuine perspective ("I spent 3 days debugging this")
+- [ ] No over-qualified hedging: "This may potentially help some users" → "This solves X"
+
+**Humanization transform examples:**
+
+Before:
+> "In this article, we will delve into the powerful features of the ClawPowers framework and explore how it can be leveraged to enhance your agent's capabilities in a seamless manner."
+
+After:
+> "ClawPowers gives your coding agent 20 skills. Here's how each one works and when to use it."
+
+Before:
+> "It's worth noting that the runtime layer provides significant performance improvements."
+
+After:
+> "The runtime layer cuts task time by 40% on average. Here's the data."
+
+### Stage 3: Platform Formatting
+
+Different platforms have different requirements:
+
+**Technical blog (dev.to, Hashnode, personal blog):**
+- Length: 1500-3000 words (comprehensive guides: up to 5000)
+- Code blocks with language hints
+- Headers for navigation (H2, H3 — not H4+)
+- Images optional but useful for architecture diagrams
+- Tags: 3-5, technical and specific
+
+**Twitter/X thread:**
+- Thread format: lead tweet → detail tweets → conclusion
+- Lead: hook + value proposition in 280 chars
+- Each tweet: one idea, can stand alone
+- No jargon in the lead tweet (hook a broader audience)
+- End with CTA (link, follow, reply)
+- Example thread structure:
+  ```
+  Tweet 1: Hook (the problem or the surprising result)
+  Tweet 2-3: Setup/context
+  Tweet 4-7: The substance (one idea per tweet)
+  Tweet 8: The takeaway
+  Tweet 9: CTA + link
+  ```
+
+**LinkedIn:**
+- Length: 150-300 words (longer performs worse)
+- Line breaks every 1-3 sentences (LinkedIn's UI favors scannable text)
+- First 2 lines must hook (everything else is hidden behind "see more")
+- Professional but human tone
+- End with a question to drive comments
+
+**Hacker News (Show HN / Ask HN):**
+- Title: factual, specific, no marketing language
+- Top comment: author context, what problem it solves, technical details
+- Avoid superlatives — community is allergic to hype
+- "I built X to solve Y problem" not "Revolutionary new tool transforms..."
+
+**GitHub README:**
+- Badge line first (CI status, npm version, license)
+- 3-sentence description: what, who, why
+- Quick start must work with copy-paste
+- Architecture diagram for complex projects
+- License and contributing section at bottom
+
+**Newsletter:**
+- Subject line: specific, implies value ("How we cut our test suite from 8min to 47sec")
+- Preheader: complements subject, not a repeat
+- Opening: straight to value — no "Hey, it's [name]!"
+- Sections: use headers, keep scannable
+- CTA: one primary action, at the bottom
+
+### Stage 4: Pre-Publish Review
+
+Before publishing:
+
+- [ ] All code samples verified (copy-paste and run)
+- [ ] All links work
+- [ ] No confidential information (internal URLs, customer names, private configs)
+- [ ] Humanization complete (banned phrases removed)
+- [ ] Platform format applied
+- [ ] Title is accurate and specific
+- [ ] Tags/categories are correct
+
+### Stage 5: Publish
+
+**Blog platforms (API publishing):**
+
+```bash
+# dev.to API
+curl -X POST "https://dev.to/api/articles" \
+  -H "api-key: $DEV_TO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "article": {
+      "title": "Your Article Title",
+      "body_markdown": "'"$(cat article.md)"'",
+      "published": true,
+      "tags": ["programming", "ai", "tools"]
+    }
+  }'
+```
+
+**GitHub (documentation):**
+```bash
+# Update docs in repo
+git add docs/new-feature.md
+git commit -m "docs: add [feature] guide"
+git push
+```
+
+## ClawPowers Enhancement
+
+When `~/.clawpowers/` runtime is initialized:
+
+**Publication Tracking:**
+
+```bash
+bash runtime/persistence/store.sh set "content:clawpowers-intro:platform" "dev.to"
+bash runtime/persistence/store.sh set "content:clawpowers-intro:published_at" "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+bash runtime/persistence/store.sh set "content:clawpowers-intro:url" "https://dev.to/..."
+```
+
+**Engagement Tracking:**
+
+After 24-48 hours, update with engagement metrics:
+```bash
+bash runtime/persistence/store.sh set "content:clawpowers-intro:views" "847"
+bash runtime/persistence/store.sh set "content:clawpowers-intro:reactions" "34"
+bash runtime/persistence/store.sh set "content:clawpowers-intro:comments" "7"
+```
+
+**Content Performance Analysis:**
+
+`runtime/feedback/analyze.sh` identifies:
+- Best-performing title patterns
+- Optimal content length per platform
+- Highest-engagement topic areas
+- Time-of-publish correlation with reach
+
+```bash
+bash runtime/metrics/collector.sh record \
+  --skill content-pipeline \
+  --outcome success \
+  --notes "clawpowers-intro: 1800 words, dev.to + twitter thread, published"
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Correct Approach |
+|-------------|-------------|-----------------|
+| Publishing technical draft directly | Reads like documentation, not content | Always run humanization step |
+| Same text on all platforms | Each platform has different format requirements | Platform-specific formatting per Stage 3 |
+| Unverified code samples | Readers can't reproduce, damages credibility | Run every code sample before publishing |
+| Superlative titles ("The BEST guide to...") | Algorithms deprioritize, readers distrust | Specific, factual titles |
+| Buried lede | Readers don't reach the value | Lead with the most interesting thing |
+| Publishing without review | Errors in published content are permanent | Pre-publish checklist, always |
+| No CTA | Content doesn't drive the desired outcome | One clear CTA per piece |

package/skills/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: dispatching-parallel-agents
+description: Fan out independent tasks to parallel agent processes with load balancing, failure isolation, and result aggregation. Activate when you have N independent tasks that can execute concurrently.
+version: 1.0.0
+requires:
+  tools: [bash, git]
+  runtime: false
+metrics:
+  tracks: [agents_dispatched, success_rate, parallel_efficiency, aggregation_errors]
+  improves: [task_partitioning, failure_isolation_strategy, aggregation_method]
+---
+
+# Dispatching Parallel Agents
+
+## When to Use
+
+Apply this skill when:
+
+- You have 3+ independent tasks with no shared dependencies
+- Each task can be described with a complete, self-contained spec
+- You have access to multiple agent processes or context windows
+- The tasks are roughly equal in complexity (or can be load-balanced)
+- A failure in one task should not abort others
+
+**Skip when:**
+- Tasks share state that would conflict under concurrent access
+- Tasks must execute in sequence (use `executing-plans` instead)
+- You have fewer than 3 tasks (overhead outweighs benefit)
+- You can't isolate failure — one bad result corrupts all results
+
+**Relationship to `subagent-driven-development`:**
+```
+subagent-driven-development: full development methodology (spec, review, worktree, integrate)
+dispatching-parallel-agents: execution mechanism (fan-out, monitor, aggregate)
+
+Use dispatching-parallel-agents for runtime parallelism.
+Use subagent-driven-development for development task orchestration.
+They are complementary — subagent-driven-development USES dispatching-parallel-agents.
+```
+
+## Core Methodology
+
+### Step 1: Task Decomposition for Parallelism
+
+Before dispatching, verify each task is:
+
+1. **Self-contained** — has all inputs it needs, produces a defined output
+2. **Isolated** — doesn't write to shared state other tasks read
+3. **Specced** — has clear success criteria (you'll need these for aggregation)
+4. **Sized appropriately** — not so small that dispatch overhead dominates
+
+**Task spec format for parallel dispatch:**
+```markdown
+## Task ID: [unique identifier]
+
+**Input:**
+- [File or data this task starts from]
+- [Any context this task needs]
+
+**Objective:** [Single sentence]
+
+**Output:**
+- [Exact artifact produced: file path, JSON structure, etc.]
+
+**Success criteria:**
+- [ ] [Verifiable criterion]
+
+**Failure behavior:**
+- [What this task does when it encounters an error]
+- [What it outputs on failure so the aggregator can detect it]
+```
+
+### Step 2: Failure Isolation Design
+
+Decide how failures propagate:
+
+| Strategy | When to Use | Implementation |
+|----------|-------------|----------------|
+| **Continue on failure** | Tasks are independent, partial results are valuable | Failed tasks return error object, aggregator handles |
+| **Fail fast** | Any failure invalidates all results | Use process groups; kill siblings on first failure |
+| **Retry on failure** | Tasks are idempotent and failures are transient | Retry N times with exponential backoff |
+| **Fallback on failure** | Alternative task exists for same output | Dispatch fallback when primary fails |
+
+**Output envelope for failure isolation:**
+```json
+{
+  "task_id": "auth-api",
+  "status": "success|failure|partial",
+  "output": { ... },
+  "error": null,
+  "duration_seconds": 47.3,
+  "checksum": "sha256_of_output"
+}
+```
+
+Every task must produce this envelope — the aggregator depends on it.
+
+### Step 3: Dispatch Mechanism
+
+**Option A: Process-level parallelism (Bash)**
+
+```bash
+#!/usr/bin/env bash
+# Fan out tasks in background, wait for all, aggregate results
+
+RESULTS_DIR=$(mktemp -d)
+PIDS=()
+
+dispatch_task() {
+  local task_id="$1"
+  local spec_file="$2"
+  
+  (
+    # Each task runs in a subshell with its own output file
+    output_file="$RESULTS_DIR/${task_id}.json"
+    
+    if run_task "$spec_file" > "$output_file" 2>&1; then
+      # Wrap output in envelope
+      echo '{"task_id":"'"$task_id"'","status":"success","output":'"$(cat "$output_file")"'}'
+    else
+      exit_code=$?
+      echo '{"task_id":"'"$task_id"'","status":"failure","error":"exit code '"$exit_code"'","output":null}'
+    fi
+  ) > "$RESULTS_DIR/${task_id}_envelope.json" &
+  
+  PIDS+=($!)
+  echo "Dispatched task $task_id (PID: ${PIDS[-1]})"
+}
+
+# Dispatch all tasks
+dispatch_task "auth-api" "specs/auth-api.md"
+dispatch_task "auth-db" "specs/auth-db.md"
+dispatch_task "auth-tests" "specs/auth-tests.md"
+
+# Wait for all tasks
+echo "Waiting for ${#PIDS[@]} tasks..."
+for pid in "${PIDS[@]}"; do
+  wait "$pid"
+done
+
+echo "All tasks complete. Results in $RESULTS_DIR/"
+```
+
+**Option B: Agent-level parallelism (Multi-context)**
+
+When you have multiple agent contexts (e.g., multiple Claude Code sessions, multiple Cursor instances):
+
+1. For each parallel task, open a new agent context
+2. Inject the complete task spec
+3. Each agent works independently in its assigned worktree
+4. Orchestrator aggregates results after all agents complete
+
+**Worktree-per-agent setup:**
+```bash
+TASKS=("auth-api" "auth-db" "auth-tests")
+for task in "${TASKS[@]}"; do
+  git worktree add "../project-${task}" -b "feature/${task}" main
+  echo "Worktree ready for ${task}: ../project-${task}"
+done
+```
+
+### Step 4: Monitoring
+
+Track task progress during execution:
+
+```bash
+# Check which tasks are still running
+for pid in "${PIDS[@]}"; do
+  if kill -0 "$pid" 2>/dev/null; then
+    echo "Still running: PID $pid"
+  fi
+done
+
+# Or: watch output files for progress indicators
+watch -n 5 'ls -la '"$RESULTS_DIR"'/'
+
+# Timeout monitoring — kill tasks that run too long
+MAX_DURATION=600  # 10 minutes
+for i in "${!PIDS[@]}"; do
+  pid="${PIDS[$i]}"
+  task="${TASKS[$i]}"
+  if kill -0 "$pid" 2>/dev/null; then
+    elapsed=$(ps -p "$pid" -o etimes= 2>/dev/null | tr -d ' ')
+    if [[ ${elapsed:-0} -gt $MAX_DURATION ]]; then
+      kill "$pid"
+      echo "TIMEOUT: Task $task (PID $pid) exceeded ${MAX_DURATION}s"
+    fi
+  fi
+done
+```
+
+### Step 5: Result Aggregation
+
+After all tasks complete, aggregate results:
+
+```bash
+#!/usr/bin/env bash
+# Aggregate results from all parallel tasks
+
+aggregate_results() {
+  local results_dir="$1"
+  local success_count=0
+  local failure_count=0
+  local failures=()
+  
+  for envelope_file in "$results_dir"/*_envelope.json; do
+    status=$(python3 -c "import json,sys; d=json.load(open('$envelope_file')); print(d['status'])")
+    task_id=$(python3 -c "import json,sys; d=json.load(open('$envelope_file')); print(d['task_id'])")
+    
+    if [[ "$status" == "success" ]]; then
+      ((success_count++))
+      echo "✓ $task_id"
+    else
+      ((failure_count++))
+      failures+=("$task_id")
+      error=$(python3 -c "import json,sys; d=json.load(open('$envelope_file')); print(d.get('error','unknown'))")
+      echo "✗ $task_id: $error"
+    fi
+  done
+  
+  echo ""
+  echo "Results: $success_count succeeded, $failure_count failed"
+  
+  if [[ $failure_count -gt 0 ]]; then
+    echo "Failed tasks: ${failures[*]}"
+    return 1
+  fi
+  
+  return 0
+}
+
+aggregate_results "$RESULTS_DIR"
+```
+
+**Aggregation decisions:**
+- All succeeded → proceed to integration
+- Some failed → re-dispatch only failed tasks (not successful ones)
+- Critical task failed → abort, fix, re-dispatch all dependent tasks
+
+### Step 6: Integration
+
+After successful aggregation:
+
+1. Verify outputs are compatible (no conflicting interfaces)
+2. Merge in dependency order (see `using-git-worktrees`)
+3. Run integration tests across all task outputs
+4. Clean up worktrees
+
+## ClawPowers Enhancement
+
+When `~/.clawpowers/` runtime is initialized:
+
+**Execution Registry:**
+
+```bash
+# Register dispatch batch
+BATCH_ID="auth-$(date +%s)"
+bash runtime/persistence/store.sh set "dispatch:${BATCH_ID}:tasks" "auth-api,auth-db,auth-tests"
+bash runtime/persistence/store.sh set "dispatch:${BATCH_ID}:started_at" "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+# Update per-task status as they complete
+bash runtime/persistence/store.sh set "dispatch:${BATCH_ID}:auth-api:status" "success"
+bash runtime/persistence/store.sh set "dispatch:${BATCH_ID}:auth-db:status" "running"
+
+# On session interrupt: resume knows exactly which tasks to re-dispatch
+bash runtime/persistence/store.sh list "dispatch:${BATCH_ID}:*:status"
+```
+
+**Load Balancing:**
+
+Track task execution times to balance future dispatches:
+```bash
+bash runtime/persistence/store.sh set "task-timing:auth-api" "47"
+bash runtime/persistence/store.sh set "task-timing:auth-db" "23"
+```
+
+Future dispatches group tasks to equalize total runtime across agents.
+
+**Failure Isolation Metrics:**
+
+```bash
+bash runtime/metrics/collector.sh record \
+  --skill dispatching-parallel-agents \
+  --outcome success \
+  --notes "auth: 3 tasks, all succeeded, 47s wall time vs 117s sequential"
+```
+
+Tracks parallel efficiency (wall time vs. theoretical serial time), helps tune batch sizes.
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Correct Approach |
+|-------------|-------------|-----------------|
+| Dispatching tasks that share mutable state | Race conditions, data corruption | Verify isolation before dispatch |
+| No output envelope format | Aggregator can't distinguish success from failure | Every task must produce structured output |
+| Waiting for all tasks when partial results suffice | Slowest task blocks all results | Consider streaming aggregation for independent outputs |
+| No timeout on tasks | One hung task blocks aggregation forever | Always set timeouts |
+| Re-dispatching succeeded tasks on retry | Wastes time, may produce different results | Track task status, retry only failed tasks |
+| No result verification after aggregation | Corrupted output passes through | Verify each task output against spec before integration |
+
+## Integration with Other Skills
+
+- Used by `subagent-driven-development` for task fan-out
+- Requires `using-git-worktrees` for file isolation
+- Outputs consumed by `verification-before-completion`