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

package/templates/.github/instructions/docs.instructions.md

@@ -1,145 +1,147 @@
-# Instruções — Documentação e Specs
-
-> Regras para o agente ao trabalhar com a camada de documentação.
-> Complementa `copilot-instructions.md` com detalhes operacionais.
-
-## Skills e fluxo
-
-O pipeline é executado por skills atômicas, cada uma com seu arquivo em `.github/skills/`:
-
-```
-/sf-start → /sf-extract → /sf-design → /sf-plan → /sf-dev → /sf-merge-docs
-```
-
-Cada skill tem pré-condições, passos e saídas documentados. **Sempre ler a skill antes de executar.**
-
-## Estado da pipeline (`.context.md`)
-
-Cada scope tem um `.context.md` (YAML frontmatter) que controla o fluxo:
-
-```
-not_started → extract_done → approved → design_done → plan_done → dev_in_progress → dev_done → done
-```
-
-- **Apenas skills atualizam** `.context.md` — o usuário nunca edita manualmente
-- **first_run é imutável** após criação (derivado da ausência de `docs/` no momento do `/sf-start`)
-- **Aprovação** acontece no início do `/sf-design` (skill pergunta ao usuário)
-- Antes de executar qualquer skill, verificar status no `.context.md`
-
-## Extração (/sf-extract)
-
-Gera PRD único com bypass automático pra scopes puro-técnicos:
-
-| Flag no PRD | Significado | Fluxo |
-|-------------|-------------|-------|
-| `empty: false` | Insumos têm conteúdo de produto (≥1 RN OU jornada OU tela OU ator) | PRD preenchido normalmente (15 seções) |
-| `empty: true` | Insumos 100% técnicos (stack, schema, infra) | PRD só com Meta + rodapé. SDD consome chunks tech do extract-log direto |
-
-Template: `.github/templates/feature/PRD.template.md`.
-
-### Multi-agent no /sf-extract
-
-| Agente | Modelo | Papel |
-|--------|--------|-------|
-| Reader (1 por arquivo) | Sonnet | Lê e cataloga 1 arquivo por vez, em paralelo |
-| Analyzer | Opus | Categoriza chunks (produto/tech/both), consulta `docs/`, cruza fontes, gera PRD |
-
-### Regras da extração
-
-- Ler TODOS os arquivos em `workspace/Input/{nome}/` (qualquer formato)
-- Chunks categorizados como `produto`, `tech` ou `both` no extract-log
-- Categorias FIXAS do template — não inventar seções novas
-- Regras de negócio com IDs únicos e estáveis (RN-001, RN-002 — nunca renumerar)
-- **Analyzer consulta `docs/` ANTES de marcar ambiguidade** — se resposta já existe em `docs/conventions.md` etc, marca "resolvido em docs/X §Y" e não pergunta
-- Ambiguidades REAIS (não cobertas por docs/) = BLOQUEANTES
-- Nunca INFERIR regra de negócio — se não está explícito, é ambiguidade
-- Contradições entre arquivos → ambiguidade citando ambos
-- Rastreabilidade obrigatória: cada informação aponta pro arquivo fonte
-- Arquivo não identificável → registrar como NÃO IDENTIFICADO no extract-log, gerar ambiguidade
-- Gerar `.extract-log.md` com hash SHA-256 (8 chars) + categorização tech chunks
-
-### Checklist de temas críticos FIXO
-
-8 temas verificados sempre (post-consulta docs/): Autenticação, Autorização/Roles,
-Separação de serviços, Ambientes & deploy, Dados sensíveis/LGPD, Validações de entrada,
-Tratamento de erros, Impacto em dados existentes. Temas não cobertos por insumos nem
-docs/ viram ambiguidades bloqueantes.
-
-### Re-extração
-
-- Compara hashes com `.extract-log.md` existente → NOVO / MODIFICADO / INALTERADO
-- Merge ADITIVO (nunca remove info de arquivos inalterados)
-- Novas regras continuam sequência de IDs (se último era RN-005, próximo é RN-006)
-- Se PRD era `empty: true` e re-extração encontra produto → flip pra `empty: false`
-
-## Design (/sf-design)
-
-1. Verificar aprovação do PRD (perguntar ao usuário)
-2. Verificar ambiguidades — todas com resposta OU marcadas "resolvido em docs/..."
-3. Ler PRD + extract-log (tech chunks) + `docs/` (se existir) + `.github/rules.md`
-4. Detectar `first_run` do `.context.md`
-5. Gerar SDD usando `.github/templates/feature/sdd.template.md`:
-   - **first_run=true**: §Sistema completo + todas as §Área-X aplicáveis + §11 tudo em ADDED
-   - **first_run=false**: §Sistema só onde muda + §Área-X tocadas com GATE=SIM + §11 refletindo impacto
-6. SDD é auto-contido — coder lê APENAS `specs/{nome}/` + task, nada mais
-7. Toda regra referencia seção do PRD (rastreabilidade)
-8. §9 Estratégia de Testes: framework, estrutura, CAs mapeados a testes
-9. §11 Delta Specs obrigatório (mesmo vazio)
-10. Em first_run: `/sf-design` também gera `docs/` (5 arquivos) + `projetos.yaml` a partir do SDD §Sistema
-11. Sempre: gera projeções em `specs/{nome}/` (brief/contracts/scenarios)
-
-## Planejamento (/sf-plan)
-
-1. Ler SDD completo + `docs/` + `.github/rules.md`
-2. Áreas são DINÂMICAS — derivadas dos GATEs do SDD (`areas_tocadas` no `.context.md`)
-3. Gerar `specs/{nome}/tasks.md` usando template de tasks
-4. Tasks em fases sequenciais com prioridade P1/P2/P3 (do PRD §11 Fases de Entrega)
-5. Cada task: ID (AREA-NNN), título, tamanho (S/M/L), arquivos, ref SDD §N, depende, testes
-6. Gerar `Progresso.md` com ordem de execução e paralelismos
-
-## Desenvolvimento (/sf-dev)
-
-### Agents por área (perfis em `.github/agents/`)
-
-| Área | Agente | Stack padrão |
-|------|--------|-------------|
-| DB | DB Coder | PostgreSQL 16 |
-| BACK | Backend Coder | .NET 8 / C# |
-| FRONT | Frontend Coder | React + Fusion |
-| INFRA | Infra Coder | Docker |
-| DOC | Doc Writer | — |
-| Todas | Reviewer | — |
-| Todas | Security Reviewer | — (gate pós-dev) |
-
-### Loop de desenvolvimento
-
-```
-Por task: implement → test unit → fix → lint → commit → review → fix → review (max 3)
-Por fase: integration tests → fix
-Por scope: E2E tests (CAs) → fix → Security Review → /sf-merge-docs automático → dev_done
-```
-
-### Regras
-
-- Implement + testes na mesma task (não separar)
-- Agente selecionado pelo prefixo: BACK-* → Backend Coder
-- Modelo por tamanho: S/M → Sonnet, L → Opus
-- 1 commit por task: `tipo(TASK-ID): descrição`
-- Quality gate validado pelo Reviewer após cada task
-- Limite de retry: 3 reprovações → escalar pro usuário
-- `/sf-merge-docs` automático no final (aplica SDD §11 em `docs/`)
-
-## /sf-start é único
-
-| Aspecto | v3 (atual) |
-|---------|-----------|
-| Comando de entrada | `/sf-start <nome>` (único pra bootstrap E features) |
-| Input | `workspace/Input/<nome>/` (nome livre) |
-| Extração | `PRD.md` (pode ser empty em scopes puro-técnicos) |
-| SDD | Sempre gerado; seções populadas conforme first_run + áreas tocadas |
-| Gera `docs/` | Só em first_run (detectado via ausência de docs/) |
-| `/sf-merge-docs` | Obrigatório após `/sf-dev` (chamado automaticamente) |
-| Pré-requisito | Insumos em `workspace/Input/<nome>/` |
-
-> No v2 existiam `/sf-new-project` (TRD/setup) e `/sf-feature` (PRD/feature) separados.
-> No v3, `/sf-start` detecta automaticamente via presença de `docs/` — mesma entrada, comportamento adaptativo.
+# Instruções — Documentação e Specs
+
+> Regras para o agente ao trabalhar com a camada de documentação.
+> Complementa `copilot-instructions.md` com detalhes operacionais.
+
+## Skills e fluxo
+
+O pipeline é executado por skills atômicas, cada uma com seu arquivo em `.github/skills/`:
+
+```
+/sf-start → /sf-load → /sf-discovery → /sf-extract → /sf-design → /sf-plan → /sf-dev → /sf-merge-docs
+```
+
+Cada skill tem pré-condições, passos e saídas documentados. **Sempre ler a skill antes de executar.**
+
+## Estado da pipeline (`.context.md`)
+
+Cada scope tem um `.context.md` (YAML frontmatter) que controla o fluxo:
+
+```
+not_started → discovery_done → extract_done → prd_approved → trd_approved → design_done → plan_done → dev_in_progress → dev_done → done
+```
+
+- **Apenas skills atualizam** `.context.md` — o usuário nunca edita manualmente
+- **first_run é imutável** após criação (derivado da ausência de `docs/` no momento do `/sf-start`)
+- **Aprovação DUPLA**: PM marca `prd_aprovado=true`, dev marca `trd_aprovado=true` (ambas = pode chamar `/sf-design`)
+- Antes de executar qualquer skill, verificar status no `.context.md`
+
+## Extração (/sf-extract)
+
+Gera **PRD e/ou TRD** conforme o conteúdo dos insumos:
+
+| Cenário | PRD | TRD |
+|---------|-----|-----|
+| first-run de projeto novo (produto + tech) | gerado | gerado |
+| bootstrap de infra (só técnico) | não gerado (`prd_existe=false`) | gerado |
+| feature de UX pura (só produto) | gerado | não gerado (`trd_existe=false`) |
+
+Templates: `.github/templates/feature/PRD.template.md` e `.github/templates/feature/TRD.template.md`.
+
+### Multi-agent no /sf-extract
+
+| Agente | Modelo | Papel |
+|--------|--------|-------|
+| Reader (1 por arquivo) | Sonnet | Lê e cataloga 1 arquivo por vez, em paralelo |
+| Produto-Analyzer | Opus | Consolida conteúdo de produto → gera PRD |
+| Tech-Analyzer | Opus | Consolida conteúdo técnico → gera TRD |
+
+### Regras da extração
+
+- Ler TODOS os arquivos em `workspace/Input/{nome}/` (qualquer formato)
+- Cada Analyzer decide se há conteúdo suficiente pra gerar seu doc
+- Categorias FIXAS dos templates — não inventar seções novas
+- IDs estáveis: RN-NNN (PRD), ADR-NNN (TRD). Nunca renumerar.
+- **Analyzer consulta `docs/` ANTES de marcar ambiguidade** — se resposta já existe em `docs/conventions.md` etc, marca "resolvido em docs/X §Y" e não pergunta
+- Ambiguidades REAIS (não cobertas por docs/) = BLOQUEANTES (§12 no PRD, §10 no TRD)
+- Nunca INFERIR regra de negócio ou decisão técnica — se não está explícito, é ambiguidade
+- Contradições entre arquivos → ambiguidade citando ambos
+- Rastreabilidade obrigatória: cada informação aponta pro arquivo fonte
+- Arquivo não identificável → registrar como NÃO IDENTIFICADO no extract-log, gerar ambiguidade
+- Gerar `.extract-log.md` com hash SHA-256 (8 chars) + destino (qual doc/seção recebeu)
+
+### Checklist de temas críticos FIXO
+
+9 temas verificados sempre (após consulta a docs/): Autenticação, Autorização/Roles,
+Separação de serviços, Ambientes & deploy, Dados sensíveis/LGPD, Validações de entrada,
+Cenários de erro de produto, Impacto em dados existentes, Métricas de sucesso. Temas
+não cobertos por insumos nem docs/ viram ambiguidades bloqueantes — em PRD se é de
+produto, em TRD se é técnico.
+
+### Re-extração
+
+- Compara hashes com `.extract-log.md` existente → NOVO / MODIFICADO / INALTERADO
+- Merge ADITIVO (nunca remove info de arquivos inalterados)
+- Novas regras continuam sequência de IDs (se último era RN-005, próximo é RN-006)
+- Se PRD era inexistente e re-extração encontra produto → cria PRD agora (`prd_existe=true`, `prd_aprovado=false`)
+- Idem para TRD
+
+## Design (/sf-design)
+
+1. Verificar aprovações duplas: `prd_aprovado` (se `prd_existe`) E `trd_aprovado` (se `trd_existe`)
+2. Verificar ambiguidades — todas com resposta OU marcadas "resolvido em docs/..."
+3. Ler PRD + TRD aprovados + `docs/` (se existir) + `.github/rules.md`
+4. Detectar `first_run` do `.context.md`
+5. **first_run=true**: gerar `docs/` (5 arquivos) + `projetos.yaml` a partir do TRD §Sistema
+6. **Sempre**: gerar projeções em `specs/{nome}/` (brief/contracts/scenarios) lendo PRD+TRD
+7. Coder lê APENAS `specs/{nome}/` + task — nunca PRD/TRD direto
+8. `areas_tocadas` preenchido no `.context.md` (dos GATEs do TRD §Área-X)
+
+## Planejamento (/sf-plan)
+
+1. Ler PRD + TRD + `specs/{nome}/` + `docs/` + `.github/rules.md`
+2. Áreas são DINÂMICAS — derivadas dos GATEs do TRD (`areas_tocadas` no `.context.md`)
+3. Gerar `specs/{nome}/tasks.md` usando template de tasks
+4. Tasks em fases sequenciais com prioridade P1/P2/P3 (do PRD §11 Fases de Entrega)
+5. Cada task: ID (AREA-NNN), título, tamanho (S/M/L), arquivos, ref TRD §N, depende, testes
+6. Gerar `Progresso.md` com ordem de execução e paralelismos
+
+## Desenvolvimento (/sf-dev)
+
+### Agents por área (perfis em `.github/agents/`)
+
+| Área | Agente | Stack padrão |
+|------|--------|-------------|
+| DB | DB Coder | PostgreSQL 16 |
+| BACK | Backend Coder | .NET 8 / C# |
+| FRONT | Frontend Coder | React + Fusion |
+| INFRA | Infra Coder | Docker |
+| DOC | Doc Writer | — |
+| Todas | Reviewer | — |
+| Todas | Security Reviewer | — (gate pós-dev) |
+
+### Loop de desenvolvimento
+
+```
+Por task: implement → test unit → fix → lint → commit → review → fix → review (max 3)
+Por fase: integration tests → fix
+Por scope: E2E tests (CAs) → fix → Security Review → /sf-merge-docs automático → dev_done
+```
+
+### Regras
+
+- Implement + testes na mesma task (não separar)
+- Agente selecionado pelo prefixo: BACK-* → Backend Coder
+- Modelo por tamanho: S/M → Sonnet, L → Opus
+- 1 commit por task: `tipo(TASK-ID): descrição`
+- Quality gate validado pelo Reviewer após cada task
+- Limite de retry: 3 reprovações → escalar pro usuário
+- `/sf-merge-docs` automático no final (diff semântico PRD+TRD ↔ docs/)
+
+## /sf-start é único
+
+| Aspecto | v4 (atual) |
+|---------|-----------|
+| Comando de entrada | `/sf-start <nome>` (único pra bootstrap E features) |
+| Input | `workspace/Input/<nome>/` (nome livre) |
+| Discovery | OBRIGATÓRIO — passo do `/sf-start` antes do `/sf-extract` |
+| Extração | `PRD.md` e/ou `TRD.md` (condicional ao conteúdo) |
+| Aprovações | DUPLAS: PM aprova PRD, dev aprova TRD |
+| Design | Gera `specs/{nome}/` sempre; `docs/` + `projetos.yaml` só em first-run |
+| Gera `docs/` | Só em first_run (detectado via ausência de docs/) |
+| `/sf-merge-docs` | Obrigatório após `/sf-dev` (chamado automaticamente) |
+| Pré-requisito | Insumos em `workspace/Input/<nome>/` |
+
+> No v3 existia SDD como doc intermediário entre PRD e specs/. No v4, SDD foi
+> eliminado — `specs/` deriva direto de PRD+TRD aprovados. TRD foi ressuscitado
+> como peer do PRD, aprovado pelo dev.

