diff --git a/.claude/commands/workflow/lite-execute.md b/.claude/commands/workflow/lite-execute.md
index c1acdd43..9074a446 100644
--- 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
- Task description string, or path to file containing task description (required)
+ 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 |
diff --git a/.claude/commands/workflow/lite-plan.md b/.claude/commands/workflow/lite-plan.md
index c8fb2ec3..a25d06bc 100644
--- 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"
},
- plan: planObject,
- exploration: explorationContext || null,
- clarifications: clarificationContext || null
+
+ context: {
+ 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**:
-```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