spec-first-copilot 0.7.0-beta.1 → 0.7.0

package/templates/.github/adapters/SETUP.md

@@ -1,314 +1,314 @@
-# 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, 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 da page {Page ID do Input}
-```
-
-**IMPORTANTE — Como o Confluence funciona no Claude Code:**
-
-O Confluence **NÃO é um comando de terminal**. Não existe `confluence` como CLI.
-O acesso é feito via **MCP tools** — funções que o Claude Code expõe automaticamente
-quando o server MCP está configurado no `.mcp.json`.
-
-As tools disponíveis são prefixadas com `mcp__atlassian__confluence_`:
-
-| Tool MCP | O que faz |
-|----------|-----------|
-| `mcp__atlassian__confluence_get_page` | Lê conteúdo de uma page por ID |
-| `mcp__atlassian__confluence_get_page_children` | Lista filhos diretos de uma page |
-| `mcp__atlassian__confluence_create_page` | Cria page nova |
-| `mcp__atlassian__confluence_update_page` | Atualiza conteúdo de page existente |
-| `mcp__atlassian__confluence_search` | Busca por texto no space |
-| `mcp__atlassian__confluence_get_labels` | Lê labels de uma page |
-| `mcp__atlassian__confluence_get_attachments` | Lista attachments de uma page |
-| `mcp__atlassian__confluence_download_attachment` | Baixa attachment |
-
-O agent chama essas tools diretamente — **nunca via bash/terminal**.
-Se o agent tentar rodar `confluence ...` no terminal, está errado.
-
-**Como verificar que o MCP está funcionando:**
-1. Reinicie o Claude Code após criar/editar `.mcp.json`
-2. Peça ao agent: "Use a tool `mcp__atlassian__confluence_get_page` com page_id {ID}" 
-3. Se funcionar, está conectado. Se der "tool not found", o MCP não subiu — verifique `.mcp.json`
-
-**Nota**: `get_page_children` retorna apenas filhos **diretos** (não recursivo).
-Para trazer toda a árvore, o agent faz loop: chama `get_page_children` em cada
-filho que tem `hasChildren`, empilha e desce. O `/sf-load` já faz isso automaticamente.
-
----
-
-## 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, 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. `/sf-start 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, Progresso]
-         mode: auto
-   ```
-3. Re-rode `/sf-extract`, `/sf-design`, `/sf-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`
+# 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, 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 da page {Page ID do Input}
+```
+
+**IMPORTANTE — Como o Confluence funciona no Claude Code:**
+
+O Confluence **NÃO é um comando de terminal**. Não existe `confluence` como CLI.
+O acesso é feito via **MCP tools** — funções que o Claude Code expõe automaticamente
+quando o server MCP está configurado no `.mcp.json`.
+
+As tools disponíveis são prefixadas com `mcp__atlassian__confluence_`:
+
+| Tool MCP | O que faz |
+|----------|-----------|
+| `mcp__atlassian__confluence_get_page` | Lê conteúdo de uma page por ID |
+| `mcp__atlassian__confluence_get_page_children` | Lista filhos diretos de uma page |
+| `mcp__atlassian__confluence_create_page` | Cria page nova |
+| `mcp__atlassian__confluence_update_page` | Atualiza conteúdo de page existente |
+| `mcp__atlassian__confluence_search` | Busca por texto no space |
+| `mcp__atlassian__confluence_get_labels` | Lê labels de uma page |
+| `mcp__atlassian__confluence_get_attachments` | Lista attachments de uma page |
+| `mcp__atlassian__confluence_download_attachment` | Baixa attachment |
+
+O agent chama essas tools diretamente — **nunca via bash/terminal**.
+Se o agent tentar rodar `confluence ...` no terminal, está errado.
+
+**Como verificar que o MCP está funcionando:**
+1. Reinicie o Claude Code após criar/editar `.mcp.json`
+2. Peça ao agent: "Use a tool `mcp__atlassian__confluence_get_page` com page_id {ID}" 
+3. Se funcionar, está conectado. Se der "tool not found", o MCP não subiu — verifique `.mcp.json`
+
+**Nota**: `get_page_children` retorna apenas filhos **diretos** (não recursivo).
+Para trazer toda a árvore, o agent faz loop: chama `get_page_children` em cada
+filho que tem `hasChildren`, empilha e desce. O `/sf-load` já faz isso automaticamente.
+
+---
+
+## 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, 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. `/sf-start 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, Progresso]
+         mode: auto
+   ```
+3. Re-rode `/sf-extract`, `/sf-design`, `/sf-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`