start-phase-execute

name	start-phase-execute
description	Mode 2 - Structured execution with quality gates (Part 1-5) with pm-db tracking. Use when Codex should run the converted start-phase-execute workflow. Inputs: task_list_file, extra_instructions, spec_id.

Start Phase Execute

Converted Claude skill workflow for Codex/OpenAI use.

Source

Converted from skills/start-phase-execute/SKILL.md.

Converted Instructions

The content below was adapted from the Claude source. Rewrite tool and runtime assumptions as needed when they refer to Claude-only features.

Codex Adaptation Notes

• Invoke this workflow as $start-phase-execute <task_list_file>.
• References to hooks, cache_wrapper.py, subagents, or parallel Task tool calls are optional host-side orchestration patterns from the original Claude setup.
• In Codex, prefer direct skill invocation, direct file edits, and explicit shell commands. If you want PM-DB-style automation, wire it from the migrated pm-db assets or your own host application.
• When this document says "agent" or "subagent", interpret that as either another Codex session, a direct invocation of a migrated specialist skill, or manual execution in the current session.

Start-Phase: Mode 2 (Execute) with PM-DB Tracking

Structured execution with quality gates enforcement and automatic project management database tracking.

Usage

# Basic execution
$start-phase-execute /path/to/task-list.md

# With extra instructions
$start-phase-execute /path/to/task-list.md "Focus on type safety and add extra error handling"

# With specific spec ID for tracking
$start-phase-execute /path/to/task-list.md "" 4

Example:

$start-phase-execute ./job-queue/prototype-build/tasks.md
$start-phase-execute ./job-queue/auth/tasks.md "Use bcrypt for passwords, add rate limiting"
$start-phase-execute ./job-queue/feature-dynamodb-profile-schema/tasks.md "" 4

Purpose

Mode 2 implements the complete execution workflow:

• Part 1: Finalize plan + create directories + initialize pm-db job
• Part 2: Detailed planning (3 required docs)
• Part 3: Execute tasks with agent personas + pm-db task tracking
• Part 3.5: Quality gates and code review tracking, either manually or via optional host automation
• Part 4: Task updates + commits
• Part 5: Phase closeout + summary + complete pm-db job

Critical: Path Management

NEVER lose these paths during execution:

Task list file: /path/to/folder/tasks.md

Derived paths (PERMANENT for this phase):
• input_folder: /path/to/folder
• planning_folder: /path/to/folder/planning

All artifacts go in planning_folder!

---

Part 1: Finalize Plan & Create Directories

Step 1.1: Extract Folder Locations

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚀 Mode 2: Execute
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Task list: {task_list_file}
Input folder: {input_folder}
Planning folder: {planning_folder}

Extra instructions: {extra_instructions or "None"}
Spec ID: {spec_id or "Auto-detect"}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Part 1: Finalizing plan and creating structure...

Store these permanently:

input_folder = directory containing {task_list_file}
planning_folder = {input_folder}/planning
phase_name = extracted from task list or folder name

---

Step 1.2: Read Approved Task List

Read {task_list_file}

Extract:

• Phase name
• All tasks
• Parallel waves (if defined)
• Dependencies

---

Step 1.2b: Initialize PM-DB Job Tracking

If you have wired the original PM-DB hook scripts into your host environment, you can use them here. Otherwise, initialize tracking manually with the pm-db scripts or direct database updates.

Create phase run record in pm-db for this execution:

# Determine project_name from input_folder
# e.g., "feature-dynamodb-profile-schema" → extract project context
feature_name=$(basename "$input_folder" | sed 's/^feature-//')
project_name=${project_name:-$feature_name}

# Initialize phase run tracking
hook_output=$(cat <<EOF | python3 ~/.codex/hooks$pm-db/on-phase-run-start.py
{
  "phase_name": "$phase_name",
  "project_name": "$project_name",
  "assigned_agent": "start-phase-execute"
}
EOF
)

Capture phase_run_id from hook output:

# Hook outputs: {"phase_run_id": 42, "phase_id": 7, "plan_id": 12, "status": "started"}
phase_run_id=$(echo "$hook_output" | jq -r '.phase_run_id')
phase_id=$(echo "$hook_output" | jq -r '.phase_id')
plan_id=$(echo "$hook_output" | jq -r '.plan_id')

Store phase_run_id for the session:

PM_DB_PHASE_RUN_ID=$phase_run_id

✅ PM-DB Phase Run Created
   Phase Run ID: $phase_run_id
   Phase ID: $phase_id
   Plan ID: $plan_id
   Phase: $phase_name

Tracking active at: ~/.codex/projects.db

---

Step 1.2c: Initialize Agent Invocation Tracking

Start cache tracking for this execution session:

# Initialize invocation linked to phase_run
invocation_output=$(python3 ~/.codex/skills/start-phase/scripts/cache_wrapper.py init \
    --agent-name "start-phase-execute" \
    --purpose "Execute phase: $phase_name" \
    --phase-run-id $phase_run_id 2>/dev/null)

# Extract invocation_id
INVOCATION_ID=$(echo "$invocation_output" | jq -r '.invocation_id')

Store for this session:

✅ Agent Invocation ID: $INVOCATION_ID

Cache tracking active:
• Linked to Phase Run: $phase_run_id
• All file reads will be tracked
• Sub-agent invocations will be linked

---

Step 1.3: Update Task List (if needed from Mode 1)

If task list was refined in Mode 1:

Updating task list with approved changes...

Edit {task_list_file}
# Write refined task list from Mode 1

Confirm:

✅ Task list finalized: {task_list_file}

---

Step 1.4: Check for Existing Planning Folder

CRITICAL: Check if planning/ already exists (resume support):

ls -la "{planning_folder}" 2>/dev/null

If planning folder EXISTS:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  Existing Planning Folder Detected
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Found: {planning_folder}/

Analyzing existing state...

Count task update files:

ls {planning_folder}/task-updates/*.md 2>/dev/null | wc -l

Read task list to get total tasks:

grep -c "^### Task\|^##.*Task" {task_list_file}

Present resume options:

Detected state:
• task-updates/: 8/40 files present (20% complete)
• Last completed: Task 8 (Mock Data Management System)
• Last modified: 2 hours ago

Options:
1. ✅ Resume from Task 9 (recommended)
   → Skip completed tasks, continue from where you left off
   → Existing quality gates preserved
   → Faster execution (skip 8 tasks)

2. 🔄 Start over (delete existing planning/)
   → WARNING: Will lose all progress tracking
   → Use if previous execution had errors
   → Full re-execution of all tasks

3. ❌ Cancel
   → Exit without changes

Which option? (1/2/3)

Handle user response:

Option 1 (Resume):

✅ Resuming from Task 9

Skipping completed tasks:
✓ Task 1: Create API Route File Structure
✓ Task 2: Implement Email Validation Function
...
✓ Task 8: Mock Data Management System

Starting: Task 9: Implement Already Verified Check

Option 2 (Start over):

🔄 Starting over

Backing up existing planning folder...

mv {planning_folder} {planning_folder}.backup.$(date +%Y%m%d-%H%M%S)

✅ Backup created: {planning_folder}.backup.20260117-143022

Creating fresh planning structure...

Option 3 (Cancel):

❌ Execution cancelled

Planning folder preserved at: {planning_folder}

---

Step 1.5: Create Directory Structure (if needed)

If no existing planning folder OR user chose "start over":

Create all required planning directories:

mkdir -p "{planning_folder}/task-updates"
mkdir -p "{planning_folder}/agent-delegation"
mkdir -p "{planning_folder}/phase-structure"
mkdir -p "{planning_folder}/code-reviews"

Confirm creation:

✅ Directory structure created:

{planning_folder}/
├── task-updates/
├── agent-delegation/
├── phase-structure/
└── code-reviews/

All phase artifacts will be stored here.

If resuming:

✅ Using existing directory structure

{planning_folder}/
├── task-updates/ (8 existing files preserved)
├── agent-delegation/ (existing files preserved)
├── phase-structure/ (existing files preserved)
└── code-reviews/ (existing files preserved)

Resuming execution from Task 9...

---

Step 1.6: Validate Structure

python skills/start-phase/scripts/validate_phase.py {input_folder}

Expected:

{
  "valid": true,
  "errors": [],
  "warnings": ["Planning files not created yet (expected)"],
  "structure_complete": false
}

Confirm:

✅ Part 1 complete: Structure ready for detailed planning

---

Part 2: Detailed Planning & Analysis

Step 2.1: Create Task Delegation Document

Analyze tasks and assign agents:

Creating task delegation plan...

Create {planning_folder}/agent-delegation/task-delegation.md:

# Task Delegation: {phase_name}

## Agent Assignments

### Available Agents
- code-reviewer
- frontend-developer
- nextjs-backend-developer
- ui-developer
- qa-engineer

## Task Assignments

```mermaid
graph TD
    T1[Task 1: Setup auth API] --> A1[nextjs-backend-developer]
    T1 --> P1[Priority: HIGH]
    T1 --> D1[Difficulty: MEDIUM]

    T2[Task 2: Create login UI] --> A2[ui-developer]
    T2 --> P2[Priority: HIGH]
    T2 --> D2[Difficulty: EASY]

    T3[Task 3: Integration] --> A3[nextjs-backend-developer]
    T3 --> P3[Priority: HIGH]
    T3 --> D3[Difficulty: MEDIUM]
    T3 --> DEP1[Depends: T1, T2]

    T4[Task 4: Add JWT] --> A4[nextjs-backend-developer]
    T4 --> P4[Priority: MEDIUM]
    T4 --> D4[Difficulty: MEDIUM]

    T5[Task 5: Write tests] --> A5[qa-engineer]
    T5 --> P5[Priority: MEDIUM]
    T5 --> D5[Difficulty: HARD]

Task Details

Task	Agent	Priority	Difficulty	Dependencies	Est. Time
1. Setup auth API	nextjs-backend-developer	HIGH	MEDIUM	None	1h
2. Create login UI	ui-developer	HIGH	EASY	None	1h
3. Integration	nextjs-backend-developer	HIGH	MEDIUM	T1, T2	30m
4. Add JWT	nextjs-backend-developer	MEDIUM	MEDIUM	T1	1h
5. Write tests	qa-engineer	MEDIUM	HARD	T1-T4	1.5h

Agent Workload

• nextjs-backend-developer: 3 tasks (~2.5h)
• ui-developer: 1 task (~1h)
• qa-engineer: 1 task (~1.5h)

**Confirm:**

✅ Task delegation created: {planning_folder}/agent-delegation/task-delegation.md

---

### Step 2.2: Create Sub-Agent Parallel Plan

**Define parallel execution strategy:**

Creating parallel execution plan...

**Create `{planning_folder}/agent-delegation/sub-agent-plan.md`:**

```markdown
# Sub-Agent Parallel Execution Plan: {phase_name}

## Parallel Execution Strategy

**IMPORTANT:** This phase will use parallel agent execution where possible.

### Wave 1: Initial Parallel Execution

**Spawn SUBAGENT WORKERS IN PARALLEL to complete these tasks:**

1. **Task 1: Setup auth API** (nextjs-backend-developer)
   - Independent: Yes
   - Can start: Immediately
   - Output: Working API endpoint

2. **Task 2: Create login UI** (ui-developer)
   - Independent: Yes
   - Can start: Immediately
   - Output: Login form component

**Expected:** Both tasks complete simultaneously (~1h total, not 2h)

---

### Wave 2: Integration (Sequential)

3. **Task 3: Integration** (nextjs-backend-developer)
   - Depends on: Task 1 ✅, Task 2 ✅
   - Must wait for: Wave 1 complete
   - Output: End-to-end working login

---

### Wave 3: Feature Addition (Parallel)

**Spawn SUBAGENT WORKERS IN PARALLEL to complete these tasks:**

4. **Task 4: Add JWT** (nextjs-backend-developer)
   - Depends on: Task 1 ✅
   - Can run parallel with: Task 5
   - Output: JWT token generation

5. **Task 5: Add DB schema** (nextjs-backend-developer)
   - Depends on: Task 1 ✅
   - Can run parallel with: Task 4
   - Output: User table created

---

### Wave 4: Finalization (Sequential)

6. **Task 6: Write tests** (qa-engineer)
   - Depends on: All previous tasks ✅
   - Must wait for: Wave 3 complete
   - Output: Integration tests passing

## Execution Instructions

When executing parallel waves:

1. **Announce wave start:**

Starting Wave 1 (Parallel Execution) Spawning 2 subagent workers...

2. **Launch agents using delegation workflow:**
- Use delegation workflow with skill for each agent
- Provide clear, isolated task descriptions
- Ensure no shared file conflicts

3. **Wait for wave completion:**

Wave 1 complete: ✅ Task 1: Complete ✅ Task 2: Complete

4. **Proceed to next wave**

## Benefits of Parallel Execution

- **Time savings:** Wave 1 takes 1h (not 2h)
- **Resource utilization:** Multiple agents working simultaneously
- **Faster iteration:** Shorter feedback loops

## Constraints

- **No file conflicts:** Tasks must modify different files
- **Clear API contracts:** Frontend/backend need agreed interface
- **Independent work:** Each task self-contained within wave

Confirm:

✅ Parallel execution plan created: {planning_folder}/agent-delegation/sub-agent-plan.md

---

Step 2.3: Create System Changes Analysis

Identify impacted files:

Analyzing system changes...

Create {planning_folder}/phase-structure/system-changes.md:

# System Changes Analysis: {phase_name}

## Impacted Files

### File Relationships

```mermaid
flowchart TD
    A[src/api/auth.ts] --> B[src/lib/db.ts]
    A --> C[src/types/user.ts]
    D[src/components/LoginForm.tsx] --> C
    D --> E[src/lib/api-client.ts]
    E --> A
    F[tests/auth.test.ts] --> A
    F --> D

SLOC Tracking

Baseline SLOC

File	Baseline SLOC	Current SLOC	Delta	Change %
src/api/auth.ts	0 (new)	TBD	TBD	TBD
src/lib/db.ts	156	TBD	TBD	TBD
src/types/user.ts	23	TBD	TBD	TBD
src/components/LoginForm.tsx	0 (new)	TBD	TBD	TBD
src/lib/api-client.ts	89	TBD	TBD	TBD
tests/auth.test.ts	0 (new)	TBD	TBD	TBD

Total baseline: 268 SLOC Projected addition: ~800-1000 SLOC

Files by Category

New files: 3

• src/api/auth.ts
• src/components/LoginForm.tsx
• tests/auth.test.ts

Modified files: 3

• src/lib/db.ts (add user table)
• src/types/user.ts (add User type)
• src/lib/api-client.ts (add auth methods)

Deleted files: 0

Change Impact

High Impact (Core Changes)

• src/api/auth.ts - New auth API endpoint
• src/lib/db.ts - Database schema changes

Medium Impact (Integration)

• src/components/LoginForm.tsx - New UI component
• src/lib/api-client.ts - API client updates

Low Impact (Types & Tests)

• src/types/user.ts - Type definitions
• tests/auth.test.ts - Test coverage

**Initialize SLOC baseline:**
```bash
python skills/start-phase/scripts/sloc_tracker.py {input_folder} --baseline \
  src/lib/db.ts \
  src/types/user.ts \
  src/lib/api-client.ts

Confirm:

✅ System changes analysis created: {planning_folder}/phase-structure/system-changes.md
✅ SLOC baseline captured: {planning_folder}/phase-structure/.sloc-baseline.json

---

Part 2 Complete:

✅ Part 2 complete: All planning documents created

Created:
• task-delegation.md (agent assignments)
• sub-agent-plan.md (parallel strategy)
• system-changes.md (file impacts + SLOC)

---

Part 3: Parallel Task Execution

Step 3.1: Begin Task Execution

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔨 Part 3: Task Execution
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Executing tasks according to delegation plan...

---

Step 3.2: Execute Tasks by Wave

For each wave in sub-agent-plan.md:

Sequential Tasks

Before starting task - show progress:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Phase Progress
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Overall: [████████████░░░░░░░░] 12/40 tasks (30%)

Recently completed:
✅ Task 10: Implement Token Generation and Database Update (25m)
✅ Task 11: Implement Email Sending (18m)
✅ Task 12: Implement Success Response (8m)

Current wave: Wave 3 (Sequential - Error Handling)
▶ Starting Task 13: Add Comprehensive Error Logging
  Agent: nextjs-backend-developer
  Priority: P1 (High)
  Estimated time: 15 minutes

Next up:
⏳ Task 14: Test API Route Manually (P0, 30m)
⏳ Task 15: Read Existing Verify Email Page Component (P0, 15m)

Time tracking:
• Elapsed: 4h 12m
• Estimated remaining: ~10h 30m
• Expected completion: Today at 18:45

Quality gates: 12/12 passed ✅
Last commit: 8 minutes ago

Create PM-DB task run record:

hook_output=$(cat <<EOF | python3 ~/.codex/hooks$pm-db/on-task-run-start.py
{
  "phase_run_id": $PM_DB_PHASE_RUN_ID,
  "task_key": "13",
  "assigned_agent": "nextjs-backend-developer"
}
EOF
)

Capture task_run_id:

# Hook outputs: {"task_run_id": 123, "task_id": 45, "status": "started"}
PM_DB_TASK_RUN_ID=$(echo "$hook_output" | jq -r '.task_run_id')

✅ PM-DB Task Run Created (ID: $PM_DB_TASK_RUN_ID)

Create agent invocation for task execution:

# Initialize sub-agent invocation
subagent_invocation=$(python3 ~/.codex/skills/start-phase/scripts/cache_wrapper.py init \
    --agent-name "{agent_persona}" \
    --purpose "Task {n}: {task_name}" \
    --phase-run-id $PM_DB_PHASE_RUN_ID \
    --task-run-id $PM_DB_TASK_RUN_ID 2>/dev/null)

SUBAGENT_INVOCATION_ID=$(echo "$subagent_invocation" | jq -r '.invocation_id')

✅ Sub-agent invocation created (ID: $SUBAGENT_INVOCATION_ID)
   Linked to: Phase Run $PM_DB_PHASE_RUN_ID, Task Run $PM_DB_TASK_RUN_ID

Now launch the task with a specialized agent:

Use the delegation workflow to delegate this task to the appropriate specialized agent:

1. Determine the agent_persona from the task-delegation.md file
2. Read the full task details from the task list
3. Invoke the delegation workflow with:
   • subagent_type: {agent_persona} (e.g., "nextjs-backend-developer", "ui-developer", "qa-engineer")
   • description: Complete task description including:
     • Task number and name
     • Full task requirements
     • Context: input_folder, planning_folder, extra_instructions
     • PM-DB tracking IDs: PM_DB_PHASE_RUN_ID, PM_DB_TASK_RUN_ID
     • Agent invocation ID: SUBAGENT_INVOCATION_ID
     • Cache wrapper instructions
     • Specific files to modify
     • Quality requirements

Example delegation workflow invocation:

delegation workflow:
  subagent_type: "nextjs-backend-developer"
  description: "Execute Task 13: Add Comprehensive Error Logging

Context:
- Input folder: {input_folder}
- Planning folder: {planning_folder}  
- Extra instructions: {extra_instructions}
- PM_DB_PHASE_RUN_ID: $PM_DB_PHASE_RUN_ID
- PM_DB_TASK_RUN_ID: $PM_DB_TASK_RUN_ID
- SUBAGENT_INVOCATION_ID: $SUBAGENT_INVOCATION_ID

IMPORTANT: For all file reads during execution, use cache_wrapper.py:

python3 ~/.codex/skills/start-phase/scripts/cache_wrapper.py read \\
    --invocation-id $SUBAGENT_INVOCATION_ID \\
    --file-path /path/to/file.md

Task Requirements:
{Full task description from task list}

Deliverables:
- Implement error logging system
- Add try-catch blocks
- Log all errors to console and file
- Include stack traces

Do NOT run quality checks - they will be run automatically by hooks.
Complete the agent invocation when done using cache_wrapper.py complete.
"

Wait for the agent to complete the task.

Do NOT proceed to the next step until the agent finishes.

When task completes:

✅ Task {n} execution complete

Duration: {actual_time}

Complete sub-agent invocation:

# Complete sub-agent invocation
subagent_stats=$(python3 ~/.codex/skills/start-phase/scripts/cache_wrapper.py complete \
    --invocation-id $SUBAGENT_INVOCATION_ID 2>/dev/null)

echo "✅ Sub-agent invocation complete"
echo "   Files read: $(echo "$subagent_stats" | jq -r '.total_files_read')"
echo "   Cache hits: $(echo "$subagent_stats" | jq -r '.cache_hits')"
echo "   Cache misses: $(echo "$subagent_stats" | jq -r '.cache_misses')"
echo "   Estimated tokens: $(echo "$subagent_stats" | jq -r '.estimated_tokens_used')"
echo "   Duration: $(echo "$subagent_stats" | jq -r '.duration_seconds')s"

Mark PM-DB task run complete:

cat <<EOF | python3 ~/.codex/hooks$pm-db/on-task-run-complete.py
{
  "task_run_id": $PM_DB_TASK_RUN_ID,
  "exit_code": 0
}
EOF

Confirm:

✅ PM-DB Task Run Completed (ID: $PM_DB_TASK_RUN_ID)

→ task-complete hook will trigger automatically
→ quality-gate hook will run
→ Waiting for quality gate...

(Quality gate runs automatically via hook - see Part 3.5)

After quality gate passes - update progress:

✅ Quality Gate PASSED

Task {n} complete and verified.

Updated progress: [█████████████░░░░░░░] 13/40 tasks (32.5%)
Proceeding to next task...

---

Parallel Tasks

For parallel task waves, you must launch multiple agents simultaneously:

First, display wave progress announcement:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Phase Progress
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Overall: [████████████░░░░░░░░] 12/40 tasks (30%)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔀 Wave {n}: Parallel Execution
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Spawning SUBAGENT WORKERS IN PARALLEL:

1. Task {n}: {task_name} ({agent}) - Est: {time}
2. Task {n+1}: {task_name} ({agent}) - Est: {time}
3. Task {n+2}: {task_name} ({agent}) - Est: {time}

Expected wave duration: ~{max_time} (parallel execution)
vs. ~{total_time} (sequential - 3x slower)

Launching agents...

Create PM-DB task records and agent invocations for all parallel tasks:

Use Bash commands to create the tracking records:

# For each parallel task, create task run record and agent invocation
declare -A task_run_ids
declare -A subagent_invocation_ids

for task in "${parallel_tasks[@]}"; do
  # Create PM-DB task run
  hook_output=$(cat <<INNER_EOF | python3 ~/.codex/hooks$pm-db/on-task-run-start.py
{
  "phase_run_id": $PM_DB_PHASE_RUN_ID,
  "task_key": "$task_key",
  "assigned_agent": "$agent"
}
INNER_EOF
)
  task_run_id=$(echo "$hook_output" | jq -r '.task_run_id')
  task_run_ids["$task_key"]=$task_run_id

  # Create agent invocation
  subagent_invocation=$(python3 ~/.codex/skills/start-phase/scripts/cache_wrapper.py init \
      --agent-name "$agent" \
      --purpose "Task $task_key: $task_name" \
      --phase-run-id $PM_DB_PHASE_RUN_ID \
      --task-run-id $task_run_id)

  invocation_id=$(echo "$subagent_invocation" | jq -r '.invocation_id')
  subagent_invocation_ids["$task_key"]=$invocation_id

  echo "✅ Task $task_key: PM-DB task run $task_run_id, invocation $invocation_id"
done

Now use the delegation workflow to launch ALL parallel agents in a SINGLE message:

This is critical - you MUST invoke the delegation workflow multiple times in ONE message to achieve true parallel execution.

For each task in the parallel wave:

1. Read the task details from the task list
2. Identify the assigned agent from task-delegation.md
3. Prepare the task description with all context

Then, in a SINGLE response message, invoke the delegation workflow once for each parallel task:

Task 1 Tool Call:

delegation workflow:
  subagent_type: "{agent_persona_1}"
  description: "Execute Task {n}: {task_name_1}

[Full task context as shown in sequential example above]
"

Task 2 Tool Call (in same message):

delegation workflow:
  subagent_type: "{agent_persona_2}"
  description: "Execute Task {n+1}: {task_name_2}

[Full task context]
"

Task 3 Tool Call (in same message):

delegation workflow:
  subagent_type: "{agent_persona_3}"
  description: "Execute Task {n+2}: {task_name_3}

[Full task context]
"

After invoking all delegation workflow calls in parallel, wait for ALL agents to complete.

Do NOT proceed until every agent in the wave has finished.

Monitor parallel execution progress:

While agents are working, you can display status (but don't interrupt them):

⏳ Parallel execution in progress...

Task {n}: ▶ In progress (nextjs-backend-developer, 12m elapsed)
Task {n+1}: ▶ In progress (ui-developer, 12m elapsed)
Task {n+2}: ⏳ Queued (qa-engineer, waiting for agent)

Wave estimated remaining: ~8 minutes

When all parallel agents complete, display wave results:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Wave {n} Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Wave results:
✅ Task {n}: Complete (15m actual vs 20m estimated)
✅ Task {n+1}: Complete (18m actual vs 15m estimated)  
✅ Task {n+2}: Complete (12m actual vs 10m estimated)

Wave duration: 18m (parallel) vs 45m (sequential)
Time saved: 27 minutes (60% faster)

All tasks passed quality gates ✅
All PM-DB task records updated ✅

Updated progress: [██████████████░░░░░░] 15/40 tasks (37.5%)

Then proceed to the next wave or next sequential task.

---

Step 3.3: Mid-Task Checkpoints

For tasks taking >30 minutes:

⏰ Long task detected ({duration} min)

Creating checkpoint commit...

git add .
git commit -m "checkpoint: {task-name} - {milestone}

WIP: Not ready for quality gate yet"

Continue task execution.

---

Step 3.4: Handle Extra Instructions

If extra_instructions provided:

Apply to ALL tasks:

📝 Extra Instructions Active

"{extra_instructions}"

Applying to all tasks:
• Type safety emphasis
• Extra error handling
• Additional validation

Remind each agent persona of extra instructions.

---

Part 3.5: Quality Gate (Automatic via Hook)

After EACH task completes:

The task-complete hook triggers automatically. The quality-gate hook runs automatically.

Quality gate performs:

1. Run lint (npm run lint)
2. Run build (npm run build)
3. Perform code review (AI-powered)
4. Validate task completion
5. Create task update file
6. Git commit (only after all pass)

Store code review in PM-DB:

# After code review completes
cat <<EOF | python3 ~/.codex/hooks$pm-db/on-code-review.py
{
  "phase_run_id": $PM_DB_PHASE_RUN_ID,
  "reviewer": "code-reviewer-agent",
  "summary": "Code review summary here",
  "verdict": "passed"
}
EOF

Store quality gate result in PM-DB:

# Record quality gate result
cat <<EOF | python3 ~/.codex/hooks$pm-db/on-quality-gate.py
{
  "phase_run_id": $PM_DB_PHASE_RUN_ID,
  "gate_type": "code_review",
  "status": "passed",
  "result_summary": "All checks passed. Lint: 0 errors, Build: success, Tests: 34/34 passing",
  "checked_by": "code-reviewer"
}
EOF

If quality gate passes:

✅ Quality Gate PASSED

Task {n} complete and verified.
Code review stored in PM-DB ✅
Quality gate recorded ✅
Proceeding to next task...

If quality gate fails:

❌ Quality Gate FAILED

Errors:
• Lint: 3 errors
• Build: 1 error

⛔ BLOCKED: Fix errors before proceeding

Options:
1. Let me fix automatically
2. I'll fix manually

Fix errors and re-run quality gate.

Do NOT proceed to next task until quality gate passes.

---

Part 4: Task Updates + Commits

Handled automatically by quality-gate hook:

For each task:

• ✅ Task update created: {planning_folder}/task-updates/{task-name}.md
• ✅ Code review created: {planning_folder}/code-reviews/{task-name}.md
• ✅ Git commit created: "Completed task: {task-name} during phase {phase}"
• ✅ PM-DB task marked complete
• ✅ PM-DB code review stored

Track progress:

Phase Progress:

Completed: {n}/{total} tasks
Quality gates passed: {n}/{n}
Git commits: {n}
PM-DB tasks tracked: {n}

Current: {current_task}
Next: {next_task}

---

Part 5: Phase Closeout

After ALL tasks complete:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 All Tasks Complete!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase: {phase_name}
Total tasks: {total}
All completed: ✅

Beginning phase closeout...

Mark PM-DB phase run complete:

hook_output=$(cat <<EOF | python3 ~/.codex/hooks$pm-db/on-phase-run-complete.py
{
  "phase_run_id": $PM_DB_PHASE_RUN_ID,
  "exit_code": 0,
  "summary": "Successfully completed all {total} tasks for {phase_name}"
}
EOF
)

Display metrics:

# Extract metrics from hook output
metrics=$(echo "$hook_output" | jq -r '.metrics')
echo "📊 Phase Metrics:"
echo "$metrics" | jq -r 'to_entries | .[] | "  - \(.key): \(.value)"'

Confirm:

✅ PM-DB Phase Run Completed (ID: $PM_DB_PHASE_RUN_ID)
   Duration: {calculated_duration}
   Tasks: {total}/{total} complete
   Status: success

📊 Phase Metrics:
  - total_runs: 3
  - successful_runs: 3
  - failed_runs: 0
  - avg_duration_minutes: 45.2
  - total_tasks: {total}
  - avg_tasks_per_run: {avg}

Phase-complete hook triggers automatically.

---

Step 5.1: Collect Metrics with Cache Statistics

📊 Collecting phase metrics...

Task metrics: ✅
Quality gate metrics: ✅
Git metrics: ✅
Time metrics: ✅
PM-DB metrics: ✅
Cache metrics: ✅

Complete main orchestrator invocation:

# Complete main invocation
main_stats=$(python3 ~/.codex/skills/start-phase/scripts/cache_wrapper.py complete \
    --invocation-id $INVOCATION_ID 2>/dev/null)

echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "📊 Agent Context Caching Statistics"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "Main Orchestrator:"
echo "  Files read: $(echo "$main_stats" | jq -r '.total_files_read')"
echo "  Cache hits: $(echo "$main_stats" | jq -r '.cache_hits')"
echo "  Cache misses: $(echo "$main_stats" | jq -r '.cache_misses')"
echo "  Estimated tokens: $(echo "$main_stats" | jq -r '.estimated_tokens_used')"
echo "  Duration: $(echo "$main_stats" | jq -r '.duration_seconds')s"
echo ""

Query sub-agent cache statistics:

# Query all sub-agent invocations for this phase
subagent_cache_stats=$(sqlite3 -json ~/.codex/projects.db <<EOF
SELECT
  COUNT(*) as total_subagents,
  SUM(total_files_read) as total_files_read,
  SUM(cache_hits) as total_cache_hits,
  SUM(cache_misses) as total_cache_misses,
  SUM(estimated_tokens_used) as total_estimated_tokens,
  ROUND(AVG(duration_seconds), 2) as avg_duration,
  ROUND(100.0 * SUM(cache_hits) / NULLIF(SUM(cache_hits) + SUM(cache_misses), 0), 2) as hit_rate
FROM agent_invocations
WHERE phase_run_id = $PM_DB_PHASE_RUN_ID
  AND agent_name != 'start-phase-execute';
EOF
)

echo "Sub-Agents:"
echo "  Total agents: $(echo "$subagent_cache_stats" | jq -r '.[0].total_subagents')"
echo "  Total files read: $(echo "$subagent_cache_stats" | jq -r '.[0].total_files_read')"
echo "  Cache hits: $(echo "$subagent_cache_stats" | jq -r '.[0].total_cache_hits')"
echo "  Cache misses: $(echo "$subagent_cache_stats" | jq -r '.[0].total_cache_misses')"
echo "  Cache hit rate: $(echo "$subagent_cache_stats" | jq -r '.[0].hit_rate')%"
echo "  Estimated tokens: $(echo "$subagent_cache_stats" | jq -r '.[0].total_estimated_tokens')"
echo "  Avg duration: $(echo "$subagent_cache_stats" | jq -r '.[0].avg_duration')s"
echo ""

Query PM-DB for metrics:

# Metrics already retrieved from on-phase-run-complete hook
# Access them from the hook output stored earlier
echo "Phase run metrics:"
echo "$metrics" | jq '.'

# Or query directly:
sqlite3 ~/.codex/projects.db <<EOF
SELECT
  COUNT(*) as total_task_runs,
  SUM(CAST((julianday(completed_at) - julianday(started_at)) * 86400 AS INTEGER)) as total_duration,
  AVG(CAST((julianday(completed_at) - julianday(started_at)) * 86400 AS INTEGER)) as avg_duration
FROM task_runs
WHERE phase_run_id = $PM_DB_PHASE_RUN_ID;
EOF

---

Step 5.2: Generate Phase Summary

Create {planning_folder}/phase-structure/phase-summary.md:

(See phase-complete hook for full template)

Include PM-DB metrics and cache statistics:

## PM-DB Tracking

- Phase Run ID: {phase_run_id}
- Phase ID: {phase_id}
- Plan ID: {plan_id}
- Total task runs: {total}
- Total execution time: {duration}
- Average task time: {avg_duration}
- Code reviews: {review_count}
- Quality gates passed: {total}/{total}

View full dashboard: $pm-db dashboard

## Agent Context Caching Statistics

### Main Orchestrator
- Files read: {main_files_read}
- Cache hits: {main_cache_hits}
- Cache misses: {main_cache_misses}
- Estimated tokens: {main_estimated_tokens}

### Sub-Agents
- Total sub-agents: {total_subagents}
- Total files read: {subagent_files_read}
- Cache hits: {subagent_cache_hits}
- Cache misses: {subagent_cache_misses}
- Cache hit rate: {hit_rate}%
- Estimated tokens: {subagent_estimated_tokens}

### Token Savings Analysis
- Total estimated tokens: {total_tokens}
- Cache hit rate: {overall_hit_rate}%
- Estimated savings vs no cache: {savings}%

**Performance:**
- Average cache lookup: <5ms
- Zero performance degradation
- Session resumption enabled

✅ Phase summary created with cache statistics

---

Step 5.3: Generate Next Phase Candidates

Create {planning_folder}/phase-structure/next-phase-candidates.md:

Document:

• Deferred items
• Technical debt
• Improvements needed
• Follow-up tasks

✅ Next phase candidates created

---

Step 5.4: Final SLOC Analysis

python skills/start-phase/scripts/sloc_tracker.py {input_folder} --final

Update {planning_folder}/phase-structure/system-changes.md with final SLOC.

✅ Final SLOC analysis complete

Total SLOC added: +847
Total SLOC removed: -23
Net change: +824

---

Step 5.5: Archive Phase Data

📦 Archiving phase data...

Create: {input_folder}/planning-archive-{phase_name}-{timestamp}/

✅ Phase data archived

---

Step 5.6: Final Announcement

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 PHASE COMPLETE: {phase_name}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Duration: {total_time}
Tasks completed: {total}/{total} ✅
Quality gates: {total}/{total} passed ✅
Git commits: {count}

Code added: +{additions} lines
Test coverage: {coverage}%
Zero lint/build errors: ✅

PM-DB Phase Run ID: {phase_run_id} ✅
PM-DB Task Runs: {total} tracked ✅

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Phase artifacts:
✅ Phase summary ({planning_folder}/phase-structure/phase-summary.md)
✅ Next phase candidates ({planning_folder}/phase-structure/next-phase-candidates.md)
✅ SLOC analysis (system-changes.md)
✅ Phase archive (planning-archive-{phase_name}/)
✅ PM-DB tracking (Phase Run #{phase_run_id})

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Recommended next steps:
1. View PM-DB dashboard: $pm-db dashboard
2. Update Memory Bank: $memorybank-sync
3. Review phase summary
4. Plan next phase from candidates

Great work! Phase complete. 🚀

---

Path Management (CRITICAL)

These paths NEVER change during execution:

Established in Part 1:
• task_list_file: {original path}
• input_folder: {directory of task list}
• planning_folder: {input_folder}/planning
• PM_DB_PHASE_RUN_ID: {phase_run_id from hook}

Used throughout Parts 1-5:
• All planning docs → {planning_folder}/
• All task updates → {planning_folder}/task-updates/
• All code reviews → {planning_folder}/code-reviews/
• All phase artifacts → {planning_folder}/phase-structure/
• SLOC baseline → {planning_folder}/phase-structure/.sloc-baseline.json
• PM-DB tracking → ~/.codex/projects.db

Never derive paths differently in different parts!

---

Success Criteria

Mode 2 succeeds when:

• ✅ All 5 parts completed
• ✅ All tasks executed and verified
• ✅ All quality gates passed
• ✅ All planning documents created
• ✅ Phase summary generated
• ✅ Planning folder preserved throughout
• ✅ PM-DB job and tasks tracked
• ✅ PM-DB job marked complete
• ✅ Ready for next phase

---

Notes

• Mode 2 is comprehensive: Expect hours, not minutes
• Quality gates are mandatory: Cannot skip
• Hooks do heavy lifting: Automation is key
• Paths are sacred: Never lose input_folder or planning_folder
• Extra instructions apply to all tasks: Context for entire phase
• PM-DB tracking is automatic: Just call hooks at right points

---

Estimated time: Varies by task count (typically 3-8 hours) Token usage: ~3,500 tokens (comprehensive execution)