A project is the subtree Ravel-Lite controls during a cycle. It is not derived from where .git sits; it’s pure path math from where the plan lives. Given a plan directory at <subtree>/<state-dir>/<plan> (typically <subtree>/LLM_STATE/<plan>), Ravel-Lite computes the project as <plan_dir>/../.. and treats that subtree as everything it’s allowed to read, write, and commit.

The decoupling matters because the project can be a checked-out repository’s root, but it can equally be a subtree inside a larger monorepo. Ravel-Lite scopes its git operations — dirty-tree checks, baseline diffs, the analyse-work snapshot — using a pathspec on the project subtree, so sibling subtrees in the same monorepo are invisible. The baseline SHA itself is repo-wide (git can’t track anything finer), but every query against the baseline is filtered to the subtree. Commit-message conventions a monorepo enforces (conventional-commits prefixes, for example) aren’t automated by Ravel-Lite — the per-commit message authored by the analyse-work phase is the customisation point.

One consequence worth knowing: a single repository can host many subtrees, each with its own plans. Ravel-Lite stays out of their way as long as their plans live at the right two-level depth.

A plan is a directory of state files representing an in-flight body of work. Conventionally it sits at <project>/LLM_STATE/<plan>/, though the state-directory name is configurable. Inside it, every piece of state Ravel-Lite needs lives as a readable file:

A project can host multiple plans. Each is its own directory under LLM_STATE/ and runs its own cycle independently. Distinct plans may share backlog conventions but never share state — <plan_a>/backlog.yaml and <plan_b>/backlog.yaml are two different files with two different lifecycles. The State files reference documents the schema and lifecycle of every file above.

Ravel-Lite spawns a coding agent as a subprocess for every reasoning phase. Two backends ship today:

Selection happens once, when Ravel-Lite is invoked. The orchestrator constructs the matching agent implementation, hands it the per-phase prompt, and streams its JSON output. Switching agents mid-cycle isn’t supported — pick one, run a cycle, switch in the next cycle if you want.

Each backend has its own configuration directory under agents/<name>/, sibling to the project’s config.yaml. Pi additionally carries a subagents/ directory with definitions for the brainstorming, TDD, and writing-plans skills the orchestrator dispatches against during specific phases. The Configuration and prompts reference covers the per-backend layout in full.

Ravel-Lite is built around three principles. They’re worth understanding before digging into specifics, because every design choice further down the reference is downstream of one of them.

These principles play out in practice in two visible ways. First, there is no opaque state — every YAML file under LLM_STATE/ can be edited by hand between phases, and a hand-edit is just another input the next phase will read. Second, every cycle leaves a complete history. The git-commit-* phases tag commits with their phase name, so a later reader can scrub through a cycle the same way they’d scrub through a video.

The terms collected here recur throughout the rest of the reference. Each entry defines the term briefly and points at the page that specifies it in detail.