clawpowers 1.1.3 → 2.0.0

package/skills/using-git-worktrees/SKILL.md

@@ -1,261 +0,0 @@
----
-name: using-git-worktrees
-description: Manage isolated Git worktrees for parallel branch development. Activate when you need to work on multiple branches simultaneously or isolate subagent work.
-version: 1.0.0
-requires:
-  tools: [git, bash]
-  runtime: false
-metrics:
-  tracks: [worktrees_created, conflicts_encountered, isolation_violations, lifecycle_completion_rate]
-  improves: [conflict_prediction, worktree_naming, cleanup_timing]
----
-
-# Using Git Worktrees
-
-## When to Use
-
-Apply this skill when:
-
-- Working on 2+ branches simultaneously without switching
-- Running subagents in parallel (each needs its own working directory)
-- Testing a feature while bug-fixing on another branch
-- Reviewing a colleague's branch while continuing your own work
-- Running long-running processes (tests, builds) on one branch while editing another
-
-**Skip when:**
-- You only have one branch active at a time
-- Your editor doesn't handle multiple root directories well
-- The branches share files that would conflict on disk (same path, different content)
-
-## Core Methodology
-
-### Understanding Worktrees
-
-A Git worktree is a separate working directory linked to the same repository. Each worktree:
-- Has its own checked-out branch
-- Has its own working tree state (staged/unstaged changes)
-- Shares the repository's history, objects, and refs
-- Cannot have the same branch checked out as another worktree
-
-```
-.git/                           ← Shared repository database
-  worktrees/
-    feature-auth/               ← Worktree metadata
-    feature-payments/           ← Worktree metadata
-
-../feature-auth/                ← Separate directory on disk
-  src/
-  tests/
-  
-../feature-payments/            ← Separate directory on disk
-  src/
-  tests/
-```
-
-### Worktree Lifecycle
-
-#### Create
-
-```bash
-# Create worktree for existing branch
-git worktree add ../feature-auth feature/auth-service
-
-# Create worktree and new branch simultaneously
-git worktree add -b feature/payments ../feature-payments main
-
-# Create worktree from specific commit
-git worktree add ../hotfix-3.1 v3.1.0
-```
-
-**Naming convention for parallel subagent work:**
-```bash
-# Use task or feature name as both branch and directory
-git worktree add ../clawpowers-task-auth feature/task-auth
-git worktree add ../clawpowers-task-db feature/task-db
-git worktree add ../clawpowers-task-api feature/task-api
-```
-
-#### Verify
-
-```bash
-git worktree list
-# output:
-# /Users/you/project                  a3f9b2c [main]
-# /Users/you/feature-auth             0000000 [feature/auth-service]
-# /Users/you/feature-payments         0000000 [feature/payments]
-```
-
-#### Work in the Worktree
-
-Each worktree is a full working directory. Navigate to it and work normally:
-
-```bash
-cd ../feature-auth
-git status          # Independent of main working tree
-git add src/auth.py
-git commit -m "feat(auth): implement JWT issuance"
-```
-
-Changes in one worktree are invisible to others until merged.
-
-#### Sync with Main
-
-When you need to update a worktree with latest main:
-
-```bash
-cd ../feature-auth
-git fetch origin
-git rebase origin/main  # Preferred: linear history
-# or
-git merge origin/main   # If rebase would cause conflicts
-```
-
-Run `git worktree list` first — if another worktree has the same base, check for merge conflicts proactively.
-
-#### Cleanup
-
-When the branch is merged:
-
-```bash
-# From main repository directory
-git worktree remove ../feature-auth          # Removes directory
-git branch -d feature/auth-service            # Remove branch
-
-# If the worktree has uncommitted changes and you want to force:
-git worktree remove --force ../feature-auth
-
-# List remaining worktrees to verify
-git worktree list
-```
-
-**Cleanup checklist:**
-- [ ] Branch is merged to main (or PR is approved)
-- [ ] Worktree has no uncommitted changes
-- [ ] No processes are running in the worktree directory
-- [ ] Remove directory, then remove branch
-
-### Conflict Prevention
-
-Worktrees share the index but have separate working trees. Common conflicts:
-
-**Same branch in two worktrees:** Git prevents this — you'll get an error:
-```
-fatal: 'feature/auth-service' is already checked out
-```
-
-**Solution:** Use separate branches even for related work.
-
-**Both worktrees editing the same file:** Legal, but merging will require conflict resolution:
-```bash
-# Check overlap before creating worktrees
-git diff --name-only main..feature/branch-a
-git diff --name-only main..feature/branch-b
-# If outputs overlap, consider sequential rather than parallel work
-```
-
-**Submodule issues:** Worktrees and submodules interact poorly. If your repo uses submodules, test worktree creation in a non-submodule path first.
-
-### Pattern: Subagent Work Isolation
-
-The primary ClawPowers use case: give each subagent its own worktree.
-
-```bash
-# Main orchestrator creates worktrees
-TASKS=("auth" "db" "api" "tests")
-for task in "${TASKS[@]}"; do
-  git worktree add "../${REPO_NAME}-task-${task}" -b "feature/task-${task}" main
-  echo "Created worktree for task-${task} at ../${REPO_NAME}-task-${task}"
-done
-
-# Each subagent receives its worktree path
-# Subagent-auth works in: ../project-task-auth/
-# Subagent-db works in: ../project-task-db/
-# They cannot interfere with each other's files
-
-# After all subagents complete, merge in dependency order
-MERGE_ORDER=("db" "auth" "api" "tests")
-git checkout main
-for task in "${MERGE_ORDER[@]}"; do
-  git merge --no-ff "feature/task-${task}" -m "merge: task-${task}"
-  git worktree remove "../${REPO_NAME}-task-${task}"
-  git branch -d "feature/task-${task}"
-done
-```
-
-### Pattern: Hotfix While Feature Work Continues
-
-```bash
-# You're in the middle of a long feature
-git worktree list
-# /Users/you/project           [feature/auth-service]
-
-# Production alert fires — need to hotfix
-git worktree add ../hotfix main
-cd ../hotfix
-# ... fix the bug ...
-git commit -m "fix: critical payment timeout in production"
-git push origin hotfix/payment-timeout
-# PR/merge the hotfix from this worktree
-
-# Back to feature work
-cd ../project  # Original feature work untouched
-git status  # Clean, feature work is exactly where you left it
-```
-
-## ClawPowers Enhancement
-
-When `~/.clawpowers/` runtime is initialized:
-
-**Worktree Lifecycle Management:**
-
-```bash
-# Register a worktree
-bash runtime/persistence/store.sh set "worktree:task-auth:path" "../project-task-auth"
-bash runtime/persistence/store.sh set "worktree:task-auth:branch" "feature/task-auth"
-bash runtime/persistence/store.sh set "worktree:task-auth:status" "active"
-bash runtime/persistence/store.sh set "worktree:task-auth:created_at" "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-
-# List all active worktrees with their status
-bash runtime/persistence/store.sh list "worktree:*:status"
-```
-
-If a session is interrupted, the worktree registry shows which are active and which branches they hold — preventing orphaned worktrees.
-
-**Conflict Prediction:**
-
-Before creating parallel worktrees, the framework checks for file overlap:
-
-```bash
-# For each planned worktree pair, check for overlapping file changes
-# High overlap = schedule sequentially; low overlap = safe to parallelize
-bash runtime/persistence/store.sh set "worktree:conflict_check:task-auth_vs_task-db" "no_overlap"
-```
-
-**Cleanup Automation:**
-
-After merge detection, automatically prompt for worktree cleanup:
-
-```bash
-bash runtime/feedback/analyze.sh --worktrees
-# Output:
-# Merged branches with active worktrees:
-#   - feature/task-auth (merged 3 hours ago) → worktree at ../project-task-auth
-# Run: git worktree remove ../project-task-auth && git branch -d feature/task-auth
-```
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It Fails | Correct Approach |
-|-------------|-------------|-----------------|
-| Checking out same branch in two worktrees | Git prevents this — error on checkout | Each worktree must have a unique branch |
-| Never cleaning up worktrees | Disk fills up, confusion about active branches | Cleanup immediately after branch merges |
-| `--force` on worktree with uncommitted work | Loses uncommitted changes permanently | Commit or stash before removing |
-| Parallel worktrees editing the same file | Merge conflicts on integration | Check file overlap before creating parallel worktrees |
-| Forgetting which worktree you're in | Wrong branch gets commits | `git worktree list` before committing |
-| Long-lived worktrees diverging from main | Painful rebase/merge on integration | Regularly sync worktrees with `git rebase origin/main` |
-
-## Integration with Other Skills
-
-- Used by `subagent-driven-development` for task isolation
-- Used by `dispatching-parallel-agents` for concurrent work
-- Used by `finishing-a-development-branch` when cleaning up

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

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