Iterative Plan Execution

Purpose

Execute multi-phase implementation plans autonomously with:

• Progressive phase-by-phase advancement
• Atomic task decomposition per phase
• Verification triad after each task
• Persistent journaling for context recovery
• Beads integration for work tracking

Execution Protocol

1. Plan Ingestion

READ plan file completely
IDENTIFY total phase count
CREATE beads issue per phase: bd create --title="Phase N: <description>" --type=task
SET current_phase = 1

2. Phase Loop

WHILE current_phase <= total_phases:
    READ phase N requirements from plan
    DECOMPOSE into atomic tasks using TodoWrite
    FOR each task in phase:
        MARK task as in_progress
        IMPLEMENT task
        VERIFY via triad
        WRITE journal entry
        MARK task as completed
    END FOR
    UPDATE plan checkboxes for phase N
    REPORT phase completion
    INCREMENT current_phase
END WHILE

3. Task Verification Triad

Every task must pass ALL three checks:

bun run typecheck

bun run scripts/spike-<feature>-phase-N.ts

Journaling Protocol

File Location

.agents/val/journal/YYYY-MM-DD-<feature>-phase-N-task-M.md

Template

# Phase N Task M

**Feature**: <feature-name>
**Date**: YYYY-MM-DD HH:MM
**Status**: complete | blocked | partial

## Files Touched

- path/to/file1.ts
- path/to/file2.ts

## Implementation Summary

<2-3 sentences describing what was done>

## Verification

### Type Safety
- [ ] bun run typecheck passed

### Runtime Smoke
- [ ] Spike script executed successfully
- Script: scripts/spike-<feature>-phase-N.ts

### Export Resolution
- [ ] Imports resolve in test file

## Learnings

<Discoveries and patterns worth noting>

## Blockers

<If status is blocked - describe the blocker>

## Next

<What follows this task>

Spike Generation Per Phase

For each phase create a minimal spike script:

Naming Convention

scripts/spike-<feature>-phase-N.ts

Spike Template

/**
 * Spike: <Feature> Phase N Verification
 *
 * Tests that Phase N implementation works correctly.
 * Run: bun run scripts/spike-<feature>-phase-N.ts
 */

import { Effect } from 'effect'

// Import the new modules from this phase
// import { ... } from '@/lib/<feature>/...'

async function main() {
  console.log('=== Phase N Verification ===\n')

  // H1: Basic instantiation
  console.log('H1: Basic instantiation')
  // ... test basic creation works

  // H2: Core functionality
  console.log('H2: Core functionality')
  // ... test main feature works

  // H3: Integration
  console.log('H3: Integration')
  // ... test integration with existing code

  console.log('\n=== Phase N Verification Complete ===')
}

main().catch(console.error)

Beads Integration

Phase Start

bd create --title="<Feature> Phase N: <phase-description>" --type=task
bd update <issue-id> --status=in_progress

Phase End

bd close <issue-id>
bd sync --from-main

Blocked

bd update <issue-id> --status=blocked
# Add blocker details to journal

Plan File Updates

After completing each phase section update the plan:

### Phase 1: G2 Theme Infrastructure

- [x] Create vanta-theme.ts
- [x] Create palettes.ts
- [x] Create index.ts
- [x] Verify theme renders correctly

Use Edit tool to check off completed items.

Recovery Protocol

If context compacts or session restarts:

1. READ .agents/val/journal/ directory for latest entries
2. IDENTIFY last completed phase and task
3. READ plan file for checkbox state
4. RESUME from next uncompleted item

Error Handling

Typecheck Fails

1. READ error message
2. FIX type errors
3. RE-RUN typecheck
4. CONTINUE only when passing

Spike Fails

1. ANALYZE failure output
2. IDENTIFY root cause
3. FIX implementation
4. RE-RUN spike
5. If 3+ failures: MARK as blocked and REPORT

Export Resolution Fails

1. CHECK index.ts exports
2. VERIFY barrel exports chain
3. FIX missing exports
4. RE-TEST import

Self-Prompts

Before Starting Phase

"Reading Phase N requirements. Decomposing into atomic tasks."

Before Each Task

"Task M of Phase N: <task-description>. Implementing now."

After Task Verification

"Task M verified. Writing journal entry."

Phase Complete

"Phase N complete. All tasks verified. Updating plan checkboxes."

Blocker Encountered

"BLOCKED on Task M of Phase N: <blocker-description>.
Journaling and requesting guidance."

Example Execution Flow

> Invoke /iterative-plan-execution with plan: .claude/plans/chart-styling.md

Reading plan...
Found 5 phases.

Creating beads issues...
  beads-101: Chart Styling Phase 1: G2 Theme Infrastructure
  beads-102: Chart Styling Phase 2: Per-Chart Style Atoms
  beads-103: Chart Styling Phase 3: ChartRenderer Integration
  beads-104: Chart Styling Phase 4: Layered Styler Services
  beads-105: Chart Styling Phase 5: Effectful Streaming

Starting Phase 1...
  Decomposed into 4 tasks:
    1. Create vanta-theme.ts
    2. Create palettes.ts
    3. Create index.ts
    4. Run verification

  Task 1/4: Creating vanta-theme.ts
    [implementing...]
    [typecheck: PASS]
    [spike: PASS]
    [exports: PASS]
    [journal written: 2026-01-18-chart-styling-phase-1-task-1.md]

  Task 2/4: Creating palettes.ts
    ...

Phase 1 complete. 4/4 tasks verified.
Updating plan checkboxes...
bd close beads-101

Proceed to Phase 2? [continuing...]

Invocation

From Ralph Prompt

/iterative-plan-execution .claude/plans/<plan-file>.md

Parameters

Related Skills

/spike-testing

/implement_plan

/beads-issue-management