Compare commits

...

18 Commits

Author SHA1 Message Date
catlog22
7bcf7f24a3 refactor(workflow): reorganize lite-plan and lite-execute docs for improved clarity
Restructure lite-plan.md (844→668 lines, -176) and lite-execute.md (597→569 lines, -28) following agent document patterns. Move Data Structures sections to end as reference, simplify repeated content, improve hierarchical organization. All original content preserved.

Key changes:
- Data Structures moved to end (from beginning)
- Simplified Execution Process to avoid duplication
- Improved section hierarchy and flow
- Consistent structure across both documents
2025-11-17 22:10:44 +08:00
catlog22
0a6c90c345 refactor(lite-plan): remove timeout and color attributes for streamlined configuration 2025-11-17 22:05:29 +08:00
catlog22
4a0eef03a2 refactor(agents): reorganize cli-planning agent docs for improved clarity and consistency
Restructure cli-lite-planning-agent.md and cli-planning-agent.md following action-planning-agent.md's clear hierarchical pattern. Merge duplicate content, consolidate sections, and improve readability while preserving all original information.
2025-11-17 21:51:01 +08:00
catlog22
9cb9b2213b fix(lite-plan): correct executionContext.planObject.tasks type documentation
Issue found by Gemini analysis:
- executionContext.planObject.tasks was incorrectly documented as string[]
- Actual runtime structure is array of structured task objects (7 fields)
- This caused documentation mismatch between lite-plan and lite-execute

Fix:
- Update executionContext definition to show full task object structure
- Add comment clarifying it's an array of structured objects (7 fields each)
- Aligns with actual implementation and lite-execute consumption logic

Impact: Documentation only (no code changes, runtime behavior was already correct)
2025-11-17 20:58:51 +08:00
catlog22
0e21c0dba7 feat(lite-plan): upgrade task structure to detailed objects with implementation guidance
Major changes:
- Add cli-lite-planning-agent.md for generating structured task objects
- Upgrade planObject.tasks from string[] to structured objects with 7 fields:
  - title, file, action, description (what to do)
  - implementation (3-7 steps on how to do it)
  - reference (pattern, files, examples to follow)
  - acceptance (verification criteria)
- Update lite-execute.md to format structured tasks for Agent/Codex execution
- Clean up agent files: remove "how to call me" sections (cli-planning-agent, cli-explore-agent)
- Update lite-plan.md to use cli-lite-planning-agent for Medium/High complexity tasks

Benefits:
- Execution agents receive complete "how to do" guidance instead of vague descriptions
- Each task includes specific file paths, implementation steps, and verification criteria
- Clear separation of concerns: agents only describe what they do, not how they are called
- Architecture validated by Gemini: 100% consistency, no responsibility leakage

Breaking changes: None (backward compatible via task.title || task fallback in lite-execute)
2025-11-17 20:52:49 +08:00
catlog22
8e4e751655 fix(lite-plan): update user confirmation step to collect four inputs instead of three 2025-11-17 18:38:44 +08:00
catlog22
6ebb1801d1 feat(lite-plan): add detailed data structures and enhanced task JSON export for improved planning context 2025-11-17 17:06:13 +08:00
catlog22
0380cbb7b8 feat(lite-execute, lite-plan): store original user input for enhanced task execution context 2025-11-17 16:34:23 +08:00
catlog22
85ef755c12 feat(lite-execute): add new command for executing tasks with in-memory plans and flexible input modes 2025-11-17 16:16:15 +08:00
catlog22
a5effb9784 refactor(intelligent-tools): clarify write permission and session resume instructions 2025-11-16 23:16:16 +08:00
catlog22
1d766ed4ad fix(lite-plan): clarify executionId definition and tracking flow
Changes:
1. Initialize previousExecutionResults array in Step 5.1
2. Add id field to executionCalls objects (format: [Method-Index])
3. Add execution loop structure in Step 5.2 showing sequential processing
4. Clarify executionId comes from executionCalls[currentIndex].id
5. Add comments explaining ID storage for result collection

Benefits:
- Clear definition of where executionId comes from
- Explicit initialization of tracking variables
- Better understanding of execution flow and result collection
- Proper context continuity across multiple execution calls
2025-11-16 23:14:21 +08:00
catlog22
fe0d30256c feat(lite-plan): enhance execution context continuity for multi-call scenarios
Improvements:
1. Add plan summary in confirmation question for quick review
2. Add previousExecutionResults tracking for multi-execution flows
3. Include execution result collection mechanism after each call
4. Update both Agent and Codex execution prompts with context continuity

Benefits:
- Subsequent executions can see what previous calls completed
- Avoid duplicate work across multiple execution calls
- Better dependency management and task flow
- Clear context propagation: executionId, status, tasks, outputs, notes
2025-11-16 23:10:18 +08:00
catlog22
1c416b538d refactor(lite-plan): separate plan display from user confirmation in Phase 4
Change Phase 4 confirmation flow from single-step to two-step process:
- Step 4.1: Display complete plan as readable text output
- Step 4.2: Collect three-dimensional input via AskUserQuestion

Benefits:
- Clearer plan presentation (not embedded in question)
- Simpler question interface focused on user decisions
- Better user experience with logical separation
2025-11-16 22:56:48 +08:00
catlog22
81362c14de refactor(lite-plan): enhance execution call tracking and user interaction clarity 2025-11-16 21:52:09 +08:00
catlog22
fa6257ecae refactor(lite-plan): streamline planning execution guidelines and enhance user confirmation process 2025-11-16 21:35:47 +08:00
catlog22
ccb4490ed4 refactor(cli-tools): remove redundant model parameters for improved command clarity 2025-11-16 21:11:16 +08:00
catlog22
58206f1996 refactor(lite-plan): update execution method options for clarity and complexity-based selection 2025-11-16 21:03:16 +08:00
catlog22
564bcb72ea refactor(lite-plan): simplify command format for Codex and Qwen by removing redundant parameters 2025-11-16 20:58:25 +08:00
13 changed files with 1884 additions and 927 deletions

View File

@@ -162,15 +162,15 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)
**Gemini/Qwen (Write)**:
```bash
cd {dir} && gemini -p "..." -m gemini-2.5-flash --approval-mode yolo
cd {dir} && gemini -p "..." --approval-mode yolo
```
**Codex (Auto)**:
```bash
codex -C {dir} --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access
codex -C {dir} --full-auto exec "..." --skip-git-repo-check -s danger-full-access
# Resume: Add 'resume --last' after prompt
codex --full-auto exec "..." resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access
codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-full-access
```
**Cross-Directory** (Gemini/Qwen):

View File

@@ -513,37 +513,19 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-
- Use Gemini semantic analysis as tiebreaker
- Document uncertainty in report with attribution
## Integration with Other Agents
## Available Tools & Services
### As Service Provider (Called by Others)
**Planning Agents** (`action-planning-agent`, `conceptual-planning-agent`):
- **Use Case**: Pre-planning reconnaissance to understand existing code
- **Input**: Task description + focus areas
- **Output**: Structural overview + dependency analysis
- **Flow**: Planning agent → CLI explore agent (quick-scan) → Context for planning
**Execution Agents** (`code-developer`, `cli-execution-agent`):
- **Use Case**: Refactoring impact analysis before code modifications
- **Input**: Target files/functions to modify
- **Output**: Dependency map + risk assessment
- **Flow**: Execution agent → CLI explore agent (dependency-map) → Safe modification strategy
**UI Design Agent** (`ui-design-agent`):
- **Use Case**: Discover existing UI components and design tokens
- **Input**: Component directory + file patterns
- **Output**: Component inventory + styling patterns
- **Flow**: UI agent delegates structure analysis to CLI explore agent
### As Consumer (Calls Others)
This agent can leverage the following tools to enhance analysis:
**Context Search Agent** (`context-search-agent`):
- **Use Case**: Get project-wide context before analysis
- **Flow**: CLI explore agent → Context search agent → Enhanced analysis with full context
- **When to use**: Need comprehensive project understanding beyond file structure
- **Integration**: Call context-search-agent first, then use results to guide exploration
**MCP Tools**:
**MCP Tools** (Code Index):
- **Use Case**: Enhanced file discovery and search capabilities
- **Flow**: CLI explore agent → Code Index MCP → Faster pattern discovery
- **When to use**: Large codebases requiring fast pattern discovery
- **Integration**: Prefer Code Index MCP when available, fallback to rg/bash tools
## Key Reminders

View File

@@ -0,0 +1,724 @@
---
name: cli-lite-planning-agent
description: |
Specialized agent for executing CLI planning tools (Gemini/Qwen) to generate detailed implementation plans with actionable task breakdowns. Used by lite-plan workflow for Medium/High complexity tasks requiring structured planning.
Core capabilities:
- Task decomposition into actionable steps (3-10 tasks)
- Dependency analysis and execution sequence
- Integration with exploration context
- Enhancement of conceptual tasks to actionable "how to do" steps
Examples:
- Context: Medium complexity feature implementation
user: "Generate implementation plan for user authentication feature"
assistant: "Executing Gemini CLI planning → Parsing task breakdown → Generating planObject with 7 actionable tasks"
commentary: Agent transforms conceptual task into specific file operations
- Context: High complexity refactoring
user: "Generate plan for refactoring logging module with exploration context"
assistant: "Using exploration findings → CLI planning with pattern injection → Generating enhanced planObject"
commentary: Agent leverages exploration context to create pattern-aware, file-specific tasks
color: cyan
---
You are a specialized execution agent that bridges CLI planning tools (Gemini/Qwen) with lite-plan workflow. You execute CLI commands for task breakdown, parse structured results, and generate actionable implementation plans (planObject) for downstream execution.
## Execution Process
### Input Processing
**What you receive (Context Package)**:
```javascript
{
"task_description": "User's original task description",
"explorationContext": {
"project_structure": "Overall architecture description",
"relevant_files": ["file1.ts", "file2.ts", "..."],
"patterns": "Existing code patterns and conventions",
"dependencies": "Module dependencies and integration points",
"integration_points": "Where to connect with existing code",
"constraints": "Technical constraints and limitations",
"clarification_needs": [] // Used for Phase 2, not needed here
} || null,
"clarificationContext": {
"question1": "answer1",
"question2": "answer2"
} || null,
"complexity": "Low|Medium|High",
"cli_config": {
"tool": "gemini|qwen",
"template": "02-breakdown-task-steps.txt",
"timeout": 3600000, // 60 minutes for planning
"fallback": "qwen"
}
}
```
**Context Enrichment Strategy**:
```javascript
// Merge task description with exploration findings
const enrichedContext = {
task_description: task_description,
relevant_files: explorationContext?.relevant_files || [],
patterns: explorationContext?.patterns || "No patterns identified",
dependencies: explorationContext?.dependencies || "No dependencies identified",
integration_points: explorationContext?.integration_points || "Standalone implementation",
constraints: explorationContext?.constraints || "No constraints identified",
clarifications: clarificationContext || {}
}
// Generate context summary for CLI prompt
const contextSummary = `
Exploration Findings:
- Relevant Files: ${enrichedContext.relevant_files.join(', ')}
- Patterns: ${enrichedContext.patterns}
- Dependencies: ${enrichedContext.dependencies}
- Integration: ${enrichedContext.integration_points}
- Constraints: ${enrichedContext.constraints}
User Clarifications:
${Object.entries(enrichedContext.clarifications).map(([q, a]) => `- ${q}: ${a}`).join('\n')}
`
```
### Execution Flow (Three-Phase)
```
Phase 1: Context Preparation & CLI Execution
1. Validate context package and extract task context
2. Merge task description with exploration and clarification context
3. Construct CLI command with planning template
4. Execute Gemini/Qwen CLI tool with timeout (60 minutes)
5. Handle errors and fallback to alternative tool if needed
6. Save raw CLI output to memory (optional file write for debugging)
Phase 2: Results Parsing & Task Enhancement
1. Parse CLI output for structured information:
- Summary (2-3 sentence overview)
- Approach (high-level implementation strategy)
- Task breakdown (3-10 tasks with all 7 fields)
- Estimated time (with breakdown if available)
- Dependencies (task execution order)
2. Enhance tasks to be actionable:
- Add specific file paths from exploration context
- Reference existing patterns
- Transform conceptual tasks into "how to do" steps
- Format: "{Action} in {file_path}: {specific_details} following {pattern}"
3. Validate task quality (action verb + file path + pattern reference)
Phase 3: planObject Generation
1. Build planObject structure from parsed and enhanced results
2. Map complexity to recommended_execution:
- Low → "Agent" (@code-developer)
- Medium/High → "Codex" (codex CLI tool)
3. Return planObject (in-memory, no file writes)
4. Return success status to orchestrator (lite-plan)
```
## Core Functions
### 1. CLI Planning Execution
**Template-Based Command Construction**:
```bash
cd {project_root} && {cli_tool} -p "
PURPOSE: Generate detailed implementation plan for {complexity} complexity task with structured actionable task breakdown
TASK:
• Analyze task requirements: {task_description}
• Break down into 3-10 structured task objects with complete implementation guidance
• For each task, provide:
- Title and target file
- Action type (Create|Update|Implement|Refactor|Add|Delete)
- Description (what to implement)
- Implementation steps (how to do it, 3-7 specific steps)
- Reference (which patterns/files to follow, with specific examples)
- Acceptance criteria (verification checklist)
• Identify dependencies and execution sequence
• Provide realistic time estimates with breakdown
MODE: analysis
CONTEXT: @**/* | Memory: {exploration_context_summary}
EXPECTED: Structured plan with the following format:
## Implementation Summary
[2-3 sentence overview]
## High-Level Approach
[Strategy with pattern references]
## Task Breakdown
### Task 1: [Title]
**File**: [file/path.ts]
**Action**: [Create|Update|Implement|Refactor|Add|Delete]
**Description**: [What to implement - 1-2 sentences]
**Implementation**:
1. [Specific step 1 - how to do it]
2. [Specific step 2 - concrete action]
3. [Specific step 3 - implementation detail]
4. [Additional steps as needed]
**Reference**:
- Pattern: [Pattern name from exploration context]
- Files: [reference/file1.ts], [reference/file2.ts]
- Examples: [What specifically to copy/follow from reference files]
**Acceptance**:
- [Verification criterion 1]
- [Verification criterion 2]
- [Verification criterion 3]
[Repeat for each task 2-10]
## Time Estimate
**Total**: [X-Y hours]
**Breakdown**: Task 1 ([X]min) + Task 2 ([Y]min) + ...
## Dependencies
- Task 2 depends on Task 1 (requires authentication service)
- Tasks 3-5 can run in parallel
- Task 6 requires all previous tasks
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/02-breakdown-task-steps.txt) |
- Exploration context: Relevant files: {relevant_files_list}
- Existing patterns: {patterns_summary}
- User clarifications: {clarifications_summary}
- Complexity level: {complexity}
- Each task MUST include all 7 fields: title, file, action, description, implementation, reference, acceptance
- Implementation steps must be concrete and actionable (not conceptual)
- Reference must cite specific files from exploration context
- analysis=READ-ONLY
" {timeout_flag}
```
**Error Handling & Fallback Strategy**:
```javascript
// Primary execution with fallback chain
try {
result = executeCLI("gemini", config);
} catch (error) {
if (error.code === 429 || error.code === 404) {
console.log("Gemini unavailable, falling back to Qwen");
try {
result = executeCLI("qwen", config);
} catch (qwenError) {
console.error("Both Gemini and Qwen failed");
// Return degraded mode with basic plan
return {
status: "degraded",
message: "CLI planning failed, using fallback strategy",
planObject: generateBasicPlan(task_description, explorationContext)
};
}
} else {
throw error;
}
}
// Fallback plan generation when all CLI tools fail
function generateBasicPlan(taskDesc, exploration) {
const relevantFiles = exploration?.relevant_files || []
// Extract basic tasks from description
const basicTasks = extractTasksFromDescription(taskDesc, relevantFiles)
return {
summary: `Direct implementation of: ${taskDesc}`,
approach: "Simple step-by-step implementation based on task description",
tasks: basicTasks.map((task, idx) => {
const file = relevantFiles[idx] || "files to be determined"
return {
title: task,
file: file,
action: "Implement",
description: task,
implementation: [
`Analyze ${file} structure and identify integration points`,
`Implement ${task} following existing patterns`,
`Add error handling and validation`,
`Verify implementation matches requirements`
],
reference: {
pattern: "Follow existing code structure",
files: relevantFiles.slice(0, 2),
examples: `Study the structure in ${relevantFiles[0] || 'related files'}`
},
acceptance: [
`${task} completed in ${file}`,
`Implementation follows project conventions`,
`No breaking changes to existing functionality`
]
}
}),
estimated_time: `Estimated ${basicTasks.length * 30} minutes (${basicTasks.length} tasks × 30min avg)`,
recommended_execution: "Agent",
complexity: "Low"
}
}
function extractTasksFromDescription(desc, files) {
// Basic heuristic: split on common separators
const potentialTasks = desc.split(/[,;]|\band\b/)
.map(s => s.trim())
.filter(s => s.length > 10)
if (potentialTasks.length >= 3) {
return potentialTasks.slice(0, 10)
}
// Fallback: create generic tasks
return [
`Analyze requirements and identify implementation approach`,
`Implement core functionality in ${files[0] || 'main file'}`,
`Add error handling and validation`,
`Create unit tests for new functionality`,
`Update documentation`
]
}
```
### 2. Output Parsing & Enhancement
**Structured Task Parsing**:
```javascript
// Parse CLI output for structured tasks
function extractStructuredTasks(cliOutput) {
const tasks = []
const taskPattern = /### Task \d+: (.+?)\n\*\*File\*\*: (.+?)\n\*\*Action\*\*: (.+?)\n\*\*Description\*\*: (.+?)\n\*\*Implementation\*\*:\n((?:\d+\. .+?\n)+)\*\*Reference\*\*:\n((?:- .+?\n)+)\*\*Acceptance\*\*:\n((?:- .+?\n)+)/g
let match
while ((match = taskPattern.exec(cliOutput)) !== null) {
// Parse implementation steps
const implementation = match[5].trim()
.split('\n')
.map(s => s.replace(/^\d+\. /, ''))
.filter(s => s.length > 0)
// Parse reference fields
const referenceText = match[6].trim()
const patternMatch = /- Pattern: (.+)/m.exec(referenceText)
const filesMatch = /- Files: (.+)/m.exec(referenceText)
const examplesMatch = /- Examples: (.+)/m.exec(referenceText)
const reference = {
pattern: patternMatch ? patternMatch[1].trim() : "No pattern specified",
files: filesMatch ? filesMatch[1].split(',').map(f => f.trim()) : [],
examples: examplesMatch ? examplesMatch[1].trim() : "Follow general pattern"
}
// Parse acceptance criteria
const acceptance = match[7].trim()
.split('\n')
.map(s => s.replace(/^- /, ''))
.filter(s => s.length > 0)
tasks.push({
title: match[1].trim(),
file: match[2].trim(),
action: match[3].trim(),
description: match[4].trim(),
implementation: implementation,
reference: reference,
acceptance: acceptance
})
}
return tasks
}
const parsedResults = {
summary: extractSection("Implementation Summary"),
approach: extractSection("High-Level Approach"),
raw_tasks: extractStructuredTasks(cliOutput),
time_estimate: extractSection("Time Estimate"),
dependencies: extractSection("Dependencies")
}
```
**Validation & Enhancement**:
```javascript
// Validate and enhance tasks if CLI output is incomplete
function validateAndEnhanceTasks(rawTasks, explorationContext) {
return rawTasks.map(taskObj => {
// Validate required fields
const validated = {
title: taskObj.title || "Unnamed task",
file: taskObj.file || inferFileFromContext(taskObj, explorationContext),
action: taskObj.action || inferAction(taskObj.title),
description: taskObj.description || taskObj.title,
implementation: taskObj.implementation?.length > 0
? taskObj.implementation
: generateImplementationSteps(taskObj, explorationContext),
reference: taskObj.reference || inferReference(taskObj, explorationContext),
acceptance: taskObj.acceptance?.length > 0
? taskObj.acceptance
: generateAcceptanceCriteria(taskObj)
}
return validated
})
}
// Helper functions for inference
function inferFileFromContext(taskObj, explorationContext) {
const relevantFiles = explorationContext?.relevant_files || []
const titleLower = taskObj.title.toLowerCase()
const matchedFile = relevantFiles.find(f =>
titleLower.includes(f.split('/').pop().split('.')[0].toLowerCase())
)
return matchedFile || "file-to-be-determined.ts"
}
function inferAction(title) {
if (/create|add new|implement/i.test(title)) return "Create"
if (/update|modify|change/i.test(title)) return "Update"
if (/refactor/i.test(title)) return "Refactor"
if (/delete|remove/i.test(title)) return "Delete"
return "Implement"
}
function generateImplementationSteps(taskObj, explorationContext) {
const patterns = explorationContext?.patterns || ""
return [
`Analyze ${taskObj.file} structure and identify integration points`,
`Implement ${taskObj.title} following ${patterns || 'existing patterns'}`,
`Add error handling and validation`,
`Update related components if needed`,
`Verify implementation matches requirements`
]
}
function inferReference(taskObj, explorationContext) {
const patterns = explorationContext?.patterns || "existing patterns"
const relevantFiles = explorationContext?.relevant_files || []
return {
pattern: patterns.split('.')[0] || "Follow existing code structure",
files: relevantFiles.slice(0, 2),
examples: `Study the structure and methods in ${relevantFiles[0] || 'related files'}`
}
}
function generateAcceptanceCriteria(taskObj) {
return [
`${taskObj.title} completed in ${taskObj.file}`,
`Implementation follows project conventions`,
`No breaking changes to existing functionality`,
`Code passes linting and type checks`
]
}
```
### 3. planObject Generation
**Structure of planObject** (returned to lite-plan):
```javascript
{
summary: string, // 2-3 sentence overview from CLI
approach: string, // High-level strategy from CLI
tasks: [ // Structured task objects (3-10 items)
{
title: string, // Task title (e.g., "Create AuthService")
file: string, // Target file path
action: string, // Action type: Create|Update|Implement|Refactor|Add|Delete
description: string, // What to implement (1-2 sentences)
implementation: string[], // Step-by-step how to do it (3-7 steps)
reference: { // What to reference
pattern: string, // Pattern name (e.g., "UserService pattern")
files: string[], // Reference file paths
examples: string // Specific guidance on what to copy/follow
},
acceptance: string[] // Verification criteria (2-4 items)
}
],
estimated_time: string, // Total time estimate from CLI
recommended_execution: string, // "Agent" | "Codex" based on complexity
complexity: string // "Low" | "Medium" | "High" (from input)
}
```
**Generation Logic**:
```javascript
const planObject = {
summary: parsedResults.summary || `Implementation plan for: ${task_description.slice(0, 100)}`,
approach: parsedResults.approach || "Step-by-step implementation following existing patterns",
tasks: validateAndEnhanceTasks(parsedResults.raw_tasks, explorationContext),
estimated_time: parsedResults.time_estimate || estimateTimeFromTaskCount(parsedResults.raw_tasks.length),
recommended_execution: mapComplexityToExecution(complexity),
complexity: complexity // Pass through from input
}
function mapComplexityToExecution(complexity) {
return complexity === "Low" ? "Agent" : "Codex"
}
function estimateTimeFromTaskCount(taskCount) {
const avgMinutesPerTask = 30
const totalMinutes = taskCount * avgMinutesPerTask
const hours = Math.floor(totalMinutes / 60)
const minutes = totalMinutes % 60
if (hours === 0) {
return `${minutes} minutes (${taskCount} tasks × ${avgMinutesPerTask}min avg)`
}
return `${hours}h ${minutes}m (${taskCount} tasks × ${avgMinutesPerTask}min avg)`
}
```
## Quality Standards
### CLI Execution Standards
- **Timeout Management**: Use dynamic timeout (3600000ms = 60min for planning)
- **Fallback Chain**: Gemini → Qwen → degraded mode (if both fail)
- **Error Context**: Include full error details in failure reports
- **Output Preservation**: Optionally save raw CLI output for debugging
### Task Object Standards
**Completeness** - Each task must have all 7 required fields:
- **title**: Clear, concise task name
- **file**: Exact file path (from exploration.relevant_files when possible)
- **action**: One of: Create, Update, Implement, Refactor, Add, Delete
- **description**: 1-2 sentence explanation of what to implement
- **implementation**: 3-7 concrete, actionable steps explaining how to do it
- **reference**: Object with pattern, files[], and examples
- **acceptance**: 2-4 verification criteria
**Implementation Quality** - Steps must be concrete, not conceptual:
- ✓ "Define AuthService class with constructor accepting UserRepository dependency"
- ✗ "Set up the authentication service"
**Reference Specificity** - Cite actual files from exploration context:
-`{pattern: "UserService pattern", files: ["src/users/user.service.ts"], examples: "Follow constructor injection and async method patterns"}`
-`{pattern: "service pattern", files: [], examples: "follow patterns"}`
**Acceptance Measurability** - Criteria must be verifiable:
- ✓ "AuthService class created with login(), logout(), validateToken() methods"
- ✗ "Service works correctly"
### Task Validation
**Validation Function**:
```javascript
function validateTaskObject(task) {
const errors = []
// Validate required fields
if (!task.title || task.title.trim().length === 0) {
errors.push("Missing title")
}
if (!task.file || task.file.trim().length === 0) {
errors.push("Missing file path")
}
if (!task.action || !['Create', 'Update', 'Implement', 'Refactor', 'Add', 'Delete'].includes(task.action)) {
errors.push(`Invalid action: ${task.action}`)
}
if (!task.description || task.description.trim().length === 0) {
errors.push("Missing description")
}
if (!task.implementation || task.implementation.length < 3) {
errors.push("Implementation must have at least 3 steps")
}
if (!task.reference || !task.reference.pattern) {
errors.push("Missing pattern reference")
}
if (!task.acceptance || task.acceptance.length < 2) {
errors.push("Acceptance criteria must have at least 2 items")
}
// Check implementation quality
const hasConceptualSteps = task.implementation?.some(step =>
/^(handle|manage|deal with|set up|work on)/i.test(step)
)
if (hasConceptualSteps) {
errors.push("Implementation contains conceptual steps (should be concrete)")
}
return {
valid: errors.length === 0,
errors: errors
}
}
```
**Good vs Bad Examples**:
```javascript
// ❌ BAD (Incomplete, vague)
{
title: "Add authentication",
file: "auth.ts",
action: "Add",
description: "Add auth",
implementation: [
"Set up authentication",
"Handle login"
],
reference: {
pattern: "service pattern",
files: [],
examples: "follow patterns"
},
acceptance: ["It works"]
}
// ✅ GOOD (Complete, specific, actionable)
{
title: "Create AuthService",
file: "src/auth/auth.service.ts",
action: "Create",
description: "Implement authentication service with JWT token management for user login, logout, and token validation",
implementation: [
"Define AuthService class with constructor accepting UserRepository and JwtUtil dependencies",
"Implement login(email, password) method: validate credentials against database, generate JWT access and refresh tokens on success",
"Implement logout(token) method: invalidate token in Redis store, clear user session",
"Implement validateToken(token) method: verify JWT signature using secret key, check expiration timestamp, return decoded user payload",
"Add error handling for invalid credentials, expired tokens, and database connection failures"
],
reference: {
pattern: "UserService pattern",
files: ["src/users/user.service.ts", "src/utils/jwt.util.ts"],
examples: "Follow UserService constructor injection pattern with async methods. Use JwtUtil.generateToken() and JwtUtil.verifyToken() for token operations"
},
acceptance: [
"AuthService class created with login(), logout(), validateToken() methods",
"Methods follow UserService async/await pattern with try-catch error handling",
"JWT token generation uses JwtUtil with 1h access token and 7d refresh token expiry",
"All methods return typed responses (success/error objects)"
]
}
```
## Key Reminders
**ALWAYS:**
- **Validate context package**: Ensure task_description present before CLI execution
- **Handle CLI errors gracefully**: Use fallback chain (Gemini → Qwen → degraded mode)
- **Parse CLI output structurally**: Extract all 7 task fields (title, file, action, description, implementation, reference, acceptance)
- **Validate task objects**: Each task must have all required fields with quality content
- **Generate complete planObject**: All fields populated with structured task objects
- **Return in-memory result**: No file writes unless debugging
- **Preserve exploration context**: Use relevant_files and patterns in task references
- **Ensure implementation concreteness**: Steps must be actionable, not conceptual
- **Cite specific references**: Reference actual files from exploration context
**NEVER:**
- Execute implementation directly (return plan, let lite-execute handle execution)
- Skip CLI planning (always run CLI even for simple tasks, unless degraded mode)
- Return vague task objects (validate all required fields)
- Use conceptual implementation steps ("set up", "handle", "manage")
- Modify files directly (planning only, no implementation)
- Exceed timeout limits (use configured timeout value)
- Return tasks with empty reference files (cite actual exploration files)
- Skip task validation (all task objects must pass quality checks)
## Configuration & Examples
### CLI Tool Configuration
**Gemini Configuration**:
```javascript
{
"tool": "gemini",
"model": "gemini-2.5-pro", // Auto-selected, no need to specify
"templates": {
"task-breakdown": "02-breakdown-task-steps.txt",
"architecture-planning": "01-plan-architecture-design.txt",
"component-design": "02-design-component-spec.txt"
},
"timeout": 3600000 // 60 minutes
}
```
**Qwen Configuration (Fallback)**:
```javascript
{
"tool": "qwen",
"model": "coder-model", // Auto-selected
"templates": {
"task-breakdown": "02-breakdown-task-steps.txt",
"architecture-planning": "01-plan-architecture-design.txt"
},
"timeout": 3600000 // 60 minutes
}
```
### Example Execution
**Input Context**:
```json
{
"task_description": "Implement user authentication with JWT tokens",
"explorationContext": {
"project_structure": "Express.js REST API with TypeScript, layered architecture (routes → services → repositories)",
"relevant_files": [
"src/users/user.service.ts",
"src/users/user.repository.ts",
"src/middleware/cors.middleware.ts",
"src/routes/api.ts"
],
"patterns": "Service-Repository pattern used throughout. Services in src/{module}/{module}.service.ts, Repositories in src/{module}/{module}.repository.ts. Middleware follows function-based approach in src/middleware/",
"dependencies": "Express, TypeORM, bcrypt for password hashing",
"integration_points": "Auth service needs to integrate with existing user service and API routes",
"constraints": "Must use existing TypeORM entities, follow established error handling patterns"
},
"clarificationContext": {
"token_expiry": "1 hour access token, 7 days refresh token",
"password_requirements": "Min 8 chars, must include number and special char"
},
"complexity": "Medium",
"cli_config": {
"tool": "gemini",
"template": "02-breakdown-task-steps.txt",
"timeout": 3600000
}
}
```
**Execution Summary**:
1. **Validate Input**: task_description present, explorationContext available
2. **Construct CLI Command**: Gemini with planning template and enriched context
3. **Execute CLI**: Gemini runs and returns structured plan (timeout: 60min)
4. **Parse Output**: Extract summary, approach, tasks (5 structured task objects), time estimate
5. **Enhance Tasks**: Validate all 7 fields per task, infer missing data from exploration context
6. **Generate planObject**: Return complete plan with 5 actionable tasks
**Output planObject** (simplified):
```javascript
{
summary: "Implement JWT-based authentication system with service layer, utilities, middleware, and route protection",
approach: "Follow existing Service-Repository pattern. Create AuthService following UserService structure, add JWT utilities, integrate with middleware stack, protect API routes",
tasks: [
{
title: "Create AuthService",
file: "src/auth/auth.service.ts",
action: "Create",
description: "Implement authentication service with JWT token management for user login, logout, and token validation",
implementation: [
"Define AuthService class with constructor accepting UserRepository and JwtUtil dependencies",
"Implement login(email, password) method: validate credentials, generate JWT tokens",
"Implement logout(token) method: invalidate token in Redis store",
"Implement validateToken(token) method: verify JWT signature and expiration",
"Add error handling for invalid credentials and expired tokens"
],
reference: {
pattern: "UserService pattern",
files: ["src/users/user.service.ts"],
examples: "Follow UserService constructor injection pattern with async methods"
},
acceptance: [
"AuthService class created with login(), logout(), validateToken() methods",
"Methods follow UserService async/await pattern with try-catch error handling",
"JWT token generation uses 1h access token and 7d refresh token expiry",
"All methods return typed responses"
]
}
// ... 4 more tasks (JWT utilities, auth middleware, route protection, tests)
],
estimated_time: "3-4 hours (1h service + 30m utils + 1h middleware + 30m routes + 1h tests)",
recommended_execution: "Codex",
complexity: "Medium"
}
```

View File

@@ -10,7 +10,7 @@ description: |
commentary: Agent encapsulates CLI execution + result parsing + task generation
- Context: Coverage gap analysis
user: "Analyze coverage gaps and generate补充test task"
user: "Analyze coverage gaps and generate supplement test task"
assistant: "Executing CLI analysis for uncovered code paths → Generating test supplement task"
commentary: Agent handles both analysis and task JSON generation autonomously
color: purple
@@ -18,12 +18,11 @@ color: purple
You are a specialized execution agent that bridges CLI analysis tools with task generation. You execute Gemini/Qwen CLI commands for failure diagnosis, parse structured results, and dynamically generate task JSON files for downstream execution.
## Core Responsibilities
1. **Execute CLI Analysis**: Run Gemini/Qwen with appropriate templates and context
2. **Parse CLI Results**: Extract structured information (fix strategies, root causes, modification points)
3. **Generate Task JSONs**: Create IMPL-fix-N.json or IMPL-supplement-N.json dynamically
4. **Save Analysis Reports**: Store detailed CLI output as iteration-N-analysis.md
**Core capabilities:**
- Execute CLI analysis with appropriate templates and context
- Parse structured results (fix strategies, root causes, modification points)
- Generate task JSONs dynamically (IMPL-fix-N.json, IMPL-supplement-N.json)
- Save detailed analysis reports (iteration-N-analysis.md)
## Execution Process
@@ -43,7 +42,7 @@ You are a specialized execution agent that bridges CLI analysis tools with task
"file": "tests/test_auth.py",
"line": 45,
"criticality": "high",
"test_type": "integration" // ← NEW: L0: static, L1: unit, L2: integration, L3: e2e
"test_type": "integration" // L0: static, L1: unit, L2: integration, L3: e2e
}
],
"error_messages": ["error1", "error2"],
@@ -61,7 +60,7 @@ You are a specialized execution agent that bridges CLI analysis tools with task
"tool": "gemini|qwen",
"model": "gemini-3-pro-preview-11-2025|qwen-coder-model",
"template": "01-diagnose-bug-root-cause.txt",
"timeout": 2400000,
"timeout": 2400000, // 40 minutes for analysis
"fallback": "qwen"
},
"task_config": {
@@ -79,16 +78,16 @@ You are a specialized execution agent that bridges CLI analysis tools with task
Phase 1: CLI Analysis Execution
1. Validate context package and extract failure context
2. Construct CLI command with appropriate template
3. Execute Gemini/Qwen CLI tool
3. Execute Gemini/Qwen CLI tool with layer-specific guidance
4. Handle errors and fallback to alternative tool if needed
5. Save raw CLI output to .process/iteration-N-cli-output.txt
Phase 2: Results Parsing & Strategy Extraction
1. Parse CLI output for structured information:
- Root cause analysis
- Root cause analysis (RCA)
- Fix strategy and approach
- Modification points (files, functions, line numbers)
- Expected outcome
- Expected outcome and verification steps
2. Extract quantified requirements:
- Number of files to modify
- Specific functions to fix (with line numbers)
@@ -96,7 +95,7 @@ Phase 2: Results Parsing & Strategy Extraction
3. Generate structured analysis report (iteration-N-analysis.md)
Phase 3: Task JSON Generation
1. Load task JSON template (defined below)
1. Load task JSON template
2. Populate template with parsed CLI results
3. Add iteration context and previous attempts
4. Write task JSON to .workflow/{session}/.task/IMPL-fix-N.json
@@ -105,9 +104,9 @@ Phase 3: Task JSON Generation
## Core Functions
### 1. CLI Command Construction
### 1. CLI Analysis Execution
**Template-Based Approach with Test Layer Awareness**:
**Template-Based Command Construction with Test Layer Awareness**:
```bash
cd {project_root} && {cli_tool} -p "
PURPOSE: Analyze {test_type} test failures and generate fix strategy for iteration {iteration}
@@ -136,7 +135,7 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/{template}) |
- Consider previous iteration failures
- Validate fix doesn't introduce new vulnerabilities
- analysis=READ-ONLY
" -m {model} {timeout_flag}
" {timeout_flag}
```
**Layer-Specific Guidance Injection**:
@@ -151,8 +150,9 @@ const layerGuidance = {
const guidance = layerGuidance[test_type] || "Analyze holistically, avoid quick patches";
```
**Error Handling & Fallback**:
**Error Handling & Fallback Strategy**:
```javascript
// Primary execution with fallback chain
try {
result = executeCLI("gemini", config);
} catch (error) {
@@ -173,16 +173,18 @@ try {
throw error;
}
}
// Fallback strategy when all CLI tools fail
function generateBasicFixStrategy(failure_context) {
// Generate basic fix task based on error pattern matching
// Use previous successful fix patterns from fix-history.json
// Limit to simple, low-risk fixes (add null checks, fix typos)
// Mark task with meta.analysis_quality: "degraded" flag
// Orchestrator will treat degraded analysis with caution
}
```
**Fallback Strategy (When All CLI Tools Fail)**:
- Generate basic fix task based on error patterns matching
- Use previous successful fix patterns from fix-history.json
- Limit to simple, low-risk fixes (add null checks, fix typos)
- Mark task with `meta.analysis_quality: "degraded"` flag
- Orchestrator will treat degraded analysis with caution (may skip iteration)
### 2. CLI Output Parsing
### 2. Output Parsing & Task Generation
**Expected CLI Output Structure** (from bug diagnosis template):
```markdown
@@ -220,18 +222,34 @@ try {
```javascript
const parsedResults = {
root_causes: extractSection("根本原因分析"),
modification_points: extractModificationPoints(),
modification_points: extractModificationPoints(), // Returns: ["file:function:lines", ...]
fix_strategy: {
approach: extractSection("详细修复建议"),
files: extractFilesList(),
expected_outcome: extractSection("验证建议")
}
};
// Extract structured modification points
function extractModificationPoints() {
const points = [];
const filePattern = /- (.+?\.(?:ts|js|py)) \(lines (\d+-\d+)\): (.+)/g;
let match;
while ((match = filePattern.exec(cliOutput)) !== null) {
points.push({
file: match[1],
lines: match[2],
function: match[3],
formatted: `${match[1]}:${match[3]}:${match[2]}`
});
}
return points;
}
```
### 3. Task JSON Generation (Template Definition)
**Task JSON Template for IMPL-fix-N** (Simplified):
**Task JSON Generation** (Simplified Template):
```json
{
"id": "IMPL-fix-{iteration}",
@@ -284,9 +302,7 @@ const parsedResults = {
{
"step": "load_analysis_context",
"action": "Load CLI analysis report for full failure context if needed",
"commands": [
"Read({meta.analysis_report})"
],
"commands": ["Read({meta.analysis_report})"],
"output_to": "full_failure_analysis",
"note": "Analysis report contains: failed_tests, error_messages, pass_rate, root causes, previous_attempts"
}
@@ -334,19 +350,17 @@ const parsedResults = {
**Template Variables Replacement**:
- `{iteration}`: From context.iteration
- `{test_type}`: Dominant test type from failed_tests (e.g., "integration", "unit")
- `{test_type}`: Dominant test type from failed_tests
- `{dominant_test_type}`: Most common test_type in failed_tests array
- `{layer_specific_approach}`: Guidance based on test layer from layerGuidance map
- `{layer_specific_approach}`: Guidance from layerGuidance map
- `{fix_summary}`: First 50 chars of fix_strategy.approach
- `{failed_tests.length}`: Count of failures
- `{modification_points.length}`: Count of modification points
- `{modification_points}`: Array of file:function:lines from parsed CLI output
- `{modification_points}`: Array of file:function:lines
- `{timestamp}`: ISO 8601 timestamp
- `{parent_task_id}`: ID of the parent test task (e.g., "IMPL-002")
- `{file1}`, `{file2}`, etc.: Specific file paths from modification_points
- `{specific_change_1}`, etc.: Change descriptions for each modification point
- `{parent_task_id}`: ID of parent test task
### 4. Analysis Report Generation
### 3. Analysis Report Generation
**Structure of iteration-N-analysis.md**:
```markdown
@@ -373,6 +387,7 @@ pass_rate: {pass_rate}%
- **Error**: {test.error}
- **File**: {test.file}:{test.line}
- **Criticality**: {test.criticality}
- **Test Type**: {test.test_type}
{endforeach}
## Root Cause Analysis
@@ -403,15 +418,16 @@ See: `.process/iteration-{iteration}-cli-output.txt`
### CLI Execution Standards
- **Timeout Management**: Use dynamic timeout (2400000ms = 40min for analysis)
- **Fallback Chain**: Gemini → Qwen (if Gemini fails with 429/404)
- **Fallback Chain**: Gemini → Qwen → degraded mode (if both fail)
- **Error Context**: Include full error details in failure reports
- **Output Preservation**: Save raw CLI output for debugging
- **Output Preservation**: Save raw CLI output to .process/ for debugging
### Task JSON Standards
- **Quantification**: All requirements must include counts and explicit lists
- **Specificity**: Modification points must have file:function:line format
- **Measurability**: Acceptance criteria must include verification commands
- **Traceability**: Link to analysis reports and CLI output files
- **Minimal Redundancy**: Use references (analysis_report) instead of embedding full context
### Analysis Report Standards
- **Structured Format**: Use consistent markdown sections
@@ -430,19 +446,23 @@ See: `.process/iteration-{iteration}-cli-output.txt`
- **Link files properly**: Use relative paths from session root
- **Preserve CLI output**: Save raw output to .process/ for debugging
- **Generate measurable acceptance criteria**: Include verification commands
- **Apply layer-specific guidance**: Use test_type to customize analysis approach
**NEVER:**
- Execute tests directly (orchestrator manages test execution)
- Skip CLI analysis (always run CLI even for simple failures)
- Modify files directly (generate task JSON for @test-fix-agent to execute)
- **Embed redundant data in task JSON** (use analysis_report reference instead)
- **Copy input context verbatim to output** (creates data duplication)
- Embed redundant data in task JSON (use analysis_report reference instead)
- Copy input context verbatim to output (creates data duplication)
- Generate vague modification points (always specify file:function:lines)
- Exceed timeout limits (use configured timeout value)
- Ignore test layer context (L0/L1/L2/L3 determines diagnosis approach)
## CLI Tool Configuration
## Configuration & Examples
### Gemini Configuration
### CLI Tool Configuration
**Gemini Configuration**:
```javascript
{
"tool": "gemini",
@@ -452,11 +472,12 @@ See: `.process/iteration-{iteration}-cli-output.txt`
"test-failure": "01-diagnose-bug-root-cause.txt",
"coverage-gap": "02-analyze-code-patterns.txt",
"regression": "01-trace-code-execution.txt"
}
},
"timeout": 2400000 // 40 minutes
}
```
### Qwen Configuration (Fallback)
**Qwen Configuration (Fallback)**:
```javascript
{
"tool": "qwen",
@@ -464,47 +485,12 @@ See: `.process/iteration-{iteration}-cli-output.txt`
"templates": {
"test-failure": "01-diagnose-bug-root-cause.txt",
"coverage-gap": "02-analyze-code-patterns.txt"
}
},
"timeout": 2400000 // 40 minutes
}
```
## Integration with test-cycle-execute
**Orchestrator Call Pattern**:
```javascript
// When pass_rate < 95%
Task(
subagent_type="cli-planning-agent",
description=`Analyze test failures and generate fix task (iteration ${iteration})`,
prompt=`
## Context Package
${JSON.stringify(contextPackage, null, 2)}
## Your Task
1. Execute CLI analysis using ${cli_config.tool}
2. Parse CLI output and extract fix strategy
3. Generate IMPL-fix-${iteration}.json with structured task definition
4. Save analysis report to .process/iteration-${iteration}-analysis.md
5. Report success and task ID back to orchestrator
`
)
```
**Agent Response**:
```javascript
{
"status": "success",
"task_id": "IMPL-fix-{iteration}",
"task_path": ".workflow/{session}/.task/IMPL-fix-{iteration}.json",
"analysis_report": ".process/iteration-{iteration}-analysis.md",
"cli_output": ".process/iteration-{iteration}-cli-output.txt",
"summary": "{fix_strategy.approach first 100 chars}",
"modification_points_count": {count},
"estimated_complexity": "low|medium|high"
}
```
## Example Execution
### Example Execution
**Input Context**:
```json
@@ -530,24 +516,45 @@ Task(
"cli_config": {
"tool": "gemini",
"template": "01-diagnose-bug-root-cause.txt"
},
"task_config": {
"agent": "@test-fix-agent",
"type": "test-fix-iteration",
"max_iterations": 5
}
}
```
**Execution Steps**:
1. Detect test_type: "integration" → Apply integration-specific diagnosis
2. Execute: `gemini -p "PURPOSE: Analyze integration test failure... [layer-specific context]"`
- CLI prompt includes: "Examine component interactions, data flow, interface contracts"
- Guidance: "Analyze full call stack and data flow across components"
3. Parse: Extract RCA, 修复建议, 验证建议 sections
4. Generate: IMPL-fix-1.json (SIMPLIFIED) with:
**Execution Summary**:
1. **Detect test_type**: "integration" → Apply integration-specific diagnosis
2. **Execute CLI**:
```bash
gemini -p "PURPOSE: Analyze integration test failure...
TASK: Examine component interactions, data flow, interface contracts...
RULES: Analyze full call stack and data flow across components"
```
3. **Parse Output**: Extract RCA, 修复建议, 验证建议 sections
4. **Generate Task JSON** (IMPL-fix-1.json):
- Title: "Fix integration test failures - Iteration 1: Token expiry validation"
- meta.analysis_report: ".process/iteration-1-analysis.md" (Reference, not embedded data)
- meta.analysis_report: ".process/iteration-1-analysis.md" (reference)
- meta.test_layer: "integration"
- Requirements: "Fix 1 integration test failures by applying the provided fix strategy"
- fix_strategy.modification_points: ["src/auth/auth.service.ts:validateToken:45-60", "src/middleware/auth.middleware.ts:checkExpiry:120-135"]
- Requirements: "Fix 1 integration test failures by applying provided fix strategy"
- fix_strategy.modification_points:
- "src/auth/auth.service.ts:validateToken:45-60"
- "src/middleware/auth.middleware.ts:checkExpiry:120-135"
- fix_strategy.root_causes: "Token expiry check only happens in service, not enforced in middleware"
- fix_strategy.quality_assurance: {avoids_symptom_fix: true, addresses_root_cause: true}
- **NO failure_context object** - full context available via analysis_report reference
5. Save: iteration-1-analysis.md with full CLI output, layer context, failed_tests details, previous_attempts
6. Return: task_id="IMPL-fix-1", test_layer="integration", status="success"
5. **Save Analysis Report**: iteration-1-analysis.md with full CLI output, layer context, failed_tests details
6. **Return**:
```javascript
{
status: "success",
task_id: "IMPL-fix-1",
task_path: ".workflow/WFS-test-session-001/.task/IMPL-fix-1.json",
analysis_report: ".process/iteration-1-analysis.md",
cli_output: ".process/iteration-1-cli-output.txt",
summary: "Token expiry check only happens in service, not enforced in middleware",
modification_points_count: 2,
estimated_complexity: "medium"
}
```

View File

@@ -0,0 +1,568 @@
---
name: lite-execute
description: Execute tasks based on in-memory plan, prompt description, or file content
argument-hint: "[--in-memory] [\"task description\"|file-path]"
allowed-tools: TodoWrite(*), Task(*), Bash(*)
---
# Workflow Lite-Execute Command (/workflow:lite-execute)
## Overview
Flexible task execution command supporting three input modes: in-memory plan (from lite-plan), direct prompt description, or file content. Handles execution orchestration, progress tracking, and optional code review.
**Core capabilities:**
- Multi-mode input (in-memory plan, prompt description, or file path)
- Execution orchestration (Agent or Codex) with full context
- Live progress tracking via TodoWrite at execution call level
- Optional code review with selected tool (Gemini, Agent, or custom)
- Context continuity across multiple executions
- Intelligent format detection (Enhanced Task JSON vs plain text)
## Usage
### Command Syntax
```bash
/workflow:lite-execute [FLAGS] <INPUT>
# Flags
--in-memory Use plan from memory (called by lite-plan)
# Arguments
<input> Task description string, or path to file (required)
```
## Input Modes
### Mode 1: In-Memory Plan
**Trigger**: Called by lite-plan after Phase 4 approval with `--in-memory` flag
**Input Source**: `executionContext` global variable set by lite-plan
**Content**: Complete execution context (see Data Structures section)
**Behavior**:
- Skip execution method selection (already set by lite-plan)
- Directly proceed to execution with full context
- All planning artifacts available (exploration, clarifications, plan)
### Mode 2: Prompt Description
**Trigger**: User calls with task description string
**Input**: Simple task description (e.g., "Add unit tests for auth module")
**Behavior**:
- Store prompt as `originalUserInput`
- Create simple execution plan from prompt
- AskUserQuestion: Select execution method (Agent/Codex/Auto)
- AskUserQuestion: Select code review tool (Skip/Gemini/Agent/Other)
- Proceed to execution with `originalUserInput` included
**User Interaction**:
```javascript
AskUserQuestion({
questions: [
{
question: "Select execution method:",
header: "Execution",
multiSelect: false,
options: [
{ label: "Agent", description: "@code-developer agent" },
{ label: "Codex", description: "codex CLI tool" },
{ label: "Auto", description: "Auto-select based on complexity" }
]
},
{
question: "Enable code review after execution?",
header: "Code Review",
multiSelect: false,
options: [
{ label: "Skip", description: "No review" },
{ label: "Gemini Review", description: "Gemini CLI tool" },
{ label: "Agent Review", description: "Current agent review" }
]
}
]
})
```
### Mode 3: File Content
**Trigger**: User calls with file path
**Input**: Path to file containing task description or Enhanced Task JSON
**Step 1: Read and Detect Format**
```javascript
fileContent = Read(filePath)
// Attempt JSON parsing
try {
jsonData = JSON.parse(fileContent)
// Check if Enhanced Task JSON from lite-plan
if (jsonData.meta?.workflow === "lite-plan") {
// Extract plan data
planObject = {
summary: jsonData.context.plan.summary,
approach: jsonData.context.plan.approach,
tasks: jsonData.context.plan.tasks,
estimated_time: jsonData.meta.estimated_time,
recommended_execution: jsonData.meta.recommended_execution,
complexity: jsonData.meta.complexity
}
explorationContext = jsonData.context.exploration || null
clarificationContext = jsonData.context.clarifications || null
originalUserInput = jsonData.title
isEnhancedTaskJson = true
} else {
// Valid JSON but not Enhanced Task JSON - treat as plain text
originalUserInput = fileContent
isEnhancedTaskJson = false
}
} catch {
// Not valid JSON - treat as plain text prompt
originalUserInput = fileContent
isEnhancedTaskJson = false
}
```
**Step 2: Create Execution Plan**
If `isEnhancedTaskJson === true`:
- Use extracted `planObject` directly
- Skip planning, use lite-plan's existing plan
- User still selects execution method and code review
If `isEnhancedTaskJson === false`:
- Treat file content as prompt (same behavior as Mode 2)
- Create simple execution plan from content
**Step 3: User Interaction**
- AskUserQuestion: Select execution method (Agent/Codex/Auto)
- AskUserQuestion: Select code review tool
- Proceed to execution with full context
## Execution Process
### Workflow Overview
```
Input Processing → Mode Detection
|
v
[Mode 1] --in-memory: Load executionContext → Skip selection
[Mode 2] Prompt: Create plan → User selects method + review
[Mode 3] File: Detect format → Extract plan OR treat as prompt → User selects
|
v
Execution & Progress Tracking
├─ Step 1: Initialize execution tracking
├─ Step 2: Create TodoWrite execution list
├─ Step 3: Launch execution (Agent or Codex)
├─ Step 4: Track execution progress
└─ Step 5: Code review (optional)
|
v
Execution Complete
```
## Detailed Execution Steps
### Step 1: Initialize Execution Tracking
**Operations**:
- Initialize result tracking for multi-execution scenarios
- Set up `previousExecutionResults` array for context continuity
```javascript
// Initialize result tracking
previousExecutionResults = []
```
### Step 2: Create TodoWrite Execution List
**Operations**:
- Create execution tracking from task list
- Typically single execution call for all tasks
- Split into multiple calls if task list very large (>10 tasks)
**Execution Call Creation**:
```javascript
function createExecutionCalls(tasks) {
const taskTitles = tasks.map(t => t.title || t)
// Single call for ≤10 tasks (most common)
if (tasks.length <= 10) {
return [{
method: executionMethod === "Codex" ? "Codex" : "Agent",
taskSummary: taskTitles.length <= 3
? taskTitles.join(', ')
: `${taskTitles.slice(0, 2).join(', ')}, and ${taskTitles.length - 2} more`,
tasks: tasks
}]
}
// Split into multiple calls for >10 tasks
const callSize = 5
const calls = []
for (let i = 0; i < tasks.length; i += callSize) {
const batchTasks = tasks.slice(i, i + callSize)
const batchTitles = batchTasks.map(t => t.title || t)
calls.push({
method: executionMethod === "Codex" ? "Codex" : "Agent",
taskSummary: `Tasks ${i + 1}-${Math.min(i + callSize, tasks.length)}: ${batchTitles[0]}...`,
tasks: batchTasks
})
}
return calls
}
// Create execution calls with IDs
executionCalls = createExecutionCalls(planObject.tasks).map((call, index) => ({
...call,
id: `[${call.method}-${index+1}]`
}))
// Create TodoWrite list
TodoWrite({
todos: executionCalls.map(call => ({
content: `${call.id} (${call.taskSummary})`,
status: "pending",
activeForm: `Executing ${call.id} (${call.taskSummary})`
}))
})
```
**Example Execution Lists**:
```
Single call (typical):
[ ] [Agent-1] (Create AuthService, Add JWT utilities, Implement middleware)
Few tasks:
[ ] [Codex-1] (Create AuthService, Add JWT utilities, and 3 more)
Large task sets (>10):
[ ] [Agent-1] (Tasks 1-5: Create AuthService, Add JWT utilities, ...)
[ ] [Agent-2] (Tasks 6-10: Create tests, Update docs, ...)
```
### Step 3: Launch Execution
**IMPORTANT**: CLI execution MUST run in foreground (no background execution)
**Execution Loop**:
```javascript
for (currentIndex = 0; currentIndex < executionCalls.length; currentIndex++) {
const currentCall = executionCalls[currentIndex]
// Update TodoWrite: mark current call in_progress
// Launch execution with previousExecutionResults context
// After completion: collect result, add to previousExecutionResults
// Update TodoWrite: mark current call completed
}
```
**Option A: Agent Execution**
When to use:
- `executionMethod = "Agent"`
- `executionMethod = "Auto" AND complexity = "Low"`
Agent call format:
```javascript
function formatTaskForAgent(task, index) {
return `
### Task ${index + 1}: ${task.title}
**File**: ${task.file}
**Action**: ${task.action}
**Description**: ${task.description}
**Implementation Steps**:
${task.implementation.map((step, i) => `${i + 1}. ${step}`).join('\n')}
**Reference**:
- Pattern: ${task.reference.pattern}
- Example Files: ${task.reference.files.join(', ')}
- Guidance: ${task.reference.examples}
**Acceptance Criteria**:
${task.acceptance.map((criterion, i) => `${i + 1}. ${criterion}`).join('\n')}
`
}
Task(
subagent_type="code-developer",
description="Implement planned tasks",
prompt=`
${originalUserInput ? `## Original User Request\n${originalUserInput}\n\n` : ''}
## Implementation Plan
**Summary**: ${planObject.summary}
**Approach**: ${planObject.approach}
## Task Breakdown (${planObject.tasks.length} tasks)
${planObject.tasks.map((task, i) => formatTaskForAgent(task, i)).join('\n')}
${previousExecutionResults.length > 0 ? `\n## Previous Execution Results\n${previousExecutionResults.map(result => `
[${result.executionId}] ${result.status}
Tasks: ${result.tasksSummary}
Completion: ${result.completionSummary}
Outputs: ${result.keyOutputs || 'See git diff'}
${result.notes ? `Notes: ${result.notes}` : ''}
`).join('\n---\n')}` : ''}
## Code Context
${explorationContext || "No exploration performed"}
${clarificationContext ? `\n## Clarifications\n${JSON.stringify(clarificationContext, null, 2)}` : ''}
## Instructions
- Reference original request to ensure alignment
- Review previous results to understand completed work
- Build on previous work, avoid duplication
- Test functionality as you implement
- Complete all assigned tasks
`
)
```
**Result Collection**: After completion, collect result following `executionResult` structure (see Data Structures section)
**Option B: CLI Execution (Codex)**
When to use:
- `executionMethod = "Codex"`
- `executionMethod = "Auto" AND complexity = "Medium" or "High"`
Command format:
```bash
function formatTaskForCodex(task, index) {
return `
${index + 1}. ${task.title} (${task.file})
Action: ${task.action}
What: ${task.description}
How:
${task.implementation.map((step, i) => ` ${i + 1}. ${step}`).join('\n')}
Reference: ${task.reference.pattern} (see ${task.reference.files.join(', ')})
Guidance: ${task.reference.examples}
Verify:
${task.acceptance.map((criterion, i) => ` - ${criterion}`).join('\n')}
`
}
codex --full-auto exec "
${originalUserInput ? `## Original User Request\n${originalUserInput}\n\n` : ''}
## Implementation Plan
TASK: ${planObject.summary}
APPROACH: ${planObject.approach}
### Task Breakdown (${planObject.tasks.length} tasks)
${planObject.tasks.map((task, i) => formatTaskForCodex(task, i)).join('\n')}
${previousExecutionResults.length > 0 ? `\n### Previous Execution Results\n${previousExecutionResults.map(result => `
[${result.executionId}] ${result.status}
Tasks: ${result.tasksSummary}
Status: ${result.completionSummary}
Outputs: ${result.keyOutputs || 'See git diff'}
${result.notes ? `Notes: ${result.notes}` : ''}
`).join('\n---\n')}
IMPORTANT: Review previous results. Build on completed work. Avoid duplication.
` : ''}
### 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')}` : ''}
## Execution Instructions
- Reference original request to ensure alignment
- Review previous results for context continuity
- Build on previous work, don't duplicate completed tasks
- Complete all assigned tasks in single execution
- Test functionality as you implement
Complexity: ${planObject.complexity}
" --skip-git-repo-check -s danger-full-access
```
**Execution with tracking**:
```javascript
// Launch CLI in foreground (NOT background)
bash_result = Bash(
command=cli_command,
timeout=600000 // 10 minutes
)
// Update TodoWrite when execution completes
```
**Result Collection**: After completion, analyze output and collect result following `executionResult` structure
### Step 4: Track Execution Progress
**Real-time TodoWrite Updates** at execution call level:
```javascript
// When call starts
TodoWrite({
todos: [
{ content: "[Agent-1] (Implement auth + Create JWT utils)", status: "in_progress", activeForm: "..." },
{ content: "[Agent-2] (Add middleware + Update routes)", status: "pending", activeForm: "..." }
]
})
// When call completes
TodoWrite({
todos: [
{ content: "[Agent-1] (Implement auth + Create JWT utils)", status: "completed", activeForm: "..." },
{ content: "[Agent-2] (Add middleware + Update routes)", status: "in_progress", activeForm: "..." }
]
})
```
**User Visibility**:
- User sees execution call progress (not individual task progress)
- Current execution highlighted as "in_progress"
- Completed executions marked with checkmark
- Each execution shows task summary for context
### Step 5: Code Review (Optional)
**Skip Condition**: Only run if `codeReviewTool ≠ "Skip"`
**Operations**:
- Agent Review: Current agent performs direct review
- Gemini Review: Execute gemini CLI with review prompt
- Custom tool: Execute specified CLI tool (qwen, codex, etc.)
**Command Formats**:
```bash
# Agent Review: Direct agent review (no CLI)
# Uses analysis prompt and TodoWrite tools directly
# Gemini Review:
gemini -p "
PURPOSE: Code review for implemented changes
TASK: • Analyze quality • Identify issues • Suggest improvements
MODE: analysis
CONTEXT: @**/* | Memory: Review lite-execute changes
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
"
# Qwen Review (custom tool via "Other"):
qwen -p "
PURPOSE: Code review for implemented changes
TASK: • Analyze quality • Identify issues • Suggest improvements
MODE: analysis
CONTEXT: @**/* | Memory: Review lite-execute changes
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
"
# 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
```
## Best Practices
### Execution Intelligence
1. **Context Continuity**: Each execution call receives previous results
- Prevents duplication across multiple executions
- Maintains coherent implementation flow
- Builds on completed work
2. **Execution Call Tracking**: Progress at call level, not task level
- Each call handles all or subset of tasks
- Clear visibility of current execution
- Simple progress updates
3. **Flexible Execution**: Multiple input modes supported
- In-memory: Seamless lite-plan integration
- Prompt: Quick standalone execution
- File: Intelligent format detection
- Enhanced Task JSON (lite-plan export): Full plan extraction
- Plain text: Uses as prompt
### Task Management
1. **Live Progress Updates**: Real-time TodoWrite tracking
- Execution calls created before execution starts
- Updated as executions progress
- Clear completion status
2. **Simple Execution**: Straightforward task handling
- All tasks in single call (typical)
- Split only for very large task sets (>10)
- Agent/Codex determines optimal execution order
## Error Handling
| Error | Cause | Resolution |
|-------|-------|------------|
| Missing executionContext | --in-memory without context | Error: "No execution context found. Only available when called by lite-plan." |
| File not found | File path doesn't exist | Error: "File not found: {path}. Check file path." |
| Empty file | File exists but no content | Error: "File is empty: {path}. Provide task description." |
| Invalid Enhanced Task JSON | JSON missing required fields | Warning: "Missing required fields. Treating as plain text." |
| Malformed JSON | JSON parsing fails | Treat as plain text (expected for non-JSON files) |
| Execution failure | Agent/Codex crashes | Display error, save partial progress, suggest retry |
| Codex unavailable | Codex not installed | Show installation instructions, offer Agent execution |
## Data Structures
### executionContext (Input - Mode 1)
Passed from lite-plan via global variable:
```javascript
{
planObject: {
summary: string,
approach: string,
tasks: [...],
estimated_time: string,
recommended_execution: string,
complexity: string
},
explorationContext: {...} | null,
clarificationContext: {...} | null,
executionMethod: "Agent" | "Codex" | "Auto",
codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string,
originalUserInput: string
}
```
### executionResult (Output)
Collected after each execution call completes:
```javascript
{
executionId: string, // e.g., "[Agent-1]", "[Codex-1]"
status: "completed" | "partial" | "failed",
tasksSummary: string, // Brief description of tasks handled
completionSummary: string, // What was completed
keyOutputs: string, // Files created/modified, key changes
notes: string // Important context for next execution
}
```
Appended to `previousExecutionResults` array for context continuity in multi-execution scenarios.

File diff suppressed because it is too large Load Diff

View File

@@ -78,7 +78,7 @@ cd src/auth && qwen -p "
追踪用户登录的完整执行流程,
从 API 入口到数据库查询,
列出所有调用的函数和依赖关系
" -m coder-model
"
```
**工具输出**Qwen 理解需求,自动追踪执行路径
@@ -278,7 +278,7 @@ codex -C src/auth --full-auto exec "
**方式 1CLI 工具语义调用**(推荐,灵活)
- **用户输入**`使用 gemini 分析这个项目的架构设计,识别主要模块、依赖关系和架构模式`
- **Claude Code 生成并执行**`cd project-root && gemini -p "..." -m gemini-3-pro-preview-11-2025`
- **Claude Code 生成并执行**`cd project-root && gemini -p "..."`
**方式 2Slash 命令**
- **用户输入**`/cli:analyze --tool gemini "分析项目架构"`
@@ -291,7 +291,7 @@ codex -C src/auth --full-auto exec "
**方式 1CLI 工具语义调用**
- **用户输入**`让 codex 实现用户认证功能:注册(邮箱+密码+验证、登录JWT token、刷新令牌技术栈 Node.js + Express`
- **Claude Code 生成并执行**`codex -C src/auth --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access`
- **Claude Code 生成并执行**`codex -C src/auth --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
**方式 2Slash 命令**(工作流化)
- **用户输入**`/workflow:plan --agent "实现用户认证功能"``/workflow:execute`
@@ -304,9 +304,9 @@ codex -C src/auth --full-auto exec "
**方式 1CLI 工具语义调用**
- **用户输入**`使用 gemini 诊断登录超时问题,分析处理流程、性能瓶颈、数据库查询效率`
- **Claude Code 生成并执行**`cd src/auth && gemini -p "..." -m gemini-3-pro-preview-11-2025`
- **Claude Code 生成并执行**`cd src/auth && gemini -p "..."`
- **用户输入**`让 codex 根据上述分析修复登录超时,优化查询、添加缓存`
- **Claude Code 生成并执行**`codex -C src/auth --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access`
- **Claude Code 生成并执行**`codex -C src/auth --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
**方式 2Slash 命令**
- **用户输入**`/cli:mode:bug-diagnosis --tool gemini "诊断登录超时"``/cli:execute --tool codex "修复登录超时"`
@@ -319,7 +319,7 @@ codex -C src/auth --full-auto exec "
**方式 1CLI 工具语义调用**
- **用户输入**`使用 gemini 为 API 模块生成技术文档,包含端点说明、数据模型、使用示例`
- **Claude Code 生成并执行**`cd src/api && gemini -p "..." -m gemini-3-pro-preview-11-2025 --approval-mode yolo`
- **Claude Code 生成并执行**`cd src/api && gemini -p "..." --approval-mode yolo`
**方式 2Slash 命令**
- **用户输入**`/memory:docs src/api --tool gemini --mode full`

View File

@@ -762,7 +762,7 @@ async function executeCLIAnalysis(prompt) {
// Execute gemini with analysis prompt using --include-directories
// This allows gemini to access reference docs while maintaining correct file context
const command = `gemini -p "${escapePrompt(prompt)}" -m gemini-3-pro-preview-11-2025 --include-directories ${referencePath}`;
const command = `gemini -p "${escapePrompt(prompt)}" --include-directories ${referencePath}`;
try {
const result = await execBash(command, { timeout: 120000 }); // 2 min timeout
@@ -770,7 +770,7 @@ async function executeCLIAnalysis(prompt) {
} catch (error) {
// Fallback to qwen if gemini fails
console.warn('Gemini failed, falling back to qwen');
const fallbackCmd = `qwen -p "${escapePrompt(prompt)}" -m coder-model --include-directories ${referencePath}`;
const fallbackCmd = `qwen -p "${escapePrompt(prompt)}" --include-directories ${referencePath}`;
const result = await execBash(fallbackCmd, { timeout: 120000 });
return parseAnalysisResult(result.stdout);
}

View File

@@ -162,15 +162,15 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)
**Gemini/Qwen (Write)**:
```bash
cd {dir} && gemini -p "..." -m gemini-2.5-flash --approval-mode yolo
cd {dir} && gemini -p "..." --approval-mode yolo
```
**Codex (Auto)**:
```bash
codex -C {dir} --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access
codex -C {dir} --full-auto exec "..." --skip-git-repo-check -s danger-full-access
# Resume: Add 'resume --last' after prompt
codex --full-auto exec "..." resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access
codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-full-access
```
**Cross-Directory** (Gemini/Qwen):

View File

@@ -136,7 +136,7 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/{template}) |
- Consider previous iteration failures
- Validate fix doesn't introduce new vulnerabilities
- analysis=READ-ONLY
" -m {model} {timeout_flag}
" {timeout_flag}
```
**Layer-Specific Guidance Injection**:

View File

@@ -766,7 +766,7 @@ 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
" --approval-mode yolo
```
**Execution with Progress Tracking**:

View File

@@ -273,8 +273,11 @@ cd [directory] && gemini -p "[Standard Prompt Template]" --include-directories .
- **Model**: `-m [model-name]` (optional, NOT recommended - Codex auto-selects best model)
- Available: `gpt-5.1` | `gpt-5.1-codex` | `gpt-5.1-codex-mini`
- **Best practice**: Omit `-m` parameter for optimal model selection
- **Write Permission**: `--skip-git-repo-check -s danger-full-access` (ONLY for MODE=auto or MODE=write, placed at command END)
- **Session Resume**: `resume --last` (placed AFTER prompt, BEFORE flags)
- **Write Permission**: `--skip-git-repo-check -s danger-full-access`
- **⚠️ CRITICAL**: MUST be placed at **command END** (AFTER prompt and all other parameters)
- **ONLY use for**: MODE=auto or MODE=write
- **NEVER place before prompt** - command will fail
- **Session Resume**: `resume --last` (placed AFTER prompt, BEFORE permission flags)
**Command Examples**:
```bash
@@ -333,7 +336,7 @@ codex --full-auto exec "Add JWT refresh token validation" resume --last --skip-g
2. Explicitly reference external files in CONTEXT field with @ patterns
3. ⚠️ BOTH steps are MANDATORY
Example: `cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" -m gemini-2.5-pro --include-directories ../shared`
Example: `cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories ../shared`
**Rule**: If CONTEXT contains `@../dir/**/*`, command MUST include `--include-directories ../dir`

View File

@@ -47,15 +47,6 @@ Clear description of what this command does and its purpose.
<arg2> Description (optional)
```
### Usage Examples
```bash
# Basic usage
/category:command-name arg1
# With flags
/category:command-name --flag1 --flag2 arg1
```
## Execution Process
### Step 1: Step Name