mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-10 02:24:35 +08:00
470 lines
14 KiB
Markdown
470 lines
14 KiB
Markdown
---
|
|
description: Lightweight interactive planning workflow with direct exploration, outputs plan.json after user confirmation
|
|
argument-hint: TASK="<task description or file.md path>" [EXPLORE="true"]
|
|
---
|
|
|
|
# Workflow Lite-Plan Command
|
|
|
|
## Overview
|
|
|
|
Intelligent lightweight planning command with dynamic workflow adaptation based on task complexity. Focuses on planning phases (exploration, clarification, planning, confirmation) and outputs plan.json for subsequent execution.
|
|
|
|
**Core capabilities:**
|
|
- Intelligent task analysis with automatic exploration detection
|
|
- Direct code exploration (grep, find, file reading) when codebase understanding needed
|
|
- Interactive clarification after exploration to gather missing information
|
|
- Adaptive planning strategy based on complexity
|
|
- Two-step confirmation: plan display → user approval
|
|
- Outputs plan.json file after user confirmation
|
|
|
|
## Task Description
|
|
|
|
**Target task**: $TASK
|
|
**Force exploration**: $EXPLORE
|
|
|
|
## Execution Process
|
|
|
|
```
|
|
Phase 1: Task Analysis & Exploration
|
|
├─ Parse input (description or .md file)
|
|
├─ Intelligent complexity assessment (Low/Medium/High)
|
|
├─ Exploration decision (auto-detect or EXPLORE="true")
|
|
└─ Decision:
|
|
├─ needsExploration=true → Direct exploration using grep/find/read
|
|
└─ needsExploration=false → Skip to Phase 2/3
|
|
|
|
Phase 2: Clarification (optional)
|
|
├─ Aggregate clarification needs from exploration
|
|
├─ Output questions to user
|
|
└─ STOP and wait for user reply
|
|
|
|
Phase 3: Planning (NO CODE EXECUTION - planning only)
|
|
└─ Generate plan.json following schema
|
|
└─ MUST proceed to Phase 4
|
|
|
|
Phase 4: Confirmation
|
|
├─ Display plan summary (tasks, complexity, estimated time)
|
|
├─ Output confirmation request
|
|
└─ STOP and wait for user approval
|
|
|
|
Phase 5: Output
|
|
└─ Write plan.json to session folder
|
|
```
|
|
|
|
## Implementation
|
|
|
|
### Phase 1: Intelligent Direct Exploration
|
|
|
|
**Session Setup** (MANDATORY - follow exactly):
|
|
```javascript
|
|
// Helper: Get UTC+8 (China Standard Time) ISO string
|
|
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
|
|
|
|
const taskSlug = "$TASK".toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
|
|
const dateStr = getUtc8ISOString().substring(0, 10) // Format: 2025-11-29
|
|
|
|
const sessionId = `${taskSlug}-${dateStr}` // e.g., "implement-jwt-refresh-2025-11-29"
|
|
const sessionFolder = `.workflow/.lite-plan/${sessionId}`
|
|
|
|
// Create session folder
|
|
mkdir -p ${sessionFolder}
|
|
```
|
|
|
|
**Exploration Decision Logic**:
|
|
```javascript
|
|
needsExploration = (
|
|
"$EXPLORE" === "true" ||
|
|
task.mentions_specific_files ||
|
|
task.requires_codebase_context ||
|
|
task.needs_architecture_understanding ||
|
|
task.modifies_existing_code
|
|
)
|
|
|
|
if (!needsExploration) {
|
|
// Skip to Phase 2 (Clarification) or Phase 3 (Planning)
|
|
proceed_to_next_phase()
|
|
}
|
|
```
|
|
|
|
**Complexity Assessment** (Intelligent Analysis):
|
|
```javascript
|
|
// Analyzes task complexity based on:
|
|
// - Scope: How many systems/modules are affected?
|
|
// - Depth: Surface change vs architectural impact?
|
|
// - Risk: Potential for breaking existing functionality?
|
|
// - Dependencies: How interconnected is the change?
|
|
|
|
const complexity = analyzeTaskComplexity("$TASK")
|
|
// Returns: 'Low' | 'Medium' | 'High'
|
|
// Low: Single file, isolated change, minimal risk
|
|
// Medium: Multiple files, some dependencies, moderate risk
|
|
// High: Cross-module, architectural, high risk
|
|
|
|
// Angle assignment based on task type
|
|
const ANGLE_PRESETS = {
|
|
architecture: ['architecture', 'dependencies', 'modularity', 'integration-points'],
|
|
security: ['security', 'auth-patterns', 'dataflow', 'validation'],
|
|
performance: ['performance', 'bottlenecks', 'caching', 'data-access'],
|
|
bugfix: ['error-handling', 'dataflow', 'state-management', 'edge-cases'],
|
|
feature: ['patterns', 'integration-points', 'testing', 'dependencies']
|
|
}
|
|
|
|
function selectAngles(taskDescription, count) {
|
|
const text = taskDescription.toLowerCase()
|
|
let preset = 'feature' // default
|
|
|
|
if (/refactor|architect|restructure|modular/.test(text)) preset = 'architecture'
|
|
else if (/security|auth|permission|access/.test(text)) preset = 'security'
|
|
else if (/performance|slow|optimi|cache/.test(text)) preset = 'performance'
|
|
else if (/fix|bug|error|issue|broken/.test(text)) preset = 'bugfix'
|
|
|
|
return ANGLE_PRESETS[preset].slice(0, count)
|
|
}
|
|
|
|
const selectedAngles = selectAngles("$TASK", complexity === 'High' ? 4 : (complexity === 'Medium' ? 3 : 1))
|
|
|
|
console.log(`
|
|
## Exploration Plan
|
|
|
|
Task Complexity: ${complexity}
|
|
Selected Angles: ${selectedAngles.join(', ')}
|
|
|
|
Starting direct exploration...
|
|
`)
|
|
```
|
|
|
|
**Direct Exploration** (No Agent - Use grep/find/read directly):
|
|
|
|
```javascript
|
|
// For each selected angle, perform direct exploration
|
|
|
|
selectedAngles.forEach((angle, index) => {
|
|
console.log(`\n### Exploring: ${angle} (${index + 1}/${selectedAngles.length})`)
|
|
|
|
// Step 1: Structural Scan
|
|
// - Find relevant files using grep/rg
|
|
// - Analyze directory structure
|
|
// - Identify modules related to the angle
|
|
|
|
// Example commands:
|
|
// rg -l "keyword_from_task" --type ts
|
|
// find . -name "*.ts" -path "*auth*"
|
|
// tree -L 3 src/
|
|
|
|
// Step 2: Content Analysis
|
|
// - Read key files identified
|
|
// - Analyze patterns and conventions
|
|
// - Identify integration points
|
|
|
|
// Step 3: Document Findings
|
|
const explorationResult = {
|
|
angle: angle,
|
|
project_structure: [], // Modules/architecture relevant to angle
|
|
relevant_files: [], // Files affected from angle perspective
|
|
patterns: [], // Angle-related patterns to follow
|
|
dependencies: [], // Dependencies relevant to angle
|
|
integration_points: [], // Where to integrate from angle viewpoint
|
|
constraints: [], // Angle-specific limitations/conventions
|
|
clarification_needs: [], // Angle-related ambiguities
|
|
_metadata: {
|
|
exploration_angle: angle,
|
|
exploration_index: index + 1,
|
|
timestamp: getUtc8ISOString()
|
|
}
|
|
}
|
|
|
|
// Write exploration result
|
|
Write(`${sessionFolder}/exploration-${angle}.json`, JSON.stringify(explorationResult, null, 2))
|
|
})
|
|
```
|
|
|
|
**Build Exploration Manifest**:
|
|
```javascript
|
|
// After all explorations complete, build manifest
|
|
const explorationFiles = find(`${sessionFolder}`, "-name", "exploration-*.json")
|
|
|
|
const explorationManifest = {
|
|
session_id: sessionId,
|
|
task_description: "$TASK",
|
|
timestamp: getUtc8ISOString(),
|
|
complexity: complexity,
|
|
exploration_count: selectedAngles.length,
|
|
explorations: explorationFiles.map(file => {
|
|
const data = JSON.parse(Read(file))
|
|
return {
|
|
angle: data._metadata.exploration_angle,
|
|
file: path.basename(file),
|
|
path: file,
|
|
index: data._metadata.exploration_index
|
|
}
|
|
})
|
|
}
|
|
|
|
Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify(explorationManifest, null, 2))
|
|
|
|
console.log(`
|
|
## Exploration Complete
|
|
|
|
Generated exploration files in ${sessionFolder}:
|
|
${explorationManifest.explorations.map(e => `- exploration-${e.angle}.json (angle: ${e.angle})`).join('\n')}
|
|
|
|
Manifest: explorations-manifest.json
|
|
Angles explored: ${explorationManifest.explorations.map(e => e.angle).join(', ')}
|
|
`)
|
|
```
|
|
|
|
**Output**:
|
|
- `${sessionFolder}/exploration-{angle1}.json`
|
|
- `${sessionFolder}/exploration-{angle2}.json`
|
|
- ... (1-4 files based on complexity)
|
|
- `${sessionFolder}/explorations-manifest.json`
|
|
|
|
---
|
|
|
|
### Phase 2: Clarification (Optional)
|
|
|
|
**Skip if**: No exploration or `clarification_needs` is empty across all explorations
|
|
|
|
**Aggregate clarification needs from all exploration angles**:
|
|
```javascript
|
|
// Load manifest and all exploration files
|
|
const manifest = JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`))
|
|
const explorations = manifest.explorations.map(exp => ({
|
|
angle: exp.angle,
|
|
data: JSON.parse(Read(exp.path))
|
|
}))
|
|
|
|
// Aggregate clarification needs from all explorations
|
|
const allClarifications = []
|
|
explorations.forEach(exp => {
|
|
if (exp.data.clarification_needs?.length > 0) {
|
|
exp.data.clarification_needs.forEach(need => {
|
|
allClarifications.push({
|
|
...need,
|
|
source_angle: exp.angle
|
|
})
|
|
})
|
|
}
|
|
})
|
|
|
|
// Intelligent deduplication: analyze allClarifications by intent
|
|
// - Identify questions with similar intent across different angles
|
|
// - Merge similar questions: combine options, consolidate context
|
|
// - Produce dedupedClarifications with unique intents only
|
|
const dedupedClarifications = intelligentMerge(allClarifications)
|
|
```
|
|
|
|
**Output Questions and Wait for User Reply**:
|
|
```javascript
|
|
if (dedupedClarifications.length > 0) {
|
|
console.log(`
|
|
## Clarification Needed
|
|
|
|
Based on exploration, the following questions need your input:
|
|
|
|
${dedupedClarifications.map((need, index) => `
|
|
### Question ${index + 1}: [${need.source_angle}]
|
|
|
|
**${need.question}**
|
|
|
|
Context: ${need.context}
|
|
|
|
Options:
|
|
${need.options.map((opt, i) => ` ${i + 1}. ${opt}${need.recommended === i ? ' ★ (Recommended)' : ''}`).join('\n')}
|
|
`).join('\n')}
|
|
|
|
---
|
|
|
|
**Please reply with your choices** (e.g., "Q1: 2, Q2: 1, Q3: 3") to continue planning.
|
|
|
|
**WAITING FOR USER INPUT...**
|
|
`)
|
|
|
|
// STOP HERE - Wait for user reply before continuing to Phase 3
|
|
return
|
|
}
|
|
```
|
|
|
|
**After User Reply**: Store responses in `clarificationContext` and proceed to Phase 3.
|
|
|
|
---
|
|
|
|
### Phase 3: Planning
|
|
|
|
**IMPORTANT**: Phase 3 is **planning only** - NO code execution.
|
|
|
|
**Read Schema**:
|
|
```javascript
|
|
// Read plan schema for reference
|
|
const schema = Read("~/.claude/workflows/cli-templates/schemas/plan-json-schema.json")
|
|
```
|
|
|
|
**Read All Exploration Files**:
|
|
```javascript
|
|
// MANDATORY - Read and review ALL exploration files
|
|
const manifest = JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`))
|
|
manifest.explorations.forEach(exp => {
|
|
const explorationData = Read(exp.path)
|
|
console.log(`\n### Exploration: ${exp.angle}\n${explorationData}`)
|
|
})
|
|
```
|
|
|
|
**Generate Plan**:
|
|
```javascript
|
|
// Generate plan following schema
|
|
// Plan MUST incorporate insights from exploration files
|
|
const plan = {
|
|
summary: "Brief description of what will be implemented",
|
|
approach: "High-level approach and strategy",
|
|
tasks: [
|
|
// Each task: { id, title, description, scope, files, depends_on, execution_group, complexity }
|
|
// Group by feature/module, NOT by file
|
|
// 2-7 tasks recommended
|
|
],
|
|
estimated_time: "Total estimated time",
|
|
complexity: complexity, // Low | Medium | High
|
|
_metadata: {
|
|
timestamp: getUtc8ISOString(),
|
|
source: "lite-plan",
|
|
planning_mode: "direct",
|
|
exploration_angles: manifest.explorations.map(e => e.angle)
|
|
}
|
|
}
|
|
```
|
|
|
|
**Task Grouping Rules**:
|
|
1. **Group by feature**: All changes for one feature = one task (even if 3-5 files)
|
|
2. **Group by context**: Tasks with similar context or related functional changes can be grouped together
|
|
3. **Minimize task count**: Simple, unrelated tasks can also be grouped to reduce overhead
|
|
4. **Avoid file-per-task**: Do NOT create separate tasks for each file
|
|
5. **Substantial tasks**: Each task should represent 15-60 minutes of work
|
|
6. **True dependencies only**: Only use depends_on when Task B cannot start without Task A's output
|
|
7. **Prefer parallel**: Most tasks should be independent (no depends_on)
|
|
|
|
**Proceed to Phase 4** - DO NOT execute code here.
|
|
|
|
---
|
|
|
|
### Phase 4: Task Confirmation
|
|
|
|
**Display Plan Summary**:
|
|
```javascript
|
|
const plan = JSON.parse(Read(`${sessionFolder}/plan.json`))
|
|
|
|
console.log(`
|
|
## Implementation Plan
|
|
|
|
**Summary**: ${plan.summary}
|
|
**Approach**: ${plan.approach}
|
|
|
|
**Tasks** (${plan.tasks.length}):
|
|
${plan.tasks.map((t, i) => `
|
|
### Task ${i+1}: ${t.title}
|
|
- **Description**: ${t.description}
|
|
- **Scope**: ${t.scope}
|
|
- **Files**: ${t.files.join(', ')}
|
|
- **Complexity**: ${t.complexity}
|
|
- **Dependencies**: ${t.depends_on?.join(', ') || 'None'}
|
|
`).join('\n')}
|
|
|
|
**Overall Complexity**: ${plan.complexity}
|
|
**Estimated Time**: ${plan.estimated_time}
|
|
|
|
---
|
|
|
|
## Confirmation Required
|
|
|
|
Please review the plan above and reply with one of the following:
|
|
|
|
- **"Allow"** - Proceed with this plan, output plan.json
|
|
- **"Modify"** - Describe what changes you want to make
|
|
- **"Cancel"** - Abort the planning workflow
|
|
|
|
**WAITING FOR USER CONFIRMATION...**
|
|
`)
|
|
|
|
// STOP HERE - Wait for user confirmation before writing plan.json
|
|
return
|
|
```
|
|
|
|
---
|
|
|
|
### Phase 5: Output Plan File
|
|
|
|
**After User Confirms "Allow"**:
|
|
```javascript
|
|
// Write final plan.json to session folder
|
|
Write(`${sessionFolder}/plan.json`, JSON.stringify(plan, null, 2))
|
|
|
|
console.log(`
|
|
## Plan Output Complete
|
|
|
|
**Plan file written**: ${sessionFolder}/plan.json
|
|
|
|
**Session folder**: ${sessionFolder}
|
|
|
|
**Contents**:
|
|
- explorations-manifest.json
|
|
${manifest.explorations.map(e => `- exploration-${e.angle}.json`).join('\n')}
|
|
- plan.json
|
|
|
|
---
|
|
|
|
You can now use this plan with your preferred execution method:
|
|
- Manual implementation following the tasks
|
|
- Pass to another tool/agent for execution
|
|
- Import into project management system
|
|
`)
|
|
```
|
|
|
|
---
|
|
|
|
## Session Folder Structure
|
|
|
|
```
|
|
.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/
|
|
├── exploration-{angle1}.json # Exploration angle 1
|
|
├── exploration-{angle2}.json # Exploration angle 2
|
|
├── exploration-{angle3}.json # Exploration angle 3 (if applicable)
|
|
├── exploration-{angle4}.json # Exploration angle 4 (if applicable)
|
|
├── explorations-manifest.json # Exploration index
|
|
└── plan.json # Implementation plan (after confirmation)
|
|
```
|
|
|
|
**Example**:
|
|
```
|
|
.workflow/.lite-plan/implement-jwt-refresh-2025-11-25/
|
|
├── exploration-architecture.json
|
|
├── exploration-auth-patterns.json
|
|
├── exploration-security.json
|
|
├── explorations-manifest.json
|
|
└── plan.json
|
|
```
|
|
|
|
## Workflow States
|
|
|
|
| State | Action | Next |
|
|
|-------|--------|------|
|
|
| Phase 1 Complete | Exploration done | → Phase 2 or 3 |
|
|
| Phase 2 Output | Questions displayed | → Wait for user reply |
|
|
| User Replied | Clarifications received | → Phase 3 |
|
|
| Phase 3 Complete | Plan generated | → Phase 4 |
|
|
| Phase 4 Output | Plan displayed | → Wait for user confirmation |
|
|
| User: "Allow" | Confirmed | → Phase 5 (Write plan.json) |
|
|
| User: "Modify" | Changes requested | → Revise plan, back to Phase 4 |
|
|
| User: "Cancel" | Aborted | → End workflow |
|
|
|
|
## Error Handling
|
|
|
|
| Error | Resolution |
|
|
|-------|------------|
|
|
| Exploration failure | Skip exploration, continue with task description only |
|
|
| No relevant files found | Broaden search scope or proceed with minimal context |
|
|
| Clarification timeout | Use exploration findings as-is |
|
|
| Confirmation timeout | Save context, display resume instructions |
|
|
| Modify loop > 3 times | Suggest breaking task into smaller pieces |
|
|
|
|
---
|
|
|
|
**Now execute the lite-plan workflow for task**: $TASK
|