Arquitectura del universo

Identidad

ai-os es el orquestador raíz de todos los proyectos del universo LADDER/Amed. Cada subdirectorio en worlds/ es un mundo autónomo que hereda las convenciones globales definidas en la raíz.

Metodología: Context-First Development (CFD)

CFD es la disciplina de construir el contexto (docs, ADRs, convenciones, memoria de decisiones) antes que el código, para que un agente de IA en CLI tenga siempre la información correcta cargada sin tener que re-explorar el repo desde cero en cada sesión. En este universo se aplica así:

• Cada mundo arranca con docs/, ADRs y CLAUDE.md antes de escribir código — el CLAUDE.md de cada mundo hereda del global vía @../../CLAUDE.md y añade solo el contexto específico de ese mundo.
• Decisiones arquitectónicas de un mundo → docs/adr/NNNN-titulo.md.
• Decisiones reutilizables entre mundos → _shared/memory/decisions.md (ADRs globales, capturados con /learn).
• Antes de empezar un mundo nuevo, se consulta _shared/memory/registry.json — el inventario vivo de todos los mundos, su stack, repo y estado.
• El sidebar “Proyectos” de este sitio existe por la misma razón: README.md + docs/adr/ de cada mundo son ya el contexto que un agente necesita, así que se publican tal cual en vez de re-escribirse a mano.

Más info sobre la metodología: Context-First Development (CFD): ingeniería de contexto para desarrollo asistido por IA en CLI.

Stack por defecto

• Backend: Supabase (RLS, Edge Functions, pgvector, Storage, Realtime) — no todo mundo lo usa; algunos productos (p. ej. ladder-api) tienen backend propio con Hono + Drizzle + PostgreSQL.
• Web: Next.js 15 + TypeScript, o Astro cuando el mundo es principalmente contenido/documentación.
• Mobile: Flutter.

Estructura del universo

ai-os/
├── CLAUDE.md                   Constitución global
├── _shared/
│   ├── agents/                 Catálogo fuente único de subagentes
│   ├── commands/                27 slash commands compartidos
│   ├── mcp/                    Grupos de MCP por stack (web, backend...)
│   ├── scripts/                attach-skills, link-world-agents, attach-mcp...
│   ├── token-stack/            Stack de telemetría de tokens compartido
│   ├── memory/                 registry.json + decisions.md (ADRs globales)
│   ├── contracts/              Contratos de API entre mundos front/backend
│   └── templates/              Plantillas para mundos nuevos
├── mcp-orchestrator/           MCP server: expone mundos entre sesiones
└── worlds/
    └── <mundo>/
        ├── CLAUDE.md           Hereda @../../CLAUDE.md + contexto propio
        ├── TASKS.md            Kanban (backlog/doing/review/done)
        ├── COWORK.md           Briefing para Claude Cowork Desktop
        ├── .mcp.json            Servidores propios + grupo(s) fusionados
        ├── docs/
        │   ├── adr/            Decisiones arquitectónicas locales
        │   └── design-system.md  Tokens para Claude Design
        └── ...                 código específico del mundo

Instalación inicial (al clonar el repo)

1. Clonar con symlinks reales — el repo trackea symlinks (.claude/agents/, .claude/commands/), Git para Windows solo los materializa si core.symlinks está en true al clonar:

   git config --global core.symlinks true
   git clone --recurse-submodules https://github.com/Ledder-Dev/ai-os.git

   Requiere además Developer Mode de Windows activado (o terminal como administrador). Si ya clonaste antes de saber esto, corre _shared/scripts/materialize-symlinks.ps1 en vez de re-clonar.
