diff --git a/.codex/prompts/workflow/execute.md b/.codex/prompts/workflow/execute.md index ae69ccae..c4c9b07b 100644 --- a/.codex/prompts/workflow/execute.md +++ b/.codex/prompts/workflow/execute.md @@ -13,19 +13,48 @@ argument-hint: SESSION= Session folder path via `$SESSION` (e.g., `.workflow/active/WFS-auth-system`) +## 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 task statuses - 2. Find FIRST pending task with met dependencies - 3. Read task JSON from .task/{task-id}.json - 4. Execute task fully (pre-analysis → implementation → verification) - 5. Update task JSON status to "completed" - 6. Output progress: "[X/N] ✓ {task.title}" - 7. CONTINUE to next task (DO NOT STOP) + 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 @@ -47,8 +76,9 @@ If missing, report error and stop. ### Step 2: Parse TODO_LIST.md -Extract task list with current statuses: +Extract the ordered task list (IDs + titles). Do not treat checkbox states as authoritative. ```markdown +- ▸ **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) @@ -59,11 +89,13 @@ Extract task list with current statuses: ```javascript // Sequential scan for first eligible task for (task of todoList) { - if (task.completed) continue - - // Check dependencies from task JSON taskJson = read(`$SESSION/.task/${task.id}.json`) - if (taskJson.depends_on?.every(dep => isCompleted(dep))) { + 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 } } @@ -80,9 +112,28 @@ cat $SESSION/.task/$TASK_ID.json cat $SESSION/.process/context-package.json ``` -### Step 5: Execute Task +### Step 5: Initialize Task Tracking (Codex TODO tool) -#### 5A: Pre-Analysis (if flow_control.pre_analysis exists) +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: +```javascript +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) ```markdown ## Pre-Analysis for: [task.title] @@ -92,45 +143,50 @@ Execute each step: 3. [Load dependencies] ``` -#### 5B: Implementation +#### 6B: Implementation ```markdown ## Implementing: [task.title] -**Objective**: [context.objective] +**Requirements**: +- [context.requirements[0]] +- ... **Steps**: -1. [flow_control.execution_steps[0]] -2. [flow_control.execution_steps[1]] +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] ... -**Deliverables**: -- [ ] [context.deliverables[0]] -- [ ] [context.deliverables[1]] +**Focus Paths**: +- [context.focus_paths[0]] +- ... ``` -#### 5C: Verification +#### 6C: Verification ```markdown ## Verifying: [task.title] **Acceptance Criteria**: -- [x] [context.acceptance_criteria[0]] -- [x] [context.acceptance_criteria[1]] +- [x] [context.acceptance[0]] +- [x] [context.acceptance[1]] All criteria met: YES → Mark completed ``` -### Step 6: Update Status +### Step 7: Update Status + +Update task JSON with correct transitions: +- Before executing: `pending → in_progress` +- After verification: `in_progress → completed` -Update task JSON: ```json { "id": "IMPL-1.1", - "status": "completed", // Changed from "pending" + "status": "completed", "completed_at": "2025-12-15T..." } ``` -### Step 7: Continue Immediately +### Step 8: Continue Immediately **DO NOT STOP. Return to Step 2 to find next task.** @@ -146,19 +202,23 @@ Output progress: { "id": "IMPL-1.1", "title": "Task Title", - "status": "pending|completed", + "status": "pending|in_progress|completed|blocked|cancelled|container", "meta": { "type": "feature|test|docs", - "execution_group": "group-id" + "agent": "code-developer|test-fix-agent|..." }, "context": { - "objective": "What to achieve", - "deliverables": ["output 1", "output 2"], - "acceptance_criteria": ["check 1", "check 2"] + "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"], - "execution_steps": ["impl step 1", "impl step 2"] + "implementation_approach": [ + { "step": "Step 1", "action": "Do X" }, + { "step": "Step 2", "action": "Do Y" } + ] }, "depends_on": ["IMPL-1"] } @@ -169,9 +229,10 @@ Output progress: 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 completed right after verification +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 blocked, report and stop +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 @@ -208,5 +269,5 @@ When ALL tasks completed: | 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, mark task failed, continue to next | -| Verification failed | Retry once, then report and continue | +| 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 |