Claude-Code-Workflow/.claude/commands/workflow/plan.md

name: plan description: Create implementation plans with intelligent input detection usage: /workflow:plan argument-hint: "text description"|file.md|ISS-001|template-name examples: - /workflow:plan "Build authentication system" - /workflow:plan requirements.md - /workflow:plan ISS-001

Workflow Plan Command (/workflow:plan)

Overview

Creates actionable implementation plans with intelligent input source detection. Supports text, files, issues, and templates through automatic recognition.

Core Principles

File Structure: @~/.claude/workflows/workflow-architecture.md

Usage

/workflow:plan [--AM gemini|codex] <input>

Analysis Method Flag (--AM)

Optional flag to specify which CLI tool to use for context analysis:

• gemini (default): Uses Gemini CLI for pattern-based analysis and architectural understanding
• codex: Uses Codex CLI for autonomous development context gathering with intelligent file discovery

Examples:

/workflow:plan --AM codex "Build authentication system"
/workflow:plan --AM gemini requirements.md

Input Detection Logic

The command automatically detects input type:

File Input (Auto-detected)

/workflow:plan requirements.md
/workflow:plan config.json

Triggers: Extensions: .md, .txt, .json, .yaml, .yml Processing: Reads file contents and extracts requirements

Issue Input (Auto-detected)

/workflow:plan ISS-001
/workflow:plan ISSUE-123

Triggers: Patterns: ISS-, ISSUE-, -request- Processing: Loads issue data and acceptance criteria

Text Input (Default)

/workflow:plan "Build user authentication with JWT and OAuth2"

Triggers: Everything else Processing: Parse natural language requirements

Automatic Behaviors

Session Management

• Creates new session if none exists
• Uses active session if available
• Generates session ID: WFS-[topic-slug]

Complexity Detection with Saturation

• Simple: ≤8 saturated tasks → Direct IMPL_PLAN.md
• Medium: 9-15 saturated tasks → IMPL_PLAN.md + TODO_LIST.md
• Complex: >15 saturated tasks → Full decomposition

Note: 1 complex preparation task = 0.5 saturated task for counting

Task Granularity Principles

• Decompose by function, not by file: Each task should complete a whole functional unit
• Maintain functional integrity: Each task produces independently runnable or testable functionality
• Implement related components together: UI, logic, tests and other related parts in the same task
• Avoid technical step decomposition: Don't make "create file" or "add function" as separate tasks

Task Decomposition Anti-patterns

❌ Wrong Example - File/Step-based Decomposition:

• IMPL-001: Create database model
• IMPL-002: Create API endpoint
• IMPL-003: Create frontend component
• IMPL-004: Add routing configuration
• IMPL-005: Write unit tests

✅ Correct Example - Function-based Decomposition:

• IMPL-001: Implement user authentication feature (includes model, API, UI, tests)
• IMPL-002: Implement data export functionality (includes processing logic, UI, file generation)

Task Generation with Saturation Control

• Task Saturation Assessment: Evaluates whether to merge preparation and execution
• Default merge mode: "Analyze and implement X" instead of "Analyze X" + "Implement X"
• Smart splitting: Only separate when preparation complexity > threshold
• Automatically creates .task/ files when complexity warrants
• Generates hierarchical task structure (max 2 levels)
• Main tasks with subtasks become container tasks (not directly executable)
• Updates session state with task references
• Runs project structure analysis to populate paths field

Project Analysis Options

Three analysis levels available:

# Quick - Structure only (5 seconds)
/workflow:plan "requirements"

# Standard - Structure + Gemini analysis (30 seconds)
/workflow:plan --analyze "requirements"

# Deep - Structure + Parallel comprehensive analysis (1-2 minutes)
/workflow:plan --deep "requirements"

Analysis Selection:

• Default: Auto-selects based on project complexity
• Manual: Use flags to override automatic selection
• Strategy: See @~/.claude/workflows/intelligent-tools-strategy.md for tool selection principles

Execution:

1. Always runs get_modules_by_depth.sh for structure
2. Applies selected analysis level
3. Populates task paths automatically

Task Saturation Assessment

Evaluates whether to merge preparation and execution:

Default Merge Principles (Saturated Tasks):

• All components of the same functional module
• Frontend and backend paired implementation
• Features with their corresponding tests
• Configuration with its usage code
• Multiple small interdependent functions

