spec-first-copilot 0.1.0

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

@@ -0,0 +1,372 @@
+# SDD — {{NOME}}
+
+> **Software Design Document** — Fonte de verdade para implementação.
+> Gerado a partir do PRD.md (features) ou TRD.md (setup).
+> O Coder lê APENAS este documento + task específica.
+> Se não está no SDD, não será implementado.
+
+---
+
+## Meta
+
+| Campo | Valor |
+|-------|-------|
+| Nome | `{{NOME}}` |
+| Tipo | `{{feature|setup}}` |
+| Documento de origem | `docs/Desenvolvimento/{{NOME}}/{{PRD|TRD}}.md` |
+| Status | `rascunho` → `em revisão` → `aprovado` → `em dev` → `concluído` |
+| Autor | /design |
+| Criado em | |
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+QUANDO USAR: Gerado pelo /design após PRD (features) ou TRD (setup) aprovado.
+QUEM GERA: Agent Architect (Opus).
+
+COMO GERAR:
+1. Ler APENAS o PRD.md ou TRD.md aprovado — NUNCA ler PM diretamente
+2. Ler docs/Estrutura/ para contexto de stack, API, modelo de dados
+3. Traduzir requisitos (O QUE) em design técnico (COMO)
+4. Manter rastreabilidade: cada item referencia o PRD/TRD (§X, RN-xxx)
+5. Ser AUTOCONTIDO: o Coder não consulta PRD, TRD, PM, ou qualquer outro doc
+
+PRINCÍPIOS:
+- Conciso mas completo — se o Coder precisar de algo que não está aqui, o SDD está incompleto
+- Contratos detalhados (request/response com schemas reais)
+- Fluxos de dados como sequências textuais (não diagramas)
+- Critérios de aceite em Given/When/Then (testáveis)
+- Delta Specs obrigatório (o que muda no sistema global)
+
+SEÇÕES: 11 seções fixas + Rastreabilidade. Não pular nenhuma.
+Se uma seção não se aplica, escrever "N/A — [motivo]"
+
+AUTENTICAÇÃO E AUTORIZAÇÃO (OBRIGATÓRIO):
+- Em features: §5 (Endpoints) DEVE definir auth/authz para CADA endpoint:
+  - Autenticação: Bearer token, API Key, ou "público" (explícito)
+  - Autorização: quais roles/permissões acessam (ex: admin, user, owner)
+  - Se o PRD não definiu auth → usar o padrão de docs/Estrutura/Seguranca.md
+  - Se não há padrão definido → PARAR e perguntar ao usuário
+- Em setup: §7 Segurança do TRD define o mecanismo global (JWT, OAuth, etc.)
+  O SDD deve refletir isso em §2 Decisões de Design
+
+SETUP vs FEATURE:
+- Em setup (tipo=setup), várias seções serão N/A (§4 Regras, §5 Endpoints, §6 Telas, §7 Fluxos, §8 Integrações)
+  Isso é NORMAL — setup foca em §1 Visão, §2 Decisões, §3 Modelo, §9 Aceite, §11 Delta
+- Em features (tipo=feature), todas seções devem ser preenchidas quando aplicáveis
+- A tabela de Rastreabilidade muda: "PRD Seção → SDD Seção" para features, "TRD Seção → SDD Seção" para setup
+
+=============================================================================
+-->
+
+## 1. Visão Geral
+
+### O que é
+<!-- 2-3 frases: feature, público-alvo, problema que resolve -->
+
+### Escopo
+<!-- Limites claros: o que ENTRA e o que FICA DE FORA -->
+
+### Premissas
+- [ ] <!-- Ex: Usuário já está autenticado ao acessar esta feature -->
+
+---
+
+## 2. Decisões de Design
+
+> Mini-ADRs inline — cada decisão técnica relevante com justificativa.
+> Referência: [ADRs.md](../../Estrutura/ADRs.md) para decisões globais.
+
+| # | Decisão | Justificativa | Alternativa descartada |
+|---|---------|---------------|------------------------|
+| 1 | | | |
+
+---
+
+## 3. Modelo de Dados
+
+> Modelo completo para implementação. Tipos e constraints são obrigatórios.
+
+### 3.1 Entidades
+
+#### `{{nome_tabela}}`
+
+| Campo | Tipo | Null? | Default | Constraint | Descrição |
+|-------|------|-------|---------|------------|-----------|
+| `id` | `UUID` | NOT NULL | `gen_random_uuid()` | PK | |
+| `created_at` | `TIMESTAMPTZ` | NOT NULL | `NOW()` | | |
+
+**Relações**:
+- `tabela.campo` → `outra_tabela.campo` (FK, ON DELETE CASCADE)
+
+**Índices**:
+- `idx_tabela_campo` — tipo (btree/gin/gist) — justificativa
+
+### 3.2 Migrations necessárias
+
+| Ordem | Descrição | Dependência |
+|-------|-----------|-------------|
+| 1 | | nenhuma |
+
+---
+
+## 4. Regras de Negócio e Validações
+
+> Cada regra rastreável ao PRD (coluna Ref). Cada validação com mensagem de erro.
+> O Coder implementa EXATAMENTE o que está aqui — sem inferir regras extras.
+
+### 4.1 Regras de Negócio
+
+| ID | Regra | Onde aplica | Ref PRD |
+|----|-------|-------------|---------|
+| RN-001 | | back / front / banco | PRD §5 RN-001 |
+
+### 4.2 Validações de Campos
+
+| Campo | Validação | Obrigatório | Mensagem de erro |
+|-------|-----------|-------------|-----------------|
+| | | | |
+
+---
+
+## 5. API — Endpoints
+
+> Contratos completos. O Coder implementa exatamente estes schemas.
+
+### `{{METHOD}} {{/api/v1/recurso}}` — {{Descrição}}
+
+**Descrição**: {{o que faz}}
+**Regras**: {{RN-xxx, RN-xxx}}
+**Autenticação**: {{público | Bearer token | API Key}} — se não público, justificar
+**Autorização**: {{roles permitidos: admin, user, owner}} — OBRIGATÓRIO se autenticado
+**Rate Limit**: {{N req/min ou N/A}} — considerar para endpoints públicos/sensíveis
+
+**Request Body**:
+```json
+{
+  "campo": "tipo (required|optional, validações)"
+}
+```
+
+**Response {{STATUS}}**:
+```json
+{
+  "campo": "tipo"
+}
+```
+
+**Erros**:
+| Status | Código | Quando |
+|--------|--------|--------|
+| 401 | `UNAUTHORIZED` | Token ausente ou inválido |
+| 403 | `FORBIDDEN` | Sem permissão para este recurso |
+| 400 | `VALIDATION_ERROR` | Campos inválidos |
+
+<!-- Repetir bloco para cada endpoint -->
+
+> **Regra de Auth**: Todo endpoint DEVE ter Autenticação e Autorização definidos explicitamente.
+> Se público, escrever "público" — nunca omitir. Erros 401/403 são obrigatórios em endpoints autenticados.
+
+---
+
+## 6. Componentes e Telas
+
+> Cada tela com seus componentes, estados e comportamentos.
+
+### Tela: {{Nome}}
+
+| Propriedade | Valor |
+|-------------|-------|
+| **Rota** | `{{/rota}}` |
+| **Permissão** | {{roles}} |
+| **Estado inicial** | {{descrição}} |
+
+**Componentes**:
+| Componente | Tipo | Comportamento |
+|------------|------|---------------|
+| | | |
+
+**Estados**:
+| Estado | Gatilho | Efeito visual |
+|--------|---------|---------------|
+| loading | requisição em andamento | skeleton/spinner |
+| empty | lista vazia | mensagem |
+| error | falha na API | toast + retry |
+
+<!-- Repetir bloco para cada tela -->
+
+---
+
+## 7. Fluxos de Dados
+
+> Sequências de operações para cada funcionalidade principal.
+> O Coder segue estes fluxos como guia de implementação.
+
+### Fluxo: {{Nome}} (fluxo principal)
+
+```
+Usuário {{ação}} → [front] {{passo}} → [back] {{passo}}
+  → [back] {{passo}}
+  → [back] retorna {{response}}
+→ [front] {{feedback}}
+```
+
+### Fluxo: {{Nome}} (fluxo de erro)
+
+```
+{{sequência do erro}}
+```
+
+<!-- Adicionar fluxos para cada funcionalidade -->
+
+---
+
+## 8. Integrações Externas
+
+> Serviços de terceiros ou outros módulos do sistema.
+
+| Serviço | Protocolo | Quando | Timeout | Retry | Fallback |
+|---------|-----------|--------|---------|-------|----------|
+| | | | | | |
+
+### Contrato: {{Nome do Serviço}}
+
+**Request**: `{{METHOD}} {{URL}}`
+```json
+{ }
+```
+**Response esperada**:
+```json
+{ }
+```
+**Tratamento de falha**: <!-- O que acontece se o serviço estiver fora -->
+
+---
+
+## 9. Estratégia de Testes
+
+> Define O QUE testar, COMO testar, ONDE ficam os testes e QUANDO rodar.
+> O Coder implementa testes junto com o código — não é etapa separada.
+
+### 9.1 Testes por área
+
+| Área | Tipo | Framework | Comando | O que cobre |
+|------|------|-----------|---------|-------------|
+| BACK | Unit | <!-- xUnit/Jest/pytest --> | <!-- dotnet test --> | Services, validações RN-*, regras de negócio |
+| BACK | Integration | <!-- WebApplicationFactory/Supertest --> | <!-- dotnet test --filter Integration --> | Endpoints completos (request → response) |
+| FRONT | Unit | <!-- React Testing Library --> | <!-- npm test --> | Componentes com lógica, hooks customizados |
+| FRONT | E2E | <!-- Playwright --> | <!-- npx playwright test --> | Jornadas do §4 / fluxos do §7 |
+| BANCO | Migration | <!-- EF migrations/Knex --> | <!-- dotnet ef database update --> | Migration roda + rollback sem erro |
+
+### 9.2 Estrutura de testes
+
+```
+<!-- Adaptar à stack do projeto. Exemplo: -->
+backend/
+├── tests/
+│   ├── Unit/              ← services, validações
+│   ├── Integration/       ← endpoints (in-memory ou testcontainers)
+│   └── Fixtures/          ← dados de teste
+frontend/
+├── tests/
+│   ├── components/        ← unit (testing library)
+│   └── e2e/               ← playwright (jornadas completas)
+```
+
+### 9.3 Critérios de Aceite
+
+> Cenários testáveis em formato Given/When/Then.
+> Cada CA mapeia para pelo menos 1 teste automatizado.
+
+#### CA-001: {{Título do cenário}}
+
+```gherkin
+Given {{pré-condição}}
+When {{ação do usuário}}
+Then {{resultado esperado}}
+```
+
+<!-- Adicionar CA-NNN para cada cenário relevante -->
+
+| CA | Tipo de teste | Arquivo de teste |
+|----|--------------|-----------------|
+| CA-001 | integration | `tests/Integration/{{Teste}}.cs` |
+| CA-002 | e2e | `tests/e2e/{{teste}}.spec.ts` |
+
+### 9.4 Métricas de Sucesso
+
+| Métrica | Threshold | Como medir |
+|---------|-----------|------------|
+| | | |
+
+---
+
+## 10. Fora de Escopo
+
+> Lista explícita — evita scope creep durante implementação.
+
+| # | Item | Motivo | Quando entra |
+|---|------|--------|--------------|
+| 1 | | | |
+
+---
+
+## 11. Delta Specs
+
+> O que muda no sistema global com esta feature.
+> Pós `/dev`: estas deltas são mergeadas nos docs de `docs/Estrutura/`.
+
+### ADDED
+<!-- Novos: tabelas, endpoints, componentes, regras, permissões -->
+-
+
+### MODIFIED
+<!-- Alterações em funcionalidades/docs existentes -->
+-
+
+### REMOVED
+<!-- Funcionalidades ou comportamentos que deixam de existir -->
+-
+
+---
+
+## Rastreabilidade Origem → SDD
+
+> Mapa rápido de referência cruzada. Garante que nenhum requisito foi perdido.
+
+### Para features (PRD → SDD):
+
+| PRD Seção | SDD Seção | Notas |
+|-----------|-----------|-------|
+| §3 Entidades | §3 Modelo de Dados | Tipos e constraints detalhados |
+| §4 Jornadas | §7 Fluxos de Dados | Traduzidas em sequências técnicas |
+| §5 Regras (RN-xxx) | §4 Regras e Validações | Mantém mesmos IDs |
+| §6 Validações | §4.2 Validações de Campos | Com mensagens de erro |
+| §7 Telas | §6 Componentes e Telas | Com estados e comportamentos |
+| §8 Integrações | §8 Integrações Externas | Com contratos detalhados |
+| §9 Erros | §5 Endpoints (Erros) | Mapeados por endpoint |
+| §10 Não-Funcionais | §9 Métricas de Sucesso | Thresholds mensuráveis |
+| §12 Fora de Escopo | §10 Fora de Escopo | Mantido igual |
+
+### Para setup (TRD → SDD):
+
+| TRD Seção | SDD Seção | Notas |
+|-----------|-----------|-------|
+| §1 Visão | §1 Visão Geral | Escopo do setup |
+| §2 Stack | §2 Decisões de Design | Justificativas expandidas |
+| §3 Arquitetura | §2 Decisões de Design | Padrões arquiteturais |
+| §4 Modelo de Dados | §3 Modelo de Dados | Tipos exatos, constraints, índices |
+| §5 API | §5 (N/A em setup) | Convenções no TRD, endpoints nas features |
+| §6 Infra | §1 Escopo | Infra base |
+| §7 Segurança | §2 Decisões + §3 | JWT, tabela usuarios |
+| §8 Módulos | §10 Fora de Escopo | Módulos futuros |
+
+---
+
+> **Regra**: Este SDD é a **única fonte de verdade** para implementação.
+> O Coder não consulta PRD, TRD, PM, ou qualquer outro documento.
+> Qualquer alteração pós-aprovação deve ser refletida aqui primeiro.

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

