Skip to main content
command CX Codex

verify · coco-research — Claude Code command: requirement checks

The verify command checks completed work against a plan or specification, then grades the evidence for each requirement. Run it before shipping changes.

MIT ★ 328 updated 2026-10-29

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/verify.md
Open on GitHub

What verify does

verify runs a staged check of an implementation against its requirements. It builds a checklist, reruns checks in a detached clean worktree, and compares the results with the builder’s own assessment. Requirements can be graded MET, PARTIAL, NOT MET, or UNVERIFIED.

The pipeline uses Python scripts under ~/.claude/skills/team-gate/scripts/, including verify_independent.py, run_gate.py, and claim_evidence.py. A later stage examines whether the cited evidence supports each claim and whether local checks can be reproduced in CI.

Git must be available for the independent rerun; otherwise, the result is UNVERIFIED. The command also reads plan and report files under .team-ship/.

What it helps with

  • compare an implementation with its plan or PRD
  • rerun checks in a clean worktree
  • grade evidence for each requirement
  • find mismatches between the builder’s claim and the rerun
  • check whether local results can be reproduced in CI

Example prompts for the agent

  • Check the implementation against the requirements in .team-ship/PLAN.md.
  • Rerun the checks in a clean worktree and compare the results with the builder’s assessment.
  • Verify the changes before shipping and identify requirements without supporting evidence.

How to install verify

Manually: put the files in place

.claude/commands/verify.md

Call it with /verify. For all projects use ~/.claude/commands/

Questions about verify

How do I install verify in Claude Code?

Copy the command file to .claude/commands/verify.md. Then invoke it with /team verify.

What does verify do?

It checks completed work against a plan and reruns checks in a separate worktree. It then grades requirements and audits the supporting evidence.

Why does verify need Git?

The independent rerun creates a clean worktree at the current HEAD. If Git is unavailable, the check is marked UNVERIFIED.

Source text

verify.md · MIT
---
description: "Use when built work must be checked against its spec, plan, or PRD before shipping, or the team router action is verify. Re-runs the gate from a clean checkout per requirement and grades it MET, PARTIAL, NOT MET, or UNVERIFIED."
---
# /team verify: Verification Pipeline

> Called by team.md router when action is `verify`.
> Checks if what was built matches what was planned/specified.

## Role Selection Bias

| Layer | Preferred Roles | Count |
|-------|----------------|-------|
| L1 | business-analyst, technical-analyst | 2 |
| L2 | qa-test-architect, (domain-dependent engineers) | 2-4 |
| L3 | domain-accuracy, standards-reviewer, architecture-reviewer (if `.arch/index.json` exists) | 2-3 |
| L4 | principal-pm | 1 |

## Stage 1: Brownfield Map

```
python3 ~/.claude/skills/team-gate/scripts/brownfield_map.py --for "<what is being verified in words>" --repo-root .
```
exit 0: continue; read `.team-ship/BROWNFIELD-MAP.md` before reading any code.
exit 1: not used; a map is not a pass or fail judgement.
exit 2: UNVERIFIED; quote the gate file's summary (gates/handoff-1-map.json).

No verify-pipeline aggregator requires this gate file; until one exists, the map is the first step by instruction.

## Pipeline Customization

### Layer 1: Spec Extraction
L1 agents gather.
- The spec/plan/PRD that defined what should be built
- `.arch/index.json` and its pin, if present, the structural baseline for failure mode (e)
- Success criteria, acceptance criteria, NFRs
- Review findings that were supposed to be addressed
- Build a requirements checklist with unique IDs

```
python3 ~/.claude/skills/team-gate/scripts/arch_gate.py --repo-root .
```
exit 0: continue; the index is CURRENT, quote the pin and head from `.arch/ARCH-GATE.json`.
exit 1: continue; a REMOVE verdict already exists, quote the reason from `.arch/ARCH-GATE.json` and carry it to Layer 3.
exit 2: continue; STALE, the index is absent (no .arch/index.json, which the script reports as not found), or drift is unreconciled, record which and carry it to Layer 3 for failure mode (e).

### Layer 2: Independent Re-Execution
- **Mode:** `bypassPermissions`, verify agents must run the gate themselves, not just read files.
- **Independence rule:** verify agents must not read the builder's summary, REVIEW-PACKAGE.md, or any "tests pass" claim before re-running. They form their own evidence first, then compare.

1. Run `verify_independent.py setup` to create a detached clean worktree at HEAD and print the exact invocation for the Layer 2 verify agent.

```
python3 ~/.claude/skills/team-gate/scripts/verify_independent.py setup --repo-root .
```
exit 0: continue; spawn the Layer 2 verify agent with the printed invocation line and nothing else, so it never reads the builder's summary, REVIEW-PACKAGE.md, or any "tests pass" claim.
exit 1: BLOCK; `.team-ship/` carries tracked files inside the worktree, quote the reason and the tracked file list.
exit 2: UNVERIFIED; git is unavailable or the run state cannot be read.

