spec-first-claude 0.3.0 → 0.5.0-beta.0

package/README.md

@@ -46,33 +46,41 @@ Isso cria a pasta `MeuProjeto/` com toda a estrutura pronta:
 ```
 MeuProjeto/
 ├── .ai/memory/napkin.md          <- Memoria persistente do projeto
-├── .claude/
+├── .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
+│   │   └── global/               <- Progresso global
 │   ├── 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
+│   │   ├── setup-projeto.md
+│   │   ├── feature.md
+│   │   ├── discovery.md
+│   │   ├── extract.md
+│   │   ├── design.md
+│   │   ├── plan.md
+│   │   ├── dev.md
+│   │   ├── merge-delta.md
+│   │   └── 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/                         <- SYSTEM KNOWLEDGE (gerado pelo /design)
+│   ├── 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
+├── workspace/                   <- TEAM CONTENT (futuro wiki)
+│   ├── Input/                    <- Jogue seus insumos aqui
+│   │   └── setup_projeto/        <- Insumos do bootstrap
+│   └── Output/                   <- Docs por feature (gerados)
+├── CLAUDE.md                     <- Regras globais pro agente
 └── .gitignore
 ```
 
@@ -84,7 +92,7 @@ MeuProjeto/
    cd MeuProjeto
    ```
 
-2. Jogue seus insumos em `docs/PM/setup_projeto/` — qualquer formato:
+2. Jogue seus insumos em `workspace/Input/setup_projeto/` — qualquer formato:
    - `.md`, `.txt` (descricoes, requisitos, decisoes)
    - `.sql` (modelagem de banco)
    - `.csv`, `.xml`, `.html` (dados, configs)
@@ -103,28 +111,25 @@ MeuProjeto/
 ## Pipeline completo
 
 ```
-docs/PM/ (seus arquivos)
+workspace/Input/ (seus arquivos)
     |
     v
 /setup-projeto  -->  /extract  -->  TRD (voce revisa e aprova)
                                       |
                                       v
-                                   /design  -->  SDD + docs/Estrutura/
+                                   /design  -->  SDD + docs/ (5 arquivos)
                                                    |
                                                    v
                                                 /plan  -->  tasks + Progresso.md
                                                               |
                                                               v
-                                                           /dev  -->  codigo nos repos
-                                                                        |
-                                                                        v
-                                                                     /merge-delta  -->  docs atualizados
+                                                           /dev  -->  codigo nos repos + merge-delta automatico
 ```
 
 Para features (apos o setup):
 
 ```
-/feature nome_da_feature  -->  /extract  -->  PRD  -->  /design  -->  /plan  -->  /dev  -->  /merge-delta
+/feature nome_da_feature  -->  /extract  -->  PRD  -->  /design  -->  /plan  -->  /dev (inclui merge-delta)
 ```
 
 ## Opcoes do CLI

package/lib/init.js

@@ -62,7 +62,7 @@ function init({ name, templatesDir, targetDir }) {
   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('  2. Add your input files to workspace/Input/setup_projeto/');
   console.log('  3. Run /setup-projeto to start the pipeline');
   console.log('');
 }

package/package.json

@@ -1,23 +1,31 @@
-{
-  "name": "spec-first-claude",
-  "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",
-  "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.5.0-beta.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": "git+https://github.com/gustavomaritan-labs/spec-first-workflow.git",
+    "directory": "packages/spec-first-claude"
+  },
+  "scripts": {
+    "test": "echo \"No tests yet\""
+  },
+  "license": "MIT"
+}

package/templates/.ai/memory/napkin.md

@@ -65,4 +65,4 @@
 
 ## Sessão Atual
 
-<!-- Atualizado pelo /pausar ao encerrar cada sessão -->
+<!-- Atualizado pelo /session-finish ao encerrar cada sessão -->

package/templates/.claude/agents/db-coder.md

@@ -39,7 +39,7 @@ src/Infrastructure/Data/
     └── DevSeedData.cs        ← Seed para desenvolvimento
 ```
 
