Review with the other model before you ship

You end with a review report from a model of another family and a clean second run.

SpecWeave CLI
1:33
Claude Code and Codex
Narrated, with captions

Recorded on SpecWeave 3.1.0 and codex-cli 0.162.1, 18 October 2026, added 18 October 2026.

Before you start: Node.js 20.12 or later and git; SpecWeave installed with npm i -g specweave and a repo set up with specweave init; the Codex CLI installed and signed in (codex login); an increment whose tasks are done on a branch, so there is a diff against main.

Length 1:33Captions

Steps

Finish the increment's tasks on a branch. The ledger records who finished each one (claude@demo in the recording).
Run specweave review --brief to see what the reviewer gets without running it: who wrote the code (counted from the ledger's done events), the acceptance criteria, the Approach, the tasks and the diff of the task files since the merge-base with main.
Run specweave review. It picks the first installed reviewer from another model family (Codex for code Claude wrote, Claude for code an OpenAI model wrote) and sends it that brief; Codex reviews it with codex exec in a read-only sandbox, using its own sign-in.
Read reports/review-codex.md in the increment folder. Every finding names a severity and a path:line. With any critical or high finding the verdict is fix first and specweave review exits 3.
Fix every critical and high finding (or add a task for it), run the tests, and commit.
Run specweave review again. With no critical or high finding left the verdict is ship and the exit code is 0. Each run appends a note to ledger.jsonl with the reviewer and its verdict, and specweave pickup shows the latest notes.
Each run keeps its own report in reports/reviews/review-<reviewer>-<n>.md, and reports/review-<reviewer>.md is always the latest; each ledger note names its own run's file. (In SpecWeave 3.1.0, as recorded, every run overwrote reports/review-<reviewer>.md; this changed in 3.1.1.)
Then run specweave verify and close the increment with specweave complete.

Real output of the SpecWeave 3.1.0 CLI in a sample repo inside a disposable home, recorded headlessly. The review is a real Codex run: `specweave review` started codex-cli 0.162.1 with its built-in command (GPT-6.1-Sol, high reasoning, read-only sandbox); each review took about 30 seconds, and that wait is cut, with the verdict shown when it arrived. Agent sessions are not shown: the commands ran in a terminal as Claude Code (SPECWEAVE_TOOL=claude), which is how the ledger reads claude@demo. Claude Code's original change, its fix and the new test were scripted off camera for the demo and committed under the claude tool id; the video shows the fix commit with `git show`, and the end card says so. The brief, the fix commit and the overwritten report's verdict line were captured afterwards from the same disposable home, without running the reviewer. Some output is shortened on screen, marked with a dimmed …: the brief shows only its author, acceptance criteria and first diff hunk; the report's first line, an HTML comment with the reviewer, base and head commits and the time, is cut; the fix commit's file headers are cut; and the verdict lines show …/reports/review-codex.md instead of the absolute path into the disposable home. As the video says, the second review overwrote reports/review-codex.md, so the fix-first report the first ledger note names no longer exists (a SpecWeave 3.1.0 limitation fixed in 3.1.1, where each run keeps its own report under reports/reviews/). Nothing was pushed. Narration is an AI voice (ElevenLabs, the author's cloned voice); captions are timed from the voice service's character timestamps.

Transcript

Built from the caption file of the narration.

0:00 What you will do

Review with the other model before you ship.

0:04 What a reviewer gets

Claude Code finished this task on a branch. specweave review --brief shows what a reviewer gets: who wrote the code, from the ledger, the acceptance criteria, and the diff since the branch began.

0:17 Codex reviews: fix first, exit 3

Before you ship, run specweave review. Claude wrote the code, so it picks Codex, from another family. Codex gets the brief in a read-only sandbox. This run took about 30 seconds. Its verdict is fix first, so the command exits 3.

0:34 What reports/review-codex.md says

The review is saved in reports/review-codex.md. Each finding cites a file and line, and how to fix it. Here, a blank name gets no fallback, which breaks AC-02.

0:47 Fix the finding

Claude's fix trims the name, and falls back to world when it's empty. It also adds a test for blank names. Run the tests: all three pass.

0:57 Review again: ship, exit 0

Then run specweave review again, on the fixed code. No critical or high finding is left, so the verdict is ship, and the exit code is 0.

1:07 Each verdict in the ledger

Each run adds a note to the ledger, with the reviewer and its verdict. Both notes name the same file, and the second run overwrote it: the fix-first report is gone, so keep a copy if you need it. specweave pickup shows the latest notes to whoever comes next.