Get started · Tutorial

First Work Item

Walk through the whole cycle once: initialize the harness, customize the project, plan, approve, implement and review.

7 steps · One complete Work Item

1. Initialize the harness

At the root of your project, rei init deploys AGENTS.md and the .rei/ folder, sets up the state structure and initializes git if it is missing. It does not overwrite existing files.

Shell
rei init

2. Customize the project

The harness needs to know your project. In OpenCode or Claude Code you can run /personalize; in any runtime, ask the agent «personaliza mi proyecto» (Spanish for "customize my project") and the Initializer role will lead the interview.

  • Product purpose, users and principles.
  • Technical stack and project commands.
  • Architecture decisions and conventions.
  • Verification checkpoints and quick checks.

3. Create the Work Item

Describe what you need to the agent. Once the scope is agreed, the Leader creates the Work Item in pending state with an identifier and a type.

Example
rei new 2026-10-27_01-54__mi-feature feature "Mi primera feature"

A Feature requires requirements.md, design.md and tasks.md; a Task is planned with a single plan.md for small, localized changes.

4. Plan

The Spec Author turns the Work Item into a technical plan you can review. It does not implement: its deliverable is the decision documents.

  • Observable, verifiable requirements.
  • Design decisions and discarded alternatives.
  • Ordered tasks with their verification.
Shell
rei status set 2026-10-27_01-54__mi-feature ready

5. Approve the plan

Review the plan before any code is written. If you agree, the approval is recorded from the CLI; if something does not reflect what was agreed, ask the Spec Author to update it.

Shell
rei status set 2026-10-27_01-54__mi-feature in_progress

6. Implement

The Implementer carries out only the approved plan, marks each task as it completes it and leaves verification evidence in .rei/progress/work-items/.

Shell
rei check

rei check verifies the harness and runs the checks declared in .rei/config.json. Slow checkpoints, such as the production build, run when the Work Item is closed.

7. Review and close

The Reviewer compares the work with the plan and the checkpoints. If something is missing, the Work Item moves to changes_requested and the Implementer fixes it; if everything passes, it becomes done.

Shell
rei status set 2026-10-27_01-54__mi-feature review
rei review-diff 2026-10-27_01-54__mi-feature
rei validate 2026-10-27_01-54__mi-feature

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.