Work Items and states
Feature versus Task, the states of the cycle, its branches and the limit of one Work Item in in_progress.
Feature or Task
All work is born as a Work Item with an identifier and a type. The type is not a cosmetic label: it decides the planning that is generated and whether the GitHub Issues integration opens an issue and a branch.
| Type | Planning | When to use it |
|---|---|---|
| Feature | requirements.md, design.md and tasks.md | The work needs a specification, there are several design decisions, or it changes behavior or architecture. |
| Task | plan.md | Documentation, contracts, or a small, localized change with no change in behavior or architecture. |
The state cycle
Features and Tasks share the same cycle. Every Work Item starts in pending, goes through planning and approval, is implemented, is reviewed and ends in done. Each state describes a real stage of the work, not a decorative label.
| State | Meaning | Kind |
|---|---|---|
| pending | Work Item created, waiting for planning. | Cycle |
| ready | Planning finished, waiting for human approval. | Cycle |
| in_progress | Implementation under way. Only one at a time. | Cycle |
| review | Implementation finished, waiting for review. | Cycle |
| done | Completed and approved; terminal state. | Terminal |
The move from ready to in_progress is the human approval. The move from in_progress to review is recorded by the Implementer when it finishes, and the move from review to done requires the Reviewer's verdict. No shortcut removes those points.
The branches of the cycle
Two states sit outside the linear path. They are not shortcuts or success states: they describe work that is stopped or a review that demands corrections.
| State | Meaning |
|---|---|
| blocked | The work cannot continue. |
| changes_requested | The review rejected the implementation and asks for changes. |
- blocked is reached from any point of the cycle when the work cannot continue; it is only left once the cause is resolved.
- changes_requested is produced by a Reviewer rejection. The Work Item returns to in_progress with the requested corrections.
- done is terminal: it is not left through a standard transition. A non-standard transition requires
--forceand an explicit order.
Where the state lives
State does not live in the conversation or in the agent's memory. It is recorded in two files with distinct, complementary responsibilities.
| File | What it records | What it is for |
|---|---|---|
meta.json | Type, state, base_commit and last_review_commit of each Work Item. | Durable record and diagnosis of the set of Work Items. |
current.md | State, log and next step of the active session. | Resuming the work exactly where it was left if the session is interrupted. |
The limit of a single in_progress is hard. rei status set enforces it when you try to activate another Work Item, also with --force, and rei check, rei doctor and rei items status verify it. Before starting another one, the active one must be closed, blocked or sent to review.
Next step
With the vocabulary clear, the next step is to understand the gate that separates ready from in_progress, or to walk through the full cycle with a real Work Item.
A human sign-off releases the sheet. Silence is not approval.