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

package/templates/.github/skills/sf-merge-docs/SKILL.md

@@ -1,152 +1,152 @@
-
-# /sf-merge-docs $ARGUMENTS
-
-Skill atômica pós-dev. Aplica as decisões de **PRD + TRD aprovados** em `docs/` pra manter a síntese cross-feature sincronizada com o estado do sistema.
-`$ARGUMENTS` = nome do scope (ex: `feat_cadastro_cliente`).
-
-Chamado automaticamente pelo `/sf-dev` ao final. Re-executável manualmente quando precisa.
-
-> **Mudança v3 → v4**: antes aplicava `SDD §11 Delta Specs` (mecanismo OpenSpec).
-> Agora lê **PRD + TRD aprovados diretamente** e infere o delta comparando com
-> o estado atual de `docs/` (diff semântico). SDD não existe mais em v4.
-
-## Agente: Integrator (Opus)
-
-Em v4 promovido de Sonnet → Opus: diff semântico PRD/TRD ↔ docs/ exige reasoning
-de maior nível que o antigo "aplicar §11 explícito". Meticuloso com consistência.
-Merge idempotente — re-aplicar os mesmos docs source não duplica conteúdo.
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | `$ARGUMENTS` informado | Parar |
-| 2 | `.context.md` com status `dev_done` (uso auto no /sf-dev) OU `design_done` a mais (uso manual) | Se anterior → "Rode /sf-design primeiro" |
-| 3 | Pelo menos PRD.md OU TRD.md existe e está aprovado | Parar — "Nenhum doc source aprovado pra mergear" |
-| 4 | `docs/` populado (veio de first-run anterior) | Parar — "/sf-design com first_run=true é quem cria docs/" |
-
-> `/sf-merge-docs` **só se aplica a features**, não a first-run. Em first-run, é o
-> próprio `/sf-design` que cria `docs/` a partir de PRD+TRD — não há o que mergear.
-
-## Passos
-
-### 1. Snapshot do estado atual de docs/
-
-Ler `docs/{architecture,domain,conventions,apiContracts,decisions}.md`.
-Indexar por elementos (tabelas, endpoints, ADRs, papéis, env vars...) pra diff.
-
-### 2. Extrair elementos-destino do PRD e TRD aprovados
-
-| Fonte (PRD/TRD) | Elemento | Destino em docs/ |
-|-----------------|----------|------------------|
-| TRD §1.1 Stack | Nova tecnologia / versão | `architecture.md` §Stack |
-| TRD §1.2 Arquitetura | Novo container / padrão | `architecture.md` §Containers/Padrões |
-| TRD §1.3 Ambientes | Novo ambiente / mudança | `architecture.md` §Ambientes |
-| TRD §1.4 Deploy | Mudança na estratégia | `architecture.md` §Deploy |
-| TRD §4 §Área-DB | Nova tabela / índice / FK | `domain.md` §Catálogo de Tabelas |
-| TRD §2.1 Endpoints | Novo endpoint | `apiContracts.md` §Catálogo |
-| TRD §7.1 Auth | Mudança em auth | `conventions.md` §Autenticação |
-| TRD §7.2 Autorização | Novo papel / permissão | `conventions.md` §Autorização |
-| TRD §7.3 LGPD | Novo dado pessoal | `conventions.md` §LGPD |
-| TRD §7.4 Rate limit | Nova categoria | `conventions.md` §Rate Limiting |
-| TRD §5.3 Env vars | Nova variável | `conventions.md` §Variáveis de Ambiente |
-| TRD §6 Integrações | Novo sistema externo | `domain.md` §Integrações Externas |
-| TRD §9 ADRs | Nova decisão | `decisions.md` (append-only, imutável) |
-| PRD §2 Atores | Novo papel/persona | `domain.md` §Usuários e Papéis |
-| PRD §5 RNs | Nova regra de negócio | (não vai pra docs/ — fica em specs/{nome}/contracts.md) |
-
-> **Regra**: PRD alimenta poucas seções de `docs/` (só atores e alto-nível).
-> O grosso vem do TRD — `docs/` é síntese técnica + negócio cross-feature.
-
-### 3. Diff semântico: calcular ADDED / MODIFIED / REMOVED
-
-Pra cada elemento-destino extraído (passo 2), comparar com snapshot (passo 1):
-
-| Resultado | Condição | Ação |
-|-----------|----------|------|
-| ADDED | Elemento não existe em docs/ | Adicionar na seção apropriada |
-| MODIFIED | Elemento existe mas mudou (nome igual, valor diferente) | Atualizar campos |
-| UNCHANGED | Elemento existe e está igual | Skip (idempotente) |
-| REMOVED | Elemento estava em docs/ mas não aparece em PRD+TRD aprovados | **NÃO remover** — apenas registrar no output como "possivelmente orfão" |
-
-> **Conservadorismo em REMOVED**: PRD/TRD falam só da feature atual. Algo que
-> "não aparece" pode ser de outra feature (que continua válida). NUNCA deletar
-> automaticamente. Reportar e deixar remoção manual.
-
-### 4. Aplicar ADDED e MODIFIED
-
-- Localizar seção apropriada no doc destino
-- Preservar estrutura do template (não quebrar tabelas)
-- ADRs em `decisions.md`: SEMPRE append; ADR com status=aceita é imutável
-- Registrar cada mudança em changelog do doc afetado
-
-### 5. Changelog em cada doc afetado
-
-Adicionar linha no `## Changelog` do doc:
-
-```markdown
-| Data | Feature | Tipo | Descrição |
-|------|---------|------|-----------|
-| {{ISO_DATE}} | $ARGUMENTS | ADDED | Endpoint POST /api/v1/users |
-| {{ISO_DATE}} | $ARGUMENTS | MODIFIED | Matriz de permissões: novo role `manager` |
-```
-
-### 6. Validar consistência cross-doc
-
-- Referências quebradas (endpoint do apiContracts referencia tabela que não existe em domain) → reportar
-- Papel novo em conventions mas não aparece em matriz de autorização → reportar
-- ADR substituída mas ainda referenciada → reportar
-
-Validação reporta, não bloqueia. Usuário decide se resolve manualmente.
-
-### 7. Atualizar status
-
-```yaml
-status: "done"
-ultima_skill: "/sf-merge-docs"
-atualizado_em: "{{ISO_DATETIME}}"
-```
-
-### 8. Saída obrigatória
-
-```
-/sf-merge-docs $ARGUMENTS — completo
-
-docs/ sincronizado com PRD + TRD aprovados:
-- docs/architecture.md    (2 ADDED, 0 MODIFIED)
-- docs/apiContracts.md    (3 ADDED, 1 MODIFIED)
-- docs/conventions.md     (0 ADDED, 1 MODIFIED — novo role)
-- docs/decisions.md       (1 ADDED — ADR-007)
-- docs/domain.md          (0 mudanças)
-
-Possivelmente órfãos (NÃO removidos — revisão manual):
-  - docs/apiContracts.md: endpoint `/legacy/foo` não aparece em PRD+TRD novos
-    (pode ser de outra feature; deletar manualmente se confirmado deprecated)
-
-Validação: passed / N issues
-```
-
-## Erros
-
-| Erro | Ação |
-|------|------|
-| Status != `dev_done` (auto) nem >= `design_done` (manual) | Parar — pedir rodar /sf-dev ou /sf-design primeiro |
-| `docs/` não existe | Parar — explicar que `/sf-design` em first-run cria docs/ (feature só atualiza) |
-| PRD+TRD sem nada novo vs docs/ | Marcar `done` (legítimo — feature sem impacto cross-feature) |
-| Elemento MODIFIED não encontrado no doc | Converter pra ADDED + reportar (doc estava desatualizado) |
-| Referências quebradas detectadas | Reportar, não bloqueia |
-
-## Uso automático (pelo `/sf-dev`)
-
-`/sf-dev` chama `/sf-merge-docs` automaticamente ao final de feature (não first-run):
-
-- Condição: `status=dev_done` E `first_run=false` E (`prd_aprovado=true` OU `trd_aprovado=true`)
-- Rodado inline, sem nova interação
-- Falha em `/sf-merge-docs` não derruba `/sf-dev` — apenas reporta; user pode re-rodar manualmente
-
-## Uso manual
-
-Rodar `/sf-merge-docs $ARGUMENTS` quando:
-- `/sf-dev` falhou e você quer sincronizar docs/ com o que já foi aprovado
-- Fez edição direta em PRD/TRD aprovados e quer propagar pra docs/
-- Quer forçar um re-merge (idempotente — não duplica)
+
+# /sf-merge-docs $ARGUMENTS
+
+Skill atômica pós-dev. Aplica as decisões de **PRD + TRD aprovados** em `docs/` pra manter a síntese cross-feature sincronizada com o estado do sistema.
+`$ARGUMENTS` = nome do scope (ex: `feat_cadastro_cliente`).
+
+Chamado automaticamente pelo `/sf-dev` ao final. Re-executável manualmente quando precisa.
+
+> **Mudança v3 → v4**: antes aplicava `SDD §11 Delta Specs` (mecanismo OpenSpec).
+> Agora lê **PRD + TRD aprovados diretamente** e infere o delta comparando com
+> o estado atual de `docs/` (diff semântico). SDD não existe mais em v4.
+
+## Agente: Integrator (Opus)
+
+Em v4 promovido de Sonnet → Opus: diff semântico PRD/TRD ↔ docs/ exige reasoning
+de maior nível que o antigo "aplicar §11 explícito". Meticuloso com consistência.
+Merge idempotente — re-aplicar os mesmos docs source não duplica conteúdo.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `$ARGUMENTS` informado | Parar |
+| 2 | `.context.md` com status `dev_done` (uso auto no /sf-dev) OU `design_done` a mais (uso manual) | Se anterior → "Rode /sf-design primeiro" |
+| 3 | Pelo menos PRD.md OU TRD.md existe e está aprovado | Parar — "Nenhum doc source aprovado pra mergear" |
+| 4 | `docs/` populado (veio de first-run anterior) | Parar — "/sf-design com first_run=true é quem cria docs/" |
+
+> `/sf-merge-docs` **só se aplica a features**, não a first-run. Em first-run, é o
+> próprio `/sf-design` que cria `docs/` a partir de PRD+TRD — não há o que mergear.
+
+## Passos
+
+### 1. Snapshot do estado atual de docs/
+
+Ler `docs/{architecture,domain,conventions,apiContracts,decisions}.md`.
+Indexar por elementos (tabelas, endpoints, ADRs, papéis, env vars...) pra diff.
+
+### 2. Extrair elementos-destino do PRD e TRD aprovados
+
+| Fonte (PRD/TRD) | Elemento | Destino em docs/ |
+|-----------------|----------|------------------|
+| TRD §1.1 Stack | Nova tecnologia / versão | `architecture.md` §Stack |
+| TRD §1.2 Arquitetura | Novo container / padrão | `architecture.md` §Containers/Padrões |
+| TRD §1.3 Ambientes | Novo ambiente / mudança | `architecture.md` §Ambientes |
+| TRD §1.4 Deploy | Mudança na estratégia | `architecture.md` §Deploy |
+| TRD §4 §Área-DB | Nova tabela / índice / FK | `domain.md` §Catálogo de Tabelas |
+| TRD §2.1 Endpoints | Novo endpoint | `apiContracts.md` §Catálogo |
+| TRD §7.1 Auth | Mudança em auth | `conventions.md` §Autenticação |
+| TRD §7.2 Autorização | Novo papel / permissão | `conventions.md` §Autorização |
+| TRD §7.3 LGPD | Novo dado pessoal | `conventions.md` §LGPD |
+| TRD §7.4 Rate limit | Nova categoria | `conventions.md` §Rate Limiting |
+| TRD §5.3 Env vars | Nova variável | `conventions.md` §Variáveis de Ambiente |
+| TRD §6 Integrações | Novo sistema externo | `domain.md` §Integrações Externas |
+| TRD §9 ADRs | Nova decisão | `decisions.md` (append-only, imutável) |
+| PRD §2 Atores | Novo papel/persona | `domain.md` §Usuários e Papéis |
+| PRD §5 RNs | Nova regra de negócio | (não vai pra docs/ — fica em specs/{nome}/contracts.md) |
+
+> **Regra**: PRD alimenta poucas seções de `docs/` (só atores e alto-nível).
+> O grosso vem do TRD — `docs/` é síntese técnica + negócio cross-feature.
+
+### 3. Diff semântico: calcular ADDED / MODIFIED / REMOVED
+
+Pra cada elemento-destino extraído (passo 2), comparar com snapshot (passo 1):
+
+| Resultado | Condição | Ação |
+|-----------|----------|------|
+| ADDED | Elemento não existe em docs/ | Adicionar na seção apropriada |
+| MODIFIED | Elemento existe mas mudou (nome igual, valor diferente) | Atualizar campos |
+| UNCHANGED | Elemento existe e está igual | Skip (idempotente) |
+| REMOVED | Elemento estava em docs/ mas não aparece em PRD+TRD aprovados | **NÃO remover** — apenas registrar no output como "possivelmente orfão" |
+
+> **Conservadorismo em REMOVED**: PRD/TRD falam só da feature atual. Algo que
+> "não aparece" pode ser de outra feature (que continua válida). NUNCA deletar
+> automaticamente. Reportar e deixar remoção manual.
+
+### 4. Aplicar ADDED e MODIFIED
+
+- Localizar seção apropriada no doc destino
+- Preservar estrutura do template (não quebrar tabelas)
+- ADRs em `decisions.md`: SEMPRE append; ADR com status=aceita é imutável
+- Registrar cada mudança em changelog do doc afetado
+
+### 5. Changelog em cada doc afetado
+
+Adicionar linha no `## Changelog` do doc:
+
+```markdown
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+| {{ISO_DATE}} | $ARGUMENTS | ADDED | Endpoint POST /api/v1/users |
+| {{ISO_DATE}} | $ARGUMENTS | MODIFIED | Matriz de permissões: novo role `manager` |
+```
+
+### 6. Validar consistência cross-doc
+
+- Referências quebradas (endpoint do apiContracts referencia tabela que não existe em domain) → reportar
+- Papel novo em conventions mas não aparece em matriz de autorização → reportar
+- ADR substituída mas ainda referenciada → reportar
+
+Validação reporta, não bloqueia. Usuário decide se resolve manualmente.
+
+### 7. Atualizar status
+
+```yaml
+status: "done"
+ultima_skill: "/sf-merge-docs"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+### 8. Saída obrigatória
+
+```
+/sf-merge-docs $ARGUMENTS — completo
+
+docs/ sincronizado com PRD + TRD aprovados:
+- docs/architecture.md    (2 ADDED, 0 MODIFIED)
+- docs/apiContracts.md    (3 ADDED, 1 MODIFIED)
+- docs/conventions.md     (0 ADDED, 1 MODIFIED — novo role)
+- docs/decisions.md       (1 ADDED — ADR-007)
+- docs/domain.md          (0 mudanças)
+
+Possivelmente órfãos (NÃO removidos — revisão manual):
+  - docs/apiContracts.md: endpoint `/legacy/foo` não aparece em PRD+TRD novos
+    (pode ser de outra feature; deletar manualmente se confirmado deprecated)
+
+Validação: passed / N issues
+```
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| Status != `dev_done` (auto) nem >= `design_done` (manual) | Parar — pedir rodar /sf-dev ou /sf-design primeiro |
+| `docs/` não existe | Parar — explicar que `/sf-design` em first-run cria docs/ (feature só atualiza) |
+| PRD+TRD sem nada novo vs docs/ | Marcar `done` (legítimo — feature sem impacto cross-feature) |
+| Elemento MODIFIED não encontrado no doc | Converter pra ADDED + reportar (doc estava desatualizado) |
+| Referências quebradas detectadas | Reportar, não bloqueia |
+
+## Uso automático (pelo `/sf-dev`)
+
+`/sf-dev` chama `/sf-merge-docs` automaticamente ao final de feature (não first-run):
+
+- Condição: `status=dev_done` E `first_run=false` E (`prd_aprovado=true` OU `trd_aprovado=true`)
+- Rodado inline, sem nova interação
+- Falha em `/sf-merge-docs` não derruba `/sf-dev` — apenas reporta; user pode re-rodar manualmente
+
+## Uso manual
+
+Rodar `/sf-merge-docs $ARGUMENTS` quando:
+- `/sf-dev` falhou e você quer sincronizar docs/ com o que já foi aprovado
+- Fez edição direta em PRD/TRD aprovados e quer propagar pra docs/
+- Quer forçar um re-merge (idempotente — não duplica)

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

@@ -1,152 +1,152 @@
-
-# /sf-plan $ARGUMENTS
-
-Skill atômica de planejamento. Lê **PRD + TRD + specs/{nome}/** e gera
-`specs/{nome}/tasks.md` (arquivo único) + `workspace/Output/{nome}/Progresso.md`.
-`$ARGUMENTS` = nome do scope (ex: `app_barbearia`, `feat_cadastro_cliente`).
-
-## Agente: Planner (Opus)
-
-Metódico e exaustivo. Cada task auto-contida. Prioriza ordem correta.
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | $ARGUMENTS informado | Parar |
-| 2 | `.context.md` com status `design_done` | Se anterior → "/sf-design primeiro". Se posterior → "Tasks já geradas" |
-| 3 | Se `prd_existe=true`: PRD.md existe e `prd_aprovado=true` | Parar (não deveria passar pelo /sf-design, mas defensivo) |
-| 4 | Se `trd_existe=true`: TRD.md existe e `trd_aprovado=true` | Parar |
-| 5 | `specs/{nome}/{contracts,scenarios}.md` existem (projeções do /sf-design) | Parar → "/sf-design não gerou projeções — re-rode" |
-
-## Passos
-
-### 1. Ler contexto
-
-- `workspace/Output/{nome}/PRD.md` (se prd_existe) + `TRD.md` (se trd_existe) — fontes
-- `specs/{nome}/{brief,contracts,scenarios}.md` (projeções já geradas pelo /sf-design)
-- `projetos.yaml` + `docs/` (architecture, domain, conventions) + `.github/rules.md`
-- Template `.github/templates/specs/tasks.template.md`
-
-### 2. Identificar fases de entrega
-
-Ler **PRD §10 (Fases de Entrega)** — cada fase vira um agrupamento de tasks:
-
-- Fases são sequenciais: Fase 2 depende de Fase 1 concluída
-- Cada fase tem entregável + critério de done
-- O `/sf-dev` pode rodar por fase: `/sf-dev feat_nome --fase 1`
-
-**Se scope não tem PRD** (puro-técnico): toda task vai pra **Fase 1**. Não há
-fases de entrega de produto — é bootstrap/infra em uma leva só.
-
-### 3. Identificar áreas (dinâmicas, vêm do TRD)
-
-Ler `.context.md → areas_tocadas` (populado pelo /sf-design a partir dos GATEs do TRD).
-
-| Seção do TRD | Área |
-|--------------|------|
-| §2 §Área-Backend (GATE=SIM) | BACK |
-| §3 §Área-Frontend (GATE=SIM) | FRONT |
-| §4 §Área-DB (GATE=SIM) | DB |
-| §5 §Área-Infra (GATE=SIM) | INFRA |
-
-Áreas com GATE=NÃO não geram tasks nessa área. Se o scope tem apenas PRD (raríssimo
-caso puro-produto sem TRD): área FRONT derivada de PRD §7 Telas.
-
-**INFRA em first-run** (detectado via `first_run=true` no .context):
-
-```
-- [ ] INFRA-001: Validar ambiente local + setup repos (projetos.yaml)
-- [ ] INFRA-002: Docker-compose dev (só dependências) + Dockerfiles prod
-- [ ] INFRA-003: Hello world — subir stack completa e validar
-```
-
-INFRA-001 sempre a PRIMEIRA; INFRA-003 sempre a ÚLTIMA da Fase 1 (validação).
-
-### 4. Gerar `specs/{nome}/tasks.md` (arquivo único)
-
-Tabela única com coluna `Área` diferenciando:
-
-```markdown
-| ID | Área | Fase | Tam | Título | Repo | Arquivos | Depende de | Ref TRD | Ref CA |
-|----|------|------|-----|--------|------|----------|-----------|---------|--------|
-| DB-001 | DB | 1 | S | Migration clientes | api | src/db/migrations/... | — | TRD §4.1 | — |
-| BACK-001 | BACK | 1 | M | Endpoint POST /clientes | api | src/routes/... | DB-001 | TRD §2.1 | CA-001 |
-```
-
-**Regras** (ver `.github/templates/specs/tasks.template.md` pra detalhes):
-
-- Cada task é atômica — coder lê `specs/{nome}/` + task, nada mais
-- **Repo obrigatório** — consultar `projetos.yaml`. Caminhos relativos ao repo.
-- Área é COLUNA, não arquivo (DB, BACK, FRONT, INFRA, MOBILE...)
-- Tamanhos: S (≤2h), M (≤4h), L (≤2 dias). L → considerar dividir (INVEST: Small)
-- IDs sequenciais por área, nunca reutilizar
-- Dependências cross-area permitidas
-- `Ref TRD`: seção do TRD (ex: `§2.1`, `§4.2`) — obrigatório quando TRD existe
-- `Ref CA`: ID do CA em `specs/{nome}/scenarios.md` ou `—`
-- Ordenar por Fase → Área → ID (visual)
-
-**Tasks L**: preencher bloco "Done When — {TASK-ID}" abaixo da tabela com 3-5
-bullets verificáveis.
-
-### 5. Gerar `workspace/Output/{nome}/Progresso.md` (tracking)
-
-Progresso.md vive em **workspace/Output** (tracking de execução, não spec).
-
-- Resumo Área × Fase com contagem (derivado de `tasks.md`)
-- Ordem de execução com paralelismos
-- Checklist pós-conclusão (já coberto pelo /sf-merge-docs automático no fim do /sf-dev)
-
-**Regra**: status das tasks vive SÓ em Progresso.md. `tasks.md` é o plano imutável.
-
-### 6. Atualizar `.context.md`
-
-```yaml
-status: "plan_done"
-ultima_skill: "/sf-plan"
-atualizado_em: "{{ISO_DATETIME}}"
-```
-
-### 7. Publicar Progresso no backend (se `sfw.config.yml` existe)
-
-Chamar `/sf-publish $ARGUMENTS Progresso`. Respeita `mode` de cada target.
-
-**Nota**: `tasks.md`, `specs/*`, `docs/*`, `projetos.yaml` são **LOCAL ONLY** — `/sf-publish`
-nunca toca neles. Apenas PRD/TRD/Progresso vão pro Confluence.
-
-### 8. Saída obrigatória
-
-```
-/sf-plan $ARGUMENTS — completo
-
-Artefatos locais:
-  - specs/$ARGUMENTS/tasks.md ({N} tasks em {F} fases, áreas: [{lista}])
-  - workspace/Output/$ARGUMENTS/Progresso.md
-
-Publish:
-  - {target-name}: Progresso: {{status}}
-  OU
-  - SKIPPED (no sfw.config.yml)
-
-Próximo passo:
-  /sf-dev $ARGUMENTS              ← implementa tudo
-  /sf-dev $ARGUMENTS --fase 1     ← só a primeira fase (RECOMENDADO)
-```
-
-## Saídas
-
-- `specs/{nome}/tasks.md` — plano (tabela única)
-- `workspace/Output/{nome}/Progresso.md` — tracking
-
-## Rastreabilidade
-
-Cada task gerada deve ter:
-- **Ref TRD** (se TRD existe): seção do TRD que motivou — garante que nada do TRD
-  fica sem task correspondente
-- **Ref CA** (se aplicável): garante que cada CA em `scenarios.md` tem pelo menos
-  1 task que o satisfaz
-
-Validação final antes de terminar:
-- Todo endpoint do TRD §2.1 tem task BACK correspondente? ✓
-- Toda tabela/migration do TRD §4 tem task DB correspondente? ✓
-- Todo CA em `scenarios.md` tem task Ref CA correspondente (ou justificativa de why not)? ✓
+
+# /sf-plan $ARGUMENTS
+
+Skill atômica de planejamento. Lê **PRD + TRD + specs/{nome}/** e gera
+`specs/{nome}/tasks.md` (arquivo único) + `workspace/Output/{nome}/Progresso.md`.
+`$ARGUMENTS` = nome do scope (ex: `app_barbearia`, `feat_cadastro_cliente`).
+
+## Agente: Planner (Opus)
+
+Metódico e exaustivo. Cada task auto-contida. Prioriza ordem correta.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | $ARGUMENTS informado | Parar |
+| 2 | `.context.md` com status `design_done` | Se anterior → "/sf-design primeiro". Se posterior → "Tasks já geradas" |
+| 3 | Se `prd_existe=true`: PRD.md existe e `prd_aprovado=true` | Parar (não deveria passar pelo /sf-design, mas defensivo) |
+| 4 | Se `trd_existe=true`: TRD.md existe e `trd_aprovado=true` | Parar |
+| 5 | `specs/{nome}/{contracts,scenarios}.md` existem (projeções do /sf-design) | Parar → "/sf-design não gerou projeções — re-rode" |
+
+## Passos
+
+### 1. Ler contexto
+
+- `workspace/Output/{nome}/PRD.md` (se prd_existe) + `TRD.md` (se trd_existe) — fontes
+- `specs/{nome}/{brief,contracts,scenarios}.md` (projeções já geradas pelo /sf-design)
+- `projetos.yaml` + `docs/` (architecture, domain, conventions) + `.github/rules.md`
+- Template `.github/templates/specs/tasks.template.md`
+
+### 2. Identificar fases de entrega
+
+Ler **PRD §10 (Fases de Entrega)** — cada fase vira um agrupamento de tasks:
+
+- Fases são sequenciais: Fase 2 depende de Fase 1 concluída
+- Cada fase tem entregável + critério de done
+- O `/sf-dev` pode rodar por fase: `/sf-dev feat_nome --fase 1`
+
+**Se scope não tem PRD** (puro-técnico): toda task vai pra **Fase 1**. Não há
+fases de entrega de produto — é bootstrap/infra em uma leva só.
+
+### 3. Identificar áreas (dinâmicas, vêm do TRD)
+
+Ler `.context.md → areas_tocadas` (populado pelo /sf-design a partir dos GATEs do TRD).
+
+| Seção do TRD | Área |
+|--------------|------|
+| §2 §Área-Backend (GATE=SIM) | BACK |
+| §3 §Área-Frontend (GATE=SIM) | FRONT |
+| §4 §Área-DB (GATE=SIM) | DB |
+| §5 §Área-Infra (GATE=SIM) | INFRA |
+
+Áreas com GATE=NÃO não geram tasks nessa área. Se o scope tem apenas PRD (raríssimo
+caso puro-produto sem TRD): área FRONT derivada de PRD §7 Telas.
+
+**INFRA em first-run** (detectado via `first_run=true` no .context):
+
+```
+- [ ] INFRA-001: Validar ambiente local + setup repos (projetos.yaml)
+- [ ] INFRA-002: Docker-compose dev (só dependências) + Dockerfiles prod
+- [ ] INFRA-003: Hello world — subir stack completa e validar
+```
+
+INFRA-001 sempre a PRIMEIRA; INFRA-003 sempre a ÚLTIMA da Fase 1 (validação).
+
+### 4. Gerar `specs/{nome}/tasks.md` (arquivo único)
+
+Tabela única com coluna `Área` diferenciando:
+
+```markdown
+| ID | Área | Fase | Tam | Título | Repo | Arquivos | Depende de | Ref TRD | Ref CA |
+|----|------|------|-----|--------|------|----------|-----------|---------|--------|
+| DB-001 | DB | 1 | S | Migration clientes | api | src/db/migrations/... | — | TRD §4.1 | — |
+| BACK-001 | BACK | 1 | M | Endpoint POST /clientes | api | src/routes/... | DB-001 | TRD §2.1 | CA-001 |
+```
+
+**Regras** (ver `.github/templates/specs/tasks.template.md` pra detalhes):
+
+- Cada task é atômica — coder lê `specs/{nome}/` + task, nada mais
+- **Repo obrigatório** — consultar `projetos.yaml`. Caminhos relativos ao repo.
+- Área é COLUNA, não arquivo (DB, BACK, FRONT, INFRA, MOBILE...)
+- Tamanhos: S (≤2h), M (≤4h), L (≤2 dias). L → considerar dividir (INVEST: Small)
+- IDs sequenciais por área, nunca reutilizar
+- Dependências cross-area permitidas
+- `Ref TRD`: seção do TRD (ex: `§2.1`, `§4.2`) — obrigatório quando TRD existe
+- `Ref CA`: ID do CA em `specs/{nome}/scenarios.md` ou `—`
+- Ordenar por Fase → Área → ID (visual)
+
+**Tasks L**: preencher bloco "Done When — {TASK-ID}" abaixo da tabela com 3-5
+bullets verificáveis.
+
+### 5. Gerar `workspace/Output/{nome}/Progresso.md` (tracking)
+
+Progresso.md vive em **workspace/Output** (tracking de execução, não spec).
+
+- Resumo Área × Fase com contagem (derivado de `tasks.md`)
+- Ordem de execução com paralelismos
+- Checklist pós-conclusão (já coberto pelo /sf-merge-docs automático no fim do /sf-dev)
+
+**Regra**: status das tasks vive SÓ em Progresso.md. `tasks.md` é o plano imutável.
+
+### 6. Atualizar `.context.md`
+
+```yaml
+status: "plan_done"
+ultima_skill: "/sf-plan"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+### 7. Publicar Progresso no backend (se `sfw.config.yml` existe)
+
+Chamar `/sf-publish $ARGUMENTS Progresso`. Respeita `mode` de cada target.
+
+**Nota**: `tasks.md`, `specs/*`, `docs/*`, `projetos.yaml` são **LOCAL ONLY** — `/sf-publish`
+nunca toca neles. Apenas PRD/TRD/Progresso vão pro Confluence.
+
+### 8. Saída obrigatória
+
+```
+/sf-plan $ARGUMENTS — completo
+
+Artefatos locais:
+  - specs/$ARGUMENTS/tasks.md ({N} tasks em {F} fases, áreas: [{lista}])
+  - workspace/Output/$ARGUMENTS/Progresso.md
+
+Publish:
+  - {target-name}: Progresso: {{status}}
+  OU
+  - SKIPPED (no sfw.config.yml)
+
+Próximo passo:
+  /sf-dev $ARGUMENTS              ← implementa tudo
+  /sf-dev $ARGUMENTS --fase 1     ← só a primeira fase (RECOMENDADO)
+```
+
+## Saídas
+
+- `specs/{nome}/tasks.md` — plano (tabela única)
+- `workspace/Output/{nome}/Progresso.md` — tracking
+
+## Rastreabilidade
+
+Cada task gerada deve ter:
+- **Ref TRD** (se TRD existe): seção do TRD que motivou — garante que nada do TRD
+  fica sem task correspondente
+- **Ref CA** (se aplicável): garante que cada CA em `scenarios.md` tem pelo menos
+  1 task que o satisfaz
+
+Validação final antes de terminar:
+- Todo endpoint do TRD §2.1 tem task BACK correspondente? ✓
+- Toda tabela/migration do TRD §4 tem task DB correspondente? ✓
+- Todo CA em `scenarios.md` tem task Ref CA correspondente (ou justificativa de why not)? ✓