# tekrondo/iterative-planner architecture

> Architecture diagram of the GitHub repository tekrondo/iterative-planner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tekrondo/iterative-planner
- Repository: https://github.com/tekrondo/iterative-planner

## Overview

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: [`src/scripts/bootstrap.mjs`](https://github.com/tekrondo/iterative-planner/blob/main/src/scripts/bootstrap.mjs) (Bootstrap), [`src/SKILL.md`](https://github.com/tekrondo/iterative-planner/blob/main/src/SKILL.md) (Skill spec), [`src/scripts/validate-plan.mjs`](https://github.com/tekrondo/iterative-planner/blob/main/src/scripts/validate-plan.mjs) (Validate plan), [`Makefile`](https://github.com/tekrondo/iterative-planner/tree/main/Makefile) (Makefile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_spec["Skill spec"]
  node_skill_spec["Skill spec<br/>md spec<br/>[SKILL.md]"]
  node_planning_rigor["Planning rigor<br/>policy<br/>[planning-rigor.md]"]
  node_complexity_control["Complexity control<br/>policy"]
  node_decision_anchoring["Decision anchoring<br/>policy"]
  node_code_hygiene["Code hygiene<br/>policy<br/>[code-hygiene.md]"]
  node_file_formats["File formats<br/>policy<br/>[file-formats.md]"]
end

subgraph group_group_runtime["Plan runtime"]
  node_claude_code(("Claude Code<br/>consumer"))
  node_plans_root[("Plans root<br/>state store")]
  node_current_plan["Current plan<br/>pointer"]
  node_plan_dir[("Plan dir<br/>workspace state")]
  node_shared_memory["Shared memory<br/>institutional memory"]
  node_git_layer["Git layer<br/>audit/recovery"]
end

subgraph group_group_tools["Tooling"]
  node_bootstrap["Bootstrap<br/>orchestrator<br/>[bootstrap.mjs]"]
  node_validate_plan["Validate plan<br/>guardrail<br/>[validate-plan.mjs]"]
  node_bootstrap_test["Bootstrap test<br/>[bootstrap.test.mjs]"]
end

subgraph group_group_release["Release"]
  node_makefile["Makefile<br/>build automation"]
  node_build_ps1["Build PS1<br/>build automation<br/>[build.ps1]"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_version["Version<br/>release marker"]
  node_changelog["Changelog<br/>release notes<br/>[CHANGELOG.md]"]
end

node_claude_code -->|"follows"| node_skill_spec
node_skill_spec -->|"includes"| node_planning_rigor
node_skill_spec -->|"includes"| node_complexity_control
node_skill_spec -->|"includes"| node_decision_anchoring
node_skill_spec -->|"includes"| node_code_hygiene
node_skill_spec -->|"includes"| node_file_formats
node_claude_code -->|"invokes"| node_bootstrap
node_claude_code -->|"checks"| node_validate_plan
node_bootstrap -->|"initializes"| node_plans_root
node_bootstrap -->|"updates"| node_current_plan
node_bootstrap -->|"creates/resumes"| node_plan_dir
node_bootstrap -->|"syncs"| node_shared_memory
node_validate_plan -->|"inspects"| node_plans_root
node_validate_plan -->|"verifies"| node_plan_dir
node_plan_dir -->|"publishes"| node_shared_memory
node_shared_memory -->|"informs"| node_plan_dir
node_plan_dir -->|"commits"| node_git_layer
node_git_layer -.->|"supports"| node_bootstrap
node_makefile -->|"packages"| node_bootstrap
node_build_ps1 -->|"packages"| node_bootstrap
node_bootstrap_test -->|"tests"| node_bootstrap
node_readme -.->|"documents"| node_skill_spec
node_version -.->|"releases"| node_makefile
node_changelog -.->|"releases"| node_makefile

click node_skill_spec "https://github.com/tekrondo/iterative-planner/blob/main/src/SKILL.md"
click node_planning_rigor "https://github.com/tekrondo/iterative-planner/blob/main/src/references/planning-rigor.md"
click node_complexity_control "https://github.com/tekrondo/iterative-planner/blob/main/src/references/complexity-control.md"
click node_decision_anchoring "https://github.com/tekrondo/iterative-planner/blob/main/src/references/decision-anchoring.md"
click node_code_hygiene "https://github.com/tekrondo/iterative-planner/blob/main/src/references/code-hygiene.md"
click node_file_formats "https://github.com/tekrondo/iterative-planner/blob/main/src/references/file-formats.md"
click node_bootstrap "https://github.com/tekrondo/iterative-planner/blob/main/src/scripts/bootstrap.mjs"
click node_validate_plan "https://github.com/tekrondo/iterative-planner/blob/main/src/scripts/validate-plan.mjs"
click node_bootstrap_test "https://github.com/tekrondo/iterative-planner/blob/main/src/scripts/bootstrap.test.mjs"
click node_makefile "https://github.com/tekrondo/iterative-planner/tree/main/Makefile"
click node_build_ps1 "https://github.com/tekrondo/iterative-planner/blob/main/build.ps1"
click node_readme "https://github.com/tekrondo/iterative-planner/blob/main/README.md"
click node_version "https://github.com/tekrondo/iterative-planner/tree/main/VERSION"
click node_changelog "https://github.com/tekrondo/iterative-planner/blob/main/CHANGELOG.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill_spec,node_planning_rigor,node_complexity_control,node_decision_anchoring,node_code_hygiene,node_file_formats toneBlue
class node_claude_code,node_plans_root,node_current_plan,node_plan_dir,node_shared_memory,node_git_layer toneAmber
class node_bootstrap,node_validate_plan,node_bootstrap_test toneMint
class node_makefile,node_build_ps1,node_readme,node_version,node_changelog toneRose
```

## Components

### Skill spec

Authoritative workflow contract and policy references.

- [Skill spec](https://github.com/tekrondo/iterative-planner/blob/main/src/SKILL.md): md spec · Authoritative behavior contract for the iterative planning workflow. · `src/SKILL.md`
- [Planning rigor](https://github.com/tekrondo/iterative-planner/blob/main/src/references/planning-rigor.md): policy · Rules for structured exploration, planning discipline, and phase boundaries. · `src/references/planning-rigor.md`
- [Complexity control](https://github.com/tekrondo/iterative-planner/blob/main/src/references/complexity-control.md): policy · Limits and heuristics that keep plans and execution incrementally manageable. · `src/references/complexity-control.md`
- [Decision anchoring](https://github.com/tekrondo/iterative-planner/blob/main/src/references/decision-anchoring.md): policy · Guidance for recording rationale, evidence, and durable decisions. · `src/references/decision-anchoring.md`
- [Code hygiene](https://github.com/tekrondo/iterative-planner/blob/main/src/references/code-hygiene.md): policy · Standards for safe changes, reversibility, and repo maintenance during execution. · `src/references/code-hygiene.md`
- [File formats](https://github.com/tekrondo/iterative-planner/blob/main/src/references/file-formats.md): policy · 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**: consumer · Host environment that consumes the skill and drives the iterative workflow.
- **Plans root**: state store · Filesystem-backed shared memory and active-plan pointer for the workflow.
- **Current plan**: pointer · Pointer to the active plan directory.
- **Plan dir**: workspace state · Per-plan directory holding state, plan, findings, decisions, progress, verification, and closeout artifacts.
- **Shared memory**: institutional memory · Cross-plan aggregates that carry findings, decisions, lessons, and index data forward.
- **Git layer**: audit/recovery · Version-control boundary used for incremental commits, revert-first recovery, and final close commits.

### Tooling

Executable orchestration, validation, and tests.

- [Bootstrap](https://github.com/tekrondo/iterative-planner/blob/main/src/scripts/bootstrap.mjs): orchestrator · Entry point for creating, resuming, listing, closing, and reporting on plans. · `src/scripts/bootstrap.mjs`
- [Validate plan](https://github.com/tekrondo/iterative-planner/blob/main/src/scripts/validate-plan.mjs): guardrail · Checks that the active plan matches the expected protocol and file structure. · `src/scripts/validate-plan.mjs`
- [Bootstrap test](https://github.com/tekrondo/iterative-planner/blob/main/src/scripts/bootstrap.test.mjs): test · Test coverage for bootstrap and validation behavior. · `src/scripts/bootstrap.test.mjs`

### Release

Packaging and repository metadata.

- [Makefile](https://github.com/tekrondo/iterative-planner/tree/main/Makefile): build automation · Unix-like packaging and validation entry point. · `Makefile`
- [Build PS1](https://github.com/tekrondo/iterative-planner/blob/main/build.ps1): build automation · Windows packaging and validation entry point. · `build.ps1`
- [README](https://github.com/tekrondo/iterative-planner/blob/main/README.md): docs · Repository overview and usage guidance. · `README.md`
- [Version](https://github.com/tekrondo/iterative-planner/tree/main/VERSION): release marker · Current packaged version identifier. · `VERSION`
- [Changelog](https://github.com/tekrondo/iterative-planner/blob/main/CHANGELOG.md): release notes · Release history and notable changes. · `CHANGELOG.md`

## Connections

- 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.
