Yardgoat Caboose

A planning framework for repositories worked on by AI agents: one authoritative roadmap that always answers where have we been, where are we, and where are we going.

This is an installable specification, not an idea file. The mechanics below install verbatim — the rules, the grammar, the vocabulary are fixed, because they only work if every repo running them means the same things by the same words. Everything else — your domain, your history, your scale — is adapted in conversation between you and your agent, and this document ends by telling you exactly how.

Here is your entire job: hand this document to your agent and say install this in my repo. Everything below the divider is addressed to it. Your part takes about five minutes — a few questions about your project's true history, one review at the end. The agent does the real work. (No agent at hand? Follow it yourself — the mechanics don't care who executes them.)

The problem this solves

Planning in most repos lives where it has always lived: a README that was true in March, TODO comments, a design doc nobody has opened since the meeting, an issue tracker with three eras of half-groomed tickets — and the real plan in somebody's head. This mostly works. Then the repo grows, or you step away for three weeks, or an agent joins the project, and the ceiling appears: nothing accumulates. You return and can't reconstruct where you left off, what state things are in, what you were addressing, what's next. Your agent has it worse — every session starts from zero, reads whatever it can find, and rebuilds the plan by inference. And here is the dangerous part: nobody involved ever says "I don't remember." The gaps get filled with confident invention. Clinicians who treat memory loss have a word for this — confabulation — and if you have watched an agent cheerfully describe a plan that does not exist, you have watched it happen.

Soldiers have a name for operating in conditions like these: the fog of war — you can always advance into the obscured part of the map, but safety is not guaranteed. Your own head has a version: brain fog — the shapes are all there, but you can't render them into a picture you'd act on. Your repository has one too.

Repo fog. The condition of a repository whose truth cannot be seen. Nothing is broken. No one failed. The folder is right there, same as ever. But between you and the actual state of the work hangs a layer that defeats confident action — and anything could be in it: decisions that were made but never written down (genuinely gone — no amount of looking harder recovers them), stale claims still posing as facts, changes someone landed while you were away, traps that were not there before — and treasure: real, finished, valuable work with no beacon on it, begging to be used, invisible. The fog's cruelest bill is not the mistakes. It is the module built twice, the dead end explored twice, the decision re-litigated a fourth time by someone who had no way to know it was ever litigated at all. Because of the fog, you cannot even tell which of these you have. That is what makes it fog. And notice where it is thickest: in exactly the repos where the most work has happened. Fog is produced by doing, not by neglect — it is the exhaust of velocity. Nobody is at fault for it, and everybody is inside it.

Fog is not cleared by trying harder. It is cleared by instruments.

What installs

Freight trains solved this problem a century ago and put the solution in its own car. The caboose was the conductor's office — the place where the train's paperwork lived. Its cupola was a raised lookout with a view over the whole consist — the full train, every car. And it hung marker lamps: lanterns whose entire job was fog and darkness — broadcasting where the train was, where it ended, and, to any crew following, that the train was whole. Records, vantage, and a lantern. One car, riding at the rear — behind the work, watching all of it.

That is what this document installs at the rear of your repo. One master file — roadmap/ROADMAP.md — that is the repo's memory, its lookout, and its lit lantern; numbered plan files; a decision register that makes choices once and keeps them forever; a verbatim record of the owner's rulings; and gates that keep all of it honest. In the language this document will occasionally indulge: it wards your repo. Placed instruments, kept current, so the fog never accumulates again.

The bar the whole system answers to — worth memorizing, because every rule below traces back to it:

A competent new hire, two months from now, reads this one document and understands everything that has been done, everything in flight, and everything that is coming — without asking anyone.

Ships kept logs. Architects keep decision records. Accountants have kept double-entry books for six hundred years. Every one of these exists because a trustworthy record beats a memory — and every one of them left the same problem unsolved: someone has to keep the books, and nobody wants to. Humans abandon planning systems because the maintenance burden grows faster than the value. That part is what changed. Your agent does not get bored, does not forget the second mention of a status, and can touch fifteen files in one pass. The bookkeeper problem is solved. This is the book.

A note on "the owner." Throughout, the owner means whoever holds decision authority for this repo — you, a lead, a committee. The framework requires only that the role exists and that its word gets recorded.

A note on scale. The core below transforms a solo repo with no further apparatus. The heavier machinery lives in five reference layers, each of which activates only when your work produces the condition that demands it — installing them early is ceremony; installing them late is pain; the triggers below are the line:

The rest of this document is addressed to the agent performing the installation.

You are installing this repository's planning and project-management system. The whole of it, in three sentences: One file, roadmap/ROADMAP.md, becomes the single place this repo answers: where have we been, where are we, where are we going. Three rules keep it true: it points but never restates (authority); nothing exists off the map (birth); the map moves in the same commit as the territory (maintenance). Decisions are made once, in files that outlive the chat that made them; the owner's word is recorded verbatim; and every rule is checked by a gate you have watched fail. Everything below is the letter of those three sentences.

Install faithfully in mechanics, adapted in content. Where this document names an example, translate it to this repo's domain; where it names a rule, install it verbatim. Nothing you produce is authoritative until the owner reviews it, and you do not execute any plan under this system until the owner gives the word.

1. The bar

A Caboose repo answers where it has been, where it is, and where it is going — at every commit. Write the master document to the new-hire bar quoted above, and hold these lines:

• History is a compressed ledger with commit hashes — enough to reconstruct the arc and know where to dig; git holds the detail. Never a wall of prose (a wall of prose is its own fog), never so terse it needs a guide.
• Statuses are honest. A thing that is half-done says so. Work that was abandoned, interrupted, or reversed is recorded plainly — failures logged in the open are what make every other claim in the document credible.
• Costs are honest. A plan states what it will cost before it runs; its closing record states what it actually cost — in units the repo declares once: hours, sessions, tokens, whatever is real here. Estimates never reconciled against actuals teach readers to ignore estimates.
• The writing is prose-first and plainspoken: tables for enumerable facts, sentences for anything that needs a why, no jargon a newcomer must decode.
• The litmus test for the whole system: check out any commit, read the roadmap, and you are reading the truth of that moment.

2. Survey first — the fog sweep

You cannot backfill honestly from assumption. Before writing anything, do the archaeology — this is the one pass through the fog that gets done by hand, and everything else in this system exists so it never has to be done twice:

1. Read the git history end to end (git log --oneline --reverse, then drill into the commits that look like era boundaries). Find the phases the work has actually moved through — eras, not months: "prototype," "the big refactor," "launch prep," whatever this repo's true story is.
2. Read every existing record of intent: README, docs, agent instruction files, TODO files, design notes, issue exports.
3. Find the existing sources of truth. Where do decisions live (ADRs? PR descriptions? nowhere?) — if a decision home exists, use it; never build a rival. Where do the owner's own words live — if such a record exists it is senior to every derived document; if none exists, start one going forward and never reconstruct past rulings from memory. Where does deferred work live — all of it gets a first-class home.
4. Find existing plan documents. They get retrofitted (§8), never discarded.
5. Where history is genuinely ambiguous, collect the questions and ask the owner once, as a batch. If asking is impossible, mark each uncertainty (unverified — owner to confirm). Never present a guess as a record. Guessing confidently is the disease this system treats; do not install it into the cure.

3. The mechanics (install verbatim)

A Caboose plan is born registered, moves through nine honest words, and closes with its actual cost recorded. The apparatus:

3.1 Where things live

<repo root>/
├── <agent-instruction file>      ← CLAUDE.md, AGENTS.md, or your tooling's
│                                    equivalent — EXTEND, never clobber (§6)
├── roadmap/
│   ├── ROADMAP.md                ← THE master document. One per repo, forever.
│   └── plans/
│       └── PLAN-nnn-<slug>.md    ← one file per plan
├── <decision home>/              ← e.g. decisions/DR-nnnn-<slug>.md + INDEX.md
└── <owner-voice home>/           ← e.g. owner-voice/OV-nnn-<slug>.md + INDEX.md

Scale the apparatus to the repo — a small repo may fold the decision home into roadmap/decisions/ — but the mechanics hold at every scale. Every plan file opens with front-matter, and this block is load-bearing, not decoration:

---
plan: PLAN-002
title: <title>
phase: PH-2
status: <one of the nine words>
born: <date> [<commissioning ref>]      ← registered in ROADMAP.md in the same commit (birth rule)
ratification: <pending | passed <date> [<ref>]>
completed: <date + closing commit + honest actual cost, on completion>
parent: PLAN-nnn        ← sub-plans only
---

The commissioning ref names the record that directed the plan — an owner ruling, a decision record, or the roadmap row that commissioned it; a retrofitted plan cites its original document.

Sub-plans are plans. When a stage outgrows its plan, the overflow is born as a new PLAN-nnn naming its parent, and the parent's stage row points to the child. No in-place bloat, ever. Plan numbers are sequential, never renumbered, never reused.

The installed roadmap's header carries one line — it tells any future maintainer which system they are looking at and where its current version lives:

Format: Yardgoat Caboose v1.0.0-draft — https://yardgoat.ai/caboose

3.2 The grammar and the nine words

Status vocabulary — these nine words and no others, for phases and plans alike: HORIZON (named, not commissioned) · COMMISSIONED (directed, not drafted) · DRAFTED (awaiting ratification) · RATIFIED (the word is given; may execute) · EXECUTING · COMPLETE · PARKED (deliberately not now, with recorded rationale) · HELD (paused by owner word) · SUPERSEDED (replaced by a named successor). The vocabulary is small so that statuses stay honest — no "done" that means nearly, no "in progress" that means stalled since June; a word for every real state, no word vague enough to hide in.

3.3 The three rules

• The authority rule. The roadmap is authoritative for plan and status — and for nothing else. Decisions and rationale live in the decision home; domain content lives in domain documents; the owner's recorded word outranks everything derived from it. The roadmap points; it never restates. This is what keeps five documents from each telling a slightly different version of the truth — the drift that fog is made of.
• The birth rule. Any document proposing new phases, plans, or waves registers them in the master in the same commit it is born. A plan that exists but is not on the map is a process defect. The rule does not tax thinking — notes and scratch ideas stay free; it binds at the moment something claims to be a plan. A Caboose repo never carries an off-book one.
• The maintenance rule. The master updates at every commit that changes plan state — a wave completing, a status moving, a checkpoint verdict, a plan born or held or completed. The update rides the same commit, so the map moves with the territory and any commit you check out tells that commit's truth. The rule does not demand narration — only state changes ride commits. A stale roadmap is not a smaller roadmap — it is a dark lantern: the crew behind you reads it as "all clear" while cars sit adrift on the line. And a production note: the most common failure is updating one mention of a status and missing the second. When a status changes, grep the master for every occurrence — the daily motion of this rule is a two-minute pass, and it is the entire difference between a record and a rumor.

3.4 One scope claim, true forever

The master's opening line declares what it is authoritative for. Scope it so it is true now and at every future scale — "the single authoritative roadmap for <exactly this repo's domain>" — never for some program that may someday outgrow the file. If the program does outgrow the repo, the answer is the program-index layer (references/programs.md), not a master that quietly annexes its neighbors.

4. The decision system

A Caboose repo decides once. This is the framework's core, and the cure for the deepest stratum of the fog — the decision that was made, mattered, and evaporated with the chat that made it.

• Decision records. One file per decision, in the decision home. Domain documents state what was decided and cite the DR — they never decide inline and never restate the rationale. A new question is a new DR; a changed answer is a new DR superseding the old (superseded-by: DR-nnnn); history is never rewritten. Each DR carries the question as its title; status front-matter from its own small fixed set — open · decided · parked · superseded-by DR-nnnn — with embodied-by:; its origin; the decision with the options honestly rejected; and its consequences. The cross-link is bidirectional — embodying documents carry embodies: — so a decided DR nobody embodies, or a claimed embodiment that doesn't exist, is a detectable defect instead of a silent one. Each register keeps an INDEX.md — one row per record: ID, one-line hook, status — the skim surface that spares reading fifty files.
• The DR-first rule. When work surfaces a genuine either/or, the decision is made — or escalated — before the text or code that depends on it is written. Deciding-by-writing, where the author's first draft quietly becomes the decision, is the exact failure this register exists to prevent.
• The owner's voice, verbatim. Rulings are captured immutably, one file each: curated front-matter above a fixed marker line (e.g. <!-- VERBATIM OWNER TEXT BEGINS -->), the owner's exact words below it, never edited. Where corpus and any derived document disagree, the corpus wins and the disagreement is a defect to file. This is what prevents the telephone game between what was said and what got built.
• The checkpoint rule. Anything value-laden or direction-setting goes to the owner as a question before it is treated as decided — with honest trade-offs, the option you reject and why, and your recommendation marked as such. A checkpoint may carry a fully-drafted candidate answer; the record must still show it was asked. Authorization is explicit and bounded: "proceed through CP2" authorizes exactly that. When in doubt whether a word covered something, ask — a one-line question is cheaper than an unauthorized wave.

5. The master document — ROADMAP.md

A Caboose roadmap points; it never restates. Build it with exactly these sections, adapting every example to this repo's actual content.

Header — the scoped one-line claim, the establishment date and its commissioning reference, the authority rule inline, the format line (§3.1), and the maintenance stamp — that exact sentence: current as of the commit that carries it (the maintenance rule is what makes it true). The lantern, lit.

§0 — If you are new here. What this repo is, in one tight paragraph. Standing constraints a newcomer must know before touching anything. A numbered reading order. One paragraph of history for the whole arc.

§1 — The planning framework. The mechanics of this specification's §3–§4 codified in the document itself, so a future agent can run the system from this section alone.

§2 — Where we have been: the ledger. One subsection per phase, PH-0 upward: date range, status, a table of what happened anchored to commit hashes, honest about failures and reversals, closed with the phase's exit state. Compressed — a three-month phase might be six rows; the reader digs in git. A real row, so you know the grain:

(Rows anchor to hashes already in history; a boundary commit cannot carry its own hash — it lands with the next entry.)

§3 — Where we are. Brutally current and deliberately small, because it changes most often and the maintenance rule has to stay cheap: the state of the main artifacts, which plan is EXECUTING under what authorization (cite the ruling), where the counters stand — the next free PLAN, DR, and OV numbers.

§4 — Where we are going: the phase table. Every phase from PH-0 to the furthest honest horizon, each with status and its plan or its commissioning trigger. Name distant eras as HORIZON — the long arc belongs on one screen.

§5 — Deferred and parked. The first-class home for everything deliberately-not-now, so nothing scatters into the margins — this is where the fog's unbeaconed treasure gets its beacon. Two tables: Scheduled (item → where its rationale lives → which plan takes it) and Standing (item → rationale → what wakes it). When a parked item wakes, record the firing — a parked row's full life should be readable forever.

§6 — The plan registry. Every plan: title, phase, status, born, completed. The birth rule's enforcement surface.

And know what makes roadmaps rot, each failure costed to the reader who arrives later: the wall-of-prose ledger (the new hire can't find where to dig, so they ask — the document has failed); the aspirational status (an agent builds on a "done" that isn't, and ships the gap); the stale map (a reader trusts §3, acts on it, and learns too late that the truth moved weeks ago — the dark lantern again). Every architectural choice above exists to make those three failures hard.

6. The agent-instruction file

