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