diff --git a/.claude/commands/workflow/lite-plan.md b/.claude/commands/workflow/lite-plan.md index b9d1dfbb..804e550a 100644 --- a/.claude/commands/workflow/lite-plan.md +++ b/.claude/commands/workflow/lite-plan.md @@ -21,7 +21,6 @@ Intelligent lightweight planning command with dynamic workflow adaptation based ## Usage -### Command Syntax ```bash /workflow:lite-plan [FLAGS] @@ -32,24 +31,8 @@ Intelligent lightweight planning command with dynamic workflow adaptation based Task description or path to .md file (required) ``` -### Input Requirements -- **Task description**: String or path to .md file (required) - - Should be specific and concrete - - Can include context about existing code or requirements - - Examples: - - "Implement user authentication with JWT tokens" - - "Refactor logging module for better performance" - - "Add unit tests for authentication service" -- **Flags** (optional): - - `-e` or `--explore`: Force exploration when: - - Task appears simple but requires codebase context - - Auto-detection might miss integration points - - Comprehensive code understanding needed before planning - ## Execution Process -### Workflow Overview - ``` User Input → Task Analysis & Exploration Decision (Phase 1) ↓ @@ -60,147 +43,99 @@ User Input → Task Analysis & Exploration Decision (Phase 1) Task Confirmation & Execution Selection (Phase 4) ↓ Dispatch to Execution (Phase 5) - ↓ - Planning Complete (lite-execute continues) ``` -### Phase Summary - -**Phase 1: Task Analysis & Exploration Decision** (10-60 seconds) -- Analyze task to determine exploration needs -- Decision logic: `--explore` flag OR requires codebase context -- If needed: Launch cli-explore-agent for code analysis -- Output: `explorationContext` with relevant files, patterns, constraints - -**Phase 2: Clarification** (30-60 seconds, optional) -- Skip if no ambiguities found in Phase 1 -- Use exploration findings to generate targeted questions -- AskUserQuestion based on `clarification_needs` from exploration -- Output: `clarificationContext` with user responses - -**Phase 3: Complexity Assessment & Planning** (20-60 seconds) -- Assess complexity (Low/Medium/High) from multiple factors -- Strategy selection: - - Low: Direct planning by current Claude (fast, 20-30s) - - Medium/High: Delegate to cli-lite-planning-agent (detailed, 40-60s) -- Output: `planObject` with tasks, time estimates, recommendations - -**Phase 4: Task Confirmation & Execution Selection** (user interaction) -- Step 1: Display complete plan as text to user -- Step 2: Collect four inputs via AskUserQuestion: - 1. Confirm plan (Allow/Modify/Cancel + supplements via "Other") - 2. Execution method (Agent/Codex/Auto) - 3. Code review tool (Skip/Gemini/Agent + custom via "Other") - 4. Export JSON (Yes/No for Enhanced Task JSON export) - -**Phase 5: Dispatch to Execution** (<1 second) -- Export Enhanced Task JSON (optional, if user selected "Yes") -- Store `executionContext` in memory with full plan + context -- Call `/workflow:lite-execute --in-memory` -- Execution tracking delegated to lite-execute - -## Detailed Phase Execution +## Implementation ### Phase 1: Task Analysis & Exploration Decision +**Session Setup**: +```javascript +const taskSlug = task_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40) +const timestamp = new Date().toISOString().replace(/[:.]/g, '-') +const shortTimestamp = timestamp.substring(0, 19).replace('T', '-') +const sessionId = `${taskSlug}-${shortTimestamp}` +const sessionFolder = `.workflow/.lite-plan/${sessionId}` + +bash(`mkdir -p ${sessionFolder}`) +``` + **Decision Logic**: ```javascript needsExploration = ( - flags.includes('--explore') || flags.includes('-e') || // Force if flag present - ( - task.mentions_specific_files || - task.requires_codebase_context || - task.needs_architecture_understanding || - task.modifies_existing_code - ) + flags.includes('--explore') || flags.includes('-e') || + task.mentions_specific_files || + task.requires_codebase_context || + task.needs_architecture_understanding || + task.modifies_existing_code ) ``` -**Decision Criteria**: +**If exploration needed** - Invoke cli-explore-agent: -| Task Type | Needs Exploration | Reason | -|-----------|-------------------|--------| -| Any task with `-e`/`--explore` flag | **Yes (forced)** | **Flag overrides auto-detection** | -| "Implement new feature X" | Maybe | Depends on integration needs | -| "Refactor module Y" | Yes | Needs current implementation understanding | -| "Add tests for Z" | Yes | Needs code structure understanding | -| "Create standalone utility" | No | Self-contained, no existing context | -| "Update documentation" | No | Doesn't require code exploration | -| "Fix bug in function F" | Yes | Needs implementation understanding | - -**Exploration Execution** (if needed): ```javascript -// Generate session identifiers for artifact storage -const taskSlug = task_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40) -const timestamp = new Date().toISOString().replace(/[:.]/g, '-') -const shortTimestamp = timestamp.substring(0, 19).replace('T', '-') // YYYY-MM-DD-HH-mm-ss -const sessionId = `${taskSlug}-${shortTimestamp}` -const sessionFolder = `.workflow/.lite-plan/${sessionId}` - Task( subagent_type="cli-explore-agent", description="Analyze codebase for task context", prompt=` - Task: ${task_description} +Analyze codebase for task context and generate exploration.json. - Analyze and return structured information: - 1. Project Structure: Architecture and module organization - 2. Relevant Files: Files to be affected (with paths) - 3. Current Patterns: Code patterns, conventions, styles - 4. Dependencies: External/internal module dependencies - 5. Integration Points: Task connections with existing code - 6. Architecture Constraints: Technical limitations/requirements - 7. Clarification Needs: Ambiguities requiring user input +## Output Schema Reference +~/.claude/workflows/cli-templates/schemas/explore-json-schema.json - Time Limit: 60 seconds - Output Format: JSON-like structured object - ` +## Task Description +${task_description} + +## Requirements +Generate exploration.json with: +- project_structure: Architecture and module organization +- relevant_files: File paths to be affected +- patterns: Code patterns, conventions, styles +- dependencies: External/internal module dependencies +- integration_points: Task connections with existing code +- constraints: Technical limitations/requirements +- clarification_needs: Ambiguities requiring user input +- _metadata: timestamp, task_description, source + +## Execution +1. Structural scan: get_modules_by_depth.sh, find, rg +2. Semantic analysis: Gemini for patterns/architecture +3. Write JSON: Write('${sessionFolder}/exploration.json', jsonContent) +4. Return brief completion summary + +Time Limit: 60 seconds +` ) - -// Save exploration results for CLI/agent access in lite-execute -const explorationFile = `${sessionFolder}/exploration.json` -Write(explorationFile, JSON.stringify(explorationContext, null, 2)) ``` -**Output**: `explorationContext` (in-memory, see Data Structures section) -**Artifact**: Saved to `{sessionFolder}/exploration.json` for CLI/agent use - -**Progress Tracking**: -- Mark Phase 1 completed -- If `clarification_needs.length > 0`: Mark Phase 2 in_progress -- Else: Skip to Phase 3 +**Output**: `${sessionFolder}/exploration.json` (if exploration performed) --- ### Phase 2: Clarification (Optional) -**Skip Condition**: Only run if `needsClarification = true` from Phase 1 +**Skip if**: No exploration or `clarification_needs` is empty -**Operations**: -- Review `explorationContext.clarification_needs` -- Generate AskUserQuestion from exploration findings -- Focus on ambiguities affecting implementation approach - -**Question Generation**: +**If clarification needed**: ```javascript -AskUserQuestion({ - questions: explorationContext.clarification_needs.map(need => ({ - question: `${need.context}\n\n${need.question}`, - header: "Clarification", - multiSelect: false, - options: need.options.map(opt => ({ - label: opt, - description: `Use ${opt} approach` +const exploration = JSON.parse(Read(`${sessionFolder}/exploration.json`)) + +if (exploration.clarification_needs?.length > 0) { + AskUserQuestion({ + questions: exploration.clarification_needs.map(need => ({ + question: `${need.context}\n\n${need.question}`, + header: "Clarification", + multiSelect: false, + options: need.options.map(opt => ({ + label: opt, + description: `Use ${opt} approach` + })) })) - })) -}) + }) +} ``` -**Output**: `clarificationContext` in format `{ question_id: selected_answer }` - -**Progress Tracking**: -- Mark Phase 2 completed -- Mark Phase 3 in_progress +**Output**: `clarificationContext` (in-memory) --- @@ -209,149 +144,96 @@ AskUserQuestion({ **Complexity Assessment**: ```javascript complexityScore = { - file_count: exploration.files_to_modify.length, - integration_points: exploration.dependencies.length, - architecture_changes: exploration.requires_architecture_change, - technology_stack: exploration.unfamiliar_technologies.length, - task_scope: (task.estimated_steps > 5), - cross_cutting_concerns: exploration.affects_multiple_modules + file_count: exploration?.relevant_files?.length || 0, + integration_points: exploration?.dependencies?.length || 0, + architecture_changes: exploration?.constraints?.includes('architecture'), + task_scope: estimated_steps > 5 } -// Calculate complexity -if (complexityScore < 3) complexity = "Low" -else if (complexityScore < 6) complexity = "Medium" -else complexity = "High" +// Low: score < 3, Medium: 3-5, High: > 5 ``` -**Complexity Levels**: +**Low Complexity** - Direct planning by Claude: +- Generate plan directly, write to `${sessionFolder}/plan.json` +- No agent invocation -| Level | Characteristics | Planning Strategy | -|-------|----------------|-------------------| -| Low | 1-2 files, simple changes, clear requirements | Direct planning (current Claude) | -| Medium | 3-5 files, moderate integration, some ambiguity | cli-lite-planning-agent | -| High | 6+ files, complex architecture, high uncertainty | cli-lite-planning-agent with detailed analysis | +**Medium/High Complexity** - Invoke cli-lite-planning-agent: -**Option A: Direct Planning (Low Complexity)** - -Current Claude generates plan directly: -- Summary: 2-3 sentence overview -- Approach: High-level implementation strategy -- Task Breakdown: 3-5 specific, actionable tasks with file paths -- Estimated Time: Total implementation time -- Recommended Execution: "Agent" - -```javascript -// Save planning results to session folder (same as Option B) -const planFile = `${sessionFolder}/plan.json` -Write(planFile, JSON.stringify(planObject, null, 2)) -``` - -**Artifact**: Saved to `{sessionFolder}/plan.json` for CLI/agent use - -**Option B: Agent-Based Planning (Medium/High Complexity)** - -Delegate to cli-lite-planning-agent: ```javascript Task( subagent_type="cli-lite-planning-agent", description="Generate detailed implementation plan", prompt=` - ## Task Description - ${task_description} +Generate implementation plan and write plan.json. - ## Exploration Context - ${JSON.stringify(explorationContext, null, 2) || "No exploration performed"} +## Output Schema Reference +~/.claude/workflows/cli-templates/schemas/plan-json-schema.json - ## User Clarifications - ${JSON.stringify(clarificationContext, null, 2) || "None provided"} +## Task Description +${task_description} - ## Complexity Level - ${complexity} +## Exploration Context +${sessionFolder}/exploration.json (if exists) - ## Your Task - 1. Execute CLI planning using Gemini (Qwen fallback) - 2. Parse CLI output and extract structured plan - 3. Enhance tasks with file paths and pattern references - 4. Generate planObject with: - - Summary (2-3 sentences) - - Approach (high-level strategy) - - Tasks (3-10 actionable steps) - - Estimated time (with breakdown) - - Recommended execution (Agent for Low, Codex for Medium/High) - 5. Return planObject (no file writes) +## User Clarifications +${JSON.stringify(clarificationContext) || "None"} - ## Quality Requirements - Each task MUST include: - - Action verb (Create/Update/Add/Implement/Refactor) - - Specific file path - - Detailed changes - - Pattern reference from exploration +## Complexity Level +${complexity} - Format: "{Action} in {file_path}: {details} following {pattern}" - ` +## Requirements +Generate plan.json with: +- summary: 2-3 sentence overview +- approach: High-level implementation strategy +- tasks: 3-10 structured tasks with: + - title, file, action, description + - implementation (3-7 steps) + - reference (pattern, files, examples) + - acceptance (2-4 criteria) +- estimated_time, recommended_execution, complexity +- _metadata: timestamp, source, planning_mode + +## Execution +1. Execute CLI planning using Gemini (Qwen fallback) +2. Parse output and structure plan +3. Write JSON: Write('${sessionFolder}/plan.json', jsonContent) +4. Return brief completion summary +` ) - -// Save planning results to session folder -const planFile = `${sessionFolder}/plan.json` -Write(planFile, JSON.stringify(planObject, null, 2)) ``` -**Output**: `planObject` (see Data Structures section) -**Artifact**: Saved to `{sessionFolder}/plan.json` for CLI/agent use - -**Progress Tracking**: -- Mark Phase 3 completed -- Mark Phase 4 in_progress - -**Expected Duration**: -- Low: 20-30 seconds (direct) -- Medium/High: 40-60 seconds (agent-based) +**Output**: `${sessionFolder}/plan.json` --- ### Phase 4: Task Confirmation & Execution Selection -**Two-Step Confirmation Process** +**Step 4.1: Display Plan** +```javascript +const plan = JSON.parse(Read(`${sessionFolder}/plan.json`)) -**Step 4.1: Display Plan Summary** - -Output complete plan as regular text: - -``` +console.log(` ## Implementation Plan -**Summary**: ${planObject.summary} +**Summary**: ${plan.summary} +**Approach**: ${plan.approach} -**Approach**: ${planObject.approach} +**Tasks** (${plan.tasks.length}): +${plan.tasks.map((t, i) => `${i+1}. ${t.title} (${t.file})`).join('\n')} -**Task Breakdown** (${planObject.tasks.length} tasks): -${planObject.tasks.map((task, i) => ` -${i+1}. **${task.title}** (${task.file}) - - What: ${task.description} - - How: ${task.implementation.length} steps - - Reference: ${task.reference.pattern} - - Verification: ${task.acceptance.length} criteria -`).join('')} - -**Complexity**: ${planObject.complexity} -**Estimated Time**: ${planObject.estimated_time} -**Recommended Execution**: ${planObject.recommended_execution} +**Complexity**: ${plan.complexity} +**Estimated Time**: ${plan.estimated_time} +**Recommended**: ${plan.recommended_execution} +`) ``` -**Step 4.2: Collect User Confirmation** - -Three questions via single AskUserQuestion call: - +**Step 4.2: Collect Confirmation** ```javascript AskUserQuestion({ questions: [ { - question: `**Plan Summary**: ${planObject.summary} - -**Tasks**: ${planObject.tasks.length} | **Complexity**: ${planObject.complexity} | **Time**: ${planObject.estimated_time} - -Confirm plan? (Multi-select: can supplement via "Other")`, - header: "Confirm Plan", + question: `Confirm plan? (${plan.tasks.length} tasks, ${plan.complexity})`, + header: "Confirm", multiSelect: true, options: [ { label: "Allow", description: "Proceed as-is" }, @@ -360,22 +242,22 @@ Confirm plan? (Multi-select: can supplement via "Other")`, ] }, { - question: "Select execution method:", + question: "Execution method:", header: "Execution", multiSelect: false, options: [ { label: "Agent", description: "@code-developer agent" }, { label: "Codex", description: "codex CLI tool" }, - { label: "Auto", description: `Auto: ${planObject.complexity === 'Low' ? 'Agent' : 'Codex'}` } + { label: "Auto", description: `Auto: ${plan.complexity === 'Low' ? 'Agent' : 'Codex'}` } ] }, { - question: "Enable code review after execution?\n\n(Custom tools via \"Other\": qwen, codex, etc.)", - header: "Code Review", + question: "Code review after execution?", + header: "Review", multiSelect: false, options: [ - { label: "Gemini Review", description: "Gemini CLI (gemini-2.5-pro)" }, - { label: "Agent Review", description: "@code-reviewer agent" }, + { label: "Gemini Review", description: "Gemini CLI" }, + { label: "Agent Review", description: "@code-reviewer" }, { label: "Skip", description: "No review" } ] } @@ -383,351 +265,95 @@ Confirm plan? (Multi-select: can supplement via "Other")`, }) ``` -**Decision Flow**: -``` -Task Confirmation (Multi-select): - ├─ Allow (+ supplements) → Execution Method Selection - ├─ Modify (+ supplements) → Re-run Phase 3 - └─ Cancel → Exit - -Execution Method (Single-select): - ├─ Agent → Launch @code-developer - ├─ Codex → Execute with codex CLI - └─ Auto → Low complexity: Agent | Medium/High: Codex - -Code Review (after execution): - ├─ Skip → No review - ├─ Gemini Review → gemini CLI analysis - ├─ Agent Review → Current Claude review - └─ Other → Custom tool (e.g., qwen, codex) -``` - -**Progress Tracking**: -- Mark Phase 4 completed -- Mark Phase 5 in_progress - --- ### Phase 5: Dispatch to Execution -**Step 5.1: Export Enhanced Task JSON** - -Always export Enhanced Task JSON to session folder: +**Step 5.1: Generate task.json** (by command, not agent) ```javascript const taskId = `LP-${shortTimestamp}` -const filename = `${sessionFolder}/task.json` +const exploration = file_exists(`${sessionFolder}/exploration.json`) + ? JSON.parse(Read(`${sessionFolder}/exploration.json`)) + : null +const plan = JSON.parse(Read(`${sessionFolder}/plan.json`)) -const enhancedTaskJson = { +const taskJson = { id: taskId, - title: original_task_description, + title: task_description, status: "pending", meta: { type: "planning", created_at: new Date().toISOString(), - complexity: planObject.complexity, - estimated_time: planObject.estimated_time, - recommended_execution: planObject.recommended_execution, + complexity: plan.complexity, + estimated_time: plan.estimated_time, + recommended_execution: plan.recommended_execution, workflow: "lite-plan", session_id: sessionId, session_folder: sessionFolder }, context: { - requirements: [original_task_description], + requirements: [task_description], plan: { - summary: planObject.summary, - approach: planObject.approach, - tasks: planObject.tasks + summary: plan.summary, + approach: plan.approach, + tasks: plan.tasks }, - exploration: explorationContext || null, + exploration: exploration, clarifications: clarificationContext || null, - focus_paths: explorationContext?.relevant_files || [], - acceptance: planObject.tasks.flatMap(t => t.acceptance) + focus_paths: exploration?.relevant_files || [], + acceptance: plan.tasks.flatMap(t => t.acceptance) } } -Write(filename, JSON.stringify(enhancedTaskJson, null, 2)) -console.log(`Enhanced Task JSON exported to: ${filename}`) -console.log(`Session folder: ${sessionFolder}`) -console.log(`Reuse with: /workflow:lite-execute ${filename}`) +Write(`${sessionFolder}/task.json`, JSON.stringify(taskJson, null, 2)) ``` -**Step 5.2: Store Execution Context** +**Step 5.2: Store executionContext** ```javascript executionContext = { - planObject: planObject, - explorationContext: explorationContext || null, + planObject: plan, + explorationContext: exploration, clarificationContext: clarificationContext || null, executionMethod: userSelection.execution_method, codeReviewTool: userSelection.code_review_tool, - originalUserInput: original_task_description, - - // Session artifacts location + originalUserInput: task_description, session: { id: sessionId, folder: sessionFolder, artifacts: { - exploration: explorationContext ? `${sessionFolder}/exploration.json` : null, + exploration: exploration ? `${sessionFolder}/exploration.json` : null, plan: `${sessionFolder}/plan.json`, - task: `${sessionFolder}/task.json` // Always exported + task: `${sessionFolder}/task.json` } } } ``` -**Step 5.3: Call lite-execute** +**Step 5.3: Dispatch** ```javascript SlashCommand(command="/workflow:lite-execute --in-memory") ``` -**Execution Handoff**: -- lite-execute reads `executionContext` variable from memory -- `executionContext.session.artifacts` contains file paths to saved planning artifacts: - - `exploration` - exploration.json (if exploration performed) - - `plan` - plan.json (always exists) - - `task` - task.json (if user selected export) -- All execution logic handled by lite-execute -- lite-plan completes after successful handoff +## Session Folder Structure -**Progress Tracking**: -- Mark Phase 5 completed -- Execution tracking delegated to lite-execute - -## Best Practices - -### Workflow Intelligence - -1. **Dynamic Adaptation**: Workflow adjusts based on task characteristics - - Smart exploration: Only when codebase context needed - - Adaptive planning: Simple → direct, complex → specialized agent - - Context-aware clarification: Only when truly needed - - Reduces unnecessary steps while maintaining thoroughness - -2. **Flag-Based Control**: Use `-e`/`--explore` to force exploration when: - - Task appears simple but requires codebase context - - Auto-detection might miss subtle integration points - - Comprehensive code understanding needed - -3. **Progressive Clarification**: Information gathered at right time - - Phase 1: Explore codebase (current state) - - Phase 2: Ask questions (based on findings) - - Phase 3: Plan with complete context - - Avoids premature assumptions, reduces rework - -4. **Complexity-Aware Planning**: Strategy matches task complexity - - Low (1-2 files): Direct planning (fast, 20-30s) - - Medium (3-5 files): CLI planning (detailed, 40-50s) - - High (6+ files): CLI planning with risk analysis (thorough, 50-60s) - -5. **Two-Step Confirmation**: Clear separation between plan and control - - Step 1: Display plan as readable text (not in question) - - Step 2: Collect multi-dimensional input - - Plan confirmation (multi-select with supplements) - - Execution method selection - - Code review tool selection (custom via "Other") - - Enhanced Task JSON always exported to session folder - - Allows plan refinement without re-selecting execution method - -### Task Management - -1. **Phase-Based Organization**: 5 distinct phases with clear transitions - - Phase 1: Analysis & Exploration (automatic) - - Phase 2: Clarification (conditional, interactive) - - Phase 3: Planning (automatic, adaptive) - - Phase 4: Confirmation (interactive, multi-dimensional) - - Phase 5: Execution Dispatch (automatic) - -2. **Flexible Task Counts**: Adapts to complexity - - Low: 3-5 tasks (focused) - - Medium: 5-7 tasks (detailed) - - High: 7-10 tasks (comprehensive) - -3. **Session Artifact Management**: - - All planning artifacts saved to dedicated session folder - - Enhanced Task JSON always exported for reusability - - Plan context passed to execution via memory and files - - Clean organization with session-based folder structure - -### Planning Standards - -1. **Context-Rich Planning**: Plans include all relevant context - - Exploration findings (structure, patterns, constraints) - - User clarifications (requirements, preferences, decisions) - - Complexity assessment (risks, dependencies, estimates) - - Execution recommendations (Direct vs CLI, specific tool) - -2. **Modification Support**: Iterative refinement - - User can request modifications in Phase 4 - - Feedback incorporated into re-planning - - No restart from scratch - - Collaborative planning workflow +``` +.workflow/.lite-plan/{task-slug}-{timestamp}/ +├── exploration.json # If exploration performed (by cli-explore-agent) +├── plan.json # Always created (by agent or direct planning) +└── task.json # Always created (by command) +``` ## Error Handling -| Error | Cause | Resolution | -|-------|-------|------------| -| Phase 1 Exploration Failure | cli-explore-agent unavailable/timeout | Skip exploration, set `explorationContext = null`, continue with task description only | -| Phase 2 Clarification Timeout | User no response > 5 minutes | Use exploration findings as-is, proceed to Phase 3 with warning | -| Phase 3 Planning Agent Failure | cli-lite-planning-agent unavailable/timeout | Fallback to direct planning by current Claude | -| Phase 3 Planning Timeout | Planning > 90 seconds | Generate simplified plan, mark as "Quick Plan", continue | -| Phase 4 Confirmation Timeout | User no response > 5 minutes | Save context to temp var, display resume instructions, exit gracefully | -| Phase 4 Modification Loop | User requests modify > 3 times | Suggest breaking task into smaller pieces or using `/workflow:plan` | - -## Session Folder Structure - -Each lite-plan execution creates a dedicated session folder to organize all artifacts: - -``` -.workflow/.lite-plan/{task-slug}-{short-timestamp}/ -├── exploration.json # Exploration results (if exploration performed) -├── plan.json # Planning results (always created) -└── task.json # Enhanced Task JSON (always created) -``` - -**Folder Naming Convention**: -- `{task-slug}`: First 40 characters of task description, lowercased, non-alphanumeric replaced with `-` -- `{short-timestamp}`: YYYY-MM-DD-HH-mm-ss format -- Example: `.workflow/.lite-plan/implement-user-auth-jwt-2025-01-15-14-30-45/` - -**File Contents**: -- `exploration.json`: Complete explorationContext object (if exploration performed, see Data Structures) -- `plan.json`: Complete planObject (always created, see Data Structures) -- `task.json`: Enhanced Task JSON with all context (always created, see Data Structures) - -**Access Patterns**: -- **lite-plan**: Creates folder and writes all artifacts during execution, passes paths via `executionContext.session.artifacts` -- **lite-execute**: Reads artifact paths from `executionContext.session.artifacts` (see lite-execute.md for usage details) -- **User**: Can inspect artifacts for debugging or reference -- **Reuse**: Pass `task.json` path to `/workflow:lite-execute {path}` for re-execution - - -## 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: [ // 3-10 structured task objects - { - title: string, // Task title - file: string, // Target file path - action: string, // Create|Update|Implement|Refactor|Add|Delete - description: string, // What to implement (1-2 sentences) - implementation: string[], // Step-by-step how-to (3-7 steps) - reference: { // What to reference - pattern: string, // Pattern name - files: string[], // Reference file paths - examples: string // Specific guidance - }, - acceptance: string[] // Verification criteria (2-4 items) - } - ], - estimated_time: string, // Total implementation time - 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: { // Complete planObject (see above) - summary: string, - approach: string, - tasks: [...], - estimated_time: string, - recommended_execution: string, - complexity: string - }, - explorationContext: {...} | null, // See explorationContext 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 - - // Session artifacts location (for lite-execute to access saved files) - session: { - id: string, // Session identifier: {taskSlug}-{shortTimestamp} - folder: string, // Session folder path: .workflow/.lite-plan/{session-id} - artifacts: { - exploration: string | null, // exploration.json path (if exploration performed) - plan: string, // plan.json path (always present) - task: string // task.json path (always exported) - } - } -} -``` - -### Enhanced Task JSON Export - -When user selects "Export JSON", lite-plan exports this structure: - -```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 strategy", - "tasks": [/* Array of task objects */] - }, - "exploration": {/* explorationContext */} | null, - "clarifications": {/* clarificationContext */} | null, - "focus_paths": ["src/auth", "tests/auth"], - "acceptance": ["Criteria from plan.tasks"] - } -} -``` - -**Schema Notes**: -- Aligns with Enhanced Task JSON Schema (6-field structure) -- `context_package_path` omitted (not used by lite-plan) -- `flow_control` omitted (handled by lite-execute) -- `focus_paths` derived from `exploration.relevant_files` -- `acceptance` derived from `plan.tasks` +| 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 /workflow:plan | diff --git a/.claude/workflows/cli-templates/schemas/explore-json-schema.json b/.claude/workflows/cli-templates/schemas/explore-json-schema.json new file mode 100644 index 00000000..be208a8b --- /dev/null +++ b/.claude/workflows/cli-templates/schemas/explore-json-schema.json @@ -0,0 +1,90 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Exploration Context Schema", + "description": "Code exploration results from cli-explore-agent for task context gathering", + "type": "object", + "required": [ + "project_structure", + "relevant_files", + "patterns", + "dependencies", + "integration_points", + "constraints", + "clarification_needs", + "_metadata" + ], + "properties": { + "project_structure": { + "type": "string", + "description": "Overall architecture description: module organization, layer structure, component relationships" + }, + "relevant_files": { + "type": "array", + "items": {"type": "string"}, + "description": "File paths to be modified or referenced for the task" + }, + "patterns": { + "type": "string", + "description": "Existing code patterns, conventions, and styles found in the codebase" + }, + "dependencies": { + "type": "string", + "description": "External and internal module dependencies relevant to the task" + }, + "integration_points": { + "type": "string", + "description": "Where this task connects with existing code: APIs, hooks, events, shared state" + }, + "constraints": { + "type": "string", + "description": "Technical constraints and limitations affecting implementation" + }, + "clarification_needs": { + "type": "array", + "items": { + "type": "object", + "required": ["question", "context", "options"], + "properties": { + "question": { + "type": "string", + "description": "The clarification question to ask user" + }, + "context": { + "type": "string", + "description": "Background context explaining why this clarification is needed" + }, + "options": { + "type": "array", + "items": {"type": "string"}, + "description": "Available options for user to choose from (2-4 options)" + } + } + }, + "description": "Ambiguities requiring user input before planning" + }, + "_metadata": { + "type": "object", + "required": ["timestamp", "task_description", "source"], + "properties": { + "timestamp": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of exploration" + }, + "task_description": { + "type": "string", + "description": "Original task description that triggered exploration" + }, + "source": { + "type": "string", + "const": "cli-explore-agent", + "description": "Agent that performed exploration" + }, + "duration_seconds": { + "type": "integer", + "description": "Exploration duration in seconds" + } + } + } + } +} diff --git a/.claude/workflows/cli-templates/schemas/plan-json-schema.json b/.claude/workflows/cli-templates/schemas/plan-json-schema.json new file mode 100644 index 00000000..652bfb42 --- /dev/null +++ b/.claude/workflows/cli-templates/schemas/plan-json-schema.json @@ -0,0 +1,127 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Plan Object Schema", + "description": "Implementation plan from cli-lite-planning-agent or direct planning", + "type": "object", + "required": [ + "summary", + "approach", + "tasks", + "estimated_time", + "recommended_execution", + "complexity", + "_metadata" + ], + "properties": { + "summary": { + "type": "string", + "description": "2-3 sentence overview of the implementation plan" + }, + "approach": { + "type": "string", + "description": "High-level implementation strategy and methodology" + }, + "tasks": { + "type": "array", + "minItems": 3, + "maxItems": 10, + "items": { + "type": "object", + "required": ["title", "file", "action", "description", "implementation", "reference", "acceptance"], + "properties": { + "title": { + "type": "string", + "description": "Task title (action verb + target)" + }, + "file": { + "type": "string", + "description": "Target file path for this task" + }, + "action": { + "type": "string", + "enum": ["Create", "Update", "Implement", "Refactor", "Add", "Delete", "Configure", "Test"], + "description": "Primary action type" + }, + "description": { + "type": "string", + "description": "What to implement (1-2 sentences)" + }, + "implementation": { + "type": "array", + "items": {"type": "string"}, + "minItems": 3, + "maxItems": 7, + "description": "Step-by-step implementation guide" + }, + "reference": { + "type": "object", + "required": ["pattern", "files", "examples"], + "properties": { + "pattern": { + "type": "string", + "description": "Pattern name to follow" + }, + "files": { + "type": "array", + "items": {"type": "string"}, + "description": "Reference file paths to study" + }, + "examples": { + "type": "string", + "description": "Specific guidance or example references" + } + }, + "description": "Reference materials for implementation" + }, + "acceptance": { + "type": "array", + "items": {"type": "string"}, + "minItems": 2, + "maxItems": 4, + "description": "Verification criteria for task completion" + } + } + }, + "description": "Structured task breakdown (3-10 tasks)" + }, + "estimated_time": { + "type": "string", + "description": "Total estimated implementation time (e.g., '30 minutes', '2 hours')" + }, + "recommended_execution": { + "type": "string", + "enum": ["Agent", "Codex"], + "description": "Recommended execution method based on complexity" + }, + "complexity": { + "type": "string", + "enum": ["Low", "Medium", "High"], + "description": "Task complexity level" + }, + "_metadata": { + "type": "object", + "required": ["timestamp", "source", "planning_mode"], + "properties": { + "timestamp": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of planning" + }, + "source": { + "type": "string", + "enum": ["cli-lite-planning-agent", "direct-planning"], + "description": "Planning source" + }, + "planning_mode": { + "type": "string", + "enum": ["direct", "agent-based"], + "description": "Planning execution mode" + }, + "duration_seconds": { + "type": "integer", + "description": "Planning duration in seconds" + } + } + } + } +}