REI HARNESS / ARNÉS SDD

REV. 03 · v0.3.0 · ES

Spec Driven Development · Arnés de agentes de IA

Tu agente escribe. Tú decides.

REI Harness convierte el trabajo con agentes de IA en un proceso con especificación, aprobación humana y evidencia, dentro de tu propio repositorio.

La aprobación se registra desde el CLI. El silencio no aprueba.

WI-014 / feature

REV. 03

Matriz de responsabilidades

4 roles · 1 firma

Hoja de ejemplo

Matriz de responsabilidades por rol y fase
FaseLeaderSpec AuthorImplementerReviewer
01SolicitudResponsableNo intervieneNo intervieneNo interviene
02PlanificaciónNo intervieneResponsableNo intervieneNo interviene
04ImplementaciónNo intervieneNo intervieneResponsableNo interviene
05RevisiónNo intervieneNo intervieneNo intervieneResponsable

Aprobación de la planificación

Pendiente

La firma humana libera la hoja. El silencio no aprueba.

Estado
ready
Checkpoints
V1 · V4
Aprobación
Pendiente
Tipo
feature

Estados del ciclo

actual: ready

  1. pending
  2. ready (estado actual)
  3. in_progress
  4. review
  5. done

Solo un Work Item puede estar en in_progress a la vez.

01Problema

La IA escribe rápido; sin proceso, el retrabajo también.

Sin REI / Con REI

Ejemplo de mecanismo

El mismo caso, dos resultados

Los agentes de IA y los LLM escriben código a partir de una conversación. Cuando decidir, planificar y ejecutar viven en la misma conversación, nada queda registrado y nadie puede revisar la decisión. El arnés separa esas tres cosas y deja la decisión por escrito.

Sin REI

La conversación decide por ti

Mismo caso: «añade un filtro por estado al listado». Sin alcance escrito, el agente empieza por el código.

  1. 01
    Riesgo

    Alcance tardío

    El LLM escribe el filtro antes de que el alcance esté claro: nadie acordó dónde entra ni qué estados cubre.

  2. 02
    Fallo

    Alucinaciones

    Inventa una API o un dato y lo presenta como cierto.

  3. 03
    Fallo

    Decisiones no autorizadas

    Cambia la arquitectura o el alcance sin una aprobación que lo respalde.

  4. 04
    Fallo

    Acciones fuera de límite

    Toca datos o entornos que no le corresponden para probar el cambio.

  5. 05
    Coste

    Retrabajo

    El código rápido es caro de corregir; la decisión solo existió en el chat.

Ejemplo de mecanismo; no reproduce una conversación real.

Con REI

La hoja decide antes del código

El mismo caso entra en un Work Item: planificación revisable, firma humana y evidencia en el repositorio.

  1. 01
    Paso

    Work Item

    El Leader registra el alcance, el tipo y el estado pending antes de escribir código.

  2. 02
    Artefactos

    Planificación

    El Spec Author entrega requirements, design y tasks revisables.

  3. 03
    Puerta

    Aprobación

    La persona revisa y firma; el CLI registra el paso a in_progress. El silencio no aprueba.

  4. 04
    Límite

    Implementación

    El Implementer ejecuta solo la planificación aprobada y deja evidencia de verificación.

  5. 05
    Hecho

    Revisión

    El Reviewer verifica contra la planificación; done exige un veredicto favorable.

Ejemplo de mecanismo construido con los estados y roles reales del arnés.

02Proceso

Una hoja, una firma, evidencia: la persona decide antes de que se escriba código.

Proceso

Una hoja, una firma, evidencia

REI no frena al agente: le da un proceso. Separa decidir, planificar y ejecutar; cada etapa deja un artefacto que se puede leer y revisar.

Recorrer el primer Work Item
  • 01

    Especificación primero

    La planificación existe antes de que el agente escriba la primera línea.

  • 02

    Aprobación humana

    Ningún Work Item pasa a implementación sin una firma explícita.

  • 03

    Roles separados

    Leader, Spec Author, Implementer y Reviewer no invaden su trabajo.

  • 04

    Evidencia versionada

    Planificación, progreso e historial viven en .rei/, no en el chat.

Ciclo y puerta

Ejemplo de mecanismo

La aprobación no es un trámite

Un Work Item recorre cinco estados. La puerta no está antes ni después del trabajo: está entre la planificación y el código. Ningún control de esta página aprueba; la firma se registra desde el CLI.