package/templates/.github/instructions/sensitive-files.instructions.md

@@ -1,32 +1,32 @@
-# Instruções para Arquivos Sensíveis
-
-> Regras especiais para arquivos que requerem cuidado extra.
-
-## Arquivos que NUNCA devem ser modificados pelo agente
-
-- `workspace/Input/**/*` — Insumos brutos do usuário. Somente leitura.
-- `.env`, `.env.*` — Variáveis de ambiente com secrets.
-- `docs/decisions.md` — decisões aceitas são imutáveis (apenas adicionar novas, com status "substituída por ADR-XXX" na original).
-
-## Arquivos que requerem aprovação antes de modificar
-
-- `docs/*` — Documentação global. Só alterar via /merge-docs após /dev.
-- `.github/rules.md` — Regras de desenvolvimento. Alteração deve ser explícita.
-- `.github/copilot-instructions.md` — Meta-regras. Alteração requer aprovação.
-- `.github/skills/*` — Skills do workflow. Alteração requer aprovação.
-- `.github/agents/*` — Perfis de agentes. Alteração requer aprovação.
-
-## Arquivos com formato rígido (gerados por skills)
-
-- `workspace/Output/*/.context.md` — YAML frontmatter, apenas skills atualizam.
-- `workspace/Output/*/.extract-log.md` — Append-only, hashes obrigatórios.
-- `workspace/Output/*/PRD.md` — Seguir template exato (pode ter empty: true em scopes puro-técnicos).
-- `workspace/Output/*/sdd.md` — Seguir template v3, §Sistema + §Área-X gateáveis + §11 Delta Specs obrigatório.
-- `specs/{nome}/tasks.md` — IDs sequenciais, campos obrigatórios (gerado pelo /sf-plan).
-- `workspace/Output/*/Progresso.md` — Tabelas com formato fixo.
-
-## Arquivos que nunca devem conter secrets
-
-- Qualquer arquivo `.md` em docs/
-- `docker-compose.yml` — usar variáveis de ambiente, não valores diretos
-- Código fonte — usar `appsettings.json` + environment variables, não hardcoded
+# Instruções para Arquivos Sensíveis
+
+> Regras especiais para arquivos que requerem cuidado extra.
+
+## Arquivos que NUNCA devem ser modificados pelo agente
+
+- `workspace/Input/**/*` — Insumos brutos do usuário. Somente leitura.
+- `.env`, `.env.*` — Variáveis de ambiente com secrets.
+- `docs/decisions.md` — decisões aceitas são imutáveis (apenas adicionar novas, com status "substituída por ADR-XXX" na original).
+
+## Arquivos que requerem aprovação antes de modificar
+
+- `docs/*` — Documentação global. Só alterar via /merge-docs após /dev.
+- `.github/rules.md` — Regras de desenvolvimento. Alteração deve ser explícita.
+- `.github/copilot-instructions.md` — Meta-regras. Alteração requer aprovação.
+- `.github/skills/*` — Skills do workflow. Alteração requer aprovação.
+- `.github/agents/*` — Perfis de agentes. Alteração requer aprovação.
+
+## Arquivos com formato rígido (gerados por skills)
+
+- `workspace/Output/*/.context.md` — YAML frontmatter, apenas skills atualizam.
+- `workspace/Output/*/.extract-log.md` — Append-only, hashes obrigatórios.
+- `workspace/Output/*/PRD.md` — Seguir template exato (condicional — só se insumos têm produto).
+- `workspace/Output/*/TRD.md` — Seguir template exato, §Sistema + §Área-X gateáveis por área.
+- `specs/{nome}/tasks.md` — IDs sequenciais, campos obrigatórios (gerado pelo /sf-plan).
+- `workspace/Output/*/Progresso.md` — Tabelas com formato fixo.
+
+## Arquivos que nunca devem conter secrets
+
+- Qualquer arquivo `.md` em docs/
+- `docker-compose.yml` — usar variáveis de ambiente, não valores diretos
+- Código fonte — usar `appsettings.json` + environment variables, não hardcoded