Skip to main content

Install SpecWeave and plan your first increment

You end with an increment whose spec.md lists numbered acceptance criteria and tasks with their files and test, and specweave pickup tells you which task to claim first.

  • SpecWeave CLI
  • 1:36
  • 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; a git repository to plan work in.

Length 1:36Captions

Steps

  1. Install the CLI with npm i -g specweave. It needs Node.js 20.12 or later; specweave --version prints the installed version.
  2. In your repo, run specweave init. Add --adapter claude (or another tool) to name your coding agent, and --quick to accept the defaults. It writes CLAUDE.md and AGENTS.md, installs six SpecWeave skills in .claude/skills/ and .agents/skills/, and keeps its settings in .specweave/config.json.
  3. Run specweave create-increment "Personal greeting". It creates .specweave/increments/0001-personal-greeting/ with a scaffolded spec.md and metadata.json.
  4. Decide first: at the default level (planning.deepInterview: critical) your agent's sw-increment skill asks only the decisions that are yours, one at a time with a recommended answer, and records them under ## Decisions as Asked, Defaulted and Open.
  5. Fill in spec.md, yourself or with the sw-increment skill: Problem, Scope, numbered acceptance criteria (- [ ] AC-01: …), Approach, Decisions, and tasks written as ### T-01 Title followed by - AC: AC-01 | Files: … | Test: ….
  6. Commit the plan and run specweave pickup. It prints the increment, the next task with its acceptance criterion, files and test, and the command that claims it.
  7. Then claim the task with specweave task claim T-01 and prove it with specweave task done T-01 --run "npm test".

Transcript

Built from the caption file of the narration.

0:00 What you will do

Install SpecWeave and plan your first increment.

0:04 Install the CLI

Install the CLI from npm with npm i -g specweave. It needs Node 20.12 or later. specweave --version prints 3.1.0.

0:18 specweave init

In your repo, run specweave init with the Claude Code adapter. It writes CLAUDE.md and AGENTS.md, installs six SpecWeave skills, and keeps its settings in.specweave/config.json.

0:32 Create the increment

Now plan the work. Give specweave create-increment a title. It makes the folder 0001-personal-greeting, with a spec.md to fill in.

0:44 The Decide step

Step one is Decide. At the default level, critical, your agent asks only the decisions that are yours, one at a time with a recommended answer.

0:54 Problem and acceptance criteria

Then fill in spec.md, yourself or with the sw-increment skill: the problem, and numbered acceptance criteria that a test can check.

1:05 Decisions and tasks

Decisions records what was asked, what was defaulted, and what is open. Each task names its acceptance criterion, its files, and the test that proves it.

1:16 specweave pickup

Commit the plan, then run specweave pickup. It shows the increment, the next task, T-01, with its acceptance criterion, files and test, and the command that claims it.

1:29 Next: claim and prove the task

Next, claim T-01 and prove it with task done --run.

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

    1:00, SpecWeave CLI

  2. Install SpecWeave and plan your first increment (this guide)

    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