Skip to content

CLAUDE.md

Latest commit

 

History

History
207 lines (163 loc) · 7.58 KB

CLAUDE.md

File metadata and controls

207 lines (163 loc) · 7.58 KB
Raw

@AGENTS.md

Agent skills

Issue tracker

GitHub Issues on complexthings/superpowers via gh; external PRs are not a triage request surface. See docs/agents/issue-tracker.md.

Triage labels

Use the default labels: needs-triage, needs-info, ready-for-agent, ready-for-human, and wontfix. See docs/agents/triage-labels.md.

Domain docs

Single-context layout with root CONTEXT.md and docs/adr/. See docs/agents/domain.md.

RTK (Rust Token Killer) - Token-Optimized Commands

🎯 SKILLS

Skills extend your capabilities with proven workflows.

Discover Skills First

Before starting any task, check for relevant skills:

  1. Use your native skill tool to list available skills.
  2. Review skill descriptions/frontmatter to identify relevant ones.

Skill Loading Rules

  • Load skills JIT only — never preload to "understand" them.
  • Follow skill instructions exactly as written — no skimming, no shortcuts.
  • If a skill has a checklist, create a todo for each item — no mental tracking.
  • Simple tasks benefit from skills as much as complex ones.

Skill priority (highest to lowest): Project → Personal

Using Tools with Skills

  1. Native skill tool — load skills via your platform's native skill tool.
  2. Symlinked skills — Superpowers skills are symlinked into your platform's skills directory.
  3. Fallback — if a skill isn't found via the native tool, inspect the configured skill directories and read its SKILL.md directly.
  4. Tool equivalence — when a skill references a tool you don't have, substitute your equivalent.

Why Skills Matter

Skills encode proven techniques that prevent mistakes. Not using them means repeating solved problems and missing edge cases.

If a skill exists for your task, you MUST use it.

Version Check

Periodically, e.g. once per day check the version of superpowers-agent:

  1. CURRENT_VERSION — run a superpowers-agent command and extract X.Y.Z from the ^^SAV:X.Y.Z^^ string in its output.
  2. NPM_LATEST_VERSION — run npm view @complexthings/superpowers-agent version.
  3. Compare by semver precedence, not string comparison (e.g. 9.10.0 > 9.9.0). If NPM_LATEST_VERSION is newer, tell the user — do not run these yourself:

    Your superpowers-agent has updates (CURRENT_VERSION → NPM_LATEST_VERSION). Run:

    npm install -g @complexthings/superpowers-agent
superpowers-agent bootstrap && superpowers-agent setup-skills
    If versions match, or either lookup fails (e.g. no network), continue silently.

Generated by Superpowers on 2026-07-12

Golden Rule

Always prefix commands with rtk. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use.

Important: Even in command chains with &&, use rtk:

# ❌ Wrong
git add . && git commit -m "msg" && git push

# ✅ Correct
rtk git add . && rtk git commit -m "msg" && rtk git push

RTK Commands by Workflow

Build & Compile (80-90% savings)

rtk cargo build         # Cargo build output
rtk cargo check         # Cargo check output
rtk cargo clippy        # Clippy warnings grouped by file (80%)
rtk tsc                 # TypeScript errors grouped by file/code (83%)
rtk lint                # ESLint/Biome violations grouped (84%)
rtk prettier --check    # Files needing format only (70%)
rtk next build          # Next.js build with route metrics (87%)

Test (60-99% savings)

rtk cargo test          # Cargo test failures only (90%)
rtk go test             # Go test failures only (90%)
rtk jest                # Jest failures only (99.5%)
rtk vitest              # Vitest failures only (99.5%)
rtk playwright test     # Playwright failures only (94%)
rtk pytest              # Python test failures only (90%)
rtk rake test           # Ruby test failures only (90%)
rtk rspec               # RSpec test failures only (60%)
rtk test <cmd>          # Generic test wrapper - failures only

Git (59-80% savings)

rtk git status          # Compact status
rtk git log             # Compact log (works with all git flags)
rtk git diff            # Compact diff (80%)
rtk git show            # Compact show (80%)
rtk git add             # Ultra-compact confirmations (59%)
rtk git commit          # Ultra-compact confirmations (59%)
rtk git push            # Ultra-compact confirmations
rtk git pull            # Ultra-compact confirmations
rtk git branch          # Compact branch list
rtk git fetch           # Compact fetch
rtk git stash           # Compact stash
rtk git worktree        # Compact worktree

Note: Git passthrough works for ALL subcommands, even those not explicitly listed.

GitHub (26-87% savings)

rtk gh pr view <num>    # Compact PR view (87%)
rtk gh pr checks        # Compact PR checks (79%)
rtk gh run list         # Compact workflow runs (82%)
rtk gh issue list       # Compact issue list (80%)
rtk gh api              # Compact API responses (26%)

JavaScript/TypeScript Tooling (70-90% savings)

rtk pnpm list           # Compact dependency tree (70%)
rtk pnpm outdated       # Compact outdated packages (80%)
rtk pnpm install        # Compact install output (90%)
rtk npm run <script>    # Compact npm script output
rtk npx <cmd>           # Compact npx command output
rtk prisma              # Prisma without ASCII art (88%)

Files & Search (60-75% savings)

rtk ls <path>           # Tree format, compact (65%)
rtk read <file>         # Code reading with filtering (60%)
rtk grep <pattern>      # Search grouped by file (75%). Format flags (-c, -l, -L, -o, -Z) run raw.
rtk find <pattern>      # Find grouped by directory (70%)

Analysis & Debug (70-90% savings)

rtk err <cmd>           # Filter errors only from any command
rtk log <file>          # Deduplicated logs with counts
rtk json <file>         # JSON structure without values
rtk deps                # Dependency overview
rtk env                 # Environment variables compact
rtk summary <cmd>       # Smart summary of command output
rtk diff                # Ultra-compact diffs

Infrastructure (85% savings)

rtk docker ps           # Compact container list
rtk docker images       # Compact image list
rtk docker logs <c>     # Deduplicated logs
rtk kubectl get         # Compact resource list
rtk kubectl logs        # Deduplicated pod logs

Network (65-70% savings)

rtk curl <url>          # Compact HTTP responses (70%)
rtk wget <url>          # Compact download output (65%)

Meta Commands

rtk gain                # View token savings statistics
rtk gain --history      # View command history with savings
rtk discover            # Analyze Claude Code sessions for missed RTK usage
rtk proxy <cmd>         # Run command without filtering (for debugging)
rtk init                # Add RTK instructions to CLAUDE.md
rtk init --global       # Add RTK to ~/.claude/CLAUDE.md

Token Savings Overview

Category Commands Typical Savings
Tests vitest, playwright, cargo test 90-99%
Build next, tsc, lint, prettier 70-87%
Git status, log, diff, add, commit 59-80%
GitHub gh pr, gh run, gh issue 26-87%
Package Managers pnpm, npm, npx 70-90%
Files ls, read, grep, find 60-75%
Infrastructure docker, kubectl 85%
Network curl, wget 65-70%

Overall average: 60-90% token reduction on common development operations.