-### Convenções SQL (alinhado com Modelo_Dados.md)
+### Convenções SQL (alinhado com domain.md)
 
 | Elemento | Convenção | Exemplo |
 |----------|-----------|---------|

package/templates/.claude/agents/doc-writer.md

@@ -1,7 +1,7 @@
 # Agent: Doc Writer
 
 > Especialista em geração de documentação técnica.
-> Usado pelo /design (setup) para gerar docs/Estrutura/ e pelo /merge-delta para atualizá-los.
+> Usado pelo /design (setup) para gerar docs/ e pelo /merge-delta para atualizá-los.
 
 ---
 
@@ -16,21 +16,18 @@
 
 ## Responsabilidades
 
-1. **No setup (via /design passo 3)**: gerar os 8 docs de `docs/Estrutura/` a partir do TRD aprovado
-2. **Em features (via /merge-delta)**: atualizar docs de Estrutura com Delta Specs do SDD §11
+1. **No setup (via /design passo 3)**: gerar os 5 docs de `docs/` a partir do TRD aprovado (architecture, domain, conventions, apiContracts, decisions)
+2. **Em features (via /merge-delta)**: atualizar os docs de `docs/` com Delta Specs do SDD §11
 
-## Mapeamento TRD → docs/Estrutura/
+## Mapeamento TRD/SDD → docs/
 
-| TRD Seção | Doc gerado | Template |
-|-----------|-----------|---------|
-| §1 Visão + §8 Módulos | Visao.md | `_templates/estrutura/Visao.template.md` |
-| §2 Stack | Stack.md | `_templates/estrutura/Stack.template.md` |
-| §3 Arquitetura | Arquitetura.md | `_templates/estrutura/Arquitetura.template.md` |
-| §4 Modelo + SDD §3 | Modelo_Dados.md | `_templates/estrutura/Modelo_Dados.template.md` |
-| §5 API | API.md | `_templates/estrutura/API.template.md` |
-| §6 Infra | Infraestrutura.md | `_templates/estrutura/Infraestrutura.template.md` |
-| §7 Segurança | Seguranca.md | `_templates/estrutura/Seguranca.template.md` |
-| SDD §2 Decisões | ADRs.md | `_templates/estrutura/ADRs.template.md` |
+| Doc gerado | Fontes | Template |
+|-----------|--------|---------|
+| architecture.md | TRD §2 Stack + §3 Arquitetura + §6 Infra (ambientes/deploy/CI/rollback) | `.claude/templates/estrutura/architecture.template.md` |
+| domain.md | TRD §1 Visão + §4 Modelo de Dados (+ SDD §3 em features) | `.claude/templates/estrutura/domain.template.md` |
+| conventions.md | TRD §7 Segurança + §6 Infra (env vars/monitoramento) + §5 API (códigos de erro) + §2 Stack (alternativas/versionamento) | `.claude/templates/estrutura/conventions.template.md` |
+| apiContracts.md | TRD §5 API (padrão geral, rotas, paginação, filtros, erros, catálogo) | `.claude/templates/estrutura/apiContracts.template.md` |
+| decisions.md | SDD §2 Decisões + decisões iniciais de stack/arquitetura | `.claude/templates/estrutura/decisions.template.md` |
 
 ## Regras
 
@@ -48,4 +45,4 @@
 2. **Ler TRD/SDD** → extrair dados para cada seção
 3. **Preencher** → seguindo formato do template exatamente
 4. **Remover instruções** → bloco `<!-- INSTRUÇÕES -->` não vai pro doc final
-5. **Commitar** → `docs(DOC-001): gerar Visao.md a partir do TRD`
+5. **Commitar** → `docs(DOC-001): gerar architecture.md a partir do TRD`

package/templates/.claude/agents/security-reviewer.md

@@ -11,7 +11,7 @@
 |-------|-------|
 | Área | Todas (cross-area) |
 | Modelo padrão | Opus |
