clawpowers 1.1.3 → 2.0.0

package/skills/writing-plans/SKILL.md

@@ -1,276 +0,0 @@
----
-name: writing-plans
-description: Transform a specification or goal into a sequenced implementation plan of concrete 2-5 minute tasks with dependency graph. Activate when someone asks you to plan work, before starting any substantial feature.
-version: 1.0.0
-requires:
-  tools: []
-  runtime: false
-metrics:
-  tracks: [plan_accuracy, task_count, estimation_error, dependency_violations]
-  improves: [task_granularity, estimation_calibration, dependency_detection]
----
-
-# Writing Plans
-
-## When to Use
-
-Apply this skill when:
-
-- You receive a specification that requires multiple distinct steps
-- Work will take more than 30 minutes total
-- Multiple people or agents will execute the work
-- The execution order matters (dependencies exist)
-- You need to communicate progress against milestones
-- The risk of missing a step is high
-
-**Skip when:**
-- The task is a single, obvious action (just do it)
-- The task is exploratory — you can't plan what you haven't understood yet
-- The plan would take longer to write than the work itself
-
-**Decision tree:**
-```
-Is the task > 30 min or > 1 context window?
-├── No  → execute directly
-└── Yes → Do you understand the full scope?
-          ├── No  → brainstorming first, then write-plans
-          └── Yes → writing-plans ← YOU ARE HERE
-```
-
-## Core Methodology
-
-### Phase 1: Specification Analysis
-
-Before writing a single task, decompose the spec into its logical components:
-
-1. **Parse the goal** — What is the desired end state? Not "build auth" but "users can register, log in, and maintain sessions securely"
-2. **Identify components** — What distinct systems or modules need to exist?
-3. **Find dependencies** — Which components require others to exist first?
-4. **Identify risks** — What's most likely to go wrong? Plan for it early.
-5. **Define done criteria** — How will you know the goal is achieved?
-
-**Specification analysis template:**
-```markdown
-## Goal
-[Single sentence: what exists when this is done that didn't exist before]
-
-## Components
-- [Component A]: [what it is and what it does]
-- [Component B]: [what it is and what it does]
-
-## Dependencies
-- Component B requires Component A's [interface/data/service]
-- Component C requires both A and B
-
-## Risks
-1. [Risk]: [mitigation]
-2. [Risk]: [mitigation]
-
-## Done Criteria
-- [ ] [Observable, testable condition]
-- [ ] [Observable, testable condition]
-```
-
-### Phase 2: Task Sequencing
-
-Break each component into atomic tasks. Rules for task granularity:
-
-**Target size:** 2-5 minutes of execution time (not wall clock time — agent execution time)
-**Signs a task is too large:**
-- It contains "and" (two things)
-- Its done criteria has more than 3 bullet points
-- It could fail in more than 2 different ways
-- It would produce more than 200 lines of code
-
-**Signs a task is too small:**
-- It produces less than 10 lines of code
-- Its setup (imports, scaffolding) outweighs its work
-- It has zero decision points
-
-**Task format:**
-```markdown
-### Task N: [Action verb] [specific thing]
-
-**Input:** [What this task needs to exist before it can run]
-**Output:** [Exact file, function, or artifact produced]
-**Duration:** [2-5 min]
-**Done when:**
-- [ ] [Specific, verifiable criterion]
-- [ ] Tests pass (if applicable)
-
-**Notes:** [Edge cases, non-obvious decisions, references]
-```
-
-### Phase 3: Dependency Graph
-
-After listing tasks, draw the dependency graph explicitly:
-
-```
-Task 1: Database schema       ──→ Task 3: Repository layer
-Task 2: Domain models         ──→ Task 3: Repository layer
-Task 3: Repository layer      ──→ Task 5: Service layer
-Task 4: Auth middleware        ──→ Task 6: Protected routes
-Task 5: Service layer          ──→ Task 6: Protected routes
-Task 6: Protected routes       ──→ Task 7: Integration tests
-Task 7: Integration tests      ──→ Task 8: Documentation
-```
-
-**Parallel execution opportunities** — tasks with no shared dependencies:
-- Task 1 and Task 2 can run in parallel
-- Task 4 can run in parallel with Tasks 1-3
-
-Label these explicitly. If using `subagent-driven-development`, parallel tasks become parallel subagent dispatches.
-
-### Phase 4: Risk-First Ordering
-
-Within the constraint of the dependency graph, sequence tasks to:
-1. **Prove the spike first** — If there's a technical uncertainty, make a task that resolves it early
-2. **Hard tasks early** — Don't save the hardest part for last (discovery of blockers costs less time early)
-3. **Reviewable checkpoints** — Insert verification tasks at natural boundaries
-
-**Risk-first example:**
-```
-# BAD ordering (risk deferred to end)
-Task 1: Build entire frontend
-Task 2: Build entire backend
-Task 3: Integrate (discovery: API shape is wrong, redo Task 1)
-
-# GOOD ordering (risk surfaced early)
-Task 1: Define API contract (OpenAPI spec)
-Task 2: Backend stub that satisfies contract
-Task 3: Frontend stub that calls contract
-Task 4: Integration smoke test ← risk surfaced HERE, at task 4 not task 20
-Task 5: Full backend implementation
-Task 6: Full frontend implementation
-```
-
-### Phase 5: The Written Plan
-
-Final output format:
-
-```markdown
-# Plan: [Goal Name]
-
-**Goal:** [Single sentence]
-**Total tasks:** N
-**Estimated duration:** [sum of task durations]
-**Parallel opportunities:** [task numbers that can run concurrently]
-
-## Done Criteria
-- [ ] [Observable, testable condition]
-- [ ] [Observable, testable condition]
-
-## Dependency Graph
-[ASCII or description]
-
-## Tasks
-
-### Task 1: [Name]
-[Full task block]
-
-### Task 2: [Name]
-[Full task block]
-
-...
-```
-
-## ClawPowers Enhancement
-
-When `~/.clawpowers/` runtime is initialized:
-
-**Historical Estimation Calibration:**
-
-Plans get compared to actual execution. After 5+ plans, calibration data is available:
-
-```bash
-# After plan execution completes
-bash runtime/persistence/store.sh set "plan:auth-service:estimated_duration" "180"
-bash runtime/persistence/store.sh set "plan:auth-service:actual_duration" "240"
-
-# Read calibration
-bash runtime/feedback/analyze.sh --skill writing-plans
-# Output: Your 2-5 min tasks average 7.3 min actual. Adjust estimates by 1.5x.
-```
-
-**Dependency Graph Validation:**
-
-Before executing a plan, validate the dependency graph has no cycles and all task inputs exist:
-
-```bash
-bash runtime/persistence/store.sh set "plan:current:task_count" "8"
-bash runtime/persistence/store.sh set "plan:current:deps" "3:1,2 4:- 5:3,4 6:4 7:5,6 8:7"
-# Analyzer checks for cycles and unreachable tasks
-```
-
-**Plan Quality Scoring:**
-
-Stored metrics enable quality scoring of plans over time:
-- Estimation accuracy (actual / estimated)
-- Task rework rate (tasks that required re-execution)
-- Dependency violation rate (tasks executed out of order)
-- Done criteria completeness (criteria met on first attempt)
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It Fails | Correct Approach |
-|-------------|-------------|-----------------|
-| Tasks with "and" | Two risks, two outcomes, ambiguous done criteria | Split into two tasks |
-| Vague done criteria | "Done" is subjective, causes rework debates | Observable, testable criteria only |
-| Skipping dependency mapping | Execution order violations cause rework | Always draw the dependency graph |
-| Planning with no spike | Technical unknown bites you at Task 15 | Schedule spike task first if uncertainty exists |
-| Giant tasks (2 hours each) | Hard to track progress, hard to parallelize | Break down to 2-5 min granularity |
-| Tiny tasks (1-2 min each) | Plan overhead exceeds value | Group related micro-tasks |
-| Over-planning volatile specs | Plan becomes invalid before execution starts | Plan only what's stable, leave flexibility for the rest |
-
-## Examples
-
-### Example 1: Small Plan (4 tasks)
-
-**Goal:** Add rate limiting to the API
-
-```markdown
-# Plan: API Rate Limiting
-
-**Goal:** All API endpoints enforce per-user rate limits with 429 response on exceeded limits.
-**Total tasks:** 4 | **Estimated:** 16 min
-
-## Done Criteria
-- [ ] Requests beyond limit receive 429 with Retry-After header
-- [ ] Rate limit state persists across server restarts
-- [ ] Tests cover limit enforcement and reset behavior
-
-## Tasks
-
-### Task 1: Write rate limit tests (RED)
-**Input:** None | **Output:** tests/test_rate_limit.py (failing) | **Duration:** 3 min
-**Done when:** Tests run and fail with ImportError
-
-### Task 2: Implement RedisRateLimiter
-**Input:** tests/test_rate_limit.py | **Output:** src/rate_limiter.py | **Duration:** 5 min
-**Done when:** All rate limiter unit tests pass
-
-### Task 3: Integrate rate limiter into middleware
-**Input:** src/rate_limiter.py | **Output:** src/middleware/rate_limit.py | **Duration:** 4 min
-**Done when:** Integration tests pass, middleware applies limits per endpoint
-
-### Task 4: Add 429 response and Retry-After header
-**Input:** src/middleware/rate_limit.py | **Output:** Modified middleware | **Duration:** 2 min
-**Done when:** 429 response includes Retry-After with correct TTL
-```
-
-### Example 2: Dependency-heavy Plan (8 tasks with parallel opportunities)
-
-**Goal:** Build notification service
-
-**Parallel opportunities:** Tasks 1+2 concurrent, Tasks 4+5 concurrent
-
-```markdown
-### Task 1: Define notification event schema [parallel with Task 2]
-### Task 2: Database migration for notification store [parallel with Task 1]
-### Task 3: NotificationRepository (depends on 1, 2)
-### Task 4: Email provider integration (depends on 1) [parallel with Task 5]
-### Task 5: Push notification provider integration (depends on 1) [parallel with Task 4]
-### Task 6: NotificationService orchestrator (depends on 3, 4, 5)
-### Task 7: API endpoints (depends on 6)
-### Task 8: Integration tests (depends on 7)
-```

