Phase Runner V2

Parameters

Token-Aware Execution (from v1)

For long phases (20+ tasks), use graceful handoff to prevent context exhaustion:

How It Works

1. Track tool calls - Count each Read, Edit, Write, Grep, Bash, etc.
2. Budget limit - Default 100 calls per session, with 25-call buffer
3. Handoff at ~75 calls - Complete current task, sync, output handoff report
4. Parent continues - Orchestration loop spawns new agent at resume point

Configuration

When Token-Aware Mode Activates

• Enabled for phases with 20+ tasks
• Disabled for small phases (<20 tasks) to avoid overhead

Resume Point Detection

Scan tasks file for first task WITHOUT ✅ timestamp:

• Skip headers (#, ##, ###)
• Find lines starting with - [ or - \[P`
• First without ✅ [2 pattern = resume point

Handoff Report Format

When tool_count >= 75:

## HANDOFF REPORT

### Session Statistics
- Tool calls used: ~[X]/100
- Tasks completed this session: [N]

### Last Completed Task
- Section: [Section Name]
- Task: [Task Description]
- Completed at: [YYYY-MM-DD HH:MM]

### Resume Point
- Next section: [Section Name]
- Next task: [First incomplete task description]
- Estimated remaining: [Approximate count]

### Status: HANDOFF_REQUIRED

Input Format Support

Auto-Detection (Default)

The skill auto-detects input format:

1. Check for 4-file structure (*-execution-plan.md, *-context.md, *-role.md, *-tasks.md)
2. If found, use 4-file mode with role adoption and wave execution
3. Otherwise, use single-file mode (phase-*.md discovery)

Single-File Mode

• Discovers phases via pattern: .planning/phase-*.md
• Each phase file is self-contained with inline tasks
• Phase type auto-detected from content

4-File Mode (from v1)

Consumes the structure generated by /expand-plan:

• *-context.md - Technical background and reference
• *-role.md - Agent identity and quality standards
• *-tasks.md - Granular task checklist with ✅ checkpoints
• *-execution-plan.md - Lean orchestration document with waves

Workflow

Step 1: Discover Planning Directory

Search for the planning directory in this order:

1. .planning/ relative to current working directory
2. Search via Glob pattern **/.planning/

If not found, ask the user for the planning directory location.

Step 2: Detect Input Format & Discover Files

For Auto/Single-File Mode: Use Glob to find phase files matching pattern: .planning/phase-*.md Sort files by phase number. Expected naming: phase-01-name.md, phase-02-name.md, etc.

For 4-File Mode:

Given: /path/to/phase-1-setup-execution-plan.md
Derive:
  - prefix: "phase-1-setup"
  - context: /path/to/phase-1-setup-context.md
  - role: /path/to/phase-1-setup-role.md
  - tasks: /path/to/phase-1-setup-tasks.md

Given: /path/to/.planning/phase-1-setup/
Discover:
  - Find *-execution-plan.md in directory
  - Use its prefix for other files

Step 3: Determine Phase Types

Analyze each phase filename and content to determine type:

• UI: Contains ui, component, screen, view, page, layout, style
• Backend: Contains api, server, database, auth, service, endpoint
• Infrastructure: Contains setup, config, deploy, ci, docker, env
• Testing: Contains test, spec, coverage, e2e
• General: Default when no pattern matches

Step 3.1: Detect App Type

Determine if this is a mobile or webapp project to enable Playwright-driven development:

Detection signals for Mobile/Webapp:

• Project contains playwright.config.ts or playwright.config.js
• Package.json has playwright dependency
• Project has Next.js, React, Vue, Angular, Svelte, or similar web frameworks
• Project has React Native, Flutter, Expo, or similar mobile frameworks
• Phase files mention UI, screens, components, pages, or user interactions
• Existing e2e/ or tests/e2e/ directory

When Mobile/Webapp is detected:

• Enable Playwright-driven development for UI phases
• Development flow becomes: Playwright → TDD → Implementation (RGR)
• See "Playwright-Driven Development" section for details

Playwright-Driven Development

For mobile and webapp projects, UI implementation follows this enhanced flow:

Development Flow

1. Playwright Acceptance Test (Write first - should FAIL)
   ↓
2. TDD Unit Tests (Red)
   ↓
3. Implementation (Green)
   ↓
4. Refactor
   ↓
5. Playwright Test Passes (Acceptance)

When to Apply

• UI Phases: Always apply for mobile/webapp UI phases
• Backend Phases: Skip Playwright, use standard TDD
• Infrastructure Phases: Skip Playwright, use standard TDD

Playwright Test Requirements

Before implementing any UI task:

1. Write the acceptance test first:

   • Define what the user should be able to do
   • Write Playwright test that exercises the feature
   • Run test - it should FAIL (feature doesn't exist yet)

2. Then proceed with TDD:

   • Write unit tests for components/logic
   • Implement to pass unit tests
   • Refactor as needed

3. Finally verify acceptance:

   • Run Playwright test - it should now PASS
   • If it fails, debug and fix

Sub-Agent Playwright Instructions

For UI tasks in mobile/webapp projects, include in sub-agent prompts:

## DEVELOPMENT FLOW (Playwright → TDD → Implementation)

This is a mobile/webapp project. Follow this sequence:

### Step 1: Playwright Acceptance Test (WRITE FIRST)
1. Create/update e2e test in: e2e/{feature}.spec.ts
2. Write test that exercises the user-facing feature
3. Run: pnpm playwright test {feature}.spec.ts
4. Verify it FAILS (expected - feature not implemented)

### Step 2: TDD Unit Tests (Red)
1. Write unit tests for components/hooks/utilities
2. Run tests - they should FAIL
3. This defines the implementation contract

### Step 3: Implementation (Green)
1. Implement the feature
2. Run unit tests - they should PASS
3. Keep implementation minimal

### Step 4: Refactor
1. Clean up code while keeping tests green
2. Apply patterns from pre-context if applicable

### Step 5: Playwright Acceptance (Verify)
1. Run: pnpm playwright test {feature}.spec.ts
2. It should now PASS
3. If it fails, debug and iterate

## TDD REQUIREMENT (still applies)
Follow Red-Green-Refactor for unit tests:
1. Write failing test first
2. Implement minimal code to pass
3. Refactor if needed

Step 4: Load Pre-Context (Phase Continuity)

BEFORE reading the phase's own context, check for previous phase handoff:

For phase N (where N > 1):
  1. Look for: .planning/phase-{N}/pre-context.md
     OR: .planning/phase-{N-padded}-*/pre-context.md
  2. If found, read and include as "Previous Phase Context"
  3. This provides implementation decisions, created files, and lessons learned

The pre-context.md contains:

• Summary of what was implemented in the previous phase
• Key files created or modified
• Important decisions made
• Dependencies or patterns established
• Any warnings or considerations for subsequent phases

Step 5: Load Phase Context

For Single-File Mode: Read phase file and extract tasks. Look for sections starting with "### Task" and extract:

• Task number (e.g., 1.1, 1.2)
• Task title
• Task description
• Files to create or modify
• Acceptance criteria

For 4-File Mode:

1. Read *-execution-plan.md for waves and task references
2. Read *-role.md and adopt the role identity
3. Read *-context.md for technical background
4. Read *-tasks.md for granular task checklist

Step 6: Adopt Role (4-File Mode Only)

When using 4-file format, read the *-role.md file and internalize:

• Role title and identity
• Core expertise areas
• Quality standards to uphold
• Decision-making boundaries
• Common pitfalls to avoid

You ARE this role for the duration of execution.

Step 7: Initialize Progress Tracking

Use TodoWrite to create todos for all tasks across all phases. Set all tasks to pending status initially.

For 4-file mode, also track wave completion status.

Step 8: Execute Phases

For each phase (respecting start-phase and end-phase parameters):

Initialize: tool_count = 0, check if token-aware mode needed (20+ tasks)

1. For each task/wave in the phase:

   • Pre-Task Budget Check: If tool_count >= 75, proceed to Handoff
   • Update TodoWrite to mark the task as in_progress
   • Construct a comprehensive prompt using the template in references/task-prompt-template.md
   • Include pre-context.md content if available for this phase
   • Spawn a Task agent with the prompt, using description parameter for context
   • Pass tool budget instructions to sub-agent (see Sub-Agent Synchronization)
   • Wait for the agent to complete (do not use run_in_background for sequential execution)
   • Update TodoWrite to mark the task as completed
   • IMMEDIATELY mark task complete with ✅ [YYYY-MM-DD HH:MM] in tasks file
   • Post-Task Budget Check: If tool_count >= 75, proceed to Handoff

2. Run Phase Verification:

   • Determine which verification to run based on phase type
   • For UI phases: Invoke verify-ui skill, then see-ui skill, then run XCUI tests
   • For backend phases: Invoke verify-backend skill
   • For other phases: Invoke verify-work skill
   • See references/verification-guide.md for detailed checklists

3. Handle Verification Failures:

   • If verification identifies issues, spawn a fix agent
   • Re-run verification after fixes
   • Do not proceed to next phase until verification passes

4. Generate Phase Handoff (see Step 9)

Step 8.1: Graceful Handoff

When tool_count >= 75:

1. Complete current task (if in progress) and sync to file
2. Output handoff report using the format above
3. Stop - Do not start new tasks

Step 8.2: Sub-Agent Synchronization

CRITICAL: Pass these explicit instructions to every sub-agent:

1. Task File Path: Always pass the full path to tasks file in the sub-agent prompt
2. Sync After Each Task: Sub-agent MUST add ✅ and timestamp to each completed task
3. Sync After Each Section: If handling multiple tasks, sync after EACH task - not at the end
4. Timestamp Format: ✅ [YYYY-MM-DD HH:MM]

Sub-agent prompt template (with token budget):

You are executing tasks from: {tasks-file-path}
Resume from: {section-name}, {first-incomplete-task}

## TOOL BUDGET (CRITICAL)
- Budget: 100 calls | Buffer: 25 | Effective limit: 75 calls
- Track tool calls mentally. When you reach ~70-75:
  1. FINISH current task
  2. SYNC to tasks file with ✅ [timestamp]
  3. OUTPUT handoff report (format below)
  4. STOP - do not start new tasks

## SYNC REQUIREMENT
After completing EACH task:
1. Edit {tasks-file-path}
2. Add: ✅ [YYYY-MM-DD HH:MM] to the task line
3. Do NOT batch - sync after EVERY task

{IF is_mobile_or_webapp AND is_ui_phase}
## DEVELOPMENT FLOW (Playwright → TDD → Implementation)

This is a mobile/webapp project. Follow this sequence for UI tasks:

### Step 1: Playwright Acceptance Test (WRITE FIRST)
1. Create/update e2e test in: e2e/{feature}.spec.ts
2. Write test that exercises the user-facing feature
3. Run: pnpm playwright test {feature}.spec.ts
4. Verify it FAILS (expected - feature not implemented)

### Step 2: TDD Unit Tests (Red)
1. Write unit tests for components/hooks/utilities
2. Run tests - they should FAIL
3. This defines the implementation contract

### Step 3: Implementation (Green)
1. Implement the feature
2. Run unit tests - they should PASS
3. Keep implementation minimal

### Step 4: Refactor
1. Clean up code while keeping tests green
2. Apply patterns from pre-context if applicable

### Step 5: Playwright Acceptance (Verify)
1. Run: pnpm playwright test {feature}.spec.ts
2. It should now PASS
3. If it fails, debug and iterate
{ENDIF}

## TDD REQUIREMENT
Follow Red-Green-Refactor for each task:
1. Write failing test first
2. Implement minimal code to pass
3. Refactor if needed

Step 8.3: Parent Orchestration Loop

The parent agent manages multi-session execution for long phases:

iteration = 0
max_iterations = 100

WHILE iteration < max_iterations:
  iteration++

  1. Read tasks file
  2. Find first task WITHOUT ✅ timestamp = resume_point
  3. IF no incomplete tasks found:
     → All tasks complete! EXIT SUCCESS

  4. Spawn sub-agent via Task tool:
     - Include phase file paths
     - Include pre-context.md content if available
     - Set resume_point (section, task)
     - Include tool budget instructions
     - Include TDD instructions
     - Include handoff report format

  5. Wait for sub-agent completion

  6. Parse sub-agent output:
     - IF "HANDOFF_REQUIRED": continue loop
     - IF "PHASE_COMPLETE": proceed to verification
     - IF error/no handoff: log warning, continue

  7. Log: "Iteration {N}: Tasks X-Y complete, continuing..."

Termination Conditions:

• ✅ All tasks have timestamps = SUCCESS (proceed to verification)
• Max iterations (100) reached = MANUAL_INTERVENTION_REQUIRED
• 5+ iterations with 0 progress = STUCK (ask user)

Step 9: Generate Phase Handoff (Pre-Context for Next Phase)

After a phase completes and passes verification, generate a handoff document for the next phase:

1. Determine next phase path:

   • For phase N, the next phase is N+1
   • Locate the next phase directory or create pre-context.md alongside it

2. Generate pre-context.md content:

# Pre-Context: Handoff from Phase {N}

Generated: [YYYY-MM-DD HH:MM]

## Implementation Summary
[Brief summary of what was accomplished in the completed phase]

## Files Created
- `path/to/file1.ts` - [Purpose]
- `path/to/file2.ts` - [Purpose]

## Files Modified
- `path/to/existing.ts` - [What changed and why]

## Key Decisions Made
- [Decision 1]: [Rationale]
- [Decision 2]: [Rationale]

## Patterns Established
- [Pattern name]: [How it works, where it's used]

## Dependencies Added
- [package@version]: [Why it was needed]

## API Contracts / Interfaces
[Any new interfaces, types, or API contracts that subsequent phases should be aware of]

## Warnings & Considerations
- [Any technical debt, known issues, or things to watch out for]

## Context for Next Phase
[Specific guidance for what the next phase needs to know to continue the work]

3. Write the file:
   • Path: .planning/phase-{N+1}/pre-context.md
   • OR alongside the next phase file: .planning/phase-{N+1-padded}-{name}/pre-context.md

See references/phase-handoff.md for detailed generation guidance.

Step 10: Handle XCUI Tests (UI Phases)

For UI phases when not skipping UI verification:

1. Discover XCUI test files matching the phase content
2. Run relevant XCUI tests using xcodebuild
3. If tests fail, spawn fix agent with failure context
4. Re-run tests until they pass

See references/xcui-integration.md for detailed test discovery and execution.

Step 11: Handle Errors

Follow the error handling strategies in references/error-handling.md:

• Retry failed tasks up to 3 times with adjustments
• Detect when stuck (5 iterations without progress)
• Escalate to user when automated recovery fails

Step 12: Completion

When all phases complete successfully:

1. Output a summary showing phases completed, tasks completed, and verification status
2. Output the completion promise message
3. Output the token: !!!end-of-planning!!!

Skill Fallback Handling

If verify-ui, verify-backend, or verify-work skills are not available:

1. Spawn a general-purpose Task agent instead
2. Provide the relevant verification checklist from references/verification-guide.md
3. Include full context about the completed work
4. Request thorough review and issue identification

If see-ui skill is not available:

1. Log that visual verification is being skipped
2. Rely on XCUI tests for UI verification
3. Continue with phase completion

Task Tool Usage

When spawning sub-agents, use the Task tool with these parameters:

• prompt: The comprehensive task prompt (see references/task-prompt-template.md)
• description: Brief description like "Implementing Task 1.1: Initialize project"

For sequential execution (default), wait for each task to complete before starting the next.

For parallel execution (--parallel-tasks), spawn multiple tasks but coordinate completion before verification.

Always include in sub-agent prompts:

• Tool budget instructions (if token-aware mode active)
• Playwright-driven development instructions (if mobile/webapp AND UI phase)
• TDD Red-Green-Refactor instructions
• Sync requirements for task completion timestamps
• Pre-context from previous phase (if available)

TodoWrite Usage

TodoWrite replaces the entire todo list each time. When updating:

1. Read current todo state
2. Modify the relevant task's status
3. Write the complete updated list

Status values: pending, in_progress, completed

Only one task should be in_progress at a time during sequential execution.

Skill Tool Usage

When invoking skills like verify-ui, verify-backend, or see-ui:

• Use the Skill tool with the skill parameter set to the skill name
• Optionally provide args for skill-specific parameters

Progress Reporting

At key milestones, output progress updates showing:

• Current phase and task
• Overall completion percentage
• Completed phases summary
• Remaining work
• Tool budget status (if token-aware mode active)

Completion Token (Sub-Agent Orchestration)

When this skill runs as a sub-agent (via Task tool), use lightweight completion detection:

Token: !!!end-of-planning!!!

Token Placement

• In agent output: Output token as the absolute LAST LINE of your response when all phases complete
• Only output token when ALL tasks have ✅ timestamps and verification passes

Parent Agent Instructions

Parent agents spawning this skill should:

1. DO NOT read the full sub-agent output (causes context exhaustion)
2. DO TAIL the last 5 lines of output only
3. LOOK FOR the !!!end-of-planning!!! token to confirm completion
4. If token NOT found in last 5 lines → sub-agent may have failed, truncated, or handed off

When to Output Token

• ALL_PHASES_COMPLETE: Output !!!end-of-planning!!! as final line
• HANDOFF_REQUIRED: Do NOT output token (phase not complete)

Reference Files

Detailed guidance is available in the references directory:

• references/task-prompt-template.md - How to construct task prompts
• references/verification-guide.md - Verification checklists by phase type
• references/xcui-integration.md - XCUI test discovery and execution
• references/error-handling.md - Error classification and recovery
• references/phase-handoff.md - Pre-context generation for phase continuity

Now Execute

When invoked, immediately:

1. Parse any provided path or parameters
2. Discover planning directory
3. Detect input format (single-file or 4-file)
4. Locate all phase files
5. Initialize tool count = 0 (if token-aware mode needed)
6. Begin the execution workflow
7. Track progress with TodoWrite
8. For each phase:
   • Load pre-context.md from previous phase (if exists)
   • Execute tasks with TDD and token budget awareness
   • Run verification
   • Generate pre-context.md for next phase
9. Monitor tool budget, handoff at ~75 calls
10. Complete all phases with validation (or handoff)

On All Phases Complete: After all tasks complete and success criteria verified, output:

!!!end-of-planning!!!