spec-first-copilot 0.1.0

package/templates/docs/Desenvolvimento/rules.md

@@ -0,0 +1,229 @@
+# Regras de Desenvolvimento
+
+> Regras que todos os agentes de desenvolvimento devem seguir.
+> Lido pelo Coder/Senior Coder e Reviewer antes de cada task.
+> Aplicado globalmente a todas as features.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+QUANDO LER: Toda vez que /dev executar uma task. Obrigatório.
+QUEM LÊ: Coder, Senior Coder e Reviewer.
+COMO USAR: Regras aqui são LEI — não são sugestões. Violações reprovam a task no quality gate.
+
+PERSONALIZAÇÃO: Este arquivo é editado manualmente pelo time.
+As regras abaixo são o padrão do framework. O time pode:
+- Adicionar regras específicas da stack
+- Remover regras que não se aplicam
+- Ajustar convenções ao projeto
+
+=============================================================================
+-->
+
+## Regras Invioláveis
+
+1. **Spec-first**: Nenhuma task pode ser executada sem SDD aprovado
+2. **SDD é a fonte**: O coder lê APENAS o SDD + task — nunca consulta PRD ou PM diretamente
+3. **Um commit por task**: Cada task gera exatamente 1 commit
+4. **Sem invenção**: Se o SDD não especifica, o coder NÃO assume — para e reporta
+5. **Entregáveis contínuos**: Toda feature é faseada em entregáveis incrementais. Cada fase entrega valor ao usuário e pode ir para produção independentemente. Nunca "tudo ou nada" — sempre "pequeno e constante"
+6. **Nunca na main**: Todo código é desenvolvido em branch própria. Merge apenas via PR aprovado pelo usuário
+
+## Convenções de Código
+
+### Padrão geral
+- Todo código segue as convenções de `docs/Estrutura/Stack.md`
+- Nomes em inglês (código) — documentação em português
+- Sem código morto (comentado) — se não usa, apaga
+- Sem secrets hardcoded — sempre variáveis de ambiente
+
+### Backend
+- Testes obrigatórios: mínimo happy path + 1 cenário de erro
+- Validação de input na borda (controller/handler) — não no service
+- Erros de negócio: usar códigos definidos em `docs/Estrutura/API.md`
+- Tipos explícitos (sem `any`, `object`, `dynamic` genéricos)
+
+### Frontend
+- Componentes tipados com props documentadas
+- Estados explícitos: loading, empty, error, success
+- Sem lógica de negócio no componente — delegar para hooks/services
+
+### Banco de dados
+- Toda migration tem rollback testado
+- Execução sequencial — nunca pular migrations
+- Seeds apenas para ambiente de desenvolvimento
+
+## Convenções de Git
+
+> **Escopo**: Estas regras se aplicam aos **repositórios em `projetos/`** (api, web, worker, etc.).
+> O projeto-base em si é o orquestrador — specs e docs ficam aqui, código fica nos repos.
+
+### Commits
+```
+tipo(TASK-ID): descrição curta
+
+Corpo opcional com detalhes.
+
+Refs: feat_cadastro_cliente
+```
+
+| Tipo | Quando usar |
+|------|-------------|
+| `feat` | Nova funcionalidade |
+| `fix` | Correção de bug |
+| `refactor` | Mudança sem alterar comportamento |
+| `test` | Adição/alteração de testes |
+| `docs` | Documentação |
+| `chore` | Configuração, build, CI |
+
+### Branches
+```
+feature/feat_cadastro_cliente
+feature/feat_mvp_fase1
+bugfix/bug_cpf_duplicado
+task/task_otimizar_listagem
+```
+
+| Regra | Descrição |
+|-------|-----------|
+| Base | Sempre a partir de `main` atualizada (origin) |
+| Merge | Via Pull Request aprovado pelo usuário — NUNCA merge automático |
+| Conflitos | Resolver antes de mergear — nunca force push em branch compartilhada |
+
+### Git Workflow (5 passos obrigatórios)
+
+O /dev DEVE seguir este fluxo para CADA fase de entrega:
+
+#### Passo 1 — Antes de codar
+```bash
+# Verificar working tree limpo
+git status
+# Se há mudanças pendentes → sugerir commit ou stash antes de prosseguir
+# NUNCA começar a codar com working tree sujo
+```
+
+#### Passo 2 — Criar branch
+```bash
+# Atualizar main a partir do remote
+git checkout main
+git pull origin main
+
+# Criar branch para a fase
+git checkout -b feature/{nome}_fase{N}
+# Ex: feature/feat_mvp_fase1
+```
+- Branch criada no **repo do serviço** (projetos/api, projetos/web, etc.)
+- Se a fase afeta múltiplos repos → branch com mesmo nome em cada um
+- NUNCA desenvolver direto na main
+
+#### Passo 3 — Ao terminar a fase
+```bash
+# Atualizar Progresso.md com status da fase
+# Push da branch
+git push origin feature/{nome}_fase{N}
+
+# Abrir PR com template detalhado (ver seção abaixo)
+gh pr create --title "..." --body "..."
+```
+- Deixar ambiente local **rodando** (docker compose up + dotnet run + npm run dev)
+- Informar ao usuário que o ambiente está ON para testes manuais
+
+#### Passo 4 — Aguardar aprovação
+```
+⏸️ PARAR e aguardar.
+- O usuário revisa o PR, testa manualmente o ambiente local
+- Merge é MANUAL — o agente NUNCA faz merge
+- Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
+```
+
+#### Passo 5 — Após merge (quando usuário confirmar)
+```bash
+# Atualizar main local
+git checkout main
+git pull origin main
+
+# Limpar branches mergeadas
+git branch -d feature/{nome}_fase{N}
+git remote prune origin
+```
+
+### Template de Pull Request
+
+Todo PR aberto pelo /dev DEVE seguir este formato:
+
+```markdown
+## Fase {N} — {Nome da fase}
+
+### O que foi entregue
+- [ ] {Entregável 1 da fase}
+- [ ] {Entregável 2 da fase}
+
+### Tasks concluídas
+| Task | Descrição | Testes |
+|------|-----------|--------|
+| BACK-001 | Criar endpoint X | ✅ unit + integration |
+| BANCO-001 | Migration tabela Y | ✅ rollback testado |
+| FRONT-001 | Tela de cadastro | ✅ unit |
+
+### Testes
+- ✅ Unit tests passando ({N}/{N})
+- ✅ Integration tests passando ({N}/{N})
+- ✅ Security Review aprovado
+- ⬜ E2E (aguardando teste manual do usuário)
+
+### Como testar manualmente
+1. Ambiente já está rodando em:
+   - API: http://localhost:8080
+   - Web: http://localhost:3000
+   - Banco: localhost:5432
+2. Fluxo para testar:
+   - {Passo 1 do teste manual}
+   - {Passo 2 do teste manual}
+   - {Resultado esperado}
+
+### Observações
+- {Decisões tomadas, trade-offs, pontos de atenção}
+```
+
+## Quality Gate (por task)
+
+> Checklist obrigatório. O Reviewer valida TODOS os itens antes de aprovar.
+
+- [ ] Código compila sem erros
+- [ ] Testes passam (se aplicável à task)
+- [ ] Lint limpo (sem warnings não justificados)
+- [ ] Critérios de aceite da task atendidos (ref SDD §9)
+- [ ] Sem TODOs no código sem justificativa
+- [ ] Sem secrets hardcoded
+- [ ] Commit segue convenção: `tipo(TASK-ID): descrição`
+- [ ] Arquivos listados na task foram os únicos modificados (sem side effects)
+
+## Regras por Stack
+
+> Seção opcional. Adicionar regras específicas da tecnologia escolhida.
+> Exemplos abaixo — remover/ajustar conforme o projeto.
+
+<!--
+### Node.js / TypeScript
+- ESLint + Prettier como formatador
+- Strict mode no tsconfig
+- Path aliases configurados (@/modules, @/shared)
+
+### Python
+- Ruff como linter/formatter
+- Type hints obrigatórios (mypy strict)
+- Virtual environment (venv ou poetry)
+
+### React / Next.js
+- Server Components por padrão, Client Components só quando necessário
+- Zustand ou Context para estado global (não Redux)
+- Tailwind CSS para estilos
+-->
+
+---
+
+> **Atualização**: Editado manualmente pelo time. Aplicado globalmente a todas as features.

