Claude-Code-Workflow/.codex/skills/workflow-lite-plan-execute/phases/01-lite-plan.md

Phase 1: 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 Phase 2: Lite Execute (phases/02-lite-execute.md).

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: Low complexity → Direct Claude; Medium/High → cli-lite-planning-agent
• Two-step confirmation: plan display → multi-dimensional input collection
• Execution handoff with complete context to lite-execute

Parameters

Parameter	Description
-y, --yes	Skip all confirmations (auto mode)
-e, --explore	Force code exploration phase (overrides auto-detection)
<task-description>	Task description or path to .md file (required)

Output Artifacts

Artifact	Description
exploration-{angle}.json	Per-angle exploration results (1-4 files based on complexity)
explorations-manifest.json	Index of all exploration files
exploration-notes.md	Full exploration log (consumed by Plan phase, 6 sections)
exploration-notes-refined.md	Refined exploration log (consumed by Execute phase, task-relevant only)
planning-context.md	Evidence paths + synthesized understanding
plan.json	Structured implementation plan (plan-json-schema.json)

Output Directory: {projectRoot}/.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/

Agent Usage:

• Low complexity → Direct Claude planning (no agent)
• Medium/High complexity → cli-lite-planning-agent generates plan.json

Schema Reference: ~/.ccw/workflows/cli-templates/schemas/plan-json-schema.json

Auto Mode Defaults

When --yes or -y flag is used:

• Clarification Questions: Skipped (no clarification phase)
• Plan Confirmation: Auto-selected "Allow"
• Execution Method: Auto-selected "Auto"
• Code Review: Auto-selected "Skip"

Flag Parsing:

const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const forceExplore = $ARGUMENTS.includes('--explore') || $ARGUMENTS.includes('-e')

Execution Process

Phase 1: Task Analysis & Exploration
   ├─ Parse input (description or .md file)
   ├─ Intelligent complexity assessment (Low/Medium/High)
   ├─ Exploration decision (auto-detect or --explore flag)
   ├─ Context protection: If file reading ≥50k chars → force cli-explore-agent
   └─ Decision:
      ├─ needsExploration=true → Launch parallel cli-explore-agents (1-4 based on complexity)
      └─ needsExploration=false → Skip to Phase 2/3

Phase 2: Clarification (optional, multi-round)
   ├─ Aggregate clarification_needs from all exploration angles
   ├─ Deduplicate similar questions
   └─ Decision:
      ├─ Has clarifications → ASK_USER (max 4 questions per round, multiple rounds allowed)
      └─ No clarifications → Skip to Phase 3

Phase 3: Planning (NO CODE EXECUTION - planning only)
   └─ Decision (based on Phase 1 complexity):
      ├─ Low → Load schema: cat ~/.ccw/workflows/cli-templates/schemas/plan-json-schema.json → Direct Claude planning (following schema) → plan.json
      └─ Medium/High → cli-lite-planning-agent → plan.json (agent internally executes quality check)

Phase 4: Confirmation & Selection
   ├─ Display plan summary (tasks, complexity, estimated time)
   └─ ASK_USER:
      ├─ Confirm: Allow / Modify / Cancel
      ├─ Execution: Agent / Codex / Auto
      └─ Review: Gemini / Agent / Skip

Phase 5: Execute
   ├─ Build executionContext (plan + explorations + clarifications + selections)
   └─ → Hand off to Phase 2: Lite Execute (phases/02-lite-execute.md) --in-memory

Implementation

Phase 1: Intelligent Multi-Angle Exploration

Session Setup (MANDATORY)

Step 0: Determine Project Root

检测项目根目录，确保 .workflow/ 产物位置正确：

PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

优先通过 git 获取仓库根目录；非 git 项目回退到 pwd 取当前绝对路径。 存储为 {projectRoot}，后续所有 .workflow/ 路径必须以此为前缀。

Step 1: Generate Session ID

Generate session ID and create session folder:

• Session ID format: {task-slug}-{YYYY-MM-DD}
  • task-slug: lowercase task description, non-alphanumeric replaced with -, max 40 chars
  • Date: UTC+8 (China Standard Time), format 2025-11-29
  • Example: implement-jwt-refresh-2025-11-29
