spec-first-claude 0.1.0

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

@@ -0,0 +1,78 @@
+# Stack Tecnológica
+
+> Tecnologias escolhidas, versões fixadas, e alternativas descartadas com justificativa.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: Gerado pelo /setup-projeto a partir do TRD §2.
+ATUALIZAÇÃO: /merge-delta quando features introduzem novas tecnologias ou mudanças de stack (raro — deve gerar ADR).
+
+COMO GERAR:
+1. Ler TRD §2 (Stack e Tecnologias) — todas decisões de tech
+2. Preencher TODAS as camadas, mesmo que "a definir"
+3. Para cada tecnologia: versão EXATA (não "latest")
+4. Justificativa deve ser técnica, não "é popular"
+5. Alternativas descartadas: documentar POR QUE foram rejeitadas (evita rediscussão)
+
+REGRAS:
+- Versões devem ser fixadas (ex: "18.3.1", não "^18.0.0")
+- Cada biblioteca/pacote precisa de justificativa (evita bloat)
+- Alternativas descartadas previnem que o time rediscuta decisões já tomadas
+- Mudanças de stack DEVEM gerar ADR em ADRs.md
+- Camadas são dinâmicas — adicionar conforme necessidade (mobile, infra, etc.)
+
+=============================================================================
+-->
+
+## 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
+
+<!-- Repetir seção para cada camada que tenha dependências relevantes -->
+
+### {{Camada}}
+
+| Pacote | Versão | Para quê | Alternativa descartada |
+|--------|--------|----------|----------------------|
+|        |        |          |                      |
+
+## Alternativas 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 ADR |
+|----------------------|------------------------|---------------------|---------|
+|                      |                        |                     |         |
+
+## Convenções de Versionamento
+
+| Aspecto | Convenção |
+|---------|-----------|
+| Versionamento | <!-- Semver? Pinned? --> |
+| Lock files | <!-- package-lock.json? yarn.lock? --> |
+| Atualização | <!-- Dependabot? Manual? Periodicidade? --> |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |

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

@@ -0,0 +1,82 @@
+# Visão do Sistema
+
+> C4 Nível 1 — Contexto do sistema: o que é, quem usa, com o que integra, quais restrições existem.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: Gerado pelo /setup-projeto a partir do TRD §1.
+ATUALIZAÇÃO: /merge-delta quando features alteram contexto global (novos atores, integrações, restrições).
+
+COMO GERAR:
+1. Ler TRD §1 (Visão do Sistema) — é a fonte primária
+2. Ler TRD §8 (Módulos Planejados) — alimenta o Roadmap
+3. Descrever o sistema em 2-3 frases objetivas (sem jargão de marketing)
+4. Listar TODOS os atores e papéis mencionados nos insumos
+5. Listar TODAS as integrações externas com direção clara
+6. Glossário: termos de domínio que o time precisa compartilhar (DDD ubiquitous language)
+
+REGRAS:
+- Descrição do sistema deve responder: O QUE faz, PARA QUEM, QUAL PROBLEMA resolve
+- Atores devem ter permissões gerais claras (o que pode E o que NÃO pode)
+- Integrações devem ter direção explícita (envia/recebe/ambos)
+- 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
+-
+
+## Roadmap de Módulos
+
+> Extraído do TRD §8. Visão de alto nível das funcionalidades planejadas.
+
+| # | Módulo | Prioridade | Dependências | Status |
+|---|--------|-----------|--------------|--------|
+|   |        |           |              | planejado / em desenvolvimento / concluído |
+
+## Glossário
+
+> Termos do domínio usados em todo o projeto. Linguagem ubíqua (DDD).
+
+| Termo | Definição | Exemplo de uso |
+|-------|-----------|----------------|
+|       |           |                |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |

package/templates/docs/_templates/feature/PRD.template.md

