Skip to content

Prompts

PAI is built by agents. This document is the map to the prompts that drive those agents — what exists, how the trees are organized, and the rules for authoring new prompts.

For an overview of the agents themselves and how they consume these prompts, see AGENTS.md.

The two prompt trees

PAI maintains two distinct, non-overlapping prompt trees.

1. Build prompts — /prompts/NN-*.md

One numbered Markdown file per build step. An agent (human or AI) executes these in numeric order to produce the PAI ISO. Each prompt is a self-contained unit of work: the agent reading it should be able to carry out the step without hunting for context elsewhere.

2. Documentation prompts — /prompts/documentation/*.md

One file per documentation-writing task. Each file is executed by a single agent in a single session to produce a specific set of top-level docs (README.md, CHANGELOG.md, etc.). These prompts describe what to write, not what to build.

The two trees never cross-drive each other: a build prompt does not write prose docs, and a documentation prompt does not modify the ISO.

Authoring rules — build prompts

A good build prompt is executable by a cold agent. Follow these rules when adding or editing any prompts/NN-*.md file:

  1. Self-contained context. State the goal, the prerequisite state (which earlier prompts must have run), and any environment variables or paths the step depends on. Do not rely on the reader having followed the conversation.
  2. Exact commands. Paste the precise shell commands to run, with correct quoting. No pseudo-code, no "run the usual build step."
  3. Idempotence notes. Call out whether re-running the step is safe. If it is not, document how to roll back or how to detect that the step has already been applied.
  4. Acceptance criteria. End with a checklist the agent uses to verify success (files exist, services enabled, hashes match, etc.).
  5. Cross-references. Link to the prompts this one depends on and the prompts that consume its output. Link to TOOLS.md when introducing a new tool, and to ARCHITECTURE.md when touching structural decisions.
  6. Numbering discipline. The NN- prefix defines execution order. Do not renumber existing prompts casually — downstream prompts and scripts may reference them by number.

See prompts/README.md for the directory layout and prompts/INDEX.md for the authoritative ordered list.

Authoring rules — documentation prompts

Documentation prompts follow the conventions laid out in prompts/documentation/INDEX.md. The essentials:

  1. One agent, one session, one prompt. Each prompt must be completable by a single agent without handoff.
  2. Name the deliverables explicitly. List every file the agent will create or modify, with full paths.
  3. Describe shape, not prose. Specify structure (headings, sections, tables, front-matter) rather than writing the copy itself.
  4. Point at sources of truth. If the agent needs facts about the build, refer it to prompts/NN-*.md; if it needs project metadata, refer it to existing top-level files rather than restating.
  5. Deliverable checklist. End with a checkable list the agent uses to confirm every file was produced and cross-linked.

Where to go next