---

name: increment-planner description: Creates comprehensive implementation plans for ANY type of SpecWeave increment (feature, hotfix, bug, change-request, refactor, experiment). Supports all work types from features to bug investigations to POCs. Activates for: increment planning, feature planning, hotfix, bug investigation, root cause analysis, SRE investigation, change request, refactor, POC, prototype, spike work, experiment, implementation plan, create increment, organize work, break down work, new product, build project, MVP, SaaS, app development, tech stack planning, production issue, critical bug, stakeholder request.

Increment Planner Skill

Self-contained increment planning that works in ANY user project after specweave init.

---

Purpose

Automates creation of increment structure for ANY type of work:

• ✅ Auto-numbered directories (0001-9999)
• ✅ Duplicate detection (prevents conflicts)
• ✅ Complete file templates (spec.md, plan.md, tasks.md, metadata.json)
• ✅ Proper YAML frontmatter
• ✅ Works in all user projects (self-contained)

---

Increment Types

Type	Description	Use When	WIP Limit
feature	New functionality	Adding features	Max 2 active
hotfix	Critical production fixes	Production broken	Unlimited
bug	Bug investigation with RCA	Needs root cause analysis	Unlimited
change-request	Stakeholder requests	Business changes	Max 2 active
refactor	Code improvement	Technical debt	Max 1 active
experiment	POC/spike work	Exploring options	Unlimited

---

When to Use

✅ USE when:

• Creating features, hotfixes, bug investigations, refactors, POCs
• Planning structured work in user projects
• Need complete increment scaffold with templates

❌ DON'T USE when:

• User asking general questions
• Another skill already handling request
• Already in active increment planning

---

Critical Rules

0. Project: Field is MANDATORY (v0.35.0+ - HIGHEST PRIORITY!)

⛔ EVERY User Story MUST have **Project**: field - NO EXCEPTIONS!

This applies to BOTH single-project AND multi-project modes:

• Single-project: Use config.project.name value (e.g., **Project**: my-app)
• Multi-project: Use one of multiProject.projects keys (e.g., **Project**: frontend-app)

HOW TO GET THE PROJECT VALUE:

1. Run specweave context projects
2. Use project ID from output

Single-project output:

{ "level": 1, "projects": [{"id": "my-app"}] }
→ Use: **Project**: my-app

Multi-project output:

{ "level": 1, "projects": [{"id": "frontend"}, {"id": "backend"}] }
→ Pick appropriate project per US

2-level output (ADO/JIRA):

{ "level": 2, "projects": [...], "boardsByProject": {"corp": [{"id": "digital-ops"}]} }
→ ALSO add: **Board**: digital-ops

EXAMPLE (v0.35.0+):

### US-001: Show Last 2 Git Commits
**Project**: aac              # ← MANDATORY! Value from config
**As a** developer, I want to see the last 2 git commits...

⛔ NEVER GENERATE:

### US-001: Feature Name
**As a** user, I want...      # ← MISSING **Project**: = INVALID!

EDGE CASES:

• Empty config.project.name: Run specweave init to configure
• Empty multiProject.projects: Invalid config - ask user to configure projects
• Project name with special chars: Only a-z, 0-9, - allowed

1. Increment Naming (MANDATORY)

Format: ####-descriptive-kebab-case-name

✅ CORRECT:

0001-user-authentication
0002-payment-processing
0003-email-notifications

❌ WRONG:

0001              ← No description
0002-feature      ← Too generic
my-feature        ← No number

2. NO Agent Spawning from Skills (CRITICAL)

Skills MUST NOT spawn content-generating agents via Task() tool.

Why: Context explosion causes Claude Code crashes:

• Skill (1500 lines) loads into context
• Agent (600 lines) spawned
• Agent output (2000+ lines) generated
• Total: 4000+ lines = CRASH 💥

✅ SAFE Workflow:

1. Skill creates basic templates (50 lines each)
2. Skill outputs: "Tell Claude: 'Complete spec for increment 0005'"
3. Agent activates in MAIN context (NOT nested) = SAFE

3. metadata.json is MANDATORY

Every increment MUST have metadata.json or:

• ❌ Status tracking broken
• ❌ WIP limits don't work
• ❌ External sync fails (GitHub/Jira/ADO)
• ❌ All increment commands fail

Complete template (values from .specweave/config.json):

{
  "id": "0001-feature-name",
  "status": "planned",
  "type": "feature",
  "priority": "P1",
  "created": "2025-11-24T12:00:00Z",
  "lastActivity": "2025-11-24T12:00:00Z",
  "testMode": "<FROM config.testing.defaultTestMode OR 'TDD'>",
  "coverageTarget": <FROM config.testing.defaultCoverageTarget OR 95>,
  "feature_id": null,
  "epic_id": null,
  "externalLinks": {}
}

NOTE: Always read testMode and coverageTarget from config, don't hardcode!

4. Increment Structure

Directory structure:

.specweave/increments/0001-feature-name/
├── spec.md          # WHAT & WHY (user stories, acceptance criteria) - REQUIRED
├── plan.md          # HOW (technical design, architecture) - OPTIONAL
├── tasks.md         # STEPS (implementation tasks with embedded tests) - REQUIRED
└── metadata.json    # Metadata - REQUIRED

plan.md is OPTIONAL - create only for complex features with architecture decisions. Skip for bug fixes, migrations, hotfixes.

NO separate tests.md - tests embedded in tasks.md (v0.7.0+)

---

Workflow (Safe, Self-Contained)

STEP 0: Detect Multi-Project Mode (MANDATORY FIRST!)

⚠️ CRITICAL: Before creating ANY user stories, detect if this is a multi-project (umbrella) setup!

Automated Detection: src/utils/multi-project-detector.ts provides detectMultiProjectMode(projectRoot) which checks ALL config formats and returns { isMultiProject, projects, detectionReason }.

Manual check (for agents): Read .specweave/config.json and check:

• umbrella.enabled: true with childRepos[]
• multiProject.enabled: true with projects{}
• sync.profiles[].config.boardMapping exists
• Multiple folders in .specweave/docs/internal/specs/

If multi-project detected (umbrella.enabled: true OR multiple project folders exist):

• ✅ MUST generate project-scoped user stories: US-FE-001, US-BE-001, US-SHARED-001
• ✅ MUST use project-scoped AC-IDs: AC-FE-US1-01, AC-BE-US1-01
• ✅ MUST group user stories by project in spec.md
• ✅ MUST infer project from repo name if available (e.g., sw-app-fe → FE, sw-app-be → BE)

Project Prefix Detection from Repo Names:

sw-thumbnail-ab-fe     → prefix: FE (frontend)
sw-thumbnail-ab-be     → prefix: BE (backend)
sw-thumbnail-ab-shared → prefix: SHARED (shared library)
my-app-mobile          → prefix: MOBILE (mobile app)
infra-terraform        → prefix: INFRA (infrastructure)

Store this for use in STEP 4 (spec.md generation)!

---

STEP 0A: Read Config Values (MANDATORY)

# Read testMode (default: "TDD")
testMode=$(cat .specweave/config.json | jq -r '.testing.defaultTestMode // "TDD"')

# Read coverageTarget (default: 95)
coverageTarget=$(cat .specweave/config.json | jq -r '.testing.defaultCoverageTarget // 95')

echo "Using testMode: $testMode"
echo "Using coverageTarget: $coverageTarget"

Store these values for use in STEP 4 and STEP 7!

STEP 0B: Get Project Context (MANDATORY - BLOCKING!)

⛔ THIS IS A HARD BLOCK - YOU CANNOT PROCEED WITHOUT PROJECT CONTEXT!

🚨 FAILURE TO COMPLETE THIS STEP = spec.md WILL BE BLOCKED BY VALIDATION HOOK!

🧠 ULTRATHINK REQUIRED - ANALYZE ALL AVAILABLE CONTEXT FIRST!

Before generating ANY spec.md content, you MUST:

0. ULTRATHINK - Gather context BEFORE running API:

# 1. Check existing project folders in living docs
ls .specweave/docs/internal/specs/