@@ -0,0 +1,115 @@
+# Tasks — {{AREA}} — {{FEATURE}}
+
+> Checklist de implementação organizado por **fases** e **prioridade**.
+> O Coder consulta o `sdd.md` para detalhes técnicos.
+> Este arquivo define O QUE fazer, EM QUE ORDEM, e ONDE.
+
+---
+
+## Meta
+
+| Campo | Valor |
+|-------|-------|
+| Feature | `{{FEATURE}}` |
+| Área | {{AREA}} |
+| SDD | [`sdd.md`](./sdd.md) {{SDD_SECTIONS}} |
+| Total de tasks | {{TOTAL}} |
+| Depende de | {{AREA_DEPENDENCIES}} |
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+COMO GERAR ESTE ARQUIVO:
+
+1. Ler o SDD completo da feature
+2. Identificar TODAS as áreas afetadas (banco, back, front, mobile, infra...)
+3. Para CADA área, gerar um arquivo `{area}_tasks.md` usando este template
+4. Áreas são DINÂMICAS — determinadas pelo SDD, não pré-definidas
+
+COMO DEFINIR FASES:
+
+- Agrupar tasks por etapa lógica de implementação
+- Fases são SEQUENCIAIS dentro da área (Fase 2 depende de Fase 1)
+- Usar prioridade P1/P2/P3 por fase
+- Nomear fases de forma descritiva (não só "Fase 1")
+- Exemplos de fases por área:
+  
+  BANCO:     Setup → Schema → Índices → Seeds
+  BACKEND:   Setup → DTOs/Validações → Repository/Service → Controller → Testes
+  FRONTEND:  Setup/Rotas → Componentes → Telas → Polish
+  MOBILE:    Setup → Navegação → Telas → Offline → Push
+  INFRA:     Provisão → Config → Deploy → Monitoramento
+
+COMO ESCREVER CADA TASK:
+
+- Formato checklist: `- [ ] **ID**: Título [Tamanho]`
+- ID: {PREFIXO}-{NNN} sequencial (BANCO-001, BACK-001, FRONT-001, MOBILE-001...)
+- Título: verbo no infinitivo + o que fazer
+- Tamanho: S (< 30min), M (30min-2h), L (2h+)
+- Fase: número da fase de entrega (do PRD §11) — OBRIGATÓRIO
+- Repo: nome do repo (de projetos.yaml) — OBRIGATÓRIO
+- Arquivos: EXATAMENTE quais files criar ou alterar (caminhos RELATIVOS ao repo)
+- SDD: seção específica (§3.1, §5 POST /rota, §6 Tela X)
+- Depende: IDs de tasks (mesma área ou cross-area)
+
+REGRAS:
+
+- Task deve ser AUTOCONTIDA: Coder lê SDD + esta task, nada mais
+- NÃO duplicar conteúdo do SDD — apenas referenciar seções
+- NÃO incluir status — vive só no Progresso.md
+- Depende cross-area é permitido (FRONT-004 depende de BACK-009)
+- "Regras desta área" = convenções específicas extraídas do SDD e docs/Estrutura
+
+=============================================================================
+-->
+
+## Fase 1 — {{FASE_NOME}} [{{PRIORIDADE}}]
+
+> {{FASE_CONTEXTO — 1 linha explicando o propósito da fase}}
+<!-- Opcional: "Depende de: Área X Fase Y concluída" -->
+
+- [ ] **{{PREFIXO}}-001**: {{Título descritivo}} [{{S|M|L}}]
+  - Fase: {{N}} — {{Nome fase de entrega}}
+  - Repo: `{{repo_name}}`
+  - Arquivos: `{{caminho/arquivo.ext}}`
+  - SDD: {{§N seção específica}}
+  - Depende: {{ID ou —}}
+
+- [ ] **{{PREFIXO}}-002**: {{Título descritivo}} [{{S|M|L}}]
+  - Fase: {{N}} — {{Nome fase de entrega}}
+  - Repo: `{{repo_name}}`
+  - Arquivos: `{{caminho/arquivo1.ext}}`, `{{caminho/arquivo2.ext}}`
+  - SDD: {{§N.M subseção}}
+  - Depende: {{PREFIXO}}-001
+
+---
+
+## Fase 2 — {{FASE_NOME}} [{{PRIORIDADE}}]
+
+> {{FASE_CONTEXTO}}
+
+- [ ] **{{PREFIXO}}-003**: {{Título}} [{{S|M|L}}]
+  - Fase: {{N}} — {{Nome fase de entrega}}
+  - Repo: `{{repo_name}}`
+  - Arquivos: `{{caminho/}}`
+  - SDD: {{§N}}
+  - Depende: {{PREFIXO}}-001, {{OUTRA_AREA}}-001
+
+<!-- Repetir fases conforme necessário -->
+
+---
+
+## Regras desta área
+
+<!-- Extraídas do SDD e docs/Estrutura/ — específicas para esta área -->
+1. {{Regra 1}}
+2. {{Regra 2}}
+
+---
+
+> **Legenda tamanho**: S = < 30min · M = 30min-2h · L = 2h+
+> **Legenda prioridade**: P1 = bloqueia outras áreas · P2 = importante · P3 = nice-to-have

