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 (`write-milestone-gate.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 task and milestone implementation review; overriding it changes both. `review-plan-change.md` is the separate observed-plan-change review
contract: overriding it changes the agent that judges scoped run-plan diffs against the immutable
source plan. That prompt must retain `{{PLAN_CHANGE_DIFF}}`, `{{SOURCE_PLAN}}`,
`{{SCOPED_PLAN_FILES}}`, and `{{OUTPUTS}}`; the declared output contract names the consumed verdict
file and its closed raw values, normally `accepted` or `rejected`.

**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-project-gate.md` and
`write-milestone-gate.md` author `bin/gate`, `write-about.md` authors the `about.md` sidecar, and
`summarize-review.md` narrates a review. One file sits outside the rule on purpose, and it should not
be "finished off" into it: `preamble.md` is the template every worker prompt is prepended with rather
than an instruction of its own. 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, resolved through the same
project, global, and bundled tiers.

**Materialized defaults stay fresh with Git history.** The global mirror is kept current
automatically: on each run a **pristine** copy (the worktree still matches Gantry's last default commit
for that path) is refreshed to the current binary's default, so an upgrade's improved prompts take
effect on their own. If an uncommitted edit sits on top of an older default that must be refreshed,
Gantry commits that edit first and then commits the refreshed default, leaving the edit reachable in
the mirror's history. `gantry config reset` is the deliberate way back to these defaults — it commits
your edits before discarding them from the worktree, rewrites every prompt to the shipped text, and
sweeps stale pre-rename copies (see [the configuration reference](https://gantry.software/docs/configuration)).
Prompt overrides may change wording freely, but they may not remove a placeholder that carries a
signal Gantry later reads from disk or uses to assemble a consumed declared output contract. 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. The shared `troubleshoot.md` prompt is used both for red-gate recovery and for `on_stop`
hooks: overrides must preserve `{{OUTPUTS}}` so the declared verdict, note, handover, and revert
paths stay visible, and should preserve `{{POSITION_CLAUSE}}` so hooks receive their stop facts
through declared pattern text.

> For a **complete catalog** of every prompt — each stage's job, its harness role, its length, and its
> placeholders, including the build, map, goal, loop, and conversational-assistant prompts — see
> [the prompt inventory](https://gantry.software/docs/prompts). 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 task prompts are carried by each roster file
and use the same ordinary worker preamble. Gantry fills each environment placeholder itself: the run
facts it already holds in
config (worktree, canonical repo, orchestration dir, wrapper state), 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 default `build` pattern's planner (`write-milestones.md`), then
**`write-project-gate.md`** authors the run-scoped full-project `bin/gate`: it finds the project's
own full gate, prefers an existing project gate over a composed subset, and reports a missing project
gate explicitly. Each milestone uses **`write-sprints.md`** to produce right-sized task brief files.
Small plans collapse to one milestone and therefore one flat pass without a separate user-selected
mode. **`write-milestone-gate.md`** authors the scoped inner-loop `bin/gate` once for the current
milestone.
`write-gate.md` remains bundled compatibility material for frozen or overridden runs.

Map mode runs **`write-map-roster.md`** first. That planner writes a declared roster directory, with
one TOML-front-matter task file per task. The prompt body in each task file is handed directly to that
task worker, and the task's `gate` value is the deterministic command Gantry runs after the worker.

**`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 task row the dashboard
will show — in the `## task <id>` blocks the cards sidecar persists to `.gantry/<plan>/about.md`
(reused on resume).

The other decoration prompts dress dashboard status cards, each a cheap one-shot whose output is parsed leniently and clamped: **`summarize-gate.md`** names what the test script `bin/gate` does in one line; **`summarize-review.md`** narrates, in 1-2 sentences, what a review actually did. Each runs at the finish of a step that declares `summarize = true` — a `gate` step for `summarize-gate.md`, a review-stage `agent` step for `summarize-review.md` — and `gantry repair` runs `summarize-review.md` again over a retained review log to reconstruct a summary an older run never persisted. All are cosmetic: any failure falls back to gantry's deterministic message or 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-project-gate, write-milestone-gate, write-gate, write-environment, write-map-roster, write-goal-check, write-gap-plan, write-about | the first declared input rendered as plan material; for gate-authoring prompts, the same plan pointer so the agent honours any stated verification constraint; for write-environment, the same plan, so the briefing is specific to the work rather than a repo tour; for write-map-roster, the task source; for write-goal-check, the goal source; for write-gap-plan, the first input, with every declared input also present in `{{INPUTS}}`; for write-about, the plan slug |
| `{{INPUTS}}` | agent prompts such as write-about, write-map-roster, write-goal-check, write-gap-plan | every declared input rendered in order, with file inputs expanded for the agent |
| `{{OUTPUTS}}` | agent prompts such as write-milestones, write-sprints, write-about, execute, review, troubleshoot, review-plan-change, write-map-roster, write-goal-check, write-gap-plan | the declared output names, paths, and closed raw values the agent must write |
| `{{ORCH}}` | write-sprints, write-milestones, write-project-gate, write-milestone-gate, write-gate, write-environment, write-map-roster, write-goal-check, write-gap-plan | the task's own `.gantry/<plan>/…` dir the task brief files, milestone files, test script, environment briefing, roster, acceptance check, or gap plan live under — absolute, and in the canonical checkout rather than under the agent's worktree |
| environment placeholder | preamble and historical map spec preambles | Gantry's own run facts (worktree, canonical repo, orchestration dir, wrapper state) plus the authored briefing from `.gantry/<plan>/environment.md` when one exists and bounded run history from the ledger, typed stop records with recorded evidence, generated task descriptions, generated review/replan summaries, and rejected attempt notes |
| `{{GATE_PATH}}` | execute, troubleshoot | the declared `judging_gate` command for the agent step, or the statement that no gate step resolves for the task |
| `{{GATE}}` | summarize-gate | the test script `bin/gate` to describe in one line |
| `{{GATE_OUTPUT}}` | troubleshoot | the failing test output (head + tail of the test log) |
| `{{DIFF}}` | troubleshoot, review, commit, summarize-review | the relevant project diff (for task fix/review/troubleshoot: the current attempt's committed session range; for milestone review: the milestone's committed range; for commit: the staged diff to describe; for summarize-review: what the review changed) |
| `{{PLAN_CHANGE_DIFF}}` | observed plan-change handlers, review-plan-change | the scoped plan-file diff that caused the current observed-plan-change handler to run; blank outside that handler path and separate from `{{DIFF}}` |
| `{{BRIEF}}` | execute, troubleshoot, review | the brief implemented (for milestone review: the milestone brief) |
| `{{REVIEW_SUBJECT}}` | review | the reviewed subject's noun (`task`, `whole milestone`) |
| `{{EXTRA_JUDGMENT}}` | review | what this review judges that `review.md` does not already state; empty for a task review |
| `{{SOURCE_PLAN}}` | review-plan-change | the protected source-plan anchor the plan-change reviewer must compare against |
| `{{SCOPED_PLAN_FILES}}` | review, review-plan-change | the plan-derived files watched for observed changes in this step |
| `{{REVIEW}}` | summarize-review | the reviewing agent's captured 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 (troubleshoot pass vs. spent-budget handover), sourced from the pattern's text parameters |
| `{{BRANCH}}` | resolve-merge, adjudicate-merge | the run branch in the disposable worktree where the home branch's tip has been integrated |
| `{{MERGE_STATE}}` | resolve-merge | the in-progress git merge state |
| `{{CONFLICT_CONTEXT}}` | resolve-merge | the conflict path list and previous refusal |
| `{{FILES}}` | adjudicate-merge | the per-file reconciliation evidence for files the mechanical file-level reconciler could not classify or preserve |

Marker decisions from the production-world cleanup are intentionally narrow: `DIFF` and
`GATE_OUTPUT` stay because agent steps can declare a boundary diff and red gates persist output;
`PLAN_CHANGE_DIFF` and `SOURCE_PLAN` stay only for the observed plan-change handler;
`SCOPED_PLAN_FILES` also reaches implementation reviews because those prompts authorize scoped
plan-file edits. `REMAINING_PLAN`, draft/situation/blocked-path markers, and `SPRINT`/`SPRINTS` have no
production artifact and stay out of shipped prompts. `REVIEW_SUBJECT`, `EXTRA_JUDGMENT`, and
`POSITION_CLAUSE` are ordinary pattern text substitutions, so they remain only where bundled patterns
provide them.

**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.

The shipped build route treats executor-declared `blocked` as a handover path: it enters a troubleshoot pass that writes the handover document, then stops. Reviewer-declared `blocked` follows the same handover path before post-review gate work, while a missing or unreadable review verdict is a failure rather than an implicit pass.

The default `build` pattern declares an `on_stop` hook for engine-forced stops: planner,
file-contract, baseline-gate, nested pattern, and integrity stops get one troubleshoot pass before
the terminal stop is recorded. The hook receives stop facts through ordinary prompt data and writes
declared outputs.
Deliberate authored `stop` steps, operator aborts, pauses, and reviewer-declared `blocked` are already
terminal and do not enter `on_stop`.

Finish-time merge repair is selected by pattern, not by prompt name. The engine owns the git merge
bracket, re-derives `conflicted`, `residue`, and `gate-red`, and invokes the selected merge pattern
inside that bracket with ordinary pattern parameters. `resolve-merge.md` and `adjudicate-merge.md`
are prompt files used by the bundled `merge.toml`; they do not grant resolver or adjudicator engine
behaviour on their own.