Skip to content

README.es.md

Latest commit

 

History

History
207 lines (148 loc) · 9.72 KB

README.es.md

File metadata and controls

207 lines (148 loc) · 9.72 KB
Raw

YapuCli — Context Engineering Framework

🇺🇸 Read in English

YapuCli 🪺

Framework de ingeniería de contexto y memoria estática para agentes de código IA (Antigravity, Claude Code, Codex). Conectado directamente al brain de Antigravity.

Inspirado en el yapú (Psarocolius decumanus), ave venezolana que teje nidos colgantes de más de un metro que desafían la gravedad. Antigravity es el árbol — Yapu teje el nido de memoria. 🪺

🚀 Inicio Rápido (Onboarding en 60 Segundos)

1. Instalación y Fundación

Entra en la carpeta de tu proyecto y ejecuta el inicializador de Yapu:

npx @davidsd/yapu-cli init

Esto creará en tu raíz los archivos esenciales de memoria estática (PROJECT.md, ROADMAP.md, STATE.md) y la carpeta .planning/.

2. Alinear a tu IA

Abre tu chat de IA (Cursor, Cline, Windsurf, etc.) e inícialo con este prompt exacto:

Prompt inicial: "Lee los archivos PROJECT.md, ROADMAP.md y STATE.md para entender las reglas de nuestra aplicación, el plan general y en qué tarea estamos trabajando hoy. ¡Por favor, toma la primera tarea pendiente de STATE.md y desarrollemos el código!"

3. Monitoreo en Tiempo Real

Mientras tu IA escribe y tacha tareas en vivo ([x]), puedes abrir una segunda terminal y correr el monitor interactivo:

npx @davidsd/yapu-cli dash

¡Verás una interfaz TUI ultra-rápida y fluida estilo Matrix actualizándose con tu progreso en tiempo real!

📦 Instalación Tradicional (Opcional)

Si prefieres tener YapuCli disponible de forma global en tu sistema, puedes instalarlo usando:

npm install -g @davidsd/yapu-cli
# o con pnpm
pnpm add -g @davidsd/yapu-cli
# o con yarn
yarn global add @davidsd/yapu-cli

Una vez instalado globalmente, puedes ejecutar cualquier comando directamente usando yapu (por ejemplo, yapu init, yapu dash, etc.).

Zero dependencies — nativo con node:fs y node:path.

🤖 ¿Eres una IA (o usas una)? Carga el Prompt Instalador para LLMs en tu agente para que instale, configure y asimile las reglas de Yapu automáticamente.

💡 ¿Quieres conocer el flujo de trabajo? Lee la Guía de Flujo de Trabajo para Vibe Coders para aprender a integrar Yapu en tu día a día con Cursor/Cline/Windsurf.

🧠 Memoria Dual — La Arquitectura Central

El brain de Antigravity es efímero (por conversación). El directorio .planning/ es persistente (por proyecto, vive en git). Yapu es el puente que sincroniza ambos mundos.

┌─────────────────────────┐       yapu sync        ┌─────────────────────────┐
│   🧠 Antigravity Brain  │ ◄────────────────────► │   🪺 .planning/         │
│   (efímero, por sesión) │       yapu handoff      │   (persistente, en git) │
└────────────┬────────────┘                         └────────────┬────────────┘
             │                                                   │
             │            ┌───────────────────┐                  │
             └───────────►│  Tríada de Memoria │◄────────────────┘
                           │  PROJECT · ROADMAP │
                           │      · STATE       │
                           └───────────────────┘

Sync automático: cada workflow tiene bloques Pre-Sync (lee estado heredado) y Post-Sync (persiste progreso). El LLM nunca pierde el hilo entre sesiones.

📜 La Tríada de Memoria

Archivo Rol Descripción
PROJECT.md 🏛️ La Visión Stack, reglas arquitectónicas y mandamientos intocables.
ROADMAP.md 🗺️ El Plan Macro Fases secuenciales del proyecto. Prohibido saltar de fase.
STATE.md ⚡ Estado Operativo Modo activo, fase actual y tareas técnicas de corta duración.

🛠️ Comandos del CLI (22)

yapu init              # 🪺 Funda la colonia (.planning/ + skills completos)
yapu status            # 📊 Radiografía del proyecto
yapu dash              # 📟 Monitor TUI en tiempo real (Zero-dependency)
yapu board [--port N]  # 🌐 Command Center (C2) web — dashboard interactivo en el navegador
yapu gc                # 🗑️ Recolector de basura contextual (comprime historial)
yapu rescue <log>      # 🚑 Auto-Heal: lee un error de CI/CD y prepara un fix
yapu archive           # 📦 Fin de temporada (congela tareas en HISTORY.md)
yapu install-hooks     # 🐝 Despliega el avispero (Yapu Guard)
yapu sync              # 🔄 Sincroniza brain de Antigravity → .planning/
yapu handoff           # 🤝 Genera handoff para la siguiente sesión
yapu brain <list|log>  # 🔍 Inspecciona el brain de Antigravity
yapu provider          # 🔍 Diagnóstico de proveedores IA detectados

