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

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
lite-plan	Lightweight interactive planning workflow with in-memory planning, code exploration, and execution dispatch to lite-execute after user confirmation	[-e|--explore] "task description"|file.md	TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*)

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

Overview

Intelligent lightweight planning command with dynamic workflow adaptation based on task complexity. Focuses on planning phases (exploration, clarification, planning, confirmation) and delegates execution to /workflow:lite-execute.

Core capabilities:

• Intelligent task analysis with automatic exploration detection
• Dynamic code exploration (cli-explore-agent) when codebase understanding needed
• Interactive clarification after exploration to gather missing information
• Adaptive planning strategy (direct Claude vs cli-lite-planning-agent) based on complexity
• Two-step confirmation: plan display → multi-dimensional input collection
• Execution dispatch with complete context handoff to lite-execute

Usage

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

# Flags
-e, --explore              Force code exploration phase (overrides auto-detection)

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

Execution Process

User Input → Task Analysis & Exploration Decision (Phase 1)
          ↓
     Clarification (Phase 2, optional)
          ↓
     Complexity Assessment & Planning (Phase 3)
          ↓
     Task Confirmation & Execution Selection (Phase 4)
          ↓
     Dispatch to Execution (Phase 5)

Implementation

Phase 1: Intelligent Multi-Angle Exploration

Session Setup:

const taskSlug = task_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
const shortTimestamp = timestamp.substring(0, 19).replace('T', '-')
const sessionId = `${taskSlug}-${shortTimestamp}`
const sessionFolder = `.workflow/.lite-plan/${sessionId}`

bash(`mkdir -p ${sessionFolder}`)

Exploration Decision Logic:

needsExploration = (
  flags.includes('--explore') || flags.includes('-e') ||
  task.mentions_specific_files ||
  task.requires_codebase_context ||
  task.needs_architecture_understanding ||
  task.modifies_existing_code
)

if (!needsExploration) {
  // Skip to Phase 2 (Clarification) or Phase 3 (Planning)
  proceed_to_next_phase()
}

Complexity Assessment & Exploration Count:

// Estimate task complexity based on description
function estimateComplexity(taskDescription) {
  const wordCount = taskDescription.split(/\s+/).length
  const text = taskDescription.toLowerCase()

  const indicators = {
    high: ['refactor', 'migrate', 'redesign', 'architecture', 'system'],
    medium: ['implement', 'add feature', 'integrate', 'modify module'],
    low: ['fix', 'update', 'adjust', 'tweak']
  }

  let score = 0
  if (wordCount > 50) score += 2
  else if (wordCount > 20) score += 1

  if (indicators.high.some(w => text.includes(w))) score += 3
  else if (indicators.medium.some(w => text.includes(w))) score += 2
  else if (indicators.low.some(w => text.includes(w))) score += 1

  // 0-2: Low, 3-4: Medium, 5+: High
  if (score >= 5) return 'High'
  if (score >= 3) return 'Medium'
  return 'Low'
}

const complexity = estimateComplexity(task_description)
const explorationCount = complexity === 'High' ? 4 : (complexity === 'Medium' ? 3 : 1)

console.log(`
## Exploration Plan

Task Complexity: ${complexity}
Exploration Count: ${explorationCount} angle(s)

Starting intelligent multi-angle exploration...
`)

Launch Parallel Explorations - Each agent chooses its own angle:

// Launch multiple cli-explore-agent tasks in parallel
const explorationTasks = []

