Skip to main content

Claim, prove, verify and complete a task

You end with a completed increment that has its test evidence and a passing verify report.

  • SpecWeave CLI
  • 1:30
  • Any agent
  • Narrated, with captions

Recorded on SpecWeave 3.1.0, 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; an increment whose spec.md lists a task with its acceptance criteria, Files and Test.

Length 1:30Captions

Steps

  1. Claim the task with specweave task claim T-01. The claim goes into ledger.jsonl under your agent id (claude@demo in the recording), and the command prints the task's acceptance criteria, files and test. Another agent trying to claim it is refused while your claim is live.
  2. Make the change and its test, and commit as 0001: <what changed>.
  3. Run specweave task done T-01 --run "npm test". The test runs again; the task is marked done only when it exits 0, and the output is kept as evidence. A failing test exits 5 and the task is not marked done (the log is still saved).
  4. Read the evidence file, reports/task-T-01.txt in the increment folder: the command, its exit code and the time, then the full test output.
  5. specweave complete 0001 refuses to close while reports/verify.json is missing, and tells you to run specweave verify first. Use --reason only if you must close without it.
  6. Run specweave verify. It runs the verification commands (testing.commands in .specweave/config.json, otherwise the test, lint and build scripts from package.json) and counts an acceptance criterion as met when the tasks that cover it are done. It writes reports/verify.md and, beside it, reports/verify.json, which specweave complete reads.
  7. Run specweave complete 0001 again. The verify check passes and the increment's status becomes completed.

Transcript

Built from the caption file of the narration.

0:00 What you will do

Claim, prove, verify and complete a task with the SpecWeave CLI.

0:07 specweave task claim

Start with specweave task claim T-01. The claim goes into the ledger as claude@demo, so others see who owns the task. It prints the acceptance criteria, the files and the test.

0:20 task done --run

With the change committed, task done --run runs the test again. Only a zero exit marks the task done, with the output as evidence.

0:31 The evidence file

The full output is saved in reports/task-T-01.txt: the command, its exit code and the time, then the test results.

0:41 complete is blocked

Now try to close the increment with specweave complete. It refuses: reports/verify.json is missing, so it tells you to run specweave verify first.

0:53 specweave verify

specweave verify runs the project's test, lint and build scripts, here only npm run test. Both acceptance criteria are met, because the task that covers them is done.

1:06 The verify report

Its report, verify.md, keeps the test output, the criteria table, and the task with its evidence. verify.json beside it is what complete reads.

1:18 complete passes

Run specweave complete again. The verify check passes, and the increment is completed.

1:24 Next: hand off

Next, hand the work to another agent with specweave handoff.

Read the workflow guide

Learning path

Run work across agents

Plan an increment, prove each task, hand off between tools and get a review from another model.

  1. Plan, prove and hand off a task with the CLI

    1:00, SpecWeave CLI

  2. Install SpecWeave and plan your first increment

    1:36, SpecWeave CLI

  3. Claim, prove, verify and complete a task (this guide)

    1:30, SpecWeave CLI

  4. Hand off from Claude Code to Codex at a usage limit

    1:18, SpecWeave CLI

  5. Review with the other model before you ship

    1:33, SpecWeave CLI

All tutorials