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.

binding	meaning	default	how to infer
<prompt>	the task to plan — a file path or inline text	—	the user's request
<repo>	the project the plan targets; read for ground-truth env + conventions (never edited)	.	the repo being worked on
<plan_file>	the human-readable plan layout (markdown)	<sandbox_root>/plan.md	—
<tasks_file>	the structured tasks, validated against schemas/plan.schema.json	<sandbox_root>/tasks.json	—
<pr_loc>	target lines of code per task (PR-sized; a task may exceed it)	100-400	—
<sandbox_root>	where plan, tasks, and the ledger live	./sandbox	—
<budget>	max refine cycles	5	—

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

Plan artifacts

<tasks_file> (tasks.json) — the machine-executable plan; full contract in schemas/plan.schema.json. Compact shape:

{
  "objective": "...", "end_state": "...", "non_goals": ["..."],
  "environment": {"language": "python", "package_manager": "uv", "test_command": "pytest -q"},
  "components": [{"id": "c1", "name": "config", "description": "load + validate config"}],
  "open_questions": ["which auth provider?"],
  "tasks": [
    {"id": "T1", "title": "config loader", "serves": ["c1"], "description": "...",
     "building_blocks": ["dataclass Config"], "tools": ["pytest"], "packages": ["pyyaml"],
     "files": [{"path": "src/config.py", "action": "create", "what": "Config + load()"}],
     "subtasks": [{"id": "T1.1", "description": "define load(path) -> Config"}],
     "tests": [{"description": "load() parses a valid file", "kind": "unit"}],
     "acceptance_criteria": ["invalid config raises ConfigError"],
     "depends_on": [], "estimated_loc": 180, "suggested_skills": []}
  ],
  "order": ["T1"]
}

<plan_file> (plan.md) — the human-readable layout: objective, end state, non-goals, environment, the components, a task table (id · title · serves · depends_on · est. LOC) in order, risks/open questions, and a one-line "how to execute" pointer to tasks.json. It mirrors tasks.json; tasks.json is the source of truth the executor consumes.

Ledger

<sandbox_root>/ledger.tsv, tab-separated, never commas in free text. Header iter phase verdict score blocking major change:

iter	phase	verdict	score	blocking	major	change
0	build	-	-	-	-	first-principles decomposition: 6 components, 8 tasks, validator ok
1	critique	revise	72	1	2	PE: T3 bundles 2 PRs; T5 has no real test; nothing covers config loading
2	revise	-	-	-	-	split T3 -> T3a/T3b; added retry test to T5; added T9 config loader; reordered
3	critique	pass	90	0	0	PE: solid; one minor naming nit recorded as an open note

Report the final plan at the cycle the critique passed (or the best score reached at <budget>).

Constraints

• Plan only — do not implement. Write no production code, scaffolding, or files in <repo>; the output is plan.md + tasks.json. Execution and debugging are downstream loops.
• Ground every claim in the real repo/environment. Do not invent packages, files, APIs, or commands; verify against <repo>. A genuine unknown is an open_question for the human, not a guess — a plan that confidently states something false is worse than one that flags the gap.
• Keep tasks PR-sized and self-contained. Each task links to ≥1 component and has tests and acceptance criteria; each subtask is atomic. Optimize for a literal implementer who will not fill gaps.
• Keep the critic independent. The principal engineer reviews the plan it did not write (spawn-or-degrade gives real isolation on Claude Code); never let the author pass its own plan.
• Edit only inside <sandbox_root> (plan, tasks, ledger); <repo> is read-only context. Run the loop to a passing critique or <budget> without pausing to ask whether to continue.

Roles

roles/principal-engineer.md — the adversarial plan critic. Spawn-or-degrade: a real isolated subagent on Claude Code (the Agent/Task tool), else adopt the role inline. It is read-only, judges against a fixed rubric, and returns JSON validated against schemas/critique.schema.json. Pass it the host's installed-skill list so it can recommend reuse; if that list is unavailable, it simply skips suggested_skills.