spec-first-copilot 0.6.0-beta.9 → 0.7.0

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

@@ -1,216 +1,161 @@
-# /sf-design $ARGUMENTS
-
-Skill atômica de design. Lê PRD aprovado + chunks tech do extract-log e gera SDD.
-`$ARGUMENTS` = nome do scope (ex: `app_barbearia`, `feat_cadastro_cliente`).
-
-Em **first-run** (docs/ ausente): popula SDD §Sistema completo + cria docs/ + projetos.yaml.
-Em **feature** (docs/ existe): popula SDD só das áreas tocadas + §11 Delta Specs pro /sf-merge-docs.
-
-## Agente: Architect (Opus)
-
-Técnico e preciso. Gera contratos completos. Toda decisão tem justificativa.
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | `$ARGUMENTS` informado | Parar |
-| 2 | `.context.md` existe com status `extract_done` ou `approved` | Se anterior → "Rode /sf-extract $ARGUMENTS primeiro". Se posterior → "SDD já gerado" |
-| 3 | `workspace/Output/$ARGUMENTS/PRD.md` existe | Parar → "Rode /sf-extract $ARGUMENTS primeiro" |
-| 4 | `.extract-log.md` existe (pra consumir tech chunks) | Parar → "/sf-extract não gerou extract-log" |
-
-Note: **não validar** presença de `docs/` — ausência é válida (first_run).
-
-## Passos
-
-### 1. Carregar contexto
-
-- `.context.md` → `first_run`, `prd_empty`
-- `workspace/Output/$ARGUMENTS/PRD.md` (pode estar empty)
-- `workspace/Output/$ARGUMENTS/.extract-log.md` → seção "Tech chunks" pra §Sistema e áreas tech
-- `docs/` se existir (feature mode: usa como baseline pra §Sistema; não preenche subseções que não mudam)
-- `workspace/Output/$ARGUMENTS/sf-discovery.md` se existir
-- `.github/rules.md`
-- Template `.github/templates/sf-feature/sdd.template.md`
-
-### 2. Checkpoint de aprovação
-
-Se status é `extract_done`:
-- Perguntar: "O PRD foi revisado e está aprovado? (s/n)"
-  - Se PRD é `empty: true`: perguntar "Os chunks tech do extract-log estão revisados?"
-- Se SIM → atualizar `.context.md` para `approved` → continuar
-- Se NÃO → parar
-
-### 3. Verificar ambiguidades pendentes
-
-- Ler §14 do PRD (Ambiguidades)
-- Filtrar: só as SEM resposta do usuário E SEM marcador "resolvido em docs/..."
-- Se restou alguma → PARAR, listar pendentes em formato:
-
-```
-Ambiguidades pendentes em PRD §14:
-
-  AMB-001: {pergunta}
-  AMB-003: {pergunta}
-
-Como responder:
-  1. Abra workspace/Output/$ARGUMENTS/PRD.md
-  2. Vá até §14 e preencha a coluna `Resposta` em cada linha pendente
-  3. Salve e rode /sf-design $ARGUMENTS de novo
-
-Mais detalhes em .github/skills/sf-extract/SKILL.md → "Como responder ambiguidades".
-```
-
-### 4. Branch first-run vs feature
-
-Ler `first_run` do `.context.md`.
-
-#### Branch A — first_run = true (bootstrap)
-
-SDD §Sistema deve ser preenchido COMPLETO (todas 7 subseções).
-SDD §Área-X: popular todas as áreas aplicáveis (scaffolding inicial baseline).
-§11 Delta Specs: TUDO em ADDED (docs/ nasce a partir daqui).
-
-#### Branch B — first_run = false (feature/incremento)
-
-SDD §Sistema: popular APENAS subseções que esta feature MUDA.
-Se feature não altera stack/arquitetura/etc → marcar §Sistema como "N/A — feature não altera baseline".
-SDD §Área-X: popular apenas áreas tocadas (GATE=SIM); resto marca N/A.
-§11 Delta Specs: ADDED/MODIFIED/REMOVED refletindo impacto cross-feature.
-
-### 5. Gerar SDD
-
-Usar template `.github/templates/sf-feature/sdd.template.md`:
-
-**Meta**: preencher `first_run`, `PRD empty`, `áreas tocadas`.
-
-**Seções obrigatórias** (seguir template v3):
-- §1 Visão Geral — escopo claro
-- §2 Decisões de Design — mini-ADRs com justificativa + origem (PRD §X ou extract-log §Y)
-- §3 §Sistema — 7 subseções gateáveis (ver Branch A/B)
-- §4 §Área-Backend — com GATE SIM/NÃO
-- §5 §Área-Frontend — com GATE SIM/NÃO
-- §6 §Área-DB — com GATE SIM/NÃO
-- §7 §Área-Infra — com GATE SIM/NÃO
-- §8 Fluxos de Dados cross-area
-- §9 Estratégia de Testes (áreas tocadas)
-- §10 Fora de Escopo
-- §11 Delta Specs — ADDED/MODIFIED/REMOVED (OBRIGATÓRIO, mesmo vazio)
-- §12 Ambiguidades Pendentes (com coluna "Consultei docs/?")
-- Rastreabilidade PRD → SDD + extract-log chunks → SDD
-
-**Regra auth em endpoints**: todo endpoint em §4.1 DEVE ter Autenticação e Autorização explícitas.
-Se não coberto pelo PRD → consultar `docs/conventions.md §Autenticação`.
-Se ausente → ambiguidade em §12.
-
-### 6. Gerar `docs/` (APENAS first_run)
-
-> Este passo SÓ executa quando `first_run = true`.
-
-Ler SDD §Sistema e popular 5 arquivos em `docs/` usando os templates de `.github/templates/estrutura/`:
-
-| Doc gerado | Fontes (SDD) |
-|-----------|--------------|
-| `architecture.md` | §3.1 Stack + §3.2 Arquitetura + §3.3 Ambientes + §3.4 Infra |
-| `domain.md` | PRD §1+§2+§8 (se não-empty) + SDD §6 §Área-DB + §3.2 |
-| `conventions.md` | §3.5 Segurança + §3.4 Infra (env vars) + §3.6 API + §3.7 Monitoring |
-| `apiContracts.md` | §3.6 Convenções de API + §4.1 Endpoints (se first-run tem) |
-| `decisions.md` | §2 Decisões de Design (transcrever como ADR-001, ADR-002...) |
-
-Regras:
-- Ler template → preencher TODAS as seções com dados do SDD
-- Remover bloco `<!-- INSTRUÇÕES -->` do doc gerado
-- Changelog inicia vazio
-- Se SDD não tem dados pra uma seção → marcar "A definir"
-- `decisions.md` é preenchido com ADRs extraídos do SDD §2
-
-### 7. Gerar `projetos.yaml` (APENAS first_run)
-
-Mapeia arquitetura do SDD §3.2 pra repositórios independentes.
-Cada serviço = 1 repo. Repos serão criados/clonados pelo `/sf-dev` (INFRA-001).
-
-1. Identificar serviços separados no SDD §3.2 Containers (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 (pra clonar em vez de criar)
-3. Gerar `projetos.yaml` na raiz usando template `.github/templates/sf-feature/projetos.template.yaml`
-4. Mapear áreas de task para repos:
-   - BACK → api (ou worker, se separado)
-   - DB → api (se usa migrations) ou repo próprio
-   - FRONT → web
-   - INFRA → todos (cross-repo)
-5. Validar: cada área DEVE mapear pra exatamente 1 repo
-
-**Regra**: Se SDD define API e Worker como containers separados, DEVEM ser repos separados. Nunca juntar serviços que o SDD definiu como distintos.
-
-### 8. Projetar SDD em `specs/$ARGUMENTS/` (sempre)
-
-Após gerar/atualizar o SDD, criar/sobrescrever os 4 arquivos em `specs/$ARGUMENTS/`
-como projeções pro coder agent consumir:
-
-| Arquivo | Projeção de | Inclui |
-|---------|-------------|--------|
-| `brief.md` | SDD §1 + §2 + §10 | Problema, Solução, Serviços tocados (de projetos.yaml), Escopo, Decisões |
-| `contracts.md` | SDD §3 + §4 + §5 + §6 + §7 (§Sistema + áreas tocadas) | Dados (schema/constraints), Validações de Entrada (separadas de RN), API, Integrações, RN com enforcement point |
-| `scenarios.md` | SDD §5.2 + §8 + §9 (fluxos + CAs) | Pré-condições de estado, Fluxos happy path, Fluxos de erro (seção própria), UI por componente, CAs com Pré-condição + Given/When/Then + Teste |
-| `tasks.md` | stub (preenchido pelo `/sf-plan`) | — |
-
-Regras:
-- Projeções são REGENERÁVEIS — ao re-rodar `/sf-design`, sobrescreve
-- NUNCA editar direto em `specs/` — SDD é a fonte
-- Templates em `.github/templates/specs/`
-- Coders e Reviewer leem daqui, NUNCA do SDD direto
-
-### 9. Atualizar `.context.md`
-
-```yaml
-status: "design_done"
-areas_tocadas: [BACK, DB]   # derivado dos GATEs do SDD
-ultima_skill: "/sf-design"
-atualizado_em: "{{ISO_DATETIME}}"
-```
-
-### 10. Publicar SDD no backend (OBRIGATÓRIO quando config existe)
-
-**Este passo NÃO é opcional**. Tomar decisão baseada em arquivo:
-
-| Detecção | Ação |
-|----------|------|
-| `sfw.config.yml` NÃO existe | Pular silenciosamente. Registrar no output: "publish: skipped (no sfw.config.yml)" |
-| `sfw.config.yml` existe | **Chamar `/sf-publish $ARGUMENTS SDD`** — sem condicional. Execute. |
-
-`/sf-publish` respeita `mode` de cada target. Ver `.github/skills/sf-publish/SKILL.md`.
-
-### 11. Saída obrigatória
-
-Antes de terminar, a skill DEVE reportar:
-
-```
-/sf-design $ARGUMENTS — completo (first_run={true|false})
-
-Artefatos locais:
-  - workspace/Output/$ARGUMENTS/sdd.md
-  - specs/$ARGUMENTS/{brief,contracts,scenarios}.md
-  {se first_run: + docs/*.md (5 arquivos) + projetos.yaml}
-
-Áreas tocadas: [{lista do Meta do SDD}]
-
-Publish:
-  - {target-name}: {CREATED|UPDATED|SKIPPED|CONFLICT|ERROR} — ver .ai/sf-publish-log.md
-  OU
-  - SKIPPED (no sfw.config.yml)
-
-Próximo passo:
-  /sf-plan $ARGUMENTS   ← gerar tasks por área
-```
-
-Se `/sf-publish` retornou ERROR, a skill NÃO falha — artefato local está salvo.
-
-## Notas
-
-- **first_run é imutável** — vem do `.context.md` criado pelo `/sf-start`
-- Em first_run, `docs/` é criado **depois** do SDD (passo 6) — SDD §3 §Sistema é a fonte
-- `projetos.yaml` é gerado uma única vez (first_run) — features podem atualizá-lo se adicionarem novo serviço (via `/sf-merge-docs`? ou edição manual — decidir se virar dor)
-- `/sf-merge-docs` é chamado automaticamente pelo `/sf-dev` ao final (não aqui)
-- Se user re-roda `/sf-design` numa feature após `/sf-merge-docs`, o `docs/` pode ter info nova que entra como baseline consulting (loop de refino)
+
+# /sf-design $ARGUMENTS
+
+Skill atômica de design. Consome PRD + TRD aprovados e gera **`docs/` + `specs/{nome}/` + `projetos.yaml`** (este último em first-run).
+`$ARGUMENTS` = nome do scope (ex: `app_barbearia`, `feat_cadastro_cliente`).
+
+Em **first-run** (docs/ ausente): cria docs/ a partir do PRD+TRD + projetos.yaml + specs/.
+Em **feature** (docs/ existe): não cria docs/ (vem pelo /sf-merge-docs depois do /sf-dev) + gera apenas specs/ do scope atual.
+
+## Agente: Architect (Opus)
+
+Técnico e preciso. Deriva projeções a partir dos docs source sem reinventar decisões.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `$ARGUMENTS` informado | Parar |
+| 2 | `.context.md` existe com status `extract_done` ou posterior | Se anterior → "/sf-extract $ARGUMENTS primeiro" |
+| 3 | Se `prd_existe=true`: `PRD.md` existe E `prd_aprovado=true` | Parar, listar ambiguidades pendentes (ver bloco abaixo) |
+| 4 | Se `trd_existe=true`: `TRD.md` existe E `trd_aprovado=true` | Parar, listar ambiguidades pendentes |
+| 5 | Pelo menos um dos 2 existe e está aprovado | Parar → "Extração falhou — nenhum doc aprovado" |
+
+Quando parar por ambiguidade:
+
+```
+Ambiguidades pendentes em PRD §12 / TRD §10:
+
+  AMB-PRD-001: {pergunta}
+  AMB-TRD-002: {pergunta}
+
+Como responder:
+  1. Abra workspace/Output/$ARGUMENTS/PRD.md (ou TRD.md)
+  2. Vá até §Ambiguidades e preencha a coluna `Resposta`
+  3. Marque prd_aprovado=true (ou trd_aprovado=true) em .context.md
+  4. Rode /sf-design $ARGUMENTS de novo
+
+Mais detalhes em .github/skills/sf-extract/SKILL.md → "Como responder ambiguidades".
+```
+
+## Passos
+
+### 1. Carregar contexto
+
+- `.context.md` → `first_run`, `prd_existe`, `trd_existe`, `areas_tocadas` (vazio, vai popular)
+- `workspace/Output/$ARGUMENTS/PRD.md` (se `prd_existe=true`)
+- `workspace/Output/$ARGUMENTS/TRD.md` (se `trd_existe=true`)
+- `docs/` (se existir — feature mode): baseline cross-feature
+- `discovery.md` (se existir): análise prévia
+- `.github/rules.md`
+- Templates:
+  - `.github/templates/specs/{brief,contracts,scenarios}.template.md`
+  - `.github/templates/estrutura/*.template.md` (só se first-run)
+  - `.github/templates/feature/projetos.template.yaml` (só se first-run)
+
+### 2. Determinar áreas tocadas
+
+Ler GATEs do TRD §2-§5 (se TRD existe). Áreas marcadas como `GATE: SIM` vão pra
+`.context.md → areas_tocadas: [...]`.
+
+Se TRD não existe (scope puro-produto, raro): `areas_tocadas = []`; `/sf-plan` vai
+gerar só tasks de frontend com base no PRD §7.
+
+### 3. Branch first-run vs feature
+
+Ler `first_run` do `.context.md`.
+
+#### Branch A — first_run = true (bootstrap)
+
+1. **Gerar `docs/`** (5 arquivos em `docs/` na raiz do projeto):
+
+   | Doc gerado | Fontes |
+   |-----------|--------|
+   | `architecture.md` | TRD §1.1 Stack + §1.2 Arquitetura + §1.3 Ambientes + §1.4 Deploy + §5 §Área-Infra |
+   | `domain.md` | PRD §1 Contexto + §2 Atores + §3 Jornadas (resumo) + TRD §4 §Área-DB |
+   | `conventions.md` | TRD §1.5 Segurança baseline + §7 Segurança detalhada + §5.3 Env vars + §5.4 Monitoramento |
+   | `apiContracts.md` | TRD §2.1 Endpoints + convenções de rota inferidas |
+   | `decisions.md` | TRD §9 ADRs (transcritas como ADR-001, ADR-002... imutáveis) |
+
+   Regras:
+   - Ler template → preencher TODAS as seções com dados do PRD/TRD
+   - Remover bloco `<!-- INSTRUÇÕES -->` do doc gerado
+   - Changelog inicia vazio
+   - Se PRD ou TRD não tem dados pra uma seção → "A definir" (não deixar vazio)
+
+2. **Gerar `projetos.yaml`** na raiz:
+
+   - Identificar serviços separados no TRD §1.2 Containers (api, worker, web, etc.)
+   - Perguntar ao usuário: organização GitHub, nome base, se algum repo já existe
+   - Mapear áreas → repos (API+DB costumam ir juntos; Frontend separado)
+   - Validar: cada área em `areas_tocadas` tem repo correspondente
+
+3. **Gerar `specs/$ARGUMENTS/`** (passo 4 abaixo, comum a first-run e feature)
+
+#### Branch B — first_run = false (feature)
+
+1. **Não toca em `docs/`** (isso é trabalho do /sf-merge-docs após /sf-dev)
+2. **Não gera `projetos.yaml`** (já existe do first-run)
+3. **Gera apenas `specs/$ARGUMENTS/`**
+
+### 4. Gerar `specs/$ARGUMENTS/` (sempre)
+
+Criar/sobrescrever os 4 arquivos em `specs/$ARGUMENTS/`:
+
+| Arquivo | Projeção de | Conteúdo |
+|---------|-------------|----------|
+| `brief.md` | PRD §1 + §10 + §11 + TRD §1 | Problema, Solução, Serviços tocados (de projetos.yaml), Escopo (Dentro/Fora), Decisões principais (ADRs resumidas) |
+| `contracts.md` | TRD §4 + §2.3 + §2.1 + §6 + PRD §5 | Dados (schema), Validações de Entrada, API (endpoints específicos), Integrações externas, Regras de Negócio com enforcement point |
+| `scenarios.md` | PRD §3 + §8 + §7 + TRD §8 | Pré-condições globais, Fluxos happy path, Fluxos de erro (com Ref CA), UI por componente, CAs com Given/When/Then, Estratégia de testes |
+| `tasks.md` | stub | (preenchido pelo `/sf-plan`) |
+
+Regras:
+- Projeções são **REGENERÁVEIS** — ao re-rodar `/sf-design`, sobrescreve
+- NUNCA editar direto em `specs/` — PRD/TRD são as fontes
+- Templates em `.github/templates/specs/`
+- Coders e Reviewer leem daqui, NUNCA de PRD/TRD direto
+
+### 5. Validação de consistência
+
+Antes de terminar, verificar:
+- Cada RN do PRD §5 aparece em `contracts.md → Regras de Negócio` com enforcement point
+- Cada endpoint do TRD §2.1 aparece em `contracts.md → API`
+- Cada CA em `scenarios.md` mapeia pra pelo menos 1 RN ou 1 jornada
+- Áreas em `areas_tocadas` têm entries em `contracts.md` e `scenarios.md`
+
+Divergências → alertar no output, sem falhar.
+
+### 6. Atualizar `.context.md`
+
+```yaml
+status: "design_done"
+areas_tocadas: [BACK, DB, ...]   # derivado do passo 2
+ultima_skill: "/sf-design"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+### 7. Saída obrigatória
+
+```
+/sf-design $ARGUMENTS — completo ({{first-run | feature}})
+
+Artefatos:
+  - specs/$ARGUMENTS/brief.md
+  - specs/$ARGUMENTS/contracts.md
+  - specs/$ARGUMENTS/scenarios.md
+  - specs/$ARGUMENTS/tasks.md (stub — será preenchido por /sf-plan)
+  (se first-run:)
+  - docs/architecture.md, domain.md, conventions.md, apiContracts.md, decisions.md
+  - projetos.yaml
+
+Áreas tocadas: [BACK, DB, FRONT, INFRA]
+Validação: {{N issues / passed}}
+
+Próximo passo: /sf-plan $ARGUMENTS
+```
+
+## Regra de ouro
+
+- `/sf-design` NUNCA reinventa decisões. Apenas projeta PRD+TRD pra formatos consumíveis.
+- Se precisa de uma decisão nova que não está no PRD ou TRD: é ambiguidade — voltar pra `/sf-extract` com novo insumo.
+- Divergências entre PRD e TRD: **PRD vence em produto, TRD vence em técnica** (não há overlap por design).