docs-system — v1.0.0
Installs and maintains a complete documentation system in any repository. Use this skill when a project needs its docs organized, classified, indexed, and kept in sync — or when asked to "set up the documentation system / doc taxonomy / doc compendiums".
The skill is implemented by four scripts (in scripts/); you invoke them in order. All are
idempotent and history-preserving (git mv); migration is review-gated (--dry-run first).
When to use
- A repo has loose, unclassified docs → install the system + migrate them.
- A doc was created/edited → regenerate that folder's compendium (mandatory step).
- Someone asks for a doc index / glossary / "memorial" / taxonomy.
Commands (scripts)
| Command | Script | Purpose |
|---|---|---|
| bootstrap | scripts/docs-bootstrap.sh <repo> | Install kit: scaffold category folders, copy governance docs (taxonomy/templates/quick-start/registry/glossary), install the 4 scripts, append the doc rule to the agent file. Idempotent. |
| migrate | scripts/docs-migrate.sh [--dry-run|--apply] <repo> | Classify existing docs by filename prefix, date them (marker→git→filename), and move to TYPE-NAME-DATE.md in the right folder. --dry-run (default) prints the plan; --apply does git mv + markers + a reference sweep. Unknown prefixes → NEEDS-REVIEW (never auto-moved). |
| compile | scripts/docs-compile.sh <folder> | (Re)build <folder>/MEMORIAL.md — a date-ordered compendium of every doc with index + glossary link + full bodies. Deterministic rebuild: idempotent / auto-append / dedup / re-order. --clean <folder> removes it. |
| append | scripts/docs-append.sh <doc> ["summary"] | Add one link line for a doc to its folder README.md index (idempotent). |
Standard workflow
# 1. configure (once per repo)
cp docs-system.conf.example .docs-system.conf # edit PROJECT_NAME, AGENT_RULES, PLAN_BUCKET
# 2. install
scripts/docs-bootstrap.sh .
# 3. migrate existing docs — DRY-RUN FIRST, review, then apply
scripts/docs-migrate.sh --dry-run .
scripts/docs-migrate.sh --apply .
# 4. build compendiums
for d in documentation features testing reviews changes PLANS; do
scripts/docs-compile.sh "docs/$d"
done
# 5. finish: reseed docs/documentation/DOCUMENTATION-REGISTRY.md, edit GLOSSARY.md project terms
MANDATORY ongoing rule
After you create or edit ANY doc under docs/<folder>/, run
scripts/docs-compile.sh docs/<folder> and commit the regenerated MEMORIAL.md with the doc.
Do not hand-edit MEMORIAL.md (it is generated). This is also written into the target repo's
agent rules file by bootstrap.
Doc header markers (enforced)
Every .md carries, under its H1:
<!-- version --> · <!-- classification: TYPE --> · <!-- date --> · <!-- last-updated -->.
date is set once (creation); only last-updated changes on edits. Types:
FEATURE / TESTING / DESIGN / GAPS / ANALYSIS / CHANGE / STUDY / REVIEW / ARCHITECTURE / SUMMARY / PLAN.
Safety / revert
docs-migrate.shdefaults to--dry-run; review the table before--apply.- Revert compendiums:
scripts/docs-compile.sh --clean docs/<folder>orfind docs -name MEMORIAL.md -delete. - Everything is git-tracked;
git revertundoes a run. Moves are renames (history preserved).
References
references/PLAYBOOK.md— full procedure, configuration knobs, verification, revert.