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

name: plan-deep description: Deep technical planning with Gemini CLI analysis and action-planning-agent usage: /workflow:plan-deep <task_description> argument-hint: "task description" | requirements.md examples: - /workflow:plan-deep "Refactor authentication system to use JWT" - /workflow:plan-deep "Implement real-time notifications across modules" - /workflow:plan-deep requirements.md

Workflow Plan Deep Command (/workflow:plan-deep)

Overview

Creates comprehensive implementation plans through deep codebase analysis using Gemini CLI and the action-planning-agent. This command enforces multi-dimensional context gathering before planning, ensuring technical decisions are grounded in actual codebase understanding.

Key Differentiators

vs /workflow:plan

Feature	/workflow:plan	/workflow:plan-deep
Analysis Depth	Basic requirements extraction	Deep codebase analysis
Gemini CLI	Optional	Mandatory (via agent)
Context Scope	Current input only	Multi-dimensional analysis
Agent Used	None (direct processing)	action-planning-agent
Output Detail	Standard IMPL_PLAN	Enhanced hierarchical plan
Best For	Quick planning	Complex technical tasks

When to Use This Command

Ideal Scenarios

• Cross-module refactoring requiring understanding of multiple components
• Architecture changes affecting system-wide patterns
• Complex feature implementation spanning >3 modules
• Performance optimization requiring deep code analysis
• Security enhancements needing comprehensive vulnerability assessment
• Technical debt resolution with broad impact

Not Recommended For

• Simple, single-file changes
• Documentation updates
• Configuration adjustments
• Tasks with clear, limited scope

Execution Flow

1. Input Processing

Input Analysis:
├── Validate input clarity (reject vague descriptions)
├── Parse task description or file
├── Extract key technical terms
├── Identify potential affected domains
└── Prepare context for agent

Clarity Requirements:

• Minimum specificity: Must include clear technical goal and affected components
• Auto-rejection: Vague inputs like "optimize system", "refactor code", "improve performance" without context
• Response: ❌ Input too vague. Deep planning requires specific technical objectives and component scope.

2. Agent Invocation with Deep Analysis Flag

The command invokes action-planning-agent with special parameters that enforce Gemini CLI analysis.

3. Agent Processing (Delegated to action-planning-agent)

Agent Execution Flow:

Agent receives DEEP_ANALYSIS_REQUIRED flag
├── Executes 4-dimension Gemini CLI analysis in parallel:
│   ├── Architecture Analysis (patterns, components)
│   ├── Code Pattern Analysis (conventions, standards)
│   ├── Impact Analysis (affected modules, dependencies)
│   └── Testing Requirements (coverage, patterns)
├── Consolidates Gemini results into gemini-analysis.md
├── Creates workflow session directory
├── Generates hierarchical IMPL_PLAN.md
├── Creates TODO_LIST.md for tracking
└── Saves all outputs to .workflow/WFS-[session-id]/

Task(action-planning-agent):
  description: "Deep technical planning with mandatory codebase analysis"
  prompt: |
    Create implementation plan for: [task_description]
    
    EXECUTION MODE: DEEP_ANALYSIS_REQUIRED
    
    MANDATORY REQUIREMENTS:
    - Execute comprehensive Gemini CLI analysis (4 dimensions)
    - Skip PRD processing (no PRD provided)
    - Skip session inheritance (standalone planning)
    - Force FLOW_CONTROL flag = true
    - Set pre_analysis = multi-step array format with comprehensive analysis steps
    - Generate hierarchical task decomposition (max 2 levels: IMPL-N.M)
    - Create detailed IMPL_PLAN.md with subtasks
    - Generate TODO_LIST.md for tracking
    
    GEMINI ANALYSIS DIMENSIONS (execute in parallel):
    1. Architecture Analysis - design patterns, component relationships
    2. Code Pattern Analysis - conventions, error handling, validation
    3. Impact Analysis - affected modules, breaking changes
    4. Testing Requirements - coverage needs, test patterns
    
    FOCUS: Technical implementation based on deep codebase understanding

4. Output Generation (by Agent)

The action-planning-agent generates in .workflow/WFS-[session-id]/:

• IMPL_PLAN.md - Hierarchical implementation plan with stages
• TODO_LIST.md - Unified hierarchical task tracking with ▸ container tasks and indented subtasks
• .task/*.json - Task definitions for complex projects
• workflow-session.json - Session tracking
• gemini-analysis.md - Consolidated Gemini analysis results

Command Processing Logic

def process_plan_deep_command(input):
    # Step 1: Parse input
    task_description = parse_input(input)
    
    # Step 2: Build agent prompt with deep analysis flag
    agent_prompt = f"""
    EXECUTION_MODE: DEEP_ANALYSIS_REQUIRED
    TASK: {task_description}
    
    MANDATORY FLAGS:
    - FLOW_CONTROL = true
    - pre_analysis = multi-step array format for comprehensive pre-analysis
    - FORCE_PARALLEL_ANALYSIS = true
    - SKIP_PRD = true
    - SKIP_SESSION_INHERITANCE = true
    
    Execute comprehensive Gemini CLI analysis before planning.
    """
    
    # Step 3: Invoke action-planning-agent
    # Agent will handle session creation and Gemini execution
    Task(
        subagent_type="action-planning-agent",
        description="Deep technical planning with mandatory analysis",
        prompt=agent_prompt
    )
    
    # Step 4: Agent handles all processing and outputs
    return "Agent executing deep analysis and planning..."

Error Handling

Common Issues and Solutions

Input Processing Errors

• Vague text input: Auto-reject without guidance
  • Rejected examples: "optimize system", "refactor code", "make it faster", "improve architecture"
  • Response: Direct rejection message, no further assistance

Agent Execution Errors

• Verify action-planning-agent availability
• Check for context size limits
• Agent handles Gemini CLI failures internally

Gemini CLI Failures (handled by agent)

• Agent falls back to file-pattern based analysis
• Agent retries with reduced scope automatically
• Agent alerts if critical analysis fails

File Access Issues

• Verify permissions for workflow directory
• Check file patterns for validity
• Alert on missing CLAUDE.md files

Integration Points

Related Commands

• /workflow:plan - Quick planning without deep analysis
• /workflow:execute - Execute generated plans
• /workflow:review - Review implementation progress
• /context - View generated planning documents

Agent Dependencies

• action-planning-agent - Core planning engine
• code-developer - For execution phase
• code-review-agent - For quality checks

Usage Examples

Example 1: Cross-Module Refactoring

/workflow:plan-deep "Refactor user authentication to use JWT tokens across all services"

Generates comprehensive plan analyzing:

• Current auth implementation
• All affected services
• Migration strategy
• Testing requirements

Example 2: Performance Optimization

/workflow:plan-deep "Optimize database query performance in reporting module"

Creates detailed plan including:

• Current query patterns analysis
• Bottleneck identification
• Optimization strategies
• Performance testing approach

Example 3: Architecture Enhancement

/workflow:plan-deep "Implement event-driven architecture for order processing"

Produces hierarchical plan with:

• Current architecture assessment
• Event flow design
• Module integration points
• Staged migration approach

Best Practices

1. Use for Complex Tasks: Reserve for tasks requiring deep understanding
2. Provide Clear Descriptions: Specific task descriptions yield better analysis
3. Review Gemini Output: Check analysis results for accuracy
4. Iterate on Plans: Refine based on initial analysis
5. Track Progress: Use generated TODO_LIST.md for execution

Technical Notes

• Agent-Driven Analysis: action-planning-agent executes all Gemini CLI commands
• Parallel Execution: Agent runs 4 Gemini analyses concurrently for performance
• Context Management: Agent handles context size limits automatically
• Structured Handoff: Command passes DEEP_ANALYSIS_REQUIRED flag to agent
• Session Management: Agent creates and manages workflow session
• Output Standards: All documents follow established workflow formats

---

System ensures: Deep technical understanding before planning through mandatory Gemini CLI analysis and intelligent agent orchestration