Documentar o sistema
Esta skill mantém docs/ e .specsfy/PACKAGES.md como retrato fiel do
projeto atual. A documentação é uma projeção reconstruível das fontes locais:
o script gera a base, você confere e corrige somente o que o código não
sustenta.
Pronto quando
specsfy docs build --project <raiz> --check termina sem falha.
docs/ cobre toda a lista de Cobertura obrigatória e
.specsfy/PACKAGES.md lista todos os pacotes dos manifests e lockfiles.
- Conteúdo humano fora dos blocos
specsfy:documentator continua intacto.
- A tarefa que acionou a skill registra comando, resultado e arquivos
atualizados.
Preparação obrigatória
Antes de executar esta skill, carregue obrigatoriamente $specsfy-setup na
raiz do projeto. Em handoff automático, carregue-o de novo antes desta etapa.
Reutilize a raiz confirmada na conversa e não prossiga se o setup apontar uma
pendência.
Modo de interação
Modo de interação: sem perguntas.
Não formule perguntas nesta skill. Registre como não identificado todo dado
que as fontes executáveis não sustentarem.
Executar
Leia em paralelo as instruções locais, PROJECT.md, .specsfy/STACK.md,
.specsfy/RULES.md, .specsfy/DATABASE.md, manifests, lockfiles,
metadados instalados e o código existente. Antes de alterar a topologia
publicada, leia o padrão documental.
Construa toda a documentação e .specsfy/PACKAGES.md, mesmo quando a skill
for acionada sem spec ou implementação recente:
specsfy docs build --project <raiz>
Pelo MCP, use a tool docs_build. Sem o binário instalado, rode o script
equivalente:
node .agents/skills/specsfy-documentator/scripts/build_documentation.mjs \
--project <raiz>
Inspecione os arquivos gerados e corrija manualmente apenas inferências que
o código não sustente. Não acrescente escolhas de arquitetura, relações ou
integrações sem fonte.
Prove que a documentação representa o estado atual:
specsfy docs build --project <raiz> --check
Pelo MCP, use a tool docs_build. Sem o binário instalado, rode o script
equivalente:
node .agents/skills/specsfy-documentator/scripts/build_documentation.mjs \
--project <raiz> --check
Registre na tarefa o comando, o resultado e os arquivos atualizados.
O conteúdo humano fica fora dos blocos specsfy:documentator, inclusive em
.specsfy/PACKAGES.md. O bloco é reconstruído a cada execução; tudo fora
dele é preservado.
Cobertura obrigatória
Manter em docs/:
- portal e roteiro de leitura;
- arquitetura, componentes e UML em Mermaid;
- registro da aplicação e das implementações existentes;
- banco e entidades com
erDiagram;
- fluxos com
flowchart e sequenceDiagram;
- guia e resumo dos testes;
- frontend, views, React e Tailwind;
- bibliotecas e pacotes nativos, de framework, integrados e terceiros, com
versão, fonte e referência GitHub;
- integrações e variáveis de configuração sem valores sensíveis;
- decisões explícitas e suas fontes.
Manter em .specsfy/PACKAGES.md:
- todos os pacotes npm e Composer encontrados nos manifests e lockfiles,
inclusive dependências transitivas registradas localmente;
- gerenciador, escopo, nome, versão, finalidade curta e fonte de cada pacote;
- descrição declarada no lockfile ou no pacote instalado, quando existir;
- aviso explícito quando os metadados locais não comprovarem a finalidade.
Mapeamento por stack:
| Stack |
O que mapear |
| Laravel |
rotas, controllers, models, services, jobs, policies, Blade, migrations e Pest/PHPUnit |
| Node, Next.js, React ou Astro |
páginas, rotas de API, componentes, módulos, scripts e Vitest/Jest/Node Test |
Limites
- Não copie segredos, valores de
.env, dados de produção ou código inteiro.
- Não documente arquivos ignorados pelo Git. Dentro de um repositório, o
script lê somente arquivos rastreados ou não ignorados pelo
.gitignore;
fora dele, usa a lista fixa de pastas geradas.
- Não apresente heurística como fato confirmado.
- Não substitua specs,
PROJECT.md ou arquivos humanos em .specsfy/.
PACKAGES.md é a única projeção reconstruída nesse diretório e preserva o
conteúdo fora do bloco gerado.
- A construção funciona sem rede. Quando o repositório GitHub de um pacote não
estiver declarado localmente nem for conhecido, publique uma busca GitHub
rotulada como tal em vez de inventar uma URL.
1---2name: specsfy-documentator3description: "Reconstrói a documentação técnica completa em docs/ e o registro de pacotes npm e Composer em .specsfy/PACKAGES.md a partir do código existente, manifests e lockfiles, preservando o conteúdo humano. Use depois de cada implementação, quando o monitor de contexto ou o progresso apontar docs/ ou PACKAGES.md ausente ou desatualizado, ou quando o usuário pedir para documentar o sistema. Não use para escrever specs, PROJECT.md ou regras (use specsfy-03-specify, specsfy-setup ou specsfy-aux-rules)."4metadata:5 source: https://skillmd.com/skills/promovaweb/specsfy-documentator6---78# Documentar o sistema910Esta skill mantém `docs/` e `.specsfy/PACKAGES.md` como retrato fiel do11projeto atual. A documentação é uma projeção reconstruível das fontes locais:12o script gera a base, você confere e corrige somente o que o código não13sustenta.1415## Pronto quando1617- `specsfy docs build --project <raiz> --check` termina sem falha.18- `docs/` cobre toda a lista de `Cobertura obrigatória` e19 `.specsfy/PACKAGES.md` lista todos os pacotes dos manifests e lockfiles.20- Conteúdo humano fora dos blocos `specsfy:documentator` continua intacto.21- A tarefa que acionou a skill registra comando, resultado e arquivos22 atualizados.2324## Preparação obrigatória2526Antes de executar esta skill, carregue obrigatoriamente `$specsfy-setup` na27raiz do projeto. Em handoff automático, carregue-o de novo antes desta etapa.28Reutilize a raiz confirmada na conversa e não prossiga se o setup apontar uma29pendência.3031## Modo de interação3233Modo de interação: `sem perguntas`.34Não formule perguntas nesta skill. Registre como não identificado todo dado35que as fontes executáveis não sustentarem.3637## Executar38391. Leia em paralelo as instruções locais, `PROJECT.md`, `.specsfy/STACK.md`,40 `.specsfy/RULES.md`, `.specsfy/DATABASE.md`, manifests, lockfiles,41 metadados instalados e o código existente. Antes de alterar a topologia42 publicada, leia [o padrão documental](references/documentation-standard.md).432. Construa toda a documentação e `.specsfy/PACKAGES.md`, mesmo quando a skill44 for acionada sem spec ou implementação recente:4546 ```bash47 specsfy docs build --project <raiz>48 ```4950 Pelo MCP, use a tool `docs_build`. Sem o binário instalado, rode o script51 equivalente:5253 ```bash54 node .agents/skills/specsfy-documentator/scripts/build_documentation.mjs \55 --project <raiz>56 ```57583. Inspecione os arquivos gerados e corrija manualmente apenas inferências que59 o código não sustente. Não acrescente escolhas de arquitetura, relações ou60 integrações sem fonte.614. Prove que a documentação representa o estado atual:6263 ```bash64 specsfy docs build --project <raiz> --check65 ```6667 Pelo MCP, use a tool `docs_build`. Sem o binário instalado, rode o script68 equivalente:6970 ```bash71 node .agents/skills/specsfy-documentator/scripts/build_documentation.mjs \72 --project <raiz> --check73 ```74755. Registre na tarefa o comando, o resultado e os arquivos atualizados.7677O conteúdo humano fica fora dos blocos `specsfy:documentator`, inclusive em78`.specsfy/PACKAGES.md`. O bloco é reconstruído a cada execução; tudo fora79dele é preservado.8081## Cobertura obrigatória8283Manter em `docs/`:8485- portal e roteiro de leitura;86- arquitetura, componentes e UML em Mermaid;87- registro da aplicação e das implementações existentes;88- banco e entidades com `erDiagram`;89- fluxos com `flowchart` e `sequenceDiagram`;90- guia e resumo dos testes;91- frontend, views, React e Tailwind;92- bibliotecas e pacotes nativos, de framework, integrados e terceiros, com93 versão, fonte e referência GitHub;94- integrações e variáveis de configuração sem valores sensíveis;95- decisões explícitas e suas fontes.9697Manter em `.specsfy/PACKAGES.md`:9899- todos os pacotes npm e Composer encontrados nos manifests e lockfiles,100 inclusive dependências transitivas registradas localmente;101- gerenciador, escopo, nome, versão, finalidade curta e fonte de cada pacote;102- descrição declarada no lockfile ou no pacote instalado, quando existir;103- aviso explícito quando os metadados locais não comprovarem a finalidade.104105Mapeamento por stack:106107| Stack | O que mapear |108| --- | --- |109| Laravel | rotas, controllers, models, services, jobs, policies, Blade, migrations e Pest/PHPUnit |110| Node, Next.js, React ou Astro | páginas, rotas de API, componentes, módulos, scripts e Vitest/Jest/Node Test |111112## Limites113114- Não copie segredos, valores de `.env`, dados de produção ou código inteiro.115- Não documente arquivos ignorados pelo Git. Dentro de um repositório, o116 script lê somente arquivos rastreados ou não ignorados pelo `.gitignore`;117 fora dele, usa a lista fixa de pastas geradas.118- Não apresente heurística como fato confirmado.119- Não substitua specs, `PROJECT.md` ou arquivos humanos em `.specsfy/`.120 `PACKAGES.md` é a única projeção reconstruída nesse diretório e preserva o121 conteúdo fora do bloco gerado.122- A construção funciona sem rede. Quando o repositório GitHub de um pacote não123 estiver declarado localmente nem for conhecido, publique uma busca GitHub124 rotulada como tal em vez de inventar uma URL.