diff --git a/docs/architecture.md b/docs/architecture.md index edcfb86..db84550 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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) diff --git a/docs/contracts/index.md b/docs/contracts/index.md index 4f2800d..712c505 100644 --- a/docs/contracts/index.md +++ b/docs/contracts/index.md @@ -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. \ No newline at end of file +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.md" + "skills/" + "/" + "SKILL.md" + "references/..." +``` + +## File Placement And Ownership Boundaries + +1. Top-level project docs stay in `docs/*.md`. +2. Skill docs stay in `docs/skills//...`. +3. Prompt docs stay in `docs/prompts//...`. +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)). diff --git a/docs/contracts/prompt.md b/docs/contracts/prompt.md new file mode 100644 index 0000000..3041148 --- /dev/null +++ b/docs/contracts/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.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. + diff --git a/docs/contracts/content.md b/docs/contracts/skill_contract.md similarity index 50% rename from docs/contracts/content.md rename to docs/contracts/skill_contract.md index c65640a..e883145 100644 --- a/docs/contracts/content.md +++ b/docs/contracts/skill_contract.md @@ -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.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.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//...`. -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. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 310418e..54aa1fc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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) diff --git a/docs/skills/new-skill/SKILL.md b/docs/skills/new-skill/SKILL.md index d1354a6..f4b8c86 100644 --- a/docs/skills/new-skill/SKILL.md +++ b/docs/skills/new-skill/SKILL.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. 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) diff --git a/zensical.toml b/zensical.toml index 36084fe..d13b6a4 100644 --- a/zensical.toml +++ b/zensical.toml @@ -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" }, ] },