spec-first-claude 0.5.0-beta.3 → 0.5.0-beta.5

package/lib/init.js

@@ -62,8 +62,8 @@ function init({ name, templatesDir, targetDir }) {
   console.log(`\nDone! Project "${name}" is ready.`);
   console.log('\nNext steps:');
   console.log(`  1. cd ${name}`);
-  console.log('  2. Add your input files to workspace/Input/setup_projeto/');
-  console.log('  3. Run /setup-projeto to start the pipeline');
+  console.log('  2. Create a folder in workspace/Input/ with your project files (e.g. workspace/Input/my_app/)');
+  console.log('  3. Run /new-project <folder-name> to start the pipeline');
   console.log('');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-claude",
-  "version": "0.5.0-beta.3",
+  "version": "0.5.0-beta.5",
   "description": "Spec-first workflow kit for Claude Code — AI-driven development with specs, not guesswork",
   "bin": {
     "spec-first-claude": "bin/cli.js"

package/templates/.claude/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: `.claude/adapters/interface.md`
+- ConfluenceAdapter: `.claude/adapters/confluence.md`
+- FilesystemAdapter: `.claude/adapters/filesystem.md`
+- Erros: `.claude/adapters/errors.md`
+- Naming: `.claude/adapters/naming.md`

package/templates/.claude/commands/new-project.md

@@ -0,0 +1,72 @@
+# /new-project <nome>
+
+Orquestrador de bootstrap técnico do projeto.
+Cria contexto TRD a partir dos insumos em `workspace/Input/{nome}/`, chama /extract e para no checkpoint de aprovação.
+
+Simétrico ao `/feature <nome>` — a diferença é que gera TRD (perfil técnico) em vez de PRD (perfil de produto).
+
+## Argumento
+
+`<nome>` = nome do item no Input. O usuário nomeia livremente (ex: `app_barbearia`, `meu_sistema`, `api_pagamentos`). O agent busca `workspace/Input/{nome}/` — se não existir, para com erro.
+
+## Execução
+
+Siga EXATAMENTE os passos da skill em ordem. Leia o arquivo completo antes de agir.
+
+### Pré-condições — validar TODAS antes de prosseguir
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `workspace/Input/{nome}/` existe | Parar → "Crie a pasta workspace/Input/{nome}/ e adicione seus insumos" |
+| 2 | Pasta contém pelo menos 1 arquivo (ignorar .gitkeep) | Parar → "Adicione insumos na pasta (aceitos: .md, .txt, .sql, .xml, .html, .json, .csv, .png, .jpg, .pdf — qualquer formato)" |
+| 3 | `workspace/Output/{nome}/.context.md` não existe ou status é `not_started` | Parar → "Este escopo já está em andamento. Verifique o status em .context.md" |
+
+### Passos
+
+1. Criar `workspace/Output/{nome}/` se não existir
+
+2. Criar `.context.md`:
+```yaml
+---
+nome: "{nome}"
+tipo: "project"
+documento: "TRD"
+pm_path: "workspace/Input/{nome}/"
+status: "not_started"
+ultima_skill: "/new-project"
+atualizado_em: "{{ISO_DATETIME}}"
+---
+```
+
+3. Sugerir /discovery (RECOMENDADO):
+```
+Recomendo rodar /discovery antes da extração para análise profunda dos insumos.
+Quer rodar /discovery workspace/Input/{nome}/ agora? (s/n)
+```
+Se SIM → rodar discovery, salvar discovery.md em workspace/Output/{nome}/
+Se NÃO → pular direto para extract
+
+4. Executar /extract {nome} (seguir o command /extract)
+
+5. CHECKPOINT — Parar e informar:
+```
+TRD gerado em workspace/Output/{nome}/TRD.md
+
+Revise o documento. Quando estiver satisfeito, execute:
+  /design {nome}
+
+Se precisar adicionar mais insumos, coloque na pasta workspace/Input/{nome}/
+e execute:
+  /extract {nome}
+```
+
+**O orquestrador encerra aqui.** Próximos passos do usuário:
+1. `/design {nome}` (pergunta aprovação → gera SDD + docs/ + projetos.yaml)
+2. `/plan {nome}` (gera tasks com campo Repo por task)
+3. `/dev {nome}` (INFRA-001 cria/clona repos em projetos/, executa tasks nos repos corretos)
+
+### Notas
+- docs/ é gerado pelo /design (passo 3), não por tasks DOC
+- `projetos.yaml` é gerado pelo /design (passo 3b) — mapeia serviços para repos
+- Repos são criados/clonados pelo /dev (INFRA-001) dentro de `projetos/`
+- /merge-delta NÃO se aplica ao new-project (é criação, não atualização)

package/templates/CLAUDE.md

@@ -24,7 +24,7 @@ Verificar que TODOS os 9 commands estão acessíveis:
 
 | Command | Caminho |
 |---------|---------|
-| `/setup-projeto` | `.claude/commands/setup-projeto.md` |
+| `/new-project` | `.claude/commands/new-project.md` |
 | `/feature` | `.claude/commands/feature.md` |
 | `/discovery` | `.claude/commands/discovery.md` |
 | `/extract` | `.claude/commands/extract.md` |
@@ -76,7 +76,7 @@ ESTE REPO (projeto-base) = ORQUESTRADOR
 
 ```
 workspace/Input/ (qualquer arquivo)
-    ↓ /setup-projeto (uma vez) ou /feature (por feature)
+    ↓ /new-project <nome> (TRD — bootstrap técnico) ou /feature <nome> (PRD — feature)
 /discovery → análise profunda dos insumos (RECOMENDADO, opcional)
     ↓
 /extract → PRD ou TRD em workspace/Output/{nome}/ (checkpoint — usuário revisa e aprova)
@@ -93,7 +93,7 @@ workspace/Input/ (qualquer arquivo)
 
 | Command | Tipo | O que faz |
 |---------|------|-----------|
-| `/setup-projeto` | Orquestrador | Bootstrap: cria .context.md, chama /extract, para no checkpoint. Roda UMA vez |
+| `/new-project <nome>` | Orquestrador | Bootstrap técnico: cria .context.md tipo TRD, chama /extract, para no checkpoint |
 | `/feature <nome>` | Orquestrador | Feature: cria .context.md tipo PRD, chama /extract, para no checkpoint |
 | `/discovery <path>` | Utilitária | Análise profunda dos insumos (RECOMENDADO antes do /extract) |
 | `/extract <nome>` | Atômico | Lê workspace/Input/{nome}/ → gera PRD ou TRD. Re-executável para novos insumos |
@@ -166,8 +166,7 @@ specs/                       ← AGENT CONTRACTS (projeções do SDD pro coder)
 
 workspace/                   ← TEAM CONTENT (futuro wiki)
 ├── Input/                   ← Insumos brutos (QUALQUER formato — nunca modificar)
-│   ├── setup_projeto/       ← Insumos de bootstrap
-│   └── feat_*/              ← Insumos por feature
+│   └── {nome}/              ← Nomeado livremente pelo usuário (ex: app_barbearia, feat_login)
 └── Output/                  ← Artefatos humanos gerados pelo workflow
     └── {nome}/
         ├── PRD.md ou TRD.md ← Requirements (gerado pelo /extract)

package/templates/.claude/commands/setup-projeto.md

@@ -1,68 +0,0 @@
-# /setup-projeto
-
-Orquestrador de bootstrap do projeto. Executa uma única vez.
-Cria contexto TRD, chama /extract e para no checkpoint de aprovação.
-
-## Execução
-
-Siga EXATAMENTE os passos da skill em ordem. Leia o arquivo completo antes de agir.
-
-### Pré-condições — validar TODAS antes de prosseguir
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | `workspace/Input/setup_projeto/` existe | Parar → "Crie a pasta workspace/Input/setup_projeto/ e adicione seus insumos" |
-| 2 | Pasta contém pelo menos 1 arquivo (ignorar .gitkeep) | Parar → "Adicione insumos na pasta (aceitos: .md, .txt, .sql, .xml, .html, .json, .csv, .png, .jpg, .pdf — qualquer formato)" |
-| 3 | `docs/` está vazio ou contém apenas .gitkeep | Parar → "Setup já foi executado. Use /feature para novas funcionalidades" |
-| 4 | `workspace/Output/setup_projeto/.context.md` não existe ou status é `not_started` | Parar → "Setup já está em andamento. Verifique o status em .context.md" |
-
-### Passos
-
-1. Criar `workspace/Output/setup_projeto/` se não existir
-
-2. Criar `.context.md`:
-```yaml
----
-nome: "setup_projeto"
-tipo: "setup"
-documento: "TRD"
-pm_path: "workspace/Input/setup_projeto/"
-status: "not_started"
-ultima_skill: "/setup-projeto"
-atualizado_em: "{{ISO_DATETIME}}"
----
-```
-
-3. Sugerir /sf-discovery (RECOMENDADO):
-```
-📋 Recomendo rodar /sf-discovery antes da extração para análise profunda dos insumos.
-Quer rodar /sf-discovery workspace/Input/setup_projeto/ agora? (s/n)
-```
-Se SIM → rodar discovery, salvar discovery.md em workspace/Output/setup_projeto/
-Se NÃO → pular direto para extract
-
-4. Executar /extract setup_projeto (seguir o command /extract)
-
-5. CHECKPOINT — Parar e informar:
-```
-✅ TRD gerado em workspace/Output/setup_projeto/TRD.md
-
-Revise o documento. Quando estiver satisfeito, execute:
-  /design setup_projeto
-
-Se precisar adicionar mais insumos, coloque na pasta workspace/Input/setup_projeto/
-e execute:
-  /extract setup_projeto
-```
-
-**O orquestrador encerra aqui.** Próximos passos do usuário:
-1. `/design setup_projeto` (pergunta aprovação → gera SDD + docs/ + projetos.yaml)
-2. `/plan setup_projeto` (gera tasks com campo Repo por task)
-3. `/dev setup_projeto` (INFRA-001 cria/clona repos em projetos/, executa tasks nos repos corretos)
-
-### Notas
-- Esta skill roda UMA ÚNICA VEZ por projeto
-- docs/ é gerado pelo /design (passo 3), não por tasks DOC
-- `projetos.yaml` é gerado pelo /design (passo 3b) — mapeia serviços para repos
-- Repos são criados/clonados pelo /dev (INFRA-001) dentro de `projetos/`
-- /merge-delta NÃO se aplica ao setup (é criação, não atualização)