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 examples: - /workflow:plan "Build authentication system" - /workflow:plan requirements.md - /workflow:plan ISS-001

Workflow Plan Command

Usage

/workflow:plan <input>

Input Detection

• Files: .md/.txt/.json/.yaml/.yml → Reads content and extracts requirements
• Issues: ISS-*, ISSUE-*, *-request-* → Loads issue data and acceptance criteria
• Text: Everything else → Parses natural language requirements

Core Workflow

Analysis & Planning Process

The command performs comprehensive analysis through:

0. Pre-Analysis Documentation Check ⚠️ FIRST STEP

• Selective documentation loading based on task requirements:
  • Always check: .workflow/docs/README.md - System navigation and module index
  • For architecture tasks: .workflow/docs/architecture/system-design.md, module-map.md
  • For specific modules: .workflow/docs/modules/[relevant-module]/overview.md
  • For API tasks: .workflow/docs/api/unified-api.md
• Context-driven selection: Only load documentation relevant to the specific task scope
• Foundation for analysis: Use relevant docs to understand affected components and dependencies

1. Context Gathering & Intelligence Selection

• Reading relevant CLAUDE.md documentation based on task requirements
• Automatic tool assignment based on complexity:
  • Simple tasks (≤3 modules): Direct CLI tools with intelligent path navigation and multi-round analysis

    # Analyze specific directory
    cd "src/auth" && ~/.claude/scripts/gemini-wrapper -p "
    PURPOSE: Analyze authentication patterns
    TASK: Review auth implementation for security patterns
    CONTEXT: Focus on JWT handling and user validation
    EXPECTED: Security assessment and recommendations
    RULES: Focus on security vulnerabilities and best practices
    "
    
    # Implement in specific directory
    codex -C src/components --full-auto exec "
    PURPOSE: Create user profile component
    TASK: Build responsive profile component with form validation
    CONTEXT: Use existing component patterns
    EXPECTED: Complete component with tests
    RULES: Follow existing component architecture
    " -s danger-full-access
    

  • Complex tasks (>3 modules): Specialized task agents with autonomous CLI tool orchestration and cross-module coordination
• Flow control integration with automatic tool selection

2. Project Structure Analysis ⚠️ CRITICAL PRE-PLANNING STEP

• Documentation Context First: Reference .workflow/docs/ content from /workflow:docs command if available
• Complexity assessment: Count total saturated tasks
• Decomposition strategy: Flat (≤5) | Hierarchical (6-10) | Re-scope (>10)
• Module boundaries: Identify relationships and dependencies using existing documentation
• File grouping: Cohesive file sets and target_files generation
• Pattern recognition: Existing implementations and conventions

3. Analysis Artifacts Generated

• ANALYSIS_RESULTS.md: Context analysis, codebase structure, pattern identification, task decomposition
• Context mapping: Project structure, dependencies, cohesion groups
• Implementation strategy: Tool selection and execution approach

Implementation Standards

Context Management & Agent Execution

Agent Context Loading ⚠️ CRITICAL The following pre_analysis steps are generated for agent execution:

