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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-copilot",
-  "version": "0.5.0-beta.4",
+  "version": "0.5.0-beta.5",
   "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,287 @@
+# 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 de {Page ID do Input}
+```
+
+O agent deve conseguir usar `confluence_get_page_children` e listar o conteúdo.
+Se der erro de auth → verifique email, token e URL no `.mcp.json`.
+Se o MCP não estiver disponível → reinicie o Claude Code.
+
+---
+
+## 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`