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

name, description, argument-hint, allowed-tools, timeout, color

name	description	argument-hint	allowed-tools	timeout	color
lite-plan	Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation	[--tool claude|gemini|qwen|codex] [--quick] "task description"|file.md	TodoWrite(*), Task(*), Bash(*), AskUserQuestion(*)	180000	cyan

Workflow Lite-Plan Command (/workflow:lite-plan)

Overview

Intelligent lightweight planning and execution command with dynamic workflow adaptation based on task complexity.

Key Characteristics:

• Dynamic Workflow: Automatically decides whether to use exploration, clarification, and detailed planning
• Smart Exploration: Calls cli-explore-agent only when task requires codebase context
• Interactive Clarification: Asks user for more information after exploration if needed
• Adaptive Planning: Simple tasks get direct planning, complex tasks use cli-planning-agent
• Two-Dimensional Confirmation: User confirms task + selects execution method in one step
• Direct Execution: Immediately starts execution (agent or CLI) after confirmation
• Live Progress Tracking: Uses TodoWrite to track execution progress in real-time

Core Functionality

• Intelligent Task Analysis: Automatically determines if exploration/planning agents are needed
• Dynamic Exploration: Calls cli-explore-agent only when task requires codebase understanding
• Interactive Clarification: Asks follow-up questions after exploration to gather missing information
• Adaptive Planning:
  • Simple tasks: Direct planning by current Claude
  • Complex tasks: Delegates to cli-planning-agent for detailed breakdown
• Two-Dimensional Confirmation: Single user interaction for task approval + execution method selection
• Direct Execution: Immediate dispatch to selected execution method (agent or CLI)
• Live Progress Tracking: Real-time TodoWrite updates during execution

Comparison with Other Commands

Feature	lite-plan	/cli:mode:plan	/workflow:plan
Workflow Adaptation	Dynamic (intelligent)	Fixed	Fixed
Code Exploration	Smart (when needed)	No	Always (context-search)
Clarification	Yes (interactive)	No	No
Planning Strategy	Adaptive (simple/complex)	Fixed template	Agent-based
User Interaction	Two-dimensional	No	Minimal
Direct Execution	Yes (immediate)	Yes (immediate)	No (requires /workflow:execute)
Progress Tracking	Yes (TodoWrite live)	No	Yes (session-based)
Execution Time	Fast (1-3 min)	Fast (2-5 min)	Slow (5-10 min)
Tool Selection	User choice	--tool flag	Fixed (agent only)
File Artifacts	No	No	Yes (IMPL_PLAN.md + JSON)

Usage

Command Syntax

/workflow:lite-plan [FLAGS] <TASK_DESCRIPTION>

# Flags
--tool <tool-name>         Preset CLI tool (claude|gemini|qwen|codex); if not provided, user selects during confirmation
--quick                    Skip code exploration phase (fast mode, completes within 60 seconds)

# Arguments
<task-description>         Task description or path to .md file (required)

Usage Examples

# Standard planning with full interaction
/workflow:lite-plan "Implement user authentication with JWT tokens"
# -> Shows plan, user confirms, selects tool, immediate execution

# Quick mode with preset tool
/workflow:lite-plan --quick --tool gemini "Refactor logging module for better performance"
# -> Skips exploration, user confirms plan, executes with Gemini

# Codex direct execution preset
/workflow:lite-plan --tool codex "Add unit tests for authentication service"
# -> User only confirms plan, executes with Codex immediately

# Agent mode with Claude
/workflow:lite-plan "Design new API endpoints for payment processing"
# -> User selects Claude agent, immediate execution

Execution Process

Workflow Overview

User Input ("/workflow:lite-plan \"task\"")
    |
    v
[Phase 1] Task Analysis & Exploration Decision (10-20 seconds)
    -> Analyze task description
    -> Decision: Need exploration? (Yes/No/--quick override)
    -> If Yes: Launch cli-explore-agent
    -> Output: exploration findings (if performed)
    |
    v
[Phase 2] Clarification (Optional, user interaction)
    -> If exploration revealed ambiguities or missing info
    -> AskUserQuestion: Gather clarifications
    -> Update task context with user responses
    -> If no clarification needed: Skip to Phase 3
    |
    v
[Phase 3] Complexity Assessment & Planning (20-60 seconds)
    -> Assess task complexity (Low/Medium/High)
    -> Decision: Planning strategy
       - Low: Direct planning (current Claude)
       - Medium/High: Delegate to cli-planning-agent
    -> Output: Task breakdown with execution approach
    |
    v
[Phase 4] Task Confirmation & Execution Selection (User interaction)
    -> Display task breakdown and approach
    -> AskUserQuestion: Two dimensions
       1. Confirm task (Yes/Modify/Cancel)
       2. Execution method (Direct/CLI)
    -> If confirmed: Proceed to Phase 5
    -> If modify: Re-run planning with feedback
    -> If cancel: Exit
    |
    v
[Phase 5] Execution & Progress Tracking
    -> Create TodoWrite task list from breakdown
    -> Launch selected execution (agent or CLI)
    -> Track progress with TodoWrite updates
    -> Real-time status displayed to user
    |
    v
Execution Complete

Task Management Pattern

• TodoWrite creates task list before execution starts (Phase 5)
• Tasks marked as in_progress/completed during execution
• Real-time progress updates visible to user
• No intermediate file artifacts generated

Detailed Phase Execution

Phase 1: Task Analysis & Exploration Decision

Operations:

• Analyze task description to determine if code exploration is needed
• Decision logic:

  needsExploration = (
    task.mentions_specific_files ||
    task.requires_codebase_context ||
    task.needs_architecture_understanding ||
    task.modifies_existing_code
  ) && !flags.includes('--quick')
  

Decision Criteria:

Task Type	Needs Exploration	Reason
"Implement new feature X"	Maybe	Depends on integration with existing code
"Refactor module Y"	Yes	Needs understanding of current implementation
"Add tests for Z"	Yes	Needs to understand code structure
"Create new standalone utility"	No	Self-contained, no existing code context
"Update documentation"	No	Doesn't require code exploration
"Fix bug in function F"	Yes	Needs to understand implementation

If Exploration Needed:

• Launch cli-explore-agent with task-specific focus
• Agent call format:

  Task(
    subagent_type="cli-explore-agent",
    description="Analyze codebase for task context",
    prompt=`
    Task: ${task_description}
  
    Analyze and return the following information in structured format:
    1. Project Structure: Overall architecture and module organization
    2. Relevant Files: List of files that will be affected by this task (with paths)
    3. Current Implementation Patterns: Existing code patterns, conventions, and styles
    4. Dependencies: External dependencies and internal module dependencies
    5. Integration Points: Where this task connects with existing code
    6. Architecture Constraints: Technical limitations or requirements
    7. Clarification Needs: Ambiguities or missing information requiring user input
  
    Time Limit: 60 seconds
  
    Output Format: Return a JSON-like structured object with the above fields populated.
    Include specific file paths, pattern examples, and clear questions for clarifications.
    `
  )
  

Expected Return Structure:

explorationContext = {
  project_structure: "Description of overall architecture",
  relevant_files: ["src/auth/service.ts", "src/middleware/auth.ts", ...],
  patterns: "Description of existing patterns (e.g., 'Uses dependency injection pattern', 'React hooks convention')",
  dependencies: "List of dependencies and integration points",
  integration_points: "Where this connects with existing code",
  constraints: "Technical constraints (e.g., 'Must use existing auth library', 'No breaking changes')",
  clarification_needs: [
    {
      question: "Which authentication method to use?",
      context: "Found both JWT and Session patterns",
      options: ["JWT tokens", "Session-based", "Hybrid approach"]
    },
    // ... more clarification questions
  ]
}

Output Processing:

• Store exploration findings in explorationContext
• Extract clarification_needs array from exploration results
• Set needsClarification = (clarification_needs.length > 0)
• Use clarification_needs to generate Phase 2 questions

Progress Tracking:

• Mark Phase 1 as completed
• If needsClarification: Mark Phase 2 as in_progress
• Else: Skip to Phase 3

Expected Duration: 10-20 seconds (analysis) + 30-60 seconds (exploration if needed)

---

Phase 2: Clarification (Optional)

Skip Condition: Only run if Phase 1 set needsClarification = true

Operations:

• Review explorationContext.clarification_needs from Phase 1
• Generate AskUserQuestion based on exploration findings
• Focus on ambiguities that affect implementation approach

AskUserQuestion Call (simplified reference):

// Use clarification_needs from exploration to build questions
AskUserQuestion({
  questions: explorationContext.clarification_needs.map(need => ({
    question: `${need.context}\n\n${need.question}`,
    header: "Clarification",
    multiSelect: false,
    options: need.options.map(opt => ({
      label: opt,
      description: `Use ${opt} approach`
    }))
  }))
})

Output Processing:

• Collect user responses and store in clarificationContext
• Format: { question_id: selected_answer, ... }
• This context will be passed to Phase 3 planning

Progress Tracking:

• Mark Phase 2 as completed
• Mark Phase 3 as in_progress

Expected Duration: User-dependent (typically 30-60 seconds)

---

Phase 3: Complexity Assessment & Planning

Operations:

• Assess task complexity based on multiple factors
• Select appropriate planning strategy
• Generate task breakdown using selected method

Complexity Assessment Factors:

complexityScore = {
  file_count: exploration.files_to_modify.length,
  integration_points: exploration.dependencies.length,
  architecture_changes: exploration.requires_architecture_change,
  technology_stack: exploration.unfamiliar_technologies.length,
  task_scope: (task.estimated_steps > 5),
  cross_cutting_concerns: exploration.affects_multiple_modules
}

// Calculate complexity
if (complexityScore < 3) complexity = "Low"
else if (complexityScore < 6) complexity = "Medium"
else complexity = "High"

Complexity Levels:

Level	Characteristics	Planning Strategy
Low	1-2 files, simple changes, clear requirements	Direct planning (current Claude)
Medium	3-5 files, moderate integration, some ambiguity	Delegate to cli-planning-agent
High	6+ files, complex architecture, high uncertainty	Delegate to cli-planning-agent with detailed analysis

Planning Execution:

Option A: Direct Planning (Low Complexity)

// Current Claude generates plan directly
planObject = {
  summary: "Brief overview of what needs to be done",
  approach: "Step-by-step implementation strategy",
  tasks: [
    "Task 1: Specific action with file references",
    "Task 2: Specific action with file references",
    // ... 3-5 tasks
  ],
  complexity: "Low",
  estimated_time: "15-30 minutes"
}

Option B: Agent-Based Planning (Medium/High Complexity)

// Delegate to cli-planning-agent
Task(
  subagent_type="cli-planning-agent",
  description="Generate detailed implementation plan",
  prompt=`
  Task: ${task_description}

  Exploration Context:
  ${JSON.stringify(explorationContext, null, 2)}

  User Clarifications:
  ${JSON.stringify(clarificationContext, null, 2) || "None provided"}

  Complexity Level: ${complexity}

  Generate a detailed implementation plan with the following components:

  1. Summary: 2-3 sentence overview of the implementation
  2. Approach: High-level implementation strategy
  3. Task Breakdown: 5-10 specific, actionable tasks
     - Each task should specify:
       * What to do
       * Which files to modify/create
       * Dependencies on other tasks (if any)
  4. Task Dependencies: Explicit ordering requirements (e.g., "Task 2 depends on Task 1")
  5. Risks: Potential issues and mitigation strategies (for Medium/High complexity)
  6. Estimated Time: Total implementation time estimate
  7. Recommended Execution: "Direct" (agent) or "CLI" (autonomous tool)

  Output Format: Return a structured object with these fields:
  {
    summary: string,
    approach: string,
    tasks: string[],
    dependencies: string[] (optional),
    risks: string[] (optional),
    estimated_time: string,
    recommended_execution: "Direct" | "CLI"
  }

  Ensure tasks are specific, with file paths and clear acceptance criteria.
  `
)

// Agent returns detailed plan
planObject = agent_output.parse()

Expected Return Structure:

planObject = {
  summary: "Implement JWT-based authentication system with middleware integration",
  approach: "Create auth service layer, implement JWT utilities, add middleware, update routes",
  tasks: [
    "Create authentication service in src/auth/service.ts with login/logout/verify methods",
    "Implement JWT token utilities in src/auth/jwt.ts (generate, verify, refresh)",
    "Add authentication middleware to src/middleware/auth.ts",
    "Update API routes in src/routes/*.ts to use auth middleware",
    "Add integration tests for auth flow in tests/auth.test.ts"
  ],
  dependencies: [
    "Task 3 depends on Task 2 (middleware needs JWT utilities)",
    "Task 4 depends on Task 3 (routes need middleware)",
    "Task 5 depends on Tasks 1-4 (tests need complete implementation)"
  ],
  risks: [
    "Token refresh timing may conflict with existing session logic - test thoroughly",
    "Breaking change if existing auth is in use - plan migration strategy"
  ],
  estimated_time: "30-45 minutes",
  recommended_execution: "CLI"  // Based on clear requirements and straightforward implementation
}

Output Structure:

planObject = {
  summary: "2-3 sentence overview",
  approach: "Implementation strategy",
  tasks: [
    "Task 1: ...",
    "Task 2: ...",
    // ... 3-10 tasks based on complexity
  ],
  complexity: "Low|Medium|High",
  dependencies: ["task1 -> task2", ...],  // if Medium/High
  risks: ["risk1", "risk2", ...],         // if High
  estimated_time: "X minutes",
  recommended_execution: "Direct|CLI"
}

Progress Tracking:

• Mark Phase 3 as completed
• Mark Phase 4 as in_progress

Expected Duration:

• Low complexity: 20-30 seconds (direct)
• Medium/High complexity: 40-60 seconds (agent-based)

---

Phase 4: Task Confirmation & Execution Selection

User Interaction Flow: Two-dimensional confirmation (task + execution method)

Operations:

• Display plan summary with full task breakdown
• Collect two-dimensional user input: Task confirmation + Execution method selection
• Support modification flow if user requests changes

Question 1: Task Confirmation

Display plan to user and ask for confirmation:

• Show: summary, approach, task breakdown, dependencies, risks, complexity, estimated time
• Options: "Confirm" / "Modify" / "Cancel"
• If Modify: Collect feedback via "Other" option, re-run Phase 3 with modifications
• If Cancel: Exit workflow
• If Confirm: Proceed to Question 2

Question 2: Execution Method Selection (Only if task confirmed)

Ask user to select execution method:

• Show recommendation from planObject.recommended_execution
• Options:
  • "Direct - Execute with Agent" (@code-developer)
  • "CLI - Gemini" (gemini-2.5-pro)
  • "CLI - Codex" (gpt-5)
  • "CLI - Qwen" (coder-model)
• Store selection for Phase 5 execution

Simplified AskUserQuestion Reference:

// Question 1: Task Confirmation
AskUserQuestion({
  questions: [{
    question: `[Display plan with all details]\n\nDo you confirm this plan?`,
    header: "Confirm Plan",
    options: [
      { label: "Confirm", description: "Proceed to execution" },
      { label: "Modify", description: "Adjust plan" },
      { label: "Cancel", description: "Abort" }
    ]
  }]
})

// Question 2: Execution Method (if confirmed)
AskUserQuestion({
  questions: [{
    question: `Select execution method:\n[Show recommendation and tool descriptions]`,
    header: "Execution Method",
    options: [
      { label: "Direct - Agent", description: "Interactive execution" },
      { label: "CLI - Gemini", description: "gemini-2.5-pro" },
      { label: "CLI - Codex", description: "gpt-5" },
      { label: "CLI - Qwen", description: "coder-model" }
    ]
  }]
})

Decision Flow:

Task Confirmation:
  ├─ Confirm → Execution Method Selection → Phase 5
  ├─ Modify → Collect feedback → Re-run Phase 3
  └─ Cancel → Exit (no execution)

Execution Method Selection:
  ├─ Direct - Execute with Agent → Launch @code-developer
  ├─ CLI - Gemini → Build and execute Gemini command
  ├─ CLI - Codex → Build and execute Codex command
  └─ CLI - Qwen → Build and execute Qwen command

Progress Tracking:

• Mark Phase 4 as completed
• Mark Phase 5 as in_progress

Expected Duration: User-dependent (1-3 minutes typical)

---

Phase 5: Execution & Progress Tracking

Operations:

• Create TodoWrite task list from plan breakdown
• Launch selected execution method (agent or CLI)
• Track execution progress with real-time TodoWrite updates
• Display status to user

Step 5.1: Create TodoWrite Task List

Before execution starts, create task list:

TodoWrite({
  todos: planObject.tasks.map((task, index) => ({
    content: task,
    status: "pending",
    activeForm: task.replace(/^(.*?):/, "$1ing:")  // "Implement X" -> "Implementing X"
  }))
})

Example Task List:

[ ] Implement authentication service in src/auth/service.ts
[ ] Create JWT token utilities in src/auth/jwt.ts
[ ] Add authentication middleware to src/middleware/auth.ts
[ ] Update API routes to use authentication
[ ] Add integration tests for auth flow

Step 5.2: Launch Execution

Based on user selection in Phase 4, execute appropriate method:

Option A: Direct Execution with Agent

Operations:

• Launch @code-developer agent with full plan context
• Agent receives exploration findings, clarifications, and task breakdown
• Agent call format:

  Task(
    subagent_type="code-developer",
    description="Implement planned tasks with progress tracking",
    prompt=`
    Implement the following tasks with TodoWrite progress updates:
  
    Summary: ${planObject.summary}
  
    Task Breakdown:
    ${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
  
    ${planObject.dependencies ? `\nTask Dependencies:\n${planObject.dependencies.join('\n')}` : ''}
  
    Implementation Approach:
    ${planObject.approach}
  
    Code Context:
    ${explorationContext || "No exploration performed"}
  
    ${clarificationContext ? `\nClarifications:\n${clarificationContext}` : ''}
  
    ${planObject.risks ? `\nRisks to Consider:\n${planObject.risks.join('\n')}` : ''}
  
    IMPORTANT Instructions:
    - Update TodoWrite as you complete each task (mark as completed)
    - Follow task dependencies if specified
    - Implement tasks in sequence unless independent
    - Test functionality as you go
    - Handle risks proactively
    `
  )
  

Agent Responsibilities:

• Mark tasks as in_progress when starting
• Mark tasks as completed when finished
• Update TodoWrite in real-time for user visibility

Option B: CLI Execution (Gemini/Codex/Qwen)

Operations:

• Build CLI command with comprehensive context
• Execute CLI tool with write permissions
• Monitor CLI output and update TodoWrite based on progress indicators
• Parse CLI completion signals to mark tasks as done

Command Format (Gemini) - Full context with exploration and clarifications:

gemini -p "
PURPOSE: Implement planned tasks with full context from exploration and planning
TASK:
${planObject.tasks.map((t, i) => `• ${t}`).join('\n')}

MODE: write

CONTEXT: @**/* | Memory: Implementation plan from lite-plan workflow

## Exploration Findings
${explorationContext ? `
Project Structure:
${explorationContext.project_structure || 'Not available'}

Relevant Files:
${explorationContext.relevant_files?.join('\n') || 'Not specified'}

Current Implementation Patterns:
${explorationContext.patterns || 'Not analyzed'}

Dependencies and Integration Points:
${explorationContext.dependencies || 'Not specified'}

Architecture Constraints:
${explorationContext.constraints || 'None identified'}
` : 'No exploration performed (task did not require codebase context)'}

## User Clarifications
${clarificationContext ? `
The following clarifications were provided by the user after exploration:
${Object.entries(clarificationContext).map(([q, a]) => `Q: ${q}\nA: ${a}`).join('\n\n')}
` : 'No clarifications needed'}

## Implementation Plan Context
Task Summary: ${planObject.summary}

Implementation Approach:
${planObject.approach}

${planObject.dependencies ? `
Task Dependencies (execute in order):
${planObject.dependencies.join('\n')}
` : ''}

${planObject.risks ? `
Identified Risks:
${planObject.risks.join('\n')}
` : ''}

Complexity Level: ${planObject.complexity}
Estimated Time: ${planObject.estimated_time}

EXPECTED: All tasks implemented following the plan approach, with proper error handling and testing

RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow implementation approach exactly | Handle identified risks proactively | write=CREATE/MODIFY/DELETE
" -m gemini-2.5-pro --approval-mode yolo

Command Format (Codex) - Session-based with resume support:

First Execution (Establish Session):

codex --full-auto exec "
TASK: ${planObject.summary}

## Task Breakdown
${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}

${planObject.dependencies ? `\n## Task Dependencies\n${planObject.dependencies.join('\n')}` : ''}

## Implementation Approach
${planObject.approach}

## Code Context from Exploration
${explorationContext ? `
Project Structure: ${explorationContext.project_structure || 'Standard structure'}
Relevant Files: ${explorationContext.relevant_files?.join(', ') || 'TBD'}
Current Patterns: ${explorationContext.patterns || 'Follow existing conventions'}
Integration Points: ${explorationContext.dependencies || 'None specified'}
Constraints: ${explorationContext.constraints || 'None'}
` : 'No prior exploration - analyze codebase as needed'}

${clarificationContext ? `\n## User Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `${q}: ${a}`).join('\n')}` : ''}

${planObject.risks ? `\n## Risks to Handle\n${planObject.risks.join('\n')}` : ''}

## Execution Instructions
- Complete all tasks following the breakdown sequence
- Respect task dependencies if specified
- Test functionality as you implement
- Handle identified risks proactively
- Create session for potential resume if needed

Complexity: ${planObject.complexity}
" -m gpt-5 --skip-git-repo-check -s danger-full-access

Subsequent Executions (Resume if needed):

# If first execution fails or is interrupted, can resume:
codex --full-auto exec "
Continue implementation from previous session.

Remaining tasks:
${remaining_tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}

Maintain context from previous execution.
" resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access

Codex Session Strategy:

• First execution establishes full context and creates session
• If execution is interrupted or fails, use resume --last to continue
• Resume inherits all context from original execution
• Useful for complex tasks that may hit timeouts or require iteration

Command Format (Qwen) - Full context similar to Gemini:

qwen -p "
PURPOSE: Implement planned tasks with comprehensive context

TASK:
${planObject.tasks.map((t, i) => `• ${t}`).join('\n')}

MODE: write

CONTEXT: @**/* | Memory: Full implementation context from lite-plan

## Code Exploration Results
${explorationContext ? `
Analyzed Project Structure:
${explorationContext.project_structure || 'Standard structure'}

Key Files to Modify:
${explorationContext.relevant_files?.join('\n') || 'To be determined during implementation'}

Existing Code Patterns:
${explorationContext.patterns || 'Follow codebase conventions'}

Dependencies:
${explorationContext.dependencies || 'None specified'}

Constraints:
${explorationContext.constraints || 'None identified'}
` : 'No exploration performed - analyze codebase patterns as you implement'}

## Clarifications from User
${clarificationContext ? `
${Object.entries(clarificationContext).map(([question, answer]) => `
Question: ${question}
Answer: ${answer}
`).join('\n')}
` : 'No additional clarifications provided'}

## Implementation Strategy
Summary: ${planObject.summary}

Approach:
${planObject.approach}

${planObject.dependencies ? `
Task Order (follow sequence):
${planObject.dependencies.join('\n')}
` : ''}

${planObject.risks ? `
Risk Mitigation:
${planObject.risks.join('\n')}
` : ''}

Task Complexity: ${planObject.complexity}
Time Estimate: ${planObject.estimated_time}

EXPECTED: Complete implementation with tests and proper error handling

RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow approach strictly | Test thoroughly | write=CREATE/MODIFY/DELETE
" -m coder-model --approval-mode yolo

Execution with Progress Tracking:

// Launch CLI in background
bash_result = Bash(
  command=cli_command,
  timeout=600000,  // 10 minutes
  run_in_background=true
)

// Monitor output and update TodoWrite
// Parse CLI output for task completion indicators
// Update TodoWrite when tasks complete
// Example: When CLI outputs "✓ Task 1 complete" -> Mark task 1 as completed

CLI Progress Monitoring:

• Parse CLI output for completion keywords ("done", "complete", "✓", etc.)
• Update corresponding TodoWrite tasks based on progress
• Provide real-time visibility to user

Step 5.3: Track Execution Progress

Real-time TodoWrite Updates:

// As execution progresses, update task status:

// Task started
TodoWrite({
  todos: [
    { content: "Implement auth service", status: "in_progress", activeForm: "Implementing auth service" },
    { content: "Create JWT utilities", status: "pending", activeForm: "Creating JWT utilities" },
    // ...
  ]
})

// Task completed
TodoWrite({
  todos: [
    { content: "Implement auth service", status: "completed", activeForm: "Implementing auth service" },
    { content: "Create JWT utilities", status: "in_progress", activeForm: "Creating JWT utilities" },
    // ...
  ]
})

User Visibility:

• User sees real-time task progress
• Current task highlighted as "in_progress"
• Completed tasks marked with checkmark
• Pending tasks remain unchecked

Progress Tracking:

• Mark Phase 5 as in_progress throughout execution
• Mark Phase 5 as completed when all tasks done
• Final status summary displayed to user

Expected Duration: Varies by task complexity and execution method

• Low complexity: 5-15 minutes
• Medium complexity: 15-45 minutes
• High complexity: 45-120 minutes

---

Best Practices

Workflow Intelligence

1. Dynamic Adaptation: Workflow automatically adjusts based on task characteristics

   • Smart exploration: Only runs when task requires codebase context
   • Adaptive planning: Simple tasks get direct planning, complex tasks use specialized agent
   • Context-aware clarification: Only asks questions when truly needed
   • Reduces unnecessary steps while maintaining thoroughness

2. Progressive Clarification: Gather information at the right time

   • Phase 1: Explore codebase to understand current state
   • Phase 2: Ask clarifying questions based on exploration findings
   • Phase 3: Plan with complete context (task + exploration + clarifications)
   • Avoids premature assumptions and reduces rework

3. Complexity-Aware Planning: Planning strategy matches task complexity

   • Low complexity (1-2 files): Direct planning by current Claude (fast, 20-30s)
   • Medium complexity (3-5 files): CLI planning agent (detailed, 40-50s)
   • High complexity (6+ files): CLI planning agent with risk analysis (thorough, 50-60s)
   • Balances speed and thoroughness appropriately

4. Two-Dimensional Confirmation: Separate task approval from execution method

   • First dimension: Confirm/Modify/Cancel plan
   • Second dimension: Direct execution vs CLI execution
   • Allows plan refinement without re-selecting execution method
   • Supports iterative planning with user feedback

Task Management

1. Live Progress Tracking: TodoWrite provides real-time execution visibility

   • Tasks created before execution starts
   • Updated in real-time as work progresses
   • User sees current task being worked on
   • Clear completion status throughout execution

2. Phase-Based Organization: 5 distinct phases with clear transitions

   • Phase 1: Task Analysis & Exploration (automatic)
   • Phase 2: Clarification (conditional, interactive)
   • Phase 3: Planning (automatic, adaptive)
   • Phase 4: Confirmation (interactive, two-dimensional)
   • Phase 5: Execution & Tracking (automatic with live updates)

3. Flexible Task Counts: Task breakdown adapts to complexity

   • Low complexity: 3-5 tasks (focused)
   • Medium complexity: 5-7 tasks (detailed)
   • High complexity: 7-10 tasks (comprehensive)
   • Avoids artificial constraints while maintaining focus

4. Dependency Tracking: Medium/High complexity tasks include dependencies

   • Explicit task ordering when sequence matters
   • Parallel execution hints when tasks are independent
   • Risk flagging for complex interactions
   • Helps agent/CLI execute correctly

Planning Standards

1. Context-Rich Planning: Plans include all relevant context

   • Exploration findings (code structure, patterns, constraints)
   • User clarifications (requirements, preferences, decisions)
   • Complexity assessment (risks, dependencies, time estimates)
   • Execution recommendations (Direct vs CLI, specific tool)

2. Modification Support: Plans can be iteratively refined

   • User can request plan modifications in Phase 4
   • Feedback incorporated into re-planning
   • No need to restart from scratch
   • Supports collaborative planning workflow

3. No File Artifacts: All planning stays in memory

   • Faster workflow without I/O overhead
   • Cleaner workspace
   • Plan context passed directly to execution
   • Reduces complexity and maintenance

Error Handling

Common Errors

Error	Cause	Resolution
Phase 1 Exploration Failure	cli-explore-agent unavailable or timeout	Skip exploration, set explorationContext = null, log warning, continue to Phase 2/3 with task description only
Phase 2 Clarification Timeout	User no response > 5 minutes	Use exploration findings as-is without clarification, proceed to Phase 3 with warning
Phase 3 Planning Agent Failure	cli-planning-agent unavailable or timeout	Fallback to direct planning by current Claude (simplified plan), continue to Phase 4
Phase 3 Planning Timeout	Planning takes > 90 seconds	Generate simplified direct plan, mark as "Quick Plan", continue to Phase 4 with reduced detail
Phase 4 Confirmation Timeout	User no response > 5 minutes	Save plan context to temporary var, display resume instructions, exit gracefully
Phase 4 Modification Loop	User requests modify > 3 times	Suggest breaking task into smaller pieces or using /workflow:plan for comprehensive planning
Phase 5 CLI Tool Unavailable	Selected CLI tool not installed	Show installation instructions, offer to re-select (Direct execution or different CLI)
Phase 5 Execution Failure	Agent/CLI crashes or errors	Display error details, save partial progress from TodoWrite, suggest manual recovery or retry

Input/Output

Input Requirements

• Task description: String or path to .md file (required)
  • Should be specific and concrete
  • Can include context about existing code or requirements
  • Examples:
    • "Implement user authentication with JWT tokens"
    • "Refactor logging module for better performance"
    • "Add unit tests for authentication service"
• Flags (optional):
  • --tool <name>: Preset execution tool (claude|gemini|codex|qwen)
  • --quick: Skip code exploration phase

Output Format

In-Memory Plan Object:

{
  summary: "2-3 sentence overview of implementation",
  approach: "High-level implementation strategy",
  tasks: [
    "Task 1: Specific action with file locations",
    "Task 2: Specific action with file locations",
    // ... 3-7 tasks total
  ],
  complexity: "Low|Medium|High",
  recommended_tool: "Claude|Gemini|Codex|Qwen",
  estimated_time: "X minutes"
}

Execution Result:

• Immediate dispatch to selected tool/agent with plan context
• No file artifacts generated during planning phase
• Execution starts immediately after user confirmation
• Tool/agent handles implementation and any necessary file operations