agentleFS
TheodoreADTheodoreAD/agent-skills/skills/plan-conveyor/SKILL.md

plan-conveyor

Skill0 starsChanged 49 days agoMITView on GitHub

Use when capturing an idea, drafting a design, or tracking work-in-progress in a repo's plans/ directory — creating or updating a plans/YYYY-MM-DD-topic.md file (including a bug, idea or risk turned up incidentally), asking what plans exist or what to work on next, here or across every repo, advancing a status, retiring a landed/abandoned plan once its content has a permanent home elsewhere, consolidating a session's plans and loose notes into one plan without loss, migrating a legacy PLAN.md/DESIGN.md onto this convention, or auditing AGENTS.md/README.md/docs for planning/status/future-work content that has drifted in and belongs in plans/ instead. Also owns where a plan file may live and what may be written in it: a work, client or employer repo that cannot take a plans/ directory keeps its plans in the store outside every working tree ($PLANS_HOME); an idea with no repo yet is filed unscoped and graduated later; and no plan committed to a repo you publish may name a client, employer or internal project.

  • Commits and pushes

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 5 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Network: only push, and only to publish a plans store to the remote that store already has.

    line 61
  2. Very specific:

    Every command that reads takes --json, so nothing here has to be parsed out of its text output.

    line 151
  3. Very specific:

    Put each decision to the user with AskUserQuestion, using the suggest line as the recommended option and the cost line as the description.

    line 460
  4. Very specific:

    Only a collection name is split into its organisation.

    line 574
  5. Distinctive:

    warn: instead, because those have legitimate uses.

    line 677
  6. Very specific:

    The same mirror serves this repo when its own tree is busy: When a plan belongs to the repo you are in but another session is writing that …

    line 718
  7. Distinctive:

    No frontmatter marks these.

    line 725
  8. Distinctive:

    When it _is_ a merge, four rules, each derived at the point of needing it:

    line 896
  9. Distinctive:

    When content could plausibly belong to more than one repo, don't grep repos to decide, and don't guess:

    line 1042
  10. Distinctive:

    Never leave it as future-work prose in README.md, AGENTS.md, a docs page, or a code comment: those describe current state, and prose has no …

    line 1075
  11. Very specific:

    Five is the whole vocabulary: Don't add a sixth — inconsistently-applied tags are worse than none, because the greps still return results …

    line 1332
  12. Very specific:

    Not bare TODO/FIXME — those collide with code comments, making rg TODO useless in a repo that also contains source.

    line 1346

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Structured, stateful plan files

Convention for plans/YYYY-MM-DD-topic.md — one file per idea or design, a YAML frontmatter status field so its lifecycle is visible without opening it, and a firm rule that plans/ stays a working set, not a permanent archive.

Rationale, prior art, and worked examples: references/design-rationale.md. Whether an existing tool should have been adopted instead — the markdown task trackers, git-bug, beads, and why cross-repo is the case none of them solves cheaply — is references/prior-art-task-trackers.md.

What this skill reads, runs and writes

  • Reads: the session repo's plans/, both plans stores ($PLANS_HOME, default ~/plans, and its sensitive sibling), its own config ($PLAN_CONVEYOR_CONFIG, else ~/.config/plan-conveyor/config.toml on every OS — on Windows, the pre-2026-11-08 %APPDATA%\plan-conveyor\ while the new path is absent, with a notice naming the move), the directory names under projects_root (to derive the private terms scan gates on — names only, never contents), git history of the session repo and the stores, and, on Claude Code, the transcript path named by $CLAUDE_CODE_SESSION_ID to anchor the cross-repo guard. migrate ledger also reads that transcript's contents, or the one --transcript names: the user's messages and the paths of files the session edited, nothing else.
  • Runs: git — read commands everywhere. It commits through commit, rename --commit and migrate finish --delete-sources, each in the repository the named paths are already in — the store for a store-held plan, the session repo for a repo-held one, never any other repository. In a store only, it also commits a store's repos.toml link table: on a repository's first write into the store (new, new --for, move --to store, graduate), and through link --remote, link --to, link --new, link --move-to private, links fix --yes, links merge and links claim, which commit the plan files they move or rewrite with it. rename also runs git mv. git push runs only through push, only against a plans store, and only once the scan of that push's own outgoing commits comes back clean. The history-purge sequence in "Never let a client's identity reach a repo you publish" is printed for you to run; the script never runs it.
  • Writes: its own config, through install, config set, describe and uninstall only. Plan files in the session repo's plans/ and in both stores — new, migrate start, set-status, move, absorb --apply, graduate, and the retirement you perform by hand. The store directories and their READMEs, created 0700. Through attach: a copy of each file you name, either in a directory beside the plan or in the store's _attachments/, the plan's own ## Attachments rows, and one line in the store's .git/info/exclude. Each store's repos.toml, and — through links fix --yes — the repo: line of store-held plans. link --move-to private and links merge move a store folder's files, and its local attachments, to another folder or the other store. A conversation ledger per session under $XDG_STATE_HOME/plan-conveyor/ledgers/ (default ~/.local/state/… on every OS; the pre-2026-11-08 %LOCALAPPDATA%\plan-conveyor\ is used while it is the only copy), created 0700, through note and migrate ledger; migrate finish copies it beside the plan as a committed attachment and then removes that state copy, which is the one file it deletes outside a repository. Deletes files only through migrate finish --delete-sources, and only the ones it has just listed as deletable, in the session's own repository, after its coverage gate has passed — never on its own initiative and never without that flag. The only other removals are of directories left holding no file: the ones a move or merge empties, and those links fix --yes --prune-empty lists. Never a file in any other repo's working tree: new refuses and names --for, and migrate refuses a source outside this repository. archive, list, tags, refs, pending, migrate check, doctor, scan, where, bare link, links and links fix without --yes write nothing.
  • Network: only push, and only to publish a plans store to the remote that store already has. It never adds a remote, never pushes a repo, and refuses rather than publishing when the scan of its own outgoing commits finds a private name. Every other command is offline.

Run the script, don't re-derive it

scripts/plans.py (stdlib, read-only unless stated) owns every mechanical step below: which directory a plan goes in, creating it with correct frontmatter, the status index, the anchored tag greps, the promotion and deletion gates, inbound references. Run it instead of opening files to work the answer out — the file reads are the expensive part, and each command below is one of them.

Write the path out in full on every call. Shell variables do not survive between an agent's Bash calls — only the working directory does — so a P=… assignment is empty by the next command and every invocation below is the whole path:

python3 ~/.agents/skills/plan-conveyor/scripts/plans.py list

status: and updated: are set-status' output. They are never lines you type. This is a rule about those two lines, not about any particular transition — it holds for idea -> in-progress, for a bare updated: refresh, and for landed, the status that precedes deletion. Whatever else you are editing in the file, the frontmatter is changed by python3 <path> set-status <file> <status> and by nothing else, because that command is the only thing that runs the gate and the only thing that knows today's date.

Measured across two repos and two sessions, 2026-08-30 and 2026-09-01: four hand-edits, no gate run. Two idea -> in-progress, one updated: stamp that also dropped a depends_on:, and one idea -> landed whose plan was then retired — git rm and all — in the next three commits. Every one went through the file-editing tool. Neither session overrode a refusal; neither reached the code path that could refuse. Both had this skill in context at the time, which is why the sentence above is a rule about two lines rather than an argument that the gate matters.

[PITFALL: the bypass leaves no trace, and the result is indistinguishable from a correct promotion. The frontmatter is well-formed, list renders the new status, and nothing records whether the gate passed or was never consulted. In all four cases it would have passed — the tags had been resolved first — but that was sequencing, not process.]

Start here. These answer most sessions, and nothing below is needed until the lifecycle reaches it:

the questionthe command
first call of a session, in any repoabsorb — silent unless something is owed
what is open? what should I work on?list — see "Asking what is open"
where does a new plan go, and write itnew <topic>, or new … --for <repo>
write up a session, its notes and docs, as one planmigrate ledger, then migrate start <topic> --from <file>… — never a summary; see "Consolidating a session's plans"
record a decision, pitfall or question as it happensnote <kind> "<one line>" — the session's ledger, which migrate carries and gates
is this machine set up, and how?doctor
<details> <summary>The rest, by the moment you need them</summary>
# writing one down
python3 <path> where                        # which directories this repo reads and writes
python3 <path> repos --search <words>       # what each repo is for, to route a plan by
python3 <path> new <topic> --for <repo>     # something belonging to a repo you are not in
python3 <path> new <topic> --to store       # this repo's plan, kept out of a tree another session holds
python3 <path> commit <file>...             # commit these plans alone, subject read from the diff
python3 <path> pending                      # what is written but not committed, and what it would say
python3 <path> new <topic> --unscoped       # an idea with no repo yet
python3 <path> graduate <file> --to <repo>  # …once it has one

# working on it
python3 <path> set-status <file> planned    # refuses if the gate for that status fails
python3 <path> tags --tag DEFERRED          # anchored, across every plan this repo can see
python3 <path> move <file> --to store       # a repo switching where it keeps plans
python3 <path> rename <file> <new-topic>    # takes its attachments and citations with it
python3 <path> attach <plan> <file>...      # copy evidence somewhere stable, and record it
python3 <path> migrate start <topic> --from <file>...  # several documents into one plan, losslessly
python3 <path> migrate check <plan>         # what of each source the rewrite has not accounted for
python3 <path> migrate finish <plan>        # the gate, then which sources may be deleted

# retiring it, and getting it back
python3 <path> refs <file>                  # inbound references, before retiring
python3 <path> archive --search <words>     # a retired plan, back out of git history

# keeping the machine right
python3 <path> scan                         # no private name reaches a repo you publish
python3 <path> push                         # scan what the push would publish, then push the store
python3 <path> orgs                         # whose repo each directory is, from its own remote
python3 <path> link                         # which repository this clone is, and its store folder
python3 <path> links fix                    # move a store onto links, or repair them; --yes applies
python3 <path> install --explain            # set the machine up, one decision at a time
</details>

Every command that reads takes --json, so nothing here has to be parsed out of its text output.

The file argument is positional where a command requires one — set-status, move, refs, graduate — and --file where it narrows a default of every plan: tags, archive. Measured 2026-08-30: a session that had just run tags --file <name> --tag DEFERRED reached for the same shape on the next command, ran refs --file <name> for seven files in one loop, got unrecognized arguments: --file seven times, and re-ran the whole loop.

Where a plan file goes

A plan normally lives in the repo it describes. That is unavailable in most employer and client repos — a plans/ directory is not yours to add there — so there are three routes, and which one a repo uses is configuration, never a judgement call made per session:

routeplans live infor
repo<repo>/plans/, committed with the codea repo you own
store<the store for its tier>/<path under projects root>a repo that can't hold its own plans
bothreads both, writes onea repo mid-switch, in either direction

Which store folder holds a repository's plans is recorded, not derived from where a clone sits. Each store keeps a repos.toml linking a repository's identity (its origin remote as <host>/<owner>/<repo>, or local:<first commit> with no remote) to a folder. Every clone of the repository — parallel checkouts in wrapper directories, a second copy for tests — reads and writes that one folder. A repository with no link yet uses its clone path, <store>/<root>/<project>/<repo> at whatever depth it sits, and its first store write records the link. So folders keep path-shaped names, and the name is only a name. repo: in a store-held plan records the identity.

When a store write stops with a message about links, follow the message. Each one says what it found, why it matters, and the exact commands that resolve it, and ends with "Nothing was written" and a section of references/store-links.md with the background. Reading plans keeps working meanwhile. The four cases are: several remotes and no origin, a first push or renamed remote, a repository linked in both stores, and a clone under a private root reaching a folder in the shareable store. Put the choice to the user rather than picking one: each is a statement about which repository a clone is, or where its plans may be published.

A store written before links existed is moved onto them with links fix — a dry run that sorts everything into automatic, needs-a-decision and left-alone, then links fix --yes for the automatic group. doctor reports what it would do. Nothing moves unless a command says so.

From a git worktree the mirror is the repository's, not that checkout's — every worktree of a repo shares one mirror and one absorb queue, so a plan written on a feature branch is visible from main. A repo-routed plan is deliberately not redirected: that file travels with the branch it was committed on, which is already the right answer, so it stays in the worktree's own plans/. where prints a worktree: line when it applies, because rel then names a directory you are not standing in and unexplained that reads as a bug. Before this, both directions lost plans in silence: one written from a worktree landed where the main checkout never looks, and one filed for the repo landed where the worktree never looks.

First: which kind of machine is this?

device in the config, and it decides whether the store splits at all:

devicethe machine holdsthe store
contractor (default)several parties' work plus your own public repostwo repositories, split by sensitivity
workone organisation — an employer-issued or corp deviceone, with no tier at all

A work device has no boundary for a tier to draw, so the split would be an empty directory every command still reasons about. sensitive_store and shareable_roots stop applying, and install asks about neither.

Nothing there prints a tier, and that is the point rather than tidiness. "Sensitive" is a relative classification — it means "must not go where the other tier goes" — so on a machine with one store there is nothing for it to be relative to, and printing it stated a property of the material nobody had claimed. doctor, list, where and config name no tier on a work device, and --json reports tier: null rather than a word a reader would have to interpret.

It also has a default, which a contractor device deliberately does not. Everything on a corporate machine belongs to one organisation, and an organisation has its own work tracker — so an unmatched repo goes to the store, and the carve-out is the user's own repos, matched by own_accounts against the remote rather than by host. That is what makes it work on a GitHub Enterprise instance, where your repos and the employer's sit on the same hostname and only the account tells them apart. where names the fallback it used (work device default, or work device, your own account), so the answer is never silent. Setting default overrides it.

What does not relax is the remote check — but it asks a different question. Pushing an employer's internal work to a personal remote does not become acceptable because the machine holds one organisation's work, so the single store is the guarded one. What changed is that the check asks which remote rather than whether there is one: a destination you have recorded is silent, and anything else is reported.

python3 <path> config set sanctioned_remotes '["<host>/<owner>"]'   # where the store may push

An entry is <host>/<owner>, <host>/<owner>/<repo>, <host>/ for a whole instance, or a path beginning with / or ~ for a drive or a NAS — matched against the remote's parsed identity, so the ssh, scp-like and https spellings of one destination all answer the same. A bare account name is refused, in code: own_accounts matches a name on any host deliberately, which is what makes one entry cover github.com and an enterprise instance, and reusing that shape here is precisely the hole — it cannot tell your account on the corporate host from the same name on a public one, and only one of those is inside the boundary.

With the key unset, every remote on the guarded store is reported, as before; the message now carries the line that answers it, so it is a decision made once rather than a warning learned and skipped. The check reads a URL and nothing else — whether the repository you push to is private needs a network call this script does not make, so making it private stays your step.

