spec-first-copilot 0.5.0-beta.2 → 0.5.0-beta.4

package/templates/.github/adapters/naming.md

@@ -0,0 +1,241 @@
+# Naming Templating Engine
+
+> Motor trivial que transforma os templates em `sfw.config.yml > naming.*`
+> em strings finais (títulos Confluence, nomes de pasta, etc.).
+>
+> **Função pura, zero dependência externa.** Implementável em qualquer
+> linguagem em ~15 linhas. Este documento é a especificação que
+> adapters/skills/bootstrap seguem.
+
+---
+
+## Por que existe
+
+Antes da decisão do adapter layer, títulos eram hardcoded em string literal
+no código das skills:
+
+```
+title = `out_${scope}_TRD`;    // ← hardcoded em 5 lugares
+```
+
+Isso forçava:
+1. Qualquer mudança de convenção → tocar N arquivos
+2. Times com outra convenção (ex: `[TRD] scope`) não conseguiam usar SFW
+3. Testes precisavam mockar strings mágicas
+
+Agora a convenção vive em **um** arquivo (`sfw.config.yml`) e é aplicada via
+templating engine centralizado.
+
+---
+
+## Placeholders suportados
+
+| Placeholder | O que substitui | Fonte |
+|-------------|-----------------|-------|
+| `{scope}` | Nome do item no Input (ex: `app_barbearia`, `feat_login`) | Argumento da skill |
+| `{type}` | Tipo do artefato (ex: `TRD`, `SDD`, `PRD`, `Progresso`) | Contexto da skill |
+
+**Nenhum outro placeholder é aceito no MVP.** Expansões futuras entram por
+proposta explícita (ex: `{phase}`, `{repo}`, `{timestamp}`).
+
+**O Input NÃO usa naming templating.** O usuário nomeia livremente os items
+no backend (Confluence, filesystem, etc.). O agent lê o nome tal qual está.
+Naming só é aplicado no Output (o que o agent GERA).
+
+---
+
+## Templates no manifest
+
+O `sfw.config.yml` define 2 templates de output:
+
+| Template | Onde | Exemplo |
+|----------|------|---------|
+| `output_container` | Subpasta/page-mãe por scope no Output | `"out_{scope}"` → `out_app_barbearia` |
+| `output_artifact` | Nome do artefato dentro do container | `"{scope} - {type}"` → `app_barbearia - TRD` |
+
+**`output_container`** é o agrupador. No Confluence vira uma page-mãe com
+children; no filesystem vira uma pasta.
+
+**`output_artifact`** é o item individual (TRD, SDD, PRD, Progresso). No
+Confluence é title de uma child page; no filesystem é nome de arquivo
+(adapter adiciona `.md` automaticamente).
+
+**Por que `{scope}` no `output_artifact`?** No Confluence, titles são
+unique per SPACE — sem `{scope}`, duas features teriam `TRD` e `SDD` com
+mesmo título e colidiria. No filesystem não colide porque vive dentro de
+pastas diferentes, então o user pode configurar `output_artifact: "{type}"`
+se preferir limpar redundância.
+
+---
+
+## Contrato da função
+
+```typescript
+/**
+ * Aplica templating de nome.
+ *
+ * @param template  String com placeholders {scope}, {type}
+ * @param vars      Objeto com os valores — chaves que não aparecem no template
+ *                  são ignoradas (não é erro)
+ * @returns         String final, pronta pra uso como título/nome
+ * @throws          NamingTemplateError se o template contém placeholder desconhecido
+ *                  OU se um placeholder usado não tem valor em vars
+ */
+function applyNaming(template: string, vars: {
+  scope?: string;
+  type?: string;
+}): string
+```
+
+### Regras invioláveis
+
+1. **Placeholder desconhecido lança erro.**
+   `"{type} {module}"` → `NamingTemplateError: unknown placeholder "{module}"`.
+   Nunca retorna a string literal `{module}` — isso vazaria inconsistência pros backends.
+
+2. **Placeholder sem valor lança erro.**
+   Template `"{scope} - {type}"` com `vars = { type: "TRD" }`
+   → `NamingTemplateError: placeholder {scope} required but not provided`.
+
+3. **Chaves extras em `vars` são ignoradas.**
+   Não é erro passar `vars.scope = "x"` pra um template que só usa `{type}`.
+   Isso permite que as skills passem o objeto cheio sem se preocupar com qual
+   template está sendo aplicado.
+
+4. **Substituição é literal — sem escape.**
+   Se o `scope` tem caracteres especiais pro backend (ex: `/` no filesystem,
+   `>` no Confluence), é responsabilidade do adapter sanitizar **depois** do
+   apply. Naming engine não conhece constraints de backend.
+
+5. **Case-sensitive.** `{Scope}` ≠ `{scope}`. Não normaliza.
+
+6. **Não suporta lógica.** Sem `{scope|upper}`, sem condicionais. Zero magic.
+
+---
+
+## Pseudo-código de referência
+
+```typescript
+const PLACEHOLDER_RE = /\{(\w+)\}/g;
+const KNOWN = new Set(["scope", "type"]);
+
+function applyNaming(template: string, vars: Record<string, string | undefined>): string {
+  // 1. Detecta placeholders usados no template
+  const used = new Set<string>();
+  for (const m of template.matchAll(PLACEHOLDER_RE)) {
+    used.add(m[1]);
+  }
+
+  // 2. Valida placeholders desconhecidos
+  for (const p of used) {
+    if (!KNOWN.has(p)) {
+      throw new NamingTemplateError(
+        `unknown placeholder "{${p}}" in template "${template}" (supported: ${[...KNOWN].join(", ")})`
+      );
+    }
+  }
+
+  // 3. Valida valores ausentes
+  for (const p of used) {
+    if (vars[p] === undefined || vars[p] === "") {
+      throw new NamingTemplateError(
+        `placeholder {${p}} required but not provided`
+      );
+    }
+  }
+
+  // 4. Substitui
+  return template.replace(PLACEHOLDER_RE, (_, key) => vars[key]!);
+}
+```
+
+---
+
+## Exemplos (matriz de casos)
+
+| Template | vars | Resultado | OK? |
+|----------|------|-----------|-----|
+| `out_{scope}` | `{scope:"app_barbearia"}` | `out_app_barbearia` | ✅ |
+| `{scope} - {type}` | `{scope:"app_barbearia", type:"TRD"}` | `app_barbearia - TRD` | ✅ |
+| `{type}` | `{type:"SDD"}` | `SDD` | ✅ (filesystem dentro de subpasta) |
+| `[{type}] {scope}` | `{type:"PRD", scope:"feat_login"}` | `[PRD] feat_login` | ✅ |
+| `{type}/{scope}` | `{type:"docs", scope:"arch"}` | `docs/arch` | ✅ (adapter sanitiza `/` depois) |
+| `{scope} - {type}` | `{type:"TRD"}` | — | ❌ `NamingTemplateError: placeholder {scope} required` |
+| `{type} {module}` | `{type:"TRD"}` | — | ❌ `NamingTemplateError: unknown placeholder "{module}"` |
+| `hello world` | `{}` | `hello world` | ✅ (sem placeholders) |
+| `out_{scope}` | `{scope:""}` | — | ❌ (string vazia é tratada como ausente) |
+
+---
+
+## Uso nas skills — matriz de quais templates usam quais placeholders
+
+| Skill / operação | Template consumido | Placeholders usados |
+|------------------|-------------------|---------------------|
+| `/load` busca scope no Input | Nenhum — usa o nome do item **tal qual está** no backend | — |
+| `/extract` publica TRD/PRD | `output_container` + `output_artifact` (type=TRD ou PRD) | `{scope}`, `{type}` |
+| `/design` publica SDD | `output_container` + `output_artifact` (type=SDD) | `{scope}`, `{type}` |
+| `/plan` publica Progresso | `output_container` + `output_artifact` (type=Progresso) | `{scope}`, `{type}` |
+| `/load` grava scope folder local | `output_container` (reuso pro path local) | `{scope}` |
+
+Skills **sempre** passam `{ scope, type }` cheio — o engine ignora o que o
+template não usa.
+
+**`/load` não formata Input** — só lê o nome real do item via
+`adapter.listChildren()` e busca match exato com o argumento da skill.
+
+---
+
+## Fluxo ponta-a-ponta (exemplo)
+
+Config:
+```yaml
+naming:
+  output_container: "out_{scope}"
+  output_artifact: "{scope} - {type}"
+```
+
+Cenário: `/new-project app_barbearia` → `/extract` → `/design` → `/plan`
+
+| Passo | Template usado | vars | Resultado |
+|-------|---------------|------|-----------|
+| `/load` busca item no Input | nenhum | — | Encontra page "app_barbearia" pelo nome |
+| `/load` grava local | `output_container` | `{scope:"app_barbearia"}` | Pasta `workspace/Input/out_app_barbearia/` |
+| `/extract` cria container no Output | `output_container` | `{scope:"app_barbearia"}` | Page/pasta `out_app_barbearia` |
+| `/extract` publica TRD | `output_artifact` | `{scope:"app_barbearia", type:"TRD"}` | `app_barbearia - TRD` (dentro do container) |
+| `/design` publica SDD | `output_artifact` | `{scope:"app_barbearia", type:"SDD"}` | `app_barbearia - SDD` |
+| `/plan` publica Progresso | `output_artifact` | `{scope:"app_barbearia", type:"Progresso"}` | `app_barbearia - Progresso` |
+
+Resultado no Confluence:
+```
+Output (page-mãe)
+└── out_app_barbearia (container)
+    ├── app_barbearia - TRD
+    ├── app_barbearia - SDD
+    └── app_barbearia - Progresso
+```
+
+Resultado no filesystem:
+```
+workspace/Output/
+└── out_app_barbearia/
+    ├── app_barbearia - TRD.md
+    ├── app_barbearia - SDD.md
+    └── app_barbearia - Progresso.md
+```
+
+---
+
+## Onde vive o código da engine
+
+Tom do MVP: implementação inline dentro do adapter layer, não arquivo próprio.
+Cada adapter que precisa formatar título chama `applyNaming(template, vars)`.
+Quando a implementação real for escrita (pós-P0.2), avaliar se extrai pra
+`lib/naming.ts` ou mantém como função no registry.
+
+---
+
+## Referências
+
+- Schema do manifest: `sfw.config.yml.example` (raiz do projeto)
+- Interface do adapter: `.github/adapters/interface.md`
+- Erros: `.github/adapters/errors.md` — `NamingTemplateError` é subclasse de `ValidationError`

