A Claude Code plugin with 17 AI skills, 5 guardrail hooks, and specialized subagents for full-stack development (Next.js 14 + Python FastAPI). The plugin enforces best practices structurally — TDD via agent boundaries, mandatory PR gates, docs on every push — so good habits happen automatically.
# 1. Register this repo as a marketplace
claude plugin marketplace add https://github.com/tapway/tapway-superpowers
# 2. Install the plugin
claude plugin install tapway-superpowers@tapway-superpowersSkills and hooks activate immediately. No restart, no config files.
Recommended companion plugins:
claude plugin install andrej-karpathy-skills@karpathy-skills
claude plugin install claude-code-setup@claude-plugins-official- Modes
- GitHub Actions — AI-Powered PR Review
- Release Convention — YYYY.WW.XX.YY
- What You Get
- Slash Commands Reference
- Built-in Claude Code Skills
- Guardrails That Run Silently
- Upgrading
- For Template Users
- Uninstalling
Not sure which mode applies? Use this table:
| Situation | Mode |
|---|---|
| Solo developer, building a new feature or fixing a bug | Individual |
| Team of 2+ people working on the same repo in parallel | Team Collaboration |
| Taking over or improving an existing codebase without tests | Legacy Refactor |
Full guide: this section covers it. No separate document needed.
/interview → /brainstorming → /plan → [implement] → /simplify → /review → /pr
/interview is optional but recommended any time the request is underspecified. /observe runs before /pr on any new endpoint. /doubt is called on demand for high-stakes decisions.
Step 0 — Clarify (when the request is fuzzy)
/interview
One question at a time. Stops when it can predict your next three questions. Outputs a Confirmed Intent statement (outcome / user / why now / success / constraints / out of scope) that feeds into /brainstorming or /plan. Never start planning until intent is confirmed.
Step 1 — Brainstorm (optional, but recommended for anything non-trivial)
/brainstorming
Explore approaches, surface trade-offs, name confusion before writing code. Output is committed to docs/brainstorming/. Run /deep-research first if the domain is unfamiliar.
Step 2 — Plan
/plan
Generates docs/plans/[feature].md with file map, task breakdown, and success criteria. For multi-task features, also generates a work package checklist at docs/checklists/[feature]-checklist.md.
Step 3 — Implement
Fast path — fully automated:
"implement it with autopilot" → /autoship
Reads the plan, validates it, runs TDD subagents per task, then simplify → review → PR. You only intervene if a task blocks twice.
Deploy mode — on a staging server:
"implement and deploy" → /autoship (deploy mode)
Same as above, but adds a deployment phase before opening the PR: detects the deploy method (docker compose / make / npm), deploys, waits for a health check, runs integration and E2E tests, then includes the deployment evidence in the PR body. Never opens a PR with a broken deployment.
Manual path — step by step:
/tdd
Test Writer agent (RED) → coordinator gate → Implementer agent (GREEN + REFACTOR) per task. Structurally impossible to skip the failing test.
Between steps — on demand
/doubt
Use this any time you're about to commit to an irreversible decision: service boundary, schema migration, auth flow, security assumption. Spawns a fresh-context adversarial reviewer that sees only the artifact + contract — never your reasoning. Max 3 cycles.
/observe
Run this before /pr on any new endpoint, background task, or external integration. Defines on-call questions first, then adds structured logging (with correlation IDs), RED metrics (bounded labels), OpenTelemetry auto-instrumentation, and symptom-based alerts. Includes staging verification: induce failures, confirm telemetry catches them.
Step 4 — Pre-PR sequence (always, in this order)
/simplify ← reduce complexity and duplication
/review ← three-tier self-review (Critical / Warnings / Suggestions)
/pr ← rebase, test, update docs, push, open PR
/pr is mandatory — it rebases against main, runs the full test suite, updates project docs, and opens a structured PR. Never push manually.
Full guide: docs/team-guide.md — step-by-step walkthrough with Alice, Bob, and Charlie working on JWT auth in parallel, with exact commands and Claude prompts for every step.
Tech lead: /brainstorming → /plan → commit docs → assign packages
Each member: worktree → /tdd or /autoship → /pr
After all PRs: merge in dependency order → /release
One worktree per person per package. Never two people editing the same branch.
# After self-assigning in docs/checklists/[feature]-checklist.md:
git worktree add -b feat/[feature]-[package] ../[project]-[package] origin/main
cd ../[project]-[package] && claude
# Tell Claude: "I'm picking up the [Backend] work package for [feature]. Let's start implementing."Docs as the coordination layer. docs/checklists/ is the live status board — who has what, what's in progress, what's merged. No Slack threads needed for "who's doing what".
docs/
brainstorming/ ← why we chose this approach
plans/ ← what we're building and how
checklists/ ← who is doing what, current status
Auto-review on every PR + @claude for fixes. Every PR gets an automatic three-tier code review when opened. After review, anyone can mention @claude in a comment to push fix commits directly to the branch. See GitHub Actions — AI-Powered PR Review for setup instructions and the required ANTHROPIC_API_KEY secret.
Merge order matters. If Package B depends on Package A's schema changes, merge A first and have B rebase:
git fetch origin && git rebase origin/main
# resolve any conflicts, then re-push# Self-assign and start
# 1. Edit docs/checklists/[feature]-checklist.md → set Assignee + 🟡
git add docs/checklists/ && git commit -m "chore: claim [package] for [name]" && git push
# 2. Create worktree
git worktree add -b feat/[feature]-[package] ../[project]-[package] origin/main
cd ../[project]-[package] && claude
# 3. Implement (automated or manual)
# "implement it with autopilot" OR /tdd
# 4. Exit via PR (never push manually)
# /simplify → /review → /prFull guide: docs/legacy-refactor-guide.md — complete workflow for teams taking over an existing codebase.
You cannot safely refactor code you haven't locked down with tests. On legacy code that means writing characterization tests — tests that capture current behavior before you change anything — before the first line of refactored code is written.
Install superpowers → /repo-docs → /code-review + /security-audit
→ /brainstorming (refactor goals)
→ Characterization tests ← lock down current behavior FIRST
→ /plan → /tdd → /pr
| Step | Standard (new feature) | Legacy refactor |
|---|---|---|
| Tests | Written for desired behavior | Written for current behavior first |
| RED phase | Fails because feature doesn't exist | Fails because code is too coupled to unit-test |
| GREEN phase | Implement the behavior | Decouple/extract until test + characterization tests pass |
| Plan scope | New capabilities | Specific code smells with measurable before/after |
For renames, deprecated API replacements, and import path updates across many files — use the optional code-refactor community skill:
claude plugin add code-refactor@andrej-karpathy-skillsAlways write characterization tests before running bulk changes on untested code. Bulk renames on untested code cascade silently into broken behavior.
# 1. Generate architecture docs first
/repo-docs
# 2. Run audits (parallel)
/code-review
/security-audit
# 3. Set refactoring goals
/brainstorming
# "Given the audit findings, what does this codebase need to look like in 6 months?"
# 4. Write characterization tests — before any production change
# See docs/legacy-refactor-guide.md for examples
# 5. Plan + execute + PR
/plan → /tdd → /prThe plugin ships a GitHub Actions workflow (.github/workflows/claude.yml) that gives every PR an automatic AI code review and lets any team member trigger fix commits by mentioning @claude in a comment.
This must be added to each project repo separately. Run
/setup-projectin any repo to create and commit the file automatically.
Add ANTHROPIC_API_KEY to GitHub repo secrets — this is required for any of the below to work.
GitHub repo → Settings → Secrets and variables → Actions → New repository secret
Name: ANTHROPIC_API_KEY
Value: your key from https://console.anthropic.com
Without this secret, the workflow will be present but every run will fail with an authentication error.
The workflow contains two separate jobs with different triggers and permissions:
| Property | Value |
|---|---|
| Trigger | PR opened, updated (synchronize), or reopened |
| Permissions | Read-only (contents: read, pull-requests: write) |
| What it does | Posts a three-tier code review as inline PR comments |
Claude reads the full diff and posts findings categorised as:
- Critical — must fix before merge (bugs, security issues, data loss risks, broken contracts)
- Warning — should fix or justify (missing tests, type gaps, N+1 queries, unhandled errors)
- Suggestion — optional improvements (simplification, naming, duplication)
If Critical findings exist, Claude requests changes. If only Warnings/Suggestions, it approves with comments. The review summary is prefixed with ## Auto-review so it's clearly labelled as automated.
| Property | Value |
|---|---|
| Trigger | @claude in any PR comment, review comment, or review body |
| Permissions | Read-write (contents: write) — can push fix commits |
| What it does | Executes whatever instruction follows @claude |
Common uses:
@claude fix the Critical findings from the auto-review
@claude fix the failing test in test_auth_service.py
@claude resolve the merge conflict in this file
@claude explain why this approach was chosen
Option A — Automated (recommended):
/setup-project
Creates .github/workflows/claude.yml, commits it, and prints the remaining manual steps including the secret reminder.
Option B — Manual:
mkdir -p .github/workflows
# Copy .github/workflows/claude.yml from this repo into your project
git add .github/workflows/claude.yml
git commit -m "chore: add @claude GitHub Actions workflow"
git pushThen add ANTHROPIC_API_KEY to GitHub repo secrets.
- Open any PR in the repo
- Within ~30 seconds, an
## Auto-reviewcomment should appear from theauto-reviewjob - On the same PR, comment
@claude explain what this PR does— theon-mentionjob should reply within ~30 seconds
If either job doesn't fire or errors out, check:
ANTHROPIC_API_KEYis set in repo secrets (Settings → Secrets and variables → Actions)- Both jobs have
id-token: writein theirpermissionsblock — the action uses OIDC for authentication and will fail with "Unable to get ACTIONS_ID_TOKEN_REQUEST_URL" without it - Both jobs have
actions/checkout@v4as the first step — the action runsgit fetchinternally and will fail with "fatal: not a git repository" if the repo isn't checked out first - The workflow file exists at
.github/workflows/claude.yml - GitHub Actions is enabled for the repo (Settings → Actions → General)
Each auto-review run costs roughly $0.50–2.00 depending on the size of the diff (input tokens). on-mention runs vary by task. For a small team running 20–30 PRs/month, expect under $30/month total.
To limit auto-review to specific branches (e.g. only PRs targeting main):
on:
pull_request:
types: [opened, synchronize, reopened]
branches: [main] # add this lineReleases are created automatically every time a PR merges to staging or prod, via .github/workflows/release.yml.
YYYY.WW.XX.YY-env
| Segment | Meaning | Example |
|---|---|---|
YYYY |
Year | 2026 |
WW |
ISO week number (01–53) | 24 |
XX |
Major increment within the week | 1 |
YY |
Minor increment within XX (bugfix / small change) | 3 |
-env |
Target environment | -stg or -prod |
2026.24.1.0-stg ← first merge of week 24 to staging
2026.24.1.1-stg ← bugfix on top of 1.0
2026.24.1.2-stg ← another small change
2026.24.2.0-stg ← breaking change or major feature (XX increments, YY resets)
2026.24.1.0-prod ← stg 1.0 promoted to prod
- YY increments on every merge by default
- XX increments (and YY resets to 0) when any commit in the merge contains
feat!orBREAKING CHANGEin the message - Both counters reset to
XX=1 YY=0at the start of each new week stgandprodmaintain independent XX.YY counters
release.yml is created automatically by /setup-project. It requires only the built-in GITHUB_TOKEN — no extra secrets needed.
Set staging as your repo's default branch (GitHub → Settings → Branches → Default branch) so gh pr create targets it automatically (branch name: staging, tag suffix: -stg).
AI behaviors that activate automatically when you use relevant keywords. Also invokable explicitly with /skill-name.
| Skill | What it does | Triggers |
|---|---|---|
brainstorming |
Explore approaches, surface trade-offs, save decisions to docs/brainstorming/ |
"Let's think about...", "What are the options..." |
writing-plans |
Implementation plans with file maps, task breakdowns, and work package checklists. Saves to docs/plans/ + docs/checklists/ |
"Write a plan...", "Break this down..." |
autoship |
Fully automated plan-to-PR: validates plan, runs TDD subagents per task, then simplify → review → docs → PR. Deploy mode (on staging server): also deploys, health-checks, and runs integration/E2E tests before PR | "implement it with autopilot", "autoship" / "implement and deploy", "ship and deploy" |
tdd |
Test Writer agent (RED) → coordinator gate → Implementer agent (GREEN + REFACTOR). Structurally enforces TDD. | "Start implementing...", "implement", any new feature or bug fix |
verification |
Confirm a task is done — tests, lint, type-checks, spec coverage | "Is this done?", "Verify...", "Final check..." |
refactor |
Protocol A (active codebase): surgical incremental refactoring. Protocol B (legacy): characterization-test-first sequence | "Refactor...", "Clean up...", "Legacy refactor..." |
code-review |
Three-tier review: Critical, Warnings, Suggestions | "Review my changes...", "Check this before I push..." |
systematic-debugging |
Repro → Isolate → Hypothesize → Test → Fix → Post-mortem saved to docs/post-mortems/ |
"Why is X failing?", "Debug...", "Works locally but not in prod..." |
pr |
Rebase, conflict resolution, test gate, update docs, push, open PR, update checklist | "Create a PR...", "I'm done...", "Push and PR..." |
git-worktrees |
Manage parallel git worktrees for concurrent feature work | "Worktree...", "Parallel branches..." |
repo-docs |
Generate ARCHITECTURE.md, WORKFLOWS.md, DB_SCHEMA.md, DEPLOYMENT.md |
"Document this repo...", "Write architecture docs..." |
security-audit |
Full-codebase OWASP Top 10 audit — for pre-launch or major refactors | "Security audit...", "Audit the whole codebase..." |
pre-review-cleanup |
Scan for template placeholders, boilerplate, and stale scaffold code | "Clean up template files...", "Remove boilerplate..." |
setup-project |
One-time setup: creates .github/workflows/claude.yml and CLAUDE.md, commits, prints checklist for remaining manual steps |
"set up the @claude workflow", "setup project", "add @claude to this repo" |
interview |
Requirements extraction — one question at a time before planning begins. Stops when it can predict your next 3 questions. Outputs a Confirmed Intent statement. | "interview me", "help me figure out requirements", "I'm not sure what I want" |
doubt |
Adversarial in-flight decision review. Fresh-context subagent gets only artifact + contract (never your reasoning). Finds problems, doesn't approve. Max 3 cycles. | "second opinion", "double-check this decision", "stress-test this design" |
observe |
Structured observability shipped with the feature: on-call questions first → structured logs + correlation IDs → RED metrics → OTel → symptom-based alerts → staging verification | "add observability", "add logging", "add metrics", "add tracing", "instrument this" |
deprecate |
Safe removal of APIs, modules, or features: decision gate → replacement first → advisory/compulsory type → migration guide → Strangler/Adapter/Feature-flag → zero-usage gate → remove | "deprecate this", "remove this API", "sunset this feature", "migrate away from X" |
All skills apply Andrej Karpathy's coding principles: Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution.
Automatic checks that fire on Claude Code lifecycle events.
| Hook | Event | What it does |
|---|---|---|
pre-bash-safety |
PreToolUse (Bash) | Blocks force-push, hard-reset on main, direct commits to main. Blocks prod commands unless ALLOW_PROD=1 is set. |
post-write-lint |
PostToolUse (Write|Edit) | Runs the project linter on changed files |
pre-commit-secrets |
PreToolUse (git commit) | Scans staged files for secrets, keys, and credentials before allowing a commit |
session-start |
SessionStart | Displays project info, git status, and environment summary when Claude Code opens |
post-commit-release-note |
PostToolUse (git commit) | Parses conventional commits and appends formatted entries to CHANGELOG.unreleased.md |
Subagent definitions for use with the TDD and autoship skills:
| Agent | Purpose |
|---|---|
code-reviewer |
Systematic review with security, performance, and type-safety checks |
test-writer |
Write tests following project conventions (pytest / Jest) |
security-auditor |
OWASP Top 10 audit for auth, payments, and user data paths |
devops-sre |
Docker, CI/CD, and infrastructure configuration review |
| Command | Mode | Purpose |
|---|---|---|
/setup-project |
All | One-time project setup: creates .github/workflows/claude.yml and CLAUDE.md, commits, and prints a manual-steps checklist (GitHub secret). Run this in any new repo adopting the plugin. |
/interview |
All | Extract requirements one question at a time before planning. Use when the request is underspecified. Output feeds into /brainstorming or /plan. |
/brainstorming |
All | Explore approaches before coding |
/plan |
All | Write implementation plan + work package checklist |
/autoship |
Individual / Team | Run full plan-to-PR loop automatically. Add "and deploy" to also deploy + run integration tests before PR (staging server only) |
/tdd |
Individual / Team | TDD subagents for task-by-task implementation |
/refactor |
Individual / Legacy | Incremental (Protocol A) or legacy characterization-test workflow (Protocol B) |
/doubt |
All | Adversarial review of any high-stakes decision before it's locked in. Use for irreversible changes, service boundaries, security assumptions. |
/observe |
All | Add structured logging, RED metrics, OTel, and alerts to any new endpoint or task. Run before /pr. |
/pr |
All | Rebase, test, update docs, push, open PR, update checklist — mandatory exit |
/deprecate |
All | Safe removal of any API, module, or feature. Enforces: replacement first, migration guide, zero-usage gate. |
/repo-docs |
Legacy / All | Generate architecture, schema, workflow, deployment docs |
/cleanup |
Individual | Remove template artifacts (tapway-claude-template users only) |
/review |
All | Three-tier self-review before PR |
/release <patch|minor|major> |
All | Semver bump, release notes, git tag |
/upgrade-skills |
All | Update all plugins to latest |
These ship with Claude Code — no installation needed. Several are wired into the skills above.
| Built-in | What it does | When to use |
|---|---|---|
/deep-research |
Multi-source web research with fact-checking and citations | Before /brainstorming for unfamiliar tech |
/bugfix |
Repro-first: failing test → root cause → minimal fix → regression test | Focused code bugs |
/investigate |
Parallel hypothesis agents with adversarial refutation; formal root-cause report | Production incidents |
/simplify |
Reviews changed code for reuse, simplification, efficiency; applies fixes | Always after /tdd, before /review |
/security-review |
Security review of the current branch diff | Before PRs touching auth, payments, user data |
/verify |
Launches the app and observes behavior in a running environment | Golden-path confirmation beyond tests |
/security-review vs /security-audit: /security-review scans the current diff (fast, pre-PR). /security-audit scans the full codebase (thorough, pre-launch or after major refactors).
These happen automatically — no commands needed:
- Can't commit to
maindirectly — the hook blocks it and tells you to create a branch - Can't run prod commands accidentally — blocked unless
ALLOW_PROD=1is set - Secrets caught before commit — staged files scanned for keys and credentials on every
git commit - Linting after every file edit — runs the project linter automatically
- Release notes auto-generated — every conventional commit appends to
CHANGELOG.unreleased.md - Docs updated on every PR —
/prruns/repo-docsor updates affected doc sections before pushing - Missing workflow detected on session start — if
.github/workflows/claude.ymlis absent, the session-start hook warns and tells you to run/setup-project
/upgrade-skills
Or manually:
claude plugin marketplace update
claude plugin update tapway-superpowers@tapway-superpowersRestart Claude Code after updating to apply changes.
If you cloned the tapway-claude-template, this plugin is already declared in .claude/settings.json and auto-installs on first open. No install commands needed.
claude plugin uninstall tapway-superpowers@tapway-superpowersYour code and project docs are unaffected.
MIT © Tapway