spec-first-claude 0.5.0-beta.9 → 0.6.0-beta.10

package/README.md

@@ -6,7 +6,7 @@ Kit completo para desenvolvimento **spec-first** com [Claude Code](https://claud
 
 Em vez de pedir pra IA "cria um CRUD de usuarios", voce fornece insumos brutos (docs, SQLs, rascunhos) e a IA:
 
-1. **Extrai** requisitos estruturados (PRD/TRD)
+1. **Extrai** requisitos estruturados (PRD)
 2. **Espera sua aprovacao** (checkpoint humano)
 3. **Gera design tecnico** (SDD) — fonte unica de verdade
 4. **Planeja tasks** com dependencias e fases
@@ -48,19 +48,24 @@ MeuProjeto/
 ├── .ai/memory/napkin.md          <- Memoria persistente do projeto
 ├── .claude/                      <- AI OPERATIONAL CONFIG
 │   ├── rules.md                  <- Regras de desenvolvimento
-│   ├── templates/                <- 15 templates do workflow
-│   │   ├── feature/              <- PRD, TRD, SDD, tasks, etc.
-│   │   ├── estrutura/            <- 5 templates de estado do sistema
+│   ├── CHANGELOG.md              <- Historico do framework
+│   ├── templates/                <- Templates do workflow
+│   │   ├── feature/              <- PRD, SDD, context, extract-log, Progresso, backlog, projetos.yaml
+│   │   ├── specs/                <- brief, contracts, scenarios, tasks (projecoes pro agent)
+│   │   ├── estrutura/            <- 5 templates de sintese cross-feature
 │   │   └── global/               <- Progresso global
-│   ├── commands/                 <- 9 commands do workflow
-│   │   ├── setup-projeto.md
-│   │   ├── feature.md
+│   ├── adapters/                 <- SourceAdapter + ConfluenceAdapter + FilesystemAdapter
+│   ├── commands/                 <- 11 commands do workflow
+│   │   ├── mcp.md
+│   │   ├── load.md
+│   │   ├── publish.md
+│   │   ├── sfw-start.md          <- entrada unica (substitui setup-projeto + feature)
 │   │   ├── discovery.md
 │   │   ├── extract.md
 │   │   ├── design.md
 │   │   ├── plan.md
 │   │   ├── dev.md
-│   │   ├── merge-delta.md
+│   │   ├── merge-docs.md         <- renomeado de merge-delta
 │   │   └── session-finish.md
 │   └── agents/                   <- 7 agentes especializados
 │       ├── backend-coder.md      <- .NET 8 / C#
@@ -70,22 +75,23 @@ MeuProjeto/
 │       ├── doc-writer.md         <- Documentacao
 │       ├── reviewer.md           <- Code review
 │       └── security-reviewer.md  <- Auditoria de seguranca
-├── docs/                         <- SYSTEM KNOWLEDGE (gerado pelo /design)
+├── docs/                         <- SINTESE CROSS-FEATURE (atualizada pelo /merge-docs)
 │   ├── architecture.md           <- Containers, stack, ambientes, deploy
 │   ├── domain.md                 <- Visao de negocio + modelo de dados
 │   ├── conventions.md            <- Auth, authz, LGPD, env vars, monitoramento
 │   ├── apiContracts.md           <- Rotas, paginacao, erros, catalogo de endpoints
-│   ├── decisions.md              <- ADRs
-│   └── specs/                    <- Especs por feature (projecoes do SDD, pro agent)
-│       └── {nome}/
-│           ├── brief.md          <- Problema/Solucao
-│           ├── contracts.md      <- Dados/API/Integracoes
-│           ├── scenarios.md      <- Fluxos/UI/CAs
-│           └── tasks.md          <- Tabela unica com coluna Area
-├── workspace/                    <- TEAM CONTENT (futuro wiki)
-│   ├── Input/                    <- Jogue seus insumos aqui
-│   │   └── setup_projeto/        <- Insumos do bootstrap
-│   └── Output/                   <- Docs narrativos pro humano (PRD, TRD, SDD, Progresso)
+│   └── decisions.md              <- ADRs (append-only)
+├── specs/                        <- AGENT CONTRACTS (projecoes do SDD pro coder)
+│   └── {nome}/
+│       ├── brief.md              <- Problema/Solucao (SDD §1+§2+§10)
+│       ├── contracts.md          <- Sistema + Áreas tocadas (SDD §3-§7)
+│       ├── scenarios.md          <- Fluxos/UI/CAs (SDD §5.2+§8+§9)
+│       └── tasks.md              <- Tabela unica com coluna Area
+├── workspace/                    <- TEAM CONTENT
+│   ├── Input/                    <- Jogue seus insumos aqui (nome livre)
+│   │   └── {nome}/               <- ex: app_barbearia, feat_login
+│   └── Output/                   <- Docs narrativos pro humano (PRD, SDD, Progresso)
+├── sfw.config.yml.example        <- Manifesto de adapters (input/output)
 ├── CLAUDE.md                     <- Regras globais pro agente
 └── .gitignore
 ```
@@ -98,7 +104,8 @@ MeuProjeto/
    cd MeuProjeto
    ```
 
-2. Jogue seus insumos em `workspace/Input/setup_projeto/` — qualquer formato:
+2. Jogue seus insumos em `workspace/Input/<nome>/` — qualquer formato.
+   `<nome>` é livre: `app_barbearia`, `bootstrap`, `feat_login`, `bug_checkout`, etc.
    - `.md`, `.txt` (descricoes, requisitos, decisoes)
    - `.sql` (modelagem de banco)
    - `.csv`, `.xml`, `.html` (dados, configs)
@@ -106,37 +113,38 @@ MeuProjeto/
 
 3. Abra o Claude Code e rode:
    ```
-   /setup-projeto
+   /sfw-start <nome>
    ```
 
-4. O pipeline comeca. A IA vai:
-   - Extrair um TRD dos seus insumos
-   - Parar e pedir sua aprovacao
+4. O pipeline comeca. A IA detecta automaticamente se e first-run (docs/ ausente)
+   ou feature (docs/ ja existe). Nao ha comandos diferentes pra setup vs feature.
+
+   - Extrai PRD dos seus insumos (pode ser empty em scopes puro-tecnicos)
+   - Para e pede sua aprovacao
    - Depois voce roda `/design`, `/plan`, `/dev` na sequencia
 
 ## Pipeline completo
 
 ```
-workspace/Input/ (seus arquivos)
+workspace/Input/<nome>/ (seus arquivos)
     |
     v
-/setup-projeto  -->  /extract  -->  TRD (voce revisa e aprova)
-                                      |
-                                      v
-                                   /design  -->  SDD + docs/ (5 arquivos)
+/sfw-start <nome>  -->  /extract  -->  PRD (voce revisa e aprova)
+                                             |
+                                             v
+                                   /design  -->  SDD + docs/ (first-run: cria 5 arquivos)
+                                                              (feature: gera só §Área-X + §11 delta)
                                                    |
                                                    v
                                                 /plan  -->  tasks + Progresso.md
                                                               |
                                                               v
-                                                           /dev  -->  codigo nos repos + merge-delta automatico
+                                                           /dev  -->  codigo nos repos
+                                                                      + /merge-docs automatico
+                                                                        (aplica §11 em docs/)
 ```
 
-Para features (apos o setup):
-
-```
-/feature nome_da_feature  -->  /extract  -->  PRD  -->  /design  -->  /plan  -->  /dev (inclui merge-delta)
-```
+Mesmo comando pra bootstrap e feature — `first_run` e derivado da ausencia/presenca de `docs/`.
 
 ## Opcoes do CLI
 

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

@@ -1,6 +1,5 @@
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
 
 const PLACEHOLDER = '{{PROJECT_NAME}}';
 
@@ -8,7 +7,9 @@ function copyDir(src, dest, replacements) {
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
     const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
+    // Rename _gitignore → .gitignore (npm strips .gitignore from packages)
+    const destName = entry.name === '_gitignore' ? '.gitignore' : entry.name;
+    const destPath = path.join(dest, destName);
     if (entry.isDirectory()) {
       copyDir(srcPath, destPath, replacements);
     } else {
@@ -24,7 +25,7 @@ function copyFile(src, dest, replacements) {
   const textExtensions = ['.md', '.yaml', '.yml', '.json', '.js', '.ts', '.gitignore', '.gitkeep', ''];
   const ext = path.extname(src).toLowerCase();
   const basename = path.basename(src);
-  const isText = textExtensions.includes(ext) || basename.startsWith('.');
+  const isText = textExtensions.includes(ext) || basename.startsWith('.') || basename === '_gitignore';
 
   if (isText) {
     let content = fs.readFileSync(src, 'utf-8');
@@ -41,29 +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);
 
-  try {
-    execSync('git init', { cwd: dest, stdio: 'pipe' });
-    execSync('git add -A', { cwd: dest, stdio: 'pipe' });
-    execSync(`git commit -m "chore: init project ${name} via spec-first-workflow"`, {
-      cwd: dest,
-      stdio: 'pipe',
-    });
-    console.log('Git initialized with initial commit.');
-  } catch {
-    console.log('Git init skipped (git not available or error).');
-  }
-
-  console.log(`\nDone! 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. 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('');
 }
@@ -56,7 +56,8 @@ function syncDir(src, dest, force, stats, root) {
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
     const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
+    const destName = entry.name === '_gitignore' ? '.gitignore' : entry.name;
+    const destPath = path.join(dest, destName);
     if (entry.isDirectory()) {
       syncDir(srcPath, destPath, force, stats, root);
     } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-claude",
-  "version": "0.5.0-beta.9",
+  "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"