/increment

description: Plan and create SpecWeave increments with PM and Architect agent collaboration. Use when starting new features, hotfixes, bugs, or any development work that needs specification and task breakdown. Creates spec.md, plan.md, tasks.md with proper AC-IDs and living docs integration.
version: 1.0.0
argument-hint: "<feature-description>"
model: opus
effort: xhigh

**Effort**: `xhigh` (Opus 4.7 default for planning). Use `--effort max` for unusually complex architecture, accepting the overthinking risk.

Plan Product Increment

Tool-Use Rationale

• **Read**: Load `.specweave/config.json`, existing increments, and referenced living docs to inform scope and AC-IDs.
• **Write**: Produce the four increment artifacts (`metadata.json`, `spec.md`, `plan.md`, `tasks.md`) inside the increment directory.
• **Edit**: Refine AC-IDs, user-story numbering, and task dependencies after the single-agent draft is complete.

CRITICAL: Plan Mode Required (BLOCKING)

**You MUST be in plan mode before proceeding.** If not, call `EnterPlanMode` now and wait for confirmation before continuing to Step 0A.

1. Call `EnterPlanMode` immediately 2. Wait for plan mode confirmation 3. Then proceed to Step 0A

Increment planning produces specs, plans, and task breakdowns that require user review. Do not skip plan mode or defer it — the user must approve the plan before any implementation begins.

Project Overrides

**Skill Memories**: If `.specweave/skill-memories/increment.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`.

**Self-contained increment planning for ANY user project after `specweave init`.**

Workflow Overview

STEP 0A: Discipline Check (BLOCKING)
STEP 0B: WIP Enforcement
STEP 0C: Tech Stack Detection
STEP 1:  Pre-flight (TDD mode, multi-project, Deep Interview check)
STEP 2:  Project Context (resolve project/board)
STEP 3:  Create Increment (via Template API) ← folder + ID exist after this
STEP 3a: Deep Interview (if enabled) ← runs AFTER folder exists
STEP 4:  Direct Specification Writing (universal, CLI-first)
STEP 4a: Enhanced: Team-Based Delegation (optional, Claude Code only)
STEP 5:  Post-Creation Sync
STEP 6:  Execution Strategy Recommendation

**CRITICAL**: Step 3 (Create Increment) MUST run before Step 3a (Deep Interview). The interview state file is written to `.specweave/state/interview-{increment-id}.json`, and the enforcement guard looks for it by increment ID. If the interview runs before the increment folder exists, the guard cannot find the state file and blocks spec.md writing.

Step 0A: Discipline Check (MANDATORY)

**Cannot start N+1 until N is DONE.**

if ! specweave check-discipline; then
  echo "Cannot create new increment! Close existing work first."
  echo "Run: sw:done <id>"
  exit 1
fi

Step 0B: WIP Enforcement

Default: 1 active increment (focus). Allow 2 for emergencies.

const active = MetadataManager.getAllActive();
const limits = config.limits || { maxActiveIncrements: 1, hardCap: 3 };

if (active.length >= limits.hardCap) {
  // BLOCK - ask user to complete/pause existing
  console.log("WIP LIMIT REACHED");
  console.log("Options: sw:done <id> | sw:pause <id>");
}

if (active.length >= limits.maxActiveIncrements) {
  // SOFT WARNING - hotfix/bug can bypass
  const isEmergency = ['hotfix', 'bug'].includes(incrementType);
  if (!isEmergency) {
    // Prompt: complete, pause, or continue anyway
  }
}

**Type-Based Limits:**

• Hotfix/Bug: Unlimited (emergency)
• Feature/Change-Request: Max 2
• Refactor: Max 1
• Experiment: Unlimited

Step 0C: Tech Stack Detection

Auto-detect from project files:

| File | Language | |------|----------| | package.json | TypeScript/JavaScript | | requirements.txt | Python | | go.mod | Go | | Cargo.toml | Rust | | pom.xml | Java | | *.csproj | C#/.NET |

If detection fails, ask user.

Step 1: Pre-flight Checks

# 1. Check TDD mode
jq -r '.testing.defaultTestMode // "TDD"' .specweave/config.json 2>/dev/null

# 2. Check multi-project config
specweave context projects 2>/dev/null

# 3. Check deep interview mode (note: interview itself runs at Step 3a, after increment exists)
DEEP_INTERVIEW=$(jq -r '.planning.deepInterview.enabled // false' .specweave/config.json 2>/dev/null)

# 4. Check WIP limits
find .specweave/increments -maxdepth 2 -name "metadata.json" -exec grep -l '"status":"active"' {} \; 2>/dev/null | wc -l

Step 2: Project Context

# Get project/board values for spec.md
specweave context projects

Every US MUST have `**Project**:` field. For 2-level structures, also `**Board**:`.

Step 3: Create Increment

3a. Determine Increment Location

**Determine where increments are stored:**

# Check umbrella mode
UMBRELLA_ENABLED=$(jq -r '.umbrella.enabled // false' .specweave/config.json 2>/dev/null)

if [ "$UMBRELLA_ENABLED" = "true" ]; then
  echo "UMBRELLA MODE: Increments go in UMBRELLA ROOT .specweave/increments/"
  echo "The **Project**: field in each user story controls sync routing to child repos."
  # List available child repos for context
  jq -r '.umbrella.childRepos[]? | "\(.name) (\(.path))"' .specweave/config.json 2>/dev/null
elif [ -d "repositories" ]; then
  echo "MULTI-REPO (no umbrella): Increments belong in EACH repo's .specweave/"
  ORG=$(jq -r '.repository.organization // empty' .specweave/config.json 2>/dev/null)
  [ -z "$ORG" ] && ORG=$(ls -d repositories/*/ 2>/dev/null | head -1 | xargs basename 2>/dev/null)
  echo "Organization: $ORG"
  ls -d repositories/*/* 2>/dev/null | head -20
else
  echo "WORKSPACE: Use .specweave/increments/"
fi

**Umbrella mode (`umbrella.enabled: true`):**

• ALL increments go in the umbrella root `.specweave/increments/` — NOT in child repos
• The `**Project**:` fie