Project Docs System

Project Docs System

Build and maintain a layered docs system so future work can reuse durable project knowledge without collapsing everything into one file.

Design Philosophy

This docs system borrows from Domain-Driven Design: organize durable knowledge around project domains and bounded contexts, keep shared vocabulary explicit, and place each convention where its scope belongs. docs/DOCS.md is the repository knowledge protocol for cross-domain language, collaboration conventions, and boundary principles; docs/<domain>/DOCS.md carries the same kind of shared principles inside one domain; index files act as a context map, and leaf docs capture stable knowledge inside one focused subdomain. Decision history lives in an adjacent <stem>.adr.md companion, reached only through its living <stem>.md document. Do not force tactical DDD patterns into the docs unless the project itself uses them.

Follow This Workflow

1. Inspect the current docs state.

   • Read AGENTS.md, docs/DOCS.md, and docs/index.md if they exist.
   • If docs/index.md exists, read relevant docs/<domain>/DOCS.md and docs/<domain>/index.md files before editing leaf docs.
   • Treat docs/ as initialized only when compatible docs/DOCS.md (Project Knowledge Protocol) and docs/index.md files exist.
   • Detect whether the repository already has a docs convention and preserve it when possible.

2. Use the starter layout in references/docs-layout.md.

   • Create or maintain the core files.
   • Keep file roles distinct.
   • Reuse the standard frontmatter keys and section layout.
   • When creating a new leaf doc, copy the structure in references/subdomain-doc-template.md.
   • Allow deeper docs scopes when they are useful and indexed.
   • Treat non-Markdown resource directories under docs/ as outside docs layout validation.

3. Sort knowledge before writing.

   • Put cross-domain language, collaboration conventions, and boundary principles in docs/DOCS.md.
   • Put domain-level language, conventions, and boundary principles shared by multiple subdomain docs in docs/<domain>/DOCS.md.
   • Put domain navigation in docs/<domain>/index.md.
   • Put stable subdomain knowledge in docs/<domain>/<subdomain>.md by default, or in a deeper indexed scope when the project needs another grouping level.
   • Add a ## Domain Language section only when a docs file depends on confirmed project-specific terms.
   • Keep current knowledge in the living document; move decision history into an adjacent <stem>.adr.md with relative Markdown links in both directions. Create it only when there is history to preserve. See the companion template.
   • Keep companions out of index entries and generated catalogs. Read them only when the linked living document makes the historical reasoning relevant.
   • Do not store short-lived debugging notes or one-off session details.

4. Keep AGENTS.md as the entry point.

   • If docs/ is initialized, ensure AGENTS.md includes this exact rules block:

<!-- BEGIN:docs-system-rules -->
# This is NOT the docs system you know

This repository maintains project-specific knowledge and conventions in `docs/`; start with `docs/index.md` and `docs/DOCS.md`, then follow links into `docs/<domain>/DOCS.md`, `docs/<domain>/index.md`, and `docs/<domain>/<subdomain>.md` as needed, treat `docs/` as the source of durable non-obvious project practices, and use the installed `$project-docs-system` skill when initializing, maintaining, or updating this docs system.
<!-- END:docs-system-rules -->

• If docs/ is not initialized yet, do not add the rules block yet.

5. Keep maps complete.

   • When adding a first-level domain, create both docs/<domain>/DOCS.md and docs/<domain>/index.md.
   • When adding, renaming, merging, or removing living Markdown docs files, update the nearest parent index.md in the same change.
   • When adding, renaming, merging, or removing a child docs directory, update the nearest parent index.md with the child index.md link in the same change.
   • When adding, renaming, merging, or removing first-level domains, update docs/index.md in the same change.

6. Update docs during normal work, not as an afterthought.

   • After a user correction, update the relevant docs file in the same task when possible.
   • After a new module or workflow appears, add or extend the relevant domain and subdomain docs.
   • Prefer short, durable bullets over long narrative notes.

Editing Rules

• Preserve the repository's chosen freshness key if one already exists.
• When bootstrapping a new system from scratch, use the frontmatter keys in references/docs-layout.md.
• Keep docs files scoped and stable; move repeated domain-level knowledge into docs/<domain>/DOCS.md and repeated cross-domain knowledge into docs/DOCS.md.
• Keep ## Domain Language short: use one-sentence definitions, optional _Avoid_: ..., and optional Related: ...; skip the section when no confirmed terms are needed.
• When migrating inline decision records, move their history into the companion without changing its meaning or chronology; retain current behavior in the living document and add both links. Use [Decision history](./<stem>.adr.md) and [Current documentation](./<stem>.md).
• Preserve earlier rationale when decisions change. A planned decision does not establish implemented behavior.
• When verification warns that a document exceeds 500 author-maintained lines, review it for accumulated ADRs, mixed responsibilities, and unnecessary reading context. Extract history, split cohesive domains, or trim content as appropriate; do not split mechanically to satisfy the threshold. This applies to companions too; generated catalog blocks are excluded.
• Reference concrete files, routes, or modules when that makes the docs more reusable.

Final Verification

• Confirm the core docs files exist and are linked together.
• Confirm every docs document starts with frontmatter.
• Confirm every first-level Markdown docs domain has docs/<domain>/DOCS.md and docs/<domain>/index.md.
• Confirm docs/index.md covers every first-level Markdown docs domain.
• Confirm each docs scope index.md covers its direct living Markdown docs files and child docs scope indexes; companion ADRs are excluded.
• Confirm each companion has a living document and relative Markdown links in both directions.
• When shell access is available, run the bundled scripts/verify-docs-system.sh with the target repo root or docs/ directory to verify the docs structure.
• Summarize what was created or updated and why.