spec-first-copilot 0.7.0-beta.1 → 0.7.0

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

@@ -1,161 +1,161 @@
-
-# /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).
+
+# /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).