Docs-as-Code Primer — AGENTS.md

Docs-as-Code Primer — AGENTS.md

Instructions for AI coding agents working on this repository.

What this is

A teaching kit for documentation judgment. 14 primer chapters teach the phases, a scaffold ships a copy-paste docs/ tree, 24 templates shape the artifacts, and a worked example (Acme Export Platform) fills them in.

Repo layout

Build & test commands

# Lint all Markdown (config in .rumdl.toml — excludes scaffold/docs)
rumdl check primer/ templates/ appendix/ recipes/ examples/ docs/ README.md CONTRIBUTING.md CODE_OF_CONDUCT.md SECURITY.md FIRST_WEEK.md LEARNING_PATH.md llms.txt

# Check links (external only — internal clean-URL links are validated by the
# cross-references job; lychee skips local file links via ^file:// in .lycheeignore)
# lychee is a standalone Rust binary, not an npm package — install it with
# `cargo install lychee` (or `brew install lychee` on macOS), then run:
lychee --no-progress --root-dir . 'primer/**/*.md' 'templates/**/*.md' 'appendix/**/*.md' 'README.md'

# Spell check (custom word list in docs/spelling-exceptions.txt)
npx cspell 'primer/**/*.md' 'templates/**/*.md' 'appendix/**/*.md' 'README.md'

# Verify all ../templates/ and ../examples/ cross-references resolve
# (custom check defined in .github/workflows/docs.yml)

CI runs on pushes to primer/, templates/, appendix/, recipes/, llms.txt, README.md, CONTRIBUTING.md, .rumdl.toml, and .github/workflows/.

Rules

1. Never edit scaffold content as a proxy for teaching — the scaffold is a copy-paste product for adopters. Primer chapters teach why; scaffold files are what. Edit primer/ if you need to change guidance; only touch scaffold/ for structural or CI changes.
2. Every primer chapter ends with a “Use” section referencing real templates or scaffold paths. Keep those references in sync.
3. Templates are not examples — templates are fill-in-the-blank shapes. Examples live in examples/acme-export-platform/. Do not put realistic content in templates.
4. Never duplicate across primer and appendix — the appendix is the canonical reference. Primer chapters link there.
5. Prefer Mermaid for new diagrams — .mmd files or inline Mermaid fenced blocks. No PNG screenshots of text.
6. Cross-references use relative paths — ../templates/..., ../examples/..., ../appendix/.... Verify they resolve.
7. Adjectives are teaching moments — before/after examples and “Check yourself” quizzes are the pedagogical pattern. Add them to new primer content.
8. Run a human-read pass before committing content — read your own diff as a reader, not a writer. Catch truncated sentences/words, invented vocabulary, name-drops and stats without a source, and filler. Automated gates (rumdl, cspell, lychee, cross-refs) cannot catch these; the PR checklist and CONTRIBUTING.md “Definition of Done” treat this as a merge-blocking gate.

What not to touch

• archive/ — working notes, kept for history but superseded by PLAN.md
• scaffold/docs/ subdirectories — these are for the adopter’s project. Stub changes go through the hybrid-stub strategy (READMEs + example-*.md in high-value folders), documented in scaffold/docs/GOVERNANCE.md

Primer chapter structure

Each phase chapter (04–13) follows this pattern:

1. What happens in this phase
2. Key artifacts (maps to templates)
3. Before/after examples
4. Check yourself questions
5. Use section (links to templates and scaffold paths)

Non-phase chapters (14, 16) follow their own structure but always include practical guidance and cross-references.

When to use which file