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. Write The Source Material Into The Body

Put every path a mission must read into the prompt body, under ## Required Reading:

## Required Reading

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

Use absolute paths when the prompt spans repositories — the session's working directory is the first entry in targets:.

Front-matter references, required_reading, context_files, and depends_on look like the natural home for this and are not. They are parsed, stored on PromptRunner.Prompt, and never read: never sent to the provider, never used for ordering. Only the markdown body reaches the model, and scheduling comes from the numeric filename prefix.

mix prompt_runner packet lint reports any prompt still carrying them.

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."
  commands:
    - "timeout 120 test -s RUNTIME_BOUNDARIES.md"
  changed_paths_only:
    - "RUNTIME_BOUNDARIES.md"

Use:

  • files_exist for required outputs
  • contains or matches for important content
  • doc when the deliverable is a written document and files_exist would be satisfied by a stub
  • commands when repo-local checks are stronger than file inspection, always wrapped in timeout
  • changed_paths_only to stop collateral edits when the runner owns the commit
  • repos_clean instead, when the packet runs with --no-commit and each session commits its own work

See Verification And Repair for the full clause reference.

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. Lint, Doctor, And Preflight Before Run

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

Lint reports authoring hazards — an id that does not match its filename prefix, a verify command with no timeout, a target naming a repo that does not exist, a typo'd verify clause. All of those load and run and quietly mean something else. See Packet Linting.

Doctor flags authoring gaps:

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

Preflight is the runtime gate that checks packet-local repo paths and git readiness, and run calls it automatically.

9. Run And Iterate

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

If verification fails after a nominal provider success, Prompt Runner repairs the prompt automatically while the repair budget lasts, then fails with the unmet verifier items.

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, source material, and verify: contracts
  • verify the override does what you expect with mix prompt_runner plan runtime-review --provider codex
  • rerun packet lint, packet doctor, packet preflight, plan, and run
  • for a long run, supervise it with mix prompt_runner watch runtime-review

Best Practices

  • keep source docs inside the packet when possible
  • write every path a mission must read into the prompt body, not into inert front-matter keys
  • make prompt boundaries correspond to reviewable outputs
  • treat verify: as part of the prompt, not cleanup work
  • wrap every verify.commands entry in timeout
  • use packet-local templates for shared team authoring patterns
  • use the authoring example in examples/authoring_packet/ as a reference