docs-system — v1.0.0
Instala e mantém um sistema completo de documentação em qualquer repositório. Use este skill quando um projeto precisar de seus documentos organizados, classificados, indexados e mantidos em sincronia — ou quando for solicitado a "configurar o sistema de documentação / taxonomia de documentos / compêndios de documentos".
O skill é implementado por quatro scripts (em scripts/); você os invoca em ordem. Todos são
idempotentes e preservam o histórico (git mv); a migração é controlada por revisão (--dry-run primeiro).
Quando usar
- Um repositório possui documentos soltos e não classificados → instale o sistema + migre-os.
- Um documento foi criado/editado → regenere o compêndio da pasta (etapa obrigatória).
- Alguém pedir um índice de documentos / glossário / "memorial" / taxonomia.
Comandos (scripts)
| Comando | Script | Propósito |
|---|---|---|
| bootstrap | scripts/docs-bootstrap.sh <repo> | Instalar o kit: criar pastas de categorias, copiar documentos de governança (taxonomia/modelos/guia-rápido/registro/glossário), instalar os 4 scripts, adicionar a regra de documentação ao arquivo de regras do agente. Idempotente. |
| migrate | `scripts/docs-migrate.sh [--dry-run | --apply] ` |
| compile | scripts/docs-compile.sh <pasta> | (Re)construir <pasta>/MEMORIAL.md — um compêndio ordenado por data de cada documento com índice + link do glossário + corpos completos. Reconstrução determinística: idempotente / inserção automática / deduplicação / reordenação. --clean <pasta> o remove. |
| append | scripts/docs-append.sh <doc> ["resumo"] | Adicionar uma linha de link para um documento ao seu README.md de índice da pasta (idempotente). |
Fluxo de trabalho padrão
# 1. configurar (uma vez por repositório)
cp docs-system.conf.example .docs-system.conf # edite PROJECT_NAME, AGENT_RULES, PLAN_BUCKET
# 2. instalar
scripts/docs-bootstrap.sh .
# 3. migrar documentos existentes — DRY-RUN PRIMEIRO, revise, depois aplique
scripts/docs-migrate.sh --dry-run .
scripts/docs-migrate.sh --apply .
# 4. construir compêndios
for d in documentation features testing reviews changes PLANS; do
scripts/docs-compile.sh "docs/$d"
done
# 5. finalizar: reabastecer docs/documentation/DOCUMENTATION-REGISTRY.md, editar GLOSSARY.md com termos do projeto
Regra contínua OBRIGATÓRIA
Após criar ou editar QUALQUER documento em docs/<pasta>/, execute
scripts/docs-compile.sh docs/<pasta> e faça commit do MEMORIAL.md regenerado junto com o documento.
Não edite manualmente MEMORIAL.md (ele é gerado). Esta regra também é escrita no arquivo de regras do agente do repositório alvo pelo bootstrap.
Marcadores de cabeçalho de documento (aplicados)
Cada .md carrega, abaixo do seu H1:
<!-- version --> · <!-- classification: TIPO --> · <!-- date --> · <!-- last-updated -->.
date é definido uma vez (criação); apenas last-updated muda em edições. Tipos:
FEATURE / TESTING / DESIGN / GAPS / ANALYSIS / CHANGE / STUDY / REVIEW / ARCHITECTURE / SUMMARY / PLAN.
Segurança / reversão
docs-migrate.shusa--dry-runcomo padrão; revise a tabela antes de--apply.- Reverter compêndios:
scripts/docs-compile.sh --clean docs/<pasta>oufind docs -name MEMORIAL.md -delete. - Tudo é rastreado pelo git;
git revertdesfaz uma execução. Movimentações são renomeações (histórico preservado).
Referências
references/PLAYBOOK.md— procedimento completo, opções de configuração, verificação, reversão.