AI Agent Harness (ai-agent-harness)

Framework de gobernanza, control y seguridad para agentes de IA agnóstico de proveedor, estructurado como paquete NPM reutilizable.

Este no es un estándar oficial de OpenAI, Anthropic, Google o GitHub. Es un estándar independiente basado en documentación oficial y prácticas operativas locales de control de agentes.

Uso rápido (Scaffolding instantáneo)

Puedes inicializar todo el arnés de políticas y sensores de manera instantánea en cualquier repositorio existente ejecutando:

npx ai-agent-harness init

O si deseas forzar la sobreescritura de archivos preexistentes:

npx ai-agent-harness init --force

En Windows, usar Git Bash para los scripts .sh o los wrappers PowerShell:

git init
powershell -ExecutionPolicy Bypass -File .agent/sensors/preflight.ps1 --staged
powershell -ExecutionPolicy Bypass -File .agent/sensors/verify.ps1

Qué genera

• AGENTS.md como contrato universal.
• .agent/ con políticas, memoria, journal, sensores, hooks y templates.
• .agent/state/ con feature activa y progreso durable entre sesiones.
• Adaptadores opcionales para Claude Code, Gemini, GitHub Copilot, Cursor y VS Code.
• Guía de desarrollo guiado por especificaciones con GitHub Spec-Kit en .agent/policy/spec-kit.md.
• Hooks Codex en .codex/hooks.json.
• Hooks Git livianos y versionables en .githooks/.
• Sensores locales Bash y PowerShell para whitespace, secretos, archivos críticos y validación por stack.
• Página operativa en docs/index.html.

Página local

Abrir docs/index.html para ver la guía visual de instalación, capas, ciclo de sesión y verificación. Está inspirada en la estructura educativa de Learn Harness Engineering, pero adaptada a este harness lean y portable.

Política principal

• Cambios pequeños, verificables y reversibles.
• Archivos críticos requieren backup o rollback plan.
• Hooks automáticos livianos; validaciones pesadas en cierre de tarea, pre-push manual o CI.
• No producción, DB destructiva, secretos, deploy o infraestructura real sin aprobación explícita.

Cambios v4

• Parser de argumentos robusto: --help y opciones antes/después de posicionales funcionan.
• preflight.sh ya no falla en modo default --worktree.
• verify.sh deja de ocultar fallos de tests/compilación.
• log-run.sh genera JSONL válido.
• post-tool-log.sh registra metadata saneada en vez del payload completo.
• .gitignore conserva .gitkeep y no ignora directorios completos.
• Detección de archivos críticos menos ruidosa: no marca secrets-scan.sh solo por el nombre.
• Claude settings agregan denegación de lectura para .env y rutas sensibles.

Cambios v4.1

• preflight --staged falla con mensaje claro si no hay repo Git, evitando falsos OK.
• Agrega sensores y hooks PowerShell para Windows.
• .codex/hooks.json usa comandos Codex y commandWindows; ya no depende de variables de Claude.
• Documenta matriz de cobertura: instrucciones, riesgo y verificación quedan cubiertos; multi-agente/evals quedan fuera del core lean.

Cambios v4.2

• Agrega página estática docs/index.html.
• Agrega .agent/state/feature_list.json y .agent/state/progress.md.
• Agrega ciclo de sesión con init-session y finish-session en Bash/PowerShell.
• Agrega template .agent/templates/session-handoff.md.

Ver docs_manual.html para el manual completo.