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

package/package.json

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

@@ -1,19 +1,18 @@
 # /sf-mcp <provider>
 
-Setup interativo de backend externo. Pergunta os dados necessários e cria todos os arquivos de configuração.
+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 + `sfw.config.yml` + `.mcp.json` + `.gitignore` |
-
-Futuros: `notion`, `jira`, `filesystem` (não precisa de MCP, só cria `sfw.config.yml`).
+| `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
 ```
 
 ---
@@ -36,9 +35,9 @@ Depois rode /sf-mcp confluence novamente.
 ```
 **Parar aqui** se uvx não estiver disponível.
 
-### Passo 2 — Coletar dados do usuário
+### Passo 2 — Coletar credenciais
 
-Perguntar um por um, com explicação curta:
+Perguntar uma por uma:
 
 ```
 Configurando Confluence para o SFW.
@@ -56,71 +55,133 @@ Configurando Confluence para o SFW.
    >
 ```
 
-Após coletar os 4 dados, perguntar sobre a estrutura no Confluence:
+### 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}"
+      }
+    }
+  }
+}
 ```
-5. Você já tem pages Input e Output criadas no Confluence? (s/n)
+
+**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 SIM** — pedir os Page IDs:
+**Se MCP não disponível** (primeira vez — `.mcp.json` acabou de ser criado):
 ```
-   Page ID da page Input (o número na URL /pages/XXXXX/...):
-   >
+.mcp.json criado. O Claude Code precisa ser reiniciado para carregar o MCP.
 
-   Page ID da page Output:
-   >
+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:
 
-**Se NÃO** — informar que serão criadas:
 ```
-   Vou criar a estrutura no Confluence:
-   - {project.name} (raiz)
-     ├── Input
-     └── Output
+Conexão OK!
 
-   Nome do projeto pra page raiz (ex: Meu Projeto):
+5. Qual é a page raiz do seu projeto no Confluence?
+   Cole o Page ID (número na URL) ou o título exato:
    >
 ```
 
-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 5 — Mapear a árvore do projeto
 
-### Passo 3 — Criar `.mcp.json`
+Após receber o Page ID ou título da raiz:
 
-Verificar se `.mcp.json` já existe:
-- Se existe → perguntar se quer sobrescrever ou adicionar entrada
-- Se não existe → criar
+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
 
-Conteúdo (credenciais hardcoded — `${VAR}` NÃO funciona no Claude Code):
+Mostrar ao usuário:
 
-```json
-{
-  "mcpServers": {
-    "atlassian": {
-      "command": "uvx",
-      "args": ["mcp-atlassian"],
-      "env": {
-        "CONFLUENCE_URL": "{url informada}",
-        "CONFLUENCE_USERNAME": "{email informado}",
-        "CONFLUENCE_API_TOKEN": "{token informado}"
-      }
-    }
-  }
-}
+```
+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 4 — Criar `sfw.config.yml`
+### Passo 6 — Identificar Input e Output
 
-Verificar se já existe:
-- Se existe → perguntar se quer sobrescrever
-- Se não existe → criar
+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: "{nome do projeto}"
+  name: "{título da page raiz}"
+  root_page_id: "{page_id raiz}"
 
 naming:
   output_container: "out_{scope}"
@@ -130,7 +191,7 @@ input:
   adapter: confluence
   config:
     space_key: "{space_key}"
-    parent_page_id: "{page_id_input}"
+    parent_page_id: "{page_id escolhido como Input}"
     recursive: true
     include_attachments: true
   cache:
@@ -144,94 +205,88 @@ output:
       adapter: confluence
       config:
         space_key: "{space_key}"
-        parent_page_id: "{page_id_output}"
+        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 5 — Ajustar `.gitignore`
+### Passo 9 — Ajustar `.gitignore`
 
-Verificar que `.gitignore` contém:
-- `.mcp.json` — se não, adicionar
-- Bloco `# SFW: workspace ignored` — se não, adicionar:
+Adicionar se não existem:
+- `.mcp.json`
+- Bloco workspace ignored:
   ```
   # SFW: workspace ignored (external backend detected)
   workspace/Output/**
   !workspace/Output/.gitkeep
   ```
 
-### Passo 6 — Testar conexão
+### Passo 10 — Resumir
 
 ```
-Testando conexão com o Confluence...
-```
+Confluence configurado!
 
-Chamar:
-```
-mcp__atlassian__confluence_get_page_children(page_id={page_id_input})
-```
-
-**Se funcionar**:
-```
-Conexão OK! Confluence configurado com sucesso.
+Projeto: {nome} ({page_id raiz})
+  Input:  {título Input} ({page_id})
+  Output: {título Output} ({page_id})
 
-Arquivos criados:
+Arquivos criados/atualizados:
   .mcp.json          ← credenciais (gitignored)
   sfw.config.yml     ← configuração do projeto
-  .gitignore         ← atualizado (workspace ignorado)
+  .gitignore         ← atualizado
 
-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
+O projeto tem {N} scopes no Input:
+  - {lista dos filhos do Input}
 
 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>
+  /sf-new-project <nome-do-scope>    ← bootstrap técnico
+  /sf-feature <nome-do-scope>        ← nova feature
 ```
 
-### Subcomando: `/sf-mcp confluence test`
+---
+
+## Subcomando: `/sf-mcp confluence test`
 
-Apenas testa a conexão sem criar arquivos:
+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={page_id_input})`
-4. Se OK → "Conexão OK! {N} pages encontradas em Input"
+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 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`
+- 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 |
-| 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 |
+| 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
 

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]