@@ -0,0 +1,256 @@
+# PRD — {{FEATURE}}
+## Product Requirements Document
+
+> **Artefato gerado pela IA** a partir do processamento de todos os insumos em `docs/PM/{{FEATURE}}/`.
+> Este é o checkpoint de extração — o usuário DEVE revisar e aprovar antes de prosseguir.
+> Todos os documentos subsequentes (SDD, tasks) são gerados a partir DESTE arquivo.
+
+---
+
+## Meta
+
+| Campo | Valor |
+|-------|-------|
+| Feature | `{{FEATURE}}` |
+| Status | `em extração` → `aguardando revisão` → `aprovado` |
+| Insumos processados | {{LISTA_INSUMOS}} |
+| Gerado em | |
+| Aprovado em | |
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+QUANDO USAR: Gerado pelo /extract (chamado via /feature).
+QUEM GERA: Agent Analyzer (Opus) a partir dos outputs dos Readers (Sonnet).
+
+COMO GERAR:
+1. Readers (Sonnet) leem cada arquivo do PM/ individualmente e catalogam por seção
+2. Analyzer (Opus) recebe todos os outputs e:
+   a. Consolida em visão unificada
+   b. Cruza informações entre fontes — detecta contradições
+   c. Identifica gaps — seções sem informação viram ambiguidades
+   d. Gera este documento seguindo as 14 seções fixas
+3. Ler `docs/Estrutura/` para contexto de arquitetura existente
+4. Para cada informação, registrar DE QUAL insumo veio (rastreabilidade §14)
+5. Se faltam dados para preencher uma seção → pergunta BLOQUEANTE em §13
+
+FORMATOS DE INSUMO (o que extrair de cada):
+- .txt, .md → requisitos, regras, contexto, restrições
+- .sql → entidades, campos, tipos, constraints, índices, relações
+- .html → telas, campos (data-field), ações (data-action),
+  validações (data-validation), rotas (data-route),
+  permissões (data-permission), estados (data-state)
+- .xml (drawio) → fluxos, decisões, atores, sequências
+- .csv → dados tabulares, mapeamentos
+- .png, .jpg, .pdf → wireframes, mockups (análise visual)
+- Outros → extrair o que for relevante — nunca ignorar
+
+REGRAS DA EXTRAÇÃO:
+- Categorias FIXAS (as 15 seções abaixo) — não inventar novas
+- §11 Fases de Entrega é OBRIGATÓRIO — organizar funcionalidades em fases incrementais
+  Se existe backlog_extraido.md, usar como referência para as fases
+  Princípio: entregáveis contínuos, cada fase entrega valor e pode ir pra produção
+- Regras de negócio com IDs únicos e ESTÁVEIS (RN-001, RN-002...)
+  → IDs nunca renumeram após criação. Em re-extração, novos continuam sequência
+- Ambiguidades como perguntas diretas — BLOQUEANTES
+- SEM texto narrativo — apenas informação estruturada em tabelas e listas
+- Rastreabilidade: de qual arquivo veio cada informação
+- Nunca INFERIR regra de negócio — se não está explícito, é ambiguidade
+- Contradição entre fontes → gerar ambiguidade citando os dois arquivos
+
+RE-EXTRAÇÃO:
+- Merge ADITIVO com PRD existente (não sobrescrever)
+- Seções afetadas marcadas com <!-- ATUALIZADO: re-extração ISO_DATE -->
+- IDs de regras continuam sequência existente
+
+=============================================================================
+-->
+
+## 1. Contexto e Motivação
+
+### Qual problema resolve?
+<!-- POR QUÊ essa feature existe — extraído dos insumos -->
+
+### Como funciona hoje?
+<!-- Estado ATUAL — o que existe, como é feito, quais os problemas -->
+
+### Estado desejado
+<!-- O que muda com essa feature — o delta é o escopo real -->
+
+---
+
+## 2. Atores e Permissões
+
+| Ator | O que pode fazer | O que NÃO pode fazer |
+|------|------------------|----------------------|
+|      |                  |                      |
+
+---
+
+## 3. Entidades e Modelo de Dados
+
+> Extraído de: arquivos `.sql`, protótipos, texto livre.
+
+| Entidade | Campos principais | Tipo dos campos | Relações |
+|----------|-------------------|-----------------|----------|
+|          |                   |                 |          |
+
+### Índices e constraints identificados
+-
+
+### Histórico / Auditoria
+-
+
+---
+
+## 4. Jornadas do Usuário
+
+> Extraído de: protótipos HTML, textos, fluxos.
+
+### Jornada 1: {{NOME}}
+| Passo | Ator | Ação | Resultado esperado |
+|-------|------|------|--------------------|
+| 1     |      |      |                    |
+
+---
+
+## 5. Regras de Negócio
+
+> Extraídas de TODOS os insumos. Cada regra deve ser clara, testável e ter ID único.
+
+| ID | Regra | Fonte | Testável? |
+|----|-------|-------|-----------|
+| RN-001 | | {{arquivo_fonte}} | Sim/Não |
+
+---
+
+## 6. Validações
+
+> Extraídas de: protótipos (`data-validation`), `.sql` (constraints), texto.
+
+| Campo | Validações | Obrigatório? | Máscara | Fonte |
+|-------|-----------|--------------|---------|-------|
+|       |           |              |         |       |
+
+---
+
+## 7. Telas e Componentes UI
+
+> Extraídos de: protótipos HTML (`data-field`, `data-action`, `data-route`, `data-state`).
+
+### Tela 1: {{NOME}}
+- **Rota**: 
+- **Campos**: (extraídos dos `data-field`)
+- **Ações**: (extraídas dos `data-action`)
+- **Navegação**: (extraída dos `data-route`)
+- **Estados**: (extraídos dos `data-state`)
+- **Permissões por elemento**: (extraídos dos `data-permission`)
+
+---
+
+## 8. Integrações Externas
+
+| Serviço | Método | Quando é chamado | O que envia | O que recebe | Fallback |
+|---------|--------|------------------|-------------|--------------|----------|
+|         |        |                  |             |              |          |
+
+---
+
+## 9. Cenários de Erro
+
+| # | Cenário | Causa | Comportamento esperado | Fonte |
+|---|---------|-------|----------------------|-------|
+| 1 |         |       |                      |       |
+
+---
+
+## 10. Requisitos Não-Funcionais
+
+| Aspecto | Requisito | Fonte |
+|---------|-----------|-------|
+| Volume esperado | | |
+| Performance | | |
+| Disponibilidade | | |
+| Acessibilidade | | |
+
+---
+
+## 11. Fases de Entrega
+
+> Princípio: **entregáveis contínuos** — cada fase entrega valor e pode ir pra produção.
+> Fases são sequenciais por dependência. Cada uma tem entregável testável.
+> Se o `/extract` foi precedido por um roadmap (backlog_extraido.md), usar as fases como base.
+
+### Fase 1 — {{Nome}} [P1]
+
+> **Entregável**: {{O que o usuário pode usar ao final}}
+> **Critério de done**: {{Como validar — testes E2E que devem passar}}
+
+| # | Funcionalidade | Entidades | Regras | Jornadas |
+|---|---------------|-----------|--------|----------|
+| 1 | | | RN-NNN | Jornada N |
+
+### Fase 2 — {{Nome}} [P1]
+
+> **Entregável**: {{...}}
+> **Critério de done**: {{...}}
+> **Depende de**: Fase 1
+
+| # | Funcionalidade | Entidades | Regras | Jornadas |
+|---|---------------|-----------|--------|----------|
+| 1 | | | | |
+
+<!-- Repetir fases conforme necessário. Máximo 4-5 fases. -->
+
+### Visão geral
+
+| Fase | Nome | Prioridade | Entregável | Depende de |
+|------|------|-----------|------------|------------|
+| 1 | | P1 | | — |
+| 2 | | P1 | | Fase 1 |
+
+---
+
+## 12. Dependências
+
+| Dependência | Tipo | Status | Impacto se indisponível |
+|-------------|------|--------|------------------------|
+|             | feature / serviço / tabela | pronto / pendente | |
+
+---
+
+## 13. Fora de Escopo
+
+> Explicitamente listado — o que NÃO será feito nesta feature.
+
+| # | Item | Motivo |
+|---|------|--------|
+| 1 |      | futuro / outra feature / decisão do usuário |
+
+---
+
+## 14. Ambiguidades e Perguntas
+
+> ⚠️ **BLOQUEANTE** — o fluxo NÃO avança até o usuário responder TODAS.
+
+| # | Pergunta | Contexto | Fonte | Resposta do usuário |
+|---|----------|----------|-------|---------------------|
+| 1 | ⚠️ | | | (aguardando) |
+
+---
+
+## 15. Rastreabilidade — De onde veio cada informação
+
+> Mapa de qual insumo originou qual seção. Permite auditoria da extração.
+
+| Insumo | Tipo | O que foi extraído |
+|--------|------|--------------------|
+| `{{arquivo}}` | {{tipo}} | {{seções alimentadas}} |
+
+---
+
+> **Próximo passo**: Após aprovação do usuário, este PRD alimenta a geração do `sdd.md` e das tasks (`*_tasks.md`).

