Claude-Code-Workflow/.claude/commands/workflow/unified-execute-with-file.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
unified-execute-with-file	Universal execution engine for consuming any planning/brainstorm/analysis output with minimal progress tracking, multi-agent coordination, and incremental execution	[-y|--yes] [-p|--plan <path>[,<path2>]] [--merge-agents] [--auto-commit] [--commit-prefix "prefix"] [-m|--mode sequential|parallel] ["execution context or task name"]	TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)

Auto Mode

When --yes or -y: Auto-confirm execution decisions, use default parallel strategy where possible.

Unified Execute-With-File Command

Quick Start

# Basic usage (auto-detect plan, ask for execution method)
/workflow:unified-execute-with-file

# Execute with specific plan
/workflow:unified-execute-with-file -p .workflow/plans/auth-plan.md

# Merge multiple plans
/workflow:unified-execute-with-file -p plan.json,agents/auth/plan.json

# Collaborative plan execution (auto-discover sub-plans)
/workflow:unified-execute-with-file -p .workflow/.planning/CPLAN-xxx --merge-agents

# With auto-commit (conventional commits)
/workflow:unified-execute-with-file --auto-commit -p plan.json

# Sequential execution (no parallelization)
/workflow:unified-execute-with-file -m sequential -p plan.json

# Auto mode (skip prompts, use Agent for simple tasks, CLI for complex)
/workflow:unified-execute-with-file -y -p plan.json

Execution Methods:

• Agent: Task tool with code-developer (recommended for standard tasks)
• CLI-Codex: ccw cli --tool codex (complex tasks, git-aware)
• CLI-Gemini: ccw cli --tool gemini (analysis-heavy tasks)
• Auto: Select based on task complexity (default in -y mode)

Context Source: Plan files (IMPL_PLAN.md, plan.json, synthesis.json, etc.) Output Directory: .workflow/.execution/{session-id}/ Default Mode: Parallel execution with smart dependency resolution Core Innovation: Unified event log + structured notes + auto-commit

Output Artifacts

During Execution

Artifact	Description
execution.md	Plan overview, task table, execution timeline
execution-events.md	⭐ Unified log (all task executions) - SINGLE SOURCE OF TRUTH

Generated Code

Files generated directly to project directories (src/, tests/, docs/, etc.), not into execution folder.

Overview

Universal execution engine consuming any planning output and executing it with multi-agent coordination, dependency management, and progress tracking.

Core workflow: Load Plan → Parse Tasks → Execute → Track → Verify

┌─────────────────────────────────────────────────────────────────────────┐
│                    UNIFIED EXECUTION WORKFLOW                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Phase 1: Plan Detection & Multi-Plan Merging                           │
│     ├─ Auto-detect or explicit --plan path                              │
│     ├─ Support multiple plans (comma-separated or --merge-agents)       │
│     ├─ Deduplicate tasks (file overlap + 90% title similarity)          │
│     ├─ Assign global IDs: GTASK-{plan-index}-{original-id}              │
│     └─ Remap cross-plan dependencies                                    │
│                                                                          │
│  Phase 2: Session Initialization                                        │
│     ├─ Create .workflow/.execution/{sessionId}/                         │
│     ├─ Generate execution.md (plan overview + task table)               │
│     ├─ Initialize execution-events.md (unified log)                     │
│     ├─ Validate dependency graph (detect cycles)                        │
│     └─ Calculate execution waves (topological sort + conflict check)    │
│                                                                          │
│  Phase 3: Pre-Execution Validation (Agent-Assisted)                     │
│     ├─ Launch validation agent to check feasibility                     │
│     ├─ Verify file existence, agent availability, file conflicts        │
│     ├─ Generate validation report with recommendations                  │
│     └─ Ask user: execution method (Agent/CLI-Codex/CLI-Gemini/Auto)     │
│                                                                          │
│  Phase 4: Wave Execution (Parallel/Sequential)                          │
│     ┌──────────────┬──────────────┬──────────────┐                      │
│     │   Wave 1     │   Wave 2     │   Wave N     │                      │
│     ├──────────────┼──────────────┼──────────────┤                      │
│     │ Task 1-A ──┐ │ Task 2-A     │ Task N-A     │  ← Dependencies OK   │
│     │ Task 1-B   │ │ Task 2-B     │ Task N-B     │  ← No file conflicts │
│     │ Task 1-C ──┘ │              │              │  ← Max 3 parallel    │
│     └──────────────┴──────────────┴──────────────┘                      │
│                                                                          │
│  Phase 5: Per-Task Execution (Agent OR CLI)                             │
│     ├─ Extract relevant notes from previous tasks                       │
│     ├─ Inject notes into execution context                              │
│     ├─ Route to Agent (Task tool) OR CLI (ccw cli command)              │
│     ├─ Generate structured notes for next task                          │
│     ├─ Auto-commit if enabled (conventional commit format)              │
│     └─ Append event to unified log                                      │
│                                                                          │
│  Phase 6: Progress Tracking & Recovery                                  │
│     ├─ execution-events.md: Single source of truth                      │
│     ├─ Each task: read previous events → execute → write event          │
│     ├─ Status indicators: ✅ (completed), ❌ (failed), ⏳ (progress)     │
│     └─ Resume support: --continue flag                                  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Output Structure

