spec-first-copilot 0.1.0

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

@@ -0,0 +1,130 @@
+---
+name: sf-feature
+description: |
+  Pipeline de feature. Cria contexto PRD, chama /sf-extract, para no checkpoint.
+  Trigger: /sf-feature
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-04-08
+---
+
+# Skill: /sf-feature
+
+> Orquestrador de feature. Cria contexto PRD, chama `/extract` e para no checkpoint de aprovação.
+
+## Tipo
+Orquestrador (primeira etapa do pipeline de feature)
+
+## Uso
+```
+/sf-feature <nome>
+```
+Exemplo: `/sf-feature feat_cadastro_cliente`
+
+### Convenção de nomes
+- Features: `feat_nome_descritivo`
+- Bugs: `bug_nome_descritivo`
+- Tasks técnicas: `task_nome_descritivo`
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | Argumento `nome` foi informado | Parar → "Informe o nome da feature. Ex: /sf-feature feat_cadastro_cliente" |
+| 2 | `docs/PM/{nome}/` existe | Parar → "Crie a pasta docs/PM/{nome}/ e adicione seus insumos" |
+| 3 | Pasta contém pelo menos 1 arquivo (ignorar .gitkeep) | Parar → "Adicione insumos na pasta (aceitos: .md, .txt, .sql, .xml, .html, .json, .csv, .png, .jpg, .pdf — qualquer formato)" |
+| 4 | `docs/Estrutura/` está populado (setup já executado) | Parar → "Execute /sf-setup-projeto antes de criar features" |
+| 5 | `.context.md` não existe ou status é `not_started` | Se existe com status avançado → "Feature já em andamento (status: {status}). Para re-extrair, use /sf-extract {nome}" |
+
+## Passos
+
+### 1. Carregar contexto do projeto
+Ler `docs/Estrutura/` para entender a arquitetura, stack, modelo de dados e convenções existentes. Esse contexto será passado ao `/extract`.
+
+### 2. Criar estrutura
+```
+docs/Desenvolvimento/{nome}/
+├── .context.md        ← criado agora
+└── (PRD.md será criado pelo /extract)
+```
+
+### 3. Criar `.context.md`
+```yaml
+---
+nome: "{nome}"
+tipo: "feature"
+documento: "PRD"
+pm_path: "docs/PM/{nome}/"
+status: "not_started"
+ultima_skill: "/sf-feature"
+atualizado_em: "{{ISO_DATETIME}}"
+---
+```
+
+### 4. Sugerir /sf-discovery (RECOMENDADO)
+
+Antes de extrair, perguntar ao usuário:
+```
+📋 Insumos encontrados em docs/PM/{nome}/.
+
+Recomendo rodar /sf-discovery antes da extração para:
+  - Análise profunda dos insumos
+  - Identificar gaps e contradições
+  - Validar entendimento com você
+
+Quer rodar /sf-discovery docs/PM/{nome}/ agora? (s/n)
+  Se SIM → rodar discovery, salvar discovery.md, depois continuar com extract
+  Se NÃO → pular direto para /sf-extract
+```
+
+Se o usuário aceitar:
+- Rodar `/sf-discovery docs/PM/{nome}/`
+- Aguardar conclusão — discovery.md salvo em `docs/Desenvolvimento/{nome}/`
+- Continuar para o passo 5
+
+### 5. Chamar `/sf-extract {nome}`
+O `/sf-extract` lê os insumos + discovery.md (se existir), gera o PRD e atualiza status para `extract_done`.
+
+### 6. CHECKPOINT — Parar e informar o usuário
+Mensagem ao usuário:
+```
+✅ PRD gerado em docs/Desenvolvimento/{nome}/PRD.md
+
+Revise o documento. Quando estiver satisfeito, execute:
+  /sf-design {nome}
+
+Se precisar adicionar mais insumos, coloque na pasta docs/PM/{nome}/
+e execute:
+  /sf-extract {nome}
+```
+
+**O orquestrador encerra aqui.** O restante do pipeline é responsabilidade do usuário chamar as skills atômicas na ordem:
+1. `/sf-design {nome}` (pergunta aprovação → gera SDD)
+2. `/sf-plan {nome}` (gera tasks + Progresso)
+3. `/sf-dev {nome}` (executa tasks)
+4. `/sf-merge-delta {nome}` (aplica Delta Specs em docs/Estrutura/)
+
+## Saídas diretas desta skill
+- `docs/Desenvolvimento/{nome}/.context.md`
+- `docs/Desenvolvimento/{nome}/PRD.md` (via /extract)
+- `docs/Desenvolvimento/{nome}/.extract-log.md` (via /extract)
+
+## Saídas indiretas (skills subsequentes)
+- `sdd.md` (via /design)
+- `*_tasks.md` + `Progresso.md` (via /plan)
+- `docs/Estrutura/` atualizado (via /sf-merge-delta após /dev)
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| Nome não informado | Parar, mostrar exemplo de uso |
+| PM/{nome}/ não existe | Parar, instruir criação |
+| PM/{nome}/ vazio | Parar, listar formatos aceitos |
+| Estrutura/ não populado | Parar, sugerir /sf-setup-projeto |
+| Pipeline já iniciado | Mostrar status atual, sugerir /sf-extract para re-extração ou skill correspondente ao status |
+
+## Notas
+- Diferente do `/sf-setup-projeto`, pode ser executado **múltiplas vezes** (uma por feature)
+- O contexto de `docs/Estrutura/` é carregado para que o `/extract` gere um PRD coerente com a arquitetura existente
+- Após `/dev`, o `/merge-delta` atualiza `docs/Estrutura/` com as mudanças da feature

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

