mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
feat(workflow): add lite-plan command for intelligent task planning and execution
This commit is contained in:
catlog22
972
.claude/commands/workflow/lite-plan.md
Normal file
972
.claude/commands/workflow/lite-plan.md
Normal file
@@ -0,0 +1,972 @@
|
||||
---
|
||||
name: lite-plan
|
||||
description: Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation
|
||||
argument-hint: "[--tool claude|gemini|qwen|codex] [--quick] \"task description\"|file.md"
|
||||
allowed-tools: TodoWrite(*), Task(*), Bash(*), AskUserQuestion(*)
|
||||
timeout: 180000
|
||||
color: cyan
|
||||
---
|
||||
|
||||
# Workflow Lite-Plan Command (/workflow:lite-plan)
|
||||
|
||||
## Overview
|
||||
|
||||
Intelligent lightweight planning and execution command with dynamic workflow adaptation based on task complexity.
|
||||
|
||||
**Key Characteristics**:
|
||||
- Dynamic Workflow: Automatically decides whether to use exploration, clarification, and detailed planning
|
||||
- Smart Exploration: Calls cli-explore-agent only when task requires codebase context
|
||||
- Interactive Clarification: Asks user for more information after exploration if needed
|
||||
- Adaptive Planning: Simple tasks get direct planning, complex tasks use cli-planning-agent
|
||||
- Two-Dimensional Confirmation: User confirms task + selects execution method in one step
|
||||
- Direct Execution: Immediately starts execution (agent or CLI) after confirmation
|
||||
- Live Progress Tracking: Uses TodoWrite to track execution progress in real-time
|
||||
|
||||
## Core Functionality
|
||||
|
||||
- **Intelligent Task Analysis**: Automatically determines if exploration/planning agents are needed
|
||||
- **Dynamic Exploration**: Calls cli-explore-agent only when task requires codebase understanding
|
||||
- **Interactive Clarification**: Asks follow-up questions after exploration to gather missing information
|
||||
- **Adaptive Planning**:
|
||||
- Simple tasks: Direct planning by current Claude
|
||||
- Complex tasks: Delegates to cli-planning-agent for detailed breakdown
|
||||
- **Two-Dimensional Confirmation**: Single user interaction for task approval + execution method selection
|
||||
- **Direct Execution**: Immediate dispatch to selected execution method (agent or CLI)
|
||||
- **Live Progress Tracking**: Real-time TodoWrite updates during execution
|
||||
|
||||
## Comparison with Other Commands
|
||||
|
||||
| Feature | lite-plan | /cli:mode:plan | /workflow:plan |
|
||||
|---------|-----------|----------------|----------------|
|
||||
| Workflow Adaptation | Dynamic (intelligent) | Fixed | Fixed |
|
||||
| Code Exploration | Smart (when needed) | No | Always (context-search) |
|
||||
| Clarification | Yes (interactive) | No | No |
|
||||
| Planning Strategy | Adaptive (simple/complex) | Fixed template | Agent-based |
|
||||
| User Interaction | Two-dimensional | No | Minimal |
|
||||
| Direct Execution | Yes (immediate) | Yes (immediate) | No (requires /workflow:execute) |
|
||||
| Progress Tracking | Yes (TodoWrite live) | No | Yes (session-based) |
|
||||
| Execution Time | Fast (1-3 min) | Fast (2-5 min) | Slow (5-10 min) |
|
||||
| Tool Selection | User choice | --tool flag | Fixed (agent only) |
|
||||
| File Artifacts | No | No | Yes (IMPL_PLAN.md + JSON) |
|
||||
|
||||
## Usage
|
||||
|
||||
### Command Syntax
|
||||
```bash
|
||||
/workflow:lite-plan [FLAGS] <TASK_DESCRIPTION>
|
||||
|
||||
# Flags
|
||||
--tool <tool-name> Preset CLI tool (claude|gemini|qwen|codex); if not provided, user selects during confirmation
|
||||
--quick Skip code exploration phase (fast mode, completes within 60 seconds)
|
||||
|
||||
# Arguments
|
||||
<task-description> Task description or path to .md file (required)
|
||||
```
|
||||
|
||||
### Usage Examples
|
||||
```bash
|
||||
# Standard planning with full interaction
|
||||
/workflow:lite-plan "Implement user authentication with JWT tokens"
|
||||
# -> Shows plan, user confirms, selects tool, immediate execution
|
||||
|
||||
# Quick mode with preset tool
|
||||
/workflow:lite-plan --quick --tool gemini "Refactor logging module for better performance"
|
||||
# -> Skips exploration, user confirms plan, executes with Gemini
|
||||
|
||||
# Codex direct execution preset
|
||||
/workflow:lite-plan --tool codex "Add unit tests for authentication service"
|
||||
# -> User only confirms plan, executes with Codex immediately
|
||||
|
||||
# Agent mode with Claude
|
||||
/workflow:lite-plan "Design new API endpoints for payment processing"
|
||||
# -> User selects Claude agent, immediate execution
|
||||
```
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Workflow Overview
|
||||
|
||||
```
|
||||
User Input ("/workflow:lite-plan \"task\"")
|
||||
|
|
||||
v
|
||||
[Phase 1] Task Analysis & Exploration Decision (10-20 seconds)
|
||||
-> Analyze task description
|
||||
-> Decision: Need exploration? (Yes/No/--quick override)
|
||||
-> If Yes: Launch cli-explore-agent
|
||||
-> Output: exploration findings (if performed)
|
||||
|
|
||||
v
|
||||
[Phase 2] Clarification (Optional, user interaction)
|
||||
-> If exploration revealed ambiguities or missing info
|
||||
-> AskUserQuestion: Gather clarifications
|
||||
-> Update task context with user responses
|
||||
-> If no clarification needed: Skip to Phase 3
|
||||
|
|
||||
v
|
||||
[Phase 3] Complexity Assessment & Planning (20-60 seconds)
|
||||
-> Assess task complexity (Low/Medium/High)
|
||||
-> Decision: Planning strategy
|
||||
- Low: Direct planning (current Claude)
|
||||
- Medium/High: Delegate to cli-planning-agent
|
||||
-> Output: Task breakdown with execution approach
|
||||
|
|
||||
v
|
||||
[Phase 4] Task Confirmation & Execution Selection (User interaction)
|
||||
-> Display task breakdown and approach
|
||||
-> AskUserQuestion: Two dimensions
|
||||
1. Confirm task (Yes/Modify/Cancel)
|
||||
2. Execution method (Direct/CLI)
|
||||
-> If confirmed: Proceed to Phase 5
|
||||
-> If modify: Re-run planning with feedback
|
||||
-> If cancel: Exit
|
||||
|
|
||||
v
|
||||
[Phase 5] Execution & Progress Tracking
|
||||
-> Create TodoWrite task list from breakdown
|
||||
-> Launch selected execution (agent or CLI)
|
||||
-> Track progress with TodoWrite updates
|
||||
-> Real-time status displayed to user
|
||||
|
|
||||
v
|
||||
Execution Complete
|
||||
```
|
||||
|
||||
### Task Management Pattern
|
||||
|
||||
- TodoWrite creates task list before execution starts (Phase 5)
|
||||
- Tasks marked as in_progress/completed during execution
|
||||
- Real-time progress updates visible to user
|
||||
- No intermediate file artifacts generated
|
||||
|
||||
## Detailed Phase Execution
|
||||
|
||||
### Phase 1: Task Analysis & Exploration Decision
|
||||
|
||||
**Operations**:
|
||||
- Analyze task description to determine if code exploration is needed
|
||||
- Decision logic:
|
||||
```javascript
|
||||
needsExploration = (
|
||||
task.mentions_specific_files ||
|
||||
task.requires_codebase_context ||
|
||||
task.needs_architecture_understanding ||
|
||||
task.modifies_existing_code
|
||||
) && !flags.includes('--quick')
|
||||
```
|
||||
|
||||
**Decision Criteria**:
|
||||
|
||||
| Task Type | Needs Exploration | Reason |
|
||||
|-----------|-------------------|--------|
|
||||
| "Implement new feature X" | Maybe | Depends on integration with existing code |
|
||||
| "Refactor module Y" | Yes | Needs understanding of current implementation |
|
||||
| "Add tests for Z" | Yes | Needs to understand code structure |
|
||||
| "Create new standalone utility" | No | Self-contained, no existing code context |
|
||||
| "Update documentation" | No | Doesn't require code exploration |
|
||||
| "Fix bug in function F" | Yes | Needs to understand implementation |
|
||||
|
||||
**If Exploration Needed**:
|
||||
- Launch cli-explore-agent with task-specific focus
|
||||
- Agent call format:
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
description="Analyze codebase for task context",
|
||||
prompt=`
|
||||
Task: ${task_description}
|
||||
|
||||
Analyze:
|
||||
- Relevant files and modules
|
||||
- Current implementation patterns
|
||||
- Dependencies and integration points
|
||||
- Architecture constraints
|
||||
|
||||
Time Limit: 60 seconds
|
||||
Output: Findings summary + clarification needs
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Output Processing**:
|
||||
- Store exploration findings in `explorationContext`
|
||||
- Identify clarification needs (ambiguities, missing info, assumptions)
|
||||
- Set `needsClarification` flag if questions exist
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 1 as completed
|
||||
- If needsClarification: Mark Phase 2 as in_progress
|
||||
- Else: Skip to Phase 3
|
||||
|
||||
**Expected Duration**: 10-20 seconds (analysis) + 30-60 seconds (exploration if needed)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Clarification (Optional)
|
||||
|
||||
**Skip Condition**: Only run if Phase 1 set `needsClarification = true`
|
||||
|
||||
**Operations**:
|
||||
- Review exploration findings for ambiguities
|
||||
- Generate clarification questions based on:
|
||||
- Missing requirements
|
||||
- Ambiguous specifications
|
||||
- Multiple implementation options
|
||||
- Unclear dependencies or constraints
|
||||
- Assumptions that need confirmation
|
||||
|
||||
**AskUserQuestion Format**:
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "Based on code exploration, I need clarification on: ...",
|
||||
header: "Clarify Requirements",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
// Dynamic options based on exploration findings
|
||||
// Example: "Which authentication method?" -> Options: JWT, OAuth2, Session
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**Example Clarification Scenarios**:
|
||||
|
||||
| Exploration Finding | Clarification Question | Options |
|
||||
|---------------------|------------------------|---------|
|
||||
| "Found 2 auth patterns: JWT and Session" | "Which authentication approach to use?" | JWT / Session-based / Hybrid |
|
||||
| "API uses both REST and GraphQL" | "Which API style for new endpoints?" | REST / GraphQL / Both |
|
||||
| "No existing test framework found" | "Which test framework to set up?" | Jest / Vitest / Mocha |
|
||||
| "Multiple state management libraries" | "Which state manager to use?" | Redux / Zustand / Context |
|
||||
|
||||
**Output Processing**:
|
||||
- Collect user responses
|
||||
- Update task context with clarifications
|
||||
- Store in `clarificationContext` variable
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 2 as completed
|
||||
- Mark Phase 3 as in_progress
|
||||
|
||||
**Expected Duration**: User-dependent (typically 30-60 seconds)
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Complexity Assessment & Planning
|
||||
|
||||
**Operations**:
|
||||
- Assess task complexity based on multiple factors
|
||||
- Select appropriate planning strategy
|
||||
- Generate task breakdown using selected method
|
||||
|
||||
**Complexity Assessment Factors**:
|
||||
```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
|
||||
}
|
||||
|
||||
// Calculate complexity
|
||||
if (complexityScore < 3) complexity = "Low"
|
||||
else if (complexityScore < 6) complexity = "Medium"
|
||||
else complexity = "High"
|
||||
```
|
||||
|
||||
**Complexity Levels**:
|
||||
|
||||
| Level | Characteristics | Planning Strategy |
|
||||
|-------|----------------|-------------------|
|
||||
| Low | 1-2 files, simple changes, clear requirements | Direct planning (current Claude) |
|
||||
| Medium | 3-5 files, moderate integration, some ambiguity | Delegate to cli-planning-agent |
|
||||
| High | 6+ files, complex architecture, high uncertainty | Delegate to cli-planning-agent with detailed analysis |
|
||||
|
||||
**Planning Execution**:
|
||||
|
||||
**Option A: Direct Planning (Low Complexity)**
|
||||
```javascript
|
||||
// Current Claude generates plan directly
|
||||
planObject = {
|
||||
summary: "Brief overview of what needs to be done",
|
||||
approach: "Step-by-step implementation strategy",
|
||||
tasks: [
|
||||
"Task 1: Specific action with file references",
|
||||
"Task 2: Specific action with file references",
|
||||
// ... 3-5 tasks
|
||||
],
|
||||
complexity: "Low",
|
||||
estimated_time: "15-30 minutes"
|
||||
}
|
||||
```
|
||||
|
||||
**Option B: Agent-Based Planning (Medium/High Complexity)**
|
||||
```javascript
|
||||
// Delegate to cli-planning-agent
|
||||
Task(
|
||||
subagent_type="cli-planning-agent",
|
||||
description="Generate detailed implementation plan",
|
||||
prompt=`
|
||||
Task: ${task_description}
|
||||
|
||||
Exploration Context:
|
||||
${explorationContext}
|
||||
|
||||
Clarifications:
|
||||
${clarificationContext || "None"}
|
||||
|
||||
Complexity: ${complexity}
|
||||
|
||||
Generate detailed task breakdown with:
|
||||
- Clear task dependencies
|
||||
- Specific file modifications
|
||||
- Test requirements
|
||||
- Rollback considerations (if High complexity)
|
||||
- Risk assessment
|
||||
|
||||
Output: Structured task list (5-10 tasks)
|
||||
`
|
||||
)
|
||||
|
||||
// Agent returns detailed plan
|
||||
planObject = agent_output.parse()
|
||||
```
|
||||
|
||||
**Output Structure**:
|
||||
```javascript
|
||||
planObject = {
|
||||
summary: "2-3 sentence overview",
|
||||
approach: "Implementation strategy",
|
||||
tasks: [
|
||||
"Task 1: ...",
|
||||
"Task 2: ...",
|
||||
// ... 3-10 tasks based on complexity
|
||||
],
|
||||
complexity: "Low|Medium|High",
|
||||
dependencies: ["task1 -> task2", ...], // if Medium/High
|
||||
risks: ["risk1", "risk2", ...], // if High
|
||||
estimated_time: "X minutes",
|
||||
recommended_execution: "Direct|CLI"
|
||||
}
|
||||
```
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 3 as completed
|
||||
- Mark Phase 4 as in_progress
|
||||
|
||||
**Expected Duration**:
|
||||
- Low complexity: 20-30 seconds (direct)
|
||||
- Medium/High complexity: 40-60 seconds (agent-based)
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Task Confirmation & Execution Selection
|
||||
|
||||
**User Interaction Flow**: Two-dimensional confirmation (task + execution method)
|
||||
|
||||
**Operations**:
|
||||
- Display plan summary with full task breakdown
|
||||
- Two-dimensional user input: Task confirmation + Execution method selection
|
||||
- Support modification flow if user requests changes
|
||||
|
||||
**AskUserQuestion Format** (Two questions):
|
||||
|
||||
**Question 1: Task Confirmation**
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: `
|
||||
Implementation Plan:
|
||||
|
||||
Summary: ${planObject.summary}
|
||||
|
||||
Approach: ${planObject.approach}
|
||||
|
||||
Task Breakdown (${planObject.tasks.length} tasks):
|
||||
${planObject.tasks.map((t, i) => ` ${i+1}. ${t}`).join('\n')}
|
||||
|
||||
${planObject.dependencies ? `\nDependencies:\n${planObject.dependencies.join('\n')}` : ''}
|
||||
${planObject.risks ? `\nRisks:\n${planObject.risks.join('\n')}` : ''}
|
||||
|
||||
Complexity: ${planObject.complexity}
|
||||
Estimated Time: ${planObject.estimated_time}
|
||||
|
||||
Do you confirm this implementation plan?`,
|
||||
header: "Confirm Tasks",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Confirm - Proceed to execution",
|
||||
description: "Tasks look good, ready to execute"
|
||||
},
|
||||
{
|
||||
label: "Modify - Adjust plan",
|
||||
description: "Need to adjust tasks or approach"
|
||||
},
|
||||
{
|
||||
label: "Cancel - Abort",
|
||||
description: "Don't execute, abort this planning session"
|
||||
}
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
**If Confirm**: Proceed to Question 2
|
||||
**If Modify**:
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "What would you like to modify about the plan?",
|
||||
header: "Plan Modifications",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Add specific requirements",
|
||||
description: "Provide additional requirements or constraints"
|
||||
},
|
||||
{
|
||||
label: "Remove/simplify tasks",
|
||||
description: "Some tasks are unnecessary or too detailed"
|
||||
},
|
||||
{
|
||||
label: "Change approach",
|
||||
description: "Different implementation strategy needed"
|
||||
},
|
||||
{
|
||||
label: "Clarify ambiguities",
|
||||
description: "Tasks are unclear or ambiguous"
|
||||
}
|
||||
]
|
||||
}]
|
||||
})
|
||||
// After modification input, re-run Phase 3 with user feedback
|
||||
```
|
||||
|
||||
**Question 2: Execution Method Selection** (Only if confirmed)
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: `
|
||||
Select execution method:
|
||||
|
||||
${planObject.recommended_execution === "Direct" ? "[Recommended] " : ""}Direct Execution (Agent):
|
||||
- Current Claude agent executes tasks with full context
|
||||
- Interactive progress tracking
|
||||
- Best for: Complex logic, iterative development
|
||||
|
||||
${planObject.recommended_execution === "CLI" ? "[Recommended] " : ""}CLI Execution:
|
||||
- External CLI tool (Gemini/Codex/Qwen) executes tasks
|
||||
- Autonomous execution, faster for straightforward tasks
|
||||
- Best for: Clear requirements, bulk operations
|
||||
|
||||
Choose execution method:`,
|
||||
header: "Execution Method",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Direct - Execute with Agent",
|
||||
description: "Use @code-developer agent (interactive, recommended for ${planObject.complexity})"
|
||||
},
|
||||
{
|
||||
label: "CLI - Gemini",
|
||||
description: "Fast semantic analysis (gemini-2.5-pro)"
|
||||
},
|
||||
{
|
||||
label: "CLI - Codex",
|
||||
description: "Autonomous development (gpt-5)"
|
||||
},
|
||||
{
|
||||
label: "CLI - Qwen",
|
||||
description: "Code analysis specialist (coder-model)"
|
||||
}
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
**Decision Flow**:
|
||||
```
|
||||
Task Confirmation:
|
||||
├─ Confirm → Execution Method Selection → Phase 5
|
||||
├─ Modify → Collect feedback → Re-run Phase 3
|
||||
└─ Cancel → Exit (no execution)
|
||||
|
||||
Execution Method Selection:
|
||||
├─ Direct - Execute with Agent → Launch @code-developer
|
||||
├─ CLI - Gemini → Build and execute Gemini command
|
||||
├─ CLI - Codex → Build and execute Codex command
|
||||
└─ CLI - Qwen → Build and execute Qwen command
|
||||
```
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 4 as completed
|
||||
- Mark Phase 5 as in_progress
|
||||
|
||||
**Expected Duration**: User-dependent (1-3 minutes typical)
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Execution & Progress Tracking
|
||||
|
||||
**Operations**:
|
||||
- Create TodoWrite task list from plan breakdown
|
||||
- Launch selected execution method (agent or CLI)
|
||||
- Track execution progress with real-time TodoWrite updates
|
||||
- Display status to user
|
||||
|
||||
**Step 5.1: Create TodoWrite Task List**
|
||||
|
||||
**Before execution starts**, create task list:
|
||||
```javascript
|
||||
TodoWrite({
|
||||
todos: planObject.tasks.map((task, index) => ({
|
||||
content: task,
|
||||
status: "pending",
|
||||
activeForm: task.replace(/^(.*?):/, "$1ing:") // "Implement X" -> "Implementing X"
|
||||
}))
|
||||
})
|
||||
```
|
||||
|
||||
**Example Task List**:
|
||||
```
|
||||
[ ] Implement authentication service in src/auth/service.ts
|
||||
[ ] Create JWT token utilities in src/auth/jwt.ts
|
||||
[ ] Add authentication middleware to src/middleware/auth.ts
|
||||
[ ] Update API routes to use authentication
|
||||
[ ] Add integration tests for auth flow
|
||||
```
|
||||
|
||||
**Step 5.2: Launch Execution**
|
||||
|
||||
Based on user selection in Phase 4, execute appropriate method:
|
||||
|
||||
#### Option A: Direct Execution with Agent
|
||||
|
||||
**Operations**:
|
||||
- Launch @code-developer agent with full plan context
|
||||
- Agent receives exploration findings, clarifications, and task breakdown
|
||||
- Agent call format:
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="code-developer",
|
||||
description="Implement planned tasks with progress tracking",
|
||||
prompt=`
|
||||
Implement the following tasks with TodoWrite progress updates:
|
||||
|
||||
Summary: ${planObject.summary}
|
||||
|
||||
Task Breakdown:
|
||||
${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
|
||||
|
||||
${planObject.dependencies ? `\nTask Dependencies:\n${planObject.dependencies.join('\n')}` : ''}
|
||||
|
||||
Implementation Approach:
|
||||
${planObject.approach}
|
||||
|
||||
Code Context:
|
||||
${explorationContext || "No exploration performed"}
|
||||
|
||||
${clarificationContext ? `\nClarifications:\n${clarificationContext}` : ''}
|
||||
|
||||
${planObject.risks ? `\nRisks to Consider:\n${planObject.risks.join('\n')}` : ''}
|
||||
|
||||
IMPORTANT Instructions:
|
||||
- Update TodoWrite as you complete each task (mark as completed)
|
||||
- Follow task dependencies if specified
|
||||
- Implement tasks in sequence unless independent
|
||||
- Test functionality as you go
|
||||
- Handle risks proactively
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Agent Responsibilities**:
|
||||
- Mark tasks as in_progress when starting
|
||||
- Mark tasks as completed when finished
|
||||
- Update TodoWrite in real-time for user visibility
|
||||
|
||||
#### Option B: CLI Execution (Gemini/Codex/Qwen)
|
||||
|
||||
**Operations**:
|
||||
- Build CLI command with comprehensive context
|
||||
- Execute CLI tool with write permissions
|
||||
- Monitor CLI output and update TodoWrite based on progress indicators
|
||||
- Parse CLI completion signals to mark tasks as done
|
||||
|
||||
**Command Format (Gemini)** - Full context with exploration and clarifications:
|
||||
```bash
|
||||
gemini -p "
|
||||
PURPOSE: Implement planned tasks with full context from exploration and planning
|
||||
TASK:
|
||||
${planObject.tasks.map((t, i) => `• ${t}`).join('\n')}
|
||||
|
||||
MODE: write
|
||||
|
||||
CONTEXT: @**/* | Memory: Implementation plan from lite-plan workflow
|
||||
|
||||
## Exploration Findings
|
||||
${explorationContext ? `
|
||||
Project Structure:
|
||||
${explorationContext.project_structure || 'Not available'}
|
||||
|
||||
Relevant Files:
|
||||
${explorationContext.relevant_files?.join('\n') || 'Not specified'}
|
||||
|
||||
Current Implementation Patterns:
|
||||
${explorationContext.patterns || 'Not analyzed'}
|
||||
|
||||
Dependencies and Integration Points:
|
||||
${explorationContext.dependencies || 'Not specified'}
|
||||
|
||||
Architecture Constraints:
|
||||
${explorationContext.constraints || 'None identified'}
|
||||
` : 'No exploration performed (task did not require codebase context)'}
|
||||
|
||||
## User Clarifications
|
||||
${clarificationContext ? `
|
||||
The following clarifications were provided by the user after exploration:
|
||||
${Object.entries(clarificationContext).map(([q, a]) => `Q: ${q}\nA: ${a}`).join('\n\n')}
|
||||
` : 'No clarifications needed'}
|
||||
|
||||
## Implementation Plan Context
|
||||
Task Summary: ${planObject.summary}
|
||||
|
||||
Implementation Approach:
|
||||
${planObject.approach}
|
||||
|
||||
${planObject.dependencies ? `
|
||||
Task Dependencies (execute in order):
|
||||
${planObject.dependencies.join('\n')}
|
||||
` : ''}
|
||||
|
||||
${planObject.risks ? `
|
||||
Identified Risks:
|
||||
${planObject.risks.join('\n')}
|
||||
` : ''}
|
||||
|
||||
Complexity Level: ${planObject.complexity}
|
||||
Estimated Time: ${planObject.estimated_time}
|
||||
|
||||
EXPECTED: All tasks implemented following the plan approach, with proper error handling and testing
|
||||
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow implementation approach exactly | Handle identified risks proactively | write=CREATE/MODIFY/DELETE
|
||||
" -m gemini-2.5-pro --approval-mode yolo
|
||||
```
|
||||
|
||||
**Command Format (Codex)** - Session-based with resume support:
|
||||
|
||||
**First Execution (Establish Session)**:
|
||||
```bash
|
||||
codex --full-auto exec "
|
||||
TASK: ${planObject.summary}
|
||||
|
||||
## Task Breakdown
|
||||
${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
|
||||
|
||||
${planObject.dependencies ? `\n## Task Dependencies\n${planObject.dependencies.join('\n')}` : ''}
|
||||
|
||||
## Implementation Approach
|
||||
${planObject.approach}
|
||||
|
||||
## Code Context from Exploration
|
||||
${explorationContext ? `
|
||||
Project Structure: ${explorationContext.project_structure || 'Standard structure'}
|
||||
Relevant Files: ${explorationContext.relevant_files?.join(', ') || 'TBD'}
|
||||
Current Patterns: ${explorationContext.patterns || 'Follow existing conventions'}
|
||||
Integration Points: ${explorationContext.dependencies || 'None specified'}
|
||||
Constraints: ${explorationContext.constraints || 'None'}
|
||||
` : 'No prior exploration - analyze codebase as needed'}
|
||||
|
||||
${clarificationContext ? `\n## User Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `${q}: ${a}`).join('\n')}` : ''}
|
||||
|
||||
${planObject.risks ? `\n## Risks to Handle\n${planObject.risks.join('\n')}` : ''}
|
||||
|
||||
## Execution Instructions
|
||||
- Complete all tasks following the breakdown sequence
|
||||
- Respect task dependencies if specified
|
||||
- Test functionality as you implement
|
||||
- Handle identified risks proactively
|
||||
- Create session for potential resume if needed
|
||||
|
||||
Complexity: ${planObject.complexity}
|
||||
" -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Subsequent Executions (Resume if needed)**:
|
||||
```bash
|
||||
# If first execution fails or is interrupted, can resume:
|
||||
codex --full-auto exec "
|
||||
Continue implementation from previous session.
|
||||
|
||||
Remaining tasks:
|
||||
${remaining_tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
|
||||
|
||||
Maintain context from previous execution.
|
||||
" resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Codex Session Strategy**:
|
||||
- First execution establishes full context and creates session
|
||||
- If execution is interrupted or fails, use `resume --last` to continue
|
||||
- Resume inherits all context from original execution
|
||||
- Useful for complex tasks that may hit timeouts or require iteration
|
||||
|
||||
**Command Format (Qwen)** - Full context similar to Gemini:
|
||||
```bash
|
||||
qwen -p "
|
||||
PURPOSE: Implement planned tasks with comprehensive context
|
||||
|
||||
TASK:
|
||||
${planObject.tasks.map((t, i) => `• ${t}`).join('\n')}
|
||||
|
||||
MODE: write
|
||||
|
||||
CONTEXT: @**/* | Memory: Full implementation context from lite-plan
|
||||
|
||||
## Code Exploration Results
|
||||
${explorationContext ? `
|
||||
Analyzed Project Structure:
|
||||
${explorationContext.project_structure || 'Standard structure'}
|
||||
|
||||
Key Files to Modify:
|
||||
${explorationContext.relevant_files?.join('\n') || 'To be determined during implementation'}
|
||||
|
||||
Existing Code Patterns:
|
||||
${explorationContext.patterns || 'Follow codebase conventions'}
|
||||
|
||||
Dependencies:
|
||||
${explorationContext.dependencies || 'None specified'}
|
||||
|
||||
Constraints:
|
||||
${explorationContext.constraints || 'None identified'}
|
||||
` : 'No exploration performed - analyze codebase patterns as you implement'}
|
||||
|
||||
## Clarifications from User
|
||||
${clarificationContext ? `
|
||||
${Object.entries(clarificationContext).map(([question, answer]) => `
|
||||
Question: ${question}
|
||||
Answer: ${answer}
|
||||
`).join('\n')}
|
||||
` : 'No additional clarifications provided'}
|
||||
|
||||
## Implementation Strategy
|
||||
Summary: ${planObject.summary}
|
||||
|
||||
Approach:
|
||||
${planObject.approach}
|
||||
|
||||
${planObject.dependencies ? `
|
||||
Task Order (follow sequence):
|
||||
${planObject.dependencies.join('\n')}
|
||||
` : ''}
|
||||
|
||||
${planObject.risks ? `
|
||||
Risk Mitigation:
|
||||
${planObject.risks.join('\n')}
|
||||
` : ''}
|
||||
|
||||
Task Complexity: ${planObject.complexity}
|
||||
Time Estimate: ${planObject.estimated_time}
|
||||
|
||||
EXPECTED: Complete implementation with tests and proper error handling
|
||||
|
||||
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow approach strictly | Test thoroughly | write=CREATE/MODIFY/DELETE
|
||||
" -m coder-model --approval-mode yolo
|
||||
```
|
||||
|
||||
**Execution with Progress Tracking**:
|
||||
```javascript
|
||||
// Launch CLI in background
|
||||
bash_result = Bash(
|
||||
command=cli_command,
|
||||
timeout=600000, // 10 minutes
|
||||
run_in_background=true
|
||||
)
|
||||
|
||||
// Monitor output and update TodoWrite
|
||||
// Parse CLI output for task completion indicators
|
||||
// Update TodoWrite when tasks complete
|
||||
// Example: When CLI outputs "✓ Task 1 complete" -> Mark task 1 as completed
|
||||
```
|
||||
|
||||
**CLI Progress Monitoring**:
|
||||
- Parse CLI output for completion keywords ("done", "complete", "✓", etc.)
|
||||
- Update corresponding TodoWrite tasks based on progress
|
||||
- Provide real-time visibility to user
|
||||
|
||||
**Step 5.3: Track Execution Progress**
|
||||
|
||||
**Real-time TodoWrite Updates**:
|
||||
```javascript
|
||||
// As execution progresses, update task status:
|
||||
|
||||
// Task started
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "Implement auth service", status: "in_progress", activeForm: "Implementing auth service" },
|
||||
{ content: "Create JWT utilities", status: "pending", activeForm: "Creating JWT utilities" },
|
||||
// ...
|
||||
]
|
||||
})
|
||||
|
||||
// Task completed
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "Implement auth service", status: "completed", activeForm: "Implementing auth service" },
|
||||
{ content: "Create JWT utilities", status: "in_progress", activeForm: "Creating JWT utilities" },
|
||||
// ...
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**User Visibility**:
|
||||
- User sees real-time task progress
|
||||
- Current task highlighted as "in_progress"
|
||||
- Completed tasks marked with checkmark
|
||||
- Pending tasks remain unchecked
|
||||
|
||||
**Progress Tracking**:
|
||||
- Mark Phase 5 as in_progress throughout execution
|
||||
- Mark Phase 5 as completed when all tasks done
|
||||
- Final status summary displayed to user
|
||||
|
||||
**Expected Duration**: Varies by task complexity and execution method
|
||||
- Low complexity: 5-15 minutes
|
||||
- Medium complexity: 15-45 minutes
|
||||
- High complexity: 45-120 minutes
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Workflow Intelligence
|
||||
|
||||
1. **Dynamic Adaptation**: Workflow automatically adjusts based on task characteristics
|
||||
- Smart exploration: Only runs when task requires codebase context
|
||||
- Adaptive planning: Simple tasks get direct planning, complex tasks use specialized agent
|
||||
- Context-aware clarification: Only asks questions when truly needed
|
||||
- Reduces unnecessary steps while maintaining thoroughness
|
||||
|
||||
2. **Progressive Clarification**: Gather information at the right time
|
||||
- Phase 1: Explore codebase to understand current state
|
||||
- Phase 2: Ask clarifying questions based on exploration findings
|
||||
- Phase 3: Plan with complete context (task + exploration + clarifications)
|
||||
- Avoids premature assumptions and reduces rework
|
||||
|
||||
3. **Complexity-Aware Planning**: Planning strategy matches task complexity
|
||||
- Low complexity (1-2 files): Direct planning by current Claude (fast, 20-30s)
|
||||
- Medium complexity (3-5 files): CLI planning agent (detailed, 40-50s)
|
||||
- High complexity (6+ files): CLI planning agent with risk analysis (thorough, 50-60s)
|
||||
- Balances speed and thoroughness appropriately
|
||||
|
||||
4. **Two-Dimensional Confirmation**: Separate task approval from execution method
|
||||
- First dimension: Confirm/Modify/Cancel plan
|
||||
- Second dimension: Direct execution vs CLI execution
|
||||
- Allows plan refinement without re-selecting execution method
|
||||
- Supports iterative planning with user feedback
|
||||
|
||||
### Task Management
|
||||
|
||||
1. **Live Progress Tracking**: TodoWrite provides real-time execution visibility
|
||||
- Tasks created before execution starts
|
||||
- Updated in real-time as work progresses
|
||||
- User sees current task being worked on
|
||||
- Clear completion status throughout execution
|
||||
|
||||
2. **Phase-Based Organization**: 5 distinct phases with clear transitions
|
||||
- Phase 1: Task Analysis & Exploration (automatic)
|
||||
- Phase 2: Clarification (conditional, interactive)
|
||||
- Phase 3: Planning (automatic, adaptive)
|
||||
- Phase 4: Confirmation (interactive, two-dimensional)
|
||||
- Phase 5: Execution & Tracking (automatic with live updates)
|
||||
|
||||
3. **Flexible Task Counts**: Task breakdown adapts to complexity
|
||||
- Low complexity: 3-5 tasks (focused)
|
||||
- Medium complexity: 5-7 tasks (detailed)
|
||||
- High complexity: 7-10 tasks (comprehensive)
|
||||
- Avoids artificial constraints while maintaining focus
|
||||
|
||||
4. **Dependency Tracking**: Medium/High complexity tasks include dependencies
|
||||
- Explicit task ordering when sequence matters
|
||||
- Parallel execution hints when tasks are independent
|
||||
- Risk flagging for complex interactions
|
||||
- Helps agent/CLI execute correctly
|
||||
|
||||
### Planning Standards
|
||||
|
||||
1. **Context-Rich Planning**: Plans include all relevant context
|
||||
- Exploration findings (code structure, patterns, constraints)
|
||||
- User clarifications (requirements, preferences, decisions)
|
||||
- Complexity assessment (risks, dependencies, time estimates)
|
||||
- Execution recommendations (Direct vs CLI, specific tool)
|
||||
|
||||
2. **Modification Support**: Plans can be iteratively refined
|
||||
- User can request plan modifications in Phase 4
|
||||
- Feedback incorporated into re-planning
|
||||
- No need to restart from scratch
|
||||
- Supports collaborative planning workflow
|
||||
|
||||
3. **No File Artifacts**: All planning stays in memory
|
||||
- Faster workflow without I/O overhead
|
||||
- Cleaner workspace
|
||||
- Plan context passed directly to execution
|
||||
- Reduces complexity and maintenance
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Phase 1 Exploration Failure | cli-explore-agent unavailable or timeout | Skip exploration, set `explorationContext = null`, log warning, continue to Phase 2/3 with task description only |
|
||||
| Phase 2 Clarification Timeout | User no response > 5 minutes | Use exploration findings as-is without clarification, proceed to Phase 3 with warning |
|
||||
| Phase 3 Planning Agent Failure | cli-planning-agent unavailable or timeout | Fallback to direct planning by current Claude (simplified plan), continue to Phase 4 |
|
||||
| Phase 3 Planning Timeout | Planning takes > 90 seconds | Generate simplified direct plan, mark as "Quick Plan", continue to Phase 4 with reduced detail |
|
||||
| Phase 4 Confirmation Timeout | User no response > 5 minutes | Save plan context to temporary 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 for comprehensive planning |
|
||||
| Phase 5 CLI Tool Unavailable | Selected CLI tool not installed | Show installation instructions, offer to re-select (Direct execution or different CLI) |
|
||||
| Phase 5 Execution Failure | Agent/CLI crashes or errors | Display error details, save partial progress from TodoWrite, suggest manual recovery or retry |
|
||||
|
||||
## Input/Output
|
||||
|
||||
### 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):
|
||||
- `--tool <name>`: Preset execution tool (claude|gemini|codex|qwen)
|
||||
- `--quick`: Skip code exploration phase
|
||||
|
||||
### 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_tool: "Claude|Gemini|Codex|Qwen",
|
||||
estimated_time: "X minutes"
|
||||
}
|
||||
```
|
||||
|
||||
**Execution Result**:
|
||||
- Immediate dispatch to selected tool/agent with plan context
|
||||
- No file artifacts generated during planning phase
|
||||
- Execution starts immediately after user confirmation
|
||||
- Tool/agent handles implementation and any necessary file operations
|
||||
|
||||
Reference in New Issue
Block a user