--- name: execute description: Coordinate agents for existing workflow tasks with automatic discovery usage: /workflow:execute argument-hint: none examples: - /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 ```markdown # 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: ```json { "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 ```bash 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 ```pseudo 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 ```bash # 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 ```bash # 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 ```json // 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 ```json { "current_phase": "EXECUTE", "last_execute_run": "2025-09-08T14:30:00Z" } ``` ## Error Handling & Recovery ### Discovery Issues ```bash # 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 ```bash # 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