Only Separate Tasks When:

• Completely independent functional modules (no shared code)
• Independent services with different tech stacks (e.g., separate frontend/backend deployment)
• Modules requiring different expertise (e.g., ML model training vs Web development)
• Large features with clear sequential dependencies

Task Examples:

• Merged Example: "IMPL-001: Implement user authentication system (includes JWT management, API endpoints, UI components, and tests)"
• Separated Example: "IMPL-001: Design cross-service authentication architecture" + "IMPL-002: Implement frontend authentication module" + "IMPL-003: Implement backend authentication service"

Task Breakdown Process

• Automatic decomposition: Only when task count >15 are tasks broken into subtasks (impl-N.M format)
• Function-based decomposition: Split by independent functional boundaries, not by technical layers
• Container tasks: Parent tasks with subtasks become containers (marked with ▸ in TODO_LIST)
• Smart decomposition: AI analyzes task title to suggest logical functional subtask structure
• Complete unit principle: Each subtask must still represent a complete functional unit
• Context inheritance: Subtasks inherit parent's requirements and scope, refined for specific needs
• Agent assignment: Automatic agent mapping based on subtask type (planning/code/test/review)
• Maximum depth: 2 levels (impl-N.M) to maintain manageable hierarchy

Implementation Field Requirements

• analysis_source: Determines context gathering method (manual|auto-detected|gemini|codex)
• Auto-assignment: manual (user provides details) → auto-detected (system infers) → gemini/codex (needs analysis)
• Required fields: files (with path/location/modifications), context_notes, analysis_source
• Paths format: Semicolon-separated list (e.g., "src/auth;tests/auth;config/auth.json")

Session Check Process

⚠️ CRITICAL: Check for existing active session before planning

1. Check Active Session: Check for .workflow/.active-* marker file
2. Session Selection: Use existing active session or create new
3. Context Integration: Load session state and existing context

Output Documents

Document References for Execution

Primary References

• Planning Document: .workflow/WFS-[topic-slug]/IMPL_PLAN.md

  • Used by: /workflow:execute for context loading
  • Contains: Requirements, task overview, success criteria

• Task Definitions: .workflow/WFS-[topic-slug]/.task/impl-*.json

  • Used by: Agents for implementation context
  • Contains: Complete task details with implementation field including preparation_complexity

• Progress Tracking: .workflow/WFS-[topic-slug]/TODO_LIST.md

  • Used by: /workflow:execute for status tracking
  • Updated by: Agents after task completion

IMPL_PLAN.md (Always Created)

# Implementation Plan - [Project Name]
*Generated from: [input_source]*

## Requirements
[Extracted requirements from input source]

## Task Breakdown
- **IMPL-001**: [Saturated task description with merged preparation and execution]
- **IMPL-002**: [Task description]

## Success Criteria
[Measurable completion conditions]

Optional TODO_LIST.md (Auto-triggered)

Created when complexity > simple or task count > 5

TODO_LIST Structure: Uses unified hierarchical list format

• Container tasks (with subtasks) marked with ▸ symbol
• Leaf tasks use standard - [ ] / - [x] checkboxes
• Indentation shows hierarchy (2 spaces per level)
• Container tasks represent logical grouping, not executable items

Task JSON Files (Auto-created)

Generated in .task/ directory when decomposition enabled

Error Handling

Input Processing Errors

• File not found: Clear error message with suggestions
• Invalid issue: Verify issue ID exists
• Unknown template: List available templates
• Empty input: Prompt for valid input
• Vague text input: Auto-reject without guidance
  • Rejected examples: "do something", "fix it", "make it better", "add feature"
  • Response: Direct rejection message, no further assistance

Recommended Task Patterns

Complete Feature Implementation

"Implement user management system" - includes CRUD operations, permissions, UI components, API endpoints, and tests

End-to-End Features

"Add Excel export functionality" - includes data processing, file generation, download API, UI buttons, and error handling

System Integration

"Integrate payment gateway" - includes API integration, order processing, payment flows, webhook handling, and testing

Problem Resolution

"Fix and optimize search functionality" - includes bug fixes, performance optimization, UI improvements, and related tests

Module Development

"Create notification system" - includes email/SMS sending, template management, subscription handling, and admin interface

System ensures: Unified planning interface with intelligent input detection and function-based task granularity