anton-abyzov/specweave/do

sw-do: work an increment to done

Tasks are defined in spec.md under ## Tasks; their state lives only in the increment's ledger.jsonl, which the CLI appends to. Never write state into spec.md.

Start

specweave pickup applies any handoff pushed from another tool or account, then prints the open increment, the next task with its acceptance criteria, claims other agents hold, and notes left for you. No increment yet? Run sw-increment first.

The loop

1. specweave task next prints the next claimable task with its AC text.
2. specweave task claim T-03 --line "Writing the ledger fold". Exit 3: someone holds it (your own earlier claim from

a crashed session: say so, then --force); 4: its Files overlap a live claim; 6: its dependencies are not done. Otherwise pick another. Never edit before claiming.

1. Implement inside that task's Files only. Need another file? Claim the task that

owns it, or add a task to spec.md ## Tasks. Use the words in GLOSSARY.md, if the project has one, for every new name.

1. Run the task's Test. Red means fix the code; never skip, weaken or delete a test.

Test-first order is optional: follow it only when the user, testing.mode: TDD or the project's conventions ask. Don't add unit tests the task did not ask for; check the AC end to end, the way a user would hit it.

1. Commit with the increment id first: git commit -m "0042: fold the ledger".
2. specweave task done T-03 --run "npm run test:e2e -- double-claim" --line "Wrote the ledger fold" --link <PR URL>.

Exit 5: the command failed and the task stays open. No Test? --evidence "<sha> + what you checked". --line is the card text (one line, past tense when done, at most 100 characters); --link is the PR, report or artifact behind it.

1. Stuck: specweave task block T-03 --reason "<what is missing>". Not needed:

specweave task skip T-03 --reason "<why>". Then back to 1.

Commands take the increment id last (specweave task next 0042) when more than one increment is active. specweave task list shows the whole board. For a status, print specweave cards --md: one ✓ / ✱ / ○ text (link) line per task. Work with no increment: specweave card add "<text>", then card start|done|wait C-01.

Unattended (auto mode)

"Auto", "run until done", "ship this while I sleep": the same loop without stopping to ask. The bar does not drop.

1. Start only when the spec has nothing under ## Decisions > ### Open and every

task has Files and a Test; otherwise fix the spec first.

1. specweave auto 0042 records the session (--dry-run previews, --reset clears

stale state). A tool that runs SpecWeave's Stop hook hands you the remaining work after every turn; in any other tool, keep looping yourself.

1. Blocked (missing secret, ambiguous spec, outside dependency): task block and move

on. When only blocked tasks remain, specweave cancel-auto and tell the user what each one needs, instead of looping to the turn limit.

1. specweave auto-status shows progress; one auto session per project.

Parallel lanes

Three or more disjoint lanes, or 15+ tasks: you are the lead. Split, start, watch, merge and close; do not implement.

1. Group tasks into 2 to 5 lanes whose Files do not overlap. Shared contracts

(types, schema) go in an early task the others list under **Dependencies**: T-01.

1. Lane agents share the existing checkout and branch, each with a unique SPECWEAVE_AGENT (such as api or web);

stage only your lane's files and commit with an explicit path list, for example git add -- src/api.ts && git commit -m "0042: build API" -- src/api.ts. Use the same unique identity for every task command in the lane. Give a lane its own worktree only when the user or the project's settings ask for worktrees (your tool's or app's worktree feature, or git worktree add .worktrees/0042-api -b inc/0042-api, never ../). Brief each one: its tasks, this loop, "edit only their Files", and on finish specweave task release --all-mine plus specweave note "api: done" 0042.

1. Watch with specweave task list 0042; blocked rows are your queue. A claim older

than 2 hours with no progress may be taken with --force.

1. If lanes had their own worktrees, merge their branches in dependency order (keep every

ledger.jsonl line from both sides) and remove the worktrees. Then close as below. Lane agents never run specweave handoff. specweave team opens agent panes for the same setup in tools that have them.

Finish without asking

When task next has nothing left, run sw-done: verify, review, complete, in the same session. "All tasks are done, should I close?" is the anti-pattern.

Plan for it from the start: a progress checklist or status you keep for the user ends with "Verify and close 0042", not with "merge" or "release". Work that shipped through a PR still gets specweave task done T-03 --evidence "<commit sha>" first, or the ledger never shows it finished. A session never ends with every task done and the increment still open; if a close gate stops you (verify fails, a manual check only the user can do), say which one in your report. A lane agent leaves the close to its lead.

Stopping early

Out of tokens, switching tool or account: specweave handoff --reason "<why>" (sw-handoff).

Manual path (no CLI)

Read the tasks from spec.md and the state from ledger.jsonl: the next task is the lowest T-id nobody holds whose Files no live claim holds. Append one JSON object per line, keys in this order, UTF-8, LF:

L=.specweave/increments/0042-ledger-fold/ledger.jsonl
printf '%s\n' '{"t":"T-01","e":"claim","by":"codex@mbp","at":"2026-09-02T10:00:00Z"}' >> "$L"

$L = '.specweave\increments\0042-ledger-fold\ledger.jsonl'
$line = '{"t":"T-01","e":"done","by":"codex@win","at":"2026-09-02T11:30:00Z","evidence":"npm run test:e2e -- double-claim exit 0 / a1b2c3d"}'
[IO.File]::AppendAllText($L, $line + "`n", [Text.UTF8Encoding]::new($false))

PowerShell never uses >> here: it writes UTF-16 and every other tool fails to read it. Events: claim, done (needs evidence), release, block and skip (both need note); any of them may carry "line" (card text) and "link", for example {"t":"T-02","e":"skip","by":"codex@mbp","at":"2026-09-02T12:00:00Z","note":"covered by T-01"}. by is SPECWEAVE_AGENT if set, else <tool>@<host>. Unattended or in lanes, follow the same steps by hand: there is no hook and no session file.

Rules

• A claim older than 2 hours with no done is stale and may be taken over.
• Append only: never edit, reorder or delete a ledger line. On a merge conflict in

ledger.jsonl keep every line from both sides.

• Never widen a task's Files or weaken a test to keep a loop moving.
• Never edit .specweave/state/auto-mode.json by hand; specweave auto --reset clears it.