catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-12 02:37:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: add session folder structure for lite-plan artifacts

Browse Source 
- Create dedicated session folder (.workflow/.lite-plan/{task-slug}-{timestamp}/)
  for each lite-plan execution to organize all planning artifacts
- Always export task.json (removed optional export question from Phase 4)
- Save exploration.json, plan.json, and task.json to session folder
- Add session artifact paths to executionContext for lite-execute delegation
- Update lite-execute to use artifact file paths for CLI/agent context
- Enable CLI tools (Gemini/Qwen/Codex) and agents to access detailed
  planning context via file references

Benefits:
- Clean separation between different task executions
- All artifacts automatically saved for reusability
- Enhanced context available for execution phase
- Natural audit trail of planning sessions
This commit is contained in:
catlog22
2025-11-22 20:32:01 +08:00
parent 9f7e33cbde
commit a98b26b111
2 changed files with 194 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
.claude/commands/workflow/lite-execute.md
View File

@@ -323,12 +323,21 @@ ${result.notes ? `Notes: ${result.notes}` : ''}
${clarificationContext ? `\n## Clarifications\n${JSON.stringify(clarificationContext, null, 2)}` : ''} ${clarificationContext ? `\n## Clarifications\n${JSON.stringify(clarificationContext, null, 2)}` : ''}
${executionContext?.session?.artifacts ? `\n## Planning Artifacts
Detailed planning context available in:
${executionContext.session.artifacts.exploration ? `- Exploration: ${executionContext.session.artifacts.exploration}` : ''}
- Plan: ${executionContext.session.artifacts.plan}
- Task: ${executionContext.session.artifacts.task}
Read these files for detailed architecture, patterns, and constraints.` : ''}
## Instructions ## Instructions
- Reference original request to ensure alignment - Reference original request to ensure alignment
- Review previous results to understand completed work - Review previous results to understand completed work
- Build on previous work, avoid duplication - Build on previous work, avoid duplication
- Test functionality as you implement - Test functionality as you implement
- Complete all assigned tasks - Complete all assigned tasks
- Read planning artifact files for detailed context when needed
` `
) )
``` ```
@@ -341,6 +350,11 @@ When to use:
- `executionMethod = "Codex"` - `executionMethod = "Codex"`
- `executionMethod = "Auto" AND complexity = "Medium" or "High"` - `executionMethod = "Auto" AND complexity = "Medium" or "High"`
**Artifact Path Delegation**:
- Include artifact file paths in CLI prompt for enhanced context
- Codex can read artifact files for detailed planning information
- Example: Reference exploration.json for architecture patterns
Command format: Command format:
```bash ```bash
function formatTaskForCodex(task, index) { function formatTaskForCodex(task, index) {
@@ -390,12 +404,22 @@ Constraints: ${explorationContext.constraints || 'None'}
${clarificationContext ? `\n### User Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `${q}: ${a}`).join('\n')}` : ''} ${clarificationContext ? `\n### User Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `${q}: ${a}`).join('\n')}` : ''}
${executionContext?.session?.artifacts ? `\n### Planning Artifact Files
Detailed planning context available in session folder:
${executionContext.session.artifacts.exploration ? `- Exploration: ${executionContext.session.artifacts.exploration}` : ''}
- Plan: ${executionContext.session.artifacts.plan}
- Task: ${executionContext.session.artifacts.task}
Read these files for complete architecture details, code patterns, and integration constraints.
` : ''}
## Execution Instructions ## Execution Instructions
- Reference original request to ensure alignment - Reference original request to ensure alignment
- Review previous results for context continuity - Review previous results for context continuity
- Build on previous work, don't duplicate completed tasks - Build on previous work, don't duplicate completed tasks
- Complete all assigned tasks in single execution - Complete all assigned tasks in single execution
- Test functionality as you implement - Test functionality as you implement
${executionContext?.session?.artifacts ? `- Read planning artifact files for detailed architecture and pattern guidance` : ''}
Complexity: ${planObject.complexity} Complexity: ${planObject.complexity}
" --skip-git-repo-check -s danger-full-access " --skip-git-repo-check -s danger-full-access
@@ -458,6 +482,17 @@ TodoWrite({
# Uses analysis prompt and TodoWrite tools directly # Uses analysis prompt and TodoWrite tools directly
# Gemini Review: # Gemini Review:
# Include artifact paths for planning context reference
${executionContext?.session?.artifacts ? `
gemini -p "
PURPOSE: Code review for implemented changes against planned approach
TASK: • Analyze quality • Identify issues • Suggest improvements • Verify alignment with plan
MODE: analysis
CONTEXT: @**/* @${executionContext.session.artifacts.plan}${executionContext.session.artifacts.exploration ? ` @${executionContext.session.artifacts.exploration}` : ''} | Memory: Review lite-execute changes with planning context
EXPECTED: Quality assessment with recommendations and plan alignment check
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on recent changes and plan adherence | analysis=READ-ONLY
"
` : `
gemini -p " gemini -p "
PURPOSE: Code review for implemented changes PURPOSE: Code review for implemented changes
TASK: • Analyze quality • Identify issues • Suggest improvements TASK: • Analyze quality • Identify issues • Suggest improvements
@@ -466,8 +501,20 @@ CONTEXT: @**/* | Memory: Review lite-execute changes
EXPECTED: Quality assessment with recommendations EXPECTED: Quality assessment with recommendations
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on recent changes | analysis=READ-ONLY RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on recent changes | analysis=READ-ONLY
" "
`}
# Qwen Review (custom tool via "Other"): # Qwen Review (custom tool via "Other"):
# Include artifact paths for planning context reference
${executionContext?.session?.artifacts ? `
qwen -p "
PURPOSE: Code review for implemented changes against planned approach
TASK: • Analyze quality • Identify issues • Suggest improvements • Verify alignment with plan
MODE: analysis
CONTEXT: @**/* @${executionContext.session.artifacts.plan}${executionContext.session.artifacts.exploration ? ` @${executionContext.session.artifacts.exploration}` : ''} | Memory: Review lite-execute changes with planning context
EXPECTED: Quality assessment with recommendations and plan alignment check
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on recent changes and plan adherence | analysis=READ-ONLY
"
` : `
qwen -p " qwen -p "
PURPOSE: Code review for implemented changes PURPOSE: Code review for implemented changes
TASK: • Analyze quality • Identify issues • Suggest improvements TASK: • Analyze quality • Identify issues • Suggest improvements
@@ -476,6 +523,7 @@ CONTEXT: @**/* | Memory: Review lite-execute changes
EXPECTED: Quality assessment with recommendations EXPECTED: Quality assessment with recommendations
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on recent changes | analysis=READ-ONLY RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on recent changes | analysis=READ-ONLY
" "
`}
# Codex Review (custom tool via "Other"): # Codex Review (custom tool via "Other"):
codex --full-auto exec "Review recent code changes for quality, potential issues, and improvements" --skip-git-repo-check -s danger-full-access codex --full-auto exec "Review recent code changes for quality, potential issues, and improvements" --skip-git-repo-check -s danger-full-access
@@ -546,10 +594,26 @@ Passed from lite-plan via global variable:
clarificationContext: {...} | null, clarificationContext: {...} | null,
executionMethod: "Agent" | "Codex" | "Auto", executionMethod: "Agent" | "Codex" | "Auto",
codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string, codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string,
originalUserInput: string originalUserInput: string,
// Session artifacts location (saved by lite-plan)
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)
}
}
} }
``` ```
**Artifact Usage**:
- Artifact files contain detailed planning context
- Pass artifact paths to CLI tools and agents for enhanced context
- See execution options below for usage examples
### executionResult (Output) ### executionResult (Output)
Collected after each execution call completes: Collected after each execution call completes:

187
.claude/commands/workflow/lite-plan.md
View File

@@ -130,6 +130,13 @@ needsExploration = (
**Exploration Execution** (if needed): **Exploration Execution** (if needed):
```javascript ```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( Task(
subagent_type="cli-explore-agent", subagent_type="cli-explore-agent",
description="Analyze codebase for task context", description="Analyze codebase for task context",
@@ -149,9 +156,14 @@ Task(
Output Format: JSON-like structured object Output Format: JSON-like structured object
` `
) )
// Save exploration results for CLI/agent access in lite-execute
const explorationFile = `${sessionFolder}/exploration.json`
Write(explorationFile, JSON.stringify(explorationContext, null, 2))
``` ```
**Output**: `explorationContext` (see Data Structures section) **Output**: `explorationContext` (in-memory, see Data Structures section)
**Artifact**: Saved to `{sessionFolder}/exploration.json` for CLI/agent use
**Progress Tracking**: **Progress Tracking**:
- Mark Phase 1 completed - Mark Phase 1 completed
@@ -228,6 +240,14 @@ Current Claude generates plan directly:
- Estimated Time: Total implementation time - Estimated Time: Total implementation time
- Recommended Execution: "Agent" - 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)** **Option B: Agent-Based Planning (Medium/High Complexity)**
Delegate to cli-lite-planning-agent: Delegate to cli-lite-planning-agent:
@@ -270,9 +290,14 @@ Task(
Format: "{Action} in {file_path}: {details} following {pattern}" Format: "{Action} in {file_path}: {details} following {pattern}"
` `
) )
// Save planning results to session folder
const planFile = `${sessionFolder}/plan.json`
Write(planFile, JSON.stringify(planObject, null, 2))
``` ```
**Output**: `planObject` (see Data Structures section) **Output**: `planObject` (see Data Structures section)
**Artifact**: Saved to `{sessionFolder}/plan.json` for CLI/agent use
**Progress Tracking**: **Progress Tracking**:
- Mark Phase 3 completed - Mark Phase 3 completed
@@ -315,7 +340,7 @@ ${i+1}. **${task.title}** (${task.file})
**Step 4.2: Collect User Confirmation** **Step 4.2: Collect User Confirmation**
Four questions via single AskUserQuestion call: Three questions via single AskUserQuestion call:
```javascript ```javascript
AskUserQuestion({ AskUserQuestion({
@@ -353,15 +378,6 @@ Confirm plan? (Multi-select: can supplement via "Other")`,
{ label: "Agent Review", description: "@code-reviewer agent" }, { label: "Agent Review", description: "@code-reviewer agent" },
{ label: "Skip", description: "No review" } { label: "Skip", description: "No review" }
] ]
},
{
question: "Export plan to Enhanced Task JSON file?\n\nAllows reuse with lite-execute later.",
header: "Export JSON",
multiSelect: false,
options: [
{ label: "Yes", description: "Export to JSON (recommended for complex tasks)" },
{ label: "No", description: "Keep in-memory only" }
]
} }
] ]
}) })
@@ -384,10 +400,6 @@ Code Review (after execution):
├─ Gemini Review → gemini CLI analysis ├─ Gemini Review → gemini CLI analysis
├─ Agent Review → Current Claude review ├─ Agent Review → Current Claude review
└─ Other → Custom tool (e.g., qwen, codex) └─ Other → Custom tool (e.g., qwen, codex)
Export JSON:
├─ Yes → Export to .workflow/lite-plans/plan-{timestamp}.json
└─ No → In-memory only
``` ```
**Progress Tracking**: **Progress Tracking**:
@@ -398,48 +410,48 @@ Export JSON:
### Phase 5: Dispatch to Execution ### Phase 5: Dispatch to Execution
**Step 5.1: Export Enhanced Task JSON (Optional)** **Step 5.1: Export Enhanced Task JSON**
Only execute if `userSelection.export_task_json === "Yes"`: Always export Enhanced Task JSON to session folder:
```javascript ```javascript
if (userSelection.export_task_json === "Yes") { const taskId = `LP-${shortTimestamp}`
const timestamp = new Date().toISOString().replace(/[:.]/g, '-') const filename = `${sessionFolder}/task.json`
const taskId = `LP-${timestamp}`
const filename = `.workflow/lite-plans/${taskId}.json`
const enhancedTaskJson = { const enhancedTaskJson = {
id: taskId, id: taskId,
title: original_task_description, title: original_task_description,
status: "pending", status: "pending",
meta: { meta: {
type: "planning", type: "planning",
created_at: new Date().toISOString(), created_at: new Date().toISOString(),
complexity: planObject.complexity, complexity: planObject.complexity,
estimated_time: planObject.estimated_time, estimated_time: planObject.estimated_time,
recommended_execution: planObject.recommended_execution, recommended_execution: planObject.recommended_execution,
workflow: "lite-plan" workflow: "lite-plan",
session_id: sessionId,
session_folder: sessionFolder
},
context: {
requirements: [original_task_description],
plan: {
summary: planObject.summary,
approach: planObject.approach,
tasks: planObject.tasks
}, },
exploration: explorationContext || null,
context: { clarifications: clarificationContext || null,
requirements: [original_task_description], focus_paths: explorationContext?.relevant_files || [],
plan: { acceptance: planObject.tasks.flatMap(t => t.acceptance)
summary: planObject.summary,
approach: planObject.approach,
tasks: planObject.tasks
},
exploration: explorationContext || null,
clarifications: clarificationContext || null,
focus_paths: explorationContext?.relevant_files || [],
acceptance: planObject.tasks.flatMap(t => t.acceptance)
}
} }
Write(filename, JSON.stringify(enhancedTaskJson, null, 2))
console.log(`Enhanced Task JSON exported to: ${filename}`)
console.log(`Reuse with: /workflow:lite-execute ${filename}`)
} }
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}`)
``` ```
**Step 5.2: Store Execution Context** **Step 5.2: Store Execution Context**
@@ -451,7 +463,18 @@ executionContext = {
clarificationContext: clarificationContext || null, clarificationContext: clarificationContext || null,
executionMethod: userSelection.execution_method, executionMethod: userSelection.execution_method,
codeReviewTool: userSelection.code_review_tool, codeReviewTool: userSelection.code_review_tool,
originalUserInput: original_task_description originalUserInput: original_task_description,
// Session artifacts location
session: {
id: sessionId,
folder: sessionFolder,
artifacts: {
exploration: explorationContext ? `${sessionFolder}/exploration.json` : null,
plan: `${sessionFolder}/plan.json`,
task: `${sessionFolder}/task.json` // Always exported
}
}
} }
``` ```
@@ -462,7 +485,11 @@ SlashCommand(command="/workflow:lite-execute --in-memory")
``` ```
**Execution Handoff**: **Execution Handoff**:
- lite-execute reads `executionContext` variable - 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 - All execution logic handled by lite-execute
- lite-plan completes after successful handoff - lite-plan completes after successful handoff
@@ -502,7 +529,7 @@ SlashCommand(command="/workflow:lite-execute --in-memory")
- Plan confirmation (multi-select with supplements) - Plan confirmation (multi-select with supplements)
- Execution method selection - Execution method selection
- Code review tool selection (custom via "Other") - Code review tool selection (custom via "Other")
- JSON export option - Enhanced Task JSON always exported to session folder
- Allows plan refinement without re-selecting execution method - Allows plan refinement without re-selecting execution method
### Task Management ### Task Management
@@ -519,11 +546,11 @@ SlashCommand(command="/workflow:lite-execute --in-memory")
- Medium: 5-7 tasks (detailed) - Medium: 5-7 tasks (detailed)
- High: 7-10 tasks (comprehensive) - High: 7-10 tasks (comprehensive)
3. **No File Artifacts During Planning**: 3. **Session Artifact Management**:
- All planning stays in memory - All planning artifacts saved to dedicated session folder
- Optional Enhanced Task JSON export (user choice) - Enhanced Task JSON always exported for reusability
- Faster workflow, cleaner workspace - Plan context passed to execution via memory and files
- Plan context passed directly to execution - Clean organization with session-based folder structure
### Planning Standards ### Planning Standards
@@ -550,6 +577,39 @@ SlashCommand(command="/workflow:lite-execute --in-memory")
| Phase 4 Confirmation Timeout | User no response > 5 minutes | Save context to temp var, display resume instructions, exit gracefully | | 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` | | 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
**Benefits**:
- Clean separation between different task executions
- Easy to find and inspect artifacts for specific tasks
- Natural history/audit trail of planning sessions
- Supports concurrent lite-plan executions without conflicts
## Data Structures ## Data Structures
### explorationContext ### explorationContext
@@ -621,7 +681,18 @@ Context passed to lite-execute via --in-memory (Phase 5):
clarificationContext: {...} | null, // User responses from Phase 2 clarificationContext: {...} | null, // User responses from Phase 2
executionMethod: "Agent" | "Codex" | "Auto", executionMethod: "Agent" | "Codex" | "Auto",
codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string, codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string,
originalUserInput: string // User's original task description 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)
}
}
} }
``` ```