cape

Audit test quality — identify tautological tests, coverage gaming, missing corner cases

Work with br (beads) issue tracking — create, update, query, close issues

Explore a feature or design problem interactively before writing code

Generate and create a git branch from session context

Challenge assumptions in designs, implementations, or requirements

Create atomic git commits with conventional format

Check code changes against documented conventions in CLAUDE.md and rules files

Investigate bugs and create br bug issues with root cause analysis

Generate competing interface designs under conflicting constraints

Execute plan tasks iteratively from br epics

Guided codebase walkthrough that builds understanding progressively

Scan a directory or module for untested behavior

Verify and close a br epic after all tasks are complete

End-to-end bug fix workflow from discovery to closure

Create a pull request with description and test plan

Behavior-preserving code transformation

Review staged or uncommitted code changes for bugs, logic errors, and convention violations

Stress-test a br task for edge cases and missing criteria

Enforce the RED-GREEN-REFACTOR cycle when implementing features or fixing bugs

Formalize brainstorm design into br epic with first task

Use this agent when debugging a bug and you need to trace execution backward from an error, find what changed, identify instrumentation points, or compare working vs broken code paths.

Use this agent when a major implementation step has been completed and needs to be reviewed against the epic contract (requirements, anti-patterns, success criteria) and coding standards.

Use this agent when you need to understand current codebase state, find existing patterns, or verify assumptions about what exists. Dispatched during planning, debugging, bug fixing, task expansion, test analysis, and task refinement.

Use this agent to verify claims, assertions, or assumptions against codebase and external evidence before acting on them. Catches hallucinated paths, wrong function signatures, and stale assumptions.

Use this agent when you need current information from the internet, API documentation, library usage patterns, or external knowledge. Dispatched during planning, debugging, and bug fixing.

Use this agent when planning or designing features and you want to surface past decisions, research notes, or references the user has already captured in their personal notebox.

Use this agent to audit test quality — identifies tautological tests, coverage gaming, weak assertions, and missing corner cases. Use when reviewing test files for effectiveness, during analyze-tests workflows, or when test quality is in question.

Use this agent to run tests, pre-commit hooks, or commits without polluting your context with verbose output. Runs commands, captures all output, and returns only summary and failures.

Audit quality of existing tests — identify tautological tests, coverage gaming, weak assertions, and missing corner cases. Use this skill whenever the user mentions test quality, test effectiveness, tautological tests, coverage gaming, "are these tests any good", "audit tests", "review test quality", test rot, flaky tests, or wants to understand whether existing tests actually catch bugs. Also triggers on: "these tests feel useless", "coverage is high but bugs keep shipping", "would these tests catch a real bug", pointing at a test file and asking if it's worth keeping. This skill audits EXISTING test quality — not finding missing tests (use find-test-gaps), writing new tests (use test-driven-development), or debugging test failures (use debug-issue).

How to use br (beads) — the CLI issue tracker for epics, tasks, and bugs. Use this skill whenever the user mentions br, beads, .beads, or issue tracking. Triggers on: creating/updating/closing/querying br issues, br command errors (e.g. --design not working on br create), asking what task to work on next, tracking findings from code review or test gap analysis as br issues, setting up a beads workspace, or building a skill that should output br items. Also use when the user says "create a bead", "log this bug", "track this", or asks about issue priorities, types, dependencies, or ready/blocked status. Also triggers when the conversation contains strings that look like bead IDs — the pattern is `<prefix>-<hash>[.<number>]` where prefix is a workspace name (e.g. cape, nit.nvim, br), hash is 3-8 alphanumeric characters, and an optional dot-number suffix for subtasks. Examples: cape-2vo, cape-2vo.13, nit.nvim-7f5, br-3. If you see an identifier matching this pattern, it is likely a bead ID — use this skill to look it up with `br show`.

Use BEFORE writing any code for new features, integrations, or system changes. Triggers when the user describes something to build, asks "how should I approach X", is unsure between approaches, or mentions adding/creating/building functionality. Also use when requirements are vague, architecture is unclear, or the task involves design decisions (e.g., choosing libraries, data models, API patterns). Do NOT use for bug fixes, refactoring where the target structure is clear (use cape:refactor), executing existing plans, or tasks where the implementation path is already clear. This skill researches the codebase, asks Socratic questions, generates competing designs under different constraints, and produces a design summary for `cape:write-plan` to formalize into a br epic.

