REI HARNESS / SDD HARNESS

REV. 03 · v0.3.0 · EN

Spec Driven Development · Harness for AI agents

Your agent writes. You decide.

REI Harness turns work with AI agents into a process with a specification, human approval and evidence, inside your own repository.

Approval is recorded from the CLI. Silence is not approval.

WI-014 / feature

REV. 03

Responsibility matrix

4 roles · 1 sign-off

Example sheet

Responsibility matrix by role and phase
PhaseLeaderSpec AuthorImplementerReviewer
01RequestResponsibleNot involvedNot involvedNot involved
02PlanningNot involvedResponsibleNot involvedNot involved
04ImplementationNot involvedNot involvedResponsibleNot involved
05ReviewNot involvedNot involvedNot involvedResponsible

Planning approval

Pending

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

State
ready
Checkpoints
V1 · V4
Approval
Pending
Type
feature

Cycle states

current: ready

  1. pending
  2. ready (current state)
  3. in_progress
  4. review
  5. done

Only one Work Item can be in in_progress at a time.

01Problem

AI writes fast; without a process, so does the rework.

Without REI / With REI

Illustrative example

The same case, two outcomes

AI agents and LLMs write code from a conversation. When deciding, planning and executing all happen in the same conversation, nothing is recorded and nobody can review the decision. The harness separates those three things and puts the decision in writing.

Without REI

The conversation decides for you

Same case: “add a status filter to the list”. With no written scope, the agent starts with the code.

  1. 01
    Risk

    Late scope

    The LLM writes the filter before the scope is clear: nobody agreed where it applies or which states it covers.

  2. 02
    Failure

    Hallucinations

    It invents an API or a piece of data and presents it as true.

  3. 03
    Failure

    Unauthorized decisions

    It changes the architecture or the scope without an approval to back it.

  4. 04
    Failure

    Out-of-bounds actions

    It touches data or environments that are not its own to test the change.

  5. 05
    Cost

    Rework

    Fast code is expensive to fix; the decision only ever existed in the chat.

Illustrative example of the mechanism; it does not reproduce a real conversation.

With REI

The sheet decides before the code

The same case becomes a Work Item: a reviewable plan, a human sign-off and evidence in the repository.

  1. 01
    Step

    Work Item

    The Leader records the scope, the type and the pending state before any code is written.

  2. 02
    Artifacts

    Planning

    The Spec Author delivers reviewable requirements, design and tasks.

  3. 03
    Gate

    Approval

    The person reviews and signs; the CLI records the move to in_progress. Silence is not approval.

  4. 04
    Limit

    Implementation

    The Implementer executes only the approved plan and leaves verification evidence.

  5. 05
    Done

    Review

    The Reviewer verifies against the plan; done requires a favorable verdict.

Illustrative example built with the harness's real states and roles.

02Process

One sheet, one sign-off, evidence: a person decides before any code is written.

Process

One sheet, one sign-off, evidence

REI does not slow the agent down: it gives it a process. It separates deciding, planning and executing; each stage leaves an artifact you can read and review.

Walk through the first Work Item
  • 01

    Specification first

    The plan exists before the agent writes the first line.

  • 02

    Human approval

    No Work Item moves to implementation without an explicit sign-off.

  • 03

    Separate roles

    Leader, Spec Author, Implementer and Reviewer stay within their own work.

  • 04

    Versioned evidence

    Planning, progress and history live in .rei/, not in the chat.

Cycle and gate

Illustrative example

Approval is not a formality

A Work Item goes through five states. The gate is not before or after the work: it sits between the plan and the code. No control on this page approves anything; the sign-off is recorded from the CLI.

The gate's artifacts are readable without JavaScript; on mobile the cycle reads top to bottom.

  1. 01

    pending

    Leader

    The Leader records the Work Item and agrees the scope.

  2. 02

    ready

    Spec Author

    The Spec Author delivers reviewable requirements, design and tasks.