Codify the rules in the repo's agent-instruction file so every future session inherits them on arrival — extend what exists (create it if none does); never clobber, never duplicate. Tersely: read the roadmap first and check it before starting anything; the layout, grammar, and nine words; the three rules; decisions only in DRs — embody, never decide inline, escalate genuine either/ors; value-laden calls go to the owner and rulings are captured verbatim; the gates and where to run them; commits land at wave boundaries and owner rulings, with the roadmap riding the same commit; the reference-layer activation triggers (the table before the divider), so future sessions open layers when their conditions arrive; and no execution without the word. Carry over any repo-specific working rules the survey found — the planning rules join them; they never replace them. Add one line of provenance (Planning per Yardgoat Caboose v1.0.0-draft — https://yardgoat.ai/caboose) so the next maintainer knows what system they inherited and where its updates live. The version in both lines is this document's own — carry it as written here. That line is the repo's pointer back to this specification; where a URL cannot be relied on, vendor a copy of the spec and its reference layers into the repo — the installer's call. When not vendoring, record the reference layers by absolute URL (https://yardgoat.ai/caboose/references/) so future sessions fetch them without inference.

7. Gates — rules that are not checked are wishes

Install the lightest checks that can actually fail, and make green gates a precondition for every commit touching governed content — the set §3.1 installs: the roadmap, plans, registers, and instruction file:

• A lint script checking at minimum: required front-matter present and legal; every plan and phase status one of the nine words, every DR status from its own set (§4); DR references resolve to real files; decided DRs have at least one embodying document (the bidirectional links make this mechanical); identifiers unique; any banned-vocabulary rules the domain has. Run it from a documented location — a checker run from the wrong directory sweeps the wrong files and lies green or lies red, both worse than no checker.
• Prove every check can fail. Before trusting any inherited checker, read it. Then plant a violation; watch the gate catch it; remove it; watch it go green. Only then trust it. A gate that prints success while one of its checks is a stub converts "unverified" into "verified" in every reader's mind — this lesson was paid for in production, and re-proving the gate is required any time the checker itself changes.
• Artifact validators, wherever a derived artifact renders a source of truth — fixtures, generated outputs, rendered documents: a mechanical check that the artifact still matches its source, re-run when either side changes. Staleness you can detect is staleness that never ships.
• A CHANGELOG in Keep a Changelog form, recording human-readable deltas — including, in the open, process violations and their repairs: the interrupted run, the stale status a verifier caught. Counterintuitive and load-bearing: the recorded failures are what make the successes credible.

8. Retrofit — every repo has a past

Messy history is the normal case, not the exception. Pre-existing plan documents become roadmap/plans/PLAN-001… in historical order, imported verbatim below a marker, with front-matter noting the original location, that the plan predates the framework, its phase, and its true status (likely COMPLETE or SUPERSEDED; a dead end with no successor is PARKED, its abandonment recorded honestly — deliberately-not-now includes never-again). A plan currently in flight is retrofitted the same way and becomes the framework's first live citizen. A plan that lives outside the repo — a scratch file, a pasted doc — gets imported: a record that exists only on someone's machine is a record the project does not have. History is preserved, never rewritten; the pre-framework past is told honestly across as many phases as it truly had, PH-0 upward. Decisions the survey uncovered may be backfilled as DRs where the evidence supports them — cite the commit or document that shows the choice; never reconstruct one from memory.

9. Delivery — then stop

1. Build the whole installation — master with full backfill, registers, instruction-file rules, retrofitted plans, and the gates, each proven able to fail.
2. Land it in a single commit, every gate green, registered per the birth rule — proof precedes landing; the founding commit arrives already clean.
3. Present the owner a concise summary: what was installed, the phase structure you reconstructed (flag any era boundary you were unsure of), every (unverified — owner to confirm) marker, and anything you found that the framework should absorb but you left untouched pending their word. Surface "A note on making it yours" to them as you close — that section is theirs, not yours.
4. Then stop. The installation is DRAFTED until the owner ratifies it — record the ratification, when it comes, as the owner-voice corpus's first entry, reflected in the master's §3. Nothing executes until then.

10. Self-check before you deliver

• Does ROADMAP.md §0–§6 exist exactly as architected, and does §1 alone suffice to run the system?
• Is the scope claim true at every future scale?
• Can the two-month new hire answer: what is this repo, what has been done (with commits to dig into), what is in flight, what is coming, what is parked and where its why lives? (The new-hire test.)
• Is every status one of the nine words, honest, at every occurrence — check out any commit; is the file true there? (The any-commit test.)
• Does every pointer resolve — every path, every hash, every ID?
• Is the roadmap free of restated rationale, every plan in the registry, every decision cross-link bidirectional?
• Do the gates run green from their documented location — and have you watched each check fail at least once? (The plant-a-violation test.)
• Is the instruction file extended, not clobbered?
• If this repo is part of a program: is it in the index with registered prefixes and one up-pointer, reading upstream repos read-only against pinned versions?
• Did you invent nothing where history was ambiguous?

Where Caboose stops

Honesty about limits is a feature of this system; it applies to the system itself. Four limits, all real:

1. It is a document convention. Nothing enforces the rules except your discipline and the gates you install. No runtime, no service, no hooks watching you.
2. It points at issue trackers; it does not integrate with them. Your tracker remains your tracker; the roadmap holds the plan-level truth and cites outward.
3. It is prose and files, not a queryable graph. Nothing computes dependencies or flags staleness beyond the checks you write. The reader's instrument is reading.
4. Multi-agent safety is coordination by discipline — briefs, scoped ownership, escalation — not concurrency machinery. The framework makes parallel work safe by making it legible, not by locking files. If you need transactional guarantees, this is not that.

If you run this system for two months and find yourself pressing against these walls — wanting the graph, the enforcement, the integrations — that pressure is real, and it is being worked on. See the footer.

Why this works

The tedious part of keeping a project legible was never the thinking — it was the bookkeeping: updating the second mention of a status, keeping cross-references true, writing down the decision after the debate instead of collapsing into the next task. Humans abandon planning systems because that burden grows faster than the value. Agents changed the economics: the bookkeeping is now nearly free, and this framework is the book — designed so that the cheap, boring, constant maintenance an agent is perfect at compounds into the one thing money couldn't previously buy: a repo where the truth is always in view.

Every rule above exists because its absence produced a named failure somewhere. The authority rule prevents five documents from drifting into five truths. The birth and maintenance rules prevent the off-book plan and the stale map — the two ways a project loses the answer to "where are we?" The decision system prevents deciding-by-writing, and its bidirectional links make silent resolution detectable. Verbatim owner-voice prevents the telephone game. Gates make the rules checkable; the open CHANGELOG makes the record credible; honest costs make estimates meaningful.

Seen from the fog: the survey is the one sweep done by hand. The roadmap and registers are the permanent wards. The maintenance rule is the upkeep — because vision decays, and a ward placed once and never refreshed is how the fog comes back wearing a green checkmark. The deeper principle under all of it: records are attributed and append-only; decisions are made once and embodied everywhere; conflict is surfaced, never silently resolved; and the system says plainly what it knows, what it assumes, and what it got wrong. Run the mechanics and you get the letter. Understand this paragraph and you get the spirit — which is what the mechanics are for. The ledgers humanity already trusts — the ship's log, the decision record, the double-entry book — never solved who keeps them. This one ships with its bookkeeper.

A note on making it yours

The mechanics you just read are fixed. Everything else is yours, and this document's last job is to insist that you take it.

What is fixed: the rules, the grammar, the nine words, the document architecture — the shared skeleton that makes any Caboose repo legible to any reader who has seen one before. What is yours: the scale (a solo repo may run the core and nothing else for a year — that is the system working, not a partial install); the content (your phases are your eras; your stream letters should name your kinds of work — a research group might run E/M/P for experiment, modeling, publication; a game studio might phase by vertical slice; your PH-0 is your actual past, told true); and the fit (a repo that already keeps ADRs keeps them — the framework joins what exists and never builds a rival; a team where "the owner" is three people writes that down and moves on).

So: talk it through with your agent. Have the conversation this document was designed to start — what does this project actually need now, which layers stay dormant, what does our history really look like, what conventions do we already have that the framework should honor. Adapt accordingly, and record the adaptations in your instruction file so every future session inherits not just the framework but your framework. Your agent has read this document too. It knows the mechanics. What it needs from you is the few minutes of truth only you have — and then the fog starts lifting, and it does not come back.

The map is yours. Keep the lantern lit.

Yardgoat Caboose v1.0.0-draft · specification © 2026 Tanner Jourdian (github.com/tannershotme) · CC BY 4.0 · canonical source: https://yardgoat.ai/caboose · Caboose is the first public component of Yardgoat — a larger system in development. A framework about honest ledgers keeps one: see CHANGELOG.md.