The worktree is a detached checkout of the same repository at HEAD, not a separate clone.

2. Each Layer 2 agent runs only the three commands the printed invocation names, `run_gate.py --repo-root . --role verifier discover`, then `run`, then `coverage`, and reports their three exit codes, nothing else. This writes gates/7-verifier.json, gates/8-verifier.json, and gates/10-verifier.json.

Provision what CI provisions inside the worktree before spawning the agent. When something cannot be provisioned, record "override integration: <reason>" in your own words as the human, and run_gate's skip rule decides the rest.

3. Run `verify_independent.py compare` to check the verifier's re-run against the builder's own gate file.

```
python3 ~/.claude/skills/team-gate/scripts/verify_independent.py compare --repo-root .
```
exit 0: continue and quote the gate file's summary (gates/11.json).
exit 1: BLOCK; quote the mismatches from the gate file, the discrepancy between the builder's claim and the re-run output.
exit 2: UNVERIFIED; the run directory or either gate file cannot be read.

4. Run `verify_independent.py teardown` to remove the worktree.

```
python3 ~/.claude/skills/team-gate/scripts/verify_independent.py teardown --repo-root .
```
exit 0: continue; the worktree is removed.
exit 1: not used; teardown exits 0 or 2.
exit 2: UNVERIFIED; the worktree or run state cannot be read.

5. Once every Layer 2 agent's re-execution is captured in the run's gate files, run `claim_evidence.py matrix` once over the whole plan to grade every requirement.

```
python3 ~/.claude/skills/team-gate/scripts/claim_evidence.py matrix .team-ship/PLAN.md --repo-root .
```
exit 0: continue; every requirement is MET, quote the gate file's summary (gates/11-matrix.json).
exit 1: NOT MET exists; quote which requirements from the gate file.
exit 2: UNVERIFIED exists with no NOT MET; quote which requirements from the gate file, never counts as MET.

A requirement the matrix grades MET may still be judged PARTIAL on closer inspection, and an implementation that goes beyond what the matrix can see is EXCEEDED, flag for review; both stay model judgement written after the matrix, since the matrix itself grades only MET, NOT MET, or UNVERIFIED.

**Toolkit integration:**
- Check team:toolkit.md for verification tools (e.g., GSD verify-work)
- If GSD active, cross-reference `.planning/REQUIREMENTS.md`

### Layer 3: Evidence Audit
L3 agents verify Layer 2's claims, and explicitly check for these failure modes, any one downgrades the verdict.
- Does the cited evidence actually prove the requirement is met?
- Are any "MET" claims actually PARTIAL on closer inspection?
- **(a) Skipped-as-passed**, tests reported "pass" while the summary shows skips, or DB-gated tests skipped because no dependency was provisioned.
- **(b) Coverage without measurement**, a coverage number with no captured `--cov` output.
- **(c) Not CI-reproducible**, a claim that only holds locally (weaker tool version, or a DSN unavailable in CI).
- **(d) Merge masquerade**, "merged" or CI-green implied for a branch not reachable from `main`.

(a), (b), and (d) are the same finding, a PR-body claim contradicted or unbacked by the evidence it cites.

```
python3 ~/.claude/skills/team-gate/scripts/claim_evidence.py check .team-ship/PR-BODY.md --repo-root .
```
exit 0: continue and quote the gate file's summary (gates/12.json).
exit 1: BLOCK; quote the findings from the gate file, including any merge-claim phrase whose named condition does not hold, and strip the unbacked claim.
exit 2: UNVERIFIED; the repository, run, lexicon, or a required input file (PR-BODY.md, EVIDENCE.json) cannot be read.

```
python3 ~/.claude/skills/team-gate/scripts/run_gate.py --repo-root . parity
```
exit 0: continue; local tool versions match CI's pinned versions, quote the gate file's summary (gates/7.json).
exit 1: BLOCK; a tool version mismatch, quote the gate file's summary (gates/7.json).
exit 2: UNVERIFIED; discover has not run yet or its gate file cannot be read.

DSN availability in CI for (c) is covered by the same provisioning paragraph in Layer 2.

- **(e) Architecture abandoned**, the build satisfied its requirements while silently
  abandoning the module boundaries it was built against. This is the one failure mode no
  test can surface: tests fail when behaviour changes, not when a component is relocated,
  merged into another, or deleted outright.

  Applies only when `.arch/index.json` exists.

  ```
  python3 ~/.claude/skills/team-gate/scripts/arch_gate.py --repo-root .
  ```
  exit 0: continue; a printed MAJOR line names a PRUNE verdict, quote which paths died from `.arch/ARCH-GATE.json`; otherwise report NO DRIFT for this failure mode.
  exit 1: CRITICAL; a REMOVE verdict (zero surviving primary paths), quote the dead paths from `.arch/ARCH-GATE.json`.
  exit 2: UNVERIFIED, never clean; the pin is behind HEAD, the index is absent (no .arch/index.json, which the script reports as not found), or drift is unreconciled.

  Files added outside every claimed path, forming a new top-level source directory, are MAJOR regardless of exit code, either a component is missing from the index or the build went somewhere it was not supposed to. This stays a review judgement no script makes.

  **Scope limit, and state it in the finding:** this detects *structural* drift only. A
  component whose datastore was swapped inside its own already-claimed directory returns
  `NO DRIFT`. A clean result licenses one sentence, that no structural drift was found,
  and no broader claim about architectural soundness.