Planning approval

Pending

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

  • requirements.md

    What must be met and how it is verified.

  • design.md

    How it is solved and which alternatives were discarded.

  • tasks.md

    Execution order with checkable tasks.

The sign-off is recorded from the CLI; this page does not approve.

  1. 03

    in_progress

    Implementer

    The Implementer executes only the approved plan.

  2. 04

    review

    Reviewer

    The Reviewer verifies against the plan and the checkpoints.

  3. 05

    done

    done

    Terminal state: approved work and evidence in the repository.

blockedThe work cannot continue.

changes_requestedThe review rejected the implementation and asks for changes.

Branches, not shortcuts. Only one Work Item can be in in_progress at a time.

Roles

Explicit roles, explicit limits

Each role gets its own contract and does not step into another's work. Open any role, keyboard included, to read its responsibility and its limit.

The gate sits between Spec Author and Implementer; the Initializer is a side branch that does not go through the Work Item cycle. The native OpenCode and Claude Code adapters are optional; Cursor and Codex work through a fallback.

  1. Receives the requestLeaderResponsibility and limit

    Leader · Responsibility and limit

    Responsibility

    Understands the request, chooses the workflow and coordinates the other roles.

    Limit

    Does not implement, except in the authorized direct mode.

  2. Receives the Work ItemSpec AuthorResponsibility and limit

    Spec Author · Responsibility and limit

    Responsibility

    Turns a pending Work Item into a reviewable technical plan.

    Limit

    Never implements.

  3. The gate

    Planning approval

    Pending· human sign-off

  4. Receives the approved planImplementerResponsibility and limit

    Implementer · Responsibility and limit

    Responsibility

    Implements only the approved plan and leaves verification evidence.

    Limit

    Does not change the scope or the plan.

  5. Receives the implementationReviewerResponsibility and limit

    Reviewer · Responsibility and limit

    Responsibility

    Validates the work against the plan and the project's checkpoints.

    Limit

    Does not implement: approves or requests changes.

  • Side branch after rei initInitializerResponsibility and limit

    Initializer · Responsibility and limit

    Responsibility

    Guides the customization of the project documentation after rei init.

    Limit

    Does not implement code nor write outside the customization documents.

The Initializer prepares the repository; it neither approves nor implements Work Items.

CLI and artifacts

The terminal leaves what the chat does not

A real snapshot of rei items status next to the Work Item's planning tree. There is no video or simulated playback: the text is what the CLI produced.

The capture is dated (2026-10-27); the states change over time.

rei items status

  1. rei items status
  2. Work Items:
  3. - 2026-10-27_00-31__estrategia-producto-web [done] (type: task)
  4. - 2026-10-27_01-54__fundaciones-visuales-shell-docs [done] (type: feature)
  5. - 2026-10-27_02-59__tests-logica-jest [done] (type: task)
  6. - 2026-10-27_03-17__contenido-producto-flujo [done] (type: feature)
  7. - 2026-10-27_11-04__pulido-home-copy-aprobacion [done] (type: task)
  8. - 2026-10-27_11-36__conceptos-guias-docs [done] (type: feature)
  9. - 2026-10-27_12-08__referencia-operacion-docs [done] (type: feature)
  10. - 2026-10-27_20-34__pulido-hero-inline-github-issues [done] (type: task)
  11. - 2026-10-27_22-04__home-demostrativa-playwright [in_progress] (type: feature) << ACTIVO
  12. Only one Work Item can be in in_progress at a time.
Real snapshot of rei items status in this repository. The state of the Work Items changes over time.Swipe or use the arrow keys to see the full line.

tree · .rei/specs/<id>/

.rei/specs/<id>/

  • requirements.md

    What must be met and how it is verified.

  • design.md

    How it is solved; discarded alternatives.

  • tasks.md

    Execution order with checkable tasks.

  • meta.json

    id, type, state, base commit and review.

