clawpowers 1.1.4 → 2.2.0

package/skills/brainstorming/SKILL.md

@@ -1,233 +0,0 @@
----
-name: brainstorming
-description: Structured ideation with convergence protocol. Activate when exploring solutions, designing architecture, or choosing between approaches.
-version: 1.0.0
-requires:
-  tools: []
-  runtime: false
-metrics:
-  tracks: [ideas_generated, ideas_pursued, convergence_time, decision_quality]
-  improves: [ideation_breadth, convergence_threshold, idea_linking]
----
-
-# Brainstorming
-
-## When to Use
-
-Apply this skill when:
-
-- A problem has multiple valid solution approaches and you need to choose
-- You're designing architecture and haven't committed to a direction
-- Someone asks "what should we do?" or "what are our options?"
-- You've been executing in one direction and need to verify it's still the right one
-- A constraint has changed and the previous approach may no longer be optimal
-- Creative solutions are needed (not just standard patterns)
-
-**Skip when:**
-- The solution is already determined and execution is what's needed
-- There's only one viable approach given the constraints
-- You need to converge immediately — brainstorming requires divergence time
-
-**Decision tree:**
-```
-Is the right approach known?
-├── Yes → execute it
-└── No  → Is this a known problem pattern?
-          ├── Yes → Apply known solution, validate fit with constraints
-          └── No  → brainstorming ← YOU ARE HERE
-```
-
-## Core Methodology
-
-Brainstorming has two phases: **diverge** (generate many ideas without judgment) and **converge** (evaluate, select, refine). Never mix them — evaluating during generation kills ideas before they can combine into something better.
-
-### Phase 1: Diverge
-
-**Rule:** No evaluation during divergence. Every idea is noted, even obviously bad ones.
-
-**Seed the space with different lenses:**
-
-1. **First-principles lens** — "If we built this from scratch knowing only the requirements, what would we build?"
-2. **Constraint-removal lens** — "If [constraint] didn't exist, what's the best solution? Now how do we get closer to it?"
-3. **Analogy lens** — "How does [analogous problem domain] solve this?"
-4. **Inversion lens** — "What would make this maximally bad? Now invert each item."
-5. **Extreme lens** — "What's the simplest possible approach? What's the most powerful?"
-6. **Time lens** — "What solution would we regret not choosing in 2 years?"
-
-**Target:** 6-12 distinct ideas before evaluation. If you have fewer than 5, you've stopped too early.
-
-**Divergence output format:**
-
-```markdown
-## Idea 1: [Name]
-[2-3 sentences: what it is, how it works, why it might be good]
-Rough feasibility: [High/Medium/Low]
-
-## Idea 2: [Name]
-...
-```
-
-### Phase 2: Rapid Pre-Filter
-
-After divergence, apply a quick filter before full evaluation:
-
-**Pre-filter criteria:**
-- Feasible within current constraints? (Hard blocker: eliminate)
-- Reversible if wrong? (Irreversible = higher bar to choose)
-- Team can execute? (Skill gap = risk, not elimination)
-
-Eliminate only ideas that fail hard feasibility. Keep everything else — your "bad" ideas might combine with your "good" ones.
-
-### Phase 3: Evaluate Remaining Ideas
-
-For each surviving idea, score on:
-
-| Criterion | Weight | Description |
-|-----------|--------|-------------|
-| Correctness | 30% | Solves the actual problem completely |
-| Maintainability | 20% | Team can reason about and change it |
-| Performance | 15% | Meets performance requirements |
-| Reversibility | 15% | Can be undone if wrong |
-| Time to implement | 10% | Fits within timeline constraint |
-| Risk | 10% | Known unknowns and failure modes |
-
-**Scoring:** 1-5 per criterion. Weighted total = decision score.
-
-This scoring is a forcing function, not a formula. If the scores conflict with your gut, investigate the gut feeling — it may be capturing a criterion you haven't named.
-
-### Phase 4: Convergence Decision
-
-**Select the highest-scoring idea** unless:
-- The second-highest is within 10% and significantly more reversible
-- The highest-scoring idea has an unmitigated risk that could invalidate the entire effort
-- The team has strong capability gaps that make the highest-scoring idea genuinely infeasible
-
-**Convergence output:**
-
-```markdown
-## Decision: [Idea Name]
-
-**Rationale:** [Why this over the alternatives]
-**Key trade-off accepted:** [What we're giving up and why that's okay]
-**Reversibility:** [Can we change this later? At what cost?]
-**Risk mitigations:**
-- [Risk 1]: [Mitigation]
-- [Risk 2]: [Mitigation]
-
-## Discarded Alternatives
-- [Idea N]: Eliminated because [specific reason]
-```
-
-The discarded alternatives section is important — it prevents re-litigating the same options in future discussions.
-
-### Phase 5: Spike Plan (if needed)
-
-If the winning idea has a technical unknown, plan a spike (time-boxed experiment):
-
-```markdown
-## Spike: Validate [unknown assumption]
-
-**Question:** [Specific question this spike answers]
-**Method:** [How to test it]
-**Time box:** [Maximum time, then decide based on results]
-**Pass criteria:** [What result confirms the approach is viable]
-**Fail criteria:** [What result means we choose the fallback]
-**Fallback:** [Idea #2 from the evaluation]
-```
-
-Spikes that don't have a fallback are bets, not spikes.
-
-## ClawPowers Enhancement
-
-When `~/.clawpowers/` runtime is initialized:
-
-**Cross-Session Idea Persistence:**
-
-Ideas don't disappear when the session ends:
-
-```bash
-# Save ideas from session
-bash runtime/persistence/store.sh set "brainstorm:auth-rate-limiting:idea1" "Token bucket with Redis"
-bash runtime/persistence/store.sh set "brainstorm:auth-rate-limiting:idea2" "Fixed window with DB"
-bash runtime/persistence/store.sh set "brainstorm:auth-rate-limiting:decision" "Token bucket with Redis"
-bash runtime/persistence/store.sh set "brainstorm:auth-rate-limiting:discarded" "Fixed window: stale at window boundary"
-
-# Recall in future session
-bash runtime/persistence/store.sh list "brainstorm:auth-rate-limiting:*"
-```
-
-This prevents re-debating decisions already made and provides context when the approach needs revisiting.
-
-**Pattern Linking:**
-
-After 10+ brainstorming sessions, `runtime/feedback/analyze.sh` identifies:
-- Which lenses generate the most pursued ideas (your most productive divergence strategies)
-- Common discarded idea reasons (helps pre-filter faster)
-- Idea-to-outcome correlation (were your decisions good?)
-
-**Idea Quality Tracking:**
-
-```bash
-bash runtime/metrics/collector.sh record \
-  --skill brainstorming \
-  --outcome success \
-  --notes "rate-limiting: 7 ideas, 1 spike, decision in 25 min"
-```
-
-After execution, mark whether the brainstorming decision held up:
-```bash
-bash runtime/persistence/store.sh set "brainstorm:auth-rate-limiting:outcome" "decision_held"
-# or
-bash runtime/persistence/store.sh set "brainstorm:auth-rate-limiting:outcome" "pivoted:reason"
-```
-
-This feeds the RSI loop — which ideas look good in brainstorming but fail in practice?
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It Fails | Correct Approach |
-|-------------|-------------|-----------------|
-| Evaluating during divergence | Kills combination ideas before they form | Strict phase separation |
-| Stopping at 2-3 ideas | First ideas are obvious; breakthroughs are later | Force 6-12 before evaluating |
-| Skipping the spike | Unknown assumption bites you mid-implementation | Spike anything technically uncertain |
-| No fallback on spike | If spike fails, you're stuck | Always name the fallback before spiking |
-| Consensus brainstorming | Group thinks converges to average | Diverge individually, converge together |
-| Re-opening decided questions | Litigating old decisions halts progress | Document discarded alternatives with reasons |
-| Brainstorming without constraints | Unconstrained ideas aren't implementable | State constraints at the start of divergence |
-
-## Examples
-
-### Example 1: Architecture Decision
-
-**Question:** How should we handle cross-service communication?
-
-**Divergence:**
-1. REST HTTP calls (synchronous, direct)
-2. Message queue (async, decoupled) — Kafka, RabbitMQ, Redis Streams
-3. gRPC (typed, fast, binary protocol)
-4. GraphQL federation
-5. Event sourcing + event bus
-6. Shared database (anti-pattern but option)
-7. Service mesh with mTLS (Istio)
-
-**Pre-filter:** Option 6 (shared DB) eliminated — violates service isolation. All others survive.
-
-**Evaluation scores:** REST: 72pts | Message queue: 85pts | gRPC: 78pts | Others < 70pts
-
-**Decision:** Message queue (Kafka) — highest score, fully decoupled, reversible per service.
-
-**Spike:** Can our team operate Kafka? → 2-hour spike → yes, managed Confluent resolves ops burden.
-
-### Example 2: Feature Design
-
-**Question:** How should users specify recurring events?
-
-**Divergence (constraint-removal):**
-1. cron syntax (powerful, opaque to non-technical users)
-2. Natural language parser ("every Monday at 9am")
-3. Visual calendar picker (intuitive, limited power)
-4. RRULE (RFC 5545 standard, complex)
-5. Predefined presets + custom exception
-6. Wizard with structured questions
-
-**Convergence:** Option 5 (presets + exceptions) — covers 90% of cases simply, 10% with power.

package/skills/content-pipeline/SKILL.md

@@ -1,282 +0,0 @@
----
-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 |