Skip to content

Plan System ​

Not code – the doctrine that decides where a piece of planning work gets written down and what its filename is allowed to say about its own state. PLANNING.md is the general framework, written once and shipped as a portable skill any project can install, and this repo's own planning/HARNESS.md fills in the local answers the framework deliberately leaves open: five category letters instead of the shipped two, the extra files the plan estate grew, and the two places this repo departs from the general rule outright – a harness task is itself a plan rather than a separate stage, and so, since 2026-08-19, is a standalone tool. Every other module in this repo was built off a plan filed this way, so the scheme is less a convention than the substrate the whole build history sits on.

In Practice ​

Ask which depth before writing one. A feature request is not automatically a request for a plan – finn asking for something built, now, gets a thin record after the fact, not a spec doc in front of it. plan/PLAN.X.M30.B.anti-slop-book--.md says so of itself in its own header: "this is a thin plan, a record not a spec pass. it exists so the decisions are written down somewhere findable, not so the build is designed up front."

Allocate a number instead of eyeballing the folder. Filenames are the truth for plan numbers, tracker prose goes stale, so the number comes from the script, which also checks the git remote so a number already taken on a branch you can't see still gets caught, and the letter set comes from the projects scheme file rather than a flag:

nu modules/frameworks/planning/scripts/plan-alloc.nu <harness root>

It only ever proposes a number, it never writes the file.

An extension gets a sub-plan, not a new top-level number. M17, the archiver, picked up two follow-ons after it shipped: retention (plan/PLAN.M17.A.retention.md) and retire (plan/PLAN.M17.B.retire.md), each its own file, each inheriting M17's letter forever, lettered A then B off a running sequence rather than taking M32 and M33. The relettering isn't only forward, either. plan/PLAN.I9.A.project-teardown.md started life as a stand-alone I20 and was re-filed as I9's sub-plan on 2026-09-02, once the two commands it covered folded into one, its own header calling the move "what I9's own file always said a change to it should be."

Closing is a rename plus a decision, not a checkbox. plan/PLAN.X.M18.A.project-scope--.md carries both markers on its filename even though its tracker row reads a clean 2/2: its own status banner explains why, "both items landed n are verified, the -- is for what could not be verified FROM HERE" – three PowerShell test suites the session that closed it had no Windows box to run. X says the plan is closed, -- says something's left behind, and they answer different questions, which is exactly what let this one carry both while every tracked item still shows done.

An example outcome. plan/PLAN.M31.idea.md sits as plain PLAN.M31.idea.md, no X, because its own header reads "STATUS, a SPEC, nothing built" – the file exists and is numbered before a line of code does, so a later session finds a real anchor with settled forks and acceptance criteria instead of a scattered design chat to re-derive.

Key Files ​

PLANNING.md ​

The doctrine – at harness/frameworks/PLANNING.md. The two plan depths (full vs thin, and when to ask rather than guess), what "closed" does and doesn't mean, the tracker-plus-plan-file split (PLAN.md carries nothing but the index, everything else lives in its own file under plan/), the done markers (X prefix, -- suffix, and why they stack rather than alternate), sub-plans and their lettered ids, item ids scoped per plan rather than counted globally, the default two category letters (F feature, P project) and the tiebreak between them, allocating a number through plan-alloc.nu, searching before planning something new, and how to present a plan once it's drafted.

planning/HARNESS.md ​

This repo's own answers – at harness/frameworks/planning/HARNESS.md, everything the general framework leaves to the project. The five-letter set this repo actually uses (M modules, I the installer/manager, H harness-wide, T tasks, U a standalone tool that does a harness job) in place of the shipped F/P default, a three-way tiebreak between a module, the manager, and the harness itself with the outermost layer winning while U sits outside that tiebreak entirely and is asked first, the reserved letters W P D already spoken for by live side-track item series (M18, H2, H3 respectively) which is why this repo never adopted the general F/P pair, the harness-only rule that a task is a plan filed straight on the T letter instead of a separate .claude/TASK-<name>.md, the extra files the plan estate grew beyond the tracker, and the plan/supplemental/ curated-list shortcut that stands in for an open web search.

The Estate ​

PLAN.md ​

The tracker and router – at the harness root, so it's the file read first and touched most. One line per plan under "the plans", a nested indent for each sub-plan, then a separate tracker section further down grouping items by plan with the status-marker legend and the ground rules. It carries the index and nothing else on purpose; a plan's body, its build notes, and its session log all live in the file that owns them instead.

plan/PLAN.<letter><n>.<name>.md ​

One plan per file – the pattern every plan doc follows, living in plan/ and linked from, never pasted into, PLAN.md. A sub-plan takes PLAN.<parent-id>.<sub-letter>.<name>.md, inheriting its parent's letter for good; plan/PLAN.M17.A.retention.md and plan/PLAN.M17.B.retire.md are both sub-plans of M17, plan/PLAN.X.M30.B.anti-slop-book--.md is a sub-plan of M30 sitting peer to M30.A, and plan/PLAN.I9.A.project-teardown.md is a sub-plan of I9, the uninstall/purge work.

plan/PLAN.detail.md ​

The execution spec – the per-item anchors behind the base numbered items, task, build notes, checkable done criteria, and an out-of-scope line pre-written so an executing agent builds instead of redesigning. Phases 0 to 2 are specced in depth because they were next when the doc was written; later phases carry gotchas and pointers only, specced properly at their own boundaries.

plan/PLAN.session-notes.md ​

The session log – append-only, and its ids were deliberately left un-relettered when the 2026-08-06 rename pass swept the rest of the estate, so a dated entry still names what a thing was called at the time; the mapping back to today's ids is context/notes/relettering-2026-08-06.md.

plan/MAYBES.md ​

The deferred pile – forks that were looked at, judged worth keeping, and consciously not taken yet, one ## header per plan. Nothing in it binds; an agent reads it to avoid re-deriving a fork already weighed and to notice when a deferral trigger has fired. A maybe only leaves the pile when finn says so.

The Tooling ​

plan-alloc.nu ​

Numbers, proposed never written – ships inside the planning skill and, in this repo, is called at its module path, modules/frameworks/planning/scripts/plan-alloc.nu. Prints the next free number per letter, and given --plan, the next free item number inside a named plan too. It reads filenames off disk as the source of truth and checks the git remote as well as the local folder, because the local folder is blind to whatever another branch already claimed, and every part of that remote check fails open if there's no git, no remote, or no network.

The letter set comes from the scheme, not a flag (H18, 2026-09-02). A bare call already knows this repo's five, because harness/.claude/planning/scheme.nuon declares them; --letters survives as a one-run override for the case no scan can answer, the very first plan on a letter nothing has claimed. The gap this page used to record here – that the disk scan was hardcoded to PLAN\.(?:X\.)?([AMIHT])(\d+) and so would never see a U-lettered plan – is closed. The scan is now a generic [A-Z], which is the deliberate half of the design: discovery is wider than the scheme on purpose, so a letter nobody declared is still found and still counted, and a wrong or missing scheme can only fail to offer you a letter rather than hand out a number a file already claims. That same hardcoded class was quietly worse than the U case implies – it meant the shipped F/P default matched nothing at all, so any project on the stock framework was handed an already-taken number every time.

--plan was dead for three weeks – from the 2026-08-13 move until 2026-09-02 it shelled parse-plan.nu from beside itself, and that file lives in the planner module, so every --plan call died File not found while the no-flag half kept working. It now reads the tracker rows directly with one regex, depending on nothing outside its own module.

scheme.nuon ​

The naming scheme, as a project's own setting – shipped from modules/frameworks/planning/scheme.nuon to .claude/planning/scheme.nuon, seeded own: true so a project's tuning survives every update, and editable through harness config --part planning. It names the filename stem, the allocatable letters, the reserved ones, the closed prefix, the leftover suffix, the plan dir and the tracker. Three scripts across two modules read it – plan-alloc.nu and plan-close.nu here, parse-plan.nu in the planner – and each one bakes the shipped scheme as a const and merges the file over it, so a missing, partial or malformed file all mean the default and none of them is an error. Because it is a project file, the planner reading it is the same class of act as reading PLAN.md; it creates no dependency edge between the two modules. This repo's own copy is two keys, the five letters and the reserved set, everything else being the shipped default.

tests/planning/check.nu ​

The drift gate – the cost of three independent readers is that they can drift apart, and they already had once: two were hardcoded to [AMIHT] while plan-close.nu had been fixed to [A-Z] and nobody carried it across. This sources each script, reads its real baked scheme rather than a copy written down in the test, and fails if any of them disagree. It then drives a fixture filed under a completely different stem, folder and tracker name (SPEC.A1.first.md under specs/ with a ROADMAP.md tracker) through all three, because three scripts agreeing on a default proves nothing about whether any of them reads the override. It was verified by deliberately breaking one script's baked stem and confirming the gate went red.

plan/supplemental/read-tags.nu ​

The search-before-you-plan shortcut – ranks the curated candidate lists in plan/supplemental/ against a handful of tags an agent invents for what it's building, so the framework's search-first rule starts from a small curated set rather than the open web. --dump 1 prints the top-scoring list's content straight into context so the agent doesn't have to open the file itself, --list shows every list with its tags. A query that scores nothing on every list falls through to a full search, or a by-hand look at the filenames in plan/supplemental/.

plan-close.nu and plan-close-hook.nu ​

The finished-but-open detector, and its Stop gate – plan-close.nu only ever reports. It scans PLAN.md's tracker rows plus every plan's own item rows (36 of this repo's 53 open plans at last count keep no items of their own and live entirely in the tracker) for a plan where every tracked item reads done or dropped but the file never took its X prefix; gate rows (- [x] G-...) count toward that check too, since an unmet gate should hold a plan open. plan-close-hook.nu wires it as a Stop hook, nu --stdin reading the payload off $in with a describe type check before trusting a single field, and it fires at most once per session off a session-keyed marker file, so it can't turn into the same five plans reported after every reply.

close-plan.md ​

The /close-plan command – the judgment call the detector can't make on its own. It works out which of the two markers apply, X alone when every item landed clean, X plus -- when something was deferred, dropped, or built but unverifiable from here; renames the file keeping the id and short name verbatim; writes the STATUS banner naming exactly what was left over when the plan takes --; fixes the tracker's link and any anchor pointer to the new filename while leaving dated session-log entries alone; and flags any still-open sub-plans in the reply rather than closing them as a side effect, since a parent closing while a child runs is legal but has to be a decision.

Closed Means Finished, Never Dropped ​

The one rule this scheme insists on getting right: to close a plan, a task, or an item is to mark it complete, the done state, the work happened. It never means drop it, abandon it, descope it, or decide it's not worth doing – those are real outcomes with their own markers, and none of them is "closed." frameworks/PLANNING.md states the failure mode directly: "an agent that reads 'close this plan' as 'get rid of this plan' has done the opposite of what was asked." If a plan should be dropped instead of finished, that's a call for finn, said out loud, not a reason to close it as a way of getting there.

filename shapemeans
PLAN.M17.A.retention.mdin flight, still being worked
PLAN.X.M20.planner.mdclosed, everything landed clean
PLAN.X.M18.A.project-scope--.mdclosed, something left over

The Category Letters ​

lettertakessource
Ffeature, a new capability, an improvement, a fixthe shipped default
Pproject, the layer above the product, its structure and conventionsthe shipped default
Mmodules, the plan builds or changes onethis repo
Ithe installer / managerthis repo
Hharness-wide, its structure, conventions, and estate behaviourthis repo
Ttasks, a feature request finn writes, filed straight as a plan herethis repo
Uutility, a standalone tool that does a harness jobthis repo

Reserved everywhere: X for the closed prefix, G for the gate series. This repo reserves three more on top, W, P, and D, already claimed by live side-track item series (M18, H2, H3), which is exactly why the harness never took up the general F/P pair – P was already spoken for.

U was carved out on 2026-08-19, split off from T rather than folded into it. The test for it is what a thing does, not its size or its language, so a one-file script that does the job of a dedicated tool takes U however small it is. It sits outside the module/manager/harness tiebreak entirely and gets asked first: does this ship a standalone tool, and only if the answer is no do the three layers get weighed. The boundary against M is that a module installs into a project while a U tool is standalone and serves the harness itself. Whether every U plan lands as a local module per LOCAL.md, or whether that's just the common case, is still open and parked in frameworks/BACKLOG.md, so an agent hits that fork asks finn rather than assuming either way. No plan has claimed U1 yet.

Connects to ​

  • Planner – reads and writes the exact tracker and plan files this scheme defines; /plan writes to the shape described here, /plan-map renders it, and neither exists without this doctrine settled first.
  • Skill-smith – the bar the plan skill and its command are built to, same as any skill in this repo.
  • Archiver – M17.A (retention) and M17.B (retire) are both sub-plans of M17, filed and lettered exactly per this scheme; both still carry status: live in their own frontmatter, open examples of the sub-plan convention in the live tracker rather than closed ones.
  • Installer – I9.A, the project-teardown work, is filed on the manager's own I letter and shows the sub-plan convention running the other direction: it started as a top-level I20 and was re-filed as a sub-plan once the work it covered turned out to belong under I9 rather than beside it.
  • Anti-slop – M30.B, the anti-slop reference book, is a live example of the thin-plan doctrine in action, filed as a record of decisions rather than a spec written up front.