spec-first-claude 0.6.0-beta.1 → 0.6.0-beta.10

package/bin/cli.js

@@ -8,19 +8,19 @@ const args = process.argv.slice(2);
 const command = args[0];
 
 function printUsage() {
-  console.log('Usage:');
-  console.log('  spec-first-claude init --name=<project-name> [--target=<path>]');
-  console.log('  spec-first-claude update [--target=<path>] [--force]');
+  console.log('Uso:');
+  console.log('  spec-first-claude init --name=<nome-do-projeto> [--target=<caminho>]');
+  console.log('  spec-first-claude update [--target=<caminho>] [--force]');
   console.log('');
-  console.log('Commands:');
-  console.log('  init     Create a new spec-first project');
-  console.log('  update   Update an existing project with new framework files');
-  console.log('           (adds missing files, updates framework files like commands/adapters/agents)');
+  console.log('Comandos:');
+  console.log('  init     Cria um novo projeto spec-first');
+  console.log('  update   Atualiza projeto existente com arquivos novos do framework');
+  console.log('           (adiciona faltantes, atualiza commands/adapters/agents/templates)');
   console.log('');
-  console.log('Options:');
-  console.log('  --name=<name>    Project name (required for init)');
-  console.log('  --target=<path>  Target directory (defaults to ./<name> for init, cwd for update)');
-  console.log('  --force          Force update all files, not just framework files (use with caution)');
+  console.log('Opções:');
+  console.log('  --name=<nome>      Nome do projeto (obrigatório no init)');
+  console.log('  --target=<path>    Diretório destino (default: ./<nome> no init, cwd no update)');
+  console.log('  --force            Força atualizar TODOS arquivos, não só os do framework (cuidado)');
 }
 
 function parseArgs(args) {
@@ -40,7 +40,7 @@ if (command === 'init') {
   const opts = parseArgs(args.slice(1));
 
   if (!opts.name) {
-    console.error('Error: --name is required.\n');
+    console.error('Erro: --name é obrigatório.\n');
     printUsage();
     process.exit(1);
   }
@@ -64,7 +64,7 @@ if (command === 'init') {
 } else {
   printUsage();
   if (command) {
-    console.error(`\nUnknown command: "${command}"`);
+    console.error(`\nComando desconhecido: "${command}"`);
   }
   process.exit(command ? 1 : 0);
 }

package/lib/init.js

@@ -42,18 +42,31 @@ function init({ name, templatesDir, targetDir }) {
   const dest = targetDir || path.resolve(process.cwd(), name);
 
   const existed = fs.existsSync(dest);
-  console.log(`\n${existed ? 'Initializing' : 'Creating'} project "${name}" in ${dest}\n`);
+  console.log(`\n${existed ? 'Inicializando' : 'Criando'} projeto "${name}" em ${dest}\n`);
 
   const replacements = { [PLACEHOLDER]: name };
   copyDir(templatesDir, dest, replacements);
   patchProjectName(dest, name);
 
-  console.log(`Done! Project "${name}" is ready.`);
-  console.log('\nNext steps:');
+  console.log(`Pronto! Projeto "${name}" criado.`);
+  console.log('\nPróximos passos:');
   console.log(`  1. cd ${name}`);
-  console.log('  2. Create a folder in workspace/Input/ with your project files (e.g. workspace/Input/my_app/)');
-  console.log('  3. Copy sfw.config.yml.example to sfw.config.yml and configure your backend');
-  console.log('  4. Run /new-project <folder-name> to start the pipeline');
+  console.log('  2. Crie uma pasta em workspace/Input/ com os insumos do seu projeto');
+  console.log('     (ex: workspace/Input/meu_app/requisitos.md)');
+  console.log('');
+  console.log('  3. (Opcional) Configure o backend de input/output:');
+  console.log('       cp sfw.config.yml.example sfw.config.yml');
+  console.log('     Sem isso, o framework roda 100% local (sem Confluence/etc.)');
+  console.log('');
+  console.log('  4. (Opcional, se vai usar Confluence) Prepare o ambiente ANTES de abrir o Claude:');
+  console.log('       node .claude/scripts/bootstrap-confluence.js');
+  console.log('     Valida uvx, coleta credenciais, gera .mcp.json e pré-cacheia o MCP.');
+  console.log('     Evita o ciclo "abrir Claude → faltar dep → reiniciar".');
+  console.log('');
+  console.log('  5. Abra o Claude Code no diretório do projeto e rode:');
+  console.log('       /sfw-start <nome-da-pasta-em-Input>');
+  console.log('     O framework detecta first-run automaticamente (cria docs/) vs feature');
+  console.log('     (atualiza docs/ via merge).');
   console.log('');
 }
 

package/lib/update.js

@@ -18,36 +18,36 @@ function update({ templatesDir, targetDir, force }) {
   const dest = targetDir || process.cwd();
 
   if (!fs.existsSync(dest)) {
-    console.error(`Error: directory "${dest}" does not exist.`);
-    console.error('Run "spec-first-claude init --name=<name>" first to create a project.');
+    console.error(`Erro: diretório "${dest}" não existe.`);
+    console.error('Rode "spec-first-claude init --name=<nome>" primeiro pra criar o projeto.');
     process.exit(1);
   }
 
   const claudeDir = path.join(dest, '.claude');
   if (!fs.existsSync(claudeDir)) {
-    console.error('Error: not a spec-first project (missing .claude/ directory).');
-    console.error('Run "spec-first-claude init --name=<name>" first.');
+    console.error('Erro: não é um projeto spec-first (pasta .claude/ não encontrada).');
+    console.error('Rode "spec-first-claude init --name=<nome>" primeiro.');
     process.exit(1);
   }
 
-  console.log(`\nUpdating project in ${dest}\n`);
+  console.log(`\nAtualizando projeto em ${dest}\n`);
 
   const stats = { added: [], updated: [], skipped: 0 };
   syncDir(templatesDir, dest, force, stats, dest);
 
   console.log('');
   if (stats.added.length > 0) {
-    console.log(`Added (${stats.added.length}):`);
+    console.log(`Adicionados (${stats.added.length}):`);
     for (const f of stats.added) console.log(`  + ${f}`);
   }
   if (stats.updated.length > 0) {
-    console.log(`Updated (${stats.updated.length}):`);
+    console.log(`Atualizados (${stats.updated.length}):`);
     for (const f of stats.updated) console.log(`  ~ ${f}`);
   }
   if (stats.added.length === 0 && stats.updated.length === 0) {
-    console.log('Already up to date — no new files to add.');
+    console.log('Já está atualizado — nenhum arquivo novo pra adicionar.');
   } else {
-    console.log(`\n${stats.added.length} added, ${stats.updated.length} updated, ${stats.skipped} unchanged`);
+    console.log(`\n${stats.added.length} adicionado(s), ${stats.updated.length} atualizado(s), ${stats.skipped} inalterado(s)`);
   }
   console.log('');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-claude",
-  "version": "0.6.0-beta.1",
+  "version": "0.6.0-beta.10",
   "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/CHANGELOG.md

@@ -8,6 +8,282 @@
 
 ---
 
+## 0.6.0-beta.10 (2026-04-13)
+
+### `bootstrap-confluence.js` agora é idempotente
+
+Script agora lê `.mcp.json` existente e reusa valores da entry `atlassian` em
+vez de perguntar tudo de novo:
+
+- Se `CONFLUENCE_URL` já existe: mostra URL atual, pergunta "Manter? [S/n]"
+- Se `CONFLUENCE_USERNAME` já existe: mostra email atual, pergunta "Manter? [S/n]"
+- Se `CONFLUENCE_API_TOKEN` já existe: mostra token mascarado (`abcd…wxyz`), pergunta "Manter? [S/n]"
+- Default ENTER = manter. Responder `n` abre o prompt completo da informação.
+
+Se todos os 3 campos foram mantidos: detecta que nada mudou e **não reescreve**
+`.mcp.json` (evita dirty git). Se mudou algo: reescreve preservando outras
+entries MCP (Supabase, GitHub, etc.).
+
+Útil pra: reexecução após novo rebuild do MCP, rotação apenas do token, debug
+de setup sem perder credenciais já válidas.
+
+---
+
+## 0.6.0-beta.9 (2026-04-13)
+
+### CLI em pt-BR + dica de bootstrap-confluence no init
+
+Mensagens do CLI (`init` e `update`) traduzidas para pt-BR — usuário final é o público.
+
+Mensagem do `init` reescrita para deixar **explícito o passo opcional de pré-setup
+do Confluence**:
+
+```
+Pronto! Projeto "X" criado.
+
+Próximos passos:
+  1. cd X
+  2. Crie uma pasta em workspace/Input/ com os insumos do seu projeto
+  3. (Opcional) Configure o backend de input/output:
+       cp sfw.config.yml.example sfw.config.yml
+  4. (Opcional, se vai usar Confluence) Prepare o ambiente ANTES de abrir o Claude:
+       node .claude/scripts/bootstrap-confluence.js
+  5. Abra o Claude Code e rode: /sfw-start <nome-da-pasta>
+```
+
+O passo 4 era invisível antes — só aparecia inline na "Dica" do skill `/mcp`.
+Agora aparece logo no fim do `init`, no momento exato em que o usuário vai decidir
+se prepara o Confluence ou não.
+
+---
+
+## 0.6.0-beta.8 (2026-04-13)
+
+### Novo: `bootstrap-confluence.js` (opcional, pré-Claude)
+
+Script Node cross-platform em `.claude/scripts/bootstrap-confluence.js` que prepara
+o ambiente para o backend Confluence **antes** de abrir o Claude Code. Evita o ciclo
+"abrir Claude → descobrir que falta `uvx` ou credenciais → sair, ajustar, reiniciar".
+
+O que faz:
+1. Valida `uvx` instalado (orienta install se faltar — não instala automaticamente)
+2. Coleta URL do Confluence, email Atlassian e API Token (com link pra gerar o token)
+3. Gera/mescla `.mcp.json` preservando outras entries de MCP existentes
+4. Garante `.mcp.json` no `.gitignore`
+5. Pré-cacheia o pacote `mcp-atlassian` via `uvx` (100+ deps no primeiro uso)
+
+Depois é só abrir o Claude Code e rodar `/mcp confluence` — vai direto pra descoberta
+da árvore no Confluence, sem reiniciar.
+
+Uso: `node .claude/scripts/bootstrap-confluence.js`
+Opcional — `/mcp confluence` sozinho também cobre esses passos, mas exige reiniciar
+Claude Code após criar `.mcp.json`.
+
+Skill `/mcp` ganhou nota referenciando o script como atalho recomendado.
+
+### Primeira release sincronizada pelo `sync-kits`
+
+Esta é a primeira release onde **toda a edição aconteceu só no kit Claude** e o script
+`npm run sync-kits` propagou para o kit Copilot automaticamente. Fluxo validado.
+
+---
+
+## 0.6.0-beta.7 (2026-04-13)
+
+### Script de sync entre kits (interno, não afeta o user)
+
+Criado `scripts/sync-kits.js` no repo SFW (não entra no pacote publicado). Mantém o
+kit Copilot (`.github/`) sincronizado com o kit Claude (`.claude/`) aplicando renames
+automaticamente (`.claude/` → `.github/`, `/extract` → `/sf-extract`, etc.).
+
+Fluxo agora: editar apenas em `spec-first-claude`, rodar `npm run sync-kits`, commit
+dos 2 kits juntos. CI pode usar `npm run check-kits` pra detectar drift.
+
+**Sem impacto pro usuário do kit Claude** — conteúdo idêntico ao beta.6.
+
+---
+
+## 0.6.0-beta.6 (2026-04-13)
+
+### Fixes detectados no smoke test de `beta.5`
+
+Rodamos o pipeline completo (`/sfw-start → /extract → /design → /plan`) em projeto
+novo com feature simples (todo app backend) e detectamos 6 inconsistências entre
+skills e templates. Todas corrigidas:
+
+**1. PRD §14 — coluna "Resolvido em docs/" adicionada**
+
+Skill `/extract` (beta.5) descreveu mecanismo do Analyzer marcar ambiguidades como
+"resolvido em docs/X §Y", mas o template do PRD não tinha coluna para isso. Agora
+a tabela de §14 tem 6 colunas: `ID | Pergunta | Contexto | Fonte | Resposta | Resolvido em docs/`.
+
+**2. PRD §14 — renomeada "Resposta do usuário" → "Resposta"**
+
+Skill `/extract` fala em preencher "coluna `Resposta`" mas o template tinha
+"Resposta do usuário". Alinhado com o skill. Também adicionado ID padronizado
+`AMB-NNN` na primeira coluna (antes era só `#`).
+
+**3. PRD §14 e SDD §12 padronizados**
+
+SDD §12 Ambiguidades também passou a usar ID `AMB-NNN` continuando a sequência
+do PRD §14. Texto do bloqueio do SDD corrigido: não é o `/design` que bloqueia
+no §12 (ele já gerou), é o `/plan` (que lê o SDD como input).
+
+**4. Status do Progresso.md clarificado**
+
+`Status Geral` do Progresso.md era confundido com o status da pipeline em
+`.context.md`. Renomeado para `Status das Fases` + bloco explicativo deixando
+claro que **este arquivo rastreia fases de entrega do PRD §11, não o pipeline**.
+
+**5. Bool tipado corretamente no `.context.md`**
+
+Antes: `first_run: "{{true|false}}"` (string com aspas). Depois: `first_run: {{true|false}}`
+(bool YAML real). Instruções do template reforçam: "SEM aspas".
+
+**6. `projetos.yaml` sem stack hardcoded**
+
+Template tinha `stack: ".NET 8"` literal no exemplo `api`. Podia induzir projetos
+Node/Python a errar. Agora usa `{{STACK_BACKEND}}` como placeholder + bloco
+explicativo listando exemplos por stack (Backend/Frontend/Mobile) como referência.
+Instruções reforçam: "stack DEVE vir do SDD §3.1".
+
+### Extras
+
+**SDD template com guidance sobre escopo pequeno**
+
+Adicionado bloco no topo do template explicando que 3-4 seções preenchidas + o
+resto como "N/A" é comportamento esperado para apps simples — não inflar conteúdo
+pra "preencher" seções vazias. Áreas não tocadas (§4-§7) usam `GATE: NÃO`.
+
+---
+
+## 0.6.0-beta.5 (2026-04-13)
+
+### Refino dos templates de specs/
+
+Templates de projeção do SDD (`specs/{scope}/`) refinados com padrões consolidados de BDD/contract-first. Dois passos de refino fizeram parte desta release.
+
+**`scenarios.template.md`** — mudanças:
+- Seção "Fluxos de Erro e Edge Cases" separada do happy path com coluna "Ref CA" (antes ficavam perdidos e soltos)
+- Seção "Pré-condições Globais" no topo (setup do contexto que aplica a todos os cenários)
+- Campo "Pré-condição" em cada CA (estado adicional específico daquele CA — não repete as globais)
+- Tabela de fluxos com colunas Ator/Ação/Resultado em vez de texto linear
+- UI/Componentes: orientação explícita para features backend-only ("N/A — backend-only")
+- Estratégia de testes: coluna "Responsável" (em vez de "Quem dispara"), sem redefinir frameworks (referencia docs/)
+- Bloco de terminologia explica diferença entre Pré-condições Globais vs Pré-condição do CA
+
+**`contracts.template.md`** — mudanças:
+- Separação explícita em **3 camadas**: Dados (schema do banco) → Validações de Entrada (formato/tipo do request) → Regras de Negócio (invariantes do domínio)
+- "Validações de Entrada" virou seção top-level (antes estava enfiada dentro de Dados)
+- Dados: subseção "Alterações em tabelas existentes" (ADD/ALTER/DROP COLUMN) — antes só tinha formato para tabela nova
+- API: erros têm coluna "Código de domínio" (linkado às RN)
+- Instrução explícita para não duplicar convenções globais de docs/apiContracts.md
+
+**`tasks.template.md`** — mudanças:
+- Padronização de áreas: `DB` (antes inconsistente com `BANCO`)
+- Coluna "Ref SDD" (obrigatória) adicionada — rastreabilidade ao documento fonte para tasks sem CA (INFRA/DOC)
+- Coluna "Ref CA" agora é opcional
+- Seção "Done When" com placeholder real (antes só tinha exemplo em comentário)
+- Removida seção "Regras por área" (era estática, contradiz áreas dinâmicas)
+- Removida seção "Convenções desta feature" (dumping ground — convenções pertencem ao SDD ou docs/)
+- Instrução explícita: bootstrap/first-run → toda task na Fase 1
+
+**`brief.template.md`** — mudanças:
+- Nova seção "Serviços tocados" (quais repos de projetos.yaml esta feature modifica + áreas)
+
+### Padronização de nome de área: `BANCO` → `DB`
+
+Inconsistência detectada entre commands/agents/templates: alguns usavam `BANCO` (português),
+outros usavam `DB`. Padronizado para **`DB`** (alinhado com nome do agente `db-coder.md` e
+com `commands/design.md`). 14 arquivos atualizados:
+
+- `.claude/agents/db-coder.md`
+- `.claude/commands/dev.md` (tabela de agents + seletor por prefixo)
+- `.claude/commands/plan.md` (mapeamento SDD → área + exemplo)
+- `.claude/rules.md` (exemplo de quality gate)
+- `.claude/templates/feature/projetos.template.yaml` (mapeamento de áreas)
+- `.claude/templates/feature/Progresso.template.md` (ordem de execução)
+- `.claude/templates/global/progresso_global.template.md` (exemplo)
+
+**Breaking**: IDs de task geradas anteriormente com prefixo `BANCO-*` continuam válidas (IDs
+estáveis, não renomear). Novas features geram `DB-*`.
+
+### `/discovery` declara modelo Opus
+
+Skill não tinha declaração explícita de modelo — rodava com o default da sessão. Descrição
+do skill ("arquiteto senior com mentalidade de consultor crítico... análises profundas e
+honestas") é trabalho Opus. Adicionado bloco **"Agente: Discovery Analyst (Opus)"** no topo.
+
+### Doc gap: como responder ambiguidades do PRD §14
+
+Skill `/extract` ganhou seção dedicada **"Como responder ambiguidades"** com fluxo
+passo a passo (caminho oficial: editar coluna `Resposta` direto no PRD §14 e re-rodar
+`/design`). Skill `/design` agora exibe instrução completa de retomada quando bloqueia
+por ambiguidades pendentes, em vez de só "pedir resposta".
+
+Caminho alternativo (adicionar `ajustes_v1.md` em Input + re-rodar `/extract`) está
+documentado como exceção para mudanças estruturais.
+
+---
+
+## 0.6.0-beta.4 (2026-04-13)
+
+### UX: `/mcp confluence` self-contained pra usuário leigo
+
+Perguntas do skill agora mostram EXATAMENTE onde achar cada informação inline,
+sem depender de consulta externa ao SETUP.md:
+
+- **URL do Confluence**: "abra no browser, copie URL base com /wiki"
+- **API Token**: 4 sub-passos numerados (URL Atlassian, Create button, nome, copiar antes que suma)
+- **Space Key**: mostra URL pattern `/wiki/spaces/XXX/` com seta + exemplos ("ST", "DEV", "PROJ")
+- **Root Page ID**: 2 opções (A: Page ID com URL pattern `/pages/NNNN/`, B: título exato com aviso de match)
+
+Qualquer modelo / usuário leigo consegue responder sem ficar travado.
+
+---
+
+## 0.6.0-beta.3 (2026-04-13)
+
+### Fix: `/mcp confluence` idempotente com `root_page_id` como âncora
+
+Antes o skill era linear e podia pular a coleta do Page ID raiz do projeto depois de
+um restart (caso user tivesse que reiniciar o Claude após criar `.mcp.json`), resultando
+em `sfw.config.yml` sem `project.root_page_id` — framework ficava sem âncora.
+
+Novo fluxo:
+1. Detecta estado de `sfw.config.yml` (tem root_page_id?) + `.mcp.json` (tem credenciais?)
+2. Se AMBOS existem → testa conexão e reconfirma Input/Output
+3. Se algo falta → pede só o que falta (idempotente)
+4. `root_page_id` validado contra `get_page(id)` antes de mapear árvore
+5. Handler explícito pra 401 (credencial expirou) e 404 (root inválido)
+
+### Fix: Auto-publish imperativo em `/extract`, `/design`, `/plan`
+
+Antes a instrução era "Se `sfw.config.yml` com output.targets[] ativo: Executar /publish" —
+ambígua, agent podia interpretar como opcional e pular.
+
+Agora:
+- Instrução imperativa: "Se `sfw.config.yml` existe → Chamar `/publish`. Execute."
+- Cada skill adiciona **seção "Saída obrigatória"** reportando status do publish
+  (CREATED/UPDATED/SKIPPED/CONFLICT/ERROR) ou "SKIPPED (no sfw.config.yml)"
+- User vê explicitamente o que aconteceu no Confluence
+
+### Fix: `publishes: [PRD, PRD, SDD, Progresso]` → `[PRD, SDD, Progresso]`
+
+Resquício do rename `TRD → PRD` na seção de template do `/mcp confluence`. Agora gera yaml correto.
+
+---
+
+## 0.6.0-beta.2 (2026-04-12)
+
+### Fix: CLI `init` output
+
+- Mensagem "Next steps" do `npx spec-first-claude init` apontava pro `/new-project` removido no v3
+- Agora aponta pro `/sfw-start <folder-name>` + nota que framework detecta first-run automaticamente
+- sfw.config.yml.example marcado como opcional (projeto funciona 100% local)
+
+---
+
 ## 0.6.0-beta.1 (2026-04-12) — Redesign v3 (BREAKING)
 
 Redesign estrutural eliminando o TRD e unificando o pipeline em um comando único.