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

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

@@ -0,0 +1,158 @@
+# Arquitetura
+
+> Arquitetura do sistema: containers, componentes, stack tecnológica, ambientes e deploy.
+> C4 Níveis 2-3 + camadas da stack + infraestrutura de runtime.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: Gerado pelo /setup-projeto a partir do TRD §2 (Stack), §3 (Arquitetura)
+e §6 (Infraestrutura — ambientes, deploy, CI/CD, rollback).
+ATUALIZAÇÃO: /merge-delta quando features adicionam containers, componentes,
+dependências de stack ou mudam ambientes/deploy.
+
+COMO GERAR:
+1. Ler TRD §3 (Arquitetura) — containers, padrões de comunicação, padrões de design
+2. Ler TRD §2 (Stack) — tecnologias por camada, versões
+3. Ler TRD §6 (Infraestrutura) — ambientes, deploy, CI/CD, rollback
+4. Montar diagrama C4 Nível 2 mostrando TODOS os containers e conexões
+5. Para cada container relevante, listar componentes internos (C4 Nível 3)
+6. Documentar stack principal com versões EXATAS (não "latest")
+7. Documentar ambientes (URLs, bancos, branches) e pipeline CI/CD concreto
+
+O QUE NÃO VAI AQUI:
+- Variáveis de ambiente → conventions.md
+- Monitoramento e observabilidade → conventions.md
+- Segurança (auth, CORS, rate limiting) → conventions.md
+- Alternativas descartadas de stack → conventions.md
+- Entidades e modelo de dados → domain.md
+
+REGRAS:
+- Versões fixadas (18.3.1, não ^18.0.0)
+- Cada container tem: tecnologia, responsabilidade, porta, tipo de comunicação
+- Padrões de design precisam de justificativa (não apenas nome)
+- Pipeline CI/CD deve ser concreto — passos reais e ferramentas
+- Rollback strategy obrigatória — "como voltar se der errado?"
+
+=============================================================================
+-->
+
+## Diagrama de Containers (C4 Nível 2)
+
+```
+<!-- Representação textual dos containers e suas conexões -->
+<!-- Usar formato: [Container] --protocolo--> [Container] -->
+```
+
+## Containers
+
+| Container | Tecnologia | Responsabilidade | Porta | Comunicação |
+|-----------|-----------|-----------------|-------|-------------|
+|           |           |                 |       |             |
+
+## Componentes Principais (C4 Nível 3)
+
+<!-- Repetir esta seção para cada container que tenha componentes internos relevantes -->
+
+### {{Container}}
+
+| Componente | Responsabilidade | Dependências internas | Dependências externas |
+|------------|-----------------|----------------------|----------------------|
+|            |                 |                      |                      |
+
+## Padrões de Comunicação
+
+### Síncrona (request/response)
+
+| De | Para | Protocolo | Formato | Observações |
+|----|------|-----------|---------|-------------|
+|    |      |           |         |             |
+
+### Assíncrona (eventos/filas)
+
+| Produtor | Tópico/Fila | Consumer | Formato | Garantia |
+|----------|-------------|----------|---------|----------|
+|          |             |          |         | at-least-once / exactly-once |
+
+## Padrões de Design Adotados
+
+| Padrão | Onde é usado | Justificativa | Ref decisão |
+|--------|-------------|---------------|-------------|
+|        |             |               |             |
+
+## Stack Principal
+
+| Camada | Tecnologia | Versão | Justificativa |
+|--------|-----------|--------|---------------|
+| Frontend | | | |
+| Backend | | | |
+| Banco de Dados | | | |
+| ORM/Query Builder | | | |
+| Autenticação | | | |
+| Testes | | | |
+| CI/CD | | | |
+
+<!-- Adicionar camadas conforme necessidade: Mobile, Cache, Fila, Monitoramento, etc. -->
+
+## Bibliotecas e Dependências por Camada
+
+<!-- Repetir bloco para cada camada com dependências relevantes -->
+
+### {{Camada}}
+
+| Pacote | Versão | Para quê |
+|--------|--------|----------|
+|        |        |          |
+
+## Ambientes
+
+| Ambiente | URL | Banco | Propósito | Branch |
+|----------|-----|-------|-----------|--------|
+| Local | `localhost:{{PORT}}` | local | Desenvolvimento | qualquer |
+| Staging | | | Testes e homologação | develop |
+| Produção | | | Usuários finais | main |
+
+## Deploy
+
+### Estratégia
+
+| Aspecto | Decisão |
+|---------|---------|
+| Plataforma | <!-- Docker? Serverless? VPS? Cloud provider? --> |
+| Orquestração | <!-- Kubernetes? ECS? PM2? --> |
+| Build | <!-- Docker multi-stage? Build nativo? --> |
+| Estratégia de deploy | <!-- Rolling? Blue-green? Canary? --> |
+
+### Pipeline CI/CD
+
+```
+push → lint → test → build → deploy(staging) → aprovação → deploy(prod)
+```
+
+| Etapa | Ferramenta | Trigger | Timeout |
+|-------|-----------|---------|---------|
+| Lint | <!-- eslint, ruff --> | push | |
+| Testes | <!-- jest, pytest --> | push | |
+| Build | <!-- docker build --> | push em main/develop | |
+| Deploy staging | <!-- CD tool --> | push em develop | |
+| Deploy produção | <!-- CD tool --> | aprovação manual | |
+
+### Rollback
+
+| Cenário | Procedimento | Responsável |
+|---------|-------------|-------------|
+| Bug em produção | <!-- Reverter deploy? Hotfix? --> | |
+| Migration com erro | <!-- Rollback da migration? --> | |
+| Serviço externo fora | <!-- Fallback? Circuit breaker? --> | |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |

package/templates/{docs/_templates/estrutura/Seguranca.template.md → .github/templates/estrutura/conventions.template.md}

@@ -1,6 +1,8 @@
-# Segurança
+# Convenções
 
-> Autenticação, autorização, CORS, rate limiting, LGPD, auditoria e proteção de dados.
+> Regras transversais do sistema: autenticação, autorização, CORS, rate limiting,
+> LGPD, auditoria, variáveis de ambiente, monitoramento, códigos de erro de domínio
+> e versionamento de dependências. Padrões que todo código segue.
 
 ---
 
@@ -9,15 +11,27 @@
 INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
 =============================================================================
 
-ORIGEM: Gerado pelo /setup-projeto a partir do TRD §7.
-ATUALIZAÇÃO: /merge-delta quando features adicionam permissões, dados pessoais ou políticas.
+ORIGEM: Gerado pelo /setup-projeto a partir do TRD §7 (Segurança),
+§6 (Infra — env vars, domínios, monitoramento), §5 (API — códigos de erro
+de domínio) e §2 (Stack — alternativas descartadas, versionamento).
+ATUALIZAÇÃO: /merge-delta quando features adicionam permissões, papéis,
+dados pessoais, variáveis de ambiente, códigos de erro ou alteram políticas.
 
 COMO GERAR:
 1. Ler TRD §7 (Segurança) — autenticação, autorização, CORS, LGPD
-2. Autenticação: método, expiração, hash, refresh strategy
-3. Autorização: papéis e matriz de permissões (RBAC/ABAC)
-4. LGPD: mapear TODOS dados pessoais com base legal
-5. Auditoria: definir O QUE é logado, ONDE e POR QUANTO TEMPO
+2. Ler TRD §6 (Infra) — variáveis de ambiente, domínios, monitoramento
+3. Ler TRD §5 (API) — códigos de erro do domínio (reutilizáveis)
+4. Ler TRD §2 (Stack) — alternativas descartadas e versionamento de dependências
+5. Autenticação: método, expiração, hash, refresh strategy
+6. Autorização: papéis e matriz de permissões (RBAC/ABAC)
+7. LGPD: mapear TODOS dados pessoais com base legal específica
+8. Auditoria: O QUE é logado, ONDE, POR QUANTO TEMPO
+9. Variáveis de ambiente: NUNCA valores reais, só exemplos
+
+O QUE NÃO VAI AQUI:
+- Rotas, paginação, filtros, catálogo de endpoints → apiContracts.md
+- Containers, ambientes, deploy → architecture.md
+- Entidades, tabelas → domain.md
 
 REGRAS:
 - Matriz de permissões é DINÂMICA — cresce a cada feature (via merge-delta)
@@ -25,7 +39,8 @@ REGRAS:
 - Nunca armazenar senhas em texto plano (hash obrigatório)
 - Secrets nunca no código — sempre variáveis de ambiente
 - Rate limiting obrigatório em endpoints públicos (login, registro)
