Claude-Code-Workflow/.claude/commands/workflow/execute.md

name, description, usage, argument-hint, examples

name	description	usage	argument-hint	examples
execute	Coordinate agents for existing workflow tasks with automatic discovery	/workflow:execute	none	/workflow:execute

Workflow Execute Command

Overview

Orchestrates autonomous workflow execution through systematic task discovery, agent coordination, and progress tracking. Executes entire workflow without user interruption, providing complete context to agents and ensuring proper flow control execution with comprehensive TodoWrite tracking.

Core Rules

Complete entire workflow autonomously without user interruption, using TodoWrite for comprehensive progress tracking. Execute all discovered pending tasks sequentially until workflow completion or blocking dependency.

Core Responsibilities

• Session Discovery: Identify and select active workflow sessions
• Task Dependency Resolution: Analyze task relationships and execution order
• TodoWrite Progress Tracking: Maintain real-time execution status throughout entire workflow
• Agent Orchestration: Coordinate specialized agents with complete context
• Flow Control Execution: Execute pre-analysis steps and context accumulation
• Status Synchronization: Update task JSON files and workflow state
• Autonomous Completion: Continue execution until all tasks complete or reach blocking state

Execution Philosophy

• Discovery-first: Auto-discover existing plans and tasks
• Status-aware: Execute only ready tasks with resolved dependencies
• Context-rich: Provide complete task JSON and accumulated context to agents
• Progress tracking: Continuous TodoWrite updates throughout entire workflow execution
• Flow control: Sequential step execution with variable passing
• Autonomous completion: Execute all tasks without user interruption until workflow complete

Flow Control Execution

[FLOW_CONTROL] marker indicates sequential step execution required for context gathering and preparation. These steps are executed BY THE AGENT, not by the workflow:execute command.

Flow Control Rules

1. Auto-trigger: When task.flow_control.pre_analysis array exists in task JSON, agents execute these steps
2. Sequential Processing: Agents execute steps in order, accumulating context
3. Variable Passing: Agents use [variable_name] syntax to reference step outputs
4. Error Handling: Agents follow step-specific error strategies (fail, skip_optional, retry_once)

Execution Pattern

Step 1: load_dependencies → dependency_context
Step 2: analyze_patterns [dependency_context] → pattern_analysis
Step 3: implement_solution [pattern_analysis] [dependency_context] → implementation

Context Accumulation Process (Executed by Agents)

• Load Dependencies: Agents retrieve summaries from context.depends_on tasks
• Execute Analysis: Agents run CLI tools with accumulated context
• Prepare Implementation: Agents build comprehensive context for implementation
• Continue Implementation: Agents use all accumulated context for task execution

Execution Lifecycle

Phase 1: Discovery

