How tekrondo/iterative-planner works
1. Repository purpose
- This repo is not an application runtime; it is a Claude Code skill package that teaches and enforces an iterative planning workflow.
- The core architecture is a filesystem-backed state machine for agent work: Explore → Plan → Execute → Reflect → Re-plan → Close.
2. Top-level split: specification vs tooling
- src/SKILL.md is the authoritative skill spec: the behavior contract Claude follows during work.
- src/references/*.md are policy/format modules that define the rules behind planning rigor, complexity control, code hygiene, decision anchoring, and file formats.
- src/scripts/*.mjs are the only executable components: they create, validate, and manage plan directories.
3. Primary runtime boundary
- The skill runs inside Claude Code, but its source of truth is the local filesystem.
- There is no service backend, database, or networked API. Persistence comes from written files under plans/, not from conversation state.
4. Central data model: plan directories
- The main unit of work is a plans/plan_<date>_<id>/ directory.
- Each plan contains separate artifacts for state, living plan, decisions, findings, progress, verification, checkpoints, lessons snapshot, and summary.
- This separation is deliberate: it supports recovery after context loss and allows each phase to write to a different file boundary.
5. Cross-plan memory layer
- At the plans/ root, consolidated files like FINDINGS.md, DECISIONS.md, LESSONS.md, and INDEX.md act as shared institutional memory across plans.
- The next plan reads these during EXPLORE, so knowledge accumulates across sessions instead of being trapped in one directory.
- plans/.current_plan is the pointer file that identifies the active work item.
6. State machine flow
- EXPLORE is read-only analysis and research; it gathers evidence into plan files.
- PLAN turns findings into an approved approach and establishes success criteria.
- EXECUTE applies changes incrementally and is guarded by revert-first rules and commit discipline.
- REFLECT compares outcomes to the written plan and verification evidence.
- RE-PLAN creates a new direction when evidence invalidates the current one.
- CLOSE finalizes the plan, merges knowledge upward, and preserves the plan directory for traceability.
7. Bootstrap subsystem
- src/scripts/bootstrap.mjs is the orchestration entry point for plan lifecycle management.
- It handles creating a new plan, resuming the active plan, reporting status, closing a plan, and listing existing plans.
- The bootstrap layer is responsible for initializing the filesystem layout and keeping the pointer/consolidated files in sync.
8. Validation subsystem
- src/scripts/validate-plan.mjs checks whether the active plan conforms to the expected protocol and file structure.
- This is the guardrail layer that enforces the repository’s own rules before the skill is considered valid.
- The presence of bootstrap.test.mjs indicates validation is tested as a first-class behavior, not just documentation.
9. Build and packaging boundary
- Makefile and build.ps1 provide parallel packaging and validation workflows for Unix-like systems and Windows.
- The repo produces release artifacts such as a zip package and a combined markdown skill file, which are deployment formats for Claude Code rather than binaries.
- VERSION, CHANGELOG.md, and the README support release management and distribution.
10. Operational rules are encoded as docs, not code
- The architecture relies heavily on Markdown rulebooks: complexity limits, decision anchoring, planning rigor, and file format templates.
- These documents define the expected contents and lifecycle of the plan files, so the “logic” is split between executable scripts and policy docs.
11. Git is part of the workflow
- Git integration is part of the execution model: successful execution steps are committed incrementally, failures are reverted, and close creates a final commit.
- This means the repo’s architecture treats version control as a recovery and audit boundary, not just source history.
12. How to diagram it
- The most accurate diagram would show:
- Claude Code as the consumer
- src/SKILL.md plus src/references/* as the governing spec/policies
- bootstrap.mjs and validate-plan.mjs as orchestration/guardrail tools
- plans/ as the persistent state store
- Git as the audit/recovery layer
- Build scripts and tests as packaging/assurance around the skill artifacts
Main entry points: bootstrap.mjs Bootstrap · SKILL.md Skill spec · validate-plan.mjs Validate plan · Makefile Makefile
Components 20
Skill spec
Authoritative workflow contract and policy references.
- Skill spec · Authoritative behavior contract for the iterative planning workflow.
src/SKILL.md - Planning rigor · Rules for structured exploration, planning discipline, and phase boundaries.
src/references/planning-rigor.md - Complexity control · Limits and heuristics that keep plans and execution incrementally manageable.
src/references/complexity-control.md - Decision anchoring · Guidance for recording rationale, evidence, and durable decisions.
src/references/decision-anchoring.md - Code hygiene · Standards for safe changes, reversibility, and repo maintenance during execution.
src/references/code-hygiene.md - File formats · Templates and conventions for plan files and shared memory documents.
src/references/file-formats.md
Plan runtime
Filesystem-backed plan state and lifecycle management inside Claude Code.
- Claude Code · Host environment that consumes the skill and drives the iterative workflow.
- Plans root · Filesystem-backed shared memory and active-plan pointer for the workflow.
- Current plan · Pointer to the active plan directory.
- Plan dir · Per-plan directory holding state, plan, findings, decisions, progress, verification, and closeout artifacts.
- Shared memory · Cross-plan aggregates that carry findings, decisions, lessons, and index data forward.
- Git layer · Version-control boundary used for incremental commits, revert-first recovery, and final close commits.
Tooling
Executable orchestration, validation, and tests.
- Bootstrap · Entry point for creating, resuming, listing, closing, and reporting on plans.
src/scripts/bootstrap.mjs - Validate plan · Checks that the active plan matches the expected protocol and file structure.
src/scripts/validate-plan.mjs - Bootstrap test · Test coverage for bootstrap and validation behavior.
src/scripts/bootstrap.test.mjs
Release
Packaging and repository metadata.
- Makefile · Unix-like packaging and validation entry point.
Makefile - Build PS1 · Windows packaging and validation entry point.
build.ps1 - README · Repository overview and usage guidance.
README.md - Version · Current packaged version identifier.
VERSION - Changelog · Release history and notable changes.
CHANGELOG.md
Connections 24
- Claude Code → Skill spec: follows · Claude Code consumes the skill contract as the governing workflow.
- Skill spec → Planning rigor: includes · The spec is supported by policy modules that define how planning works.
- Skill spec → Complexity control: includes · Complexity constraints shape the iterative workflow.
- Skill spec → Decision anchoring: includes · Rationale capture and evidence rules are part of the skill.
- Skill spec → Code hygiene: includes · Execution safety and change discipline are enforced through policy.
- Skill spec → File formats: includes · Plan file structure and templates are defined as reusable formats.
- Claude Code → Bootstrap: invokes · Bootstrap manages the plan lifecycle on the local filesystem.
- Claude Code → Validate plan: checks · Validation guards the plan protocol before work proceeds.
- Bootstrap → Plans root: initializes · Creates and maintains the shared plan store.
- Bootstrap → Current plan: updates · Tracks which plan is active.
- Bootstrap → Plan dir: creates/resumes · Bootstraps individual plan workspaces.
- Bootstrap → Shared memory: syncs · Keeps consolidated cross-plan memory in step with plan lifecycle.
- Validate plan → Plans root: inspects · Validation checks the plan store and active plan layout.
- Validate plan → Plan dir: verifies · Ensures the plan directory follows the expected protocol.
- Plan dir → Shared memory: publishes · Plan outcomes are promoted into shared memory on close.
- Shared memory → Plan dir: informs · Next plans read prior findings, decisions, and lessons during explore.
- Plan dir → Git layer: commits · Execution and closeout are captured as git history for recovery and audit.
- Git layer → Bootstrap: supports · Git history underpins resumption, rollback, and lifecycle management.
- Makefile → Bootstrap: packages · Unix workflow wraps the skill build and validation commands.
- Build PS1 → Bootstrap: packages · Windows workflow wraps the skill build and validation commands.
- Bootstrap test → Bootstrap: tests · Behavioral coverage for plan lifecycle orchestration.
- README → Skill spec: documents · Repository usage and purpose are documented around the skill spec.
- Version → Makefile: releases · Versioning feeds packaging and release artifacts.
- Changelog → Makefile: releases · Release notes support distribution workflows.