**Idioma:** [English](../../README.md) | [Português (Brasil)](../pt-BR/README.md) | [简体中文](../../README.zh-CN.md) | [繁體中文](../zh-TW/README.md) | [日本語](../ja-JP/README.md) | [한국어](../ko-KR/README.md) | [Türkçe](../tr/README.md) | [Русский](../ru/README.md) | [Tiếng Việt](../vi-VN/README.md) | [ไทย](../th/README.md) | [Deutsch](../de-DE/README.md) | **Español**

# ECC

![ECC - el sistema operativo nativo del harness para trabajo agentivo](../../assets/hero.png)

[![Stars](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Fstars&style=flat)](https://github.com/affaan-m/ECC/stargazers)
[![Forks](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Fforks&style=flat)](https://github.com/affaan-m/ECC/network/members)
[![Contributors](https://img.shields.io/github/contributors/affaan-m/ECC?style=flat)](https://github.com/affaan-m/ECC/graphs/contributors)
[![npm ecc-universal](https://img.shields.io/npm/dw/ecc-universal?label=ecc-universal%20weekly%20downloads&logo=npm)](https://www.npmjs.com/package/ecc-universal)
[![npm ecc-agentshield](https://img.shields.io/npm/dw/ecc-agentshield?label=ecc-agentshield%20weekly%20downloads&logo=npm)](https://www.npmjs.com/package/ecc-agentshield)
[![GitHub App Install](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Finstalls&logo=github)](https://github.com/marketplace/ecc-tools)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
![Shell](https://img.shields.io/badge/-Shell-4EAA25?logo=gnu-bash&logoColor=white)
![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white)
![Python](https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white)
![Go](https://img.shields.io/badge/-Go-00ADD8?logo=go&logoColor=white)
![Java](https://img.shields.io/badge/-Java-ED8B00?logo=openjdk&logoColor=white)
![Perl](https://img.shields.io/badge/-Perl-39457E?logo=perl&logoColor=white)
![Markdown](https://img.shields.io/badge/-Markdown-000000?logo=markdown&logoColor=white)

> **182K+ estrellas** | **28K+ forks** | **170+ contribuidores** | **12+ ecosistemas de lenguajes** | **Flujos de trabajo de agentes multi-harness**

---

<div align="center">

**Language / 语言 / 語言 / Dil / Язык / Ngôn ngữ / Idioma**

[**English**](../../README.md) | [Português (Brasil)](../pt-BR/README.md) | [简体中文](../../README.zh-CN.md) | [繁體中文](../zh-TW/README.md) | [日本語](../ja-JP/README.md) | [한국어](../ko-KR/README.md)
 | [Türkçe](../tr/README.md) | [Русский](../ru/README.md) | [Tiếng Việt](../vi-VN/README.md) | [ไทย](../th/README.md) | [Deutsch](../de-DE/README.md) | **Español**

</div>

---

**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).

---

<table>
<tr>
<td width="25%" align="center">
  <a href="https://ecc.tools/pricing">
    <strong> ECC Pro</strong><br />
    <sub>Repos privados · GitHub App · $19/asiento/mes</sub>
  </a>
</td>
<td width="25%" align="center">
  <a href="https://github.com/sponsors/affaan-m">
    <strong> Patrocinar</strong><br />
    <sub>Financia el OSS · Desde $5/mes</sub>
  </a>
</td>
<td width="25%" align="center">
  <a href="https://github.com/affaan-m/ECC/discussions">
    <strong>Comunidad</strong>
    <br />
    <sub>Discusiones · Preguntas · Showcase</sub>
  </a>
</td>
<td width="25%" align="center">
  <a href="https://github.com/apps/ecc-tools">
    <strong> GitHub App</strong><br />
    <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.

<table>
<tr>
<td width="33%">
<a href="https://x.com/affaanmustafa/status/2012378465664745795">
<img src="../../assets/images/guides/shorthand-guide.png" alt="La Guía Resumida de ECC" />
</a>
</td>
<td width="33%">
<a href="https://x.com/affaanmustafa/status/2014040193557471352">
<img src="../../assets/images/guides/longform-guide.png" alt="La Guía Extensa de ECC" />
</a>
</td>
<td width="33%">
<a href="https://x.com/affaanmustafa/status/2033263813387223421">
<img src="../../assets/images/security/security-guide-header.png" alt="La Guía de Seguridad Agentiva" />
</a>
</td>
</tr>
<tr>
<td align="center"><b>Guía Resumida</b><br/>Configuración, fundamentos, filosofía. <b>Empieza aquí.</b></td>
<td align="center"><b>Guía Extensa</b><br/>Optimización de tokens, persistencia de memoria, evaluaciones, paralelización.</td>
<td align="center"><b>Guía de Seguridad</b><br/>Vectores de ataque, sandboxing, sanitización, CVEs, AgentShield.</td>
</tr>
</table>

| Tema | Qué aprenderás |
|------|----------------|
| Optimización de Tokens | Selección de modelos, reducción de system prompts, procesos en segundo plano |
| Persistencia de Memoria | Hooks que guardan/cargan contexto entre sesiones automáticamente |
| Aprendizaje Continuo | Extrae patrones de las sesiones y los convierte en skills reutilizables |
| Bucles de Verificación | Evaluaciones de checkpoint vs. continuas, tipos de evaluadores, métricas pass@k |
| Paralelización | Git worktrees, método cascada, cuándo escalar instancias |
| 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ô** — `ito-market-intelligence`, `ito-basket-compare`, `ito-trade-planner`, `ito-data-atlas-agent`, `prediction-market-oracle-research` y `prediction-market-risk-review` añaden flujos de trabajo públicos de mercado/cartera 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.
- **Nuevos comandos del harness** — `/harness-audit`, `/loop-start`, `/loop-status`, `/quality-gate`, `/model-route`.
- **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
- **5 nuevas skills genéricas de negocio/contenido** — `article-writing`, `content-engine`, `market-research`, `investor-materials`, `investor-outreach`
- **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
- **7 nuevas skills** — `search-first`, `swift-actor-persistence`, `swift-protocol-di-testing`, `regex-vs-llm-structured-text`, `content-hash-cache-pattern`, `cost-aware-llm-pipeline`, `skill-stocktake`
- **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)
- **3 herramientas personalizadas nativas** — run-tests, check-coverage, security-audit
- **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-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:

```bash
./install.sh --profile minimal --target claude
```

```powershell
.\install.ps1 --profile minimal --target claude
# o
npx ecc-install --profile minimal --target claude
```

Este perfil excluye intencionalmente `hooks-runtime`.

Si quieres el perfil core normal pero necesitas desactivar los hooks, usa:

```bash
./install.sh --profile core --without baseline:hooks --target claude
```

Añade hooks después solo si quieres aplicación en tiempo de ejecución:

```bash
./install.sh --target claude --modules hooks-runtime
```

### Encuentra primero los componentes correctos

Si no estás seguro de qué perfil o componente de ECC instalar, consulta al asesor empaquetado desde cualquier proyecto:

```bash
npx ecc consult "security reviews" --target claude
```

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:

```bash
npx ecc consult "mlops training model deployment" --target claude
npx ecc install --profile minimal --target claude --with capability:machine-learning
```

### Paso 1: Instalar el Plugin (Recomendado)

> 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.

```bash
# Agregar marketplace
/plugin marketplace add https://github.com/affaan-m/ECC

# Instalar plugin
/plugin install ecc@ecc
```

### Nota de Nombres y Migración

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-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)
npm install        # o: pnpm install | yarn install | bun install

# Ruta de plugin: copiar solo las reglas de ECC en un espacio de nombres propio
mkdir -p ~/.claude/rules/ecc
cp -R rules/common ~/.claude/rules/ecc/
cp -R rules/typescript ~/.claude/rules/ecc/

# Ruta de instalación completamente manual (usa esto en lugar de /plugin install)
# ./install.sh --profile full
```

```powershell
# Windows PowerShell

# Ruta de plugin: copiar solo las reglas de ECC en un espacio de nombres propio
New-Item -ItemType Directory -Force -Path "$HOME/.claude/rules/ecc" | Out-Null
Copy-Item -Recurse rules/common "$HOME/.claude/rules/ecc/"
Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/ecc/"

# Ruta de instalación completamente manual (usa esto en lugar de /plugin install)
# .\install.ps1 --profile full
# npx ecc-install --profile full
```

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:

```bash
./install.sh --profile full
```

```powershell
.\install.ps1 --profile full
# o
npx ecc-install --profile full
```

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
5. **Configuración global**: `~/.claude/package-manager.json`
6. **Alternativa**: Primer gestor de paquetes disponible

Para establecer tu gestor de paquetes preferido:

```bash
# Mediante variable de entorno
export CLAUDE_PACKAGE_MANAGER=pnpm

# Mediante configuración global
node scripts/setup-package-manager.js --global pnpm

# Mediante configuración del proyecto
node scripts/setup-package-manager.js --project bun

# Detectar configuración actual
node scripts/setup-package-manager.js --detect
```

O usa el comando `/setup-pm` en Claude Code.

### Controles de Ejecución de Hooks

Usa flags de ejecución para ajustar la estrictez o deshabilitar hooks específicos temporalmente:

```bash
# Perfil de estrictez del hook (por defecto: standard)
export ECC_HOOK_PROFILE=standard

# IDs de hooks separados por coma para deshabilitar
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

# Limitar el contexto adicional de SessionStart (por defecto: 8000 caracteres)
export ECC_SESSION_START_MAX_CHARS=4000

# Deshabilitar completamente el contexto adicional de SessionStart para configuraciones de bajo contexto/modelo local
export ECC_SESSION_START_CONTEXT=off

# Mantener advertencias de contexto/alcance/bucle pero suprimir estimaciones de costo por tasa de API
export ECC_CONTEXT_MONITOR_COST_WARNINGS=off
```

Windows PowerShell:

```powershell
[Environment]::SetEnvironmentVariable('ECC_CONTEXT_MONITOR_COST_WARNINGS', 'off', 'User')
```

---

## Qué Incluye

Este repo es un **plugin de Claude Code** — instálalo directamente o copia componentes manualmente.

```
ECC/
|-- .claude-plugin/   # Manifiestos del plugin y marketplace
|   |-- plugin.json         # Metadatos del plugin y rutas de componentes
|   |-- marketplace.json    # Catálogo del marketplace para /plugin marketplace add
|
|-- agents/           # 63 subagentes especializados para delegación
|   |-- planner.md           # Planificación de implementación de features
|   |-- architect.md         # Decisiones de diseño del sistema
|   |-- tdd-guide.md         # Desarrollo guiado por pruebas
|   |-- code-reviewer.md     # Revisión de calidad y seguridad
|   |-- security-reviewer.md # Análisis de vulnerabilidades
|   |-- build-error-resolver.md
|   |-- e2e-runner.md        # Pruebas E2E con Playwright
|   |-- refactor-cleaner.md  # Limpieza de código muerto
|   |-- doc-updater.md       # Sincronización de documentación
|   |-- docs-lookup.md       # Búsqueda de documentación/API
|   |-- chief-of-staff.md    # Clasificación de comunicaciones y borradores
|   |-- loop-operator.md     # Ejecución autónoma de bucles
|   |-- harness-optimizer.md # Ajuste de configuración del harness
|   |-- cpp-reviewer.md      # Revisión de código C++
|   |-- cpp-build-resolver.md # Resolución de errores de build en C++
|   |-- fsharp-reviewer.md   # Revisión de código funcional en F#
|   |-- go-reviewer.md       # Revisión de código Go
|   |-- go-build-resolver.md # Resolución de errores de build en Go
|   |-- python-reviewer.md   # Revisión de código Python
|   |-- database-reviewer.md # Revisión de base de datos/Supabase
|   |-- typescript-reviewer.md # Revisión de código TypeScript/JavaScript
|   |-- java-reviewer.md     # Revisión de código Java/Spring Boot
|   |-- java-build-resolver.md # Errores de build en Java/Maven/Gradle
|   |-- kotlin-reviewer.md   # Revisión de código Kotlin/Android/KMP
|   |-- kotlin-build-resolver.md # Errores de build en Kotlin/Gradle
|   |-- harmonyos-app-resolver.md # Desarrollo de apps HarmonyOS/ArkTS
|   |-- rust-reviewer.md     # Revisión de código Rust
|   |-- rust-build-resolver.md # Resolución de errores de build en Rust
|   |-- pytorch-build-resolver.md # Errores de entrenamiento PyTorch/CUDA
|   |-- mle-reviewer.md      # Revisión de pipeline de ML en producción, evaluación, serving y monitoreo
|
|-- skills/           # Definiciones de flujos de trabajo y conocimiento de dominio
|   |-- coding-standards/           # Mejores prácticas por lenguaje
|   |-- clickhouse-io/              # Analytics en ClickHouse, consultas, ingeniería de datos
|   |-- backend-patterns/           # Patrones de API, base de datos, caché
|   |-- frontend-patterns/          # Patrones de React, Next.js
|   |-- frontend-slides/            # Presentaciones HTML y flujos de trabajo de conversión PPTX a web (NUEVO)
|   |-- article-writing/            # Escritura de formato largo con voz propia sin tono genérico de IA (NUEVO)
|   |-- content-engine/             # Contenido social multiplataforma y flujos de reutilización (NUEVO)
|   |-- market-research/            # Investigación de mercado, competidores e inversores con fuentes (NUEVO)
|   |-- investor-materials/         # Pitch decks, one-pagers, memos y modelos financieros (NUEVO)
|   |-- investor-outreach/          # Alcance personalizado de fundraising y seguimiento (NUEVO)
|   |-- continuous-learning/        # Patrón legado v1 de extracción con hook Stop
|   |-- continuous-learning-v2/     # Aprendizaje basado en instintos con puntuación de confianza
|   |-- iterative-retrieval/        # Refinamiento progresivo de contexto para subagentes
|   |-- strategic-compact/          # Sugerencias de compactación manual (Guía Extensa)
|   |-- tdd-workflow/               # Metodología TDD
|   |-- security-review/            # Lista de verificación de seguridad
|   |-- eval-harness/               # Evaluación de bucle de verificación (Guía Extensa)
|   |-- verification-loop/          # Verificación continua (Guía Extensa)
|   |-- videodb/                   # Video y audio: ingestión, búsqueda, edición, generación, streaming (NUEVO)
|   |-- golang-patterns/            # Modismos y mejores prácticas de Go
|   |-- golang-testing/             # Patrones de pruebas en Go, TDD, benchmarks
|   ...
|
|-- commands/         # Compatibilidad mantenida de entradas slash; preferir skills/
|-- rules/            # Directrices de cumplimiento obligatorio (copiar a ~/.claude/rules/ecc/)
|-- hooks/            # Automatizaciones basadas en eventos
|-- scripts/          # Scripts Node.js multiplataforma (NUEVO)
|-- tests/            # Suite de pruebas (NUEVO)
|-- contexts/         # Inyección dinámica de contexto en el system prompt
|-- examples/         # Configuraciones y sesiones de ejemplo
|-- mcp-configs/      # Configuraciones de servidores MCP
|-- ecc_dashboard.py  # Dashboard GUI de escritorio (Tkinter)
|-- marketplace.json  # Configuración del marketplace autoalojado
```

---

## Herramientas del Ecosistema

### Creador de Skills

Dos formas de generar skills de Claude Code desde tu repositorio:

#### Opción A: Análisis Local (Integrado)

Usa el comando `/skill-create` para análisis local sin servicios externos:

```bash
/skill-create                    # Analizar el repo actual
/skill-create --instincts        # También generar instintos para continuous-learning-v2
```

Esto analiza tu historial de git localmente y genera archivos SKILL.md.

#### Opción B: GitHub App (Avanzado)

Para características avanzadas (más de 10k commits, PRs automáticos, compartir en equipo):

[Instalar GitHub App](https://github.com/apps/skill-creator) | [ecc.tools](https://ecc.tools)

```bash
# Comenta en cualquier issue:
/skill-creator analyze

# 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).

[GitHub](https://github.com/affaan-m/agentshield) | [npm](https://www.npmjs.com/package/ecc-agentshield)

### Aprendizaje Continuo v2

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:

```bash
# Añadir este repo como marketplace
/plugin marketplace add https://github.com/affaan-m/ECC

# Instalar el plugin
/plugin install ecc@ecc
```

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
cp -r rules/python ~/.claude/rules/ecc/
cp -r rules/golang ~/.claude/rules/ecc/
cp -r rules/php ~/.claude/rules/ecc/
cp -r rules/arkts ~/.claude/rules/ecc/

# Instalar skills con el instalador consciente de migraciones.
# Conserva skills del usuario, informa conflictos y evita sobrescribirlos.
node scripts/install-apply.js --target claude --modules workflow-quality

# Opcional: instalar skills concretas solo cuando las necesites.
node scripts/install-apply.js --target claude --skills search-first
# node scripts/install-apply.js --target claude --skills django-patterns,django-tdd

# 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
```

```powershell
# Windows PowerShell
pwsh -File .\install.ps1 --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:

```bash
export ECC_DISABLED_MCPS="github,context7,exa,playwright,sequential-thinking,memory"
```

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:

```json
{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
  "hooks": [{
    "type": "command",
    "command": "#!/bin/bash\ngrep -n 'console\\.log' \"$file_path\" && echo '[Hook] Remove console.log' >&2"
  }]
}
```

### Reglas

Las reglas son directrices de cumplimiento obligatorio, organizadas en `common/` (agnóstico al lenguaje) + directorios específicos por lenguaje:

```
rules/
  common/          # Principios universales (siempre instalar)
  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 |
|-----------|---------------------|--------------|
| Planificar una nueva feature | `/ecc:plan "Añadir auth"` | planner |
| Diseñar arquitectura del sistema | `/ecc:plan` + agente architect | architect |
| Escribir código con pruebas primero | skill `tdd-workflow` | tdd-guide |
| Revisar código que acabo de escribir | `/code-review` | code-reviewer |
| Corregir un build fallido | `/build-fix` | build-error-resolver |
| Ejecutar pruebas end-to-end | skill `e2e-testing` | e2e-runner |
| Encontrar vulnerabilidades de seguridad | `/security-scan` | security-reviewer |
| Eliminar código muerto | `/refactor-clean` | refactor-cleaner |
| Actualizar documentación | `/update-docs` | doc-updater |
| Revisar código Go | `/go-review` | go-reviewer |
| Revisar código Python | `/python-review` | python-reviewer |
| Revisar código F# | *(invocar `fsharp-reviewer` directamente)* | fsharp-reviewer |
| Revisar código TypeScript/JavaScript | *(invocar `typescript-reviewer` directamente)* | typescript-reviewer |
| Desarrollar apps HarmonyOS | *(invocar `harmonyos-app-resolver` directamente)* | harmonyos-app-resolver |
| 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"
                                              → planner crea el blueprint de implementación
skill tdd-workflow                            → tdd-guide refuerza escribir pruebas primero
/code-review                                  → code-reviewer verifica tu trabajo
```

**Corrigiendo un bug:**
```
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

Ejemplo mínimo:

```bash
export ANTHROPIC_BASE_URL=https://your-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=your-token
claude
```

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:

```bash
# Solo agentes
cp agents/*.md ~/.claude/agents/

# Solo reglas
mkdir -p ~/.claude/rules/ecc/
cp -r rules/common ~/.claude/rules/ecc/
```

Cada componente es completamente independiente.
</details>

<details>
<summary><b>¿Funciona con Cursor / OpenCode / Codex / Antigravity / GitHub Copilot?</b></summary>

Sí. ECC es multiplataforma:
- **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 `.agent/`. 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 --target cursor typescript
.\install.ps1 --target cursor python golang swift php
```

### 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 |
| Reglas | 34 | 9 comunes (alwaysApply) + 25 específicas de lenguaje (TypeScript, Python, Go, Swift, PHP) |
| Agentes | 48 | `.cursor/agents/ecc-*.md` cuando se instala; con prefijo para evitar colisiones con agentes de usuario o marketplace |
| Skills | Compartidas + Empaquetadas | `.cursor/skills/` para adiciones traducidas |
| 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
- **beforeSubmitPrompt** — Detecta secretos (sk-, ghp_, patrones AKIA) en prompts
- **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 |
| AGENTS.md | 2 | Raíz (universal) + `.codex/AGENTS.md` (suplemento específico de Codex) |
| Skills | 32 | `.agents/skills/` — SKILL.md + agents/openai.yaml por skill |
| Servidores MCP | 6 | GitHub, Context7, Exa, Memory, Playwright, Sequential Thinking |
| Perfiles | 2 | `strict` (sandbox de solo lectura) y `yolo` (auto-aprobación completa) |
| Roles de Agente | 3 | `.codex/agents/` — explorer, reviewer, docs-researcher |

---

## Soporte para OpenCode

ECC proporciona **soporte completo para OpenCode** incluyendo plugins y hooks.

### Inicio Rápido

```bash
# Instalar OpenCode
npm install -g opencode

# Ejecutar en la raíz del repositorio
opencode
```

La configuración se detecta automáticamente desde `.opencode/opencode.json`.

### Paridad de Características

| Característica | Claude Code         | OpenCode | Estado |
|----------------|---------------------|----------|--------|
| Agentes | 63 agentes | 12 agentes | **Claude Code lidera** |
| Comandos | 79 comandos | 35 comandos | **Claude Code lidera** |
| Skills | 249 skills | 37 skills | **Claude Code lidera** |
| Hooks | 8 tipos de eventos | 11 eventos | **¡OpenCode tiene más!** |
| Reglas | 29 reglas | 13 instrucciones | **Claude Code lidera** |
| Servidores MCP | 14 servidores | Completo | **Paridad completa** |
| 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 |
| Configuración de VS Code | `.vscode/settings.json` | Archivos de instrucciones por tarea para generación de código, pruebas y mensajes de commit |
| 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.
3. Selecciona el prompt (por ejemplo, `plan`, `tdd`, `security-review`).

---

## Compatibilidad Cross-Tool

ECC es el **primer plugin que maximiza todas las principales herramientas de codificación con IA**. Así se compara cada harness:

| Característica | Claude Code           | Cursor IDE | Codex CLI | OpenCode | GitHub Copilot |
|----------------|-----------------------|------------|-----------|----------|----------------|
| **Agentes** | 63                    | Compartidos (AGENTS.md) | Compartidos (AGENTS.md) | 12 | N/A |
| **Comandos** | 79                    | Compartidos | Basados en instrucciones | 35 | 5 prompts |
| **Skills** | 249                   | Compartidas | 10 (formato nativo) | 37 | Mediante instrucciones |
| **Eventos de Hook** | 8 tipos               | 15 tipos | Ninguno aún | 11 tipos | Ninguno |
| **Scripts de Hook** | 20+ scripts           | 16 scripts (adaptador DRY) | N/A | Hooks de plugin | N/A |
| **Reglas** | 34 (común + lenguaje) | 34 (frontmatter YAML) | Basadas en instrucciones | 13 instrucciones | 1 archivo siempre activo |
| **Herramientas Personalizadas** | Mediante hooks        | Mediante hooks | N/A | 6 herramientas nativas | N/A |
| **Servidores MCP** | 14                    | Compartidos (mcp.json) | 7 (fusión automática vía parser TOML) | Completo | N/A |
| **Formato de Configuración** | settings.json         | hooks.json + rules/ | config.toml | opencode.json | copilot-instructions.md + settings.json |
| **Archivo de Contexto** | CLAUDE.md + AGENTS.md | AGENTS.md | AGENTS.md | AGENTS.md | copilot-instructions.md |

---

## Antecedentes

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 |
| `/model opus` | Arquitectura compleja, depuración, razonamiento profundo |
| `/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

[![Star History Chart](https://api.star-history.com/svg?repos=affaan-m/ECC&type=Date)](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)
- **Seguir:** [@affaanmustafa](https://x.com/affaanmustafa)

---

## Licencia

MIT - Úsalo libremente, modifícalo según tus necesidades, contribuye de vuelta si puedes.

---

**Dale una estrella al repo si te ayuda. Lee las dos guías. Construye algo grandioso.**
