@event4u/agent-config

Agent Config — cada afirmación verificada por máquina, incluido "cero demonio en tiempo de ejecución"

Pruébalo en 30 segundos — coloca un subagente de solo lectura en cualquier repositorio y observa cómo marca "hecho": @production-validator check this branch is actually done. Sin asistentes, sin bloqueo, sin nada más que instalar — la cuña de 30 segundos ↓ es todo el primer paso. Empieza por la prueba, no por el catálogo: event4u-app.github.io/agent-config/proof/.

Cada afirmación pública en este README está verificada por máquina — compruébalo tú mismo. En un mercado que se basa en cifras destacadas sin respaldo, este vincula cada afirmación a evidencia resoluble o falla en su propia compilación.

Elige tu experiencia — desarrollador · fundador · contenido · agencia · finanzas · operaciones. Añade paquetes. Obtén un conjunto de comandos enfocado, no un volcado de 500 artefactos. Trae tu propio proveedor de IA.

Una biblioteca profunda de habilidades, comandos y reglas gobernadas — además de un enrutador de capacidades que carga la habilidad correcta según la intención y orquestación multiagente con revisión por consenso. Toda la capa se compila en 20 agentes anfitriones — de 23 detectados, 3 solo de exportación (Claude Code, Cursor, Augment, Cline, Windsurf, Copilot, Gemini CLI, Codex, Continue, Zed, JetBrains, Aider y más) — con cero demonio en tiempo de ejecución. Seis rutas de entrada con forma de rol se sitúan encima, de modo que cualquier anfitrión se convierte en un miembro confiable del equipo — sin bloquearte a un solo modelo o proveedor.

Qué es diferente

Es profundo y disciplinado — y honesto sobre lo que deliberadamente no es:

• Profundidad que se enruta sola — una biblioteca profunda de habilidades y comandos, con un enrutador de capacidades que carga la correcta según la intención, no un volcado de contexto de 500 artefactos.
• Gobernanza en cada anfitrión — reglas compiladas en el formato nativo de cada herramienta en el momento de la proyección; ganchos de ejecución deterministas añadidos en anfitriones con capacidad de ganchos. Esta gobernanza en el espacio de configuración, agnóstica al anfitrión, es el foso (la ventaja de la gobernanza · aplicación por anfitrión).
• Desinstalación quirúrgica — elimina solo sus propias claves de una configuración de anfitrión compartida (coincidencia por puntero JSON + SHA-256), nunca las entradas de una herramienta vecina.
• Instalación con ámbito de paquete — escribe solo el paquete activo, no un volcado de 500 artefactos.

Lo que deliberadamente no es — el núcleo es una capa de gobernanza con motores integrados opcionales y de aceptación individual (inteligencia de código, alcance restringido, la GUI de configuración, el laboratorio de pruebas — ADR-124): sin demonio en segundo plano, sin base de datos de estado separada, sin memoria que se reescribe sola, sin pipeline de compilación automática. Los motores nunca son obligatorios, nunca están activados por defecto sin una mejora medida, y terminan con el comando que los invocó. El agente anfitrión ejecuta el bucle; cada cambio aprendido es revisado por humanos; la misma capa sigue siendo portátil entre herramientas. Capacidad sin un proceso que cuidar.

De dónde viene esto (procedencia honesta). Las habilidades, reglas y personas se destilan de trabajo de producción real en bases de código TypeScript y PHP. La mecánica de gobernanza es agnóstica al stack, pero las heurísticas de dominio son más ricas donde se forjaron — trata la cobertura en otros stacks como prometedora, no probada, y cuéntanos dónde se queda corta.

Consulta exactamente qué funciona en qué anfitrión o salta a cosas que puedes hacer en un minuto.

Elige tu perfil — seis rutas de entrada

agent-config setup escribe profile.id en .agent-settings.yml; cada ancla abajo es la primera pantalla a la que el asistente te envía. Un README, seis entradas, sin adivinanzas de detección de rol.

Perfil (profile.id)	Audiencia	Primeros comandos	Primeras habilidades
👩‍💻 developer	Ingeniero IC	/implement-ticket · /work · /review-changes · /fix · /commit	developer-like-execution · verify-completion-evidence · minimal-safe-diff · systematic-debugging · test-driven-development
✍️ content_creator	Escritores, redactores fantasma, especialistas en marketing	/work · /post-as · /ghostwriter · /optimize-prompt · /video:from-script · /video:storyboard	voice-and-tone-design · messaging-architecture · editorial-calendar · release-comms · character-consistency
🚀 founder	Fundador en solitario / etapa temprana	/work · /feature · /challenge-me · /council	refine-prompt · rice-prioritization · vision-articulation · fundraising-narrative · runway-cognition
🏛 agency	Taller de entrega multicliente	/work · /implement-ticket · /refine-ticket · /feature · /roadmap	doc-coauthoring · decision-record · refine-ticket · estimate-ticket · perf-feedback-craft
💼 finance	CFO / finanzas fraccionadas / FP&A	/work · /council · /challenge-me	dcf-modeling · forecasting · scenario-modeling · unit-economics-modeling · runway-cognition
🛡 ops	RevOps, soporte, adyacente a SRE	/work · /threat-model · /review-changes · /fix	incident-commander · dashboard-design · logging-monitoring · threat-modeling · launch-readiness

