AURUM — Orquestación de la construcción con agentes

Cómo se construye el juego de punta a punta usando Claude Code con orquestación multi-agente. Este documento es la guía operativa: Pablo dirige, los agentes construyen, y cada fase tiene compuertas (gates) que impiden avanzar sin prueba de que funciona. Escrito para ser usado con cualquier modelo de la familia Claude (Opus 5 incluido): la fuente de verdad son estos documentos, no la memoria de una sesión.

#Principios (innegociables)

1. El plan manda: docs/plan/ es la fuente de verdad. Todo agente que construye algo primero lee la sección relevante. Si la realidad contradice al plan, se actualiza el plan (con nota), nunca se ignora.
2. Nada está "hecho" sin prueba: cada entregable se demuestra jugando en navegador real (screenshots/video), con tests en verde y con sus métricas. La palabra del agente no alcanza.
3. Una fase por vez: no se abre la fase N+1 sin cerrar los gates de la fase N. Dentro de una fase sí hay paralelismo masivo.
4. Cadena estándar por fase: spec de fase → workflow(s) ultracode (el ancho) → /loop de cierre (el largo) → /code-review → gates → actualizar memoria + changelog → deploy dev.
5. Versión visible: el juego muestra su versión (v0.1, v0.2…) y sube con cada deploy — el progreso se VE.
6. Verificación adversarial: los workflows de construcción siempre terminan con agentes verificadores que intentan romper/refutar lo construido antes de integrarlo.
7. Los docs viajan, el contexto no: cada sesión nueva arranca leyendo memoria + los docs de su fase. Nunca dependemos de que "la sesión anterior se acuerde".

#Estructura del repositorio (monorepo aurum/)

aurum/
├── client/            # TypeScript + Three.js + Vite (PWA)
│   ├── src/{render,net,sim,ui,audio,i18n,input}/
│   └── e2e/           # Playwright con fixtures determinísticos
├── server/            # Rust workspace
│   ├── crates/sim-core/     # reglas puras, corre headless (simulador de balance)
│   ├── crates/net/          # WebSocket, protocolo, AOI, reconexión
│   ├── crates/persist/      # Postgres, ledger, migraciones
│   ├── crates/ao-datos/     # parser .csm/.dat del AO (el conversor)
│   └── crates/admin/        # panel GM, métricas, moderación
├── protocol/          # esquema de paquetes → codegen TS + Rust (una sola verdad)
├── assets/            # glTF optimizados + pipeline (gltf-transform, meshopt, KTX2)
├── i18n/              # catálogos ES/EN/RU + glosario + pipeline de traducción
├── infra/             # CI, deploy, observabilidad, bots de carga
└── docs/              # este plan + specs por fase + decisiones

#Gates globales (CI, corren siempre)

#Las fases y el prompt literal para arrancar cada una

Cómo usarlas con Opus 5: abrís sesión en aurum/ (o argentum-web/ hasta el rename), elegís el modelo en la app, pegás el prompt de la fase. La palabra ultracode activa la orquestación a escala; al final de cada prompt está el /loop para dejar al agente cerrando solo. Los workflows heredan el modelo de la sesión.

#F0 — Investigación, plan y demo técnica ✅ HECHA

Research (8 agentes), plan maestro (8 agentes), demo jugable real en Three.js publicada.

#F1 — Fundaciones

Entrega: monorepo armado; cliente con escena isométrica, cámara 90°-imán, input (click/WASD/Ctrl/Shift-sprint); server Rust con WebSocket, tick y eco de movimiento; protocol/ v0 con codegen doble; CI completa; deploy dev con link. Gate: dos pestañas caminando y viéndose mutuamente en el link dev; CI verde. Prompt:

ultracode — Fase 1 de AURUM (Fundaciones). Leé la memoria del proyecto y docs/plan/04, 05 y 08.
Armá el monorepo completo según 08, con workflow multi-agente: un equipo por módulo
(client-escena, client-input, server-net, server-tick, protocol-codegen, CI/deploy) +
verificadores. Gate: dos pestañas caminando juntas en el deploy dev, CI verde.
Verificá jugando con Playwright y mostrame screenshots. No avances a F2.