for (let i = 1; i <= explorationCount; i++) {
  explorationTasks.push(
    Task(
      subagent_type="cli-explore-agent",
      description=`Explore angle ${i}/${explorationCount}`,
      prompt=`
**以解决任务为目标的智能探索** - 从不同角度分析代码库，为任务规划提供上下文。

## Output Schema Reference
~/.claude/workflows/cli-templates/schemas/explore-json-schema.json

## Task Description
${task_description}

## Your Mission
You are exploration ${i} of ${explorationCount} parallel explorations.

**Choose ONE unique angle** most relevant to solving this task:
- Choose different angles from what other explorations might cover
- Focus on aspects critical for task success
- Examples: architecture, security, dataflow, patterns, performance, dependencies, testing, error-handling, state-management, etc.
- Be creative and task-driven - not limited to examples above

## Output File Naming
Choose a descriptive angle name (lowercase, no spaces, hyphen-separated if needed)
Examples: "architecture", "security", "dataflow", "auth-patterns", "error-handling"

Generate file: exploration-{your-chosen-angle}.json

Example angles based on task type:
- Architecture refactoring → "architecture", "modularity", "dependencies"
- Security feature → "security", "auth-patterns", "dataflow"
- Performance fix → "performance", "bottlenecks", "caching"
- Bug fix → "error-handling", "dataflow", "state-management"

## Requirements
Generate exploration-{angle}.json with:
- project_structure: Architecture and module organization relevant to your angle
- relevant_files: File paths to be affected
- patterns: Code patterns relevant to your angle
- dependencies: Dependencies relevant to your angle
- integration_points: Integration points from your angle's viewpoint
- constraints: Constraints related to your angle
- clarification_needs: Ambiguities requiring user input
- _metadata:
  - timestamp: ISO 8601 timestamp
  - task_description: Original task description
  - source: "cli-explore-agent"
  - exploration_angle: "your-chosen-angle"
  - exploration_index: ${i}
  - total_explorations: ${explorationCount}

## Execution Steps
1. Decide your unique exploration angle based on task needs
2. Structural scan: get_modules_by_depth.sh, find, rg (focused on your angle)
3. Semantic analysis: Use Gemini for patterns/architecture specific to your angle
4. Write JSON: Write('${sessionFolder}/exploration-{your-angle}.json', jsonContent)
5. Return: Brief summary stating your chosen angle and key findings

Time Limit: 60 seconds

**Remember**: Choose a unique, task-relevant angle. Don't duplicate other explorations' focus.
`
    )
  )
}

// Execute all exploration tasks in parallel (single message, multiple tool calls)
console.log(`Launching ${explorationCount} parallel explorations...`)

Auto-discover Generated Exploration Files:

// After explorations complete, auto-discover all exploration-*.json files
const explorationFiles = bash(`find ${sessionFolder} -name "exploration-*.json" -type f`)
  .split('\n')
  .filter(f => f.trim())

// Read metadata to build manifest
const explorationManifest = {
  session_id: sessionId,
  task_description: task_description,
  timestamp: new Date().toISOString(),
  complexity: complexity,
  exploration_count: explorationCount,
  explorations: explorationFiles.map(file => {
    const data = JSON.parse(Read(file))
    const filename = path.basename(file)
    return {
      angle: data._metadata.exploration_angle,
      file: filename,
      path: file,
      index: data._metadata.exploration_index
    }
  })
}

Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify(explorationManifest, null, 2))

console.log(`
## Exploration Complete

Generated exploration files in ${sessionFolder}:
${explorationManifest.explorations.map(e => `- exploration-${e.angle}.json (angle: ${e.angle})`).join('\n')}

Manifest: explorations-manifest.json
Angles explored: ${explorationManifest.explorations.map(e => e.angle).join(', ')}
`)

Output:

• ${sessionFolder}/exploration-{angle1}.json
• ${sessionFolder}/exploration-{angle2}.json
• ... (1-4 files based on complexity)
• ${sessionFolder}/explorations-manifest.json

---

Phase 2: Clarification (Optional)

Skip if: No exploration or clarification_needs is empty across all explorations

Aggregate clarification needs from all exploration angles:

// Load manifest and all exploration files
const manifest = JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`))
const explorations = manifest.explorations.map(exp => ({
  angle: exp.angle,
  data: JSON.parse(Read(exp.path))
}))

// Aggregate clarification needs from all explorations
const allClarifications = []
explorations.forEach(exp => {
  if (exp.data.clarification_needs?.length > 0) {
    exp.data.clarification_needs.forEach(need => {
      allClarifications.push({
        ...need,
        source_angle: exp.angle
      })
    })
  }
})

// Deduplicate by question similarity
function deduplicateClarifications(clarifications) {
  const unique = []
  clarifications.forEach(c => {
    const isDuplicate = unique.some(u =>
      u.question.toLowerCase() === c.question.toLowerCase()
    )
    if (!isDuplicate) unique.push(c)
  })
  return unique
}

const uniqueClarifications = deduplicateClarifications(allClarifications)

if (uniqueClarifications.length > 0) {
  AskUserQuestion({
    questions: uniqueClarifications.map(need => ({
      question: `[${need.source_angle}] ${need.question}\n\nContext: ${need.context}`,
      header: need.source_angle,
      multiSelect: false,
      options: need.options.map(opt => ({
        label: opt,
        description: `Use ${opt} approach`
      }))
    }))
  })
}

Output: clarificationContext (in-memory)

---

Phase 3: Complexity Assessment & Planning

Complexity Assessment:

complexityScore = {
  file_count: exploration?.relevant_files?.length || 0,
  integration_points: exploration?.dependencies?.length || 0,
  architecture_changes: exploration?.constraints?.includes('architecture'),
  task_scope: estimated_steps > 5
}

// Low: score < 3, Medium: 3-5, High: > 5

Low Complexity - Direct planning by Claude:

• Generate plan directly, write to ${sessionFolder}/plan.json
• No agent invocation

Medium/High Complexity - Invoke cli-lite-planning-agent:

Task(
  subagent_type="cli-lite-planning-agent",
  description="Generate detailed implementation plan",
  prompt=`
Generate implementation plan and write plan.json.

## Output Schema Reference
~/.claude/workflows/cli-templates/schemas/plan-json-schema.json

## Task Description
${task_description}

## Multi-Angle Exploration Context

${manifest.explorations.map(exp => `### Exploration: ${exp.angle} (${exp.file})
Path: ${exp.path}

Read this file for detailed ${exp.angle} analysis.`).join('\n\n')}

Total explorations: ${manifest.exploration_count}
Angles covered: ${manifest.explorations.map(e => e.angle).join(', ')}

Manifest: ${sessionFolder}/explorations-manifest.json

## User Clarifications
${JSON.stringify(clarificationContext) || "None"}

## Complexity Level
${complexity}

## Requirements
Generate plan.json with:
- summary: 2-3 sentence overview
- approach: High-level implementation strategy (incorporating insights from all exploration angles)
- tasks: 3-10 structured tasks with:
  - title, file, action, description
  - implementation (3-7 steps)
  - reference (pattern, files, examples)
  - acceptance (2-4 criteria)
- estimated_time, recommended_execution, complexity
- _metadata:
  - timestamp, source, planning_mode
  - exploration_angles: ${JSON.stringify(manifest.explorations.map(e => e.angle))}

## Execution
1. Read ALL exploration files for comprehensive context
2. Execute CLI planning using Gemini (Qwen fallback)
3. Synthesize findings from multiple exploration angles
4. Parse output and structure plan
5. Write JSON: Write('${sessionFolder}/plan.json', jsonContent)
4. Return brief completion summary
`
)

Output: ${sessionFolder}/plan.json

---

Phase 4: Task Confirmation & Execution Selection

Step 4.1: Display Plan

const plan = JSON.parse(Read(`${sessionFolder}/plan.json`))

console.log(`
## Implementation Plan

**Summary**: ${plan.summary}
**Approach**: ${plan.approach}

**Tasks** (${plan.tasks.length}):
${plan.tasks.map((t, i) => `${i+1}. ${t.title} (${t.file})`).join('\n')}

**Complexity**: ${plan.complexity}
**Estimated Time**: ${plan.estimated_time}
**Recommended**: ${plan.recommended_execution}
`)

Step 4.2: Collect Confirmation

AskUserQuestion({
  questions: [
    {
      question: `Confirm plan? (${plan.tasks.length} tasks, ${plan.complexity})`,
      header: "Confirm",
      multiSelect: true,
      options: [
        { label: "Allow", description: "Proceed as-is" },
        { label: "Modify", description: "Adjust before execution" },
        { label: "Cancel", description: "Abort workflow" }
      ]
    },
    {
      question: "Execution method:",
      header: "Execution",
      multiSelect: false,
      options: [
        { label: "Agent", description: "@code-developer agent" },
        { label: "Codex", description: "codex CLI tool" },
        { label: "Auto", description: `Auto: ${plan.complexity === 'Low' ? 'Agent' : 'Codex'}` }
      ]
    },
    {
      question: "Code review after execution?",
      header: "Review",
      multiSelect: false,
      options: [
        { label: "Gemini Review", description: "Gemini CLI" },
        { label: "Agent Review", description: "@code-reviewer" },
        { label: "Skip", description: "No review" }
      ]
    }
  ]
})

---

Phase 5: Dispatch to Execution

Step 5.1: Generate task.json (by command, not agent)

const taskId = `LP-${shortTimestamp}`

// Load manifest and all exploration files
const manifest = JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`))
const explorations = {}

