/do

description: Execute increment tasks following spec and plan with sync hooks. Use when saying "implement", "start working", "execute tasks", or "continue increment". IMPORTANT - Before starting, check task count and domain count. If 3+ domains or 15+ tasks, recommend sw:team-lead instead (ask user for confirmation, or auto-invoke in auto mode).
version: 1.0.0
argument-hint: "<increment-id>"

Do Increment

Project Overrides

**Skill Memories**: If `.specweave/skill-memories/do.md` exists, read and apply its learnings.

Project Context

**Project Context**: If `.specweave/config.json` exists, read it for testing mode, TDD enforcement, and multi-project settings. Check for active increments in `.specweave/increments/*/metadata.json`.

Execute a SpecWeave increment by running tasks from tasks.md with automatic AC-sync after every task completion.

Usage

sw:do <increment-id>    # Execute specific increment
sw:do                   # Auto-select best candidate
sw:do <id> --model <model-id>  # Override the model (effort stays at xhigh)

• `<increment-id>`: Optional. Supports "001", "0001", "1", "0042", or "0153-feature-name" formats.
• `--model <model-id>`: Optional. Overrides the model. Effort stays at `xhigh`.

All tasks execute at the `xhigh` effort tier (Opus 4.7 default). Use `--model` to override the model if needed, but effort stays at xhigh.

Tool-Use Rationale

• **Read**: Load spec.md, plan.md, tasks.md, and any referenced living docs before executing a task.
• **Edit**: Apply task-scoped code changes and flip `[ ]` → `[x]` in tasks.md after verification passes.
• **Write**: Create new files the task defines (source, tests, migrations).
• **Bash**: Run the task's test command and project-level verification (`npx vitest run`, `pytest`, `go test ./...`).

---

Workflow

Step 1: Smart Increment Auto-Selection

When no ID provided, auto-select (NEVER ask user for ID):

1. Scan by priority: `in-progress` > `planned` > `ready_for_review` (with incomplete tasks) > `backlog` (with incomplete tasks) 2. For each candidate, count incomplete tasks: `grep -c '^\- \[ \]'` + `grep -c '\*\*Status\*\*: \[ \]'` in tasks.md 3. Select best candidate and auto-promote to in-progress if needed 4. If no candidates, show status summary and offer: create new, close ready_for_review, resume backlog, or view status

Step 1.5: Auto-Mode Context Override

When running inside an active auto session (`.specweave/state/auto-mode.json` has `active: true`):

1. **Explicit ID takes priority**: If an explicit increment ID was passed (e.g., `sw:do 0252`), use it directly — skip this step 2. **Stop hook guidance**: If the stop hook feedback in the current conversation mentions a specific increment ID (e.g., "Continue: sw:do 0252"), use that ID 3. **Read incrementIds**: If no ID from above, read `incrementIds` array from `auto-mode.json` and use the **first entry** — this is the increment prioritized by scoring at session start 4. **Skip filesystem scanning**: When auto-mode context provides an increment ID via steps 2 or 3, skip Step 1's filesystem scanning entirely — auto-mode context takes priority

This ensures the execution loop stays focused on the contextually correct increment rather than re-scanning the filesystem each iteration.

Step 2: Load Context

1. **Find increment directory**: Normalize ID to 4-digit format, match `.specweave/increments/NNNN-*/` 2. **Load files**: Read `spec.md`, `plan.md`, `tasks.md`, `tests.md` 3. **Load living docs**: Check ADRs and specs in `.specweave/docs/internal/` for related context 4. **Verify readiness**: Status is planned/in-progress, no blocking deps, tasks exist 5. **Task count validation**: If >25 tasks, warn and offer to split, phase, or use `sw:auto`/`sw:team-lead` 6. **Validate AC presence** (MANDATORY): Check that spec.md contains AC-IDs (e.g., `AC-US1-01`). If missing: add ACs to spec.md before proceeding. Do NOT proceed without ACs in spec.md.

Step 2.5: PR-Based Branch Setup (conditional)

Check push strategy:

PUSH_STRATEGY=$(jq -r '.cicd.pushStrategy // "direct"' .specweave/config.json 2>/dev/null)

**If `pr-based`:** 1. Read git config:

   BRANCH_PREFIX=$(jq -r '.cicd.git.branchPrefix // "sw/"' .specweave/config.json 2>/dev/null)

2. Compute branch name: `BRANCH_NAME="${BRANCH_PREFIX}${INCREMENT_ID}"` 3. Check current branch: `CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)` 4. If not on the feature branch:

• Branch exists? `git branch --list ${BRANCH_NAME}` → `git checkout ${BRANCH_NAME}`
• Branch doesn't exist? `git checkout -b ${BRANCH_NAME}`

5. For umbrella/multi-repo: repeat in each `repositories/*/*/` that has a `.git` directory 6. Log: `"Working on feature branch: ${BRANCH_NAME}"`

**If `direct`:** Skip this step entirely (no-op, current behavior preserved).

Step 2.7: Execution Strategy Check

**Skip this step if already running inside `sw:auto` or `sw:team-lead`.** Check `.specweave/state/auto-mode.json` — if `active: true`, skip.

Assess increment complexity to recommend the best execution mode:

1. **Count pending tasks**: `grep -c '^\- \[ \]\|Status\*\*: \[ \]' tasks.md` 2. **Count domains**: Scan spec.md and plan.md for distinct technology areas (frontend, backend, database, API, DevOps, security, mobile, ML/AI). Each distinct area = 1 domain. 3. **Count ACs**: `grep -c 'AC-US' spec.md`

**Recommendation matrix** (see CLAUDE.md Execution Strategy):

| Tasks | Domains | Action | |-------|---------|--------| | ≤8 | 1 | Proceed with `sw:do` silently | | 9-15 | 1-2 | Suggest `sw:auto` for unattended execution | | >15 | 1-2 | Recommend `sw:auto` (many tasks benefit from autonomous loop) | | any | 3+ | Recommend `sw:team-lead` for parallel multi-agent execution |

**When recommending (non-auto mode)**, use `AskUserQuestion` with these options:

• `sw:do` — Continue manual step-by-step (current mode)
• `sw:auto` — Autonomous sequential execution (unattended, stop-hook lo