Referencia · Adaptadores

Adaptadores

El contrato canónico de rol, la generación de subagentes nativos y el fallback sin adaptador.

contrato canónico · OpenCode · Claude Code · fallback

El contrato canónico de rol

Cada rol vive en .rei/agents/<rol>.md. El archivo tiene tres partes en este orden: frontmatter YAML, sección ## Contrato y sección ## Referencia. No debe haber contenido normativo fuera de esas dos secciones.

ClaveObligatoriaValor
nameSíIdentificador del rol; coincide con el nombre del archivo.
descriptionSíUna frase; es el texto que muestra el runtime al elegir agente.
modeSíprimary para el Leader; subagent para el resto.
toolsSíLista inline de herramientas genéricas: read, write, edit, search, shell, subagent.
modelNoModelo del runtime, por ejemplo provider/modelo.
Frontmatter
---
name: implementer
description: Implementa un único Work Item siguiendo la planificación aprobada.
mode: subagent
tools: [read, write, edit, search, shell]
---

tools usa nombres genéricos: el formato canónico nunca menciona herramientas de un runtime concreto. La traducción la hace el adaptador.

Contrato frente a Referencia

## Contrato es autosuficiente: contiene identidad, objetivo, precondiciones, protocolo, reglas duras, formato de salida y herramientas permitidas. ## Referencia contiene solo detalle opcional —racional, ejemplos, casos límite— y su omisión no impide ejecutar el rol.

  • Si una regla o un paso es necesario para ejecutar el rol, vive en ## Contrato.
  • Si es justificación o ejemplo, vive en ## Referencia.
  • Al subagente se le transmite únicamente ## Contrato, nunca el archivo completo.

Generar subagentes nativos

Con un adaptador nativo, el CLI extrae el frontmatter y el ## Contrato de cada rol y los traduce al formato del runtime. Ambos comandos instalan el esqueleto si falta.

OpenCode y Claude Code
rei init opencode
rei init claude
RuntimeArchivos generados
OpenCode.opencode/agents/<rol>.md y el comando /personalize en .opencode/commands/personalize.md, con agent: initializer y subtask: true.
Claude Code.claude/agents/<rol>.md con frontmatter nativo, el comando /personalize en .claude/commands/personalize.md y CLAUDE.md, que importa AGENTS.md con @AGENTS.md.
  • Los archivos generados llevan la marca GENERATED.
  • Ningún comando sobrescribe un archivo que no haya generado: si lo encuentra, avisa y lo conserva.
  • La instalación es idempotente: reejecutarla sobre archivos generados los deja idénticos.
  • /personalize lanza la entrevista del rol initializer para personalizar la documentación del proyecto.

Comprobar la deriva

Si editas el ## Contrato de un rol en .rei/agents/, los archivos generados quedan desactualizados. --check compara la generación canónica con lo instalado sin escribir nada.

Verificación
rei init opencode --check
rei init claude --check
CódigoSignificado
0Todos los archivos existen, llevan la marca y coinciden con la generación canónica.
1Falta algún archivo, no lleva la marca o difiere.

Fallback sin adaptador

Cursor y Codex no exponen subagentes nativos configurables por rol, así que no tienen adaptador. Funcionan por fallback, sin configuración: no se crea ningún archivo .cursor/ ni .codex/.

En ese caso, el Leader transmite a cada subagente solo la sección ## Contrato del rol —la misma que alimenta a los adaptadores nativos—, de modo que el contrato operativo es idéntico.

Los roles

El arnés define cinco roles. El Leader coordina; el Spec Author planifica; el Implementer ejecuta la planificación aprobada; el Reviewer valida; el Initializer conduce la personalización. La responsabilidad, el momento y el límite de cada uno se documentan una sola vez en la página de agentes del producto.

Aprobación de la planificación

Pendiente

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

La aprobación se registra desde el CLI; el visor no la sustituye.