Templates

Prompt Runner 0.9.0 uses template-based prompt scaffolding.

Templates are markdown files with YAML front matter. They define:

• prompt metadata defaults
• authoring sections in the prompt body
• placeholder markers that packet doctor can detect until you replace them

Where Templates Live

Home-scoped templates:

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

Packet-local templates:

demo/
  templates/
    from-adr.prompt.md

Resolution order when you create a prompt:

1. prompt new --template ...
2. packet prompt_template
3. home templates
4. built-in default template

Packet-local templates override home templates with the same name.

Initialize The Template Store

mix prompt_runner init
mix prompt_runner template list

init creates editable home templates if they do not already exist.

Use A Template

Set a packet-wide default:

mix prompt_runner packet new demo \
  --prompt-template from-adr

Or choose a template for one prompt:

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

You can also point directly at a file:

mix prompt_runner prompt new 02 \
  --packet demo \
  --phase 1 \
  --name "Review contracts" \
  --template /path/to/custom.prompt.md

Template Format

Example:

---
verify:
  files_exist: []
  contains: []
  commands: []
---
# {{name}}

## Required Reading

<!-- prompt_runner:placeholder required_reading -->
- Add ADRs and design docs here.

## Mission

<!-- prompt_runner:placeholder mission -->
Describe the exact work to perform.

Prompt Runner merges generated prompt attributes such as id, phase, targets, and commit into the template front matter.

Supported body placeholders:

• {{id}}
• {{phase}}
• {{name}}
• {{commit}}
• {{targets_csv}}
• {{targets_bullets}}

Placeholder Markers

The marker:

<!-- prompt_runner:placeholder ... -->

is intentional.

mix prompt_runner packet doctor flags prompts that still contain placeholder markers so incomplete scaffolds are loud before you run the packet.

mix prompt_runner packet lint is the separate authoring-hazard check, and mix prompt_runner packet preflight the separate runtime readiness check. Run setup first when a packet creates local repos or workspaces, then run preflight before provider execution.

Keys Templates Deliberately Omit

Before 0.9.0 both built-in templates scaffolded references, required_reading, context_files, and depends_on. They no longer do, because none of them is read at runtime: they are parsed, stored on PromptRunner.Prompt, and never sent to the provider or used for ordering. Scaffolding a key the runtime ignores teaches the wrong habit on the first prompt someone writes.

Put required reading in the body, under ## Required Reading, where the model will actually see it. mix prompt_runner packet lint warns about any prompt still carrying the front-matter forms.

Recommended Practice

• use home templates for personal defaults
• use packet-local templates when a packet needs a shared authoring shape
• keep verify: skeletons in the template, including an empty commands: list as a reminder that files_exist alone is satisfied by an empty file
• replace placeholder markers before running real work
• run mix prompt_runner packet lint --strict before a real run

If you created home templates with an earlier release, they still contain the inert keys. mix prompt_runner packet lint will point at the prompts they generate; edit ~/.config/prompt_runner/templates/*.prompt.md to drop them.