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
- [x] Cluster K3s desplegado en CubePath (Houston)
- [x] 3 Control Planes + 3 Workers + 2 Load Balancers
- [x] Red privada 10.100.0.0/24
- [x] Longhorn storage HA (3 réplicas)
- [x] Nginx Ingress + Cert-Manager (TLS automático)
- [x] DNS configurado (*.fuq.tv)

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

### 2. Bases de Datos y Servicios
- [x] MariaDB 11.4 LTS con storage HA
- [x] Redis 7 desplegado
- [x] Gitea 1.25.3 con Container Registry habilitado
- [x] ArgoCD instalado (configuración pendiente - Fase 4)

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

### 3. Backend Inicial
- [x] Estructura del proyecto creada
- [x] Bun 1.3.6 configurado
- [x] Database schema (projects, agents, tasks) con Drizzle
- [x] Dockerfile multi-stage
- [x] Gitea Actions Runner configurado
- [x] 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**:
```bash
# 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**:
```bash
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 🚀

**⚠️ IMPORTANTE**: ArgoCD ya está instalado en el cluster pero NO configurado
**URL**: https://argocd.fuq.tv
**Credenciales**: admin / LyPF4Hy0wvp52IoU

---

#### 4.1 ArgoCD Setup (CRÍTICO - No olvidar)
**Objetivo**: Migrar de kubectl manual a GitOps automático
**Prioridad**: ALTA - Esto desbloquea todo lo demás

**Estado actual (sin ArgoCD)**:
```bash
git push → CI/CD → kubectl apply (MANUAL)
```

**Estado deseado (con ArgoCD)**:
```bash
git push → CI/CD → git push manifests → ArgoCD auto-sync ✨
```

**Tareas**:
- [ ] **Login a ArgoCD UI**: https://argocd.fuq.tv (verificar acceso)
- [ ] **Conectar Gitea repo** al ArgoCD
  - Agregar repo: `https://git.fuq.tv/admin/aiworker.git`
  - Configurar credenciales (usar token de Gitea)
- [ ] **Crear Application para Backend**
  ```bash
  argocd app create backend \
    --repo https://git.fuq.tv/admin/aiworker.git \
    --path k8s/backend \
    --dest-server https://kubernetes.default.svc \
    --dest-namespace control-plane \
    --sync-policy automated
  ```
- [ ] **Crear Application para Frontend**
  ```bash
  argocd app create frontend \
    --repo https://git.fuq.tv/admin/aiworker.git \
    --path k8s/frontend \
    --dest-server https://kubernetes.default.svc \
    --dest-namespace control-plane \
    --sync-policy automated
  ```
- [ ] **Habilitar auto-sync y auto-prune**
  ```bash
  argocd app set backend --sync-policy automated --auto-prune --self-heal
  argocd app set frontend --sync-policy automated --auto-prune --self-heal
  ```
- [ ] **Verificar sincronización inicial**
  - ArgoCD debe detectar manifests en `k8s/backend/` y `k8s/frontend/`
  - Ver en UI que todo esté verde
- [ ] **Test del flujo GitOps**
  - Cambiar algo en k8s/backend/deployment.yaml (ej: replicas: 3)
  - Push a git
  - Verificar que ArgoCD auto-deploya (max 3 min)

**Referencia completa**: `docs/06-deployment/gitops.md`
**CLI ArgoCD**: `argocd` (instalar si no está: `brew install argocd`)

**Beneficios inmediatos**:
- ✅ Rollback con `git revert` (sin kubectl)
- ✅ Audit trail (todo en Git)
- ✅ UI visual del estado real vs deseado
- ✅ Auto-healing si alguien hace kubectl directo

---

#### 4.2 Preview Environments con ArgoCD ApplicationSets
**Objetivo**: Deploy automático e isolado por cada task
**Prerequisito**: ArgoCD configurado (4.1)

**Flujo deseado**:
```
Agent completa task
↓
Crea PR con código
↓
PR merged
↓
Backend crea preview manifest en git
↓
ArgoCD detecta nuevo manifest ← AUTOMÁTICO
↓
Crea namespace preview-task-{id} ← AUTOMÁTICO
↓
Deploy en task-{id}.r.fuq.tv ← AUTOMÁTICO
```