# 2. Check how recent increments assigned projects
grep -r "^\*\*Project\*\*:" .specweave/increments/*/spec.md | tail -10

# 3. Read config.json for project.name or multiProject.projects
cat .specweave/config.json | jq '.project.name, .multiProject'

1. RUN THE CONTEXT API (via Bash tool):

specweave context projects

2. CAPTURE AND STORE THE OUTPUT:

For 1-level structures:

{
  "level": 1,
  "projects": [{"id": "my-app", "name": "My App"}],
  "detectionReason": "multiProject configuration"
}

For 2-level structures (ADO/JIRA boards):

{
  "level": 2,
  "projects": [{"id": "acme-corp", "name": "ACME Corporation"}],
  "boardsByProject": {
    "acme-corp": [
      {"id": "digital-ops", "name": "Digital Operations"},
      {"id": "mobile-team", "name": "Mobile Team"}
    ]
  }
}

3. 🧠 ULTRATHINK - SMART PROJECT RESOLUTION (v0.35.0+ CRITICAL!):

RESOLUTION PRIORITY (MUST FOLLOW THIS ORDER!):

1. ✅ EXACT MATCH: config.project.name or multiProject.projects key → USE IT
2. ✅ LIVING DOCS: Existing folder in specs/ → USE THAT PROJECT ID
3. ✅ RECENT PATTERNS: Same feature type in past increments → USE SAME PROJECT
4. ⚠️  UNCERTAIN: Multiple valid options OR no clear match → ASK USER!
5. 🔄 FALLBACK: If all else fails → USE "default" (NEVER "specweave"!)

⚠️ CRITICAL: IF UNCERTAIN - YOU MUST ASK THE USER!

I found multiple potential projects for this feature:
- frontend-app (keywords: UI, form, React)
- backend-api (keywords: API, endpoint)

Which project should I assign to this feature?

❌ NEVER DO THIS:

• Silently assign to "specweave" (that's the framework name, not user's project!)
• Guess without analyzing context
• Skip asking when genuinely uncertain

✅ CORRECT FALLBACK (when no projects configured):

**Project**: default

4. RESOLVE PROJECT/BOARD FOR EACH USER STORY:

CONTEXT_OUTPUT = <output from specweave context projects>

For each US you will generate:
  IF CONTEXT_OUTPUT.level == 1:
    US.project = select from CONTEXT_OUTPUT.projects[].id

  IF CONTEXT_OUTPUT.level == 2:
    US.project = select from CONTEXT_OUTPUT.projects[].id
    US.board = select from CONTEXT_OUTPUT.boardsByProject[project][].id

5. NOW PROCEED TO STEP 1 (with resolved values stored)

---

VALIDATION RULES (ENFORCED BY HOOK):

✅ REQUIRED: Actually RUN "specweave context projects" command
✅ REQUIRED: Parse the JSON and extract project IDs
✅ REQUIRED: project field MUST match one of projects[].id from output
✅ REQUIRED: board field (2-level) MUST match one of boardsByProject[project][].id
✅ REQUIRED: Each US has **Project**: and **Board**: (2-level) with RESOLVED values
✅ REQUIRED: ASK USER when uncertain (multiple valid options or no clear match)

❌ FORBIDDEN: Skipping this step and generating spec.md directly
❌ FORBIDDEN: Inventing project names not in the API output
❌ FORBIDDEN: Using "specweave" as project name (it's the framework, not user's project!)
❌ FORBIDDEN: Using folder names as project (e.g., "my-project-folder")
❌ FORBIDDEN: Using {{PROJECT_ID}} or {{BOARD_ID}} placeholders
❌ FORBIDDEN: Creating spec.md for 2-level without board: field
❌ FORBIDDEN: Generating spec.md without running context API first
❌ FORBIDDEN: Silently guessing project without analyzing context

WHY THIS IS BLOCKING:

• Hook spec-project-validator.sh BLOCKS spec.md with placeholders or invalid projects
• Without resolved project/board, living docs sync FAILS
• Without resolved project/board, external tool sync (GitHub/JIRA/ADO) FAILS
• User gets blocked error and must manually fix - BAD UX!

Structure Levels:

• 1-Level: internal/specs/{project}/FS-XXX/ - requires project per US
• 2-Level: internal/specs/{project}/{board}/FS-XXX/ - requires project AND board per US

Alternative: Interactive Selection:

specweave context select
# Returns auto-selected or prompts for selection

Get boards for a specific project (2-level):

specweave context boards --project=acme-corp

Project/Board Selection - ULTRA-SMART LOGIC (MANDATORY BEFORE STEP 4!):

⚠️ CORE PRINCIPLE: Each User Story belongs to exactly ONE project (1-level) or ONE project+board (2-level). An increment can contain USs spanning MULTIPLE projects/boards.

---

RULE 0: LEVERAGE ALL AVAILABLE CONTEXT (v0.33.0+ CRITICAL!)

🧠 YOU ARE AN LLM WITH FULL CONTEXT ACCESS - USE IT!

Before asking the user ANYTHING about project/board, you MUST analyze:

1. Living Docs Structure (.specweave/docs/internal/specs/):

# List existing project folders
ls -la .specweave/docs/internal/specs/
# Example output: frontend-app/, backend-api/, mobile-app/, shared-lib/

→ These ARE the actual project IDs! Use them directly.

2. Existing Increment Patterns (.specweave/increments/):

# Read recent increments to see project assignments
grep -r "^\*\*Project\*\*:" .specweave/increments/*/spec.md | tail -20

→ Learn from how past USs were assigned to projects.

3. Config projectMappings (.specweave/config.json):

cat .specweave/config.json | jq '.projectMappings'

→ Use ACTUAL project IDs from config, not generic keywords.

4. Git Remotes (for repo-based projects):

git remote -v | head -2

→ If repo is myorg/frontend-app, that's likely the project.

5. Feature Description + US Content:

• Analyze the feature user is describing
• Match against project patterns from above sources
• Map generic terms to actual project IDs

MAPPING EXAMPLE:

User says: "Add login form to the frontend"
You detect: "frontend" keyword

WRONG: Assign project = "frontend" (generic, may not exist!)
RIGHT: Check living docs → find "frontend-app" folder → Assign project = "frontend-app"

RESOLUTION PRIORITY:

1. Exact match in projectMappings keys → USE IT
2. Exact match in living docs folders → USE IT
3. Pattern match in recent increment specs → USE SAME PROJECT
4. Keyword → Map to closest projectMappings/folder
5. ONLY IF ALL ABOVE FAIL → Ask user with dropdown of valid options

FORBIDDEN:

