From 231bb543e2c3aee7a32559a511f137caa25afacf Mon Sep 17 00:00:00 2001 From: Hector Ros Date: Tue, 20 Jan 2026 01:20:32 +0100 Subject: [PATCH] Add FASE 5: Smart Specification Engine (BrainGrid-style) Inspired by https://www.braingrid.ai/ - Adding intelligent specification generation layer to achieve 5-star rating in all categories: New FASE 5 includes: - Spec generation with Claude API (goals, architecture, edge cases) - Smart clarification questions (Q&A system) - Automatic task decomposition with dependencies - Context management and codebase indexing - Schema extensions for specifications - Frontend integration with wizard UI - New API endpoints for spec workflow Goal: From vague idea to production - AI plans, codes, and deploys Comparison with competition: - BrainGrid: Planning only (no execution/deploy) - Cursor/Windsurf: Coding only (no planning/deploy) - Vercel v0: Good at all, but not self-hosted - AiWorker: Will be 5 stars in everything (Planning + Code + Deploy + Infra) MVP (Phases 1-4) remains priority, FASE 5 comes after. Co-Authored-By: Claude Sonnet 4.5 (1M context) --- ROADMAP.md | 285 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 275 insertions(+), 10 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index dd8b34d..0ecab0b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -274,6 +274,244 @@ kubectl get pods -n control-plane --- +### FASE 5: Smart Specification Engine (BrainGrid-style) 🧠 + +**InspiraciΓ³n**: https://www.braingrid.ai/ +**Objetivo**: GeneraciΓ³n inteligente de especificaciones antes del coding + +#### 5.1 Spec Generation con Claude API +**Objetivo**: Convertir ideas vagas en especificaciones detalladas +**Tareas**: +- [ ] Integrar Claude API para generation +- [ ] Prompt engineering para specs estructuradas +- [ ] Templates para diferentes tipos de features +- [ ] Output: Goals, Context, Architecture, Edge Cases, Acceptance Criteria + +**Ejemplo flow**: +```typescript +User: "Add user authentication" +↓ +Claude API generates: +{ + goals: ["Secure login", "Session management", "Password reset"], + context: "Current app has no auth, needs to protect /dashboard routes", + architecture: "JWT-based with refresh tokens, bcrypt for passwords", + edgeCases: [ + "Concurrent logins from multiple devices", + "Token expiration during active session", + "Password reset with expired token" + ], + acceptanceCriteria: [ + "User can register with email/password", + "Login returns valid JWT token", + "Protected routes return 401 without token", + "Password reset flow works end-to-end" + ] +} +``` + +#### 5.2 Smart Clarification Questions +**Objetivo**: AI hace preguntas inteligentes para descubrir edge cases +**Tareas**: +- [ ] Sistema de Q&A conversacional +- [ ] Detectar ambigΓΌedades en task description +- [ ] Generar preguntas relevantes por tipo de feature +- [ ] Guardar respuestas para context enrichment + +**Ejemplo**: +```typescript +Task: "Add payment processing" +↓ +AI Questions: +1. "Which payment providers? (Stripe, PayPal, both?)" +2. "Subscription or one-time payments?" +3. "Currency support? (USD only or multi-currency?)" +4. "Refund/chargeback handling required?" +5. "PCI compliance needed or using hosted checkout?" +↓ +User answers +↓ +Enhanced specification generated +``` + +#### 5.3 Automatic Task Decomposition +**Objetivo**: Dividir features grandes en subtasks atΓ³micas +**Tareas**: +- [ ] Algoritmo para detectar complejidad +- [ ] HeurΓ­sticas para dividir en subtasks +- [ ] Dependencias entre subtasks +- [ ] EstimaciΓ³n automΓ‘tica de effort + +**Ejemplo**: +```typescript +Feature: "User authentication system" +↓ +Decomposed into: +[ + { + id: 1, + title: "Setup database schema for users", + dependencies: [], + estimatedTime: "30min" + }, + { + id: 2, + title: "Implement password hashing with bcrypt", + dependencies: [1], + estimatedTime: "45min" + }, + { + id: 3, + title: "Create JWT token generation/validation", + dependencies: [1], + estimatedTime: "1h" + }, + { + id: 4, + title: "Build registration endpoint", + dependencies: [1, 2, 3], + estimatedTime: "1h" + }, + ... +] +``` + +#### 5.4 Context Management +**Objetivo**: Mantener contexto de proyecto para mejores specs +**Tareas**: +- [ ] Indexar codebase existente +- [ ] Detectar patrones de arquitectura +- [ ] Identificar tecnologΓ­as usadas +- [ ] Generar spec consistente con codebase + +**Features**: +- VectorizaciΓ³n de cΓ³digo con embeddings +- BΓΊsqueda semΓ‘ntica de componentes similares +- DetecciΓ³n automΓ‘tica de breaking changes +- Sugerencias de refactoring cuando aplique + +#### 5.5 Schema Extensions +**Objetivo**: Extender DB schema para soportar specs +**Tareas**: +- [ ] Agregar campos a tabla `tasks` +- [ ] Nueva tabla `task_specifications` +- [ ] Nueva tabla `clarification_questions` +- [ ] Nueva tabla `subtasks` con dependencias + +**Schema**: +```typescript +// Extender tasks table +tasks { + ...existing fields + hasSpecification: boolean + specificationId: varchar(36) + needsClarification: boolean + isDecomposed: boolean +} + +// Nueva tabla +task_specifications { + id: varchar(36) + taskId: varchar(36) + goals: json + context: text + architecture: text + edgeCases: json + acceptanceCriteria: json + estimatedComplexity: enum('low','medium','high','very_high') + generatedAt: timestamp + approvedByUser: boolean +} + +clarification_questions { + id: varchar(36) + taskId: varchar(36) + question: text + answer: text + askedAt: timestamp + answeredAt: timestamp +} + +subtasks { + id: varchar(36) + parentTaskId: varchar(36) + title: varchar(255) + description: text + dependencies: json // Array of subtask IDs + estimatedTime: varchar(20) + order: int + status: enum('pending','in_progress','completed') +} +``` + +#### 5.6 Frontend Integration +**Objetivo**: UI para spec generation y Q&A +**Tareas**: +- [ ] Modal de "Generate Specification" +- [ ] Chat interface para clarification questions +- [ ] Vista de specification preview +- [ ] Editor de specs generados (allow edits) +- [ ] VisualizaciΓ³n de subtasks tree con dependencias + +**Components**: +```typescript + + ↓ + Step 1: Initial task description + Step 2: AI clarification questions (chat UI) + Step 3: Generated spec preview + Step 4: Task decomposition view (tree) + Step 5: Approve & queue for agents +``` + +#### 5.7 API Endpoints +**Objetivo**: Endpoints para spec generation +**Tareas**: +```typescript +POST /api/tasks/:id/generate-spec + β†’ Trigger Claude API to generate specification + +POST /api/tasks/:id/ask-questions + β†’ Generate clarification questions + +POST /api/tasks/:id/answer-question + β†’ Submit answer to question, regenerate spec if needed + +POST /api/tasks/:id/decompose + β†’ Break task into subtasks with dependencies + +PATCH /api/tasks/:id/specification + β†’ Update/edit generated specification + +GET /api/tasks/:id/specification + β†’ Get current specification details +``` + +--- + +## πŸ“Š ROADMAP VISUAL - Estado de Features + +### ComparaciΓ³n con Competencia + +| Feature | BrainGrid | Cursor | Vercel v0 | **AiWorker MVP** | **AiWorker + Phase 5** | +|---------|-----------|--------|-----------|------------------|------------------------| +| **Smart Planning** | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | +| **AI Coding** | ❌ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | +| **Deploy Automation** | ❌ | ❌ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | +| **Infrastructure** | ❌ | ❌ | ⭐⭐⭐ (Vercel) | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | +| **Preview Envs** | ❌ | ❌ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | +| **GitOps** | ❌ | ❌ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | + +### Value Proposition por Fase + +**Fase 1-4 (MVP)**: +> "From task to production - fully automated pipeline with HA infrastructure" + +**Fase 5 (+ Smart Specs)**: +> "From vague idea to production - AI plans, codes, and deploys your features end-to-end" + +--- + ## πŸ“š DOCUMENTACIΓ“N EXISTENTE ### Arquitectura @@ -435,15 +673,19 @@ kubectl logs -n gitea-actions deployment/gitea-runner -c runner ## πŸ“Š PROGRESO GENERAL ``` -Infraestructura: β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ 100% -Backend: β–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 20% -Frontend: β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 0% -Agentes: β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 0% -GitOps/Deploy: β–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 10% -────────────────────────────────────────── -Total: β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 26% +FASE 1 - Backend: β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ 100% βœ… +FASE 2 - Frontend: β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 0% +FASE 3 - Agentes: β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 0% +FASE 4 - GitOps/Deploy: β–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 10% +FASE 5 - Smart Specs: β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 0% +────────────────────────────────────────────────── +Total MVP (Fases 1-4): β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 28% +Total con AI Planning: β–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ 22% ``` +**Última sesiΓ³n completada**: 2026-01-19 (Backend API + MCP Server) +**PrΓ³xima sesiΓ³n**: Frontend Dashboard + Primer Agente + --- ## πŸš€ QUICK START para PrΓ³xima SesiΓ³n @@ -517,15 +759,38 @@ open https://git.fuq.tv/admin/aiworker-backend/actions ## 🎯 OBJETIVO FINAL -Sistema completo de orquestaciΓ³n de agentes IA que automatiza: +Sistema completo de orquestaciΓ³n de agentes IA que automatiza **de idea a producciΓ³n**: + +### MVP (Fases 1-4) 1. Usuario crea tarea en Dashboard 2. Agente Claude Code toma tarea vΓ­a MCP 3. Agente trabaja: cΓ³digo, commits, PR 4. Deploy automΓ‘tico en preview environment 5. Usuario aprueba β†’ Staging β†’ Production -**Todo automΓ‘tico, todo con HA, todo monitoreado.** +### Full Vision (+ Fase 5) +1. Usuario describe idea vaga: *"Add payments"* +2. **AI hace preguntas inteligentes**: *"Stripe or PayPal? Subscriptions?"* +3. **AI genera spec completa**: Goals, Architecture, Edge Cases, Tests +4. **AI descompone en subtasks** atΓ³micas con dependencias +5. Agente Claude Code ejecuta cada subtask automΓ‘ticamente +6. Deploy automΓ‘tico en preview environment +7. Usuario aprueba β†’ Staging β†’ Production + +**Todo automΓ‘tico, todo con HA, todo monitoreado, todo inteligente.** --- -**πŸ’ͺ Β‘Hemos construido bases sΓ³lidas! El siguiente paso mΓ‘s lΓ³gico es completar el Backend para tener la API funcional.** +## πŸš€ NEXT STEPS + +**Ahora mismo**: Completado FASE 1 (Backend API + MCP Server) βœ… + +**Siguiente sesiΓ³n**: FASE 2 + 3 (Frontend Dashboard + Primer Agente) + +**DespuΓ©s**: FASE 4 (GitOps + Preview Environments) + +**Futuro**: FASE 5 (Smart Specification Engine - BrainGrid style) + +--- + +**πŸ’ͺ Β‘Bases sΓ³lidas construidas! Rumbo al MVP completo, y despuΓ©s... Β‘5 estrellas en todo! ⭐⭐⭐⭐⭐**