The README prompt

# gantry — default agent prompts

The prompts the pipeline assembles for each agent stage. These are the **defaults** that ship with
gantry. There are two ways to override them:

- **Per run (project tier):** place a file of the same prompt id under a run's own `.gantry/<plan>/`.
  Enum-owned engine prompts stay flat (`write-gate.md`, not `agent-prompts/write-gate.md`);
  string-keyed pattern prompts keep their slash path (`design/briefs/execute.md`).
- **Globally (every run):** edit the materialized copy under `~/.config/gantry`. Gantry mirrors this
  whole tree there at the **same relative path** — `~/.config/gantry/agent-prompts/write-gate.md` — so
  the file you see is the file you edit is the file that overrides. Editing it in place makes it a
  global override; leaving it as shipped keeps it a refreshable default (below).

`review.md` is shared by sprint and milestone review; overriding it changes every review altitude.

**Every prompt is named for the instruction it gives, in the imperative**, and where that instruction
produces a named artifact, the object of the verb is that artifact: `write-gate.md` authors `bin/gate`,
`write-about.md` authors the `about.md` sidecar, `summarize-review.md` narrates a review. Two files
sit outside the rule on purpose, and neither should be "finished off" into it: `preamble.md` is the
template every worker prompt is prepended with rather than an instruction of its own, and
`gantry-agent.md` is the conversational assistant's persona and standing brief for a session, not a
task. The role nouns the UI shows — Builder, Fixer, Reviewer, Sprint Planner — stay nouns.

Engine-owned prompts are addressed in code by the `AgentPrompt` enum. Pattern-owned prompts are
addressed by slash-separated string ids such as `design/briefs/execute`, resolved through the same
project, global, and bundled tiers. Retired pre-rename filenames are not read; rename an old override
file to the current filename for it to apply.