• Session Folder: {projectRoot}/.workflow/.lite-plan/{session-id}/
• Create folder via mkdir -p and verify existence

Exploration Decision

Exploration is needed when ANY of these conditions are met:

• --explore / -e flag is set
• Task mentions specific files
• Task requires codebase context understanding
• Task needs architecture understanding
• Task modifies existing code

If none apply → skip to Phase 2 (Clarification) or Phase 3 (Planning).

⚠️ Context Protection: If file reading would exceed ≥50k chars → force exploration (delegate to cli-explore-agent).

Complexity Assessment

Analyze task complexity based on four dimensions:

Dimension	Low	Medium	High
Scope	Single file, isolated	Multiple files, some dependencies	Cross-module, architectural
Depth	Surface change	Moderate structural impact	Architectural impact
Risk	Minimal	Moderate	High risk of breaking
Dependencies	None	Some interconnection	Highly interconnected

Exploration Angle Selection

Angles are assigned based on task type keyword matching, then sliced by complexity:

Task Type	Keywords	Angle Presets (priority order)
Architecture	refactor, architect, restructure, modular	architecture, dependencies, modularity, integration-points
Security	security, auth, permission, access	security, auth-patterns, dataflow, validation
Performance	performance, slow, optimi, cache	performance, bottlenecks, caching, data-access
Bugfix	fix, bug, error, issue, broken	error-handling, dataflow, state-management, edge-cases
Feature (default)	—	patterns, integration-points, testing, dependencies

Angle count by complexity: Low → 1, Medium → 3, High → 4

Planning strategy: Low → "Direct Claude Planning", Medium/High → "cli-lite-planning-agent"

Display exploration plan summary (complexity, selected angles, planning strategy) before launching agents.

Launch Parallel Explorations

⚠️ CRITICAL — SYNCHRONOUS EXECUTION: Exploration results are REQUIRED before planning. Use spawn_agent + wait pattern.

Orchestration Flow:

1. Spawn agents
   └─ For each selected angle → create cli-explore-agent with Agent Prompt (below)

2. Batch wait
   └─ Wait for ALL agents (timeout: 10 minutes)

3. Handle timeout
   └─ If partial timeout → log warning, continue with completed results

4. Collect results
   └─ For each completed agent → store exploration data keyed by angle

5. Close agents
   └─ Close ALL exploration agents after collection

Agent Prompt Template (per angle):

## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
2. Read: {projectRoot}/.workflow/project-tech.json
3. Read: {projectRoot}/.workflow/project-guidelines.json

---

## Task Objective
Execute **{angle}** exploration for task planning context. Analyze codebase from this specific angle to discover relevant structure, patterns, and constraints.

## Output Location

**Session Folder**: {sessionFolder}
**Output File**: {sessionFolder}/exploration-{angle}.json

## Assigned Context
- **Exploration Angle**: {angle}
- **Task Description**: {task_description}
- **Exploration Index**: {index} of {total}

## MANDATORY STEPS (Execute by Agent)
**You (cli-explore-agent) MUST execute these steps in order:**
1. Run: ccw tool exec get_modules_by_depth '{}' (project structure)
2. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files)
3. Execute: cat ~/.ccw/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference)
4. Read: {projectRoot}/.workflow/project-tech.json (technology stack and architecture context)
5. Read: {projectRoot}/.workflow/project-guidelines.json (user-defined constraints and conventions)

## Exploration Strategy ({angle} focus)

**Step 1: Structural Scan** (Bash)
- get_modules_by_depth.sh → identify modules related to {angle}
- find/rg → locate files relevant to {angle} aspect
- Analyze imports/dependencies from {angle} perspective

**Step 2: Semantic Analysis** (Gemini CLI)
- How does existing code handle {angle} concerns?
- What patterns are used for {angle}?
- Where would new code integrate from {angle} viewpoint?

**Step 3: Write Output**
- Consolidate {angle} findings into JSON
- Identify {angle}-specific clarification needs

## Expected Output

**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly

**Required Fields** (all {angle} focused):
- project_structure: Modules/architecture relevant to {angle}
- relevant_files: Files affected from {angle} perspective
  **IMPORTANT**: Use object format with relevance scores for synthesis:
  `[{path: "src/file.ts", relevance: 0.85, rationale: "Core {angle} logic"}]`
  Scores: 0.7+ high priority, 0.5-0.7 medium, <0.5 low
- patterns: {angle}-related patterns to follow
- dependencies: Dependencies relevant to {angle}
- integration_points: Where to integrate from {angle} viewpoint (include file:line locations)
- constraints: {angle}-specific limitations/conventions
- clarification_needs: {angle}-related ambiguities (options array + recommended index)
- _metadata.exploration_angle: "{angle}"

## Success Criteria
- [ ] Schema obtained via cat explore-json-schema.json
- [ ] get_modules_by_depth.sh executed
- [ ] At least 3 relevant files identified with {angle} rationale
- [ ] Patterns are actionable (code examples, not generic advice)
- [ ] Integration points include file:line locations
- [ ] Constraints are project-specific to {angle}
- [ ] JSON output follows schema exactly
- [ ] clarification_needs includes options + recommended

## Execution
**Write**: `{sessionFolder}/exploration-{angle}.json`
**Return**: 2-3 sentence summary of {angle} findings

Auto-discover & Manifest Generation

After explorations complete:

1. Discover — Find all exploration-*.json files in session folder
2. Read metadata — Extract _metadata.exploration_angle and _metadata.exploration_index from each file
3. Build manifest — Create explorations-manifest.json containing:
   • session_id, task_description, timestamp, complexity, exploration_count
   • explorations[]: array of { angle, file, path, index } per exploration
4. Write — Save manifest to {sessionFolder}/explorations-manifest.json
5. Display — Summary of generated files and explored angles

Output:

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

Generate Exploration Notes

Auto-generated after exploration completes.

Steps:

1. Load all exploration JSON files via manifest
2. Extract core files — Filter relevant_files with relevance ≥ 0.7, sort by relevance descending, deduplicate by path
3. Build exploration notes — 6-part Markdown document (structure below)
4. Write to {sessionFolder}/exploration-notes.md

Exploration Notes Structure (exploration-notes.md):

# Exploration Notes: {task_description}

**Generated**: {timestamp}  |  **Complexity**: {complexity}
**Exploration Angles**: {angles}

---

## Part 1: Multi-Angle Exploration Summary
Per angle: Key Files (priority sorted), Code Patterns, Integration Points, Dependencies, Constraints

## Part 2: File Deep-Dive Summary
Top 10 core files: read content, find cross-references via rg, format structural details

## Part 3: Architecture Reasoning Chains
Synthesized from exploration findings and task description

## Part 4: Potential Risks and Mitigations
Derived from explorations and core file analysis

## Part 5: Clarification Questions Summary
Aggregated from all exploration angles

## Part 6: Execution Recommendations Checklist
Generated from task description, explorations, and core files

---

## Appendix: Key Code Location Index

| Component | File Path | Key Lines | Purpose |

Output: {sessionFolder}/exploration-notes.md (full version, consumed by Plan phase)

---

Phase 2: Clarification (Optional, Multi-Round)

Skip Conditions: No exploration performed OR clarification_needs empty across all explorations

⚠️ CRITICAL: ASK_USER limits max 4 questions per call. MUST execute multiple rounds to exhaust all clarification needs — do NOT stop at round 1.

Flow:

1. Load manifest + all exploration files

2. Aggregate clarification_needs
   └─ For each exploration → collect needs, tag each with source_angle

3. Deduplicate
   └─ Intelligent merge: identify similar intent across angles
      → combine options, consolidate context
      → produce unique-intent questions only

4. Route by mode:
   ├─ --yes mode → Skip all clarifications, log count, proceed to Phase 3
   └─ Interactive mode → Multi-round clarification:
      ├─ Batch size: 4 questions per round
      ├─ Per round: display "Round N/M", present via ASK_USER
      │   └─ Each question: [source_angle] question + context
      │      Options with recommended marked ★
      ├─ Store responses in clarificationContext after each round
      └─ Repeat until all questions exhausted

Output: clarificationContext (in-memory, keyed by question)

---

Phase 3: Planning

