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

package/templates/.github/skills/sf-design/SKILL.md

@@ -39,10 +39,10 @@ Exemplo: `/sf-design feat_cadastro_cliente`
 | # | Validação | Se falhar |
 |---|-----------|-----------|
 | 1 | Argumento `nome` foi informado | Parar → "Informe o nome. Ex: /sf-design feat_cadastro_cliente" |
-| 2 | `docs/Desenvolvimento/{nome}/.context.md` existe | Parar → "Execute /sf-feature {nome} ou /sf-setup-projeto primeiro" |
+| 2 | `workspace/Output/{nome}/.context.md` existe | Parar → "Execute /sf-feature {nome} ou /sf-setup-projeto primeiro" |
 | 3 | Status é `extract_done` ou `approved` | Se anterior → "Execute /sf-extract primeiro". Se posterior → "SDD já foi gerado (status: {status})" |
 | 4 | PRD.md ou TRD.md existe na pasta | Parar → "Documento de extração não encontrado. Execute /sf-extract {nome}" |
-| 5 | `docs/Estrutura/` está populado (para features) | Parar → "Execute /sf-setup-projeto primeiro" (não aplica para tipo=setup) |
+| 5 | `docs/` está populado (para features) | Parar → "Execute /sf-setup-projeto primeiro" (não aplica para tipo=setup) |
 
 ## Passos
 
@@ -50,7 +50,7 @@ Exemplo: `/sf-design feat_cadastro_cliente`
 Se status é `extract_done` (não `approved`):
 ```
 Pergunta ao usuário:
-  "O {PRD/TRD} em docs/Desenvolvimento/{nome}/ foi revisado e está aprovado? (s/n)"
+  "O {PRD/TRD} em workspace/Output/{nome}/ foi revisado e está aprovado? (s/n)"
 
   Se SIM → atualizar .context.md status: approved → continuar
   Se NÃO → parar → "Revise o documento e chame /sf-design {nome} quando estiver pronto"
@@ -62,29 +62,27 @@ Ler seção de ambiguidades do PRD (§13) ou TRD (§9):
 - Listar as ambiguidades pendentes
 - Instruir: "Responda as ambiguidades no documento e chame /sf-design {nome} novamente"
 
-### 3. Gerar docs/Estrutura/ (APENAS para setup)
+### 3. Gerar docs/ (APENAS para setup)
 
-> Este passo só executa quando tipo=setup. Para features, docs/Estrutura/ já existe.
+> Este passo só executa quando tipo=setup. Para features, docs/ já existe.
 
-Ler TRD e gerar os 8 docs de `docs/Estrutura/` usando os templates correspondentes:
+Ler TRD e gerar os 5 docs de `docs/` usando os templates correspondentes:
 
-| TRD Seção | Doc gerado | Template |
-|-----------|-----------|---------|
-| §1 Visão + §8 Módulos | Visao.md | `_templates/estrutura/Visao.template.md` |
-| §2 Stack | Stack.md | `_templates/estrutura/Stack.template.md` |
-| §3 Arquitetura | Arquitetura.md | `_templates/estrutura/Arquitetura.template.md` |
-| §4 Modelo de Dados | Modelo_Dados.md | `_templates/estrutura/Modelo_Dados.template.md` |
-| §5 API | API.md | `_templates/estrutura/API.template.md` |
-| §6 Infra | Infraestrutura.md | `_templates/estrutura/Infraestrutura.template.md` |
-| §7 Segurança | Seguranca.md | `_templates/estrutura/Seguranca.template.md` |
-| SDD §2 (após gerar) | ADRs.md | `_templates/estrutura/ADRs.template.md` |
+| Doc gerado | Fontes (TRD) | Template |
+|-----------|--------------|---------|
+| architecture.md | §3 Arquitetura + §2 Stack + §6 Infra (ambientes, deploy, CI/CD, rollback) | `.github/templates/estrutura/architecture.template.md` |
+| domain.md | §1 Visão + §4 Modelo de Dados | `.github/templates/estrutura/domain.template.md` |
+| conventions.md | §7 Segurança + §6 Infra (env vars, domínios, monitoramento) + §5 API (códigos de erro de domínio) + §2 Stack (alternativas, versionamento) | `.github/templates/estrutura/conventions.template.md` |
+| apiContracts.md | §5 API (padrão geral, rotas, paginação, filtros, erros, catálogo) | `.github/templates/estrutura/apiContracts.template.md` |
+| decisions.md | SDD §2 Decisões (após gerar) + decisões iniciais de stack/arquitetura | `.github/templates/estrutura/decisions.template.md` |
 
 Regras:
 - Ler template → preencher TODAS seções com dados do TRD
 - Remover bloco `<!-- INSTRUÇÕES -->` do doc gerado
 - Changelog inicia vazio (primeira geração)
 - Se TRD não tem dados pra uma seção → marcar "A definir"
-- ADRs.md é gerado APÓS o SDD (usa §2 Decisões de Design)
+- decisions.md é gerado APÓS o SDD (usa §2 Decisões de Design como ponto de partida)
+- TRD §8 Módulos NÃO vira doc de Estrutura — vai para backlog faseado
 
 ### 3b. Gerar `projetos.yaml` (APENAS para setup)
 
@@ -112,9 +110,9 @@ Nunca juntar serviços que o TRD definiu como distintos.
 
 ### 4. Carregar contexto
 - Ler PRD.md ou TRD.md completo (conforme `.context.md`)
-- Ler `docs/Estrutura/` completo (agora já populado, mesmo no setup)
-- Ler `docs/Desenvolvimento/rules.md` (convenções de desenvolvimento)
-- Carregar template `docs/_templates/feature/sdd.template.md`
+- Ler `docs/` completo (agora já populado, mesmo no setup)
+- Ler `.github/rules.md` (convenções de desenvolvimento)
+- Carregar template `.github/templates/feature/sdd.template.md`
 
 ### 5. Gerar SDD
 Produzir `sdd.md` com as 11 seções obrigatórias:
@@ -123,15 +121,15 @@ Produzir `sdd.md` com as 11 seções obrigatórias:
 |-------|----------|-----------------|
 | §1 Visão geral | O que, escopo, premissas | PRD §1 / TRD §1 |
 | §2 Decisões de design | Mini-ADRs com justificativa | Arquitetura + análise do agente |
-| §3 Modelo de dados | Entidades com tipos exatos, constraints, migrations | PRD §3 + Modelo_Dados.md |
+| §3 Modelo de dados | Entidades com tipos exatos, constraints, migrations | PRD §3 + domain.md |
 | §4 Regras e validações | Ref PRD §5 RN-NNN, mensagens de erro | PRD §5 + §6 |
-| §5 Endpoints API | Contratos completos: request/response JSON, status codes | PRD §4 + API.md |
+| §5 Endpoints API | Contratos completos: request/response JSON, status codes | PRD §4 + apiContracts.md |
 | §6 Componentes e telas | Estados (loading/empty/error), componentes, comportamentos | PRD §7 |
 | §7 Fluxos de dados | Sequências usuário→front→back, caminhos de erro | PRD §4 + §9 |
 | §8 Integrações externas | Protocolo, timeout, retry, fallback | PRD §8 |
 | §9 Estratégia de testes | Framework, estrutura, CAs mapeados a testes | PRD §4 + §10 |
 | §10 Fora do escopo | Lista explícita do que NÃO será feito | PRD §12 |
-| §11 Delta Specs | ADDED/MODIFIED/REMOVED para merge em docs/Estrutura/ | Análise do agente |
+| §11 Delta Specs | ADDED/MODIFIED/REMOVED para merge em docs/ | Análise do agente |
 
 **Regras de geração:**
 1. SDD deve ser **auto-contido** — o coder lê APENAS o SDD + task, nunca PRD/PM
@@ -142,8 +140,9 @@ Produzir `sdd.md` com as 11 seções obrigatórias:
 6. Critérios de aceite testáveis — Given/When/Then, não frases vagas
 7. Delta Specs sempre preenchida, mesmo que vazia (ADDED: nenhum)
 
-### 6. Gerar ADRs.md (setup — complemento do passo 3)
-Após gerar SDD §2, criar ADRs.md com as decisões iniciais de arquitetura.
+### 6. Complementar decisions.md (setup — complemento do passo 3)
+Após gerar SDD §2, popular `decisions.md` com as decisões iniciais de arquitetura
+(stack principal, padrões de design, trade-offs significativos).
 
 ### 7. Atualizar `.context.md`
 ```yaml
