🚀 ECC: Harness-Native Agent Operating System

ECC (ECC Universal) es un sistema operativo y entorno de orquestación diseñado nativamente para agentes de Inteligencia Artificial. Facilita la ejecución, evaluación, estandarización y control de flujos de trabajo autónomos en múltiples entornos de desarrollo (IDEs como Cursor, VS Code, OpenCode, Codex), plataformas conversacionales (Claude Code, Gemini, Kimi) y flujos de trabajo nativos de terminal.

Inspirado en arquitecturas avanzadas de evaluación de IA (como el diseño de arneses de Anthropic para aplicaciones de largo recorrido), ECC actúa como un plano de control unificado que integra Model Context Protocol (MCP), ganchos (hooks) de ciclo de vida, reglas contextuales, almacenamiento de memoria a largo plazo y sistemas iterativos de generación-evaluación estilo GAN.

---

📋 Descripción General

ECC es un motor híbrido (Node.js + Python) que proporciona a los agentes autónomos de IA un marco estructurado de capacidades de ejecución (skills), reglas estrictas de desarrollo guiado por pruebas (TDD), revisión automatizada de código y auditoría de seguridad.

Capacidades Principales

• Arnés de Pruebas Iterativo (GAN-Style Harness): Orquestador que ejecuta bucles iterativos entre un Generador de código y un Evaluador independiente (gan-harness.sh) para refinar implementaciones de software hasta alcanzar el umbral de calidad requerido.
• Plano de Control Multi-Agente (Control-Plane): Concentrador de telemetría y panel de control (ecc-control-pane) que permite supervisar las acciones de los agentes, evaluar su consumo y gestionar sus permisos en tiempo real.
• Integración Nativa MCP (Model Context Protocol): Conector estandarizado para exponer recursos del sistema, bases de datos SQLite empotradas (sql.js), APIs y herramientas personalizadas directamente a los LLMs.
• Hibridación de Modelos (Local & Cloud): Backend flexible en Python que permite conmutar dinámicamente entre proveedores locales de inferencia (Ollama con soporte CLI) y APIs cloud de última generación.

---

🛠️ Tecnologías y Librerías Utilizadas

El repositorio combina un núcleo de automatización y CLI en Node.js con un motor de ejecución e inferencia en Python:

Entorno Node.js (CLI, Orquestación y Hooks)

• Entorno de Ejecución: Node.js (v18 o superior) compilado con TypeScript.
• Bases de Datos: sql.js para almacenamiento ligero relacional y persistencia en memoria del estado de los agentes.
• Formatos de Configuración: @iarna/toml para análisis avanzado de configuraciones de agentes.
• Validación de Esquemas: ajv (Another JSON Schema Validator) para validar manifiestos y la configuración de los agentes.

Entorno Python (Inferencia y Dashboards)

• Gestor de Dependencias: pyproject.toml para el aislamiento y empaquetado del módulo LLM.
• Inferencia Local: Integración nativa con Ollama (src/llm/providers/ollama.py) y resolvedores dinámicos de modelos.
• Cuadro de Mando: ecc_dashboard.py para la visualización del estado operativo y métricas de los agentes en ejecución.

---

📂 Estructura de Carpetas

La arquitectura del proyecto está organizada para separar las herramientas de ejecución, los scripts de automatización del ciclo de vida y el motor LLM subyacente:

├── .agents/                    # Configuraciones y manifiestos específicos por agente de IA
├── .claude-plugin/             # Integración y manifiestos para Claude Code y Claude Plugins
├── .cursor/                    # Reglas contextuales, prompts y hooks para Cursor IDE
├── .opencode/                  # Configuración y compilación para entornos OpenCode
├── src/                        # Código fuente principal de la aplicación
│   └── llm/                    # Módulo Python para la gestión de LLMs
│       ├── cli/                # CLI interactivo para la selección de modelos (selector.py)
│       ├── core/               # Tipos, interfaces de abstracción y contratos principales
│       ├── providers/          # Integración de proveedores de inferencia (Ollama, Resolvers)
│       └── tools/              # Ejecutores de código y herramientas sandbox para los agentes
├── scripts/                    # Scripts de orquestación, utilidades y ciclo de vida (Node.js / Bash)
│   ├── ecc.js                  # Punto de entrada principal de la CLI de ECC
│   ├── control-pane.js         # Lógica interna del panel de control
│   ├── gan-harness.sh          # Orquestador del bucle generador-evaluador estilo GAN
│   ├── worktree-lifecycle.js   # Gestión avanzada del ciclo de vida de ramas y Git Worktrees
│   └── install-apply.js        # Script de instalación y aprovisionamiento
├── rules/                      # Reglas de validación, estándares de código y directivas de IA
├── hooks/                      # Scripts para eventos de Git y hooks de ejecución de agentes
├── ecc_dashboard.py            # Dashboard visual de monitorización en Python
├── agent.yaml / mem0.yaml      # Configuración general del agente de IA y persistencia de memoria
├── pyproject.toml              # Definición de dependencias y empaquetado Python
├── package.json                # Configuración de scripts, binarios CLI y dependencias Node.js
└── Dockerfile                  # Empaquetado en contenedor para producción Nginx + Dist estática

---

🚀 Instalación y Ejecución Local

Requisitos Previos

• Node.js: Versión >= 18 (gestión recomendada mediante .tool-versions).
• Python: Versión >= 3.10 para el módulo LLM y el Dashboard.
• Ollama (Opcional): Si deseas ejecutar los modelos de lenguaje de forma local.

Paso 1: Instalación de Dependencias

Ejecuta el instalador automatizado multiplataforma:

En Linux / macOS:

chmod +x install.sh
./install.sh

En Windows (PowerShell):

./install.ps1

O realiza la instalación manual de los entornos:

# Instalar dependencias de Node.js
yarn install --immutable

# Instalar dependencias de Python y el módulo LLM local
pip install -e .

Paso 2: Configuración del Entorno

Copia el archivo de variables de entorno de ejemplo y configúralo de acuerdo a tus necesidades:

cp .env.example .env

Asegúrate de configurar los tokens de tus proveedores cloud preferidos o la ruta de tu servidor Ollama local.

Paso 3: Uso de la CLI de ECC

El paquete ecc-universal expone tres comandos globales una vez instalado:

1. ecc: Interfaz de comandos para la gestión de agentes.
2. ecc-control-pane: Lanza el plano de control para monitorear el comportamiento de tus agentes.
3. ecc-install: Aplica configuraciones y actualiza los manifiestos del sistema.

Ejemplo de ejecución del arnés de pruebas GAN para generar componentes de forma iterativa y validada:

# Ejecutar el arnés generador-evaluador para una funcionalidad
GAN_MAX_ITERATIONS=5 GAN_PASS_THRESHOLD=8.5 ./scripts/gan-harness.sh "Construir un panel de visualización en tiempo real"

---

⚙️ Gobernanza del Proyecto

El desarrollo en este repositorio está estrictamente ligado a los estándares de calidad automatizados de la plataforma:

• Validación de Commits y Código: El proyecto utiliza lefthook para orquestar ganchos de pre-commit y pre-push, garantizando la consistencia del código mediante el formateador Biome, linters estáticos y eslint.config.js.
• Seguridad y Secretos: Integración con gitleaks mediante el archivo .gitleaksignore y escaneo preventivo de IOCs (Indicators of Compromise) en la cadena de suministro usando scripts en scripts/ci/.
• Control de Errores en Git: Se utiliza un proxy Git personalizado (.no-mistakes.yaml) que intercepta comandos de publicación accidentales y commits fuera de estándar para mantener una historia de Git limpia y profesional.

---

Megacore - Automatizando y estandarizando la calidad del software en Megasoft.