IMPORTANT: Phase 3 is planning only — NO code execution. All execution happens in Phase 5 via lite-execute.

Executor Assignment Rules

Applied after plan generation. Priority (high → low):

1. User explicit — If task description specifies tool (e.g., "用 gemini 分析...") → use that executor
2. Default → agent

Result: executorAssignments map — { taskId: { executor: 'gemini'|'codex'|'agent', reason: string } }

Low Complexity — Direct Planning by Claude

1. Read schema — cat ~/.ccw/workflows/cli-templates/schemas/plan-json-schema.json
2. Read ALL exploration files (⚠️ MANDATORY) — Load manifest, read each exploration JSON, review findings
3. Generate plan following schema — Claude directly generates plan incorporating exploration insights

plan.json structure (Low complexity):

{
  summary: "...",
  approach: "...",
  tasks: [...],  // Each: { id, title, scope, ..., depends_on, execution_group, complexity }
  estimated_time: "...",
  recommended_execution: "Agent",
  complexity: "Low",
  _metadata: { timestamp, source: "direct-planning", planning_mode: "direct" }
}

4. Write {sessionFolder}/plan.json
5. Continue to Phase 4 (Confirmation) — DO NOT execute code here

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

Orchestration:

1. Spawn planning agent → with Agent Prompt (below)
2. Wait for completion → timeout: 15 minutes
3. Close agent → after completion

Agent Prompt Template:

## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/cli-lite-planning-agent.md (MUST read first)
2. Read: {projectRoot}/.workflow/project-tech.json
3. Read: {projectRoot}/.workflow/project-guidelines.json

---

Generate implementation plan and write plan.json.

## Output Location

**Session Folder**: {sessionFolder}
**Output Files**:
- {sessionFolder}/planning-context.md (evidence + understanding)
- {sessionFolder}/plan.json (implementation plan)
- {sessionFolder}/exploration-notes-refined.md (refined exploration notes for Execute phase)

## Output Schema Reference
Execute: cat ~/.ccw/workflows/cli-templates/schemas/plan-json-schema.json (get schema reference before generating plan)

## Project Context (MANDATORY - Read Both Files)
1. Read: {projectRoot}/.workflow/project-tech.json (technology stack, architecture, key components)
2. Read: {projectRoot}/.workflow/project-guidelines.json (user-defined constraints and conventions)

**CRITICAL**: All generated tasks MUST comply with constraints in project-guidelines.json

## Task Description
{task_description}

## Multi-Angle Exploration Context

{For each exploration:
### Exploration: {angle} ({file})
Path: {path}

Read this file for detailed {angle} analysis.
}

Total explorations: {count}
Angles covered: {angles}

Manifest: {sessionFolder}/explorations-manifest.json

## User Clarifications
{clarificationContext or "None"}

## Complexity Level
{complexity}

## Requirements
Generate plan.json following the schema obtained above. Key constraints:
- tasks: 2-7 structured tasks (**group by feature/module, NOT by file**)
- _metadata.exploration_angles: {angles}

## Task Grouping Rules
1. **Group by feature**: All changes for one feature = one task (even if 3-5 files)
2. **Group by context**: Tasks with similar context or related functional changes can be grouped together
3. **Minimize agent count**: Simple, unrelated tasks can also be grouped to reduce agent execution overhead
4. **Avoid file-per-task**: Do NOT create separate tasks for each file
5. **Substantial tasks**: Each task should represent 15-60 minutes of work
6. **True dependencies only**: Only use depends_on when Task B cannot start without Task A's output
7. **Prefer parallel**: Most tasks should be independent (no depends_on)

## Execution
1. Read schema file (cat command above)
2. Execute CLI planning using Gemini (Qwen fallback)
3. Read ALL exploration files for comprehensive context
4. Synthesize findings and generate plan following schema
5. **Write**: `{sessionFolder}/planning-context.md` (evidence paths + understanding)
6. **Write**: `{sessionFolder}/plan.json`
7. Execute Phase 5 (Plan Quality Check) and Phase 6 (Refine Exploration Notes) per agent role definition
8. **Write**: `{sessionFolder}/exploration-notes-refined.md` (Phase 6 output)
9. Return brief completion summary

