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 (/workflow:execute)

Overview

Coordinates multiple agents for executing existing workflow tasks through automatic discovery and intelligent task orchestration. Analyzes workflow folders, checks task statuses, and coordinates agent execution based on discovered plans.

Core Principles

Execution Philosophy

The intelligent execution approach focuses on:

• Discovery-first execution - Automatically discover existing plans and tasks
• Status-aware coordination - Execute only tasks that are ready
• Context-rich agent assignment - Use complete task JSON data for agent context
• Dynamic task orchestration - Coordinate based on discovered task relationships
• Progress tracking - Update task status after agent completion

Analysis Markers:

• [GEMINI_CLI_REQUIRED]: Forces agent to use Gemini CLI for pattern-based codebase analysis
  • Auto-trigger: When task.analysis_source = "gemini" OR scope > 3 files (default)
  • Agent Action: MUST execute Gemini CLI as first step
• [CODEX_CLI_REQUIRED]: Forces agent to use Codex CLI for autonomous development analysis
  • Auto-trigger: When task.analysis_source = "codex"
  • Agent Action: MUST execute Codex CLI in autonomous mode as first step

analysis_source to Marker Mapping:

• "gemini" → Add [GEMINI_CLI_REQUIRED]
• "codex" → Add [CODEX_CLI_REQUIRED]
• "auto-detected" + scope > 3 files → Add [GEMINI_CLI_REQUIRED] (default)
• "manual" → No marker added

Execution Flow

1. Discovery & Analysis Phase

Workflow Discovery:
├── Locate workflow folder (provided or current session)
├── Load workflow-session.json for session state  
├── Scan .task/ directory for all task JSON files
├── Read IMPL_PLAN.md for workflow context
├── Analyze task statuses and dependencies
└── Determine executable tasks

Discovery Logic:

• Folder Detection: Use provided folder or find current active session
• Task Inventory: Load all impl-*.json files from .task/ directory
• Status Analysis: Check pending/active/completed/blocked states
• Dependency Check: Verify all task dependencies are met
• Execution Queue: Build list of ready-to-execute tasks

2. TodoWrite Coordination Setup

Always First: Create comprehensive TodoWrite based on discovered tasks

# Workflow Execute Coordination
*Session: WFS-[topic-slug]*

## Execution Plan
- [ ] **TASK-001**: [Agent: planning-agent] [GEMINI_CLI_REQUIRED] Design auth schema (impl-1.1)
- [ ] **TASK-002**: [Agent: code-developer] [CODEX_CLI_REQUIRED] Implement auth logic (impl-1.2)  
- [ ] **TASK-003**: [Agent: code-review-agent] Review implementations
- [ ] **TASK-004**: Update task statuses and session state

**Marker Legend**: 
- [GEMINI_CLI_REQUIRED] = Agent must use Gemini CLI for pattern analysis
- [CODEX_CLI_REQUIRED] = Agent must use Codex CLI for autonomous analysis

3. Agent Context Assignment

For each executable task:

{
  "task": {
    "id": "impl-1.1",
    "title": "Design auth schema",
    "context": {
      "requirements": ["JWT authentication", "User model design"],
      "scope": ["src/auth/models/*"],
      "acceptance": ["Schema validates JWT tokens"]
    },
    "implementation": {
      "files": [
        {
          "path": "src/auth/models/User.ts",
          "location": {
            "function": "UserSchema",
            "lines": "10-50",
            "description": "User model definition"
          },
          "original_code": "// Requires gemini analysis for current schema",
          "modifications": {
            "current_state": "Basic user model without auth fields",
            "proposed_changes": [
              "Add JWT token fields to schema",
              "Include OAuth provider fields"
            ],
            "logic_flow": [
              "createUser() ───► validateSchema() ───► generateJWT()",
              "◊─── if OAuth ───► linkProvider() ───► storeTokens()"
            ],
            "reason": "Support modern authentication patterns",
            "expected_outcome": "Flexible user schema supporting multiple auth methods"
          }
        }
      ],
      "context_notes": {
        "dependencies": ["mongoose", "jsonwebtoken"],
        "affected_modules": ["auth-middleware", "user-service"],
        "risks": [
          "Schema changes require database migration",
          "Existing user data compatibility"
        ],
        "performance_considerations": "Index JWT fields for faster lookups",
        "error_handling": "Graceful schema validation errors"
      },
      "analysis_source": "auto-detected"
    }
  },
  "workflow": {
    "session": "WFS-user-auth", 
    "phase": "IMPLEMENT",
    "plan_context": "Authentication system with OAuth2 support"
  },
  "focus_modules": ["src/auth/", "tests/auth/"],
  "gemini_required": true
}

Context Assignment Rules:

• Complete Context: Use full task JSON context including implementation field for agent execution
• Implementation Details: Pass complete implementation.files array to agents for precise execution
• Code Context: Include original_code snippets and logic_flow diagrams in agent prompts
• Risk Awareness: Alert agents to implementation.context_notes.risks before execution
• Workflow Integration: Include session state and IMPL_PLAN.md context
• Scope Focus: Direct agents to specific files from implementation.files[].path
• Gemini Marker: Auto-add [GEMINI_CLI_REQUIRED] when analysis_source = "gemini"

4. Agent Execution & Progress Tracking