**Tareas**:
- [ ] **Crear ApplicationSet para previews**
  ```yaml
  # argocd/preview-applicationset.yaml
  apiVersion: argoproj.io/v1alpha1
  kind: ApplicationSet
  metadata:
    name: preview-environments
    namespace: argocd
  spec:
    generators:
    - git:
        repoURL: https://git.fuq.tv/admin/aiworker-gitops.git
        directories:
        - path: preview/*
    template:
      metadata:
        name: '{{path.basename}}'
      spec:
        source:
          repoURL: https://git.fuq.tv/admin/aiworker-gitops.git
          path: '{{path}}'
        destination:
          server: https://kubernetes.default.svc
          namespace: '{{path.basename}}'
        syncPolicy:
          automated:
            prune: true
            selfHeal: true
          syncOptions:
          - CreateNamespace=true
  ```
- [ ] **Crear repo separado** para manifests (opcional pero recomendado)
  - `aiworker-gitops` → solo manifests, no código
  - Separar code repo de config repo (GitOps best practice)
- [ ] **Backend API para crear preview**
  ```typescript
  POST /api/tasks/:id/deploy-preview
  → Genera manifests en preview/task-{id}/
  → Commit y push a repo gitops
  → ArgoCD detecta y deploya (automático)
  ```
- [ ] **Ingress dinámico por preview**
  - `task-abc123.r.fuq.tv` → namespace `preview-task-abc123`
  - Wildcard cert con cert-manager
- [ ] **TTL y cleanup automático**
  - Anotación en namespace: `ttl: 7d`
  - CronJob que elimina namespaces expirados
  - ArgoCD auto-prune elimina Application

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

---

#### 4.3 Staging y Production Environments
**Objetivo**: Pipeline completo con aprobaciones
**Prerequisito**: ArgoCD + Preview Environments funcionando

**Pipeline completo**:
```
Development → Preview (automático)
             ↓
Preview → Staging (merge a staging branch, automático)
         ↓
Staging → Production (aprobación manual, ArgoCD sync)
```

**Tareas**:
- [ ] **Crear Application para Staging**
  - Repo/branch: `staging` branch
  - Namespace: `staging`
  - Auto-sync: true
- [ ] **Crear Application para Production**
  - Repo/branch: `production` branch
  - Namespace: `production`
  - Auto-sync: false (requiere aprobación manual)
- [ ] **Workflow de promoción**
  ```bash
  # Preview aprobado
  → Merge PR a main
  → CI/CD build
  → Auto-merge main → staging
  → ArgoCD deploya staging (automático)

  # Staging OK
  → Usuario aprueba en dashboard
  → Merge staging → production
  → Admin hace sync manual en ArgoCD UI
  → Deploy production
  ```
- [ ] **Rollback capability**
  ```bash
  # Opción 1: Git revert
  git revert {bad-commit}
  git push
  ArgoCD auto-sync

  # Opción 2: ArgoCD history
  argocd app rollback production {revision}
  ```
- [ ] **Health checks y smoke tests**
  - Pre-sync hooks en ArgoCD
  - Post-sync validation

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

---

### 📋 CHECKLIST FASE 4 (para no olvidar nada)

Antes de empezar FASE 4, verificar:
- [x] Backend deployado y funcionando
- [x] Frontend deployado y funcionando
- [x] Agentes Claude Code operativos
- [x] CI/CD (Gitea Actions) funcionando
- [ ] **ArgoCD accesible** en https://argocd.fuq.tv ← VERIFICAR PRIMERO

Durante FASE 4, completar en orden:
1. [ ] Login a ArgoCD UI (verificar credenciales)
2. [ ] Conectar repo de Gitea
3. [ ] Crear Applications (backend, frontend)
4. [ ] Habilitar auto-sync
5. [ ] Test: cambiar manifest → push → verificar auto-deploy
6. [ ] Crear ApplicationSet para previews
7. [ ] Test: crear preview manual → verificar auto-deploy
8. [ ] Integrar backend API con preview creation
9. [ ] Configurar staging/production environments
10. [ ] Test flujo completo: task → preview → staging → prod

**Documentación clave para FASE 4**:
- `docs/06-deployment/gitops.md` - Setup completo de ArgoCD
- `docs/06-deployment/preview-envs.md` - ApplicationSets
- `docs/06-deployment/staging-production.md` - Multi-env workflow

---

### 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
<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**:
```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
- `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**:
```bash
export KUBECONFIG=~/.kube/aiworker-config
```

---

## ⚡ COMANDOS ÚTILES

### Cluster
```bash
# Ver nodos
kubectl get nodes -o wide

# Ver todos los pods
kubectl get pods -A

# Namespaces
kubectl get ns
```

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

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

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

### Logs
```bash
# 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

```bash
# 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! ⭐⭐⭐⭐⭐**