Reference · Adapters

Adapters

The canonical role contract, native subagent generation and the fallback without an adapter.

canonical contract · OpenCode · Claude Code · fallback

The canonical role contract

Each role lives in .rei/agents/<rol>.md. The file has three parts in this order: YAML frontmatter, a ## Contrato section and a ## Referencia section. There must be no normative content outside those two sections.

KeyRequiredValue
nameYesIdentifier of the role; it matches the file name.
descriptionYesOne sentence; it is the text the runtime shows when choosing an agent.
modeYesprimary for the Leader; subagent for the rest.
toolsYesInline list of generic tools: read, write, edit, search, shell, subagent.
modelNoRuntime model, for example provider/model.
Frontmatter
---
name: implementer
description: Implementa un único Work Item siguiendo la planificación aprobada.
mode: subagent
tools: [read, write, edit, search, shell]
---

tools uses generic names: the canonical format never mentions the tools of a specific runtime. The translation is done by the adapter.

Contract versus Reference

## Contrato is self-sufficient: it contains identity, objective, preconditions, protocol, hard rules, output format and allowed tools. ## Referencia contains only optional detail —rationale, examples, edge cases— and omitting it does not prevent the role from running.

  • If a rule or a step is needed to run the role, it lives in ## Contrato.
  • If it is justification or an example, it lives in ## Referencia.
  • Only ## Contrato is passed to the subagent, never the full file.

Generating native subagents

With a native adapter, the CLI extracts the frontmatter and the ## Contrato of each role and translates them to the runtime's format. Both commands install the skeleton if it is missing.

OpenCode and Claude Code
rei init opencode
rei init claude
RuntimeGenerated files
OpenCode.opencode/agents/<rol>.md and the /personalize command in .opencode/commands/personalize.md, with agent: initializer and subtask: true.
Claude Code.claude/agents/<rol>.md with native frontmatter, the /personalize command in .claude/commands/personalize.md and CLAUDE.md, which imports AGENTS.md with @AGENTS.md.
  • The generated files carry the GENERATED mark.
  • No command overwrites a file it did not generate: if it finds one, it warns and keeps it.
  • The installation is idempotent: running it again over generated files leaves them identical.
  • /personalize launches the initializer role's interview to customize the project documentation.

Checking for drift

If you edit the ## Contrato of a role in .rei/agents/, the generated files become outdated. --check compares the canonical generation with what is installed without writing anything.

Verification
rei init opencode --check
rei init claude --check
CodeMeaning
0All files exist, carry the mark and match the canonical generation.
1A file is missing, lacks the mark or differs.

Fallback without an adapter

Cursor and Codex do not expose native subagents configurable per role, so they have no adapter. They work through the fallback, with no configuration: no .cursor/ or .codex/ file is created.

In that case, the Leader passes each subagent only the ## Contrato section of the role —the same one that feeds the native adapters—, so the operational contract is identical.

The roles

The harness defines five roles. The Leader coordinates; the Spec Author plans; the Implementer executes the approved planning; the Reviewer validates; the Initializer drives the customization. The responsibility, the moment and the limit of each one are documented once, on the product's agents page.

Planning approval

Pending

A human sign-off releases the sheet. Silence is not approval.

Approval is recorded from the CLI; the viewer does not replace it.