@@ -160,7 +159,7 @@ atualizado_em: "{{ISO_DATETIME}}"
 |---------|-----------|
 | `sdd.md` | Especificação técnica completa e auto-contida |
 | `projetos.yaml` | (setup) Manifesto de repos — mapeamento serviço → repo → áreas |
-| `docs/Estrutura/*.md` | (setup) 8 docs globais preenchidos do TRD |
+| `docs/*.md` | (setup) 5 docs globais preenchidos do TRD (architecture, domain, conventions, apiContracts, decisions) |
 | `.context.md` | Atualizado: `approved` → `design_done` |
 
 ## Pós-condições
@@ -177,5 +176,5 @@ atualizado_em: "{{ISO_DATETIME}}"
 | Status posterior a approved | Informar que SDD já foi gerado |
 | Ambiguidades pendentes no PRD/TRD | Parar, listar ambiguidades |
 | PRD/TRD não encontrado | Parar, sugerir /sf-extract |
-| docs/Estrutura/ vazio (em features) | Parar, sugerir /sf-setup-projeto |
+| docs/ vazio (em features) | Parar, sugerir /sf-setup-projeto |
 | Informação insuficiente no PRD/TRD para gerar seção | NÃO inventar — marcar seção como incompleta, reportar ao usuário |

package/templates/.github/skills/sf-dev/SKILL.md

