Generate plan.md and tasks.md for PLANNING increment using Architect Agent
Generate plan.md and tasks.md for an existing increment with spec.md. Use this after editing spec.md to create implementation plans and test-aware task lists.
/plugin marketplace add anton-abyzov/specweave/plugin install sw@specweave⚠️ FOR EXISTING INCREMENTS ONLY - NOT for creating new increments!
When to use /sw:plan:
spec.md createdplan.md and tasks.mdWhen NOT to use /sw:plan:
/sw:increment insteadspec.md exists yet → Use /sw:increment insteadGenerate plan.md and tasks.md for an increment using Architect Agent and test-aware-planner.
/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
Auto-detect increment (if not specified):
Validate pre-conditions:
Error Handling (v1.0.102+):
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;
}
Generate plan.md (via Architect Agent):
Generate tasks.md (via test-aware-planner):
Update metadata:
--force: Overwrite existing plan.md/tasks.md--preserve-task-status: Keep existing task completion status (requires --force)--verbose: Show detailed execution informationAuto-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
🎯 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:
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
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
Components:
IncrementDetector: Auto-detect or validate incrementPlanValidator: Validate pre-conditionsArchitectAgentInvoker: Generate plan.md via Architect AgentTaskGeneratorInvoker: Generate tasks.md via test-aware-plannerPlanCommandOrchestrator: Coordinate execution pipelineState transitions:
/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--preserve-task-status to keep completion checkmarks when regeneratingPart of: Increment 0039 (Ultra-Smart Next Command) Status: Phase 1 - Foundation (US-007)