spec-first-claude 0.2.0 → 0.4.0

package/README.md

@@ -1,147 +1,144 @@
-# spec-first-claude
-
-Kit completo para desenvolvimento **spec-first** com [Claude Code](https://claude.ai/code). A IA segue um pipeline disciplinado — da especificacao ao codigo — com checkpoints humanos e rastreabilidade ponta a ponta.
-
-## O que e spec-first?
-
-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)
-2. **Espera sua aprovacao** (checkpoint humano)
-3. **Gera design tecnico** (SDD) — fonte unica de verdade
-4. **Planeja tasks** com dependencias e fases
-5. **Implementa** com agentes especializados por area + security review
-6. **Atualiza docs** automaticamente (delta specs)
-
-Resultado: codigo previsivel, seguro e rastreavel.
-
-## Pre-requisitos
-
-- **Node.js** 18+
-- **Git** instalado
-- **Claude Code** instalado e configurado
-
-### Windows (PowerShell)
-
-Se encontrar erro de script nao assinado ao rodar o CLI, execute:
-
-```powershell
-Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
-```
-
-## Instalacao
-
-```bash
-npm i -g spec-first-claude
-```
-
-## Uso
-
-```bash
-spec-first-claude init --name=MeuProjeto
-```
-
-Isso cria a pasta `MeuProjeto/` com toda a estrutura pronta:
-
-```
-MeuProjeto/
-├── .ai/memory/napkin.md          <- Memoria persistente do projeto
-├── .claude/
-│   ├── commands/                 <- 9 commands do workflow
-│   │   ├── setup-projeto.md     <- Bootstrap do projeto
-│   │   ├── feature.md           <- Pipeline de feature
-│   │   ├── discovery.md         <- Analise profunda de insumos
-│   │   ├── extract.md           <- PM -> PRD/TRD
-│   │   ├── design.md            <- PRD/TRD -> SDD
-│   │   ├── plan.md              <- SDD -> tasks
-│   │   ├── dev.md               <- Executa tasks
-│   │   ├── merge-delta.md       <- Atualiza docs globais
-│   │   └── pausar.md            <- Encerra sessao
-│   └── agents/                  <- 7 agentes especializados
-│       ├── backend-coder.md     <- .NET 8 / C#
-│       ├── frontend-coder.md    <- React
-│       ├── db-coder.md          <- PostgreSQL
-│       ├── infra-coder.md       <- Docker
-│       ├── doc-writer.md        <- Documentacao
-│       ├── reviewer.md          <- Code review
-│       └── security-reviewer.md <- Auditoria de seguranca
-├── docs/
-│   ├── PM/                      <- Jogue seus insumos aqui
-│   │   └── setup_projeto/       <- Insumos do bootstrap
-│   ├── _templates/              <- 18 templates do workflow
-│   ├── Estrutura/               <- Docs globais (gerados)
-│   └── Desenvolvimento/         <- Docs por feature (gerados)
-│       └── rules.md             <- Regras de desenvolvimento
-├── CLAUDE.md                    <- Regras globais pro agente
-└── .gitignore
-```
-
-## Como comecar
-
-1. Crie o projeto:
-   ```bash
-   spec-first-claude init --name=MeuProjeto
-   cd MeuProjeto
-   ```
-
-2. Jogue seus insumos em `docs/PM/setup_projeto/` — qualquer formato:
-   - `.md`, `.txt` (descricoes, requisitos, decisoes)
-   - `.sql` (modelagem de banco)
-   - `.csv`, `.xml`, `.html` (dados, configs)
-   - `.png`, `.jpg`, `.pdf` (telas, diagramas)
-
-3. Abra o Claude Code e rode:
-   ```
-   /setup-projeto
-   ```
-
-4. O pipeline comeca. A IA vai:
-   - Extrair um TRD dos seus insumos
-   - Parar e pedir sua aprovacao
-   - Depois voce roda `/design`, `/plan`, `/dev` na sequencia
-
-## Pipeline completo
-
-```
-docs/PM/ (seus arquivos)
-    |
-    v
-/setup-projeto  -->  /extract  -->  TRD (voce revisa e aprova)
-                                      |
-                                      v
-                                   /design  -->  SDD + docs/Estrutura/
-                                                   |
-                                                   v
-                                                /plan  -->  tasks + Progresso.md
-                                                              |
-                                                              v
-                                                           /dev  -->  codigo nos repos
-                                                                        |
-                                                                        v
-                                                                     /merge-delta  -->  docs atualizados
-```
-
-Para features (apos o setup):
-
-```
-/feature nome_da_feature  -->  /extract  -->  PRD  -->  /design  -->  /plan  -->  /dev  -->  /merge-delta
-```
-
-## Opcoes do CLI
-
-```
-spec-first-claude init --name=<nome> [--target=<caminho>]
-```
-
-| Opcao | Descricao |
-|-------|-----------|
-| `--name` | Nome do projeto (obrigatorio) |
-| `--target` | Diretorio destino (default: `./<nome>`) |
-
-## Links
-
-- [Repositorio](https://github.com/gustavomaritan-labs/spec-first-workflow)
-
-## Licenca
-
-MIT
+# spec-first-claude
+
+Kit completo para desenvolvimento **spec-first** com [Claude Code](https://claude.ai/code). A IA segue um pipeline disciplinado — da especificacao ao codigo — com checkpoints humanos e rastreabilidade ponta a ponta.
+
+## O que e spec-first?
+
+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)
+2. **Espera sua aprovacao** (checkpoint humano)
+3. **Gera design tecnico** (SDD) — fonte unica de verdade
+4. **Planeja tasks** com dependencias e fases
+5. **Implementa** com agentes especializados por area + security review
+6. **Atualiza docs** automaticamente (delta specs)
+
+Resultado: codigo previsivel, seguro e rastreavel.
+
+## Pre-requisitos
+
+- **Node.js** 18+
+- **Git** instalado
+- **Claude Code** instalado e configurado
+
+### Windows (PowerShell)
+
+Se encontrar erro de script nao assinado ao rodar o CLI, execute:
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+```
+
+## Instalacao
+
+```bash
+npm i -g spec-first-claude
+```
+
+## Uso
+
+```bash
+spec-first-claude init --name=MeuProjeto
+```
+
+Isso cria a pasta `MeuProjeto/` com toda a estrutura pronta:
+
+```
+MeuProjeto/
+├── .ai/memory/napkin.md          <- Memoria persistente do projeto
+├── .claude/
+│   ├── commands/                 <- 9 commands do workflow
+│   │   ├── setup-projeto.md     <- Bootstrap do projeto
+│   │   ├── feature.md           <- Pipeline de feature
+│   │   ├── discovery.md         <- Analise profunda de insumos
+│   │   ├── extract.md           <- PM -> PRD/TRD
+│   │   ├── design.md            <- PRD/TRD -> SDD
+│   │   ├── plan.md              <- SDD -> tasks
+│   │   ├── dev.md               <- Executa tasks
+│   │   ├── merge-delta.md       <- Atualiza docs globais
+│   │   └── session-finish.md    <- Encerra sessao
+│   └── agents/                  <- 7 agentes especializados
+│       ├── backend-coder.md     <- .NET 8 / C#
+│       ├── frontend-coder.md    <- React
+│       ├── db-coder.md          <- PostgreSQL
+│       ├── infra-coder.md       <- Docker
+│       ├── doc-writer.md        <- Documentacao
+│       ├── reviewer.md          <- Code review
+│       └── security-reviewer.md <- Auditoria de seguranca
+├── docs/
+│   ├── PM/                      <- Jogue seus insumos aqui
+│   │   └── setup_projeto/       <- Insumos do bootstrap
+│   ├── _templates/              <- 18 templates do workflow
+│   ├── Estrutura/               <- Docs globais (gerados)
+│   └── Desenvolvimento/         <- Docs por feature (gerados)
+│       └── rules.md             <- Regras de desenvolvimento
+├── CLAUDE.md                    <- Regras globais pro agente
+└── .gitignore
+```
+
+## Como comecar
+
+1. Crie o projeto:
+   ```bash
+   spec-first-claude init --name=MeuProjeto
+   cd MeuProjeto
+   ```
+
+2. Jogue seus insumos em `docs/PM/setup_projeto/` — qualquer formato:
+   - `.md`, `.txt` (descricoes, requisitos, decisoes)
+   - `.sql` (modelagem de banco)
+   - `.csv`, `.xml`, `.html` (dados, configs)
+   - `.png`, `.jpg`, `.pdf` (telas, diagramas)
+
+3. Abra o Claude Code e rode:
+   ```
+   /setup-projeto
+   ```
+
+4. O pipeline comeca. A IA vai:
+   - Extrair um TRD dos seus insumos
+   - Parar e pedir sua aprovacao
+   - Depois voce roda `/design`, `/plan`, `/dev` na sequencia
+
+## Pipeline completo
+
+```
+docs/PM/ (seus arquivos)
+    |
+    v
+/setup-projeto  -->  /extract  -->  TRD (voce revisa e aprova)
+                                      |
+                                      v
+                                   /design  -->  SDD + docs/Estrutura/
+                                                   |
+                                                   v
+                                                /plan  -->  tasks + Progresso.md
+                                                              |
+                                                              v
+                                                           /dev  -->  codigo nos repos + merge-delta automatico
+```
+
+Para features (apos o setup):
+
+```
+/feature nome_da_feature  -->  /extract  -->  PRD  -->  /design  -->  /plan  -->  /dev (inclui merge-delta)
+```
+
+## Opcoes do CLI
+
+```
+spec-first-claude init --name=<nome> [--target=<caminho>]
+```
+
+| Opcao | Descricao |
+|-------|-----------|
+| `--name` | Nome do projeto (obrigatorio) |
+| `--target` | Diretorio destino (default: `./<nome>`) |
+
+## Links
+
+- [Repositorio](https://github.com/gustavomaritan-labs/spec-first-workflow)
+
+## Licenca
+
+MIT

package/bin/cli.js

@@ -1,52 +1,52 @@
-#!/usr/bin/env node
-
-const path = require('path');
-const { init } = require('../lib/init');
-
-const args = process.argv.slice(2);
-const command = args[0];
-
-function printUsage() {
-  console.log('Usage: spec-first-claude init --name=<project-name> [--target=<path>]');
-  console.log('');
-  console.log('Creates a new spec-first project configured for Claude Code.');
-  console.log('');
-  console.log('Options:');
-  console.log('  --name=<name>    Project name (required)');
-  console.log('  --target=<path>  Target directory (defaults to ./<name>)');
-}
-
-function parseArgs(args) {
-  const parsed = {};
-  for (const arg of args) {
-    const match = arg.match(/^--(\w+)=(.+)$/);
-    if (match) {
-      parsed[match[1]] = match[2];
-    }
-  }
-  return parsed;
-}
-
-if (command === 'init') {
-  const opts = parseArgs(args.slice(1));
-
-  if (!opts.name) {
-    console.error('Error: --name is required.\n');
-    printUsage();
-    process.exit(1);
-  }
-
-  const templatesDir = path.join(__dirname, '..', 'templates');
-
-  init({
-    name: opts.name,
-    templatesDir,
-    targetDir: opts.target || undefined,
-  });
-} else {
-  printUsage();
-  if (command) {
-    console.error(`\nUnknown command: "${command}"`);
-  }
-  process.exit(command ? 1 : 0);
-}
+#!/usr/bin/env node
+
+const path = require('path');
+const { init } = require('../lib/init');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function printUsage() {
+  console.log('Usage: spec-first-claude init --name=<project-name> [--target=<path>]');
+  console.log('');
+  console.log('Creates a new spec-first project configured for Claude Code.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --name=<name>    Project name (required)');
+  console.log('  --target=<path>  Target directory (defaults to ./<name>)');
+}
+
+function parseArgs(args) {
+  const parsed = {};
+  for (const arg of args) {
+    const match = arg.match(/^--(\w+)=(.+)$/);
+    if (match) {
+      parsed[match[1]] = match[2];
+    }
+  }
+  return parsed;
+}
+
+if (command === 'init') {
+  const opts = parseArgs(args.slice(1));
+
+  if (!opts.name) {
+    console.error('Error: --name is required.\n');
+    printUsage();
+    process.exit(1);
+  }
+
+  const templatesDir = path.join(__dirname, '..', 'templates');
+
+  init({
+    name: opts.name,
+    templatesDir,
+    targetDir: opts.target || undefined,
+  });
+} else {
+  printUsage();
+  if (command) {
+    console.error(`\nUnknown command: "${command}"`);
+  }
+  process.exit(command ? 1 : 0);
+}

package/lib/init.js

@@ -1,93 +1,89 @@
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-
-const PLACEHOLDER = '{{PROJECT_NAME}}';
-
-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);
-    if (entry.isDirectory()) {
-      copyDir(srcPath, destPath, replacements);
-    } else {
-      copyFile(srcPath, destPath, replacements);
-    }
-  }
-}
-
-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('.');
-
-  if (isText) {
-    let content = fs.readFileSync(src, 'utf-8');
-    for (const [placeholder, value] of Object.entries(replacements)) {
-      content = content.split(placeholder).join(value);
-    }
-    fs.writeFileSync(dest, content, 'utf-8');
-  } else {
-    fs.copyFileSync(src, dest);
-  }
-}
-
-function init({ name, templatesDir, targetDir }) {
-  const dest = targetDir || path.resolve(process.cwd(), name);
-
-  if (fs.existsSync(dest)) {
-    const files = fs.readdirSync(dest);
-    if (files.length > 0) {
-      console.error(`Error: directory "${dest}" already exists and is not empty.`);
-      process.exit(1);
-    }
-  }
-
-  console.log(`\nCreating project "${name}" in ${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(`  1. cd ${name}`);
-  console.log('  2. Add your input files to docs/PM/setup_projeto/');
-  console.log('  3. Run /setup-projeto to start the pipeline');
-  console.log('');
-}
-
-function patchProjectName(dest, name) {
-  const filesToPatch = [
-    path.join('.ai', 'memory', 'napkin.md'),
-    path.join('.github', 'copilot-instructions.md'),
-    'CLAUDE.md',
-  ];
-
-  for (const relPath of filesToPatch) {
-    const filePath = path.join(dest, relPath);
-    if (!fs.existsSync(filePath)) continue;
-
-    let content = fs.readFileSync(filePath, 'utf-8');
-    content = content.replace(/# Napkin Runbook\b/, `# Napkin Runbook — ${name}`);
-    content = content.replace(/# Copilot Instructions — Projeto\b/, `# Copilot Instructions — ${name}`);
-    content = content.replace(/# CLAUDE\.md — Projeto\b/, `# CLAUDE.md — ${name}`);
-    fs.writeFileSync(filePath, content, 'utf-8');
-  }
-}
-
-module.exports = { init };
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const PLACEHOLDER = '{{PROJECT_NAME}}';
+
+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);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, replacements);
+    } else {
+      copyFile(srcPath, destPath, replacements);
+    }
+  }
+}
+
+function copyFile(src, dest, replacements) {
+  // Skip if file already exists (preserve user's files)
+  if (fs.existsSync(dest)) return;
+
+  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('.');
+
+  if (isText) {
+    let content = fs.readFileSync(src, 'utf-8');
+    for (const [placeholder, value] of Object.entries(replacements)) {
+      content = content.split(placeholder).join(value);
+    }
+    fs.writeFileSync(dest, content, 'utf-8');
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+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`);
+
+  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(`  1. cd ${name}`);
+  console.log('  2. Add your input files to docs/PM/setup_projeto/');
+  console.log('  3. Run /setup-projeto to start the pipeline');
+  console.log('');
+}
+
+function patchProjectName(dest, name) {
+  const filesToPatch = [
+    path.join('.ai', 'memory', 'napkin.md'),
+    path.join('.github', 'copilot-instructions.md'),
+    'CLAUDE.md',
+  ];
+
+  for (const relPath of filesToPatch) {
+    const filePath = path.join(dest, relPath);
+    if (!fs.existsSync(filePath)) continue;
+
+    let content = fs.readFileSync(filePath, 'utf-8');
+    content = content.replace(/# Napkin Runbook\b/, `# Napkin Runbook — ${name}`);
+    content = content.replace(/# Copilot Instructions — Projeto\b/, `# Copilot Instructions — ${name}`);
+    content = content.replace(/# CLAUDE\.md — Projeto\b/, `# CLAUDE.md — ${name}`);
+    fs.writeFileSync(filePath, content, 'utf-8');
+  }
+}
+
+module.exports = { init };

package/package.json

@@ -1,23 +1,24 @@
-{
-  "name": "spec-first-claude",
-  "version": "0.2.0",
-  "description": "Spec-first workflow kit for Claude Code — AI-driven development with specs, not guesswork",
-  "bin": {
-    "spec-first-claude": "./bin/cli.js"
-  },
-  "files": [
-    "bin/",
-    "lib/",
-    "templates/"
-  ],
-  "author": "gustavomaritan",
-  "keywords": ["spec-first", "workflow", "ai", "claude", "anthropic", "scaffolding"],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/gustavomaritan-labs/spec-first-workflow"
-  },
-  "scripts": {
-    "test": "echo \"No tests yet\""
-  },
-  "license": "MIT"
-}
+{
+  "name": "spec-first-claude",
+  "version": "0.4.0",
+  "description": "Spec-first workflow kit for Claude Code — AI-driven development with specs, not guesswork",
+  "bin": {
+    "spec-first-claude": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/"
+  ],
+  "author": "gustavomaritan",
+  "keywords": ["spec-first", "workflow", "ai", "claude", "anthropic", "scaffolding"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gustavomaritan-labs/spec-first-workflow",
+    "directory": "packages/spec-first-claude"
+  },
+  "scripts": {
+    "test": "echo \"No tests yet\""
+  },
+  "license": "MIT"
+}