john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

contract updates

Browse Source
This commit is contained in:
John Lancaster
2026-06-21 22:29:46 -05:00
parent 123c491413
commit c893173fcc
7 changed files with 181 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+1 -1
View File
@@ -26,7 +26,7 @@ This architecture is anchored by three contracts:
Detailed contract pages:
1. [Content Contract](./contracts/content.md)
1. [Content Contract](./contracts/index.md#content-contract)
2. [Frontmatter Contract](./contracts/frontmatter.md)
3. [URI Contract](./contracts/uris.md)
docs/contracts/index.md
+76 -3
View File
@@ -8,8 +8,81 @@ This section groups the core data and contract documents for the repository.
## Pages
1. [Content Contract](./content.md)
2. [Frontmatter Contract](./frontmatter.md)
3. [URI Contract](./uris.md)
1. [Prompt Contract](./prompt.md)
2. [Skill Contract](./skill_contract.md)
3. [Frontmatter Contract](./frontmatter.md)
4. [URI Contract](./uris.md)
Use these pages as the normative source for authored content layout, frontmatter schema, and canonical MCP URI semantics.
## Content Contract
This page defines the authored content contract for the docs-first MCP architecture.
## Canonical Source Of Truth
1. All authored Markdown lives under `docs/`.
2. MCP resources and static docs are two distribution surfaces of the same authored files.
3. No parallel authored markdown is allowed in `src/` or other package-only paths.
## Canonical Content Shape
Authored content is organized under `docs/`:
```mermaid
---
config:
treeView:
rowIndent: 20
lineThickness: 2
themeVariables:
treeView:
labelColor: '#FFFFFF'
lineColor: '#FFFFFF'
---
treeView-beta
"docs/"
"*.md (top-level docs pages)"
"contracts/"
"prompt.md"
"skill_contract.md"
"frontmatter.md"
"uris.md"
"prompts/"
"<prompt-id>/"
"PROMPT.md"
"skills/"
"<skill-id>/"
"SKILL.md"
"references/..."
```
## File Placement And Ownership Boundaries
1. Top-level project docs stay in `docs/*.md`.
2. Skill docs stay in `docs/skills/<skill-id>/...`.
3. Prompt docs stay in `docs/prompts/<prompt-id>/...`.
4. A skill or prompt may link across sections, but must not store content in another artifact's directory.
5. Server and runtime code may index and serve docs, but must not be the source of authored markdown.
## Delegated Contracts
1. Skill-specific directory, metadata, and id rules are defined in [Skill Contract](./skill_contract.md).
2. Prompt-specific directory, metadata, and id rules are defined in [Prompt Contract](./prompt.md).
## Invariants
This contract guarantees:
1. One authored source tree in `docs/` for both website and MCP.
2. Skill and prompt artifacts remain path-stable within their own sections.
3. Cross-surface publishing remains deterministic because authored content paths are canonical.
## Non-Goals
This contract does not define:
1. URI versioning policy details.
2. The full frontmatter schema.
3. Detailed skill rules (see [Skill Contract](./skill_contract.md)).
4. Detailed prompt rules (see [Prompt Contract](./prompt.md)).
docs/contracts/prompt.md
+75
View File
@@ -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.
docs/contracts/content.md → docs/contracts/skill_contract.md
+25 -38
View File
@@ -1,28 +1,34 @@
---
icon: lucide/file-text
icon: lucide/brain-circuit
---
# Content Contract
# Skill Contract
This page defines the authored content contract for the docs-first MCP architecture.
## Canonical Source Of Truth
1. All authored Markdown lives under `docs/`.
2. MCP resources and static docs are two distribution surfaces of the same authored files.
3. No parallel authored markdown is allowed in `src/` or other package-only paths.
This page defines the canonical contract for skills in the docs-first MCP architecture.
## Canonical Skill Shape
Each skill is one directory under `docs/skills/`:
```text
docs/
skills/
<skill-id>/
SKILL.md
references/
... (one or more markdown files, optional nested folders)
```mermaid
---
config:
treeView:
rowIndent: 20
lineThickness: 2
themeVariables:
treeView:
labelColor: '#FFFFFF'
lineColor: '#FFFFFF'
---
treeView-beta
"docs/"
"... (other docs)"
"skills/"
"<skill-id>/"
"SKILL.md"
"references/"
"... (one or more markdown files, optional nested folders)"
```
Rules:
@@ -32,13 +38,6 @@ Rules:
3. Nested folders inside `references/` are allowed so a skill can reorganize internals without changing global architecture.
4. Skill directories are independent ownership boundaries; no cross-skill file writes.
## File Placement And Ownership Boundaries
1. Top-level project docs stay in `docs/*.md`.
2. Skill docs stay in `docs/skills/<skill-id>/...`.
3. A skill may link to other skills, but must not store content inside another skill's directory.
4. Server and runtime code may index and serve docs, but must not be the source of authored markdown.
## Metadata Location Constraint
1. Skill metadata is embedded in YAML frontmatter in `SKILL.md`.
@@ -69,20 +68,8 @@ Invalid examples:
2. `Zensical-Docs`
3. `docs.zensical`
## Invariants
## Direct Documentation Inclusion
This contract guarantees:
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.
1. One authored source tree in `docs/` for both website and MCP.
2. One skill directory maps to one skill identity per revision.
3. Namespace and slug drift is minimized by keeping directory and frontmatter ids aligned per revision.
4. Per-skill reference structure can evolve without changing cross-skill architecture.
5. Packaging for stdio is deterministic because authored content is path-stable.
## Non-Goals
This contract does not define:
1. URI versioning policy details.
2. The full frontmatter schema.
3. Migration instructions from the current architecture.
docs/index.md
+1 -1
View File
@@ -40,7 +40,7 @@ When the server is running, the health check is available at `/healthz` and the
- [Resource-First Pattern Module Architecture](./architecture.md)
- [Contracts](./contracts/index.md)
- [Content Contract](./contracts/content.md)
- [Content Contract](./contracts/index.md#content-contract)
- [Frontmatter Contract](./contracts/frontmatter.md)
- [URI Contract](./contracts/uris.md)
- [Static Docs Hosting Pattern](./mcp_layout.md)
docs/skills/new-skill/SKILL.md
-1
View File
@@ -44,7 +44,6 @@ If the domain includes naming or hierarchy conventions, include a dedicated nami
1. Use this file as the baseline template for new skill authoring.
2. Read and follow these docs before implementing a new skill:
- [docs/architecture.md](../../architecture.md)
- [docs/contracts/content.md](../../contracts/content.md)
- [docs/contracts/frontmatter.md](../../contracts/frontmatter.md)
- [docs/mcp_layout.md](../../mcp_layout.md)
- [docs/contracts/uris.md](../../contracts/uris.md)
zensical.toml
+2 -1
View File
@@ -50,7 +50,8 @@ nav = [
{ "Arch" = "architecture.md" },
{ "Contracts" = [
{ "Overview" = "contracts/index.md" },
{ "Content" = "contracts/content.md" },
{ "Prompt" = "contracts/prompt.md" },
{ "Skill" = "contracts/skill_contract.md" },
{ "Frontmatter" = "contracts/frontmatter.md" },
{ "URIs" = "contracts/uris.md" },
] },