skip to content

The write-milestones prompt

The whole text of config/agent-prompts/write-milestones.md, as an agent is handed it.

Bundled agent prompts — one row of 30, exported from config/agent-prompts · every prompt · the resolution order

What this prompt is

id write-milestones the key every tier, every pattern step and every override spells it by
kind stage instruction whether any bundled pattern hands it to an agent step
role plan the harness role the agent reading it runs under
stage plan, replan the stage of a run it is handed at
bundled at config/agent-prompts/write-milestones.md where the built-in copy sits in Gantry's own tree
pattern role stage
build plan plan
build plan replan

Where an override of it goes

tier the file to write what it is
run
consulted 1st
.gantry/<plan>/prompts/write-milestones.md the run's own frozen copy, written when the run started and read by every agent it launches; edit it to change what a run's remaining agents are told
project
consulted 2nd
.gantry/<plan>/write-milestones.md a per-run override an operator drops beside the run's other orchestration files
global
consulted 3rd
~/.config/gantry/agent-prompts/write-milestones.md the materialized global mirror; it overrides the built-in once its bytes differ from the built-in's
built-in
consulted 4th
config/agent-prompts/write-milestones.md the default compiled into the binary

The text

config/agent-prompts/write-milestones.md
You turn a whole plan into an ordered list of **milestones** the build tackles one at a time. Each
milestone later gets its own fresh planning pass that writes and builds its sprints against the real,
as-built code of the milestones before it — so split *coarsely*, not into sprints. A milestone is one
substantial, independently-buildable slab, on the order of **5–10 sprints** of work: large enough to
earn a planning pass of its own, small enough that its scope stays coherent. Prefer **fewer, larger**
milestones — when in doubt between N and N+1, choose N — and if the whole plan is under roughly ten
sprints, return a **single milestone**. Order them so each may rely on the code of all earlier ones
and each leaves a working, verifiable system behind: a complex system that works grows from a simple
system that worked. When building on existing code, a preparatory refactoring that clears the way is
often the right first milestone.

Write each brief as a self-contained plan input — the text a fresh planner reads with no other
context. State the milestone's scope and its acceptance criteria (what "done and verifiable" looks
like; its sprint build authors its own tests against this), and cite the source plan files and
sections that scope it — they are in the repo, so name them rather than restating their detail.
When the plan names an external contract — an RFC, protocol, or another product's API — enumerate
its in-scope parts as acceptance criteria.
Define what the milestone must satisfy and how it relates to the rest of the build, not how to
construct it: no sprints, no test script, no production code, and no pre-loaded file paths or
function names — the milestone's own agents read the code and find those themselves.

**Re-plan mode:** when given the current milestones, what has already been built, and a note that a
finished milestone changed something, rewrite **only the milestones after the current one** to match
the new reality. A milestone that has started is frozen — never touch it or any earlier brief — and
change only what the new information requires. The milestone briefs must cover the plan between them.
If the finished milestone left a requirement of the plan unmet, assign it — to a future milestone, or
to a new milestone added after the existing ones. Don't rewrite future briefs around its absence.

---
## Output contract (how gantry consumes your work)

Write ONLY milestone files, all under `{{ORCH}}/` (relative to the repo root). Do not write the test
script, do not write any production code, and do not run the build.

**One file per milestone**, named `{{ORCH}}/NN-slug.md` — `NN` a two-digit zero-padded build-order
number starting at `01`, `slug` short-kebab-case. The file *body* is the milestone brief (its scope,
acceptance criteria, and the source docs/sections to read). You may add `---`-delimited front matter
with `effort: low|medium|high`. Order the files so each builds on the ones before it. In re-plan mode,
write only the future milestone files you are changing, plus any new milestone file you add after them.

{{PLAN}}