spec-first-copilot 0.5.0-beta.13 → 0.5.0-beta.15

package/lib/update.js

@@ -37,9 +37,6 @@ function update({ templatesDir, targetDir, force }) {
   const stats = { added: [], updated: [], skipped: 0 };
   syncDir(templatesDir, dest, force, stats, dest);
 
-  // Auto-configure .gitignore based on sfw.config.yml (before printing results)
-  adjustGitignore(dest, stats);
-
   console.log('');
   if (stats.added.length > 0) {
     console.log(`Added (${stats.added.length}):`);
@@ -132,37 +129,4 @@ function isFrameworkPath(rel) {
   return false;
 }
 
-const WORKSPACE_IGNORE_MARKER = '# SFW: workspace ignored (external backend detected)';
-const WORKSPACE_IGNORE_BLOCK = `
-${WORKSPACE_IGNORE_MARKER}
-# Content lives in the external backend (Confluence, etc.) — local is just cache
-workspace/Output/**
-!workspace/Output/.gitkeep
-`;
-
-function adjustGitignore(dest, stats) {
-  const configPath = path.join(dest, 'sfw.config.yml');
-  const gitignorePath = path.join(dest, '.gitignore');
-
-  if (!fs.existsSync(configPath) || !fs.existsSync(gitignorePath)) return;
-
-  const config = fs.readFileSync(configPath, 'utf-8');
-  const gitignore = fs.readFileSync(gitignorePath, 'utf-8');
-
-  const inputMatch = config.match(/^\s*adapter:\s*(\S+)/m);
-  const inputAdapter = inputMatch ? inputMatch[1] : 'filesystem';
-  const isExternal = inputAdapter !== 'filesystem';
-
-  const alreadyHasBlock = gitignore.includes(WORKSPACE_IGNORE_MARKER);
-
-  if (isExternal && !alreadyHasBlock) {
-    fs.appendFileSync(gitignorePath, WORKSPACE_IGNORE_BLOCK);
-    stats.updated.push('.gitignore (workspace ignored — external backend)');
-  } else if (!isExternal && alreadyHasBlock) {
-    const cleaned = gitignore.split(WORKSPACE_IGNORE_MARKER)[0].trimEnd() + '\n';
-    fs.writeFileSync(gitignorePath, cleaned, 'utf-8');
-    stats.updated.push('.gitignore (workspace restored — local mode)');
-  }
-}
-
 module.exports = { update };

package/package.json

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

@@ -20,10 +20,11 @@
 
 ### 2. Validar acesso a todas skills
 
-Verificar que TODAS as 10 skills estão acessíveis:
+Verificar que TODAS as 11 skills estão acessíveis:
 
 | Skill | Caminho |
 |-------|---------|
+| `/sf-mcp` | `.github/skills/sf-mcp/SKILL.md` |
 | `/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` |
@@ -96,6 +97,7 @@ Nenhum código é escrito sem especificação aprovada (SDD).
 
 | Skill | Tipo | O que faz |
 |-------|------|-----------|
+| `/sf-mcp <provider>` | Setup | Configura backend externo interativamente. Cria .mcp.json + sfw.config.yml + ajusta .gitignore |
 | `/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 |

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

@@ -156,7 +156,29 @@ Formato append-only:
 - 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
+### 5. Ajustar `.gitignore` conforme o adapter
+
+Se o adapter NÃO é `filesystem` (ou seja, é um backend externo como Confluence):
+- Verificar se `.gitignore` contém o bloco `# SFW: workspace ignored`
+- Se NÃO contém, **adicionar** ao final do `.gitignore`:
+  ```
+  # SFW: workspace ignored (external backend detected)
+  # Content lives in the external backend (Confluence, etc.) — local is just cache
+  workspace/Output/**
+  !workspace/Output/.gitkeep
+  ```
+- Informar ao usuário: "workspace/Output/ adicionado ao .gitignore (conteúdo vive no {adapter})"
+
+Se o adapter É `filesystem`:
+- Se `.gitignore` contém o bloco `# SFW: workspace ignored`, **removê-lo**
+- Informar ao usuário: "workspace/Output/ removido do .gitignore (modo local)"
+
+Isso garante que:
+- Projetos com Confluence não commitam cache local
+- Projetos que mudam de Confluence → filesystem voltam a rastrear
+- A lógica roda no momento certo (após configurar `sfw.config.yml`, não no `init`)
+
+### 6. Informar o usuário
 
 ```
 Insumos carregados em workspace/Input/{nome}/

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

@@ -0,0 +1,240 @@
+# /sf-mcp <provider>
+
+Setup interativo de backend externo. Pergunta os dados necessários e cria todos os arquivos de configuração.
+
+## Providers disponíveis
+
+| Provider | O que faz |
+|----------|-----------|
+| `confluence` | Configura MCP Atlassian + `sfw.config.yml` + `.mcp.json` + `.gitignore` |
+
+Futuros: `notion`, `jira`, `filesystem` (não precisa de MCP, só cria `sfw.config.yml`).
+
+## Uso
+
+```
+/sf-mcp confluence
+```
+
+---
+
+## Provider: Confluence
+
+### Passo 1 — Verificar pré-requisitos
+
+Verificar se `uvx` está instalado:
+```bash
+uvx --version
+```
+
+Se NÃO está instalado:
+```
+uvx não encontrado. Instale com:
+  pip install uv
+
+Depois rode /sf-mcp confluence novamente.
+```
+**Parar aqui** se uvx não estiver disponível.
+
+### Passo 2 — Coletar dados do usuário
+
+Perguntar um por um, com explicação curta:
+
+```
+Configurando Confluence para o SFW.
+
+1. URL do Confluence (ex: https://sua-empresa.atlassian.net/wiki):
+   >
+
+2. Email da conta Atlassian (ex: dev@empresa.com):
+   >
+
+3. API Token (gere em https://id.atlassian.com/manage-profile/security/api-tokens):
+   >
+
+4. Space Key (as letras na URL: /wiki/spaces/XX/...):
+   >
+```
+
+Após coletar os 4 dados, perguntar sobre a estrutura no Confluence:
+
+```
+5. Você já tem pages Input e Output criadas no Confluence? (s/n)
+```
+
+**Se SIM** — pedir os Page IDs:
+```
+   Page ID da page Input (o número na URL /pages/XXXXX/...):
+   >
+
+   Page ID da page Output:
+   >
+```
+
+**Se NÃO** — informar que serão criadas:
+```
+   Vou criar a estrutura no Confluence:
+   - {project.name} (raiz)
+     ├── Input
+     └── Output
+
+   Nome do projeto pra page raiz (ex: Meu Projeto):
+   >
+```
+
+Então usar MCP pra criar:
+1. `mcp__atlassian__confluence_create_page` → page raiz com título informado
+2. `mcp__atlassian__confluence_create_page` → page "Input" como filha da raiz
+3. `mcp__atlassian__confluence_create_page` → page "Output" como filha da raiz
+4. Anotar os 3 Page IDs retornados
+
+### Passo 3 — Criar `.mcp.json`
+
+Verificar se `.mcp.json` já existe:
+- Se existe → perguntar se quer sobrescrever ou adicionar entrada
+- Se não existe → criar
+
+Conteúdo (credenciais hardcoded — `${VAR}` NÃO funciona no Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "uvx",
+      "args": ["mcp-atlassian"],
+      "env": {
+        "CONFLUENCE_URL": "{url informada}",
+        "CONFLUENCE_USERNAME": "{email informado}",
+        "CONFLUENCE_API_TOKEN": "{token informado}"
+      }
+    }
+  }
+}
+```
+
+### Passo 4 — Criar `sfw.config.yml`
+
+Verificar se já existe:
+- Se existe → perguntar se quer sobrescrever
+- Se não existe → criar
+
+```yaml
+project:
+  name: "{nome do projeto}"
+
+naming:
+  output_container: "out_{scope}"
+  output_artifact: "{scope} - {type}"
+
+input:
+  adapter: confluence
+  config:
+    space_key: "{space_key}"
+    parent_page_id: "{page_id_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: "{space_key}"
+        parent_page_id: "{page_id_output}"
+      publishes: [PRD, TRD, SDD, Progresso]
+      mode: auto
+      conflict_detection: version
+      approval_mechanism: label
+      approval_label: "sfw-approved"
+```
+
+### Passo 5 — Ajustar `.gitignore`
+
+Verificar que `.gitignore` contém:
+- `.mcp.json` — se não, adicionar
+- Bloco `# SFW: workspace ignored` — se não, adicionar:
+  ```
+  # SFW: workspace ignored (external backend detected)
+  workspace/Output/**
+  !workspace/Output/.gitkeep
+  ```
+
+### Passo 6 — Testar conexão
+
+```
+Testando conexão com o Confluence...
+```
+
+Chamar:
+```
+mcp__atlassian__confluence_get_page_children(page_id={page_id_input})
+```
+
+**Se funcionar**:
+```
+Conexão OK! Confluence configurado com sucesso.
+
+Arquivos criados:
+  .mcp.json          ← credenciais (gitignored)
+  sfw.config.yml     ← configuração do projeto
+  .gitignore         ← atualizado (workspace ignorado)
+
+Próximo passo:
+  1. Crie pages de insumo como filhas de Input no Confluence
+  2. Rode /sf-new-project <nome-da-page> ou /sf-feature <nome-da-page>
+```
+
+**Se falhar** (MCP não disponível):
+```
+MCP não está disponível. Isso acontece porque o Claude Code precisa
+ser reiniciado para carregar o .mcp.json que acabamos de criar.
+
+Arquivos foram criados com sucesso:
+  .mcp.json          ← credenciais
+  sfw.config.yml     ← configuração
+
+Próximo passo:
+  1. Reinicie o Claude Code (feche e abra novamente)
+  2. Rode /sf-mcp confluence test    ← para verificar a conexão
+  3. Depois: /sf-new-project <nome> ou /sf-feature <nome>
+```
+
+### Subcomando: `/sf-mcp confluence test`
+
+Apenas testa a conexão sem criar arquivos:
+
+1. Verificar que `.mcp.json` existe
+2. Verificar que `sfw.config.yml` existe e tem `adapter: confluence`
+3. Chamar `mcp__atlassian__confluence_get_page_children(page_id={page_id_input})`
+4. Se OK → "Conexão OK! {N} pages encontradas em Input"
+5. Se falha → orientar troubleshooting (ver `.github/adapters/SETUP.md`)
+
+## Notas
+
+- `.mcp.json` é SEMPRE gitignored — contém credenciais
+- `sfw.config.yml` é commitável — zero segredos
+- Após criar `.mcp.json`, Claude Code PRECISA ser reiniciado pra carregar o MCP
+- Se o user já tem `.mcp.json` com outras entradas, o comando ADICIONA a entrada `atlassian` sem apagar as existentes
+- Token da Atlassian pode expirar — se der 401 depois de um tempo, gerar novo token e atualizar `.mcp.json`
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| uvx não instalado | Parar, instruir instalação |
+| URL inválida | Pedir novamente |
+| Token vazio | Pedir novamente, linkar página de geração |
+| Space key não encontrado | Pedir novamente, sugerir como descobrir |
+| Page ID inválido | Pedir novamente, sugerir como descobrir |
+| MCP não disponível após criar | Normal — pedir reinício do Claude Code |
+| Create page falhou (403) | Usuário sem permissão de escrita no space |
+
+## Referências
+
+- Setup guide completo: `.github/adapters/SETUP.md`
+- Confluence adapter: `.github/adapters/confluence.md`
+- Interface do adapter: `.github/adapters/interface.md`