clawpowers 1.0.0

package/skills/requesting-code-review/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: requesting-code-review
+description: Prepare and submit a code review request with full context, risk areas, and reviewer guidance. Activate when a branch is finished and needs peer review.
+version: 1.0.0
+requires:
+  tools: [git, bash]
+  runtime: false
+metrics:
+  tracks: [review_response_time, review_cycles, reviewer_match_score, feedback_actionability]
+  improves: [context_completeness, risk_identification_accuracy, reviewer_selection]
+---
+
+# Requesting Code Review
+
+## When to Use
+
+Apply this skill when:
+
+- `finishing-a-development-branch` is complete
+- You need peer review before merging
+- The change is non-trivial (> 50 lines of production code)
+- You want to give reviewers the best chance of catching issues
+
+**Skip when:**
+- Trivial typo fix or single-line change
+- Emergency hotfix where time doesn't permit (document post-hoc)
+- The change is documentation-only with no logic
+
+## Core Methodology
+
+### Step 1: Pre-Review Self-Review
+
+Before requesting review, do a self-review as if you were the reviewer:
+
+```bash
+git diff main...HEAD
+```
+
+Go through the diff and ask:
+- Would I understand what this code does without explanation?
+- Are there any obvious bugs I can see fresh?
+- Is anything over-engineered or unnecessarily complex?
+- Would a new team member be able to maintain this?
+
+Fix anything you find. Requesting review of code you know has issues wastes the reviewer's time.
+
+### Step 2: Identify Risk Areas
+
+Proactively identify what deserves the most scrutiny:
+
+**Risk categories:**
+- **Security-sensitive paths** — authentication, authorization, input validation, crypto
+- **Concurrency code** — locks, goroutines, async patterns, shared state
+- **External integrations** — third-party APIs, payment processors, auth providers
+- **Database changes** — schema migrations, query performance, transaction handling
+- **Performance-critical paths** — hot loops, cached data invalidation, N+1 queries
+- **Backward compatibility** — changed interfaces, removed fields, modified contracts
+
+For each risk area, note:
+- What the risk is
+- What you did to mitigate it
+- What the reviewer should specifically examine
+
+### Step 3: Choose Reviewers
+
+Select reviewers based on:
+
+1. **Domain expertise** — Who has worked with this code area before?
+2. **Security knowledge** — For any security-sensitive changes, at least one reviewer with security background
+3. **Fresh eyes** — For complex logic, someone unfamiliar with the code (catches implicit assumptions)
+4. **Availability** — Don't block on a reviewer who won't be available for 3+ days
+
+**Reviewer load:** Don't request review from someone who already has 3+ open review requests.
+
+**Minimum reviewers:** 1 for low-risk changes, 2 for security changes, 2 for schema migrations.
+
+### Step 4: Write the Review Request
+
+Build on the PR description from `finishing-a-development-branch` and add reviewer-specific guidance:
+
+```markdown
+## Code Review Request: [Feature Name]
+
+**Branch:** feature/auth-service → main
+**PR:** [link]
+**Priority:** [Normal / Urgent / Low]
+**Review by:** [date — give at least 24 hours]
+
+### What This Does
+[2-3 sentences for someone who hasn't seen any of the work]
+
+### What's Changed (Key Files)
+- `src/auth/service.py` — Core JWT issuance and validation logic (NEW)
+- `src/middleware/auth.py` — Request authentication middleware (MODIFIED)
+- `tests/test_auth.py` — 34 new tests (NEW)
+- `migrations/003_auth_sessions.sql` — Session storage schema (NEW)
+
+### What to Focus On
+
+**[HIGH PRIORITY] `src/auth/service.py:47-89` — JWT validation logic**
+This is the most security-critical path. Specifically review:
+- Token expiry check (line 61) — must reject expired tokens before checking signature
+- Algorithm enforcement (line 78) — must reject HS256, accept RS256 only
+- Error handling (lines 84-89) — must not leak token contents in error messages
+
+**[MEDIUM] `migrations/003_auth_sessions.sql`**
+Irreversible change. Verify the rollback migration is correct before approving.
+
+**[LOW] `src/middleware/auth.py`**
+Standard middleware pattern. Verify session cache key structure is consistent.
+
+### Known Tradeoffs Accepted
+- Sessions stored in Redis (not DB) for performance — accepted: Redis is already a dependency
+- TTL is fixed at 1 hour — accepted: configurable TTL deferred to follow-up issue #247
+
+### Not in Scope
+- Password reset flow — tracked in issue #248
+- MFA support — tracked in issue #249
+
+### Testing Summary
+- 34 unit tests (all auth logic paths)
+- 8 integration tests (real Redis, real DB)
+- Manual test: registered, logged in, made authenticated request, logged out
+- Security test: expired token rejected, tampered token rejected, algorithm confusion rejected
+
+### Questions for Reviewers
+1. Is the error message at line 88 safe to expose to clients? (no token contents, but mentions "signature verification failed")
+2. Should the session TTL be in seconds or milliseconds in the Redis key expiry? Currently seconds — consistent with Python's time.time().
+```
+
+### Step 5: Notify Reviewers
+
+Don't just assign in GitHub and wait. Notify:
+
+```
+[Message to reviewer]
+Hey, I've opened a PR for the auth service implementation. About 400 lines of 
+new code + a schema migration. Review should take 30-45 minutes. 
+
+High priority focus: the JWT validation logic in src/auth/service.py (lines 47-89).
+
+PR: [link]
+No rush on today — tomorrow EOD works. Let me know if you have questions 
+before diving in.
+```
+
+Direct notification (Slack, Teams, etc.) gets 3x faster response than GitHub assignment alone.
+
+### Step 6: Be Available for Questions
+
+During review:
+- Check for review comments every few hours
+- Answer questions promptly — blocking the reviewer = slower iteration
+- If you need to make changes during review, push to the same branch (don't open a new PR)
+- Respond to every comment — even "acknowledged" or "agreed, will fix" counts
+
+## ClawPowers Enhancement
+
+When `~/.clawpowers/` runtime is initialized:
+
+**Reviewer Matching Based on Code Area:**
+
+Track which reviewers have reviewed which paths:
+
+```bash
+bash runtime/persistence/store.sh set "reviewer:alice:areas" "src/auth/,src/middleware/"
+bash runtime/persistence/store.sh set "reviewer:bob:areas" "migrations/,src/models/"
+bash runtime/persistence/store.sh set "reviewer:carol:areas" "src/api/,tests/"
+
+# Get suggested reviewers for current diff
+CHANGED_DIRS=$(git diff main...HEAD --name-only | xargs -I{} dirname {} | sort -u | tr '\n' ',')
+bash runtime/persistence/store.sh list "reviewer:*:areas" | grep -f <(echo "$CHANGED_DIRS" | tr ',' '\n')
+```
+
+**Review History:**
+
+```bash
+bash runtime/persistence/store.sh set "review:auth-service:requested_at" "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+bash runtime/persistence/store.sh set "review:auth-service:reviewers" "alice,bob"
+# After review completes:
+bash runtime/persistence/store.sh set "review:auth-service:response_time_hours" "6"
+bash runtime/persistence/store.sh set "review:auth-service:cycles" "2"
+bash runtime/persistence/store.sh set "review:auth-service:outcome" "approved"
+```
+
+**Review Request Quality Metrics:**
+
+Correlates review request quality (risk areas identified, context completeness) with number of review cycles required. PRs with complete context average 1.3 cycles; PRs without average 2.8 cycles.
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Correct Approach |
+|-------------|-------------|-----------------|
+| No context in PR description | Reviewers waste time figuring out what the PR does | Complete description with focus areas |
+| Requesting review of known-bad code | Wastes reviewer time, undermines trust | Self-review first, fix what you find |
+| Assigning everyone to every PR | Diffusion of responsibility, everyone waits for someone else | 1-2 targeted reviewers |
+| No risk areas identified | Reviewers apply uniform attention, miss high-risk areas | Explicitly call out what needs scrutiny |
+| Requesting review on Friday afternoon | Review blocked until Monday | Time requests for prompt turnaround |
+| Not notifying reviewers directly | Notification gets buried | Direct message in addition to GitHub assignment |
+| "Take your time" with security changes | Security review gets deprioritized | State urgency explicitly |
+
+## Integration with Other Skills
+
+- Preceded by `finishing-a-development-branch`
+- Followed by `receiving-code-review`
+- Use `security-audit` to pre-scan before requesting security-sensitive reviews

package/skills/security-audit/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: security-audit
+description: Run automated security scanning with Trivy, gitleaks, dependency audits, and SAST tools. Produces an actionable vulnerability report. Activate before any production deployment or release.
+version: 1.0.0
+requires:
+  tools: [bash, trivy, gitleaks, npm, python3]
+  runtime: false
+metrics:
+  tracks: [vulnerabilities_found, critical_count, high_count, false_positive_rate, fix_rate]
+  improves: [scan_coverage, reporting_clarity, fix_prioritization]
+---
+
+# Security Audit
+
+## When to Use
+
+Apply this skill when:
+
+- Preparing for a production release
+- A new dependency has been added
+- Infrastructure code (Dockerfiles, K8s manifests) has changed
+- A security incident occurred and you need to understand scope
+- Before merging a PR with authentication/authorization changes
+- Onboarding a new codebase (baseline security posture assessment)
+
+**Skip when:**
+- Running on every trivial PR (overhead too high — use pre-commit hooks for that)
+- Dependencies haven't changed and no new code paths touch auth/IO/crypto
+
+## Tools Reference
+
+| Tool | What It Scans | Install |
+|------|-------------|---------|
+| `trivy` | Containers, filesystems, IaC, SBOMs for CVEs | `brew install trivy` / `apt install trivy` |
+| `gitleaks` | Secret detection in git history | `brew install gitleaks` / `go install` |
+| `npm audit` | Node.js dependency CVEs | Bundled with npm |
+| `pip-audit` | Python dependency CVEs | `pip install pip-audit` |
+| `bandit` | Python SAST (hardcoded creds, injection) | `pip install bandit` |
+| `semgrep` | Multi-language SAST patterns | `pip install semgrep` |
+| `cargo audit` | Rust dependency CVEs | `cargo install cargo-audit` |
+
+## Core Methodology
+
+### Step 1: Secret Scanning (Run First)
+
+Secrets in code are the highest-priority finding. Scan before any other step:
+
+```bash
+# Scan the entire git history (not just current commit)
+gitleaks detect --source . --verbose
+
+# Scan current filesystem (for CI/CD pipelines where git history isn't available)
+gitleaks detect --no-git --source . --verbose
+
+# Scan a specific branch range
+gitleaks detect --log-opts="main..HEAD"
+```
+
+**What gitleaks finds:**
+- API keys (AWS, Google Cloud, Stripe, GitHub, etc.)
+- Database connection strings with credentials
+- Private keys (RSA, ECDSA, PGP)
+- OAuth tokens and session secrets
+- Generic high-entropy strings that look like credentials
+
+**Critical:** Any detected secret must be rotated immediately — not just removed from code. The secret was exposed from the moment it was committed, regardless of whether the commit still exists.
+
+**Secret rotation protocol:**
+1. Identify the secret type (API key, DB password, etc.)
+2. Rotate/regenerate the secret at the source (AWS console, GitHub settings, etc.)
+3. Update all deployments with the new secret
+4. Remove the old secret from git history (`git filter-branch` or BFG Repo Cleaner)
+5. Force-push the cleaned history (with team coordination)
+6. Verify old secret no longer works
+
+### Step 2: Dependency CVE Scanning
+
+```bash
+# Node.js
+npm audit --audit-level=moderate
+# For a non-zero exit on vulnerabilities:
+npm audit --audit-level=high 2>&1 | tee npm-audit-results.txt
+
+# Python
+pip-audit --desc on --output json > pip-audit-results.json
+pip-audit --fix --dry-run  # See what would be auto-fixed
+
+# Containers (Dockerfile + base image)
+trivy image your-image:tag --severity HIGH,CRITICAL --exit-code 1
+trivy image your-image:tag --format json -o trivy-image-results.json
+
+# Filesystem (all languages + config files)
+trivy fs . --severity HIGH,CRITICAL
+trivy fs . --format json -o trivy-fs-results.json
+
+# Infrastructure as Code (Terraform, K8s, Helm, CloudFormation)
+trivy config ./infrastructure/ --severity HIGH,CRITICAL
+trivy config k8s/ --format table
+
+# Rust
+cargo audit
+
+# Go
+govulncheck ./...
+```
+
+### Step 3: SAST (Static Application Security Testing)
+
+Find security-relevant code patterns:
+
+```bash
+# Python — bandit
+bandit -r src/ -ll -f json -o bandit-results.json
+bandit -r src/ -ll --skip B101  # Skip assert_used if it's test code
+
+# Multi-language — semgrep
+semgrep --config=auto src/ --json -o semgrep-results.json
+semgrep --config=p/python src/ --json  # Language-specific rules
+semgrep --config=p/javascript src/ --json
+semgrep --config=p/owasp-top-ten src/ --json  # OWASP rules
+
+# Node.js — eslint-plugin-security
+npx eslint --plugin security --rule 'security/detect-non-literal-regexp: warn' src/
+```
+
+**High-priority bandit checks:**
+- `B105-B107`: Hardcoded password/credentials
+- `B301-B302`: Pickle deserialization (arbitrary code execution)
+- `B501-B511`: TLS/SSL configuration weaknesses
+- `B601-B614`: Shell injection, subprocess calls
+- `B701-B703`: Jinja2/Mako template injection
+
+**High-priority semgrep rules:**
+- SQL injection patterns
+- Path traversal
+- XSS (reflected, stored)
+- SSRF (server-side request forgery)
+- Authentication bypass patterns
+- Insecure deserialization
+
+### Step 4: Container Security
+
+If the project uses Docker:
+
+```bash
+# Scan Dockerfile for misconfigurations
+trivy config Dockerfile
+
+# Common Dockerfile issues trivy finds:
+# - Running as root (ADD USER directive missing)
+# - COPY . . (copies .env, .git, sensitive files)
+# - Latest tag (non-deterministic base image)
+# - Exposed ports beyond what's necessary
+# - Unverified downloads (curl | bash patterns)
+# - Secrets passed as ENV vars or ARG
+
+# Scan built image
+docker build -t myapp:audit .
+trivy image myapp:audit --severity HIGH,CRITICAL
+```
+
+**Critical Dockerfile security checks:**
+```dockerfile
+# BAD
+FROM ubuntu:latest
+RUN curl -fsSL https://example.com/install.sh | bash
+ENV DB_PASSWORD=secretpassword123
+COPY . .
+CMD ["npm", "start"]
+
+# GOOD
+FROM node:20-alpine@sha256:PINNED_HASH
+USER node
+COPY --chown=node:node package*.json ./
+RUN npm ci --only=production
+COPY --chown=node:node src/ ./src/
+CMD ["node", "src/index.js"]
+```
+
+### Step 5: Generate Actionable Report
+
+```markdown
+# Security Audit Report
+
+**Date:** [timestamp]
+**Scope:** [repository name, branch, version]
+**Tools:** gitleaks v8, trivy v0.48, bandit v1.7, semgrep v1.50
+
+---
+
+## Executive Summary
+
+| Severity | Count | Status |
+|----------|-------|--------|
+| Critical | 0 | ✅ None found |
+| High | 3 | ⚠️ Action required |
+| Medium | 7 | ℹ️ Review recommended |
+| Low | 12 | — Informational |
+| Secrets | 0 | ✅ None found |
+
+---
+
+## Critical Findings (Fix Before Deploy)
+
+[None]
+
+---
+
+## High Findings (Fix This Sprint)
+
+### H1: CVE-2024-XXXXX in lodash@4.17.20
+- **Tool:** npm audit
+- **Severity:** High (CVSS 7.5)
+- **Description:** Prototype pollution vulnerability
+- **Affected:** `node_modules/lodash`
+- **Fix:** `npm install lodash@4.17.21`
+- **Effort:** 15 min
+
+### H2: Running as root in production container
+- **Tool:** trivy config
+- **Severity:** High
+- **Description:** Dockerfile has no USER directive — container runs as root
+- **Fix:** Add `USER node` before CMD
+- **Effort:** 5 min
+
+### H3: Hardcoded development credential
+- **Tool:** bandit B105
+- **Severity:** High
+- **File:** `src/config/defaults.py:47`
+- **Description:** Default password `"dev_password_123"` in production config path
+- **Fix:** Remove default; require explicit environment variable
+- **Effort:** 20 min
+
+---
+
+## Medium Findings (Fix This Month)
+
+[...]
+
+---
+
+## Remediation Priority
+
+1. H3 (hardcoded credential) — rotate first, fix second
+2. H1 (lodash CVE) — `npm install lodash@4.17.21`
+3. H2 (root container) — add USER directive
+
+**Estimated total remediation time:** 40 min
+```
+
+### Step 6: Fix and Verify
+
+For each finding in priority order:
+
+1. Fix the issue (specific code change or dependency update)
+2. Re-run the specific scan that found it
+3. Verify the finding is gone
+4. Add to regression prevention (pre-commit hook, CI gate, or code review checklist)
+
+```bash
+# After fixing all High findings, re-run full suite to verify
+gitleaks detect --no-git --source .
+npm audit --audit-level=high
+trivy fs . --severity HIGH,CRITICAL
+bandit -r src/ -ll
+```
+
+## ClawPowers Enhancement
+
+When `~/.clawpowers/` runtime is initialized:
+
+**Historical Vulnerability Tracking:**
+
+```bash
+bash runtime/persistence/store.sh set "audit:$(date +%Y%m%d):critical" "0"
+bash runtime/persistence/store.sh set "audit:$(date +%Y%m%d):high" "3"
+bash runtime/persistence/store.sh set "audit:$(date +%Y%m%d):secrets" "0"
+bash runtime/persistence/store.sh set "audit:$(date +%Y%m%d):tools" "gitleaks,trivy,bandit,semgrep"
+```
+
+**Trend Analysis:**
+
+`runtime/feedback/analyze.sh` tracks:
+- Vulnerability count over time (is your security posture improving?)
+- Most common finding types (what to add to code review checklists)
+- Fix rate and time (how quickly are findings remediated)
+- Repeat findings (findings that recur indicate a systemic issue)
+
+**Automated Report Generation:**
+
+```bash
+bash runtime/metrics/collector.sh record \
+  --skill security-audit \
+  --outcome success \
+  --notes "audit: 0 critical, 3 high, 7 medium — lodash CVE, root container, hardcoded default"
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Correct Approach |
+|-------------|-------------|-----------------|
+| Scanning only current HEAD | Misses secrets in history | `gitleaks detect --source .` scans full history |
+| Dismissing medium findings as "not urgent" | Medium findings compound into exploitable chains | Review all medium findings; schedule fixes |
+| Not rotating leaked secrets | Rotated-but-historical secrets are still active | Rotate at the source, not just in code |
+| Suppressing all bandit warnings | Masks real issues | Suppress only proven false positives, with comment |
+| No regression prevention | Same vulnerability reappears | Add findings to pre-commit hooks or CI gates |
+| Scanning without context | False positives waste time | Run tools in repo root with proper config files |
+| Fixing without re-scanning | Fix may be incomplete or introduce new issue | Re-run full scan after every remediation |