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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-copilot",
-  "version": "0.5.0-beta.14",
+  "version": "0.5.0-beta.16",
   "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,295 @@
+# /sf-mcp <provider>
+
+Setup interativo de backend externo. Pergunta os dados necessários, descobre a estrutura do projeto e cria todos os arquivos de configuração.
+
+## Providers disponíveis
+
+| Provider | O que faz |
+|----------|-----------|
+| `confluence` | Configura MCP Atlassian + descobre projeto + cria `sfw.config.yml` + `.mcp.json` + `.gitignore` |
+
+## Uso
+
+```
+/sf-mcp confluence
+/sf-mcp confluence test     ← só testa conexão
+```
+
+---
+
+## 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 credenciais
+
+Perguntar uma por uma:
+
+```
+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/...):
+   >
+```
+
+### Passo 3 — Criar `.mcp.json`
+
+Verificar se `.mcp.json` já existe:
+- Se existe e já tem entrada `atlassian` → perguntar se quer atualizar
+- Se existe sem `atlassian` → adicionar entrada
+- Se não existe → criar
+
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "uvx",
+      "args": ["mcp-atlassian"],
+      "env": {
+        "CONFLUENCE_URL": "{url}",
+        "CONFLUENCE_USERNAME": "{email}",
+        "CONFLUENCE_API_TOKEN": "{token}"
+      }
+    }
+  }
+}
+```
+
+**IMPORTANTE**: Credenciais hardcoded — `${VAR}` NÃO funciona no Claude Code.
+
+### Passo 4 — Testar conexão e descobrir projeto
+
+Testar chamando:
+```
+mcp__atlassian__confluence_search(query="space.key={space_key}", limit=5)
+```
+ou
+```
+mcp__atlassian__confluence_get_page_children(page_id=<root do space>)
+```
+
+**Se MCP não disponível** (primeira vez — `.mcp.json` acabou de ser criado):
+```
+.mcp.json criado. O Claude Code precisa ser reiniciado para carregar o MCP.
+
+1. Reinicie o Claude Code (feche e abra)
+2. Rode /sf-mcp confluence novamente — vou continuar de onde paramos
+```
+**Parar aqui.**
+
+**Se MCP funcionar** — pedir o projeto:
+
+```
+Conexão OK!
+
+5. Qual é a page raiz do seu projeto no Confluence?
+   Cole o Page ID (número na URL) ou o título exato:
+   >
+```
+
+### Passo 5 — Mapear a árvore do projeto
+
+Após receber o Page ID ou título da raiz:
+
+1. Chamar `mcp__atlassian__confluence_get_page` pra confirmar que existe
+2. Chamar `mcp__atlassian__confluence_get_page_children` na raiz
+3. Chamar recursivamente nos filhos pra mapear a árvore completa
+
+Mostrar ao usuário:
+
+```
+Projeto: "Barbearia Digital" (page_id: 65708)
+
+Estrutura encontrada:
+  ├── Requisitos (page_id: 360668)
+  │   ├── App mobile (page_id: 294950)
+  │   └── Painel admin (page_id: 131084)
+  ├── Documentação técnica (page_id: 294931)
+  ├── Referências (page_id: 557057)
+  └── Decisões (page_id: 425998)
+```
+
+### Passo 6 — Identificar Input e Output
+
+Perguntar ao usuário:
+
+```
+Preciso saber qual pasta contém os INSUMOS (Input) e onde devo PUBLICAR os artefatos (Output).
+
+Qual dessas é o Input (onde estão os insumos do PM/PO)?
+  1. Requisitos (360668)
+  2. Documentação técnica (294931)
+  3. Referências (557057)
+  4. Decisões (425998)
+  5. Criar nova page "Input"
+  >
+```
+
+Após o user escolher Input:
+
+```
+Qual dessas é o Output (onde publico TRD, SDD, Progresso)?
+  1. Documentação técnica (294931)
+  2. Referências (557057)
+  3. Decisões (425998)
+  4. Criar nova page "Output"
+  >
+```
+
+**Se o user escolher "Criar nova"** → usar `mcp__atlassian__confluence_create_page` como filha da raiz.
+
+### Passo 7 — Sugerir mapeamento de páginas úteis (opcional)
+
+Se a árvore tem outras pages relevantes, sugerir:
+
+```
+Encontrei outras páginas que podem ser úteis durante o desenvolvimento:
+
+  - "Referências" (557057) → posso consultar durante /sf-extract e /sf-design
+  - "Decisões" (425998) → posso consultar para ADRs no /sf-design
+
+Quer que eu mapeie essas páginas como contexto adicional? (s/n)
+```
+
+Se sim, registrar no `sfw.config.yml` como `context_pages`.
+
+### Passo 8 — Criar `sfw.config.yml`
+
+```yaml
+project:
+  name: "{título da page raiz}"
+  root_page_id: "{page_id raiz}"
+
+naming:
+  output_container: "out_{scope}"
+  output_artifact: "{scope} - {type}"
+
+input:
+  adapter: confluence
+  config:
+    space_key: "{space_key}"
+    parent_page_id: "{page_id escolhido como 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 escolhido como Output}"
+      publishes: [PRD, TRD, SDD, Progresso]
+      mode: auto
+      conflict_detection: version
+      approval_mechanism: label
+      approval_label: "sfw-approved"
+
+# Pages de contexto adicional (consultadas pelo /sf-extract e /sf-design)
+# context_pages:
+#   - id: "557057"
+#     title: "Referências"
+#     use_in: [extract, design]
+#   - id: "425998"
+#     title: "Decisões"
+#     use_in: [design]
+```
+
+### Passo 9 — Ajustar `.gitignore`
+
+Adicionar se não existem:
+- `.mcp.json`
+- Bloco workspace ignored:
+  ```
+  # SFW: workspace ignored (external backend detected)
+  workspace/Output/**
+  !workspace/Output/.gitkeep
+  ```
+
+### Passo 10 — Resumir
+
+```
+Confluence configurado!
+
+Projeto: {nome} ({page_id raiz})
+  Input:  {título Input} ({page_id})
+  Output: {título Output} ({page_id})
+
+Arquivos criados/atualizados:
+  .mcp.json          ← credenciais (gitignored)
+  sfw.config.yml     ← configuração do projeto
+  .gitignore         ← atualizado
+
+O projeto tem {N} scopes no Input:
+  - {lista dos filhos do Input}
+
+Próximo passo:
+  /sf-new-project <nome-do-scope>    ← bootstrap técnico
+  /sf-feature <nome-do-scope>        ← nova feature
+```
+
+---
+
+## Subcomando: `/sf-mcp confluence test`
+
+Apenas testa a conexão sem criar/modificar 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={input.parent_page_id})`
+4. Se OK → "Conexão OK! {N} scopes encontrados em Input: {lista}"
+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
+- O framework conhece o projeto INTEIRO (raiz + toda a árvore), não só Input/Output
+- `context_pages` permite que /sf-extract e /sf-design consultem páginas extras como referência
+- Token Atlassian pode expirar — se der 401, gerar novo e atualizar `.mcp.json`
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| uvx não instalado | Parar, instruir instalação |
+| MCP não disponível | Pedir reinício do Claude Code |
+| Page raiz não encontrada | Pedir ID/título correto |
+| Sem permissão de escrita | Informar, pedir ao admin |
+| Space key errado | Listar spaces disponíveis se possível |
+
+## Referências
+
+- Setup guide completo: `.github/adapters/SETUP.md`
+- Confluence adapter: `.github/adapters/confluence.md`
+- Interface do adapter: `.github/adapters/interface.md`

package/templates/sfw.config.yml.example

@@ -23,6 +23,8 @@
 # ----------------------------------------------------------------------------
 project:
   name: "Meu Projeto"
+  # Page ID raiz do projeto no Confluence (o framework conhece o projeto inteiro)
+  # root_page_id: "65708"
 
 # ----------------------------------------------------------------------------
 # naming — templates de nome (aplicados pela engine em .github/adapters/naming.md)
@@ -129,3 +131,17 @@ output:
     #   mode: auto
     #   conflict_detection: hash
     #   approval_mechanism: none
+
+# ----------------------------------------------------------------------------
+# context_pages — páginas extras que o framework pode consultar (opcional)
+# ----------------------------------------------------------------------------
+# O /mcp descobre a árvore do projeto e sugere pages que podem ser úteis
+# como contexto durante /extract e /design (referências, decisões, etc.)
+#
+# context_pages:
+#   - id: "557057"
+#     title: "Referências"
+#     use_in: [extract, design]
+#   - id: "425998"
+#     title: "Decisões"
+#     use_in: [design]