-- Auditoria obrigatória para operações destrutivas (delete, update de dados sensíveis)
+- Auditoria obrigatória para operações destrutivas
+- Códigos de erro do domínio são globais — reutilizáveis por múltiplos endpoints
 
 =============================================================================
 -->
@@ -105,7 +120,7 @@ REGRAS:
 
 | Direito | Implementação | Endpoint/Fluxo |
 |---------|--------------|----------------|
-| Acesso aos dados | | <!-- Como o usuário acessa? --> |
+| Acesso aos dados | | |
 | Correção | | |
 | Exclusão (right to be forgotten) | | <!-- Soft delete? Hard delete? Anonimização? --> |
 | Portabilidade | | <!-- Formato de exportação? --> |
@@ -129,6 +144,55 @@ REGRAS:
 | Dados sensíveis em repouso | <!-- Criptografia? Quais campos? --> |
 | Backup | <!-- Criptografado? Frequência? --> |
 
+## Variáveis de Ambiente
+
+> NUNCA colocar valores reais aqui. Apenas nomes, descrição e exemplos.
+
+| Variável | Ambientes | Obrigatória | Descrição | Exemplo |
+|----------|-----------|-------------|-----------|---------|
+| `DATABASE_URL` | todos | sim | Conexão com banco | `postgres://user:pass@host:5432/db` |
+| `JWT_SECRET` | todos | sim | Chave de assinatura JWT | `sua-chave-secreta-aqui` |
+| `NODE_ENV` | todos | sim | Ambiente atual | `development` / `production` |
+
+## Domínios e DNS
+
+| Domínio | Aponta para | Certificado | Gerenciado por |
+|---------|-------------|-------------|----------------|
+|         |             | <!-- Let's Encrypt? AWS ACM? --> | |
+
+## Monitoramento e Observabilidade
+
+| Aspecto | Ferramenta | O que monitora |
+|---------|-----------|----------------|
+| Logs | <!-- Ex: CloudWatch, Datadog --> | |
+| APM | <!-- Ex: New Relic, Sentry --> | |
+| Uptime | <!-- Ex: Pingdom, UptimeRobot --> | |
+| Alertas | <!-- Ex: PagerDuty, Slack --> | |
+
+## Códigos de Erro do Domínio
+
+> Códigos reutilizáveis por múltiplos endpoints. Novos códigos são adicionados via /merge-delta.
+
+| Código | Descrição | HTTP padrão |
+|--------|-----------|-------------|
+| <!-- Ex: DUPLICATE_EMAIL --> | <!-- Email já cadastrado --> | <!-- 409 --> |
+
+## Alternativas Tecnológicas Descartadas
+
+> Decisões já tomadas. Se alguém perguntar "por que não usamos X?", a resposta está aqui.
+
+| Tecnologia escolhida | Alternativa considerada | Por que descartamos | Ref decisão |
+|----------------------|------------------------|---------------------|-------------|
+|                      |                        |                     |             |
+
+## Convenções de Versionamento de Dependências
+
+| Aspecto | Convenção |
+|---------|-----------|
+| Versionamento | <!-- Semver? Pinned? --> |
+| Lock files | <!-- package-lock.json? yarn.lock? --> |
+| Atualização | <!-- Dependabot? Manual? Periodicidade? --> |
+
 ---
 
 ## Changelog

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

@@ -1,4 +1,4 @@
-# ADRs — Architecture Decision Records
+# 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.
@@ -10,33 +10,33 @@
 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)
+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
+  - /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 ADR com TODOS os campos
+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 ADR com status "aceita" — criar nova com "substituída por ADR-XXX"
+- 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 ADR
-- ADRs são APPEND-ONLY — histórico importa
+- Toda mudança de stack, banco, framework DEVE ter registro aqui
+- Decisões são APPEND-ONLY — histórico importa
 
-QUANDO CRIAR ADR:
+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 ADR:
+QUANDO NÃO CRIAR:
 - Escolha de nome de variável
 - Implementação seguindo padrão já definido
 - Bug fix
@@ -53,7 +53,7 @@ QUANDO NÃO CRIAR ADR:
 
 ## Formato
 
-Cada ADR segue este modelo:
+Cada decisão segue este modelo:
 
 ```markdown
 ### ADR-NNN: Título da Decisão
@@ -88,4 +88,12 @@ Cada ADR segue este modelo:
 
 ---
 
-> **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.
+> **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 |
+|------|---------|------|-----------|
+|      |         |      |           |