feat(lite-plan): add detailed data structures and enhanced task JSON export for improved planning context

.claude/commands/workflow/lite-execute.md

@@ -31,10 +31,41 @@ Flexible task execution command supporting three input modes: in-memory plan (fr
 --in-memory                Use plan from memory (called by lite-plan)
 
 # Arguments
-<input>                    Task description string, or path to file containing task description (required)
+<input>                    Task description string, or path to file containing task description or Enhanced Task JSON (required)
 ```
 
-### Input Modes
+## Data Structures
+
+### Input Data (from lite-plan)
+
+**executionContext** (Mode 1: --in-memory):
+- Passed from lite-plan via global variable
+- Contains: `planObject`, `explorationContext`, `clarificationContext`, `executionMethod`, `codeReviewTool`, `originalUserInput`
+
+**Enhanced Task JSON file parsing** (Mode 3: file input):
+- **When detected**: File is valid JSON with `meta.workflow === "lite-plan"` (exported by lite-plan)
+- **Extracted fields**: `planObject` (from `context.plan`), `explorationContext` (from `context.exploration`), `clarificationContext` (from `context.clarifications`), `originalUserInput` (from `title`)
+- **Otherwise**: File content treated as plain text prompt
+
+### Output Data (produced by lite-execute)
+
+**executionResult**:
+```javascript
+{
+  executionId: string,                 // e.g., "[Agent-1]", "[Codex-1]"
+  status: "completed" | "partial" | "failed",
+  tasksSummary: string,                // Brief description of tasks handled
+  completionSummary: string,           // What was completed
+  keyOutputs: string,                  // Files created/modified, key changes
+  notes: string                        // Any important context for next execution
+}
+```
+
+Collected after each execution call completes and appended to `previousExecutionResults` array for context continuity in multi-execution scenarios.
+
+---
+
+## Input Modes
 
 #### Mode 1: In-Memory Plan
 
@@ -42,24 +73,7 @@ Flexible task execution command supporting three input modes: in-memory plan (fr
 
 **Input Source**: `executionContext` global variable set by lite-plan
 
-**Expected Structure**:
+**Expected Structure**: See [executionContext](#executioncontext) in Data Structures section
-```javascript
-executionContext = {
-  planObject: {
-    summary: string,
-    approach: string,
-    tasks: string[],
-    estimated_time: string,
-    recommended_execution: string,
-    complexity: string
-  },
-  explorationContext: {...} | null,
-  clarificationContext: {...} | null,
-  executionMethod: "Agent" | "Codex" | "Auto",
-  codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string,
-  originalUserInput: string | null  // User's original task description
-}
-```
 
 **Behavior**:
 - Skip execution method selection (already set)
@@ -110,16 +124,67 @@ AskUserQuestion({
 
 **Trigger**: User calls with file path
 
-**Input**: Path to file containing task description or plan
+**Input**: Path to file containing task description, plan, or Enhanced Task JSON
 
 **Behavior**:
-- Read file content and store as `originalUserInput`
+
-- Use file content as task prompt (equivalent to Mode 2)
+**Step 3.1: Read and Detect File Format**
+```javascript
+fileContent = Read(filePath)
+
+// Attempt to parse as JSON
+try {
+  jsonData = JSON.parse(fileContent)
+
+  // Check if it's Enhanced Task JSON from lite-plan
+  if (jsonData.meta?.workflow === "lite-plan") {
+    // Extract plan data from Enhanced Task JSON
+    planObject = {
+      summary: jsonData.context.plan.summary,
+      approach: jsonData.context.plan.approach,
+      tasks: jsonData.context.plan.tasks,
+      estimated_time: jsonData.meta.estimated_time,
+      recommended_execution: jsonData.meta.recommended_execution,
+      complexity: jsonData.meta.complexity
+    }
+    explorationContext = jsonData.context.exploration || null
+    clarificationContext = jsonData.context.clarifications || null
+    originalUserInput = jsonData.title  // Original task description
+
+    // Set detected format flag
+    isEnhancedTaskJson = true
+  } else {
+    // Valid JSON but not Enhanced Task JSON - treat as plain text
+    originalUserInput = fileContent
+    isEnhancedTaskJson = false
+  }
+} catch {
+  // Not valid JSON - treat as plain text prompt
+  originalUserInput = fileContent
+  isEnhancedTaskJson = false
+}
+```
+
+**Step 3.2: Create Execution Plan**
+
+If `isEnhancedTaskJson === true`:
+- Use extracted `planObject` directly
+- Skip planning, use lite-plan's existing plan
+- User still selects execution method and code review
+
+If `isEnhancedTaskJson === false`:
+- Create simple execution plan from file content (treated as prompt)
+- Same behavior as Mode 2
+
+**Step 3.3: User Interaction**
 - Ask user to select execution method (Agent/Codex/Auto)
 - Ask user about code review preference
-- Proceed to execution with `originalUserInput` included
+- Proceed to execution with full context
 
-**Note**: File content is treated as prompt text, no special format parsing required. Any file format can be used as long as it contains readable task description.
+**Note**:
+- Enhanced Task JSON format from lite-plan is automatically recognized and parsed
+- Other file formats (plain text, markdown, etc.) are treated as prompts
+- All extracted data stored in `originalUserInput` for execution reference
 
 ## Execution Process
 
@@ -131,7 +196,9 @@ Input Processing
     v
 [Mode Detection]
     ├─ --in-memory → Load from executionContext variable
-    ├─ File path → Read file content as prompt
+    ├─ File path → Read and detect format
+    │   ├─ Enhanced Task JSON (lite-plan export) → Extract plan data
+    │   └─ Plain text/other → Use as prompt
     └─ String → Use as prompt directly
     |
     v
@@ -265,21 +332,9 @@ ${result.notes ? `Notes: ${result.notes}` : ''}
 )
 ```
 
-**Note**: `originalUserInput` is the user's original prompt (Mode 2) or file content (Mode 3). For Mode 1 (--in-memory), this may be null if not provided by lite-plan.
+**Note**: `originalUserInput` is the user's original prompt (Mode 2), file content (Mode 3 plain text), or task title (Mode 3 Enhanced Task JSON). For Mode 1 (--in-memory), this may be null if not provided by lite-plan.
 
-**Execution Result Collection**:
+**Execution Result Collection**: After agent execution completes, collect result following [executionResult](#executionresult) structure in Data Structures section and append to `previousExecutionResults` array
-After agent execution completes:
-```javascript
-executionResult = {
-  executionId: executionCalls[currentIndex].id, // e.g., "[Agent-1]"
-  status: "completed" | "partial" | "failed",
-  tasksSummary: "Brief description of tasks handled",
-  completionSummary: "What was completed",
-  keyOutputs: "Files created/modified, key changes",
-  notes: "Any important context for next execution"
-}
-previousExecutionResults.push(executionResult)
-```
 
 #### Option B: CLI Execution (Codex)
 
@@ -335,7 +390,7 @@ Complexity: ${planObject.complexity}
 " --skip-git-repo-check -s danger-full-access
 ```
 
-**Note**: `originalUserInput` is the user's original prompt (Mode 2) or file content (Mode 3). For Mode 1 (--in-memory), this may be null if not provided by lite-plan.
+**Note**: `originalUserInput` is the user's original prompt (Mode 2), file content (Mode 3 plain text), or task title (Mode 3 Enhanced Task JSON). For Mode 1 (--in-memory), this may be null if not provided by lite-plan.
 
 **Execution with Progress Tracking**:
 ```javascript
@@ -348,8 +403,7 @@ bash_result = Bash(
 // Update TodoWrite when CLI execution call completes
 ```
 
-**Execution Result Collection**:
+**Execution Result Collection**: After CLI execution completes, analyze output and collect result following [executionResult](#executionresult) structure in Data Structures section
-After CLI execution completes, analyze output and collect result summary with same structure as Agent execution.
 
 ### Step 4: Track Execution Progress
 
@@ -442,7 +496,9 @@ codex --full-auto exec "Review the recent code changes for quality, potential is
 3. **Flexible Execution**: Supports multiple input modes
    - In-memory: Seamless integration with lite-plan
    - Prompt: Quick standalone execution
-   - File: Read file content as prompt for execution
+   - File: Intelligent format detection
+     - Enhanced Task JSON (lite-plan export): Extracts full plan context
+     - Plain text: Uses as prompt for execution
 
 ### Task Management
 
@@ -463,6 +519,8 @@ codex --full-auto exec "Review the recent code changes for quality, potential is
 | Missing executionContext | --in-memory called without context | Display error: "No execution context found. This mode is only available when called by lite-plan." |
 | File not found | File path doesn't exist | Display error: "File not found: {path}. Please check the file path." |
 | Empty file | File exists but has no content | Display error: "File is empty: {path}. Please provide task description." |
+| Invalid Enhanced Task JSON | JSON parsing succeeds but missing required fields | Display warning: "File appears to be Enhanced Task JSON but missing required fields. Treating as plain text prompt." |
+| Malformed JSON | JSON parsing fails | Treat as plain text prompt, no error displayed (expected behavior for non-JSON files) |
 | Execution failure | Agent/Codex crashes or errors | Display error details, save partial progress, suggest retry |
 | Codex unavailable | Codex tool not installed | Show installation instructions, offer Agent execution |
 

.claude/commands/workflow/lite-plan.md

@@ -39,6 +39,122 @@ Intelligent lightweight planning command with dynamic workflow adaptation based
 ```
 
 
+## Data Structures
+
+All workflow phases use these standardized data structures:
+
+### explorationContext
+
+Exploration findings from cli-explore-agent (Phase 1):
+
+```javascript
+{
+  project_structure: string,           // Overall architecture description
+  relevant_files: string[],            // File paths to be modified/referenced
+  patterns: string,                    // Existing patterns and conventions
+  dependencies: string,                // Dependencies and integration points
+  integration_points: string,          // Where this connects with existing code
+  constraints: string,                 // Technical constraints
+  clarification_needs: [               // Questions requiring user input
+    {
+      question: string,
+      context: string,
+      options: string[]
+    }
+  ]
+}
+```
+
+### planObject
+
+Implementation plan from Phase 3:
+
+```javascript
+{
+  summary: string,                     // 2-3 sentence overview
+  approach: string,                    // High-level implementation strategy
+  tasks: string[],                     // 3-10 tasks with file paths
+  estimated_time: string,              // Total implementation time estimate
+  recommended_execution: string,       // "Agent" (Low) or "Codex" (Medium/High)
+  complexity: string                   // "Low" | "Medium" | "High"
+}
+```
+
+### executionContext
+
+Context passed to lite-execute via --in-memory (Phase 5):
+
+```javascript
+{
+  planObject: {                        // See planObject structure above
+    summary: string,
+    approach: string,
+    tasks: string[],
+    estimated_time: string,
+    recommended_execution: string,
+    complexity: string
+  },
+  explorationContext: {...} | null,    // See explorationContext structure above
+  clarificationContext: {...} | null,  // User responses from Phase 2
+  executionMethod: "Agent" | "Codex" | "Auto",
+  codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string,
+  originalUserInput: string            // User's original task description
+}
+```
+
+### Enhanced Task JSON Export
+
+When user selects "Export JSON", lite-plan exports an enhanced structure aligned with Enhanced Task JSON Schema:
+
+```json
+{
+  "id": "LP-{timestamp}",
+  "title": "Original task description",
+  "status": "pending",
+
+  "meta": {
+    "type": "planning",
+    "created_at": "ISO timestamp",
+    "complexity": "Low|Medium|High",
+    "estimated_time": "X minutes",
+    "recommended_execution": "Agent|Codex",
+    "workflow": "lite-plan"
+  },
+
+  "context": {
+    "requirements": ["Original task description"],
+    "plan": {
+      "summary": "2-3 sentence overview",
+      "approach": "High-level implementation strategy",
+      "tasks": ["Task 1", "Task 2", "..."]
+    },
+    "exploration": {
+      "project_structure": "...",
+      "relevant_files": ["file1.ts", "file2.ts"],
+      "patterns": "...",
+      "dependencies": "...",
+      "integration_points": "...",
+      "constraints": "..."
+    } | null,
+    "clarifications": {
+      "question1": "answer1",
+      "question2": "answer2"
+    } | null,
+    "focus_paths": ["src/auth", "tests/auth"],
+    "acceptance": ["Task completion criteria from plan.tasks"]
+  }
+}
+```
+
+**Schema Alignment Notes**:
+- Aligns with Enhanced Task JSON Schema (6-field structure)
+- `context_package_path` omitted (lite-plan doesn't use context packages)
+- `flow_control` omitted (execution handled by lite-execute)
+- `focus_paths` derived from `exploration.relevant_files`
+- `acceptance` derived from `plan.tasks`
+
+---
+
 ## Execution Process
 
 ### Workflow Overview
@@ -51,7 +167,7 @@ User Input ("/workflow:lite-plan \"task\"")
     -> Analyze task description
     -> Decision: Need exploration? (Yes/No)
     -> If Yes: Launch cli-explore-agent
-    -> Output: exploration findings (if performed)
+    -> Output: explorationContext (if performed)
     |
     v
 [Phase 2] Clarification (Optional, user interaction)
@@ -66,21 +182,23 @@ User Input ("/workflow:lite-plan \"task\"")
     -> Decision: Planning strategy
        - Low: Direct planning (current Claude)
        - Medium/High: Delegate to cli-planning-agent
-    -> Output: Task breakdown with execution approach
+    -> Output: planObject
     |
     v
 [Phase 4] Task Confirmation & Execution Selection (User interaction)
     -> Step 4.1: Output complete plan as text to user
-    -> Step 4.2: AskUserQuestion with three dimensions
+    -> Step 4.2: AskUserQuestion with four dimensions
        1. Confirm task: Allow/Modify/Cancel (multi-select, can supplement via Other)
        2. Execution method: Agent/Codex/Auto (single-select, auto: simple→agent, complex→codex)
        3. Code review: Skip/Gemini/Agent/Other (single-select, can specify custom tool via Other)
+       4. Export JSON: Yes/No (single-select, export enhanced task JSON)
     -> Process selections and proceed to Phase 5
     -> If cancel: Exit
     |
     v
 [Phase 5] Dispatch to Execution
-    -> Store execution context (plan, exploration, clarifications, selections)
+    -> Export enhanced task JSON (optional, if user selected "Yes")
+    -> Store executionContext in memory
     -> Call /workflow:lite-execute --in-memory
     -> Execution delegated to lite-execute command
     |
@@ -93,7 +211,7 @@ Planning Complete (Execution continues in lite-execute)
 - lite-plan focuses on planning phases (1-4) with TodoWrite tracking
 - Phase 5 stores execution context and dispatches to lite-execute
 - Execution tracking (TodoWrite updates, progress monitoring) handled by lite-execute
-- No intermediate file artifacts generated (all planning in-memory)
+- Optional enhanced task JSON export aligned with Enhanced Task JSON Schema
 - Execution artifacts (code changes, test results) managed by lite-execute
 
 ## Detailed Phase Execution
@@ -154,25 +272,7 @@ Planning Complete (Execution continues in lite-execute)
   )
   ```
 
-**Expected Return Structure**:
+**Expected Return Structure**: See [explorationContext](#explorationcontext) in Data Structures section
-```javascript
-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`
@@ -297,17 +397,7 @@ Task(
 )
 ```
 
-**Expected Return Structure (Both Options)**:
+**Expected Return Structure (Both Options)**: See [planObject](#planobject) in Data Structures section
-```javascript
-planObject = {
-  summary: string,              // 2-3 sentence overview
-  approach: string,             // High-level implementation strategy
-  tasks: string[],              // 3-10 tasks with file paths
-  estimated_time: string,       // Total implementation time estimate
-  recommended_execution: string, // "Agent" (Low) or "Codex" (Medium/High)
-  complexity: string            // "Low" | "Medium" | "High"
-}
-```
 
 **Progress Tracking**:
 - Mark Phase 3 as completed
@@ -473,58 +563,57 @@ Task JSON Export:
 **Operations**:
 - Create `.workflow/lite-plans/` directory if not exists
 - Generate timestamp-based filename
-- Export complete plan context to JSON file
+- Export enhanced task JSON aligned with Enhanced Task JSON Schema
 
 ```javascript
 // Only execute if userSelection.export_task_json === "Yes"
 if (userSelection.export_task_json === "Yes") {
   const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
-  const filename = `.workflow/lite-plans/plan-${timestamp}.json`
+  const taskId = `LP-${timestamp}`
+  const filename = `.workflow/lite-plans/${taskId}.json`
 
-  const planExport = {
+  const enhancedTaskJson = {
-    metadata: {
+    id: taskId,
+    title: original_task_description,
+    status: "pending",
+
+    meta: {
+      type: "planning",
       created_at: new Date().toISOString(),
-      task_description: original_task_description,
       complexity: planObject.complexity,
-      estimated_time: planObject.estimated_time
+      estimated_time: planObject.estimated_time,
+      recommended_execution: planObject.recommended_execution,
+      workflow: "lite-plan"
     },
-    plan: planObject,
+
-    exploration: explorationContext || null,
+    context: {
-    clarifications: clarificationContext || null
+      requirements: [original_task_description],
+      plan: {
+        summary: planObject.summary,
+        approach: planObject.approach,
+        tasks: planObject.tasks
+      },
+      exploration: explorationContext || null,
+      clarifications: clarificationContext || null,
+      focus_paths: explorationContext?.relevant_files || [],
+      acceptance: planObject.tasks  // Tasks serve as acceptance criteria
+    }
   }
 
-  Write(filename, JSON.stringify(planExport, null, 2))
+  Write(filename, JSON.stringify(enhancedTaskJson, null, 2))
 
   // Display export confirmation to user
-  console.log(`Plan exported to: ${filename}`)
+  console.log(`Enhanced task JSON exported to: ${filename}`)
   console.log(`You can reuse this plan with: /workflow:lite-execute ${filename}`)
 }
 ```
 
-**Export File Format**:
+**Export File Format**: See [Enhanced Task JSON Export](#enhanced-task-json-export) in Data Structures section
-```json
-{
-  "metadata": {
-    "created_at": "2025-01-17T10:30:00.000Z",
-    "task_description": "Original task description",
-    "complexity": "Medium",
-    "estimated_time": "30 minutes"
-  },
-  "plan": {
-    "summary": "...",
-    "approach": "...",
-    "tasks": [...],
-    "recommended_execution": "Agent|Codex",
-    "complexity": "Low|Medium|High"
-  },
-  "exploration": {...} or null,
-  "clarifications": {...} or null
-}
-```
 
 **Step 5.2: Store Execution Context**
 
 Create execution context variable with all necessary information:
+
 ```javascript
 // Create execution context for lite-execute
 executionContext = {
@@ -537,24 +626,7 @@ executionContext = {
 }
 ```
 
-**Context Structure**:
+**Context Structure**: See [executionContext](#executioncontext) in Data Structures section
-```javascript
-{
-  planObject: {
-    summary: string,
-    approach: string,
-    tasks: string[],
-    estimated_time: string,
-    recommended_execution: string,
-    complexity: string
-  },
-  explorationContext: {...} | null,
-  clarificationContext: {...} | null,
-  executionMethod: "Agent" | "Codex" | "Auto",
-  codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string,
-  originalUserInput: string  // User's original task description
-}
-```
 
 **Step 5.3: Call lite-execute**
 
@@ -693,25 +765,16 @@ SlashCommand(command="/workflow:lite-execute --in-memory")
 
 ### Output Format
 
-**In-Memory Plan Object**:
+**In-Memory Plan Object**: See [planObject](#planobject) in Data Structures section
-```javascript
+
-{
+**Optional Enhanced Task JSON Export**: See [Enhanced Task JSON Export](#enhanced-task-json-export) in Data Structures section (when user selects "Export JSON")
-  summary: "2-3 sentence overview of implementation",
+
-  approach: "High-level implementation strategy",
+**Execution Context**: See [executionContext](#executioncontext) in Data Structures section (passed to lite-execute)
-  tasks: [
-    "Task 1: Specific action with file locations",
-    "Task 2: Specific action with file locations",
-    // ... 3-7 tasks total
-  ],
-  complexity: "Low|Medium|High",
-  recommended_execution: "Agent|Codex",  // Based on complexity
-  estimated_time: "X minutes"
-}
-```
 
 **Execution Result**:
-- Immediate dispatch to selected tool/agent with plan context
+- Immediate dispatch to lite-execute with executionContext
-- No file artifacts generated during planning phase
+- Optional enhanced task JSON file export aligned with Enhanced Task JSON Schema
-- Execution starts immediately after user confirmation
+- No other file artifacts generated during planning phase
+- Execution starts immediately in lite-execute after context handoff
 - Tool/agent handles implementation and any necessary file operations