sedd 0.1.2 → 0.1.4

package/README.md

@@ -20,152 +20,172 @@
 
 ## Quick Start
 
-### Instalação
-
 ```bash
+# Instalar
 npm install -g sedd
-```
-
-### Uso
 
-```bash
-# 1. Navegue para seu projeto
+# Inicializar no projeto
 cd meu-projeto
-
-# 2. Inicialize SEDD
 sedd init
 
-# 3. Crie uma feature spec
+# Criar feature spec
 sedd specify 001 user-auth
 
-# 4. Edite a spec
-# .sedd/001-user-auth/spec.md
-
-# 5. Use seu LLM favorito para implementar
+# Usar AI assistant
 claude  # ou cursor, copilot, etc.
 
-# 6. Documente decisões
-sedd clarify
+# Comandos no AI
+/sedd.clarify    # Definir expectativa e gerar tasks
+/sedd.implement  # Executar tasks
 ```
 
-### Comandos
-
-| 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 |
-
 ---
 
 ## 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 captura sua **expectativa** antes de qualquer código. A AI sempre sabe o que você espera.
 
 ```
-SEDD = Spec Driven Development + Expectativas do Dev
-```
+🎯 EXPECTATIVA: "User can toggle dark mode and persist across sessions"
 
-### O Superpoder
+📊 Coverage: ~85% 🟢
 
-SEDD captura três dimensões:
-
-| Dimensão | Pergunta | Artefato |
-|----------|----------|----------|
-| **Spec** | O que o sistema faz? | `spec.md` |
-| **Expectation** | Como você espera que funcione? | `clarify.md` |
-| **Decision** | Por que foi decidido assim? | `decisions.md` |
+Tasks:
+- T001-001: Create ThemeContext
+- T001-002: Add toggle component
+- T001-003: Persist to localStorage
+```
 
 ---
 
-## Por que SEDD?
+## Expectation-First Workflow
 
-Ao trabalhar com AI assistants em projetos de desenvolvimento:
+### 1. Captura Obrigatória
 
-| Problema | Sem SEDD | Com SEDD |
-|----------|----------|----------|
-| **Contexto perdido** | AI "esquece" decisões anteriores | Tudo documentado em migrations |
-| **Falta de rastreabilidade** | "Por que fizemos assim?" | `decisions.md` com timestamps |
-| **Specs vagas** | Retrabalho constante | Clarificação interativa |
-| **Tasks desorganizadas** | Espalhadas ou esquecidas | `tasks.md` com IDs únicos |
-| **Difícil retomar** | Onde parei? O que falta? | `progress.md` atualizado |
+Ao usar `/sedd.specify` ou `/sedd.clarify`, a AI pergunta primeiro:
 
----
+```
+🎯 Qual é sua EXPECTATIVA para esta feature?
+
+O que você espera ver funcionando quando estiver pronto?
+```
 
-## Como Funciona
+### 2. Score de Alinhamento
 
-### Fluxo em 4 Passos
+Ao gerar tasks, SEDD calcula cobertura:
 
 ```
-┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
-│  1. SPECIFY │ →  │  2. CLARIFY │ →  │  3. TASKS   │ →  │ 4. IMPLEMENT│
-│             │    │             │    │             │    │             │
-│  O que?     │    │  Como?      │    │  Quanto?    │    │  Fazer!     │
-│  spec.md    │    │  clarify.md │    │  tasks.md   │    │  código     │
-└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
+📊 Coverage: ~83% 🟢
+
+Tokens encontrados:
+  ✅ toggle (T001-003)
+  ✅ dark mode (T001-003, T001-004)
+  ✅ persist (T001-003)
+  ❌ sessions - não encontrado
+
+⚠️ Deseja adicionar tasks para cobrir os gaps? [Y/n]
 ```
 
-### Estrutura de Pastas
+### 3. Acceptance Criteria Automático
+
+SEDD gera `acceptance.md` baseado na expectativa:
+
+```markdown
+## Checklist de Aceite
 
