**El sistema operativo nativo del harness para trabajo agentivo. Construido a partir de flujos de trabajo de ingeniería multi-harness del mundo real.**
No son solo configuraciones. Es un sistema completo: skills, instintos, optimización de memoria, aprendizaje continuo, análisis de seguridad y desarrollo orientado a la investigación. Agentes listos para producción, skills, hooks, reglas, configuraciones de MCP y comandos legados, evolucionados durante más de 10 meses de uso diario intensivo construyendo productos reales.
Funciona en **Codex**, **Claude Code**, **Cursor**, **OpenCode**, **Gemini**, **Zed**, **GitHub Copilot** y otros harnesses de agentes de IA.
ECC v2.0.0-rc.1 añade la historia pública del operador Hermes sobre esa capa reutilizable: comienza con la [guía de configuración de Hermes](../HERMES-SETUP.md), luego revisa las [notas de la versión rc.1](../releases/2.0.0-rc.1/release-notes.md) y la [arquitectura multi-harness](../architecture/cross-harness.md).
<sub>Instalar · Auditorías de PR · Tier gratuito</sub>
</a>
</td>
</tr>
</table>
<sub>**El OSS es gratis para siempre.** Este repositorio tiene licencia MIT permanente. ECC Pro es la GitHub App alojada para repositorios privados. Los <a href="https://github.com/sponsors/affaan-m">patrocinadores</a> y los <a href="https://ecc.tools/pricing">suscriptores Pro</a> financian el trabajo — por eso un solo mantenedor publica semanalmente en 7 harnesses.</sub>
---
## Las Guías
Este repositorio contiene solo el código. Las guías explican todo.
| Orquestación de Subagentes | El problema del contexto, patrón de recuperación iterativa |
---
## Novedades
### v2.0.0-rc.1 — Actualización de Superficie, Flujos de Trabajo de Operador y Alpha de ECC 2.0 (Abr 2026)
- **Dashboard GUI** — Nueva aplicación de escritorio basada en Tkinter (`ecc_dashboard.py` o `npm run dashboard`) con alternancia de tema oscuro/claro, personalización de fuente y logo del proyecto en el encabezado y la barra de tareas.
- **Superficie pública sincronizada con el repo en vivo** — metadatos, conteos del catálogo, manifiestos de plugins y documentación de instalación ahora coinciden con la superficie OSS real: 63 agentes, 249 skills y 79 shims de comandos legados.
- **Expansión de flujos de trabajo de operador y salida** — `brand-voice`, `social-graph-ranker`, `connections-optimizer`, `customer-billing-ops`, `ecc-tools-cost-audit`, `google-workspace-ops`, `project-flow-ops` y `workspace-surface-audit` completan el carril de operador.
- **Herramientas de medios y lanzamiento** — `manim-video`, `remotion-video-creation` y superficies de publicación social actualizadas integran la creación de contenido técnico y de lanzamiento en el mismo sistema.
- **Crecimiento de frameworks y productos** — `nestjs-patterns`, superficies de instalación más ricas para Codex/OpenCode y empaquetado cross-harness expandido mantienen el repo utilizable más allá de Claude Code.
- **Pack de skills de mercados de predicción Itô** — la skill consolidada `ito-baskets` (índice de cestas de solo lectura, comparación, briefs de mercado y hojas de planificación no ejecutables; reemplaza a las antiguas `ito-market-intelligence`, `ito-basket-compare`, `ito-trade-planner` y `ito-data-atlas-agent`), junto con `prediction-market-oracle-research` y `prediction-market-risk-review`, añaden flujos de trabajo públicos de mercado/cesta no asesorados, manteniendo el acceso a la API de Itô separado de la facturación de ECC Tools.
- **Pack de skills de optimización** — `parallel-execution-optimizer`, `benchmark-optimization-loop`, `data-throughput-accelerator`, `latency-critical-systems` y `recursive-decision-ledger` convierten los prompts de velocidad/recursión repetidos en flujos de trabajo acotados de benchmark, rendimiento y decisiones.
- **ECC 2.0 alpha incluido en el árbol** — el prototipo del plano de control en Rust en `ecc2/` ya compila localmente y expone los comandos `dashboard`, `start`, `sessions`, `status`, `stop`, `resume` y `daemon`. Está disponible como alpha, aún no como versión general.
- **Instantáneas de estado del operador** — `ecc status --markdown --write status.md` convierte el almacén de estado local en un informe portátil de transferencia que cubre disponibilidad, sesiones activas, estado de ejecución de skills, estado de la instalación, eventos de gobernanza pendientes y elementos de trabajo vinculados de Linear/GitHub/transferencias. Usa `ecc work-items upsert ...` para entradas manuales, `ecc work-items sync-github --repo owner/repo` para el estado de la cola de PRs/issues, y `ecc status --exit-code` para hacer fallar la automatización cuando la disponibilidad requiere atención.
- **Hardening del ecosistema** — AgentShield, controles de costos de ECC Tools, trabajo en el portal de facturación y actualizaciones del sitio web continúan publicándose junto al plugin principal en lugar de desviarse hacia silos separados.
### v1.9.0 — Instalación Selectiva y Expansión de Lenguajes (Mar 2026)
- **Arquitectura de instalación selectiva** — Pipeline de instalación basado en manifiestos con `install-plan.js` e `install-apply.js` para instalación de componentes específicos. El almacén de estado rastrea lo instalado y permite actualizaciones incrementales.
- **6 nuevos agentes** — `typescript-reviewer`, `pytorch-build-resolver`, `java-build-resolver`, `java-reviewer`, `kotlin-reviewer`, `kotlin-build-resolver` amplían la cobertura de lenguajes a 10 idiomas de programación.
- **Nuevas skills** — `pytorch-patterns` para flujos de trabajo de aprendizaje profundo, `documentation-lookup` para investigación de referencias de API, `bun-runtime` y `nextjs-turbopack` para toolchains modernas de JS, además de 8 skills de dominio operacional y `mcp-server-patterns`.
- **Infraestructura de sesiones y estado** — Almacén de estado SQLite con CLI de consultas, adaptadores de sesión para grabación estructurada, base para la evolución de skills auto-mejorables.
- **Revisión de orquestación** — Puntuación de auditoría del harness hecha determinista, estado de orquestación y compatibilidad del lanzador reforzados, prevención de bucles de observador con guardia de 5 capas.
- **Confiabilidad del observador** — Corrección de explosión de memoria con throttling y muestreo de cola, corrección de acceso a sandbox, lógica de inicio diferido y guardia de reentrada.
- **12 ecosistemas de lenguajes** — Nuevas reglas para Java, PHP, Perl, Kotlin/Android/KMP, C++ y Rust se suman a TypeScript, Python, Go y reglas comunes existentes.
- **Contribuciones de la comunidad** — Traducciones al coreano y chino, optimización de hooks de biome, skills de procesamiento de video, skills operacionales, instalador de PowerShell, soporte para Antigravity IDE.
- **Hardening de CI** — 19 correcciones de fallos en pruebas, aplicación de conteos del catálogo, validación del manifiesto de instalación y suite de pruebas completa en verde.
### v1.8.0 — Sistema de Rendimiento del Harness (Mar 2026)
- **Primera versión centrada en el harness** — ECC ahora se enmarca explícitamente como un sistema de rendimiento del harness de agentes, no solo un paquete de configuración.
- **Revisión de la confiabilidad de hooks** — Fallback de raíz en SessionStart, resúmenes de sesión en la fase Stop y hooks basados en scripts que reemplazan frágiles one-liners en línea.
- **Controles de ejecución de hooks** — `ECC_HOOK_PROFILE=minimal|standard|strict` y `ECC_DISABLED_HOOKS=...` para control en tiempo de ejecución sin editar los archivos de hooks.
- **NanoClaw v2** — enrutamiento de modelos, carga en caliente de skills, rama/búsqueda/exportación/compactación/métricas de sesión.
- **Paridad cross-harness** — comportamiento ajustado entre Claude Code, Cursor, OpenCode y Codex app/CLI.
- **997 pruebas internas pasando** — suite completa en verde tras la refactorización de hooks/runtime y actualizaciones de compatibilidad.
### v1.7.0 — Expansión Multiplataforma y Constructor de Presentaciones (Feb 2026)
- **Soporte para Codex app + CLI** — Soporte directo de Codex basado en `AGENTS.md`, targeting del instalador y documentación de Codex
- **Skill `frontend-slides`** — Constructor de presentaciones HTML sin dependencias con guía de conversión a PPTX y reglas estrictas de ajuste al viewport
- **Mayor cobertura de herramientas** — Soporte para Cursor, Codex y OpenCode reforzado para que el mismo repo funcione limpiamente en todos los harnesses principales
- **992 pruebas internas** — Validación y cobertura de regresión ampliadas en plugin, hooks, skills y empaquetado
### v1.6.0 — Codex CLI, AgentShield y Marketplace (Feb 2026)
- **Soporte para Codex CLI** — Nuevo comando `/codex-setup` que genera `codex.md` para compatibilidad con OpenAI Codex CLI
- **Integración de AgentShield** — La skill `/security-scan` ejecuta AgentShield directamente desde Claude Code; 1282 pruebas, 102 reglas
- **GitHub Marketplace** — La GitHub App ECC Tools disponible en [github.com/marketplace/ecc-tools](https://github.com/marketplace/ecc-tools) con niveles gratuito/pro/empresarial
- **Más de 30 PRs de la comunidad fusionados** — Contribuciones de 30 colaboradores en 6 lenguajes
- **978 pruebas internas** — Suite de validación ampliada en agentes, skills, comandos, hooks y reglas
### v1.4.1 — Corrección de Errores (Feb 2026)
- **Corrección de pérdida de contenido en importación de instintos** — `parse_instinct_file()` descartaba silenciosamente todo el contenido tras el frontmatter (secciones Action, Evidence, Examples) durante `/instinct-import`. ([#148](https://github.com/affaan-m/ECC/issues/148), [#161](https://github.com/affaan-m/ECC/pull/161))
### v1.4.0 — Reglas Multi-Lenguaje, Asistente de Instalación y PM2 (Feb 2026)
- **Asistente de instalación interactivo** — La nueva skill `configure-ecc` proporciona configuración guiada con detección de fusión/sobrescritura
- **PM2 y orquestación multi-agente** — 6 nuevos comandos (`/pm2`, `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend`, `/multi-workflow`) para gestionar flujos de trabajo complejos multi-servicio
- **Arquitectura de reglas multi-lenguaje** — Reglas reestructuradas de archivos planos en directorios `common/` + `typescript/` + `python/` + `golang/`. Instala solo los lenguajes que necesitas
- **Traducciones al chino (zh-CN)** — Traducción completa de todos los agentes, comandos, skills y reglas (más de 80 archivos)
- **Soporte de GitHub Sponsors** — Patrocina el proyecto a través de GitHub Sponsors
- **CONTRIBUTING.md mejorado** — Plantillas detalladas de PR para cada tipo de contribución
### v1.3.0 — Soporte para Plugin de OpenCode (Feb 2026)
- **Integración completa con OpenCode** — 12 agentes, 24 comandos, 16 skills con soporte de hooks mediante el sistema de plugins de OpenCode (más de 20 tipos de eventos)
- **Documentación para LLM** — `llms.txt` con documentación completa de OpenCode
### v1.2.0 — Comandos y Skills Unificados (Feb 2026)
- **Soporte para Python/Django** — Skills de patrones de Django, seguridad, TDD y verificación
- **Skills para Java Spring Boot** — Patrones, seguridad, TDD y verificación para Spring Boot
- **Gestión de sesiones** — Comando `/sessions` para historial de sesiones
- **Aprendizaje continuo v2** — Aprendizaje basado en instintos con puntuación de confianza, importación/exportación y evolución
Consulta el changelog completo en [Releases](https://github.com/affaan-m/ECC/releases).
---
## Inicio Rápido
Empieza a trabajar en menos de 2 minutos:
### Elige solo un camino
La mayoría de los usuarios de Claude Code deben usar exactamente un método de instalación:
- **Opción recomendada por defecto:** instala el plugin de Claude Code, luego copia solo las carpetas de reglas que realmente necesites.
- **Usa el instalador manual solo si** quieres un control más granular, deseas evitar completamente la ruta del plugin o tu build de Claude Code tiene problemas para resolver la entrada del marketplace autoalojado.
- **No combines métodos de instalación.** La configuración rota más común es: `/plugin install` primero, luego `install.sh --profile full` o `npx ecc-universal install --profile full` después.
Si ya combinaste múltiples instalaciones y hay duplicados, salta directamente a [Restablecer / Desinstalar ECC](#restablecer--desinstalar-ecc).
### Ruta sin contexto / sin hooks
Si los hooks te parecen demasiado globales o solo quieres las reglas, agentes, comandos y skills principales de ECC, omite el plugin y usa el perfil manual mínimo:
Devuelve los componentes coincidentes, los perfiles relacionados y los comandos de vista previa/instalación. Usa el comando de vista previa antes de instalar si quieres inspeccionar el plan de archivos exacto.
Para flujos de trabajo de ML/MLOps en producción, mantén la instalación opt-in y con alcance de componentes:
> NOTA: El plugin es conveniente, pero el instalador OSS de abajo sigue siendo la ruta más confiable si tu build de Claude Code tiene problemas para resolver entradas del marketplace autoalojado.
ECC tiene tres identificadores públicos que no son intercambiables:
- Repositorio fuente de GitHub: `affaan-m/ECC`
- Identificador de marketplace/plugin de Claude: `ecc@ecc`
- Paquete npm: `ecc-universal`
Esto es intencional. Las instalaciones del marketplace/plugin de Anthropic se identifican por un identificador de plugin canónico, por lo que ECC usa `ecc@ecc` para mantener los nombres de herramientas y los espacios de nombres de comandos slash lo suficientemente cortos para los validadores estrictos de Desktop/API. Las publicaciones antiguas pueden mostrar el anterior identificador largo del marketplace; trátalo solo como un alias heredado. Por su parte, el paquete npm se mantuvo en `ecc-universal`, por lo que las instalaciones de npm y las del marketplace usan intencionalmente nombres diferentes.
### Paso 2: Instalar Reglas Solo Si Las Necesitas
> ADVERTENCIA: **Importante:** Los plugins de Claude Code no pueden distribuir `rules` automáticamente.
> Si ya instalaste ECC mediante `/plugin install`, **no ejecutes `./install.sh --profile full`, `.\install.ps1 --profile full`, ni `npx ecc-universal install --profile full` después**. El plugin ya carga las skills, comandos y hooks de ECC. Ejecutar el instalador completo tras una instalación del plugin copia esas mismas superficies en tus directorios de usuario y puede crear skills duplicadas más comportamiento duplicado en tiempo de ejecución.
> Para instalaciones de plugin, copia manualmente solo los directorios `rules/` que quieras bajo `~/.claude/rules/ecc/`. Empieza con `rules/common` más un pack de lenguaje o framework que uses realmente. No copies todos los directorios de reglas a menos que quieras explícitamente todo ese contexto en Claude.
>
> Usa el instalador completo solo cuando hagas una instalación completamente manual de ECC en lugar de la ruta del plugin.
>
> Si tu configuración local de Claude fue eliminada o restablecida, eso no significa que necesites volver a comprar ECC. Empieza con `node scripts/ecc.js list-installed`, luego ejecuta `node scripts/ecc.js doctor` y `node scripts/ecc.js repair` antes de reinstalar cualquier cosa. Eso generalmente restaura los archivos gestionados por ECC sin reconstruir tu configuración. Si el problema es el acceso a la cuenta o al marketplace para ECC Tools, gestiona la recuperación de la facturación/cuenta por separado.
```bash
# Clonar el repo primero
git clone https://github.com/affaan-m/ECC.git
cd ECC
# Instalar dependencias (elige tu gestor de paquetes)
Para instrucciones de instalación manual consulta el README en la carpeta `rules/`. Al copiar reglas manualmente, copia el directorio completo del lenguaje (por ejemplo `rules/common` o `rules/golang`), no los archivos dentro de él, para que las referencias relativas sigan funcionando y los nombres de archivo no colisionen.
### Instalación completamente manual (Alternativa)
Usa esto solo si estás omitiendo intencionalmente la ruta del plugin:
Si eliges esta ruta, detente aquí. No ejecutes también `/plugin install`.
### Restablecer / Desinstalar ECC
Si ECC parece duplicado, intrusivo o roto, no lo reinstales encima de sí mismo.
- **Ruta del plugin:** elimina el plugin de Claude Code, luego borra las carpetas de reglas específicas que copiaste manualmente bajo `~/.claude/rules/ecc/`.
- **Ruta del instalador manual / CLI:** desde la raíz del repo, previsualiza la eliminación primero:
```bash
node scripts/uninstall.js --dry-run
```
Luego elimina los archivos gestionados por ECC:
```bash
node scripts/uninstall.js
```
También puedes usar el wrapper del ciclo de vida:
```bash
node scripts/ecc.js list-installed
node scripts/ecc.js doctor
node scripts/ecc.js repair
node scripts/ecc.js uninstall --dry-run
```
ECC solo elimina los archivos registrados en su estado de instalación. No borrará archivos no relacionados que no haya instalado.
Si combinaste métodos, limpia en este orden:
1. Elimina la instalación del plugin de Claude Code.
2. Ejecuta el comando de desinstalación de ECC desde la raíz del repo para eliminar los archivos gestionados por el estado de instalación.
3. Borra las carpetas de reglas adicionales que copiaste manualmente y ya no necesites.
4. Reinstala una vez, usando un único método.
### Paso 3: Empezar a Usar
```bash
# Las skills son la superficie principal de flujo de trabajo.
# Los nombres de comandos estilo slash existentes siguen funcionando mientras ECC migra fuera de commands/.
# La instalación por plugin usa la forma canónica con espacio de nombres
/ecc:plan "Añadir autenticación de usuario"
# La instalación manual mantiene la forma slash más corta:
# /plan "Añadir autenticación de usuario"
# Ver comandos disponibles
/plugin list ecc@ecc
```
**¡Listo!** Ahora tienes acceso a 63 agentes, 249 skills y 79 shims de comandos legados.
### Dashboard GUI
Lanza el dashboard de escritorio para explorar visualmente los componentes de ECC:
```bash
npm run dashboard
# o
python3 ./ecc_dashboard.py
```
**Características:**
- Interfaz con pestañas: Agentes, Skills, Comandos, Reglas, Configuración
- Alternancia de tema oscuro/claro
- Personalización de fuente (familia y tamaño)
- Logo del proyecto en el encabezado y la barra de tareas
- Búsqueda y filtrado en todos los componentes
### Los comandos multi-modelo requieren configuración adicional
> ADVERTENCIA: Los comandos `multi-*` **no** están cubiertos por la instalación base del plugin/reglas anterior.
>
> Para usar `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend` y `/multi-workflow`, también debes instalar el runtime `ccg-workflow`.
>
> Inicialízalo con `npx ccg-workflow`.
>
> Ese runtime proporciona las dependencias externas que esperan estos comandos, incluyendo:
> - `~/.claude/bin/codeagent-wrapper`
> - `~/.claude/.ccg/prompts/*`
>
> Sin `ccg-workflow`, estos comandos `multi-*` no funcionarán correctamente.
---
## Soporte Multiplataforma
Este plugin ahora es totalmente compatible con **Windows, macOS y Linux**, junto con una integración estrecha en los principales IDEs (Cursor, Zed, OpenCode, Antigravity) y harnesses de CLI. Todos los hooks y scripts han sido reescritos en Node.js para máxima compatibilidad.
### Detección del Gestor de Paquetes
El plugin detecta automáticamente tu gestor de paquetes preferido (npm, pnpm, yarn o bun) con la siguiente prioridad:
1.**Variable de entorno**: `CLAUDE_PACKAGE_MANAGER`
2.**Configuración del proyecto**: `.claude/package-manager.json`
3.**package.json**: campo `packageManager`
4.**Archivo de bloqueo**: Detección desde package-lock.json, yarn.lock, pnpm-lock.yaml o bun.lockb
# O se activa automáticamente al hacer push a la rama por defecto
```
Ambas opciones crean:
- **Archivos SKILL.md** - Skills listas para usar en Claude Code
- **Colecciones de instintos** - Para continuous-learning-v2
- **Extracción de patrones** - Aprende de tu historial de commits
### AgentShield — Auditor de Seguridad
> Construido en el Claude Code Hackathon (Cerebral Valley x Anthropic, Feb 2026). 1282 pruebas, 98% de cobertura, 102 reglas de análisis estático.
Analiza tu configuración de Claude Code en busca de vulnerabilidades, configuraciones incorrectas y riesgos de inyección.
```bash
# Análisis rápido (sin instalación necesaria)
npx ecc-agentshield scan
# Corrección automática de problemas seguros
npx ecc-agentshield scan --fix
# Análisis profundo con tres agentes Opus 4.6
npx ecc-agentshield scan --opus --stream
# Generar configuración segura desde cero
npx ecc-agentshield init
```
**Qué analiza:** CLAUDE.md, settings.json, configuraciones de MCP, hooks, definiciones de agentes y skills en 5 categorías — detección de secretos (14 patrones), auditoría de permisos, análisis de inyección en hooks, perfilado de riesgo de servidores MCP y revisión de configuración de agentes.
**El flag `--opus`** ejecuta tres agentes Claude Opus 4.6 en un pipeline red-team/blue-team/auditor. El atacante encuentra cadenas de exploits, el defensor evalúa las protecciones y el auditor sintetiza ambos en una evaluación de riesgo priorizada. Razonamiento adversarial, no solo coincidencia de patrones.
**Formatos de salida:** Terminal (color graduado A-F), JSON (pipelines de CI), Markdown, HTML. Código de salida 2 en hallazgos críticos para puertas de build.
Usa `/security-scan` en Claude Code para ejecutarlo, o añádelo a CI con la [GitHub Action](https://github.com/affaan-m/agentshield).
El sistema de aprendizaje basado en instintos aprende tus patrones automáticamente:
```bash
/instinct-status # Ver instintos aprendidos con confianza
/instinct-import <file> # Importar instintos de otros
/instinct-export # Exportar tus instintos para compartir
/evolve # Agrupar instintos relacionados en skills
```
Consulta `skills/continuous-learning-v2/` para la documentación completa.
Mantén `continuous-learning/` solo cuando quieras explícitamente el flujo legado v1 de skills aprendidas con hook Stop.
---
## Requisitos
### Versión del CLI de Claude Code
**Versión mínima: v2.1.0 o posterior**
Este plugin requiere Claude Code CLI v2.1.0+ debido a cambios en cómo el sistema de plugins gestiona los hooks.
Comprueba tu versión:
```bash
claude --version
```
### Importante: Comportamiento de Carga Automática de Hooks
> ADVERTENCIA: **Para Contribuidores:** NO añadas un campo `"hooks"` a `.claude-plugin/plugin.json`. Esto está reforzado por una prueba de regresión.
Claude Code v2.1+ **carga automáticamente**`hooks/hooks.json` de cualquier plugin instalado por convención. Declararlo explícitamente en `plugin.json` provoca un error de detección de duplicados:
```
Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file
```
**Historial:** Esto ha causado ciclos repetidos de corrección/reversión en este repo ([#29](https://github.com/affaan-m/ECC/issues/29), [#52](https://github.com/affaan-m/ECC/issues/52), [#103](https://github.com/affaan-m/ECC/issues/103)). El comportamiento cambió entre versiones de Claude Code, generando confusión. Ahora tenemos una prueba de regresión para prevenir que se reintroduzca.
---
## Instalación
### Opción 1: Instalar como Plugin (Recomendado)
La forma más fácil de usar este repo — instálalo como plugin de Claude Code:
O añade directamente a tu `~/.claude/settings.json`:
```json
{
"extraKnownMarketplaces":{
"ecc":{
"source":{
"source":"github",
"repo":"affaan-m/ECC"
}
}
},
"enabledPlugins":{
"ecc@ecc":true
}
}
```
Esto te da acceso instantáneo a todos los comandos, agentes, skills y hooks.
> **Nota:** El sistema de plugins de Claude Code no permite distribuir `rules` mediante plugins ([limitación upstream](https://code.claude.com/docs/en/plugins-reference)). Necesitas instalar las reglas manualmente:
>
> ```bash
> # Clonar el repo primero
> git clone https://github.com/affaan-m/ECC.git
> cd ECC
>
> # Opción A: Reglas a nivel de usuario (se aplican a todos los proyectos)
> mkdir -p ~/.claude/rules/ecc
> cp -r rules/common ~/.claude/rules/ecc/
> cp -r rules/typescript ~/.claude/rules/ecc/ # elige tu stack
> cp -r rules/python ~/.claude/rules/ecc/
> cp -r rules/golang ~/.claude/rules/ecc/
> cp -r rules/php ~/.claude/rules/ecc/
>
> # Opción B: Reglas a nivel de proyecto (se aplican solo al proyecto actual)
> mkdir -p .claude/rules/ecc
> cp -r rules/common .claude/rules/ecc/
> cp -r rules/typescript .claude/rules/ecc/ # elige tu stack
> ```
---
### Opción 2: Instalación Manual
Si prefieres control manual sobre lo que se instala:
```bash
# Clonar el repo
git clone https://github.com/affaan-m/ECC.git
cd ECC
# Copiar agentes a tu configuración de Claude
cp agents/*.md ~/.claude/agents/
# Copiar directorios de reglas (common + específicos del lenguaje)
mkdir -p ~/.claude/rules/ecc
cp -r rules/common ~/.claude/rules/ecc/
cp -r rules/typescript ~/.claude/rules/ecc/ # elige tu stack
# Opcional: mantener compatibilidad con entradas slash durante la migración
mkdir -p ~/.claude/commands
cp commands/*.md ~/.claude/commands/
# Los shims retirados están en legacy-command-shims/commands/.
# Copia archivos individuales de ahí solo si todavía necesitas nombres viejos como /tdd.
```
#### Instalar hooks
No copies el `hooks/hooks.json` del repo directamente en `~/.claude/settings.json` ni en `~/.claude/hooks/hooks.json`. Ese archivo está orientado al plugin/repo y está pensado para instalarse mediante el instalador de ECC o cargarse como plugin, por lo que la copia directa no es una ruta de instalación manual soportada.
Usa el instalador para instalar solo el runtime de hooks de Claude de forma que las rutas de comandos se reescriban correctamente:
```bash
# macOS / Linux
bash ./install.sh --target claude --modules hooks-runtime
Eso escribe los hooks resueltos en `~/.claude/hooks/hooks.json` y deja intacto cualquier `~/.claude/settings.json` existente.
Si instalaste ECC mediante `/plugin install`, no copies esos hooks en `settings.json`. Claude Code v2.1+ ya carga automáticamente el `hooks/hooks.json` del plugin, y duplicarlos en `settings.json` provoca ejecución duplicada y conflictos de hooks multiplataforma.
Nota para Windows: el directorio de configuración de Claude es `%USERPROFILE%\\.claude`, no `~/claude`.
#### Configurar MCPs
Las instalaciones de plugin de Claude intencionalmente no habilitan automáticamente las definiciones de servidores MCP empaquetadas en ECC. Esto evita nombres de herramientas MCP demasiado largos en puertas de acceso estrictas de terceros mientras mantiene la configuración manual de MCP disponible.
Usa el comando `/mcp` de Claude Code o la configuración de MCP gestionada por CLI para cambios en tiempo de ejecución de servidores MCP de Claude Code. Usa `/mcp` para deshabilitar en el runtime de Claude Code; Claude Code persiste esas opciones en `~/.claude.json`.
Para acceso a MCP local del repo, copia las definiciones de servidor MCP deseadas de `mcp-configs/mcp-servers.json` en un `.mcp.json` con alcance de proyecto.
Si ya ejecutas tus propias copias de los MCPs empaquetados en ECC, establece:
Los flujos de instalación y sincronización de Codex gestionados por ECC omitirán o eliminarán esos servidores empaquetados en lugar de volver a añadir duplicados. `ECC_DISABLED_MCPS` es un filtro de instalación/sincronización de ECC, no un interruptor en tiempo de ejecución de Claude Code.
**Importante:** Reemplaza los marcadores `YOUR_*_HERE` con tus claves de API reales.
---
## Conceptos Clave
### Agentes
Los subagentes manejan tareas delegadas con alcance limitado. Ejemplo:
```markdown
---
name:code-reviewer
description:Reviews code for quality, security, and maintainability
tools:["Read","Grep","Glob","Bash"]
model:opus
---
You are a senior code reviewer...
```
### Skills
Las skills son la superficie principal de flujo de trabajo. Pueden invocarse directamente, sugerirse automáticamente y ser reutilizadas por agentes. ECC sigue enviando `commands/` mantenidas durante la migración, mientras que los shims de nombres cortos retirados están en `legacy-command-shims/` solo para opt-in explícito. El nuevo desarrollo de flujos de trabajo debe aterrizar primero en `skills/`.
```markdown
# Flujo de Trabajo TDD
1. Define las interfaces primero
2. Escribe pruebas que fallen (ROJO)
3. Implementa el código mínimo (VERDE)
4. Refactoriza (MEJORAR)
5. Verifica 80%+ de cobertura
```
### Hooks
Los hooks se disparan en eventos de herramientas. Ejemplo — advertir sobre console.log:
typescript/ # Patrones y herramientas específicos de TS/JS
python/ # Patrones y herramientas específicos de Python
golang/ # Patrones y herramientas específicos de Go
swift/ # Patrones y herramientas específicos de Swift
php/ # Patrones y herramientas específicos de PHP
arkts/ # Patrones y restricciones de HarmonyOS / ArkTS
```
Consulta [`rules/README.md`](../../rules/README.md) para detalles de instalación y estructura.
---
## ¿Qué Agente Debo Usar?
¿No sabes por dónde empezar? Usa esta referencia rápida. Las skills son la superficie canónica de flujo de trabajo; las entradas slash mantenidas siguen disponibles para flujos de trabajo orientados a comandos.
| Quiero... | Usar esta superficie | Agente usado |
| Auditar consultas de base de datos | *(delegado automáticamente)* | database-reviewer |
| Revisar cambios de ML en producción | skill `mle-workflow` + agente `mle-reviewer` | mle-reviewer |
### Flujos de Trabajo Comunes
Las formas slash a continuación se muestran donde siguen siendo parte de la superficie de comandos mantenida. Los shims de nombres cortos retirados como `/tdd` y `/eval` están en `legacy-command-shims/` solo para opt-in explícito.
**Empezando una nueva feature:**
```
/ecc:plan "Añadir autenticación de usuario con OAuth"
skill tdd-workflow → tdd-guide: escribe una prueba que falle y lo reproduzca
→ implementa la corrección, verifica que la prueba pase
/code-review → code-reviewer: detecta regresiones
```
**Preparando para producción:**
```
/security-scan → security-reviewer: auditoría OWASP Top 10
skill e2e-testing → e2e-runner: pruebas de flujos de usuario críticos
/test-coverage → verificar 80%+ de cobertura
```
---
## Preguntas Frecuentes
<details>
<summary><b>¿Cómo veo qué agentes/comandos están instalados?</b></summary>
```bash
/plugin list ecc@ecc
```
Muestra todos los agentes, comandos y skills disponibles del plugin.
</details>
<details>
<summary><b>Mis hooks no funcionan / Veo errores de "Duplicate hooks file"</b></summary>
Este es el problema más común. **NO añadas un campo `"hooks"` a `.claude-plugin/plugin.json`.** Claude Code v2.1+ carga automáticamente `hooks/hooks.json` de los plugins instalados. Declararlo explícitamente provoca errores de detección de duplicados. Consulta [#29](https://github.com/affaan-m/ECC/issues/29), [#52](https://github.com/affaan-m/ECC/issues/52), [#103](https://github.com/affaan-m/ECC/issues/103).
</details>
<details>
<summary><b>¿Puedo usar ECC con Claude Code en un endpoint de API personalizado o un gateway de modelos?</b></summary>
Sí. ECC no tiene configuraciones de transporte alojadas en Anthropic. Se ejecuta localmente a través de la superficie CLI/plugin normal de Claude Code, por lo que funciona con:
- Claude Code alojado en Anthropic
- Configuraciones de gateway oficial de Claude Code usando `ANTHROPIC_BASE_URL` y `ANTHROPIC_AUTH_TOKEN`
- Endpoints personalizados compatibles que hablen la API de Anthropic que espera Claude Code
Si tu gateway reasigna nombres de modelos, configúralo en Claude Code en lugar de en ECC. Los hooks, skills, comandos y reglas de ECC son agnósticos al proveedor de modelos una vez que el CLI `claude` ya funciona.
Referencias oficiales:
- [Documentación del gateway LLM de Claude Code](https://docs.anthropic.com/en/docs/claude-code/llm-gateway)
- [Documentación de configuración de modelos de Claude Code](https://docs.anthropic.com/en/docs/claude-code/model-config)
</details>
<details>
<summary><b>Mi ventana de contexto se está reduciendo / Claude se queda sin contexto</b></summary>
Demasiados servidores MCP consumen tu contexto. Cada descripción de herramienta MCP consume tokens de tu ventana de 200k, potencialmente reduciéndola a ~70k. El contexto de SessionStart está limitado a 8000 caracteres por defecto; redúcelo con `ECC_SESSION_START_MAX_CHARS=4000` o desactívalo con `ECC_SESSION_START_CONTEXT=off` para configuraciones de bajo contexto o modelo local.
**Solución:** Deshabilita los MCPs no utilizados desde Claude Code con `/mcp`. Claude Code escribe esas opciones en tiempo de ejecución en `~/.claude.json`; `.claude/settings.json` y `.claude/settings.local.json` no son interruptores confiables para servidores MCP ya cargados.
Mantén menos de 10 MCPs habilitados y menos de 80 herramientas activas.
</details>
<details>
<summary><b>¿Puedo usar solo algunos componentes (por ejemplo, solo los agentes)?</b></summary>
Sí. Usa la Opción 2 (instalación manual) y copia solo lo que necesites:
- **Cursor**: Configuraciones pre-traducidas en `.cursor/`. Consulta [Soporte para Cursor IDE](#soporte-para-cursor-ide).
- **Gemini CLI**: Soporte experimental local al proyecto mediante `.gemini/GEMINI.md` y conexiones compartidas del instalador.
- **OpenCode**: Soporte completo del plugin en `.opencode/`. Consulta [Soporte para OpenCode](#soporte-para-opencode).
- **Codex**: Soporte de primera clase para la app macOS y CLI, con guardias de deriva del adaptador y fallback de SessionStart. Consulta PR [#257](https://github.com/affaan-m/ECC/pull/257).
- **GitHub Copilot (VS Code)**: Capa de instrucciones y prompts mediante `.github/copilot-instructions.md`, `.vscode/settings.json` y `.github/prompts/`. Consulta [Soporte para GitHub Copilot](#soporte-para-github-copilot).
- **Antigravity**: Configuración estrechamente integrada para flujos de trabajo, skills y reglas aplanadas en `.agents/`. Consulta la [Guía de Antigravity](../ANTIGRAVITY-GUIDE.md).
- **JoyCode / CodeBuddy**: Adaptadores de instalación selectiva locales al proyecto para comandos, agentes, skills y reglas aplanadas. Consulta la [Guía del Adaptador JoyCode](../JOYCODE-GUIDE.md).
- **Qwen CLI**: Adaptador de instalación selectiva en el directorio home para comandos, agentes, skills, reglas y configuración de Qwen. Consulta la [Guía del Adaptador Qwen CLI](../QWEN-GUIDE.md).
- **Zed**: Adaptador de instalación selectiva local al proyecto para `.zed/settings.json`, reglas aplanadas, comandos, agentes y skills.
- **Harnesses no nativos**: Ruta de respaldo manual para Grok e interfaces similares. Consulta la [Guía de Adaptación Manual](../MANUAL-ADAPTATION-GUIDE.md).
- **Claude Code**: Nativo — este es el objetivo principal.
</details>
<details>
<summary><b>¿Cómo contribuyo con una nueva skill o agente?</b></summary>
Consulta [CONTRIBUTING.md](CONTRIBUTING.md). La versión corta:
1. Haz fork del repo
2. Crea tu skill en `skills/tu-nombre-de-skill/SKILL.md` (con frontmatter YAML)
3. O crea un agente en `agents/tu-agente.md`
4. Envía un PR con una descripción clara de qué hace y cuándo usarlo
</details>
---
## Ejecutar Pruebas
El plugin incluye una suite de pruebas completa:
```bash
# Ejecutar todas las pruebas
node tests/run-all.js
# Ejecutar archivos de prueba individuales
node tests/lib/utils.test.js
node tests/lib/package-manager.test.js
node tests/hooks/hooks.test.js
```
---
## Contribuir
**Las contribuciones son bienvenidas y fomentadas.**
Este repo está pensado para ser un recurso comunitario. Si tienes:
- Agentes o skills útiles
- Hooks ingeniosos
- Mejores configuraciones de MCP
- Reglas mejoradas
¡Contribuye! Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para las directrices.
### Ideas para Contribuciones
- Skills específicas de lenguaje (Rust, C#, Kotlin, Java) — Go, Python, Perl, Swift, TypeScript y HarmonyOS/ArkTS ya están incluidos
- Configs específicas de frameworks (Rails, FastAPI) — Django, NestJS, Spring Boot y Laravel ya están incluidos
- Agentes de DevOps (Kubernetes, Terraform, AWS, Docker)
- Estrategias de prueba (diferentes frameworks, regresión visual)
- Conocimiento de dominio específico (ML, ingeniería de datos, móvil)
### Notas del Ecosistema Comunitario
Estos no están empaquetados con ECC y no son auditados por este repo, pero vale la pena conocerlos si estás explorando el ecosistema más amplio de skills de Claude Code:
- [claude-seo](https://github.com/AgriciDaniel/claude-seo) — Colección de skills y agentes centrados en SEO
- [claude-ads](https://github.com/AgriciDaniel/claude-ads) — Colección de flujos de trabajo de auditoría de anuncios y crecimiento de pago
- [claude-cybersecurity](https://github.com/AgriciDaniel/claude-cybersecurity) — Colección de skills y agentes orientados a seguridad
---
## Soporte para Cursor IDE
ECC proporciona soporte para Cursor IDE con hooks, reglas, agentes, skills, comandos y configuraciones de MCP adaptados para el diseño de proyecto de Cursor.
### Inicio Rápido (Cursor)
```bash
# macOS/Linux
./install.sh --target cursor typescript
./install.sh --target cursor python golang swift php
```
```powershell
# Windows PowerShell
.\install.ps1--targetcursortypescript
.\install.ps1--targetcursorpythongolangswiftphp
```
### Qué Incluye
| Componente | Cantidad | Detalles |
|------------|---------|---------|
| Eventos de Hook | 15 | sessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt, y 10 más |
| Scripts de Hook | 16 | Scripts Node.js delgados que delegan a `scripts/hooks/` mediante adaptador compartido |
| Comandos | Compartidos | `.cursor/commands/` si se instala |
| Configuración MCP | Compartida | `.cursor/mcp.json` si se instala |
### Notas de Carga en Cursor
ECC no instala el `AGENTS.md` raíz en `.cursor/`. Cursor trata los archivos `AGENTS.md` anidados como contexto de directorio, por lo que copiar la identidad del repo de ECC en un proyecto host contaminaría ese proyecto.
El comportamiento de carga nativo de Cursor puede variar según la versión. ECC instala agentes como `.cursor/agents/ecc-*.md`; si tu versión de Cursor no expone los agentes del proyecto, esos archivos siguen funcionando como definiciones de referencia explícitas en lugar de contexto de prompt global oculto.
### Arquitectura de Hooks (Patrón de Adaptador DRY)
Cursor tiene **más eventos de hook que Claude Code** (20 vs 8). El módulo `.cursor/hooks/adapter.js` transforma el JSON de stdin de Cursor al formato de Claude Code, permitiendo reutilizar los `scripts/hooks/*.js` existentes sin duplicación.
```
JSON de stdin de Cursor → adapter.js → transforma → scripts/hooks/*.js
(compartido con Claude Code)
```
Hooks clave:
- **beforeShellExecution** — Bloquea servidores de desarrollo fuera de tmux (exit 2), revisión de git push
- **afterFileEdit** — Auto-formato + verificación de TypeScript + advertencia de console.log
- **beforeTabFileRead** — Bloquea a Tab de leer archivos .env, .key, .pem (exit 2)
- **beforeMCPExecution / afterMCPExecution** — Registro de auditoría de MCP
### Formato de Reglas
Las reglas de Cursor usan frontmatter YAML con `description`, `globs` y `alwaysApply`:
```yaml
---
description:"TypeScript coding style extending common rules"
globs:["**/*.ts","**/*.tsx","**/*.js","**/*.jsx"]
alwaysApply:false
---
```
---
## Soporte para Codex macOS App + CLI
ECC proporciona **soporte de primera clase para Codex** tanto para la app macOS como para el CLI, con una configuración de referencia, un suplemento AGENTS.md específico de Codex y skills compartidas.
### Inicio Rápido (Codex App + CLI)
```bash
# Ejecutar Codex CLI en el repo — AGENTS.md y .codex/ se detectan automáticamente
codex
# Configuración automática: sincronizar activos de ECC (AGENTS.md, skills, servidores MCP) en ~/.codex
npm install && bash scripts/sync-ecc-to-codex.sh
# O manualmente: copiar la configuración de referencia a tu directorio home
cp .codex/config.toml ~/.codex/config.toml
```
El script de sincronización fusiona de forma segura los servidores MCP de ECC en tu `~/.codex/config.toml` existente usando una estrategia **solo de adición** — nunca elimina ni modifica tus servidores existentes. Ejecuta con `--dry-run` para previsualizar los cambios, o `--update-mcp` para forzar la actualización de los servidores ECC a la configuración recomendada más reciente.
### Qué Incluye
| Componente | Cantidad | Detalles |
|------------|---------|---------|
| Configuración | 1 | `.codex/config.toml` — aprobaciones de nivel superior/sandbox/web_search, servidores MCP, notificaciones, perfiles |
| Herramientas Personalizadas | Mediante hooks | 6 nativas | **OpenCode es mejor** |
---
## Soporte para GitHub Copilot
ECC proporciona **soporte para GitHub Copilot** para VS Code mediante el sistema nativo de archivos de instrucciones y prompts de Copilot Chat — sin herramientas adicionales necesarias.
### Qué Incluye
| Componente | Archivo | Propósito |
|------------|---------|-----------|
| Instrucciones principales | `.github/copilot-instructions.md` | Reglas siempre cargadas: estilo de código, seguridad, pruebas, flujo de git |
| Prompt de plan | `.github/prompts/plan.prompt.md` | Planificación de implementación por fases |
| Prompt de TDD | `.github/prompts/tdd.prompt.md` | Ciclo Rojo-Verde-Mejorar |
| Prompt de revisión de seguridad | `.github/prompts/security-review.prompt.md` | Análisis de seguridad profundo alineado con OWASP |
| Prompt de corrección de build | `.github/prompts/build-fix.prompt.md` | Resolución sistemática de errores de build y CI |
| Prompt de refactorización | `.github/prompts/refactor.prompt.md` | Limpieza de código muerto y simplificación |
### Inicio Rápido (GitHub Copilot)
Los archivos ya están en su lugar — abre cualquier repo que contenga este proyecto y GitHub Copilot Chat recogerá automáticamente `.github/copilot-instructions.md`.
El `.vscode/settings.json` confirmado habilita `chat.promptFiles` para que VS Code pueda cargar los prompts reutilizables de `.github/prompts/`.
Para usar los prompts de flujo de trabajo en Copilot Chat:
1. Abre el panel de Copilot Chat en VS Code.
2. Haz clic en el icono de **clip / adjuntar** y selecciona **Prompt...**, o escribe `/` y elige un prompt.
He estado usando Claude Code desde el lanzamiento experimental. Gané el hackathon de Anthropic x Forum Ventures en sep 2025 con [@DRodriguezFX](https://x.com/DRodriguezFX) — construí [zenith.chat](https://zenith.chat) completamente usando Claude Code.
Estas configuraciones han sido probadas en múltiples aplicaciones de producción.
---
## Optimización de Tokens
El uso de Claude Code puede ser costoso si no gestionas el consumo de tokens. Estas configuraciones reducen significativamente los costos sin sacrificar calidad.
### Configuración Recomendada
Añade a `~/.claude/settings.json`:
```json
{
"model":"sonnet",
"env":{
"MAX_THINKING_TOKENS":"10000",
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE":"50"
}
}
```
| Configuración | Por defecto | Recomendado | Impacto |
| `model` | opus | **sonnet** | ~60% de reducción de costos; maneja más del 80% de las tareas de codificación |
| `MAX_THINKING_TOKENS` | 31,999 | **10,000** | ~70% de reducción en el costo de pensamiento oculto por solicitud |
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 95 | **50** | Compacta antes — mejor calidad en sesiones largas |
| `ECC_CONTEXT_MONITOR_COST_WARNINGS` | on | **off para suscriptores** | Suprime las advertencias de estimación de tasa de API frente al agente manteniendo las advertencias de contexto/alcance/bucle |
Cambia a Opus solo cuando necesites razonamiento arquitectónico profundo:
```
/model opus
```
### Comandos del Flujo de Trabajo Diario
| Comando | Cuándo usarlo |
|---------|---------------|
| `/model sonnet` | Por defecto para la mayoría de las tareas |
| `/clear` | Entre tareas no relacionadas (gratis, restablecimiento instantáneo) |
| `/compact` | En puntos de quiebre lógicos de tareas |
| `/cost` | Monitorear el gasto de tokens durante la sesión |
### Compactación Estratégica
La skill `strategic-compact` (incluida en este plugin) sugiere `/compact` en puntos de quiebre lógicos en lugar de depender de la auto-compactación al 95% del contexto.
**Cuándo compactar:**
- Después de investigación/exploración, antes de la implementación
- Después de completar un hito, antes de empezar el siguiente
- Después de depurar, antes de continuar con el trabajo de features
- Después de un enfoque fallido, antes de probar uno nuevo
**Cuándo NO compactar:**
- A mitad de la implementación (perderás nombres de variables, rutas de archivos, estado parcial)
---
## ADVERTENCIA: Notas Importantes
### Optimización de Tokens
¿Alcanzando los límites diarios? Consulta la **[Guía de Optimización de Tokens](../token-optimization.md)** para configuraciones recomendadas y consejos de flujo de trabajo.
Ganancias rápidas:
```json
// ~/.claude/settings.json
{
"model":"sonnet",
"env":{
"MAX_THINKING_TOKENS":"10000",
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE":"50",
"CLAUDE_CODE_SUBAGENT_MODEL":"haiku"
}
}
```
### Personalización
Estas configuraciones funcionan para mi flujo de trabajo. Deberías:
1. Empezar con lo que resuene
2. Modificar para tu stack
3. Eliminar lo que no uses
4. Añadir tus propios patrones
---
## Proyectos de la Comunidad
Proyectos construidos sobre o inspirados en ECC:
| Proyecto | Descripción |
|----------|-------------|
| [EVC](https://github.com/SaigonXIII/evc) | Espacio de trabajo para agentes de marketing — 42 comandos para operadores de contenido, gobernanza de marca y publicación multicanal. [Resumen visual](https://saigonxiii.github.io/evc). |
| [trading-skills](https://github.com/VictorVVedtion/trading-skills) | 68 skills de Claude Code temáticas de trading con prompts de revisión pre-trade y puertas de riesgo inspiradas en operadores de mercado. |
¿Construiste algo con ECC? Abre un PR para añadirlo aquí.
---
## Patrocinadores
Este proyecto es gratuito y de código abierto. Los patrocinadores ayudan a mantenerlo y hacerlo crecer.
[**Conviértete en Patrocinador**](https://github.com/sponsors/affaan-m) | [Niveles de Patrocinio](SPONSORS.md) | [Programa de Patrocinio](SPONSORING.md)
---
## Historial de Estrellas
[](https://star-history.com/#affaan-m/ECC&Date)
---
## Enlaces
- **Guía Resumida (Empieza aquí):** [La Guía Resumida de Everything Claude Code](https://x.com/affaanmustafa/status/2012378465664745795)
- **Guía Extensa (Avanzado):** [La Guía Extensa de Everything Claude Code](https://x.com/affaanmustafa/status/2014040193557471352)
- **Guía de Seguridad:** [Guía de Seguridad](../../the-security-guide.md) | [Hilo](https://x.com/affaanmustafa/status/2033263813387223421)
