claude-code-system-prompts/architecture/5-plan-mode-flow.md

Plan Mode Flow

This diagram shows the planning subsystem—how Claude Code enters, operates in, and exits plan mode.

stateDiagram-v2
    [*] --> NormalMode: Session Start
    
    NormalMode --> PlanMode: Shift+Tab OR<br/>EnterPlanMode tool
    
    state PlanMode {
        direction TB
        [*] --> Exploring
        Exploring --> Designing: Understanding complete
        Designing --> ProposingPlan: Design ready
        
        state Exploring {
            direction LR
            ReadFiles: Read relevant files
            SearchCode: Search codebase
            AnalyzeArch: Analyze architecture
        }
        
        state Designing {
            direction LR
            IdentifyPatterns: Identify patterns
            ConsiderTradeoffs: Consider trade-offs
            PlanSteps: Plan implementation steps
        }
    }
    
    PlanMode --> ExitDecision: ExitPlanMode tool
    
    state ExitDecision <<choice>>
    ExitDecision --> Implementation: User approves
    ExitDecision --> PlanMode: User requests changes
    
    Implementation --> NormalMode: Work complete
    NormalMode --> PlanMode: Re-enter (Shift+Tab)
    
    NormalMode --> [*]: Session End

Plan Mode Entry Points

flowchart LR
    subgraph Triggers["Entry Triggers"]
        Keyboard["⌨️ Shift+Tab"]
        Tool["🔧 EnterPlanMode tool"]
        Complex["🤔 Complex task detected"]
    end
    
    subgraph Entry["Plan Mode Activation"]
        Enter["EnterPlanMode"]
        Reminder["Plan Mode Reminder<br/>injected into context"]
    end
    
    Triggers --> Entry
    
    click Enter href "../system-prompts/tool-description-enterplanmode.md" "EnterPlanMode"
    click Reminder href "../system-prompts/system-reminder-plan-mode-is-active.md" "Plan Mode Reminder"

Key Prompts:

• EnterPlanMode Tool - Tool description for entering plan mode
• Plan Mode Active Reminder - System reminder injected when plan mode is active

Plan Mode Operation

While in plan mode, Claude Code operates in read-only mode with specific capabilities:

flowchart TB
    subgraph Capabilities["✅ Allowed in Plan Mode"]
        Read["Read files"]
        Search["Search codebase"]
        Analyze["Analyze patterns"]
        Design["Design solutions"]
        Parallel["Spawn parallel<br/>exploration agents"]
    end
    
    subgraph Restricted["❌ Restricted in Plan Mode"]
        Write["Write files"]
        Edit["Edit files"]
        Execute["Execute commands<br/>(except read-only)"]
        Create["Create anything"]
    end
    
    PlanAgent["Plan Mode Agent"]
    PlanAgent --> Capabilities
    PlanAgent -.->|blocked| Restricted
    
    click PlanAgent href "../system-prompts/agent-prompt-plan-mode-enhanced.md" "Plan Mode Agent"

Key Prompts:

• Plan Mode Agent - Enhanced planning prompt
• Plan Mode for Subagents - Simplified reminder for spawned sub-agents

Plan Mode Exit

flowchart TB
    PlanReady["Plan Ready"]
    Exit["ExitPlanMode Tool"]
    
    subgraph Dialog["Plan Approval Dialog"]
        Present["Present plan to user"]
        UserChoice{{"User Decision"}}
        Approve["✅ Approve"]
        Modify["✏️ Request changes"]
        Reject["❌ Reject"]
    end
    
    PlanReady --> Exit
    Exit --> Present
    Present --> UserChoice
    UserChoice --> Approve
    UserChoice --> Modify
    UserChoice --> Reject
    
    Approve --> Implement["Begin Implementation"]
    Modify --> Continue["Continue Planning"]
    Reject --> Normal["Return to Normal Mode"]
    
    click Exit href "../system-prompts/tool-description-exitplanmode.md" "ExitPlanMode"

Key Prompts:

• ExitPlanMode Tool - Standard exit tool
• ExitPlanMode v2 - Enhanced plan dialog

Re-entry Flow

Users can re-enter plan mode after exiting:

flowchart LR
    Normal["Normal Mode<br/>(implementing)"]
    ReEnter["Shift+Tab"]
    PlanAgain["Plan Mode<br/>(re-entered)"]
    Reminder["Re-entry Reminder"]
    
    Normal --> ReEnter
    ReEnter --> PlanAgain
    PlanAgain --> Reminder
    
    click Reminder href "../system-prompts/system-reminder-plan-mode-re-entry.md" "Re-entry Reminder"

Key Prompt:

• Plan Mode Re-entry - Reminder when re-entering plan mode after implementation

All Plan Mode Prompts

Prompt	Purpose	File
EnterPlanMode	Tool to enter plan mode	tool-description-enterplanmode.md
ExitPlanMode	Tool to exit with plan	tool-description-exitplanmode.md
ExitPlanMode v2	Enhanced exit dialog	tool-description-exitplanmode-v2.md
Plan Mode Agent	Agent behavior in plan mode	agent-prompt-plan-mode-enhanced.md
Active Reminder	Injected while plan mode active	system-reminder-plan-mode-is-active.md
Subagent Reminder	Simplified reminder for sub-agents	system-reminder-plan-mode-is-active-for-subagents.md
Re-entry Reminder	When re-entering after exit	system-reminder-plan-mode-re-entry.md