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

code

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

code

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:

Check	Command	Purpose
Type Safety	`bun run typecheck`	Catch compile errors
Runtime Smoke	`bun run scripts/spike-<feature>-phase-N.ts`	Exercise new code
Export Resolution	Import in scratch file	Verify module wiring

Journaling Protocol

File Location

code

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

Template

markdown

# 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

code

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

Spike Template

typescript

/**
 * 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

bash

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

Phase End

bash

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

Blocked

bash

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

Plan File Updates

After completing each phase section update the plan:

markdown

### 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:

code

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

code

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

Spike Fails

code

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

code

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

Self-Prompts

Before Starting Phase

code

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

Before Each Task

code

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

After Task Verification

code

"Task M verified. Writing journal entry."

Phase Complete

code

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

Blocker Encountered

code

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

Example Execution Flow

code

> 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

code

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

Parameters

Parameter	Description
Plan path	Required - path to plan markdown file
--start-phase N	Optional - start from specific phase
--dry-run	Optional - show decomposition without executing

Related Skills

Skill	Use
`/spike-testing`	Spike methodology for verification
`/implement_plan`	Alternative non-iterative execution
`/beads-issue-management`	Work tracking commands