spec-first-copilot 0.6.0-beta.9 → 0.7.0

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

@@ -1,351 +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
----
-
-# 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 |
-|------|--------|--------|--------|
-| DB | 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: `DB-*` → 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 | `specs/{nome}/tasks.md` e `workspace/Output/{nome}/Progresso.md` existem | Parar → "Tasks não encontradas. Execute /sf-plan {nome}" |
-| 4 | `specs/{nome}/` populado (brief, contracts, scenarios, tasks) | Parar → "Projeções do SDD não encontradas. Execute /sf-design {nome}" |
-| 5 | `.github/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 (scenarios.md — CAs)    ║
-│  ║     → Falhou? Identificar task → fix → loop   ║
-│  ║  2. Todos CAs passam? → prosseguir             ║
-│  ╚═══════════════════════════════════════════════╝
-│         ↓ (E2E aprovado, só features)
-│  ╔═══════════════════════════════════════════════╗
-│  ║  MERGE-DELTA (automático, só features)        ║
-│  ║                                               ║
-│  ║  1. Ler SDD §11 (Delta Specs)                ║
-│  ║  2. Aplicar ADDED/MODIFIED/REMOVED em         ║
-│  ║     docs/                           ║
-│  ║  3. Registrar changelog em cada doc alterado  ║
-│  ║  4. dev_done ✅                                ║
-│  ╚═══════════════════════════════════════════════╝
-```
-
----
-
-## Passos detalhados
-
-### 1. Carregar contexto
-- Ler `.context.md` → validar status
-- Ler `projetos.yaml` → mapeamento área → repo → path local
-- Ler `workspace/Output/{nome}/Progresso.md` → ordem de execução e estado atual
-- Ler `.github/rules.md` → convenções
-- Ler `specs/{nome}/brief.md` → contexto do que está sendo construído
-- Ler `specs/{nome}/contracts.md` → contratos de dados, API, integrações
-- Ler `specs/{nome}/scenarios.md` → fluxos, UI, critérios de aceite (CAs)
-- Ler `specs/{nome}/tasks.md` → tabela única de tasks
-- Carregar perfil do agente correspondente à área da task
-- Validar que repos em `projetos/` existem (se não, INFRA-001 ainda não rodou)
-
-**Regra**: o coder NUNCA lê o SDD direto (`workspace/Output/{nome}/sdd.md`). O SDD é narrativo pro humano. Os agents leem apenas as projeções em `specs/{nome}/`.
-
-### 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 (scenarios.md → estratégia de testes)
-- 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 + specs/{nome}/contracts.md (endpoints/auth) + docs/conventions.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, DB, 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 (cada CA de `specs/{nome}/scenarios.md` 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 → prosseguir para /sf-merge-docs
-
-### 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. /sf-merge-docs automático
-
-Após E2E aprovado, executar `/sf-merge-docs $ARGUMENTS`:
-- Aplica SDD §11 (ADDED/MODIFIED/REMOVED) em `docs/`
-- Em first_run: merge é idempotente (docs/ já criado pelo /sf-design — conteúdo bate)
-- Em feature: aplica deltas reais, atualiza catálogos e matrizes
-- Ver `.github/skills/sf-merge-docs/SKILL.md` pros detalhes
-
-> `/sf-merge-docs` continua callable manualmente se precisar re-aplicar.
-
-### 10. Atualizar `.context.md`
-```yaml
-status: "dev_in_progress"  # durante execução
-# ou
-status: "dev_done"         # todas fases + integration + security + E2E + /sf-merge-docs
-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 |
-| `workspace/Output/{nome}/Progresso.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 `specs/{nome}/scenarios.md`)
-- Merge-delta aplicado automaticamente (features) — docs/ atualizado
-
-## 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 |
+---
+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)
+```