spec-first-copilot 0.4.0 → 0.5.0-beta.0

package/templates/{docs/_templates/estrutura/ADRs.template.md → .github/templates/estrutura/decisions.template.md}

@@ -1,91 +1,99 @@
-# ADRs — Architecture Decision Records
-
-> Registro de decisões arquiteturais com contexto, alternativas e consequências.
-> Cada decisão é imutável após aceita. Novas decisões podem substituir anteriores.
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-ORIGEM: Criado pelo /setup-projeto com ADRs iniciais (stack, arquitetura base).
-ATUALIZAÇÃO: Novas ADRs adicionadas quando:
-  - /setup-projeto define stack e arquitetura (ADRs iniciais)
-  - /design gera SDD §2 com decisões de design significativas
-  - /merge-delta detecta mudança de stack ou padrão
-  - Usuário toma decisão que impacta arquitetura
-
-COMO GERAR:
-1. Para cada decisão significativa, criar ADR com TODOS os campos
-2. Contexto: POR QUE essa decisão foi necessária (não apenas "precisávamos")
-3. Alternativas: OBRIGATÓRIO listar ao menos 1 alternativa (com motivo da rejeição)
-4. Consequências: o que MUDA por causa da decisão (positivo E negativo)
-
-REGRAS:
-- IDs sequenciais: ADR-001, ADR-002... nunca reutilizar
-- NUNCA editar ADR com status "aceita" — criar nova com "substituída por ADR-XXX"
-- Status "proposta" = ainda em discussão, não implementar até aceitar
-- Toda mudança de stack, banco, framework DEVE ter ADR
-- ADRs são APPEND-ONLY — histórico importa
-
-QUANDO CRIAR ADR:
-- Escolha de tecnologia/framework
-- Mudança de padrão de design
-- Decisão de infra (cloud provider, DB engine)
-- Trade-off significativo (performance vs simplicidade, etc.)
-
-QUANDO NÃO CRIAR ADR:
-- Escolha de nome de variável
-- Implementação seguindo padrão já definido
-- Bug fix
-- Refactor sem mudança de interface
-
-=============================================================================
--->
-
-## Índice
-
-| ADR | Título | Status | Data |
-|-----|--------|--------|------|
-| ADR-001 | {{Título}} | proposta / aceita / substituída / descartada | |
-
-## Formato
-
-Cada ADR segue este modelo:
-
-```markdown
-### ADR-NNN: Título da Decisão
-- **Status**: proposta | aceita | substituída por ADR-XXX | descartada
-- **Data**: YYYY-MM-DD
-- **Contexto**: Por que essa decisão foi necessária?
-- **Decisão**: O que decidimos?
-- **Alternativas consideradas**:
-  1. Alternativa A — rejeitada porque...
-  2. Alternativa B — rejeitada porque...
-- **Consequências**:
-  - Positivas: ...
-  - Negativas: ...
-  - Riscos: ...
-```
-
----
-
-## Decisões
-
-### ADR-001: {{Título}}
-- **Status**: aceita
-- **Data**:
-- **Contexto**:
-- **Decisão**:
-- **Alternativas consideradas**:
-  1. —
-- **Consequências**:
-  - Positivas:
-  - Negativas:
-  - Riscos:
-
----
-
-> **Regra**: ADRs aceitas são imutáveis. Para reverter uma decisão, crie nova ADR com status "substituída por ADR-XXX" na ADR original.
+# Decisões — Architecture Decision Records
+
+> Registro de decisões arquiteturais com contexto, alternativas e consequências.
+> Cada decisão é imutável após aceita. Novas decisões podem substituir anteriores.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: Criado pelo /setup-projeto com decisões iniciais (stack, arquitetura base).
+ATUALIZAÇÃO: Novas decisões adicionadas quando:
+  - /setup-projeto define stack e arquitetura (decisões iniciais)
+  - /design gera SDD §2 com decisões de design significativas
+  - /merge-delta detecta mudança de stack ou padrão arquitetural
+  - Usuário toma decisão que impacta arquitetura
+
+COMO GERAR:
+1. Para cada decisão significativa, criar registro com TODOS os campos
+2. Contexto: POR QUE essa decisão foi necessária (não apenas "precisávamos")
+3. Alternativas: OBRIGATÓRIO listar ao menos 1 alternativa (com motivo da rejeição)
+4. Consequências: o que MUDA por causa da decisão (positivo E negativo)
+
+REGRAS:
+- IDs sequenciais: ADR-001, ADR-002... nunca reutilizar
+- NUNCA editar decisão com status "aceita" — criar nova com "substituída por ADR-XXX"
+- Status "proposta" = ainda em discussão, não implementar até aceitar
+- Toda mudança de stack, banco, framework DEVE ter registro aqui
+- Decisões são APPEND-ONLY — histórico importa
+
+QUANDO CRIAR:
+- Escolha de tecnologia/framework
+- Mudança de padrão de design
+- Decisão de infra (cloud provider, DB engine)
+- Trade-off significativo (performance vs simplicidade, etc.)
+
+QUANDO NÃO CRIAR:
+- Escolha de nome de variável
+- Implementação seguindo padrão já definido
+- Bug fix
+- Refactor sem mudança de interface
+
+=============================================================================
+-->
+
+## Índice
+
+| ADR | Título | Status | Data |
+|-----|--------|--------|------|
+| ADR-001 | {{Título}} | proposta / aceita / substituída / descartada | |
+
+## Formato
+
+Cada decisão segue este modelo:
+
+```markdown
+### ADR-NNN: Título da Decisão
+- **Status**: proposta | aceita | substituída por ADR-XXX | descartada
+- **Data**: YYYY-MM-DD
+- **Contexto**: Por que essa decisão foi necessária?
+- **Decisão**: O que decidimos?
+- **Alternativas consideradas**:
+  1. Alternativa A — rejeitada porque...
+  2. Alternativa B — rejeitada porque...
+- **Consequências**:
+  - Positivas: ...
+  - Negativas: ...
+  - Riscos: ...
+```
+
+---
+
+## Decisões
+
+### ADR-001: {{Título}}
+- **Status**: aceita
+- **Data**:
+- **Contexto**:
+- **Decisão**:
+- **Alternativas consideradas**:
+  1. —
+- **Consequências**:
+  - Positivas:
+  - Negativas:
+  - Riscos:
+
+---
+
+> **Regra**: Decisões aceitas são imutáveis. Para reverter, criar nova decisão com status "substituída por ADR-XXX" na original.
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |

package/templates/.github/templates/estrutura/domain.template.md

@@ -0,0 +1,148 @@
+# Domínio
+
+> Visão de negócio + modelo de dados.
+> O que o sistema é, quem usa, com o que integra, quais entidades existem e como se relacionam.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: Gerado pelo /setup-projeto a partir do TRD §1 (Visão) e §4 (Modelo de Dados Base).
+ATUALIZAÇÃO: /merge-delta quando features adicionam/alteram tabelas, entidades,
+atores, integrações externas ou termos de domínio.
+
+COMO GERAR:
+1. Ler TRD §1 (Visão do Sistema) — contexto, atores, integrações
+2. Ler TRD §4 (Modelo de Dados Base) — tabelas iniciais, convenções
+3. Descrever o sistema em 2-3 frases objetivas (O QUE, PARA QUEM, QUAL PROBLEMA)
+4. Listar TODOS os atores com permissões gerais (o que PODE e o que NÃO pode)
+5. Listar TODAS as integrações externas com direção explícita
+6. Gerar diagrama ER textual com TODAS as relações
+7. Catálogo de tabelas com tipos EXATOS do banco (varchar(255), não "string")
+8. Glossário (DDD ubiquitous language) é obrigatório
+
+O QUE NÃO VAI AQUI:
+- Roadmap de módulos → vive no backlog faseado, não no Estrutura
+- Containers, stack, deploy → architecture.md
+- Autorização, LGPD, auditoria → conventions.md
+
+REGRAS:
+- Atores devem ter permissões gerais claras
+- Integrações devem ter direção explícita (envia/recebe/ambos)
+- Toda FK define ON DELETE/ON UPDATE
+- Índices precisam de justificativa (query que justifica)
+- Convenções de nomenclatura são LEI — SDDs seguem à risca
+- Glossário não é opcional — termos ambíguos geram bugs
+
+=============================================================================
+-->
+
+## O que é este sistema?
+
+<!-- Descrição em 2-3 frases. O que ele faz, para quem, qual problema resolve. -->
+
+
+## Usuários e Papéis
+
+| Papel | O que faz | O que NÃO pode fazer | Nível de acesso |
+|-------|-----------|----------------------|-----------------|
+|       |           |                      |                 |
+
+## Integrações Externas
+
+| Sistema/Serviço | Tipo (API/Webhook/Arquivo/Fila) | Direção (Envia/Recebe/Ambos) | Descrição | SLA/Disponibilidade |
+|-----------------|--------------------------------|------------------------------|-----------|---------------------|
+|                 |                                |                              |           |                     |
+
+## Restrições e Premissas
+
+### Restrições técnicas
+-
+
+### Restrições de negócio
+-
+
+### Premissas
+-
+
+## Glossário
+
+> Termos do domínio usados em todo o projeto. Linguagem ubíqua (DDD).
+
+| Termo | Definição | Exemplo de uso |
+|-------|-----------|----------------|
+|       |           |                |
+
+## Modelo de Dados
+
+### Diagrama ER
+
+```
+<!-- Representação textual do ER -->
+<!-- Formato: [tabela_a] 1---N [tabela_b] (campo_fk) -->
+```
+
+### Convenções de Nomenclatura
+
+| Elemento | Convenção | Exemplo |
+|----------|-----------|---------|
+| Tabelas | snake_case, plural | `clientes`, `pedidos` |
+| Colunas | snake_case | `nome_completo`, `criado_em` |
+| PKs | `id` (UUID ou SERIAL) | `id UUID PRIMARY KEY DEFAULT gen_random_uuid()` |
+| FKs | `{tabela_singular}_id` | `cliente_id`, `cidade_id` |
+| Índices | `idx_{tabela}_{colunas}` | `idx_clientes_cpf` |
+| Unique | `uq_{tabela}_{colunas}` | `uq_clientes_email` |
+| Timestamps | `criado_em`, `atualizado_em` | `TIMESTAMPTZ NOT NULL DEFAULT now()` |
+| Soft delete | `ativo` (boolean) | `ativo BOOLEAN DEFAULT true` |
+| Auditoria | `criado_por`, `atualizado_por` | `UUID REFERENCES usuarios(id)` |
+
+### Catálogo de Tabelas
+
+<!-- Repetir bloco para cada tabela -->
+
+#### {{tabela}}
+
+> Descrição breve da tabela.
+
+| Coluna | Tipo | Nullable | Default | Constraint | Descrição |
+|--------|------|----------|---------|------------|-----------|
+|        |      |          |         |            |           |
+
+**Relações:**
+- `campo_id` → `tabela_ref(id)` — ON DELETE CASCADE / SET NULL / RESTRICT
+
+**Índices:**
+
+| Nome | Colunas | Tipo | Justificativa |
+|------|---------|------|---------------|
+|      |         | btree / unique / gin | <!-- Qual query justifica este índice? --> |
+
+### Estratégia de Migrations
+
+| Aspecto | Convenção |
+|---------|-----------|
+| Ferramenta | <!-- Ex: knex, prisma, flyway, alembic, EF Core --> |
+| Nomenclatura | <!-- Ex: 001_create_tabela.sql, YYYYMMDD_descricao --> |
+| Rollback | <!-- Toda migration TEM rollback? Testado como? --> |
+| Execução | <!-- Sequencial? Transacional? --> |
+| Dados existentes | <!-- Como lidar com migrations em tabelas com dados? --> |
+
+### Regras Globais de Dados
+
+| Regra | Descrição |
+|-------|-----------|
+| Soft delete | <!-- Todas as tabelas usam? Quais exceções? --> |
+| Auditoria | <!-- criado_por/atualizado_por em todas? --> |
+| Timestamps | <!-- criado_em/atualizado_em obrigatórios? --> |
+| Encoding | <!-- UTF-8? Collation? --> |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |