Gantry · The write-map-spec prompt

What this prompt is

id	write-map-spec	the key every tier, every pattern step and every override spells it by
kind	not a stage instruction	whether any bundled pattern hands it to an agent step
role	—	the harness role the agent reading it runs under
stage	—	the stage of a run it is handed at
bundled at	config/agent-prompts/write-map-spec.md	where the built-in copy sits in Gantry's own tree

No bundled pattern hands this file to an agent step. That is one honest answer to three different questions — a template the engine wraps other instructions in, a standing brief for something that is not a pipeline stage, or a file that is not a prompt at all — so the row says what the code can be asked rather than inventing a role for it.

Where an override of it goes

tier	the file to write	what it is
run consulted 1st	`.gantry/<plan>/prompts/write-map-spec.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-map-spec.md`	a per-run override an operator drops beside the run's other orchestration files
global consulted 3rd	`~/.config/gantry/agent-prompts/write-map-spec.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-map-spec.md`	the default compiled into the binary

The text

config/agent-prompts/write-map-spec.md

You are the map-spec planner for this Gantry run. Read the prose fan-out request below and inspect the repository. Author the machine-readable map spec and its support prompt files for the run.

Prose request:

{{PLAN}}

{{REPAIR_CONTEXT}}

Write only these files, all under the run orchestration directory `{{ORCH}}`:

- `{{MAP_SPEC}}`
- `{{MAP_WORKER_PREAMBLE}}`
- `{{MAP_CHECKPOINT}}` only if you include a `[checkpoint]` section

Do not run the fan-out and do not change production code. The generated spec must use Gantry's existing map-spec format: top-level `enumerate`, `prompt`, `preamble`, `artifact`, a `[gate]` section with `command` and `skip_test`, and optionally `[checkpoint]` with a `prompt`. The checkpoint has no cadence field: how often it fires is a fixed property of the map pattern, not something you set in the spec.

The planner authors the machine, not the work list. `enumerate` must be a deterministic command that derives units from real repository data at run time. Never emit a literal list of units that you composed yourself, even if wrapped in `printf`, `echo`, a here-doc, a tiny script, or a generated static data file.

Map commands are argv-style command lines. Gantry tokenizes and spawns them directly without a shell, so pipes, `&&`, redirects, variables, and shell globs do not work unless the command explicitly invokes a shell, such as `sh script.sh`.

Reference the support files through stable worktree-relative paths. The spec's `preamble` must be `{{MAP_WORKER_PREAMBLE}}`. If you include `[checkpoint]`, its `prompt` must be `{{MAP_CHECKPOINT}}`.

The worker preamble you write is a *template*, and it must contain the literal marker `{{ENVIRONMENT}}` on a line of its own. Gantry replaces that marker with the run's environment section — the worktree path, the canonical repository, the orchestration directory, the sandbox mode, and the run's environment briefing — before handing the preamble to each unit worker as its system prompt. A preamble without the marker is rejected. Put it where a reader would want those facts, normally under a short heading near the top and ahead of the task-specific instructions, and write nothing around it: do not restate the worktree path, the sandbox mode, or anything else the section already carries.