Kick the tyres by hand

This walkthrough uses the CLI to demonstrate RCF Lite's checks on a throwaway project. Allow about ten minutes. Day-to-day use is through a coding agent; Wire your agent covers that setup next.

First: Node 24, then the install

rcf-lite requires Node.js 24 or newer. Check before you install, because the failure on an older Node is silent:

node -v                    # must print v24 or higher
npm install -g rcf-lite
rcf --version              # expect 0.36.1 or later

On Node 22 or older, npm install -g rcf-lite reports success but installs an old placeholder release that contains no CLI at all: rcf never lands on your PATH. The only tell is a single npm warn deprecated rcf-lite@0.0.1 line before added 1 package, easy to miss on a scrolling install. If rcf --version comes back command not found, check whether the installation succeeded and whether the executable is on your PATH instead of assuming the Node version is the cause. Install Node 24 (brew install node@24, or your platform's equivalent), then install again.

Scaffold a throwaway project

mkdir plant-log && cd plant-log
rcf init --non-interactive --project-name "Plant log" --no-agent-setup

--no-agent-setup skips the agent wiring, because there is no agent in this walkthrough. You get the document chain under rcf/: a PRD, one requirement, one user story with one acceptance criterion, architecture placeholders and a one-item build queue, all carrying TODO text for now.

One honest side effect of that flag: rcf doctor on this project will report drift for exactly the pieces you skipped (the gitignore managed block, the knowledge space, the operator profile). That is the doctor doing its job, not something to fix mid-walkthrough. When you graduate this project to a real agent setup, run plain rcf init in the same directory: it leaves the document chain untouched, seeds the skipped pieces, and rcf doctor comes back clean. Re-running rcf init --no-agent-setup on the existing project is refused with exit 2 and writes nothing because the RCF tree already exists.

Open the viewer in a second terminal and leave it running. Every change you make below streams straight to the browser tab:

rcf audit view

Fill in a small chain

The tool assigns ids; you fill in content. Give the scaffolded documents something real:

rcf define update PRD-001 --set problemStatement="Notes about house plants live on scraps of paper." --set objectives.0="One list of plants and when each was last watered."
rcf define update REQ-001 --set title="Plant log" --set description="Users can record a plant with a name and a watering interval." --set domain=log
rcf define update US-101 --set title="Record a plant" --set asA="plant owner" --set iWant="to record a plant with its watering interval" --set soThat="I know when it is next due" --set acceptanceCriteria.0.description="Recording a plant with a name and an interval succeeds"

Every write is schema-validated on the way in. Now ask the referee about the whole tree:

rcf define validate

rcf define validate: tree is clean.
notice: 5 document(s) still carry scaffold TODO placeholder text (informational; exit code unaffected):
  ...

Clean, exit 0. The notice lists the placeholders you have not filled in, and leaves the exit code alone.

Break it, and watch the referee catch it

The JSON files are the source of truth, and hand-editing them is legitimate, so prove the referee catches drift. Open rcf/user-stories/us-101.json in an editor, change reqId to REQ-999, save, validate again:

[error] brokenReference US-101: US US-101 references unknown REQ REQ-999
[error] 1 error found.

Exit 3, the tree-is-unsound code, and the same answer an agent would be refused with. Change it back and validate once more. Clean.

Coverage is the same honesty applied to tests. rcf audit coverage reports REQ-001 uncovered right now, because nothing in the tree names a test, and rcf audit trace US-101 --both walks the story's ancestry and descendants. Mechanical questions, mechanical answers.

Drive one build item forward, then try to cheat

rcf define update FBS-001 --set title="Record a plant end to end" --set summary="Implement the plant model, storage and the record flow behind AC-101-1."
rcf build queue
rcf build mark FBS-001 inProgress
rcf build mark FBS-001 complete --no-code-nodes

The queue shows the item actionable, then the two marks walk it forward. --no-code-nodes waives the gate that normally demands a Code Node tying each acceptance criterion to real source, because this walkthrough has no source; in a real build the agent authors those and the flag stays off. Now try to go backwards:

rcf build mark FBS-001 inProgress

[error] refused build: refusing backward transition complete -> inProgress on FBS-001

Exit 4, the refused code. The lifecycle is forward-only, and the refusal names the deliberate-correction escape hatch rather than silently allowing the walk-back.

What you just proved

Ids assigned by the tool, every write schema-checked, drift caught with a named error and a meaningful exit code, a forward-only build queue that refuses to walk work backwards. That is the referee your agent works under.

FBS-001 is now sitting at complete, one stage short of the end of the cycle. If you want to watch the loop actually close, keep the directory: Close the loop without a deploy carries this same project through a verifier run against a local server and on to the finalise gate. Otherwise delete it; the real setup is Wire your agent, and the full command surface is in the CLI reference.