@@ -0,0 +1,142 @@
+---
+name: sf-merge-delta
+description: |
+  Delta Specs. Aplica mudanças do SDD em docs/Estrutura/.
+  Trigger: /sf-merge-delta
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-04-08
+---
+
+# Skill: /sf-merge-delta
+
+> Skill atômica pós-dev. Aplica Delta Specs do SDD em docs/Estrutura/.
+> Última etapa do pipeline de feature — não se aplica a setup.
+
+## Tipo
+Atômica — Single-agent
+
+## Uso
+```
+/sf-merge-delta <nome>
+```
+Exemplo: `/sf-merge-delta feat_cadastro_cliente`
+
+---
+
+## Agente
+
+| Campo | Valor |
+|-------|-------|
+| **Papel** | Integrador de documentação — aplica mudanças incrementais mantendo consistência global |
+| **Modelo** | Sonnet |
+| **Comportamento** | Meticuloso com consistência. Aplica apenas o que o Delta Specs diz — não infere mudanças adicionais. Cada alteração gera entrada no changelog. Se há conflito com conteúdo existente, para e pede resolução. |
+
+---
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | Argumento `nome` foi informado | Parar → "Informe o nome. Ex: /sf-merge-delta feat_cadastro_cliente" |
+| 2 | `.context.md` existe com status `dev_done` | Se anterior → "Execute /sf-dev {nome} primeiro" |
+| 3 | `.context.md` tipo é `feature` (não `setup`) | Parar → "Setup não usa merge-delta — docs/Estrutura/ foi criado diretamente pelo /sf-dev" |
+| 4 | `sdd.md` existe com §11 Delta Specs preenchida | Parar → "Delta Specs não encontrada no SDD" |
+| 5 | `docs/Estrutura/` está populado | Parar → "docs/Estrutura/ vazio — execute /sf-setup-projeto primeiro" |
+
+## Passos
+
+### 1. Ler Delta Specs
+Ler `sdd.md` §11 e classificar cada delta:
+
+| Tipo | Significado | Exemplo |
+|------|------------|---------|
+| **ADDED** | Elemento novo no sistema | Nova tabela `clientes`, novo endpoint POST /api/v1/clientes |
+| **MODIFIED** | Elemento existente alterado | Tabela `usuarios` recebe coluna `telefone` |
+| **REMOVED** | Elemento removido do sistema | Endpoint DELETE /api/v1/legacy removido |
+
+### 2. Mapear deltas para docs alvo
+Cada delta afeta um ou mais docs em `docs/Estrutura/`:
+
+| Elemento | Doc alvo |
+|----------|----------|
+| Tabelas, colunas, índices | `Modelo_Dados.md` |
+| Endpoints, contratos | `API.md` |
+| Decisões de arquitetura | `Arquitetura.md` + `ADRs.md` |
+| Mudanças de infra | `Infraestrutura.md` |
+| Mudanças de segurança | `Seguranca.md` |
+| Mudanças de stack | `Stack.md` |
+| Mudanças de visão/escopo | `Visao.md` |
+
+### 3. Aplicar cada delta
+Para cada delta, no doc alvo:
+
+**ADDED:**
+- Adicionar novo conteúdo na seção apropriada do doc
+- Registrar no changelog
+
+**MODIFIED:**
+- Localizar elemento existente no doc
+- Aplicar a modificação
+- Registrar no changelog
+
+**REMOVED:**
+- Localizar elemento existente no doc
+- Remover ou marcar como deprecated (conforme contexto)
+- Registrar no changelog
+
+**Formato do changelog** (no final de cada doc afetado):
+```markdown
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+| 2026-04-08 | feat_cadastro_cliente | ADDED | Tabela `clientes`, tabela `clientes_enderecos` |
+| 2026-04-08 | feat_cadastro_cliente | ADDED | POST/GET /api/v1/clientes |
+```
+
+### 4. Validar consistência
+Após todas alterações:
+- Verificar que docs não ficaram com referências quebradas
+- Verificar que REMOVED não deixou referências órfãs em outros docs
+- Se inconsistência detectada → reportar ao usuário, não corrigir automaticamente
+
+### 5. Atualizar status
+- `.context.md` → status: `done`
+- `docs/Desenvolvimento/progresso.md` → feature marcada como concluída
+- Informar ao usuário:
+  ```
+  ✅ Delta Specs aplicadas em docs/Estrutura/
+  
+  Docs atualizados:
+  - Modelo_Dados.md — ADDED: tabelas clientes, clientes_enderecos
+  - API.md — ADDED: endpoints POST/GET /api/v1/clientes
+  
+  Feature {nome} concluída.
+  ```
+
+---
+
+## Saídas
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `docs/Estrutura/*.md` | Docs globais atualizados com deltas da feature |
+| `progresso.md` (global) | Feature marcada como concluída |
+| `.context.md` | Status: `done` |
+
+## Pós-condições
+- `docs/Estrutura/` reflete o estado real do sistema
+- Cada mudança rastreável: changelog → feature → SDD → PRD → insumo
+- Feature completamente concluída
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| Nome não informado | Parar, mostrar exemplo |
+| Status não é dev_done | Parar, sugerir /sf-dev |
+| Tipo é setup | Parar, informar que setup não usa merge-delta |
+| Delta Specs vazia | Informar (legítimo em refactors internos), marcar como done |
+| Elemento MODIFIED/REMOVED não encontrado no doc alvo | Parar, reportar conflito — pedir resolução manual |
+| Inconsistência entre docs após merge | Parar, listar inconsistências |

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