Use this skill whenever the user wants to CREATE or SET UP a new git branch. This includes any request to generate a branch name, start a new branch, check out a fresh branch, or begin work that requires branching. Covers explicit requests ("create a branch", "new branch", "branch for this") and implicit ones ("set up a branch for X", "start working on X" when no branch exists). Also applies to `/cape:branch`. Do NOT use for operations on existing branches: switching, deleting, listing, rebasing, merging, pushing, or comparing branches.

Challenge assumptions in designs, implementations, or requirements. Use when reviewing a proposed design before committing, auditing completed work for scope creep, or when the user asks to challenge/question/audit assumptions. Triggers on: "challenge this", "check my assumptions", "what am I assuming", "audit this design", "did I over-engineer", reviewing a plan before execution, or reflecting after implementation. Do NOT use for test gap analysis (use cape:find-test-gaps) or debugging (use cape:debug-issue).

Create atomic git commits with conventional commit format and selective staging. Use whenever the user wants to commit changes — explicit requests ("commit this", "make a commit", "let's commit", "/cape:commit") and implicit ones ("we're done, save this", "wrap this up"). Also use when another cape skill finishes a unit of work and needs to commit. Covers staging decisions, splitting large diffs into separate logical commits, and writing thorough commit messages that explain the change. Do NOT use for pushing, creating PRs, or branch operations.

Check code changes against documented conventions in CLAUDE.md and rules files. Use whenever the user asks to check convention adherence — "check my code against rules", "does this conform", "lint conventions", "check rules", "/cape:conform", or any request to verify code follows documented standards. Covers project and global CLAUDE.md rules plus per-language rule files in ~/.claude/rules/. Do NOT use for bug-finding or code quality review (use cape:review), running external linters (use cape check), or investigating bugs (use cape:debug-issue).

Systematic debugging workflow that investigates bugs with tools before guesses and evidence before hypotheses. Use when the user reports something broken, shares a stack trace, encounters a test failure, sees unexpected output, says "this doesn't work", "something is wrong", "why is X happening", or pastes an error message. Also use when the user asks to debug, diagnose, trace, or find the root cause of a problem. This skill investigates only -- it finds the root cause and documents it as a br bug issue with evidence and reproduction steps. Do NOT use for applying fixes (use fix-bug after investigation), quick config tweaks where the solution is already known, performance profiling without a specific defect, or feature design (use brainstorm).

Generate competing code interface designs (API surfaces, module boundaries, function signatures, type contracts) using parallel sub-agents with conflicting constraints. Use whenever the user asks to design an interface, API surface, module boundary, or type contract. Triggers on: "design an interface", "what should the API look like", "module boundary", "function signature", "type contract", "API surface", "how should callers interact with this", "what should this expose". Also triggers when brainstorm identifies the core design question as an interface shape question. Do NOT use for UI/UX design, full feature brainstorming where requirements are unclear (use cape:brainstorm), or implementing an already-designed interface (use cape:execute-plan).

Meta-skill that activates cape's workflow system. Injected at session start — always active, never manually triggered. Routes every task to the right cape skill and enforces workflow chains: brainstorm before planning, plan before coding, TDD during implementation, debug before fixing. If you're about to act on a user request, check this skill's routing table first. When a cape skill matches the task, using it is mandatory.

Builds code from a br epic, one task at a time. The counterpart to cape:write-plan -- write-plan creates the epic, this skill implements it. TRIGGER: any user intent to make forward progress on planned work. Common signals: "continue", "next task", "resume", "let's go", "work on the plan", a bare "Continue.", br task IDs like br-7.3, or transitioning after planning is complete. Picks up from br state automatically -- never asks where you left off. Implements one task, reflects on learnings, creates the informed next task, then stops for user review. NOT for: initial planning (cape:brainstorm, cape:write-plan), bug investigation, status queries, or git operations.

Internal skill called by execute-plan before implementation begins. Takes a single br task and expands it into a concrete, zero-context implementation plan with exact file paths, line numbers, code changes, and verification commands. Never called directly by users — execute-plan invokes this automatically when a task lacks an expanded plan. Do NOT use for creating epics (use cape:write-plan), stress-testing edge cases (use cape:task-refinement), or executing the plan itself (use cape:execute-plan).

Guided codebase walkthrough that builds understanding progressively. Use whenever the user asks to understand code — "explain", "how does X work", "walk me through", "what does this module do", "give me an overview", "I'm new to this part of the codebase", "teach me", or any question about how code flows, connects, or is structured. Covers everything from single functions to full system architecture. Do NOT use for investigating bugs (use debug-issue) or for internal agent queries about codebase state (that's codebase-investigator).

Scan a directory or module for untested behavior and create br tasks per gap found. Make sure to use this skill whenever the user mentions test gaps, missing tests, untested code, test coverage for a specific scope, or wants to know what's not tested before a refactor or after shipping a feature. Triggers on any of these patterns: "find test gaps", "what's untested", "check test coverage", "improve tests for", "we need tests for", "what's not covered", "test completeness", "missing test cases", pointing at a directory and asking about its tests, mentioning they shipped something and want to verify test completeness, or preparing for a refactor and wanting safety nets. This skill is specifically about FINDING gaps (static analysis, source-to-test mapping, bug risk assessment) — not about writing tests (use test-driven-development), auditing existing test quality (use analyze-tests), debugging test failures (use debug-issue), or running a test suite. Even if the request seems simple, use this skill — it provides structured br output with per-module tasks that plain analysis does not.

Verify and close a br epic after all tasks are complete. Use when the user says "finish the epic", "we're done", "close out the epic", all tasks are done and the user wants to close it, or execute-plan detects all success criteria appear met. Runs final verification (tests, linting, hooks), checks every success criterion with evidence, executes manual verification steps from the epic, appends an Outcome to the epic, and closes it. Also triggers on epic IDs combined with closure intent. Do NOT use for implementing tasks (use execute-plan), creating plans (use write-plan), or git operations (merge/PR/push — user handles those).

End-to-end bug fix workflow from discovery to closure. Triggers on: "fix this bug", "can you fix", user wants to address a diagnosed br bug, applying a fix after debug-issue, "the fix for br-N", fixing a regression, patching broken behavior. Also use when the user has a br bug issue and wants to resolve it, or when they report a bug and want it fixed (not just investigated). Do NOT use for investigation-only (use debug-issue), feature work (use execute-plan), or refactoring without a specific defect (use cape:refactor).

Create a pull request with clear description and actionable test plan. Use whenever the user wants to open a PR — explicit requests ("create a PR", "open a pull request", "let's PR this", "/cape:pr") and implicit ones ("ship it", "ready for review", "push this up"). Also use when finish-epic completes and the user wants to publish their work. Runs automatable test plan items before creating the PR. Do NOT use for reviewing someone else's PR (use cape:review) or committing (use cape:commit).

Behavior-preserving code transformation workflow — the "evolve chain." Use whenever the user wants to restructure code without changing what it does. Triggers on: "refactor", "extract", "inline", "rename across", "move this to", "reduce duplication", "simplify", "split this function", "clean up", "restructure", "decouple", "untangle." Also triggers mid-workflow: when execute-plan hits structural problems that block feature work, or when review/code-reviewer flags structural issues to act on. Covers single-operation refactorings (Extract Method, Rename) through multi-step restructurings (decompose module, invert dependency). Do NOT use for: adding new behavior (use execute-plan), fixing broken behavior (use fix-bug), architectural redesign where the target structure is unclear (use brainstorm).

Review code changes for bugs, logic errors, security issues, and design problems using structural analysis from the code-review-graph. Use whenever the user wants a code review — explicit requests ("review my changes", "review this", "check my code", "/cape:review") and implicit ones ("anything wrong here?", "is this ready?", "look this over"). Also use when reviewing someone else's PR or branch. Covers self-review before committing, pre-PR review, and reviewing others' work. Do NOT use for writing review (prose, docs) or for committing (use cape:commit).

Stress-test a br task for missing edge cases, vague criteria, implicit assumptions, and unspecified failure modes before implementation begins. Use after cape:write-plan creates a task and before cape:execute-plan picks it up. Triggers on: "refine this task", "stress-test br-N", "check this task", "is this task ready", reviewing a task for completeness, any mention of edge cases or failure modes in the context of a br task. Also use when the user wants to harden a task description or feels unsure whether a task captures enough detail. Do NOT use for creating epics or tasks from scratch (use cape:write-plan), executing tasks (use cape:execute-plan), or investigating bugs (use cape:debug-issue).

Drive behavioral changes with tests that are written before the production code they justify. Use this skill whenever implementing a feature, fixing a bug, adding behavior, or changing logic that automated tests can verify. Also use when another cape skill (fix-bug, execute-plan) says to follow TDD. Do NOT use for: verification testing (manual run-the-app checks), documentation changes, configuration changes, or refactoring that has no behavioral change.

Formalize a brainstorm design into a br epic with immutable requirements and a first task. Use after cape:brainstorm has produced a design summary. Triggers on: user runs /cape:write-plan, "create the epic", "formalize this design", "write the plan", transitioning from brainstorm to implementation. Do NOT use for initial exploration (use cape:brainstorm), executing existing plans (use cape:execute-plan), or bug investigation (use cape:debug-issue).

6 hooks across 4 events