Detalle de Comandos

  • yapu init — Scaffolds .planning/ con 11 subdirectorios + 5 archivos base. Copia 41 workflows, 25 referencias, 3 contextos y 5 plantillas de codebase a .agents/skills/. También copia PROJECT.md, ROADMAP.md y STATE.md a la raíz del proyecto. Nunca sobreescribe archivos existentes.
  • yapu status — Lee STATE.md y reporta modo operacional, fase activa, lista de tareas e integridad de specs.
  • yapu dash — Renderiza un monitor interactivo TUI a 60FPS leyendo el ROADMAP.md y los logs de la IA (Sin dependencias).
  • yapu board [--port N] — Lanza un Command Center (C2) web local con streaming SSE en tiempo real, toggles interactivos de tareas, feed neuronal, y ejecución de comandos por lista blanca. Sin dependencias.
  • yapu gc — Archiva fases antiguas de .planning/phases/ y prepara la compresión de tokens (Contextual Garbage Collector).
  • yapu rescue <log> — Crea instantáneamente una sesión de depuración e instrucción de Auto-Heal para tu IA basada en un log de error.
  • yapu archive — Congela tareas completadas de STATE.md en HISTORY.md con marca de tiempo.
  • yapu install-hooks — Despliega Yapu Guard, hook pre-commit nativo ultrarrápido (<1.5s).
  • yapu sync --brain-path <path> — Fallback manual: sincroniza artefactos del brain de Antigravity a .planning/.
  • yapu handoff — Genera HANDOFF.json + .continue-here.md para continuidad de sesión.
  • yapu brain list --path <path> — Lista artefactos del brain con tipo, resumen y fecha.
  • yapu brain log --path <path> -n N — Muestra las últimas N entradas del log de conversación.
  • yapu provider — Comando de diagnóstico que detecta los CLIs de IA instalados (Antigravity, Claude Code, Codex), muestra sus rutas de datos, cantidad de sesiones, y cuál proveedor está activo.

⚡ Flujos de Agentes Autónomos Incluidos

Además de la organización, YapuCli instala plantillas avanzadas (.agents/skills/) para que tu IA trabaje como un equipo completo:

  • LORE_MASTER: Condensa miles de tokens de contexto en un solo LORE.md ultradenso.
  • GUARDIÁN DE PRODUCCIÓN: Workflow de Auto-Heal que se acciona mediante yapu rescue en CI/CD.
  • CHAOS MONKEY (yapu-chaos.md): Ingeniería de Resiliencia Autónoma. Ordénale a tu IA ejecutar este modo para que inyecte latencia y rompa dependencias intencionalmente, y luego repare la arquitectura para lograr una degradación elegante (Graceful Degradation).

📂 Estructura de .planning/

.planning/
├── STATE.md
├── ROADMAP.md
├── REQUIREMENTS.md
├── METHODOLOGY.md
├── config.json
├── codebase/       # 7 docs de análisis (generados por yapu-map)
├── phases/         # CONTEXT.md, PLAN.md, SUMMARY.md por fase
├── debug/          # Tracking de sesiones de debug
├── seeds/          # Ideas forward-looking
├── notes/
├── todos/
├── research/
├── quick/
└── spikes/

⚡ Arsenal de Skills (85 archivos)

41 workflows · 11 schemas · 25 referencias · 3 contextos · 5 plantillas de codebase

1. Flujo Base 🪺

map · plan · execute · verify

2. Interrogación (Grill) 🔥

grill-me · grill-docs · spec

3. Escuadrones de Élite 🎯

secops · dba · ui · forensics

4. Descubrimiento 🔬

discovery · discuss · research

5. Gestión de Sesión 📋

resume · progress · session-report · handoff

6. Utilidades 🔧

debug · seed · quick · thread · health · audit · code-review · docs · tests · undo · ship · sketch · autonomous · learnings

🧪 Tests e Infraestructura

29 pruebas de integración · ESLint clean

npm run test    # Suite completa de integración
npm run lint    # Validación estática

🪺 Filosofía

El yapú no improvisa: cada fibra del nido tiene un propósito estructural.

Yapu aplica el mismo principio al contexto del LLM — memoria estática explícita, sincronización determinista y cero dependencias externas. El agente siempre sabe dónde está, qué hizo y qué sigue.

YapuCli 🪺 — El nido que desafía la gravedad.