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

package/package.json

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