One directory per Work Item; the id is date and slug.

03Evidence

The real product: the viewer, GitHub Issues and the limits of the harness.

Viewer

rei view shows the Work Item, it does not approve it

A real capture of the local viewer: rendered documents, table of contents, validation and FICHA. It is read-only and has no buttons that pretend to approve.

Capture taken with pnpm capture:evidence on 2026-10-27; the viewer is served locally and is not part of this website.

See the viewer page

127.0.0.1 · rei view

Local rei view viewer with the Work Item «Referencia y operación de documentación» on desktop (interface in Spanish): document index, active document and validation FICHA.
Real capture of the viewer · 2026-10-27View full capture
  1. 01

    Work Item table of contents

    The index lists the Work Item's documents; those that do not exist are marked «no existe».

  2. 02

    Validation

    The viewer shows the checkpoint results next to the FICHA, with the real state of the work.

  3. 03

    FICHA

    The Work Item's type, state, date and links. There is no approval button or route.

diff

Diff shown by the viewer for requirements.md of the Work Item «Referencia y operación de documentación» (interface in Spanish): Cambios +48 / −0, that is, 48 lines added and none removed.

Diff

If there are changes against the review base, the viewer publishes them; here they appear as added lines.

Viewer diff for requirements.md: Cambios +48 / −0 (48 lines added, none removed).

The crop shows the start of the diff; the full capture stays in the Work Item's evidence. View full capture

GitHub Issues

GitHub Issues is a projection, not the source of truth

The integration is optional and does not change where the state lives. These are real captures of the public issues in the REI Harness repository: they are closed and shown with their published state.

The CLI never calls GitHub: gh and git do, under the Leader's explicit order.

Read the GitHub Issues guide
[prueba v2] Épica: módulo de prueba (issue title in Spanish)

github.com · issues/3

Header of GitHub Issue #3 «[prueba v2] Épica: módulo de prueba» (the title is in Spanish) with state Closed and labels rei, rei:epic.
GitHub Issues v2: epics, backlog and assignment (issue title in Spanish)

issues/2

Header of GitHub Issue #2 «GitHub Issues v2: épicas, backlog y asignación» (the title is in Spanish) with state Closed and labels rei, rei:feature.
[prueba v2] Hija B: asignación y lote (issue title in Spanish)

issues/5

Header of GitHub Issue #5 «[prueba v2] Hija B: asignación y lote» (the title is in Spanish) with state Closed and labels rei, rei:backlog.

Projection, not source

.rei/specs/<id>/

source of truth

Planning, progress and history live in the repository, not in the issue.

  • Issue

    It exists, is assigned and is closed as a reflection of the Work Item.

  • Branch

    It holds the work the Reviewer verifies.

  • PR

    It proposes the change; `.rei` still rules over the state.

Optional integration: enable it with rei github enable and the flow works without it.

issue · body

Body of GitHub Issue #3 «[prueba v2] Épica: módulo de prueba» (content in Spanish) with its published task list.
Published body of the epic: the real task list, with its child issues closed. The crop shows the start of the capture.View full capture

Limits

What the website does not do

Showing the limits is part of the proposal: the website documents the harness, it does not replace it.

Check the commands
  • 01

    No search or version selector

    The navigation, the table of contents and a predictable URL structure cover the current volume.

  • 02

    The viewer is read-only

    Approval is recorded from the CLI, not from the browser.

  • 03

    GitHub Issues is optional

    It is not the source of truth for the Work Item nor a requirement to work.

  • 04

    Direct mode is restricted

    It only applies to trivial changes that are explicitly requested.

  • 05

    The website does not run commands

    It does not modify Work Items nor replace the CLI or the viewer.

04Close

The evidence stays in your repository; you open the next Work Item.

Next step

Install REI and open your first Work Item

Your agent writes; you decide. One binary, one command and a plan approved before implementation. The evidence stays in your repository.