.workflow/.execution/{EXEC-slug-YYYY-MM-DD}/
├── execution.md              # Plan overview + task table + timeline
└── execution-events.md       # ⭐ Unified log (all task executions) - SINGLE SOURCE OF TRUTH

# Generated files (direct to project):
src/*, tests/*, docs/*

Key Concept: execution-events.md serves as both human-readable log AND machine-parseable state store. No redundancy, one unified source.

Implementation

Session Initialization

Objective: Parse plan paths, create session directory, build unified task graph.

Prerequisites: None (entry point)

Workflow Steps:

1. Parse Command Flags

   • Extract plan paths from --plan or -p argument
   • Detect --merge-agents flag for collaborative plan auto-discovery
   • Detect --auto-commit and --commit-prefix for git integration
   • Detect --mode for execution strategy (parallel/sequential)
   • Detect -y or --yes for auto-confirmation mode

2. Resolve Plan Paths

   Input Format	Resolution Strategy
   Comma-separated	Split by comma: plan1.json,plan2.json
   --merge-agents	Auto-discover: plan-note.md + agents/**/plan.json
   Single path	Direct use
   No path	Auto-detect from .workflow/ (IMPL_PLAN.md or task JSONs)

3. Build Unified Graph

   • Parse all plans via format-agnostic parsePlan()
   • Assign global IDs: GTASK-{plan-index}-{original-id}
   • Deduplicate tasks (file overlap + 90% title similarity)
   • Remap dependencies (handle merged tasks + cross-plan refs)
   • Validate (detect cycles), topological sort
   • Return: { tasks, executionOrder, planSources, metadata }

4. Create Session Directory

   • Generate session ID: EXEC-{slug}-{date}-{random}
   • Create .workflow/.execution/{sessionId}/
   • Initialize execution.md with plan sources and merge statistics
   • Initialize execution-events.md (empty, will be appended)

Success Criteria:

• All plans parsed successfully
• No circular dependencies in task graph
• Session directory created with execution.md template
• Execution order calculated (topological sort)

Completion: Log session ID and ready for validation phase

---

Pre-Execution Validation (Agent-Assisted)

Objective: Use validation agent to check execution feasibility, then ask user about execution method.

Prerequisites: Session initialized, unified graph built

Workflow Steps:

1. Launch Validation Agent

   Task(
     subagent_type="cli-explore-agent",
     run_in_background=false,
     description="Validate execution plan feasibility",
     prompt=`
   

Validation Mission

Analyze the following execution plan and generate a validation report.

Plan Summary

• Total Tasks: ${unifiedGraph.tasks.length}
• Plan Sources: ${unifiedGraph.planSources.map(p => p.path).join(', ')}
• Execution Mode: ${executionMode}

Tasks to Validate

${unifiedGraph.tasks.slice(0, 10).map(t => - ${t.id}: ${t.title} (files: ${t.files_to_modify?.join(', ')})).join('\n')}

Validation Checks

1. File Existence: Verify files_to_modify exist or will be created
2. Dependency Resolution: Check all depends_on targets exist
3. File Conflicts: Identify same-file modifications in parallel waves
4. Complexity Assessment: Estimate task complexity (Low/Medium/High)
5. Risk Analysis: Identify potential issues or blockers

Output Format

Generate validation-report.json in ${sessionFolder}: { "status": "pass" | "warn" | "fail", "file_checks": { "missing": [], "will_create": [] }, "dependency_issues": [], "file_conflicts": [{ "file": "", "tasks": [], "wave": 0 }], "complexity_assessment": { "low": 0, "medium": 0, "high": 0 }, "risks": [{ "severity": "critical|high|medium|low", "description": "" }], "recommendations": [] } ` )

2. **Process Validation Result**
- Read `{sessionFolder}/validation-report.json`
- Display summary: status, conflicts count, risks count
- If `status === "fail"`: Show blockers, ask to abort/continue
- If `status === "warn"`: Show warnings, ask to proceed/fix

3. **Select Execution Method** (unless `--yes` flag)

| Method | Description | When to Use |
|--------|-------------|-------------|
| Agent | `Task(subagent_type="code-developer")` | Standard implementation |
| CLI-Codex | `ccw cli --tool codex --mode write` | Complex tasks, git-aware |
| CLI-Gemini | `ccw cli --tool gemini --mode write` | Analysis-heavy tasks |
| Auto | Auto-select by complexity | Default for `--yes` mode |

