Tell ampm's agents how your repository works

Add markdown files under .ampm/ in your repository, and the agents that work on it follow them. You don't touch ampm to do this. The files are an ordinary code change: they go through your normal review, and agents pick up the new text on the next run against a checkout that contains it.

Layout

your-repo/
└── .ampm/
    ├── personas/
    │   └── {role}.md    # who the seat is: appended to the role's system prompt
    ├── steps/
    │   └── {step}.md    # what the step does: appended to the step's task prompt
    ├── environment.json         # the sandbox each step runs in
    ├── serializing-paths.json   # PRs that always collide
    ├── ci-evidence.json         # which CI checks Autopilot may merge on
    └── diff-risk.json           # which changed paths make a merge higher risk

Both folders are optional, every file is optional, and a missing file changes nothing. This page covers the two folders of markdown guidance. The JSON files each have their own page:

Role and step names

Persona files are named after a role (the seat), and step files after a step. Settings → Prompts lists every shipped role and step.

role (personas/)	step (steps/)	the seat's job
`dedup`	`dedup`	intake duplicate check
`admit`	`admit`	the GO / NO-GO call on accepting an item at all
`spike`	`spike`	throwaway-branch research
`refine`	`refine`	shape a raw item into a story
`breakdown`	`breakdown`	decompose too-big work into pieces
`planner`	`plan`	plan the change and name the repository's affected published docs
`implementer`	`implement`	implement the plan and rewrite affected published docs
`qa`	`qa`	verify the change, including its published docs
`reviewer`	`review`	review the change and block missing or stale published docs
`deploy`	`deploy`	do what "releasing" means here
`land`	`land`	post-merge follow-up filing
`grooming`	`grooming`	scheduled backlog hygiene
`ideas-grooming`	`ideas-grooming`	curate the idea shelf so it stays worth reading
`sprint-planning`	`sprint-planning`	plan the next two sprints
`promote`	`promote`	pick which ideas earn refinement
`unpark`	`unpark`	glance at every parked task for a cleared blocker
`guidance`	`guidance`	cluster guidance gaps into proposed documentation work
`redraft`	`redraft`	rewrite pending follow-ups the operator sent back
`recheck`	`recheck`	investigate one parked task's blocker, deeply
`followup-recheck`	`followup-recheck`	check whether a pending follow-up's cause still holds
`followup-triage`	`followup-triage`	fold and vet one origin's pending follow-ups before you rule
`simulate-ci`	`simulate-ci`	say what this exact change needs before merge, and what was run
`change-review`	`semantic-review`	review an operator-requested change to a task, settling changes to a task already split into child tasks against its children
`feedback-review`	`feedback-review`	find a shared, fixable cause across the factory's own failures
`converse`	`converse`	the workspace Assistant and Autopilot, reasoning over the board

Role and step names match everywhere except four places, so check the step column before you name a step file. The planner role runs the plan step, implementer runs implement, reviewer runs review, and change-review runs semantic-review. For every other seat, the persona file and the step file share one name.

Two older names still work. .ampm/personas/failure-review.md and .ampm/steps/failure-review.md are read as a fallback for feedback-review, and .ampm/steps/build.md is read as a fallback for implement. When both an old and a new file exist, the new one wins. ampm logs a warning that names the rename, so rename your file to stop depending on the fallback.

.ampm/steps/simulate-ci.md is where a repository states its CI mandate. The CI-simulation seat picks the smallest credible evidence set from the diff and defers to stricter repository guidance. If your simulation is the same few commands every time, list them there as a command list (see below).

How your files combine with ampm's prompts

Each seat's instructions come in two layers:

ampm's shipped persona: the seat's generic craft standards, read-only under Settings → Prompts.
Your .ampm/personas/{role}.md, which is appended after the shipped persona. It adds and never replaces.

A step file works the same way. It is appended to the end of the step's task prompt, under a heading that names the file it came from. The shipped step prompt (also read-only under Settings → Prompts) plus your append is the whole stack.

Guidance comes only from these repository files, and it is append-only. There is no workspace-level override for personas or steps. Models and effort levels are workspace settings, not guidance, so a repository cannot change which model runs or how hard it thinks.

Your step file is written in the same medium as the shipped one. Read the shipped prompt in Settings → Prompts before you write yours, because your text follows it.

What to write

Use .ampm/ for guidance that is too specific to one seat or step for AGENTS.md or CLAUDE.md. Those files speak to every agent generically and always outrank generic best practice. .ampm/ speaks to particular seats and steps. For example:

<!-- .ampm/personas/reviewer.md -->
- This service returns Result values; a `throw` crossing a service boundary is always a revision.
- Check the RLS policies on any migration touching a tenant table.

<!-- .ampm/steps/plan.md -->
Plans must name the affected OpenAPI operations and state whether the change is
backward-compatible on the wire.

A command list for the CI simulation

If your simulation is the same few commands every time, list them in .ampm/steps/simulate-ci.md and ampm runs them itself. An agent gets involved only when a command fails, to work out why, so a run where everything passes uses no agent time. Put the list in one fenced block whose info string is ampm-ci-commands:

```ampm-ci-commands
[
  { "name": "typecheck", "command": "pnpm typecheck" },
  { "name": "test", "command": "pnpm test" },
  { "name": "browser", "command": "pnpm e2e", "paths": ["web/**"] }
]
```

An entry is a name, one shell command, and optionally paths, a list of globs: the entry runs only when the change touches a matching path. Entries run in order, every one runs even after another fails, and exit code 0 is a pass. ampm never reads the output. The report has one row per command with its exit code, duration and the end of its log. If any command failed, one agent turn looks at all the failures together. Keep your advice for failures (flaky tests, memory limits, breakages the base branch already has) in the prose around the block, because that is what the agent reads.

ampm is not a CI platform. It runs your commands in the sandbox your repository already has and nothing else. An entry cannot set environment variables, timeouts, retries, parallelism, dependencies, matrices, services, caching, artifacts or secrets, and ampm never imports another CI system's config. Put anything more in your own scripts. Your database starts from the starter your environment declares, before the first command, never from an entry. A command that must fail under some condition fails through its exit code.

A command that already passed on this exact commit is not run again, but only when it is one of your repository's required checks. Everything else, such as installing dependencies, runs each time. An entry with an unknown field, a list that is not valid, or an entry with no command fails the simulation with a report that names the problem. It never falls back to the prose. A file with no list works as before.

You don't have to work out what belongs here from scratch. A seat that needs guidance you never wrote down does its best anyway and reports the gap. Those reports collect in a guidance-gap list, a daily pass groups related entries, and each group arrives in your inbox as one approval you can edit before ratifying. Approving it creates an ordinary task to write the missing guidance, and the change reaches you as a reviewed pull request like any other.

Limits

Each file has a soft size cap of 16 KiB. Longer files are cut off at the end without a warning. Keep them short, because they ride into every matching agent turn.
A file ampm cannot read is treated as absent. Guidance never fails a step.
The text is plain data, like the plan document. It cannot grant tools, change models or effort, or get past a gate.