-| Lê | Código produzido + SDD §5 (endpoints/auth) + SDD §9 (testes) + docs/Estrutura/Seguranca.md |
+| Lê | Código produzido + SDD §5 (endpoints/auth) + SDD §9 (testes) + docs/conventions.md (auth, authz, LGPD, auditoria) |
 | Nunca lê | PRD, PM |
 
 ## Quando é acionado

package/templates/.claude/commands/design.md

@@ -13,7 +13,7 @@ Técnico e preciso. Gera contratos completos. Toda decisão tem justificativa.
 | 1 | $ARGUMENTS informado | Parar |
 | 2 | `.context.md` existe com status `extract_done` ou `approved` | Se anterior → "/extract primeiro". Se posterior → "SDD já gerado" |
 | 3 | PRD.md ou TRD.md existe | Parar → "/extract primeiro" |
-| 4 | `docs/Estrutura/` populado (para features) | Parar → "/setup-projeto primeiro" (não aplica para tipo=setup) |
+| 4 | `docs/` populado (para features) | Parar → "/setup-projeto primeiro" (não aplica para tipo=setup) |
 
 ## Passos
 
@@ -27,29 +27,27 @@ Se status é `extract_done`:
 - Ler seção de ambiguidades (§13 PRD / §9 TRD)
 - Se há perguntas sem resposta → PARAR, listar pendentes
 
-### 3. Gerar docs/Estrutura/ (APENAS para setup)
+### 3. Gerar docs/ (APENAS para setup)
 
-> Este passo só executa quando tipo=setup. Para features, docs/Estrutura/ já existe.
+> Este passo só executa quando tipo=setup. Para features, docs/ já existe.
 
-Ler TRD e gerar os 8 docs de `docs/Estrutura/` usando os templates correspondentes:
+Ler TRD e gerar os 5 docs de `docs/` usando os templates correspondentes:
 
-| TRD Seção | Doc gerado | Template |
-|-----------|-----------|---------|
-| §1 Visão + §8 Módulos | Visao.md | `_templates/estrutura/Visao.template.md` |
-| §2 Stack | Stack.md | `_templates/estrutura/Stack.template.md` |
-| §3 Arquitetura | Arquitetura.md | `_templates/estrutura/Arquitetura.template.md` |
-| §4 Modelo de Dados | Modelo_Dados.md | `_templates/estrutura/Modelo_Dados.template.md` |
-| §5 API | API.md | `_templates/estrutura/API.template.md` |
-| §6 Infra | Infraestrutura.md | `_templates/estrutura/Infraestrutura.template.md` |
-| §7 Segurança | Seguranca.md | `_templates/estrutura/Seguranca.template.md` |
-| SDD §2 (após gerar) | ADRs.md | `_templates/estrutura/ADRs.template.md` |
+| Doc gerado | Fontes (TRD) | Template |
+|-----------|--------------|---------|
+| architecture.md | §3 Arquitetura + §2 Stack + §6 Infra (ambientes, deploy, CI/CD, rollback) | `.claude/templates/estrutura/architecture.template.md` |
+| domain.md | §1 Visão + §4 Modelo de Dados | `.claude/templates/estrutura/domain.template.md` |
+| conventions.md | §7 Segurança + §6 Infra (env vars, domínios, monitoramento) + §5 API (códigos de erro de domínio) + §2 Stack (alternativas, versionamento) | `.claude/templates/estrutura/conventions.template.md` |
+| apiContracts.md | §5 API (padrão geral, rotas, paginação, filtros, erros, catálogo) | `.claude/templates/estrutura/apiContracts.template.md` |
+| decisions.md | SDD §2 Decisões (após gerar) + decisões iniciais de stack/arquitetura | `.claude/templates/estrutura/decisions.template.md` |
 
 Regras:
 - Ler template → preencher TODAS seções com dados do TRD
 - Remover bloco `<!-- INSTRUÇÕES -->` do doc gerado
 - Changelog inicia vazio (primeira geração)
 - Se TRD não tem dados pra uma seção → marcar "A definir"
