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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-copilot",
-  "version": "0.5.0-beta.4",
+  "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

@@ -0,0 +1,314 @@
+# Adapter Setup Guide
+
+> Guia passo a passo para configurar os adapters do SFW.
+> Se o usuário pedir ajuda pra configurar, siga este guia.
+
+---
+
+## Escolha seu modo de trabalho
+
+O SFW funciona em **3 modos**, configurados no `sfw.config.yml`:
+
+| Modo | Input | Output | Quando usar |
+|------|-------|--------|-------------|
+| **Full Confluence** | `adapter: confluence` | `mode: auto` | Time usa Confluence, PM publica lá, quer artefatos lá |
+| **Confluence só leitura** | `adapter: confluence` | `mode: off` | PM publica no Confluence, mas artefatos ficam só local |
+| **100% local** | `adapter: filesystem` | `mode: off` | Time sem Confluence, tudo no disco |
+
+Para mudar: edite `sfw.config.yml` e ajuste `input.adapter` e `output.targets[].mode`.
+
+---
+
+## Setup 1: Confluence (Full ou só leitura)
+
+### Pré-requisitos
+
+- Python 3.10+ instalado
+- Conta Atlassian com acesso ao Confluence Cloud
+- Claude Code instalado
+
+### Passo 1 — Instalar uvx
+
+`uvx` é o runtime que executa o MCP server do Confluence.
+
+```bash
+# Windows (PowerShell)
+pip install uv
+
+# Mac/Linux
+pip install uv
+# ou
+brew install uv
+```
+
+Verificar:
+```bash
+uvx --version
+```
+
+### Passo 2 — Gerar API Token Atlassian
+
+1. Acesse: https://id.atlassian.com/manage-profile/security/api-tokens
+2. Clique **Create API token**
+3. Nome: `sfw-mcp` (ou qualquer nome descritivo)
+4. Copie o token gerado — **ele só aparece uma vez**
+
+Você vai precisar de:
+- **Email**: seu email da conta Atlassian (ex: `dev@empresa.com`)
+- **Token**: o token que acabou de copiar
+- **URL do Confluence**: geralmente `https://sua-empresa.atlassian.net/wiki`
+
+### Passo 3 — Criar `.mcp.json`
+
+Crie o arquivo `.mcp.json` na **raiz do projeto** (onde está o `sfw.config.yml`).
+
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "uvx",
+      "args": ["mcp-atlassian"],
+      "env": {
+        "CONFLUENCE_URL": "https://sua-empresa.atlassian.net/wiki",
+        "CONFLUENCE_USERNAME": "seu-email@empresa.com",
+        "CONFLUENCE_API_TOKEN": "seu-token-aqui"
+      }
+    }
+  }
+}
+```
+
+**IMPORTANTE — Gotchas aprendidos na prática:**
+
+1. **Credenciais HARDCODED no arquivo** — `${VAR}` com variáveis de ambiente **NÃO funciona** no startup do Claude Code. Coloque os valores direto.
+
+2. **`.mcp.json` DEVE estar no `.gitignore`** — tem credenciais. O template do kit já inclui isso, mas verifique:
+   ```
+   # .gitignore
+   .mcp.json
+   ```
+
+3. **Após criar/editar `.mcp.json`, REINICIE o Claude Code** — servers MCP só são carregados no startup. Mudança no arquivo não tem efeito em sessão ativa.
+
+4. **Primeira execução baixa ~118 dependências** — o pacote `mcp-atlassian` é pesado. A primeira vez pode demorar 1-2 minutos. As seguintes são instantâneas.
+
+### Passo 4 — Descobrir seu Space Key
+
+O Space Key é o identificador curto do espaço Confluence (ex: `ST`, `DEV`, `PROJ`).
+
+Para encontrar:
+- Abra qualquer página do seu espaço Confluence
+- Olhe a URL: `https://empresa.atlassian.net/wiki/spaces/ST/pages/...`
+- O `ST` é o Space Key
+
+### Passo 5 — Criar estrutura no Confluence
+
+Crie manualmente no Confluence (ou peça pro PM criar):
+
+```
+{Seu Space}
+└── {Nome do Projeto}          ← page raiz do projeto
+    ├── Input                  ← PM coloca insumos aqui
+    │   └── (scopes como pages filhas)
+    └── Output                 ← agent publica aqui (não editar manualmente)
+```
+
+Anote os **Page IDs** de `Input` e `Output`:
+- Abra a page → ... (menu) → Page information → o ID está na URL
+- Ou: URL da page contém `/pages/123456/...` — o número é o Page ID
+
+### Passo 6 — Configurar `sfw.config.yml`
+
+Copie o `sfw.config.yml.example` pra `sfw.config.yml` e preencha:
+
+```yaml
+project:
+  name: "Meu Projeto"
+
+naming:
+  output_container: "out_{scope}"
+  output_artifact: "{scope} - {type}"
+
+input:
+  adapter: confluence
+  config:
+    space_key: "ST"                    # ← seu Space Key
+    parent_page_id: "360668"           # ← Page ID da page Input
+    recursive: true
+    include_attachments: true
+  cache:
+    local_dir: "workspace/Input/"
+    log: ".ai/load-log.md"
+    incremental: true
+
+output:
+  targets:
+    - name: confluence-mirror
+      adapter: confluence
+      config:
+        space_key: "ST"                # ← mesmo Space Key
+        parent_page_id: "294931"       # ← Page ID da page Output
+      publishes: [PRD, TRD, SDD, Progresso]
+      mode: auto                       # ← auto | manual | off
+      conflict_detection: version
+      approval_mechanism: label
+      approval_label: "sfw-approved"
+```
+
+### Passo 7 — Testar a conexão
+
+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 da page {Page ID do Input}
+```
+
+**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.
+
+---
+
+## Setup 2: 100% Local (sem Confluence)
+
+Nenhuma instalação extra necessária. Não precisa de `.mcp.json`.
+
+### Passo 1 — Configurar `sfw.config.yml`
+
+```yaml
+project:
+  name: "Meu Projeto"
+
+naming:
+  output_container: "out_{scope}"
+  output_artifact: "{type}"           # sem {scope} no nome — sem risco de colisão local
+
+input:
+  adapter: filesystem
+  config:
+    root_path: "workspace/Input"
+  cache:
+    local_dir: "workspace/Input/"
+    log: ".ai/load-log.md"
+    incremental: true
+
+output:
+  targets:
+    - name: local
+      adapter: filesystem
+      config:
+        root_path: "workspace/Output"
+      publishes: [PRD, TRD, SDD, Progresso]
+      mode: auto
+      conflict_detection: hash
+      approval_mechanism: none
+```
+
+### Passo 2 — Criar pastas de Input
+
+```bash
+mkdir -p workspace/Input/meu_escopo
+# Adicione seus arquivos de insumo na pasta
+```
+
+Pronto. `/new-project meu_escopo` funciona direto.
+
+---
+
+## Ligar e desligar Confluence (sem mudar nada estrutural)
+
+### Desligar output pro Confluence (manter input)
+
+Mude `mode` no target:
+
+```yaml
+output:
+  targets:
+    - name: confluence-mirror
+      mode: off              # ← era "auto", agora "off"
+```
+
+Pipeline roda normal, artefatos ficam locais. Quando quiser religar, volte pra `auto`.
+
+### Desligar tudo (input + output) — virar 100% local
+
+Mude o adapter do input:
+
+```yaml
+input:
+  adapter: filesystem        # ← era "confluence"
+  config:
+    root_path: "workspace/Input"
+```
+
+E coloque `mode: off` nos targets de Confluence.
+
+### Adicionar Confluence depois (começou local, quer publicar)
+
+1. Siga os passos 1-5 do Setup Confluence
+2. Adicione o target no `sfw.config.yml`:
+   ```yaml
+   output:
+     targets:
+       - name: confluence-mirror
+         adapter: confluence
+         config:
+           space_key: "ST"
+           parent_page_id: "294931"
+         publishes: [PRD, TRD, SDD, Progresso]
+         mode: auto
+   ```
+3. Re-rode `/extract`, `/design`, `/plan` — os artefatos locais serão publicados
+
+---
+
+## Troubleshooting
+
+| Problema | Solução |
+|----------|---------|
+| MCP server não aparece no Claude Code | Reiniciar Claude Code. MCP só carrega no startup |
+| `${VAR}` não resolve no `.mcp.json` | Hardcode as credenciais direto. Variáveis de ambiente não funcionam |
+| "401 Unauthorized" | Verifique email + token no `.mcp.json`. Token pode ter expirado |
+| "403 Forbidden" | Usuário sem permissão no space. Pedir acesso ao admin |
+| "Page not found" (404) | Page ID errado. Confirme o ID via URL da page no Confluence |
+| Primeira execução demora muito | Normal — uvx baixa ~118 deps na primeira vez |
+| `BadRequestException: title already exists` | Title duplicado no space (unique per space no Confluence). Renomear o scope no Input |
+| Edição no `.mcp.json` não faz efeito | Reiniciar Claude Code obrigatório |
+| Content no Confluence parece diferente do local | Markdown roundtrip normaliza (`#`→`===`, `-`→`*`). Normal — version number é fonte de verdade, não bytes |
+
+---
+
+## Referências
+
+- Interface do adapter: `.github/adapters/interface.md`
+- ConfluenceAdapter: `.github/adapters/confluence.md`
+- FilesystemAdapter: `.github/adapters/filesystem.md`
+- Erros: `.github/adapters/errors.md`
+- Naming: `.github/adapters/naming.md`

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`