// Example pre_analysis steps generated by /workflow:plan for agent execution
"flow_control": {
  "pre_analysis": [
    {
      "step": "load_planning_context",
      "action": "Load plan-generated analysis and context",
      "command": "bash(cat .workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md 2>/dev/null || echo 'planning analysis not found')",
      "output_to": "planning_context"
    },
    {
      "step": "mcp_codebase_exploration",
      "action": "Explore codebase structure and patterns using MCP tools",
      "command": "mcp__code-index__find_files(pattern=\"[task_focus_patterns]\") && mcp__code-index__search_code_advanced(pattern=\"[relevant_patterns]\", file_pattern=\"[target_extensions]\")",
      "output_to": "codebase_structure"
    },
    {
      "step": "mcp_external_context",
      "action": "Get external API examples and best practices",
      "command": "mcp__exa__get_code_context_exa(query=\"[task_technology] [task_patterns]\", tokensNum=\"dynamic\")",
      "output_to": "external_context"
    },
    {
      "step": "load_dependencies",
      "action": "Retrieve dependency task summaries",
      "command": "bash(cat .workflow/WFS-[session]/.summaries/IMPL-[dependency_id]-summary.md 2>/dev/null || echo 'dependency summary not found')",
      "output_to": "dependency_context"
    },
    {
      "step": "load_base_documentation",
      "action": "Load core documentation files",
      "commands": [
        "bash(cat .workflow/docs/README.md 2>/dev/null || echo 'Base docs not found')",
        "bash(cat CLAUDE.md README.md 2>/dev/null || echo 'Project docs not found')"
      ],
      "output_to": "base_docs"
    },
    {
      "step": "load_task_specific_docs",
      "action": "Load documentation relevant to task type",
      "commands": [
        "bash(cat .workflow/docs/architecture/*.md 2>/dev/null || echo 'Architecture docs not found')",
        "bash(cat .workflow/docs/api/*.md 2>/dev/null || echo 'API docs not found')"
      ],
      "output_to": "task_docs"
    },
    {
      "step": "analyze_task_patterns",
      "action": "Analyze existing code patterns for task context",
      "commands": [
        "bash(cd \"[task_focus_paths]\")",
        "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze task patterns TASK: Review '[task_title]' patterns CONTEXT: Task [task_id] in [task_focus_paths] EXPECTED: Pattern analysis RULES: Focus on existing patterns\")"
      ],
      "output_to": "task_context",
      "on_error": "fail"
    }
  ]
}

Context Accumulation Guidelines: Flow_control design should follow these principles:

1. Structure Analysis: Project hierarchy and patterns
2. Dependency Mapping: Previous task summaries → inheritance context
3. Task Context Generation: Combined analysis → task.context fields
4. CLI Tool Analysis: Use Gemini/Codex appropriately for pattern analysis when needed

MCP Integration Principles:

• Code Index First: Use mcp__code-index__ for internal codebase exploration before external tools
• Exa for Context: Use mcp__exa__get_code_context_exa to supplement with external API patterns and examples
• Automatic Fallback: If MCP tools unavailable, workflow uses traditional bash/CLI tools
• Enhanced Analysis: MCP tools provide deeper codebase understanding and external best practices

Benefits of MCP Integration:

• Faster Analysis: Direct codebase indexing vs. manual file searching
• External Context: Real-world API patterns and implementation examples
• Pattern Recognition: Advanced code pattern matching and similarity detection
• Comprehensive Coverage: Both internal code exploration and external best practice lookup

Implementation Approach Planning: Each task's flow_control.implementation_approach defines execution strategy (planning phase):

1. task_description: Implementation strategy definition:

   • Clear implementation goal to be executed later
   • Planned reference to patterns from pre_analysis results
   • Integration strategy with existing codebase

2. modification_points: Planned code modification targets:

   • Specific code changes to be made during execution
   • Planned use of parent task patterns via [parent] context
   • Integration points with existing components via [context] from dependencies

3. logic_flow: Business logic execution plan:

   • Step-by-step workflow to be implemented
   • Planned data flow between components
   • Integration points using [inherited] and [shared] context

4. target_files: Target file specifications for execution:

   • src/auth/login.ts:handleLogin:75-120 (planned function and line range)
   • src/middleware/auth.ts:validateToken (planned function target)
   • Must align with task's context.focus_paths

Variable Reference System:

• [design] - Results from pre_analysis steps
• [parent] - Context inherited from parent tasks
• [context] - Dependencies from related tasks
• [inherited] - Shared context from session
• [shared] - Global rules and patterns

Content Sources:

• Task summaries: .workflow/WFS-[session]/.summaries/
• Documentation: .workflow/docs/, CLAUDE.md, README.md, config files
• Analysis artifacts: .workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md
• Dependency contexts: .workflow/WFS-[session]/.task/IMPL-*.json

Task Decomposition Standards

Core Principle: Task Merging Over Decomposition

• Merge Rule: Tasks that can be executed together should not be separated - avoid unnecessary decomposition
• Decomposition Criteria: Only decompose tasks in the following situations:
  • Excessive Workload: Code exceeds 2500 lines or modifies more than 6 files
  • Context Separation: Involves completely different tech stacks or business domains
  • Dependency Blocking: Subsequent tasks must wait for prerequisite task completion
  • Parallel Execution: Independent features that can be developed simultaneously by different developers

Rules:

• Maximum 10 tasks: Hard limit - exceeding requires re-scoping
• Function-based: Complete functional units with related files (logic + UI + tests + config)
• File cohesion: Group tightly coupled components in same task
• Hierarchy: Flat (≤5 tasks) | Two-level (6-10 tasks) | Re-scope (>10 tasks)

Session Management ⚠️ CRITICAL

• ⚡ FIRST ACTION: Check for all .workflow/.active-* markers before any planning
• Multiple sessions support: Different Claude instances can have different active sessions
• User selection: If multiple active sessions found, prompt user to select which one to work with
• Auto-session creation: WFS-[topic-slug] only if no active session exists
• Session continuity: MUST use selected active session to maintain context
• ⚠️ Dependency context: MUST read ALL previous task summary documents from selected session before planning
• Session isolation: Each session maintains independent context and state

Task Patterns:

• ✅ Correct (Function-based): IMPL-001: User authentication system (models + routes + components + middleware + tests)
• ❌ Wrong (File/step-based): IMPL-001: Create database model, IMPL-002: Create API endpoint

Document Generation

Workflow: Identifier Creation → Folder Structure → IMPL_PLAN.md → .task/IMPL-NNN.json → TODO_LIST.md

Always Created:

• IMPL_PLAN.md: Requirements, task breakdown, success criteria
• Session state: Task references and paths

Auto-Created (complexity > simple):

• TODO_LIST.md: Hierarchical progress tracking
• .task/*.json: Individual task definitions with flow_control
• .process/ANALYSIS_RESULTS.md: Analysis results and planning artifacts

Document Structure:

.workflow/WFS-[topic]/
├── IMPL_PLAN.md          # Main planning document
├── TODO_LIST.md          # Progress tracking (if complex)
├── .process/
│   └── ANALYSIS_RESULTS.md  # Analysis results and planning artifacts
└── .task/
    ├── IMPL-001.json     # Task definitions with flow_control
    └── IMPL-002.json

IMPL_PLAN.md Structure ⚠️ REQUIRED FORMAT

File Header (required)：

• Identifier: Unique project identifier and session ID, format WFS-[topic]
• Source: Input type, e.g. "User requirements analysis"
• Analysis: Analysis document reference

Summary (execution overview)：

• Concise description of core requirements and objectives
• Technical direction and implementation approach

Context Analysis (context analysis)：

• Project - Project type and architectural patterns
• Modules - Involved modules and component list
• Dependencies - Dependency mapping and constraints
• Patterns - Identified code patterns and conventions

Task Breakdown (task decomposition)：

• Task Count - Total task count and complexity level
• Hierarchy - Task organization structure (flat/hierarchical)
• Dependencies - Inter-task dependency graph

Implementation Plan (implementation plan)：

• Execution Strategy - Execution strategy and methodology
• Resource Requirements - Required resources and tool selection
• Success Criteria - Success criteria and acceptance conditions

Reference Information

Task JSON Schema (5-Field Architecture)

Each task.json uses the workflow-architecture.md 5-field schema:

• id: IMPL-N[.M] format (max 2 levels)
• title: Descriptive task name
• status: pending|active|completed|blocked|container
• meta: { type, agent }
• context: { requirements, focus_paths, acceptance, parent, depends_on, inherited, shared_context }
• flow_control: { pre_analysis[], implementation_approach, target_files[] }

MCP Tools Integration: Enhanced with optional MCP servers for advanced analysis:

• Code Index MCP: mcp__code-index__find_files(), mcp__code-index__search_code_advanced()
• Exa MCP: mcp__exa__get_code_context_exa() for external patterns

File Structure Reference

Architecture: @~/.claude/workflows/workflow-architecture.md

Execution Integration

Documents created for /workflow:execute:

• IMPL_PLAN.md: Context loading and requirements
• .task/*.json: Agent implementation context
• TODO_LIST.md: Status tracking (container tasks with ▸, leaf tasks with checkboxes)

Error Handling

• Vague input: Auto-reject ("fix it", "make better", etc.)
• File not found: Clear suggestions
• >10 tasks: Force re-scoping into iterations

Planning-Only Constraint

This command creates implementation plans but does not execute them. Use /workflow:execute for actual implementation.