docs-system

A portable kit that installs a complete documentation system into any repo: classification taxonomy, header markers, the PLAN doc type, category folders, per-folder README indexes, a central GLOSSARY, and per-folder MEMORIAL compendiums — plus a doc rule wired into the project's agent file.

Status: v1.0.2 · 10/10 scenario tests pass · CHANGELOG. For AgentFactory, use the full-agent release bundle (--from-git imports scripts only — AgentFactory#179).

Quick start

git clone https://github.com/matheusmlopess/docs-system ~/docs-system
cd <your-repo>
cp ~/docs-system/docs-system.conf.example .docs-system.conf   # edit it
~/docs-system/scripts/docs-bootstrap.sh .
scripts/docs-migrate.sh --dry-run .      # review
scripts/docs-migrate.sh --apply .
for d in documentation features testing reviews changes PLANS; do scripts/docs-compile.sh "docs/$d"; done

See PLAYBOOK.md for the full procedure, configuration, verification, and revert.

Use it as an agent / skill

The capability is packaged as a portable agent (agent/, matching AgentFactory's agent-manifest.json schema) so each harness consumes it however it's configured — as a skill, as commands, or as raw scripts. Full guide: CONSUMING-AGENTS.md.

                          ┌────────────────────────────────────────────┐
   docs-system repo  ───► │ agent/                                      │
                          │   skills/docs-system/SKILL.md  (skill)      │
                          │   commands/docs-*.md           (commands)   │
                          │   scripts/docs-*.sh            (scripts)    │
                          │   agent-manifest.json          (agent)      │
                          └───────────────┬────────────────────────────┘
        ┌─────────────────────────────────┼─────────────────────────────────┐
        ▼                                 ▼                                 ▼
   AgentFactory                      Claude Code                       Generic / any CLI

Scripts as tools / commands / scripts — depending on the agent

Harness	Consumes as	How
AgentFactory (agentfactory-gen)	agent (skill + commands + scripts)	import docs-system-agent.zip (full — bundle on each release); --from-git = scripts only (#179)
Claude Code	skill + slash commands	copy agent/skills/… → .claude/skills/, agent/commands/*.md → .claude/commands/ (/docs-bootstrap …)
Cursor / rule-based	rule + scripts	add kit/rule-snippet.md to your rules, expose scripts/
Generic / no agent	raw scripts	run scripts/docs-*.sh

# AgentFactory — FULL import (skills+commands+docs+scripts) via the release bundle:
agentfactory-gen import docs-system-agent.zip --allow-scripts
#   (download docs-system-agent.zip from the latest release; --from-git imports scripts only — #179)

# Claude Code — drop in the skill + slash commands
cp -r agent/skills/docs-system .claude/skills/docs-system
cp agent/commands/*.md .claude/commands/        # /docs-bootstrap /docs-migrate /docs-compile /docs-append

agent/ layout

agent/
├── agent-manifest.json                 # AgentFactory descriptor (resources.skills/commands/scripts/docs)
├── skills/docs-system/
│   ├── SKILL.md                        # frontmatter triggers + workflow + the mandatory compile rule
│   ├── skill-manifest.json
│   └── references/ PLAYBOOK.md · TAXONOMY-QUICKREF.md
├── commands/ docs-{bootstrap,migrate,compile,append}.md   # one per script (dual: AF command + CC slash)
├── scripts/  docs-{bootstrap,migrate,compile,append}.sh   # the implementation
└── docs/SKILL-DOCS-SYSTEM.md

Behavioural contract (what the agent does)

1. "set up documentation / organize docs / doc system" → bootstrap → migrate --dry-run → present the table + get confirmation → migrate --apply → compile all folders → reseed registry + glossary.
2. On any doc create/edit → run compile on that folder and commit the regenerated MEMORIAL.md (this rule is also installed into the target repo's agent-rules file).
3. Review-gated: never --apply without a --dry-run first; unknown-prefix docs are surfaced as NEEDS-REVIEW for a human decision.

What's in here

scripts/
  docs-bootstrap.sh   install the kit into a target repo (idempotent)
  docs-migrate.sh     classify/date/move existing docs (--dry-run default, --apply)
  docs-compile.sh     build a folder's MEMORIAL.md compendium (date-ordered)
  docs-append.sh      add a doc to its folder README index
kit/
  documentation/      TAXONOMY · TEMPLATES · QUICK-START · REGISTRY(skeleton) · GLOSSARY(skeleton) · README
  rule-snippet.md     the doc rule appended to the target's agent file
docs-system.conf.example   per-repo knobs
PLAYBOOK.md                the procedure

How the compendium generator works

docs-compile.sh reads every doc in a folder, sorts by creation date, and rewrites a single MEMORIAL.md with a clickable index + glossary link + every doc's full text. It's a deterministic rebuild, so it's idempotent, auto-includes new docs, never duplicates, and re-sorts by date. --clean <folder> removes a compendium.

License

Use freely.