clawpowers 1.0.0

package/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: verification-before-completion
+description: Run quality gates before any merge, deployment, or handoff. Activate when you're about to declare work done.
+version: 1.0.0
+requires:
+  tools: [git, bash]
+  runtime: false
+metrics:
+  tracks: [gate_pass_rate, gates_failed, defect_escape_rate, verification_duration]
+  improves: [gate_selection, gate_ordering, parallel_gate_execution]
+---
+
+# Verification Before Completion
+
+## When to Use
+
+Apply this skill when:
+
+- You're about to open a PR or request a merge
+- You're handing work to another agent or team member
+- You're about to tag a release
+- You've completed all tasks in a plan
+- Someone says "are we done?"
+
+**The rule:** Nothing moves forward until verification passes. This is a hard gate, not a suggestion.
+
+**Skip when:**
+- This is a work-in-progress (WIP) commit — label it as such
+- You're committing to a draft branch specifically for CI to run (CI is the verification)
+- The change is a single-line config fix with zero behavior impact
+
+## Core Methodology
+
+### The Verification Checklist
+
+Run these gates in order. A failure at any gate stops the process — fix and restart verification from that gate.
+
+#### Gate 1: Completeness
+
+- [ ] All tasks in the plan are marked complete
+- [ ] All done criteria in the plan are verified
+- [ ] No TODOs, stubs, or `# FIXME` in production code paths
+- [ ] All specified features are implemented
+
+```bash
+# Check for stubs
+grep -r "TODO\|FIXME\|STUB\|NOTIMPLEMENTED\|raise NotImplementedError\|pass  # " src/ --include="*.py"
+grep -r "TODO\|FIXME\|STUB" src/ --include="*.ts" --include="*.js"
+```
+
+#### Gate 2: Tests Pass
+
+- [ ] Full test suite passes with zero failures
+- [ ] Zero flaky tests in this run
+- [ ] Test coverage meets threshold (≥80% line coverage for new code)
+
+```bash
+# Python
+pytest --tb=short -q
+pytest --cov=src --cov-report=term-missing --cov-fail-under=80
+
+# JavaScript/TypeScript
+npm test -- --passWithNoTests
+npx jest --coverage --coverageThreshold='{"global":{"lines":80}}'
+
+# Go
+go test ./... -count=1 -race
+go test ./... -cover -covermode=atomic
+```
+
+#### Gate 3: Static Analysis
+
+- [ ] No linting errors
+- [ ] No type errors (if typed language)
+- [ ] No security scan findings (high/critical)
+
+```bash
+# Python
+ruff check src/
+mypy src/ --strict
+bandit -r src/ -ll  # medium+ severity only
+
+# JavaScript/TypeScript
+npx eslint src/
+npx tsc --noEmit
+
+# Go
+go vet ./...
+staticcheck ./...
+```
+
+#### Gate 4: Build Succeeds
+
+- [ ] Project builds without errors or warnings
+- [ ] Dependencies are pinned (no floating versions in production)
+- [ ] Build artifacts are reproducible
+
+```bash
+# Python
+pip install -e . --quiet
+python -c "import your_package"  # smoke test import
+
+# Node.js
+npm ci  # use ci not install (honors package-lock.json)
+npm run build
+
+# Go
+go build ./...
+```
+
+#### Gate 5: Integration Tests
+
+- [ ] Integration tests pass (database, external services, etc.)
+- [ ] API contract tests pass (if applicable)
+- [ ] No regression in end-to-end test suite
+
+```bash
+# Integration tests (requires real DB, may need Docker)
+pytest tests/integration/ -v
+# Or
+docker-compose up -d && pytest tests/integration/ && docker-compose down
+```
+
+#### Gate 6: Security Scan
+
+- [ ] No hardcoded secrets in new code
+- [ ] Dependencies have no critical CVEs
+- [ ] No SQL injection / XSS vectors in new endpoints
+
+```bash
+# Secret scanning
+gitleaks detect --no-git -v
+
+# Dependency audit
+npm audit --audit-level=high
+pip-audit --desc on
+trivy fs . --severity HIGH,CRITICAL --exit-code 1
+
+# SAST for known vulnerability patterns
+bandit -r src/ -l  # Python
+semgrep --config=auto src/  # multi-language
+```
+
+#### Gate 7: Documentation
+
+- [ ] Public API changes have updated docstrings/JSDoc
+- [ ] README reflects any changed setup steps
+- [ ] CHANGELOG updated with this change
+- [ ] Any new environment variables are documented
+
+```bash
+# Check for undocumented public functions (Python)
+pydocstyle src/ --add-ignore=D100,D104
+
+# Verify CHANGELOG was updated
+git diff HEAD~1 CHANGELOG.md | grep "^+" | wc -l  # should be > 0
+```
+
+### Verification Report
+
+After running all gates, produce a report:
+
+```markdown
+## Verification Report — [Feature Name]
+
+**Date:** [timestamp]
+**Branch:** [branch name]
+**Commit:** [short hash]
+
+### Gate Results
+| Gate | Status | Notes |
+|------|--------|-------|
+| 1. Completeness | ✅ PASS | All 8 plan tasks verified |
+| 2. Tests | ✅ PASS | 127 tests, 0 failures, 84% coverage |
+| 3. Static Analysis | ✅ PASS | 0 ruff errors, 0 mypy errors |
+| 4. Build | ✅ PASS | Clean build, deps pinned |
+| 5. Integration | ✅ PASS | 12 integration tests passing |
+| 6. Security | ✅ PASS | 0 secrets, 0 critical CVEs |
+| 7. Documentation | ✅ PASS | Docstrings updated, CHANGELOG updated |
+
+**Verdict: READY FOR REVIEW**
+```
+
+If any gate fails:
+
+```markdown
+| 2. Tests | ❌ FAIL | test_payment_retry: AssertionError: expected 3 retries, got 1 |
+
+**Verdict: NOT READY — address test failure before proceeding**
+```
+
+### Failure Protocol
+
+When a gate fails:
+
+1. **Stop** — don't open the PR
+2. **Fix the specific failure** — don't work around it
+3. **Re-run the full gate sequence from Gate 1** — a fix can break something earlier
+4. **If the same gate fails twice**, escalate to `systematic-debugging`
+
+**Exception:** If Gates 2-6 pass but Gate 7 (documentation) is being updated in a separate follow-up PR with a tracking issue, this is the only acceptable skip with documented justification.
+
+## ClawPowers Enhancement
+
+When `~/.clawpowers/` runtime is initialized:
+
+**Automated Verification Suite Execution:**
+
+Instead of running gates manually, execute the full suite:
+
+```bash
+# Run all verification gates automatically
+bash runtime/persistence/store.sh set "verification:feature-name:started_at" "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+# Gates execute in parallel where safe (Gates 3, 4, 6 can parallelize)
+# Results saved to state store for resumability
+
+bash runtime/persistence/store.sh set "verification:feature-name:gate2:status" "pass"
+bash runtime/persistence/store.sh set "verification:feature-name:gate2:details" "127 tests, 0 failures"
+```
+
+**Historical Pass Rates:**
+
+After 20+ verifications, `runtime/feedback/analyze.sh` reports:
+- Which gate fails most often (target for process improvement)
+- Average verification duration
+- Defect escape rate (bugs found in review or production vs. caught by verification)
+- Gates that catch zero issues over N runs (candidates for removal or replacement)
+
+**Gate Configuration:**
+
+Store project-specific gate thresholds:
+```bash
+bash runtime/persistence/store.sh set "config:verification:coverage_threshold" "85"
+bash runtime/persistence/store.sh set "config:verification:security_level" "medium"
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Correct Approach |
+|-------------|-------------|-----------------|
+| "Tests probably pass" without running | False confidence, bugs escape | Run every time — no exceptions |
+| Disabling tests to pass gate | Silences real bugs | Fix the code, never the test |
+| Running only unit tests | Integration issues escape | All gates required |
+| Skipping security scan "because it's internal" | Internal breaches exist | Security scan always |
+| Fixing gate failures without re-running from Gate 1 | Fix introduces new failures | Full restart after any fix |
+| Annotating known issues as "acceptable" | Debt accumulates, gets shipped | Fix it or don't ship |
+
+## Integration with Other Skills
+
+- Preceded by `executing-plans` (all plan tasks must be complete)
+- Use `systematic-debugging` if tests fail
+- Followed by `finishing-a-development-branch` or `requesting-code-review`
+- Use `security-audit` for extended security coverage beyond Gate 6

package/skills/writing-plans/SKILL.md

@@ -0,0 +1,276 @@
+---
+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)
+```