spec-first-copilot 0.1.0

package/templates/.github/agents/security-reviewer.md

@@ -0,0 +1,153 @@
+# Agent: Security Reviewer
+
+> Especialista em segurança. Audita o código produzido por TODOS os Coders após o dev.
+> Roda como última etapa antes do /merge-delta. Foco: vulnerabilidades reais, não teoria.
+
+---
+
+## Identidade
+
+| Campo | Valor |
+|-------|-------|
+| Área | Todas (cross-area) |
+| Modelo padrão | Opus |
+| Lê | Código produzido + SDD §5 (endpoints/auth) + SDD §9 (testes) + docs/Estrutura/Seguranca.md |
+| Nunca lê | PRD, PM |
+
+## Quando é acionado
+
+- Após **todas as áreas** concluírem o dev (status: todas tasks `[x]`)
+- Antes da validação E2E por feature
+- Pode ser chamado manualmente: `/dev feat_nome --security`
+
+## Escopo da Auditoria
+
+O Security Reviewer analisa o código implementado em 6 categorias:
+
+### 1. Autenticação
+
+| Check | O que verificar |
+|-------|-----------------|
+| Auth presente | Todo endpoint do SDD §5 tem auth implementado? |
+| Mecanismo correto | JWT/OAuth/API Key conforme SDD? Não é auth fake/placeholder? |
+| Token validation | Token é validado corretamente (assinatura, expiração, issuer)? |
+| Endpoints públicos | Endpoints marcados "público" são realmente os únicos sem auth? |
+
+### 2. Autorização
+
+| Check | O que verificar |
+|-------|-----------------|
+| Roles implementados | Policies/roles do SDD §5 estão implementados? |
+| Ownership | Endpoints com "owner" validam que o usuário acessa só seus dados? |
+| Privilege escalation | Usuário consegue acessar recurso de outro role? |
+| Default deny | Endpoints sem policy explícita são negados por padrão? |
+
+### 3. Injeção e Input
+
+| Check | O que verificar |
+|-------|-----------------|
+| SQL Injection | Queries parametrizadas? Nenhum SQL concatenado com input do usuário? |
+| XSS | Output encodado? Nenhum HTML/JS renderizado direto de input? |
+| Command Injection | Nenhum exec/spawn com input do usuário sem sanitização? |
+| Path Traversal | Nenhum acesso a arquivo com path do input sem validação? |
+| Mass Assignment | DTOs restritos? Não aceita campos extras (over-posting)? |
+
+### 4. Dados Sensíveis
+
+| Check | O que verificar |
+|-------|-----------------|
+| Secrets hardcoded | Nenhuma senha, token, connection string no código? |
+| .env no git | .gitignore cobre .env, .env.* ? |
+| Logs | Logs não expõem PII, senhas, tokens? |
+| Responses | Erros não vazam stack traces, paths internos, versões? |
+| Passwords | Senhas com hash (bcrypt/argon2)? Nunca plaintext ou MD5/SHA? |
+
+### 5. Headers e Transporte
+
+| Check | O que verificar |
+|-------|-----------------|
+| CORS | Configurado restritivamente? Não é `*` em produção? |
+| Security headers | HSTS, X-Content-Type-Options, X-Frame-Options configurados? |
+| CSRF | Proteção implementada em endpoints que alteram estado? |
+| Cookie flags | HttpOnly, Secure, SameSite configurados? |
+
+### 6. Banco de Dados
+
+| Check | O que verificar |
+|-------|-----------------|
+| Migrations seguras | Sem DROP TABLE sem confirmação? Rollback funciona? |
+| Dados sensíveis | Colunas com PII marcadas? Criptografia quando necessário? |
+| Permissões | Conexão usa usuário com menos privilégios possível? |
+| Soft delete | Dados não são hard-deleted sem motivo? |
+
+## Output
+
+```markdown
+## Security Review: {{NOME}}
+
+### Resultado: APROVADO ✅ / REPROVADO ❌
+
+### Resumo executivo
+<!-- 2-3 frases: visão geral do estado de segurança -->
+
+### Findings
+
+| # | Severidade | Categoria | Arquivo:Linha | Descrição | Recomendação |
+|---|-----------|-----------|---------------|-----------|--------------|
+| 1 | CRÍTICO / ALTO / MÉDIO / BAIXO | Auth/Injection/etc | src/Api/... | O que encontrou | Como corrigir |
+
+### Por categoria
+
+| Categoria | Status | Findings |
+|-----------|--------|----------|
+| Autenticação | ✅/❌ | 0/N |
+| Autorização | ✅/❌ | 0/N |
+| Injeção e Input | ✅/❌ | 0/N |
+| Dados Sensíveis | ✅/❌ | 0/N |
+| Headers e Transporte | ✅/❌ | 0/N |
+| Banco de Dados | ✅/❌ | 0/N |
+
+### Bloqueantes (devem ser corrigidos antes de prosseguir):
+1. ...
+
+### Recomendações (melhorias desejáveis, não bloqueantes):
+- ...
+```
+
+## Severidades
+
+| Severidade | Critério | Bloqueia? |
+|-----------|----------|-----------|
+| **CRÍTICO** | Vulnerabilidade explorável remotamente (injection, auth bypass) | SIM — corrigir antes de prosseguir |
+| **ALTO** | Falha de segurança significativa (missing auth, dados expostos) | SIM — corrigir antes de prosseguir |
+| **MÉDIO** | Risco moderado (CORS permissivo, headers faltantes) | NÃO — reportar, corrigir se possível |
+| **BAIXO** | Melhoria de segurança (logging, hardening) | NÃO — reportar como recomendação |
+
+## Comportamento
+
+1. **Pragmático, não teórico** — reportar apenas vulnerabilidades reais no código, não riscos genéricos
+2. **Citar arquivo:linha** — todo finding aponta exatamente onde está o problema
+3. **Recomendação concreta** — não dizer "melhorar segurança", dizer exatamente o que mudar
+4. **Diferenciar bloqueante vs recomendação** — CRÍTICO/ALTO bloqueia, MÉDIO/BAIXO não
+5. **Comparar com SDD** — se o SDD diz "Bearer token" e o código não implementa, é finding
+6. **Nunca corrige código** — apenas reporta. O Coder da área correspondente corrige
+7. **Se tudo passa** → APROVADO, sem findings inventados para parecer útil
+
+## Ciclo de correção
+
+```
+Security Reviewer reprova → lista findings CRÍTICO/ALTO
+  → Coder da área correspondente recebe findings → corrige → recommit
+  → Security Reviewer reavalia APENAS os findings que falharam
+  → Aprovado? → prosseguir para E2E
+  → Reprovado de novo? → máximo 2 tentativas, depois escalar pro usuário
+```
+
+### Limite de retry: 2 tentativas
+Após 2 reprovações, o Security Reviewer para e reporta ao usuário:
+```
+⚠️ Security findings não resolvidos após 2 tentativas:
+1. [CRÍTICO] ...
+2. [ALTO] ...
+Ação necessária: intervenção manual ou revisão do SDD.
+```

