Claude-Code-Workflow/.codex/prompts/execute.md

description, argument-hint

description	argument-hint
Execute workflow tasks sequentially from session folder. Supports parallel execution and task filtering.	SESSION=<path-to-session-folder> [--parallel] [--filter=<pattern>] [--skip-tests]

Workflow Execute (Codex Version)

Core Principle

Serial Execution: Execute tasks ONE BY ONE in dependency order. Complete current task fully before moving to next. Continue autonomously until ALL tasks complete.

Input

Session folder path via $SESSION (e.g., .workflow/active/WFS-auth-system)

• --parallel: Execute tasks in parallel (default: sequential)
• --filter: Filter tasks by pattern (e.g., IMPL-1.*)
• --skip-tests: Skip test execution

Task Tracking (JSON Source of Truth + Codex TODO Tool)

• Source of truth: Task state MUST be read from and written to $SESSION/.task/IMPL-*.json.
• Markdown views: $SESSION/TODO_LIST.md and $SESSION/IMPL_PLAN.md are views; use them for ordering and display, but do NOT trust them for status.
• Codex TODO tool: Mirror the workflow into the built-in update_plan tool so progress is visible and consistent.

Status mapping (Task JSON → update_plan)

• Task JSON uses workflow statuses (source of truth): pending, in_progress, completed (optionally also blocked, cancelled, container).
• update_plan only supports: pending, in_progress, completed.
• Map as:
  • pending|blocked|cancelled|container → pending
  • in_progress → in_progress
  • completed → completed

update_plan rules (must follow)

1. At most ONE step can be in_progress at a time.
2. Do NOT jump pending → completed; always go through in_progress.
3. Do NOT batch-complete steps after the fact; update as you go.
4. If the plan changes (new tasks, re-order, merge/split), call update_plan with an explanation.
5. After calling update_plan, do NOT repeat the full plan in chat; only output a short progress line.
6. Keep each step short and stable (ID-first), e.g. IMPL-1.1 - Add JWT middleware.

Autonomous Execution Loop

INIT: Validate session folder structure

WHILE tasks remain:
  1. Read TODO_LIST.md → Get ordered task IDs (ignore checkbox status)
  2. For each task ID, read $SESSION/.task/{task-id}.json → Get true status + deps
  3. Find FIRST eligible task:
     - status != "completed"
     - deps = taskJson.depends_on OR taskJson.context.depends_on (source of truth)
     - deps all completed (from JSON)
     - task is executable (skip status="container" or tasks with subtasks)
  4. Mark task JSON status to "in_progress" (immediately)
  5. Mirror status to `update_plan` (exactly one in_progress)
  6. Execute task fully (pre-analysis → implementation → verification)
  7. Mark task JSON status to "completed" (immediately after verification)
  8. Mirror completion to `update_plan`, output progress line, CONTINUE (DO NOT STOP)

WHEN all tasks completed:
  Output final summary

Execution Steps

Step 1: Validate Session

Check required files exist:

$SESSION/
├── IMPL_PLAN.md        ← Required
├── TODO_LIST.md        ← Required
└── .task/              ← Required, must have IMPL-*.json

If missing, report error and stop.

Step 2: Parse TODO_LIST.md

Extract the ordered task list (IDs + titles). Do not treat checkbox states as authoritative.

- ▸ **IMPL-1**: Parent task (container)
- [x] IMPL-1: Task 1 title (completed)
- [ ] IMPL-1.1: Task 2 title (pending) ← Execute this
- [ ] IMPL-2: Task 3 title (pending, depends on IMPL-1.1)

Step 3: Find Next Executable Task

// Sequential scan for first eligible task
for (task of todoList) {
  taskJson = read(`$SESSION/.task/${task.id}.json`)
  if (taskJson.status === "completed") continue
  if (taskJson.status === "container") continue
  
  // Check dependencies from task JSON (source of truth)
  const deps = taskJson.depends_on || taskJson.context?.depends_on || []
  if (deps.every(dep => read(`$SESSION/.task/${dep}.json`).status === "completed")) {
    return task  // Execute this one
  }
}
return null  // All done or all blocked

Step 4: Load Task Context

