prompts/docs/contracts/prompt.md

icon

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/:

---
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. fill-pytest-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.