package/skills/writing-skills/SKILL.md

@@ -1,260 +0,0 @@
----
-name: writing-skills
-description: Create new ClawPowers skills using TDD methodology — write test scenarios, watch the agent fail without the skill, write the skill, verify the agent passes. Activate when you need a new skill that ClawPowers doesn't have.
-version: 1.0.0
-requires:
-  tools: [bash]
-  runtime: false
-metrics:
-  tracks: [skills_written, skill_quality_scores, test_coverage, anti_pattern_count]
-  improves: [skill_structure_quality, when_to_use_clarity, example_relevance]
----
-
-# Writing Skills
-
-## When to Use
-
-Apply this skill when:
-
-- ClawPowers lacks a skill you need repeatedly
-- You've solved a non-trivial problem 3+ times and want to codify the approach
-- A team has domain-specific methodologies that should be agent-accessible
-- An existing skill is missing important context or examples
-- You're improving an existing skill that consistently produces suboptimal results
-
-**Skip when:**
-- The skill would be a one-off
-- The methodology is already captured in a skill that could be extended
-- You don't have enough real experience with the problem to write a useful skill (skills written from theory, not experience, are worse than no skill)
-
-**Decision tree:**
-```
-Have you solved this problem multiple times manually?
-├── No  → Solve it first. Document later.
-└── Yes → Is it covered by an existing skill?
-          ├── Yes → Extend the existing skill (new section, new example)
-          └── No  → writing-skills ← YOU ARE HERE
-```
-
-## Core Methodology
-
-### TDD for Skills
-
-Skills are tested by measuring whether an agent WITHOUT the skill fails a scenario that an agent WITH the skill handles correctly. This is behavioral testing — not unit testing of code.
-
-### Phase 1: Write Test Scenarios (RED)
-
-Before writing any skill content, write test scenarios that the skill must handle.
-
-**Test scenario format:**
-```markdown
-## Scenario N: [Descriptive name]
-
-**Agent state:** Agent has no knowledge of [skill domain]
-**Input:** [Exact prompt or situation the agent receives]
-**Without skill:** [Specific wrong behavior the agent exhibits]
-**With skill:** [Specific correct behavior the skill produces]
-**Success criteria:**
-- [ ] [Observable, verifiable outcome]
-- [ ] [Observable, verifiable outcome]
-```
-
-**Minimum scenarios before writing the skill:**
-- 1 happy path (common use case)
-- 1 edge case (unusual but valid)
-- 1 failure case (when NOT to use the skill)
-- 1 anti-pattern case (common mistake the skill prevents)
-
-**Example scenarios for a hypothetical "database-migration" skill:**
-
-```markdown
-## Scenario 1: Running migrations safely
-Without skill: Agent runs `alembic upgrade head` without backing up first
-With skill: Agent follows backup → dry-run → verify → apply sequence
-
-## Scenario 2: Rolling back a bad migration
-Without skill: Agent manually deletes rows or drops columns (data loss)
-With skill: Agent runs `alembic downgrade -1`, verifies schema, identifies root cause
-
-## Scenario 3: When NOT to use this skill
-Input: "Update the user model to add an index"
-Without skill: Agent triggers migration skill for every schema change
-With skill: Agent recognizes index-only changes don't need this protocol
-
-## Scenario 4: Anti-pattern — concurrent migrations
-Without skill: Agent runs migrations in parallel across multiple servers
-With skill: Agent ensures single-server serial execution with distributed lock
-```
-
-### Phase 2: Verify Failure (The "RED" Moment)
-
-Before writing the skill, verify that an agent without it fails at least Scenario 1. This confirms:
-- The skill is actually needed
-- The test scenarios are meaningful
-- The skill will produce measurable improvement
-
-If an agent without the skill already handles the scenarios correctly, you don't need the skill.
-
-### Phase 3: Write the Skill
-
-Use the ClawPowers skill template:
-
-```markdown
----
-name: skill-name-kebab-case
-description: [One sentence: when to trigger this skill. Start with "Activate when..."]
-version: 1.0.0
-requires:
-  tools: [tool1, tool2]  # Only tools the skill actually requires
-  runtime: false          # true if skill needs ~/.clawpowers/
-metrics:
-  tracks: [metric1, metric2]  # Observable outcomes
-  improves: [param1, param2]  # Parameters RSI can tune
----
-
-# [Skill Name]
-
-## When to Use
-
-[Decision tree. Include when to skip the skill.]
-
-## Core Methodology
-
-[The actual methodology. Numbered steps. Concrete, not abstract.]
-
-## ClawPowers Enhancement
-
-[What the runtime layer adds. Only if runtime: true or if runtime is optional benefit.]
-
-## Anti-Patterns
-
-[Table of common mistakes, why they fail, correct approach.]
-
-## Examples
-
-[1-3 concrete examples with real code/commands, not hypotheticals.]
-```
-
-### Phase 4: Quality Gates
-
-Before the skill is "done", it must pass these gates:
-
-**Gate 1: When to Use is a decision tree, not a list**
-- Does it tell you when NOT to use the skill?
-- Does it handle edge cases in the decision?
-
-**Gate 2: Core Methodology is actionable**
-- Can someone follow these steps without guessing?
-- Does every step produce a verifiable output?
-- Are code/command examples real, not pseudocode?
-
-**Gate 3: Anti-Patterns are specific**
-- Each anti-pattern names a specific behavior, not a category
-- Each explains WHY it fails (not just "don't do this")
-- Each provides a concrete correct approach
-
-**Gate 4: Examples are real**
-- Examples use plausible real names (not `foo`, `bar`, `example`)
-- Code examples are syntactically correct
-- Examples cover the most common real-world use case
-
-**Gate 5: No stubs**
-- No "TODO: add examples here"
-- No "coming soon" sections
-- No placeholder text
-
-### Phase 5: Verify Pass (The "GREEN" Moment)
-
-Apply the test scenarios to the completed skill. Verify:
-- Scenario 1 (happy path): skill guides agent to correct outcome
-- Scenario 2 (edge case): skill handles it explicitly or provides guidance
-- Scenario 3 (skip case): skill's "When to Use" correctly excludes this
-- Scenario 4 (anti-pattern): skill's Anti-Patterns section covers it
-
-### Phase 6: Register the Skill
-
-Add the skill to `skills/using-clawpowers/SKILL.md`:
-
-```markdown
-# In the "Quick Reference" section, add:
-25. `database-migration` — Safe migration sequence with backup, dry-run, and rollback
-```
-
-Add trigger pattern to the pattern map:
-```markdown
-| Running or planning a database schema change | `database-migration` |
-```
-
-## ClawPowers Enhancement
-
-When `~/.clawpowers/` runtime is initialized:
-
-**Skill Quality Scoring:**
-
-Each skill is scored on:
-- Scenario coverage (how many test scenarios does it pass?)
-- Usage frequency (how often is it triggered per session?)
-- Outcome rate (when triggered, what % of executions succeed?)
-- Anti-pattern prevention (how often does it prevent a documented anti-pattern?)
-
-```bash
-bash runtime/persistence/store.sh set "skill-quality:database-migration:scenario_coverage" "4/4"
-bash runtime/persistence/store.sh set "skill-quality:database-migration:outcome_rate" "0.92"
-```
-
-**Anti-Pattern Detection:**
-
-The feedback engine monitors skill usage for anti-patterns not covered by the skill:
-```bash
-bash runtime/feedback/analyze.sh --skill database-migration
-# → New anti-pattern detected: agents omit the verify step after applying migrations
-# → Recommend adding explicit verify step to Core Methodology
-```
-
-**Skill Evolution:**
-
-When a skill's outcome rate drops below threshold (< 80%), the feedback engine flags it for revision:
-```bash
-bash runtime/metrics/collector.sh record \
-  --skill writing-skills \
-  --outcome success \
-  --notes "database-migration: 4 scenarios, all passing, quality gates cleared"
-```
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It Fails | Correct Approach |
-|-------------|-------------|-----------------|
-| Writing from theory | Skill misses real-world edge cases | Write skills from real experience only |
-| Skipping test scenarios | No way to verify the skill works | Write scenarios first (TDD) |
-| Vague "When to Use" | Skill triggers at wrong times | Decision tree with explicit skip conditions |
-| Placeholder sections | Skill is deployed incomplete | All sections must be complete before registration |
-| One giant methodology section | Agents lose track of where they are | Numbered steps with verifiable outputs |
-| No anti-patterns section | Common mistakes recur | Always include anti-patterns |
-| Examples with foo/bar names | Low signal — agents don't recognize applicability | Use realistic domain names in examples |
-
-## Examples
-
-### Example 1: Simple Skill (2 scenarios)
-
-**Skill:** `git-submodule-update`
-**Problem:** Agents frequently forget to update submodules after `git pull`
-
-**Scenarios:**
-1. After `git pull`, submodule code is stale — skill ensures `git submodule update --init --recursive`
-2. New submodule added — skill ensures `git submodule update --init` for new submodules only
-
-**Skill structure:** When to Use → 3-step methodology (detect stale, update, verify) → 2 anti-patterns → 1 example
-
-### Example 2: Complex Skill (4 scenarios)
-
-**Skill:** `zero-downtime-deployment`
-**Problem:** Agents deploy without considering traffic impact
-
-**Scenarios:**
-1. Deploying new version (happy path) — blue-green or rolling strategy
-2. Deploying with schema migration — migration-first, app second
-3. Rolling back a bad deploy — revert app before revert migration
-4. Skip case — deploying to a dev environment with no traffic
-
-**Skill structure:** When to Use (with explicit skip for dev) → 5-step methodology → 4 anti-patterns → 2 examples (with and without migration)