• ❌ Inventing project names not in config/folders
• ❌ Using generic keywords ("frontend") when actual ID exists ("frontend-app")
• ❌ Asking user when context provides clear answer
• ❌ Assigning {{PROJECT_ID}} placeholder

---

SMART SELECTION DECISION TREE

RULE 1: NO QUESTION IF ONLY 1 OPTION

IF 1-level AND only 1 project → AUTO-SELECT silently
IF 2-level AND only 1 project AND only 1 board → AUTO-SELECT silently

RULE 2: KEYWORD-BASED AUTO-DETECTION (v0.33.0+)

Use CrossCuttingDetector utility for programmatic detection:

import { detectCrossCutting } from 'src/utils/cross-cutting-detector.js';

const result = detectCrossCutting("OAuth with React frontend and Node backend");
// result.isCrossCutting = true
// result.suggestedProjects = ["frontend", "backend"]
// result.confidence = "high"

Or analyze feature description and US content for keywords:

Project-Level Keywords (1-level and 2-level):

Frontend (FE) keywords:
  UI, form, button, page, component, React, Vue, Angular, Next.js,
  CSS, style, responsive, chart, dashboard, view, modal, widget,
  Tailwind, Material-UI, Recharts

Backend (BE) keywords:
  API, endpoint, REST, GraphQL, database, query, migration, service,
  controller, authentication, JWT, session, middleware, CRUD,
  Redis, PostgreSQL, MongoDB, microservice

Mobile keywords:
  mobile, iOS, Android, React Native, Flutter, Expo, app, native,
  push notification, offline, AsyncStorage, screen, touch, gesture

Infrastructure (INFRA) keywords:
  deploy, CI/CD, Docker, Kubernetes, terraform, monitoring,
  logging, pipeline, AWS, Azure, GCP, nginx, Helm, ArgoCD

Shared (SHARED) keywords:
  types, interfaces, utilities, validators, shared, common, library,
  SDK, models, constants, helpers

Board-Level Keywords (2-level structures only):

When project has multiple boards, also match board-specific keywords:

analytics/reporting: analytics, metrics, KPI, dashboard, report, chart, graph
user-management: user, auth, login, registration, profile, permissions, roles
integrations: integration, webhook, API, third-party, sync, import, export
payments: payment, billing, subscription, invoice, stripe, checkout
notifications: notification, alert, email, SMS, push, messaging
devops/platform: deploy, infrastructure, monitoring, CI/CD, pipeline

RULE 3: CONFIDENCE CALCULATION FORMULA

confidence = (matched_keywords / total_feature_keywords) × 100

Example: "Add React login form with JWT authentication"
  Keywords found: React (FE), login (FE), form (FE), JWT (BE), authentication (BE)
  FE matches: 3, BE matches: 2
  FE confidence: 3/5 = 60%
  BE confidence: 2/5 = 40%
  → Primary: FE (60%), Secondary: BE (40%)
  → SUGGEST: "Frontend (60%), but also touches Backend (40%)"

If multiple projects have similar confidence (within 15%):
  → Treat as MULTI-PROJECT feature
  → Auto-split USs by detected keywords

RULE 4: CONFIDENCE-BASED DECISION

>80% single project → AUTO-SELECT with notification (no question)
50-80% single project → SUGGEST with quick confirm option
Multiple projects within 15% → AUTO-SPLIT across projects
<50% OR ambiguous → ASK user with all options

RULE 5: FALLBACK TO DEFAULTS

IF US has explicit **Project**: field → USE IT
ELSE IF frontmatter has default_project → USE default_project
ELSE → ASK user (should not happen if flow followed correctly)

Same logic applies to **Board**: and default_board for 2-level

---

DECISION FLOWCHART

START
  │
  ▼
┌─────────────────────────────────────┐
│ 1. Detect structure level (1 or 2) │
│ 2. Count available projects/boards │
└─────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────┐
│ ONLY 1 PROJECT?                     │
│ (1-level: 1 project)                │
│ (2-level: 1 project + 1 board)      │
└─────────────────────────────────────┘
  │
  ├── YES ──► AUTO-SELECT SILENTLY
  │           Output: "✅ Project: {name} (auto-selected)"
  │           NO QUESTION ASKED
  │
  ▼ NO
┌─────────────────────────────────────┐
│ ANALYZE KEYWORDS in feature desc   │
│ Calculate confidence per project   │
└─────────────────────────────────────┘
  │
  ├── HIGH CONFIDENCE (>80% single) ──► AUTO-SELECT + NOTIFY
  │   Output: "✅ Detected: {project} (keywords: form, React)"
  │
  ├── MULTI-PROJECT (within 15%) ──► AUTO-SPLIT USs
  │   Output: "🔀 Multi-project detected:
  │            • US-001 (Login UI) → web-app (60%)
  │            • US-002 (Auth API) → api-service (55%)
  │            Proceed? (Y/n)"
  │
  ├── MEDIUM CONFIDENCE (50-80%) ──► SUGGEST + CONFIRM
  │   Output: "📍 Suggested: {project}. Confirm? (Y/n)"
  │
  ▼ LOW CONFIDENCE (<50%)
┌─────────────────────────────────────┐
│ ASK USER with ALL options listed   │
│ multiSelect: true                  │
│ Show complete list (never truncate)│
└─────────────────────────────────────┘

---

PER-USER-STORY ASSIGNMENT MODEL

CRITICAL: Assignment is at USER STORY level, not increment level!

Each US in spec.md has its own project (and board for 2-level):

## User Stories

### US-001: Login Form UI
**Project**: web-app
**Board**: frontend  <!-- 2-level only -->
**As a** user...

### US-002: Auth API Endpoints
**Project**: api-service
**Board**: backend  <!-- 2-level only -->
**As a** developer...

### US-003: Mobile Login Screen
**Project**: mobile-app
**Board**: mobile-team  <!-- 2-level only -->
**As a** mobile user...

User can manually change project/board per US at any time by editing spec.md!

---

EXAMPLE SCENARIOS

Scenario 1: Single Project (NO QUESTION)

Config: 1 project (my-app)
Feature: "Add user authentication"

→ AUTO-SELECT: my-app
→ Output: "✅ Project: my-app (single project - auto-selected)"
→ NO question asked

Scenario 2: Multiple Projects, Clear Keywords (AUTO-DETECT)

Config: 3 projects (web-app, api-service, mobile-app)
Feature: "Add React dashboard with charts"

→ Keyword analysis: "React" (FE), "dashboard" (FE), "charts" (FE)
→ Confidence: 95% → web-app
→ Output: "✅ Detected project: web-app (keywords: React, dashboard, charts)"
→ NO question asked (high confidence)

Scenario 3: Multiple Projects, Multi-Area Feature (SMART SPLIT)

Config: 3 projects (web-app, api-service, shared-lib)
Feature: "User authentication with JWT"

→ Analyze: This spans FE (login form) + BE (auth API) + possibly shared (types)
→ Output:
  "🔍 This feature likely spans multiple projects:

   Based on 'user authentication with JWT', I'll create:
   • US-001: Login/Register UI → web-app (keywords: UI, form)
   • US-002: Auth API endpoints → api-service (keywords: API, JWT)
   • US-003: Auth types/validators → shared-lib (keywords: types, shared)

   ✅ Proceed with this assignment? (Y/n)
   💡 You can modify project per US in spec.md anytime"

Scenario 4: 2-Level, Single Project, Auto-Detect Board

Config: 1 project (enterprise-corp), 5 boards (analytics, frontend, backend, mobile, devops)
Feature: "Add reporting dashboard"

→ Project: AUTO-SELECT enterprise-corp (only option)
→ Board keywords: "reporting" → analytics, "dashboard" → frontend
→ Confidence: 70% analytics, 60% frontend
→ Output:
  "✅ Project: enterprise-corp (auto-selected)
   📍 Suggested board: analytics (keyword: reporting)

   Confirm or select different board:
   1. analytics (suggested)
   2. frontend
   3. backend
   4. mobile
   5. devops"

Scenario 5: Completely Ambiguous (ASK WITH ALL OPTIONS)

Config: 4 projects (proj-a, proj-b, proj-c, proj-d)
Feature: "Improve system performance"

→ Keyword analysis: No clear project match
→ Output:
  "❓ Which project(s) should this increment target?

   Available projects:
   • proj-a - E-commerce frontend
   • proj-b - Order processing API
   • proj-c - Mobile shopping app
   • proj-d - Infrastructure/DevOps

   Select one or more (comma-separated, e.g., '1,2' or 'proj-a,proj-b'):"

---

VALIDATION RULES

❌ FORBIDDEN: Asking project question when only 1 project exists
❌ FORBIDDEN: Asking board question when only 1 board exists in project
❌ FORBIDDEN: Hiding options behind "Let me see all" - ALWAYS show complete list
❌ FORBIDDEN: Truncating project/board lists
❌ FORBIDDEN: Assigning ALL USs to same project when content clearly differs
✅ REQUIRED: Auto-select when only 1 option available
✅ REQUIRED: Use keyword matching before asking user
✅ REQUIRED: Each US has explicit project (and board for 2-level) assignment
✅ REQUIRED: Allow user to modify assignments per-US in spec.md
✅ REQUIRED: When asking, show ALL options with descriptions

---

SPEC.MD YAML FORMAT

1-Level Structure:

---
increment: 0045-user-auth
title: "User Authentication"
# Optional default (used if US doesn't specify)
default_project: web-app
---

2-Level Structure:

---
increment: 0045-user-auth
title: "User Authentication"
# Optional defaults (used if US doesn't specify)
default_project: enterprise-corp
default_board: backend
---

Store detected/selected values for use in STEP 4!

---

STEP 1: Get Next Increment Number

Use helper script:

node plugins/specweave/skills/increment-planner/scripts/feature-utils.js next
# Returns: "0021"

Or manually scan:

ls -1 .specweave/increments/ | grep -E '^[0-9]{4}-' | sort | tail -1
# Get highest number, add 1

STEP 2: Check for Duplicates

node plugins/specweave/skills/increment-planner/scripts/feature-utils.js check-increment 0021
# If exists: STOP and inform user

STEP 3: Create Directory Structure

mkdir -p .specweave/increments/0021-feature-name

⚠️ CRITICAL: Increment Folder Structure Rules

ONLY these files allowed at increment ROOT:

• metadata.json - Increment state (auto-managed)
• spec.md - Specification
• plan.md - Implementation plan
• tasks.md - Task list

ALL other files MUST go in subfolders:

.specweave/increments/####-name/
├── reports/     # Validation reports, QA, completion summaries
├── logs/        # Debug logs, session traces
├── scripts/     # Helper scripts
├── docs/        # Additional documentation, domain knowledge
└── backups/     # Backup files

STEP 4: Create metadata.json FIRST (MANDATORY - CRITICAL ORDER!)

🚨 CRITICAL: metadata.json MUST be created BEFORE spec.md!

The metadata-json-guard.sh hook BLOCKS spec.md creation if metadata.json doesn't exist. This prevents broken increments that lack proper tracking.

IMPORTANT: Read testMode and coverageTarget from .specweave/config.json:

# Read config to get defaultTestMode and defaultCoverageTarget
cat .specweave/config.json | jq -r '.testing.defaultTestMode // "TDD"'
cat .specweave/config.json | jq -r '.testing.defaultCoverageTarget // 95'

Create .specweave/increments/0021-feature-name/metadata.json:

{
  "id": "0021-feature-name",
  "status": "planned",
  "type": "feature",
  "priority": "P1",
  "created": "2025-11-24T12:00:00Z",
  "lastActivity": "2025-11-24T12:00:00Z",
  "testMode": "<VALUE FROM config.testing.defaultTestMode OR 'TDD'>",
  "coverageTarget": <VALUE FROM config.testing.defaultCoverageTarget OR 95>,
  "feature_id": null,
  "epic_id": null,
  "externalLinks": {}
}

Use Write tool to create this file IMMEDIATELY after creating directory.

Example Logic:

// Read config
const config = JSON.parse(fs.readFileSync('.specweave/config.json', 'utf8'));
const testMode = config?.testing?.defaultTestMode || 'TDD';
const coverageTarget = config?.testing?.defaultCoverageTarget || 95;

// Create metadata with config values
const metadata = {
  id: "0021-feature-name",
  status: "planned",
  type: "feature",
  priority: "P1",
  created: new Date().toISOString(),
  lastActivity: new Date().toISOString(),
  testMode: testMode,  // ← FROM CONFIG!
  coverageTarget: coverageTarget,  // ← FROM CONFIG!
  feature_id: null,
  epic_id: null,
  externalLinks: {}
};

STEP 5: Create spec.md Template

⚠️ This step REQUIRES metadata.json to exist (created in STEP 4)!

Create .specweave/increments/0021-feature-name/spec.md:

⚠️ CRITICAL: You MUST have PROJECT_ID (and BOARD_ID for 2-level) from STEP 0B before proceeding!

⚠️ IMPORTANT: Use the correct template based on STEP 0 detection!

5A: 1-Level Structure (GitHub, Single Project, Multi-Repo without ADO/JIRA)

USE THIS WHEN: specweave context projects returns level: 1

Examples of 1-level:

• GitHub sync profiles (each repo = project)
• Single project mode
• Umbrella repos WITHOUT multiple teams

Template Rules for 1-level:

• Each User Story has **Project**: field
• NO **Board**: field - GitHub doesn't have boards!
• User story IDs: US-001, US-002 (or US-API-001, US-WEB-001 for multi-repo)
• AC-IDs: AC-US1-01 (or AC-API-US1-01 for multi-repo)

Example 1-level spec.md:

### US-API-001: Create Auth API
**Project**: sw-content-repurposer-api

**As a** frontend, I want auth endpoints...

**Acceptance Criteria**:
- [ ] **AC-API-US1-01**: POST /auth/login returns JWT

⚠️ CRITICAL: Do NOT add **Board**: for 1-level structures!

5B: 2-Level Structure (ADO Area Paths, JIRA Boards, Multi-Team Umbrella)

USE THIS WHEN: specweave context projects returns level: 2

Examples of 2-level:

• ADO with areaPathMapping
• JIRA with multiple boardMapping.boards
• Umbrella repos with multiple teams

Template Rules for 2-level:

• Each User Story has BOTH **Project**: AND **Board**: fields
• User story IDs: US-FE-001, US-BE-001 (with project prefix)
• AC-IDs: AC-FE-US1-01, AC-BE-US1-01 (with project prefix)

Example 2-level spec.md:

### US-FE-001: Create Login Form
**Project**: acme-corp
**Board**: frontend-team

