Read this guide as markdown

Give each step the sandbox it needs

Prompts tell a step what to do. .ampm/environment.json decides what the step can run. If your repository needs a database, a browser or any other system binary, declare the sandbox here and every step you name gets it.

Write the file

Declare one default profile plus any named profiles. Each named profile owns one or more steps.

{
  "version": 2,
  "profiles": {
    "default": {
      "backends": ["docker"],
      "docker": { "dockerfile": ".ampm/agent.Dockerfile", "context": "." },
      "resources": { "minimumMemoryMiB": 2048 },
      "checks": [{ "name": "pnpm", "argv": ["pnpm", "--version"], "expectedExitCode": 0 }]
    },
    "checks": {
      "phases": ["implement", "qa", "simulate-ci"],
      "backends": ["docker"],
      "docker": { "dockerfile": ".ampm/full-agent.Dockerfile", "context": "." },
      "resources": { "minimumMemoryMiB": 4096 },
      "checks": [{
        "name": "postgresql",
        "argv": ["/usr/local/bin/ampm-check-db"],
        "expectedExitCode": 0,
        "provides": [{ "kind": "service", "name": "postgres", "starter": "ampm-db-up" }]
      }]
    }
  }
}

  • Phases are the step names from the guidance files page. The phases a profile can own are dedup, admit, refine, breakdown, spike, plan, implement, qa, review, merge, land, deploy, grooming, ideas-grooming, followup-review, sprint-planning, promote, unpark, guidance, redraft, recheck, simulate-ci, semantic-review, feedback-review, converse, followup-recheck and followup-triage. The CI simulation's phase is simulate-ci. A phase may belong to only one profile, and any phase no profile names uses default.

  • One profile may own several phases, or several profiles may share one Dockerfile. Use separate profiles when the phases need different memory floors. For example, you might give implement 3072 MiB and qa 6144 MiB from one image.

  • Every profile needs backends, and a docker profile needs docker (dockerfile and context, with the Dockerfile inside the context). resources and checks may be left out. They default to { "minimumMemoryMiB": 2048 } and no checks. Write them out anyway. The smallest valid file is:

    {
  "version": 2,
  "profiles": {
    "default": {
      "backends": ["docker"],
      "docker": { "dockerfile": ".ampm/agent.Dockerfile", "context": "." },
      "resources": { "minimumMemoryMiB": 2048 },
      "checks": [{ "name": "node", "argv": ["node", "--version"], "expectedExitCode": 0 }]
    }
  }
}

  • minimumMemoryMiB can raise one shared memory floor for both the container's starting cap and what admission reserves for it. The platform floor is 512 MiB; the effective minimum is the higher of that floor and the selected profile's declaration. Size it to what the phase's routine checks need, and keep it under what one seat can reserve on your worker. If it cannot fit on an otherwise-idle worker after Assistant headroom, ampm fails before queueing the run and names the declared minimum, worker budget, available per-run memory, and the choices to use a larger worker or lower the declaration when the repository can safely do so.

  • checks run without network when the image is built and again at every checkout, as the image's non-root user. Keep them cheap, and make them prove the capability rather than the presence of a binary.

  • The image must work as a sandbox: a non-root user named node, with bash, node, git, and a writable home. Workers build with Docker's classic builder, so COPY --chmod is not available. An image that starts services in its ENTRYPOINT pays for them in every turn. Install PostgreSQL and Chromium if your seats need them, but start neither until a seat asks.

  • provides tells ampm what a check proves. List each tool, service or variable the check shows is present, with a starter command when it has to be started first. When a step reports one of them missing and that check passed in the same run, ampm reminds the step instead of asking you. ampm only links a report to a check through this list, and never guesses from names. Each step is also shown this list, so a step that needs Chromium asks for it as tool chromium, the name your check declares, and a starter tells it how to start a service itself. QA does not wait to be told: before its first turn, ampm runs the starter of a passed check that provides the postgres service, so Postgres suites find the database running.

When the file is wrong

A task that changes the file is checked before code review and QA. If ampm cannot read the file, or it names a Dockerfile or build context the branch does not have, the task goes back to be fixed, with each problem and its fix listed. A key the schema does not know counts as a problem.

A file that still reaches your base branch broken is reported under Settings → Repositories → Environment, and ampm files one task to fix it, linked from that page.

Older versions

A version 1 file, or a phase spelled the way it was before a rename, is still read exactly as it always was. When ampm reads one, it files a low-priority task with the exact current-version file to replace it with. The environment it describes does not change.

How a change reaches your workers

A changed environment file or Dockerfile does nothing by itself. It reaches workers as an environment-change approval. Once you approve it, the worker builds every profile, and the new map replaces the old one only when all of them pass their checks.

If the newest approved revision fails, Rebuild retries its unfinished profiles. A lost response can be retried with the same request identity without starting another build. The request keeps its original run through completion or interruption. A later explicit rebuild after interruption starts a new attempt; an old retry never restarts finished work. Verify for the workspace also keeps one request identity: retrying the same request checks its original builds without starting another batch or requesting the same waiting-task releases again. If the assigned worker changes, inspect the recorded request and explicitly request verification on the new worker.

When .ampm/environment.json or one of its Dockerfiles changes on your base branch, ampm reads the new definition and asks you to approve it. You don't report anything. A task's own landing is read at once. Any other change, such as a PR merged outside a task, a push, a revert or a dependency bump, is read within a few minutes. Check again now under Settings → Repositories → Environment reads the newest commit immediately.

The approval shows the Dockerfile and its FROM lines as written. ampm does not resolve a tag to a digest, so write FROM image@sha256:… where you want the base pinned.

If your build context is the whole repository (.), a change to a file the Dockerfile copies in is not noticed unless the manifest or the Dockerfile also changes. Give the image a build context of its own to have those changes noticed.

Prove the sandbox on an onboarding pull request

On an onboarding task, ampm builds and checks the sandbox before the pull request can merge. You approve the branch's Dockerfiles once, on a card that names the branch and its head commit. The worker then builds every profile and runs every check. Any failure goes back to the onboarding task with the profile, the build log and the failing check. If you decline the card, the task goes back with your reason.

Changing the environment file, a Dockerfile it names, or a build-context folder other than the repository root asks for approval again. A commit that touches none of them keeps the earlier approval and build.

The onboarding task's own QA and CI simulation then run in that sandbox, using the profile assigned to the step or default, so the pull request proves the environment it adds. They use it only while it is the task's latest build, it passed its checks, and it still matches the environment file, Dockerfiles and build-context folders on the branch or pull request head. Otherwise they run in the repository's current environment. The run record and the step's brief name the revision and the profile. No other task, and no other step of the onboarding task, uses the branch build.

When the onboarding pull request merges with the same definition, that approved build becomes the repository's environment. You are not asked a second time and the worker does not build it again. If the merged definition differs in any way, for example after a conflict resolution, the ordinary environment-change approval is filed and the branch build is not used. If GitHub cannot be read at the moment of the merge, the next look at the base branch files the ordinary approval. Other tasks are unchanged: they build an environment only after it merges.

Manual environment reports, Check again now, and Ask again for an environment need keep a request receipt. Retrying a lost response recovers that request without filing another proposal, reopening a need again, or reading GitHub again. A recovered older inspection does not replace the repository's latest inspection. Report bodies stay out of browser storage; keep the page open to recover an uncertain report, or check request history before submitting a new report after reload.