spec-first-claude 0.7.0-beta.1 → 0.8.0-beta.1

package/README.md

@@ -1,166 +1,296 @@
-# 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)
-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/                      <- AI OPERATIONAL CONFIG
-│   ├── rules.md                  <- Regras de desenvolvimento
-│   ├── 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
-│   ├── 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-docs.md         <- renomeado de merge-delta
-│   │   └── session-finish.md
-│   └── 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/                         <- 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 (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
-```
-
-## Como comecar
-
-1. Crie o projeto:
-   ```bash
-   spec-first-claude init --name=MeuProjeto
-   cd MeuProjeto
-   ```
-
-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)
-   - `.png`, `.jpg`, `.pdf` (telas, diagramas)
-
-3. Abra o Claude Code e rode:
-   ```
-   /sfw-start <nome>
-   ```
-
-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/<nome>/ (seus arquivos)
-    |
-    v
-/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-docs automatico
-                                                                        (aplica §11 em docs/)
-```
-
-Mesmo comando pra bootstrap e feature — `first_run` e derivado da ausencia/presenca de `docs/`.
-
-## 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
+
+[![npm version](https://img.shields.io/npm/v/spec-first-claude.svg)](https://www.npmjs.com/package/spec-first-claude)
+[![license](https://img.shields.io/npm/l/spec-first-claude.svg)](https://github.com/gustavomaritan-labs/spec-first-workflow/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/spec-first-claude.svg)](https://nodejs.org)
+
+Kit completo de desenvolvimento **spec-first** para [Claude Code](https://claude.ai/code).
+Pipeline disciplinado do insumo bruto ao código — com checkpoints humanos,
+agents especializados por área, security review e rastreabilidade ponta a ponta.
+
+> **v0.7.0 (estável)** — TRD ressuscitado como peer do PRD, aprovação por persona,
+> SDD eliminado. Ver [CHANGELOG](templates/.claude/CHANGELOG.md) para detalhes da migração v3→v4.
+
+---
+
+## Conteúdo
+
+- [Pra quem é isso](#pra-quem-é-isso)
+- [O que você ganha](#o-que-você-ganha)
+- [Instalação](#instalação)
+- [Estrutura gerada](#estrutura-gerada)
+- [Pipeline passo a passo](#pipeline-passo-a-passo)
+- [Brownfield: assumir aplicação existente](#brownfield-assumir-aplicação-existente)
+- [Commands disponíveis](#commands-disponíveis)
+- [Agents especializados](#agents-especializados)
+- [Backends plugáveis (adapters)](#backends-plugáveis-adapters)
+- [Troubleshooting](#troubleshooting)
+- [Links](#links)
+
+---
+
+## Pra quem é isso
+
+Você gerencia projetos onde PMs/POs entregam requisitos em formatos
+heterogêneos (docs no Confluence, SQLs de modelagem, wireframes, notas
+dispersas) e quer que o desenvolvimento assistido por IA siga um processo
+previsível. Sem "a IA adivinhou" — com specs aprovadas antes de uma linha
+de código.
+
+**Use-cases cobertos**:
+- Bootstrap de projeto novo (define stack + arquitetura + primeiras features)
+- Features novas em projeto existente (merge aditivo em docs cross-feature)
+- **Brownfield**: assumir aplicação existente — `/sfw-onboard` lê o código e gera a base documental (ver [seção dedicada](#brownfield-assumir-aplicação-existente))
+- Bugs e tasks técnicas (mesmo pipeline, escopo menor)
+- Times multi-dev (contratos firmes via `specs/` + `projetos.yaml`)
+
+## O que você ganha
+
+| Benefício | Como entrega |
+|-----------|--------------|
+| **Spec-first rígido** | Nenhum código sem PRD/TRD aprovados + `specs/` gerado |
+| **Dois revisores, dois docs** | PM aprova PRD (produto), dev aprova TRD (técnico) |
+| **Rastreabilidade total** | Cada RN, ADR, endpoint, task aponta pro insumo-fonte via hash SHA-256 |
+| **Security by default** | Security Reviewer audita 6 categorias pós-dev (Auth, AuthZ, Injeção, PII, Headers, Banco) |
+| **Backend-agnóstico** | Rode local (filesystem) ou sincronize com Confluence via MCP |
+| **Multi-repo nativo** | `projetos.yaml` mapeia serviços → repos; cada repo com branch/PR próprio |
+| **Entregáveis contínuos** | Features obrigatoriamente faseadas (P1/P2/P3) — nunca "tudo ou nada" |
+| **Re-executável** | Toda skill pode rodar de novo; hashes detectam incremental |
+
+## Instalação
+
+```bash
+npm i -g spec-first-claude
+```
+
+**Pré-requisitos**: Node.js 18+, Git, [Claude Code](https://claude.ai/code) instalado.
+
+**Windows (PowerShell)** — se o CLI não rodar por política de execução:
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+```
+
+## Primeiros passos
+
+```bash
+# 1. Criar o projeto
+spec-first-claude init --name=MeuProjeto
+cd MeuProjeto
+
+# 2. Jogar insumos brutos (qualquer formato)
+#    em workspace/Input/<nome>/
+#    Ex: workspace/Input/app_barbearia/visao.md + modelo.sql + decisoes.md
+
+# 3. Abrir com Claude Code e iniciar o pipeline
+#    /sfw-start app_barbearia
+```
+
+**Opções do CLI**:
+
+| Opção | Descrição |
+|-------|-----------|
+| `--name` | Nome do projeto (obrigatório) |
+| `--target` | Diretório destino (default: `./<name>`) |
+
+## Estrutura gerada
+
+```
+MeuProjeto/
+├── .ai/memory/napkin.md          <- Memória persistente (curada continuamente)
+├── .claude/                      <- AI OPERATIONAL CONFIG
+│   ├── rules.md                  <- Regras invioláveis + quality gate
+│   ├── CHANGELOG.md              <- Histórico do framework
+│   ├── templates/                <- 17 templates do workflow
+│   │   ├── feature/              <- PRD, TRD, context, extract-log, Progresso, projetos.yaml
+│   │   ├── specs/                <- brief, contracts, scenarios, tasks (projeções pro coder)
+│   │   ├── estrutura/            <- 5 docs cross-feature (architecture, domain, conventions, apiContracts, decisions)
+│   │   └── global/               <- progresso_global
+│   ├── adapters/                 <- SourceAdapter interface + 2 implementations built-in
+│   ├── commands/                 <- 11 slash commands (ver tabela abaixo)
+│   └── agents/                   <- 7 perfis especializados (ver tabela abaixo)
+├── docs/                         <- SÍNTESE CROSS-FEATURE (atualizada pelo /merge-docs)
+│   ├── architecture.md           <- Containers C4 + stack + ambientes + deploy
+│   ├── domain.md                 <- Visão de negócio + modelo de dados consolidado
+│   ├── conventions.md            <- Auth, authz, LGPD, env vars, códigos de erro, monitoramento
+│   ├── apiContracts.md           <- Convenções de API + catálogo de endpoints
+│   └── decisions.md              <- ADRs (append-only)
+├── specs/                        <- AGENT CONTRACTS (projeções de PRD+TRD pro coder)
+│   └── {scope}/
+│       ├── brief.md              <- Problema/Solução
+│       ├── contracts.md          <- Sistema + áreas tocadas (schema, endpoints, integrações, RNs)
+│       ├── scenarios.md          <- Jornadas + CAs + estratégia de testes
+│       └── tasks.md              <- Tabela única com coluna Área (gerado pelo /plan)
+├── workspace/                    <- TEAM CONTENT
+│   ├── Input/                    <- Insumos brutos (QUALQUER formato — nunca modificar)
+│   │   └── {scope}/              <- Nome livre (app_barbearia, feat_login, bug_checkout)
+│   └── Output/                   <- Docs narrativos pro humano
+│       └── {scope}/
+│           ├── PRD.md            <- Requirements de produto (se insumos têm produto)
+│           ├── TRD.md            <- Requirements técnicos (se insumos têm técnica)
+│           ├── Progresso.md      <- Tracking de execução
+│           └── .context.md       <- Estado da pipeline (YAML)
+├── projetos/                     <- Repos de código (gitignored, cada um com .git)
+├── projetos.yaml                 <- Manifesto de repos (gerado no first-run)
+├── sfw.config.yml.example        <- Manifesto de adapters (input/output)
+├── CLAUDE.md                     <- Meta-regras pro agente
+└── .gitignore
+```
+
+**Três zonas, zero ambiguidade**:
+- `.claude/` + `.ai/` → config operacional + memória (time edita raro)
+- `docs/` → síntese cross-feature (atualizada pelo `/merge-docs`)
+- `workspace/` → content compartilhável (Input = time, Output = workflow)
+
+## Pipeline passo a passo
+
+```
+workspace/Input/<scope>/ (seus arquivos)
+    │
+    ▼
+/sfw-start <scope>  ──▶  /load  ──▶  /discovery  ──▶  /extract
+                                                         │
+                                                         ▼
+                                                PRD + TRD gerados
+                                                         │
+                                    ┌──────── CHECKPOINT DUPLO ────────┐
+                                    │  PM aprova PRD | dev aprova TRD   │
+                                    └──────────────────────────────────┘
+                                                         │
+                                                         ▼
+                                                    /design  ──▶  specs/ (sempre)
+                                                                  docs/ + projetos.yaml (first-run)
+                                                         │
+                                                         ▼
+                                                    /plan   ──▶  tasks.md + Progresso.md
+                                                         │
+                                                         ▼
+                                                    /dev    ──▶  código nos repos
+                                                                 + Security Review
+                                                                 + /merge-docs automático
+                                                                   (diff PRD+TRD ↔ docs/)
+```
+
+Mesmo comando pra bootstrap e feature — `first_run` é derivado da
+ausência/presença de `docs/`.
+
+**Apresentação visual**: abra
+[`apresentacao.html`](https://github.com/gustavomaritan-labs/spec-first-workflow/blob/main/packages/apresentacao.html)
+pra ver o fluxo completo com personas, artefatos e adapters.
+
+## Brownfield: assumir aplicação existente
+
+Para projetos que **já existem** e não nasceram com SFW. O `/sfw-onboard` lê o
+código, identifica stack/padrões/decisões observadas, e popula a base documental
+(TRD + `docs/` + `projetos.yaml`) sem PRD.
+
+**Filosofia**: cartógrafo, não arquiteto. Descreve o que existe sem julgar.
+Coders de features futuras **seguem** os padrões observados — mudanças entram
+como features propostas pelo dev.
+
+```bash
+# 1. Criar shell SFW vazio (mesma instalação)
+spec-first-claude init --name=MeuProjeto
+cd MeuProjeto
+
+# 2. Onboardar repo existente (pré-req: SSH/PAT já configurado)
+/sfw-onboard https://github.com/empresa/app-legado.git
+
+# 3. (Multi-repo) Re-rodar pra cada repo do mesmo projeto
+/sfw-onboard https://github.com/empresa/app-legado-web.git
+/sfw-onboard https://github.com/empresa/app-legado-worker.git
+
+# 4. Começar features novas com o pipeline normal
+/sfw-start feat_nova_funcionalidade
+```
+
+**O que é gerado**:
+- `projetos/<repo>/` — clone(s) com `.git` próprio
+- `workspace/Output/onboard_<repo>/TRD.md` — completo, com §1.6 Padrões Observados (snippets reais)
+- `workspace/Input/onboard_<repo>/code-snapshot.md` — índice + hashes (re-onboard incremental)
+- `docs/` — 5 arquivos cross-feature populados
+- `projetos.yaml` — entries dos repos clonados
+- `docs/decisions.md` — ADRs **inferidas** com flag `Inferido: true` (dev revisa e remove flag ao confirmar)
+
+**Re-onboard** quando o código legado evolui: rodar de novo, hash detecta arquivos
+modificados, merge aditivo no TRD.
+
+**Diferença vs `/sfw-start`**: brownfield NÃO gera PRD nem ambiguidades (código é
+a verdade), não tem checkpoint humano, e auto-aprova TRD. Após onboard, features
+novas entram pelo `/sfw-start` normal — `first_run` da feature já será `false`
+porque `docs/` existe.
+
+## Commands disponíveis
+
+| Command | Tipo | Função |
+|---------|------|--------|
+| `/mcp <provider>` | Setup | Configura backend externo (Confluence). Cria `.mcp.json` + `sfw.config.yml` |
+| `/load <scope>` | Utilitária | Puxa Input do backend (incremental via hash) |
+| `/publish <scope> <tipo>` | Utilitária | Publica PRD/TRD/Progresso nos targets. Auto-chamada por extract/plan |
+| `/sfw-start <scope>` | Orquestrador | Entrada única. Cria `.context.md`, chama `/load` + `/discovery` + `/extract` |
+| `/sfw-onboard <git-url>` | Atômica | **Brownfield**. Clona repo existente, gera TRD + docs/ + projetos.yaml (sem PRD) |
+| `/discovery <path>` | Atômica | Análise profunda prévia dos insumos (obrigatório em v4) |
+| `/extract <scope>` | Atômica | Gera PRD e/ou TRD conforme conteúdo dos insumos |
+| `/design <scope>` | Atômica | PRD+TRD aprovados → `specs/`. First-run também cria `docs/` + `projetos.yaml` |
+| `/plan <scope>` | Atômica | Lê PRD + TRD + specs/ → tasks por área + Progresso.md |
+| `/dev <scope>` | Atômica | Implementa tasks com loop (implement → test → review). Merge-docs automático no fim |
+| `/merge-docs <scope>` | Atômica | Diff semântico PRD+TRD ↔ docs/ → atualiza síntese cross-feature |
+| `/session-finish` | Utilitária | Encerra sessão: salva estado, atualiza napkin, gera retomada.md |
+
+## Agents especializados
+
+| Agent | Área | Stack padrão | Modelo |
+|-------|------|--------------|--------|
+| Backend Coder | BACK | .NET 8 / C# (editável) | Sonnet (S/M) · Opus (L) |
+| Frontend Coder | FRONT | React + Fusion (editável) | Sonnet (S/M) · Opus (L) |
+| DB Coder | DB | PostgreSQL 16 (editável) | Sonnet (S/M) · Opus (L) |
+| Infra Coder | INFRA | Docker | Sonnet (S/M) · Opus (L) |
+| Doc Writer | DOC | — | Sonnet |
+| Reviewer | Todas | — (quality gate) | Sonnet |
+| Security Reviewer | Todas | — (gate pós-dev) | Opus |
+
+Perfis em `.claude/agents/` — editáveis pelo time pra ajustar stack
+específica do projeto (ex: Node.js em vez de .NET, Angular em vez de React).
+
+## Backends plugáveis (adapters)
+
+Arquitetura de **adapter layer** via `sfw.config.yml`. Skills não conhecem
+Confluence ou filesystem — chamam uma interface padrão. Novos backends
+entram como plugins sem tocar o pipeline.
+
+**Built-in**:
+- **`FilesystemAdapter`** — zero dependência externa. Ideal pra times
+  offline, testes automatizados (mock natural), ou diretório compartilhado.
+- **`ConfluenceAdapter`** — via MCP Atlassian. Conflict detection client-side.
+  PM edita Input no Confluence, agent auto-publica Output (PRD/TRD/Progresso)
+  após cada skill.
+
+**Roadmap**: `NotionAdapter`, `JIRAAdapter`, `SharePointAdapter`,
+`GitHubIssuesAdapter` (formalizados quando surgir 3º caso real).
+
+Setup do Confluence:
+```
+/mcp confluence
+```
+Guia o setup interativo (space key, parent IDs, credenciais gitignored).
+
+## Troubleshooting
+
+| Problema | Solução |
+|----------|---------|
+| `/sfw-start` reclama que pasta Input está vazia | Verifique que há pelo menos 1 arquivo em `workspace/Input/<scope>/` |
+| Pipeline trava em ambiguidade | PRD §12 ou TRD §10 têm linhas sem resposta. Preencher coluna "Resposta" e rodar `/design` de novo |
+| PM quer mudar algo depois do PRD aprovado | Criar `workspace/Input/<scope>/ajustes_v1.md` e rodar `/extract` → merge aditivo preserva IDs |
+| `/publish` não envia TRD pro Confluence | Verificar `publishes: [PRD, TRD, Progresso]` no `sfw.config.yml` |
+| Coder pede algo que não está nas specs/ | Não é bug — é feature. Significa que spec ficou incompleto. Completar via `/extract` e re-rodar `/design` |
+| Security Review bloqueia merge | CRÍTICO/ALTO são bloqueantes. MÉDIO/BAIXO são recomendações. Ver `agents/security-reviewer.md` |
+
+## Links
+
+- **Repositório**: [gustavomaritan-labs/spec-first-workflow](https://github.com/gustavomaritan-labs/spec-first-workflow)
+- **Kit Copilot** (equivalente pra GitHub Copilot): [spec-first-copilot](https://www.npmjs.com/package/spec-first-copilot)
+- **Apresentação do pipeline**: [apresentacao.html](https://github.com/gustavomaritan-labs/spec-first-workflow/blob/main/packages/apresentacao.html)
+- **Issues**: [github.com/.../issues](https://github.com/gustavomaritan-labs/spec-first-workflow/issues)
+
+## Licença
+
+MIT © [Gustavo Maritan](https://github.com/GustavoMaritan)

package/bin/cli.js

@@ -1,70 +1,70 @@
 #!/usr/bin/env node
-
-const path = require('path');
-const { init } = require('../lib/init');
-const { update } = require('../lib/update');
-
-const args = process.argv.slice(2);
-const command = args[0];
-
-function printUsage() {
-  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('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('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) {
-  const parsed = { flags: [] };
-  for (const arg of args) {
-    const match = arg.match(/^--(\w+)=(.+)$/);
-    if (match) {
-      parsed[match[1]] = match[2];
-    } else if (arg.startsWith('--')) {
-      parsed.flags.push(arg.slice(2));
-    }
-  }
-  return parsed;
-}
-
-if (command === 'init') {
-  const opts = parseArgs(args.slice(1));
-
-  if (!opts.name) {
-    console.error('Erro: --name é obrigatório.\n');
-    printUsage();
-    process.exit(1);
-  }
-
-  const templatesDir = path.join(__dirname, '..', 'templates');
-
-  init({
-    name: opts.name,
-    templatesDir,
-    targetDir: opts.target || undefined,
-  });
-} else if (command === 'update') {
-  const opts = parseArgs(args.slice(1));
-  const templatesDir = path.join(__dirname, '..', 'templates');
-
-  update({
-    templatesDir,
-    targetDir: opts.target || undefined,
-    force: opts.flags.includes('force'),
-  });
-} else {
-  printUsage();
-  if (command) {
-    console.error(`\nComando desconhecido: "${command}"`);
-  }
-  process.exit(command ? 1 : 0);
-}
+
+const path = require('path');
+const { init } = require('../lib/init');
+const { update } = require('../lib/update');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function printUsage() {
+  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('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('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) {
+  const parsed = { flags: [] };
+  for (const arg of args) {
+    const match = arg.match(/^--(\w+)=(.+)$/);
+    if (match) {
+      parsed[match[1]] = match[2];
+    } else if (arg.startsWith('--')) {
+      parsed.flags.push(arg.slice(2));
+    }
+  }
+  return parsed;
+}
+
+if (command === 'init') {
+  const opts = parseArgs(args.slice(1));
+
+  if (!opts.name) {
+    console.error('Erro: --name é obrigatório.\n');
+    printUsage();
+    process.exit(1);
+  }
+
+  const templatesDir = path.join(__dirname, '..', 'templates');
+
+  init({
+    name: opts.name,
+    templatesDir,
+    targetDir: opts.target || undefined,
+  });
+} else if (command === 'update') {
+  const opts = parseArgs(args.slice(1));
+  const templatesDir = path.join(__dirname, '..', 'templates');
+
+  update({
+    templatesDir,
+    targetDir: opts.target || undefined,
+    force: opts.flags.includes('force'),
+  });
+} else {
+  printUsage();
+  if (command) {
+    console.error(`\nComando desconhecido: "${command}"`);
+  }
+  process.exit(command ? 1 : 0);
+}