Iterative Planner

Core Principle: Context Window = RAM. Filesystem = Disk. Write to disk immediately. The context window will rot. The files won’t.

{plan-dir} = plans/plan_YYYY-MM-DD_XXXXXXXX/ (active plan directory under project root). Discovery: plans/.current_plan contains the plan directory name. One active plan at a time. Cross-plan context: plans/FINDINGS.md and plans/DECISIONS.md persist across plans (merged on close).

State Machine

stateDiagram-v2
    [*] --> EXPLORE
    EXPLORE --> PLAN : enough context
    PLAN --> EXPLORE : need more context
    PLAN --> PLAN : user rejects / revise
    PLAN --> EXECUTE : user approves
    EXECUTE --> REFLECT : phase ends/failed/surprise/leash
    REFLECT --> CLOSE : all criteria met
    REFLECT --> RE_PLAN : failed / better approach
    REFLECT --> EXPLORE : need more context
    RE_PLAN --> PLAN : new approach ready
    CLOSE --> [*]

Transitions

Every transition → log in state.md. RE-PLAN transitions → also log in decisions.md (what failed, what learned, why new direction). At CLOSE → audit decision anchors (references/decision-anchoring.md). Merge per-plan findings/decisions to plans/FINDINGS.md and plans/DECISIONS.md.

Mandatory Re-reads (CRITICAL)

These files are active working memory. Re-read during the conversation, not just at start.

>50 messages: re-read state.md + plan.md before every response. Files are truth, not memory.

Bootstrapping

node <skill-path>/scripts/bootstrap.mjs "goal"              # Create new plan (backward-compatible)
node <skill-path>/scripts/bootstrap.mjs new "goal"           # Create new plan
node <skill-path>/scripts/bootstrap.mjs new --force "goal"   # Close active plan, create new one
node <skill-path>/scripts/bootstrap.mjs resume               # Re-entry summary for new sessions
node <skill-path>/scripts/bootstrap.mjs status               # One-line state summary
node <skill-path>/scripts/bootstrap.mjs close                # Close plan (preserves directory)
node <skill-path>/scripts/bootstrap.mjs list                 # Show all plan directories

new refuses if active plan exists — use resume, close, or --force. new ensures .gitignore includes plans/ — prevents plan files from being committed during EXECUTE step commits. close merges per-plan findings/decisions to consolidated files, updates state.md, and removes the .current_plan pointer. The protocol CLOSE state (writing summary.md, auditing decision anchors) should be completed by the agent before running close. After bootstrap → read every file in {plan-dir} (state.md, plan.md, decisions.md, findings.md, progress.md, verification.md) before doing anything else. Then begin EXPLORE. User-provided context → write to findings.md first.

Filesystem Structure

plans/
├── .current_plan                  # → active plan directory name
├── FINDINGS.md                    # Consolidated findings across all plans (merged on close)
├── DECISIONS.md                   # Consolidated decisions across all plans (merged on close)
└── plan_2026-02-14_a3f1b2c9/      # {plan-dir}
    ├── state.md                   # Current state + transition log
    ├── plan.md                    # Living plan (rewritten each iteration)
    ├── decisions.md               # Append-only decision/pivot log
    ├── findings.md                # Summary + index of findings
    ├── findings/                  # Detailed finding files (subagents write here)
    ├── progress.md                # Done vs remaining
    ├── verification.md            # Verification results per REFLECT cycle
    ├── checkpoints/               # Snapshots before risky changes
    └── summary.md                 # Written at CLOSE

Templates: references/file-formats.md

File Lifecycle Matrix

R = read only | W = update (implicit read + write) | R+W = distinct read and write operations | — = do not touch (wrong state if you are).

Read-before-write rule: Always read a plan file before writing/overwriting it — even on the first update after bootstrap. Claude Code’s Write tool will reject writes to files you haven’t read in the current session. This applies to every W and R+W cell below.

Per-State Rules

EXPLORE

• Read state.md, plans/FINDINGS.md and plans/DECISIONS.md at start of EXPLORE for cross-plan context.
• Read code, grep, glob, search. One focused question at a time.
• Flush to findings.md + findings/ after every 2 reads. Read the file first before each write.
• Include file paths + code path traces (e.g. auth.rb:23 → SessionStore#find → redis_store.rb:get).
• DO NOT skip EXPLORE even if you think you know the answer.
• Minimum depth: ≥3 indexed findings in findings.md before transitioning to PLAN. Findings must cover: (1) problem scope, (2) affected files, (3) existing patterns or constraints. Fewer than 3 → keep exploring.
• Use Task subagents to parallelize research. All subagent output → {plan-dir}/findings/ files. Never rely on context-only results. Main agent updates findings.md index after subagents write — subagents don’t touch the index. Naming: findings/{topic-slug}.md (kebab-case, descriptive — e.g. auth-system.md, test-coverage.md).
• Use “think hard” / “ultrathink” for complex analysis.
• REFLECT → EXPLORE loops: append to existing findings, don’t overwrite. Mark corrections with [CORRECTED iter-N].

PLAN

• Gate check: read state.md, plan.md, findings.md, findings/*, decisions.md, progress.md, verification.md, plans/FINDINGS.md, plans/DECISIONS.md before writing anything. If not read → read now. No exceptions. If findings.md has <3 indexed findings → go back to EXPLORE.
• Problem Statement first — before designing steps, write in plan.md: (1) what behavior is expected, (2) invariants — what must always be true, (3) edge cases at boundaries. Can’t state the problem clearly → go back to EXPLORE.
• Write plan.md: problem statement, steps, failure modes, risks, success criteria, verification strategy, complexity budget.
• Verification Strategy — for each success criterion, define: what test/check to run, what command to execute, what result means “pass”. Write to plan.md Verification Strategy section. Plans with no testable criteria → write “N/A — manual review only” (proves you checked). See references/file-formats.md for template.
• Failure Mode Analysis — for each external dependency or integration point in the plan, answer: what if slow? returns garbage? is down? What’s the blast radius? Write to plan.md Failure Modes section. No dependencies → write “None identified” (proves you checked).
• Write decisions.md: log chosen approach + why (mandatory even for first plan). Trade-off rule — phrase every decision as “X at the cost of Y”. Never recommend without stating what it costs.
• Read then write verification.md with initial template (criteria table populated from success criteria, methods from verification strategy, results pending).
• Read then write state.md + progress.md.
• List every file to modify/create. Can’t list them → go back to EXPLORE.
• Only recommended approach in plan. Alternatives → decisions.md.
• Wait for explicit user approval.

EXECUTE

• Pre-Step Checklist in state.md: reset all boxes [ ], then check each [x] as completed before starting the step. This is the file-based enforcement of Mandatory Re-reads.
• Iteration 1, first EXECUTE → create checkpoints/cp-000-iter1.md (nuclear fallback). “Git State” = commit hash BEFORE changes (the restore point).
• One step at a time. Post-Step Gate after each (see below).
• Checkpoint before risky changes (3+ files, shared modules, destructive ops). Name: cp-NNN-iterN.md (e.g. cp-001-iter2.md). Increment NNN globally across iterations.
• Commit after each successful step: [iter-N/step-M] description.
• If something breaks → STOP. 2 fix attempts max (Autonomy Leash). Each must follow Revert-First.
• Irreversible operations (DB migrations, external API calls, service config, non-tracked file deletion): mark step [IRREVERSIBLE] in plan.md during PLAN. Full procedure: references/code-hygiene.md.
• Surprise discovery (behavior contradicts findings, unknown dependency, wrong assumption) → note in state.md, finish or revert current step, transition to REFLECT. Do NOT silently update findings during EXECUTE.
• Add # DECISION D-NNN comments where needed (references/decision-anchoring.md).

Post-Step Gate (successful steps only — all 3 before moving on)

1. plan.md — mark step [x], advance marker, update complexity budget
2. progress.md — move item Remaining → Completed, set next In Progress
3. state.md — update step number, append to change manifest

On failed step: skip gate. Follow Autonomy Leash (revert-first, 2 attempts max).

REFLECT

• Read plan.md (criteria + verification strategy) + progress.md before evaluating.
• Read findings.md + relevant findings/* — check if discoveries during EXECUTE contradict earlier findings. Note contradictions in decisions.md.
• Read checkpoints/* — know what rollback options exist before deciding next transition. Note available restore points in decisions.md if transitioning to RE-PLAN.
• Cross-validate: every [x] in plan.md must be “Completed” in progress.md. Fix drift first.
• Run verification — execute each check defined in the Verification Strategy. Read verification.md, then record results: criterion, method, command/action, result (PASS/FAIL), evidence (output summary or log reference). See references/file-formats.md for template.
• Read decisions.md — check 3-strike patterns.
• Compare against written criteria, not memory. Run 5 Simplification Checks (references/complexity-control.md).
• Write decisions.md (what happened, learned, root cause) + progress.md + state.md.

RE-PLAN

• Read decisions.md, findings.md, relevant findings/*.
• Read checkpoints/* — decide keep vs revert. Default: if unsure, revert to latest checkpoint. See references/code-hygiene.md for full decision framework.
• If earlier findings proved wrong or incomplete → update findings.md + findings/* with corrections. Mark corrections: [CORRECTED iter-N] + what changed and why. Append, don’t delete original text.
• Write decisions.md: log pivot + mandatory Complexity Assessment.
• Write state.md + progress.md (mark failed items, note pivot).
• Present options to user → get approval → transition to PLAN.

Complexity Control (CRITICAL)

Default response to failure = simplify, not add. See references/complexity-control.md.

Revert-First — when something breaks: (1) STOP (2) revert? (3) delete? (4) one-liner? (5) none → REFLECT. 10-Line Rule — fix needs >10 new lines → it’s not a fix → REFLECT. 3-Strike Rule — same area breaks 3× → RE-PLAN with fundamentally different approach. Revert to checkpoint covering the struck area. Complexity Budget — tracked in plan.md: files added 0/3, abstractions 0/2, lines net-zero target. Forbidden: wrapper cascades, config toggles, copy-paste, exception swallowing, type escapes, adapters, “temporary” workarounds. Nuclear Option — iteration 5 + bloat >2× scope → recommend full revert to cp-000 (or later checkpoint if user agrees). Otherwise proceed with caution. See references/complexity-control.md.

Autonomy Leash (CRITICAL)

When a step fails during EXECUTE:

1. 2 fix attempts max — each must follow Revert-First + 10-Line Rule.
2. Both fail → STOP COMPLETELY. No 3rd fix. No silent alternative. No skipping ahead.
3. Revert uncommitted changes to last clean commit. Codebase must be known-good before presenting.
4. Present: what step should do, what happened, 2 attempts, root cause guess, available checkpoints for rollback.
5. Transition → REFLECT. Log leash hit in state.md. Wait for user.

Track attempts in state.md. Resets on: user direction, new step, or RE-PLAN. No exceptions. Unguided fix chains derail projects.

Code Hygiene (CRITICAL)

Failed code must not survive. Track changes in change manifest in state.md. Failed step → revert all uncommitted. RE-PLAN → explicitly decide keep vs revert. Codebase must be known-good before any PLAN. See references/code-hygiene.md.

Decision Anchoring (CRITICAL)

Code from failed iterations carries invisible context. Anchor # DECISION D-NNN at point of impact — state what NOT to do and why. Audit at CLOSE. See references/decision-anchoring.md.

Iteration Limits

Increment on PLAN → EXECUTE. Iteration 0 = EXPLORE-only (pre-plan). First real = iteration 1.

• Iteration 6+: hard STOP. Going in circles? Harder than scoped? Break into smaller tasks.

Recovery from Context Loss

0. If plans/.current_plan is missing or corrupted: run bootstrap.mjs list to find plan directories, then recreate the pointer: echo "plan_YYYY-MM-DD_XXXXXXXX" > plans/.current_plan (substitute actual directory name).
1. plans/.current_plan → plan dir name
2. state.md → where you are
3. plan.md → current plan
4. decisions.md → what was tried / failed
5. progress.md → done vs remaining
6. findings.md + findings/* → discovered context
7. checkpoints/* → available rollback points and their git hashes
8. plans/FINDINGS.md + plans/DECISIONS.md → cross-plan context from previous plans
9. Resume from current state. Never start over.

Git Integration

• EXPLORE/PLAN/REFLECT/RE-PLAN: no commits.
• EXECUTE: commit per successful step [iter-N/step-M] desc. Failed step → revert uncommitted.
• RE-PLAN: keep successful commits if valid under new plan, or git checkout <checkpoint-commit> -- . to revert. No partial state. Log choice in decisions.md.
• CLOSE: final commit + tag.

User Interaction

When NOT to Use

Simple single-file changes, obvious solutions, known-root-cause bugs, or “just do it”.

References

• references/file-formats.md — templates for all {plan-dir} files
• references/complexity-control.md — anti-complexity protocol, forbidden patterns
• references/code-hygiene.md — change manifest, revert procedures
• references/decision-anchoring.md — when/how to anchor decisions in code