spec-first-claude 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,147 @@
+# 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

package/bin/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 const path = require('path');
-const { init } = require('spec-first-core');
+const { init } = require('../lib/init');
 
 const args = process.argv.slice(2);
 const command = args[0];

package/lib/init.js

@@ -0,0 +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) {
+  // 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,12 +1,13 @@
 {
   "name": "spec-first-claude",
-  "version": "0.1.0",
+  "version": "0.3.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",
@@ -15,9 +16,6 @@
     "type": "git",
     "url": "https://github.com/gustavomaritan-labs/spec-first-workflow"
   },
-  "dependencies": {
-    "spec-first-core": "0.1.0"
-  },
   "scripts": {
     "test": "echo \"No tests yet\""
   },