clawpowers 1.1.4 → 2.2.0

package/skills/economic-code-optimization/SKILL.md

@@ -1,265 +0,0 @@
----
-name: economic-code-optimization
-description: Autonomously allocate micro-budgets to improve code quality - premium models, cloud compute, expert reviews, specialized tools. ROI-tracked spending that compounds agent performance over time.
-version: 1.0.0
-requires:
-  tools: []
-  runtime: true
-  skills: [agent-payments]
-metrics:
-  tracks: [spend_decisions, amount_spent, roi_ratio, quality_delta, upgrades_purchased]
-  improves: [spend_efficiency, roi_accuracy, tier_selection, budget_utilization]
----
-
-# Economic Code Optimization
-
-## When to Use
-
-Apply this skill when:
-
-- A task is complex enough (estimated 2+ hours) that premium resources would meaningfully improve quality or speed
-- Confidence is low on a critical PR and a paid expert review would catch issues you'd miss
-- Mutation testing or formal verification needs more compute than the local machine provides
-- An external API or tool (static analyzer, security scanner, profiler) would produce better results than manual inspection
-- The task has high business value and the cost of a bug outweighs the cost of premium resources
-
-Do NOT use when:
-- The task is routine (simple CRUD, config changes, docs updates)
-- The owner hasn't configured spending limits in `~/.clawpowers/config.json`
-- The wallet balance is below the minimum threshold
-- The task value doesn't justify any spend (ROI would be negative)
-
-## Background: Why Agents Should Spend Money on Code
-
-Static frameworks assume all resources are equal. They're not.
-
-A $0.003 API call to a premium static analyzer catches bugs that 200 lines of manual review miss. A $0.10 GPU burst runs 10,000 mutation tests in 30 seconds instead of 20 minutes locally. A $2.00 expert review on a security-critical PR prevents a $200,000 vulnerability.
-
-The question isn't whether to spend. It's how much, on what, and whether the ROI justifies it. This skill makes that decision automatically, within hard limits the owner controls.
-
-## Setup
-
-### Configure Spending Limits
-
-Create or update `~/.clawpowers/config.json`:
-
-```json
-{
-  "economic_optimization": {
-    "enabled": true,
-    "global_daily_limit_usd": 5.00,
-    "per_task_max_usd": 1.00,
-    "min_task_value_usd": 50.00,
-    "auto_approve_below_usd": 0.10,
-    "require_owner_approval_above_usd": 2.00,
-    "allowed_categories": ["premium_model", "compute", "static_analysis", "security_scan", "expert_review"]
-  }
-}
-```
-
-If no config exists, the skill operates in dry-run mode - it calculates what it would spend and logs the decision, but doesn't execute any payments.
-
-### Verify Prerequisites
-
-```bash
-# Check that agent-payments skill is available
-npx clawpowers store get "skill:agent-payments:configured"
-
-# Check wallet balance (if configured)
-npx clawpowers store get "wallet:balance:usd"
-```
-
-## Core Methodology
-
-### Step 1: Task Value Assessment
-
-Before any spend decision, estimate the task's business value. Be conservative.
-
-**Value heuristics:**
-
-| Task Type | Estimated Value | Rationale |
-|-----------|----------------|-----------|
-| Security-critical fix | $500-5,000 | Vulnerability cost if shipped |
-| Core business logic | $200-1,000 | Revenue impact of bugs |
-| Public API change | $100-500 | Breaking changes affect users |
-| Performance optimization | $50-200 | Compute savings over time |
-| Internal tooling | $20-100 | Developer time savings |
-| Docs/config changes | $5-20 | Low risk, low impact |
-
-Record the assessment:
-
-```bash
-npx clawpowers store set "eco:${TASK_ID}:estimated_value" "500"
-npx clawpowers store set "eco:${TASK_ID}:task_type" "security-critical"
-```
-
-### Step 2: Spend Tier Calculation
-
-Calculate the optimal spend as a percentage of task value:
-
-```
-spend_budget = min(task_value * spend_ratio, per_task_max)
-
-Spend ratios by complexity:
-  Simple (1-3):   0% - no spend needed
-  Medium (4-6):   0.5% of task value
-  Complex (7-8):  2% of task value  
-  Critical (9-10): 5% of task value
-```
-
-**Decision tree:**
-
-1. Is `economic_optimization.enabled` true? If no, stop.
-2. Is `estimated_value >= min_task_value_usd`? If no, stop - task too small to justify spend.
-3. Calculate `spend_budget` using complexity ratio.
-4. Is `spend_budget < auto_approve_below_usd`? If yes, proceed automatically.
-5. Is `spend_budget > require_owner_approval_above_usd`? If yes, queue for approval and continue with base resources.
-6. Otherwise, proceed with spend.
-
-Record the decision:
-
-```bash
-npx clawpowers store set "eco:${TASK_ID}:spend_tier" "medium"
-npx clawpowers store set "eco:${TASK_ID}:budget_usd" "0.50"
-npx clawpowers store set "eco:${TASK_ID}:approved" "auto"
-```
-
-### Step 3: Resource Allocation
-
-Based on the budget, select upgrades from this priority list:
-
-**Tier 1: Free optimizations (always apply)**
-- Use cached results from `cross-project-knowledge` pattern library
-- Apply known-good patterns from previous projects
-- Run local linters and type checkers
-
-**Tier 2: Micro-spend ($0.01-0.10)**
-- Premium static analysis API call (Semgrep Pro, SonarCloud)
-- Extended mutation testing run (2x-5x normal iterations)
-- Dependency vulnerability deep scan
-
-**Tier 3: Small spend ($0.10-1.00)**
-- Cloud GPU burst for heavy formal verification (1000+ property tests)
-- Premium model API call for complex code review (Claude Opus, GPT-4o)
-- Performance profiling service for optimization tasks
-
-**Tier 4: Significant spend ($1.00-5.00)**
-- Paid expert review routing for security-critical PRs
-- Multi-model consensus (run 3 premium models, majority vote on approach)
-- Extended cloud compute for exhaustive test generation
-
-Record allocations:
-
-```bash
-npx clawpowers store set "eco:${TASK_ID}:allocations" "premium_model,mutation_testing_5x"
-```
-
-### Step 4: Execute Spend
-
-Use the `agent-payments` skill for all financial transactions. Never bypass spending limits.
-
-```bash
-# Record the spend decision
-npx clawpowers metrics record \
-  --skill economic-code-optimization \
-  --outcome success \
-  --duration 0 \
-  --notes "Allocated $0.50: premium model ($0.30) + extended mutation testing ($0.20) for task ${TASK_ID}"
-```
-
-For each purchased resource, track what was bought and the immediate result:
-
-```bash
-npx clawpowers store set "eco:${TASK_ID}:purchase:premium_model:cost" "0.30"
-npx clawpowers store set "eco:${TASK_ID}:purchase:premium_model:result" "3 additional edge cases identified"
-npx clawpowers store set "eco:${TASK_ID}:purchase:mutation_5x:cost" "0.20"
-npx clawpowers store set "eco:${TASK_ID}:purchase:mutation_5x:result" "mutation score 72% -> 91%"
-```
-
-### Step 5: Measure ROI
-
-After the task completes, calculate actual return on investment:
-
-```
-roi = (quality_improvement_value + time_saved_value) / amount_spent
-
-Quality improvement value:
-  - Bugs caught before merge × estimated bug cost = quality value
-  - Mutation score improvement × coverage confidence factor
-
-Time saved value:
-  - Hours saved by premium resources × hourly rate
-```
-
-Record ROI:
-
-```bash
-npx clawpowers store set "eco:${TASK_ID}:roi" "4.2"
-npx clawpowers store set "eco:${TASK_ID}:bugs_caught" "3"
-npx clawpowers store set "eco:${TASK_ID}:time_saved_min" "45"
-
-npx clawpowers metrics record \
-  --skill economic-code-optimization \
-  --outcome success \
-  --duration 2700 \
-  --notes "ROI 4.2x: spent $0.50, saved ~$2.10 (3 bugs caught pre-merge, 45 min saved)"
-```
-
-### Step 6: Feed Back to Meta-Skill-Evolution
-
-After 10+ economic optimization cycles, patterns emerge:
-
-- Which spend categories produce the highest ROI?
-- What's the optimal spend ratio for each task complexity level?
-- Are certain tools/services consistently worth their cost?
-- Where is the agent over-spending or under-spending?
-
-The `meta-skill-evolution` skill picks up these patterns and adjusts the spend ratios automatically. After 50 cycles, the agent's spending becomes highly efficient - it knows exactly when premium resources pay for themselves.
-
-```bash
-# The meta-skill-evolution cycle reads this data automatically
-npx clawpowers store list "eco:" | head -20
-```
-
-## ClawPowers Enhancement
-
-This skill requires runtime persistence. Without `~/.clawpowers/`:
-- Spend decisions can't reference historical ROI
-- The agent can't learn which purchases are worthwhile
-- Budget tracking across sessions is impossible
-
-With runtime:
-- Full spend history with ROI tracking
-- Automatic spend ratio optimization over time
-- Cross-project spend intelligence (some tools are worth it for all projects)
-- Budget compliance verification
-
-## Anti-Patterns
-
-1. **Spending on every task.** Most tasks don't need premium resources. The skill should result in $0 spend on 70%+ of tasks.
-
-2. **Ignoring ROI data.** If a spend category consistently produces ROI < 1.0, stop spending on it. The data is there - use it.
-
-3. **Over-spending on low-value tasks.** A $2 expert review on a README typo fix is waste. The `min_task_value_usd` threshold exists for a reason.
-
-4. **Bypassing spending limits.** Never modify `config.json` programmatically to increase limits. Only the owner adjusts caps.
-
-5. **Spending without tracking.** Every cent spent must be recorded with task ID, category, amount, and result. Untracked spend is unaccountable spend.
-
-6. **Assuming spend equals quality.** Premium resources help, but they don't replace good methodology. Always apply free optimizations (Tier 1) first. Spend only when free options are insufficient.
-
-## Dry-Run Mode
-
-When `economic_optimization.enabled` is false or the config doesn't exist, the skill runs in observation mode:
-
-- Calculates what it would spend on each task
-- Logs hypothetical ROI based on task outcomes
-- After 20+ dry-run cycles, the agent can show the owner: "Here's what I would have spent and the estimated ROI"
-- Owner can then enable with confidence, knowing the agent's spending judgment is calibrated
-
-## References
-
-- `agent-payments` skill: payment execution and wallet interaction
-- `meta-skill-evolution` skill: automatic spend ratio optimization
-- `agentwallet-sdk` v6.0: non-custodial wallets, spending policies, x402 protocol
-- ERC-6551: token-bound accounts with smart-contract spending enforcement

