# Start Phase Execute

> 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.

- Skill: `artsmc/start-phase-execute` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add artsmc/start-phase-execute`
- Raw SKILL.md: https://api.skillmd.com/api/skills/artsmc/start-phase-execute/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: artsmc (https://skillmd.com/u/artsmc)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/artsmc/start-phase-execute

---


# 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

```bash
# 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:**
```bash
$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

```bash
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:**

```bash
# 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:**
```bash
# 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:**

```bash
# 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...
```

```bash
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):**

```bash
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:**
```bash
ls {planning_folder}/task-updates/*.md 2>/dev/null | wc -l
```

**Read task list to get total tasks:**
```bash
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...
```
```bash
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:**

```bash
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

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

**Expected:**
```json
{
  "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`:**

```markdown
# 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`:**

```markdown
# 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:**
```bash
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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
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:

```bash
# 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...
```

```bash
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:**
```bash
# 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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**

```bash
# 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:**

```bash
# 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:**
```bash
# 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:
```markdown
## 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

```bash
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)