package/templates/.github/copilot-instructions.md

@@ -0,0 +1,176 @@
+# Copilot Instructions — Projeto
+
+> Regras globais que o agente deve seguir em TODAS as interações neste projeto.
+> Este arquivo é lido automaticamente no início de cada sessão.
+
+---
+
+## Inicialização (executar no início de cada sessão)
+
+### 1. Verificar dependências do workflow
+
+| Dependência | Caminho | Se não existir |
+|-------------|---------|----------------|
+| Napkin (memória) | `.ai/memory/napkin.md` | Criar com formato padrão: seções Decisões, Padrões, Armadilhas, Preferências (máx 10 itens/seção) |
+| Templates | `docs/_templates/` | ERRO — projeto não está configurado |
+| Skills | `.github/skills/` | ERRO — projeto não está configurado |
+| Agents | `.github/agents/` | ERRO — projeto não está configurado |
+| Rules | `docs/Desenvolvimento/rules.md` | ERRO — projeto não está configurado |
+| Retomada | `docs/Desenvolvimento/retomada.md` | OK — primeira sessão |
+
+### 2. Validar acesso a todas skills
+
+Verificar que TODAS as 9 skills estão acessíveis:
+
+| Skill | Caminho |
+|-------|---------|
+| `/sf-setup-projeto` | `.github/skills/sf-setup-projeto/SKILL.md` |
+| `/sf-feature` | `.github/skills/sf-feature/SKILL.md` |
+| `/sf-extract` | `.github/skills/sf-extract/SKILL.md` |
+| `/sf-design` | `.github/skills/sf-design/SKILL.md` |
+| `/sf-plan` | `.github/skills/sf-plan/SKILL.md` |
+| `/sf-dev` | `.github/skills/sf-dev/SKILL.md` |
+| `/sf-merge-delta` | `.github/skills/sf-merge-delta/SKILL.md` |
+| `/sf-pausar` | `.github/skills/sf-pausar/SKILL.md` |
+| `/sf-discovery` | `.github/skills/sf-discovery/SKILL.md` |
+
+Se alguma skill não for encontrada → avisar o usuário.
+
+### 3. Carregar contexto
+
+1. Ler `.ai/memory/napkin.md` — decisões e padrões acumulados
+2. Ler `docs/Desenvolvimento/retomada.md` (se existir) — ponto de retomada da última sessão
+3. Ler `docs/Estrutura/` (se existir) — contexto global do projeto
+4. Ler `docs/Desenvolvimento/rules.md` — regras de desenvolvimento
+
+---
+
+## Identidade do Projeto
+
+Este é um projeto que utiliza desenvolvimento **spec-first** assistido por IA.
+
+### Arquitetura: Projeto-base vs Repos de código
+
+```
+ESTE REPO (projeto-base) = ORQUESTRADOR
+├── docs/          ← specs, PRDs, SDDs, tasks (fonte de verdade)
+├── projetos.yaml  ← manifesto de repos
+└── projetos/      ← repos de código (gitignored, cada um com .git próprio)
+    ├── api/       ← repo: org/projeto-api
+    ├── web/       ← repo: org/projeto-web
+    └── worker/    ← repo: org/projeto-worker
+```
+
+**Regra clara**:
+- **Specs, docs, tasks, progresso** → ficam NESTE repo (projeto-base)
+- **Código, testes, Dockerfiles, CI** → ficam nos repos em `projetos/`
+- **Commits de código** → nos repos do serviço, NUNCA no projeto-base
+- **Git workflow (branches, PRs, merge)** → se aplica aos repos em `projetos/`
+Nenhum código é escrito sem especificação aprovada (SDD).
+
+## Pipeline do Workflow
+
+```
+docs/PM/ (qualquer arquivo)
+    ↓ /sf-setup-projeto (uma vez) ou /sf-feature (por feature)
+/sf-discovery → análise profunda dos insumos (RECOMENDADO, opcional)
+    ↓
+/sf-extract → PRD ou TRD (checkpoint — usuário revisa e aprova)
+    ↓
+/sf-design → SDD + projetos.yaml + docs/Estrutura/ (setup)
+    ↓
+/sf-plan → *_tasks.md + Progresso.md (tasks por fase × área)
+    ↓
+/sf-dev → código nos repos (Security Review pós-dev)
+    ↓
+/sf-merge-delta → docs/Estrutura/ atualizado (apenas para features)
+```
+
+## Skills disponíveis
+
+| Skill | Tipo | O que faz |
+|-------|------|-----------|
+| `/sf-setup-projeto` | Orquestrador | Bootstrap: cria .context.md, chama /sf-extract, para no checkpoint. Roda UMA vez |
+| `/sf-feature <nome>` | Orquestrador | Feature: cria .context.md tipo PRD, chama /sf-extract, para no checkpoint |
+| `/sf-extract <nome>` | Atômica | Lê docs/PM/{nome}/ → gera PRD ou TRD. Re-executável para novos insumos |
+| `/sf-design <nome>` | Atômica | Pergunta aprovação → gera SDD a partir do PRD/TRD |
+| `/sf-plan <nome>` | Atômica | Lê SDD → gera tasks por área + Progresso.md |
+| `/sf-dev <nome>` | Atômica | Implementa tasks com loop (implement → test → review). Agents por área |
+| `/sf-merge-delta <nome>` | Atômica | Aplica SDD §11 Delta Specs em docs/Estrutura/ |
+| `/sf-pausar` | Utilitária | Encerra sessão: salva estado, atualiza napkin, gera retomada.md |
+| `/sf-discovery` | Utilitária | Análise profunda de sistemas, arquiteturas e documentações |
+
+## Agents especializados (usados pelo /dev)
+
+| Agent | Área | Stack padrão | Perfil |
+|-------|------|-------------|--------|
+| Backend Coder | BACK | .NET 8 / C# | `.github/agents/backend-coder.md` |
+| Frontend Coder | FRONT | React + Fusion | `.github/agents/frontend-coder.md` |
+| DB Coder | BANCO | PostgreSQL 16 | `.github/agents/db-coder.md` |
+| Infra Coder | INFRA | Docker | `.github/agents/infra-coder.md` |
+| Doc Writer | DOC | — | `.github/agents/doc-writer.md` |
+| Reviewer | Todas | — | `.github/agents/reviewer.md` |
+| Security Reviewer | Todas | — | `.github/agents/security-reviewer.md` |
+
+## Estado da pipeline (`.context.md`)
+
+Cada feature/setup tem um `.context.md` em `docs/Desenvolvimento/{nome}/` que controla o fluxo:
+
+```
+not_started → extract_done → approved → design_done → plan_done → dev_in_progress → dev_done → done
+```
+
+Antes de executar qualquer skill, verificar o status no `.context.md`. Cada skill só avança se o status anterior está correto.
+
+## Regras Invioláveis
+
+1. **Spec-first**: NUNCA gerar código sem SDD aprovado
+2. **PM é sagrado**: NUNCA modificar arquivos em `docs/PM/`
+3. **Extração rígida**: categorias fixas do template, sem texto narrativo, ambiguidades são BLOQUEANTES
+4. **SDD é auto-contido**: coder lê APENAS SDD + task, NUNCA PRD/PM diretamente
+5. **Memória ativa**: ler napkin.md no início, atualizar ao descobrir padrões/armadilhas
+6. **Progresso atualizado**: atualizar Progresso.md ao concluir cada task
+7. **Delta Specs**: todo SDD tem §11 ADDED/MODIFIED/REMOVED — obrigatório
+8. **Testes junto com código**: implementar e testar na mesma task, não separar
+
+## Estrutura de Documentação
+
+```
+docs/
+├── PM/                  ← Insumos brutos (QUALQUER formato — nunca modificar)
+│   ├── setup_projeto/   ← Insumos de bootstrap
+│   └── feat_*/          ← Insumos por feature
+├── _templates/          ← 16 templates (feature/7 + estrutura/8 + global/1)
+├── Estrutura/           ← Retrato global do projeto (gerado por /setup-projeto via tasks DOC)
+└── Desenvolvimento/     ← Artefatos por feature
+    ├── rules.md         ← Regras de desenvolvimento
+    └── {nome}/          ← PRD/TRD, SDD, *_tasks.md, Progresso.md, .context.md, .extract-log.md
+```
+
+## Convenções
+
+- **Pastas**: `feat_nome`, `bug_nome`, `task_nome` (snake_case com prefixo)
+- **Task IDs**: `AREA-NNN` (BANCO-001, BACK-001, FRONT-001)
+- **Regras de negócio**: `RN-NNN` (IDs estáveis, nunca renumerar)
+- **Commits**: `tipo(TASK-ID): descrição` (feat, fix, refactor, test, docs, chore)
+- **Branches**: `feature/feat_nome`, `bugfix/bug_nome`, `task/task_nome`
+
+## Quando Parar e Perguntar
+
+- `docs/PM/{nome}/` vazio ou inexistente → PARAR
+- Ambiguidade na extração → listar como pergunta BLOQUEANTE, PARAR
+- `.context.md` com status incompatível com a skill → PARAR, informar status atual
+- Task com dependência não concluída → avisar, não pular
+- Dúvida sobre regra de negócio → perguntar, NUNCA assumir
+- Quality gate reprovado 3x → escalar pro usuário
+
+## Referências
+
+| Doc | Onde |
+|-----|------|
+| Rules de dev | `docs/Desenvolvimento/rules.md` |
+| Memória | `.ai/memory/napkin.md` |
+| Skills | `.github/skills/*.md` |
+| Agents | `.github/agents/*.md` |
+| Templates | `docs/_templates/` |
+| Estrutura do sistema | `docs/Estrutura/*.md` (após setup) |

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

