Templates
The canonical templates for current.md, history.md and meta.json and how the session is archived.
The canonical templates
.rei/templates/ contains the three templates from which the state files come: current.md, history.md and meta.json. They are the single source of format and no agent should invent a new one.
- The CLI uses them when it starts, archives or resets the session.
- They are not copied or written by hand: they are generated and reset with
rei. - Changing a template by hand puts the files already generated from it out of sync.
current.md
current.md represents the current state of the session: which Work Item is active, in what state, what plan remains, what has happened and what the next step is. Its template fixes five fields and three sections.
| Part | Content |
|---|---|
| Header | Work Item, Tipo (type), Estado (state), Inicio (start) and Agente activo (active agent). |
| Plan | Steps of the work, checked off as they advance. |
| Bitácora | Chronological record of what happened in the session. |
| Próximo paso | What must happen next. |
The Spec Author initializes it with rei session start when planning begins and leaves it in ready. The Implementer maintains it during in_progress and leaves it in review. It is updated throughout the cycle, not only at the end.
{{WORK_ITEM}}
{{TYPE}}
{{STATE}}
{{START}}
{{AGENT}}
{{PLAN}}
{{LOG}}
{{NEXT}}history.md
history.md is the project's historical log and its content is append-only: earlier entries are never modified or deleted. Each entry summarizes the date, Work Item, agent, work done, files modified, verification and final state.
rei session archiveappends the summary ofcurrent.mdto the end of the history.- The entry reflects the Reviewer's verdict, because archiving happens after
rei status set <id> done. - An entry is not rewritten to correct it: if context is needed, a new one is added.
meta.json
The meta.json template declares the eight fields with placeholders that the CLI fills in when the Work Item is created. It is not a list of values: the id format, the values of type and status and the use of the commits are documented on the meta.json page.
{
"id": "{{ID}}",
"title": "{{TITLE}}",
"description": "{{DESCRIPTION}}",
"type": "{{TYPE}}",
"status": "{{STATUS}}",
"created_at": "{{CREATED_AT}}",
"base_commit": "{{BASE_COMMIT}}",
"last_review_commit": "{{LAST_REVIEW_COMMIT}}"
}Archiving the session
rei session archive moves the summary of current.md to history.md and resets current.md to its initial state. It only archives when the Work Item is closed and the session state is consistent.
- It checks that
meta.jsonis in a terminal state: done or blocked. - It checks that the Estado field of
current.mdmatches the one inmeta.json. - If something does not match, it rejects the archiving with code 1 and explains the cause; it writes nothing.
- If everything matches, it appends the entry to the end of history.md and resets current.md.
rei session reset resets current.md to its initial state without archiving the history. It is used to discard a session that was never closed, never to delete the evidence of a finished Work Item.
A human sign-off releases the sheet. Silence is not approval.