contract updates

2026-06-21 22:29:46 -05:00
parent 123c491413
commit c893173fcc
7 changed files with 181 additions and 46 deletions
@@ -0,0 +1,75 @@
+---
+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. `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.
+