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

name: plan description: Create implementation plans by orchestrating intelligent context gathering and analysis modules 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 (/workflow:plan)

Overview

Creates implementation plans by orchestrating intelligent context gathering and analysis modules.

Core Principles

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)

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

Task JSON Creation Process

Task JSON Generation Philosophy:

1. Analysis-Driven: Task definitions generated from intelligent analysis results
2. Context-Rich: Each task includes comprehensive context for autonomous execution
3. Flow-Control Ready: Pre-analysis steps and implementation approach pre-defined
4. Agent-Optimized: Complete context provided for specialized agent execution

Automatic Task Generation Workflow:

1. Parse Analysis Results: Extract task recommendations from ANALYSIS_RESULTS.md
2. Extract Task Details: Parse task ID, title, scope, complexity from structured analysis
3. Generate Context: Create requirements, focus_paths, and acceptance criteria
4. Build Flow Control: Define pre_analysis steps and implementation approach
5. Create JSON Files: Generate individual .task/IMPL-*.json files with 5-field schema

Session Management ⚠️ CRITICAL

• Command: Uses /workflow:session:start command for intelligent session discovery and creation
• ⚡ FIRST ACTION: Check for all .workflow/.active-* markers before any planning
• Relevance Analysis: Automatically analyzes task relevance with existing sessions
• Auto-session creation: WFS-[topic-slug] only if no active session exists or task is unrelated
• 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

Session ID Transmission Guidelines ⚠️ CRITICAL

• Format: WFS-[topic-slug] from active session markers
• Usage: /context:gather --session WFS-[id] and /analysis:run --session WFS-[id]
• Rule: ALL modular commands MUST receive current session ID for context continuity

Execution Lifecycle

Phase 1: Session Management

1. Session Discovery: Use /workflow:session:start command for intelligent session discovery
2. Relevance Analysis: Automatically analyze task relevance with existing sessions
3. Session Selection: Auto-select or create session based on relevance analysis
4. Context Preparation: Load session state and prepare for planning

Phase 2: Context Gathering

1. Context Collection: Execute /context:gather with task description and session ID
2. Asset Discovery: Gather relevant documentation, code, and configuration files
3. Context Packaging: Generate standardized context-package.json
4. Validation: Ensure context package contains sufficient information

Phase 3: Intelligent Analysis

1. Analysis Execution: Run /analysis:run with context package and session ID
2. Tool Selection: Automatically select optimal analysis tools (Gemini/Qwen/Codex)
3. Result Generation: Produce structured ANALYSIS_RESULTS.md
4. Validation: Verify analysis completeness and task recommendations

Phase 4: Plan Assembly & Document Generation

1. Plan Generation: Create IMPL_PLAN.md from analysis results
2. Task JSON Creation: Generate individual task JSON files with 5-field schema
3. TODO List Creation: Generate TODO_LIST.md with document format
4. Session Update: Mark session as ready for execution

TodoWrite Progress Tracking

Comprehensive planning tracking with real-time status updates throughout entire planning lifecycle:

TodoWrite Planning Rules

1. Initial Creation: Generate TodoWrite from planning phases
2. Single In-Progress: Mark ONLY ONE phase as in_progress at a time
3. Immediate Updates: Update status after each phase completion
4. Continuous Tracking: Maintain TodoWrite throughout entire planning workflow

TodoWrite Tool Usage

// Initialize planning workflow tracking
TodoWrite({
  todos: [
    {"content": "Initialize session management", "status": "pending", "activeForm": "Initializing session management"},
    {"content": "Gather intelligent context", "status": "pending", "activeForm": "Gathering intelligent context"},
    {"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
    {"content": "Generate implementation plan and tasks", "status": "pending", "activeForm": "Generating implementation plan and tasks"}
  ]
})

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

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",
      "commands": [
        "Read(.workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md)",
        "Read(.workflow/WFS-[session]/.process/context-package.json)"
      ],
      "output_to": "planning_context"
    },
    {
      "step": "load_context_assets",
      "action": "Load structured assets from context package",
      "command": "Read(.workflow/WFS-[session]/.process/context-package.json)",
      "output_to": "context_assets"
    },
    {
      "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"
    }
  ]
}

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)