Custom Harness: ingeniería multiagente bajo tu control

Soy Fernando Gómez y construí Custom Harness para convertir el trabajo con agentes de código en un proceso que puedas entender, adaptar y gobernar. Coordina leader, implementer y reviewer sin quitarte el control sobre las decisiones ni sobre tu repositorio.

Lo hice porque la velocidad no sirve de mucho cuando un mismo agente planea, implementa y aprueba su propio trabajo. La separación de roles, las pruebas y una revisión independiente devuelven al desarrollo con IA los límites que exige la ingeniería real.

Mi filosofía es sencilla: herramientas pequeñas, componibles y fáciles de cambiar. El harness aporta disciplina sin adueñarse de tu proceso; tú defines las políticas, el contexto y el nivel de autonomía.

La idea

Los agentes de código pueden avanzar rápido y aun así dejar un resultado difícil de confiar: el mismo agente planea, implementa y aprueba; las tareas grandes consumen el contexto; una validación tardía descubre cambios parciales; y cada repositorio termina copiando reglas que pertenecían a otro proyecto.

Custom Harness convierte ese trabajo en un ciclo explícito y verificable:

init → análisis → implementación → pruebas → reviewer → correcciones → init final

El proyecto combina dos piezas distintas:

• Una skill para el agente: enseña a clasificar tareas, separar responsabilidades y respetar las políticas del repositorio consumidor.
• Un instalador de harness: aplica archivos concretos de coordinación al repositorio objetivo mediante plantillas para Codex, Claude Code o Cursor.

Instalar la skill no modifica automáticamente tu repositorio. Aplicar las plantillas sí crea archivos en el target, siempre después de un preflight visible.

Qué resuelve

• Evita que el leader implemente o apruebe su propio trabajo.
• Clasifica solicitudes como small, medium o large según alcance y riesgo.
• Delega cambios al implementer y exige revisión independiente del reviewer.
• Conserva estado en .harness/task-status.json y continuidad en .harness/context/task-context.toon.
• Mantiene comandos, permisos, rutas protegidas e idioma como políticas configurables del consumidor.
• Detiene la instalación ante colisiones, symlinks, hardlinks o rutas de backup inseguras.
• Ofrece --dry-run, instalación idempotente y validación semántica de los adaptadores.

Cómo funciona

Responsabilidad	Contrato
Leader	Clasifica, registra, delega y coordina. No implementa ni se autoaprueba.
Implementer	Modifica solo el alcance delegado, preserva cambios existentes y ejecuta pruebas.
Reviewer	Revisa sin editar, aporta evidencia y aprueba o rechaza explícitamente.

La clasificación orienta el nivel de razonamiento y el grado de coordinación, sin fijar nombres de modelos que una plataforma podría no ofrecer:

Clase	Señales típicas
small	Cambio localizado, bajo riesgo y pocos archivos.
medium	Varios archivos, una integración o ambigüedad moderada.
large	Arquitectura transversal, persistencia, seguridad, distribución o alto impacto.

Solo el leader puede marcar una tarea como done, y únicamente cuando el reviewer aprobó y el init final pasó.

Instalación rápida

Opción 1: instalar la skill en tu agente

El CLI de skills.sh permite seleccionar la skill y el agente de destino:

npx skills@latest add Axus00/skills

Selecciona custom-harness y Codex, Claude Code o Cursor según tu entorno. Después puedes pedir al agente que use custom-harness para adaptar un repositorio.

Este comando instala conocimiento para el agente. No ejecuta por sí solo el instalador Python sobre tu proyecto.

Opción 2: clonar el repositorio

Esta vía es la más transparente para inspeccionar, desarrollar y ejecutar los scripts directamente:

git clone https://github.com/Axus00/skills.git
cd skills
./init.sh

Requisitos para los scripts locales:

• Python 3.
• Bash para init.sh, o PowerShell para init.ps1.
• Node.js únicamente si eliges la instalación mediante npx skills.

Aplicar el harness a un repositorio

Ejecuta estos comandos desde el clone de skills. Sustituye /ruta/al/proyecto por el repositorio consumidor.

1. Previsualizar

python3 custom-harness/scripts/install_harness.py \
  --target /ruta/al/proyecto \
  --platform codex \
  --dry-run

El dry-run muestra el plan completo sin escribir. Si encuentra contenido diferente o una ruta estructural insegura, informa una colisión y aborta.

2. Instalar

python3 custom-harness/scripts/install_harness.py \
  --target /ruta/al/proyecto \
  --platform codex

Puedes repetir --platform para generar varios adaptadores en una sola operación:

python3 custom-harness/scripts/install_harness.py \
  --target /ruta/al/proyecto \
  --platform codex \
  --platform claude \
  --platform cursor

3. Validar

python3 custom-harness/scripts/validate_harness.py \
  --target /ruta/al/proyecto \
  --platform codex

Para varios adaptadores, repite --platform igual que durante la instalación. La validación comprueba estructura, contratos por rol, ciclo de trabajo, estado, checkpoint y gates de finalización.

Elegir adaptador

Todos los adaptadores conservan las mismas invariantes, pero usan las convenciones de cada producto:

Plataforma	Archivos principales	Consideración
Codex	AGENTS.md y .agents/{leader,implementer,reviewer}.md	Aprovecha coordinación de subagentes cuando está disponible.
Claude Code	CLAUDE.md y .claude/agents/*.md	Define agentes nativos con herramientas acordes a cada rol.
Cursor	.cursor/rules/custom-harness.mdc	Si no hay subagentes aislados, exige pases separados y registra la degradación.

Los tres comparten:

• .harness/config.toml
• .harness/task-status.json
• .harness/context/task-context.toon

Actualizar, reemplazar y retirar

El instalador es idempotente: volver a ejecutarlo con el mismo contenido produce operaciones unchanged.

Para actualizar desde el código fuente:

git pull --ff-only
python3 custom-harness/scripts/install_harness.py \
  --target /ruta/al/proyecto \
  --platform codex \
  --dry-run

Si aceptas reemplazar archivos divergentes, ejecuta de nuevo con --force. Esta opción es deliberadamente explícita y crea respaldos confinados al target en .harness/backups/ antes de reemplazar:

python3 custom-harness/scripts/install_harness.py \
  --target /ruta/al/proyecto \
  --platform codex \
  --force

No existe todavía un comando automático de desinstalación. Para retirar el harness, revisa el diff y restaura o elimina únicamente los archivos generados mediante tu sistema de control de versiones. No borres .harness/ sin comprobar antes si contiene estado o configuración que quieras conservar.

Arquitectura resumida

Skill y políticas del consumidor
              │
              ▼
       Core independiente
  clasificación · workflow · estado
              │
      ┌───────┼────────┐
      ▼       ▼        ▼
    Codex   Claude   Cursor
      │       │        │
      └──── validación ┘

El core define invariantes y estado; .harness/config.toml conserva decisiones del consumidor; los adaptadores cambian sintaxis y capacidades, no el significado del flujo. Las referencias técnicas están dentro de custom-harness/references/.

Seguridad

• Las instrucciones de sistema, usuario y repositorio siempre tienen prioridad sobre los defaults del harness.
• El instalador preflighta destinos y backups antes de mutar archivos.
• Las colisiones abortan toda la operación por defecto; --force requiere una decisión explícita.
• Symlinks, destinos con múltiples hardlinks, ancestros inválidos y backups fuera del target se rechazan.
• La configuración no se ejecuta como comandos durante la instalación.
• Estado y checkpoints no deben contener secretos, tokens, credenciales ni payloads sensibles.
• Una tarea no puede pasar a done sin review aprobada y validación final exitosa.

Estructura del repositorio

.
├── custom-harness/
│   ├── SKILL.md
│   ├── agents/openai.yaml
│   ├── assets/templates/
│   ├── references/
│   ├── scripts/
│   └── tests/
├── .agents/
├── assets/axus-profile.jpeg
├── AGENTS.md
├── init.sh
└── init.ps1

Roadmap

Hoy el repositorio ofrece una skill válida y un CLI Python local. Los siguientes canales están diseñados, pero aún no están publicados:

• Un paquete npm común consumible mediante npm/npx, pnpm y Bun.
• Una .NET tool distribuida como paquete NuGet separado.
• Versionado sincronizado y pruebas de conformidad sobre el mismo core para ambos wrappers.

Hasta que esos artefactos existan, usa npx skills para instalar la skill o clona este repositorio para aplicar el harness con Python.

Contribuir

Las contribuciones son bienvenidas. Antes de abrir un pull request:

1. Mantén el core independiente del framework y coloca las políticas específicas en el consumidor.
2. Añade regresiones para cualquier cambio de comportamiento.
3. Ejecuta ./init.sh.
4. Comprueba que el instalador siga siendo idempotente y que los tres adaptadores conserven sus invariantes.
5. Usa Conventional Commits para describir el cambio.

Licencia

Publicado bajo la licencia MIT.

Autor

Creado y mantenido por Fernando Gómez — @Axus00.

Si este enfoque te resulta útil, adapta las políticas a tu equipo, prueba el flujo en un repositorio real y comparte los casos en los que el harness todavía pueda ser más claro o seguro.