sw:plan - Generate Implementation Plan

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 architectural changes');
  console.log('');
}

Why This Helps: Planning for framework features requires different considerations than user apps:

• Backward compatibility is critical
• Changes affect ALL SpecWeave users
• Architecture decisions need ADRs
• Workflow changes need CLAUDE.md updates

---

Workflow Integration

Typical workflow:

# 1. Create increment (generates spec.md)
sw:increment "Add user authentication"
# Status: BACKLOG → PLANNING (spec.md created)

# 2. Edit spec.md (add requirements, ACs)
# ... edit spec.md ...

# 3. Generate plan and tasks
sw:plan
# Status: PLANNING → ACTIVE (tasks.md created)

# 4. Execute tasks
sw:do

Error Handling

spec.md not found:

❌ spec.md not found in increment '0039-ultra-smart-next-command'
💡 Create spec.md first using `sw:increment` or manually

plan.md already exists:

❌ plan.md already exists in increment '0039'
💡 Use --force to overwrite existing plan.md

Increment closed:

❌ Cannot generate plan for COMPLETED increment
💡 Reopen increment with `sw:reopen` first

Architecture

Components:

• IncrementDetector: Auto-detect or validate increment
• PlanValidator: Validate pre-conditions
• ArchitectAgentInvoker: Generate plan.md via Architect Agent
• TaskGeneratorInvoker: Generate tasks.md with BDD test plans
• PlanCommandOrchestrator: Coordinate execution pipeline

State transitions:

• PLANNING → ACTIVE (when tasks.md created)
• ACTIVE → ACTIVE (regenerate plan/tasks)
• BACKLOG → (no change - spec.md already exists)

Markdown Preview Guidelines

When the execution strategy analysis (Step 6) identifies 2+ viable execution approaches or when task dependency ordering has meaningful alternatives, use AskUserQuestion with the markdown preview field to show DAG diagrams of task dependencies.

When to use: Presenting execution strategy options where the task dependency graph helps visualize parallelism, critical path, or execution order trade-offs.

When NOT to use: When there's only one viable strategy, or when the choice is purely about tooling (e.g., sw:do vs sw:auto) without structural implications.

Example: Task Execution Strategy with DAG Preview

AskUserQuestion({
  questions: [{
    question: "Which execution strategy should we use for this increment?",
    header: "Strategy",
    multiSelect: false,
    options: [
      {
        label: "Parallel (Recommended)",
        description: "Frontend and backend in parallel, merge at integration. 2 parallel lanes.",
        markdown: "T-001 [DB Schema]  ──► T-003 [API Routes] ──┐\n                                             ├──► T-006 [E2E Tests]\nT-002 [JWT Utils]  ──► T-004 [Middleware] ──┘\n                   └──► T-005 [Frontend]  ──► T-007 [Docs]\n\nCritical path: T-001 → T-003 → T-006\nParallel lanes: 2  |  Tasks: 7"
      },
      {
        label: "Sequential",
        description: "All tasks in order. Simpler but slower, no parallelism.",
        markdown: "T-001 [DB Schema] ──► T-002 [JWT Utils] ──► T-003 [API Routes]\n    ──► T-004 [Middleware] ──► T-005 [Frontend]\n    ──► T-006 [E2E Tests] ──► T-007 [Docs]\n\nCritical path: T-001 → T-002 → ... → T-007 (all)\nParallel lanes: 0  |  Tasks: 7"
      }
    ]
  }]
})

Related Commands

• sw:increment - Create new increment (generates spec.md)
• sw:do - Execute tasks from tasks.md
• sw:validate - Validate increment structure
• sw:sync-docs - Sync spec changes to living docs

Notes

• Auto-transition: Creating tasks.md automatically transitions PLANNING → ACTIVE
• Force mode: Use with caution - overwrites existing work
• Preserve status: Use --preserve-task-status to keep completion checkmarks when regenerating
• Architect Agent: Requires ~10-30 seconds for plan generation
• Test coverage: tasks.md includes embedded test plans for each task

---

Part of: Increment 0039 (Ultra-Smart Next Command) Status: Phase 1 - Foundation (US-007)

Resources

• Official Documentation