package/templates/.github/adapters/registry.md

@@ -0,0 +1,244 @@
+# Adapter Registry
+
+> Como o SFW resolve `adapter: "confluence"` no `sfw.config.yml` pra uma
+> instância concreta de `SourceAdapter`.
+>
+> Este arquivo é a **especificação** do registry. A implementação real vive
+> no bootstrap do kit (quando for codada — §9.9.P0.2+).
+
+---
+
+## Conceito
+
+O usuário declara no manifest:
+
+```yaml
+input:
+  adapter: confluence
+  config:
+    space_key: ST
+    parent_page_id: "360668"
+```
+
+As skills **nunca** veem a string `"confluence"`. Elas recebem uma instância
+que implementa `SourceAdapter` — já configurada, já validada. O registry é
+a ponte entre os dois.
+
+---
+
+## Responsabilidades do registry
+
+1. **Descobrir adapters disponíveis** (builtin + futuros plugins)
+2. **Resolver** a string `adapter: X` na classe correta
+3. **Instanciar** o adapter passando o objeto `config` do manifest
+4. **Validar** chamando `adapter.validateConfig(config)` antes de devolver
+5. **Falhar cedo e rápido** se o adapter não existe ou config está errado
+
+---
+
+## Adapters built-in no MVP
+
+| Chave no YAML | Classe | Arquivo de runbook | Status MVP |
+|---------------|--------|-------------------|------------|
+| `confluence` | `ConfluenceAdapter` | `.github/adapters/confluence.md` | P0.2 — reuso do validado em testes/barbearia |
+| `filesystem` | `FilesystemAdapter` | `.github/adapters/filesystem.md` | P0.2 — novo, trivial |
+
+**Apenas esses 2 no MVP.** Qualquer outro valor em `adapter:` → `ValidationError`
+no load do manifest.
+
+---
+
+## Fluxo de resolução
+
+```
+1. Skill começa (ex: /load)
+2. Carrega sfw.config.yml
+3. Para cada seção que precisa de adapter (input, cada output.target):
+   a. Lê string `adapter: X`
+   b. Consulta registry: registry.get("X")
+      - Se X não existe → ValidationError: "unknown adapter 'X' (available: confluence, filesystem)"
+   c. Instancia: const a = new AdapterClass()
+   d. Valida config: a.validateConfig(target.config)
+      - Se inválido → ValidationError (propaga do adapter)
+   e. Armazena a instância configurada em memória pra reuso durante a skill
+4. Usa as instâncias via interface — nunca chama .name direto no hot path
+```
+
+**Importante**: o registry é consultado **1 vez** por execução de skill.
+Instâncias são cached pela duração da skill. Skills que rodam em sequência
+(`/extract` → `/design`) podem re-instanciar — não há estado compartilhado
+entre execuções (não deveria haver, por contrato).
+
+---
+
+## Contrato textual do registry
+
+```typescript
+interface AdapterRegistry {
+  /**
+   * Retorna a classe do adapter (não instancia).
+   * @throws ValidationError se a chave não existir
+   */
+  get(key: string): AdapterClass;
+
+  /**
+   * Lista as chaves disponíveis. Usado em mensagens de erro.
+   */
+  available(): string[];
+
+  /**
+   * Registra um novo adapter. No MVP só é chamado internamente pros 2 builtin.
+   * Plugin system (P2) usaria isso pra carregar adapters externos.
+   */
+  register(key: string, cls: AdapterClass): void;
+}
+
+interface AdapterClass {
+  new(): SourceAdapter;
+  /** Chave que o adapter usa no YAML — deve bater com o que está no registry */
+  readonly adapterName: string;
+}
+```
+
+### Inicialização builtin (pseudo-código)
+
+```typescript
+const registry = new AdapterRegistry();
+registry.register("confluence", ConfluenceAdapter);
+registry.register("filesystem", FilesystemAdapter);
+
+// quando o manifest é carregado:
+function resolveAdapter(section: { adapter: string; config: object }): SourceAdapter {
+  const cls = registry.get(section.adapter);   // throws se não existe
+  const instance = new cls();
+  instance.validateConfig(section.config);     // throws se config errada
+  return instance;
+}
+```
+
+---
+
+## Declaração de config requerida (contrato por adapter)
+
+Cada adapter **documenta** (em `.github/adapters/{name}.md`) quais campos
+são obrigatórios e quais são opcionais na seção `config`. O registry não
+valida isso — delega pro `validateConfig` do adapter. Isso evita duplicação
+e mantém a responsabilidade localizada.
+
+**Exemplo — ConfluenceAdapter**:
+| Campo | Obrigatório | Tipo | Descrição |
+|-------|:---:|------|-----------|
+| `space_key` | ✅ | string | ex: `"ST"` |
+| `parent_page_id` | ✅ | string | ID numérico da page pai |
+| `recursive` | — | boolean | default `true` |
+| `include_attachments` | — | boolean | default `true` |
+
+**Exemplo — FilesystemAdapter**:
+| Campo | Obrigatório | Tipo | Descrição |
+|-------|:---:|------|-----------|
+| `root_path` | ✅ | string | path absoluto ou relativo ao projeto |
+| `glob` | — | string | default `**/*.md` |
+| `watch` | — | boolean | default `false` (watch mode é P2) |
+
+---
+
+## Ordem de validação no load do manifest
+
+Quando skill chama `loadConfig("sfw.config.yml")`:
+
+1. **Parse YAML.** Erro de sintaxe → `ValidationError` (nem chama registry).
+2. **Valida shape top-level.** Presença de `project`, `naming`, `input`, `output.targets[]`.
+3. **Resolve `input.adapter`** via registry + `validateConfig` do adapter.
+4. **Resolve cada `output.targets[i].adapter`** via registry + `validateConfig`.
+5. **Valida `naming.*`** — templates precisam ser strings não-vazias; placeholders
+   desconhecidos detectados agora (antecipa erro de runtime).
+6. **Valida coerência inter-seções**: ex., `output.targets[i].mode: auto` exige
+   `approval_mechanism` presente quando `publishes` contém TRD/PRD/SDD (artefatos
+   com gate de aprovação).
+
+Tudo no load. Se qualquer passo falha, skill para antes de tocar backend.
+
+---
+
+## Config de exemplo resolvida
+
+Input YAML:
+```yaml
+project:
+  name: "Barbearia"
+input:
+  adapter: confluence
+  config:
+    space_key: ST
+    parent_page_id: "360668"
+output:
+  targets:
+    - name: confluence-mirror
+      adapter: confluence
+      config:
+        space_key: ST
+        parent_page_id: "294931"
+      publishes: [PRD, TRD, SDD, Progresso]
+      mode: auto
+    - name: local-mirror
+      adapter: filesystem
+      config:
+        root_path: "./mirror"
+      publishes: [PRD, TRD, SDD, Progresso, backlog]
+      mode: auto
+```
+
+Após load:
+```typescript
+const manifest = {
+  project: { name: "Barbearia" },
+  input: <ConfluenceAdapter instance, configured>,
+  outputs: [
+    { name: "confluence-mirror", adapter: <ConfluenceAdapter>, publishes: [...], mode: "auto" },
+    { name: "local-mirror",      adapter: <FilesystemAdapter>,  publishes: [...], mode: "auto" },
+  ],
+};
+```
+
+Skill chama `manifest.input.listChildren(...)` e `manifest.outputs[0].adapter.update(...)`.
+A string `"confluence"` nunca aparece fora do registry.
+
+---
+
+## O que NÃO é responsabilidade do registry
+
+- **Credenciais.** Adapter lê `.mcp.json` / env var direto. Registry nem vê.
+- **Retry/backoff.** Cada adapter implementa. Registry devolve instância "crua".
+- **Logging.** Skills logam. Adapter/registry silenciam (exceto em erro).
+- **Connection pooling.** MVP é single-process single-skill. Se virar batch,
+  registry pode cachear. Não agora.
+
+---
+
+## Futuro (P2) — Plugin system
+
+Quando aparecer o 3º caso real de backend não-builtin:
+
+1. `sfw.config.yml` ganha seção `plugins:`:
+   ```yaml
+   plugins:
+     - npm:@sfw/notion-adapter@1.2.0
+     - file:./local-adapters/sharepoint.js
+   ```
+2. Bootstrap do kit carrega plugins antes do manifest.
+3. Cada plugin exporta `{ key, class }` e chama `registry.register(...)`.
+4. Interface do adapter fica estável (breaking change vira major version).
+
+**Decisão (2026-04-11)**: não implementar agora. Builtin resolve 95% dos casos
+e prova que a interface está certa. Plugin system vira prioridade quando um
+usuário real pedir.
+
+---
+
+## Referências
+
+- Interface: `.github/adapters/interface.md`
+- Erros: `.github/adapters/errors.md`
+- Naming: `.github/adapters/naming.md`
+- Manifest: `sfw.config.yml.example`
+- Roadmap: `planodetarefas.md §9.9.P0.2` (implementação dos builtins)