package/templates/docs/_templates/estrutura/ADRs.template.md

@@ -0,0 +1,91 @@
+# 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.

package/templates/docs/_templates/estrutura/API.template.md

@@ -0,0 +1,144 @@
+# Convenções de API
+
+> Padrões globais para todas as APIs do sistema: versionamento, autenticação, paginação, erros.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: Gerado pelo /setup-projeto a partir do TRD §5.
+ATUALIZAÇÃO: /merge-delta quando features adicionam endpoints (Delta Specs do SDD §5 e §11).
+
+COMO GERAR:
+1. Ler TRD §5 (Convenções de API) — padrão geral, versionamento, autenticação
+2. Padrão geral e convenções são FIXOS após setup — definidos uma vez
+3. Catálogo de endpoints é DINÂMICO — cresce a cada feature
+4. Formatos de paginação, filtro e erro são FIXOS — toda API segue
+
+REGRAS:
+- Convenções são LEI — todo SDD §5 (endpoints) deve seguir estes padrões
+- Catálogo de endpoints atualizado a cada merge-delta
+- Mudanças em convenções (raro) devem gerar ADR
+- Rate limiting definido por categoria de endpoint, não individual
+
+=============================================================================
+-->
+
+## Padrão Geral
+
+| Aspecto | Padrão |
+|---------|--------|
+| Estilo | <!-- REST / GraphQL / gRPC --> |
+| Formato | <!-- JSON / Protobuf --> |
+| Versionamento | <!-- /api/v1/ no path? Header? --> |
+| Autenticação | <!-- Bearer JWT? API Key? --> |
+| Content-Type | <!-- application/json --> |
+| Encoding | <!-- UTF-8 --> |
+
+## Convenções de Rotas
+
+| Operação | Método | Rota | Exemplo |
+|----------|--------|------|---------|
+| Listar | GET | `/api/v1/{recurso}` | |
+| Detalhar | GET | `/api/v1/{recurso}/:id` | |
+| Criar | POST | `/api/v1/{recurso}` | |
+| Atualizar completo | PUT | `/api/v1/{recurso}/:id` | |
+| Atualizar parcial | PATCH | `/api/v1/{recurso}/:id` | |
+| Remover/Inativar | DELETE | `/api/v1/{recurso}/:id` | |
+
+### Convenções de nomenclatura
+| Regra | Exemplo |
+|-------|---------|
+| Recursos no plural, kebab-case | `/api/v1/order-items` |
+| Ações não-CRUD como sub-recurso | `/api/v1/users/:id/activate` |
+| Filtros via query params | `/api/v1/users?status=active` |
+| Relações aninhadas (max 2 níveis) | `/api/v1/users/:id/orders` |
+
+## Paginação
+
+```json
+{
+  "data": [],
+  "meta": {
+    "page": 1,
+    "per_page": 20,
+    "total": 0,
+    "total_pages": 0
+  }
+}
+```
+
+Query params: `?page=1&per_page=20&sort=campo&order=asc`
+
+| Parâmetro | Default | Máximo | Descrição |
+|-----------|---------|--------|-----------|
+| `page` | 1 | — | Página atual |
+| `per_page` | 20 | <!-- Ex: 100 --> | Itens por página |
+| `sort` | — | — | Campo para ordenação |
+| `order` | `asc` | — | `asc` ou `desc` |
+
+## Filtros
+
+Query params: `?busca=termo&campo=valor`
+
+| Tipo de filtro | Formato | Exemplo |
+|----------------|---------|---------|
+| Igualdade | `?campo=valor` | `?status=ativo` |
+| Busca textual | `?busca=termo` | `?busca=joao` |
+| Range de data | `?de=YYYY-MM-DD&ate=YYYY-MM-DD` | `?de=2026-01-01&ate=2026-12-31` |
+| Múltiplos valores | `?campo=a,b,c` | `?status=ativo,pendente` |
+
+## Respostas de Erro
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Mensagem legível para o usuário",
+    "details": [
+      { "field": "campo", "message": "Detalhe do erro" }
+    ]
+  }
+}
+```
+
+### Códigos HTTP
+
+| Código | Quando usar | Exemplo |
+|--------|-------------|---------|
+| 200 | Sucesso (GET, PUT, PATCH) | Recurso retornado/atualizado |
+| 201 | Criado com sucesso (POST) | Recurso criado, retorna o objeto |
+| 204 | Sucesso sem conteúdo (DELETE) | Recurso removido |
+| 400 | Dados inválidos (formato) | JSON malformado |
+| 401 | Não autenticado | Token ausente ou expirado |
+| 403 | Sem permissão | Papel sem acesso ao recurso |
+| 404 | Recurso não encontrado | ID inexistente |
+| 409 | Conflito (duplicidade) | Email já cadastrado |
+| 422 | Validação de negócio falhou | CPF inválido, regra RN-XXX violada |
+| 429 | Rate limit excedido | Muitas requisições |
+| 500 | Erro interno | Bug não tratado |
+
+### Códigos de erro do domínio
+
+| Código | Descrição | HTTP |
+|--------|-----------|------|
+| <!-- Ex: DUPLICATE_EMAIL --> | <!-- Email já cadastrado --> | <!-- 409 --> |
+
+## Catálogo de Endpoints
+
+> Atualizado a cada feature via /merge-delta. Visão consolidada de todas as APIs.
+
+| Método | Rota | Feature | Descrição |
+|--------|------|---------|-----------|
+|        |      |         |           |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |

package/templates/docs/_templates/estrutura/Arquitetura.template.md

@@ -0,0 +1,82 @@
+# Arquitetura
+
+> C4 Níveis 2-3 — Containers, componentes, comunicação e padrões adotados.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: Gerado pelo /setup-projeto a partir do TRD §3.
+ATUALIZAÇÃO: /merge-delta quando features adicionam containers, componentes significativos ou novos padrões.
+
+COMO GERAR:
+1. Ler TRD §3 (Arquitetura) — containers, padrões de comunicação, padrões de design
+2. Ler Stack.md — tecnologias já definidas para cada container
+3. Criar diagrama textual C4 Nível 2 (containers e suas conexões)
+4. Para cada container: listar componentes internos (C4 Nível 3)
+5. Documentar padrões de comunicação (sync/async, protocolos)
+6. Documentar padrões de design com justificativa
+
+REGRAS:
+- Diagrama deve mostrar TODOS os containers e suas conexões
+- Cada container deve ter: tecnologia, responsabilidade, porta
+- Padrões de design precisam de justificativa (não apenas nome)
+- Se o sistema usa filas/eventos: documentar tópicos e consumers
+- Componentes são internos ao container — não confundir com containers
+
+=============================================================================
+-->
+
+## 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 ADR |
+|--------|-------------|---------------|---------|
+|        |             |               |         |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |

package/templates/docs/_templates/estrutura/Infraestrutura.template.md

@@ -0,0 +1,104 @@
+# Infraestrutura
+
+> Ambientes, deploy, CI/CD, variáveis de ambiente, domínios e estratégia de rollback.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: Gerado pelo /setup-projeto a partir do TRD §6.
+ATUALIZAÇÃO: /merge-delta quando features adicionam variáveis de ambiente, serviços ou mudam infra.
+
+COMO GERAR:
+1. Ler TRD §6 (Infraestrutura) — ambientes, deploy, CI/CD
+2. Listar TODOS os ambientes com URLs e propósitos
+3. Pipeline CI/CD deve ser concreto (passos reais, não genéricos)
+4. Variáveis de ambiente: NUNCA colocar valores reais (só exemplos)
+5. Estratégia de rollback é OBRIGATÓRIA
+
+REGRAS:
+- Variáveis de ambiente com valores reais NÃO vão pro repositório
+- Cada variável precisa de descrição (não só o nome)
+- Pipeline CI/CD deve ter passos claros e ferramentas definidas
+- Rollback strategy obrigatória — "como voltar se der errado?"
+- Novas variáveis adicionadas via merge-delta devem entrar na tabela
+
+=============================================================================
+-->
+
+## 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? --> | |
+
+## 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 --> | |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |