Req Engine

English · 简体中文

A Zero-LLM verb-based requirements store. Rust + SQLite enforce the lifecycle. A Windows WebView2 board is the human seat. MCP disc_ / build_ pair codes bind coding agents to one project and one role. The engine never calls a model.

Rust License: MIT

Who it is for. People who run local coding-agent hosts (Cursor, Claude Desktop, Codex, Grok, …) and want a board those agents cannot rewrite. Humans who decide done.

What it is not. Not an agent runtime, worker pool, or IDLE scheduler. Not a cloud SaaS. Not a model wrapper — Zero LLM inside the engine is the contract. Not a free-form Kanban you can PATCH into consistency. demo/*.html files are static mocks, not the runtime UI. MCP --role + token is a debug back door; do not ship it.

Start here

Windows is the official path. You need Rust and the WebView2 Runtime (already on most Win10/11).

1. Double-click 启动需求引擎.bat (or 启动需求引擎.vbs once a binary exists). First run builds target/release/req-engine.exe if needed, then starts a hidden-console desktop on --home req-engine/data --port 7420.
2. Or from a terminal:

cd req-engine
cargo run -- desktop --home ./data

That opens a native WebView2 window (not a browser tab), auto-inits an empty SQLite home, and injects the admin token. Close hides to the tray; quit only from the tray menu.

3. Create a project on the board. Copy discuss or Copy build. Paste the pack into the agent host MCP config — the board is not an MCP client.

{
  "mcpServers": {
    "req-engine-discuss": {
      "command": "C:\\path\\to\\req-engine.exe",
      "args": ["mcp", "--pair", "disc_…", "--home", "C:\\path\\to\\req-engine\\data"]
    }
  }
}

Host and desktop must share --home. Templates: req-engine/examples/. Matrix: req-engine/docs/MCP.md.

Double-click launchers pin req-engine/data. Without --home / REQ_ENGINE_HOME, the CLI default is %USERPROFILE%\.req-engine (Unix: ~/.req-engine).

cd req-engine
cargo test
cargo build --release

# Optional demo projects on the desktop
cargo run -- desktop --home ./data --seed-if-missing
# or: cargo run -- seed --home ./data

# API only (no native window)
cargo run -- init --home ./data --seed
cargo run -- serve --home ./data --host 127.0.0.1 --port 7420

Why this exists

Writing a requirement and implementing it are different jobs. Discussion agents should create and refine todos. Implementer agents should claim work and submit it. A human should decide done. Most “AI boards” collapse those jobs into a chatbot that can also PATCH status to whatever it likes.

req-engine is the opposite: a local state machine with seats. Intelligence stays in the agent host. The engine only stores facts, rejects illegal verbs, and shows who is seated.

Why verbs beat set_status

A free-form status API is an invitation to invent workflow. Two agents can mark the same card done without claiming it. A planner can skip review. A confused model can write "in-review" instead of "review". You then debug the prompt, not the product.

Here status is not a field you write. It is the result of a verb:

There is no set_status / update_status on HTTP or MCP. done and cancelled are terminal. Soft-cancel only — no hard delete. Claim uses BEGIN IMMEDIATE plus WHERE status = 'todo' AND claimed_by IS NULL, so two MCP processes cannot both win.

The machine lives in req-engine/src/domain/state.rs. Services apply it; HTTP and MCP never bypass it.

Why Zero-LLM is a feature

If the store can think, you cannot audit it. A model inside the engine would invent transitions, hide failures in prose, and couple your board to an API key.

This process does not call OpenAI, Anthropic, or any other model. MCP is a server the host connects to. Tokens and pair codes are ACL, not “AI keys”. Seat faces are a display map from self-reported clientInfo.name (known host or identicon) — not authentication.

You can unit-test every illegal transition without a GPU, a network, or a prompt.

Architecture

 Human ── WebView2 board ── HTTP /v1 (admin Bearer) ─┐
                                                     │
 Discuss agent ── MCP stdio --pair disc_…  ──────────┼──►  req-engine
 Build agent   ── MCP stdio --pair build_… ──────────┘         │
                                                               ▼
                                              SQLite  (requirements, events,
                                              token hashes, pair hashes,
                                              seat_presence heartbeats)

Seats, pair codes, occupancy

Each project has two seats:

Desktop Copy discuss / Copy build puts a pair code plus an onboarding prompt on the clipboard.

• SQLite stores SHA-256 of the code (discuss_pair_hash / build_pair_hash).
• Plaintext lives in {home}/pair-codes.json (gitignored). Rotate invalidates the old code immediately.
• A seated MCP process heartbeats every 4s. The UI treats a seat as occupied while last_seen is within 15s. Clearing the process (or a different pid) drops the face.

list_ready_tasks returns todo cards whose dependency ids are all done.

HTTP (local)

Auth: Authorization: Bearer <token>. CORS allows common localhost static origins. Health is open; everything else is authed.

Port 7420. Desktop injects the admin token into the WebView; you do not paste it for the normal path.

Data home

Inside {home}:

Treat those two plaintext files as secrets. Root .gitignore already excludes data/, data-*/, *.sqlite, tokens.txt, and pair-codes.json.

Layout

Crate-level developer notes: req-engine/README.md.

What this is not

• Not an agent runtime, worker pool, or IDLE scheduler
• Not a cloud multi-tenant SaaS
• Not a model wrapper — Zero LLM inside the engine is the contract
• Not a free-form Kanban you can PATCH into consistency

MIT. github.com/Player-YN/req-engine.