+- [ ] AC-001: User can toggle dark mode
+- [ ] AC-002: Toggle está em settings
+- [ ] AC-003: Theme persists after refresh
+- [ ] AC-004: Theme persists across sessions
 ```
-.sedd/001-user-auth/
-├── spec.md                       # Especificação base
-├── _meta.json                    # Metadados
-│
-├── M001/                         # Migration 1
-│   ├── clarify.md               # Discussão
-│   ├── decisions.md             # Decisões
-│   └── tasks.md                 # Tasks T001-XXX
-│
-├── M002/                         # Migration 2
-│   ├── clarify.md
-│   ├── decisions.md
-│   └── tasks.md                 # Tasks T002-XXX
-│
-└── progress.md                   # Progresso geral
+
+### 4. Checkpoints Durante Implementação
+
+A cada 3 tasks, SEDD verifica alinhamento:
+
 ```
+⏸️ Checkpoint - 3/10 tasks completas
 
----
+Sua expectativa:
+> User can toggle dark mode and persist
 
-## Migrations: O Diferencial
+Isso ainda está alinhado? [Y/n/ajustar]
+```
 
-O grande diferencial do SEDD é o sistema de **migrations incrementais**.
+### 5. Validação Final
 
-Você não precisa saber tudo no início. Pode clarificar aos poucos:
+Ao completar migration, valida contra acceptance criteria:
 
-```bash
-sedd clarify  →  Migration M001 (5 tasks)
-# implemente...
-sedd clarify  →  Migration M002 (3 tasks mais)
-# implemente...
-sedd clarify  →  Migration M003 (ajustes)
 ```
+🏁 Migration 001 Completa!
 
-### Benefícios
+Acceptance Criteria:
+- [x] AC-001: User can toggle ✓
+- [x] AC-002: Toggle in settings ✓
+- [ ] AC-003: Persist after refresh ✗
 
-- **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
+Criar migration de follow-up? [Y/n]
+```
 
 ---
 
-## Slash Commands (AI Assistants)
+## Comandos CLI
+
+| 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 |
 
-Use estes comandos no Claude Code, Cursor, etc:
+## Slash Commands (AI)
 
 | Comando | Descrição |
 |---------|-----------|
-| `/sedd.specify` | Criar spec base |
-| `/sedd.clarify` | Clarificar e gerar tasks |
-| `/sedd.tasks` | Adicionar tasks à migration |
-| `/sedd.implement` | Executar tasks |
+| `/sedd.specify` | Criar spec (pergunta expectativa primeiro) |
+| `/sedd.clarify` | Clarificar e gerar tasks com score |
+| `/sedd.implement` | Executar tasks com checkpoints |
 | `/sedd.implement --all` | Executar tudo sem parar |
 
 ---
 
+## Estrutura de Pastas
+
+```
+.sedd/001-user-auth/
+├── spec.md                       # Especificação + Expectativa
+├── _meta.json                    # Metadados + expectation field
+│
+├── 001_timestamp/                # Migration 1
+│   ├── clarify.md               # Discussão
+│   ├── decisions.md             # Decisões
+│   ├── tasks.md                 # Tasks T001-XXX
+│   └── acceptance.md            # Critérios de aceite
+│
+└── progress.md                   # Progresso + checkpoints
+```
+
+---
+
+## Hooks Inteligentes
+
+O hook `check-roadmap.js` sempre mostra:
+
+```xml
+<sedd-context>
+Branch: 024-feature | Migration: 001 | Progress: 3/10 🟢 ~85%
+
+🎯 FEATURE: User can customize theme
+📍 MIGRATION 001: Toggle dark mode with persistence
+
+Pending tasks:
+- T001-004: Add to settings page
+- T001-005: API endpoint
+</sedd-context>
+```
+
+---
+
 ## Configuração
 
 `sedd.config.json`:
@@ -178,12 +198,6 @@ Use estes comandos no Claude Code, Cursor, etc:
 }
 ```
 
-| Opção | Default | Descrição |
-|-------|---------|-----------|
-| `specsDir` | `.sedd` | Pasta das specs |
-| `branchPattern` | `{{id}}-{{name}}` | Formato do nome da branch |
-| `scriptRunner` | `auto` | `auto`, `powershell`, ou `bash` |
-
 ---
 
 ## Licença
@@ -195,5 +209,5 @@ MIT
 <p align="center">
   <b>Especificações dizem O QUE construir.<br>
   Expectativas dizem COMO você imagina que deve funcionar.<br>
-  Juntas, são o superpoder que faltava.</b>
+  SEDD garante que as duas estejam sempre alinhadas.</b>
 </p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sedd",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "SEDD - Spec & Expectation Driven Development. A phase-based specification workflow for AI-assisted development.",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,8 @@
     "templates",
     "commands",
     "scripts",
-    "hooks"
+    "hooks",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc",