How it works
The full flow of a Work Item, the human approval gate, the states and direct mode.
One Work Item · one gate · a single in_progress
From request to close
A Work Item goes through the same flow whether it is a Feature or a Task. What changes is the plan the Spec Author produces: requirements, design and tasks for a Feature; a short plan for a Task.
pending
Work Item created, waiting to be planned.
pending → ready
The Spec Author finishes the plan.
pending → blocked
The work cannot continue.
The window is an automatic simulation: when it scrolls into view it runs through the six stops and pauses at the gate to stage the sign-off. The cursor, the "Approve" button and the check are fake; real approval is human and is recorded from the CLI. You can pause it or step through the stops by hand: the simulation does not run commands or approve Work Items. The state table below keeps the full record.
The state of the work does not live in the conversation: meta.json records the stage of each Work Item and current.md reflects the active session so it can be resumed.
The approval gate
The gate is real: the Work Item stays in ready until the person reviews the plan and decides. Approval is given in the chat or the terminal, and the Leader records the step with rei status set <id> in_progress. The viewer does not replace it.
States and branches
The cycle has five states and two branches. blocked and changes_requested are not shortcuts: they describe work that cannot continue or a review that demands corrections.
- pendingWork Item created, waiting to be planned.
- readyPlanning finished, waiting for human approval.
- Planning approvalA human sign-off releases the sheet. Silence is not approval.
- in_progressImplementation under way. Only one can exist at a time.
- reviewImplementation finished, waiting for review.
- doneCompleted and approved; terminal state.
- blockedThe work cannot continue.
- changes_requestedThe review rejected the implementation and asks for changes.
Branches, not shortcuts: they describe stopped work or a review that demands corrections.
- Only one Work Item can be in_progress at a time. The limit is enforced by
rei status set,rei check,rei doctorandrei items status. - done is terminal: you do not leave it through a standard transition.
- If the Reviewer rejects, the Work Item moves to changes_requested and returns to in_progress with the corrections.
- If the work cannot continue at any point, it moves to blocked.
Authorized direct mode
There is a path outside the workflow for trivial changes that are explicitly requested. It is not a Work Item type or a state: it works on the current branch and tree, and it creates no Work Item, plan, session, issue or branch.
Eligible
Documentation, typos, formatting, comments or trivial adjustments with no change in behavior.
Refusal
If it affects behavior, security, data, dependencies, public API, architecture, more than one file, or needs a specification or review, the Leader refuses and offers a Task or a Feature.
Authorization
The Leader asks for explicit confirmation and states that there will be no plan, branch or record.
No record
The only trace is the diff or commit and the conversation;
current.md,meta.jsonandhistory.mdare not written.Delivery
Without an explicit order there is no commit, push, PR or merge.
How it fits with the home page and the documentation
The home page presents the product; this section explains the mechanism and the gate; the documentation teaches concrete tasks. None of the three duplicates the others.