Documentation Manager
Conhecimento vivo de projeto para humanos e agentes de IA. O código é a fonte da verdade para como e para se uma afirmação é verdadeira.
AGENTS.md + docs/ capturam o quê, por quê, decisões e planos — mas nunca substituem o código quando discordam.
Regras principais
- Prefira
AGENTS.mdcomo hub. Seagents.mdjá existir, use-o. Se apenasCLAUDE.mdexistir, estenda-o com um índice de docs ou adicioneAGENTS.mde faça links cruzados — não crie três hubs concorrentes. - Cada documento gerado/atualizado usa links Markdown relativos de volta ao hub e documentos relacionados.
- Nunca exclua conhecimento duradouro sem um motivo; prefira notas de Substituído por em ADRs.
- Não faça auto-commit ou auto-push. Deixe o git para o usuário.
- Escreva o conteúdo gerado no idioma do usuário (ou no idioma dominante do repositório). Este corpo do skill está em inglês para compatibilidade do ecossistema.
- Prefira precisão e utilidade em vez de volume. Conjunto principal primeiro; documentos opcionais sob demanda.
- Intenção primeiro (nível de projeto). Classifique a Intenção:
integrate|audit|from-zero(e híbrido opcional). Consulte a Etapa 0. Não obrigatório para feature/plano/sincronia puros. - O código vence em conflitos. Afirmações de documentação que falham na verificação estrutural são marcadas como Contraditadas/Ausentes — não invente código para corresponder à documentação; corrija ou sinalize a documentação.
- Integrar primeiro (quando Intent=integrate). Documentos maduros → índice + lacunas + links canônicos; sem reescrita paralela de visão-do-produto/requisitos/ADRs. Consulte adopt-integrate.
- Uma autoridade por tópico. Cada tópico tem um documento canônico; todo o resto faz link para ele.
- Matriz de cobertura em projeto adopt/from-zero. Superfícies de produto (nav, ModuleId, pacote) aparecem como documentadas / vinculadas / lacuna.
- Atomicidade de feature. Um slug ≈ um ModuleId ou contexto limitado. Clusters = índice + filhos.
- Taxonomia de status. references/status-taxonomy.md.
- Sandbox opt-in / from-zero de primeira classe.
Out: sandbox:caminhoquando o usuário solicitar (test/, etc.). Banner de hub sandbox não-SSOT + plano de promoção. - Autopilot de feature (v1.5 / v2). “nova feature X” / “documentá X” → skill escolhe plano vs pacote de feature, aplica não-escritas padrão, define Kind (nova feature | spike | épico | redesign). Bridge de implementação (posicionamento / stubs) apenas com opt-in (“implementá”, “stubs”, “scaffold”) — padrão é apenas documentação + dica de uma linha. Consulte modes.md §3 e implementation-bridge.md.
- Modo de plano (v1.3+). Ideias de feature greenfield vão para
docs/plans/<slug>/, não para um pacote de implementação falso e nem para um bootstrap completo de projeto. Promova paradocs/features/<slug>/quando o código for real (não apenas stubs). - Bridge ArkGate (v1.4). Se ArkGate for detectado (
ark.config.json,ark-check,.ark/, skills ark) ou o usuário acabou de concluir um portão, execute o subfluxo bridge: enriquecer inventário a partir do contrato; após passagem do portão → sincronia / auditoria com escopo; violações residuais → marcar afirmações como Contraditadas/Parciais — nunca reescreva documentos para justificar arquitetura quebrada. Sem Ark → sem operação. Dicas de posicionamento na bridge de implementação reutilizam camadas Ark quando detectadas. Consulte arkgate-bridge.md e modes.md §9. - Painel de conhecimento (v1.6). Visão HTML estática opcional de planos/features/afirmações (
scripts/generate-docs-dashboard.sh→docs/audit/generated/dashboard.html). Markdown é SSOT; HTML é gitignored e apenas para visualização. Ofereça após auditoria uma vez ou mediante solicitação “dashboard”. Consulte knowledge-dashboard.md e modes.md §10. - Reforço do skill (v1.7). Mantenedores: execute
validate-skill.sh+test-skill-hardening.shantes do lançamento. Agentes: detectem instalação/versão via skill-discovery.md; sugiram reinstalação quando desatualizado (sem auto-patch silencioso). - Pacote v2.0. Completa a linha 10×: capacidades 1.4–1.7 mais monitoramento de docs/adoption-matrix.md. O piso de instalação base permanece 2.0.0; multilíngue 2.1.0; monorepo 2.2.0; equipe 2.3.0; Bridge completo 2.4.0; a linha atual é 2.5.0+ (Knowledge OS primeiro incremento em direção a 100× — afirmações vivas + auditoria CI; não é um segundo 10×).
- Detecção de stack multilíngue (v2.1 Slice A / skill 2.1.0). Na descoberta de projeto (integrate / audit / from-zero / adopt), detecte o stack a partir do sistema de arquivos (
package.json,pyproject.toml,go.mod, …) via skill-discovery.md Detecção de stack multilíngue (ouscripts/detect-stack.sh). Use Inventário por stack e Orientação de layout de documentos por stack — não presuma Node/TS. Nunca invente ModuleIds/endpoints para frameworks sem evidência de código. Consulte modes.md §0.3. - Hubs de monorepo (v2.2 Slice B). Detecte árvores multipacote (
pnpm-workspace.yaml,package.jsonworkspaces,go.work, diretórios multipacote) via skill-discovery.md Hubs de monorepo (ouscripts/detect-packages.sh). O hub raiz é um mapa + Índice de pacotes, não um despejo; a cobertura multipacote marca pacotes lacuna; padrão de não-escritas de pacote ao indexar apenas a raiz. Consulte modes.md §0.4. - Governança de equipe (v2.3 Slice C).
docs/team/opcional com proprietários + notas de aprovação (estilo última-aprovação). Criar vs vincular conforme team-governance.md; o hub vincula a Equipe sem se tornar uma wiki de RH; integrate-first — adicionar equipe não deve reescrever visão-do-produto / requisitos / ADRs. Sem mecanismo CODEOWNERS ou BPM. Consulte modes.md §11. - Telemetria de template (v2.4 Slice D). Registro local opt-in para lacunas de UX de template/skill apenas (template-telemetry.md;
scripts/template-telemetry.sh). Desligado por padrão; nunca envie fontes/segredos/URLs de repositório; nunca em rede; sem operação em ambiente air-gapped quando opt-in desligado. Consulte modes.md §12. - Afirmações vivas + auditoria estrutural CI (v2.5 / primeiro incremento Knowledge OS). Matrizes de auditoria usam afirmações vivas v0:
anchor.path/anchor.symbolopcional /anchor.hashopcional,severity(critical|normal), vereditos inalterados. Primeiro a matriz (audit-template.md); procedimento living-claims.md; fio ADR-0001. A pontuação de verdade permanece consultiva (heurística do painel); air-gapped localscripts/audit-claims.sh/ exemplodocs-auditCI é o portão (falha em Contradictado crítico). Sem SaaS. Consulte modes.md §6 / §13.
Etapa 0 — Detectar escopo, modo e Intenção
Escopo (obrigatório):
| Escopo | Quando | Foco da saída |
|---|---|---|
| projeto | Produto inteiro / “documentação para o projeto” | Hub + documentos do projeto (conforme Intenção) |
| feature | Feature/módulo nomeado com código (ou pacote de atualização) | docs/features/<slug>/ + link do hub |
| plano | Nova feature nomeada / épico antes ou sem código sólido | docs/plans/<slug>/ + link do hub |
| híbrido | Feature/plano quando ainda não há hub | Pacote ou plano + hub mínimo |
Modo (obrigatório):
| Modo | Sinais |
|---|---|
| bootstrap | Greenfield, sem hub/docs, ou Intenção from-zero em vazio/fino |
| adopt | Código existe; docs finos/ausentes ou Intenção integrate |
| auditoria | “auditar docs”, “docs vs código”, deriva, validar afirmações |
| plano | “nova feature”, “plano”, “épico”, “vamos a construir X” sem código |
| feature | Documentar uma feature/módulo que tem (ou é) código |
| sincronia | Diff / PR / atualizar docs para uma alteração; pós-portão quando Ark acabou de passar |
| roadmap | Planejar release / atualizar lista de épicos |
Intenção (obrigatória apenas para trabalho em nível de projeto):
| Intenção | Sinais do usuário (exemplos) | Comportamento |
|---|---|---|
| integrate | “mejorar docs”, “ordenar”, “sync hub”, melhoria madura | adopt-integrate (ou completo se fino); auditoria prévia opcional se houver suspeita de deriva |
| auditoria | “auditar”, “¿as docs mienten?”, “docs vs código”, “validar paths” | Inventário de código + matriz de afirmações apenas (ou então passar adiante) |
| from-zero | “toda nueva”, “de cero”, “generá docs en test/”, “full KB en carpeta X” | Base de conhecimento completa; prefira sandbox se caminho informado; inferido do código; docs antigos = hipótese apenas |
Inferência (não pergunte demais):
- “nueva feature X” / “new feature X” / “quiero agregar X” → Autopilot de feature (plano se sem código, feature se com código; Kind a partir da redação). Intenção = n/a
- “implementá X” / “generá stubs” / “scaffold X” → autopilot Estágio A se necessário + Bridge de implementação opt-in (código apenas se stubs solicitados)
- “generá toda la documentación en
test/” → Intenção: from-zero | Out: sandbox:test/ - Repositório maduro + “mejorá / integrá / indexá” → Intenção: integrate
- “auditar docs” / “código vs docs” → Intenção: auditoria
- Trabalho de projeto ambíguo com
docs/existente → pergunte uma vez: integrate | audit | from-zero - Superfície única nomeada → nunca exija que o usuário liste não-escritas ou escolha pastas
- “after ark-check” / “post-gate docs” / portão acabou de rodar + intenção de docs → sincronia ou auditoria com Bridge ArkGate
- “dashboard” / “docs HTML” / “knowledge report” → gerar Painel de conhecimento (knowledge-dashboard.md)
- “owners” / “quién es dueño” / “team docs” / “approval notes” / “docs/team” → Governança de equipe (team-governance.md; modes §11)
- “template telemetry” / “opt-in telemetry” / “record template gap” → Telemetria de template apenas se o usuário optar por ativar (template-telemetry.md; modes §12); desligado por padrão
- “living claims” / “truth score” / “docs CI” / “fail on Contradictado” → Afirmações vivas + portão CI local (living-claims.md; modes §13)
Maturidade (quando relevante): fina | mista | madura — consulte modes.md.
Se escopo/modo ainda estiverem ambíguos após a inferência, pergunte uma vez. Carregue procedimentos de references/modes.md.
Anuncie antes de escrever:
Escopo: <x> | Modo: <y> | Intenção: <integrate|audit|from-zero|n/a> | Variante: <full|integrate|arkgate-bridge|n/a> | Maturidade: <…|n/a> | Saída: <root|sandbox:caminho> | Stack: <node-ts|python|go|mixed|unknown|n/a> | Monorepo: <sim|não|n/a> | ArkGate: <none|detected> | Slug: <slug|n/a>
Quando integrate, liste não-escritas (inclua não-escritas de pacote quando índice-raiz de monorepo apenas). Quando auditoria, liste o caminho da matriz e as principais contradições. Quando from-zero + sandbox, inclua plano de promoção. Quando plano ou feature, liste caminho + não-escritas padrão. Quando Bridge ArkGate, liste sinais e sincronia pós-portão vs auditoria-enriquecimento. Quando em nível de projeto, inclua Stack e Monorepo da descoberta.
Layout recomendado
raiz-do-projeto/
├── AGENTS.md
└── docs/
├── product-vision.md # bootstrap / from-zero / adopt-full
├── requirements.md
├── architecture.md
├── roadmap.md
├── team/ # v2.3 governança de equipe (opcional)
│ ├── OWNERS.md
│ └── approval-notes.md
├── audit/ # Intenção auditoria (opcional)
│ └── claims-matrix.md # colunas afirmações vivas v0
├── adr/ # ADRs de pacote/projeto (opcional)
├── plans/<slug>/ # v1.3 modo de plano (pré-código / épico)
│ └── README.md
├── decisions/
└── features/<slug>/ # pacotes de feature com respaldo de código
Documentos de suporte apenas quando justificados (exceto from-zero, que pode criar um conjunto mínimo central completo).
Matriz de artefatos (resumo)
| Artefato | from-zero / bootstrap | integrate (maduro) | auditoria | plano | feature | sincronia |
|---|---|---|---|---|---|---|
| Hub | criar | estender / indexar | atualizar status opcional | vincular Planos | vincular | se necessário |
| Documentos narrativos principais | sim | sem reescrita | não (apenas leitura) | não | não | se impacto |
| Matriz de cobertura | sim | obrigatório | parte do inventário | linha opcional | linha | atualizar |
| Matriz de afirmações | opcional pré | recomendado se houver deriva | obrigatório | n/a | com escopo se auditoria | se deriva |
Planos docs/plans/ | n/a | n/a | n/a | obrigatório | vincular se existir | se impacto |
| Pacotes de feature | domínios-chave | lacunas / entradas | não (a menos que solicitado) | não (até promover) | obrigatório | se impacto |
Equipe docs/team/ | se proprietários conhecidos | criar/vincular se solicitado | não | n/a | n/a | se impacto |
| Árvore completa paralela | sandbox ok | proibido na raiz | n/a | n/a | n/a | n/a |
Fluxo de trabalho (todos os modos)
- Etapa 0 — escopo, modo, Intenção (se projeto), maturidade/variante, Saída, slug; detectar sinais ArkGate quando relevante; detectar Stack e Monorepo para trabalho de projeto (skill-discovery.md Polyglot + Monorepo hubs).
- Descubra o código primeiro — inventário ciente de stack; se monorepo, Índice de pacotes + inventário por pacote; árvore, manifestos, pontos de entrada, testes de exemplo. Depois, documentos (se houver). Para features nomeadas, pesquise essa superfície primeiro. Se Ark detectado, enriquecer inventário conforme arkgate-bridge.md.
- Se auditoria ou docs existirem e Intenção for integrate/from-zero com suspeita de deriva: execute reconciliação (modes.md § Auditoria, audit-template.md). Pós-portão → handoff de bridge (modes.md §9).
- Arquivos de plano — cria/atualiza e não-escritas (padrões para feature/plano).
- …