---
name: yardgoat-caboose
description: Install and run a complete planning system for any repository - one authoritative ROADMAP.md, numbered plans, decision records, owner rulings kept verbatim, and honest statuses, built and maintained by your agent. Use when a repo's planning is scattered or stale, when every new session re-derives the plan from scratch, when you need to know where a project has been, where it is, and where it is going, when standing up project management for agent-driven work, when retrofitting a repo with messy history, or when asked to install Yardgoat Caboose, ward a repo, or clear repo fog.
license: CC-BY-4.0
metadata:
  author: Tanner Jourdian
  author-url: https://github.com/tannershotme
  version: 1.0.0-draft
  source: https://yardgoat.ai/caboose
---

# 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:

| Layer | Activate when | What broke without it |
|---|---|---|
| `references/decision-craft.md` — escalation ledgers, checkpoint packet craft, owner-voice curation | The first genuine either/or the owner's word doesn't already cover; the first scoped agent working under a plan | Deciding-by-writing; the telephone game between what was said and what got built |
| `references/waves-and-streams.md` — the wave pipeline, briefs, disjoint ownership, verification and repair | Work fans out: more than one stream or agent under one plan | Two agents in one file; findings nobody owned; authors grading their own work |
| `references/continuity.md` — interruption recovery, the session handoff, the compaction protocol | Long-running agent sessions; before any planned context compaction; after any killed run | The successor who guessed; good partial work reverted; the relationship lost at the boundary |
| `references/versioning-and-currency.md` — draft suffixes, stamp events, basis stamps | Your first ratified milestone or first derived artifact | The derived document silently stale — "current" discovered false by an embarrassed reader |
| `references/programs.md` — the program index, namespacing, multi-repo instances | The day a second repo is born — not before | Sibling pointers without bound; one repo secretly owning the map of the others |

---

*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

| Thing | ID | Notes |
|---|---|---|
| Phase | `PH-n` | Eras of the work. Stable forever; never renumbered. The survey's historical eras become phases too — the past maps to as many as it truly had, PH-0 (the earliest) upward. |
| Plan | `PLAN-nnn` | One file; belongs to exactly one phase. |
| Wave | `Wn` (plan-scoped) | Stages inside a plan; commits land at wave boundaries. Naturally continuous work still defines waves — as milestones. |
| Work stream | letter + number (plan-scoped) | R research · A authoring · V verification · F fix · I integration. Adapt the letters to this repo's work; declare the legend in the master's §1; keep it fixed. |
| Owner checkpoint | `CPn` (plan-scoped) | Every value-laden decision routes through one. |
| Decision | `DR-nnnn` | One file each. Never renumbered, reused, or rewritten. |
| Owner ruling | `OV-nnn` | One file each. Verbatim body, immutable. |

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:

| What | Record |
|---|---|
| Auth rebuilt on session tokens; the JWT dead end abandoned for cause (DR-0007) | `a3f9c21` |
| v0.9 shipped to the pilot cohort — PH-2's exit state | `c2d81b9` |

(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](https://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.*