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 23, 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 | 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; editing it changes what a run's remaining agents are told |
|
project
consulted 2nd |
.gantry/<plan>/write-milestones.md |
a per-run override an operator places 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 tasks against the real,
as-built code of the milestones before it — so split *coarsely*, not into tasks. A milestone is one
substantial, independently-buildable slab, on the order of **5–10 tasks** 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
tasks, 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 task 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 tasks, 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.
---
## Output contract (how gantry consumes your work)
Write ONLY the declared outputs below — those paths are relative to `{{ORCH}}/`, not to your
worktree. Do not write the test script, do not write any production code, and do not run the build.
{{OUTPUTS}}
Create the `milestones` output directory and write one file per milestone inside it, named
`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.
Open every milestone brief body with a level-one heading naming that milestone — `# Watch Core`,
2-5 words, Title Case, no trailing punctuation — before any other line. Gantry titles the
milestone's sidebar row and cards from that line, so a brief that opens on a section label instead
names every milestone after the label. Do not repeat the number or the slug in it, and do not reuse
one title for two milestones.
Write the `plan_scope` output as exactly `work` when there is at least one actionable milestone, or
exactly `none` when there is nothing for Gantry to build. Do not wrap the value in TOML.
{{PLAN}}