@@ -0,0 +1,120 @@
+---
+name: sf-pausar
+description: |
+  Encerrar sessão. Salva estado, atualiza napkin, gera retomada.md.
+  Trigger: /sf-pausar
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-04-08
+---
+
+# Skill: /sf-pausar
+
+> Encerra a sessão de trabalho de forma organizada.
+> Consolida estado, atualiza memória, gera ponto de retomada para a próxima sessão.
+
+## Tipo
+Utilitária — roda a qualquer momento
+
+## Uso
+```
+/sf-pausar
+```
+
+---
+
+## Passos
+
+### 1. Levantar estado atual de cada feature/setup
+
+Para cada `.context.md` em `docs/Desenvolvimento/*/`:
+- Ler status atual
+- Ler Progresso.md (se existir) → % concluído, fase atual
+- Identificar tasks em andamento (`- [ ]` com dependências resolvidas)
+
+### 2. Verificar working tree dos repos
+
+Para cada repo em `projetos/`:
+```bash
+cd projetos/{repo}
+git status --short
+git log --oneline -3
+```
+- Listar mudanças não commitadas
+- Listar branches ativas
+- Se há working tree sujo → avisar (sugerir commit antes de pausar)
+
+### 3. Atualizar `.ai/memory/napkin.md`
+
+Adicionar/atualizar seção `## Sessão Atual` com:
+- Data da sessão
+- O que foi feito (tasks concluídas, fases entregues)
+- O que estava em andamento (task atual, bloqueios)
+- Decisões tomadas durante a sessão
+- Armadilhas encontradas (se houver novos aprendizados)
+
+### 4. Gerar resumo de retomada
+
+Criar/atualizar `docs/Desenvolvimento/retomada.md`:
+
+```markdown
+# Ponto de Retomada — {{DATA}}
+
+> Gerado pelo /sf-pausar. Leia este arquivo ao iniciar a próxima sessão.
+
+## Estado geral
+
+| Feature/Setup | Status | Fase atual | % | Próxima ação |
+|---------------|--------|------------|---|-------------|
+| {{nome}} | {{status}} | Fase {{N}} | {{%}} | {{ação}} |
+
+## Repos — estado do git
+
+| Repo | Branch ativa | Working tree | Último commit |
+|------|-------------|-------------|---------------|
+| {{repo}} | {{branch}} | limpo/sujo | {{commit msg}} |
+
+## O que estava em andamento
+
+- Task: {{AREA-NNN}} — {{descrição}}
+- Bloqueios: {{se houver}}
+- Decisões pendentes: {{se houver}}
+
+## Para retomar
+
+1. {{Passo 1 — ex: "Subir infra: docker compose up -d"}}
+2. {{Passo 2 — ex: "Continuar /sf-dev feat_mvp --fase 2"}}
+3. {{Passo 3 — ex: "Resolver ambiguidade X do PRD"}}
+
+## Aprendizados desta sessão
+
+- {{Decisão ou armadilha que vale registrar}}
+```
+
+### 5. Informar ao usuário
+
+```
+✅ Sessão encerrada. Estado salvo em:
+  - `.ai/memory/napkin.md` — memória atualizada
+  - `docs/Desenvolvimento/retomada.md` — ponto de retomada
+
+Para retomar na próxima sessão:
+  1. Ler retomada.md
+  2. Seguir os passos listados em "Para retomar"
+```
+
+---
+
+## Saídas
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `.ai/memory/napkin.md` | Sessão atual atualizada |
+| `docs/Desenvolvimento/retomada.md` | Ponto de retomada com estado completo |
+
+## Notas
+
+- Não modifica .context.md (o status da pipeline não muda ao pausar)
+- Não faz commit automático — se tem working tree sujo, avisa mas não força
+- Pode ser chamada a qualquer momento, não só no final do dia
+- O arquivo `retomada.md` é sobrescrito a cada /sf-pausar (é ponto atual, não histórico)

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

