Plan Loop

Plan Loop

A planning loop: it turns a prompt into a plan detailed and correct enough to hand to a lower-tier model. The artifact is the plan — plan.md (the layout) + tasks.json (PR-sized tasks, each with files, tests, dependencies, and atomic subtasks). The feedback signal is two-part, like the repo's other evaluator loops: an objective gate (tools/validate_plan.py — schema shape, an acyclic dependency graph, a valid topological order, full component coverage) and a qualitative gate (a separate principal engineer agent that critiques alignment, decomposition, testability, and whether a junior could execute each task without guessing). You build the plan from first principles, validate it, critique it, and revise until the critique passes. This is the plan stage of a larger prompt → plan → execute → debug pipeline; it stops once the plan is ready to delegate.

When to use

Use to convert a feature/bug/refactor prompt into an executable plan grounded in a real repository — when the goal is a hand-off artifact a downstream executor (or a smaller model) can implement task-by-task. The plan is only as good as its weakest task for a literal-minded implementer, so the loop optimizes for executability, not prose.

Default: ground the plan in the <repo> you are given and let the principal-engineer critique drive the revisions. Escape hatch: if a key decision can't be resolved from the prompt or the repo, record it as an open_question for the human rather than guessing. Not for writing the code (a downstream execute loop), and not for research/experiment proposals (use research-proposal).

Setup

Resolve bindings interactively. If loop.run.yaml exists, load it, confirm the values in one line, and skip to the loop. Otherwise: on Claude Code (the AskUserQuestion tool is available) infer a likely value per binding and recommend it; on other hosts ask each as a quoted prompt. Then write loop.run.yaml (format: examples/run.example.yaml) and confirm before creating any other files.

<skill_dir> is this skill's installed folder; substitute the real path when writing loop.run.yaml. The objective gate runs each cycle:

python3 <skill_dir>/tools/validate_plan.py --tasks <tasks_file>

It prints one JSON object {ok, errors, warnings, stats} — ok must be true (no errors) before a plan is considered ready.

The loop

Copy this checklist and tick items off.

Build the plan (iteration 0 — first principles):

• Ground. Read <prompt> and inspect <repo> for ground truth: language, package manager, runtime/OS, the test command, and existing modules/conventions to reuse. Check what you can; never assume what you can read.
• Decompose. Lay out the components from first principles — objective; end state / definition of done; non-goals; environment; building blocks; interfaces/contracts between blocks; tools; packages; data/assets; reuse (existing code + installed skills); open questions. Recursively split any component too big to reason about in one piece.
• Tasks (PR-sized). Break the work into tasks, each ~<pr_loc> and equivalent to one PR. For each record: which components it serves, a description, building_blocks/tools/packages, the exact files it creates/modifies, tests that prove it, acceptance_criteria, and estimated_loc.
• Order. Fill each task's depends_on, then compute a topological order (every task after its dependencies).
• Subtasks. Split each task into atomic subtasks a junior can do with no further decisions — "create file X", "define function f(args) -> T", "wire f into Y".
• Write + validate. Write <plan_file> and <tasks_file>, then run tools/validate_plan.py; fix every error and weigh every warning before the first critique. Log the baseline ledger row.

Refine (repeat until the plan passes or <budget>):

• Critique. Spawn the principal engineer (spawn-or-degrade, roles/principal-engineer.md) with the prompt, the repo, plan.md, tasks.json, the latest validate_plan.py output, and the list of installed skills on this host. It returns a structured critique (schemas/critique.schema.json): verdict, score, issues (blocking/major/minor, each with a fix), coverage gaps, and suggested skills.
• Revise. Apply the fix for every blocking and major issue — re-decompose, re-size, re-order, add tests, pin packages, add concrete signatures/paths/data shapes so a junior can't go wrong. Re-run tools/validate_plan.py. Append a ledger row.
• Stop when the critique returns pass (no blocking or major issues) and the validator is clean — the plan is ready to delegate. Else loop, up to <budget>; if the score plateaus with only minor issues, stop and record them as open notes.

On stop, the deliverable is <plan_file> + <tasks_file> (plus any open_questions for the human), built to be executed task-by-task in order by a downstream execute loop or a lower-tier model.