plan-loop

Provide the prompt and the target repository; the loop decomposes the work from first principles into components and PR-sized tasks, writes plan.md and tasks.json, then validates and critiques the plan until it passes. The output is designed for task-by-task execution.

A deterministic validator checks tasks.json against a JSON schema plus semantic invariants: unique ids, an acyclic dependency graph, a valid topological order, and full component coverage. A separate principal-engineer critique then judges alignment, sizing, testability, and executability.

The loop emits two artifacts: plan.md, a human-readable layout with the objective, components, and task table, and tasks.json, the machine-executable source of truth containing files, subtasks, tests, acceptance criteria, dependencies, and execution order.

No. The target repository is read-only context used for grounding; the loop only writes plan.md, tasks.json, and a ledger inside the sandbox directory. Implementation and debugging are handled by separate downstream loops.

Skip it when you want code written immediately, since this loop stops once the plan is ready to delegate. It is also not intended for research proposals or experiment plans, which need a different planning structure.

The validator script is stdlib-only and requires Python 3.9 or later. It prints a single JSON object with ok, errors, warnings, and stats, exiting nonzero when any error is present.