Los artefactos de la puerta son legibles sin JavaScript; el ciclo se lee de arriba abajo en móvil.

  1. 01

    pending

    Leader

    El Leader registra el Work Item y acuerda el alcance.

  2. 02

    ready

    Spec Author

    El Spec Author entrega requisitos, diseño y tareas revisables.

Aprobación de la planificación

Pendiente

La firma humana libera la hoja. El silencio no aprueba.

  • requirements.md

    Qué debe cumplirse y cómo se verifica.

  • design.md

    Cómo se resuelve y qué alternativas se descartaron.

  • tasks.md

    Orden de ejecución con tareas marcables.

La firma se registra desde el CLI; esta página no aprueba.

  1. 03

    in_progress

    Implementer

    El Implementer ejecuta solo la planificación aprobada.

  2. 04

    review

    Reviewer

    El Reviewer verifica contra la planificación y los checkpoints.

  3. 05

    done

    done

    Estado terminal: trabajo aprobado y evidencia en el repositorio.

blockedEl trabajo no puede continuar.

changes_requestedLa revisión rechazó la implementación y pide cambios.

Ramas, no atajos. Solo un Work Item puede estar in_progress a la vez.

Roles

Roles explícitos, límites explícitos

Cada rol recibe un contrato propio y no invade el trabajo de otro. Abre cualquier rol —también con teclado— para leer su responsabilidad y su límite.

La puerta ocupa el lugar entre Spec Author e Implementer; el Initializer es una rama lateral que no recorre el ciclo del Work Item. Los adaptadores nativos de OpenCode y Claude Code son opcionales; Cursor y Codex funcionan por fallback.

  1. Recibe la solicitudLeaderResponsabilidad y límite

    Leader · Responsabilidad y límite

    Responsabilidad

    Comprende la solicitud, elige el workflow y coordina a los demás roles.

    Límite

    No implementa salvo en el modo directo autorizado.

  2. Recibe el Work ItemSpec AuthorResponsabilidad y límite

    Spec Author · Responsabilidad y límite

    Responsabilidad

    Convierte un Work Item pendiente en una planificación técnica revisable.

    Límite

    Nunca implementa.

  3. La puerta

    Aprobación de la planificación

    Pendiente· firma humana

  4. Recibe la planificación aprobadaImplementerResponsabilidad y límite

    Implementer · Responsabilidad y límite

    Responsabilidad

    Implementa únicamente la planificación aprobada y deja evidencia de verificación.

    Límite

    No cambia el alcance ni la planificación.

  5. Recibe la implementaciónReviewerResponsabilidad y límite

    Reviewer · Responsabilidad y límite

    Responsabilidad

    Valida el trabajo contra la planificación y los checkpoints del proyecto.

    Límite

    No implementa: aprueba o solicita cambios.

  • Rama lateral tras rei initInitializerResponsabilidad y límite

    Initializer · Responsabilidad y límite

    Responsabilidad

    Conduce la personalización guiada de la documentación del proyecto tras rei init.

    Límite

    No implementa código ni escribe fuera de los documentos de personalización.

El Initializer prepara el repositorio; no aprueba ni implementa Work Items.

CLI y artefactos

La terminal deja lo que el chat no deja

Una instantánea real de rei items status junto al árbol de planificación del Work Item. No hay vídeo ni reproducción simulada: el texto es el que produjo el CLI.

La captura está fechada (2026-10-27); los estados cambian con el tiempo.

rei items status

  1. rei items status
  2. Work Items:
  3. - 2026-10-27_00-31__estrategia-producto-web [done] (type: task)
  4. - 2026-10-27_01-54__fundaciones-visuales-shell-docs [done] (type: feature)
  5. - 2026-10-27_02-59__tests-logica-jest [done] (type: task)
  6. - 2026-10-27_03-17__contenido-producto-flujo [done] (type: feature)
  7. - 2026-10-27_11-04__pulido-home-copy-aprobacion [done] (type: task)
  8. - 2026-10-27_11-36__conceptos-guias-docs [done] (type: feature)
  9. - 2026-10-27_12-08__referencia-operacion-docs [done] (type: feature)
  10. - 2026-10-27_20-34__pulido-hero-inline-github-issues [done] (type: task)
  11. - 2026-10-27_22-04__home-demostrativa-playwright [in_progress] (type: feature) << ACTIVO
  12. Solo un Work Item puede estar in_progress a la vez.
Instantánea real de rei items status en este repositorio. El estado de los Work Items cambia con el tiempo.Desliza o usa las flechas para ver la línea completa.

árbol · .rei/specs/<id>/