2. Stack de telemetría de tokens → _shared/token-stack/SETUP.md.
3. Variable de sistema AI_OS_ROOT apuntando a la raíz del repo — la usan todos los scripts .ps1 de _shared/scripts/ para resolver rutas sin depender del cwd.
4. Secretos MCP — copiar .env.example a .env en la raíz y rellenar GITHUB_PAT, VIKUNJA_URL, VIKUNJA_API_TOKEN como variables de usuario de Windows (setx), nunca literales en .mcp.json.
5. Enlazar agentes y comandos del universo:

   .\_shared\scripts\link-universe-agents.ps1
   .\_shared\scripts\link-universe-commands.ps1

Comandos principales

Comando	Qué hace
/new-world*	Crea un mundo nuevo (scaffold + TASKS + COWORK + design-system + registry), una variante por stack (-react, -astro, -shipfree, -vanilla, -supabase, -import…)
/sync-context	Actualiza registry.json desde el estado real
/cross-search	Busca cómo se resolvió un problema similar en otro mundo
/learn	Captura un patrón reutilizable como ADR global
/link-contract	Registra el contrato de API del mundo backend con sus fronts
/tasks	Lee/edita TASKS.md desde el chat
/standup	Estado diario: git + tareas + tokens + cowork
/session-start / /session-end	Abre/cierra sesión de trabajo con contexto completo
/cowork-brief	Genera/actualiza COWORK.md
/design-handoff	Integra bundle de Claude Design con ADR y tarea
/semgrep-scan, /sonar-audit	Seguridad y calidad de código
/site-check, /web-check, /audit-clients	Análisis de sitios de clientes

Catálogo completo y detalle de cada uno en el README.md de la raíz del repo.

Multi-usuario: cómo funcionan los worlds

ai-os es solo el orquestador. Los mundos NO viven en este repo — cada uno es su propio repo git independiente, y worlds/* está en .gitignore por defecto:

• Mundo personal — vive solo en la máquina de quien lo trabaja + su propio repo remoto. El universo no lo referencia.
• Mundo colaborativo (varias personas) — se registra como git submodule en ai-os, con !worlds/<mundo> des-ignorado en .gitignore, para que cualquiera que clone el universo lo traiga con git clone --recurse-submodules.
• Cada mundo registra su repo en _shared/memory/registry.json (null si aún no tiene repo propio).

Telemetría de tokens compartida

Un único stack de observabilidad de coste de tokens sirve a todo el universo, en _shared/token-stack/ (guía completa de instalación y troubleshooting: Token Stack):

• Headroom (:8787) — proxy de prefix-cache: cachea el prefijo repetido de los prompts (system prompt, CLAUDE.md, definiciones de herramientas) para no re-facturarlo en cada request.
• Stats server (:8788) — agrega uso y coste por sesión, leyendo los logs locales hacia ~/.headroom/stats.db.
• CodeBurn — no es un servidor persistente: lee los logs de sesión que ya existen en disco y se levanta on-demand vía npx para visualizar el burn rate de tokens.
• Dashboard (_shared/token-stack/dashboard.html) — vista general con pestañas de overview, sesiones, y catálogo de agentes/skills instalados.

Contratos de API entre mundos

Cuando un par de mundos front/backend comparte contrato, este vive en _shared/contracts/<producto>/api-contract.yaml como symlink al artefacto real del mundo backend (nunca una copia), registrado en _shared/contracts/registry.json.

Cómo se genera este sitio

Este sitio de documentación (universe-docs/) no contiene contenido editado a mano sobre los mundos, las convenciones, el token stack ni el catálogo: npm run sync (script scripts/sync-worlds.mjs) recorre worlds/*/README.md (o CLAUDE.md si no hay README) y worlds/*/docs/adr/*.md (publicado como “Decisiones” dentro de cada mundo), copia _shared/CONVENTIONS.md a Convenciones compartidas y _shared/token-stack/SETUP.md a Token Stack, y genera el catálogo de agentes, comandos y skills leyendo el frontmatter de _shared/agents/, _shared/commands/ y _shared/skills/ — todo con el frontmatter que Starlight necesita. Corre automáticamente antes de dev y build.