execute-phase

What this skill does

# Execute Phase Skill

Execute all pending tasks in a specific development phase using **wave-based parallel execution** (max 4 agents per wave).

---

## How It Works

```
/execute-phase [phase_number]
      |
      v
  STEP 1: Get phase number (from arg or AskUserQuestion)
      |
      v
  STEP 2: Read progress.json, filter executable tasks
      |
      v
  STEP 3: Group tasks by complexity → assign agent types → plan waves
      |
      v
  STEP 4: WAVE LOOP (max 4 agents per wave)
      |
      |   ┌───────────────────────────────────────────┐
      |   │  4a. Take next batch (up to 4 tasks)      │
      |   │  4b. Spawn agents in parallel (1 message)  │
      |   │  4c. Wait for all agents in wave           │
      |   │  4d. Update progress.json IMMEDIATELY      │
      |   │  4e. Re-filter: find newly unblocked tasks │
      |   │  4f. If more tasks → loop back to 4a       │
      |   └───────────────────────────────────────────┘
      |
      v
  STEP 5: Final report (all waves combined)
```

### Why Waves?

```
BEFORE (all at once):
  10 agents spawn → context limit reached → phase fails

AFTER (wave-based, max 4):
  Wave 1: [agent][agent][agent][agent] → update progress.json
  Wave 2: [agent][agent][agent]        → update progress.json (includes newly unblocked)
  Wave 3: [agent][agent][agent]        → update progress.json
  Done. All tasks completed across 3 manageable waves.
```

---

## Step 1: Get Phase Number

### Option A: From arguments

If the user provides a phase number:
```
/execute-phase 0
/execute-phase 3
/execute-phase 5
```

Extract the phase number directly. **Do NOT ask questions — proceed to Step 2.**

### Option B: No argument provided

If the user invokes with no argument (`/execute-phase`), you MUST use AskUserQuestion:

```
AskUserQuestion:
  question: "Which phase would you like to execute?"
  header: "Phase"
  options:
    - label: "Phase 0: Foundation"
      description: "Project setup, design tokens, config files"
    - label: "Phase 1: Backend"
      description: "Database schema, migrations, RLS policies"
    - label: "Phase 2: Shared UI"
      description: "Shared components in src/components/"
    - label: "Phase 3: Features"
      description: "Feature modules in src/features/"
```

If the project has more phases (4, 5, etc.), include them. Read progress.json first to determine which phases exist, then build the options dynamically.

**If all tasks in the selected phase are already completed or blocked:**

```
AskUserQuestion:
  question: "All tasks in Phase {N} are {completed/blocked}. What would you like to do?"
  header: "Phase Status"
  options:
    - label: "Pick another phase"
      description: "Choose a different phase to execute"
    - label: "Re-run completed tasks"
      description: "Force re-execution of already completed tasks"
    - label: "Show blocked tasks"
      description: "See which tasks are blocked and why"
```

---

## Step 2: Read progress.json and Analyze Phase

### 2.1 Locate and read progress.json

```
Glob: **/progress.json
Read: [found path]
```

**If progress.json does NOT exist:**
> `progress.json` not found. Run `/complete-plan` first to generate the task tracker.

**STOP. Do NOT proceed.**

### 2.2 Find the target phase

Parse progress.json and locate the phase object matching the requested phase number.

**If the phase does NOT exist:**
> Phase {N} does not exist in progress.json. Available phases: {list phases}.

**STOP.**

### 2.3 Filter executable tasks

From the target phase, collect tasks that meet ALL criteria:

```
executable_tasks = phase.tasks.filter(task =>
  task.status === "pending" AND
  task.blocked_by.length === 0
)
```

**Categorize the results:**

| Scenario | Action |
|----------|--------|
| `executable_tasks` is empty, all tasks `completed` | Report "Phase {N} is already complete." STOP. |
| `executable_tasks` is empty, some tasks `blocked` | Report which tasks are blocked and by what. STOP. |
| `executable_tasks` has tasks | Proceed to Step 3. |

### 2.4 Report blocked tasks (if any)

If some tasks in the phase are blocked, list them:

```markdown
### Blocked Tasks (will not be executed)

| Task | Blocked By | Reason |
|------|------------|--------|
| {id} {name} | {blocked_by IDs} | Dependencies not yet completed |
```

These tasks will be skipped. Only unblocked pending tasks will be executed.

---

## Step 3: Group Tasks by Agent Type and Plan Waves

Split `executable_tasks` into two groups based on progress.json classification:

```
small_tasks = executable_tasks.filter(t => t.complexity === "low")
  → Each spawns a potenlab-small-coder agent

high_tasks = executable_tasks.filter(t => t.complexity === "high")
  → Each spawns a potenlab-high-coder agent
```

### Combine and chunk into waves of max 4:

```
all_executable = [...high_tasks, ...small_tasks]  // high-complexity first (longer running)
total_waves = Math.ceil(all_executable.length / 4)
```

### Report the execution plan before spawning:

```markdown
### Execution Plan — Phase {N}: {name}

| Task | Complexity | Agent | Files | Reason | Wave |
|------|-----------|-------|-------|--------|------|
| {id} {name} | high | potenlab-high-coder | {estimated_files} | {complexity_reason} | 1 |
| {id} {name} | low | potenlab-small-coder | {estimated_files} | {complexity_reason} | 1 |
| {id} {name} | low | potenlab-small-coder | {estimated_files} | {complexity_reason} | 1 |
| {id} {name} | low | potenlab-small-coder | {estimated_files} | {complexity_reason} | 1 |
| {id} {name} | low | potenlab-small-coder | {estimated_files} | {complexity_reason} | 2 |

**Total tasks:** {count} across {wave_count} wave(s)
**Max parallel agents per wave:** 4
- potenlab-small-coder: {small_count}
- potenlab-high-coder: {high_count}
```

---

## Step 4: Wave-Based Parallel Execution

**CRITICAL: Max 4 agents per wave. Update progress.json AFTER EACH wave. Re-filter between waves.**

### 4.0 Initialize wave tracking

```
all_wave_results = []       // accumulate results across all waves
wave_number = 0
```

### 4.1 Wave Loop

**Repeat the following until no more executable tasks remain:**

#### 4.1a — Filter executable tasks (re-read progress.json each iteration)

```
Read: docs/progress.json   // MUST re-read — previous wave may have changed it

executable_tasks = phase.tasks.filter(task =>
  task.status === "pending" AND
  task.blocked_by.length === 0
)

IF executable_tasks is empty → EXIT loop, go to Step 5
```

#### 4.1b — Take the next batch (max 4)

```
wave_number += 1
wave_batch = executable_tasks.slice(0, 4)   // take up to 4
```

#### 4.1c — Report wave start

```markdown
### Wave {wave_number} — Spawning {wave_batch.length} agent(s)

| Task | Agent |
|------|-------|
| {id} {name} | {agent_type} |
```

#### 4.1d — Spawn wave agents in PARALLEL (single message, max 4 Task calls)

Spawn all agents for THIS wave in ONE message with multiple Task tool calls:

**Agent Prompt Template — potenlab-small-coder**

For EACH task in wave where `complexity === "low"`:

```
Task:
  subagent_type: potenlab-small-coder
  description: "Task {task.id}: {task.name}"
  prompt: |
    Execute task {task.id}: {task.name}

    Read ALL plan files first (MANDATORY):
    - docs/dev-plan.md (single source of truth — find task {task.id})
    - docs/frontend-plan.md (component specs if frontend task)
    - docs/backend-plan.md (schema specs if backend task)
    - docs/ui-ux-plan.md (design context)
    - docs/progress.json (task details and dependencies)

    Task details from progress.json:
    - ID: {task.id}
    - Name: {task.name}
    - Domain: {task.domain}
    - Output files: {task.output}
    - Verify steps: {task.verify}
    - Notes: {task.notes}

    Instructions:
    1. Read ALL plans to understand full project context
    2. Find task {task.id} in dev-plan.md for Output, Behavior, Verify details
    3. Check the specialist plan (frontend-plan.md or backend-plan.md) for detailed specs
    4. Check existing code to understand wha