spec-first-claude 0.2.0 → 0.4.0

package/templates/docs/Desenvolvimento/rules.md

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

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