**As a** user, I want a login form...

**Acceptance Criteria**:
- [ ] **AC-FE-US1-01**: Login form displays email/password fields

Key Rules for spec.md (ADR-0140: v0.35.0+):

1. project: field REMOVED from YAML frontmatter - now resolved from per-US fields
2. board: field REMOVED from YAML frontmatter (2-level) - now in per-US fields
3. Each User Story MUST have **Project**: field - source of truth for project
4. Each User Story (2-level ONLY) MUST have **Board**: field - source of truth for board

⚠️ VALIDATION RULES:

✅ 1-level: **Project**: required, NO **Board**:
✅ 2-level: **Project**: AND **Board**: both required
❌ FORBIDDEN: **Board**: on 1-level structure → hook will BLOCK
❌ FORBIDDEN: Missing **Board**: on 2-level → sync will fail
❌ FORBIDDEN: Unresolved placeholders like {{PROJECT_ID}}

STEP 6: Create plan.md Template (OPTIONAL)

Create .specweave/increments/0021-feature-name/plan.md:

Template File: templates/plan.md

Replace {{FEATURE_TITLE}} placeholder. plan.md is OPTIONAL - create only for complex features with architecture decisions.

STEP 7: Create tasks.md Template

Create .specweave/increments/0021-feature-name/tasks.md:

⚠️ IMPORTANT: Use the correct template based on STEP 0 detection!

7A: Single-Project Template

Template File: templates/tasks-single-project.md

Replace {{FEATURE_TITLE}} placeholder.

7B: Multi-Project Template (umbrella.enabled: true) - USE THIS!

Template File: templates/tasks-multi-project.md

Replace placeholders: {{FEATURE_TITLE}}, {{PROJECT_FE_ID}}, {{PROJECT_BE_ID}}, {{PROJECT_SHARED_ID}}

Key Rules for Multi-Project tasks.md:

1. Tasks MUST reference project-scoped user stories: US-FE-001, US-BE-001
2. Tasks MUST reference project-scoped ACs: AC-FE-US1-01, AC-BE-US1-01
3. Group tasks by project/phase (Shared first, then BE, then FE)
4. Test file paths MUST include project folder: sw-app-be/tests/, sw-app-fe/tests/
5. Dependencies between projects should be explicit

STEP 8: Guide User to Complete Planning

Output this guidance to user:

✅ Increment structure created: .specweave/increments/0021-feature-name/

📋 Basic templates created:
   • spec.md (user stories, acceptance criteria)
   • plan.md (technical design, architecture)
   • tasks.md (implementation steps with test plans)
   • metadata.json (increment metadata)

🚀 To complete planning, run these commands in sequence:

1. Complete product specification:
   Tell Claude: "Complete the spec for increment 0021-feature-name"
   (PM expertise will activate automatically in main conversation)

2. Create technical architecture:
   Tell Claude: "Design architecture for increment 0021-feature-name"
   (Architect will create detailed design in main conversation)

3. Generate implementation tasks:
   Tell Claude: "Create tasks for increment 0021-feature-name"
   (Test-aware planner will generate tasks with embedded tests)

⚠️  These commands run in MAIN conversation (NOT nested agents) to prevent crashes!

DO NOT invoke Task() tool to spawn agents from this skill!

STEP 9: Trigger Living Docs & External Tool Sync (v0.32.2+)

🔄 CRITICAL: After increment files are created, trigger sync to living docs AND external tools!

This step uses the existing sync infrastructure to:

1. Create living docs (FS-XXX folder with FEATURE.md and us-*.md files)
2. Check permissions (canUpsertInternalItems) from .specweave/config.json
3. Sync to external tools (GitHub/JIRA/ADO) if configured and permitted

Run the sync-specs command:

/sw:sync-specs {increment-id}

Expected output:

🔄 Syncing increment to living docs...
✅ Living docs synced: FS-021
   Created: 4 files (FEATURE.md, us-001.md, us-002.md, us-003.md)

📡 Syncing to external tools: github
   📋 Permissions: upsert=true, update=true, status=true
   ✅ Synced to GitHub: 0 updated, 3 created

Permission handling (v0.32.2+):

If canUpsertInternalItems: false in config:

⚠️ Skipping external sync - canUpsertInternalItems is disabled
💡 Enable in .specweave/config.json: sync.settings.canUpsertInternalItems: true

Error handling:

External tool sync failures are NON-BLOCKING:

⚠️ External sync failed: Rate limit exceeded
💡 Run /sw:sync-specs {increment-id} to retry

Output after sync:

✅ Increment created and synced!

Next steps:
1. Review the increment plan and docs
2. Start implementation: /sw:do {increment-id}
3. Monitor status: /sw:status {increment-id}

---

Model Selection for Tasks

When creating tasks, assign optimal models:

⚡ Haiku (fast, cheap):

• Clear instructions with specific file paths
• Detailed acceptance criteria (3+ points)
• Simple CRUD, configuration, setup
• Mechanical work with defined approach

