Configuración

Esta guía lleva un repositorio de cero a un flujo de trabajo de repo-harness operativo: instala el runtime, adopta el repositorio, conecta los hooks de tu agente y confirma que las protecciones se disparan.

Requisitos previos

Un repositorio git

repo-harness es local del repositorio. Ejecútalo desde un árbol de trabajo git — haz git init primero si la carpeta aún no lo es.

Un agente

Claude Code o la CLI de Codex como ejecutor. ChatGPT Pro es opcional, para planificar.

Bun

La CLI se ejecuta sobre Bun — el instalador lo incorpora si falta. No se requiere configurar Node.

1. Instala la CLI

Consigue el binario repo-harness en tu máquina con el punto de entrada que prefieras:

curl

# macOS / Linux — installs Bun if missing, then the CLI
curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh

bun

bun add -g repo-harness

npm

npm install -g repo-harness

Dos “instalaciones” distintas

El paso anterior instala el paquete de la CLI. El siguiente paso, repo-harness init, es una acción aparte que configura el runtime en esta máquina. La misma palabra, trabajos distintos — por eso el comando de arranque es init, no install.

2. Arranca el runtime

1. Ejecuta init una vez por máquina. Es idempotente — conecta los adaptadores de hook del host, las skills de Waza y el índice de CodeGraph para cada proyecto que uses:

   repo-harness init
   # ✓ host adapters · skills · CodeGraph configured

2. Comprueba la disponibilidad en cualquier momento (solo lectura):

   repo-harness status   # CLI version, host install state, route coverage
   repo-harness doctor   # PATH, version, hosts, trust state

¿Ya arrancado?

repo-harness init es seguro de volver a ejecutar — úsalo para reparar una máquina configurada a medias. Para obtener un runtime más reciente más adelante, usa repo-harness update.

3. Adopta tu repositorio

1. Desde la raíz de tu repositorio, previsualiza lo que cambiará. No se escribe nada:

   repo-harness adopt --dry-run   # Migration Report

2. Aplica el contrato local del repositorio:

   repo-harness adopt

Adopt inspecciona el repositorio, instala los archivos del flujo de trabajo, conecta los hooks, construye el índice de CodeGraph y ejecuta la comprobación del flujo de trabajo. El árbol que despliega:

• AGENTS.md contrato de enrutamiento de Codex
• CLAUDE.md contrato de enrutamiento de Claude Code
• Directorio.ai/

  • Directorioharness/ contrato, política, comprobaciones, traspaso

    • …
  • Directoriocontext/ mapa de contexto + capacidades

    • …
  • Directoriohooks/ runtime de hooks local del repositorio

    • …
• Directoriodocs/

  • spec.md verdad del producto
• Directorioplans/ catálogo de planes con marca de tiempo

  • …
• Directoriotasks/

  • Directoriocontracts/ autoridad del alcance de edición

    • …
  • Directorioreviews/ puertas de finalización

    • …
• Directorioscripts/ ayudantes del flujo de trabajo

  • …

¿No es un repositorio git?

Adopt se niega a ejecutarse fuera de un árbol de trabajo git. Haz git init primero, o pasa un destino explícito con repo-harness adopt --repo <path> para un andamiaje no git.

4. Conecta tu agente

init instala adaptadores de host que despachan los eventos del editor hacia repo-harness. Apunta tu agente hacia ellos y luego reinicia la sesión para que los hooks se carguen.

Claude Code

El adaptador vive en tu configuración de usuario — ~/.claude/settings.json — y enruta cada evento SessionStart, PreToolUse, PostToolUse, UserPromptSubmit y Stop hacia el harness. Reinicia Claude Code para tomarlo.

Codex

Codex lee ~/.codex/hooks.json. Después de que init lo escriba, confía en la configuración de hooks en los Ajustes de Codex — Codex no ejecutará hooks no confiables. Luego inicia una sesión nueva.

5. Verifica que está activo

1. Enrutamiento de prompts — envía cualquier prompt. El hook UserPromptSubmit clasifica la intención y expone el estado del plan en su salida informativa.

2. La protección de edición — pide al agente que edite un archivo antes de que se apruebe ningún plan. La protección PreToolUse.edit falla de forma cerrada y bloquea la escritura hasta que captures un plan.

3. La comprobación del flujo de trabajo — ejecuta la puerta directamente:

   bash scripts/check-task-workflow.sh --strict

Una marca verde significa que la superficie del contrato es consistente y que las protecciones están armadas.

6. Planifica con ChatGPT Pro (opcional)

¿Quieres que ChatGPT Pro lea tus planes sin tocar el código fuente? Expón únicamente los archivos del flujo de trabajo a través de un sidecar MCP local:

repo-harness mcp setup chatgpt --repo .
repo-harness mcp serve --transport http \
  --host 127.0.0.1 --port 8765 --profile planner

Todos los detalles —incluido el límite de seguridad de solo lectura— están en la página del planificador con ChatGPT Pro.

Próximos pasos

El flujo de trabajo Plan → Sprint → Goal, y la Tarjeta de Revisión Humana.

Hooks Las ocho rutas gestionadas que protegen y rastrean tu trabajo.

Referencia de la CLI Cada comando que vas a necesitar.