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 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
pattern role stage
build plan plan
until plan plan

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

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