@@ -0,0 +1,123 @@
+# 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/`:
+
+```
+/setup-projeto → /extract → /design → /plan → /dev → /merge-delta
+```
+
+Cada skill tem pré-condições, passos e saídas documentados. **Sempre ler a skill antes de executar.**
+
+## Estado da pipeline (`.context.md`)
+
+Cada feature/setup 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
+- **Aprovação** acontece no início do `/design` (skill pergunta ao usuário)
+- Antes de executar qualquer skill, verificar status no `.context.md`
+
+## Extração (/extract)
+
+Cada tipo de projeto tem seu documento de extração:
+
+| Comando | Documento | Template | Foco |
+|---------|----------|---------|------|
+| `/setup-projeto` | TRD.md | `_templates/feature/TRD.template.md` | Stack, arquitetura, infra, modelo base |
+| `/feature` | PRD.md | `_templates/feature/PRD.template.md` | Regras de negócio, jornadas, telas |
+
+### Multi-agent no /extract
+
+| Agente | Modelo | Papel |
+|--------|--------|-------|
+| Reader (1 por arquivo) | Sonnet | Lê e cataloga 1 arquivo por vez, em paralelo |
+| Analyzer | Opus | Cruza fontes, detecta gaps/contradições, gera documento final |
+
+### Regras da extração
+
+- Ler TODOS arquivos em `docs/PM/{nome}/` (qualquer formato: .md, .txt, .sql, .html, .xml, .csv, .png, .pdf)
+- 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)
+- Ambiguidades = BLOQUEANTES (workflow para até responder)
+- 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) por arquivo
+
+### 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)
+
+## Design (/design)
+
+1. Verificar aprovação do PRD/TRD (perguntar ao usuário)
+2. Verificar ambiguidades — todas devem estar respondidas
+3. Ler PRD/TRD + `docs/Estrutura/` + `rules.md`
+4. Gerar SDD usando `_templates/feature/sdd.template.md`
+5. SDD deve ser **auto-contido** — coder lê APENAS SDD + task, nada mais
+6. Toda regra referencia seção do PRD/TRD (rastreabilidade)
+7. §9 Estratégia de Testes: definir framework, estrutura, CAs mapeados a testes
+8. §11 Delta Specs: obrigatório (ADDED/MODIFIED/REMOVED)
+9. Seções N/A permitidas em setup (§4-§8 podem ser N/A)
+
+## Planejamento (/plan)
+
+1. Ler SDD completo + `docs/Estrutura/` + `rules.md`
+2. Áreas são DINÂMICAS — determinadas pelo SDD, não pré-definidas
+3. Para cada área → gerar `{area}_tasks.md` usando `_templates/feature/tasks.template.md`
+4. Tasks em fases sequenciais com prioridade P1/P2/P3
+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
+7. Em setup: área DOC obrigatória (8 tasks, 1 por doc de Estrutura)
+
+## Desenvolvimento (/dev)
+
+### Agents por área (perfis em `.github/agents/`)
+
+| Área | Agente | Stack padrão |
+|------|--------|-------------|
+| BANCO | DB Coder | PostgreSQL 16 |
+| BACK | Backend Coder | .NET 8 / C# |
+| FRONT | Frontend Coder | React + Fusion |
+| INFRA | Infra Coder | Docker |
+| DOC | Doc Writer | — |
+| Todas | Reviewer | — |
+
+### Loop de desenvolvimento
+
+```
+Por task: implement → test unit → fix → lint → commit → review → fix → review (max 3)
+Por fase: integration tests → fix
+Por feature: E2E tests (CAs) → fix → 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
+
+## /setup-projeto vs /feature
+
+| Aspecto | /setup-projeto | /feature |
+|---------|---------------|----------|
+| Input | `docs/PM/setup_projeto/` | `docs/PM/feat_nome/` |
+| Extração | TRD.md (técnico) | PRD.md (produto) |
+| SDD + Tasks | Sim (infra + DOC tasks) | Sim (feature tasks) |
+| Gera docs/Estrutura/ | Via tasks DOC | Não — atualiza via /merge-delta |
+| /merge-delta | Não se aplica | Obrigatório após /dev |
+| Pré-requisito | Nenhum (primeiro comando) | docs/Estrutura/ deve existir |

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

@@ -0,0 +1,32 @@
+# Instruções para Arquivos Sensíveis
+
+> Regras especiais para arquivos que requerem cuidado extra.
+
+## Arquivos que NUNCA devem ser modificados pelo agente
+
+- `docs/PM/**/*` — Insumos brutos do usuário. Somente leitura.
+- `.env`, `.env.*` — Variáveis de ambiente com secrets.
+- `docs/Estrutura/ADRs.md` — ADRs aceitas são imutáveis (apenas adicionar novas).
+
+## Arquivos que requerem aprovação antes de modificar
+
+- `docs/Estrutura/*` — Documentação global. Só alterar via /merge-delta após /dev.
+- `docs/Desenvolvimento/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)
+
+- `docs/Desenvolvimento/*/.context.md` — YAML frontmatter, apenas skills atualizam.
+- `docs/Desenvolvimento/*/.extract-log.md` — Append-only, hashes obrigatórios.
+- `docs/Desenvolvimento/*/PRD.md` ou `TRD.md` — Seguir template exato.
+- `docs/Desenvolvimento/*/sdd.md` — Seguir template, todas as 11 seções + rastreabilidade.
+- `docs/Desenvolvimento/*/*_tasks.md` — IDs sequenciais, campos obrigatórios.
+- `docs/Desenvolvimento/*/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

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

@@ -0,0 +1,181 @@
+---
+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 |