clawpowers 1.1.4 → 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/validator/SKILL.md

@@ -1,281 +0,0 @@
----
-name: validator
-description: Multi-round automated validation pipeline for any software project. Runs 14 rounds of checks — compile gates, lint, tests, security scanning, documentation, secrets detection, link verification, spelling, cross-platform compatibility, dependency health, and PR-readiness. Auto-detects project language. Use before publish, deploy, merge, or external PR submission.
-version: 1.0.0
-requires:
-  tools: [bash, node, npm]
-  optional_tools: [trivy, gitleaks, codespell, markdownlint-cli2, eslint, cargo, go, python3]
-  runtime: false
-metrics:
-  tracks: [rounds_passed, rounds_failed, rounds_warned, total_issues, critical_issues, test_count, test_pass_rate, type_coverage_pct, vulnerability_count]
-  improves: [code_quality, security_posture, documentation_completeness, publish_readiness]
----
-
-# Validator
-
-## When to Use
-
-- Before `npm publish` / `cargo publish` / any package release
-- Before merging a PR to your own repo
-- Before submitting a PR to an external repo (NVIDIA, Google, CNCF, etc.)
-- After a major refactor or dependency update
-- On any project — auto-detects language from marker files
-
-**Skip when:**
-- Trivial docs-only changes (run rounds 5, 8 only)
-- Quick iteration cycles (run round 0 + 2 only: compile + test)
-
-## Quick Start
-
-```text
-Run the Validator on ~/DevDrive/my-project
-```
-
-Target specific rounds:
-
-```text
-Run Validator round 0-2 on my-project (compile + lint + test only)
-```
-
-PR-readiness for external submission:
-
-```text
-Run Validator PR-readiness checks on my-project for NVIDIA/NeMo-Agent-Toolkit-Examples
-```
-
-## Language Auto-Detection
-
-Detect project type from marker files. When multiple markers exist, run checks for ALL detected languages.
-
-| Marker File(s) | Language | Compile | Lint | Test | Security |
-|---|---|---|---|---|---|
-| `package.json` + `tsconfig.json` | TypeScript | `tsc --noEmit` | ESLint | `npm test` | `npm audit` |
-| `package.json` (no tsconfig) | JavaScript | `node --check *.js` | ESLint | `npm test` | `npm audit` |
-| `Cargo.toml` | Rust | `cargo check` | Clippy + rustfmt | `cargo test` | `cargo audit` |
-| `go.mod` | Go | `go build ./...` | golangci-lint | `go test ./...` | `govulncheck` |
-| `pyproject.toml` / `setup.py` | Python | `py_compile` | Ruff + Bandit | pytest | Bandit |
-| `Dockerfile` | Docker | `docker build --check` | Hadolint | — | Trivy |
-| `foundry.toml` | Solidity | `forge build` | `forge fmt --check` | `forge test` | Slither |
-| `*.sh` | Shell | `bash -n` | ShellCheck | — | — |
-
-## The 14 Rounds
-
-Execute in order. Round 0 is a **blocking gate** — if it fails, stop everything.
-
-### Round 0 — Compile Gate (BLOCKING)
-
-If this fails, ALL subsequent rounds are blocked. Fix compile errors first.
-
-```bash
-# TypeScript
-npx tsc --noEmit
-
-# JavaScript
-find . -name "*.js" -not -path "*/node_modules/*" -exec node --check {} \;
-
-# Rust
-cargo check
-
-# Python
-python3 -m py_compile <each .py file>
-```
-
-**Pass criteria:** Zero compile errors.
-
-### Round 1 — Lint
-
-```bash
-# TypeScript/JavaScript
-npx eslint . --ext .ts,.js,.tsx,.jsx 2>&1
-
-# Rust
-cargo clippy -- -D warnings
-
-# Python
-ruff check . 2>&1
-
-# Go
-golangci-lint run ./...
-```
-
-**Pass criteria:** Zero errors. Warnings are advisory.
-
-### Round 2 — Test Suite
-
-```bash
-# Node.js
-npm test
-
-# Rust
-cargo test
-
-# Python
-pytest -v
-
-# Go
-go test ./...
-```
-
-**Pass criteria:** All tests pass. Report total count and pass rate.
-
-### Round 3 — Security Audit
-
-```bash
-# Node.js
-npm audit --audit-level=high
-
-# Rust
-cargo audit
-
-# Python
-pip-audit
-
-# Container
-trivy fs --severity HIGH,CRITICAL .
-```
-
-**Pass criteria:** Zero HIGH or CRITICAL vulnerabilities. LOW/MODERATE are advisory.
-
-### Round 4 — Type Coverage
-
-```bash
-# TypeScript
-npx type-coverage --at-least 90
-
-# JavaScript (JSDoc)
-# Count @param, @returns, @type annotations
-grep -r "@param\|@returns\|@type" --include="*.js" -l | wc -l
-```
-
-**Pass criteria:** ≥90% for TypeScript. For JS, report JSDoc annotation count.
-
-### Round 5 — Documentation
-
-Check that these exist and are non-trivial:
-- [ ] README.md (≥50 lines)
-- [ ] Version mentioned in README or badge
-- [ ] Installation instructions
-- [ ] Usage examples with real code
-- [ ] License declared (package.json or LICENSE file)
-- [ ] CHANGELOG.md (if versioned package)
-
-**Pass criteria:** All items checked.
-
-### Round 6 — Changelog
-
-- [ ] CHANGELOG.md exists
-- [ ] Current version has an entry
-- [ ] Entry describes what changed (not just "bug fixes")
-
-**Pass criteria:** Current version documented.
-
-### Round 7 — Secrets Detection
-
-```bash
-# gitleaks (git history)
-gitleaks detect --source . -v 2>&1
-
-# detect-secrets (current files)
-detect-secrets scan . 2>&1
-```
-
-**Pass criteria:** Zero real secrets. Document false positives (contract addresses, example values) and recommend `.gitleaksignore` entries.
-
-### Round 8 — Spelling
-
-```bash
-codespell --skip="node_modules,dist,.git,package-lock.json,*.min.js" .
-```
-
-**Pass criteria:** Zero typos in source code and documentation.
-
-### Round 9 — Link Verification
-
-Check all URLs in README.md and documentation:
-
-```bash
-# Extract URLs and test each
-grep -oP 'https?://[^\s\)\"]+' README.md | while read url; do
-  code=$(curl -o /dev/null -s -w "%{http_code}" "$url")
-  if [ "$code" != "200" ] && [ "$code" != "301" ]; then
-    echo "BROKEN: $url → $code"
-  fi
-done
-```
-
-**Pass criteria:** All links return 200 or 301. Flag example.com/placeholder URLs as advisory.
-
-### Round 10 — PR-Readiness (for external submissions)
-
-- [ ] Conventional commit messages (`feat:`, `fix:`, `docs:`, etc.)
-- [ ] DCO sign-off on commits (`git commit -s`)
-- [ ] SPDX license headers in source files
-- [ ] No merge commits (rebase-clean history)
-- [ ] Branch is up-to-date with target
-
-**Pass criteria:** All items for external PR targets. DCO/SPDX are advisory for own repos.
-
-### Round 11 — Cross-Platform Compatibility
-
-- [ ] No hardcoded absolute paths
-- [ ] No macOS-only or Linux-only commands without guards
-- [ ] No case-sensitive filename conflicts
-- [ ] `engines` field in package.json (Node.js)
-- [ ] `.env.example` exists if `.env` is used
-
-**Pass criteria:** Works on macOS, Linux, and CI runners.
-
-### Round 12 — Dependency Health
-
-```bash
-# All deps pinned (no * or latest)
-grep -E '"[\*]"|"latest"' package.json
-
-# Lock file committed
-ls package-lock.json || ls yarn.lock || ls pnpm-lock.yaml
-
-# Clean install
-npm ci --dry-run
-```
-
-**Pass criteria:** Deps pinned, lock file committed, clean install works.
-
-### Round 13 — Summary & Verdict
-
-Compile results from all rounds:
-
-```
-## Validator Report — [Project] v[Version]
-
-| Round | Check | Result |
-|-------|-------|--------|
-| 0 | Compile | ✅/❌ |
-| 1 | Lint | ✅/⚠️/❌ |
-| ... | ... | ... |
-
-**Verdict:** PASS ✅ / WARN ⚠️ / FAIL ❌
-**Score:** X/14 rounds clean
-
-Blocking issues: [list or "none"]
-Advisory warnings: [list or "none"]
-```
-
-## Verdicts
-
-| Verdict | Meaning |
-|---------|---------|
-| **PASS ✅** | All rounds clean. Safe to publish/merge. |
-| **WARN ⚠️** | No blockers but advisory issues exist. Safe to publish, address warnings when convenient. |
-| **FAIL ❌** | Blocking issues in Round 0-3. Fix before proceeding. |
-
-## Output
-
-Save the full report to `ops/reports/validator-YYYY-MM-DD-HH-<project>.md` in the workspace.
-
-## Tips
-
-- Run rounds 0-2 frequently during development (fast feedback)
-- Run full 14 rounds before any publish or external PR
-- Round 7 (secrets) is critical before pushing to public repos
-- Round 10 (PR-readiness) only matters for external repo submissions
-- Use `--skip-round N` to skip specific rounds when re-running after fixes