From ADRs To Packets

Copy Markdown View Source

This guide covers the actual authoring journey:

  • you have source docs and ADRs
  • you have one or more target repos
  • you do not yet have finished prompts

1. Start With A Packet

Initialize Prompt Runner once:

mix prompt_runner init

Create a packet and register repos up front:

mix prompt_runner packet new runtime-review \
  --profile simulated-default \
  --provider simulated \
  --model simulated-demo \
  --repo core=/path/to/core \
  --repo asm=/path/to/agent_session_manager \
  --default-repo core \
  --prompt-template from-adr

Why start with simulated? Because it lets you prove the packet shape and verification contracts without requiring any external CLI or credentials.

Once the packet is solid, switch the provider to Codex, Claude, Amp, Cursor, or Antigravity.

2. Put Source Material Inside The Packet

Create a docs directory inside the packet:

runtime-review/
  docs/
    adr-001-runtime-boundaries.md
    adr-002-recovery-contract.md

This keeps prompt references stable and reviewable.

3. Split Work Into Prompts

A good prompt boundary usually has:

  • one primary output
  • a clear repo target set
  • a verification contract you can explain in one screen
  • a commit message that makes sense on its own

Bad split:

  • one giant prompt that edits many unrelated outputs

Good split:

  • one prompt captures the architecture summary
  • one prompt creates the execution checklist
  • one prompt updates a specific implementation surface

4. Scaffold Prompts From A Template

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

If the packet has prompt_template: "from-adr", that template is used automatically. Otherwise pass --template.

5. Fill In The Planning Metadata

Use these prompt keys:

  • references
  • required_reading
  • context_files
  • depends_on

Example:

references:
  - "docs/adr-001-runtime-boundaries.md"
required_reading:
  - "docs/adr-001-runtime-boundaries.md"
context_files:
  - "workspace/README.md"
depends_on:
  - "01"

These keys are descriptive. They do not directly change runtime semantics, but they make prompts self-describing and reviewable.

6. Translate Deliverables Into verify:

Do not stop at prose. Add a deterministic contract.

Typical pattern:

verify:
  files_exist:
    - "RUNTIME_BOUNDARIES.md"
  contains:
    - path: "RUNTIME_BOUNDARIES.md"
      text: "Prompt Runner owns packet orchestration."
  changed_paths_only:
    - "RUNTIME_BOUNDARIES.md"

Use:

  • files_exist for required outputs
  • contains or matches for important content
  • commands when repo-local checks are stronger than file inspection
  • changed_paths_only to stop collateral edits

7. Generate Checklist Views

mix prompt_runner checklist sync runtime-review

Checklist files are for humans. The source of truth is still the verifier contract plus .prompt_runner/state.json.

If a prompt has no verifier items yet, checklist sync warns loudly.

8. Preflight And Doctor Before Run

mix prompt_runner packet preflight runtime-review
mix prompt_runner packet doctor runtime-review

Preflight is the runtime gate that checks packet-local repo paths and git readiness. Doctor includes the same runtime readiness fields plus authoring guidance. Doctor flags common authoring gaps:

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

9. Run And Iterate

mix prompt_runner list runtime-review
mix prompt_runner plan runtime-review
mix prompt_runner run runtime-review
mix prompt_runner status runtime-review

If verification fails after a nominal provider success, Prompt Runner can repair the prompt automatically when recovery is enabled.

10. Move To A Real Provider

Once the packet structure is stable:

  • switch profile/provider/model in prompt_runner_packet.md
  • keep the same prompts, references, and verify: contracts
  • rerun packet preflight, packet doctor, plan, and run

Best Practices

  • keep source docs inside the packet when possible
  • make prompt boundaries correspond to reviewable outputs
  • treat verify: as part of the prompt, not cleanup work
  • use packet-local templates for shared team authoring patterns
  • use the authoring example in examples/authoring_packet/ as a reference