contract updates
This commit is contained in:
John Lancaster
@@ -26,7 +26,7 @@ This architecture is anchored by three contracts:
|
|||||||
|
|
||||||
Detailed contract pages:
|
Detailed contract pages:
|
||||||
|
|
||||||
1. [Content Contract](./contracts/content.md)
|
1. [Content Contract](./contracts/index.md#content-contract)
|
||||||
2. [Frontmatter Contract](./contracts/frontmatter.md)
|
2. [Frontmatter Contract](./contracts/frontmatter.md)
|
||||||
3. [URI Contract](./contracts/uris.md)
|
3. [URI Contract](./contracts/uris.md)
|
||||||
|
|
||||||
|
|||||||
+77
-4
@@ -8,8 +8,81 @@ This section groups the core data and contract documents for the repository.
|
|||||||
|
|
||||||
## Pages
|
## Pages
|
||||||
|
|
||||||
1. [Content Contract](./content.md)
|
1. [Prompt Contract](./prompt.md)
|
||||||
2. [Frontmatter Contract](./frontmatter.md)
|
2. [Skill Contract](./skill_contract.md)
|
||||||
3. [URI Contract](./uris.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.
|
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)).
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|
||||||
@@ -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.
|
This page defines the canonical contract for skills in 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 Skill Shape
|
## Canonical Skill Shape
|
||||||
|
|
||||||
Each skill is one directory under `docs/skills/`:
|
Each skill is one directory under `docs/skills/`:
|
||||||
|
|
||||||
```text
|
```mermaid
|
||||||
docs/
|
---
|
||||||
skills/
|
config:
|
||||||
<skill-id>/
|
treeView:
|
||||||
SKILL.md
|
rowIndent: 20
|
||||||
references/
|
lineThickness: 2
|
||||||
... (one or more markdown files, optional nested folders)
|
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:
|
Rules:
|
||||||
@@ -32,13 +38,6 @@ Rules:
|
|||||||
3. Nested folders inside `references/` are allowed so a skill can reorganize internals without changing global architecture.
|
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.
|
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
|
## Metadata Location Constraint
|
||||||
|
|
||||||
1. Skill metadata is embedded in YAML frontmatter in `SKILL.md`.
|
1. Skill metadata is embedded in YAML frontmatter in `SKILL.md`.
|
||||||
@@ -69,20 +68,8 @@ Invalid examples:
|
|||||||
2. `Zensical-Docs`
|
2. `Zensical-Docs`
|
||||||
3. `docs.zensical`
|
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.
|
|
||||||
+1
-1
@@ -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)
|
- [Resource-First Pattern Module Architecture](./architecture.md)
|
||||||
- [Contracts](./contracts/index.md)
|
- [Contracts](./contracts/index.md)
|
||||||
- [Content Contract](./contracts/content.md)
|
- [Content Contract](./contracts/index.md#content-contract)
|
||||||
- [Frontmatter Contract](./contracts/frontmatter.md)
|
- [Frontmatter Contract](./contracts/frontmatter.md)
|
||||||
- [URI Contract](./contracts/uris.md)
|
- [URI Contract](./contracts/uris.md)
|
||||||
- [Static Docs Hosting Pattern](./mcp_layout.md)
|
- [Static Docs Hosting Pattern](./mcp_layout.md)
|
||||||
|
|||||||
@@ -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.
|
1. Use this file as the baseline template for new skill authoring.
|
||||||
2. Read and follow these docs before implementing a new skill:
|
2. Read and follow these docs before implementing a new skill:
|
||||||
- [docs/architecture.md](../../architecture.md)
|
- [docs/architecture.md](../../architecture.md)
|
||||||
- [docs/contracts/content.md](../../contracts/content.md)
|
|
||||||
- [docs/contracts/frontmatter.md](../../contracts/frontmatter.md)
|
- [docs/contracts/frontmatter.md](../../contracts/frontmatter.md)
|
||||||
- [docs/mcp_layout.md](../../mcp_layout.md)
|
- [docs/mcp_layout.md](../../mcp_layout.md)
|
||||||
- [docs/contracts/uris.md](../../contracts/uris.md)
|
- [docs/contracts/uris.md](../../contracts/uris.md)
|
||||||
|
|||||||
+2
-1
@@ -50,7 +50,8 @@ nav = [
|
|||||||
{ "Arch" = "architecture.md" },
|
{ "Arch" = "architecture.md" },
|
||||||
{ "Contracts" = [
|
{ "Contracts" = [
|
||||||
{ "Overview" = "contracts/index.md" },
|
{ "Overview" = "contracts/index.md" },
|
||||||
{ "Content" = "contracts/content.md" },
|
{ "Prompt" = "contracts/prompt.md" },
|
||||||
|
{ "Skill" = "contracts/skill_contract.md" },
|
||||||
{ "Frontmatter" = "contracts/frontmatter.md" },
|
{ "Frontmatter" = "contracts/frontmatter.md" },
|
||||||
{ "URIs" = "contracts/uris.md" },
|
{ "URIs" = "contracts/uris.md" },
|
||||||
] },
|
] },
|
||||||
|
|||||||
Reference in New Issue
Block a user