¿No estás seguro de cuál? Ejecuta npx @event4u/agent-config init y luego agent-config setup — el asistente del navegador hace una única pregunta de rol con 8 opciones y mapea al perfil más cercano. Fuente de verdad: src/agent-src/profiles/ · esquema: docs/contracts/profile-system.md. Más allá del software: user-types/ (galabau · metalurgia · camiones — consulta Más allá del software.

Páginas de experiencia por perfil (para quién es · primeras tareas · paquetes + flujos · qué no está cargado · ejemplos): desarrollador · creador_de_contenido · fundador · agencia · finanzas · operaciones.

Flujos de trabajo, no comandos en bruto

No memorizas cada comando — ejecutas un viaje de trabajo. Cuatro flujos abarcan la historia del desarrollador de principio a fin; cada uno nombra el comando que ESCRIBES para comenzar y las habilidades que compone:

Flujo	Comienza con	El viaje
🔍 Descubrimiento	/feature:plan · /research	explorar → planificar → estimar → refinar, antes de construir
🔨 Implementación	/work · /implement-ticket	planificar → implementar → verificar → confirmar
🔎 Revisión	/review-changes · /judge	auto-revisión → juez → corrección de calidad → modelo de amenazas
🚢 Entrega	/commit · /pr:create	confirmar en fragmentos → abrir PR → responder revisión

Detalle completo — comandos de entrada, ruta canónica, habilidades compuestas por flujo: docs/flows.md. (agent-admin — memoria / analítica / configuración — es operación de plataforma, no un flujo de trabajo de usuario.)

CHANGELOG · Actualizar a 6.0 · Cambios disruptivos · Última versión · Discusiones

_{Distribución: npm install @event4u/agent-config. Los incrementos mayores siguen semver; cada uno incluye una entrada ### Breaking — todos los mayores están indexados en BREAKING_CHANGES.md.}

---

Paquete Creativo — video cinematográfico con IA. guion → imagen con personaje bloqueado → prompt de movimiento+audio → renderizado del proveedor → clip cosido, con AIV_DRYRUN=true como el valor predeterminado de seguridad de costos. Una capacidad de primera clase dentro de la experiencia de contenido / creador — ya no es el titular del paquete. Consulta /video:from-script.

Paquete Legal — no es asesoramiento legal. El paquete legal UE/DE (revisión de contratos/NDA/DPA, triaje) es solo una ayuda de investigación y redacción — no proporciona asesoramiento legal, no reemplaza a un abogado calificado y no debe usarse como base para ningún asunto concreto. Produce información general y plantillas generales, nunca examen de casos individuales. Lee LEGAL_NOTICE.md antes de usarlo.

Catálogo completo — cada habilidad, regla, comando, directriz: docs/catalog.md. El titular es la experiencia (perfil + paquetes) y la profundidad detrás de ella.

Úsalo en tu proyecto

Ejecuta desde un repositorio de consumo — arranca mediante npx, el agente detecta tu stack y entregas trabajo de principio a fin. ¿Instalación nueva? Comienza con la Guía de inicio rápido. ¿Ya instalado? Herramientas compatibles muestra las IA conectadas; docs/featured-commands.md enumera los flujos de trabajo de extremo a extremo (/implement-ticket, /work, /commit, /pr:create). Recorrido más profundo: demo de 2 minutos.

Alcance de instalación. Elige un alcance por máquina — local al proyecto (predeterminado, recomendado para repositorios de aplicaciones) o global al usuario (recomendado para repositorios de herramientas / dotfiles). El instalador rechaza un segundo alcance conflictivo mediante la verificación previa scope_guard. Detalles: docs/contracts/install-scopes.md. Limpieza cuando sea necesario: bash src/scripts/cleanup_other_scope.sh --confirm.

Pruébalo

No tomes las afirmaciones por confianza — verifícalas. docs/proof.md se genera desde la fuente: una tabla de afirmación→evidencia (cada afirmación pública se vincula a un puntero resoluble o la CI falla), benchmarks honestos de nulos incluyendo las ejecuciones donde el paquete no cambió nada y un bloque de "verifícalo tú mismo" que ejecutas en una copia nueva. La página de prueba falla en la CI si se desvía de sus fuentes — la reproducibilidad es la prueba. Explórala en el sitio de documentación desplegado — la página de prueba es la entrada principal: event4u-app.github.io/agent-config/proof/. El marco de comparación honesto vive en docs/us-vs-the-category.md. Fila medida más reciente: en una sesión posterior a la corrección, la inyección de contexto de asesoría redujo las violaciones de espejo de lenguaje 555 → 19 mientras que los dos bloqueos pasaron de 8 → 0 y 1 → 0 — la asesoría se redujo masivamente, solo el bloqueo se eliminó. Una sesión y una lectura posterior, así que es un antecedente registrado, no una ley.

¿Mantienes tu propio catálogo de habilidades? La puerta anti-revestimiento que bloquea los PR de re-revestimiento por buscar-y-reemplazar aquí también funciona en tu catálogo — docs/anti-reskin-gate.md.

Disciplinado para auditoría por construcción — cada consulta de memoria, clave de decisión y preocupación de gancho termina en agents/runtime/state/ para que puedas reproducirlo. Principios fundamentales nombra los cuatro invariantes; Qué es agent-config — y qué no es dibuja el límite del alcance.

Contribuye

¿Trabajas en el paquete mismo? Desarrollo cubre el pipeline task ci, Requisitos la cadena de herramientas, Telemetría del mantenedor el bucle de medición opcional. El árbol de fuente de verdad es src/ (src/skills, src/rules, src/agent-src/); nunca edites a mano .augment/ o dist/agent-src/.

Seguridad. Política de divulgación: SECURITY.md. Modelo de amenazas: docs/threat-model.md.

---

Guía de inicio rápido

Prueba una cosa en 30 segundos — antes de la suite completa, coloca un subagente autónomo y ve la disciplina en tu propio repositorio:

mkdir -p .claude/agents
curl -fsSL https://raw.githubusercontent.com/event4u-app/agent-config/main/docs/wedge/production-validator/production-validator.md \
  -o .claude/agents/production-validator.md
# then in Claude Code:  @production-validator check this branch is actually done

production-validator es de solo lectura y no instala nada más: marca "done" (terminado) buscando mocks/stubs en la ruta enviada y exigiendo evidencia del sistema real (qué hace). ¿Te gusta? Instala el paquete completo:

Un solo comando. Impulsado por detección: tus herramientas de IA instaladas se encuentran y se preseleccionan. No se escribe nada hasta que haces clic en Finalizar. Sin YAML a mano.

Esos cuatro son estructurales: se mantienen en cada ejecución, porque son propiedades de la ruta del código, no de tu máquina. Cuánto tiempo toma no es uno de ellos: eso está dominado por la latencia de red y del registro, que no controlamos. El tiempo de pared de instalación → doctor lo mide CI en cada ejecución general y se publica con sus condiciones, como evidencia; nunca es un número prometido.

# 1. Install — on a terminal with a display, the browser wizard launches
#    automatically; the same TypeScript installer runs the real install behind it.
npx -y @event4u/agent-config init

# 2. Pick your profile + tools in the wizard, click Finish.
#    (Writes ~/.event4u/agent-config/, ~/.claude/, ~/.cursor/, …)

# 3. First real task — agent refines, plans, verifies.
/work "your first real task"

Headless / CI: init omite la GUI automáticamente en CI, en un no-TTY, en un host headless y siempre que esté presente cualquier indicador de modo CLI; luego ejecuta el instalador no interactivo directamente. El conjunto completo de exclusión se lista una vez, contra el código, en gui-wizard § Cuándo se omite la GUI. Pasa indicadores (--profile=balanced --tools=claude-code,cursor); agrega --dry-run para previsualizar escrituras. La GUI y la CLI comparten un instalador (src/scripts/install.ts), por lo que ambos producen resultados idénticos. Referencia: docs/wizard.md.

Elige IAs específicas: --tools=claude-code,cursor,augment,windsurf,cline,gemini-cli,copilot,roocode,aider,codex,claude-desktop,continue (cualquier subconjunto). Selector visual: agrega --gui (enlazado a loopback, protegido por CSRF; contrato gui-wizard). --gui es una opción voluntaria que fuerza al asistente más allá de las comprobaciones de TTY y headless — no anula CI, AGENT_CONFIG_NO_UI ni un indicador de modo CLI; combinarlo con uno de esos sale con código distinto de cero en lugar de ejecutar silenciosamente la instalación CLI. En un host headless agrega --allow-headless y conecta un navegador a la URL impresa.

Verifica la cobertura de hooks: npx @event4u/agent-config hooks:status imprime la matriz por plataforma (--strict para CI, --format json para herramientas).

Alcance (v2.5+): init escribe global únicamente — ~/.event4u/agent-config/, ~/.claude/, ~/.cursor/, …. El árbol del proyecto recibe solo agents/overrides/ (el marcador de puente se retiró — enmienda ADR-020 2026-07-13; la raíz global se resuelve desde ~/.event4u/agent-config). --project es solo para mantenedores detrás de AGENT_CONFIG_DEV_MODE=1 (ADR-020, modo dev).

¿Migrando desde una instalación v1.x? npx @event4u/agent-config migrate — notas completas en docs/migration/v1-to-v2.md.

---

Qué es agent-config — y qué no es

Una capa de contenido — habilidades, reglas, comandos, pautas, personas — distribuida vía npm y proyectada en el formato de configuración nativo de cada herramienta de IA compatible. Sigue el estándar abierto Agent Skills.

No es un runtime de agente. El bucle del agente, el despachador de LLM y la orquestación de herramientas permanecen en la herramienta anfitriona (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI, Copilot). Piénsalo como un manual de jugadas y una guía de estilo para esas herramientas — no un reemplazo.

En alcance	Fuera de alcance
Habilidades, reglas, comandos, pautas, personas	Bucle del agente / despachador de LLM
Proyección multi-herramienta + pipeline de condensación	Motor de ejecución dentro del paquete
Ayudantes de memoria (memory-add, memory-promote)	Panel de observabilidad entre herramientas
Linters, CI, validación de frontmatter contra JSON-Schema (contrato)	GUI de runtime / panel web
Orquestación de habilidades vía citas + ayudantes deterministas	Resolvedor de habilidades automático opinado (clasificación ML / relevancia que decide por ti)
Filtrado por perfil + packs en tiempo de proyección impulsado por el usuario (ADR-040)	Un resolvedor / daemon de runtime (cambio a mitad de sesión — condicional, posterior a 6.0.0)

Qué se le pide a tu agente

Comportamiento predeterminado	Con agent-config
Adivinar y editar a ciegas	Analizar el código antes de cambiarlo
Desviarse de las convenciones del proyecto	Seguir las convenciones de stack detectadas
Omitir o inventar pruebas	Escribir pruebas en el framework del proyecto
Mensajes de commit genéricos	Conventional Commits con alcance + enlaces de ticket
Omitir comprobaciones de calidad	Ejecutar el pipeline de calidad del proyecto y corregir errores reportados
Abrir PRs sin contexto	Descripciones de PR estructuradas desde Jira / Linear / GitHub
Afirmar "done" sin prueba	Verificar con ejecución real antes de afirmar done

---

Demo de 2 minutos — /implement-ticket

El comando insignia. Conduce un ticket de principio a fin a través de un flujo lineal fijo — y se detiene ante la ambigüedad en lugar de adivinar.

/implement-ticket PROJ-123

El agente ejecuta esta secuencia:

refine → memory → analyze → plan → implement → test → verify → report

• Refina el ticket si los criterios de aceptación son vagos.
• Consulta la memoria para decisiones pasadas, invariantes, incidentes.
• Planifica el cambio; confirmas antes de que se toque cualquier archivo.
• Implementa bajo minimal-safe-diff + scope-control — sin ediciones al paso.
• Prueba (dirigido primero, suite completa si tiene éxito).
• Revisa el diff a través de cuatro jueces (errores, seguridad, pruebas, calidad de código).
• Reporta cambios, veredictos, seguimientos — luego se detiene. /commit y /pr:create son sugerencias, nunca auto-ejecutadas.

Cualquier ambigüedad detiene el flujo con opciones numeradas — nunca una suposición silenciosa. La persona proviene de .agent-settings.yml (roles.active_role): senior-engineer (predeterminado), qa o advisory (solo plan).

→ Referencia de comandos · Contrato de flujo

Hermano — /work (prompt de forma libre)

Mismo motor, sin ticket requerido:

/work add a CSV export endpoint to the audit-log controller

La primera pasada puntúa el prompt en cinco dimensiones y enruta según la banda:

Banda	Puntaje	Acción
alta	≥ 0.8	Proceder silencioso — AC + suposiciones en el reporte
media	0.5–0.79	Se detiene con reporte de suposiciones; confirma o edita
baja	< 0.5	Se detiene con una pregunta aclaratoria sobre la dimensión más débil

Después de la compuerta de banda, el flujo es idéntico a /implement-ticket. Objetivo de forma libre → /work; payload de ticket → /implement-ticket.

→ Referencia de comandos · habilidad refine-prompt

Después de la ejecución: agent-config explain last reconstruye el rastro (ruta · memoria · consejo · detenciones · proveedor) — solo lectura, sin PII, sin conexión. Docs

Pista de UI de producto

El trabajo con forma de UI se enruta a uno de tres conjuntos de directivas — ui (auditoría completa→diseño→aplicar→revisar→pulir→reportar), ui-trivial (≤ 1 archivo, ≤ 5 líneas: aplicar→probar→reportar), mixed (backend + UI: contrato→ui→unir). La auditoría de UI existente es una compuerta dura (ui-audit-gate); el pulido tiene un límite de 2 rondas con precedencia de accesibilidad. Detección de stack → blade-livewire-flux / react-shadcn / vue / plain.

→ Modelo mental (1 página) · Contrato de flujo

---

Personalizar

Perfiles — cuánta gobernanza se carga

El piso de seguridad (predeterminados no destructivos · preguntar antes de adivinar · reflejar el idioma del usuario) se incluye en cada perfil. Lo que cambia es cuánto entrenamiento adicional se incorpora.

Perfil	Qué obtienes	Cuándo elegirlo
minimal	Solo el piso de seguridad no negociable. Más barato, más rápido.	Preguntas rápidas · scripts desechables · CI · presupuestos de tokens ajustados
balanced (predeterminado)	Piso de seguridad + entrenamiento cotidiano (predeterminados sensatos, recordatorios de revisión, errores comunes).	Trabajo diario
full	Todo, incluidas reglas de cola larga que normalmente solo necesitan los mantenedores.	Trabajar en agent-config mismo · auditorías · demos de máxima fidelidad

Bajo el capó: solo kernel · kernel + nivel 1 · kernel + nivel 1 + nivel 2. Detalles: rule-router · kernel-membership · Configurar →.

Estabilidad: STABILITY.md para la matriz completa. Work Engine (/work + /implement-ticket): beta. Runtime Dispatcher: estable. Tool Adapters: experimental (perfil full únicamente).

.agent-user.md y Ghostwriter — primitivas de voz

Primitiva	Voz	Divulgación
personas/*.md	Lente de revisión (crítica interna)	n/a
.agent-user.md (raíz del proyecto, gitignored)	La propia voz del mantenedor — /post-as:me	Ninguna (tú eres el autor)
agents/reference/ghostwriter/<slug>.md (gitignored)	Figura pública documentada — /post-as:ghostwriter	Pie de página obligatorio, no removible

Crea el archivo de usuario interactivamente: /agents user init (esquema). Clúster de Ghostwriter: /ghostwriter:fetch <url-or-name> ejecuta una compuerta de atestación; individuos privados rechazados; contenido de pago / filtrado / DM prohibido a nivel de esquema.

MCP auto-alojado en Cloudflare — cero instalación local

Las habilidades, comandos, reglas y pautas pueden servirse como un endpoint MCP desde tu propio Cloudflare Worker — cualquier cliente MCP (Claude Desktop, Claude Code, Cursor, Zed, Continue, agentes alojados) habla con él sobre HTTP. Dos modos de autenticación: public (predeterminado, despliegues OSS de solo lectura) y bearer-auth (opt-in del operador, secreto MCP-Token de Wrangler).

task mcp:cloud:login         # one-time, opens browser
task mcp:cloud:setup         # check → r2-create → r2-verify → whoami
task mcp:cloud:secret-put    # opt in to bearer-auth (recommended for private deploys)

→ Tutorial del operador: mcp-cloud-setup · Configuración por cliente: mcp-client-config · Endpoints: mcp-cloud-endpoints.

Alcance — Lite, no Full. El Worker sirve gobernanza de solo lectura (habilidades · comandos · reglas · pautas · contextos) como prompts y recursos MCP, además de pequeñas herramientas de solo lectura (memory_lookup, chat_history_read, list_*). No ejecuta los ~112 scripts de Python (linters, auditorías, task ci, hooks de work-engine) — esos requieren instalación local según Quickstart.

El servidor local stdio integrado se lista para descubrimiento en el Glama MCP Registry (desarrolladores de agentes / contribuidores; requiere un checkout local, no una instalación llave en mano — ver ADR-067).

Postura de despliegue

Forma	Estado	Ruta
Espacio de trabajo de un solo usuario	✅ hoy	npx @event4u/agent-config init — una máquina, un usuario; sin sincronización remota
Equipo pequeño (3–10 personas)	✅ hoy	Repo Git agents/overrides/ compartido + NAS compartido para conocimiento — sin cambio de código, sin nuevo servidor. Receta: docs/deploy/small-team-recipe.md
Modo organización (SSO · política central · contexto de equipo · conectores internos)	⏸ no iniciado	Cada forma condicionada a un cliente reclutado + auditoría financiada + ADR de mantenedor. Racional de postura: docs/deploy/team-deployment-posture.md

El Piso Duro en las características de modo organización (SSO, política central, conectores OAuth, contexto de equipo) se preserva por diseño — permanecen canceladas hasta que un primer cliente real + auditoría de seguridad financiada las levante. La receta de equipo pequeño es la ruta compatible mientras tanto.

La ronda de retroalimentación 9.3/10 (2026-05-25) volvió a pedir conectores de conocimiento OAuth, gobernanza IAM / org y memoria compartida de organización. Cada una es una fila de cancelación estable en team-deployment-posture bajo las mismas tres compuertas de lanzamiento — cliente de equipo reclutado · auditoría financiada · ADR de mantenedor.

---

Expectativas del harness

Tres clases de comportamiento de instalación/runtime parecen errores de paquete pero son comportamiento del harness anfitrión que el paquete no puede controlar — espacios de nombres de plugins hermanos (codex:*, cc-gemini-plugin:*), herramientas diferidas expuestas vía ToolSearch y deriva de habilidades entre alcances (error real, corregido en la pista de canales de distribución). Diagnósticos + la respuesta del paquete: docs/contracts/harness-expectations.md. Primer paso cuando una habilidad aparece dos veces: task probe:skills.

Herramientas compatibles

Instaladas en el proyecto (npx)

Herramienta	Reglas	Habilidades	Comandos	Cómo funciona
Claude Code	✅	✅	✅	Lee .claude/
Cursor	✅	—	☑️	Lee .cursor/rules/ + comandos vía AGENTS.md
Cline	✅	—	☑️	Lee .clinerules/ + comandos vía AGENTS.md
Windsurf	✅	—	☑️	Lee .windsurfrules + comandos vía AGENTS.md
Gemini CLI	✅	—	☑️	Lee GEMINI.md
GitHub Copilot	✅	—	☑️	Lee .github/copilot-instructions.md
Roo Code	✅	—	☑️	Auto-descubre .roo/rules/*.md + AGENTS.md
Codex CLI	✅	—	☑️	Auto-descubre AGENTS.md
Continue.dev	✅	—	☑️	Auto-descubre .continue/rules/*.md + AGENTS.md
Aider	📌	—	—	read: manual en .aider.conf.yml
Augment (VSCode/IntelliJ)	📌	—	—	Solo global; el proyecto escribe marcador
Claude Desktop	📌	—	—	Solo global

✅ nativo   ☑️ referencia de texto (en AGENTS.md, no invocable como comando slash nativo)   📌 solo marcador   — no disponible

Reproducibilidad del equipo: cada herramienta que init queda registrada en agents/installed-tools.lock (confirmado, gestionado por máquina). Los nuevos miembros del equipo ejecutan npx @event4u/agent-config sync después de clonar; CI limita la deriva con agent-config validate. Esquema: installed-tools-manifest.

Instalado por plugin (opcional, global)

Herramienta	Instalación
Augment CLI · Copilot CLI	Instalar → — reglas + habilidades + comandos, actualizado por marketplace

Claude Code: el plugin del marketplace está obsoleto (modelo de superficie única). La proyección de archivos npx/npm ahora lleva contenido y los hooks deterministas (registrados en un bloque ~/.claude/settings.json gestionado por agent-config global / upgrade), por lo que el plugin solo duplica los listados de habilidades/comandos mientras su instantánea git-SHA se pudre silenciosamente. Instalaciones existentes: claude plugin uninstall agent-config@event4u-agent-config — agent-config doctor marca la superficie duplicada.

Mantén la instalación global actualizada con agent-config upgrade (última) o agent-config refresh --global (reinstalación de la misma versión); agent-config doctor marca un binario faltante de PATH o un cableado de hooks roto. Consulta getting-started § Mantenerse actualizado · Solución de problemas.

La superficie de comandos de un vistazo

Comando	Qué hace
agent-config init	Instalación de una sola vez — abre el asistente del navegador (ruta recomendada o paso a paso)
agent-config init --project	Inicializa un proyecto: puente agents/ mínimo + bloque .gitignore gestionado
agent-config config	Abre la GUI de configuración — centro de ajustes global (niveles simple + avanzado, búsqueda, restablecer a valores predeterminados)
agent-config config --project	Abre la superficie de configuración del proyecto
agent-config setup	Vuelve a ejecutar el asistente de incorporación guiado (prellenado desde tu estado actual)
agent-config upgrade	Actualiza la instalación global a la última versión + sincroniza ajustes de forma aditiva
agent-config doctor	Informe de salud/deriva de solo lectura

Superficies de nube / agente alojado

Para plataformas donde los scripts del paquete no pueden ejecutarse, los artefactos se construyen para pegar o subir:

• Linear AI (Codegen, Charlie, …) — dist/linear/{workspace,team,personal}.md
• Claude.ai Web Skills — dist/cloud/<skill>.zip

→ Instalar →

---

Funciona con agent-switch

agent-switch es el CLI compañero para ejecutar varias cuentas de agente en una sola máquina: aísla cada cuenta en su propio perfil (CLAUDE_CONFIG_DIR por perfil), por lo que cambiar de cuenta nunca significa cerrar sesión y volver a entrar. Los dos se componen — agent-switch aísla las cuentas, agent-config gobierna lo que los agentes hacen dentro de ellas. Cuando agent-config se ejecuta bajo un perfil de agent-switch lo indica en el centro de configuración, advierte antes de escrituras que aterrizarían en un árbol compartido (entre perfiles), y acepta una raíz de configuración proporcionada por el host para que sus propios ajustes permanezcan con ámbito de perfil.

→ Cómo se componen los dos →

---

Para quién es esto

Núcleo de gobernanza agnóstico de pila (orquestación · modos de rol · clústeres de comandos · puertas de calidad · disciplina de auditoría) más conjuntos de habilidades específicos de pila en paralelo:

Pila	Cobertura
Laravel · PHP moderno (más profundo)	Pest · PHPStan · Rector · ECS · Eloquent · Livewire/Flux · Horizon · Pulse · Reverb · Pennant
Symfony	symfony-workflow (DI · Doctrine · Messenger · voters · Twig) + análisis de proyecto
Next.js App Router	nextjs-patterns (RSC · Server Actions · caching · route handlers) + UI react-shadcn
Zend / Laminas	análisis de proyecto + habilidades compartidas de coder/calidad PHP
React · Node / Express	análisis de proyecto + UI react-shadcn
Vue · HTML plano	conjunto de directivas UI (vue / plain)
Multi-pila	diseño de API · pruebas · seguridad · base de datos · Docker · Git · CI · revisión · modelado de amenazas · observabilidad

Más allá del software

El mismo núcleo de orquestación impulsa oficios no relacionados con software vía user-types/: galabau-field-crew · metalworking-shop · truck-driver. Contribuye con el tuyo — andamiaje de 5 minutos.

---

Gobernanza de datos y seguridad de dominio

Tres reglas de seguridad de dominio (domain-safety-pii, domain-safety-disclaimer, domain-safety-retention) actúan como pisos de salida por dominio en ~12 áreas — redacción de PII (soporte / finanzas / reclutamiento / marketing), avisos de asesoramiento (legal / financiero / médico / consultoría), orientación de retención (finanzas / soporte), pisos operativos (registro / exportación). Matriz completa de superficie → regla → piso: docs/safety.md. Contratos beta: memory-visibility-v1 · decision-trace-v1.

Procedencia de código y gobernanza de licencias

Cada diff se verifica contra una política de licencias derivada de la licencia detectada del propio repositorio objetivo (LICENSE/package.json/composer.json, ordenadas por precedencia; las fuentes discrepan → escalar, nunca adivinar) y un linter estricto sobre nuestro propio libro de préstamos (provenance/borrows.jsonl → docs/THIRD-PARTY-NOTICES.md) que falla ante una licencia de clase denegada, una licencia desconocida, una nota de transformación faltante o una redactada solo como cambio de nombre — conectado a ci/ci-strict desde el primer día. Una tercera pieza, license-compliance-audit, ejecuta un escaneo de similitud offline/online bajo demanda — un humano lo invoca deliberadamente, nunca un pipeline. Esto es disciplina de préstamo gobernada por procedencia, aplicada por política de licencias respaldada por un rastro de préstamos auditado — no un detector de copias.

Alcance y límites

• La reproducción inconsciente de datos de entrenamiento no es detectable en esta capa. Ninguna herramienta aquí — ni en ningún lugar — puede ver qué contenía los datos de entrenamiento de un modelo; este sistema gobierna lo que se toma prestado conscientemente y se registra, nunca lo que un modelo recuerda silenciosamente.
• La detección, donde existe, cubre una base de conocimiento de solo OSS conocido — un subconjunto de todo el código que ha existido, nunca el corpus de entrenamiento de un modelo.
• No existe una puerta de detección orientada a CI. Se construyó un escáner determinista (jscpd offline + SCANOSS online) y se midió contra un corpus sintético congelado, pero no alcanzó sus propios umbrales pre-registrados (medido: recall 12/16, falsos positivos 2/12, recall de solo cambio de nombre de SCANOSS 0/8) — ver docs/CLAIMS.md. Se envía en ninguna forma en CI, ni siquiera como asesoramiento — solo como la habilidad bajo demanda anterior.
• El lavado de solo cambio de nombre no se detecta por nada de lo que enviamos o evaluamos. La verificación de nota de transformación del libro rechaza una nota redactada solo como cambio de nombre, pero no puede atrapar una copia de solo cambio de nombre no divulgada que nunca se registró.

Reduce y documenta el riesgo — nunca lo elimina.

Telemetría de mantenedores (opt-in, desactivada por defecto)

Registro de participación de artefactos solo local. Establece telemetry.artifact_engagement.enabled: true en .agent-settings.yml. Registra qué habilidades / reglas / comandos / pautas consulta el agente durante /implement-ticket / /work. JSONL bajo la raíz del proyecto, nada se sube. Informes: npx @event4u/agent-config telemetry:report.

Sugerencia de comandos consciente del contexto

Cuando un prompt coincide con el propósito de un comando ("setze ticket ABC-123 um" → /implement-ticket), el agente muestra coincidencias como opciones numeradas — nada se auto-ejecuta. Desactivación por conversación: /command-suggestion-off. Ajustes: commands.suggestion.{enabled,blocklist,confidence_floor} en .agent-settings.yml.

---

Principios fundamentales

• Analizar antes de implementar — sin adivinanzas, sin ediciones a ciegas
• Verificar con ejecución real — sin "debería funcionar"
• Desafiar para mejorar — los agentes son socios de pensamiento, no máquinas de sí
• Estricto por diseño — calidad sobre flexibilidad
• Cero sobrecarga por defecto — nada se ejecuta hasta que lo pidas

---

Documentación

Documento	Contenido
Getting Started	Primera ejecución, experiencia de 3 pruebas, perfiles, próximos pasos
Instalación	Todas las rutas de instalación, Composer/npm, detalles del orquestador
Arquitectura	Capas del sistema, pipeline de contenido, matriz de soporte de herramientas
Personalización	Anulaciones, AGENTS.md, ajustes de agente, perfiles de costo
Calidad y CI	Linting, pipeline de CI, sistema de condensación
Migración	Pasos de actualización por versión
Showcase	Más ejemplos y comportamiento esperado

Explora el contenido: todos los comandos · catálogo de habilidades · catálogo completo · llms.txt.

---

Solución de problemas

Primera parada para cualquier problema de instalación: agent-config doctor — marca un binario faltante de PATH, deriva de versión binario↔plugin, huérfanos obsoletos y problemas de manifiesto, cada uno con una pista de corrección de una línea.

Para preguntas de "¿por qué no se disparó la regla/hook X?": agent-config routing:doctor — un diagnóstico en vivo de solo lectura que informa cada puerta de inicio de sesión como ACTIVO/INACTIVO con la razón propia de la preocupación (p. ej. session-canary: ACTIVE for "Alex" vs INACTIVO — sin nombre en ninguna capa de ajustes), la cadena de preocupaciones de la plataforma, el registro de hooks del host, y la frescura del router + proyección. Internos más profundos de hooks (postura fail-open/closed, último comentario del despachador por preocupación): agent-config hooks:doctor.

Falta un nuevo comando / habilidad en Claude Code después de una actualización

Bajo el modelo de superficie única, agent-config upgrade actualiza la proyección de archivos ~/.claude/ — ESA es la superficie de contenido, por lo que una sesión nueva recoge los nuevos comandos directamente. Si los comandos aún faltan, la causa habitual es un plugin de marketplace sobrante: es una instantánea git-SHA que nunca se mueve con la actualización de npm y no oculta nada — solo lista todo dos veces mientras se queda atrás. Elimínalo:

claude plugin uninstall agent-config@event4u-agent-config

Luego inicia una sesión nueva de Claude Code. agent-config doctor informa un plugin sobrante como claude-plugin: duplicate surface; los hooks no se ven afectados (viven en un bloque ~/.claude/settings.json gestionado — verifica con la verificación hook-wiring).

Las habilidades / comandos aparecen dos veces en Claude Code

Misma causa que arriba: el plugin de marketplace obsoleto está instalado junto a la proyección de archivos ~/.claude/, por lo que cada habilidad se lista simple y con prefijo agent-config:. Desinstala el plugin (comando anterior) e inicia una sesión nueva.

agent-config upgrade falla con Unknown argument: --no-ui

Error conocido en 8.2.0: upgrade pasó una bandera --no-ui que el orquestador de instalación aún no aceptaba, por lo que la ejecución se abortó temprano. Corregido en main; hasta la próxima versión, solucionalo con:

AGENT_CONFIG_NO_UI=1 agent-config global   # refresh the global install, no wizard

La actualización se interrumpió (Ctrl-C, asistente cerrado, paso fallido)

Solo el npm install -g inicial aborta de forma forzosa una actualización. Cada paso posterior (re-despliegue global con registro de hooks, sincronización de ajustes, actualización de wrapper + git-hooks) se ejecuta de forma independiente — un único paso fallido se reporta en el resumen final de la ejecución en lugar de omitir silenciosamente el resto. Vuelve a ejecutar agent-config upgrade para converger y usa agent-config doctor para nombrar cualquier cosa que quede en un estado mixto.

agent-config: command not found / los hooks dejaron de dispararse

Los hooks en tiempo de ejecución resuelven el binario global en PATH — una instalación solo a nivel de proyecto no es suficiente para ellos. Reinstala el binario:

npm install -g @event4u/agent-config
agent-config doctor   # verifies PATH + plugin wiring

Los archivos del proyecto se ven desactualizados tras una actualización de paquete

Las proyecciones a nivel de proyecto solo se reescriben en una actualización explícita:

agent-config refresh             # re-apply the installed version to this project
agent-config refresh --global    # same-version re-install of the global root

Más pasos por versión: Migración · getting-started § Mantenerse al día.

---

Desarrollo

¿Trabajando en el propio paquete? Edita src/ (la fuente de verdad — src/skills, src/rules, src/agent-src/), regenera los árboles:

task sync             # regenerate dist/agent-src/ and .augment/
task generate-tools   # regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
task ci               # full pipeline — green before PR
task test             # unit + integration tests
task dev:setup        # boot the onboarding wizard against the working tree

Invocar la CLI desde un checkout del código fuente: ./agent-config <command> (el shim de mantenimiento en la raíz del repo → scripts/agent-config → dist/cli/agent-config.js). npx @event4u/agent-config no se resuelve en el repo fuente sin un npm link previo, ya que no hay un symlink node_modules/.bin/agent-config — usa ./agent-config en su lugar. Compila el binario TS con npm run build:cli si dist/cli/agent-config.js falta.

→ Estructura completa del proyecto y comandos: docs/development.md · CONTRIBUTING.md. Stack: TypeScript CLI/UI + Python 3.10+ scripts de build/lint. Los payloads del registro MCP se renderizan bajo dist/mcp/ (lista de verificación de envío).

---

Requisitos

• Node ≥ 20.11 — npx @event4u/agent-config init es la ruta de instalación canónica. Sin Python en la ruta de instalación (el instalador de Python se retiró con la migración a TypeScript).
• Plataforma: macOS 12.3+, Linux, WSL2. Git Bash necesita el Modo Desarrollador para symlinks. Los contribuidores que reconstruyan .augment/ también necesitan Task.

Windows

PowerShell / cmd nativo no es compatible para la instalación de archivos — usa WSL2 para el árbol instalado completo. La superficie nativa de Windows compatible es el servidor MCP stdio: apunta cualquier cliente MCP a

npx -y @event4u/agent-config mcp-server

y el contenido de gobernanza (prompts, recursos, herramientas) está disponible sin la instalación de archivos. Portar el dispatcher bash a Windows nativo está condicionado a la demanda: un adoptante de Windows nombrado que no pueda usar WSL2 o la ruta MCP lo reabre (ver agents/roadmaps/ — road-to-credible-install Fase 3).

Financiación

El paquete es gratuito, MIT, y seguirá siéndolo — sin nivel de pago, sin doble licencia. Si te ahorra tiempo y quieres contribuir, el botón de GitHub Sponsor en la parte superior del repo es todo el mecanismo. Si prefieres no hacerlo, úsalo de todos modos; nada aquí depende de ello.

Licencia

MIT.

mcp-name: io.github.event4u-app/agent-config