# Read task definition
cat $SESSION/.task/$TASK_ID.json

# Read context package if exists
cat $SESSION/.process/context-package.json

Step 5: Initialize Task Tracking (Codex TODO tool)

Before executing the first task, initialize update_plan from the ordered task list:

• Only include executable tasks (skip containers) to avoid non-actionable TODO items.
• step: Use a stable ID-first label like IMPL-1.1 - {title}.
• status: Map from task JSON status using the rules above.

Keep this plan updated throughout execution (see rules above).

Example initialization:

update_plan({
  plan: [
    { step: "IMPL-1.1 - Task title", status: "pending" },
    { step: "IMPL-2 - Task title", status: "pending" }
  ]
})

Step 6: Execute Task

6A: Pre-Analysis (if flow_control.pre_analysis exists)

## Pre-Analysis for: [task.title]

Execute each step:
1. [Read referenced files]
2. [Search for patterns]
3. [Load dependencies]

6B: Implementation

## Implementing: [task.title]

**Requirements**:
- [context.requirements[0]]
- ...

**Steps**:
1. [flow_control.implementation_approach[0].step] - [flow_control.implementation_approach[0].action]
2. [flow_control.implementation_approach[1].step] - [flow_control.implementation_approach[1].action]
...

**Focus Paths**:
- [context.focus_paths[0]]
- ...

6C: Verification

## Verifying: [task.title]

**Acceptance Criteria**:
- [x] [context.acceptance[0]]
- [x] [context.acceptance[1]]

All criteria met: YES → Mark completed

Step 7: Update Status

Update task JSON with correct transitions:

• Before executing: pending → in_progress
• After verification: in_progress → completed

{
  "id": "IMPL-1.1",
  "status": "completed",
  "completed_at": "2025-12-15T..."
}

Step 8: Continue Immediately

DO NOT STOP. Return to Step 2 to find next task.

Output progress:

✓ [3/7] Completed: IMPL-1.1 - [task title]
→ Next: IMPL-2 - [next task title]

Task JSON Structure

{
  "id": "IMPL-1.1",
  "title": "Task Title",
  "status": "pending|in_progress|completed|blocked|cancelled|container",
  "meta": {
    "type": "feature|test|docs",
    "agent": "code-developer|test-fix-agent|..."
  },
  "context": {
    "requirements": ["Requirement 1", "Requirement 2"],
    "focus_paths": ["src/module/"],
    "acceptance": ["Criterion 1", "Criterion 2"],
    "depends_on": ["IMPL-1"]
  },
  "flow_control": {
    "pre_analysis": ["step 1", "step 2"],
    "implementation_approach": [
      { "step": "Step 1", "action": "Do X" },
      { "step": "Step 2", "action": "Do Y" }
    ]
  },
  "depends_on": ["IMPL-1"]
}

Execution Rules

1. Never stop mid-workflow - Continue until all tasks complete
2. One task at a time - Fully complete before moving on
3. Respect dependencies - Skip blocked tasks, find next eligible
4. Update status immediately - Mark in_progress on start, completed right after verification
5. Self-verify - All acceptance criteria must pass before marking done
6. Handle blocked state - If all remaining tasks have unmet deps, report and stop
7. Keep tracking in sync - Task JSON is truth; update_plan must reflect the same state

Final Summary

When ALL tasks completed:

## Workflow Execution Complete

**Session**: $SESSION
**Total Tasks**: N
**Completed**: N

### Execution Log
| # | Task ID | Title | Status |
|---|---------|-------|--------|
| 1 | IMPL-1 | ... | ✓ |
| 2 | IMPL-1.1 | ... | ✓ |
| 3 | IMPL-2 | ... | ✓ |

### Files Modified
- `src/auth/login.ts`
- `src/utils/validator.ts`

### Summary
[What was accomplished across all tasks]

Error Handling

Situation	Action
Session folder not found	Error and stop
Missing required files	Error: specify which file missing
Task JSON not found	Error, skip task, continue
Task blocked (deps not met)	Skip, find next eligible task
All tasks blocked	Report circular dependency, stop
Execution error	Report, set task JSON back to pending, continue to next eligible task
Verification failed	Retry once; if still failing, set back to pending and continue