Task(subagent_type="code-developer",
     prompt="[GEMINI_CLI_REQUIRED] Implement authentication logic based on schema
     
     Task Context: impl-1.2 - Implement auth logic
     Session Context:
     - Workflow Directory: .workflow/WFS-user-auth/
     - TODO_LIST Location: .workflow/WFS-user-auth/TODO_LIST.md
     - Summaries Directory: .workflow/WFS-user-auth/.summaries/
     - Task JSON Location: .workflow/WFS-user-auth/.task/impl-1.2.json
     
     Implementation Details:
     - Target File: src/auth/models/User.ts
     - Function: UserSchema (lines 10-50)
     - Current State: Basic user model without auth fields
     - Required Changes: Add JWT token fields, Include OAuth provider fields
     - Logic Flow: createUser() ───► validateSchema() ───► generateJWT()
     - Dependencies: mongoose, jsonwebtoken
     - Risks: Schema changes require database migration, Existing user data compatibility
     - Performance: Index JWT fields for faster lookups
     
     Focus Paths (from task JSON): $(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json)
     Gemini Command: gemini -p "$(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}"
     
     IMPORTANT: Update TODO_LIST.md and create summary in provided directories upon completion.
     Use implementation details above for precise, targeted development.",
     description="Execute impl-1.2 with full workflow context and implementation details")

Execution Protocol:

• Sequential Execution: Respect task dependencies and execution order
• Progress Monitoring: Track through TodoWrite updates
• Status Updates: Update task JSON status after each completion
• Cross-Agent Handoffs: Coordinate results between related tasks

Discovery & Analysis Process

File Structure Analysis

.workflow/WFS-[topic-slug]/
├── workflow-session.json     # Session state and stats
├── IMPL_PLAN.md             # Workflow context and requirements  
├── .task/                   # Task definitions
│   ├── impl-1.json         # Main tasks
│   ├── impl-1.1.json       # Subtasks
│   └── impl-1.2.json       # Detailed tasks
└── .summaries/             # Completed task summaries

Task Status Assessment

function analyze_tasks(task_files):
  executable_tasks = []
  
  for task in task_files:
    if task.status == "pending" and dependencies_met(task):
      if task.subtasks.length == 0:  // leaf task
        executable_tasks.append(task)
      else:  // container task - check subtasks
        if all_subtasks_ready(task):
          executable_tasks.extend(task.subtasks)
  
  return executable_tasks

Automatic Agent Assignment

Based on discovered task data:

• task.agent field: Use specified agent from task JSON
• task.type analysis:
  • "feature" → code-developer
  • "test" → code-review-test-agent
  • "docs" → code-developer
  • "review" → code-review-agent
• Gemini context: Auto-assign based on task.context.scope and requirements

Agent Task Assignment Patterns

Discovery-Based Assignment

# Agent receives complete discovered context
Task(subagent_type="code-developer",
     prompt="[GEMINI_CLI_REQUIRED] Execute impl-1.2: Implement auth logic
     
     Context from discovery:
     - Requirements: JWT authentication, OAuth2 support
     - Scope: src/auth/*, tests/auth/*
     - Dependencies: impl-1.1 (completed)
     - Workflow: WFS-user-auth authentication system
     
     Session Context:
     - Workflow Directory: .workflow/WFS-user-auth/
     - TODO_LIST Location: .workflow/WFS-user-auth/TODO_LIST.md
     - Summaries Directory: .workflow/WFS-user-auth/.summaries/
     - Task JSON: .workflow/WFS-user-auth/.task/impl-1.2.json
     
     Focus Paths: $(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json)
     Analysis Command: Use gemini -p \"$(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}\"
     
     CRITICAL: Use task-specific paths for focused analysis. Update TODO_LIST.md and create completion summary using provided paths.",
     
     description="Agent executes with task-specific paths and full discovered context")

Status Tracking Integration

# After agent completion, update discovered task status
update_task_status("impl-1.2", "completed")
mark_dependent_tasks_ready(task_dependencies)

Coordination Strategies

Automatic Coordination

• Task Dependencies: Execute in dependency order from discovered relationships
• Agent Handoffs: Pass results between agents based on task hierarchy
• Progress Updates: Update TodoWrite and JSON files after each completion

Context Distribution

• Rich Context: Each agent gets complete task JSON + workflow context
• Focus Areas: Direct agents to specific files from task.context.scope
• Inheritance: Subtasks inherit parent context automatically
• Session Integration: Include workflow-session.json state in agent context

Status Management

Task Status Updates

// Before execution
{
  "id": "impl-1.2",
  "status": "pending",
  "execution": {
    "attempts": 0,
    "last_attempt": null
  }
}

// After execution  
{
  "id": "impl-1.2", 
  "status": "completed",
  "execution": {
    "attempts": 1,
    "last_attempt": "2025-09-08T14:30:00Z"
  }
}

Session State Updates

{
  "current_phase": "EXECUTE",
  "last_execute_run": "2025-09-08T14:30:00Z"
}

Error Handling & Recovery

Discovery Issues

# No active session found
❌ No active workflow session found
→ Use: /workflow:session:start "project name" first

# No executable tasks  
⚠️ All tasks completed or blocked
→ Check: /context for task status overview

# Missing task files
❌ Task impl-1.2 referenced but JSON file missing
→ Fix: /task/create or repair task references

Execution Recovery

• Failed Agent: Retry with adjusted context or different agent
• Blocked Dependencies: Skip and continue with available tasks
• Context Issues: Reload from JSON files and session state

Integration Points

Automatic Behaviors

• Discovery on start - Analyze workflow folder structure
• TodoWrite coordination - Generate based on discovered tasks
• Agent context preparation - Use complete task JSON data
• Status synchronization - Update JSON files after completion

Next Actions

# After /workflow:execute completion
/context                  # View updated task status
/task:execute impl-X      # Execute specific remaining tasks  
/workflow:review          # Move to review phase when complete

Related Commands

• /context - View discovered tasks and current status
• /task:execute - Execute individual tasks (user-controlled)
• /workflow:session:status - Check session progress and dependencies
• /workflow:review - Move to review phase after completion

---

System ensures: Intelligent task discovery with context-rich agent coordination and automatic progress tracking