package/templates/docs/_templates/feature/Progresso.template.md

@@ -0,0 +1,136 @@
+# Progresso — {{FEATURE}}
+
+> Visão consolidada do andamento da feature.
+> Organizado por **fases de entrega** — cada fase é um entregável independente.
+> Atualizado automaticamente pelo /dev a cada task concluída.
+
+---
+
+## Status Geral: `não iniciado`
+
+<!-- não iniciado → em desenvolvimento → em revisão → concluído → arquivado -->
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+COMO GERAR ESTE ARQUIVO:
+
+1. Ler PRD §11 (Fases de Entrega) para definir as fases
+2. Ler TODOS os *_tasks.md da feature
+3. Para cada FASE DE ENTREGA, listar as áreas e contagem de tasks
+4. A visão primária é POR FASE, não por área
+
+COMO ATUALIZAR:
+
+- O /dev atualiza após cada task concluída
+- Status por fase: ⬜ pendente → 🔄 em andamento → ✅ concluída
+- Fase concluída = todas tasks de todas áreas daquela fase estão [x]
+- Ao concluir uma fase: registrar no Histórico + abrir PR
+
+=============================================================================
+-->
+
+## Fases de Entrega
+
+| Fase | Nome | Prioridade | Entregável | Status | Tasks |
+|------|------|-----------|------------|--------|-------|
+| 1 | {{Nome}} | P1 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
+| 2 | {{Nome}} | P1 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
+| 3 | {{Nome}} | P2 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
+
+---
+
+## Fase 1 — {{Nome}} [P1]
+
+> **Entregável**: {{O que o usuário pode usar}}
+> **Critério de done**: {{Testes E2E que devem passar}}
+> **Branch**: `feature/{{FEATURE}}_fase1`
+> **PR**: (a ser criado)
+
+### Tasks por área
+
+#### {{AREA_1}} ({{N}} tasks)
+
+| Task | Descrição | Tamanho | Repo | Status |
+|------|-----------|---------|------|--------|
+| AREA-001 | | S/M/L | {{repo}} | ⬜ |
+
+#### {{AREA_2}} ({{N}} tasks)
+
+| Task | Descrição | Tamanho | Repo | Status |
+|------|-----------|---------|------|--------|
+| AREA-001 | | S/M/L | {{repo}} | ⬜ |
+
+### Resumo Fase 1
+
+| Área | Total | Feitas | % |
+|------|-------|--------|---|
+| {{AREA_1}} | {{N}} | 0 | 0% |
+| {{AREA_2}} | {{N}} | 0 | 0% |
+| **Total Fase 1** | **{{N}}** | **0** | **0%** |
+
+---
+
+## Fase 2 — {{Nome}} [P1]
+
+> **Entregável**: {{...}}
+> **Depende de**: Fase 1 concluída
+
+<!-- Repetir mesma estrutura -->
+
+---
+
+## Totais Gerais
+
+| Fase | Total | Feitas | % |
+|------|-------|--------|---|
+| Fase 1 | {{N}} | 0 | 0% |
+| Fase 2 | {{N}} | 0 | 0% |
+| **Total** | **{{N}}** | **0** | **0%** |
+
+---
+
+## Ordem de Execução
+
+```
+Fase 1:
+  1. INFRA (setup de repos/ambiente)
+  2. BANCO (schema/migrations)
+  3. BACK (endpoints) ← pode paralelizar com FRONT após BANCO
+  4. FRONT (telas)
+  → PR Fase 1 + testes manuais + merge
+
+Fase 2:
+  1. BANCO (novas tabelas/migrations)
+  2. BACK (endpoints + regras)
+  3. FRONT (telas + integração)
+  → PR Fase 2 + testes manuais + merge
+```
+
+---
+
+## Histórico
+
+| Data | Evento | Detalhes |
+|------|--------|----------|
+| | Feature criada | PRD aprovado, SDD gerado |
+
+---
+
+## Pós-conclusão (por fase)
+
+- [ ] PR aberto com template detalhado
+- [ ] Ambiente local rodando para testes manuais
+- [ ] Testes automatizados passando (unit + integration + security)
+- [ ] Usuário aprovou e fez merge
+
+## Pós-conclusão (feature completa)
+
+- [ ] Todas fases concluídas e mergeadas
+- [ ] Mergear Delta Specs (SDD §11) nos docs de `docs/Estrutura/`
+- [ ] Atualizar `docs/Desenvolvimento/progresso.md` (visão global)
+- [ ] Atualizar `.ai/memory/napkin.md` se houver aprendizado relevante