**Materialized defaults stay fresh without clobbering edits.** The global mirror is kept current
automatically: on each run a **pristine** copy (bytes still matching what Gantry last wrote) is
refreshed to the current binary's default, so an upgrade's improved prompts take effect on their own;
an **edited** copy — a global override — is never touched, and if the shipped default has since changed
the run prints one card noting your version now diverges. A hidden `~/.config/gantry/.gantry-defaults.toml`
manifest records the last-written default per file so pristine and edited can be told apart; it is
managed automatically, not hand-edited. `gantry config reset` is the deliberate way back to these
defaults — it discards your edits, rewrites every prompt to the shipped text, and sweeps stale
pre-rename copies (see [the config reference](../../docs/agents/config.md#materialized-defaults-provenance-auto-refresh-and-reset)).
Prompt overrides may change wording freely, but they may not remove a placeholder that carries a
signal Gantry later reads from disk. A stale project or global override that drops one is refused at
run start with the override path, the missing signal, and the two remedies: reconcile it with the
current default, or delete it and customize again.

> For a **complete catalog** of every prompt — each stage's job, its harness role, its length, and its
> placeholders, including the milestone, map, goal, loop, and conversational-agent prompts — see
> [`docs/reference/agent-prompts.md`](../../docs/reference/agent-prompts.md). This file documents the
> placeholder-filling *contract* and the minimalism rationale; that one is the *inventory*.

Every worker agent gets a rendered worker preamble prepended, then its stage prompt. For ordinary
builds that preamble comes from **`preamble.md`**. Map mode renders the preamble file named by the map
spec for fan-out workers, plus the ordinary **`preamble.md`** for checkpoint workers when a checkpoint
is configured. Gantry fills each environment placeholder itself: the run facts it already holds in
config (worktree, canonical repo, orchestration dir, sandbox mode), followed by the authored
briefing at `.gantry/<plan>/environment.md` when one exists. The briefing is inserted as-is and is never
validated — every claim in it is self-correcting at the point of use, and an absent one simply leaves
the facts standing alone.

A plain build starts with the milestone driver (`write-milestones.md`); each milestone then uses
**`write-sprints.md`** to produce right-sized sprint files. Small plans collapse to one milestone and
therefore one flat pass without a separate user-selected mode. **`write-gate.md`** is the dedicated
test-builder run that authors the test script `bin/gate` once for the current sprint set — the
planner no longer writes the tests.

Design and redesign are bundled patterns, not a separate prompt tier. `design.toml` invokes the shared
`milestone` unit twice with `design/briefs/` and `design/pages/` prompt prefixes; `redesign.toml` first
runs `design/clean-slate.md` and requires the real marker
`docs/page-design/.clean-slate-complete`.

Map mode accepts either a hand-written map spec or prose. Prose sources run **`write-map-spec.md`**
first; that planner writes `.gantry/<plan>/map-spec.map`, `.gantry/<plan>/map-worker-preamble.md`, and,
when the generated spec has a checkpoint, `.gantry/<plan>/map-checkpoint.md`. The generated spec is
then parsed and empirically checked as the same map-spec format hand-written map runs already use.
Rejected generated specs are retried with Gantry's concrete check diagnostic for a small bounded budget,
tracked in `.gantry/<plan>/map-spec-repair.json`; only an accepted generated spec is promoted to the
ordinary map fan-out.

**`commit.md`**, **`write-about.md`**, and the **decoration prompts** are the exceptions: they are *not*
worker prompts and get **no worker preamble** or environment section. Reader-facing one-shots do get
the short shared vocabulary primer from **`reader-preamble.md`** prepended to their user prompt, through
the same frozen/project/global/bundled prompt tiers, while keeping each prompt's own output contract.
Each runs as a self-contained one-shot on a cheap model (`haiku` by default, `GANTRY_COMMIT_MODEL`).
`commit.md` writes each content-bearing commit's message from the staged diff, so gantry's commits read
like a human's instead of `NN: slug`. `write-about.md` names the run or current build pass — a short
project title and a one-line description **plus** a title + blurb for every sprint row the dashboard
will show — in the form the cards sidecar persists to `.gantry/<plan>/about.md` (reused on resume).

The four other decoration prompts dress the dashboard's status cards, each a cheap one-shot whose
output is parsed leniently and clamped: **`title-plan.md`** titles the planner's card (headline +
blurb) from the raw plan before planning starts; **`summarize-gate.md`** names what the test script
`bin/gate` does in one line; **`summarize-review.md`** and **`summarize-replan.md`** narrate, in 1–2
sentences, what a review or an observed-change re-plan actually did. All are cosmetic: any failure falls back to
gantry's deterministic message / the plan slug / the stage default.

**`stop-summary.md`** is the generated stop-card prompt. It receives `{{READER_PREAMBLE}}` and a
bounded `{{STOP_BUNDLE}}`, then asks for exactly a short title line and one concise body paragraph:
lead with the cause, name one next action, cite provenance only when present, and invent nothing
outside the bundle. The parser accepts only that two-part shape and rejects empty, fenced, over-length,
or otherwise malformed responses so callers can use the mechanical stop rendering instead.

Placeholders in double braces are filled by the orchestrator at dispatch:

| Placeholder | Stage(s) | Content |
|---|---|---|
| `{{PLAN}}` | plan, write-sprints, write-milestones, write-gate, write-environment, write-map-spec, write-about, title-plan | the plan to decompose (re-plan: + what's landed + the change); for write-gate, the same plan pointer so the test-builder honours any stated verification constraint; for write-environment, the same plan, so the briefing is specific to the work rather than a repo tour — except on a map run, which has no plan prose and passes the spec's own account of the work (enumerator, artifact, gate, unit prompt); for write-map-spec, the prose fan-out request; for write-about, the plan slug; for title-plan, the raw plan material |
| `{{ORCH}}` | write-sprints, write-milestones, write-gate, write-environment, write-map-spec | the `.gantry/<plan>/` dir (relative) the sprint files, milestone files, test script, environment briefing, or generated map artifacts live under |
| `{{MAP_SPEC}}` | write-map-spec | the worktree-relative path for the generated map spec |
| `{{MAP_WORKER_PREAMBLE}}` | write-map-spec | the worktree-relative path for the generated map worker preamble |
| `{{MAP_CHECKPOINT}}` | write-map-spec | the worktree-relative path for the optional generated checkpoint prompt |
| `{{REPAIR_CONTEXT}}` | write-map-spec | empty on the first generated-spec attempt; on repair attempts, the previous empirical check diagnostic to fix |
| `{{SPRINT}}` | execute, fix | the sprint's brief (for a loop iteration's fix: the standing prompt) |
| environment placeholder | preamble and map spec preambles | Gantry's own run facts (worktree, canonical repo, orchestration dir, sandbox mode) plus the authored briefing from `.gantry/<plan>/environment.md` when one exists and bounded run history from the ledger, generated unit descriptions, generated review/replan summaries, and recovery notes |
| `{{GATE_PATH}}` | execute, fix, troubleshoot | the exact test command the pipeline runs (`.gantry/<plan>/bin/gate`, or a loop's `test:` command), so the agent self-verifies against the real tests |
| `{{SPRINTS}}` | write-about | the current sprint outline (`NN-slug: intent` per line) to name, summarize, and title per visible sprint row |
| `{{GATE}}` | summarize-gate | the test script `bin/gate` to describe in one line |
| `{{GATE_OUTPUT}}` | fix, troubleshoot | the failing test output (head + tail of the test log) |
| `{{DIFF}}` | fix, troubleshoot, review, commit, summarize-review | the unit's diff (for milestone review: the milestone's merged diff; for commit: the staged diff to describe; for summarize-review: what the review changed) |
| `{{BRIEF}}` | troubleshoot, review | the brief implemented (for milestone review: the milestone brief) |
| `{{REVIEW_SUBJECT}}` | review | the review altitude's subject noun (`sprint`, `whole milestone`) |
| `{{ALTITUDE_CLAUSE}}` | review | the review altitude's subject, review emphasis, and meaning of the remaining plan |
| `{{SOURCE_PLAN}}` | review | the protected source-plan anchor the reviewer must compare against |
| `{{REMAINING_PLAN}}` | review | the remaining plan context at the review altitude |
| `{{WITHHELD_DRAFT}}` | review | an optional withheld plan-edit draft when the pattern supplied one; otherwise an explicit absence note |
| `{{VERDICT_PATH}}` | review, design/*/review | the review scope channel file declared by the pattern |
| `{{RETRY_NOTE_PATH}}` | review, design/*/review | the note file for retry verdicts declared by the pattern |
| `{{REVIEW}}` | summarize-review | the reviewing agent's captured output |
| `{{PLAN_IMPACT}}` | summarize-replan | compatibility placeholder name carrying the observed plan-change context for the re-plan summary |
| `{{REPLAN}}` | summarize-replan | the re-planner's output |
| `{{READER_PREAMBLE}}` | stop-summary | the resolved reader-facing vocabulary primer from `reader-preamble.md` |
| `{{STOP_BUNDLE}}` | stop-summary | the bounded stop record bundle that grounds the generated stop card |
| `{{POSITION_CLAUSE}}` | troubleshoot | the step's escalation position (repair rung vs. spent-budget handover), sourced from the agent step's `template_values` in the pattern TOML rather than filled by the engine |
| `{{DISPOSITION_PATH}}` | troubleshoot | the troubleshoot disposition channel file (`retry` or `handover`) declared by the pattern |
| `{{NOTE_PATH}}` | troubleshoot | the note file a `retry` disposition briefs the next attempt through |
| `{{HANDOVER_PATH}}` | troubleshoot | the handover document a `handover` disposition stops the unit with |

**Keep these short.** They are deliberately minimal — modern models are capable, and a prompt should
start as a few clear paragraphs and accrete only what real runs prove necessary.