Cierre: /loop corré los gates de F1 y arreglá lo que falle hasta que todo pase → /code-review.

#F2 — Netcode multijugador serio

Entrega: movimiento autoritativo con predicción/reconciliación; interpolación de entidades; interés por áreas; reconexión con gracia (feature sagrada); 100 bots de carga; métricas de latencia. Gate: 100 bots + 2 humanos fluido con 80-120 ms simulados; cortar el WiFi 10 s NO mata al personaje. Prompt: análogo a F1 citando docs/plan/05 §netcode + adenda de reconexión.

#F3 — El mundo real (conversor AO)

Entrega: crate ao-datos parseando los .csm/.dat (formato en research/01); mapeo GrhIndex→assets v1; la región de 3 ciudades (Ullathorpe, Nix, Banderbill) navegable con NPCs estáticos, triggers, agua, techos que se desvanecen, música original por zona. Gate: caminar de Ullathorpe a Nix por el mapa convertido REAL, con el soundtrack sonando. Nota de orquestación: acá brilla el patrón por lotes — un workflow con agentes por grupo de mapas + verificadores visuales (screenshot de cada zona vs checklist).

#F4 — Combate y "feel" ⚠️ EL GATE MÁS IMPORTANTE

Entrega: melee/rango/hechizos base con los intervalos exactos del AO; sprint con cansancio; estados (parálisis, invi…); muerte/drop con las 3 mitigaciones; IA hostil (aggro/leash); daño flotante; el agite completo. Gate doble: (a) sim-core reproduce los números del AO en tests; (b) sesión de validación con ≥5 veteranos del AO — si dicen "no se siente como AO", se itera acá hasta que sí. El riesgo nº1 del proyecto se mata en esta fase.

#F5 — Progresión y economía

Clases/razas/skills/leveo; inventario TRANSACCIONAL; comercio NPC; banco; crafteo v1; ledger de doble entrada anti-dupe. Gate: bots economía 48 h sin crear/destruir oro de la nada (el ledger cierra en 0).

#F6 — Social

Chat con canales por idioma; clanes con elecciones; parties con bonus; comercio seguro; mercado. Gate: guerra de clanes de prueba con 20 bots + humanos.

#F7 — Retención y gobernanza

Kit diario/semanal completo (racha, criatura del día, ventanas, tareas); arena + torneo automático; temporada base; polls in-game; killboard. Gate: los ganchos disparan y se miden (telemetría activa).

#F8 — Contenido e idiomas

Quests artesanales del lanzamiento; bestiario completo por zona (≥6 especies); EN/RU generado+revisado con glosario; QA lingüístico con screenshots automáticos por idioma. Gate: jugar 1 h entera en RU sin encontrar español.

#F9 — Pulido, ops y beta

VFX/audio final, onboarding interactivo, perf móvil, panel web de cuenta, observabilidad completa, status page con contador real, seguridad, backups probados. Gate: beta cerrada con veteranos (reclutados de los Discords mapeados en research/05) + su encuesta.

#F10 — Lanzamiento

Apertura-evento con cuenta regresiva, prensa/streamers del nicho, marketing trilingüe. Luego: TWA Android, cadencia de temporadas.

#Patrones de workflow por tipo de trabajo

• Lotes de contenido (293 hechizos, quests, bestiario, mapas): pipeline(lotes, construir → verificar-adversarial → integrar) — cada ítem verificado apenas sale, sin barrera.
• Sistemas críticos (netcode, ledger, combate): panel de 3 enfoques independientes → jueces → se implementa el ganador con lo mejor de los otros.
• Caza de bugs pre-gate: loop-until-dry — tandas de agentes buscadores hasta que 2 tandas seguidas no encuentren nada nuevo.
• Paralelismo con archivos compartidos: worktrees de git por agente cuando dos equipos tocan lo mismo.

#Qué hace Pablo en cada fase

#Registro de decisiones de sesión a sesión

Al cerrar cada fase se actualizan: docs/plan/ (si cambió algo), la memoria persistente del proyecto, el CHANGELOG.md y la versión visible del juego. Cualquier sesión futura (con cualquier modelo) retoma leyendo eso — cero dependencia del contexto anterior.