Packet Manifest Reference

Prompt Runner 0.7.0 uses two primary authoring files:

• prompt_runner_packet.md
• *.prompt.md

Both are markdown documents with YAML front matter.

Optional supporting authoring files include:

• templates/*.prompt.md
• packet-local docs such as docs/*.md

Packet Manifest

Recommended filename:

• prompt_runner_packet.md

Example:

---
name: "demo"
profile: "codex-default"
prompt_template: "from-adr"
provider: "codex"
model: "gpt-5.4"
reasoning_effort: "xhigh"
permission_mode: "bypass"
allowed_tools:
  - "Read"
  - "Edit"
  - "Write"
  - "Bash"
cli_confirmation: "require"
recovery:
  resume_attempts: 2
  retry:
    max_attempts: 3
    base_delay_ms: 1000
    max_delay_ms: 30000
    jitter: true
  repair:
    enabled: true
    max_attempts: 2
    trigger_on_nominal_success_with_failed_verifier: true
    trigger_on_provider_failure_with_workspace_changes: true
    trigger_on_retry_exhaustion_with_workspace_changes: true
repos:
  app:
    path: "./workspace"
    default: true
phases:
  "1": "Bootstrap"
  "2": "Wrap Up"
---
# Demo Packet

Packet Keys

Core keys:

• name
• profile
• prompt_template
• repos
• phases
• recovery

Shared execution keys:

• provider
• model
• permission_mode
• allowed_tools
• timeout
• log_mode
• log_meta
• events_mode
• tool_output

Provider-specific keys:

• adapter_opts
• sdk_opts
• claude_opts
• codex_opts
• codex_thread_opts
• amp_opts
• cursor_opts
• antigravity_opts
• system_prompt
• append_system_prompt
• max_turns
• cli_confirmation

Prompt Front Matter

Recommended filename pattern:

• 01_create_hello.prompt.md

Example:

---
id: "01"
phase: 1
name: "Create hello file"
template: "from-adr"
targets:
  - "app"
commit: "docs: add hello file"
references:
  - "docs/adr-001-runtime-boundaries.md"
required_reading:
  - "docs/adr-001-runtime-boundaries.md"
context_files:
  - "workspace/README.md"
depends_on: []
provider: "codex"
model: "gpt-5.4"
verify:
  files_exist:
    - "hello.txt"
  contains:
    - path: "hello.txt"
      text: "Hello from Prompt Runner"
  changed_paths_only:
    - "hello.txt"
---
# Create hello file

## Mission

Create `hello.txt` with exactly one line: `Hello from Prompt Runner`.

Prompt Keys

Scheduling and identity:

• id
• phase
• name
• template
• targets
• commit
• references
• required_reading
• context_files
• depends_on

Prompt-local execution overrides:

• provider
• model
• reasoning_effort
• permission_mode
• recovery
• allowed_tools
• sdk_opts
• adapter_opts
• claude_opts
• codex_opts
• codex_thread_opts
• amp_opts
• cursor_opts
• antigravity_opts
• cli_confirmation
• timeout
• system_prompt
• append_system_prompt
• max_turns

Completion contract:

• verify
• simulate

Prompt-local recovery is deep-merged onto the packet default. Use it when a single prompt needs a tighter or more generous retry/repair budget than the rest of the packet.

Example:

recovery:
  retry:
    class_attempts:
      provider_runtime_claim: 1

Completion Contract Keys

Prompt Runner 0.7.0 supports:

• files_exist
• files_absent
• contains
• matches
• commands
• changed_paths_only

Entries can be repo-scoped:

verify:
  files_exist:
    - repo: "alpha"
      path: "NOTES.md"

Generated Checklist Files

mix prompt_runner checklist sync converts the deterministic contract into a human-readable checklist file next to each prompt.

The checklist is derived output, not the source of truth.

If a prompt still has no verifier items, checklist sync prints a warning and the generated checklist explicitly says that verification items are still missing.

mix prompt_runner packet preflight reports runtime readiness as JSON and exits non-zero when packet-local repos or git state are not ready. run calls this gate before invoking a provider unless --skip-preflight is explicit.

mix prompt_runner packet doctor also reports common authoring gaps:

• packet has no prompts
• packet has no default repo
• prompt has no targets
• prompt has no verification items
• prompt still contains scaffold placeholder markers

Simulated Provider Scripts

When provider: "simulated" is active, prompts can define deterministic recovery scripts:

simulate:
  attempts:
    - error:
        kind: "provider_capacity"
        message: "Selected model is at capacity. Please try again."
    - writes:
        - path: "retry.txt"
          text: "retry ok"
  resume:
    writes:
      - path: "resumed.txt"
        text: "resumed ok"

Supported simulation keys:

• attempts
• resume

Each step can include:

• messages
• writes
• error
• error.recovery