.rei/specs/<id>/

  • requirements.md

    Qué debe cumplirse y cómo se verifica.

  • design.md

    Cómo se resuelve; alternativas descartadas.

  • tasks.md

    Orden de ejecución con tareas marcables.

  • meta.json

    id, tipo, estado, commit base y revisión.

Un directorio por Work Item; el id es fecha y slug.

03Evidencia

El producto real: el visor, las GitHub Issues y los límites del arnés.

Visor

rei view muestra el Work Item, no lo aprueba

Una captura real del visor local: documentos renderizados, tabla de contenidos, validación y FICHA. Es de solo lectura y no tiene botones que finjan aprobar.

Captura tomada con pnpm capture:evidence el 2026-10-27; el visor se sirve en local y no forma parte de la web.

Ver la página del visor

127.0.0.1 · rei view

Visor local rei view con el Work Item «Referencia y operación de documentación» en escritorio: índice de documentos, documento activo y FICHA de validación.
Captura real del visor · 2026-10-27Ver captura completa
  1. 01

    TOC del Work Item

    El índice lista los documentos del Work Item; los que no existen se marcan como «no existe».

  2. 02

    Validación

    El visor muestra el resultado de los checkpoints junto a la FICHA, con el estado real del trabajo.

  3. 03

    FICHA

    Tipo, estado, fecha y enlaces del Work Item. No hay botón ni ruta de aprobación.

diff

Diff mostrado por el visor para requirements.md del Work Item «Referencia y operación de documentación»: Cambios +48 / −0.

Diff

Si hay cambios respecto de la base de revisión, el visor los publica; aquí aparecen como líneas añadidas.

Diff del visor para requirements.md: Cambios +48 / −0.

El recorte muestra el inicio del diff; la captura completa queda en la evidencia del Work Item. Ver captura completa

GitHub Issues

GitHub Issues es una proyección, no la fuente de verdad

La integración es opcional y no cambia dónde vive el estado. Estas son capturas reales de las issues públicas del repositorio de REI Harness: están cerradas y se muestran con su estado publicado.

El CLI nunca llama a GitHub: lo hacen gh y git bajo orden explícita del Leader.

Leer la guía de GitHub Issues
[prueba v2] Épica: módulo de prueba

github.com · issues/3

Cabecera de la GitHub Issue #3 «[prueba v2] Épica: módulo de prueba» con estado Closed y etiquetas rei, rei:epic.
GitHub Issues v2: épicas, backlog y asignación

issues/2

Cabecera de la GitHub Issue #2 «GitHub Issues v2: épicas, backlog y asignación» con estado Closed y etiquetas rei, rei:feature.
[prueba v2] Hija B: asignación y lote

issues/5

Cabecera de la GitHub Issue #5 «[prueba v2] Hija B: asignación y lote» con estado Closed y etiquetas rei, rei:backlog.

Proyección, no fuente

.rei/specs/<id>/

fuente de verdad

Planificación, progreso e historial viven en el repositorio, no en la issue.

  • Issue

    Existe, se asigna y se cierra como reflejo del Work Item.

  • Rama

    Contiene el trabajo que el Reviewer verifica.

  • PR

    Propone el cambio; `.rei` sigue mandando sobre el estado.

Integración opcional: se activa con rei github enable y el flujo funciona sin ella.

issue · cuerpo

Cuerpo de la GitHub Issue #3 «[prueba v2] Épica: módulo de prueba» con su task list publicada.
Cuerpo publicado de la épica: la task list real, con sus hijas cerradas. El recorte muestra el inicio de la captura.Ver captura completa

Límites

Lo que la web no hace

Mostrar los límites forma parte de la propuesta: la web documenta el arnés, no lo sustituye.

Consultar los comandos
  • 01

    Sin búsqueda ni selector de versiones

    La navegación, el TOC y una estructura de URLs predecible cubren el volumen actual.

  • 02

    El visor es de solo lectura

    La aprobación se registra desde el CLI, no desde el navegador.

  • 03

    GitHub Issues es opcional

    No es la fuente de verdad del Work Item ni un requisito para trabajar.

  • 04

    El modo directo está restringido

    Solo aplica a cambios triviales solicitados explícitamente.

  • 05

    La web no ejecuta comandos

    No modifica Work Items ni sustituye al CLI o al visor.

04Cierre

La evidencia queda en tu repositorio; el siguiente Work Item lo abres tú.

Siguiente paso

Instala REI y abre tu primer Work Item

Tu agente escribe; tú decides. Un binario, un comando y una planificación aprobada antes de implementar. La evidencia queda en tu repositorio.