spec-first-copilot 0.1.0

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

@@ -0,0 +1,326 @@
+---
+name: sf-dev
+description: |
+  Desenvolvimento. Implementa tasks com loop implement/test/review.
+  Trigger: /sf-dev
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-04-08
+---
+
+# Skill: /sf-dev
+
+> Skill atômica de execução. Implementa tasks em loop (implement → test → fix → review)
+> até quality gate aprovado, depois valida integração e E2E por feature.
+
+## Tipo
+Atômica — Multi-agent (agentes especializados por área)
+
+## Uso
+```
+/sf-dev <nome>
+/sf-dev <nome> --area banco
+/sf-dev <nome> --task BACK-003
+```
+
+---
+
+## Agentes
+
+Cada área tem seu agente especializado. Perfis completos em `.github/agents/`.
+
+| Área | Agente | Perfil | Modelo |
+|------|--------|--------|--------|
+| BANCO | DB Coder | `agents/db-coder.md` | Sonnet (S/M) / Opus (L) |
+| BACK | Backend Coder | `agents/backend-coder.md` | Sonnet (S/M) / Opus (L) |
+| FRONT | Frontend Coder | `agents/frontend-coder.md` | Sonnet (S/M) / Opus (L) |
+| INFRA | Infra Coder | `agents/infra-coder.md` | Sonnet (S/M) / Opus (L) |
+| DOC | Doc Writer | `agents/doc-writer.md` | Sonnet |
+| — | Reviewer | `agents/reviewer.md` | Sonnet |
+| — | Security Reviewer | `agents/security-reviewer.md` | Opus |
+
+O agente é selecionado pelo prefixo da task: `BANCO-*` → DB Coder, `BACK-*` → Backend Coder, etc.
+
+---
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | Argumento `nome` foi informado | Parar → "Informe o nome. Ex: /sf-dev feat_cadastro_cliente" |
+| 2 | `.context.md` existe com status `plan_done` ou `dev_in_progress` | Se anterior → "Execute /sf-plan {nome} primeiro" |
+| 3 | `*_tasks.md` e `Progresso.md` existem | Parar → "Tasks não encontradas. Execute /sf-plan {nome}" |
+| 4 | `sdd.md` existe | Parar → "SDD não encontrado" |
+| 5 | `docs/Desenvolvimento/rules.md` existe | Parar → "rules.md não encontrado" |
+| 6 | `projetos.yaml` existe na raiz | Parar → "Execute /sf-design primeiro (gera projetos.yaml)" |
+| 7 | Infra local rodando (`docker compose ps` → containers healthy) | Parar → "Suba a infra primeiro: `docker compose up -d` e aguarde healthy" |
+
+> **Nota**: A validação #7 verifica se os containers de infra (banco, redis, etc.) estão rodando.
+> Não valida apps (api, web) — essas são iniciadas durante o /dev.
+
+## Modalidades
+
+| Modo | Comando | Comportamento |
+|------|---------|---------------|
+| **Por fase** | `/sf-dev feat_nome --fase 1` | Todas tasks da fase de entrega (RECOMENDADO) |
+| **Completo** | `/sf-dev feat_nome` | Executa todas tasks pendentes, respeitando ordem de fases |
+| **Por área** | `/sf-dev feat_nome --area banco` | Só tasks da área especificada |
+| **Task individual** | `/sf-dev feat_nome --task BACK-003` | Só a task especificada (valida dependências) |
+
+> **Recomendado**: Usar `--fase N` para desenvolvimento incremental. Cada fase gera 1 PR.
+
+---
+
+## Fluxo de Execução
+
+```
+/sf-dev feat_nome
+│
+│  ╔═══════════════════════════════════════════════╗
+│  ║  LOOP POR TASK                                ║
+│  ║                                               ║
+│  ║  1. Selecionar agente pela área (BACK-* etc)  ║
+│  ║  2. Agente implementa código + testes unit    ║
+│  ║  3. Rodar testes unit                         ║
+│  ║     → Falhou? Agente corrige → volta pro 3    ║
+│  ║  4. Rodar lint                                ║
+│  ║     → Falhou? Agente corrige → volta pro 4    ║
+│  ║  5. Commit: tipo(TASK-ID): descrição          ║
+│  ║  6. Reviewer valida quality gate              ║
+│  ║     → Reprovado? Agente corrige → volta pro 3 ║
+│  ║     → 3 reprovações? Escalar pro usuário      ║
+│  ║  7. Marcar task concluída ✅                   ║
+│  ║  8. Atualizar Progresso.md                    ║
+│  ╚═══════════════════════════════════════════════╝
+│         ↓ (todas tasks da fase concluídas)
+│  ╔═══════════════════════════════════════════════╗
+│  ║  VALIDAÇÃO POR FASE                           ║
+│  ║                                               ║
+│  ║  1. Rodar testes integration da área/fase     ║
+│  ║     → Falhou? Criar fix inline → loop         ║
+│  ║  2. Fase aprovada → próxima fase              ║
+│  ╚═══════════════════════════════════════════════╝
+│         ↓ (todas fases/áreas concluídas)
+│  ╔═══════════════════════════════════════════════╗
+│  ║  SECURITY REVIEW (cross-area)                 ║
+│  ║                                               ║
+│  ║  1. Security Reviewer audita todo código      ║
+│  ║     → CRÍTICO/ALTO? Coder corrige → re-audit  ║
+│  ║     → 2 falhas? Escalar pro usuário           ║
+│  ║  2. Aprovado → prosseguir para E2E            ║
+│  ╚═══════════════════════════════════════════════╝
+│         ↓ (security aprovado)
+│  ╔═══════════════════════════════════════════════╗
+│  ║  VALIDAÇÃO POR FEATURE                        ║
+│  ║                                               ║
+│  ║  1. Rodar testes E2E (SDD §9.3 CAs)          ║
+│  ║     → Falhou? Identificar task → fix → loop   ║
+│  ║  2. Todos CAs passam? → dev_done ✅            ║
+│  ╚═══════════════════════════════════════════════╝
+```
+
+---
+
+## Passos detalhados
+
+### 1. Carregar contexto
+- Ler `.context.md` → validar status
+- Ler `projetos.yaml` → mapeamento área → repo → path local
+- Ler `Progresso.md` → ordem de execução e estado atual
+- Ler `rules.md` → convenções
+- Ler `sdd.md` → fonte de verdade (§9 para estratégia de testes)
+- Carregar perfil do agente correspondente à área
+- Validar que repos em `projetos/` existem (se não, INFRA-001 ainda não rodou)
+
+### 2. Preparar repos (multi-repo)
+
+#### 2a. Verificar working tree (OBRIGATÓRIO)
+Em cada repo que será afetado:
+- `git status` — verificar se há mudanças pendentes
+- Se working tree sujo → sugerir commit ou stash antes de prosseguir
+- NUNCA começar a codar com working tree sujo
+
+#### 2b. INFRA-001 (setup — primeira execução)
+No setup, INFRA-001 é responsável por criar/clonar os repos:
+- Ler `projetos.yaml` → para cada repo:
+  - Se `existing: true` → `git clone {repo} projetos/{name}`
+  - Se `existing: false` → criar repo no GitHub (`gh repo create {repo} --private`) + clone local
+- Criar estrutura base em cada repo (conforme stack: .NET → `dotnet new`, React → `create-react-app`, etc.)
+- Criar `projetos/.gitkeep` na raiz (pasta existe mas conteúdo é ignorado)
+
+#### 2c. Branch por fase (NUNCA na main)
+Para cada repo que será afetado por esta fase:
+- `cd projetos/{repo_path}`
+- `git checkout main && git pull origin main` (garantir main atualizada)
+- `git checkout -b feature/{nome}_fase{N}` (se branch não existe)
+- Se branch já existe → `git checkout feature/{nome}_fase{N}`
+- NUNCA desenvolver direto na main
+
+#### 2c. Resolver próxima task
+- Filtrar tasks pendentes (`- [ ]`) conforme modalidade
+- Ler campo `Repo:` da task → identificar em qual repo trabalhar
+- Validar dependências: todas tasks em `Depende:` devem estar `- [x]`
+- Se dependência pendente → listar o que falta
+
+### 3. Loop por task
+
+#### 3a. Implementar
+- Ler campo `Repo:` da task → navegar para `projetos/{repo_path}/`
+- Selecionar agente pela área da task (BACK-* → Backend Coder)
+- Selecionar modelo pelo tamanho (S/M → Sonnet, L → Opus)
+- Input para o agente:
+  - Task completa (ID, título, arquivos, SDD ref, dependências)
+  - Seções do SDD referenciadas (apenas as seções necessárias)
+  - Perfil do agente (`.github/agents/*.md`)
+  - `rules.md`
+  - **Working directory**: `projetos/{repo_path}/` (caminhos de arquivo são relativos ao repo)
+- Agente implementa código **E testes unit** na mesma task
+
+#### 3b. Test loop
+```
+Rodar testes unit → passou? → continuar
+                  → falhou? → agente analisa erro → corrige → rodar de novo
+                  → 5 falhas seguidas? → parar, reportar ao usuário
+```
+
+#### 3c. Lint
+```
+Rodar lint → passou? → continuar
+          → falhou? → agente corrige → rodar de novo
+```
+
+#### 3d. Commit (no repo do serviço)
+- Working directory: `projetos/{repo_path}/`
+- `git add` + `git commit -m "tipo(TASK-ID): descrição curta"`
+- Commit acontece no repo do serviço, NÃO no projeto-base
+- Corpo opcional se Senior Coder tomou decisão (mini-ADR)
+
+#### 3e. Review
+- Spawn Reviewer (Sonnet) com: código + testes + quality gate checklist
+- Se APROVADO → marcar task `- [x]`, atualizar Progresso.md
+- Se REPROVADO → agente recebe problemas, corrige, volta pro 3b
+- Limite: **3 reprovações** → escalar pro usuário
+
+### 4. Validação por fase
+Ao concluir todas tasks de uma fase:
+- Rodar testes integration da área (SDD §9.1)
+- Se falhou → identificar causa, corrigir no código da task afetada, recommit
+- Se passou → avançar pra próxima fase
+
+### 5. Security Review (cross-area)
+Ao concluir todas tasks de todas áreas, ANTES dos testes E2E:
+- Spawn Security Reviewer (Opus) com: todo código produzido + SDD §5 + Seguranca.md
+- Audita 6 categorias: Auth, AuthZ, Injeção, Dados Sensíveis, Headers, Banco
+- Se findings CRÍTICO ou ALTO:
+  - Identificar área responsável (BACK, FRONT, BANCO, INFRA)
+  - Coder da área corrige → recommit
+  - Security Reviewer reavalia apenas os findings
+- Se aprovado → prosseguir para E2E
+- Limite: **2 tentativas** → escalar pro usuário
+
+### 6. Validação por feature
+Ao concluir security review com aprovação:
+- Rodar testes E2E (SDD §9.3 — cada CA deve ter teste correspondente)
+- Se falhou:
+  - Identificar qual CA falhou
+  - Mapear pra task/área responsável
+  - Criar fix inline (não cria nova task)
+  - Rodar E2E de novo
+- Se passou → dev_done
+
+### 7. Finalizar fase — PR + ambiente ON
+Ao concluir todos testes da fase:
+
+1. **Atualizar Progresso.md** com status da fase
+2. **Push da branch** em cada repo afetado:
+   ```bash
+   cd projetos/{repo_path}
+   git push origin feature/{nome}_fase{N}
+   ```
+3. **Abrir PR** em cada repo com template detalhado (ver `rules.md` → Template de PR):
+   - Tasks concluídas, testes passando, como testar manualmente
+   - Usar `gh pr create`
+4. **Deixar ambiente local rodando**:
+   - `docker compose up -d` (infra)
+   - `dotnet run` / `npm run dev` (apps)
+   - Informar URLs ao usuário
+5. **PARAR e aguardar** — o usuário testa manualmente e aprova o PR
+   - O agente NUNCA faz merge — merge é manual pelo usuário
+   - Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
+
+### 8. Após merge (quando usuário confirmar)
+```bash
+# Em cada repo afetado:
+cd projetos/{repo_path}
+git checkout main
+git pull origin main
+git branch -d feature/{nome}_fase{N}
+git remote prune origin
+```
+
+### 9. Atualizar `.context.md`
+```yaml
+status: "dev_in_progress"  # durante execução
+# ou
+status: "dev_done"         # todas fases + integration + security + E2E passaram
+ultima_skill: "/sf-dev"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+---
+
+## Limites de retry
+
+| Nível | Limite | Ação ao exceder |
+|-------|--------|-----------------|
+| Test loop (unit) | 5 tentativas por task | Parar, reportar erro persistente |
+| Review loop | 3 reprovações por task | Parar, escalar pro usuário |
+| Integration fix | 3 tentativas por fase | Parar, reportar ao usuário |
+| Security fix | 2 tentativas por feature | Parar, escalar findings não resolvidos |
+| E2E fix | 3 tentativas por feature | Parar, reportar ao usuário |
+
+Mensagem de escalação:
+```
+⚠️ Task {ID} não passou após {N} tentativas.
+Problemas persistentes:
+1. ...
+2. ...
+Ação necessária: revisar SDD ou intervir manualmente.
+```
+
+---
+
+## Saídas
+
+| Saída | Descrição |
+|-------|-----------|
+| Código implementado | Em `projetos/{repo}/` — arquivos criados/modificados conforme tasks |
+| Testes | Unit + integration + E2E nos repos correspondentes |
+| Commits | 1 commit por task no repo do serviço: `tipo(TASK-ID): descrição` |
+| Branches | `feature/{nome}` criado em cada repo afetado |
+| `*_tasks.md` | Tasks marcadas como concluídas (no projeto-base) |
+| `Progresso.md` | Atualizado com status real (no projeto-base) |
+| `progresso.md` (global) | Atualizado (no projeto-base) |
+| `.context.md` | Status atualizado (no projeto-base) |
+
+## Pós-condições
+- Todas tasks concluídas = status `dev_done`
+- Quality gate aprovado em cada task
+- Integration tests passam por fase
+- Security Review aprovado (zero findings CRÍTICO/ALTO)
+- E2E tests passam por feature (todos CAs do SDD §9.3)
+- Pronto para `/merge-delta` (se feature) ou conclusão (se setup)
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| Nome não informado | Parar, mostrar exemplo |
+| Status anterior a plan_done | Parar, sugerir skill correspondente |
+| Dependência não concluída | Parar, listar dependências pendentes |
+| Test loop excedeu limite | Parar, reportar erro + stack trace |
+| Review excedeu 3 tentativas | Parar, escalar com lista de problemas |
+| Integration/E2E persistente | Parar, reportar CAs que falharam |
+| SDD ambíguo | Parar, reportar ambiguidade |
+| --task com ID inexistente | Parar, listar tasks disponíveis |
+| --area com área inexistente | Parar, listar áreas disponíveis |