swapped docs symlink

2026-08-07 21:07:23 -05:00
parent 5005cd7001
commit f240486a7e
92 changed files with 69 additions and 42 deletions
@@ -0,0 +1,84 @@
+---
+icon: lucide/messages-square
+---
+
+# Prompt Contract
+
+This page defines the canonical contract for declarative prompts published through a custom [FastMCP provider](https://gofastmcp.com/servers/providers/custom).
+
+## Canonical Prompt Shape
+
+Each prompt is one self-describing Markdown document:
+
+```mermaid
+---
+config:
+    treeView:
+        rowIndent: 20
+        lineThickness: 2
+    themeVariables:
+        treeView:
+            labelColor: '#FFFFFF'
+            lineColor: '#FFFFFF'
+---
+treeView-beta
+    "docs/prompts/"
+      "<prompt-id>/"
+        "PROMPT.md"
+    "src/personal_mcp/prompts/"
+      "content.py"
+      "models.py"
+      "provider.py"
+```
+
+Rules:
+
+1. The parent directory name defines the public prompt id.
+2. The nested `prompt` frontmatter block defines version, description, tags, and arguments.
+3. Argument declarations define names, descriptions, requiredness, and optional string choices.
+4. The Markdown body owns the rendered prompt prose and uses `{{argument_name}}` placeholders.
+5. Declared arguments and body placeholders must match exactly.
+6. No Python file is added when authoring a prompt.
+
+## Ownership Boundary
+
+1. Each `PROMPT.md` owns both its runtime metadata and prose.
+2. Python owns only generic parsing, validation, rendering, and provider behavior.
+3. There is no central prompt catalog, generated signature, or metadata sidecar.
+4. The provider scans direct children of packaged `docs/prompts/` on each list or get request.
+5. Additions, edits, and deletions become visible on the next request without restarting the server.
+6. Reload is pull-based; the provider does not watch files or emit proactive change notifications.
+
+## 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. The provider derives the prompt name from the directory; frontmatter must not duplicate it.
+7. Treat `prompt-id` as immutable after release; a rename is a breaking replacement.
+
+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`
+
+## Rendering Contract
+
+1. The loader requires one leading YAML frontmatter block and validates its nested `prompt` mapping strictly.
+2. All MCP arguments are strings; `choices` optionally restricts accepted values.
+3. Missing required arguments, unknown arguments, and invalid choices fail before rendering.
+4. An omitted optional value renders as `Not provided`.
+5. Unknown prompt ids, malformed metadata, and mismatched placeholders fail immediately.
+6. Prompt content is read through [importlib resources](https://docs.python.org/3/library/importlib.resources.html) and does not depend on the working directory.
+