1. Check Active Sessions: Find .workflow/.active-* markers
2. Select Session: If multiple found, prompt user selection
3. Load Session State: Read workflow-session.json and IMPL_PLAN.md
4. Scan Tasks: Analyze .task/*.json files for ready tasks

Phase 2: Analysis

1. Dependency Resolution: Build execution order based on depends_on
2. Status Validation: Filter tasks with status: "pending" and met dependencies
3. Agent Assignment: Determine agent type from meta.agent or meta.type
4. Context Preparation: Load dependency summaries and inherited context

Phase 3: Planning

1. Create TodoWrite List: Generate task list with status markers
2. Mark Initial Status: Set first task as in_progress
3. Prepare Session Context: Inject workflow paths for agent use
4. Prepare Complete Task JSON: Include pre_analysis and flow control steps for agent consumption
5. Validate Prerequisites: Ensure all required context is available

Phase 4: Execution

1. Pass Task with Flow Control: Include complete task JSON with pre_analysis steps for agent execution
2. Launch Agent: Invoke specialized agent with complete context including flow control steps
3. Monitor Progress: Track agent execution and handle errors without user interruption
4. Collect Results: Gather implementation results and outputs
5. Continue Workflow: Automatically proceed to next pending task until completion

Phase 5: Completion

1. Update Task Status: Mark completed tasks in JSON files
2. Generate Summary: Create task summary in .summaries/
3. Update TodoWrite: Mark current task complete, advance to next
4. Synchronize State: Update session state and workflow status

Task Discovery & Queue Building

Session Discovery Process

├── Check for .active-* markers in .workflow/
├── If multiple active sessions found → Prompt user to select
├── Locate selected session's workflow folder
├── Load selected session's workflow-session.json and IMPL_PLAN.md
├── Scan selected session's .task/ directory for task JSON files
├── Analyze task statuses and dependencies for selected session only
└── Build execution queue of ready tasks from selected session

Task Status Logic

pending + dependencies_met → executable
completed → skip
blocked → skip until dependencies clear

TodoWrite Coordination

Comprehensive workflow tracking with immediate status updates throughout entire execution without user interruption:

TodoWrite Workflow Rules

1. Initial Creation: Generate TodoWrite from discovered pending tasks for entire workflow
2. Single In-Progress: Mark ONLY ONE task as in_progress at a time
3. Immediate Updates: Update status after each task completion without user interruption
4. Status Synchronization: Sync with JSON task files after updates
5. Continuous Tracking: Maintain TodoWrite throughout entire workflow execution until completion

TodoWrite Tool Usage

Use Claude Code's built-in TodoWrite tool to track workflow progress in real-time:

// Create initial todo list from discovered pending tasks
TodoWrite({
  todos: [
    {
      content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]",
      status: "pending",
      activeForm: "Executing IMPL-1.1: Design auth schema"
    },
    {
      content: "Execute IMPL-1.2: Implement auth logic [code-developer] [FLOW_CONTROL]",
      status: "pending",
      activeForm: "Executing IMPL-1.2: Implement auth logic"
    },
    {
      content: "Execute IMPL-2: Review implementations [code-review-agent]",
      status: "pending",
      activeForm: "Executing IMPL-2: Review implementations"
    }
  ]
});

// Update status as tasks progress - ONLY ONE task should be in_progress at a time
TodoWrite({
  todos: [
    {
      content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]",
      status: "in_progress",  // Mark current task as in_progress
      activeForm: "Executing IMPL-1.1: Design auth schema"
    },
    // ... other tasks remain pending
  ]
});

TodoWrite Integration Rules:

• Continuous Workflow Tracking: Use TodoWrite tool throughout entire workflow execution
• Real-time Updates: Immediate progress tracking without user interruption
• Single Active Task: Only ONE task marked as in_progress at any time
• Immediate Completion: Mark tasks completed immediately after finishing
• Status Sync: Sync TodoWrite status with JSON task files after each update
• Full Execution: Continue TodoWrite tracking until all workflow tasks complete

TODO_LIST.md Update Timing

• Before Agent Launch: Update TODO_LIST.md to mark task as in_progress (⚠️)
• After Task Complete: Update TODO_LIST.md to mark as completed (✅), advance to next
• On Error: Keep as in_progress in TODO_LIST.md, add error note
• Session End: Sync all TODO_LIST.md statuses with JSON task files

3. Agent Context Management

Comprehensive context preparation for autonomous agent execution:

Context Sources (Priority Order)

1. Complete Task JSON: Full task definition including all fields
2. Flow Control Context: Accumulated outputs from pre_analysis steps
3. Dependency Summaries: Previous task completion summaries
4. Session Context: Workflow paths and session metadata
5. Inherited Context: Parent task context and shared variables

Context Assembly Process

1. Load Task JSON → Base context
2. Execute Flow Control → Accumulated context
3. Load Dependencies → Dependency context
4. Prepare Session Paths → Session context
5. Combine All → Complete agent context

Agent Context Package Structure

{
  "task": { /* Complete task JSON */ },
  "flow_context": {
    "step_outputs": { "pattern_analysis": "...", "dependency_context": "..." }
  },
  "session": {
    "workflow_dir": ".workflow/WFS-session/",
    "todo_list_path": ".workflow/WFS-session/TODO_LIST.md",
    "summaries_dir": ".workflow/WFS-session/.summaries/",
    "task_json_path": ".workflow/WFS-session/.task/IMPL-1.1.json"
  },
  "dependencies": [ /* Task summaries from depends_on */ ],
  "inherited": { /* Parent task context */ }
}

Context Validation Rules

• Task JSON Complete: All 5 fields present and valid
• Flow Control Ready: All pre_analysis steps completed if present
• Dependencies Loaded: All depends_on summaries available
• Session Paths Valid: All workflow paths exist and accessible
• Agent Assignment: Valid agent type specified in meta.agent

4. Agent Execution Pattern

Structured agent invocation with complete context and clear instructions:

Agent Prompt Template

Task(subagent_type="{agent_type}",
     prompt="Execute {task_id}: {task_title}

     ## Task Definition
     **ID**: {task_id}
     **Type**: {task_type}
     **Agent**: {assigned_agent}

     ## Execution Instructions
     {flow_control_marker}

     ### Flow Control Steps (if [FLOW_CONTROL] present)
     **AGENT RESPONSIBILITY**: Execute these pre_analysis steps sequentially with context accumulation:
     {pre_analysis_steps}

     ### Implementation Context
     **Requirements**: {context.requirements}
     **Focus Paths**: {context.focus_paths}
     **Acceptance Criteria**: {context.acceptance}
     **Target Files**: {flow_control.target_files}

     ### Session Context
     **Workflow Directory**: {session.workflow_dir}
     **TODO List Path**: {session.todo_list_path}
     **Summaries Directory**: {session.summaries_dir}
     **Task JSON Path**: {session.task_json_path}

     ### Dependencies & Context
     **Dependencies**: {context.depends_on}
     **Inherited Context**: {context.inherited}
     **Previous Outputs**: {flow_context.step_outputs}

     ## Completion Requirements
     1. Execute all flow control steps if present
     2. Implement according to acceptance criteria
     3. Update TODO_LIST.md at provided path
     4. Generate summary in summaries directory
     5. Mark task as completed in task JSON",
     description="{task_description}")

