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

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

@@ -1,204 +1,204 @@
----
-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
----
-
-# /sf-dev $ARGUMENTS
-
-Skill atômica de execução. Implementa tasks em loop até quality gate aprovado.
-$ARGUMENTS = nome (ex: feat_mvp)
-Flags opcionais: --fase 1 (RECOMENDADO) | --area banco | --task BACK-003
-
-## Agents por área (perfis em `.github/agents/`)
-
-| Área | Agente | Stack | Modelo |
-|------|--------|-------|--------|
-| DB | DB Coder | PostgreSQL 16 | Sonnet (S/M) / Opus (L) |
-| BACK | Backend Coder | .NET 8 / C# | Sonnet (S/M) / Opus (L) |
-| FRONT | Frontend Coder | React + Fusion | Sonnet (S/M) / Opus (L) |
-| INFRA | Infra Coder | Docker | Sonnet (S/M) / Opus (L) |
-| DOC | Doc Writer | — | Sonnet |
-| Todas | Reviewer | — | Sonnet |
-| Todas | Security Reviewer | — | Opus |
-
-Agente selecionado pelo prefixo: BACK-* → Backend Coder, DB-* → DB Coder, etc.
-Ler o perfil do agente em `.github/agents/` antes de implementar.
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | $ARGUMENTS informado | Parar |
-| 2 | `.context.md` com status `plan_done` ou `dev_in_progress` | Se anterior → "/sf-plan primeiro" |
-| 3 | `specs/{nome}/tasks.md` e `workspace/Output/{nome}/Progresso.md` existem | Parar |
-| 4 | `specs/{nome}/` populado (brief, contracts, scenarios, tasks) | Parar — "/sf-design não rodou" |
-| 5 | `rules.md` existe | Parar |
-| 6 | `projetos.yaml` existe | Parar → "Execute /sf-design primeiro" |
-| 7 | Infra local rodando (`docker compose ps` → healthy) | Parar → "Suba a infra: `docker compose up -d`" |
-
-## Fluxo de execução
-
-```
-╔═══════════════════════════════════════════════╗
-║  LOOP POR TASK                                ║
-║                                               ║
-║  1. Selecionar agente pela área               ║
-║  2. Ler perfil do agente (.github/agents/)    ║
-║  3. Implementar código + testes unit          ║
-║  4. Rodar testes unit                         ║
-║     → Falhou? Corrigir → volta pro 4          ║
-║     → 5 falhas? Parar, reportar               ║
-║  5. Rodar lint                                ║
-║     → Falhou? Corrigir → volta pro 5          ║
-║  6. Commit: tipo(TASK-ID): descrição          ║
-║  7. Review (quality gate)                     ║
-║     → Reprovado? Corrigir → volta pro 4       ║
-║     → 3 reprovações? Escalar pro usuário      ║
-║  8. Marcar task concluída ✅                   ║
-╚═══════════════════════════════════════════════╝
-        ↓ (todas tasks da fase)
-╔═══════════════════════════════════════════════╗
-║  VALIDAÇÃO POR FASE                           ║
-║  1. Rodar testes integration da área          ║
-║     → Falhou? Fix → loop (max 3)             ║
-╚═══════════════════════════════════════════════╝
-        ↓ (tudo concluído)
-╔═══════════════════════════════════════════════╗
-║  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 E2E (scenarios.md — CAs)           ║
-║     → Falhou? Identificar → fix → loop (max 3)║
-║  2. Tudo passou? → prosseguir                 ║
-╚═══════════════════════════════════════════════╝
-        ↓ (E2E aprovado, só features)
-╔═══════════════════════════════════════════════╗
-║  MERGE-DOCS (automático, só features)         ║
-║  1. Ler PRD + TRD aprovados                   ║
-║  2. Diff semântico vs docs/ atual             ║
-║  3. Aplicar ADDED/MODIFIED em docs/           ║
-║  4. Registrar changelog em cada doc alterado  ║
-║  5. dev_done → done ✅                         ║
-╚═══════════════════════════════════════════════╝
-```
-
-## Multi-repo + Git Workflow
-
-### Contexto inicial
-- Ler `projetos.yaml` → mapeamento área → repo → path local
-- Validar que repos em `projetos/` existem (se não, INFRA-001 ainda não rodou)
-
-### Passo 1 — Verificar working tree (OBRIGATÓRIO)
-Em cada repo afetado: `git status`
-- Se working tree sujo → sugerir commit ou stash antes de prosseguir
-- NUNCA começar a codar com working tree sujo
-
-### INFRA-001 (setup — primeira execução)
-No setup, INFRA-001 cria/clona os repos:
-- Ler `projetos.yaml` → para cada repo:
-  - Se `existing: true` → `git clone {repo} projetos/{name}`
-  - Se `existing: false` → criar repo (`gh repo create {repo} --private`) + clone
-- Criar estrutura base em cada repo (conforme stack)
-
-### Passo 2 — Branch por fase (NUNCA na main)
-Para cada repo afetado por esta fase:
-```bash
-cd projetos/{repo_path}
-git checkout main && git pull origin main
-git checkout -b feature/{nome}_fase{N}
-```
-- NUNCA desenvolver direto na main
-
-## Implementação por task
-
-1. **Navegar**: ler campo `Repo:` da task → `cd projetos/{repo_path}/`
-2. **Ler**: task completa + `specs/{nome}/brief.md` + `contracts.md` + `scenarios.md` (NUNCA ler PRD/TRD direto — só as projeções em specs/) + perfil do agente + `.github/rules.md`
-3. **Implementar**: código nos arquivos listados (caminhos relativos ao repo)
-4. **Testar**: testes unit nos arquivos de teste listados na task
-5. **Commit**: no repo do serviço — `tipo(TASK-ID): descrição curta`
-6. **Review**: quality gate (compilar, testes, lint, conformidade com specs/, convenções)
-
-## Quality gate (Reviewer)
-
-| Check | Critério |
-|-------|----------|
-| Compila | Sem erros |
-| Testes unit | Passam |
-| Lint | Limpo |
-| Conformidade spec | Contratos, tipos, regras conforme `specs/{nome}/contracts.md` |
-| Convenções | rules.md respeitado |
-| Sem TODOs | Injustificados |
-| Sem secrets | Hardcoded |
-| Arquivos corretos | Só os listados na task modificados |
-
-## Limites de retry
-
-| Nível | Limite | Ação ao exceder |
-|-------|--------|-----------------|
-| Test unit | 5 por task | Parar, reportar |
-| Review | 3 por task | Escalar pro usuário |
-| Integration | 3 por fase | Parar, reportar |
-| Security | 2 por feature | Escalar findings não resolvidos |
-| E2E | 3 por feature | Parar, reportar |
-
-## Passo 3 — Ao terminar fase: PR + ambiente ON
-
-1. Atualizar Progresso.md com status da fase
-2. Push da branch em cada repo: `git push origin feature/{nome}_fase{N}`
-3. Abrir PR com template detalhado (ver rules.md → Template de PR):
-   - Tasks concluídas, testes passando, como testar manualmente
-   - `gh pr create`
-4. Deixar ambiente local rodando:
-   - `docker compose up -d` (infra)
-   - `dotnet run` / `npm run dev` (apps nos repos)
-   - Informar URLs ao usuário
-5. **PARAR e aguardar** — merge é MANUAL pelo usuário
-
-## Passo 4 — Aguardar aprovação
-
-- O agente NUNCA faz merge
-- Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
-
-## Passo 5 — Após merge (quando usuário confirmar)
-
-```bash
-cd projetos/{repo_path}
-git checkout main && git pull origin main
-git branch -d feature/{nome}_fase{N}
-git remote prune origin
-```
-
-## Merge-Docs automático (só features)
-
-Após E2E aprovado, SE `.context.md → first_run=false`:
-
-1. Chamar inline `/sf-merge-docs {nome}` (ver `.github/skills/sf-merge-docs/SKILL.md`)
-2. Integrator (Opus) faz diff semântico entre PRD+TRD aprovados e docs/ atual
-3. Aplica ADDED/MODIFIED em cada doc afetado
-4. Registra changelog em cada doc alterado
-5. Valida consistência cross-doc (reporta, não bloqueia)
-
-Se `first_run=true` → **pular** merge-docs automático (docs/ já foi criado pelo /sf-design).
-
-Se `/sf-merge-docs` falhar → reportar mas não derrubar `/sf-dev`. User pode re-rodar manual.
-
-> `/sf-merge-docs` continua existindo como command atômico pra re-execução manual.
-> Mesma semântica sempre — idempotente, não duplica conteúdo.
-
-## Atualizar `.context.md`
-```yaml
-status: "dev_in_progress"   # durante
-status: "dev_done"           # ao final das tasks (antes do merge-docs)
-status: "done"               # após merge-docs aplicado (ou pulado em first_run)
-```
+---
+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
+---
+
+# /sf-dev $ARGUMENTS
+
+Skill atômica de execução. Implementa tasks em loop até quality gate aprovado.
+$ARGUMENTS = nome (ex: feat_mvp)
+Flags opcionais: --fase 1 (RECOMENDADO) | --area banco | --task BACK-003
+
+## Agents por área (perfis em `.github/agents/`)
+
+| Área | Agente | Stack | Modelo |
+|------|--------|-------|--------|
+| DB | DB Coder | PostgreSQL 16 | Sonnet (S/M) / Opus (L) |
+| BACK | Backend Coder | .NET 8 / C# | Sonnet (S/M) / Opus (L) |
+| FRONT | Frontend Coder | React + Fusion | Sonnet (S/M) / Opus (L) |
+| INFRA | Infra Coder | Docker | Sonnet (S/M) / Opus (L) |
+| DOC | Doc Writer | — | Sonnet |
+| Todas | Reviewer | — | Sonnet |
+| Todas | Security Reviewer | — | Opus |
+
+Agente selecionado pelo prefixo: BACK-* → Backend Coder, DB-* → DB Coder, etc.
+Ler o perfil do agente em `.github/agents/` antes de implementar.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | $ARGUMENTS informado | Parar |
+| 2 | `.context.md` com status `plan_done` ou `dev_in_progress` | Se anterior → "/sf-plan primeiro" |
+| 3 | `specs/{nome}/tasks.md` e `workspace/Output/{nome}/Progresso.md` existem | Parar |
+| 4 | `specs/{nome}/` populado (brief, contracts, scenarios, tasks) | Parar — "/sf-design não rodou" |
+| 5 | `rules.md` existe | Parar |
+| 6 | `projetos.yaml` existe | Parar → "Execute /sf-design primeiro" |
+| 7 | Infra local rodando (`docker compose ps` → healthy) | Parar → "Suba a infra: `docker compose up -d`" |
+
+## Fluxo de execução
+
+```
+╔═══════════════════════════════════════════════╗
+║  LOOP POR TASK                                ║
+║                                               ║
+║  1. Selecionar agente pela área               ║
+║  2. Ler perfil do agente (.github/agents/)    ║
+║  3. Implementar código + testes unit          ║
+║  4. Rodar testes unit                         ║
+║     → Falhou? Corrigir → volta pro 4          ║
+║     → 5 falhas? Parar, reportar               ║
+║  5. Rodar lint                                ║
+║     → Falhou? Corrigir → volta pro 5          ║
+║  6. Commit: tipo(TASK-ID): descrição          ║
+║  7. Review (quality gate)                     ║
+║     → Reprovado? Corrigir → volta pro 4       ║
+║     → 3 reprovações? Escalar pro usuário      ║
+║  8. Marcar task concluída ✅                   ║
+╚═══════════════════════════════════════════════╝
+        ↓ (todas tasks da fase)
+╔═══════════════════════════════════════════════╗
+║  VALIDAÇÃO POR FASE                           ║
+║  1. Rodar testes integration da área          ║
+║     → Falhou? Fix → loop (max 3)             ║
+╚═══════════════════════════════════════════════╝
+        ↓ (tudo concluído)
+╔═══════════════════════════════════════════════╗
+║  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 E2E (scenarios.md — CAs)           ║
+║     → Falhou? Identificar → fix → loop (max 3)║
+║  2. Tudo passou? → prosseguir                 ║
+╚═══════════════════════════════════════════════╝
+        ↓ (E2E aprovado, só features)
+╔═══════════════════════════════════════════════╗
+║  MERGE-DOCS (automático, só features)         ║
+║  1. Ler PRD + TRD aprovados                   ║
+║  2. Diff semântico vs docs/ atual             ║
+║  3. Aplicar ADDED/MODIFIED em docs/           ║
+║  4. Registrar changelog em cada doc alterado  ║
+║  5. dev_done → done ✅                         ║
+╚═══════════════════════════════════════════════╝
+```
+
+## Multi-repo + Git Workflow
+
+### Contexto inicial
+- Ler `projetos.yaml` → mapeamento área → repo → path local
+- Validar que repos em `projetos/` existem (se não, INFRA-001 ainda não rodou)
+
+### Passo 1 — Verificar working tree (OBRIGATÓRIO)
+Em cada repo afetado: `git status`
+- Se working tree sujo → sugerir commit ou stash antes de prosseguir
+- NUNCA começar a codar com working tree sujo
+
+### INFRA-001 (setup — primeira execução)
+No setup, INFRA-001 cria/clona os repos:
+- Ler `projetos.yaml` → para cada repo:
+  - Se `existing: true` → `git clone {repo} projetos/{name}`
+  - Se `existing: false` → criar repo (`gh repo create {repo} --private`) + clone
+- Criar estrutura base em cada repo (conforme stack)
+
+### Passo 2 — Branch por fase (NUNCA na main)
+Para cada repo afetado por esta fase:
+```bash
+cd projetos/{repo_path}
+git checkout main && git pull origin main
+git checkout -b feature/{nome}_fase{N}
+```
+- NUNCA desenvolver direto na main
+
+## Implementação por task
+
+1. **Navegar**: ler campo `Repo:` da task → `cd projetos/{repo_path}/`
+2. **Ler**: task completa + `specs/{nome}/brief.md` + `contracts.md` + `scenarios.md` (NUNCA ler PRD/TRD direto — só as projeções em specs/) + perfil do agente + `.github/rules.md`
+3. **Implementar**: código nos arquivos listados (caminhos relativos ao repo)
+4. **Testar**: testes unit nos arquivos de teste listados na task
+5. **Commit**: no repo do serviço — `tipo(TASK-ID): descrição curta`
+6. **Review**: quality gate (compilar, testes, lint, conformidade com specs/, convenções)
+
+## Quality gate (Reviewer)
+
+| Check | Critério |
+|-------|----------|
+| Compila | Sem erros |
+| Testes unit | Passam |
+| Lint | Limpo |
+| Conformidade spec | Contratos, tipos, regras conforme `specs/{nome}/contracts.md` |
+| Convenções | rules.md respeitado |
+| Sem TODOs | Injustificados |
+| Sem secrets | Hardcoded |
+| Arquivos corretos | Só os listados na task modificados |
+
+## Limites de retry
+
+| Nível | Limite | Ação ao exceder |
+|-------|--------|-----------------|
+| Test unit | 5 por task | Parar, reportar |
+| Review | 3 por task | Escalar pro usuário |
+| Integration | 3 por fase | Parar, reportar |
+| Security | 2 por feature | Escalar findings não resolvidos |
+| E2E | 3 por feature | Parar, reportar |
+
+## Passo 3 — Ao terminar fase: PR + ambiente ON
+
+1. Atualizar Progresso.md com status da fase
+2. Push da branch em cada repo: `git push origin feature/{nome}_fase{N}`
+3. Abrir PR com template detalhado (ver rules.md → Template de PR):
+   - Tasks concluídas, testes passando, como testar manualmente
+   - `gh pr create`
+4. Deixar ambiente local rodando:
+   - `docker compose up -d` (infra)
+   - `dotnet run` / `npm run dev` (apps nos repos)
+   - Informar URLs ao usuário
+5. **PARAR e aguardar** — merge é MANUAL pelo usuário
+
+## Passo 4 — Aguardar aprovação
+
+- O agente NUNCA faz merge
+- Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
+
+## Passo 5 — Após merge (quando usuário confirmar)
+
+```bash
+cd projetos/{repo_path}
+git checkout main && git pull origin main
+git branch -d feature/{nome}_fase{N}
+git remote prune origin
+```
+
+## Merge-Docs automático (só features)
+
+Após E2E aprovado, SE `.context.md → first_run=false`:
+
+1. Chamar inline `/sf-merge-docs {nome}` (ver `.github/skills/sf-merge-docs/SKILL.md`)
+2. Integrator (Opus) faz diff semântico entre PRD+TRD aprovados e docs/ atual
+3. Aplica ADDED/MODIFIED em cada doc afetado
+4. Registra changelog em cada doc alterado
+5. Valida consistência cross-doc (reporta, não bloqueia)
+
+Se `first_run=true` → **pular** merge-docs automático (docs/ já foi criado pelo /sf-design).
+
+Se `/sf-merge-docs` falhar → reportar mas não derrubar `/sf-dev`. User pode re-rodar manual.
+
+> `/sf-merge-docs` continua existindo como command atômico pra re-execução manual.
+> Mesma semântica sempre — idempotente, não duplica conteúdo.
+
+## Atualizar `.context.md`
+```yaml
+status: "dev_in_progress"   # durante
+status: "dev_done"           # ao final das tasks (antes do merge-docs)
+status: "done"               # após merge-docs aplicado (ou pulado em first_run)
+```