package/templates/docs/_templates/global/progresso_global.template.md

@@ -0,0 +1,57 @@
+# Progresso Geral
+
+> Visão consolidada de todas as features, bugs e tarefas do projeto.
+> Atualizado automaticamente ao final de cada `/plan` e `/dev`.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado na primeira vez)
+=============================================================================
+
+QUANDO USAR: Criado pelo /plan do primeiro setup ou feature. Atualizado por cada /plan e /dev.
+
+COMO ATUALIZAR:
+- Ao criar nova feature (/plan) → adicionar linha na tabela com contadores zerados
+- Ao concluir tasks (/dev) → atualizar contadores
+- Ao concluir feature (/merge-delta) → status "concluído" ou "done"
+
+ÁREAS SÃO DINÂMICAS:
+- Colunas de área mudam conforme o projeto (BANCO, BACK, FRONT, DOC, INFRA, MOBILE...)
+- Cada feature pode ter áreas diferentes
+- Usar "—" quando uma feature não tem tasks naquela área
+
+STATUS USA O VALOR DO .context.md:
+- not_started, extract_done, approved, design_done, plan_done, dev_in_progress, dev_done, done
+
+=============================================================================
+-->
+
+## Resumo
+
+| # | Feature | Status | {{AREA_1}} | {{AREA_2}} | {{AREA_N}} | Última atualização |
+|---|---------|--------|------------|------------|------------|-------------------|
+| 1 | {{NOME}} | {{status}} | 0/N | 0/N | 0/N | {{data}} |
+
+<!-- Exemplo preenchido:
+| 1 | setup_projeto | plan_done | BANCO: 0/7 | BACK: 0/10 | FRONT: 0/3 | DOC: 0/8 | 2026-04-08 |
+| 2 | feat_cadastro_cliente | extract_done | — | — | — | — | 2026-04-09 |
+-->
+
+## Legenda de Status
+
+| Status | Significado |
+|--------|-------------|
+| `not_started` | Pipeline iniciado, aguardando extração |
+| `extract_done` | PRD/TRD gerado, aguardando aprovação |
+| `approved` | Documento aprovado |
+| `design_done` | SDD gerado |
+| `plan_done` | Tasks geradas, pronto para /dev |
+| `dev_in_progress` | /dev em execução |
+| `dev_done` | Todas tasks concluídas |
+| `done` | Delta specs mergeadas (features) ou docs gerados (setup) |
+
+---
+
+> **Atualização**: Cada skill atualiza este arquivo ao criar ou concluir features.