Pular para conteúdo

name: initialize-docs description: 'Create standard docs hierarchy (01-09 dirs, READMEs, briefing/UCs/DER/ADRs/APIs/tests/ops). Triggers: "inicializar docs", "criar estrutura docs", "setup documentacao". Skip if structure exists and no --force.' argument-hint: "[--dry-run | --force | --no-move]" allowed-tools: - Read - Write - Glob - Grep - Bash - Edit

Skill: Inicializar Estrutura de Documentacao

Inicializa a estrutura padrao de documentacao do projeto, criando diretorios e arquivos de template.

Argumentos

$ARGUMENTS

Instrucoes

Execute os seguintes passos para inicializar a estrutura de documentacao:

1. Verificar Estrutura Atual

Primeiro, verifique o diretorio docs/ atual usando Glob e Bash.

Configuracao

Se config.json existe no diretorio desta skill, usar a estrutura customizada nele definida (campo structure, docs_dir, keep_in_root, file_routing). Caso contrario, usar a estrutura default 01-09 documentada abaixo.

2. Estrutura Padrao de Diretorios

Crie os seguintes diretorios (se nao existirem):

docs/
-- 01-briefing-discovery/      # Documentos de briefing, requisitos iniciais
-- 02-requisitos-casos-uso/    # Casos de uso (UC-XXX-*.md)
-- 03-modelagem-dados/         # DERs, schemas de banco (DER-*.md)
-- 04-arquitetura-sistema/     # ADRs, diagramas de arquitetura (ADR-*.md)
-- 05-definicao-apis/          # Contratos de API
|   -- REST/                   # APIs REST
|   -- gRPC/                   # Definicoes gRPC/protobuf
|   -- WEBHOOKS/               # Webhooks
|   -- MESSAGING/              # Mensageria (RabbitMQ, Kafka, etc)
-- 06-ui-ux-design/            # Wireframes, mockups, guias de estilo
-- 07-plano-testes/            # Planos de teste, casos de teste
-- 08-operacoes/               # Runbooks, procedimentos operacionais
-- 09-entregaveis/             # Documentos de entrega, releases notes

3. Criar Diretorios

Preferir o script scripts/scaffold.sh (mesmo diretorio desta skill), que cria todos os diretorios, gera READMEs template e e idempotente:

# Dry-run para ver o que seria feito
bash skills/initialize-docs/scripts/scaffold.sh --dry-run

# Criar estrutura
bash skills/initialize-docs/scripts/scaffold.sh

# Forcar reescrita de READMEs
bash skills/initialize-docs/scripts/scaffold.sh --force

# Usar diretorio customizado
bash skills/initialize-docs/scripts/scaffold.sh --dir=documentation

Alternativa manual (sem script), se o script nao estiver disponivel:

mkdir -p docs/01-briefing-discovery docs/02-requisitos-casos-uso \
         docs/03-modelagem-dados docs/04-arquitetura-sistema \
         docs/05-definicao-apis/REST docs/05-definicao-apis/gRPC \
         docs/05-definicao-apis/WEBHOOKS docs/05-definicao-apis/MESSAGING \
         docs/06-ui-ux-design docs/07-plano-testes \
         docs/08-operacoes docs/09-entregaveis

4. Criar READMEs Template

Para cada diretorio, crie um README.md se nao existir, com: - Descricao do proposito do diretorio - Convencoes de nomenclatura - Tipos de arquivo esperados - Links para templates relevantes

docs/README.md (Principal)

# Documentacao do Projeto

| Diretorio | Descricao |
|-----------|-----------|
| [01-briefing-discovery](./01-briefing-discovery/) | Documentos iniciais, briefings, requisitos de negocio |
| [02-requisitos-casos-uso](./02-requisitos-casos-uso/) | Casos de uso detalhados (UC-*) |
| [03-modelagem-dados](./03-modelagem-dados/) | Modelagem de dados, DERs, schemas |
| [04-arquitetura-sistema](./04-arquitetura-sistema/) | Decisoes de arquitetura (ADR-*), diagramas |
| [05-definicao-apis](./05-definicao-apis/) | Contratos de API (REST, gRPC, Webhooks) |
| [06-ui-ux-design](./06-ui-ux-design/) | Wireframes, mockups, guias de estilo |
| [07-plano-testes](./07-plano-testes/) | Planos e casos de teste |
| [08-operacoes](./08-operacoes/) | Runbooks, procedimentos operacionais |
| [09-entregaveis](./09-entregaveis/) | Release notes, documentos de entrega |

## Convencoes de Nomenclatura

- **UC-XXX-NNN**: Caso de Uso
- **ADR-NNN**: Architectural Decision Record
- **DER-XXX**: Diagrama Entidade-Relacionamento
- **TC-NNN**: Test Case
- **RB-NNN**: Runbook

5. Mover Arquivos Existentes

Se existirem arquivos na raiz de docs/, mova-os para os diretorios apropriados:

Padrao do Arquivo Destino
UC-*.md 02-requisitos-casos-uso/
DER-*.md, SCHEMA-*.md 03-modelagem-dados/
ADR-*.md 04-arquitetura-sistema/
*-api.md, *.proto.md 05-definicao-apis/{tipo}/
TC-*.md, TP-*.md 07-plano-testes/
RB-*.md, RUNBOOK-*.md 08-operacoes/
RELEASE-*.md, CHANGELOG*.md 09-entregaveis/
*.pdf, BRIEFING-*.md 01-briefing-discovery/
tasks-*.md, cronograma*.md manter na raiz de docs/

6. Relatorio de Execucao

Ao final, exiba um relatorio com: - Diretorios criados - Arquivos movidos - Templates criados - Avisos (arquivos que nao puderam ser movidos automaticamente)

Opcoes de Argumento

  • --dry-run: Apenas mostra o que seria feito, sem executar
  • --force: Sobrescreve READMEs existentes
  • --no-move: Apenas cria diretorios e templates, nao move arquivos

Notas

  • Este comando e idempotente - pode ser executado multiplas vezes
  • Arquivos ja existentes nao sao sobrescritos (exceto com --force)
  • Arquivos de projeto como tasks-*.md e cronograma.md sao mantidos na raiz

Gotchas

Idempotente nao significa "rodar sem pensar"

Rodar duas vezes nao estraga nada (READMEs nao sobrescritos), mas se o projeto ja tem uma organizacao ALTERNATIVA (ex: docs/rfcs/, docs/guides/), a skill vai criar 01-09 ao lado sem aviso. Antes de rodar, verificar docs/ — se existe organizacao alternativa, perguntar ao usuario se deve coexistir ou substituir.

tasks-.md e cronograma.md ficam NA RAIZ de docs/

Nao mover esses arquivos para subdiretorios. Eles sao arquivos de projeto global, nao artefatos de categoria. O mapeamento do passo 5 exclui explicitamente esses padroes.

--force sobrescreve READMEs, nao o conteudo dos diretorios

A flag --force regenera os READMEs template. Nao deleta arquivos reais (UCs, ADRs) dentro dos diretorios. Mas se o usuario customizou os READMEs, --force apaga essas customizacoes.

Movimentacao automatica pode errar em casos ambiguos

Um arquivo API-GATEWAY-SETUP.md pode ir para 04-arquitetura ou 05-definicao-apis dependendo do conteudo. Quando o padrao nao bate claramente, listar o arquivo no relatorio como "nao movido — requer revisao manual" ao inves de chutar.

Se UC-CAD-001.md referencia ../outro-doc.md, mover o UC para 02-requisitos-casos-uso/ quebra o link. Apos mover, avisar no relatorio sobre links que podem precisar atualizacao — nao tentar corrigir automaticamente.