sedd 0.1.0 → 0.1.2

package/README.md

@@ -4,14 +4,7 @@
 
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
-
-## O que é SEDD?
-
-SEDD é um toolkit que transforma a forma como você desenvolve software com AI assistants. Em vez de apenas especificar *o que* construir, você também captura *como espera que funcione* - suas expectativas como desenvolvedor.
-
-```
-SEDD = Spec Driven Development + Expectativas do Dev
-```
+[![npm](https://img.shields.io/npm/v/sedd.svg)](https://www.npmjs.com/package/sedd)
 
 ### Compatível com
 
@@ -25,19 +18,55 @@ SEDD = Spec Driven Development + Expectativas do Dev
 
 ---
 
-## Por que SEDD?
+## Quick Start
+
+### Instalação
+
+```bash
+npm install -g sedd
+```
+
+### Uso
+
+```bash
+# 1. Navegue para seu projeto
+cd meu-projeto
+
+# 2. Inicialize SEDD
+sedd init
+
+# 3. Crie uma feature spec
+sedd specify 001 user-auth
+
+# 4. Edite a spec
+# .sedd/001-user-auth/spec.md
+
+# 5. Use seu LLM favorito para implementar
+claude  # ou cursor, copilot, etc.
 
-### A Evolução do Spec Driven Development
+# 6. Documente decisões
+sedd clarify
+```
 
-**Spec Driven Development (SDD)** já era poderoso: você documenta o que vai construir antes de codar. Mas ao trabalhar com AI assistants, percebemos que specs sozinhas não bastavam.
+### Comandos
 
-Faltava capturar as **expectativas do desenvolvedor** - aquele conhecimento tácito que fica na cabeça:
+| Comando | Descrição |
+|---------|-----------|
+| `sedd init` | Inicializar SEDD no projeto |
+| `sedd specify <id> <name>` | Criar nova feature spec |
+| `sedd clarify` | Criar migration com decisões |
+| `sedd status` | Ver status atual |
+| `sedd --help` | Ver todos os comandos |
 
-- *"Eu espero que isso seja rápido, tipo < 100ms"*
-- *"Eu imagino que o usuário vai clicar aqui primeiro"*
-- *"Na minha cabeça, isso funciona parecido com o Stripe"*
+---
 
-Essas expectativas raramente são documentadas. Ficam implícitas. E quando você trabalha com uma AI, ela não tem como adivinhar.
+## O que é SEDD?
+
+SEDD é um toolkit que transforma a forma como você desenvolve software com AI assistants. Em vez de apenas especificar *o que* construir, você também captura *como espera que funcione* - suas expectativas como desenvolvedor.
+
+```
+SEDD = Spec Driven Development + Expectativas do Dev
+```
 
 ### O Superpoder
 
@@ -49,11 +78,9 @@ SEDD captura três dimensões:
 | **Expectation** | Como você espera que funcione? | `clarify.md` |
 | **Decision** | Por que foi decidido assim? | `decisions.md` |
 
-Quando você clarifica uma feature no SEDD, não está só respondendo perguntas técnicas. Está **externalizando suas expectativas** para que a AI (e você mesmo no futuro) entenda o *espírito* do que você quer construir.
-
 ---
 
-## O Problema que Resolvemos
+## Por que SEDD?
 
 Ao trabalhar com AI assistants em projetos de desenvolvimento:
 
@@ -80,104 +107,19 @@ Ao trabalhar com AI assistants em projetos de desenvolvimento:
 └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
 ```
 
-### 1. Specify - Defina o que construir
-
-```bash
-/sedd.specify "Add dark mode toggle to settings"
-```
-
-Cria a especificação base com:
-- `spec.md` - Requisitos funcionais
-- `interfaces.ts` - Entidades do domínio
-- `ui-mockups/` - ASCII mockups (se UI)
-
-### 2. Clarify - Capture expectativas
-
-```bash
-/sedd.clarify
-```
-
-**Modo de discussão flexível** - você controla o ritmo:
-
-```
-📝 Clarification Session - Migration 001
-
-Você pode:
-• Explicar livremente o que precisa
-• Adicionar notas e decisões
-• Responder perguntas
-
-Comandos:
-┌───────────┬────────────────────────────────────┐
-│ continue  │ Continuar explicando (mais, +)     │
-│ pergunta  │ AI faz próxima pergunta (q, ?)     │
-│ tasks     │ Gerar tasks e finalizar (done)     │
-└───────────┴────────────────────────────────────┘
-```
-
-Cada clarificação cria uma **migration** com timestamp:
-- `clarify.md` - O que foi discutido
-- `decisions.md` - Decisões tomadas
-- `tasks.md` - Tarefas geradas
-
-### 3. Tasks - Quebre em tarefas
-
-Tasks são geradas automaticamente no `/sedd.clarify`, mas você pode adicionar mais:
-
-```bash
-/sedd.tasks
-```
-
-Formato das tasks:
-```
-T001-001 = Migration 001, Task 1
-T001-002 = Migration 001, Task 2
-T002-001 = Migration 002, Task 1
-```
-
-### 4. Implement - Execute
-
-```bash
-/sedd.implement        # Pergunta entre migrations
-/sedd.implement --all  # Executa tudo sem parar
-/sedd.implement 001    # Só migration específica
-```
-
-A AI executa cada task, atualiza `progress.md`, e marca como concluída.
-
----
-
-## Migrations: O Diferencial
-
-O grande diferencial do SEDD é o sistema de **migrations incrementais**.
-
-### Por que Migrations?
-
-Você não precisa saber tudo no início. Pode clarificar aos poucos:
-
-```
-/sedd.clarify  →  Migration 001 (5 tasks)
-/sedd.implement 001
-/sedd.clarify  →  Migration 002 (3 tasks mais)
-/sedd.implement 002
-/sedd.clarify  →  Migration 003 (ajustes)
-...
-```
-
-### Estrutura
+### Estrutura de Pastas
 
 ```
-specs/024-dark-mode/
+.sedd/001-user-auth/
+├── spec.md                       # Especificação base
 ├── _meta.json                    # Metadados
-├── spec.md                       # Spec base (imutável)
-├── interfaces.ts                 # Entidades
 │
-├── 001_2026-01-10_14-30-45/     # Migration 1
+├── M001/                         # Migration 1
 │   ├── clarify.md               # Discussão
 │   ├── decisions.md             # Decisões
 │   └── tasks.md                 # Tasks T001-XXX
 │
-├── 002_2026-01-10_16-45-22/     # Migration 2
+├── M002/                         # Migration 2
 │   ├── clarify.md
 │   ├── decisions.md
 │   └── tasks.md                 # Tasks T002-XXX
@@ -185,150 +127,34 @@ specs/024-dark-mode/
 └── progress.md                   # Progresso geral
 ```
 
-### Benefícios
-
-- **Histórico completo**: Cada decisão tem timestamp e contexto
-- **Rastreabilidade**: Task T002-003 → Migration 002 → Decisão D002-003
-- **Flexibilidade**: Implemente migration 001, depois clarifica mais
-- **Retomada fácil**: Volte semanas depois e saiba exatamente onde parou
-
 ---
 
-## Fases de Desenvolvimento
-
-SEDD funciona em qualquer fase do projeto:
-
-### 🌱 Greenfield (Projeto Novo)
-
-Comece do zero com especificações claras:
-
-```bash
-npx sedd init my-project
-cd my-project
-git checkout -b 001-auth-system
-/sedd.specify "User authentication with OAuth"
-/sedd.clarify
-/sedd.implement --all
-```
-
-### 🔧 Brownfield (Projeto Existente)
-
-Adicione features incrementalmente:
-
-```bash
-git checkout -b 042-dark-mode
-/sedd.specify "Add dark mode to existing settings"
-# SEDD analisa código existente e sugere integrações
-/sedd.clarify
-/sedd.implement
-```
-
-### 🔄 Refactoring
-
-Documente antes de refatorar:
-
-```bash
-git checkout -b 050-refactor-auth
-/sedd.specify "Refactor auth to use JWT instead of sessions"
-/sedd.clarify  # Capture todas as decisões de migração
-/sedd.implement --all
-```
-
----
-
-## Quick Start
-
-### Instalação
-
-```bash
-npm install -g sedd
-# ou use diretamente com npx
-```
-
-### Projeto Existente (Recomendado)
-
-```bash
-# Navegar para seu projeto
-cd meu-projeto
-
-# SEDD detecta automaticamente o package.json
-sedd init
-
-# Output:
-# 🔍 Detected project: meu-projeto
-# 🚀 Initializing SEDD...
-```
-
-### Projeto Novo
-
-```bash
-# Criar projeto primeiro
-mkdir meu-projeto && cd meu-projeto
-npm init -y
+## Migrations: O Diferencial
 
-# Depois inicializar SEDD
-sedd init
-```
+O grande diferencial do SEDD é o sistema de **migrations incrementais**.
 
-### Se não houver projeto
+Você não precisa saber tudo no início. Pode clarificar aos poucos:
 
 ```bash
-sedd init
-
-# Output:
-# ⚠️  No project detected in current directory.
-#
-# SEDD works best inside a project. Try one of these:
-#   1. Run npm init -y to create a package.json
-#   2. Run sedd init my-project to specify a project name
-#   3. Navigate to an existing project folder
-#
-# ? Initialize SEDD anyway in current directory? (y/N)
+sedd clarify  →  Migration M001 (5 tasks)
+# implemente...
+sedd clarify  →  Migration M002 (3 tasks mais)
+# implemente...
+sedd clarify  →  Migration M003 (ajustes)
 ```
 
-### Workflow Completo
-
-```bash
-# 1. Navegar para projeto existente
-cd meu-projeto
-
-# 2. Inicializar SEDD (detecta package.json)
-sedd init
-
-# 3. Criar branch da feature
-git checkout -b 001-user-auth
-
-# 4. Especificar (no Claude Code / Cursor)
-/sedd.specify "User authentication with email and password"
-
-# 5. Clarificar (modo interativo)
-/sedd.clarify
-# → Explique suas expectativas
-# → Responda perguntas
-# → Digite "tasks" quando pronto
+### Benefícios
 
-# 6. Implementar
-/sedd.implement --all
-```
+- **Histórico completo**: Cada decisão tem timestamp e contexto
+- **Rastreabilidade**: Task T002-003 → Migration M002 → Decisão
+- **Flexibilidade**: Implemente M001, depois clarifica mais
+- **Retomada fácil**: Volte semanas depois e saiba onde parou
 
 ---
 
-## Comandos
+## Slash Commands (AI Assistants)
 
-### CLI (Terminal)
-
-| Comando | Descrição |
-|---------|-----------|
-| `sedd init` | Inicializar (detecta package.json automaticamente) |
-| `sedd init meu-projeto` | Inicializar com nome específico |
-| `sedd init --force` | Atualizar arquivos existentes |
-| `sedd check` | Verificar estrutura |
-| `sedd status` | Ver status atual |
-| `sedd clarify` | Criar nova migration |
-| `sedd tasks '<json>'` | Adicionar tasks |
-| `sedd complete T001-001` | Marcar task completa |
-
-### Slash Commands (AI Assistants)
+Use estes comandos no Claude Code, Cursor, etc:
 
 | Comando | Descrição |
 |---------|-----------|
@@ -337,62 +163,6 @@ git checkout -b 001-user-auth
 | `/sedd.tasks` | Adicionar tasks à migration |
 | `/sedd.implement` | Executar tasks |
 | `/sedd.implement --all` | Executar tudo sem parar |
-| `/sedd.migrate` | Migrar specs antigas |
-
----
-
-## Hooks: Contexto Automático para AI
-
-SEDD inclui **hooks inteligentes** que injetam contexto automaticamente nas suas conversas com AI.
-
-### Como Funciona
-
-Quando você digita algo no AI assistant, o hook analisa e injeta:
-
-```
-You: "vamos implementar a próxima task"
-
-⎿  UserPromptSubmit says:
-   <sedd-context>
-   **Branch: 023-agent-executor** | Migration: 002 | Progress: 69/110 tasks
-
-   Pending tasks:
-   - T001-054: [Polish] Remove all // TODO comments
-   - T001-055: [Polish] Remove deprecated modals
-   - T001-056: [Polish] Update tool.service.ts
-   ... and 36 more
-
-   Use `/sedd.implement` to execute tasks.
-   </sedd-context>
-```
-
-A AI recebe automaticamente:
-- Branch atual e migration ativa
-- Progresso geral (X/Y tasks)
-- Lista de tasks pendentes
-- Sugestão do próximo comando
-
-### Ativação de Skills
-
-O hook também detecta contexto e sugere skills relevantes:
-
-```
-You: "estou tendo erro no langgraph"
-
-⎿  Hook detected: LangChain/LangGraph context
-   Suggesting: langchain-expert skill
-```
-
-### Instalação dos Hooks
-
-Os hooks são copiados automaticamente no `sedd init`:
-
-```
-.claude/hooks/
-└── check-roadmap.js    # Hook principal
-```
-
-Ou copie manualmente de `node_modules/sedd/hooks/`.
 
 ---
 
@@ -404,78 +174,15 @@ Ou copie manualmente de `node_modules/sedd/hooks/`.
 {
   "specsDir": ".sedd",
   "branchPattern": "{{id}}-{{name}}",
-  "scriptRunner": "auto",
-  "autoSplit": {
-    "enabled": true,
-    "maxLines": 400
-  },
-  "commit": {
-    "askBeforeCommit": true
-  }
+  "scriptRunner": "auto"
 }
 ```
 
 | Opção | Default | Descrição |
 |-------|---------|-----------|
-| `specsDir` | `.sedd` | Pasta das specs (use `specs` para legacy) |
+| `specsDir` | `.sedd` | Pasta das specs |
 | `branchPattern` | `{{id}}-{{name}}` | Formato do nome da branch |
 | `scriptRunner` | `auto` | `auto`, `powershell`, ou `bash` |
-| `autoSplit.maxLines` | `400` | Auto-split de arquivos grandes |
-| `commit.askBeforeCommit` | `true` | Perguntar antes de commitar |
-
-### Script Runner
-
-Por padrão (`auto`), SEDD detecta o OS e usa:
-- **Windows** → PowerShell (`.ps1`)
-- **macOS/Linux** → Bash (`.sh`)
-
-Para forçar um runner específico (ex: usar Bash no Windows via WSL/Git Bash):
-
-```json
-{
-  "scriptRunner": "bash"
-}
-```
-
----
-
-## Filosofia
-
-### Princípios
-
-1. **Expectativas primeiro** - Não só o que, mas como você espera que funcione
-2. **Nada acontece sem task** - Toda implementação deve estar rastreada
-3. **Decisões são documentadas** - Não confie na memória, documente
-4. **Incremental > Big Bang** - Clarifica aos poucos, implementa aos poucos
-5. **AI como parceiro** - Ferramentas pensadas para colaboração AI-humano
-
-### Comparação
-
-| Aspecto | Vibe Coding | Spec-Driven | SEDD |
-|---------|-------------|-------------|------|
-| Especificação | ❌ Nenhuma | ✅ Detalhada | ✅ Detalhada |
-| Expectativas | ❌ Implícitas | ❌ Implícitas | ✅ **Explícitas** |
-| Histórico | ❌ Nenhum | ⚠️ Limitado | ✅ **Migrations** |
-| Clarificação | ❌ Ad-hoc | ⚠️ Única vez | ✅ **Incremental** |
-| Retomada | ❌ Difícil | ⚠️ Possível | ✅ **progress.md** |
-
----
-
-## Migração de Projetos
-
-Se você já tem specs em formato antigo:
-
-```bash
-npx sedd migrate
-# ou
-/sedd.migrate
-```
-
----
-
-## Contribuindo
-
-Contribuições são bem-vindas! Veja [CONTRIBUTING.md](CONTRIBUTING.md) para guidelines.
 
 ---
 
@@ -486,19 +193,7 @@ MIT
 ---
 
 <p align="center">
-  <i>
-    SEDD nasceu da evolução do Spec Driven Development para incluir o que realmente importa: <b>suas expectativas como desenvolvedor</b>.
-  </i>
-</p>
-
-<p align="center">
-  <i>
-    Se você já teve que explicar a mesma coisa 3 vezes para uma AI, ou se já perdeu horas porque a AI não entendeu o "espírito" do que você queria — este projeto é para você.
-  </i>
-</p>
-
-<p align="center">
-  <b>Porque especificações dizem O QUE construir.<br>
+  <b>Especificações dizem O QUE construir.<br>
   Expectativas dizem COMO você imagina que deve funcionar.<br>
-  E juntas, elas são o superpoder que faltava.</b>
+  Juntas, são o superpoder que faltava.</b>
 </p>