-- ADRs.md é gerado APÓS o SDD (usa §2 Decisões de Design)
+- decisions.md é gerado APÓS o SDD (usa §2 Decisões de Design como ponto de partida)
+- TRD §8 Módulos NÃO vira doc de Estrutura — vai para backlog faseado
 
 ### 3b. Gerar `projetos.yaml` (APENAS para setup)
 
@@ -75,8 +73,8 @@ Nunca juntar serviços que o TRD definiu como distintos.
 
 ### 4. Carregar contexto
 - PRD.md ou TRD.md completo
-- `docs/Estrutura/` (agora já populado, mesmo no setup)
-- `docs/Desenvolvimento/rules.md`
+- `docs/` (agora já populado, mesmo no setup)
+- `.claude/rules.md`
 - Template `sdd.template.md`
 
 ### 5. Gerar SDD
@@ -96,8 +94,9 @@ Nunca juntar serviços que o TRD definiu como distintos.
 **Setup**: §4-§8 podem ser N/A (normal).
 **Feature**: todas seções aplicáveis preenchidas.
 
-### 6. Gerar ADRs.md (setup — complemento do passo 3)
-Após gerar SDD §2, criar ADRs.md com as decisões iniciais de arquitetura.
+### 6. Complementar decisions.md (setup — complemento do passo 3)
+Após gerar SDD §2, popular `decisions.md` com as decisões iniciais de arquitetura
+(stack principal, padrões de design, trade-offs significativos).
 
 ### 7. Atualizar `.context.md`
 ```yaml

package/templates/.claude/commands/dev.md

@@ -70,7 +70,16 @@ Ler o perfil do agente em `.claude/agents/` antes de implementar.
 ║  VALIDAÇÃO POR FEATURE                        ║
 ║  1. Rodar E2E (SDD §9.3 CAs)                 ║
 ║     → Falhou? Identificar → fix → loop (max 3)║
-║  2. Tudo passou? → dev_done ✅                 ║
+║  2. Tudo passou? → prosseguir                 ║
+╚═══════════════════════════════════════════════╝
+        ↓ (E2E aprovado, só features)
+╔═══════════════════════════════════════════════╗
+║  MERGE-DELTA (automático, só features)        ║
+║  1. Ler SDD §11 (Delta Specs)                ║
+║  2. Aplicar ADDED/MODIFIED/REMOVED em         ║
+║     docs/                           ║
+║  3. Registrar changelog em cada doc alterado  ║
+║  4. dev_done ✅                                ║
 ╚═══════════════════════════════════════════════╝
 ```
 
@@ -160,8 +169,21 @@ git branch -d feature/{nome}_fase{N}
 git remote prune origin
 ```
 
+## Merge-Delta automático (só features)
+
+Após E2E aprovado, SE `.context.md` tipo = `feature`:
+1. Ler SDD §11 (seção Delta Specs: ADDED/MODIFIED/REMOVED)
+2. Para cada delta, mapear para o doc de `docs/` correspondente
+3. Aplicar as mudanças (adicionar, modificar ou remover seções)
+4. Registrar changelog em cada doc alterado: `| {{DATA}} | {{NOME}} | {{TIPO}} | {{DESCRIÇÃO}} |`
+5. Validar consistência cross-doc (ex: endpoint no apiContracts.md referencia tabela no domain.md)
+
+Se tipo = `setup` → pular (docs/ já foi criado pelo /design).
+
+> O `/merge-delta` continua existindo como command atômico para re-execução manual se necessário.
+
 ## Atualizar `.context.md`
 ```yaml
 status: "dev_in_progress"  # durante
-status: "dev_done"         # ao final (todas fases mergeadas)
+status: "dev_done"         # ao final (todas fases mergeadas + merge-delta aplicado)
 ```