manifest.explorations.forEach(exp => {
  if (file_exists(exp.path)) {
    explorations[exp.angle] = JSON.parse(Read(exp.path))
  }
})

const plan = JSON.parse(Read(`${sessionFolder}/plan.json`))

const taskJson = {
  id: taskId,
  title: task_description,
  status: "pending",

  meta: {
    type: "planning",
    created_at: new Date().toISOString(),
    complexity: plan.complexity,
    estimated_time: plan.estimated_time,
    recommended_execution: plan.recommended_execution,
    workflow: "lite-plan",
    session_id: sessionId,
    session_folder: sessionFolder,
    exploration_count: manifest.exploration_count,
    exploration_angles: manifest.explorations.map(e => e.angle)
  },

  context: {
    requirements: [task_description],
    plan: {
      summary: plan.summary,
      approach: plan.approach,
      tasks: plan.tasks
    },

    // Multi-angle exploration structure
    explorations: explorations,

    // Exploration files for reference
    exploration_files: manifest.explorations.map(exp => ({
      angle: exp.angle,
      file: exp.file,
      path: exp.path,
      index: exp.index
    })),

    clarifications: clarificationContext || null,

    // Aggregate relevant files from all exploration angles
    focus_paths: Array.from(new Set(
      Object.values(explorations).flatMap(exp => exp.relevant_files || [])
    )),

    acceptance: plan.tasks.flatMap(t => t.acceptance)
  }
}

Write(`${sessionFolder}/task.json`, JSON.stringify(taskJson, null, 2))

Step 5.2: Store executionContext

executionContext = {
  planObject: plan,
  explorationsContext: explorations,  // Multiple explorations
  explorationAngles: manifest.explorations.map(e => e.angle),
  explorationManifest: manifest,
  clarificationContext: clarificationContext || null,
  executionMethod: userSelection.execution_method,
  codeReviewTool: userSelection.code_review_tool,
  originalUserInput: task_description,
  session: {
    id: sessionId,
    folder: sessionFolder,
    artifacts: {
      explorations: manifest.explorations.map(exp => ({
        angle: exp.angle,
        path: exp.path
      })),
      explorations_manifest: `${sessionFolder}/explorations-manifest.json`,
      plan: `${sessionFolder}/plan.json`,
      task: `${sessionFolder}/task.json`
    }
  }
}

Step 5.3: Dispatch

SlashCommand(command="/workflow:lite-execute --in-memory")

Session Folder Structure

.workflow/.lite-plan/{task-slug}-{timestamp}/
├── exploration-{angle1}.json      # Exploration angle 1 (agent-decided)
├── exploration-{angle2}.json      # Exploration angle 2 (agent-decided)
├── exploration-{angle3}.json      # Exploration angle 3 (if applicable)
├── exploration-{angle4}.json      # Exploration angle 4 (if applicable)
├── explorations-manifest.json     # Exploration index
├── plan.json                      # Implementation plan
└── task.json                      # Task definition with multi-exploration refs

Example (angles decided by agents):

.workflow/.lite-plan/implement-jwt-refresh-2025-11-25-14-30-25/
├── exploration-architecture.json
├── exploration-auth-patterns.json
├── exploration-security.json
├── explorations-manifest.json
├── plan.json
└── task.json

Error Handling

Error	Resolution
Exploration agent failure	Skip exploration, continue with task description only
Planning agent failure	Fallback to direct planning by Claude
Clarification timeout	Use exploration findings as-is
Confirmation timeout	Save context, display resume instructions
Modify loop > 3 times	Suggest breaking task or using /workflow:plan