Req0

Req0 allows you to keep structured requirement packs in your product git repo. The same pack drives definition, implementation, and proof — not a ticket, a chat, or a separate test script.

A local cockpit runs that loop: a coding agent (Cursor, Copilot, Claude, or Codex) interviews you, drafts frozen-grammar requirement.md, and later implements — only after you answer, a compiler checks the grammar, and Jev (TypeSafe System One) judges Ready. The browser then proves the app against the spec. If proof fails, Fix from proof sends that report back so the same agent can repair the implementation — not the spec.

Implement is optional. On first run pick I’ll write the code, or set "implement": false in req0.json at the product repo root. Req0 then stays on the pack and QA; you implement your own way.

Req0 is a CLI plus a thin HTML cockpit, free and open source. It is not a hosted SaaS.

Install

Node.js 22.15 or newer.

npx @richjava/req0 start

You can open the cockpit and compile a spec with that alone. Judgment, Implement, and Prove need Jev: set TYPESAFE_API_KEY in the product repo’s .env (TypeSafe System One). Without the key, Check fails closed and Ready stays Not yet.

Quick start

From the product repo (the app you are specifying), not from inside this package:

cd /path/to/your-product
npx @richjava/req0 start

The cockpit opens at http://127.0.0.1:4370 (or the next free port). From the requirement list, create a pack with a kebab-case id such as 001. That writes docs/requirements/<id>/. On Define, describe the requirement and Start — the recorded coding agent interviews you (you can skip questions) and drafts frozen-grammar requirement.md. Optional PNG/JPG/WebP go in that pack’s context/ folder. req0 create on the CLI still writes the starter template only.

You can also edit requirement.md yourself. Save compiles. Spec Valid means the grammar parsed — it does not mean the spec is ready to implement. With a TypeSafe key, authoring keeps going until Ready is Clear; without one, it stops at Spec Valid.

Commands

| Command | What it does | | --- | --- | | req0 start | Local cockpit | | req0 create <id> | Create a pack folder (kebab-case) | | req0 compile | Compile the pack; exit 2 on grammar errors | | req0 check | Ask Jev to judge the spec. Needs TYPESAFE_API_KEY. Exit 3 if the key is missing; exit 2 if Ready is blocked | | req0 implement | Launch the recorded coding agent after Ready. --adapter=cursor\|copilot\|claude\|codex\|manual. --stack=nextjs-default\|amplify-gen2 on an empty repo | | req0 prove | Run compiled browser QA after Ready (and Build, unless Implement is off) |

req0 compile, check, implement, and prove resolve a pack from the current directory (a pack folder, or the only pack under docs/requirements/). The cockpit does not auto-open a pack from the product root — you pick one from the list.

Setup

In the product repo

Packs live at docs/requirements/<kebab-id>/:

docs/requirements/invoice-approval/
  requirement.md
  fixtures/personas.yaml    # test users, never production credentials
  fixtures/runtime.yaml     # app URL and login selectors for Prove
  context/                  # optional screenshots the authoring agent can Read
  derived/                  # generated; do not hand-edit

First run asks how code should be written (I’ll write the code, Cursor, Copilot, Claude, or Codex) and, if an agent will implement, which stack. That writes req0.json at the product repo root. Edit that file later: "implement": false turns Implement off (same as I’ll write the code); "adapter": "cursor" (or copilot, claude, codex) records which CLI to launch.

House standards (optional freeform markdown) live at docs/requirement-standards/pack.md and document.md. Authoring, Improve, and Implement Read those files and follow them in substance while still emitting frozen requirement.md grammar. Point req0.json at other paths with "standards": { "pack": "…", "document": "…" }. Missing files fall back to the copies shipped with the package. Jev scores the pack against that house style as Ready nits only — they do not block Implement.

The as-built schema map is docs/system.md at the product root (override with "system" in req0.json). Every Implement plans first: the agent Reads that map, writes derived/implement-plan.md, and asks if a schema change has implications. Continue / Skip answers land under Decisions. Coding starts only after that round closes. Each accepted plan is copied to derived/plans/<timestamp>.md. After Build succeeded, the coding agent updates docs/system.md. Missing map is fine on the first pass. Off when Implement is off. Prove still checks the app against the spec, not the plan.

Copy names-only env vars into .env as needed. Do not put secrets in .env.example.

| Variable | Used for | | --- | --- | | TYPESAFE_API_KEY | Judgment Check (Jev / TypeSafe System One) | | AWS_REGION / AWS_PROFILE | Amplify Gen 2 implement only. ampx does not read .env — export the vars or run npx ampx configure profile |

Prove

npx playwright install chromium

fixtures/runtime.yaml must parse (baseUrl, login selectors). Personas supply test emails and passwords.

Implement

Install the agent CLI you recorded: Cursor agent, GitHub Copilot CLI, Claude Code, or Codex CLI. --adapter=manual skips launch. Codex runs codex exec --json --sandbox workspace-write (not --full-auto or --yolo). npm / ampx that need network beyond the workspace may fail until you widen that sandbox.

Grammar (short)

requirement.md needs one # title and these ## sections: Business Rules, Use Cases, Roles & Permissions. Optional headings include Overview, Definitions, Data Definition, Verification Scenarios, Related Requirements, and Implementation Notes. Rules use Id: BR-001 with Statement and Observable. Use cases use Id: UC-001 with Actor, numbered Steps, and Outcome. The roles table cells are only allow or deny. Full rules: docs/grammar.md.

Docs

• What Req0 is
• Cockpit
• Architecture and CLI
• Glossary

This git repository

Clone if you are changing Req0 itself:

git clone https://github.com/richjava/req0.git
cd req0
npm install
npm test
npm start

npm start is req0 start via tsx. npm run build compiles the CLI to dist/ (what npm publishes).

This repo also contains a sample Invoice Desk app (Amplify Gen 2 + Next.js) and the golden invoice-approval pack. That app is not part of the published npm package. To run it from a clone: copy .env.example to .env, then npm run sandbox, npm run db:seed, and npm run dev. Personas: docs/requirements/invoice-approval/fixtures/personas.yaml.