Step reference

All eight step types — prompt, check, command, git, notify, publish, preview, loop — with every field.

Eight step types cover the pipeline. Steps run in order within their phase; prompt-driven steps (prompt, publish, preview) accept a per-step agent override.

prompt — hand the agent an instruction

- type: prompt
  prompt: Implement the approved spec.
  persona: engineer        # optional — see Personas
  allowQuestions: true     # optional — may ask you mid-run questions
  agent: { provider: claude, model: opus-4.8, effort: high }

Peractor prepends the task itself — title, description, attachment paths — so write prompts against "the task", not a restatement of it. Long instructions can live in a shared markdown file instead: promptFile: prompt/spec.md. The closing message of a phase's last prompt step becomes the phase summary used in the pull request and commit message.

check — verification that must pass

- { type: check, name: test, run: pnpm test }

Runs a command in the workspace. On failure the output goes back to the preceding prompt's agent with a fix instruction — root-cause fixes, not disabling the check — for up to two attempts; still red, the phase fails and parks at its gate for a human. A check needs a preceding prompt step in its phase (someone has to be there to fix it).

command — a step that just runs

- { type: command, name: install, run: pnpm install }

Same shape as check, different contract: a failure here is your problem, not the agent's — the phase halts rather than asking the agent to fix your infrastructure. Commands run at the workspace root with the run's environment (declared secrets, the git token as GITHUB_TOKEN).

git — VCS actions, where you declare them

- { type: git, action: open-pr, draft: true }
- { type: git, action: ready-pr }
- { type: git, action: merge, method: squash }   # merge | squash | rebase

Branching and committing are automatic — phases commit and push on completion — so git steps are for the VCS side-effects: open-pr (optionally draft), ready-pr to undraft, merge into main. Each runs at its declared position: work so far is committed and pushed first, then the control plane performs the action with its own credentials — so "open a draft PR early, keep working, undraft at the end" behaves exactly as written. See Git & credentials.

notify — tell the team

- type: notify
  to: [slack, telegram]    # slack | discord | telegram | teams | googlechat | mattermost | webhook
  message: Spec is ready for review

Posts your message through the named notifier connectors, threaded under the run's notification thread. Channels come from each connector's own configuration — the step never picks one. Notify steps send at phase end, only when the phase succeeded, and an outage never fails a run.

publish — render and deliver artifacts

- type: publish
  to: [issue, pr, notify]
  prompt: Render each design/ui page to a PNG with a headless browser you install.

A prompt run whose job is to produce reviewable artifacts — screenshots, diagrams, rendered pages — and list them in a manifest. On phase success Peractor delivers them to the tracker issue, the pull request, and/or your notifiers. See Artifacts & previews for the manifest contract.

preview — park the run at a live URL

- type: preview
  name: live preview
  prompt: Serve the built site.

The agent starts a server on the sandbox's reserved port (PERACTOR_PREVIEW_PORT; a static serve is pre-installed), and the run parks with the result reachable at a per-run URL — reviewers click around the real thing, then Continue or Request changes. The sandbox is held open while parked, with a 30-minute ceiling (timeout counts as continue). Use an inline prompt on preview steps.

loop — iterate until it's actually done

- type: prompt
  prompt: Implement the task with tests.
  id: impl                   # loop target
- { type: check, name: tests, run: pnpm test }
- type: loop
  to: impl
  until: checks-pass         # checks-pass | agent-verdict, or both
  max: 4                     # default 3
  onMax: fail                # fail (default) | continue

A bounded back-edge inside the phase: while the condition is unmet, execution jumps back to the target step, threading the failing output into the next attempt. checks-pass means every check and command in the body went green; agent-verdict asks the body's last prompt to declare done — combine them and the loop runs until both hold. At max, fail parks the phase at its gate; continue moves on regardless. Loops can't nest or overlap, and never leave their phase.