Adaptadores
El contrato canónico de rol, la generación de subagentes nativos y el fallback sin adaptador.
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.
| Clave | Obligatoria | Valor |
|---|---|---|
| name | Sí | Identificador del rol; coincide con el nombre del archivo. |
| description | Sí | Una frase; es el texto que muestra el runtime al elegir agente. |
| mode | Sí | primary para el Leader; subagent para el resto. |
| tools | Sí | Lista inline de herramientas genéricas: read, write, edit, search, shell, subagent. |
| model | No | Modelo del runtime, por ejemplo provider/modelo. |
---
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.
rei init opencode
rei init claude| Runtime | Archivos 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.
/personalizelanza 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.
rei init opencode --check
rei init claude --check| Código | Significado |
|---|---|
| 0 | Todos los archivos existen, llevan la marca y coinciden con la generación canónica. |
| 1 | Falta 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.
La firma humana libera la hoja. El silencio no aprueba.