Iterative Planner skill
A Claude Code skill that drives a hard task through explore, plan, execute and reflect, writing every decision to disk.
- 72 ★ on the repository
- Last commit
Extended access
Why this level
- The skill creates plan files and makes the agent commit every step.
- Node.js bootstrap scripts run locally in the project.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/iterative-plannerDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The skill creates plan files and makes the agent commit every step.
- Node.js bootstrap scripts run locally in the project.
This is third-party code. Review the repository files before installing.
What it does
Iterative Planner tackles an agent losing the plot on a big task: the context window acts as RAM and forgets early decisions. The skill makes the agent write every finding, decision, pivot and dead end to the `plans/` folder the moment it appears, while a six-state machine drives the work: explore, plan, execute, reflect, pivot and close. The agent first reads the code, then brings a written plan for approval and only then edits files. Steps run one at a time, each committed, so a bad turn rolls back with `git revert`. At iteration five forced decomposition kicks in, and from iteration six execution stops, leaving a partial close and new plans. The next task reads the accumulated records as a map of the system.
Who it is for. Developers who hand an agent a refactor, migration or debugging task and want to see what was already tried and where the work stands.
Good fit when
- A migration touches more than three files or two systems and needs a written plan.
- A task has already failed once and the agent repeats earlier attempts.
- Context was cut mid-work and the state must be restored with `resume`.
- Decisions and lessons must be kept as a reference for the next task.
Not a fit when
- A single-file single-step edit, where the planning loop adds overhead.
- The solution is obvious and the task is familiar and simple.
- The repository cannot be cluttered with a `plans/` folder and it cannot be moved out of the project.
Example request
Plan the REST to GraphQL migration with the iterative-planner protocol: explore the code first, then bring a plan for approval.Limitations
The bootstrap and validator scripts are written in Node.js, version 18 or newer is needed, and no dependencies must be installed. There is always exactly one active plan, kept in `plans/`, and a new one cannot start before the current one closes except with `new --force`. The `plans/` folder is excluded from git through `.gitignore`, only `plans/ANCHORS.md` enters history, and you commit it yourself because the skill never runs `git add`. Sub-agents and the `/ip-dashboard` command are copied separately and are optional. The single-file version works without the bootstrap scripts.
How to disable. Delete `~/.claude/skills/iterative-planner` and the copied files from `~/.claude/agents` and `~/.claude/commands`. Remove the `plans/` folder in projects by hand.
FAQ
What happens at iteration five?
The protocol forces a decomposition into two or three independent sub-goals, each of which may become its own plan. From iteration six or after 18 rounds execution stops.
Can several plans run at once?
No, one plan is active, tracked by the `plans/.current_plan` file. A new one starts after the current closes or with `new --force`.
What if context is lost?
Run `bootstrap.mjs resume`. The script restores state from disk using `state.md` and prints a summary, so the agent continues where it left off.
Do I need the sub-agent definitions?
No. They speed things up: scouts run in parallel, and there is a verifier and an adversarial reviewer. Without them the same state machine runs in a single thread.
How do I install without the archive?
Clone the repository, run `make build` and copy `build/iterative-planner` to `~/.claude/skills/`. A single-file version goes into custom instructions.
Discussion
No questions or reviews yet.
Related
SkillsThe /improve skill: a strong model audits a repository and writes self-contained fix plans, and you hand the execution to a cheaper model
14 skills that find the gaps in a task before the code: interviews, plans, assumption tests and proof that a bug fix works
An autonomous iteration skill for agents: modify, verify, revert failed changes, and repeat the loop toward a target metric
A set of 29 skills that make an agent think like a senior engineer before writing code: plans, failure causes and review
A Claude Code working configuration: a planner with per-milestone review, sub-agents and skills for analysis, refactoring and docs sync
Over twenty skills for coding agents: MCP and hooks, plan mode, a bug-fix protocol, prompting and a bash safety hook
README in short
The repository holds the skill, bootstrap and validator scripts, sub-agent definitions, the `/ip-dashboard` panel and a `node:test` suite. The author describes the result as accumulating knowledge: every plan leaves findings and lessons, so the next task does not start from zero.
README badge
Original SKILL.md
---
name: iterative-planner
description: >
State-machine driven iterative planning and execution for complex coding tasks.
Cycle: Explore → Plan → Execute → Reflect → Pivot. Filesystem as persistent memory.
Use for multi-file tasks, migrations, refactoring, failed tasks, or anything non-trivial.
version: __SKILL_VERSION__
released: __SKILL_DATE__
commit: __SKILL_COMMIT__
---
# 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-DDTHHMMSS-XXXXXXXX/` (active plan directory under project root; UTC timestamp, colon-free, 8-hex tail). Directories created before v2.36.0 use the legacy shape `plans/plan_YYYY-MM-DD_XXXXXXXX/` — never generated again, but **always still read**: every id-recognizing path (pointer, `retire`, anchor scan, `## <plan-id>` sections, `*Plan:*` preamble, sliding-window trim, INDEX date) accepts the union of both grammars.
**Discovery**: `plans/.current_plan` contains the plan directory name. One active plan at a time.
**Cross-plan context**: `plans/FINDINGS.md`, `plans/DECISIONS.md` (merged on close), `plans/LESSONS.md` (rewritten on close), `plans/SYSTEM.md` (system atlas — domain-neutral map of the target system, rewritten on close), `plans/INDEX.md` (topic→directory map, survives sliding-window trim). Caps + R/W rules: File Lifecycle Matrix.
## Orchestrator Role Assumption (READ FIRST)
This skill is driven by a state-machine orchestrator. The authoritative runtime dispatch logic — sub-agent spawning, the six Presentation Contracts, the PLAN compression gate, and the EXECUTE pre-step gate — lives in `agents/ip-orchestrator.md`, NOT in this file. This file is the protocol and state-machine **specification**; `agents/ip-orchestrator.md` is the **procedure** you execute.
On activation, determine your mode:
1. **Already the orchestrator** — if you were launched as `iterative-planner-orchestrator` (via `claude --agent iterative-planner-orchestrator`) OR you have already read `agents/ip-orchestrator.md` and assumed that role earlier in this conversation: do NOT re-read it and do NOT spawn another orchestrator. You ARE the orchestrator — continue with the dispatch logic you already hold. This guard is evaluated FIRST and short-circuits the reload loop that would otherwise arise because `agents/ip-orchestrator.md` declares `skills: [iterative-planner]` (loading it re-loads this skill).
2. **Agent definitions installed** — if `agents/ip-orchestrator.md` is readable and you are NOT already operating as the orchestrator: immediately Read `agents/ip-orchestrator.md` and assume that role for the remainder of this conversation. Resolve `agents/ip-orchestrator.md` against the skill base directory the harness announces on activation (the "Base directory for this skill: ..." line). Treat its Sub-Agent Dispatch Rules, Presentation Contracts, compression gate, and pre-step gate as your operating procedure. Adopt the role **in-thread** — do NOT spawn or launch a separate `iterative-planner-orchestrator` agent. On first activation, FIRST emit the version + credit banner as the load-up line — run `node <skill-path>/scripts/bootstrap.mjs banner` and surface its stdout verbatim — then announce the live mode with one user-visible line — e.g. `[iterative-planner] orchestrator engaged — dispatching specialized sub-agents.` — so the user sees the version and credit and knows sub-agent dispatch is active. Then begin bootstrapping.
3. **Monolithic fallback** — if `agents/ip-orchestrator.md` (and the `agents/ip-*.md` definitions) are NOT installed: run the full protocol yourself in this single thread, driving the state machine from this file's spec — the per-state operative rules come from the `emit-state` router (see below), NOT from inline bodies (the Per-State Rules section is summaries + pointers only) — and FIRST emit the version + credit banner as the load-up line — run `node <skill-path>/scripts/bootstrap.mjs banner` and surface its stdout verbatim — then announce the degraded mode with one user-visible line on activation — e.g. `[iterative-planner] sub-agent definitions not found — running monolithic (single-thread) mode.` — so the user sees the version and credit and silent degradation becomes a visible signal. Use `Task` subagents where this file calls for parallel work (EXPLORE, REFLECT review). The state machine, gates, leash, and Presentation Contracts (`references/file-formats.md`) are identical — you are simply both coordinator and worker. In this mode you also run `node <skill-path>/scripts/emit-state.mjs --state <state>` on entering each of EXPLORE/PLAN/EXECUTE/REFLECT/PIVOT and follow its output as the operative per-state rules (the Per-State Rules section here is now a summary + pointer; the scripts ship with the skill bundle, so the router resolves even without agent definitions installed).
**Idempotency rule**: the trigger for reading `agents/ip-orchestrator.md` is "not yet operating as the orchestrator." Once you have read it once in this conversation, condition 1 holds for every subsequent skill re-trigger — you never read it twice, and there is no spawn, so no reload loop.
### Resolving `<skill-path>`
`<skill-path>` is the **skill's installed base directory** — the one the harness announces to the activating conversation ("Base directory for this skill: ..."). It is the single definition; everything below is a pointer to it.
- **The orchestrator** sees that announcement and holds the absolute path.
- **Sub-agents do not.** So the orchestrator MUST pass it down: every spawn prompt opens with a `SKILL PATH: <absolute-path>` line. A sub-agent resolves `<skill-path>` from that line — nowhere else.
- **Fallback** (line absent, e.g. an out-of-band dispatch): use the installed skill bundle, `~/.claude/skills/iterative-planner/`.
- **It is NEVER a path relative to the target project's root.** A shipped prompt that says `src/scripts/<x>.mjs` is always wrong: a consuming project has no `src/scripts/` and the invocation silently resolves to nothing, disabling whatever check it was supposed to run. This failure is mechanically gated — `scripts/check-agent-wiring.mjs` rules (a) and (d).
## State Machine
```mermaid
stateDiagram-v2
[*] --> EXPLORE
EXPLORE --> PLAN : enough context
PLAN --> EXPLORE : need more context
PLAN --> PLAN : user rejects / revise
PLAN --> EXECUTE : user approves