@@ -0,0 +1,178 @@
+---
+name: sf-plan
+description: |
+  Planejamento. Gera tasks por fase de entrega e área.
+  Trigger: /sf-plan
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-04-08
+---
+
+# Skill: /sf-plan
+
+> Skill atômica de planejamento. Lê SDD e gera tasks por área + Progresso.
+
+## Tipo
+Atômica — Single-agent
+
+## Uso
+```
+/sf-plan <nome>
+```
+Exemplo: `/sf-plan feat_cadastro_cliente`
+
+---
+
+## Agente
+
+| Campo | Valor |
+|-------|-------|
+| **Papel** | Planejador técnico — decompõe especificação em tasks atômicas, ordenadas e com dependências explícitas |
+| **Modelo** | Opus |
+| **Comportamento** | Metódico e exaustivo. Cada task deve ser auto-contida (coder lê SDD §N + task, nada mais). Prioriza ordem de execução correta sobre paralelismo. Nunca cria task sem referência ao SDD. |
+
+---
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | Argumento `nome` foi informado | Parar → "Informe o nome. Ex: /sf-plan feat_cadastro_cliente" |
+| 2 | `docs/Desenvolvimento/{nome}/.context.md` existe com status `design_done` | Se anterior → "Execute /sf-design {nome} primeiro". Se posterior → "Tasks já foram geradas (status: {status})" |
+| 3 | `sdd.md` existe na pasta | Parar → "SDD não encontrado. Execute /sf-design {nome}" |
+
+## Passos
+
+### 1. Ler contexto
+- Ler `.context.md` → validar status
+- Ler `sdd.md` completo
+- Ler `projetos.yaml` (manifesto de repos — mapeamento área → repo)
+- Ler `docs/Estrutura/` (Stack, Arquitetura — para convenções por área)
+- Ler `docs/Desenvolvimento/rules.md` (padrões de código, commit, branch)
+- Carregar template `docs/_templates/feature/tasks.template.md`
+
+### 2. Identificar fases de entrega
+Ler PRD §11 (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 e critério de done
+- O `/dev` pode rodar por fase: `/sf-dev feat_nome --fase 1`
+
+### 3. Identificar áreas afetadas (por fase)
+Para cada fase de entrega, mapear seções do SDD para áreas de tasks:
+
+| Seção do SDD | Área | Condição |
+|-------------|------|----------|
+| §3 Modelo de dados | BANCO | Se há entidades/migrations |
+| §5 Endpoints API | BACK | Se há endpoints definidos |
+| §6 Componentes e telas | FRONT | Se há UI especificada |
+| §8 Integrações externas | INFRA | Se há infra/serviços externos |
+| Outras | MOBILE, DEVOPS, etc. | Conforme necessidade do SDD |
+
+> **Nota**: Área DOC NÃO existe mais no setup. docs/Estrutura/ é gerado pelo /sf-design (passo 3).
+> DOC só aparece em features se houver necessidade explícita de documentação adicional.
+
+Áreas são **dinâmicas** — só cria o que o SDD exige. Não criar área vazia.
+
+**Área INFRA obrigatória no setup:**
+Sempre gerar estas tasks no setup (antes de qualquer código):
+```
+- [ ] INFRA-001: Validar e configurar ambiente local [M]
+  (detectar OS, instalar Docker/.NET/Node, verificar portas)
+- [ ] INFRA-002: Criar docker-compose.yml + Dockerfiles [M]
+- [ ] INFRA-003: Hello world — subir stack completa e validar [M]
+  (docker compose up, migrations, health check, frontend carrega)
+```
+INFRA-001 é a PRIMEIRA task executada no /sf-dev do setup (antes de BANCO, BACK, FRONT).
+INFRA-003 é a ÚLTIMA task (após tudo, como validação final).
+Setup só é `done` quando INFRA-003 passa.
+
+### 4. Gerar tasks por fase × área
+Para cada área identificada, gerar `{area}_tasks.md`.
+Tasks são agrupadas por **fase de entrega** (do PRD §11), não só por fase técnica.
+
+**Estrutura de cada task:**
+```markdown
+- [ ] **AREA-NNN**: Título descritivo [Tamanho]
+  - Fase: {{N}} — {{Nome da fase de entrega}}
+  - Repo: `{{nome_repo}}` (de projetos.yaml)
+  - Arquivos: `caminho/do/arquivo.ext` (relativo à raiz do repo)
+  - SDD: §N.N — Referência específica
+  - Depende: AREA-NNN (ou — se não depende)
+```
+
+**Regras de decomposição:**
+1. Cada task é **atômica** — implementável sem consultar nada além de SDD §N + task
+2. **Repo obrigatório** — consultar `projetos.yaml` para mapear área → repo. Caminhos de arquivo são relativos à raiz do repo
+3. Tamanhos realistas: **S** (<30min), **M** (30min-2h), **L** (2h+)
+4. Se uma task é L, avaliar se pode ser quebrada em M+S
+5. IDs sequenciais por área: BANCO-001, BANCO-002, BACK-001, BACK-002
+6. IDs nunca reutilizados — se uma task for removida, o ID é aposentado
+7. Dependências explícitas — inclusive cross-area (FRONT-004 depende BACK-003)
+8. Prioridades por fase: **P1** (bloqueia outros), **P2** (importante), **P3** (nice-to-have)
+
+**Organização em fases (sequenciais dentro da área):**
+
+| Área | Fases típicas (adaptar ao SDD) |
+|------|-------------------------------|
+| BANCO | Schema/Migrations → Índices/Constraints → Seeds |
+| BACK | Setup/Config → DTOs/Validações → Repository/Service → Controller → Testes |
+| FRONT | Setup/Rotas → Componentes base → Telas → Integração API → Polish/UX |
+| INFRA | Provisioning → Config → Deploy → Monitoramento |
+| DOC | Gerar docs/Estrutura/ a partir do TRD |
+
+### 5. Gerar `Progresso.md`
+Usando template `docs/_templates/feature/Progresso.template.md`:
+
+- Resumo por Área × Fase com contagem de tasks
+- Status por fase: ⬜ pendente | 🔄 em andamento | ✅ concluída
+- **Ordem de execução** com paralelismos:
+  ```
+  1. BANCO Fase 1 (Schema) — primeiro sempre
+  2. BANCO Fase 2 + BACK Fase 1 — podem paralelizar
+  3. BACK Fase 2-3 — sequencial
+  4. FRONT Fase 1-2 — pode iniciar após BACK Fase 3
+  ...
+  ```
+- Totais por área e geral
+- Checklist pós-conclusão (merge delta, atualizar progresso global, napkin)
+
+### 6. Atualizar progresso global
+Adicionar entrada em `docs/Desenvolvimento/progresso.md`:
+
+```markdown
+| {nome} | plan_done | BANCO: 0/N | BACK: 0/N | FRONT: 0/N |
+```
+
+### 7. Atualizar `.context.md`
+```yaml
+status: "plan_done"
+ultima_skill: "/sf-plan"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+---
+
+## Saídas
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `{area}_tasks.md` | 1 arquivo por área (dinâmico: banco_tasks.md, back_tasks.md, etc.) |
+| `Progresso.md` | Dashboard da feature com ordem de execução |
+| `progresso.md` (global) | Atualizado com nova feature |
+| `.context.md` | Atualizado com status `plan_done` |
+
+## Pós-condições
+- Cada task é auto-contida com referência ao SDD
+- Dependências resolvíveis (não há ciclos)
+- Ordem de execução definida no Progresso.md
+- Feature pronta para `/dev`
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| Nome não informado | Parar, mostrar exemplo |
+| Status não é design_done | Parar, sugerir skill correspondente |
+| SDD não encontrado | Parar, sugerir /sf-design |
+| SDD com seções vazias obrigatórias | Parar, listar o que falta — sugerir voltar ao /sf-design |
+| Dependência circular detectada | Parar, reportar o ciclo e sugerir reorganização |

package/templates/.github/skills/sf-setup-projeto/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: sf-setup-projeto
+description: |
+  Bootstrap do projeto. Cria contexto TRD, chama /sf-extract, para no checkpoint.
+  Trigger: /sf-setup-projeto
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-04-08
+---
+
+# Skill: /sf-setup-projeto
+
+> Orquestrador de bootstrap do projeto. Executa uma única vez.
+> Cria contexto TRD, chama `/extract` e para no checkpoint de aprovação.
+
+## Tipo
+Orquestrador (primeira etapa do pipeline)
+
+## Uso
+```
+/sf-setup-projeto
+```
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `docs/PM/setup_projeto/` existe | Parar → "Crie a pasta docs/PM/setup_projeto/ e adicione seus insumos" |
+| 2 | Pasta contém pelo menos 1 arquivo (ignorar .gitkeep) | Parar → "Adicione insumos na pasta (aceitos: .md, .txt, .sql, .xml, .html, .json, .csv, .png, .jpg, .pdf — qualquer formato)" |
+| 3 | `docs/Estrutura/` está vazio ou contém apenas templates vazios | Parar → "Setup já foi executado. Use /sf-feature para novas funcionalidades" |
+| 4 | `docs/Desenvolvimento/setup_projeto/.context.md` não existe ou status é `not_started` | Parar → "Setup já está em andamento. Verifique o status em .context.md" |
+
+## Passos
+
+### 1. Criar estrutura
+```
+docs/Desenvolvimento/setup_projeto/
+├── .context.md        ← criado agora
+└── (TRD.md será criado pelo /extract)
+```
+
+### 2. Criar `.context.md`
+```yaml
+---
+nome: "setup_projeto"
+tipo: "setup"
+documento: "TRD"
+pm_path: "docs/PM/setup_projeto/"
+status: "not_started"
+ultima_skill: "/sf-setup-projeto"
+atualizado_em: "{{ISO_DATETIME}}"
+---
+```
+
+### 3. Sugerir /sf-discovery (RECOMENDADO)
+
+Antes de extrair, perguntar ao usuário:
+```
+📋 Insumos encontrados em docs/PM/setup_projeto/.
+
+Recomendo rodar /sf-discovery antes da extração para:
+  - Análise profunda dos insumos (parseia drawio, XML, SQL completo)
+  - Identificar gaps e contradições antes de estruturar
+  - Validar entendimento com você (mapa do sistema)
+
+Quer rodar /sf-discovery docs/PM/setup_projeto/ agora? (s/n)
+  Se SIM → rodar discovery, salvar discovery.md, depois continuar com extract
+  Se NÃO → pular direto para /sf-extract (ok para insumos simples)
+```
+
+Se o usuário aceitar:
+- Rodar `/sf-discovery docs/PM/setup_projeto/`
+- Aguardar conclusão — discovery.md salvo em `docs/Desenvolvimento/setup_projeto/`
+- Continuar para o passo 4
+
+### 4. Chamar `/sf-extract setup_projeto`
+O `/sf-extract` lê os insumos + discovery.md (se existir), gera o TRD e atualiza status para `extract_done`.
+
+### 5. CHECKPOINT — Parar e informar o usuário
+Mensagem ao usuário:
+```
+✅ TRD gerado em docs/Desenvolvimento/setup_projeto/TRD.md
+
+Revise o documento. Quando estiver satisfeito, execute:
+  /sf-design setup_projeto
+
+Se precisar adicionar mais insumos, coloque na pasta docs/PM/setup_projeto/
+e execute:
+  /sf-extract setup_projeto
+```
+
+**O orquestrador encerra aqui.** O restante do pipeline é responsabilidade do usuário chamar as skills atômicas na ordem:
+1. `/sf-design setup_projeto` (pergunta aprovação → gera SDD + docs/Estrutura/ + projetos.yaml)
+2. `/sf-plan setup_projeto` (gera tasks com campo Repo por task)
+3. `/sf-dev setup_projeto` (INFRA-001 cria/clona repos em projetos/, executa tasks nos repos corretos)
+
+## Saídas diretas desta skill
+- `docs/Desenvolvimento/setup_projeto/.context.md`
+- `docs/Desenvolvimento/setup_projeto/TRD.md` (via /extract)
+- `docs/Desenvolvimento/setup_projeto/.extract-log.md` (via /extract)
+
+## Saídas indiretas (skills subsequentes)
+- `sdd.md` (via /design)
+- `projetos.yaml` (via /sf-design — manifesto de repos)
+- `docs/Estrutura/` populado (via /design)
+- `*_tasks.md` + `Progresso.md` (via /plan)
+- `projetos/` com repos criados/clonados (via /sf-dev INFRA-001)
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| PM/setup_projeto/ não existe | Parar, instruir criação |
+| PM/setup_projeto/ vazio | Parar, listar formatos aceitos |
+| Estrutura/ já populado | Parar, sugerir /sf-feature |
+| Pipeline já iniciado | Parar, mostrar status atual do .context.md |
+
+## Notas
+- Esta skill roda **uma única vez** por projeto
+- docs/Estrutura/ é gerado pelo /sf-design (passo 3), não por tasks DOC
+- `projetos.yaml` é gerado pelo /sf-design (passo 3b) — mapeia serviços para repos
+- Repos são criados/clonados pelo /sf-dev (INFRA-001) dentro de `projetos/`
+- O `/merge-delta` NÃO se aplica ao setup (é criação, não atualização)