Output: {sessionFolder}/plan.json + {sessionFolder}/exploration-notes-refined.md

Note

: exploration-notes-refined.md is generated by cli-lite-planning-agent (Phase 6) as part of its execution flow. See ~/.codex/agents/cli-lite-planning-agent.md Phase 6 for structure and generation logic.

---

Phase 4: Task Confirmation & Execution Selection

Step 4.1: Display Plan

Read {sessionFolder}/plan.json and display summary:

• Summary: plan.summary
• Approach: plan.approach
• Tasks: numbered list with title and file
• Complexity: plan.complexity
• Estimated Time: plan.estimated_time
• Recommended: plan.recommended_execution

Step 4.2: Collect Confirmation

Route by mode:

├─ --yes mode → Auto-confirm with defaults:
│   ├─ Confirmation: "Allow"
│   ├─ Execution: "Auto"
│   └─ Review: "Skip"
│
└─ Interactive mode → ASK_USER with 3 questions:

Interactive Questions:

Question	Options	Default
Confirm plan? ({N} tasks, {complexity})	Allow (proceed as-is), Modify (adjust before execution), Cancel (abort workflow)	Allow
Execution method	Agent (@code-developer), Codex (codex CLI), Auto (Low→Agent, else→Codex)	Auto
Code review after execution?	Gemini Review, Codex Review (git-aware), Agent Review, Skip	Skip

Output: userSelection — { confirmation, executionMethod, codeReviewTool }

---

Phase 5: Handoff to Execution

CRITICAL: lite-plan NEVER executes code directly. ALL execution MUST go through lite-execute.

Step 5.1: Build executionContext

Assemble the complete execution context from all planning phase outputs:

{
  planObject: plan,                                    // From plan.json
  explorationsContext: { [angle]: explorationData },   // From exploration JSONs
  explorationAngles: ["angle1", "angle2", ...],        // From manifest
  explorationManifest: manifest,                       // Full manifest object
  clarificationContext: { [question]: answer } | null,
  userSelection: { confirmation, executionMethod, codeReviewTool },
  executionMethod: userSelection.executionMethod,      // Global default; may be overridden by executorAssignments
  codeReviewTool: userSelection.codeReviewTool,
  originalUserInput: task_description,

  // Task-level executor assignments (priority over global executionMethod)
  executorAssignments: { [taskId]: { executor, reason } },

  session: {
    id: sessionId,
    folder: sessionFolder,
    artifacts: {
      explorations: [{ angle, path }],                          // Per-angle exploration paths
      explorations_manifest: "{sessionFolder}/explorations-manifest.json",
      exploration_log: "{sessionFolder}/exploration-notes.md",            // Full version (Plan consumption)
      exploration_log_refined: "{sessionFolder}/exploration-notes-refined.md",  // Refined version (Execute consumption)
      plan: "{sessionFolder}/plan.json"
    }
  }
}

Step 5.2: Execute

→ Hand off to Phase 2: Lite Execute (phases/02-lite-execute.md) with --in-memory flag

Session Folder Structure

{projectRoot}/.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/
├── exploration-{angle1}.json           # Exploration angle 1
├── exploration-{angle2}.json           # Exploration angle 2
├── exploration-{angle3}.json           # Exploration angle 3 (if applicable)
├── exploration-{angle4}.json           # Exploration angle 4 (if applicable)
├── explorations-manifest.json          # Exploration index
├── exploration-notes.md                # Full exploration notes (Plan phase consumption)
├── exploration-notes-refined.md        # Refined exploration notes (Execute phase consumption)
└── plan.json                           # Implementation plan

Example:

{projectRoot}/.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

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 full planning workflow (workflow-plan-execute/SKILL.md)

---

Post-Phase Update

After Phase 1 (Lite Plan) completes:

• Output Created: executionContext with plan.json, explorations, clarifications, user selections
• Session Artifacts: All files in {projectRoot}/.workflow/.lite-plan/{session-id}/
• Next Action: Auto-continue to Phase 2: Lite Execute with --in-memory
• TodoWrite: Mark "Lite Plan - Planning" as completed, start "Execution (Phase 2)"