# Reapr mutation-audit agent skill

> Your agent writes tests that pass. This skill makes them catch bugs. mutation-audit runs Reapr on your diff, writes one focused test per surviving mutant, and reruns until each one is killed. It never changes your production code.

Source: https://reapr.dev/skill

## What it does

The skill runs `rpr run --diff <base> --json`. For each surviving mutant it states the behavior the mutant changes, writes one focused test in the repo's conventions, runs the test, then reruns rpr and keeps the test only when the mutant is killed. Equivalent mutants, which no test can kill, are reported instead of getting a forced test. When the intended behavior is unclear, it asks the human instead of writing a test that pins a possible bug. It also lists tests that cover the diff but kill no mutant, and checks the diff for edge cases mutation operators do not produce.

## Requirements

- rpr, Linux x86_64 or aarch64 (macOS and Windows are planned):

  ```sh
  curl -LsSf https://github.com/reapr-corp/reapr/releases/latest/download/rpr-installer.sh | sh
  ```

- A mutation engine: StrykerJS with a config file (JavaScript, TypeScript; Node.js 20.10 or later), or cargo-mutants 26.2 to 27.x (Rust).

## Install in Claude Code

1. Install the plugin:

   ```text
   /plugin marketplace add reapr-corp/reapr
   /plugin install reapr@reapr
   ```

   On Claude Code 2.1.275 or later, one step does both: `/plugin install reapr --marketplace reapr-corp/reapr`

2. Run `/reapr:setup`. It checks rpr, the engine and its config, measures the baseline score, and offers to add the CI job and the agent rule, asking before every change.

3. Run `/reapr:mutation-audit`, or ask Claude to check the tests on the current branch.

## Install in other agents (Cursor, Codex, Gemini CLI and others)

1. Install rpr with the command above.
2. Give the agent the rules below (the same file is at https://raw.githubusercontent.com/reapr-corp/reapr/main/plugins/reapr/AGENTS.md). It links the full workflow in SKILL.md: https://github.com/reapr-corp/reapr/blob/main/plugins/reapr/skills/mutation-audit/SKILL.md
3. Ask the agent to check the tests on the current branch.

The contents of AGENTS.md:

````markdown
# Reapr: instructions for coding agents

For any agent (Cursor, Codex, Copilot, Aider and others) asked to check, strengthen or review the tests of a
branch or pull request. Point the agent at this file or copy it into the agent's instructions.

The skill runs Reapr (`rpr run --diff <base> --json`, or `rpr run --all --json` for a whole-codebase audit) and
uses the surviving mutants as evidence: one focused test per survivor, confirmed killed by a second run. It flags
tests that cover the scope but kill nothing, then audits the code for edge cases that mutation operators do not
represent.

## Hard rules

- Never change production code, thresholds or engine config, and never create an engine config. If rpr, the
  engine or a StrykerJS config is missing, follow Setup below (`npx stryker init` is the human's to run).
  Rust projects use `--engine cargo-mutants`, whose config is optional; it has no thresholds, so only
  `--min-score` (the human's choice) gates it.
- When the intended behavior is ambiguous (the code disagrees with docs, types, names, callers, specs or an
  existing test, or nothing specifies it), ask the human. Do not write a test that pins the current behavior.
- A test is done only when a later `rpr` run (the same `--diff <base>` or `--all` command as the first) shows
  it kills a mutant. Engine-only checks (`cargo mutants -f <file>`) are for iterating, not for the report.
  Equivalent mutants are listed for the human with the input domain that makes them equivalent, not forced.
- Never delete tests; change existing tests only with the human's OK. One behavior per test, in the repo's
  conventions, inside the diff scope. Rust tests go in the mutated package; commit them before re-running
  `rpr --diff`, or the scope shifts.
- Do not change process-wide state (env vars, cwd, PATH) in tests; use a child process or a project-local fake.

- Generate one UUID v4 per session (`uuidgen` or `node -e 'console.log(crypto.randomUUID())'`) and prefix
  every `rpr` command with `RPR_INVOKED_BY=mutation-audit RPR_SESSION_ID=<uuid>`. It only tags Reapr's
  anonymous telemetry and changes nothing when `DO_NOT_TRACK` is set.

## Setup (first use)

Ask before every step that changes anything. 1. `rpr --version`, else offer the installer
(`curl -LsSf https://github.com/reapr-corp/reapr/releases/latest/download/rpr-installer.sh | sh`). 2. Detect
StrykerJS (package.json with vitest/jest, `stryker.*config*` files, per package in monorepos) or cargo-mutants
(`Cargo.toml`); both → `--engine`. 3. cargo-mutants installed (`cargo install --locked cargo-mutants`); for
StrykerJS a config must exist: never write one, ask the human to run `npx stryker init`, and stop until it
exists. 4. Baseline: `RPR_INVOKED_BY=setup RPR_SESSION_ID=<uuid> rpr run --all --json` per config; report score,
survivors per file and time. 5. Optionally, with consent, a `reapr-corp/run@v1` pull-request job and an agent
rule. Full steps: [skills/setup/SKILL.md](skills/setup/SKILL.md).

## Workflow

Follow the full workflow in [skills/mutation-audit/SKILL.md](skills/mutation-audit/SKILL.md). Ignore its YAML
header; where it says `/reapr:setup`, use the Setup section above. `${CLAUDE_SKILL_DIR}` in it means the
`skills/mutation-audit` folder next to this file.
````

## What it never does

- Change production code to kill a mutant. If a test shows the code is wrong, it reports the bug and stops.
- Lower a threshold, or change Reapr's flags to move the score.
- Edit your engine config, or invent one when the repo has none.
- Rewrite or delete an existing test without asking you.

## Results

- On Reapr's own Rust codebase, the skill raised the mutation score from 89.51% to 94.65%: 23 surviving mutants killed by 8 new tests, with no production code changed (https://github.com/reapr-corp/reapr/pull/30).
- In the skill's evals (four prompts on a TypeScript + Vitest + StrykerJS fixture, each run with and without the skill), 21 of 21 rule checks passed with the skill and 14 of 21 without it. Without the skill, the agent wrote its own Stryker config when the repo had none, and rewrote existing tests without asking (https://github.com/reapr-corp/reapr/pull/14, https://github.com/reapr-corp/reapr/blob/main/plugins/reapr/skills/mutation-audit/evals/evals.json).

## Frequently asked questions

### Does it work without Claude Code?

Yes. Claude Code installs it as a plugin. Cursor, Codex, Gemini CLI and other agents can follow the same workflow: point them at AGENTS.md in the reapr repository, which has the hard rules and links the full SKILL.md.

### Does it send my code anywhere?

No. The skill runs rpr and your own test suite on your machine. rpr sends one anonymous usage event per run, with counts and durations and never code, paths or names, and DO_NOT_TRACK=1 turns it off. Every property is listed at reapr.dev/telemetry.

### Does it change my Stryker or cargo-mutants config?

No. It never edits or creates an engine config, never lowers a threshold and never changes Reapr's flags. It adds test files, and it changes an existing test only after you say yes.

### What if my repo has no Stryker config?

The skill stops and tells you to create one with npx stryker init. It does not write one itself: the config decides the test runner, what is mutated and the thresholds, and those are your team's choices.

### Does it work with Rust?

Yes. rpr supports cargo-mutants (26.2 to 27.x), and the skill runs it with the project's own .cargo/mutants.toml when there is one. On Reapr's own Rust code it raised the mutation score from 89.51% to 94.65% with 8 new tests.