/plan

description: "[DEPRECATED] Standalone `sw:plan` is deprecated. Use `sw:increment --regenerate-plan` to regenerate plan.md for an existing increment."
version: 1.0.0

sw:plan - Generate Implementation Plan

Migration

> Standalone `sw:plan` is deprecated. Use `sw:increment --regenerate-plan` to regenerate `plan.md` and `tasks.md` for an existing increment.

The standalone plan skill has been folded into `sw:increment` via the `--regenerate-plan` flag. This avoids two near-identical entry points and centralises planning logic. The old workflow still works during the deprecation window but will be removed in SpecWeave v1.3.0.

Replace:

/sw:plan 0014

With:

/sw:increment --regenerate-plan 0014

**⚠️ FOR EXISTING INCREMENTS ONLY - NOT for creating new increments!**

**When to use `sw:plan`:**

• You already have `spec.md` created
• Increment status is PLANNING or ACTIVE
• You need to generate/regenerate `plan.md` and `tasks.md`

**When NOT to use `sw:plan`:**

• Creating a brand new increment from scratch → Use `sw:increment` instead
• No `spec.md` exists yet → Use `sw:increment` instead

---

Generate `plan.md` and `tasks.md` for an increment using Architect Agent.

Usage

sw:plan                      # Auto-detect PLANNING increment
sw:plan 0039                 # Explicit increment ID
sw:plan --force              # Overwrite existing plan/tasks
sw:plan 0039 --verbose       # Verbose output

What It Does

1. **Auto-detect increment** (if not specified):

• Prefers PLANNING status
• Falls back to single ACTIVE increment

2. **Validate pre-conditions**:

• spec.md exists and is not empty
• Increment is not COMPLETED/ABANDONED
• plan.md/tasks.md don't exist (unless --force)

**Error Handling:**

   import { ERROR_MESSAGES, formatError } from './src/utils/error-formatter.js';

   // If spec.md not found
   if (!specExists) {
     formatError(ERROR_MESSAGES.SPEC_NOT_FOUND(incrementId));
     return;
   }

   // If increment not found
   if (!incrementExists) {
     formatError(ERROR_MESSAGES.INCREMENT_NOT_FOUND(incrementId));
     return;
   }

   // If user tries to use sw:plan for NEW increments
   if (userIsCreatingNew) {
     formatError(ERROR_MESSAGES.WRONG_COMMAND_FOR_NEW_INCREMENT());
     return;
   }

3. **Generate plan.md** (via Architect Agent):

• Technical approach
• Architecture design
• Dependencies
• Risk assessment

4. **Generate tasks.md**:

• Checkable task list
• Embedded test plans (BDD format)
• Coverage targets

5. **Update metadata**:

• PLANNING → ACTIVE transition (tasks.md now exists)
• Update lastUpdated timestamp

6. **Execution Strategy Recommendation** (MANDATORY): After generating tasks.md, analyze complexity and output a recommendation:

**6a. Count pending tasks** in the generated tasks.md (count `[ ]` markers)

**6b. Detect domains** from file paths and task descriptions:

• Frontend: `src/components/`, `src/pages/`, `src/hooks/`, `src/styles/`, `.tsx`, `.css`, React/Vue/Angular keywords
• Backend: `src/api/`, `src/services/`, `src/middleware/`, `src/routes/`, Express/Fastify/NestJS keywords
• Database: `prisma/`, `src/db/`, `migrations/`, `schema`, SQL/Prisma keywords
• DevOps: `Dockerfile`, `.github/`, `k8s/`, `terraform/`, CI/CD keywords
• Testing: `tests/`, `e2e/`, `.test.`, `.spec.`, test framework keywords
• Security: `src/auth/`, authentication, authorization keywords
• Mobile: `ios/`, `android/`, React Native keywords

**6c. Apply execution strategy matrix** and output:

   EXECUTION STRATEGY
   ══════════════════════════════════════════
   Tasks: [N] pending | Domains: [N] ([list])
   ──────────────────────────────────────────
   Recommended: sw:do        (≤8 tasks, 1 domain)
   Recommended: sw:auto      (9-15 tasks, 1-2 domains)
   Recommended: sw:team-lead (>15 tasks OR 3+ domains)
   ══════════════════════════════════════════
   ⚠️  sw:team-lead uses more tokens but produces higher quality
      through parallel domain-specialized agents.

   Next: sw:team-lead [ID] | sw:auto [ID] | sw:do [ID]

Show ONLY the matching recommendation line (not all three). For 3+ domains, add a stronger nudge:

   ⚡ This is a multi-domain feature. sw:team-lead is strongly recommended
      for parallel execution across [domain1], [domain2], [domain3].

Options

• `--force`: Overwrite existing plan.md/tasks.md
• `--preserve-task-status`: Keep existing task completion status (requires --force)
• `--verbose`: Show detailed execution information

Examples

**Auto-detect and plan**:

sw:plan
# ✅ Auto-detected increment: 0039-ultra-smart-next-command
# ✅ Generated plan.md (2.5K)
# ✅ Generated tasks.md (4.2K, 15 tasks)
# ✅ Transitioned PLANNING → ACTIVE

**Force regenerate**:

sw:plan 0039 --force
# ⚠️  Overwriting existing plan.md
# ⚠️  Overwriting existing tasks.md
# ✅ Generated plan.md (2.8K)
# ✅ Generated tasks.md (5.1K, 18 tasks)

**Multiple PLANNING increments**:

sw:plan
# ❌ Multiple increments in PLANNING status found:
#    - 0040-feature-a
#    - 0041-feature-b
# Please specify: sw:plan 0040

Self-Awareness Check

**🎯 OPTIONAL**: Detect if planning for SpecWeave framework increment.

Before generating plan.md, check repository context:

import { detectSpecWeaveRepository } from './src/utils/repository-detector.js';

const repoInfo = detectSpecWeaveRepository(process.cwd());

if (repoInfo.isSpecWeaveRepo) {
  console.log('ℹ️  Planning for SpecWeave framework increment');
  console.log('');
  console.log('   💡 Framework Planning Considerations:');
  console.log('      • Design for backward compatibility');
  console.log('      • Consider impact on existing user projects');
  console.log('      • Plan for migration guides if breaking');
  console.log('      • Document new patterns in CLAUDE.md');
  console.log('      • Add ADR for significant arc