Add RCF Lite to an existing repository

Running rcf init in the project root adds a document tree under rcf/, merges an rcf entry into .mcp.json, and writes a managed instructions block into your existing agent instructions file (CLAUDE.md is preferred; AGENTS.md is written to only when CLAUDE.md is absent; both are created only when neither exists). Init never reads or writes source code. It refreshes existing instructions only inside the rcf:managed markers and preserves everything outside them. After init, restart the session so the agent reads the instructions and discovers the rcf MCP tools. It then asks what you want to build before drafting documents.

Before you start

• rcf-lite installed: npm install -g rcf-lite on Node.js 24 or later. Current releases refuse installation on Node versions below 24 (the preinstall check prints the detected version and fails), so check node -v first. npx rcf-lite <verb> works if you would rather not install it. Full install steps are in Wire your agent.
• A repository you are willing to let rcf init write into. The next section says exactly what it touches.

Initialise the project

This one step is a shell action; the agent-first work starts after it. Run init in the project root:

rcf init

Init scaffolds the rcf/ tree, including a knowledge space at rcf/knowledge/ and a gitignored per-clone operator profile at rcf/.identity/. It merges the rcf MCP server entry into the project-root .mcp.json, writes a managed instructions block into your agent instructions file, writes a managed block into .gitignore, and merges the feedback hooks into .claude/settings.json and .codex/hooks.json (skip them with --no-feedback-hooks). On a fresh project it creates CLAUDE.md (creating AGENTS.md too only when both files were absent); if CLAUDE.md already exists, it refreshes that file in place and does not touch AGENTS.md; if only AGENTS.md exists, it refreshes that file in place. Init also runs a Playwright MCP wiring pass on every project (adding a Playwright MCP entry to .mcp.json when no scope-visible one is present); opt out with --no-playwright-mcp. The browser-facing detection is separate: it gates rcf doctor checks around browser tooling, not the init pass itself. Re-running init is idempotent: it re-runs the wiring passes without rewriting existing chain documents.

On an existing repository, the contract is:

There is no --dry-run on init. The honest preview is to start from a clean tree, run it, and read the diff:

git status
rcf init
git diff

Everything init writes is an ordinary working-tree change. Nothing is staged or committed.

Set the boundary honestly: init is an entry point, nothing more. It does not retrofit traceability onto existing code, and it does not make a repository compliant on its own. You get the method wired in, your existing chain records untouched, and a scaffold that fills in from the next piece of work. If you want the tree without the agent wiring, rcf init --no-agent-setup scaffolds it and prints the manual steps.

Now restart your agent session so it re-reads .mcp.json and the instructions file. From here on, the interesting work is your agent's.

Turn to your agent, and see if the wiring took

This is the moment the exercise is really about. Your agent should now be operating under RCF, with whatever project rules you had before intact. The signal is not in the CLI, it is in what your agent says back:

AIYou should now be running under RCF. Has it taken?

Working sounds like a plain confirmation from your agent: it is operating under RCF, it can see the rcf tools, and whatever project instructions you already had are still in place. Ask it to build something small next, and it should start with elicitation questions rather than drafting straight into the tree. If you had a CLAUDE.md or AGENTS.md before, this is also the moment to spot-check the merge yourself: init only writes between <!-- rcf:managed:begin --> and <!-- rcf:managed:end -->, and everything else in the file is still yours.

Broken tends to show up as one of two common symptoms, though these are not exhaustive: the agent does not mention RCF at all (a session that started before init wrote the wiring is the usual cause; a project-root resolution issue for the MCP server, or an instructions file the harness does not actually read, are others worth checking); or the agent surfaces errors reaching the tools. For the first, restart the session so the harness re-reads .mcp.json and the instructions file it landed in. For the second (tool-reachability errors), inspect .mcp.json and the MCP server error the harness surfaced (a wrong project root, a stale server entry from a prior install, or an rcf-lite version the harness can no longer launch are the usual causes), then re-run rcf init to refresh the entry and restart the session. Separately, rcf doctor runs a small set of hygiene and browser-tooling checks (see rcf doctor --help for the current list) and rcf doctor --fix applies the supported safe repairs; it is not a wiring diagnostic for MCP reachability. The one shape you should not see, and the reason this step exists, is a silent regression on your existing instructions. Init only writes bytes inside the managed markers, so the bytes of any custom rules above or below them are preserved verbatim; semantic behaviour can still shift if a custom rule conflicts with the managed RCF rules the block adds, so if the agent behaves differently after the merge, do not paper over it. Walk git diff on the paths in the table above, check the marker positions, and read your own rules alongside the new managed block for any real disagreement.

Where this leaves you

The wiring is in, your existing files are still yours, and your agent is operating under RCF. Two things worth doing next, before you commit anything or ask the agent to build.

First, open the tree viewer and see what init just put in your repository:

AIOpen the requirements viewer for me.

Terminalrcf audit view

That serves http://127.0.0.1:4373/ in your browser, and it is the visible evidence of what happened. The Readiness tab opens first and reports what the tree still needs. The PRD tab shows the placeholder PRD your agent will fill in from your elicitation answers. The Requirements tab carries one placeholder requirement with one user story and one acceptance criterion, ready to be replaced. The Architecture tab shows the placeholders init seeded, and the Build tab's Specs sub-tab shows one placeholder FBS specification at build order 1. A real document tree, sitting beside code init never read. Using the tree viewer covers the five tabs in more depth.

Second, the question every real repository raises: what about the code that is already here? RCF Lite is chain-first by design. Its build cycle starts from a requirement and drives forward under the referee's watch, and existing code was not built that way. There is no official brownfield method yet that back-fills a chain over legacy code, and this page will not invent one. Put the question to your agent plainly:

AIWhat approach do you suggest for working with existing code and RCF?

Your agent has the packaged RCF guidance to hand: rcf guidance overview, rcf guidance document-model, rcf guidance build-cycle, rcf guidance elicitation-playbook and rcf guidance harness-template each print a section of the pack, and the same files sit under guidance/ inside the installed rcf-lite package. The shipped blueprints sit alongside them; each blueprint's guide/ directory explains when to reach for it. Treat what the agent comes back with as guidance, not an official brownfield method. What a good answer looks like is a plain grouping of your existing code. Work you are about to change or extend: bring it under a chain going forward, requirement first. Code that is stable and out of scope: leave it as-is, and let the chain fill in as future changes arrive. Anywhere your agent flags as risky or unclear: a targeted requirement plus a couple of acceptance criteria makes the next change to it safer. It is a plan you decide on, not a migration the agent runs.

From here, Wire your agent is where you paste in your first build instruction and the agent walks the elicitation playbook. For the document types the tree carries and how they link, see document types.