Getting Started

This guide targets prompt_runner_sdk ~> 0.9.0.

Install

def deps do
  [
    {:prompt_runner_sdk, "~> 0.9.0"}
  ]
end

mix deps.get

Provider Credentials

Set the CLI credentials your chosen provider expects:

Gemini CLI support is retired. Antigravity is the current Google coding-agent provider; gemini_ex is a separate model API SDK.

For local recovery demos, you can skip provider credentials entirely and use the built-in simulated provider.

Initialize Prompt Runner

Initialize the home-scoped profile store once:

mix prompt_runner init
mix prompt_runner template list

This creates:

~/.config/prompt_runner/
  config.md
  profiles/
    codex-default.md
    simulated-default.md
  templates/
    default.prompt.md
    from-adr.prompt.md

Create A Packet

Start with the simulated path first so you can prove the packet shape and verification contracts without any external CLI setup:

mix prompt_runner packet new demo \
  --profile simulated-default \
  --provider simulated \
  --model simulated-demo \
  --repo app=/path/to/repo \
  --default-repo app \
  --prompt-template from-adr

mix prompt_runner prompt new 01 \
  --packet demo \
  --phase 1 \
  --name "Capture runtime boundaries" \
  --targets app \
  --commit "docs: add runtime boundaries summary"

The new prompt is created from the selected template. You should then edit it to add source material and a deterministic verifier contract.

For a finished example of this authoring flow, see examples/authoring_packet/.

Optional: Create A Ready-To-Demo Recovery Packet

If you want the recovery walkthrough specifically:

mix prompt_runner packet new recovery-demo \
  --profile simulated-default \
  --provider simulated \
  --model simulated-demo \
  --permission bypass

That creates:

demo/
  prompt_runner_packet.md
  templates/
  prompts/
    01_capture_runtime_boundaries.prompt.md

Add Source Material And A Deterministic Contract

Edit demo/prompts/01_capture_runtime_boundaries.prompt.md:

---
id: "01"
phase: 1
name: "Capture runtime boundaries"
template: "from-adr"
targets:
  - "app"
commit: "docs: add runtime boundaries summary"
verify:
  files_exist:
    - "RUNTIME_BOUNDARIES.md"
  contains:
    - path: "RUNTIME_BOUNDARIES.md"
      text: "Prompt Runner owns packet orchestration."
  commands:
    - "timeout 60 test -s RUNTIME_BOUNDARIES.md"
  changed_paths_only:
    - "RUNTIME_BOUNDARIES.md"
---
# Capture runtime boundaries

## Required Reading

- `docs/adr-001-runtime-boundaries.md`

## Mission

Read ADR 001 and create `RUNTIME_BOUNDARIES.md` in the target repo.

## Deliverables

- `RUNTIME_BOUNDARIES.md` summarizing the runtime boundary split

## Non-Goals

Do not modify any other files. Respond with exactly `ok`.

Two things to notice, because both are easy to get wrong:

• Required reading goes in the body. Only the markdown after the front matter reaches the model; the required_reading: front-matter key is parsed, stored, and never sent anywhere.
• Every commands: entry is wrapped in timeout. The verifier runs commands through bash -lc with no timeout of its own, so a hung command hangs the whole run after the model work is already spent.

mix prompt_runner packet lint reports both mistakes.

Generate the checklist view and check the packet:

mix prompt_runner checklist sync demo
mix prompt_runner packet lint demo
mix prompt_runner packet doctor demo
mix prompt_runner packet preflight demo

Inspect And Run

mix prompt_runner list demo
mix prompt_runner plan demo
mix prompt_runner run demo --dry-run
mix prompt_runner run demo
mix prompt_runner status demo

plan takes the same override flags as run, so mix prompt_runner plan demo --provider simulated shows the plan that override would actually build. run --dry-run prints the per-prompt execution details and starts nothing.

status prints .prompt_runner/state.json as formatted JSON.

For a long run, supervise it from a second pane:

mix prompt_runner watch demo
# WATCH 16:57Z runner=UP prompt=11 quiet=0min repos=1 dirty=0 commits=27

packet preflight is the runtime readiness gate that run calls before a provider starts. If a packet uses generated or packet-local repos, run the packet's documented setup command before preflight. Use --skip-preflight only when you intentionally want provider execution to handle readiness failures.

What Gets Created At Runtime

CLI packet runs create:

demo/
  .prompt_runner/
    state.json
    progress.log
    logs/

API runs default to in-memory state plus a no-op committer unless you opt into file-backed state or git commits.

Next Steps

• From ADRs To Packets
• CLI Guide
• API Guide
• Packet Manifest Reference
• Templates
• Profiles
• Simulated Provider
• Verification And Repair
• Packet Linting
• Supervising A Long Run
• Examples