Skip to main content

Plan, prove and hand off a task with the CLI

You see the whole loop once: the plan, the claim, the test evidence and the handoff all travel with the repository.

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

Recorded on SpecWeave 3.0.6, added 12 October 2026.

Before you start: Node.js 20.12 or later and git; SpecWeave installed with npm i -g specweave.

Length 1:00Captions

Steps

  1. Create an increment with specweave create-increment "title", then write the problem, the acceptance criteria and a task with its exact files and test command in spec.md.
  2. Claim the task with specweave task claim T-01, so everyone can see who owns it.
  3. Implement the change and run the tests. In the recording, both tests pass.
  4. Commit, then run specweave task done T-01 --run "<test command>". SpecWeave runs the command again and keeps its output as evidence.
  5. Stop with specweave handoff --reason "<why>". The recording keeps everything local instead of pushing.
  6. In another clone, run specweave pickup. It prints the next task with its acceptance criteria.

Transcript

Built from the caption file of the narration.

0:00 A disposable demo repository

Here is a real SpecWeave workflow in a disposable demo repository. No production code is touched.

0:07 Create an increment

First, create an increment. Write down the problem, the acceptance criteria, and a task with its exact files and test command.

0:15 Claim the task

Now claim the task, so ownership is visible.

0:18 Implement and test

Implement the function and run the tests. In this example, we check a list of numbers and an empty list. Both tests pass.

0:25 Commit and mark done

Commit the implementation. Then mark the task done with the test command. SpecWeave runs it again and records the evidence.

0:33 Hand off

To stop, create an explicit handoff. This demo uses no push, so everything stays local. We save that handoff and make a clean local clone.

0:43 Pick up in a clean clone

Run pickup in the clone. The next task is still there: document the empty-list behavior. The plan, ownership, and evidence travel with the repository. Try the same workflow in your own small project at spec weave dot com.

Plan your first increment

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 (this guide)

    1:00, SpecWeave CLI

  2. Install SpecWeave and plan your first increment

    1:36, SpecWeave CLI

  3. Claim, prove, verify and complete a task

    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