docuemntação

2026-08-12 14:01:38 -03:00 · 2026-08-12 14:01:38 -03:00 · b92dc7b06e
commit b92dc7b06e
parent 9fa1b57614
12 changed files with 432 additions and 4 deletions
--- a/DOCUMENTACAO/INDICE
+++ b/DOCUMENTACAO/INDICE
@ -0,0 +1,40 @@
+---
+type: structural
+name: INDICE
+description: Índice central navegável de todas as categorias de documentação
+updatedAt: "2026-08-12"
+---
+
+# Índice de Documentação
+
+Este documento serve como ponto central de navegação para todas as documentações do ecossistema. Os documentos serão listados aqui conforme forem criados.
+
+## Arquitetura
+Decisões técnicas e arquiteturais (ADRs) que impactam o sistema.
+**Template**: `DOCUMENTACAO/arquitetura/_template-adr`
+
+- *(Nenhum documento criado ainda)*
+
+## Módulos
+Documentação do domínio, glossário e entidades de cada módulo do sistema.
+**Template**: `DOCUMENTACAO/modulos/_template-modulo`
+
+- *(Nenhum documento criado ainda)*
+
+## Regras de Negócio
+Regras operacionais e de negócio extraídas do código ou definidas pelos operadores.
+**Template**: `DOCUMENTACAO/regras-negocio/_template-regra`
+
+- *(Nenhum documento criado ainda)*
+
+## Contratos
+Definição de contratos de API, schemas de dados e especificações de endpoints.
+**Template**: `DOCUMENTACAO/contratos/_template-contrato`
+
+- *(Nenhum documento criado ainda)*
+
+## Fluxos
+Mapeamento de jornadas do usuário, interações de interface e fluxos de uso do sistema.
+**Template**: `DOCUMENTACAO/fluxos/_template-fluxo`
+
+- *(Nenhum documento criado ainda)*
--- a/DOCUMENTACAO/README
+++ b/DOCUMENTACAO/README
@ -0,0 +1,53 @@
+---
+type: structural
+name: README
+description: Manifesto e guia para o Desenvolvimento Orientado a Documentação (DDD)
+updatedAt: "2026-08-12"
+---
+
+# Documentation-Driven Development (DDD)
+
+## Manifesto
+No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regra, skill, workflow, módulo, API, decisão técnica) deve ser implementado sem documentação prévia. A documentação é a especificação viva.
+
+## Princípios
+1. **Doc First** — Nenhum artefato novo sem documentação prévia.
+2. **Doc como Contrato** — A documentação é a especificação; o código a implementa.
+3. **Código Satisfaz Doc** — Se o código diverge da doc, o código está errado.
+4. **Sincronia Obrigatória** — Mudança no código → atualização da doc; mudança na doc → atualização no código.
+5. **Templates Padronizados** — Cada categoria tem seu template; nenhuma documentação é criada do zero.
+6. **Leitura Antes de Escrita** — Antes de documentar, leia o que já existe.
+
+## Categorias de Documentação
+
+| Categoria | Diretório | O que documenta | Template |
+| :--- | :--- | :--- | :--- |
+| Arquitetura | `DOCUMENTACAO/arquitetura/` | Decisões técnicas e arquiteturais (ADRs) | `_template-adr` |
+| Módulos | `DOCUMENTACAO/modulos/` | Domínio, glossário e entidades de cada módulo | `_template-modulo` |
+| Regras de Negócio | `DOCUMENTACAO/regras-negocio/` | Regras extraídas do código ou definidas pelo operador | `_template-regra` |
+| Contratos | `DOCUMENTACAO/contratos/` | Contratos de API, schemas, endpoints | `_template-contrato` |
+| Fluxos | `DOCUMENTACAO/fluxos/` | Jornadas do usuário e fluxos de uso | `_template-fluxo` |
+
+## Workflow DDD
+1. **Receber demanda**
+2. **Documentar** (criar/atualizar documentação na categoria apropriada usando o template)
+3. **Revisar** (apresentar a documentação ao operador para validação)
+4. **Implementar** (codificar de acordo com a documentação aprovada)
+5. **Validar** (verificar se o código satisfaz a doc 100%)
+6. **Sincronizar** (atualizar a documentação se a implementação revelou ajustes necessários)
+
+## Integração com o Ecossistema
+
+| Artefato | Como Integra com DDD |
+| :--- | :--- |
+| `rules/regras-negocio-md.md` | Define formato e obrigatoriedade de documentar regras de negócio |
+| `skills/documentar-decisao-tecnica` | Fornece habilidade para criar e atualizar ADRs |
+| `skills/documentar-dominio-modulo` | Estrutura para levantar glossário e domínio de módulos |
+| `skills/documentar-regras-negocio` | Habilidade para extrair e redigir regras |
+| `rules/diagnostico-antes-correcao.md`| Diagnóstico exige leitura e alinhamento com doc antes de corrigir bugs |
+
+## Referências
+- `rules/ddd-documentacao-primeiro.md`
+- `skills/documentar-decisao-tecnica`
+- `skills/documentar-dominio-modulo`
+- `skills/documentar-regras-negocio`
--- a/DOCUMENTACAO/arquitetura/_template-adr
+++ b/DOCUMENTACAO/arquitetura/_template-adr
@ -0,0 +1,49 @@
+---
+type: template
+name: _template-adr
+description: Template para Architecture Decision Records (ADRs)
+updatedAt: "2026-08-12"
+---
+
+# ADR: <PREENCHER TÍTULO>
+
+## Data
+<PREENCHER DATA>
+
+## Status
+<Proposta | Aceita | Rejeitada | Descontinuada>
+
+## Autores
+<PREENCHER AUTORES>
+
+## Contexto
+<Descrever o cenário que motiva a necessidade de uma decisão técnica. O que está acontecendo? Qual o problema a ser resolvido?>
+
+## Decisão
+<Descrever claramente a decisão técnica que está sendo tomada para resolver o problema descrito no contexto.>
+
+## Alternativas Consideradas
+<Listar outras abordagens avaliadas e os motivos para não terem sido escolhidas.>
+- Alternativa 1: [...] (Motivo da rejeição: [...])
+- Alternativa 2: [...] (Motivo da rejeição: [...])
+
+## Consequências
+
+### Positivas
+- <Listar ganhos com a decisão>
+- [...]
+
+### Negativas
+- <Listar desvantagens, trade-offs ou custos gerados>
+- [...]
+
+### Neutras
+- <Listar impactos que não são inerentemente bons ou ruins>
+- [...]
+
+## Impacto no Monorepo
+<Como essa decisão afeta a estrutura existente? Módulos afetados? Mudanças em dependências?>
+
+## Referências
+<Links úteis, issues, PRs ou outras documentações que sustentem a decisão>
+- [...]
--- a/DOCUMENTACAO/contratos/_template-contrato
+++ b/DOCUMENTACAO/contratos/_template-contrato
@ -0,0 +1,70 @@
+---
+type: template
+name: _template-contrato
+description: Template para definição de contratos de API e schemas
+updatedAt: "2026-08-12"
+---
+
+# Contrato: <PREENCHER NOME DO SERVIÇO OU DOMÍNIO>
+
+## Serviço
+<Nome e breve descrição do serviço ou microsserviço responsável por esta API>
+
+## Base URL
+`<URL base de desenvolvimento e/ou produção>`
+
+## Autenticação
+<Como autenticar? Token Bearer, API Key, sem auth?>
+
+## Endpoints
+
+| Método | Rota | Descrição | Auth |
+| :--- | :--- | :--- | :--- |
+| `GET` | `/rota/exemplo` | `<Descrição>` | `Sim/Não` |
+| `POST` | `/rota/exemplo` | `<Descrição>` | `Sim/Não` |
+
+---
+
+## Detalhamento por Endpoint
+
+### `<MÉTODO>` `<ROTA>`
+<Breve descrição adicional do endpoint>
+
+**Request Params**
+- `param1` (tipo, obrigatório?): <descrição>
+
+**Body Schema**
+```json
+{
+  // Exemplo de body esperado
+}
+```
+
+**Response Schema (Sucesso)**
+```json
+{
+  // Exemplo de resposta 200/201
+}
+```
+
+**Códigos de Erro**
+- `400 Bad Request`: <motivo>
+- `404 Not Found`: <motivo>
+
+---
+
+## Schema Zod de Referência
+<Adicionar fragmento de código Zod caso o projeto utilize validação via schema>
+```typescript
+// z.object({ ... })
+```
+
+## Exemplos de Uso
+<Comandos curl, snippets fetch ou scripts de exemplo>
+```bash
+curl -X GET ...
+```
+
+## Referências
+<Links para outras documentações, regras de negócio ou ADRs relacionadas>
+- [...]
--- a/DOCUMENTACAO/fluxos/_template-fluxo
+++ b/DOCUMENTACAO/fluxos/_template-fluxo
@ -0,0 +1,48 @@
+---
+type: template
+name: _template-fluxo
+description: Template para mapeamento de jornadas do usuário e fluxos de uso
+updatedAt: "2026-08-12"
+---
+
+# Fluxo: <PREENCHER NOME DO FLUXO>
+
+## Objetivo do Fluxo
+<O que o usuário ou sistema deseja alcançar ao completar este fluxo?>
+
+## Ator(es)
+<Quem inicia e participa do fluxo? (Ex: Cliente, Administrador, Sistema, Job em background)>
+- [...]
+
+## Pré-condições
+<O que precisa ser verdadeiro antes deste fluxo iniciar? (Ex: Usuário estar logado, possuir saldo, etc)>
+- [...]
+
+## Fluxo Principal
+<O caminho feliz. O passo a passo em ordem cronológica de como o objetivo é alcançado>
+1. [...]
+2. [...]
+3. [...]
+
+## Fluxos Alternativos
+<Caminhos secundários ou desvios do fluxo principal que ainda levam a um resultado bem sucedido (ou parcial)>
+- **Alternativa A** (Ocorre no passo X se a condição Y for verdadeira):
+  1. [...]
+  2. [...] (retorna ao passo Z do fluxo principal)
+
+## Tratamento de Erros
+<Como o fluxo reage a falhas, validações incorretas ou problemas de sistema>
+- **Erro 1** (Falha no passo X): Ação de mitigação e mensagem de erro apresentada.
+
+## Regras de Negócio Aplicáveis
+<Quais regras validam e controlam este fluxo? Linkar para `DOCUMENTACAO/regras-negocio/`>
+- `Regra X`: [...]
+- `Regra Y`: [...]
+
+## Telas Envolvidas
+<Se aplicável, quais telas da UI compõem o fluxo>
+- [...]
+
+## Referências
+<Links para protótipos, designs, issues ou módulos relacionados>
+- [...]
--- a/DOCUMENTACAO/modulos/_template-modulo
+++ b/DOCUMENTACAO/modulos/_template-modulo
@ -0,0 +1,36 @@
+---
+type: template
+name: _template-modulo
+description: Template para documentação de módulos e domínios
+updatedAt: "2026-08-12"
+---
+
+# Módulo: <PREENCHER NOME DO MÓDULO>
+
+## Área de Conhecimento
+<Descrever brevemente o domínio de negócio deste módulo. Qual sua responsabilidade principal e área de atuação no ecossistema?>
+
+## Glossário do Módulo
+
+| Termo | Definição | Contexto de Uso |
+| :--- | :--- | :--- |
+| `<Termo 1>` | `<Definição>` | `<Contexto>` |
+| `<Termo 2>` | `<Definição>` | `<Contexto>` |
+
+## Entidades Principais
+<Descrever as entidades de dados fundamentais que compõem este módulo>
+- **Entidade A**: <Descrição do papel da entidade e principais atributos>.
+- **Entidade B**: <Descrição do papel da entidade e principais atributos>.
+
+## Legislação Aplicável
+<Listar leis, normas técnicas ou portarias que afetam as regras deste domínio, se aplicável>
+- [...]
+
+## Fluxos do Domínio
+<Listar os fluxos de negócios centrais orquestrados por este módulo, referenciando documentos em `DOCUMENTACAO/fluxos/` se existirem>
+- **Fluxo Principal X**: [...]
+- **Fluxo Principal Y**: [...]
+
+## Vocabulário de Interface
+<Termos específicos que devem ser usados na UI para manter a consistência com a linguagem ubíqua do domínio>
+- [...]
--- a/DOCUMENTACAO/regras-negocio/_template-regra
+++ b/DOCUMENTACAO/regras-negocio/_template-regra
@ -0,0 +1,34 @@
+---
+type: template
+name: _template-regra
+description: Template para especificação de regras de negócio
+updatedAt: "2026-08-12"
+---
+
+# Regra: <PREENCHER NOME DA REGRA>
+
+## Contexto
+<Descrever em qual situação, processo ou fluxo essa regra é aplicada. Qual o propósito de negócio dela?>
+
+## Critérios de Entrada / Identificação
+<O que aciona essa regra? Quais dados ou condições precisam existir para que ela seja avaliada?>
+- Condição 1: [...]
+- Condição 2: [...]
+
+## Regras de Processamento
+<Passo a passo lógico e determinístico da regra. Como a validação ou transformação acontece?>
+1. [...]
+2. [...]
+3. [...]
+
+## Casos de Revisão Manual
+<Existem exceções onde o sistema não decide automaticamente e envia para análise humana? Listar os cenários.>
+- Cenário A: [...]
+
+## Estratégia de Fusão / Resultado
+<Qual é o output da execução dessa regra? (ex: aprovação, recusa, alteração de status, cálculo final)>
+- [...]
+
+## Dependências Externas
+<A regra depende de integrações de terceiros, APIs, ou outras regras do sistema para ser processada?>
+- [...]
--- a/9
+++ b/9
@ -11,6 +11,7 @@ Usado como **git submodule** `.agent` nos monorepos.
 2. **Aprendizado contínuo** — conhecimento evolui a cada sessão via workflow `aprimorar-IA`
 3. **Vendor-neutral** — arquitetura em Markdown puro, compatível com qualquer LLM
 4. **Sem extensões** — artefatos de conhecimento não possuem extensão de arquivo
+5. **Documentation-Driven** — documentação precede implementação; DOCUMENTACAO/ é a fonte de verdade

 ---

@ -19,6 +20,14 @@ Usado como **git submodule** `.agent` nos monorepos.
 ```
 .memoria-ia/                    ← armazenamento de memórias do projeto (mesmo nível do .agent, versionado pelo pai)
 .agent/                             ← raiz do repositório (submodulo)
+├── DOCUMENTACAO/                   ← hub DDD — documentação precede código
+│   ├── README                      ← manifesto DDD: princípios e workflow
+│   ├── INDICE                      ← índice navegável de toda documentação
+│   ├── arquitetura/                ← decisões técnicas (ADRs)
+│   ├── modulos/                    ← domínio e glossário por módulo
+│   ├── regras-negocio/             ← regras de negócio documentadas
+│   ├── contratos/                  ← contratos de API e schemas
+│   └── fluxos/                     ← jornadas do usuário
 ├── README                          ← este arquivo
 ├── TOOLS                           ← ferramentas CLI recomendadas
 ├── manifesto.json                  ← inventário de todos os artefatos
--- a/agents/documentacao/agent.json
+++ b/agents/documentacao/agent.json
@ -8,7 +8,7 @@
      "systemPromptSections": [
        {
          "title": "Identidade e Escopo",
-          "content": "# Agente de Documentação (@documentacao)\n\n## Identidade\n\nVocê é o agente responsável por tornar o conhecimento do ecossistema Azteca acessível — para desenvolvedores, usuários finais e o próprio agente de IA. Você transforma código complexo, decisões técnicas e regras de negócio em documentação clara e utilizável.\n\n## Idioma\n\nToda sua comunicação — incluindo raciocínio interno, reflexões e respostas — **DEVE** ser em **português brasileiro (pt-BR)**. Nunca use inglês para pensar, raciocinar ou responder.\n\n## Escopo de Atuação\n\n- Todos os pacotes: `*-back`, `*-front`, `*-comuns`\n- Diretório `.agent/` (base/ herdado + local/ extensões + memory/)\n- Arquivos `.regras-negocio.md` co-localizados\n- JSDoc em funções compartilhadas\n- Guias de usuário e ajuda contextual nas telas\n- ADRs (Architecture Decision Records)\n\n## Responsabilidades\n\n1. **Diagnosticar lacunas antes de documentar** — executar a skill `diagnosticar-lacunas-documentacao` para identificar o que falta (ver `global/rules/diagnostico-antes-correcao`)\n2. Criar e manter arquivos `.regras-negocio.md` para módulos com lógica complexa\n3. Escrever JSDoc em funções e serviços compartilhados\n4. Criar guias de ajuda para usuários finais (módulo de ajuda contextual)\n5. Manter o `README` e documentação do projeto atualizada\n6. Documentar APIs internas (contratos de rotas, parâmetros, retornos)\n\n## Restrições\n\n- NUNCA documentar sem antes diagnosticar o que está ausente ou desatualizado (ver `global/rules/diagnostico-antes-correcao`)\n- NUNCA inventar, fabricar ou supor regras de negócio — documenta **exclusivamente** o que o código implementa ou o que o operador declarou\n- NUNCA descrever comportamento de API, schema ou componente sem antes **ler o código-fonte** para confirmar\n- NUNCA criar exemplos fictícios que possam ser confundidos com dados reais do sistema\n- NÃO duplica conteúdo entre artefatos — referencia via links\n- Documentação para usuário final deve usar linguagem do domínio, sem termos técnicos\n- JSDoc documenta o \"porquê\", não o \"o quê\" (que o TypeScript já expressa)\n- Quando não souber como uma funcionalidade opera, **ler o código antes de documentar** — nunca presumir\n\n## Colaborações\n\n- **Recebe código para documentar de:** `@back`, `@front`\n- **Recebe decisões arquiteturais de:** `@arquiteto`\n- **Fornece docs para:** `@comercial` (argumentos sobre features)\n- **Atualiza artefatos com:** regras e padrões definidos em qualquer conversa\n\n## Tom e Estilo\n\n- Claro, preciso e orientado ao leitor-alvo\n- Para usuários: linguagem do domínio, sem TI\n- Para desenvolvedores: técnico, com exemplos de código\n- Para o agente de IA: estruturado, sem ambiguidade\n\n\n## Checklist de documentação completa\n\n- [ ] Módulos com lógica complexa têm `.regras-negocio.md`?\n- [ ] Funções compartilhadas têm JSDoc?\n- [ ] ADRs registram decisões de alto impacto?\n- [ ] Ajuda contextual usa vocabulário do domínio?\n- [ ] Referências cruzadas entre artefatos são válidas?\n\n## Memória Persistente\n\nO ecossistema adota uma arquitetura de memória em duas camadas:\n\n- **Memórias do Projeto ()**: Armazena decisões de negócio, contexto do produto, especificações funcionais e ADRs na raiz do projeto pai (versionado pelo repositório pai).\n- **Evoluções da IA ()**: Armazena registros de sessões , otimizações dos agentes e melhorias da arquitetura multiagente (versionado pelo submódulo ).\n\n### Regras de Operação\n- Gravar memórias de projeto em  (na raiz do pai).\n- Gravar evoluções da IA em  (no submódulo).\n- Toda memória deve ser um arquivo Markdown em  com frontmatter (, , , , ).\n"
+          "content": "# Agente de Documentação (@documentacao)\n\n## Identidade\n\nVocê é o agente responsável por tornar o conhecimento do ecossistema Azteca acessível — para desenvolvedores, usuários finais e o próprio agente de IA. Você transforma código complexo, decisões técnicas e regras de negócio em documentação clara e utilizável.\n\n## Idioma\n\nToda sua comunicação — incluindo raciocínio interno, reflexões e respostas — **DEVE** ser em **português brasileiro (pt-BR)**. Nunca use inglês para pensar, raciocinar ou responder.\n\n## Escopo de Atuação\n\n- `DOCUMENTACAO/` — hub central de documentação DDD\n- Todos os pacotes: `*-back`, `*-front`, `*-comuns`\n- Diretório `.agent/` (base/ herdado + local/ extensões + memory/)\n- Arquivos `.regras-negocio.md` co-localizados\n- JSDoc em funções compartilhadas\n- Guias de usuário e ajuda contextual nas telas\n- ADRs (Architecture Decision Records)\n\n## Responsabilidades\n\n0. **Aplicar Documentation-Driven Development** — garantir que toda implementação tenha documentação prévia em `DOCUMENTACAO/` usando templates padronizados (ver `rules/ddd-documentacao-primeiro`)\n1. **Diagnosticar lacunas antes de documentar** — executar a skill `diagnosticar-lacunas-documentacao` para identificar o que falta (ver `global/rules/diagnostico-antes-correcao`)\n2. Criar e manter arquivos `.regras-negocio.md` para módulos com lógica complexa\n3. Escrever JSDoc em funções e serviços compartilhados\n4. Criar guias de ajuda para usuários finais (módulo de ajuda contextual)\n5. Manter o `README` e documentação do projeto atualizada\n6. Documentar APIs internas (contratos de rotas, parâmetros, retornos)\n\n## Restrições\n\n- NUNCA permitir implementação de artefato novo sem documentação prévia em DOCUMENTACAO/ (ver rules/ddd-documentacao-primeiro)\n- NUNCA documentar sem antes diagnosticar o que está ausente ou desatualizado (ver `global/rules/diagnostico-antes-correcao`)\n- NUNCA inventar, fabricar ou supor regras de negócio — documenta **exclusivamente** o que o código implementa ou o que o operador declarou\n- NUNCA descrever comportamento de API, schema ou componente sem antes **ler o código-fonte** para confirmar\n- NUNCA criar exemplos fictícios que possam ser confundidos com dados reais do sistema\n- NÃO duplica conteúdo entre artefatos — referencia via links\n- Documentação para usuário final deve usar linguagem do domínio, sem termos técnicos\n- JSDoc documenta o \"porquê\", não o \"o quê\" (que o TypeScript já expressa)\n- Quando não souber como uma funcionalidade opera, **ler o código antes de documentar** — nunca presumir\n\n## Colaborações\n\n- **Mantém hub DDD:** DOCUMENTACAO/ — fonte de verdade para todos os agentes\n- **Recebe código para documentar de:** `@back`, `@front`\n- **Recebe decisões arquiteturais de:** `@arquiteto`\n- **Fornece docs para:** `@comercial` (argumentos sobre features)\n- **Atualiza artefatos com:** regras e padrões definidos em qualquer conversa\n\n## Tom e Estilo\n\n- Claro, preciso e orientado ao leitor-alvo\n- Para usuários: linguagem do domínio, sem TI\n- Para desenvolvedores: técnico, com exemplos de código\n- Para o agente de IA: estruturado, sem ambiguidade\n\n\n## Checklist de documentação completa\n\n- [ ] Módulos com lógica complexa têm `.regras-negocio.md`?\n- [ ] Funções compartilhadas têm JSDoc?\n- [ ] ADRs registram decisões de alto impacto?\n- [ ] Ajuda contextual usa vocabulário do domínio?\n- [ ] Referências cruzadas entre artefatos são válidas?\n\n## Memória Persistente\n\nO ecossistema adota uma arquitetura de memória em duas camadas:\n\n- **Memórias do Projeto ()**: Armazena decisões de negócio, contexto do produto, especificações funcionais e ADRs na raiz do projeto pai (versionado pelo repositório pai).\n- **Evoluções da IA ()**: Armazena registros de sessões , otimizações dos agentes e melhorias da arquitetura multiagente (versionado pelo submódulo ).\n\n### Regras de Operação\n- Gravar memórias de projeto em  (na raiz do pai).\n- Gravar evoluções da IA em  (no submódulo).\n- Toda memória deve ser um arquivo Markdown em  com frontmatter (, , , , ).\n"
        }
      ],
      "toolNames": [
--- a/agents/documentacao/persona
+++ b/agents/documentacao/persona
@ -29,6 +29,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas

 ## Escopo de Atuação

+- `DOCUMENTACAO/` — hub central de documentação DDD
 - Todos os pacotes: `*-back`, `*-front`, `*-comuns`
 - Diretório `.agent/` (base/ herdado + local/ extensões + memory/)
 - Arquivos `.regras-negocio.md` co-localizados
@ -38,6 +39,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas

 ## Responsabilidades

+0. **Aplicar Documentation-Driven Development** — garantir que toda implementação tenha documentação prévia em `DOCUMENTACAO/` usando templates padronizados (ver `rules/ddd-documentacao-primeiro`)
 1. **Diagnosticar lacunas antes de documentar** — executar a skill `diagnosticar-lacunas-documentacao` para identificar o que falta (ver `global/rules/diagnostico-antes-correcao`)
 2. Criar e manter arquivos `.regras-negocio.md` para módulos com lógica complexa
 3. Escrever JSDoc em funções e serviços compartilhados
@ -47,6 +49,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas

 ## Restrições

+- NUNCA permitir implementação de artefato novo sem documentação prévia em DOCUMENTACAO/ (ver rules/ddd-documentacao-primeiro)
 - NUNCA documentar sem antes diagnosticar o que está ausente ou desatualizado (ver `global/rules/diagnostico-antes-correcao`)
 - NUNCA inventar, fabricar ou supor regras de negócio — documenta **exclusivamente** o que o código implementa ou o que o operador declarou
 - NUNCA descrever comportamento de API, schema ou componente sem antes **ler o código-fonte** para confirmar
@ -58,6 +61,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas

 ## Colaborações

+- **Mantém hub DDD:** DOCUMENTACAO/ — fonte de verdade para todos os agentes
 - **Recebe código para documentar de:** `@back`, `@front`
 - **Recebe decisões arquiteturais de:** `@arquiteto`
 - **Fornece docs para:** `@comercial` (argumentos sobre features)
--- a/manifesto.json
+++ b/manifesto.json
@ -1,6 +1,6 @@
 {
-  "versao": "3.0.0",
-  "atualizadoEm": "2026-08-11",
+  "versao": "3.1.0",
+  "atualizadoEm": "2026-08-12",
  "projeto": "e-licencie",
  "artefatos": {
    "global": {
@ -26,7 +26,8 @@
        "global/rules/tsconfig-ignore-deprecations.md",
        "global/rules/typescript-module-resolution.md",
        "global/rules/typescript-sem-any.md",
-        "global/rules/zod-validacao-padrao.md"
+        "global/rules/zod-validacao-padrao.md",
+        "global/rules/ddd-documentacao-primeiro.md"
      ],
      "workflows": [
        "global/workflows/aprimora-ia.md",
@ -45,6 +46,38 @@
        "global/skills/orquestrar-agentes/SKILL.md"
      ]
    },
+    "documentacao": {
+      "diretorio": "DOCUMENTACAO",
+      "manifesto": "DOCUMENTACAO/README",
+      "indice": "DOCUMENTACAO/INDICE",
+      "categorias": {
+        "arquitetura": {
+          "diretorio": "DOCUMENTACAO/arquitetura",
+          "template": "DOCUMENTACAO/arquitetura/_template-adr",
+          "descricao": "Decisões técnicas e arquiteturais (ADRs)"
+        },
+        "modulos": {
+          "diretorio": "DOCUMENTACAO/modulos",
+          "template": "DOCUMENTACAO/modulos/_template-modulo",
+          "descricao": "Domínio, glossário e entidades de cada módulo"
+        },
+        "regras-negocio": {
+          "diretorio": "DOCUMENTACAO/regras-negocio",
+          "template": "DOCUMENTACAO/regras-negocio/_template-regra",
+          "descricao": "Regras de negócio extraídas do código ou declaradas pelo operador"
+        },
+        "contratos": {
+          "diretorio": "DOCUMENTACAO/contratos",
+          "template": "DOCUMENTACAO/contratos/_template-contrato",
+          "descricao": "Contratos de API, schemas e endpoints"
+        },
+        "fluxos": {
+          "diretorio": "DOCUMENTACAO/fluxos",
+          "template": "DOCUMENTACAO/fluxos/_template-fluxo",
+          "descricao": "Jornadas do usuário e fluxos de uso"
+        }
+      }
+    },
    "agents": {
      "agente": {
        "persona": "agents/agente/persona",
--- a/rules/ddd-documentacao-primeiro.md
+++ b/rules/ddd-documentacao-primeiro.md
@ -0,0 +1,52 @@
+---
+type: rule
+name: ddd-documentacao-primeiro
+description: Regra global que exige a documentação de novos artefatos antes da implementação (Documentation-Driven Development).
+scope: global
+trigger: always_on
+priority: alta
+updatedAt: "2026-08-12"
+---
+
+# Regra: Documentação Obrigatória Antes da Implementação
+
+## Contexto
+Implementar sem documentar leva ao acúmulo de conhecimento implícito, código inconsistente e perda do conhecimento institucional. Para garantir que as decisões de design, regras de negócio e fluxos estejam claros antes de qualquer código ser escrito, adotamos o Documentation-Driven Development (DDD). A documentação atua como o contrato formal do que será construído.
+
+## Regra
+Antes de implementar qualquer novo artefato (regra, skill, workflow, módulo, endpoint de API, decisão técnica) ou realizar alterações substanciais em artefatos existentes, o agente **DEVE OBRIGATORIAMENTE** criar ou atualizar a documentação na pasta `DOCUMENTACAO/` utilizando o template apropriado da respectiva categoria.
+
+## Protocolo DDD
+
+Para toda nova demanda ou funcionalidade, siga rigorosamente os passos abaixo:
+
+1. **Identificar Categoria**: Analisar a demanda e determinar em qual(is) categoria(s) de documentação ela se encaixa (arquitetura, módulos, regras-negócio, contratos, fluxos).
+2. **Consultar Template**: Consultar o respectivo template em `DOCUMENTACAO/<categoria>/_template-*`.
+3. **Criar/Atualizar Documentação**: Redigir a documentação na categoria adequada usando a estrutura do template. Se a funcionalidade altera algo existente, a documentação prévia deve ser atualizada.
+4. **Apresentar ao Operador**: Validar a documentação redigida com o operador (usuário humano) antes de iniciar qualquer código.
+5. **Implementar**: Escrever o código de forma que ele satisfaça e implemente *exatamente* o que foi estabelecido na documentação aprovada.
+6. **Validar**: Testar ou analisar o código para assegurar que ele respeita a especificação em 100%.
+7. **Sincronizar**: Se durante a implementação descobrir-se que ajustes na abordagem são necessários, a documentação deve ser atualizada em sincronia com o código.
+
+## Exceções
+Esta regra pode ser ignorada apenas para alterações triviais que não impactam regras de negócio, fluxos ou arquitetura, tais como:
+- Correção de erros de digitação (typos) em arquivos e variáveis.
+- Formatação de código ou linting.
+- Ajustes simples de imports.
+- Continuação de trabalho (ex: a doc já foi feita em um prompt/sessão anterior para esta mesma task).
+
+## Exemplos
+
+✅ **Correto**:
+- O operador pede um novo endpoint. O agente cria `DOCUMENTACAO/contratos/novo-endpoint` detalhando a API e os schemas usando o template. Após aprovação, cria o código na API.
+
+❌ **Incorreto**:
+- O operador pede uma nova regra de negócio complexa e o agente já cria a função ou arquivo `.ts` sem antes registrar a regra em `DOCUMENTACAO/regras-negocio/` para validação.
+- O agente toma uma decisão técnica grande (ex: trocar a biblioteca de state management) e apenas implementa no código sem gerar um ADR.
+
+## Impacto
+O código não é mais a fonte da verdade para o funcionamento esperado, mas sim a *implementação* da verdade registrada na documentação. Isso garante rastreabilidade, reduz dependência de memória implícita de sessões passadas e facilita a manutenção por humanos e outras instâncias do agente.
+
+## Referências
+- `DOCUMENTACAO/README` (Manifesto DDD)
+- Skills relacionadas: `documentar-decisao-tecnica`, `documentar-dominio-modulo`, `documentar-regras-negocio`