bmad-plus review

bmad-plus review is the evidence layer of a code review. It does not read your code with a model and it does not judge it: the assistant (usually Sentinel) does the reading. The command fixes what is being reviewed (the scope), checks that every quoted finding really sits in the code, and derives the verdict from what was actually covered, so a review that stopped halfway can never be reported as clean. Use it when you want a review whose result you can check, script or gate a pull request on.

Synopsis#

npx bmad-plus review <action> [id] [options]
npx bmad-plus review rules [path]
npx bmad-plus review compare <id> --since <earlier-id>

id names a review and becomes a folder: lowercase letters, digits, dots and dashes, starting with a letter or digit, at most 81 characters (for example pr-42). rules is the only action that takes a path instead of an id.

The order of work#

1. 01

   Seal the scope

   review scope <id> writes scope.json and a checklist of the rules that apply to the changed paths. The scope has a digest: any later change of code or rules is detectable.

   In your project terminal

   npx bmad-plus review scope pr-42 --base main --effort high

2. 02

   Review and write the evidence

   The assistant reads the files, writes findings.json (each finding quotes its code verbatim, with category, severity, confidence and disposition) and coverage.json (every selected file ends as completed, failed or waived with a reason). BMAD+ never calls a model for this.

3. 03

   Anchor the findings

   review anchor <id> finds each quoted excerpt in the code. Line numbers written by a model are never used; only the quote is.

   In your project terminal

   npx bmad-plus review anchor pr-42

4. 04

   Ask for the verdict

   review gate <id> derives clean, findings or incomplete. Add --emit-check to get a JSON document a CI step can consume.

   In your project terminal

   npx bmad-plus review gate pr-42 --emit-check ci/review-check.json

5. 05

   Resume or compare when needed

   review continue <id> after an interruption; review compare <new-id> --since <id> after the code changed and you reviewed again.

What it reads and writes#

The command reads the git history and files of the project (it starts git for rev-parse, diff, merge-base and ls-files) and the review rules. It writes only inside <dir>/<id>/, plus the --emit-check file. It opens no network connection and calls no model.

Closed vocabularies#

An unknown value is an error, never coerced. A refuted finding must keep its refutation, a confirmed one needs evidence, a failed or waived file needs a reason. Only run.stop: completed lets the gate reach a verdict; any other reason keeps it incomplete. A unit that fails three attempts in a row is abandoned and stays failed.

Effort levels and the plan#

A pass is a complete read of the scope; later passes look for what earlier ones missed. The plan printed by scope also depends on size: from 150 changed lines the reviewer plans before reading, and with more than one unit and at least 400 changed lines the units can be reviewed in parallel. A unit groups at most 8 files and 400 lines.

Files that are never selected#

• secret: .env*, keys and certificates (*.pem, *.key, *.p12, *.pfx, id_rsa*, id_ed25519*), .npmrc, .netrc, and anything under credentials/, .credentials/ or secrets/. Checked before any --include, so no pattern can bring them in.
• binary, deleted, excluded-by-pattern (your --exclude), not-included (outside your --include).
• generated-or-vendored: node_modules, dist, build, coverage, vendor, minified files, source maps and lockfiles, unless an --include pattern matches them.
• The review folder itself: writing findings never changes the scope they answer.

Review rules#

A rule is a Markdown checklist chosen by file path. Every rule whose patterns match a file applies to it, so rules add up. Eight ship with the CLI.

When the Shield pack is installed, six compliance rules are added (they never replace or disable a built-in one): shield-access-control, shield-personal-data, shield-cryptography, shield-logging, shield-ai-integrations and shield-change-and-supply-chain. Each names the controls it examines as FRAMEWORK:ID, for example ISO27001:A.8.5, SOC2:CC6.1, NIST-800-53:AC-3 or NIS2:Art.21(2)(i), and a finding may cite only controls that the rules for its file examine.

A project adds, replaces (same id) or disables rules in _bmad/review-rules.yaml. Its doc files are Markdown, resolved next to that file. Disabling an unknown id is an error.

schema: bmad-plus/review-rules/1
rules:
  - id: billing-money
    title: Money amounts
    group: code
    globs: ['src/billing/**/*.ts']
    doc: review-rules/billing-money.md
disable:
  - python

Exit codes#

Sample output#

These transcripts are simulated: the lines follow the message templates of the command, the numbers and the digest are illustrative. The paths printed by the real command are absolute.

$ npx bmad-plus review scope pr-42 --base main --effort high
<project>/_bmad-output/review/pr-42/scope.json
3 file(s) to review, 41 changed lines, 1 unit(s) — scope 3f9a1c0d52b7
  excluded 1 × generated-or-vendored
checklist: <project>/_bmad-output/review/pr-42/checklist.md
plan: high effort, 3 pass(es), refutation pass
Every selected file must end in coverage.json as completed, failed or waived (with a reason).

$ npx bmad-plus review gate pr-42
pr-42: incomplete — coverage 1/3 completed (0 waived), 0 open finding(s), 0 refuted
  - 2 selected file(s) never accounted for: src/a.js, src/b.js
# Exit code 2. The review owes two files.

$ npx bmad-plus review gate pr-42 --emit-check ci/review-check.json
pr-42: clean — coverage 3/3 completed (0 waived), 0 open finding(s), 0 refuted
  check: <project>/ci/review-check.json
  clean: no open finding within a fully covered scope. It does not prove the code correct.
# Exit code 0.

The --emit-check document is stable (no timestamp, so the same evidence gives the same bytes). It carries the status, exit code, reasons, counts, the scope it answers, the open findings with their lines and a github block shaped like the check-runs API: conclusion (success or failure) and an output with a Markdown summary and up to 50 annotations. A working-tree review writes its check inside the review folder or outside the project, so it cannot enter the change it reports on.

Errors and what to do#

Errors print review: <message> on the error stream (or a JSON object with status: "error" under --json) and exit 3.

Examples#

Sentinel, review this branch against main. If the BMAD+ CLI is available, seal the scope with bmad-plus review scope pr-42 --base main --effort high, quote every finding verbatim, then anchor and gate it, and report the gate answer without upgrading it.

Sentinel, continue the review pr-42 where it stopped. Use bmad-plus review continue pr-42 and only do what it lists.

Sentinel, compare review pr-43 with pr-42 using bmad-plus review compare pr-43 --since pr-42 and tell me what is new, what persists and what is really resolved.

Sentinel, run bmad-plus review rules src/auth/login.ts and tell me which rules and which compliance controls apply.

Using it in CI#

The repository ships copy-ready GitHub Actions recipes in docs/recipes/ci-review/: review-scope.yml seals the scope and publishes the checklist (no agent, no model), review-gate.yml has the host agent installed on a self-hosted runner write the evidence, verifies that nothing outside the review folder changed, anchors the findings and fails the check on incomplete or open findings. They run only for pull requests from the repository itself, never from forks, and need no model key stored in GitHub. In a script, the three exit codes are enough: 0 passes, 1 means findings to read, 2 means the evidence is not there yet.