clawpowers 1.1.4 → 2.2.0

package/skills/test-driven-development/SKILL.md

@@ -1,416 +0,0 @@
----
-name: test-driven-development
-description: Enforce RED-GREEN-REFACTOR with mandatory failure witness. Activate whenever writing new code, implementing a feature, or fixing a bug with a reproducible test case.
-version: 1.0.0
-requires:
-  tools: [bash]
-  runtime: false
-metrics:
-  tracks: [red_witnessed, green_achieved, refactor_cycles, mutation_score, test_effectiveness]
-  improves: [test_granularity, refactor_threshold, mutation_analysis_frequency]
----
-
-# Test-Driven Development
-
-## When to Use
-
-Apply this skill when:
-
-- Implementing any new feature or function
-- Fixing a bug that has a reproducible failure condition
-- Refactoring code where behavior must be preserved
-- Building an API endpoint, utility function, or module
-- Implementing a specification with defined inputs and outputs
-
-**Skip when:**
-- Exploratory prototyping where the interface isn't known yet (write the prototype, then TDD the real implementation)
-- One-off scripts with no production path
-- Pure configuration changes (infrastructure, env vars, YAML)
-
-**Decision tree:**
-```
-Do you know what correct behavior looks like?
-├── No  → Explore/prototype first, then TDD the real version
-└── Yes → Do you have a reproducible failure condition?
-          ├── Yes (bug fix) → TDD from the failing test
-          └── No (new feature) → TDD from the spec → RED-GREEN-REFACTOR
-```
-
-## Core Methodology
-
-### The Laws of TDD
-
-1. You may not write production code unless it is to make a failing test pass.
-2. You may not write more of a unit test than is sufficient to fail (compilation failures count as failures).
-3. You may not write more production code than is sufficient to pass the currently failing test.
-
-These are not suggestions. Violations produce code that is tested after the fact — which is not TDD.
-
-### The RED Phase
-
-**Objective:** Write a test that fails for the right reason.
-
-```
-Step 1: Write the test before any production code exists
-Step 2: Run the test suite
-Step 3: WITNESS the failure — read the actual error message
-Step 4: Confirm the failure is the expected one (not a compile error, not a wrong import)
-```
-
-**Failure witness requirement:** You must see the test runner output showing failure. Copy-pasting the expected error is not sufficient — run it.
-
-**Example (Python):**
-```python
-# test_auth.py — write this FIRST
-def test_jwt_issue_returns_token_with_expiry():
-    auth = AuthService(secret="test-secret")
-    result = auth.issue(user_id="u123", ttl_seconds=3600)
-    
-    assert result["token"] is not None
-    assert result["expires_at"] > time.time()
-    assert result["user_id"] == "u123"
-
-# Run and witness:
-# pytest test_auth.py::test_jwt_issue_returns_token_with_expiry
-# FAILED: ImportError: cannot import name 'AuthService' from 'auth'
-# ← This is the expected RED failure. Correct.
-```
-
-**What a bad RED looks like:**
-```
-# WRONG: Writing AuthService first, then the test
-# WRONG: Test passes on first run (you tested nothing)
-# WRONG: Test fails with wrong error (syntax error in test, not missing implementation)
-```
-
-### The GREEN Phase
-
-**Objective:** Write the minimum production code to make the test pass.
-
-```
-Step 1: Write only what the test requires — nothing more
-Step 2: No edge case handling beyond what the test covers
-Step 3: Run the test suite
-Step 4: WITNESS the green — all targeted tests pass
-Step 5: If other tests broke, fix them (don't disable them)
-```
-
-**Minimum code principle:** If the test only checks that `add(2, 3)` returns `5`, write `return 5` if that makes it green. The next test will force generalization.
-
-**Example:**
-```python
-# auth.py — write this AFTER the test fails
-import jwt
-import time
-
-class AuthService:
-    def __init__(self, secret: str):
-        self.secret = secret
-    
-    def issue(self, user_id: str, ttl_seconds: int) -> dict:
-        now = time.time()
-        payload = {"sub": user_id, "iat": now, "exp": now + ttl_seconds}
-        token = jwt.encode(payload, self.secret, algorithm="HS256")
-        return {"token": token, "expires_at": now + ttl_seconds, "user_id": user_id}
-
-# Run and witness:
-# pytest test_auth.py::test_jwt_issue_returns_token_with_expiry
-# PASSED
-```
-
-### The REFACTOR Phase
-
-**Objective:** Improve code structure without changing behavior.
-
-```
-Step 1: All tests must be green BEFORE refactoring begins
-Step 2: Identify: duplication, poor naming, complex conditionals, missing abstractions
-Step 3: Refactor ONE thing at a time
-Step 4: Run full test suite after each change
-Step 5: If tests break, revert immediately (don't debug during refactor)
-Step 6: Refactor test code too — tests are first-class code
-```
-
-**What belongs in REFACTOR:**
-- Extract repeated logic into helper functions
-- Rename variables/functions for clarity
-- Simplify nested conditionals
-- Add type annotations
-- Break long functions into smaller ones
-- Move related code into a class
-
-**What does NOT belong in REFACTOR:**
-- New functionality (that's the next RED phase)
-- Performance optimization (benchmark first, optimize second)
-- Changing behavior "while you're in there"
-
-### The Cycle
-
-```
-RED (5-15 min) → GREEN (5-30 min) → REFACTOR (5-20 min) → RED...
-```
-
-Each cycle covers ONE behavior. Not a feature — one behavior of a feature.
-
-For `AuthService`, the full TDD cycle would be:
-1. RED/GREEN/REFACTOR: `issue()` returns token
-2. RED/GREEN/REFACTOR: `issue()` handles invalid user_id
-3. RED/GREEN/REFACTOR: `validate()` returns valid for good token
-4. RED/GREEN/REFACTOR: `validate()` returns invalid for expired token
-5. RED/GREEN/REFACTOR: `validate()` returns invalid for tampered token
-6. RED/GREEN/REFACTOR: `issue()` and `validate()` work end-to-end
-
-### Test Naming Convention
-
-Tests are documentation. Name them:
-```
-test_[unit]_[action]_[expected_result]
-test_jwt_issue_with_negative_ttl_raises_value_error()
-test_jwt_validate_expired_token_returns_invalid_with_reason()
-test_jwt_validate_tampered_token_returns_invalid_with_reason()
-```
-
-Not:
-```
-test_1()
-test_auth()
-test_jwt_token_stuff()
-```
-
-### Testing Layers
-
-| Layer | What It Tests | Tool |
-|-------|-------------|------|
-| Unit | Single function, isolated | pytest, jest, go test |
-| Integration | Multiple units together | pytest with real DB |
-| Contract | API interface compliance | pact, dredd |
-| E2E | Full system path | playwright, cypress |
-
-TDD applies at all layers. Start with unit. Add integration when units pass.
-
-### Autonomous Mutation Testing
-
-After the REFACTOR phase is complete and all tests are green, run autonomous mutation testing to verify your tests actually catch bugs — not just pass on correct code.
-
-**The mutation testing loop:**
-
-```
-GREEN tests → generate mutants → run suite against each → calculate score → fix gaps → re-run
-```
-
-**Step 1: Generate mutants**
-
-Mutation tools automatically modify your production code in small ways to simulate bugs:
-
-| Mutation type | Example | What it tests |
-|--------------|---------|-------------|
-| Operator swap | `a > b` → `a >= b` | Off-by-one detection |
-| Condition removal | `if (valid && active)` → `if (active)` | Guard clause tests |
-| Return value swap | `return true` → `return false` | Output assertion coverage |
-| Constant mutation | `ttl = 3600` → `ttl = 0` | Boundary value tests |
-| Statement deletion | Remove a line entirely | Whether tests catch missing logic |
-
-**Step 2: Run mutation tools**
-
-```bash
-# Python: mutmut
-pip install mutmut
-mutmut run --paths-to-mutate src/ --tests-dir tests/
-mutmut results  # shows surviving (undetected) mutants
-
-# JavaScript/TypeScript: Stryker
-npx stryker run
-# Stryker generates a detailed HTML report with surviving mutants
-
-# Go: go-mutesting
-go install github.com/zimmski/go-mutesting/cmd/go-mutesting@latest
-go-mutesting ./...
-
-# Java: PIT
-mvn org.pitest:pitest-maven:mutationCoverage
-```
-
-**Step 3: Calculate and interpret the mutation score**
-
-```
-mutation score = (killed mutants / total mutants) × 100
-```
-
-| Score | Assessment | Action |
-|-------|-----------|--------|
-| ≥ 90% | Excellent | No action needed |
-| 80–89% | Good | Review surviving mutants; add 1-2 targeted tests |
-| 70–79% | Marginal | Systematic gap; add boundary and error-path tests |
-| < 70% | Poor | Tests exist but don't assert enough; add failing-case coverage |
-
-**Step 4: Kill surviving mutants**
-
-For each surviving mutant, the tool shows what change it made. Write a test that would catch that bug:
-
-```python
-# Stryker report shows this mutant survived:
-# Original:  if score >= passing_threshold:
-# Mutant:    if score > passing_threshold:
-
-# Write a test that detects the off-by-one:
-def test_score_at_exact_threshold_passes():
-    # This test kills the >= vs > mutant
-    assert grade(score=passing_threshold) == "pass"
-    assert grade(score=passing_threshold - 1) == "fail"
-```
-
-```typescript
-// Stryker shows this mutant survived:
-// Original:  return { token, expiresAt, userId }
-// Mutant:    return { token, expiresAt, userId: "" }
-
-// Write a test that kills it:
-test('issue() returns correct userId in payload', () => {
-  const result = auth.issue('user-abc', 3600);
-  expect(result.userId).toBe('user-abc');  // was not previously asserted!
-});
-```
-
-**Step 5: Iterate until score ≥ 80%**
-
-```bash
-# After adding new tests, re-run to measure improvement
-mutmut run --paths-to-mutate src/ --tests-dir tests/
-NEW_SCORE=$(mutmut results | grep "Killed" | awk '{print $2/$4 * 100}')
-echo "Mutation score: $NEW_SCORE%"
-```
-
-**Tracking mutation scores over time:**
-
-```bash
-# Record in ClawPowers metrics after each TDD cycle
-MUTATION_SCORE=87
-bash runtime/metrics/collector.sh record \
-  --skill test-driven-development \
-  --outcome success \
-  --notes "AuthService: RED×6 witnessed, mutation_score=$MUTATION_SCORE%, 0 surviving mutants after 2 additions"
-```
-
-The TDD cycle with mutation testing:
-
-```
-RED → GREEN → REFACTOR → MUTATE → [score < 80%? → KILL SURVIVORS → RE-MUTATE] → done
-```
-
-## ClawPowers Enhancement
-
-When `~/.clawpowers/` runtime is initialized:
-
-**Mutation Score History:**
-
-```bash
-# Query historical mutation scores
-bash runtime/persistence/store.sh list "tdd:mutation:*" | sort
-# Shows trend: if scores are declining, tests are growing but not keeping up with code complexity
-```
-
-**Mutation Analysis Integration:**
-
-After the GREEN phase, optionally run mutation analysis to verify your tests actually catch bugs — not just pass on correct code:
-
-```bash
-# Python: mutmut
-pip install mutmut
-mutmut run --paths-to-mutate src/auth.py --tests-dir tests/
-
-# JavaScript: Stryker
-npx stryker run
-
-# Go: go-mutesting
-go-mutesting ./...
-```
-
-Mutation score target: ≥ 80%. Below 70% means your tests would miss real bugs.
-
-**Test Portfolio Lifecycle Tracking:**
-
-```bash
-bash runtime/metrics/collector.sh record \
-  --skill test-driven-development \
-  --outcome success \
-  --notes "AuthService: 6 behaviors, mutation score 87%, 0 stubs"
-```
-
-**Effectiveness Scoring:**
-
-`runtime/feedback/analyze.sh` computes per-feature test effectiveness based on:
-- Mutation score
-- Number of RED phases witnessed (vs skipped)
-- Time from RED to GREEN (indicates test complexity)
-- Defect rate post-merge (bugs found in production = test misses)
-
-Skills with declining effectiveness scores trigger recommendations:
-- If mutation score < 70%: add boundary and error case tests
-- If RED skipped: review test authoring process
-- If GREEN > 60 min: tests are too coarse, decompose
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It Fails | Correct Approach |
-|-------------|-------------|-----------------|
-| Write tests after code | Tests are biased toward existing implementation | Tests must be written first — that's the definition |
-| Skip the failure witness | Tests may pass vacuously (wrong assertion, wrong import) | Run the suite, read the failure message |
-| Test implementation details | Tests break on refactor | Test behavior/interface, not internal state |
-| One giant test | Hard to diagnose failures | One test per behavior |
-| Mocking everything | Tests pass but real system fails | Mock only at true system boundaries (network, DB, time) |
-| Skip REFACTOR | Technical debt accumulates | REFACTOR is mandatory, not optional |
-| Write all tests upfront | Spec changes invalidate all tests | Write tests incrementally, one behavior at a time |
-| Disable failing tests | Silences real bugs | Fix the code, never disable the test |
-
-## Examples
-
-### Example 1: Pure Function (simplest case)
-
-```python
-# RED
-def test_celsius_to_fahrenheit_converts_correctly():
-    assert convert_temp(0, "celsius", "fahrenheit") == 32.0
-    assert convert_temp(100, "celsius", "fahrenheit") == 212.0
-
-# GREEN
-def convert_temp(value, from_unit, to_unit):
-    if from_unit == "celsius" and to_unit == "fahrenheit":
-        return value * 9/5 + 32
-    raise ValueError(f"Unsupported conversion: {from_unit} → {to_unit}")
-
-# REFACTOR → add UNIT_CONVERTERS dict, extract conversion logic
-```
-
-### Example 2: Side-effecting Code
-
-```python
-# RED — test the effect, not the implementation
-def test_user_created_event_emitted_on_signup(event_bus):
-    service = UserService(db=FakeDB(), events=event_bus)
-    service.signup(email="a@b.com", password="secure123")
-    
-    assert event_bus.has_event("user.created")
-    assert event_bus.last_event("user.created")["email"] == "a@b.com"
-
-# Note: FakeDB is a test double for the DB boundary
-# event_bus is a test double for the event system boundary
-# The UserService logic itself is real — no mocking of it
-```
-
-### Example 3: Bug Fix
-
-```python
-# Reproduce the bug first
-def test_cart_total_with_discount_code_not_negative():
-    cart = Cart()
-    cart.add_item(price=10.00, qty=1)
-    cart.apply_discount(code="HALF_OFF")
-    cart.apply_discount(code="HALF_OFF")  # applying twice — the bug
-    
-    assert cart.total() >= 0.0  # was returning -5.00
-
-# Run → FAIL (reproduces the bug)
-# Fix the bug
-# Run → PASS
-# Now the bug is regression-protected
-```

package/skills/using-clawpowers/SKILL.md

@@ -1,160 +0,0 @@
----
-name: using-clawpowers
-description: Meta-skill explaining ClawPowers, available skills, and how to trigger them. Auto-injected at session start.
-version: 1.0.0
-requires:
-  tools: []
-  runtime: false
-metrics:
-  tracks: [session_starts, skill_activations, platform]
-  improves: [onboarding_clarity, trigger_accuracy]
----
-
-# ClawPowers — Skills Framework
-
-## When to Use
-
-This skill activates automatically at session start. You never invoke it manually.
-
-- **Session start:** Injected by the session hook to provide skill discovery
-- **New user onboarding:** Reference this document when unsure which skill applies
-- **Skill lookup:** Check the trigger map below to find the right skill for your task
-
-## Core Methodology
-
-ClawPowers follows a three-layer approach:
-
-1. **Pattern Recognition** — Match your current task to a skill via the trigger map
-2. **Skill Application** — Read the matched skill's SKILL.md and follow its methodology
-3. **Outcome Tracking** — If runtime is available, record execution outcomes for self-improvement
-
-
-You have ClawPowers loaded. This gives you 24 skills that go beyond static instructions — they execute tools, persist state across sessions, and track outcomes for self-improvement. The RSI Intelligence Layer (skills 21-24) enables the agent to improve its own methodology over time.
-
-## How Skills Work
-
-Skills activate automatically when you recognize a matching task pattern. You don't announce them. You just apply them.
-
-**Pattern → Skill mapping:**
-
-| When you encounter... | Apply this skill |
-|----------------------|-----------------|
-| A complex task that should be broken into parallel workstreams | `subagent-driven-development` |
-| Writing new code, any feature | `test-driven-development` |
-| A request to plan work | `writing-plans` |
-| Executing a plan that already exists | `executing-plans` |
-| "What should we do about X?" or ideation needed | `brainstorming` |
-| A bug, unexpected behavior, or error | `systematic-debugging` |
-| About to complete, merge, or hand off work | `verification-before-completion` |
-| Done with a feature branch, need to merge | `finishing-a-development-branch` |
-| Need someone else to review the code | `requesting-code-review` |
-| Received code review feedback | `receiving-code-review` |
-| Working on multiple branches simultaneously | `using-git-worktrees` |
-| Need to create a new skill | `writing-skills` |
-| Multiple independent tasks that can run concurrently | `dispatching-parallel-agents` |
-| Making a payment or calling a paid API | `agent-payments` |
-| "setup payments" / "enable wallet" / "configure spending" | `agent-payments` → `npx clawpowers payments setup` |
-| "demo x402" / "test payments" / "mock merchant" | `npx clawpowers demo x402` |
-| "payment log" / "spending history" | `npx clawpowers payments log` |
-| Checking code/containers for vulnerabilities | `security-audit` |
-| Writing blog posts, docs, or social content | `content-pipeline` |
-| Need to understand how to learn something effectively | `learn-how-to-learn` |
-| Competitive research or trend analysis | `market-intelligence` |
-| Finding leads or prospects | `prospecting` |
-| Task counter hits 50; skill success rates declining | `meta-skill-evolution` |
-| Test suite fails; want automatic patch-and-commit | `self-healing-code` |
-| Starting a task; want to check cross-project patterns first | `cross-project-knowledge` |
-| After fixing a bug or architecture decision; want to store the pattern | `cross-project-knowledge` |
-| TDD GREEN phase complete; want invariant property tests | `formal-verification-lite` |
-| Need roundtrip/idempotence/commutativity tests for a pure function | `formal-verification-lite` |
-| Complex task where premium resources would improve quality | `economic-code-optimization` |
-| Deciding whether to pay for expert review or premium model | `economic-code-optimization` |
-| Hiring another agent to complete a task with payment escrow | `agent-bounties` |
-| Want skin-in-the-game guarantees before a multi-agent task | `agent-bounties` |
-
-## Reading a Skill
-
-Skills are in `skills/<skill-name>/SKILL.md`. Read them with:
-
-```bash
-# From repo root
-cat skills/systematic-debugging/SKILL.md
-```
-
-Or reference them by path in your context: `skills/systematic-debugging/SKILL.md`
-
-## Runtime Layer
-
-If the runtime is initialized (`~/.clawpowers/` exists), skills can:
-
-1. **Persist state** — `runtime/persistence/store.sh get|set|list`
-2. **Track outcomes** — `runtime/metrics/collector.sh` appends JSON lines
-3. **Analyze performance** — `runtime/feedback/analyze.sh` computes success rates
-
-Check if runtime is available:
-```bash
-[ -d ~/.clawpowers ] && echo "runtime available" || echo "static mode"
-```
-
-Initialize runtime:
-```bash
-npx clawpowers init
-# or directly:
-bash runtime/init.sh
-```
-
-## Graceful Degradation
-
-Skills work in two modes:
-
-- **Static mode** (no runtime): Skills provide methodology guidance. Same capability as competing frameworks.
-- **Runtime mode** (`~/.clawpowers/` initialized): Full capability — persistence, metrics, RSI feedback, resumable workflows.
-
-You never need to check the mode. Skills detect it themselves and adapt their instructions accordingly.
-
-## Anti-Patterns
-
-- **Don't announce skill usage** — Apply the skill silently, don't say "I'm now using the systematic-debugging skill"
-- **Don't read the skill on every step** — Read once, apply throughout
-- **Don't stack conflicting skills** — If TDD and subagent-driven-development both apply, let subagent-driven-development drive; it includes TDD internally
-- **Don't ignore ClawPowers enhancements** — When the runtime is available, use it; the static path is a fallback, not the goal
-
-## Quick Reference: All 24 Skills
-
-### Core Development (14)
-1. `subagent-driven-development` — Parallel subagents, two-stage review, worktree isolation
-2. `test-driven-development` — RED-GREEN-REFACTOR with failure witness and autonomous mutation testing
-3. `writing-plans` — Spec to sequenced 2-5 min tasks with dependency graph
-4. `executing-plans` — Tracked execution with resumability and milestone persistence
-5. `brainstorming` — Structured ideation with convergence protocol
-6. `systematic-debugging` — Hypothesis-driven debugging with persistent hypothesis memory
-7. `verification-before-completion` — Quality gates before any merge or handoff
-8. `finishing-a-development-branch` — Branch cleanup, changelog, squash, merge prep
-9. `requesting-code-review` — Review request with context, risk areas, reviewer matching
-10. `receiving-code-review` — Constructive processing, pattern database, response protocol
-11. `using-git-worktrees` — Isolated parallel branch development
-12. `using-clawpowers` — This document
-13. `writing-skills` — TDD for skills: test scenarios → fail → write skill → pass
-14. `dispatching-parallel-agents` — Fan-out execution, load balancing, result aggregation
-
-### Extended Capabilities (6)
-15. `agent-payments` — x402 payment protocol, non-custodial wallets, spending limits
-16. `security-audit` — Trivy, gitleaks, npm audit, bandit — actionable report output
-17. `content-pipeline` — Write → humanize → format → publish workflow
-18. `learn-how-to-learn` — 5-layer learning stack, 14 anti-patterns, confidence calibration
-19. `market-intelligence` — Competitive analysis, trend detection, opportunity scoring
-20. `prospecting` — ICP → company search → contact enrichment → outreach prep
-
-### RSI Intelligence Layer (4) — NEW
-21. `meta-skill-evolution` — Every 50 tasks: analyze outcomes, find weakest skill, surgically improve it, commit with version bump
-22. `self-healing-code` — Test failure → hypothesis tree → ≥2 candidate patches → auto-commit winner or escalate
-23. `cross-project-knowledge` — Persistent pattern KB across all projects; search before tasks, store after fixes
-24. `formal-verification-lite` — Property-based testing (fast-check/Hypothesis) after TDD GREEN; 1000+ iterations per invariant
-25. `economic-code-optimization` — Autonomously spend micro-budgets on premium models, compute, expert reviews when ROI justifies it
-
-### Agent Economy Layer (1) — NEW
-26. `agent-bounties` — Post tasks with USDC rewards, escrow both-party collateral via MutualStakeEscrow, verify with automation, release or dispute on-chain
-
-## Session Initialization Complete
-
-ClawPowers is ready. 26 skills active. Skills activate on pattern recognition. Runtime enhancements available when `~/.clawpowers/` exists. RSI Intelligence Layer (meta-skill-evolution, self-healing-code, cross-project-knowledge, formal-verification-lite) provides persistent learning across sessions and projects. Agent Economy Layer (agent-bounties) enables autonomous agent-to-agent hiring with on-chain escrow.