sedd 0.1.0

package/commands/sedd.clarify.md

@@ -0,0 +1,435 @@
+# /sedd.clarify - Clarify & Generate Tasks
+
+## Purpose
+Create a new migration with clarifications, decisions, AND tasks.
+
+## Trigger
+User runs `/sedd.clarify`
+
+## Pre-flight Checks
+
+1. **Read sedd.config.json** to get `specsDir` (default: `.sedd`, legacy: `specs`)
+   ```
+   Read sedd.config.json → specsDir = "specs" or ".sedd"
+   ```
+
+2. **Get current branch** from git
+   ```
+   git rev-parse --abbrev-ref HEAD → "023-agent-executor"
+   ```
+
+3. **Find feature directory**
+   ```
+   {specsDir}/{branch}/ → specs/023-agent-executor/
+   ```
+
+4. **Verify spec.md exists** in feature directory (run /sedd.specify first)
+
+5. **Load _meta.json** from feature directory to get current state
+
+## CRITICAL RULES
+
+⚠️ **THIS COMMAND IS READ-ONLY FOR CODE**
+- NEVER execute code
+- NEVER create implementation files
+- NEVER modify files outside specs/
+- ONLY create migration folder with clarify/tasks/decisions
+
+⚠️ **FLEXIBLE DISCUSSION MODE - INLINE COMMANDS**
+- User can freely explain, discuss, and add notes at any time
+- AI listens and records everything in clarify.md
+- User controls the flow with inline commands:
+
+| Command | Aliases | Action |
+|---------|---------|--------|
+| `continue` | `mais`, `more`, `+` | Keep discussing, AI records notes |
+| `pergunta` | `question`, `q`, `?` | AI asks next clarification question |
+| `tasks` | `done`, `gerar`, `finish` | Generate tasks.md and finish |
+
+⚠️ **ALWAYS CREATES TASKS**
+- Every clarify creates a NEW migration
+- Every migration has tasks.md (generated at the end)
+- Tasks reference this migration ID
+
+## Workflow
+
+### Step 1: Load Context
+
+Read from feature root:
+- spec.md
+- interfaces.ts
+- Previous migrations (if any)
+
+### Step 2: Capture Expected Outcome (NEW)
+
+Before creating migration, ask user:
+```
+What do you expect to achieve with this clarification?
+(This will be used to verify task alignment)
+```
+
+Save in `clarify.md` under `## Expected Outcome` section.
+
+### Step 3: Create New Migration Folder
+
+Generate new migration folder FIRST:
+
+```
+Migration ID: 001 (or next: 002, 003...)
+Timestamp: 2026-01-11_10-30-45
+Folder: 001_2026-01-11_10-30-45/
+```
+
+Create initial structure:
+```
+specs/024-feature/
+└── 001_2026-01-11_10-30-45/
+    ├── clarify.md      # Will be updated incrementally
+    ├── tasks.md        # Created at the end
+    └── decisions.md    # Updated after each answer
+```
+
+Initialize clarify.md:
+```markdown
+# Clarification - Migration 001
+
+**Timestamp:** 2026-01-11 10:30:45
+**Branch:** 024-feature
+**Parent:** (none)
+
+## Expected Outcome
+
+> User's expected outcome from this migration
+
+[Captured from Step 2]
+
+---
+
+## Questions & Answers
+
+```
+
+### Step 4: Start Interactive Session
+
+Present the clarification session with available commands:
+
+```
+📝 Clarification Session - Migration 001
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Spec loaded: spec.md
+Interfaces: interfaces.ts
+
+Você pode:
+• Explicar livremente o que precisa
+• Adicionar notas e decisões
+• Responder perguntas
+
+Comandos disponíveis:
+┌───────────┬────────────────────────────────────┐
+│ continue  │ Continuar explicando (mais, +)     │
+│ pergunta  │ AI faz próxima pergunta (q, ?)     │
+│ tasks     │ Gerar tasks e finalizar (done)     │
+└───────────┴────────────────────────────────────┘
+
+Como você quer começar?
+```
+
+### Step 5: Flexible Discussion Loop
+
+The AI responds based on user input:
+
+#### 5.1 User Explains/Discusses (Default Mode)
+
+When user provides information (not a command):
+
+1. **Listen and understand** the user's explanation
+2. **Update clarify.md immediately** with notes:
+
+```markdown
+## Notes & Discussions
+
+### Note 001 - 10:30:45
+**User said:**
+"O sistema precisa suportar múltiplos tenants, cada um com suas próprias configurações..."
+
+**Key Points Extracted:**
+- Multi-tenant architecture required
+- Per-tenant configuration
+- Isolation between tenants
+
+---
+```
+
+3. **Update decisions.md** if a decision is implied:
+
+```markdown
+## D001-001: Multi-tenant Architecture
+
+**Source:** User explanation (Note 001)
+
+**Decision:**
+System will support multiple tenants with isolated configurations.
+
+**Impact:**
+- Database schema needs tenant_id
+- API routes need tenant context
+- Auth must include tenant info
+
+---
+```
+
+4. **Acknowledge and prompt for more:**
+
+```
+✓ Anotado: Multi-tenant com configurações isoladas
+
+Continue explicando ou use um comando:
+• continue / mais → mais detalhes
+• pergunta / ? → AI faz uma pergunta
+• tasks / done → gerar tasks
+```
+
+#### 5.2 User Says "continue" / "mais" / "more" / "+"
+
+Keep in discussion mode:
+
+```
+Ok, continue explicando...
+```
+
+#### 5.3 User Says "pergunta" / "question" / "q" / "?"
+
+AI analyzes gaps and asks ONE clarification question:
+
+```
+---
+Q1: Tenant Isolation Level
+**Impact:** High | **Area:** Architecture
+
+Como deve ser o isolamento entre tenants?
+
+┌───────┬───────────────────────────────────────┐
+│ Opção │          Descrição                    │
+├───────┼───────────────────────────────────────┤
+│ A     │ Logical (same DB, tenant_id filter)   │
+│ B     │ Schema (separate schemas per tenant)  │
+│ C     │ Physical (separate DBs per tenant)    │
+└───────┴───────────────────────────────────────┘
+
+Sua resposta (ou continue explicando):
+---
+```
+
+After user answers, update clarify.md and decisions.md immediately.
+
+#### 5.4 User Says "tasks" / "done" / "gerar" / "finish"
+
+Proceed to Step 6 (Generate Tasks).
+
+### Step 6: Generate tasks.md (After All Q&A Complete)
+
+Based on all decisions, create tasks:
+
+```markdown
+# Tasks - Migration 001
+
+**Migration:** 001
+**Timestamp:** 2026-01-11_10-30-45
+**Parent:** (none)
+
+## Summary
+Total: 5 | Completed: 0 | Pending: 5
+
+## Tasks
+
+- [ ] T001-001 [Foundation] Create ThemeContext in `src/contexts/ThemeContext.tsx`
+- [ ] T001-002 [Foundation] Add theme column to users table `prisma/schema.prisma`
+- [ ] T001-003 [US1] Create ThemeToggle component `src/components/ThemeToggle.tsx`
+- [ ] T001-004 [US1] Add toggle to settings page `src/pages/settings.tsx`
+- [ ] T001-005 [US1] Implement theme API endpoint `src/api/user/theme.ts`
+
+## Dependencies
+
+T001-001, T001-002 → T001-003 → T001-004
+                   → T001-005
+```
+
+### Step 7: Expectation Alignment Check (NEW)
+
+After generating tasks, verify alignment with expected outcome:
+
+```markdown
+## Expectation Alignment Check
+
+**Your expectation:**
+> [User's expected outcome from clarify.md]
+
+**Generated tasks cover:**
+- Task T001-001: Creates ThemeContext ✅
+- Task T001-002: Updates database schema ✅
+- Task T001-003: Creates toggle component ✅
+- Task T001-004: Adds to settings page ✅
+- Task T001-005: API endpoint ✅
+
+**Alignment:** ✅ Aligned
+```
+
+#### When Misaligned:
+
+If tasks don't cover the expectation:
+
+```
+⚠️ Tasks geradas não cobrem completamente sua expectativa.
+
+**Missing from expectation:**
+- [item not covered by tasks]
+
+Deseja prosseguir mesmo assim? [Y/n]
+```
+
+**If user says "no"** - Return to discussion mode:
+```
+Ok, vamos continuar a clarificação.
+
+Use os comandos:
+• continue - explicar mais detalhes
+• pergunta - AI faz pergunta de refinamento
+• tasks - tentar gerar tasks novamente
+```
+
+### Step 8: Update _meta.json
+
+```json
+{
+  "currentMigration": "001",
+  "migrations": {
+    "001": {
+      "id": "001",
+      "timestamp": "2026-01-11_10-30-45",
+      "folder": "001_2026-01-11_10-30-45",
+      "status": "in-progress",
+      "tasksTotal": 5,
+      "tasksCompleted": 0,
+      "createdAt": "2026-01-11T10:30:45Z",
+      "expectation": "User can toggle dark mode and have it persist"
+    }
+  }
+}
+```
+
+### Step 9: Update CHANGELOG.md
+
+```markdown
+## [2026-01-11] - Migration 001
+
+- Clarified 5 requirements
+- Created 5 decisions
+- Generated 5 tasks
+- Areas covered: Persistence, API, UI
+```
+
+### Step 10: Ask About Commit
+
+```
+Migration 001 completed with 5 tasks!
+
+Do you want to commit?
+Message: "docs(024): migration 001 - clarify requirements and generate tasks"
+```
+
+### Step 11: Offer Next Steps
+
+```
+What would you like to do?
+
+1. /sedd.clarify - Create another migration (more clarifications)
+2. /sedd.implement - Start implementing tasks
+3. /sedd.implement 001 - Implement only this migration
+```
+
+## Task ID Format
+
+Tasks are prefixed with migration ID:
+
+```
+T001-001  = Migration 001, Task 1
+T001-002  = Migration 001, Task 2
+T002-001  = Migration 002, Task 1
+```
+
+## Running Multiple Times
+
+Each `/sedd.clarify` creates a NEW migration:
+
+```
+1st run: 001_2026-01-11_10-30-45/
+2nd run: 002_2026-01-11_14-15-30/
+3rd run: 003_2026-01-12_09-00-00/
+```
+
+Parent references allow tracking the evolution:
+- 002.parent = 001
+- 003.parent = 002
+
+## Rules
+
+- **NEVER EXECUTE CODE** - Design phase only
+- **FLEXIBLE DISCUSSION** - User controls the flow with inline commands
+- **UPDATE FILES IMMEDIATELY** - After each user input
+- **RECOGNIZE INLINE COMMANDS:**
+  - `continue`, `mais`, `more`, `+` → Keep discussing
+  - `pergunta`, `question`, `q`, `?` → AI asks next question
+  - `tasks`, `done`, `gerar`, `finish` → Generate tasks and end
+- ALWAYS generate tasks.md when user says "tasks/done"
+- Task IDs include migration ID (T001-XXX)
+- Each clarify = new migration folder
+- Auto-split files > 400 lines
+
+## Flow Summary
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  User runs /sedd.clarify                                    │
+│  → AI creates migration folder                              │
+│  → AI shows available commands                              │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  DISCUSSION LOOP                                            │
+│                                                             │
+│  User explains → AI records in clarify.md + decisions.md    │
+│       ↓                                                     │
+│  "continue" → AI: "Ok, continue..."                         │
+│  "pergunta" → AI asks ONE question                          │
+│  "tasks"    → Exit loop, generate tasks                     │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  User says "tasks" / "done"                                 │
+│  → AI generates tasks.md from all notes + decisions         │
+│  → AI updates _meta.json                                    │
+│  → AI asks about commit                                     │
+│  → AI offers next steps                                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## CLI Alternative
+
+For automated workflows, use the SEDD CLI:
+
+```bash
+# Create new migration (creates clarify.md, tasks.md, decisions.md)
+sedd clarify
+
+# Add tasks to current migration
+sedd tasks '[{"story":"US1","description":"Task description"}]'
+
+# Mark task complete
+sedd complete T001-001
+
+# Check status
+sedd status
+```
+
+Scripts also available in `.sedd/scripts/powershell/` and `.sedd/scripts/bash/`.

package/commands/sedd.dashboard.md

@@ -0,0 +1,145 @@
+# /sedd.dashboard - Interactive TUI Dashboard
+
+## Purpose
+Open an interactive terminal dashboard to manage specs, migrations, and tasks with keyboard navigation.
+
+## Trigger
+- `/sedd.dashboard` or `sedd dashboard` - Open full dashboard
+- `/sedd.dashboard -m 001` - Focus on specific migration
+
+## Features
+
+### Visual Layout
+
+```
++------------------------------------------------------------------+
+| SEDD Dashboard | Branch: 024-feature-name | Migration: 001       |
++---------------------+--------------------------------------------+
+| MIGRATIONS          | TASKS (3/5 completed)                      |
+| -----------------   | ------------------------------------------ |
+| > 001 [in-progress] | [x] T001-001 Create ThemeContext           |
+|   002 [pending]     | [x] T001-002 Update database schema        |
+|   003 [pending]     | [ ] T001-003 Create toggle component <     |
+|                     | [ ] T001-004 Add to settings page          |
+|                     | [ ] T001-005 API endpoint                  |
++---------------------+--------------------------------------------+
+| PREVIEW: clarify.md                                              |
+| ---------------------------------------------------------------- |
+| ## Expected Outcome                                              |
+| > User can toggle dark mode and have it persist                  |
+|                                                                  |
+| ## Questions & Answers                                           |
+| ### Q1: Where to store preference?                               |
+| **Answer:** In user account database...                          |
++------------------------------------------------------------------+
+| [==================  ] 60% (3/5 tasks)     [?] Help | [q] Quit   |
++------------------------------------------------------------------+
+```
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `j/k` or `arrows` | Navigate up/down |
+| `Tab` | Switch panel (migrations → tasks → preview) |
+| `Enter` | Select migration / Focus task |
+| `Space` | Toggle task completion |
+| `e` | Edit selected file in $EDITOR |
+| `r` | Refresh data |
+| `1-4` | Switch preview file (1=spec, 2=clarify, 3=tasks, 4=decisions) |
+| `?` | Toggle help overlay |
+| `q` | Quit dashboard |
+
+### Panels
+
+1. **Migrations Panel** - Left sidebar showing all migrations
+   - Status indicators: `>` in-progress, `*` completed, ` ` pending
+   - Navigate and select to filter tasks
+
+2. **Tasks Panel** - Center area showing tasks
+   - Filtered by selected migration
+   - Toggle completion with Space
+   - Progress counter
+
+3. **Preview Panel** - Right area showing file content
+   - Markdown syntax highlighting
+   - Switch between spec.md, clarify.md, tasks.md, decisions.md
+
+### Status Bar
+
+Shows overall progress with:
+- Progress bar visualization
+- Percentage complete
+- Task count
+- Quick help hints
+
+## CLI Usage
+
+```bash
+# Open dashboard
+sedd dashboard
+
+# Short alias
+sedd d
+
+# Focus on specific migration
+sedd dashboard -m 001
+sedd d -m 002
+```
+
+## Requirements
+
+- Must be on a feature branch (###-feature-name)
+- Feature must have _meta.json (run /sedd.specify first)
+- Terminal must support ANSI colors
+
+## Dependencies
+
+The dashboard uses:
+- **Ink** - React for CLIs
+- **ink-spinner** - Loading indicators
+- **React** - Component architecture
+
+Install with:
+```bash
+npm install
+```
+
+## File Editing
+
+When pressing `e`, the dashboard:
+1. Pauses rendering
+2. Opens file in `$EDITOR` (defaults to vim)
+3. After saving and closing, refreshes data
+
+Supported editors:
+- vim/nvim
+- nano
+- code (VS Code)
+- Any editor in $EDITOR env var
+
+## Task Toggle
+
+Pressing `Space` on a task:
+1. Reads tasks.md file
+2. Toggles `[ ]` ↔ `[x]`
+3. Writes back to file
+4. Refreshes display
+
+Changes are persisted immediately to the filesystem.
+
+## Rules
+
+- Dashboard is READ-ONLY for code files
+- Only modifies task checkboxes in tasks.md
+- Never executes code
+- Safe to use during implementation
+
+## Error States
+
+| Error | Solution |
+|-------|----------|
+| "Not on a feature branch" | Checkout a feature branch (###-name) |
+| "Feature directory not found" | Run /sedd.specify first |
+| "_meta.json not found" | Initialize feature with /sedd.specify |
+| "TUI dependencies not installed" | Run `npm install` in packages/sedd |