76 lines
2.3 KiB
Markdown
76 lines
2.3 KiB
Markdown
---
|
|
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.
|
|
|