sedd 0.1.0

package/README.md

@@ -0,0 +1,504 @@
+# SEDD - Spec & Expectation Driven Development
+
+> Desenvolvimento orientado por especificações **e expectativas** com sistema de migrations incrementais.
+
+[![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
+```
+
+### Compatível com
+
+<p>
+  <img src="https://img.shields.io/badge/Claude_Code-blueviolet?style=for-the-badge&logo=anthropic" alt="Claude Code" />
+  <img src="https://img.shields.io/badge/Cursor-000000?style=for-the-badge&logo=cursor" alt="Cursor" />
+  <img src="https://img.shields.io/badge/GitHub_Copilot-000000?style=for-the-badge&logo=github" alt="GitHub Copilot" />
+  <img src="https://img.shields.io/badge/Windsurf-0066FF?style=for-the-badge" alt="Windsurf" />
+  <img src="https://img.shields.io/badge/Gemini_CLI-4285F4?style=for-the-badge&logo=google" alt="Gemini CLI" />
+</p>
+
+---
+
+## Por que SEDD?
+
+### A Evolução do Spec Driven Development
+
+**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.
+
+Faltava capturar as **expectativas do desenvolvedor** - aquele conhecimento tácito que fica na cabeça:
+
+- *"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 Superpoder
+
+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` |
+
+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
+
+Ao trabalhar com AI assistants em projetos de desenvolvimento:
+
+| 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 |
+
+---
+
+## Como Funciona
+
+### Fluxo em 4 Passos
+
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│  1. SPECIFY │ →  │  2. CLARIFY │ →  │  3. TASKS   │ →  │ 4. IMPLEMENT│
+│             │    │             │    │             │    │             │
+│  O que?     │    │  Como?      │    │  Quanto?    │    │  Fazer!     │
+│  spec.md    │    │  clarify.md │    │  tasks.md   │    │  código     │
+└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
+```
+
+### 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
+
+```
+specs/024-dark-mode/
+├── _meta.json                    # Metadados
+├── spec.md                       # Spec base (imutável)
+├── interfaces.ts                 # Entidades
+│
+├── 001_2026-01-10_14-30-45/     # Migration 1
+│   ├── clarify.md               # Discussão
+│   ├── decisions.md             # Decisões
+│   └── tasks.md                 # Tasks T001-XXX
+│
+├── 002_2026-01-10_16-45-22/     # Migration 2
+│   ├── clarify.md
+│   ├── decisions.md
+│   └── tasks.md                 # Tasks T002-XXX
+│
+└── 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
+
+# Depois inicializar SEDD
+sedd init
+```
+
+### Se não houver projeto
+
+```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)
+```
+
+### 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
+
+# 6. Implementar
+/sedd.implement --all
+```
+
+---
+
+## Comandos
+
+### 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)
+
+| Comando | Descrição |
+|---------|-----------|
+| `/sedd.specify` | Criar spec base |
+| `/sedd.clarify` | Clarificar e gerar tasks |
+| `/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/`.
+
+---
+
+## Configuração
+
+`sedd.config.json`:
+
+```json
+{
+  "specsDir": ".sedd",
+  "branchPattern": "{{id}}-{{name}}",
+  "scriptRunner": "auto",
+  "autoSplit": {
+    "enabled": true,
+    "maxLines": 400
+  },
+  "commit": {
+    "askBeforeCommit": true
+  }
+}
+```
+
+| Opção | Default | Descrição |
+|-------|---------|-----------|
+| `specsDir` | `.sedd` | Pasta das specs (use `specs` para legacy) |
+| `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.
+
+---
+
+## Licença
+
+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>
+  Expectativas dizem COMO você imagina que deve funcionar.<br>
+  E juntas, elas são o superpoder que faltava.</b>
+</p>

package/bin/sedd.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import('../dist/cli/index.js').catch((err) => {
+  console.error('Failed to start SEDD CLI:', err.message);
+  process.exit(1);
+});