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

package/templates/.github/templates/feature/Progresso.template.md

@@ -1,136 +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/`
-- [ ] Atualizar `workspace/Output/progresso.md` (visão global)
-- [ ] Atualizar `.ai/memory/napkin.md` se houver aprendizado relevante
+# 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 specs/{nome}/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/`
+- [ ] Atualizar `workspace/Output/progresso.md` (visão global)
+- [ ] Atualizar `.ai/memory/napkin.md` se houver aprendizado relevante

package/templates/.github/templates/specs/brief.template.md

@@ -0,0 +1,47 @@
+# Brief — {{NOME}}
+
+> Projeção estruturada do SDD para consumo do agent coder.
+> Gerado automaticamente pelo /sf-design a partir do SDD em `workspace/Output/{{NOME}}/sdd.md`.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: /sf-design — projeção do SDD §1 Visão geral + §2 Decisões + §10 Fora do escopo.
+ATUALIZAÇÃO: Sempre regenerado junto com o SDD. NUNCA editado manualmente.
+
+REGRA DE OURO: Se algo aqui diverge do SDD, o SDD vence. Re-rode /sf-design.
+
+O brief é o "por quê" + "o quê" destilado. Sem narrativa longa — bullets objetivos.
+O coder lê o brief pra contexto, mas não deriva código daqui.
+Contratos ficam em contracts.md. Cenários ficam em scenarios.md.
+
+=============================================================================
+-->
+
+## Problema
+
+<!-- 2-3 frases. O que está faltando/quebrado que essa feature resolve. -->
+
+## Solução
+
+<!-- High level: como estamos resolvendo. Não é design técnico. -->
+
+## Escopo
+
+### Dentro
+-
+
+### Fora
+-
+
+## Decisões principais
+
+<!-- Mini-ADRs inline — cada decisão com justificativa em 1 linha. -->
+
+| # | Decisão | Justificativa |
+|---|---------|---------------|
+| 1 |         |               |

package/templates/.github/templates/specs/contracts.template.md

@@ -0,0 +1,82 @@
+# Contracts — {{NOME}}
+
+> Projeção estruturada do SDD para consumo do agent coder.
+> Gerado automaticamente pelo /sf-design a partir do SDD em `workspace/Output/{{NOME}}/sdd.md`.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: /sf-design — projeção do SDD §3 Modelo de dados + §4 Regras/validações
+        + §5 Endpoints API + §8 Integrações externas.
+ATUALIZAÇÃO: Sempre regenerado junto com o SDD. NUNCA editado manualmente.
+
+REGRA DE OURO: Se algo aqui diverge do SDD, o SDD vence. Re-rode /sf-design.
+
+O contracts.md é o "o que construir" — contratos executáveis.
+Tipos exatos do banco (não "string"). Request/response JSON completos.
+Regras de negócio com RN-NNN e enforcement points.
+
+=============================================================================
+-->
+
+## Dados
+
+<!-- Entidades, tabelas, campos, constraints, índices.
+Tipos EXATOS do banco escolhido (varchar(255), não "string"). -->
+
+### {{tabela}}
+
+| Coluna | Tipo | Nullable | Default | Constraint |
+|--------|------|----------|---------|------------|
+|        |      |          |         |            |
+
+**Relações:**
+- `campo_id` → `tabela_ref(id)` ON DELETE ...
+
+**Índices:**
+- `idx_nome` em `(colunas)` — justificativa
+
+## API
+
+<!-- Endpoints com contratos JSON completos. -->
+
+### {{método}} {{rota}}
+
+**Auth**: <!-- Bearer / público / role -->
+**Rate limit**: <!-- categoria -->
+
+**Request:**
+```json
+{}
+```
+
+**Response 200:**
+```json
+{}
+```
+
+**Errors:**
+| Status | Code | Quando |
+|--------|------|--------|
+| 400 | | |
+| 422 | | |
+
+## Integrações externas
+
+<!-- Sistemas terceiros que essa feature consome/notifica. -->
+
+| Sistema | Direção | Protocolo | Timeout | Retry | Fallback |
+|---------|---------|-----------|---------|-------|----------|
+|         |         |           |         |       |          |
+
+## Regras de negócio
+
+<!-- RN-NNN com ponto de enforcement (DB constraint, service, middleware, etc). -->
+
+| ID | Regra | Enforcement | Error code |
+|----|-------|-------------|------------|
+| RN-001 |  |  |  |

package/templates/.github/templates/specs/scenarios.template.md

@@ -0,0 +1,79 @@
+# Scenarios — {{NOME}}
+
+> Projeção estruturada do SDD para consumo do agent coder e reviewer.
+> Gerado automaticamente pelo /sf-design a partir do SDD em `workspace/Output/{{NOME}}/sdd.md`.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: /sf-design — projeção do SDD §6 Componentes/telas + §7 Fluxos de dados
+        + §9 Estratégia de testes + Critérios de aceite.
+ATUALIZAÇÃO: Sempre regenerado junto com o SDD. NUNCA editado manualmente.
+
+REGRA DE OURO: Se algo aqui diverge do SDD, o SDD vence. Re-rode /sf-design.
+
+O scenarios.md é o "como validar que funciona" — Given/When/Then testáveis,
+fluxos usuário→front→back, estados de UI (loading/empty/error/success).
+
+O REVIEWER usa este arquivo pra validar critérios de aceite após implementação.
+Cada CA-NNN deve ser mapeável a um teste executável.
+
+=============================================================================
+-->
+
+## Fluxos principais
+
+<!-- Sequências usuário → front → back → resposta. Caminhos de erro inclusos. -->
+
+### Fluxo: {{nome}}
+
+```
+usuário → [ação] → front → [request] → back → [validação+persistência] → resposta
+```
+
+**Caminhos de erro:**
+- Erro X → resposta Y
+- Timeout → retry / fallback
+
+## UI / Componentes
+
+<!-- Telas e componentes principais com seus estados. -->
+
+### {{componente}}
+
+| Estado | Gatilho | Visual |
+|--------|---------|--------|
+| loading | | |
+| empty | | |
+| error | | |
+| success | | |
+
+## Critérios de Aceite
+
+<!-- Given/When/Then. Cada CA deve ser mapeável a um teste. -->
+
+### CA-001: {{título curto}}
+
+- **Given**: estado inicial
+- **When**: ação
+- **Then**: resultado esperado
+- **Teste**: `tipo` — `arquivo_de_teste.ext`
+
+### CA-002: {{título curto}}
+
+- **Given**:
+- **When**:
+- **Then**:
+- **Teste**:
+
+## Estratégia de testes
+
+| Nível | Framework | O que testa | Onde rodam |
+|-------|-----------|-------------|------------|
+| Unit | | lógica isolada | por task |
+| Integration | | entre componentes | por fase |
+| E2E | | CAs completos | por feature |

package/templates/.github/templates/specs/tasks.template.md

@@ -0,0 +1,61 @@
+# Tasks — {{NOME}}
+
+> Plano de implementação único. Todas as tasks em uma tabela com coluna Área.
+> Gerado pelo /sf-plan a partir do SDD + specs/{{NOME}}/.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+ORIGEM: /sf-plan — deriva de sdd.md + contracts.md + scenarios.md
+ATUALIZAÇÃO: /sf-plan re-roda se SDD/contracts/scenarios mudarem.
+
+STATUS vive em workspace/Output/{{NOME}}/Progresso.md — NÃO aqui.
+Tasks são só a definição do que precisa ser feito, não o estado.
+
+CAMPOS OBRIGATÓRIOS:
+- ID: {ÁREA}-NNN sequencial por área (BANCO-001, BACK-001, FRONT-001, INFRA-001)
+- Área: BANCO | BACK | FRONT | INFRA | DOC
+- Fase: número da fase de entrega (entregáveis contínuos)
+- Tamanho: S (≤2h) | M (meio dia) | L (1-2 dias)
+- Título: ação no imperativo ("Criar tabela clientes")
+- Repo: nome do serviço no projetos.yaml (api, web, worker...)
+- Arquivos: caminhos que a task vai criar/modificar (relativos ao repo)
+- Depende de: outros IDs — cross-area OK
+- Ref spec: seção do SDD que define essa task
+- Ref CA: ID do critério de aceite em scenarios.md (se aplica)
+
+REGRAS:
+- IDs estáveis — nunca renumerar após commit
+- Depends_on cross-area é OK (BACK-001 depende de BANCO-001)
+- Toda task deve ter pelo menos 1 teste (unit + optional integration)
+- Tarefas da mesma fase/área rodam em sequência, fases são sequenciais
+
+=============================================================================
+-->
+
+## Tasks
+
+| ID | Área | Fase | Tam | Título | Repo | Arquivos | Depende de | Ref spec | Ref CA |
+|----|------|------|-----|--------|------|----------|-----------|----------|--------|
+| BANCO-001 | BANCO | 1 | S | | | | — | SDD §3.1 | — |
+| BACK-001 | BACK | 1 | M | | | | BANCO-001 | SDD §5.1 | CA-001 |
+
+## Regras por área
+
+<!-- Convenções específicas extraídas do SDD + docs/ (architecture, domain, conventions). -->
+
+### BANCO
+-
+
+### BACK
+-
+
+### FRONT
+-
+
+### INFRA
+-

package/templates/.github/templates/feature/tasks.template.md

@@ -1,115 +0,0 @@
-# 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
-
-=============================================================================
--->
-
-## 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/ — 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