Appearance
Planner
Finn's planning method, productised. The method itself is not new here: surface the load-bearing forks first, answer them, then write a plan doc of numbered items where each carries a one-line task, two to five criteria you can actually check against real output, and an explicit out-of-scope clause. That method built every other module in this repo, and until now it lived entirely in finn's head and in the shape of the plan files, which made the agent a cold and expensive planner every single time.
The planner is two halves that share one format. The plan skill runs the method and writes the plan doc. The plan map reads a plan back and renders it as one self-contained page you can actually see the shape of. The linchpin joining them is a parseable format, so the map is a pure deterministic transform: cheap, always fresh, and it spends no tokens at all.
In Practice
Three commands, and only one of them costs anything.
/plan turn a goal into an anchored plan doc, forks first
/plan-map render a plan as one self-contained html page
/plan-review adversarially pressure-test a drafted plan, opt in/plan is interactive and asks before it writes. /plan-map is free and deterministic, re-run it any time. /plan-review is the only one that fans out agents, and it is deliberately absent from the default path.
The Format
The linchpin. It is a light extension of what the plan files already do, so the existing plan parses with no rewrite at all.
A plan lives across two kinds of file and the parser merges them by item id. PLAN.md is the tracker and the authoritative item set, one row per item under ## phase headings:
- [x] 115 the parseable format spec + parser
- [~] 121 the wiki integration
- [ ] 122 packagingThe four markers are [ ] not started, [~] in progress, [x] done, and [-] dropped. A dropped item keeps its row and renders struck rather than vanishing.
An item id is one of three shapes, and the parser reads all three as an opaque string, never as an integer: a core number (43, the plain-integer items from before the lettered scheme), a plan id (M20.1, or M20.A.1 once a sub-plan letter is in play), and a gate id (G1, a survey or phase gate carried as a tracker row). Item ids went plan-scoped in 2026-07-25, so M25.11 means the 11th item of plan M25 and only makes sense alongside its plan.
The plan docs carry the richer anchors that enrich a tracker item:
- 115 the parseable format spec + parser. done, the spec doc is written,
a malformed anchor is reported not swallowed. out of scope, editing the
existing items to add tags.A plan-doc bullet only counts as an anchor when it carries a done, clause and its id matches a tracker row, so a numbered bullet sitting in ordinary prose is never mistaken for an item.
Two optional labels sharpen the map when you use them. deps: gated 83-90, needs 21, amends 24 declares dependencies explicitly, one of four kinds (gated, needs, amends, or supersedes, which marks a replaced item), and effort: S | M | L weights a node. Neither is required. When no deps: line is present the parser falls back to scanning the prose for the same relationships, which is why the existing hundred-plus items resolve their edges today with no backfill at all.
A criterion is plain prose or the sharper when <input> then <observable output> form. The skill treats a criterion you cannot check, anything reading "works well" or "is robust", as a defect and rewrites it toward the observable form. This is the single most valuable discipline in the method and the easiest to skimp.
The phase headers double as the map's lanes. The live shape is ## <plan id> <name>, with an optional trailing (<label>) stripped off, so ## M25 reminders (4ae) reads as the lane M25 named "reminders". The retired ## phase <id>, <name> (amendment <n>) shape still parses too, since an archived doc carries it.
The Pipeline
Three deterministic stages, each readable on its own, each finding its siblings via path self so they work wherever they are installed.
parse-plan.nu
Reads the tracker plus every plan doc into one item model: id, status, phase, task, criteria, out-of-scope, deps, effort, gates, source. It reports rather than swallows, so a malformed anchor or an anchor with no tracker row surfaces as an error instead of vanishing. --list prints a human table, --errors prints only the problems.
It also reads the project's plan naming scheme, .claude/planning/scheme.nuon, for the stem, the closed prefix, the plan dir, and the tracker name, the same record plan-alloc.nu and plan-close.nu in the planning framework bake. That file is shipped and owned by the Plan System module, so reading it is a project-file read exactly like reading PLAN.md itself, not a new dependency on that module. The shipped scheme is baked into the script as a default and the file merges over it, so a missing, partial, or malformed file all mean the shipped scheme rather than an error. Matching stays generic on purpose: every id pattern uses a plain [A-Z] letter class rather than the scheme's own letters, because a scheme says what a project writes, never what the parser will read.
plan-model.nu
Takes that model and derives every map primitive from it in one pass: nodes sized by effort, edges resolved from prerequisite to dependent, phase lanes, the critical path as the longest dependency chain, the unblocked-next set of items whose prerequisites are all done, and the progress rollup per phase and overall. Cycles cannot hang it, the longest-path pass is bounded relaxation rather than recursion.
render-map.nu
Turns the derived model into the page. One parse feeds every view, so a status change in PLAN.md flips a node colour, moves the rollup, and recomputes what is unblocked, all from re-running the same chain.
The Map
The generated page carries a progress rollup, a whats-next list of everything actionable right now, a dependency graph, a phase roadmap, a four-column status board, and an expandable card per item showing its criteria checklist, out-of-scope, gates, and dependencies in and out.
The graph is hand-laid inline SVG rather than a charting library, so the page needs no external asset and always renders. Nodes are laid out in longest-path layers, and each layer is ordered by the average slot of its predecessors, a barycentre pass, which is what keeps the edges from crossing. The critical path is highlighted through both the nodes and the edges. The graph deliberately draws only the items that actually participate in a dependency, because a flat graph of two hundred mostly-unconnected nodes is a wall rather than a diagram. Everything else lives in the roadmap, the board, and the cards.
Output is guarded. Generated pages carry a marker, and the renderer refuses to overwrite any file that lacks it unless you pass --force, so a hand-made page can never be silently clobbered by a regeneration.
The Review
/plan-review is two halves and the cheap one stands alone.
plan-review-check.nu needs no agent and runs instantly. It scans for dependency cycles using Kahn's algorithm, for phases holding active items but carrying no gate, for load-bearing items with no gate, and for criteria that read as uncheckable. Run it as a quick structural gate before spending anything.
The agent panel, plan-review.workflow.js, is a budget-aware workflow that fans independent adversarial lenses over the plan text: a pre-mortem, a devils-advocate on the core decisions, a hidden-assumptions pass, and one advocate per declared fork, the fork advocates dropping out once fewer than 80,000 tokens remain in the budget. Each lens runs as the lean toolless judge worker, and a synthesizer worker then merges its findings with the deterministic ones, dedupes, and ranks them. It never edits the plan. The review advises and finn decides.
Flags and Notes
--narrate <file>injects agent-written per-phase and per-item prose into the map. With the flag off not a single token is spent, the render stays deterministic and the narration is an optional input rather than a step in the pipeline.--wikiemits the map as a page into a vitepress site when one exists underwiki/, wiring a "Plan Map" entry into the sidebar's Reference group idempotently, and degrades to the standalone single file when there is no site.--mermaidemits the markdown-and-mermaid form directly, which is what the wiki path uses. The standalone page stays library-free SVG.- Numbers are proposed, never written.
plan-alloc.nureports the next free plan number for each letter, and the next free item number inside one when you name it (--plan <id>), reading the filenames rather than the prose because the prose goes stale, and it fetches so it sees the remote too. The letters it allocates across come from the same project scheme file, so a bare call is enough on a project that declares its own;--lettersonly overrides that set for a single run, and--no-fetchskips the remote check to read whatever ref is already on disk. The skill prints splice-ready tracker rows and finn splices them, because concurrent edits toPLAN.mdare common here and an agent writing to it directly would collide.
Connects to
- Plan System, the plan files themselves, which this reads and writes.
- Diverge, used to spread candidate approaches for a fork before it locks, a soft dependency that degrades to plain alternatives when it is absent.
- Orchestration,
plan-review.workflow.jsruns its lenses and synthesis on the judge and synthesizer baked agent types, a hard dependency declared inmodule.json. - Skill-smith, the bar the plan skill is written to.
- Wiki, the site the map emits into when one is present.
See also harness/modules/planner/USAGE.md, the thin end-user doc this page fleshes out.