[PITFALL: the default is contractor because the two mistakes cost differently. Guessing contractor on a single-employer machine costs an unused directory and a line of output. Guessing work on a machine that does hold several parties' work puts client plans in a store the user believes is safe to push. The default follows the failure that cannot leak, so a machine nobody configured is never the dangerous one.]

On a contractor device, the store is two repositories

tierholdsremote
shareable_unscoped/ and the roots in shareable_rootsallowed — usually private
sensitiveevery other root: employer and client worknone

Both are ordinary git repositories with full history, so retirement, archive and the commit-immediately rule work identically in either. Nothing about the plan format, the status vocabulary or the tags changes with the tier.

Both are created mode 0700 — a free default, not a protection to rely on. The tier decides what may leave the machine; the mode only narrows who on the machine can read it, and it is set because it costs nothing: a umask can only narrow a mode passed to mkdir, and Windows ignores the argument, so there is no branch and nothing to configure.

Nothing checks it afterwards, and that is deliberate. This corpus assumes a single-user machine, where there is no second person for the mode to protect against — and a check would have fired on every Windows run, where the concept does not exist, telling the reader to run a command they do not have. A store you move, restore from a backup or create by hand keeps whatever mode it arrives with; if you are on a shared machine and that matters to you, chmod 700 it yourself, because this skill will not notice either way.

You never pick a tier. A root's tier follows from shareable_roots (which defaults to public_roots), and every command resolves it for you — where prints it, new --for prints it and the exact git -C line to commit with, archive searches both. Read what the command tells you rather than deriving the path.

The split is structure, not the safety mechanism. The risk is a client's name inside any file, not a file inside a client's directory — an unscoped idea or a plan for a personal repo can easily name work that is not yours to disclose. So the shareable tier is gated on content, like any repo you publish:

python3 <path> scan --mode history --path <the shareable store>   # before the FIRST push
python3 <path> scan --mode staged  --path <the shareable store>   # before each commit after that

Both exit non-zero on a hit. The tier boundary is only what keeps the whole of a client root off a remote in the first place.

--mode tree is not the pre-push gate, and using it as one is the mistake to avoid. A push ships history, not the working tree, and the two diverge exactly where it matters: a plan that named a client, was reworded, and was committed again leaves a clean tree and a dirty history, and the push publishes the history. Confirmed 2026-08-29 while wiring this store's own remote — --mode tree was written into this section as the gate, and the first real push was the thing that showed it was the wrong question.

The first push is the one moment history mode is cheap to act on: nothing is published, so a hit is still an edit rather than a purge decision. After that, --mode staged on every commit is what keeps history clean going forward, and --mode history becomes the periodic audit rather than a gate.

If you do rewrite, the scan keeps failing until you drop refs/original/. --mode history reads git log --all -p, and git filter-branch leaves the pre-rewrite refs under refs/original/, which --all still walks — so a rewrite that worked reports exactly the hit count it started with, and reads as though it did nothing. Confirmed 2026-08-29 doing this store's first push. Check the branch itself before concluding anything, then drop the backup ref and let the old objects go:

git -C <store> log <branch> -p | grep -i <term>        # the real answer
git -C <store> update-ref -d refs/original/refs/heads/<branch>
git -C <store> reflog expire --expire=now --all && git -C <store> gc --prune=now

Take a copy of the whole directory first. It is the only copy of those plans, and a rewrite is the one operation in this convention that can lose them.

shareable_roots exists as its own key, defaulting to public_roots, because the two questions nearly always agree but are not the same: a root's name may be publishable while its plans are not, or the reverse. Leave it unset until they actually disagree.

[tiers] answers the same question for one clone — "<path under projects_root>" = "shareable" or "sensitive", longest prefix winning — for the clone its root's answer is wrong for: a public library cloned under a client root, a client repo cloned under your own. Set it only when a message names it, with config set tiers.<path> <tier>; declaring a private-root clone shareable is a statement that nothing private is ever written from it.

Moving a root between tiers moves no files. doctor reports a mirrored root sitting in the wrong store and names where it should go; relocating it is a git mv in two histories and a decision about what gets published, so it is never done automatically.

Whose repo is it? Ask the remote, not the directory

A directory name is where a clone was filed; its remote is who it belongs to, and only the second one stays true when a clone is moved. So [orgs] routes by <host>/<owner> read from the repo's own remote, and it is checked after [repos] and before [roots] — the full order is:

checkedkeymeans
1st[repos] exact paththis one repository
2nd[orgs] remote ownerevery clone belonging to that account or organisation
3rdlongest [roots] prefixevery repo filed under that directory
4thdefaultthe machine's answer for everything unmatched
5ththe device fallbackwork devices only, see above

[orgs] sits above [roots] because the two answer different questions and only one of them is about the repository. Where they disagree — one clone from somebody else's organisation sitting under a root routed repo — the remote is right and the directory is a coincidence.

A repo belonging to an organisation you have not decided about is refused a plans/ directory. Organisations keep their own trackers, so a plans/ directory committed into theirs is a convention nobody there agreed to, and the commit is visible inside that organisation the moment it is pushed. where exits 3 naming the org and the line that records the answer either way. Two things deliberately do not trigger it: a repo with no remote (local, so nobody could have agreed or objected — absence of evidence is not evidence), and a machine where own_accounts is unset, because with nothing to compare against every owner reads as foreign and the check would fire on every repo at once, which is how a check gets configured away rather than answered.

python3 <path> orgs            # every owner on this machine, its route, and who decided it
python3 <path> orgs --repos    # …with each organisation's clones listed

It exits 3 when a foreign organisation's repos are routed repo with nobody having said so, so it works as a check and not only as a listing. Like doctor and repos, its output names employers and clients: it is for deciding where plans go, never for pasting into a repo you publish.

where exiting 3 is a question, not a failure. It means no rule covers this repo, or it belongs to an organisation nobody has decided about. Ask the user which route it should use, then record the answer. Never pick a side silently: guessing "repo" writes a directory into someone else's repository, and guessing "store" hides the plan somewhere the user never named.

Record it with config set, never by editing the TOML yourself:

python3 <path> config set roots.<root-name> repo         # a whole root
python3 <path> config set repos.<root>/<repo> store      # one repo, beats any root rule
python3 <path> config set orgs.<host>/<owner> store      # every clone of theirs, beats a root rule
python3 <path> config set own_accounts '["<account>"]'   # the accounts that are yours
python3 <path> config set sanctioned_remotes '["<host>/<owner>"]'  # where the guarded store may push
python3 <path> config set default store                  # everything unmatched
python3 <path> config set view.idea_limit 20             # how many ideas a listing shows

Write an [orgs] key unquoted on the command line. The quotes are how it is spelled inside the TOML file, so copying one out of the config writes a key whose first character is " — well-formed TOML that matches no organisation ever. The script unwraps a quoted name rather than storing it, because that mistake is otherwise silent.

It preserves every comment in the file — those comments carry the reasoning for each key — replaces a commented-out example in place, and rejects a value the config's own schema will not accept, restoring the file rather than leaving it broken. A key's table is whatever precedes its first dot, so a repo path full of dots stays one key.

projects_root = "~/projects"
store = "~/plans" # the shareable tier
# sensitive_store = "~/plans-sensitive" # defaults to <store>-sensitive
default = "store" # omit it and an unmatched repo asks instead

public_roots = ["github.com-personal"] # names that may appear in a published repo
# shareable_roots = ["github.com-personal"] # the tier boundary; defaults to public_roots

own_accounts = ["your-account"] # unset = no repo's ownership is checked at all
# sanctioned_remotes = ["git.corp.example/your-account"] # where the guarded store may push

[roots]
"github.com-personal" = "repo" # longest matching prefix wins

[repos] # an exact repo entry beats any root entry
"github.com-acme/legacy-api" = { mode = "both", write = "store" }

[tiers] # one clone's store half, overriding its root's; longest prefix wins
"github.com-acme/vendored-lib" = "shareable"

[orgs] # by remote owner; beats [roots], loses to [repos]
"github.com/acme-corp" = "store"

Environment assumptions, and setting them up

$PLANS_HOME (default ~/plans) is the shareable store and $PLANS_SENSITIVE_HOME (default <store>-sensitive) the other half — pinning the first pins both, since the second derives from it; projects_root (default ~/projects) is the root the mirrored paths are relative to; $PLAN_CONVEYOR_CONFIG overrides the config location.

This skill was called plan-docs until 2026-09-27, and both halves of that name were derived from it: the config directory and the override variable. A config still at ~/.config/plan-docs/config.toml, or named only by $PLAN_DOCS_CONFIG, stops every command with the move to make, rather than being read or ignored. Ignoring it is the dangerous option: the writers lay down a skeleton over an absent config, so the next run would answer with an empty one and drop the [private] extra terms that scan cannot derive from directory names. Both were read, with a note, until 2026-09-28. The other two variables, $PLAN_CONVEYOR_SESSION_REPO and $PLAN_CONVEYOR_DEVICE, kept the old prefix until that day and still accept it, since neither guards a file.

The config is per-machine, not per-user, and is deliberately not version-controlled. It maps the repos that happen to be cloned on this box to routes, so it says nothing meaningful anywhere else — a second machine with a different set of clones needs a different file, not a copy of this one. Do not propose committing it to a repo or syncing it; losing it costs one install and one pass of config set, which is cheaper than maintaining a shared file that is wrong on every machine but one.

Setting up a machine is a walkthrough, and you run it. The script never prompts — it has to keep working when a human runs it by hand, and an interactive prompt inside an agent's Bash call hangs with nothing to type into. So the decisions are printed as data and you are the interactive surface:

  1. python3 <path> install --explain — what it would create, then one block per decision, each with what it is, what is currently set, what it would suggest, and what it costs to get wrong. Writes nothing.
  2. Put each decision to the user with AskUserQuestion, using the suggest line as the recommended option and the cost line as the description. Do not skip to the defaults: the default, own_accounts, public_roots and shareable_roots answers decide whether plans land in repos the user does not own, whether scan will catch a client's name, and which roots may reach a remote at all. own_accounts is the one to confirm rather than accept: the suggestion is built from the commonest remote owner on the machine, which on a corporate box is the employer — recording that answer would mark their organisation as the user's own and make every ownership check downstream pass silently.
  3. Record each answer with config set (above). Never edit the TOML by hand.
  4. python3 <path> install — idempotent: writes the config skeleton if there isn't one (never over an existing one), creates both stores as git repositories, adds neither a remote, creates the repo-less area.
  5. python3 <path> doctor — confirm it took, and that no problem is left.

It asks one question per unrouted root only when no default covers them; with a default set, that answer is already given and the walkthrough stays short.

python3 <path> uninstall reverses it: it removes the config but keeps both stores, because the store is the only copy of those plans; deleting them takes --purge-store --force and a deliberate decision, and the file count that triggers the refusal is taken across both tiers before either is touched.

What the projects tree has to look like

Repos are discovered by walking projects_root and stopping at each .git, so the walk assumes a shape. A collection directory is any directory on the path down to a repo — projects_root itself, each root under it, and each intermediate level of a <root>/<project>/<repo> hierarchy. Collection-ness is derived, never configured: a directory is one if it is not a repo and has repos beneath it.

  • projects_root must not be a git repository. This one is fatal and refuses rather than reporting: with a .git there the walk returns a single repo named ., every real repo becomes invisible, and scan derives almost no terms — a confidentiality gate that passes because it can no longer see anything.
  • A symlink is never followed. Git resolves symlinks, so a link to a repo inside the root enrolls the same repo twice under two paths, and a link to one outside is counted by discovery while where refuses it. Plan in the repo at its real path.
  • A bare repository is neither a repo nor a collection, and is reported as such rather than walked into.
  • A linked worktree is not a second repo. It is enrolled nowhere and doctor names the checkout it belongs to. Without that, one repo was listed as three, routed to three separate store mirrors, and its branch name entered the private term list — and branch names are ordinary words (feat, main, docs), which is how a scan becomes noisy enough to switch off. Both sibling layouts do this: VS Code's default <repo>.worktrees/<name> and the flat <repo>-<branch>. A submodule looks the same from outside — both put a .git file where a checkout has a directory — and stays a repo, because only a worktree's names worktrees in it.
  • A directory holding no repos is simply ignored — doctor counts them and --strict lists them.
  • A repo cloned straight into projects_root is routed with [repos], never [roots]. A [roots] key is a path prefix, and a repo at depth 1 has no prefix, so an entry naming it is never consulted and the repo falls through to default — which doctor reports through inert_root_rules if you write one anyway. A git repository is never a candidate root, so neither doctor nor install --explain ever asks you to categorise one: on a flat ~/projects/<repo> layout, the more common one in the wild, every clone would otherwise be listed as an undecided root, which is one warning per repo on the machine. default answers all of them, and a repo that genuinely needs its own answer takes a [repos] entry when a plan is first written there.

Categorise every root explicitly, even where default would give the same answer. Then a root falling through to default means exactly "this appeared since you last decided anything", and doctor lists it as awaiting a decision — no seen-markers, no registry, just the config read as a record of what has been answered. "Root" there means a directory holding repos, so a machine whose projects root holds only repos has nothing to categorise and doctor says nothing about it. Without that pass, a newly cloned root is routed silently, which is right for a client root and quietly wrong for a personal one: its plans would accumulate in the store mirror forever, because a store-routed repo's mirror is its home and absorb correctly does nothing.

Is this machine set up, and what is in it

python3 <path> doctor

One call for the whole picture: config location, every store with its git state and whether its remote was sanctioned, which roots are enrolled, by which rule and into which tier, which repos actually hold plans, a tally by status and open tag, and a problems list — a store that is not a git repository or has lost its git identity, an unsanctioned remote on the guarded store, a mirrored root filed in the wrong tier, an unset PLANS_HOME, a repo holding plans that no rule routes, an organisation that is not yours whose repos are routed repo, and a foreign organisation's clone filed under a shareable root, whose store plans would land in the tier that may have a remote. Run it when something behaves oddly and before trusting archive, which retrieves nothing from a store with no git history.

It aggregates by root and names an individual repo only when that repo holds plans — a per-repo listing is one row per clone on the machine, which is a roster of employers and clients. Its output is for setting the machine up, never for pasting into a repo you publish.

The guarded store's remote rule is the design, not an oversight — the sensitive tier on a contractor device, the only store on a work device. doctor reports a remote there unless sanctioned_remotes covers it: local history is the benefit, and one personal remote accumulating several clients' internal architecture is the outcome to avoid. Recording a destination is a decision against that employer's actual policy, never a convenience, and until one is recorded treat that store as unbacked-up. Never symlink either store, or a subtree of it, into a work repo — that puts the content back inside the tree repo-scoped agent reads walk.

Never let a client's identity reach a repo you publish

The store exists because work repos can't hold plans. The mirror image of that is the rule that matters more: a plan committed to a repo you publish must not name the client, employer, project or repo it came from. Not the org, not the internal project name, not the work email address, not the ticket prefix. A plan about work for someone else can still be written — describe the shape ("a work root with a <project>/<repo> hierarchy", "a client repo under review pressure") and keep the specifics in the store, where they belong.

Run python3 <path> scan before committing to any repo that is or might become public, and --mode staged immediately before the commit itself. It exits non-zero on a hit. The terms come from the machine — every root, project and repo name under projects_root that is not under a public_roots entry, each root name also split into its organisation (so the client behind <org>.com-<host>-<team> is caught in an @<org>.com address too), plus [private] extra — so a newly cloned client is covered with nothing to maintain, and the list itself never has to be written into a public repo.

[private] extra is not optional decoration: an employer with no repo on this machine has no directory to derive from, and is invisible to the scan until someone adds it.

Only a collection name is split into its organisation. A directory under projects_root that is itself a repository contributes its whole name and nothing else — splitting it is how ordinary words enter the term list, and a gate that flags "repo" in every document is a gate that gets switched off.

Never hand-roll the pattern for an audit. scan --list-terms prints the list the scanner derives; scan --mode history is the audit. A regex written by hand is a narrower list whose edges you cannot see, and it will look like a clean result. Confirmed live 2026-08-29: a repo was surveyed with a hand-written alternation covering the addresses already known about, declared clean apart from those, purged — and the scanner then found an employer's name in that repo's first two commits from 2021, in four branches, because the hand-written pattern omitted one work root the derived list had all along.

Failure modes to handle correctly:

  • A generic hit. A work repo named tools or settings matches ordinary English. Put that one name in the config's [private] ignore list — never widen public_roots, which silences a whole organisation's worth of names to fix one word.
  • Writing about a hit reintroduces it. A plan explaining what leaked, a rationale page using a real name as an example, a commit message quoting the offending line — each puts the term straight back into the tree the scan just cleared. Measured three times in one session, 2026-08-29, each caught by --mode staged before the commit. Reference the thing by where it lives — the commits and the scan --mode history command that print it — not by quoting it.
  • A hit in pushed history. --mode history scans every commit. Redacting the working tree does not remove anything from a published repo; purging history means a force-push and a support request, and it is the user's call, not an edit to make quietly. Report it, name the commits, stop.
  • A path the scan could not read. --mode tree enumerates with git ls-files, and a nested checkout — a linked worktree under .claude/worktrees/, a submodule — comes back as one directory entry rather than as its files. Those paths are listed under the hit count and are not covered by it; each is a repository of its own, scanned by pointing --path at it. --mode staged and --mode history read git's own output and are unaffected, which is the reason the pre-commit rule above calls staged rather than tree.

Confirmed live 2026-08-28: this repo had already published a plan whose measurement table listed six employer/client root directory names, plus one client's internal <project>/<repo> path — written by an agent with no rule telling it not to, into a repo whose own README advertises it as public.

Pushing a store: push, not git push

python3 <path> push             # scan the outgoing commits, then push
python3 <path> push --dry-run   # scan and report, publish nothing

It scans the range the push would publish — not the working tree. A push ships commits, so a plan that named a client and was reworded afterwards leaves a clean tree behind a dirty history, and that is precisely what --mode tree cannot see. On a branch with no upstream the whole history is outgoing, so the first push scans --all.

It publishes the commit it scanned, not whatever HEAD has become. The tip is read once and pushed by SHA, so a commit another session lands mid-push stays local for the next push, which scans it; the output says when that happened. Until 2026-09-28 a bare git push ran after the scan, so such a commit went out unscanned.

It lists every outgoing commit before pushing, so a commit you did not make is on screen before it is published rather than found in git log afterwards. A failed push prints git's own error.

Another session's commit is named, never a reason to stop or ask. A store is a shared log that every session commits into and pushes wholesale, and its commits are scanned like yours, so the home instructions' "ask before your push publishes a commit you did not make" does not apply to a store push. Mention the foreign commits in your report so the user knows what went out. Decided by the user 2026-09-28, after asking per commit was weighed as friction with nothing to protect.

On a hit it refuses and publishes nothing, naming the lines. A push cannot be taken back by a later edit: the content stays in the history, and a repo's history is as readable as its tip.

Measured 2026-09-22: 101 pushes to a plans store, 32 of them (32%) with no scan anywhere in the eight calls before. The rule had been stated in the store's own README, which is read once at install time and never again at the moment it applies. This is a command rather than a git hook on purpose — an agent should know what to run, not be corrected behind its back by something it cannot see.

It pushes only a store, only to a remote that store already has, and it never adds one. A store with no remote is reported as nothing to push, which is the documented and permanent state of the sensitive tier rather than a problem to fix.

Something that belongs to a repo you are not in

Work that belongs to another repo is filed as a plan for that repo, not performed — a plan file least of all, but the rule is about the work, not about the file type. Parallel sessions on one machine share that tree, so anything appearing there under a session already working in it is the failure this rule exists to prevent, and a commit across repos is one nobody in that repo asked for.

The rule being stated about plan files is how sessions walk past it. A session reads it, uses --for correctly, concludes it has complied, and then edits that repo's source anyway — because the thing being written was not a plan. Confirmed live 2026-08-29: a session did exactly that within the hour, proposing as its recommended option to edit two files in another repo and run that repo's deploy task. An edit is arguably the worse case: a stray plan file is inert and obvious, while an edit to a file that repo's session is holding is a real conflict.

The escape hatch is narrow, and worth quoting rather than paraphrasing — it is "unless it's a very complex process that requires a lot of back and forth to fix". That is not "unless it is small": a one-line fragment edit is exactly the case that feels too small to file and is not. It is about a change that cannot be described faster than it can be done jointly, and that one wants its own session in the owning repo rather than a relay.

Reading another repo stays fine, and is how a filed plan gets written accurately enough to act on. The prohibition is on writing.

For plan files the script enforces it rather than trusting anyone to remember: new refuses to create a plan in a repo other than the one the session is in, and names --for in the error. Commands that act on files which already exist — graduate, and anything reached by --path — warn instead, because those have legitimate uses; when you see that warning, prefer doing the work from a session inside that repo, and if you continue, tell the user exactly what landed where.

The guard is anchored to the repo the session started in, not to the working directory, because cwd is unreliable in both directions — a reset and a persisted cd were both observed inside one session, 2026-08-29. A guard comparing cwd against cwd cannot fire when cwd drifts, since both sides move together; an anchor gives the comparison two independent sides.

Three tiers, most trustworthy first. Nothing here is Claude-only except tier 2, and no tier is required for the skill to work:

tiersignalwhen it applies
1$PLAN_CONVEYOR_SESSION_REPOany harness, if it exports it
2$CLAUDE_CODE_SESSION_ID → the session's transcript pathClaude Code, no setup needed
3cwdfallback; cannot detect drift

On a harness that is not Claude Code, export PLAN_CONVEYOR_SESSION_REPO at session start — export PLAN_CONVEYOR_SESSION_REPO="$(git rev-parse --show-toplevel)" — and the guard is exactly as strong as it is under Claude Code. Without it everything still works; the guard just degrades to tier 3 and stops catching a drifted directory. doctor reports which tier is in use and lists the fallback as a problem, so nobody is in the weak tier without being told.

Two habits that hold at every tier:

  • Read the repo: line every create prints. It names the repo the plan just became the property of, derived from where the file was written rather than from any comparison, so it is true regardless of what cwd or the anchor did.
  • Never cd into another repo without asking the user first, and after any cross-repo command treat cwd as unknown until a call re-establishes it. The anchor makes a stray cd survivable, not free — everything else in a session still runs relative to cwd.
python3 <path> new <topic> --for github.com-personal/<repo>   # or an absolute path

It writes into that repo's store mirror, outside every working tree, whatever that repo's route says. Nothing in the target changes. The session working there sees it — list at repo scope reads the store mirror regardless of route — and absorbs it on its own schedule with move <file> --to repo, committing only to its own repo.

The same mirror serves this repo when its own tree is busy. When a plan belongs to the repo you are in but another session is writing that working tree, new <topic> --to store puts it in this repo's store mirror instead, and absorb offers it here later. --for on your own repo is refused, and --unscoped is the wrong fallback: the unscoped area is where absorb never looks. Confirmed 2026-09-13: a plan filed unscoped for that reason sat unoffered for three hours, until a harvest noticed new takes --to and moved it.

No frontmatter marks these. For a repo that keeps its own plans, a file in its store mirror is in transit by definition; for a repo routed to the store, the same file is at its permanent home. Route plus location already says it, so there is nothing to set and nothing to drift.

If the store has uncommitted changes, add a new plan rather than editing an existing one, and reference the plan it relates to. Another session may be holding that file; a new file cannot conflict, while an edit to a held file is the one loss that is not recoverable. Check with git -C <store> status --porcelain — against the store this write targets, which the create command names for you. Checking the other tier answers a question about a different repository.

The check works because both tiers are real git repositories. That is why the sensitive roots are a second repository rather than entries in the shareable one's .gitignore: verified 2026-08-29, a write to a gitignored path does not appear in git status --porcelain at all, so this check would report clean about the tier it cannot see — worse than having no check, because the answer is trusted.

Commit a store plan the moment it is written, never at the end of a session. Every minute the store is dirty is a minute another session must fall back to adding a file it would rather have edited, so the rule above and this one are the same rule from two ends: the fallback is cheap because dirty windows are short, and dirty windows are short because nobody sits on an uncommitted plan. new produces an empty skeleton, so the moment to commit is after the content is written, not at creation.

python3 <path> commit <the plan> -m "<repo>: <what it is>"

Use the command rather than git add && git commit, because the store is one working tree with one index and every session on the machine writes to it. commit builds the commit from HEAD plus the files you name, through a private index, so a parallel session's staged work can neither ride along under your message nor be disturbed by your commit. Measured 2026-08-29, before it existed: a git add was swept into another session's commit twice in one sitting, each time reporting nothing added to commit — which reads exactly like the add failed, when in fact it had succeeded and someone else's commit had already taken it. The content was never wrong; the message described a different change than the diff it carried, and git log -- <path> was the only way to find out where the file actually landed.

Doing it by hand was the single most repeated shape on this machine — 142 calls across 23 sessions, measured 2026-09-01 — which is what earned it a command rather than a longer sentence.

Name every file of one logical change in one call; an absorption is one commit, not N. The command took a single file until 2026-09-09, and four sessions met the cost: two reasoned their way to git -C <store> commit -- <dir> — correctly, since a pathspec commit does not ship the index — one paid it as two commits with two messages for one absorption, and one hit the plural at seven, after five sessions in three repos had filed into the same queue. Each deviation was stated in full in its own commit message, so this is evidence about the wording rather than about those sessions: a rule that gives a mechanism can be argued around by anyone who accepts the mechanism. Naming several paths is that same private index with a loop, so there is nothing left to argue with.

-m is required once you name more than one, because the generated message names a single plan's topic and no default describes a set. There is deliberately no whole-directory form: a directory argument makes it easy to sweep a file this session never touched, and the store has held another session's staged deletions in a second mirror at exactly the moment one of these commits was made — a <dir> argument was correct there by one directory level, and nothing in the command would have said so.

If a path you name has vanished, the command says whether absorb took it. A store plan you edited can be absorbed by another session between your edit and your commit, and the commit then carries a pure deletion under a message announcing an addition. Confirmed 2026-09-04, following the already-owned rule in session-harvest step 2: 76 deletions, 0 insertions, and eight minutes of reading the target repo to establish the content had survived — which it had, absorbed whole. The note names the destination and the commit that added it, and it prints only when a destination actually resolves, so an ordinary retirement is not told its plan was absorbed.

[PITFALL: Edit catches this a step earlier and Write does not, which is the tool rather than the convention. An Edit against an absorbed path fails loudly with File does not exist; a Write to that same path recreates the file, and the commit then records a resurrection under a message written for an append — a plan back in the store that a session already took, which absorb will offer again. Confirmed 2026-09-05, from the harmless side: a session extending a plan it had filed earlier in the run found the store path gone and learned it from Edit. So reach for Edit when adding to a store plan somebody else may be absorbing, and read a failure as news rather than as something to route around with Write.]

Pushing is a separate, gated step, and only the shareable tier has anywhere to push to. Scan before pushing and push only on a clean result — --mode staged on the commit you are about to make, and --mode history before the store's very first push, since that is what a push actually ships and the last moment a hit is an edit rather than a purge decision. The tier boundary keeps whole client roots off the remote, but a client's name inside a personal repo's plan or an unscoped idea is exactly what it cannot catch. The sensitive tier has no remote, so there is nothing to push.

Absorbing what was filed for this repo

On your first plan-conveyor call in a session, run absorb before anything else:

python3 <path> absorb            # report only — silent when nothing is waiting and nothing is owed
python3 <path> absorb --apply    # move them into this repo's plans/

[PITFALL: in a repo whose plans live in the store, there is nothing for absorb to absorb, and the call is still the right first one. The mirror is that repo's permanent home, so nothing is ever in transit — but this is the one command that carries the retirement prompt, and a store-held plan goes terminal like any other. On a machine where every repo is store-routed, which is the normal shape of a corporate one, that prompt is the whole of what it ever prints. The command is named for the other case; read a silent run as "nothing is owed here", not as a command that did not apply.]

It is silent when the store holds nothing for this repo and nothing is owed retirement, so it costs nothing on the sessions where it does not apply. When it does print filed plans, put the set to the user with AskUserQuestion before applying — one question for the set, not one per plan — then apply, run the repo's quality gate, and commit twice: this repo for the additions, the store for the removals. --apply prints the store's commit with its paths filled in; run it with your message rather than assembling the paths, and note that commit resolves a path where it points and never by basename — a store-relative path committed an absorption's removal as an empty commit in the wrong repo until 2026-09-13. Then carry on with whatever the session was for.

Once per session, not once per command. The script is stateless and cannot tell a first call from a fifth; you can, so the rule lives here. list also prints a one-line footer when plans are waiting, for a session that skipped the proposal.

Committing to both repositories here is not the cross-repo commit this section forbids. You are the session working in this repo: the additions go to your own tree, and the store only loses the file you just took. What is forbidden is writing into a tree that is not yours — and absorb --apply enforces exactly that, refusing when the target is not the repo your session belongs to. Reporting for another repo (absorb --path <other>, no --apply) is a harmless question and stays allowed.

A name collision is a merge, not a rename. absorb refuses when a filed plan's name already exists in plans/, exits non-zero, and destroys neither copy — two plans sharing a name means both cover the topic, and that is the moment to combine them by hand.

Absorption is where a dirty-store split gets reconciled — and absorb can only tell you a reference exists, never why. When a harvest found the store dirty it added a new plan referencing an existing one rather than editing a file another session might have been holding; those two halves want merging. But the common case for one plan citing another is simply that they are related, and several say so outright — "filed alongside it", "this is a new concern rather than an addition to that one", "not re-raised here". So absorb prints references … beside each pair and the judgement is yours: read both, then merge only when they are two halves of one topic.

Measured across two absorptions, 2026-08-29 and 2026-08-30: seven of twelve pairings were deliberate separations. The failure is asymmetric, which is why the report states no cause — a missed genuine split costs one duplicated topic that someone notices later, while a wrongly-merged pair destroys a separation someone reasoned about in writing, and the reasoning goes with it. Nothing re-surfaces a genuine pair after absorption, because the pairing lives in prose, so a real split skipped here is one nobody is reminded of again.

Read the incoming titles as a set, and ask whether any two are one subject — because name equality is the only collision anything detects, and two plans on the same subject with different names are invisible to all of it. That is the shape that actually occurs here: parallel sessions pick their own descriptive filenames, so the ordinary act of naming a plan well defeats the check.

Confirmed 2026-09-03, and the pair is a good one because neither plan was wrong. One was filed into the store about what a skill declares regarding its config and mutations; the other was committed in the target repo within hours, by a parallel session, about where a skill may put things at all — XDG config versus data versus state, and the two store env vars. They compose rather than duplicate, and the dependency runs one way: a disclosure names locations, so its format cannot be settled before the locations are. A session absorbing the first without the second would have designed the disclosure format against locations that were about to change. absorb reported neither fact, because the two did not cite each other — neither author knew the other existed.

[PITFALL: the collision is least visible exactly when it is most likely. Two sessions converge on one subject because the user raised it with both, in the same period — which is also when neither can see the other's filename, since the other plan may not exist yet at filing time. The mechanism that would catch it (citation) needs knowledge the authors cannot have, and the mechanism that does run (name equality) is defeated by choosing a descriptive filename.]

[DECISION: a prompt to think, not a detector. Settled 2026-09-09, after weighing both. Filename word overlap is crude — the 2026-09-03 pair shares only "skills". Frontmatter is no help: neither carried a topic field, and adding one is a new thing to maintain and get wrong. A weak detector that is trusted is worse than a prompt to think, because it converts "I should look" into "the tool would have told me" — and this section's whole argument is already that a wrongly-merged pair destroys a separation someone reasoned about in writing. The same reasoning refuses putting the check on the filing session instead: it only helps when the other plan already exists, and these two were hours apart, so it would have caught one direction and not the other.]

The same gap exists inside one repo's own plans/ — nothing stops two sessions opening two plans on one subject there either, and list groups by status rather than by topic, so a reader scanning it sees them apart. Only the store case has been observed; the in-repo case is the same mechanism with no store involved, and the same prompt covers it whenever you are reading the list as a list.

When it is a merge, four rules, each derived at the point of needing it:

  • Keep the name that describes the merged subject, not one case of it. "The earlier filename" is undefined when both plans share a date, which is the common case.
  • A correction is merged in place, not appended — otherwise the wrong argument stands above the right one and the reader has to arbitrate.
  • Name the merged-away file in the surviving plan, or archive cannot find it: the deleted plan is in git, and that line is the only thing pointing at the name to search for.
  • A cluster member already implemented is marked done, not carried, so the merge does not queue edits that already exist.

A cited filename that resolves to no actual file is not a pair — plans legitimately reference retired and foreign plans in prose, and only a name matching a real file on either side counts.

Absorption applies only to a repo that keeps its own plans. For a repo routed to the store, the mirror is the permanent home and nothing is ever in transit.

The retirement prompt absorb also carries

plans/ is defined as a working set that empties out, and until 2026-09-02 nothing ever asked anyone to empty it. The convention was never missing the mechanism — a five-step procedure, a deletion gate, an inbound-reference check, archive to read a retired plan back — it was missing a trigger. Measured 2026-08-29, machine-wide: nine terminal plans across five repos, two of them reaching that status the same day, so the backlog grew faster than it drained while list's footer printed throughout. One of the nine was not merely unretired but stalled mid-procedure.

So absorb says it, in two groups that are two different requests:

  • STALLED mid-retirement — the plan carries a ## Migrated to section, so step 4 is done and steps 5–6 never ran. Cheapest to finish and likeliest to be lost, since nothing else distinguishes it from a plan nobody has started. Raised whatever its age. Finish these first.
  • awaiting retirement — terminal for RETIREMENT_PROMPT_AFTER_DAYS (3) or more, oldest first, at most five rows before the rest collapse to a count.

Put it to the user as one question, with the cost in it, and make "not now" a real answer. Retirement is a judgement procedure, not a command: triage the content by lifecycle, find a home for the rationale, write ## Migrated to, fix inbound references, delete. So the prompt is an offer to spend a chunk of the current session on something the user did not come here for. "Retiring these two will take most of a session" is a different question from "shall I tidy up?", and only the first one can be answered honestly. A stalled plan is minutes, and asking about it in the same breath as an unstarted one loses that.

Three settled choices, each of which was an open question:

  • The throttle is age, and age is chosen because it needs no state. A marker file recording what was asked and when would be a second lifecycle store with no retirement of its own — the objection this convention already makes to parking anything outside plans/. Three days rather than one so a plan landed on a Friday does not nag on the Saturday. The throttle is about nagging, not readiness — it governs when a plan is raised for somebody else to pick up, and says nothing about the session that landed it, which retires it the same day per the rule above.
  • Three surfaces, three distinct triggers, no split ownership. absorb speaks for the aged backlog at the top of a session. session-harvest already reports plans this session made terminal, under "decisions waiting" — and it has to, because absorb runs before this session has landed anything. list keeps its passive one-line footer for a session already reading plan state. Each answers a question the other two cannot see.
  • The prompt trusts nothing but the status field it reads, and that is a known limit. A plan whose status was hand-edited past the gate looks identical here — which is why "status: and updated: are set-status' output" is a rule at the top of this file rather than a note.

This does not propose retiring a backlog that already exists. That is real work needing real sessions and should be scheduled deliberately; folding it into the change that adds the prompt would make the prompt's first run its worst.

Plans that belong to no repo yet

An idea, task or exploration that has not earned a repo goes to $PLANS_HOME/_unscoped/:

python3 <path> new <topic> --unscoped     # works anywhere, including outside any git repo
python3 <path> list --scope unscoped      # the repo-less backlog on its own
python3 <path> graduate <file> --to <path inside the new repo>

graduate routes the file through the destination repo's own rule — into its committed plans/, or into that repo's store directory — and stamps the repo: frontmatter when the destination is the store. Do it the moment the repo appears, not later: an unscoped plan whose work has moved into a repo is a plan nobody will find again.

Asking what is open

Answer "what plans do we have" and "what should I work on" with one list call, not by opening plan files. The scope is chosen for you:

python3 <path> list                       # auto: this repo when in one, the machine when not
python3 <path> list --scope family        # every repo, always
python3 <path> list --stale 14            # only what nobody has touched in a fortnight
python3 <path> list --since 2026-08-01    # only what moved on or after a date
python3 <path> list --tag DEFERRED        # only plans carrying that open tag
python3 <path> list --all                 # include landed, abandoned and superseded
python3 <path> list --limit 0             # every idea, uncapped

--scope auto is the default and resolves to repo inside a routed repo, family outside any repo and inside the store itself — so a session that has cd'd nowhere in particular gets the machine-wide answer without asking for it.

Repo scope reads the repo's plans/, its store mirror, and the unscoped area, whatever the route says. A route decides where a write lands; letting it decide what a read can see is what kept unscoped plans invisible from every repo on a machine whose roots are all mode = "repo" (confirmed 2026-08-29) — the plans with no other route back to attention were the ones nothing surfaced.

--stale and --since are opposite questions and treat an unstamped plan oppositely: --stale keeps it (nothing says it was touched), --since drops it (nothing says it moved). Neither bounds the default output — the cap below does that, because a date window's size is not predictable.

Output is bounded, and only the idea tier is capped. in-progress, blocked and planned are limited by how much work can actually be in flight; idea grows forever, so it is the only group whose cost is unbounded. The cap is [view] idea_limit (default 10), --limit overrides per call, and the footer always says how many rows were elided. Never read a capped listing as the whole set — if you are about to conclude something about every plan, pass --limit 0 first.

One thing only --scope family reports, because no per-repo command can see it: depends_on as a blocked-by view, summarised as counts. The plans themselves print under --scope repo in the repo being waited on, as "waiting on this repo" — that is where the wait is actionable, and printing every edge machine-wide is a section that grows with the corpus exactly the way the idea tier does (measured 2026-08-29: 22 of 81 lines).

Status drift prints at every scope, and a drifted status is not what it looks like. A status outside the vocabulary — done where landed is defined, or a free-form paragraph where an enum belongs — renders as its own group heading, so at repo scope it reads as a deliberate blocked on … rather than as a mistake. Family scope is still the only view that catches drift in a repo nobody is working in, and it found the first two instances (2026-08-29) and two more (2026-09-02) — but it is the wrong only place to report it, because writing into another repo is out, so every finding had to be filed as a plan and wait for the one session that would never be shown it. Nothing about the check needs the family: the vocabulary is a fixed enum, so one repo has everything required.

[PITFALL: a drift that reads as a synonym hides more than one that reads as prose. A paragraph where an enum belongs is obviously wrong to any reader. done is a single plausible word that renders as a tidy heading — and it is the more consequential of the two, because it quietly asserts the plan is finished while landed, the vocabulary's real terminal status, is gated: set-status landed refused that same plan on an open UNVERIFIED tag the moment it was asked. The synonym did not merely mislabel the state, it routed around the check. Drift is therefore read off the unfiltered set — a landed by hand is grouped as terminal and would otherwise be dropped from the rows before the check ever saw it.]

A terminal-status plan is hidden from the rows but never silently. plans/ is a working set that empties out, so a landed plan still sitting in one is a retirement owed; the footer counts them and --all shows them. That count is often the most useful line in the output.

Like repos, family output names work repos: use it to decide what to work on, never paste it into a repo you publish.

Which repo does a plan belong to?

When content could plausibly belong to more than one repo, don't grep repos to decide, and don't guess:

python3 <path> repos --search "<the words the plan is about>"

It prints every repo under the projects root with its route and a one-line description — the config's [about] entry, else that repo's README first line — ranked by the search words. Take the top two or three and put them to the user as AskUserQuestion options with those descriptions as the option text: an informed guess to confirm, not an open question. Record a better description with python3 <path> describe <repo> "<what belongs there>" whenever a README's own line turns out to be a poor answer. That listing names work repos, so it is for choosing a destination — never paste it into a repo you publish.

Creating a plan

python3 <path> new <topic> — kebab-case topic, one file per topic. It writes YYYY-MM-DD-topic.md in the route's write directory with the frontmatter already correct:

---
status: idea
updated: YYYY-MM-DD
repo: <origin URL> # store-held plans only — location no longer names the repo
---

Body: ## Context → ## Open questions (each unresolved point marked with an inline [NEEDS CLARIFICATION: ...] tag) → ## Recommended direction (rough, non-prescriptive).

This applies to anything turned up incidentally, not only to deliberate design requests. A bug worth fixing later, an idea worth brainstorming, a risk worth mitigating — each gets its own file. Never leave it as future-work prose in README.md, AGENTS.md, a docs page, or a code comment: those describe current state, and prose has no status field, so nothing ever prompts anyone back. (Confirmed live 2026-08-23: a known test-coverage gap sat in a README.md as "a real gap… not yet fixed" instead of a plan file, invisible to anything scanning plans/ for open work.)

Committing a plan file

Run the repo's quality gate before every plans/*.md commit — create, update, or retirement. "Just markdown" is not an exemption: formatters reflow prose, and doc-only commits that skipped the gate are the single most common cause of red CI in repos using this convention.

A store-held plan is committed to the store's git repository instead, and no work repo's gate applies to it. Commit it there anyway, in the same session that wrote it: the store's history is the only record that plan has, and an uncommitted file in a directory nobody browses is the same as no plan at all.

The message has two halves, and the script owns one of them

Don't write the subject. commit reads it from what git is about to record.

python3 <path> commit <file>...                  # the subject is derived
python3 <path> commit <file>... --body "<body>"  # …with your commit body under it
python3 <path> commit <file>... -m "<whole msg>" # override both, for the case neither covers

--body is a commit body: what the change is for, what it beat, what it cost. Write what you would have written after -m, minus the subject line, which is the part already derived.

[DECISION: called --why until 2026-09-22, and the rename is the fix its own documentation kept describing. Three separate prompts had to explain that "why" meant a commit body rather than a clause — a name arguing with its help text, and the explanation is the tell. --body sits beside --message so the pair reads as commit anatomy, and it matches gh pr create --body, which is the spelling already used for this on this machine. Not --commit-body: the subcommand is commit, so the prefix would restate its own context.]

What belongs inside the quotes, for a plan that settled where plans go when a repo cannot hold one:

Settles where a plan goes when the repo it is about cannot hold one. Seven of the eight roots here are employer or client work, so the planning happens and then evaporates with the session.

Recorded as a parallel path rather than a rework: the per-repo plans/ stays exactly as it is and nothing migrates. It beat a single global store, which would have put several parties' plans in one directory with no tier boundary, and it costs a routing config nobody had to maintain before.

Blank lines inside the one argument are real paragraph breaks, so the whole shape of a commit body is available. One paragraph of substance is the floor, and three is plenty even where the change had alternatives worth naming.

[PITFALL: the floor is not a quota, and padding is worse than a short answer. A formatting fix's why is one clause and should stay one clause — filler reads as reasoning, which misleads a later reader more than a bare subject would. That is also why nothing here measures the length of a --body and why no length gate should ever be added: it would enforce form, and the only way to satisfy it is the padding this warns against.]

what the diff iswhat it commits as
a new plan<repo>: <the plan's own # title>
the store side of an absorption<repo>: absorbed into <repo>, removed from store
a deletion after ## Migrated to<repo>: retire <topic>, migrated to <where>
a status transition<repo>: <topic> is now <status>
tags opened or closed<repo>: <topic> opens 2 DECISION
a new ## section<repo>: <topic> adds <heading>

A topic is named once however many store mirrors the commit touches, and a heading loses a leading "Added 2026-09-26:" stamp, since the subject already says adds and the commit carries its date. There is deliberately no length cap: a retirement's subject is often long, and refusing it would break the one flow documented to need no message.

--body is the body, always and only — it goes under the derived subject and never replaces it. So there is one thing to write and never a question of how to format it.

--body is expected wherever this commit is the plan's permanent record — which is everywhere except a plan in transit. Measured 2026-09-22 across the 1,639 commits that have ever touched a plan file in this family, classified by what the diff did and by what each plan's route says:

the commit is…commitscarried a body
a repo's own plans/1,18097%
an unscoped plan in the store, until it graduates1070%
a store-held plan for a repo routed to the store0no evidence
a plan in transit, awaiting absorb into its repo44921%

[PITFALL: "is it in the store" is the wrong question, and it is the one this corpus asked first. A store holds two populations with opposite needs. A repo that cannot take a plans/ directory at all keeps its plans there permanently — there is no later repo commit, so the store's history is the only record those plans will ever have, and their commits deserve a reason more than a repo's do, not less. The 22% a store-versus-repo split reports is almost entirely the transit half: unscoped plans, whose only record is also the store, sit at 70% with a median body of 1,146 characters and behave like repo-held plans. The permanently-store-held population had no commits at all on the machine measured, so exempting stores would have been generalising from a population of zero — and exempting exactly the plans whose reasoning is least recoverable.]

So the exemption is narrow and it is about permanence. A plan filed with --for against a repo that keeps its own plans is staging: absorb will move it, and the repo-side commit is where the reasoning belongs. Everything else stops and asks, handing you the subject it read so you write only the half it cannot. -m commits without a body — and it is deliberately the more expensive thing to type, because an opt-out cheaper than compliance is the opt-out everyone takes.

Two independent gates decide this, and each flag has exactly one meaning. --body is a body; -m is the whole message, taken verbatim. Neither ever stands in for the other:

the diffthe commitwhat you pass
a subject can be reada plan in transitnothing
a subject can be readits own permanent record--body — the body
no subject can be readeither-m — the whole thing

A subject can be read for every transition in the table above. It cannot for a mixed set, for several plans whose statuses or edits differ, or for a content edit that opened and closed no tag and added no section — a change that is only prose. That last case is 9% of this corpus's plan commits, so it is a path you will meet, not a corner.

[DECISION: --body does not rescue the unreadable case, though an earlier version let it. It became the subject there, on the reasoning that the reason is then the only thing anyone can say. The cost was that --body and -m produced the same commit apart from the <label>: prefix, on one commit in eleven — two flags converging on one behaviour, with the meaning of one of them depending on the diff. So the command now offers the only thing it still knows, which is the label, and hands it over in the refusal rather than applying it to your -m. Nothing rewrites what you typed.]

"In transit" means the plan sits in the store mirror of a repo whose own route writes to repo, so absorb has it ahead of it. A commit naming several plans is exempt only if every one of them is in transit; otherwise the permanent one would have its reason decided by argument order.

[PITFALL: rename --commit and migrate finish --delete-sources commit through neither gate. They build their own subject from an operation they performed themselves and carry no body, which is the deliberate shape for "just the rename" — but it does mean a rename of a repo-held plan records no reason. Where the rename needs one, run rename without --commit and commit it yourself.]

Measured 2026-09-22 across this machine's transcripts: of 403 plans.py commit calls, 369 passed a hand-written -m — because the old default was the filename stem, a date-prefixed slug that described nothing — and a third of those messages were the diff read back in words: 97 said some form of "absorbed", 17 "filed", 10 named a status the frontmatter already carried.

[PITFALL: an absorption is an addition in one repo and a deletion in the other, and a hand-written message routinely describes the wrong one. Confirmed 2026-09-04: a commit carried 76 deletions and 0 insertions under a message announcing an addition, and establishing that the content had survived took eight minutes. A derived subject reads HEAD in the repo the path is actually in, so it cannot make that mistake — which is the single strongest reason to stop writing these by hand.]

Two cases still refuse, and both name what they saw. A set whose paths are doing different things has no one honest sentence; a content edit whose diff is only prose has no fact to read, so the refusal lists the transitions it found and asks for --body. Neither is a nudge to reach for -m and retype the facts.

Don't ask git what is uncommitted — ask pending

python3 <path> pending        # every plan git disagrees with, and the subject each would land under

It names the file, its state, the repo it belongs to, and what commit would say about it, plus any unpushed commits. commit prints the same two facts on the way out, so neither side of the call needs a git status. Measured 2026-09-22: 83 git status and 30 git log @{u}..HEAD calls naming a plan or a store sat within two Bash calls of a plans.py commit, every one of them re-deriving state the script was already holding.

[PITFALL: a plan filed with --for lives in a mirror this session deliberately cannot see, so pending does not list it — that is the isolation working, not a gap. commit still reports what is left beside anything it just committed, which is where that plan turns up.]

Renaming a plan

rename, never git mv. A plan's filename is not only its own name — three other things are keyed on the stem, and none of them is visible from the file you are moving:

python3 <path> rename <file> <new-topic>                 # the date prefix is kept
python3 <path> rename <file> <new-topic> --update-refs   # …and repoint every file citing it
python3 <path> rename <file> <new-topic> --commit        # …and commit just the rename
what moves with itwhere it lives
committed attachmentsa directory beside the plan, named for the stem
local attachments<store>/_attachments/<repo>/<stem>/
plans citing it by filenamethis repo and the store dirs it reads

The second is the one that makes this a command rather than advice: git never sees the local attachments area, so a hand-rolled rename orphans it silently — the plan's own ## Attachments rows go on naming files that are no longer where the rows say, and nothing checks.

Citations are reported, and rewritten only with --update-refs. A filename substitution is right for a link and wrong for a sentence: a reference that quoted a section title still points at the old wording, and some hits are prose about the plan rather than a pointer to it. Same judgement the retirement procedure asks for, and the same reason it is not automatic there either.

commit reads a rename as one change rather than a mixed set, so plans.py commit <new-name> works afterwards without -m — it compares the removed path's blob in HEAD against the added path's bytes. An edit made in the same breath as the rename does not match and stays a mixed set, which is honest: that is two changes, and no one sentence covers both.

Attaching evidence to a plan

A plan citing a log in Downloads, a scratch directory, or the transcript its own source_session names is citing something that stops existing — the transcript on a timer, the others the next time anyone tidies up. attach copies the file somewhere stable and writes a row into the plan saying what it took:

python3 <path> attach <plan> <file>...           # size decides where each one goes
python3 <path> attach <plan> <file>... --commit  # evidence someone will read
python3 <path> attach <plan> <file>... --local   # bulk output, or something that must stay exact

Two destinations, and only you can judge the axis that matters. A file at or under [attachments] commit_limit_kb (1024 by default) is copied into a directory beside the plan, named for it, and committed with it; anything larger goes to the store's _attachments/ area, which git never sees. Size is the half a script can judge, so it picks the default — the flags are for the other half:

the filewhere it belongs
another agent's investigation, a screenshotcommitted
a multi-megabyte log, a data dumplocal
anything that has to stay byte-exactlocal

[PITFALL: a committed attachment is an ordinary file in that repository and goes through its gate. dprint reflows markdown, so an investigation report committed as .md stops being byte-exact the first time the gate runs — silently, because the gate rewrites it and passes. Use --local when the exact wording is the evidence.]

A local attachment is the only copy of that file, and attach says so every time it writes one. It is in no git history, so archive cannot bring it back, and on a contractor device it sits in the tier that deliberately has no remote. The plan's row carries a sha256 so a later reader can tell it from a different file of the same name; whether to keep the original as well is your call.

A row never names where the file came from. Independence from an ephemeral path is the whole point of copying it, and a source path can carry a client directory or an account name into a repo you publish. Say in prose what the file is and what it shows; the row carries name, size and digest.

scan sees a committed attachment like any tracked file and cannot see a local one. That asymmetry is deliberate rather than a gap — the local half never leaves the machine.

Attachments travel with their plan. absorb, move and graduate carry the directory, and commit <plan> takes the plan and its attachments as one commit. A directory already sitting where they would land blocks the move exactly as a name collision does: two things claiming one name is a merge, not a rename.

At retirement the committed half is deleted with the plan and stays reachable in the history archive reads. The local half is named by refs and left alone — deleting it is the one irreversible step in a procedure built to be reversible, so it is a decision to put to the user.

Tags

Five inline markers, all [SHOUTY-WORD: text], so the judgment calls below become greps instead of re-reads, and nothing costly is lost when a file is deleted.

tagmeansat retirement
[NEEDS CLARIFICATION: …]open questionblocks planned and landed
[DECISION: …]settled choice + why it beat the alternatives→ design rationale
[PITFALL: …]non-obvious trap, confirmed by hitting it→ design rationale
[DEFERRED: …]consciously scoped out, still wanted→ an open plan; blocks deletion
[UNVERIFIED: …]designed or implemented but not actually proven→ verify or defer; blocks landed

Five is the whole vocabulary. Don't add a sixth — inconsistently-applied tags are worse than none, because the greps still return results and get trusted while being incomplete. There is deliberately no [VERIFIED:]; the absence of [UNVERIFIED: is the signal.

set-status enforces the two tag columns above, and it gates on the status you are moving to, not on the one you are leaving. in-progress is deliberately ungated: starting work with questions open is the normal case, and blocked on <reason> exists for when it is not. landed gates on both UNVERIFIED and NEEDS CLARIFICATION, because it is the status that precedes deletion and idea -> landed skips planned entirely. That last clause is a fix, not a description: until 2026-09-02 the question gate hung off planned alone, so the one transition ending in a one-way door was the one nothing checked, and a plan carrying two open questions went straight to landed printing nothing but its status line. DEFERRED blocking deletion is still prose in the retirement procedure rather than a gate — see step 2 there.

Not bare TODO/FIXME — those collide with code comments, making rg TODO useless in a repo that also contains source.

Tag the claim, not the section. One tag per discrete, individually-extractable fact. A tag scoped to "everything below this heading" can't be migrated mechanically, which is the whole point.

A tag opens its own line, starting a paragraph or immediately following a list marker. Searches for it must be anchored the same way — a bare rg '\[DEFERRED:' matches every prose mention of a tag, so any document discussing this convention reports a false backlog. plans.py tags is the anchoring, applied across every directory the repo's route reads:

python3 <path> tags --tag DEFERRED               # the whole backlog, no file opened
python3 <path> tags --file <file>.md             # one plan, all five tags

Tag at status transitions, not while drafting — those are the moments someone is already reading closely. Retrofit an existing corpus in one pass rather than lazily; half-tagged is the failure mode above.

Promoting a plan

Promote in place, in the same file — never split into a second file for the same topic. Resolve every NEEDS CLARIFICATION first, then python3 <path> set-status <file> planned — it runs that gate and refuses while any remain, so a refusal is the answer, not an obstacle to route around with --force. Rewrite the body as ## Context → ## Design (numbered subsections, one per file/component touched, rationale inline) → ## Files touched → ## Verification.

As work proceeds, bump status again with the same command (it also stamps updated) — never by editing the frontmatter, per "status: and updated: are set-status' output" above, which is where the measurement lives. The sections don't change:

  • in-progress — actively being built.
  • blocked on <reason> — stalled on something external, with the reason in the status line itself, e.g. blocked on the upstream API adding a /search endpoint.
  • landed — implemented and verified. Transient; see "Retiring a plan".
  • abandoned — killed before landing. Also transient.
  • superseded by plans/<file>.md — a landed plan whose decision was later reversed by another.

Optional depends_on: [<repo-name>, ...] frontmatter names sibling repos this plan can't fully land without. Omit it for the ordinary single-repo case.

Plans that arrive from another repo

new --for writes four more fields and an ## Evidence section — the inbound mirror of depends_on, for the case where the plan is read in one repo and the thing that produced it happened in another:

source_repo: <the repo you were in> # filled in for you, from where the session was
source_session: 8f3c….jsonl # filled in under Claude Code; elsewhere, the transcript's filename
source_moment: 2026-08-22T16:50:15Z # plus a distinctive quoted phrase in the body
source_plan: plans/2026-08-22-why-this.md # the filing repo's plan that owns this decision

The point is that a triage session can re-read the original turns instead of trusting a summary. Record a timestamp and a quoted phrase — either alone can miss in a multi-megabyte transcript — and note that a cited transcript only survives while the harness keeps it (30 days by default), so a capture worth acting on is worth acting on soon.

source_plan answers a different question from the other three: they point at the evidence, it points at whoever still owns the decision. Fill it in when the plan proposes something, and leave it blank when the plan reports a fact — a blank is a real answer and means there is nobody to check with. A filed plan is a snapshot, and the filing repo can change its mind after it has been absorbed. Confirmed 2026-09-04: a repo filed a placement decision on its own reasoning, the user overturned it there the same day, and the absorbing session implemented the superseded version faithfully, wrote the beaten argument into a shipped docstring and a contributing/ page, retired the plan and pushed. Nobody made a mistake — the filing session recorded the correction where it belonged and could not write into the other repo, and the absorbing session implemented exactly what it was handed. What was missing was a named place to look.

So: when a plan you are absorbing proposes rather than reports, read its source_plan before implementing. absorb prints these under decision owned elsewhere so the prompt arrives at the moment of use. A named plan that no longer exists is not a dead end — the filing repo retires plans by deleting them, and plans.py archive --file <name> reads one back out of its own retirement commit.

[DECISION: one field and one prompt, deliberately, with no watcher and no staleness scan. Settled 2026-09-09. The corpus of filed plans is small and this failure needed a same-day reversal by the user of a decision the filing session had itself proposed — rare, and it cost about an hour to recover, so a mechanism firing on every filed plan would be a poor trade. What was missing was never that looking is expensive, only that nobody knew there was somewhere to look. It fails safe in both directions: an absent field, an unfilled one and a retired target all read as "no further information", which is exactly the state before this existed.]

A plan carrying source_repo is not done until its ## Verification names the original repro, checked in the repo where it happened and after the fix is installed there. A fix verified only where it was written has not been tested against the case that produced it.

[PITFALL: the template asks because judgement does not. Filling these in is the whole value and it is exactly what gets skipped. Measured twice: 2026-08-23, a session captured this kind of friction unprompted and correctly, then paraphrased the incident instead of citing it — by an agent that had every reason to do better. 2026-09-01, the session reading the plan that describes that failure filed a cross-repo plan and paraphrased it too. Two for two, which is why the fields are emitted as blanks in the file rather than described in a skill someone might not open.]

[PITFALL: in a background job the job id is not the session id, and only the transcript's id is a source_session. Confirmed 2026-09-27: a job session typed the id from its task-output paths into two plans, and it named no transcript. So new --for now fills the field itself when Claude Code exports $CLAUDE_CODE_SESSION_ID and a transcript by that name exists; on any other harness it is still yours to type, and the filename under the harness's transcript directory is the value.]

Where retired content goes

Three destinations, named by role rather than by path, because every repo lays them out differently — and a repo may have no separate directory for the middle two at all:

rolewhat belongs there
the code itselfchanges needing no explanation beyond the code and its comments
usage docsanything about how a person or agent uses the result
design rationalesettled decisions, rejected alternatives, confirmed pitfalls

Map these onto whatever the repo has — a docs/ tree, a contributing/ tree, a package's own references/, a section of AGENTS.md, a code comment. The requirement is somewhere durable and findable, never a specific directory name. If a repo has no obvious home for design rationale, picking one is part of the first retirement, not a reason to skip it.

Retiring a plan

On reaching landed, abandoned, or an old superseded by ...: plans/ is a working set that empties out — but nothing genuinely costly to work out gets silently dropped. Deleting the file takes it off the working set, not out of the repository: the drafting commits, its final state and the ## Migrated to commit all stay reachable through git, and python3 <path> archive is how they are read back — see "Getting a retired plan back" below. That is what makes the deletion cheap, and it is why a plan is only ever kept in version control.

The session that lands a plan retires it, in the same session, once the change is pushed. Not after a wait, and not left for whoever comes next: that session has already read the code and the destination doc, which are the two expensive halves of a retirement, and a session three days later re-derives both from nothing. The gate is pushed, not landed — retirement deletes the file, so retiring an unpushed change deletes the reason for something that is not in the product (see the PITFALL at step 3 below). Everything absorb's prompt does is therefore an exception handler for plans that slipped past this rule, rather than the normal path.

Settled 2026-09-06 against a measured backlog: sixteen terminal plans had accumulated in agent-skills, fifteen of them landed on one day, and draining them took four batches in one session. What that pass established, and what makes the same-day rule worth stating as a rule:

  • A plan whose rules already shipped still owes its rejected alternatives. Almost every conclusion had already become a sentence in a SKILL.md, often better worded than the plan. What had no home was uniformly the option not taken and the measurement that killed it. So retirement is mostly a search for what was decided against, and the landing session is the one that still remembers.
  • Batch by destination, not by age, when a backlog does form: the expensive half is establishing what the destination file already covers, and one read serves four to six plans. Confirm the destination by reading rather than by what the plan talks about — a plan discusses the tool it found the problem in while concluding about the tool that has to change.
  • The most valuable rationale section is usually the one that existed in no single plan. Four plans retired together turned out to be one finding wearing four faces, which is only visible when they are read as a set.

A repo that keeps its own plans retires them in its own history — absorb first, then retire. set-status refuses a terminal status on a plan still sitting in the store mirror of a repo-routed repo, and names absorb. The reason is that retirement deletes the file and archive reads it back out of the deletion commit: retiring from the store would put the drafting, the landing and the deletion in the store's history while the repo's history has nothing, so archive run inside that repo would find the plan missing. One plan, one history. Non-terminal statuses are unaffected — nothing has been deleted, so nothing is split.

A store-held plan retires exactly like a repo-held one, and is deleted the same way. This is about a repo whose plans live in the store permanently, not one whose plan is merely in transit. The usage docs and design rationale still go into the repo the plan is about — updating a repo's own docs is an ordinary contribution, available even where adding a plans/ directory is not, and it would be owed just the same if the planning had happened in a tracker instead. What is left after that migration is reasoning that belongs to nobody but you, and it stays in the store's git history, which is why the store is a git repository at all.

Triage the file's content by lifecycle first. Split by what each passage is, never by how long the file is: a long file that is all one lifecycle stays one file, while a short one mixing several gets split.

kindexampledestination
settled decisionwhy tool X beat tool Y, with the evidencedesign rationale
pitfalla trap confirmed by hitting itdesign rationale
code contractsignatures, flags, behavioralready in code/tests/README — drop
verification log"ran it, it worked", dry-run transcriptsdrop, except the unverified residue
live open workanything still wanted but not donean open plan — see step 2

Code contracts and verification logs are usually the bulk of the deletable volume.

  1. Default: preserve. Assume debugging, investigation and rejected-alternative reasoning has future value unless it is already written down elsewhere. Often it is — check the existing docs before assuming new rationale content is needed.
    • In a repo family, check the sibling repo that owns the concern, not just this one. A plan that designed something later extracted elsewhere describes a decision that repo now owns and keeps current; migrating it here ships a second, diverging copy that reads as authoritative. Point at the owning repo instead, and migrate only what it genuinely doesn't cover.
  2. A plan carrying live unfinished work is not deletable. Run the deletion gate and move everything it finds into a plan that stays, before going further:
    python3 <path> tags --file <file>.md --tag DEFERRED
    python3 <path> tags --file <file>.md --tag UNVERIFIED
    Prefer appending to an existing open plan that already owns the concern over spawning a new file. On an untagged legacy plan, grep prose instead (deferred|not yet|follow-up|TODO|known limitation) and read what it finds.
  3. Find inbound references before starting, not after — python3 <path> refs <file>.md, which also warns if the repo has unpushed commits, and names the attachments the plan holds. The count decides whether this is one commit or several. The committed attachments go with the plan; the local ones are the one thing here that deletion cannot undo, so they are the user's call, not a step in the procedure.

    [PITFALL: landed does not mean published, and retirement deletes the file. set-status gates landed on open tags and on nothing about whether the work reached the remote — so a plan can be landed and retired while the change it explains sits in a local commit. The change is then not in the product and the reason for it has been deleted. Push first, or keep the plan until you have. This is reported at retirement rather than gated at landed on purpose: a gate would be unpassable for a repo with no remote — the sensitive store is deliberately one, permanently — so it would only teach people to force past it, and a repo with no upstream is therefore not warned about at all.] It searches the whole repo (code comments and docstrings cite plan paths too) plus the store, on the bare filename rather than the full plans/ path, since short-form references are the easy miss, and including files you have not committed yet — the successor plan written during a retirement is untracked at the moment refs runs, which is the normal shape of a retirement rather than an edge case. Confirmed 2026-09-02: before that, refs reported zero while two files written the same hour named the plan.

    Then grep for section-shaped citations, which refs cannot see — rg -n '§' over plans/ and whatever docs directories the repo has. A sentence citing "that plan's §9 decision" names no filename, so nothing in the deletion gate reaches it, and a link checker does not either: a bare §11 is not a link. Confirmed 2026-08-30 retiring two plans: refs found 9 real hits across seven files and missed two more, both written by earlier sessions that had the plan open and cited its sections the way a reader in context would. Both dangled at deletion, and both were found only because that session ran the grep on a hunch. A plan organised into numbered sections is precisely the one whose citations will be section-shaped.

    Expect most of the output to be noise, and expect the ratio to get worse as a repo grows. Measured twice: 17 lines of which 2 were real on one repo, 2026-08-30; 45 lines of which 0 were real on a second repo, 2026-09-02, retiring six plans across two runs. The difference is not luck — on the second repo 24 of the 45 were one reference document's own internal §N numbering, which is a permanent noise floor that grows with the corpus and never contains a finding. So read the output, but read it expecting nothing; the grep earns its place because a real hit is silent and unrecoverable, not because it is often right. That is also why this stays a documented grep rather than a refs flag — at 0 real hits in 45, a flag would be reporting its own noise, and refs answers "who links to this file", which is well defined and is what the deletion gate needs.

  4. Add a ## Migrated to section naming each destination, and name what you deliberately did not migrate and why. Commit this addition on its own, before deleting the file — add-and-delete in one commit means the section is never recorded in history at all, which defeats the point of writing it.
    • Organize the rationale home by the question a reader arrives with, not one file per retired plan — that just reproduces each plan's lifecycle mixing under a new name. Expect the most valuable file to be one that existed in no single plan.
    • Before dropping anything as "already in the code", check that it is. Verify what you migrate too: prose written months ago about a module drifts, and a plan is not evidence about current behavior.
  5. Fix the references from step 3, then delete the file — only once step 4 is genuinely covered. If there is any doubt whether something worth keeping was captured, ask before deleting; it is a one-way door once the commit lands.
    • commit takes the deletion too, and is still the right way to make it: the store's index is shared whether the change is an addition or a removal.

      python3 <path> commit <the plan that is now gone>

      No message needed: step 4 put ## Migrated to in HEAD, so the derived subject is <repo>: retire <topic>, migrated to <where it went>. Pass the path, not a bare filename — nothing can search for a file that no longer exists. It works whether the deletion is staged (git rm) or the file was simply removed, and git rm also prunes the directory it just emptied, which is ordinary for a store mirror holding one last plan. Retiring several at once is one call and one message, same as an absorption.

    • Don't blindly swap the old path for the new one at every hit. A reference to a specific quoted section title needs that title updated to match where the content actually landed — a valid path aimed at a renamed heading still dangles. Some cited content is already duplicated at a third location; point at that copy rather than migrating a second one. And some references are better rewritten than repointed: "X landed in <plan>" just becomes "X landed."
    • The finishing grep should return no live pointers, which is not the same as zero hits. Provenance legitimately survives ("extracted from the now-retired plans/X.md") and should — but must say retired, so a reader knows not to go looking.
  6. Run the repo's gate again before committing the reference fixes. Editing many comments/docstrings in one pass is exactly what quietly trips a line-length rule.

Getting a retired plan back

Deleting a plan is only cheap because the file is still in the repository, and that is only true in practice if getting one back is a single command rather than an archaeology session:

python3 <path> archive                      # every plan deleted from this repo's plans/, newest first
python3 <path> archive --search "<phrase>"  # only the ones whose content ever contained it
python3 <path> archive --show <file>        # print one back, as it stood the moment before deletion
python3 <path> archive --file <file>        # one plan's whole lifecycle: drafting, landing, retirement
python3 <path> archive --all                # every repo on the machine, plus both stores' histories

Each row carries the plan's final status and its ## Migrated to destinations, which are usually the real answer — the content is in a doc somewhere, and only the reasoning that had no home is in the deleted file itself. Nothing is written and no file is restored: a retired plan comes back on stdout, and if the work is live again it earns a new plan file rather than a resurrected one.

Three things worth knowing before trusting a result:

  • --search matches across line breaks, so a phrase the formatter has since reflowed is still found. It also searches every version of every retired plan, not just the final one — so a passage cut two commits before the deletion still matches, and --show will not contain it. Use --file to find the commit that did, and read that one with git show <sha>:<path>.
  • A plan that moved between the repo and the store is not retired, though its old location's history says it was deleted. Those rows say still live and name where it is; go read that file.
  • A store with no git repository archives nothing. archive says so in its header when it finds one, per tier. Fix it with python3 <path> install before retiring anything held there. Both tiers keep full history precisely so this stays true for client plans, which are the ones with no other copy.

Consolidating a session's plans and loose documents into one

Use migrate, and do not consolidate by summarising. A session ends with a plan file, two scratch documents and a body of reasoning that reached neither. Asked to pull that together, an agent summarises — and a summary is lossy in a way nothing detects, because the output reads as finished either way. Reported by this user 2026-09-22 after hitting it twice in one day.

python3 <path> note <kind> "<one line>"                 # during the work: decision, pitfall, risk, question, …
python3 <path> migrate ledger                           # at the end: every heading, and the user's words verbatim
# …fill every empty section of the ledger it names
python3 <path> migrate start <topic> --from <file>...   # the plan, with the ledger and every source carried in
# …move the content into the sections, then delete the carried block
python3 <path> migrate check <plan>                     # what of the ledger and each source is still unaccounted for
python3 <path> migrate finish <plan>                    # the gate, the ledger attached, then which sources may go

start carries every source into the new plan verbatim, under a delimited block, and writes migrated_from: into the frontmatter. Then you move its content into the sections out of that block and delete it. That is deliberately a different act from recalling what the sources said: editing content that is in front of you can drop a paragraph on purpose, and recalling content you read earlier can lose one without anyone knowing it existed.

The conversation is a source too, and start refuses without it. What the session argued out is the one input with no other copy, so it goes into a ledger, one file per session, and the ledger is carried, gated and kept like the documents are. Reported by this user 2026-09-29 on three harnesses: consolidations that kept the files and lost both the depth and the conversation.

  • note <kind> "<text>" as things happen, not only at the end. A long session's early turns may already be compacted by then. The kinds are decision, pitfall, risk, question, deferred, assumption, failed, measurement and user, and the first five are written as the matching tagged line. A decision names the option it beat and why.
  • migrate ledger before start. It gives the ledger every heading and, on Claude Code, rewrites two sections from the transcript: every user message verbatim, and the files the session changed. Then it names each section still empty. Fill every one from the conversation, or write none. An empty section reads as "forgot".
  • Every line you write in the ledger is gated: the plan carries it, or ## Deliberately dropped names it. The two generated sections are evidence and are not gated; they survive whole because finish attaches the ledger beside the plan as conversation-ledger.md and never offers it for deletion.
  • The ledger is keyed by Claude Code's session id. On any other harness, pick a name and pass --ledger <name> to every note, migrate ledger and migrate start, and write the user's words under "What the user asked for and corrected" yourself, quoted rather than paraphrased.
  • --no-ledger on start is for a consolidation with genuinely no conversation behind it — a legacy document migrated cold. It is written on the command line so the choice is visible.

[PITFALL: a resumed session has a new session id and a new transcript, and migrate ledger reads only the current one, so everything said before the resume is missing from the generated section. Measured 2026-09-30 on the session that built this: 5 of the session's user messages found, the rest in the pre-resume transcript. Until the ledger follows a resume, copy what the user said before it into "What the user asked for and corrected" by hand.]

Move paragraphs, do not compress them. The gate does not check prose yet, so you are the check: a source paragraph lands in the plan at the same depth, edited only where two sources overlap or where the code shows a claim is no longer true. Five paragraphs becoming one sentence is the failure this command exists to stop, even when every tagged line survives it.

check gates on the things whose loss is expensive and silent: every [TAG: …] line, every line carrying a YYYY-MM-DD date, and every line written in the ledger. A document's prose is not gated — rewording is the job, and a verbatim-coverage test would forbid it. It reads the sources live from disk (or out of HEAD if one is already deleted), so the comparison can never go stale, and it ignores the carried block: a check run against a file that still holds its sources verbatim would pass by construction.

Dropping something is a decision on the record, not an omission. Put it under ## Deliberately dropped with the reason and check counts it as accounted for — the same shape as ## Migrated to in the retirement procedure, and it leaves the reasoning in the file where the next reader finds it rather than in a flag nobody kept.

finish decides which sources may be deleted, and never deletes on its own. Put its offer to the user and pass --delete-sources only once they agree:

the sourceoffered?why
untrackedyesthis is the only copy, and the gate says it survived
tracked, and the plan landed in this repoyesthe deletion and the plan share one history
tracked, and the plan landed in the storenoit would split one lifecycle across two histories

[DECISION: the third row is why finish classifies rather than just deleting. A tracked file whose replacement lives outside the repo leaves that repo's history holding a deletion that points nowhere, while the store holds a plan the repo cannot see — the same failure the "absorb before retiring" rule exists to prevent, arrived at from the other direction.]

A source that is itself a plan gets its ## Migrated to section written and committed before it is deleted, which is step 4 of the retirement procedure and the step most often skipped by hand: add-and-delete in one commit means the section naming the destination is in no history at all.

Migrating a legacy single plan file

A repo predating this convention often has one big PLAN.md/DESIGN.md/NOTES.md mixing unrelated threads at different lifecycle stages. Don't retire it as a unit — split by thread first, then apply the lifecycle above to each piece. Where the split lands on one consolidated plan rather than several, migrate above is the mechanism; where it lands on several, run these steps and let each thread reach migrate start or new on its own:

  1. Sort its sections into threads: implemented and verified (→ landed), genuinely still undecided or stalled (→ its own new plan file, status: idea or blocked on <reason>), and simply inaccurate now (a design later replaced — drop it, it has no destination). One legacy file routinely becomes zero, one, or several plans, not one.
  2. Run the landed threads through "Retiring a plan" immediately, in the same pass — no reason to copy them into plans/ only to retire them a moment later.
  3. Give each still-open thread a real plan file with correct frontmatter, reformatted into the standard sections — not a leftover fragment of the old file's prose.
  4. Only once every thread has a home does the legacy file get its own ## Migrated to section (naming every destination) and go through the normal commit-then-delete sequence.

Don't stash future work in prose docs

Applies to any narrative doc — README.md and docs pages included, not only AGENTS.md. Each should describe the repo as it is right now. A known bug, an unfinished feature or an open risk belongs in its own plan file, linked from the doc if it is worth a pointer, never spelled out there: prose future-work rots into a permanently-true-sounding sentence, or worse, an already-fixed problem still calling itself "not yet fixed".

AGENTS.md (or any equivalent instructions file) gets the strictest version: instructions for developing and deploying the repo only — never planning, ideation, or a status report. Three drifts worth auditing for:

  • Dated status narrative. "Status: implemented and exercised live 2026-08-14" is a changelog entry, not an instruction — true today, stale tomorrow. Trim to an undated statement of what is architecturally true now, and drop the "as of <date>, confirmed working, tests pass" framing entirely; that belongs in a commit message.
  • Stale implementation claims. "These functions are stubs", "not yet confirmed" — silently rots once the work lands. Don't prose-review these: grep the code for the thing described (e.g. rg NotImplementedError before trusting a docstring that claims it) before deciding whether a passage is accurate, superseded, or safe to cut.
  • Speculative asides. "This might be cheaper a different way once X is understood" is a musing, not an instruction. Either it is a real open question deserving its own plan file, or it is colour already captured in the rationale home and can just be dropped.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.