**User Interaction** (unless `--yes`):
```javascript
if (autoYes) {
  executionMethod = "Auto"
  console.log(`[--yes] Auto-selecting execution method: Auto`)
} else {
  const selection = AskUserQuestion({
    questions: [{
      question: `选择执行方式 (${unifiedGraph.tasks.length} tasks, complexity: ${avgComplexity}):`,
      header: "Execution",
      multiSelect: false,
      options: [
        { label: "Agent (Recommended)", description: "@code-developer - 标准实现" },
        { label: "CLI-Codex", description: "ccw cli --tool codex - 复杂任务" },
        { label: "CLI-Gemini", description: "ccw cli --tool gemini - 分析型任务" },
        { label: "Auto", description: "按复杂度自动选择" }
      ]
    }]
  })
  executionMethod = selection.execution
}

4. Confirm Execution (unless --yes flag)

   Options:

   • "开始执行" → Proceed with selected method
   • "更换方式" → Re-select execution method
   • "查看详情" → View full validation report
   • "取消" → Exit without execution

Success Criteria:

• Validation agent completed successfully
• No critical blockers (or user chose to continue)
• Execution method selected
• User confirmed (or auto-mode enabled)

Variables Set:

• validationReport: Parsed validation-report.json
• executionMethod: "Agent" | "CLI-Codex" | "CLI-Gemini" | "Auto"

---

Wave Execution

Objective: Execute tasks in waves, respecting dependencies and file conflicts.

Prerequisites: Validation completed, user confirmed

Workflow Steps:

1. Calculate Execution Waves

   Constraints:

   • Tasks with dependencies must wait for completion
   • Same file modifications → Sequential (no parallel)
   • Max 3 parallel tasks per wave (resource limit)

   Algorithm:

   • Find available tasks (dependencies satisfied, not completed)
   • Check file conflicts (task.files_to_modify)
   • Group non-conflicting tasks (up to 3 per wave)
   • Mark completed, repeat

2. Execute Each Wave

   • Launch tasks in parallel via executeTask()
   • Wait for wave completion via Promise.allSettled()
   • Process results (mark completed/failed)
   • Update execution.md timeline
   • Append events to execution-events.md

3. Handle Failures

   Failure Type	Action
   Task timeout	Ask: retry/skip/abort
   Dependency failed	Auto-skip dependent tasks
   Max retries reached	Ask: retry/skip/abort (unless auto-mode)

Success Criteria:

• All waves executed
• Results captured in execution-events.md
• Failed tasks handled appropriately

---

Task Execution

Objective: Execute individual task with context awareness, structured notes, and optional auto-commit.

Prerequisites: Task selected from available wave

Workflow Steps:

1. Extract Relevant Notes

   • Read all notes from execution-events.md
   • Filter by file overlap (notes.related_files ∩ task.files_to_modify)
   • Always include Critical severity notes
   • Sort by severity (Critical → High → Medium → Low)

2. Build Execution Context

   const executionContext = `
   ⚠️ Execution Notes from Previous Tasks
   ${relevantNotes}  // Categorized notes with severity
   
   Current Task: ${task.id}
   - Original ID: ${task.original_id}
   - Source Plan: ${task.source_plan}
   - Modified Files: ${task.files_to_modify}
   
   Previous Agent Executions (for reference)
   ${previousEvents}  // All previous task results
   `
   

3. Route to Executor (based on executionMethod)

   Option A: Agent Execution

   When: executionMethod === "Agent" or Auto + Low Complexity

   Execute task via Task tool with code-developer agent:

   Task({
     subagent_type: "code-developer",  // or other agent types
     run_in_background: false,
     description: task.title,
     prompt: buildAgentPrompt(executionContext, task)
   })
   
   // buildAgentPrompt generates:
   // - Execution context with notes
   // - Task details (title, description)
   // - Files to modify
   // - Dependencies
   // - Expected output
   

   Agent Type Selection:

   Agent Type	Use Case
   code-developer	Code implementation
   tdd-developer	Code with tests
   test-fix-agent	Test execution and fixing
   cli-execution-agent	CLI-based tasks
   debug-explore-agent	Bug diagnosis
   universal-executor	Generic tasks

   ---

   Option B: CLI Execution

   When: executionMethod === "CLI-Codex"/"CLI-Gemini" or Auto + Medium/High Complexity

   Execute task via CLI in background mode:

   // Build CLI prompt from execution context
   const cliPrompt = buildCliPrompt(task, executionContext)
   // Generates: PURPOSE, TASK, MODE, CONTEXT, EXPECTED, CONSTRAINTS
   
   // Select tool based on execution method
   const tool = executionMethod === "CLI-Gemini" ? "gemini" : "codex"
   
   // Generate fixed execution ID for resume capability
   const fixedId = `${sessionId}-${task.id}`
   
   // Execute in background
   Bash({
     command: `ccw cli -p "${cliPrompt}" --tool ${tool} --mode write --id ${fixedId}`,
     run_in_background: true,
     description: `Execute task ${task.id} via CLI`
   })
   
   // STOP HERE - CLI executes in background, task hook will notify on completion
   

   Resume on Failure:

   if (cliResult.status === 'failed' || cliResult.status === 'timeout') {
     console.log(`Task ${task.id} incomplete. Resume with fixed ID: ${fixedId}`)
     // Resume command: ccw cli -p "Continue" --resume ${fixedId} --id ${fixedId}-retry
   }
   

4. Generate Structured Notes

   Pattern Detection (auto-generate notes):

   • localStorage|sessionStorage → WARNING (High): XSS防护提醒
   • package.json modified → DEPENDENCY (Medium): npm install提醒
   • api.*change|breaking → API_CHANGE (Critical): 兼容性检查

5. Auto-Commit (if --auto-commit enabled)

   • Get changed files via git status --porcelain
   • Filter to task.files_to_modify
   • Stage files: git add
   • Generate conventional commit message: type(scope): subject
   • Commit: git commit -m

6. Append to Event Log

   Event Format:

   ## Task ${task.id} - COMPLETED ✅
   
   **Timestamp**: ${time}
   **Duration**: ${ms}
   **Agent**: ${agent}
   
   ### Execution Summary
   ${summary}
   
   ### Generated Artifacts
   - `src/auth.ts` (2.3KB)
   
   ### Git Commit (if --auto-commit)
   **Files Committed**: ${files.length}
   **Commit Message**: feat(auth): implement user login
   
   ### 注意事项 (Execution Notes)
   **Category**: WARNING
   **Severity**: High
   **Related Files**: src/auth.ts
   **Message**: 使用了localStorage，注意XSS防护
   
   ---
   

Success Criteria:

• Task executed successfully
• Notes generated for next agent
• Event appended to execution-events.md
• Auto-commit completed (if enabled)

---

Completion

Objective: Summarize execution results and offer follow-up actions.

Prerequisites: All waves completed

Workflow Steps:

1. Collect Statistics

   • Total tasks: normalizedTasks.length
   • Completed: tasks.filter(t => t.status === 'completed').length
   • Failed: tasks.filter(t => t.status === 'failed').length
   • Skipped: tasks.filter(t => t.status === 'skipped').length
   • Success rate: (completed / total * 100).toFixed(1)

2. Update execution.md

   • Append "Execution Completed" section
   • Include statistics table
   • Link to execution-events.md for details

3. Display Summary

   • Show session ID and folder
   • Display statistics
   • List failed tasks (if any)

4. Offer Follow-Up Actions (unless --yes)

   Options:

   • "查看详情" → View full execution log
   • "调试失败项" → Debug failed tasks
   • "优化执行" → Analyze execution improvements
   • "完成" → No further action

Success Criteria:

• Statistics collected and displayed
• execution.md updated with final status
• User informed of completion

---

Helper Functions

Multi-Plan Support

discoverCollaborativePlans(basePath):

• Search for plan-note.md or plan.json in base path
• Glob agents/*/plan.json for sub-plans
• Return: Array of plan paths

buildUnifiedGraph(planPaths):

• Parse each plan, assign global IDs
• Deduplicate tasks (file overlap + 90% title similarity via Levenshtein)
• Remap dependencies (merged tasks + cross-plan refs)
• Validate (detect cycles), topological sort
• Return: { tasks, executionOrder, planSources, metadata }

Deduplication Logic:

• Same files + 90%+ title similarity → Merge
• Merge metadata: source_plans, merged_from

---

Structured Notes

Note Categories: WARNING, DECISION, API_CHANGE, FILE_CONFLICT, DEPENDENCY, PATTERN

Note Severity: Critical, High, Medium, Low

extractNotesFromEvents(eventLogPath):

• Parse structured note blocks from execution-events.md
• Pattern: **Category**: ... **Severity**: ... **Related Files**: ... **Message**: ...
• Return: Array of note objects

filterRelevantNotes(notes, task):

• Include: File overlap with task.files_to_modify
• Always include: Critical severity notes
• Sort: By severity (Critical first)

generateNotesForNextAgent(result, task):

• Pattern detection for common issues
• Auto-generate structured notes
• Return: Markdown-formatted notes

---

Git Auto-Commit

inferCommitType(task):

• Check action/title for keywords: fix, refactor, test, doc
• Default: feat

extractScope(task):

• Check files_to_modify for patterns: frontend/, backend/, components/, api/, auth/
• Return: scope or null

generateCommitMessage(task):

• Format: type(scope): subject
• Footer: Task-ID: ${task.id}\nPlan: ${plan}

autoCommitTaskChanges(task):

• Get changed files, filter to task.files_to_modify
• Stage, commit with conventional message
• Return: { files, message } or null

---

Plan Format Parsers

parsePlan(content, filePath):

• Route to appropriate parser based on filename pattern
• Support: IMPL_PLAN.md, plan.json, synthesis.json, conclusions.json

parsePlanJson(content):

• Handle plan-json-schema (lite-plan, collaborative-plan, sub-plans)
• Map fields: modification_points → files_to_modify, acceptance → expected_output
• Infer: agent_type, task.type
• Build: prompt from task details

---

Validation & Execution Method

validateExecutionPlan(unifiedGraph, sessionFolder):

• Launch validation agent (cli-explore-agent)
• Check file existence, dependencies, file conflicts
• Generate validation-report.json with status/risks/recommendations
• Return: { status: "pass"|"warn"|"fail", report: {...} }

selectExecutionMethod(validationReport, autoYes):

• If autoYes === true: Return "Auto"
• Otherwise: AskUserQuestion with options (Agent/CLI-Codex/CLI-Gemini/Auto)
• Return: Selected execution method

resolveExecutor(task, executionMethod, complexity):

• If executionMethod === "Agent": Return "agent"
• If executionMethod === "CLI-Codex": Return "cli-codex"
• If executionMethod === "CLI-Gemini": Return "cli-gemini"
• If executionMethod === "Auto":
  • Low complexity → "agent"
  • Medium/High complexity → "cli-codex"
• Return: Executor type

---

Agent Selection

selectBestAgent(task):

Task Type	Agent
code (with tests)	tdd-developer
code	code-developer
test	test-fix-agent
doc	doc-generator
analysis	cli-execution-agent
debug	debug-explore-agent
default	universal-executor

---

Parallelization

calculateParallel(tasks):

Group into waves with constraints:

• Same file modifications → Sequential
• Dependencies → Wait for completion
• Max 3 parallel tasks per wave

Algorithm: Find available → Check conflicts → Group → Repeat

---

Error Handling & Recovery

Situation	Action
Task timeout	Mark timeout, ask: retry/skip/abort
Missing dependency	Auto-skip dependent tasks, log warning
File conflict	Detect before execution, ask resolution
Output mismatch	Validate vs expected_output, flag review
Agent unavailable	Fallback to universal-executor
Execution interrupted	Resume with --continue flag

Retry Logic:

• Auto-retry up to max_retries (default: 2) in auto-yes mode
• Interactive mode: Ask user after max retries

Dependency Handling:

• Failed task → Auto-skip all dependent tasks
• Log warning with skipped task IDs

---

Session Resume

/workflow:unified-execute-with-file --continue                      # Resume last
/workflow:unified-execute-with-file --continue EXEC-xxx-2025-01-27  # Resume specific

Resume Process:

1. Load execution.md and execution-events.md
2. Parse events to identify completed/failed/skipped tasks (via status indicators)
3. Recalculate remaining dependencies
4. Resume from first incomplete task
5. Append "Resumed from [sessionId]" note to events

---

Configuration

Flag	Default	Description
-p, --plan <path>	Auto-detect	Plan file(s), comma-separated for multiple
--merge-agents	false	Auto-discover collaborative plan sub-plans
--auto-commit	false	Commit after each successful task
--commit-prefix	null	Custom commit message prefix
-m, --mode	parallel	Execution strategy: sequential or parallel
-y, --yes	false	Auto-confirm all decisions

---

Best Practices

1. Clear Plan Structure: Well-structured plans → better execution
2. Review Validation Report: Check validation-report.json for risks before proceeding
3. Choose Right Execution Method:
   • Agent: Standard tasks, straightforward implementation
   • CLI-Codex: Complex tasks, requires git-aware context
   • CLI-Gemini: Analysis-heavy or exploratory tasks
   • Auto: Let system decide based on complexity
4. Use Auto-Commit: Enable --auto-commit for automatic progress tracking
5. Resolve Conflicts Early: Address file conflicts before execution
6. Monitor Events Log: Check execution-events.md for detailed progress
7. Resume on Failure: Use --continue to resume interrupted executions (Agent) or fixed ID (CLI)
8. Multi-Plan Merging: Leverage --merge-agents for collaborative plan execution

---

Advanced Features

Multi-Plan Merging

Use Cases:

• Collaborative planning output (plan-note.md + agents/**/plan.json)
• Multiple feature plans to execute together
• Incremental plan additions

Edge Cases:

• Same title, different files → Keep both
• Same files, different title → Merge if 90%+ similarity
• Same task in multiple plans → Merge once

Structured Execution Notes

Categories & Severity:

• WARNING (High): Security risks, potential issues
• DECISION (Medium): Architectural choices
• API_CHANGE (Critical): Breaking changes
• FILE_CONFLICT (High): Multi-task file modifications
• DEPENDENCY (Medium): Package/module changes
• PATTERN (Low): Coding patterns established

Note Filtering:

• File overlap: Show notes affecting task.files_to_modify
• Always show: Critical severity (regardless of files)

Auto-Commit

Conventional Commit Format:

• Structure: type(scope): subject
• Types: feat, fix, refactor, test, docs
• Scope: Inferred from file paths (frontend, backend, ui, api, auth)
• Footer: Task-ID, Plan source

Safety:

• Never commit on task failure
• Never skip hooks (no --no-verify)
• Use heredoc for commit messages (avoid shell injection)