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

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

@@ -1,181 +1,180 @@
----
-name: sf-design
-description: |
-  Design técnico. Gera SDD a partir do PRD/TRD aprovado.
-  Trigger: /sf-design
-author: GustavoMaritan
-version: 1.0.0
-date: 2026-04-08
----
-
-# Skill: /sf-design
-
-> Skill atômica de design técnico. Lê PRD/TRD aprovado e gera SDD.
-> Responsável pelo checkpoint de aprovação do documento de extração.
-
-## Tipo
-Atômica — Single-agent
-
-## Uso
-```
-/sf-design <nome>
-```
-Exemplo: `/sf-design feat_cadastro_cliente`
-
----
-
-## Agente
-
-| Campo | Valor |
-|-------|-------|
-| **Papel** | Arquiteto de software — transforma requisitos aprovados em especificação técnica implementável |
-| **Modelo** | Opus |
-| **Comportamento** | Técnico e preciso. Gera contratos completos (JSON schemas, SQL DDL, componentes com estados). Toda decisão tem justificativa. Se o PRD/TRD tem gaps, não inventa — para e reporta. |
-
----
-
-## Pré-condições
-
-| # | 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" |
-| 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) |
-
-## Passos
-
-### 1. Checkpoint de aprovação
-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)"
-
-  Se SIM → atualizar .context.md status: approved → continuar
-  Se NÃO → parar → "Revise o documento e chame /sf-design {nome} quando estiver pronto"
-```
-
-### 2. Verificar ambiguidades
-Ler seção de ambiguidades do PRD (§13) ou TRD (§9):
-- Se há perguntas sem resposta → **PARAR**
-- Listar as ambiguidades pendentes
-- Instruir: "Responda as ambiguidades no documento e chame /sf-design {nome} novamente"
-
-### 3. Gerar docs/Estrutura/ (APENAS para setup)
-
-> Este passo só executa quando tipo=setup. Para features, docs/Estrutura/ já existe.
-
-Ler TRD e gerar os 8 docs de `docs/Estrutura/` 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` |
-
-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)
-
-### 3b. Gerar `projetos.yaml` (APENAS para setup)
-
-> Mapeia a arquitetura do TRD §3 para repositórios independentes.
-> Cada serviço = 1 repo. Os repos serão criados/clonados pelo /sf-dev (INFRA-001).
-
-Ler TRD §3 (Arquitetura) e §6 (Infra) para identificar os serviços:
-
-1. Identificar serviços separados (api, worker, web, mobile, etc.)
-2. Perguntar ao usuário:
-   - Organização/usuário do GitHub (ex: `empresa`)
-   - Nome base do projeto (ex: `meu-projeto`)
-   - Se algum repo já existe (para clonar em vez de criar)
-3. Gerar `projetos.yaml` na raiz usando template `projetos.template.yaml`
-4. Mapear áreas de task para repos:
-   - BACK → api (ou worker, se separado)
-   - BANCO → api (se usa EF migrations) ou repo próprio
-   - FRONT → web
-   - MOBILE → mobile
-   - INFRA → todos (cross-repo)
-5. Validar: cada área DEVE mapear para exatamente 1 repo
-
-**Regra**: Se o TRD indica API e Worker como serviços separados, DEVEM ser repos separados.
-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`
-
-### 5. Gerar SDD
-Produzir `sdd.md` com as 11 seções obrigatórias:
-
-| Seção | Conteúdo | Fonte principal |
-|-------|----------|-----------------|
-| §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 |
-| §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 |
-| §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 |
-
-**Regras de geração:**
-1. SDD deve ser **auto-contido** — o coder lê APENAS o SDD + task, nunca PRD/PM
-2. Toda regra/entidade referencia seção do PRD/TRD (rastreabilidade)
-3. Seções não aplicáveis marcadas `N/A — [motivo]` (ex: §6 em setup sem UI)
-4. Contratos de API com JSON schema completo (request, response, erros)
-5. Modelo de dados com tipos exatos, não genéricos (varchar(255), não "string")
-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.
-
-### 7. Atualizar `.context.md`
-```yaml
-status: "design_done"
-ultima_skill: "/sf-design"
-atualizado_em: "{{ISO_DATETIME}}"
-```
-
----
-
-## Saídas
-
-| Arquivo | Descrição |
-|---------|-----------|
-| `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 |
-| `.context.md` | Atualizado: `approved` → `design_done` |
-
-## Pós-condições
-- SDD é fonte única de verdade para implementação
-- Toda informação para implementar está no SDD — nenhuma consulta externa necessária
-- Rastreabilidade: SDD → PRD/TRD → insumos
-
-## Erros
-
-| Erro | Ação |
-|------|------|
-| Nome não informado | Parar, mostrar exemplo |
-| Status anterior a extract_done | Parar, sugerir /sf-extract |
-| 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 |
-| Informação insuficiente no PRD/TRD para gerar seção | NÃO inventar — marcar seção como incompleta, reportar ao usuário |
+---
+name: sf-design
+description: |
+  Design técnico. Gera SDD a partir do PRD/TRD aprovado.
+  Trigger: /sf-design
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-04-08
+---
+
+# Skill: /sf-design
+
+> Skill atômica de design técnico. Lê PRD/TRD aprovado e gera SDD.
+> Responsável pelo checkpoint de aprovação do documento de extração.
+
+## Tipo
+Atômica — Single-agent
+
+## Uso
+```
+/sf-design <nome>
+```
+Exemplo: `/sf-design feat_cadastro_cliente`
+
+---
+
+## Agente
+
+| Campo | Valor |
+|-------|-------|
+| **Papel** | Arquiteto de software — transforma requisitos aprovados em especificação técnica implementável |
+| **Modelo** | Opus |
+| **Comportamento** | Técnico e preciso. Gera contratos completos (JSON schemas, SQL DDL, componentes com estados). Toda decisão tem justificativa. Se o PRD/TRD tem gaps, não inventa — para e reporta. |
+
+---
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | Argumento `nome` foi informado | Parar → "Informe o nome. Ex: /sf-design feat_cadastro_cliente" |
+| 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/` está populado (para features) | Parar → "Execute /sf-setup-projeto primeiro" (não aplica para tipo=setup) |
+
+## Passos
+
+### 1. Checkpoint de aprovação
+Se status é `extract_done` (não `approved`):
+```
+Pergunta ao usuário:
+  "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"
+```
+
+### 2. Verificar ambiguidades
+Ler seção de ambiguidades do PRD (§13) ou TRD (§9):
+- Se há perguntas sem resposta → **PARAR**
+- Listar as ambiguidades pendentes
+- Instruir: "Responda as ambiguidades no documento e chame /sf-design {nome} novamente"
+
+### 3. Gerar docs/ (APENAS para setup)
+
+> Este passo só executa quando tipo=setup. Para features, docs/ já existe.
+
+Ler TRD e gerar os 5 docs de `docs/` usando os templates correspondentes:
+
+| 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"
+- 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)
+
+> Mapeia a arquitetura do TRD §3 para repositórios independentes.
+> Cada serviço = 1 repo. Os repos serão criados/clonados pelo /sf-dev (INFRA-001).
+
+Ler TRD §3 (Arquitetura) e §6 (Infra) para identificar os serviços:
+
+1. Identificar serviços separados (api, worker, web, mobile, etc.)
+2. Perguntar ao usuário:
+   - Organização/usuário do GitHub (ex: `empresa`)
+   - Nome base do projeto (ex: `meu-projeto`)
+   - Se algum repo já existe (para clonar em vez de criar)
+3. Gerar `projetos.yaml` na raiz usando template `projetos.template.yaml`
+4. Mapear áreas de task para repos:
+   - BACK → api (ou worker, se separado)
+   - BANCO → api (se usa EF migrations) ou repo próprio
+   - FRONT → web
+   - MOBILE → mobile
+   - INFRA → todos (cross-repo)
+5. Validar: cada área DEVE mapear para exatamente 1 repo
+
+**Regra**: Se o TRD indica API e Worker como serviços separados, DEVEM ser repos separados.
+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/` 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:
+
+| Seção | Conteúdo | Fonte principal |
+|-------|----------|-----------------|
+| §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 + 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 + 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/ | Análise do agente |
+
+**Regras de geração:**
+1. SDD deve ser **auto-contido** — o coder lê APENAS o SDD + task, nunca PRD/PM
+2. Toda regra/entidade referencia seção do PRD/TRD (rastreabilidade)
+3. Seções não aplicáveis marcadas `N/A — [motivo]` (ex: §6 em setup sem UI)
+4. Contratos de API com JSON schema completo (request, response, erros)
+5. Modelo de dados com tipos exatos, não genéricos (varchar(255), não "string")
+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. 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
+status: "design_done"
+ultima_skill: "/sf-design"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+---
+
+## Saídas
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `sdd.md` | Especificação técnica completa e auto-contida |
+| `projetos.yaml` | (setup) Manifesto de repos — mapeamento serviço → repo → áreas |
+| `docs/*.md` | (setup) 5 docs globais preenchidos do TRD (architecture, domain, conventions, apiContracts, decisions) |
+| `.context.md` | Atualizado: `approved` → `design_done` |
+
+## Pós-condições
+- SDD é fonte única de verdade para implementação
+- Toda informação para implementar está no SDD — nenhuma consulta externa necessária
+- Rastreabilidade: SDD → PRD/TRD → insumos
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| Nome não informado | Parar, mostrar exemplo |
+| Status anterior a extract_done | Parar, sugerir /sf-extract |
+| 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/ 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 |