Execution Flow

1. Prepare Agent Context: Assemble complete context package
2. Generate Prompt: Fill template with task and context data
3. Launch Agent: Invoke specialized agent with structured prompt
4. Monitor Execution: Track progress and handle errors
5. Collect Results: Process agent outputs and update status

Agent Assignment Rules

meta.agent specified → Use specified agent
meta.agent missing → Infer from meta.type:
  - "feature" → @code-developer
  - "test" → @code-review-test-agent
  - "review" → @code-review-agent
  - "docs" → @doc-generator

Error Handling During Execution

• Agent Failure: Retry once with adjusted context
• Flow Control Error: Skip optional steps, fail on critical
• Context Missing: Reload from JSON files and retry
• Timeout: Mark as blocked, continue with next task

Workflow File Structure Reference

.workflow/WFS-[topic-slug]/
├── workflow-session.json     # Session state and metadata
├── IMPL_PLAN.md             # Planning document and requirements
├── TODO_LIST.md             # Progress tracking (auto-updated)
├── .task/                   # Task definitions (JSON only)
│   ├── IMPL-1.json          # Main task definitions
│   └── IMPL-1.1.json        # Subtask definitions
├── .summaries/              # Task completion summaries
│   ├── IMPL-1-summary.md    # Task completion details
│   └── IMPL-1.1-summary.md  # Subtask completion details
└── .process/                # Planning artifacts
    └── ANALYSIS_RESULTS.md  # Planning analysis results

Error Handling & Recovery

Discovery Phase Errors

Error	Cause	Resolution	Command
No active session	No .active-* markers found	Create or resume session	/workflow:plan "project"
Multiple sessions	Multiple .active-* markers	Select specific session	Manual choice prompt
Corrupted session	Invalid JSON files	Recreate session structure	/workflow:status --validate
Missing task files	Broken task references	Regenerate tasks	/task:create or repair

Execution Phase Errors

Error	Cause	Recovery Strategy	Max Attempts
Agent failure	Agent crash/timeout	Retry with simplified context	2
Flow control error	Command failure	Skip optional, fail critical	1 per step
Context loading error	Missing dependencies	Reload from JSON, use defaults	3
JSON file corruption	File system issues	Restore from backup/recreate	1

Recovery Procedures

Session Recovery

# Check session integrity
find .workflow -name ".active-*" | while read marker; do
  session=$(basename "$marker" | sed 's/^\.active-//')
  if [ ! -d ".workflow/$session" ]; then
    echo "Removing orphaned marker: $marker"
    rm "$marker"
  fi
done

# Recreate corrupted session files
if [ ! -f ".workflow/$session/workflow-session.json" ]; then
  echo '{"session_id":"'$session'","status":"active"}' > ".workflow/$session/workflow-session.json"
fi

Task Recovery

# Validate task JSON integrity
for task_file in .workflow/$session/.task/*.json; do
  if ! jq empty "$task_file" 2>/dev/null; then
    echo "Corrupted task file: $task_file"
    # Backup and regenerate or restore from backup
  fi
done

# Fix missing dependencies
missing_deps=$(jq -r '.context.depends_on[]?' .workflow/$session/.task/*.json | sort -u)
for dep in $missing_deps; do
  if [ ! -f ".workflow/$session/.task/$dep.json" ]; then
    echo "Missing dependency: $dep - creating placeholder"
  fi
done

Context Recovery

# Reload context from available sources
if [ -f ".workflow/$session/.process/ANALYSIS_RESULTS.md" ]; then
  echo "Reloading planning context..."
fi

# Restore from documentation if available
if [ -d ".workflow/docs/" ]; then
  echo "Using documentation context as fallback..."
fi

Error Prevention

• Pre-flight Checks: Validate session integrity before execution
• Backup Strategy: Create task snapshots before major operations
• Atomic Updates: Update JSON files atomically to prevent corruption
• Dependency Validation: Check all depends_on references exist
• Context Verification: Ensure all required context is available

Usage Examples

Basic Usage

/workflow:execute          # Execute all pending tasks autonomously
/workflow:status           # Check progress
/task:execute IMPL-1.2     # Execute specific task

Integration

• Planning: /workflow:plan → /workflow:execute → /workflow:review
• Recovery: /workflow:status --validate → /workflow:execute