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

2026-02-05 01:50:27 +08:00 · 2025-11-17 17:06:13 +08:00
parent 0380cbb7b8
commit 6ebb1801d1
2 changed files with 267 additions and 146 deletions
--- a/.claude/commands/workflow/lite-execute.md
+++ b/.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**:
-```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
-}
-```
+**Expected Structure**: See [executionContext](#executioncontext) in Data Structures section

 **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**:
-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)
-```
+**Execution Result Collection**: After agent execution completes, collect result following [executionResult](#executionresult) structure in Data Structures section and append to `previousExecutionResults` array

 #### 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**:
-After CLI execution completes, analyze output and collect result summary with same structure as Agent execution.
+**Execution Result Collection**: After CLI execution completes, analyze output and collect result following [executionResult](#executionresult) structure in Data Structures section

 ### 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 |

--- a/.claude/commands/workflow/lite-plan.md
+++ b/.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**:
-```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
-  ]
-}
-```
+**Expected Return Structure**: See [explorationContext](#explorationcontext) in Data Structures section

 **Output Processing**:
 - Store exploration findings in `explorationContext`
@@ -297,17 +397,7 @@ Task(
 )
 ```

-**Expected Return Structure (Both Options)**:
-```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"
-}
-```
+**Expected Return Structure (Both Options)**: See [planObject](#planobject) in Data Structures section

 **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 = {
-    metadata: {
+  const enhancedTaskJson = {
+    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"
+    },
+
+    context: {
+      requirements: [original_task_description],
+      plan: {
+        summary: planObject.summary,
+        approach: planObject.approach,
+        tasks: planObject.tasks
      },
-    plan: planObject,
      exploration: explorationContext || null,
-    clarifications: clarificationContext || 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**:
-```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
-}
-```
+**Export File Format**: See [Enhanced Task JSON Export](#enhanced-task-json-export) in Data Structures section

 **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**:
-```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
-}
-```
+**Context Structure**: See [executionContext](#executioncontext) in Data Structures section

 **Step 5.3: Call lite-execute**

@@ -693,25 +765,16 @@ SlashCommand(command="/workflow:lite-execute --in-memory")

 ### Output Format

-**In-Memory Plan Object**:
-```javascript
-{
-  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_execution: "Agent|Codex",  // Based on complexity
-  estimated_time: "X minutes"
-}
-```
+**In-Memory Plan Object**: See [planObject](#planobject) in Data Structures section
+
+**Optional Enhanced Task JSON Export**: See [Enhanced Task JSON Export](#enhanced-task-json-export) in Data Structures section (when user selects "Export JSON")
+
+**Execution Context**: See [executionContext](#executioncontext) in Data Structures section (passed to lite-execute)

 **Execution Result**:
- Immediate dispatch to selected tool/agent with plan context
- No file artifacts generated during planning phase
- Execution starts immediately after user confirmation
+- Immediate dispatch to lite-execute with executionContext
+- Optional enhanced task JSON file export aligned with Enhanced Task JSON Schema
+- 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