---
icon: lucide/messages-square
---

# Prompt Contract

This page defines the canonical contract for prompts in the docs-first MCP architecture.

## Canonical Prompt Shape

Each prompt is one directory under `docs/prompts/`:

```mermaid
---
config:
    treeView:
        rowIndent: 20
        lineThickness: 2
    themeVariables:
        treeView:
            labelColor: '#FFFFFF'
            lineColor: '#FFFFFF'
---
treeView-beta
    "docs/"
      "... (other docs)"
      "prompts/"
        "<prompt-id>/"
          "PROMPT.md"
          "references/"
            "... (one or more markdown files, optional nested folders)"
```

Rules:

1. `PROMPT.md` is required for every prompt.
2. `references/` is the only place for prompt-specific supporting docs.
3. Nested folders inside `references/` are allowed so a prompt can reorganize internals without changing global architecture.
4. Prompt directories are independent ownership boundaries; no cross-prompt file writes.

## Metadata Location Constraint

1. Prompt metadata is embedded in YAML frontmatter in `PROMPT.md`.
2. No `metadata.yaml` sidecar exists in the end state.
3. Reference lookup metadata is documented and explicit: top-level `references/*.md` are auto-discovered from filenames, while `PROMPT.md` frontmatter declares overrides and nested mappings when needed.

## Prompt Id Contract

`prompt-id` is the public identifier and should satisfy all rules below:

1. Format: lowercase kebab-case only.
2. Character set: `a-z`, `0-9`, and `-`.
3. Must start with a letter.
4. No underscores, spaces, dots, or uppercase characters.
5. Directory name should equal `prompt-id` in each committed revision.
6. Frontmatter `id` should equal directory name in each committed revision.
7. Treat `prompt-id` as immutable after release; any rename is a breaking replacement and clients must move to the new id.

Valid examples:

1. `pytest-fill-scaffold`
2. `review-pr-comments`
3. `scaffold-fastapi-service`

Invalid examples:

1. `fill_pytest_scaffold`
2. `Prompt-Template`
3. `docs.prompt`

## Direct Documentation Inclusion

1. For direct API documentation, use mkdocstrings directives rather than pasting large code blocks.
2. Keep manually-authored code examples short and task-focused; large implementation excerpts are out of scope for this contract.