- Requirements missed entirely surface as UNVERIFIED in the same requirements matrix (gates/11-matrix.json), a requirement absent from every gate's mapping.

### Layer 4: Verdict
Principal produces.
- **Pass/Fail verdict**: Pass requires compare (gates/11.json), matrix (gates/11-matrix.json), and check (gates/12.json) all at exit 0, and arch_gate (`.arch/ARCH-GATE.json`) at exit 0 or an override receipt naming gate "arch". Any `UNVERIFIED` surface or any Layer 3 finding (a) through (e) forces Fail or a downgraded, gap-listed verdict.
- Requirements traceability matrix, gates/11-matrix.json from Layer 2 (requirement, status, captured evidence)
- Gap list: what's missing, prioritized by impact
- Recommendation: ship as-is, fix gaps first, or rework needed

## GSD Integration

When `.planning/` exists, verify requirements from REQUIREMENTS.md. Cross-reference with phase success criteria.

© coco-research · MIT · coco-research/coco

Similar slash commands

All slash commands for Testing and QA →

verify by other authors comes first.

verify Manavarya Singh verify rebuilds a page from design tokens, compares the render with the live site, and reports a fidelity score. Use it to check an extracted design system. CX Codex +1 ★ 5,183repo stars verify Affaan Mustafa The verify command checks the build, types, lint, tests, logs, and Git state. Use it before a commit or pull request. CX Codex +1 ★ 6,739repo stars modernize-verify official Anthropic Re-runs verification of modernized code independently and assigns each module one verdict: PROVEN, PARTLY PROVEN, or NOT PROVEN. The verdict comes from a script with fixed rules, not from the agent. CX Codex +1 ★ 47,914repo stars maestro-verify ReinaMacCredy The maestro-verify skill checks acceptance criteria against verification evidence, records a verdict, and guides bundle closure. Use it before handing work back or closing a task. CX Codex +1 ★ 238repo stars verify-and-stop JuliusBrussee verify-and-stop proves existing work meets acceptance criteria without expanding scope. Useful for validation tasks and last-mile checks. CX Codex +1 129,000installs verify-this cursor The verify-this skill tests a specific claim against fresh local evidence: it captures before and after measurements, compares artifacts, and returns one verdict. CX Codex +1 2,600installs gsd-verify-work open-gsd gsd-verify-work is a Claude Code skill that runs conversational user acceptance testing for completed features. Validates changes test by test and outputs a markdown report. CX Codex +1 594installs vibe-verify KhazP The vibe-verify skill exercises a running product against acceptance criteria and reports evidence. A passing build on its own proves nothing about behavior. CX Codex +1 ★ 3,267repo stars

From the same set82

The whole set →
browser-automation browser-automation enables agents to navigate URLs, fill web forms, interact with elements, and take screenshots. CX Codex +1 ★ 328repo stars workflow-routing The workflow-routing skill chooses between Superpowers and GSD based on project state and task scope. It runs before other skills or GSD commands when both systems are installed. CX Codex +1 ★ 328repo stars theme-crossfade-morph theme-crossfade-morph is a Claude Code rule for whole-scene theme changes: it re-skins the background, type, radii, icons and logos in about 0.3 s while one anchor element stays fixed. CX Codex +1 ★ 328repo stars clone-website clone-website replicates target web pages into a self-contained single-file HTML prototype without build tools. Handy when you need to inspect or recreate UI layouts quickly. CX Codex +1 ★ 328repo stars particle-burst The particle-burst rule describes confetti pops, dots bursting behind text, and glyphs dissolving into particles. Use it for timeline animation that needs to render correctly at a scrubbed frame. CX Codex +1 ★ 328repo stars cursor-drag Defines GSAP choreography for driven cursor drags: lockstep ghost movement, slot drop-snaps, corner resizing, and spreadsheet auto-fills. CX Codex +1 ★ 328repo stars product-design-super-intelligence The product-design-super-intelligence skill brings product and design perspectives into decisions about what to build, change, or cut. Use it to examine a choice before implementation, rather than only review it afterward. CX Codex +1 ★ 328repo stars control-target-sync control-target-sync — a rule for scenes where one control edits a value and a second element answers in the same frame. Useful for editor and inspector demos. CX Codex +1 ★ 328repo stars

Project sponsors

Companies that keep this analytics open