spec-first-copilot 0.5.0-beta.5 → 0.5.0-beta.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-copilot",
-  "version": "0.5.0-beta.5",
+  "version": "0.5.0-beta.6",
   "description": "Spec-first workflow kit for GitHub Copilot — AI-driven development with specs, not guesswork",
   "bin": {
     "spec-first-copilot": "bin/cli.js"

package/templates/.github/adapters/SETUP.md

@@ -160,12 +160,39 @@ output:
 Após reiniciar o Claude Code com o `.mcp.json` configurado, peça ao agent:
 
 ```
-Teste a conexão com o Confluence: liste as páginas filhas de {Page ID do Input}
+Teste a conexão com o Confluence: liste as páginas filhas da page {Page ID do Input}
 ```
 
-O agent deve conseguir usar `confluence_get_page_children` e listar o conteúdo.
-Se der erro de auth → verifique email, token e URL no `.mcp.json`.
-Se o MCP não estiver disponível → reinicie o Claude Code.
+**IMPORTANTE — Como o Confluence funciona no Claude Code:**
+
+O Confluence **NÃO é um comando de terminal**. Não existe `confluence` como CLI.
+O acesso é feito via **MCP tools** — funções que o Claude Code expõe automaticamente
+quando o server MCP está configurado no `.mcp.json`.
+
+As tools disponíveis são prefixadas com `mcp__atlassian__confluence_`:
+
+| Tool MCP | O que faz |
+|----------|-----------|
+| `mcp__atlassian__confluence_get_page` | Lê conteúdo de uma page por ID |
+| `mcp__atlassian__confluence_get_page_children` | Lista filhos diretos de uma page |
+| `mcp__atlassian__confluence_create_page` | Cria page nova |
+| `mcp__atlassian__confluence_update_page` | Atualiza conteúdo de page existente |
+| `mcp__atlassian__confluence_search` | Busca por texto no space |
+| `mcp__atlassian__confluence_get_labels` | Lê labels de uma page |
+| `mcp__atlassian__confluence_get_attachments` | Lista attachments de uma page |
+| `mcp__atlassian__confluence_download_attachment` | Baixa attachment |
+
+O agent chama essas tools diretamente — **nunca via bash/terminal**.
+Se o agent tentar rodar `confluence ...` no terminal, está errado.
+
+**Como verificar que o MCP está funcionando:**
+1. Reinicie o Claude Code após criar/editar `.mcp.json`
+2. Peça ao agent: "Use a tool `mcp__atlassian__confluence_get_page` com page_id {ID}" 
+3. Se funcionar, está conectado. Se der "tool not found", o MCP não subiu — verifique `.mcp.json`
+
+**Nota**: `get_page_children` retorna apenas filhos **diretos** (não recursivo).
+Para trazer toda a árvore, o agent faz loop: chama `get_page_children` em cada
+filho que tem `hasChildren`, empilha e desce. O `/load` já faz isso automaticamente.
 
 ---
 

package/templates/.github/adapters/confluence.md

@@ -54,16 +54,38 @@ Não valida que `space_key` existe no Confluence — isso acontece no primeiro
 
 **MCP**: `mcp__atlassian__confluence_get_page_children`
 
+> **ATENÇÃO**: `get_page_children` retorna apenas filhos **diretos** — NÃO é recursivo.
+> Para trazer a árvore inteira, o caller (ex: `/load`) deve implementar recursão manual.
+
 **Passos**:
-1. Chamar tool com `parent_id: containerId`, `limit: 100`, `expand: "version"`
+1. Chamar tool com `page_id: containerId`
 2. Para cada filho retornado, montar `Item`:
    - `id` = `page.id` (string)
    - `title` = `page.title`
-   - `version` = `String(page.version.number)`
+   - `version` = `String(page.version.number)` (se disponível, senão chamar `get_page` pra obter)
    - `type` = `"page"` (Confluence só tem páginas — folders são páginas vazias convencionadas)
-   - `hasChildren` = `page.children_count > 0` (se vier na resposta; senão `true` por default — custo de 1 chamada extra é baixo)
-3. Se retorno paginado (cursor), iterar até esgotar
-4. Retornar array
+   - `hasChildren` = verificar via `get_page_children` no filho ou assumir `true` por default
+3. Se retorno paginado, iterar até esgotar
+4. Retornar array (apenas filhos diretos — 1 nível)
+
+**Recursão (obrigatória pro `/load` com `recursive: true`)**:
+
+O `/load` precisa de toda a árvore. Padrão:
+
+```
+function listChildrenRecursive(containerId):
+  filhos = listChildren(containerId)       // 1 nível
+  resultado = [...filhos]
+  para cada filho em filhos:
+    se filho.type == "page":               // tudo no Confluence é page
+      netos = listChildrenRecursive(filho.id)
+      resultado = [...resultado, ...netos]
+  retornar resultado
+```
+
+Custo: 1 chamada MCP por nó da árvore. Uma árvore com 5 scopes × 3 filhos = ~20 chamadas.
+É aceitável — MCP é local (uvx), não HTTP. Se ficar lento com árvores grandes,
+considerar cache em `.ai/load-log.md` e re-scan incremental.
 
 **Erros**:
 - `404` → `NotFoundError { kind: "container", itemId: containerId }`

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

@@ -20,10 +20,11 @@
 
 ### 2. Validar acesso a todas skills
 
-Verificar que TODAS as 9 skills estão acessíveis:
+Verificar que TODAS as 10 skills estão acessíveis:
 
 | Skill | Caminho |
 |-------|---------|
+| `/sf-load` | `.github/skills/sf-load/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` |
@@ -76,8 +77,9 @@ Nenhum código é escrito sem especificação aprovada (SDD).
 ## Pipeline do Workflow
 
 ```
-workspace/Input/ (qualquer arquivo)
-    ↓ /sf-new-project <nome> (TRD — bootstrap técnico) ou /sf-feature <nome> (PRD — feature)
+/sf-load <nome> → puxa insumos do backend (Confluence/filesystem) → workspace/Input/{nome}/
+    ↓
+/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,6 +96,7 @@ workspace/Input/ (qualquer arquivo)
 
 | Skill | Tipo | O que faz |
 |-------|------|-----------|
+| `/sf-load <nome>` | Utilitária | Puxa insumos do backend (Confluence/filesystem) para workspace/Input/{nome}/. Incremental |
 | `/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 |

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

@@ -0,0 +1,161 @@
+# /sf-load <nome>
+
+Puxa os insumos de um scope do backend configurado (Confluence, filesystem, etc.)
+e materializa em `workspace/Input/{nome}/` no projeto local.
+
+## Argumento
+
+`<nome>` = nome do item no backend de input (título da page no Confluence,
+nome da pasta no filesystem). Match exato — se não encontrar, para com erro.
+
+## Quando usar
+
+- **Antes de `/sf-new-project <nome>` ou `/sf-feature <nome>`** — para trazer
+  insumos que o PM publicou no Confluence (ou outro backend)
+- **Após o PM adicionar novos insumos** (ex: `ajustes_v1` como page filha) —
+  para re-sincronizar. O log incremental detecta NOVO/MODIFICADO/INALTERADO
+- **Não obrigatório** se o usuário já colocou insumos direto em `workspace/Input/{nome}/`
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `sfw.config.yml` existe na raiz do projeto | Parar → "Copie sfw.config.yml.example para sfw.config.yml e configure. Veja .github/adapters/SETUP.md" |
+| 2 | `sfw.config.yml` tem seção `input` com `adapter` e `config` | Parar → "Seção input não encontrada no sfw.config.yml" |
+| 3 | Adapter do input está acessível (MCP rodando pra Confluence, pasta existe pra filesystem) | Parar → orientar setup conforme `.github/adapters/SETUP.md` |
+
+## Execução
+
+### 1. Carregar configuração
+
+Ler `sfw.config.yml` e extrair:
+- `input.adapter` — tipo do adapter (`confluence` ou `filesystem`)
+- `input.config` — config específica do adapter
+- `input.cache.local_dir` — onde materializar (default: `workspace/Input/`)
+- `input.cache.log` — arquivo de log (default: `.ai/sf-load-log.md`)
+- `input.cache.incremental` — se compara hashes antes de sobrescrever
+- `naming.output_container` — template pra nomear a pasta local (usa `{scope}`)
+
+### 2. Buscar o scope no backend
+
+**Para Confluence** (`adapter: confluence`):
+
+```
+1. Chamar mcp__atlassian__confluence_get_page_children
+   com page_id = config.parent_page_id
+2. Na lista de filhos, buscar o que tem title == {nome} (match exato)
+3. Se não encontrou → ERRO: "Scope '{nome}' não encontrado no Confluence
+   (parent_page_id: {id}). Verifique se a page existe como filha de Input."
+4. Anotar scope_id = page.id
+```
+
+**Para Filesystem** (`adapter: filesystem`):
+
+```
+1. Listar conteúdo de config.root_path
+2. Buscar pasta ou arquivo com nome == {nome}
+3. Se não encontrou → ERRO: "Scope '{nome}' não encontrado em {root_path}"
+4. Anotar scope_path
+```
+
+### 3. Trazer conteúdo recursivamente
+
+**Para Confluence**:
+
+```
+function loadScope(pageId, localDir):
+  // Baixar conteúdo da page-mãe
+  page = mcp__atlassian__confluence_get_page(page_id=pageId, convert_to_markdown=true)
+  salvar page.content em {localDir}/_parent.md (ou {titulo_sanitizado}.md)
+  registrar no load-log: pageId, title, version, sha256(content)
+
+  // Baixar attachments (se include_attachments=true)
+  attachments = mcp__atlassian__confluence_get_attachments(page_id=pageId)
+  para cada attachment:
+    bytes = mcp__atlassian__confluence_download_attachment(page_id=pageId, filename=attachment.title)
+    salvar em {localDir}/attachments/{filename}
+    registrar no load-log
+
+  // Recursão nos filhos
+  children = mcp__atlassian__confluence_get_page_children(page_id=pageId)
+  para cada child:
+    childDir = {localDir}/{sanitize(child.title)}
+    mkdir childDir
+    loadScope(child.id, childDir)     // recursão
+```
+
+**Para Filesystem**:
+
+```
+function loadScope(sourcePath, localDir):
+  // Se source == localDir → no-op (input já é local)
+  // Senão: copiar recursivamente sourcePath → localDir
+  // Calcular sha256 de cada arquivo pra load-log
+```
+
+### 4. Log incremental (`.ai/sf-load-log.md`)
+
+Formato append-only:
+
+```markdown
+## Load: {nome} — {ISO_DATETIME}
+
+| Item ID | Title | Version | SHA256 | Local Path | Status |
+|---------|-------|---------|--------|------------|--------|
+| 294950 | setup_projeto | 3 | a3f5... | workspace/Input/app_barbearia/_parent.md | NOVO |
+| 557057 | brief fullstack | 1 | 9fc3... | workspace/Input/app_barbearia/brief_fullstack.md | NOVO |
+| att:diagram.png | diagram.png | — | 7d2e... | workspace/Input/app_barbearia/attachments/diagram.png | NOVO |
+```
+
+**Se `incremental: true`** (default):
+- Antes de baixar, comparar hash atual com hash no log anterior
+- Se hash idêntico → status `INALTERADO`, não sobrescrever
+- Se hash diferente → status `MODIFICADO`, sobrescrever
+- Se não existia no log → status `NOVO`
+- Arquivo que existia no log mas sumiu do backend → status `REMOVIDO` (log only, não deleta local)
+
+### 5. Informar o usuário
+
+```
+Insumos carregados em workspace/Input/{nome}/
+
+  {N} arquivos ({X novos, Y modificados, Z inalterados})
+  {M} attachments
+
+Próximo passo:
+  /sf-new-project {nome}    ← se é bootstrap técnico (gera TRD)
+  /sf-feature {nome}        ← se é feature (gera PRD)
+
+Log salvo em .ai/sf-load-log.md
+```
+
+## Notas
+
+- `/sf-load` é **idempotente** — rodar N vezes com mesmos insumos no backend
+  não muda nada (hashes batem, status = INALTERADO)
+- Se o PM adicionar page `ajustes_v1` como filha do scope no Confluence,
+  re-rodar `/sf-load {nome}` traz como NOVO automaticamente
+- O `/sf-load` **nunca modifica o backend** — só lê
+- O `/sf-load` **nunca deleta arquivos locais** — se algo sumiu do backend,
+  marca como REMOVIDO no log mas mantém o arquivo local
+- Attachments são salvos em subpasta `attachments/` dentro do scope
+- Nomes de arquivo são sanitizados: espaços → `_`, caracteres especiais removidos
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| `sfw.config.yml` não existe | Parar, orientar setup |
+| Adapter não configurado | Parar, apontar pra SETUP.md |
+| MCP não disponível (Confluence) | Parar → "Reinicie o Claude Code. MCP carrega no startup" |
+| Scope não encontrado no backend | Parar, listar scopes disponíveis se possível |
+| Auth error (401/403) | Parar → "Verifique credenciais no .mcp.json" |
+| Page sem conteúdo | OK — salvar arquivo vazio, registrar no log |
+
+## Referências
+
+- Adapter interface: `.github/adapters/interface.md`
+- Confluence adapter: `.github/adapters/confluence.md`
+- Filesystem adapter: `.github/adapters/filesystem.md`
+- Setup guide: `.github/adapters/SETUP.md`
+- Naming: `.github/adapters/naming.md`