メインコンテンツまでスキップ

Your First Increment

This walks through one small change from request to closed increment, and shows how to move it to another tool halfway through.

Length 1:36Captions

Real output of the SpecWeave 3.1.0 CLI in a sample repo inside a disposable home, recorded headlessly. `npm i -g specweave` installed 3.1.0 from the npm registry into that home, and every later command ran the installed copy. No agent session is shown: the commands ran in a terminal with SPECWEAVE_TOOL=claude, which is why pickup reads claude@demo. The filled-in spec.md is a sample written in advance and swapped in for the scaffold off camera; no agent wrote it and no decisions were asked live. `--adapter claude` names the adapter so detection does not look at the recording machine's own tools. Nothing was pushed. Narration is an AI voice (ElevenLabs, the author's cloned voice); captions are timed from the voice service's character timestamps. Open the guide with steps and transcript

Before you start​

  • SpecWeave installed: npm install -g specweave
  • The project initialized: specweave init
  • A coding agent: Claude Code, Codex, Grok Build, Cursor or any tool that reads AGENTS.md

We will use a small example: "Add a greeting that uses the signed-in user's name."

1. Create the increment​

"Add a greeting that uses the signed-in user's name"

You get one file, .specweave/increments/0001-personal-greeting/spec.md:

# Personal greeting

## Problem
Signed-in users see a generic welcome.

## Scope
The header greeting. Not emails.

## Acceptance Criteria
- [ ] AC-01: A signed-in user sees "Hi, <first name>"
- [ ] AC-02: A signed-out visitor sees "Welcome"

## Approach
Read the name from the session in the header component.

## Open questions
- none

## Tasks

### T-01 Render the name from the session
- AC: AC-01 | Files: src/header/Greeting.tsx | Test: npm test -- greeting

### T-02 Fall back for signed-out visitors
- AC: AC-02 | Files: src/header/Greeting.tsx | Test: npm test -- greeting

Read it before any code is written. Adjust the criteria until they say exactly what done means.

2. Work through the tasks​

"Start implementing"

Under the hood the agent runs:

specweave task next                        # T-01 and the text of AC-01
specweave task claim T-01
specweave task done T-01 --run "npm test -- greeting"  # records the real check

Each task arrives with its own criteria, so the agent does not reread the whole spec. When every task covering a criterion is done, that criterion is met.

3. Switch tools halfway (optional)​

Say you run out of usage after T-01. Tell the agent "hand off", or run:

specweave handoff

It pushes your branch and uncommitted edits to git. Then open the project in another tool, or the same tool under another subscription, and run:

specweave pickup

It fetches the handoff, applies your edits, and shows increment 0001, T-02 with AC-02, any notes and the project memory. Continue from there. Nothing to copy or paste. See Cross-tool handoff.

4. Review and close​

"Review increment 0001"
"We're done with increment 0001"

verify runs your project's build, test and lint commands and writes a report. complete closes the increment only when the tasks are done and the checks passed. Closing does not touch GitHub, Jira or Azure DevOps unless you set that up.

Common questions​

Can I change the spec halfway? Yes. Edit spec.md; add criteria and tasks as you learn more.

What if a task turns out to be unnecessary? Skip it with a reason: specweave task skip T-02 --reason "covered by T-01".

Do I need plan.md? Only for a genuinely large design. Most increments never need one.

Next​