package/skills/executing-plans/SKILL.md

@@ -1,255 +0,0 @@
----
-name: executing-plans
-description: Execute an existing plan with progress tracking, interruption recovery, and milestone verification. Activate when you have a written plan and are ready to implement it.
-version: 1.0.0
-requires:
-  tools: [bash, git]
-  runtime: false
-metrics:
-  tracks: [tasks_completed, rework_rate, interruption_recovery_time, milestone_hit_rate]
-  improves: [task_sequencing, checkpoint_frequency, verification_rigor]
----
-
-# Executing Plans
-
-## When to Use
-
-Apply this skill when:
-
-- You have a written plan (from `writing-plans` or equivalent) ready to execute
-- Executing a multi-task sequence where progress matters
-- You need to be able to pause and resume without losing context
-- You're executing work that someone else is tracking
-
-**Skip when:**
-- You don't have a plan yet (use `writing-plans` first)
-- The task is a single step (just execute it)
-- You're mid-execution and don't need the overhead
-
-**Relationship to other skills:**
-```
-writing-plans → executing-plans → verification-before-completion → finishing-a-development-branch
-```
-
-## Core Methodology
-
-### Pre-Execution Setup
-
-Before executing the first task:
-
-1. **Read the full plan** — Don't start mid-plan. Read it completely.
-2. **Verify preconditions** — All inputs for Task 1 must exist. If they don't, stop and get them.
-3. **Create execution checkpoint** — Save plan state to resume on interruption.
-4. **Identify parallel tasks** — Group concurrent tasks from the dependency graph.
-
-**Checkpoint structure (file-based, no runtime required):**
-```json
-{
-  "plan_name": "auth-service",
-  "started_at": "2026-03-21T14:00:00Z",
-  "tasks": {
-    "1": {"status": "pending"},
-    "2": {"status": "pending"},
-    "3": {"status": "pending"}
-  },
-  "current_task": null
-}
-```
-
-If runtime is available:
-```bash
-bash runtime/persistence/store.sh set "execution:plan_name" "auth-service"
-bash runtime/persistence/store.sh set "execution:task_1:status" "pending"
-```
-
-### Task Execution Loop
-
-For each task in the plan (in dependency order):
-
-**Step 1: Mark task in progress**
-```bash
-# With runtime
-bash runtime/persistence/store.sh set "execution:task_N:status" "in_progress"
-bash runtime/persistence/store.sh set "execution:task_N:started_at" "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-```
-
-**Step 2: Execute the task**
-- Follow the task spec exactly — scope, deliverables, done criteria
-- Do not expand scope ("while I'm here, I'll also...")
-- Do not shrink scope ("this is probably good enough...")
-
-**Step 3: Verify done criteria**
-
-Each done criterion must be checked explicitly:
-```
-Task 2 done criteria:
-- [ ] Repository layer exists at src/repos/user_repo.py → CHECK: file exists ✓
-- [ ] All repository tests pass → CHECK: pytest tests/test_user_repo.py → 8 passed ✓
-- [ ] No raw SQL in service layer → CHECK: grep "SELECT\|INSERT\|UPDATE" src/services/ → 0 results ✓
-```
-
-If any criterion fails: **stop, diagnose, fix, re-verify** — do not proceed to the next task.
-
-**Step 4: Mark task complete**
-```bash
-bash runtime/persistence/store.sh set "execution:task_N:status" "complete"
-bash runtime/persistence/store.sh set "execution:task_N:completed_at" "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-```
-
-**Step 5: Git commit the task output**
-
-Each completed task gets its own commit:
-```bash
-git add [task output files]
-git commit -m "feat(auth): implement UserRepository with connection pooling
-
-Task 2/8 of auth-service plan. Completes repository layer.
-All 8 repository tests passing. Zero raw SQL in service layer."
-```
-
-This makes the plan's execution history visible in git log and enables rollback to any task boundary.
-
-### Handling Parallel Tasks
-
-When the plan identifies parallel tasks:
-
-1. Dispatch them concurrently (via `dispatching-parallel-agents` if agents, or concurrent execution)
-2. Wait for ALL parallel tasks to complete before proceeding
-3. Verify all parallel task done criteria before moving to dependent tasks
-4. If one parallel task fails, others continue — don't cancel them
-
-```
-parallel_group = [Task 1, Task 2]  # Both have no dependencies
-
-Execute Task 1 and Task 2 concurrently
-Wait for both → verify both → only then execute Task 3
-```
-
-### Milestone Verification
-
-At natural boundaries (end of a logical phase), run a milestone verification:
-
-1. All tasks in the phase are marked complete
-2. All done criteria are checked
-3. Integration between phase tasks is verified (not just individual tasks)
-4. Run any integration tests that cover the phase boundary
-
-**Example milestone:** After implementing the repository and service layers:
-```bash
-# Milestone: data layer complete
-pytest tests/ -k "repository or service"  # All must pass
-# Verify no circular imports
-python -c "from src.services.user import UserService"
-# Verify interface contracts
-python -m mypy src/repos/ src/services/
-```
-
-### Interruption Recovery
-
-If execution is interrupted (session ends, error halts, requirement change):
-
-**With runtime:**
-```bash
-# On resume
-bash runtime/persistence/store.sh get "execution:plan_name"
-# → auth-service
-
-# Find last completed task
-bash runtime/persistence/store.sh list "execution:task_*:status"
-# → task_1: complete, task_2: complete, task_3: in_progress, task_4: pending
-
-# Assess task_3: was it actually completed?
-# Check: does the output exist? Do tests pass?
-# If yes → mark complete, continue from task_4
-# If no  → re-execute task_3 from scratch
-```
-
-**Without runtime:** Check git log for the last committed task, verify its done criteria, continue from the next task.
-
-**Key principle:** Never assume a task is complete because it was started. Verify the done criteria on resume.
-
-### Scope Change During Execution
-
-If requirements change mid-execution:
-
-1. **Stop** — don't continue executing the current plan
-2. **Assess** — how many tasks are invalidated by the change?
-3. **If < 20% of tasks affected:** modify affected tasks in place, re-verify done criteria
-4. **If > 20% of tasks affected:** return to `writing-plans` — the plan needs revision
-5. **Document the change** — what changed and why, update the plan document
-
-Never silently adjust scope while executing. Make the change explicit.
-
-### Progress Reporting
-
-When asked for progress, report against the plan:
-
-```
-Plan: auth-service (8 tasks)
-Progress: 5/8 complete (62.5%)
-
-✓ Task 1: Database schema
-✓ Task 2: Repository layer  
-✓ Task 3: Service layer
-✓ Task 4: Auth middleware
-✓ Task 5: JWT utilities
-⟳ Task 6: Protected routes (in progress)
-  Task 7: Integration tests (pending)
-  Task 8: Documentation (pending)
-
-Current: Implementing route guards for admin endpoints
-ETA: ~12 min remaining
-Blockers: None
-```
-
-## ClawPowers Enhancement
-
-When `~/.clawpowers/` runtime is initialized:
-
-**Milestone Persistence:** Every task completion and milestone hit is saved to `~/.clawpowers/state/`. If your laptop crashes at Task 6 of 8, you resume from Task 7, not Task 1.
-
-```bash
-# Full execution history on resume
-bash runtime/persistence/store.sh list "execution:*"
-```
-
-**Progress Dashboard:** Generate a real-time execution report:
-
-```bash
-bash runtime/feedback/analyze.sh --plan auth-service
-# Output:
-# Plan: auth-service
-# Duration so far: 47 min (estimated 60 min total)
-# Tasks: 5/8 complete
-# Velocity: 1 task / 9.4 min (plan estimated: 1/7.5 min)
-# Projected completion: +13 min
-# Warning: Task 3 took 24 min vs estimated 5 min (spec was underspecified)
-```
-
-**Interruption Recovery Statistics:** Tracks how often execution is interrupted and how long recovery takes, informing optimal checkpoint frequency.
-
-**Rework Tracking:** When a task must be re-executed (done criteria failed), records the cause:
-- Spec was ambiguous (improve `writing-plans`)
-- Dependency missing (improve dependency mapping)
-- Requirement changed (flag as scope change, not rework)
-- Implementation error (improve task verification step)
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It Fails | Correct Approach |
-|-------------|-------------|-----------------|
-| Skipping done criteria verification | Tasks appear complete but aren't | Verify every criterion explicitly |
-| Expanding task scope mid-execution | Creates unanticipated dependencies | Strict scope adherence; new scope = new task |
-| Proceeding past a failed task | Subsequent tasks build on broken foundation | Stop, fix, re-verify, then continue |
-| Not committing per task | Can't identify which task introduced a bug | Commit every task completion |
-| Ignoring parallel opportunities | Sequential execution of parallel-safe tasks wastes time | Dispatch parallel tasks concurrently |
-| Silently adjusting requirements | Plan/reality divergence | Explicit scope change protocol |
-| Skipping milestone verification | Integration problems discovered late | Verify at every phase boundary |
-
-## Integration with Other Skills
-
-- Preceded by `writing-plans` (plan must exist before execution)
-- Use `subagent-driven-development` for parallel task dispatch
-- Use `using-git-worktrees` for concurrent task isolation
-- Followed by `verification-before-completion` before merging
-- Use `systematic-debugging` when a task fails unexpectedly