package/templates/.github/copilot-instructions.md

@@ -24,7 +24,7 @@ Verificar que TODAS as 9 skills estão acessíveis:
 
 | Skill | Caminho |
 |-------|---------|
-| `/sf-setup-projeto` | `.github/skills/sf-setup-projeto/SKILL.md` |
+| `/sf-new-project` | `.github/skills/sf-new-project/SKILL.md` |
 | `/sf-feature` | `.github/skills/sf-feature/SKILL.md` |
 | `/sf-extract` | `.github/skills/sf-extract/SKILL.md` |
 | `/sf-design` | `.github/skills/sf-design/SKILL.md` |
@@ -77,7 +77,7 @@ Nenhum código é escrito sem especificação aprovada (SDD).
 
 ```
 workspace/Input/ (qualquer arquivo)
-    ↓ /sf-setup-projeto (uma vez) ou /sf-feature (por feature)
+    ↓ /sf-new-project <nome> (TRD — bootstrap técnico) ou /sf-feature <nome> (PRD — feature)
 /sf-discovery → análise profunda dos insumos (RECOMENDADO, opcional)
     ↓
 /sf-extract → PRD ou TRD em workspace/Output/{nome}/ (checkpoint — usuário revisa e aprova)
@@ -94,7 +94,7 @@ workspace/Input/ (qualquer arquivo)
 
 | Skill | Tipo | O que faz |
 |-------|------|-----------|
-| `/sf-setup-projeto` | Orquestrador | Bootstrap: cria .context.md, chama /sf-extract, para no checkpoint. Roda UMA vez |
+| `/sf-new-project <nome>` | Orquestrador | Bootstrap técnico: cria .context.md tipo TRD, chama /sf-extract, para no checkpoint |
 | `/sf-feature <nome>` | Orquestrador | Feature: cria .context.md tipo PRD, chama /sf-extract, para no checkpoint |
 | `/sf-extract <nome>` | Atômica | Lê workspace/Input/{nome}/ → gera PRD ou TRD. Re-executável para novos insumos |
 | `/sf-design <nome>` | Atômica | Pergunta aprovação → gera SDD a partir do PRD/TRD |
@@ -168,8 +168,7 @@ specs/                       ← AGENT CONTRACTS (projeções do SDD pro coder)
 
 workspace/                   ← TEAM CONTENT (futuro wiki)
 ├── Input/                   ← Insumos brutos (QUALQUER formato — nunca modificar)
-│   ├── setup_projeto/       ← Insumos de bootstrap
-│   └── feat_*/              ← Insumos por feature
+│   └── {nome}/              ← Nomeado livremente pelo usuário (ex: app_barbearia, feat_login)
 └── Output/                  ← Artefatos humanos gerados pelo workflow
     └── {nome}/
         ├── PRD.md ou TRD.md ← Requirements (gerado pelo /sf-extract)

package/templates/.github/skills/sf-new-project/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: sf-new-project
+description: |
+  Bootstrap técnico do projeto. Recebe nome do scope no Input, cria contexto TRD,
+  chama /sf-extract, para no checkpoint.
+  Trigger: /sf-new-project <nome>
+author: GustavoMaritan
+version: 2.0.0
+date: 2026-04-12
+---
+
+# Skill: /sf-new-project <nome>
+
+> Orquestrador de bootstrap técnico do projeto.
+> Cria contexto TRD a partir dos insumos em `workspace/Input/{nome}/`,
+> chama `/sf-extract` e para no checkpoint de aprovação.
+>
+> Simétrico ao `/sf-feature <nome>` — a diferença é que gera TRD (perfil técnico)
+> em vez de PRD (perfil de produto).
+
+## Tipo
+Orquestrador (primeira etapa do pipeline)
+
+## Uso
+```
+/sf-new-project <nome>
+```
+
+`<nome>` = nome da pasta no Input. O usuário nomeia livremente
+(ex: `app_barbearia`, `meu_sistema`, `api_pagamentos`).
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `workspace/Input/{nome}/` existe | Parar → "Crie a pasta workspace/Input/{nome}/ 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 | `workspace/Output/{nome}/.context.md` não existe ou status é `not_started` | Parar → "Este escopo já está em andamento. Verifique o status em .context.md" |
+
+## Passos
+
+### 1. Criar estrutura
+```
+workspace/Output/{nome}/
+├── .context.md        ← criado agora
+└── (TRD.md será criado pelo /sf-extract)
+```
+
+### 2. Criar `.context.md`
+```yaml
+---
+nome: "{nome}"
+tipo: "project"
+documento: "TRD"
+pm_path: "workspace/Input/{nome}/"
+status: "not_started"
+ultima_skill: "/sf-new-project"
+atualizado_em: "{{ISO_DATETIME}}"
+---
+```
+
+### 3. Sugerir /sf-discovery (RECOMENDADO)
+
+Antes de extrair, perguntar ao usuário:
+```
+Insumos encontrados em workspace/Input/{nome}/.
+
+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 workspace/Input/{nome}/ 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 workspace/Input/{nome}/`
+- Aguardar conclusão — discovery.md salvo em `workspace/Output/{nome}/`
+- Continuar para o passo 4
+
+### 4. Chamar `/sf-extract {nome}`
+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 workspace/Output/{nome}/TRD.md
+
+Revise o documento. Quando estiver satisfeito, execute:
+  /sf-design {nome}
+
+Se precisar adicionar mais insumos, coloque na pasta workspace/Input/{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 + docs/ + projetos.yaml)
+2. `/sf-plan {nome}` (gera tasks com campo Repo por task)
+3. `/sf-dev {nome}` (INFRA-001 cria/clona repos em projetos/, executa tasks nos repos corretos)
+
+## Saídas diretas desta skill
+- `workspace/Output/{nome}/.context.md`
+- `workspace/Output/{nome}/TRD.md` (via /sf-extract)
+- `workspace/Output/{nome}/.extract-log.md` (via /sf-extract)
+
+## Saídas indiretas (skills subsequentes)
+- `sdd.md` (via /sf-design)
+- `projetos.yaml` (via /sf-design — manifesto de repos)
+- `docs/` populado (via /sf-design)
+- `specs/{nome}/tasks.md` + `Progresso.md` (via /sf-plan)
+- `projetos/` com repos criados/clonados (via /sf-dev INFRA-001)
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| workspace/Input/{nome}/ não existe | Parar, instruir criação |
+| workspace/Input/{nome}/ vazio | Parar, listar formatos aceitos |
+| Pipeline já iniciado | Parar, mostrar status atual do .context.md |
+
+## Notas
+- docs/ é 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 `/sf-merge-delta` NÃO se aplica ao new-project (é criação, não atualização)