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 |
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
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}}