💎 Opus (best quality, default):

• Architecture decisions
• Multiple valid approaches
• Integration between components
• Complex business logic
• Error handling strategies
• Critical system architecture
• Security-critical decisions
• Performance-critical algorithms
• Novel problem-solving

🧠 Sonnet (legacy, rarely needed):

• Use only for backwards compatibility
• Prefer Opus or Haiku instead

---

Validation Checklist

Before marking increment planning complete, verify:

Increment Structure:

• Directory exists: .specweave/increments/####-name/
• spec.md has valid YAML frontmatter
• plan.md has technical design
• tasks.md has embedded test plans (NO separate tests.md)
• metadata.json exists and is valid

spec.md Content:

• User stories with AC-IDs (AC-US1-01, etc.)
• Functional requirements
• Success criteria (measurable)
• Out of scope defined
• Dependencies identified

plan.md Content:

• Components identified
• Data model defined
• API contracts specified
• Technology choices explained
• Architecture decisions documented

tasks.md Content:

• All tasks have embedded test plans
• Test cases in BDD format (Given/When/Then)
• All AC-IDs from spec covered by tasks
• Model hints assigned (⚡🧠💎)
• Dependencies explicitly stated

metadata.json Content:

• Valid JSON syntax
• All required fields present
• Status is "planned"
• Type matches increment purpose
• Timestamps in ISO-8601 format

---

Helper Scripts

Located in plugins/specweave/skills/increment-planner/scripts/:

Get next increment number:

node plugins/specweave/skills/increment-planner/scripts/feature-utils.js next

Check for duplicates:

node plugins/specweave/skills/increment-planner/scripts/feature-utils.js check-increment 0021

Generate short name from description:

node plugins/specweave/skills/increment-planner/scripts/generate-short-name.js "Add user authentication"
# Returns: "user-authentication"

---

Common Patterns

Pattern 1: Simple Feature

User request: "Add user authentication"

Process:

1. Get next number: 0015
2. Generate short name: user-authentication
3. Create directory: .specweave/increments/0015-user-authentication/
4. Create metadata.json FIRST (required before spec.md)
5. Create spec.md (now allowed - metadata.json exists)
6. Create tasks.md (plan.md optional for simple features)
7. Guide user to complete in main conversation

Pattern 2: Critical Hotfix

User request: "Fix critical security vulnerability CVE-2024-1234"

Process:

1. Get next number: 0016
2. Short name: security-fix-cve-2024-1234
3. Type: hotfix (in metadata.json)
4. Priority: P1
5. Create templates with urgency markers
6. Guide user to complete quickly

Pattern 3: Bug Investigation

User request: "Investigate memory leak in production API"

Process:

1. Get next number: 0017
2. Short name: memory-leak-investigation
3. Type: bug (in metadata.json)
4. spec.md focuses on: What's broken? Expected vs actual? Impact?
5. plan.md focuses on: Investigation approach, tools, hypothesis
6. tasks.md focuses on: Investigation steps, fix implementation, verification

---

Troubleshooting

Issue: spec.md Write BLOCKED by guard Solution: Create metadata.json FIRST! The metadata-json-guard.sh hook blocks spec.md creation until metadata.json exists. Always follow the order: directory → metadata.json → spec.md → tasks.md

Issue: Feature number conflict Solution: Always run duplicate check before creating increment

Issue: metadata.json missing after creation Solution: Verify Write tool succeeded, check file exists with Read tool

Issue: Claude Code crashes during planning Solution: This skill creates templates only - completion happens in main conversation (NOT via nested agent spawning)

Issue: User stories don't have AC-IDs Solution: Ensure AC-IDs follow format: AC-US{number}-{criteria} (e.g., AC-US1-01)

Issue: Tasks missing test plans Solution: Each testable task MUST have Test Plan section with BDD format (Given/When/Then)

---

Integration with External Tools

GitHub Issues: After increment creation, optionally sync to GitHub:

/sw-github:create-issue 0021

Jira Epics: Sync to Jira:

/sw-jira:sync 0021

Azure DevOps: Sync to ADO work items:

/sw-ado:create-workitem 0021

---

Best Practices

✅ DO:

• Always create metadata.json (MANDATORY)
• Always create spec.md and tasks.md (MANDATORY)
• Create plan.md only for complex features with architecture decisions
• Use descriptive increment names
• Include AC-IDs in all acceptance criteria
• Embed tests in tasks.md (NO separate tests.md)
• Guide user to complete in main conversation
• Check for duplicates before creating

❌ DON'T:

• Use bare numbers (0001) without description
• Spawn agents from this skill (causes crashes)
• Skip metadata.json creation
• Create plan.md for bug fixes, simple migrations, or hotfixes
• Create separate tests.md (deprecated v0.7.0+)
• Reference SpecWeave internal docs/ADRs (users won't have them)
• Over-plan in skill (keep templates simple)

---

This skill is self-contained and works in ANY user project after specweave init.