@@ -51,7 +51,7 @@ O agente é selecionado pelo prefixo da task: `BANCO-*` → DB Coder, `BACK-*`
 | 2 | `.context.md` existe com status `plan_done` ou `dev_in_progress` | Se anterior → "Execute /sf-plan {nome} primeiro" |
 | 3 | `*_tasks.md` e `Progresso.md` existem | Parar → "Tasks não encontradas. Execute /sf-plan {nome}" |
 | 4 | `sdd.md` existe | Parar → "SDD não encontrado" |
-| 5 | `docs/Desenvolvimento/rules.md` existe | Parar → "rules.md não encontrado" |
+| 5 | `.github/rules.md` existe | Parar → "rules.md não encontrado" |
 | 6 | `projetos.yaml` existe na raiz | Parar → "Execute /sf-design primeiro (gera projetos.yaml)" |
 | 7 | Infra local rodando (`docker compose ps` → containers healthy) | Parar → "Suba a infra primeiro: `docker compose up -d` e aguarde healthy" |
 
@@ -115,7 +115,17 @@ O agente é selecionado pelo prefixo da task: `BANCO-*` → DB Coder, `BACK-*`
 │  ║                                               ║
 │  ║  1. Rodar testes E2E (SDD §9.3 CAs)          ║
 │  ║     → Falhou? Identificar task → fix → loop   ║
-│  ║  2. Todos CAs passam? → dev_done ✅            ║
+│  ║  2. Todos CAs passam? → prosseguir             ║
+│  ╚═══════════════════════════════════════════════╝
+│         ↓ (E2E aprovado, só features)
+│  ╔═══════════════════════════════════════════════╗
+│  ║  MERGE-DELTA (automático, só features)        ║
+│  ║                                               ║
+│  ║  1. Ler SDD §11 (Delta Specs)                ║
+│  ║  2. Aplicar ADDED/MODIFIED/REMOVED em         ║
+│  ║     docs/                           ║
+│  ║  3. Registrar changelog em cada doc alterado  ║
+│  ║  4. dev_done ✅                                ║
 │  ╚═══════════════════════════════════════════════╝
 ```
 
@@ -209,7 +219,7 @@ Ao concluir todas tasks de uma fase:
 
 ### 5. Security Review (cross-area)
 Ao concluir todas tasks de todas áreas, ANTES dos testes E2E:
-- Spawn Security Reviewer (Opus) com: todo código produzido + SDD §5 + Seguranca.md
+- Spawn Security Reviewer (Opus) com: todo código produzido + SDD §5 + conventions.md
 - Audita 6 categorias: Auth, AuthZ, Injeção, Dados Sensíveis, Headers, Banco
 - Se findings CRÍTICO ou ALTO:
   - Identificar área responsável (BACK, FRONT, BANCO, INFRA)
@@ -226,7 +236,7 @@ Ao concluir security review com aprovação:
   - Mapear pra task/área responsável
   - Criar fix inline (não cria nova task)
   - Rodar E2E de novo
-- Se passou → dev_done
+- Se passou → prosseguir para merge-delta (features) ou dev_done (setup)
 
 ### 7. Finalizar fase — PR + ambiente ON
 Ao concluir todos testes da fase:
@@ -258,11 +268,24 @@ git branch -d feature/{nome}_fase{N}
 git remote prune origin
 ```
 
-### 9. Atualizar `.context.md`
+### 9. Merge-Delta automático (só features)
+
+Após E2E aprovado, SE `.context.md` tipo = `feature`:
+1. Ler SDD §11 (seção Delta Specs: ADDED/MODIFIED/REMOVED)
+2. Para cada delta, mapear para o doc de `docs/` correspondente
+3. Aplicar as mudanças (adicionar, modificar ou remover seções)
+4. Registrar changelog em cada doc alterado: `| {{DATA}} | {{NOME}} | {{TIPO}} | {{DESCRIÇÃO}} |`
+5. Validar consistência cross-doc (ex: endpoint no apiContracts.md referencia tabela no domain.md)
+
+Se tipo = `setup` → pular (docs/ já foi criado pelo /design).
+
+> O `/sf-merge-delta` continua existindo como skill atômica para re-execução manual se necessário.
+
+### 10. Atualizar `.context.md`
 ```yaml
 status: "dev_in_progress"  # durante execução
 # ou
-status: "dev_done"         # todas fases + integration + security + E2E passaram
+status: "dev_done"         # todas fases + integration + security + E2E + merge-delta
 ultima_skill: "/sf-dev"
 atualizado_em: "{{ISO_DATETIME}}"
 ```
@@ -309,7 +332,7 @@ Ação necessária: revisar SDD ou intervir manualmente.
 - Integration tests passam por fase
 - Security Review aprovado (zero findings CRÍTICO/ALTO)
 - E2E tests passam por feature (todos CAs do SDD §9.3)
-- Pronto para `/merge-delta` (se feature) ou conclusão (se setup)
+- Merge-delta aplicado automaticamente (features) — docs/ atualizado
 
 ## Erros