aiworker/ROADMAP.md

🗺️ AiWorker - Roadmap y Próximos Pasos

Última actualización: 2026-01-19 Estado actual: Infraestructura completa, Backend iniciado

---

✅ COMPLETADO (Sesión 1 - 2026-01-19)

1. Infraestructura Kubernetes HA

• Cluster K3s desplegado en CubePath (Houston)
• 3 Control Planes + 3 Workers + 2 Load Balancers
• Red privada 10.100.0.0/24
• Longhorn storage HA (3 réplicas)
• Nginx Ingress + Cert-Manager (TLS automático)
• DNS configurado (*.fuq.tv)

Docs: K8S-CLUSTER.md, docs/04-kubernetes/

2. Bases de Datos y Servicios

• MariaDB 11.4 LTS con storage HA
• Redis 7 desplegado
• Gitea 1.25.3 con Container Registry habilitado
• ArgoCD instalado (configuración pendiente - Fase 4)

Credenciales: CLUSTER-CREDENTIALS.md Acceso Gitea: https://git.fuq.tv (admin/admin123)

3. Backend Inicial

• Estructura del proyecto creada
• Bun 1.3.6 configurado
• Database schema (projects, agents, tasks) con Drizzle
• Dockerfile multi-stage
• Gitea Actions Runner configurado
• Workflow CI/CD básico

Repo: https://git.fuq.tv/admin/aiworker-backend

---

🎯 PRÓXIMOS PASOS

FASE 1: Completar Backend

1.1 Verificar y corregir CI/CD

Objetivo: Build automático funcionando Tareas:

• Verificar build en https://git.fuq.tv/admin/aiworker-backend/actions
• Corregir errores si los hay
• Confirmar imagen en registry: git.fuq.tv/admin/aiworker-backend:latest

Comandos útiles:

# Ver runner logs
kubectl logs -n gitea-actions deployment/gitea-runner -c runner --tail=50

# Ver packages en Gitea
https://git.fuq.tv/admin/-/packages

1.2 Implementar API Routes con Bun.serve()

Objetivo: Endpoints REST funcionales Tareas:

• Crear /api/projects (CRUD)
• Crear /api/tasks (CRUD)
• Crear /api/agents (list, status)
• Implementar validación con Zod
• Health check mejorado con DB/Redis status

Referencia: docs/02-backend/api-endpoints.md

Estructura:

src/api/
├── routes/
│   ├── projects.ts
│   ├── tasks.ts
│   └── agents.ts
└── middleware/
    ├── auth.ts
    └── validate.ts

1.3 Implementar MCP Server

Objetivo: Herramientas para agentes Claude Code Tareas:

• Instalar @modelcontextprotocol/sdk
• Crear MCP server en puerto 3100
• Implementar tools: get_next_task, update_task_status, etc.
• Conectar con Gitea API
• Conectar con Kubernetes API

Referencia: docs/02-backend/mcp-server.md, docs/05-agents/mcp-tools.md

Archivo: src/services/mcp/server.ts

1.4 Integración con Gitea

Objetivo: Gestión de repos y PRs Tareas:

• Cliente API de Gitea
• Webhooks handler
• Operaciones: create repo, create PR, merge, etc.

Referencia: docs/02-backend/gitea-integration.md

Token Gitea: 159a5de2a16d15f33e388b55b1276e431dbca3f3 (full access)

1.5 Integración con Kubernetes

Objetivo: Crear/gestionar deployments y namespaces Tareas:

• Cliente K8s usando @kubernetes/client-node
• Crear namespaces dinámicos
• Crear deployments de preview
• Crear ingress automáticos
• Gestionar pods de agentes

Referencia: docs/04-kubernetes/deployments.md

Kubeconfig: ~/.kube/aiworker-config

1.6 Sistema de Colas (BullMQ)

Objetivo: Jobs asíncronos para deployments Tareas:

• Setup BullMQ con Redis
• Queue para tasks
• Queue para deployments
• Workers para procesar jobs

Referencia: docs/02-backend/queue-system.md

1.7 WebSocket Real-time

Objetivo: Notificaciones en tiempo real Tareas:

• WebSocket server con Bun.serve()
• Eventos: task:created, task:status_changed, etc.
• Autenticación de conexiones

Referencia: docs/01-arquitectura/flujo-de-datos.md

1.8 Deploy Backend en K8s

Objetivo: Backend corriendo en producción Tareas:

• Crear manifests K8s (deployment, service, ingress)
• Configurar secrets (DB, Gitea, etc.)
• Deploy en namespace control-plane
• Verificar en api.fuq.tv

Comandos:

kubectl apply -f k8s/backend/
kubectl get pods -n control-plane

---

FASE 2: Frontend React 19.2

2.1 Inicializar Proyecto

Objetivo: Setup base de React Tareas:

• Crear proyecto con Vite + React 19.2
• Instalar TailwindCSS 4
• Configurar TypeScript
• Estructura de carpetas

Stack:

• React 19.2.0
• Vite 6.x
• TailwindCSS 4.x
• Bun como package manager

Auth: Lucia Auth (https://github.com/lucia-auth/lucia) Skills: Vercel Agent Skills (https://github.com/vercel-labs/agent-skills)

2.2 Componentes Base

Objetivo: UI components library Tareas:

• Layout (Header, Sidebar)
• Componentes UI (Button, Card, Modal, etc.)
• TailwindCSS config con tema

Referencia: docs/03-frontend/componentes.md

2.3 Kanban Board

Objetivo: Gestión visual de tareas Tareas:

• Implementar con @dnd-kit
• Columnas por estado (backlog, in_progress, etc.)
• Drag & drop funcional
• Filtros y búsqueda

Referencia: docs/03-frontend/kanban.md

2.4 Consolas Web

Objetivo: Terminales para agentes Tareas:

• Implementar con xterm.js
• WebSocket a pods de agentes
• Tabs manager

Referencia: docs/03-frontend/consolas-web.md

2.5 Deploy Frontend

Objetivo: Frontend en producción Tareas:

• Build para producción
• Dockerfile con nginx
• Deploy en app.fuq.tv

---

FASE 3: Agentes Claude Code

3.1 Docker Image del Agente

Objetivo: Imagen base para agentes Tareas:

• Dockerfile con Claude Code CLI
• Git config
• SSH keys setup
• Script de trabajo (agent-loop.sh)

Referencia: docs/05-agents/claude-code-pods.md

3.2 Gestión de Agentes desde Backend

Objetivo: Crear/eliminar pods de agentes Tareas:

• API endpoint /agents (create, delete, list)
• Auto-scaling basado en tareas pendientes
• Healthcheck de agentes

Referencia: docs/05-agents/ciclo-vida.md

3.3 Comunicación MCP

Objetivo: Agentes conectados al backend Tareas:

• MCP client en agentes
• Herramientas implementadas (get_next_task, etc.)
• Heartbeat system

Referencia: docs/05-agents/comunicacion.md

---

FASE 4: GitOps y Deployments

4.1 ArgoCD Setup

Objetivo: GitOps funcional Tareas:

• Conectar repos de Gitea a ArgoCD
• Crear Applications
• Auto-sync configurado

Referencia: docs/06-deployment/gitops.md URL: https://argocd.fuq.tv (admin/LyPF4Hy0wvp52IoU)

4.2 Preview Environments

Objetivo: Deploy automático por tarea Tareas:

• Lógica para crear namespace temporal
• Deploy app en task-{id}.r.fuq.tv
• Cleanup automático (TTL)

Referencia: docs/06-deployment/preview-envs.md

4.3 Staging y Production

Objetivo: Pipeline completo Tareas:

• Merge a staging branch
• Deploy staging automático
• Aprobación manual para production
• Rollback capability

Referencia: docs/06-deployment/staging-production.md

---

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:

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:

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:

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:

// 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:

<SpecificationWizard taskId={taskId} />
  ↓
  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:

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

• docs/01-arquitectura/overview.md - Visión general
• docs/01-arquitectura/stack-tecnologico.md - Stack completo
• docs/01-arquitectura/flujo-de-datos.md - Diagramas de flujo
• docs/01-arquitectura/modelo-datos.md - Database schema

Backend

• docs/02-backend/estructura.md - Estructura del proyecto
• docs/02-backend/database-schema.md - Drizzle schema
• docs/02-backend/mcp-server.md - MCP implementation
• docs/02-backend/gitea-integration.md - Gitea API client
• docs/02-backend/queue-system.md - BullMQ
• docs/02-backend/api-endpoints.md - REST API specs

Frontend

• docs/03-frontend/estructura.md - Estructura
• docs/03-frontend/componentes.md - Componentes principales
• docs/03-frontend/estado.md - React Query + Zustand
• docs/03-frontend/kanban.md - Kanban board
• docs/03-frontend/consolas-web.md - xterm.js

Kubernetes

• docs/04-kubernetes/cluster-setup.md - Setup inicial
• docs/04-kubernetes/namespaces.md - Estructura
• docs/04-kubernetes/deployments.md - Manifests
• docs/04-kubernetes/gitea-deployment.md - Gitea en K8s
• docs/04-kubernetes/networking.md - Ingress y red

Agentes

• docs/05-agents/claude-code-pods.md - Pods de agentes
• docs/05-agents/mcp-tools.md - Herramientas MCP
• docs/05-agents/comunicacion.md - MCP protocol
• docs/05-agents/ciclo-vida.md - Lifecycle

Deployment

• docs/06-deployment/ci-cd.md - Pipelines
• docs/06-deployment/gitops.md - ArgoCD
• docs/06-deployment/preview-envs.md - Previews
• docs/06-deployment/staging-production.md - Promoción

Cluster

• K8S-CLUSTER.md - Estado del cluster
• CLUSTER-CREDENTIALS.md - Credenciales (⚠️ sensible)
• AGENT-GUIDE.md - Guía para agentes IA
• docs/CONTAINER-REGISTRY.md - Uso del registry
• k8s-cluster-info.md - Info técnica

---

🔑 CREDENCIALES RÁPIDAS

Gitea:

• URL: https://git.fuq.tv
• User: admin / admin123
• Token: 159a5de2a16d15f33e388b55b1276e431dbca3f3

Registry:

• URL: git.fuq.tv
• Token: 7401126cfb56ab2aebba17755bdc968c20768c27

ArgoCD:

• URL: https://argocd.fuq.tv
• User: admin / LyPF4Hy0wvp52IoU

Longhorn:

• URL: https://longhorn.fuq.tv
• User: admin / aiworker2026

MariaDB (interno):

• Host: mariadb.control-plane.svc.cluster.local:3306
• DB: aiworker
• User: aiworker / AiWorker2026_UserPass!

Kubeconfig:

export KUBECONFIG=~/.kube/aiworker-config

---

⚡ COMANDOS ÚTILES

Cluster

# Ver nodos
kubectl get nodes -o wide

# Ver todos los pods
kubectl get pods -A

# Namespaces
kubectl get ns

Backend

cd backend
bun run dev           # Desarrollo local
bun run db:generate   # Generar migraciones

Gitea

# Ver Actions
https://git.fuq.tv/admin/aiworker-backend/actions

# Ver packages/imágenes
https://git.fuq.tv/admin/-/packages

Logs

# MariaDB
kubectl logs -n control-plane mariadb-0

# Redis
kubectl logs -n control-plane deployment/redis

# Gitea
kubectl logs -n gitea gitea-0

# Runner
kubectl logs -n gitea-actions deployment/gitea-runner -c runner

---

🎯 PRÓXIMA SESIÓN - Plan Sugerido

Opción A: Completar Backend (Recomendado)

1. Verificar CI/CD funcional
2. Implementar API routes básicas
3. Implementar MCP Server básico
4. Deploy backend en K8s
5. Probar end-to-end

Tiempo estimado: 2-3 horas

Opción B: Frontend Paralelo

1. Inicializar React 19.2 + Vite
2. Setup TailwindCSS
3. Componentes básicos UI
4. Kanban board inicial

Tiempo estimado: 2-3 horas

Opción C: Agentes Primero

1. Crear imagen Docker de agente
2. Deploy agente de prueba
3. Conectar con MCP
4. Primera tarea automática

Tiempo estimado: 3-4 horas

---

📊 PROGRESO GENERAL

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

# 1. Verificar cluster
export KUBECONFIG=~/.kube/aiworker-config
kubectl get nodes

# 2. Verificar servicios
kubectl get pods -n control-plane
kubectl get pods -n gitea
kubectl get pods -n gitea-actions

# 3. Acceder a Gitea
open https://git.fuq.tv

# 4. Continuar con backend
cd backend
bun run dev

# 5. Ver Actions
open https://git.fuq.tv/admin/aiworker-backend/actions

---

🎓 APRENDIZAJES DE ESTA SESIÓN

Lo que funcionó bien ✅

• CubeCLI para gestionar VPS
• K3s con instalación manual (control total)
• Longhorn para storage HA
• Gitea como plataforma todo-en-uno
• Bun.serve() nativo (más simple que Express)

Challenges superados 💪

• Configurar red privada en K3s
• TLS automático con Cert-Manager
• Container Registry en Gitea
• Gitea Actions Runner con DinD
• Auto-migrations en la app

Tips para futuras sesiones 💡

• Port-forward solo para testing, nunca para migrations
• Migrations deben ser automáticas en la app
• Usar TCP probes en vez de exec para MariaDB
• DinD necesita privileged + volumen compartido
• Gitea Actions compatible con GitHub Actions

---

📞 REFERENCIAS EXTERNAS

Tecnologías

• Bun: https://bun.sh/docs
• K3s: https://docs.k3s.io
• Drizzle ORM: https://orm.drizzle.team/docs
• Longhorn: https://longhorn.io/docs/
• Gitea: https://docs.gitea.com
• Cert-Manager: https://cert-manager.io/docs/
• Lucia Auth: https://github.com/lucia-auth/lucia
• Vercel Agent Skills: https://github.com/vercel-labs/agent-skills

APIs

• MCP Protocol: @modelcontextprotocol/sdk
• Kubernetes: @kubernetes/client-node
• Gitea API: https://git.fuq.tv/api/swagger

---

🎯 OBJETIVO FINAL

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

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.

---

🚀 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! ⭐⭐⭐⭐⭐