Start Phase Execute

Start-Phase Execute

Execute a task list with parallel waves, agent delegation, and quality gates.

Usage

/start-phase execute /path/to/task-list.md
/start-phase execute /path/to/task-list.md "Focus on type safety"
/start-phase execute /path/to/task-list.md --team        # force team mode
/start-phase execute /path/to/task-list.md --sequential  # force solo mode
/start-phase execute /path/to/task-list.md --graph       # force graph mode (dependency-streamed Workflow execution; forced-only, never auto-detected)

Workflow Overview

Phase 1: Setup        → Read task list, detect resume, create dirs
Phase 2: Plan         → Delegation plan, wave decomposition, impact analysis
Phase 3: Execute      → Run tasks by wave (parallel where possible)
Phase 4: Quality Gate → Lint, build, review after each task
Phase 5: Closeout     → Summary, metrics, archive

Team Mode (--team)

Formerly the standalone /start-phase-execute-team skill.

When to use: auto-enables at 7+ tasks in the list; force on with --team, force off with --sequential. Worth it for complex features (2+ hours sequential) with multiple independent modules — expect ~3x tokens for 1.5-2x speed. Skip for simple changes, routine maintenance, or single-file work.

Procedure summary: parse the task list → group tasks into dependency waves (empty wave = circular dependency, abort) → TeamCreate("phase-execution") → TaskCreate per task, wiring blockers via TaskUpdate({ addBlockedBy }) → per wave, spawn one agent per task (model: sonnet); each agent claims its task, executes, passes quality gates (hard blocks), self-reviews, commits, and marks complete → team lead polls TaskList until the wave completes → verify all tasks completed → SendMessage shutdown to members, then TeamDelete.

In team mode, agents handle Phase 3 execution and their own per-task commits (Phase 4 gates run inside each agent); Phases 1, 2, and 5 are unchanged.

Lean Orchestrator (mandatory cost discipline): 30-day mining showed workers are only ~15% of cost — the waste is the parent re-reading fat accumulated context 50–100×/turn (71% of the worst session). So:

• Workers default to Sonnet at medium effort; escalate per-task only for ambiguity, cross-cutting design, or security — and down-route fully-specified, self-contained, gate-verified tasks to Haiku (benchmarked 6/6 pass, zero escalations; routing table in the reference).
• Spawn prompts are scoped snapshots — goal, input paths (never pasted blobs; headroom-compress unavoidable large handoffs), constraints, acceptance, output contract.
• Workers return a compact report (status, artifact paths, verification evidence, ≤2-sentence notes); full detail goes to files in {planning_folder}/task-updates/.
• Parent keeps ≤~30k tokens of accumulated state, dispatches each wave in ONE message, never re-reads worker artifacts it doesn't need, and checkpoints to task-list.md/pm-db between waves so the session can /clear or resume.
• Retries get the same scoped snapshot + the specific failure evidence — never the parent's history.
• Wave Gate: a wave is done only when every worker's return is collected AND the verification gate ran — never end the turn/session with workers in flight (background workers: DONE-markers + bounded polling; timeout = failure with evidence).

Before executing in team mode, read references/lean-orchestrator.md (the canonical protocol above, with evidence and templates), references/team-mode.md (full procedure, mode detection, error recovery, best practices), and references/team-mode-examples.md (pseudocode, the exact agent spawn-prompt template, worked 7-task example, display formats).

Phase 1: Setup

1.1 Extract Paths (NEVER lose these)

task_list_file = {the file path provided}
input_folder   = directory containing task_list_file
planning_folder = {input_folder}/planning

1.2 Read and Parse Task List

Read the task list file. Extract:

• Phase/feature name
• All tasks with descriptions
• Dependencies between tasks
• Any wave/phase groupings already defined

1.3 Resume Detection

Check THREE sources for prior progress (not just filesystem):

1. Filesystem check:

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

2. PM-DB check:

# Query for prior phase runs on this feature
import sqlite3
conn = sqlite3.connect(str(Path.home() / '.claude/projects.db'))
rows = conn.execute("""
    SELECT pr.id, pr.status, pr.started_at,
           COUNT(tr.id) as task_runs,
           SUM(CASE WHEN tr.status='completed' THEN 1 ELSE 0 END) as completed
    FROM phase_runs pr
    LEFT JOIN task_runs tr ON tr.phase_run_id = pr.id
    JOIN phases p ON p.id = pr.phase_id
    WHERE p.name LIKE ? AND pr.status IN ('started', 'in_progress')
    GROUP BY pr.id
    ORDER BY pr.started_at DESC LIMIT 1
""", (f'%{feature_name}%',)).fetchall()

3. Git check:

git log --oneline --grep="{feature_name}" -5

If prior progress found:

Prior progress detected:
- Planning folder: {X} task-update files
- PM-DB: Phase run #{id}, {completed}/{total} tasks
- Git: {N} related commits

Options:
1. Resume from task {next_incomplete} (recommended)
2. Start fresh (backs up existing planning/)
3. Cancel

If no progress found but user said "resume":

No prior progress found for this feature.
Starting fresh execution. All tasks will run from the beginning.

1.4 Create Directory Structure

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

Phase 2: Planning (3 Required Documents)

These documents force comprehensive analysis before any code is written. This is the skill's primary value — don't skip this phase.

Create all three in {planning_folder}:

1. agent-delegation/task-delegation.md — per-task agent type, priority, difficulty, dependencies, estimate; plus agent workload summary
2. agent-delegation/sub-agent-plan.md — wave decomposition: dependency graph → parallel waves with file-conflict analysis and time-savings calculation (the most important document)
3. phase-structure/system-changes.md — all files created/modified/deleted, grouped by impact level, with cross-app impacts

Read references/planning-docs.md for the full template and instructions for each document BEFORE writing them.

Phase 3: Execute Tasks by Wave

Sequential Tasks

For each task in the current wave:

1. Show progress:

[████████░░░░░░░░░░░░] 8/20 tasks (40%)
Starting Task 9: {name}
Agent: {agent_type} | Priority: {priority}

2. Spawn the agent using the Task tool:

Task tool:
  subagent_type: "{agent_type}"
  prompt: "Execute Task {n}: {task_name}

  Context:
  - Working directory: {monorepo_root}
  - Task requirements: {full task description}
  - Extra instructions: {extra_instructions}
  - Files to modify: {from system-changes.md}

  Complete the task, then stop. Quality gate runs separately."

3. Wait for completion, then run quality gate (Phase 4)

Parallel Wave Execution

For parallel waves, spawn ALL agents in a SINGLE message:

Starting Wave 3 (3 tasks in parallel):
  Task 7: {name} → {agent_type}
  Task 8: {name} → {agent_type}
  Task 9: {name} → {agent_type}

Launching agents...

Use the Task tool 3 times in one response to achieve true parallelism. Wait for ALL to complete before proceeding to next wave.

Extra Instructions

If extra_instructions provided, include them in every agent prompt:

ADDITIONAL REQUIREMENTS: {extra_instructions}

Phase 4: Quality Gate (After Each Task)

After each task completes:

1. Lint check:

cd {monorepo_root} && npm run lint 2>&1 | tail -20

2. Build check:

cd {monorepo_root} && npm run build 2>&1 | tail -20

3. If both pass: Create task update file and commit

# Create task update
echo "# Task {n}: {name}\nStatus: Complete\nAgent: {agent}\nTime: {duration}" \
  > {planning_folder}/task-updates/task-{n}-{slug}.md

# Commit
git add -A && git commit -m "task({feature}): complete task {n} - {name}"

4. If either fails: Fix errors before proceeding

Quality Gate FAILED:
- Lint: {error count} errors
- Build: {error details}

Fix the errors, then re-run the quality gate.
Do NOT proceed to the next task until this passes.

Phase 5: Closeout

After all tasks complete:

1. Generate phase summary at {planning_folder}/phase-structure/phase-summary.md:

   • Total tasks completed
   • Total duration
   • Quality gates: all passed
   • Files changed (from git diff)

2. Update PM-DB (if database exists): Read references/tracking.md for PM-DB integration details.

3. Display final report:

PHASE COMPLETE: {feature_name}

Tasks: {total}/{total} complete
Quality gates: {total}/{total} passed
Duration: {time}
Commits: {count}

Next steps:
1. /pm-db dashboard — view project status
2. Review phase summary at {planning_folder}/phase-structure/phase-summary.md

PM-DB Tracking

PM-DB integration is optional but recommended. If ~/.claude/projects.db exists, track phase runs and task completions.

For detailed PM-DB hook commands, read references/tracking.md.

The key hooks (all at ~/.claude/hooks/pm-db/):

• on-phase-run-start.py — call at Phase 1 start
• on-task-run-start.py — call before each task
• on-task-run-complete.py — call after each task
• on-phase-run-complete.py — call at Phase 5

Path Management (CRITICAL)

These paths are set in Phase 1 and NEVER change:

task_list_file  → original file path
input_folder    → directory of task list
planning_folder → {input_folder}/planning

All artifacts go in planning_folder.
Never derive paths differently in different phases.

Notes

• Phase 2 planning is the skill's primary value — don't skip it
• Quality gates are mandatory — don't proceed on failures
• Parallel waves need file conflict analysis — same-file = sequential
• Long tasks (>30 min): create checkpoint commits
• Extra instructions apply to ALL tasks in the phase