What RIFF does
RIFF helps Codex turn your request into a clear plan, build it in useful steps, check the results, and remember where to continue.
You describe the application or improvement you want. Codex does the work. RIFF provides the instructions and progress records that keep that work connected to the goal. You can use it for a new idea or an application that already exists.
The project brief
PROJECT.md says what you are building, who it is for, what matters, and what is outside the current scope. It gives future work the same starting point, even after a break.
The roadmap
ROADMAP.yaml divides the goal into steps you can try. Each step has a priority and lists anything that must be completed first. RIFF calls a step a phase.
For a recipe app, a useful first phase is “save a recipe and find it again.” A later phase might add search. Each phase should deliver a usable result, rather than leaving you with several disconnected pieces of an unfinished feature.
Your first conversation
For a new idea, choose $riff:start. For an existing application, install RIFF, use $riff:map, then $riff:onboard. Once onboarded, use $riff:evolve to plan a product change. Describe the result you want in ordinary language.
$riff:start I want a recipe app where I can save a recipe, find it later, and read the ingredients while cooking.
For a production application, start prepares the complete version dossier: stories and success criteria, journeys, data and access rules, architecture, diagrams, and design. An independent review must pass before building. Scratch work stays lightweight. Use $riff:wave separately to begin implementation; start, onboard, and evolve stop after planning.
How much you direct
| Mode | What happens |
|---|---|
| Loop, the default | RIFF makes conservative choices, records assumptions, and continues through ready work. It preserves existing behavior and data and avoids adding speculative scope. |
| Guided | RIFF asks about the current planning decisions and pauses between phases so you can direct what happens next. |
You choose the mode during installation and can change it with riff-codex init --configure. Both modes still require the relevant checks. Uploading code to GitHub or putting the application online needs your instruction.
Installation
Install RIFF once in a permanent folder, then connect each application you want to use it in. Each application keeps its own plan and progress.
1. Check what you need
- Codex, installed and signed in.
- Git, which keeps the history of changes to your application.
- Node.js 20 or newer, with npm included. These run and install RIFF.
- Bun, which runs the dashboard and is required by the full setup check.
- A GitHub account with access to the private
alexadark/riff-codexrepository.
In Terminal, git --version, node --version, npm --version, and bun --version tell you whether those tools are available. Install any missing tool before continuing.
2. Download RIFF
git clone https://github.com/alexadark/riff-codex.git ~/riff-codex cd ~/riff-codex npm install npm link
Keep this folder in place: your projects will refer to it. If you already downloaded RIFF, use that folder and run npm install and npm link there. You do not need another copy.
3. Connect your application
Replace the example path with your application's folder. It must already use Git. For a completely new folder, run git init there first.
cd /path/to/your-project riff-codex init
RIFF asks about project scope, conversation language, document language, explanation level, and loop or guided mode. Press Enter to accept a suggested choice. This connects the tools; it does not write your product plan yet.
4. Make the skills available in Codex
Open the application in a fresh Codex session. Initialization adds RIFF entries to the project's skill picker. Choose the RIFF start, onboard, wave, or other skill there.
The exact $riff:... names in this manual are provided by the native RIFF plugin in the checkout's riff/ folder. npm link and riff-codex init do not enable the plugin themselves. If those names are unavailable, select the corresponding installed project skill. See the installation guide for the distinction.
5. Approve the automatic checks
Run riff-codex doctor first. If it reports matching system-managed hooks, reload Codex configuration or restart the app; no individual hook approval is required. Otherwise, open /hooks in Codex, review RIFF's project checks, and approve them. Hooks are checks triggered automatically at certain moments while work happens. After you have actually approved them, record that approval:
riff-codex doctor --record-hooks-approved
This records your approval and checks the setup; it cannot approve the hooks for you. Read any reported error or warning. A roadmap that has not been created yet is normal before your first start or onboard request.
Now choose start for a new product, or map then onboard for an existing application. Evolve prepares subsequent product changes. Use $riff:wave when the plan is ready.
Update RIFF or change preferences
To revisit the setup choices, run riff-codex init --configure in the application. To update RIFF, finish active work first, check that its permanent folder has no uncommitted edits, then run git pull --ff-only and npm install there. Run riff-codex resync and riff-codex doctor in each application afterward.
For this release, resync each connected project once. This refreshes local installation files, including newly available skills such as evolve and the hook configuration, while preserving its brief, roadmap and preferences.
Projects linked to the same RIFF folder already read its updated files. They do not need separate Git pulls or reinstalls. Start a fresh Codex session to load the updated skills. For model-routing-only changes, a fresh session is enough when the links are intact. Another checkout, machine or separately installed plugin copy needs its own update.
If doctor reports matching system-managed hooks, reload Codex configuration; individual approval is not required. Otherwise, review changed project hooks before recording approval. Restart an already-running dashboard process and reload its page to load server changes. The update guide explains the steps.
How the work moves
The brief and roadmap guide the build. Checks decide whether the result can be saved as complete. Saved progress tells RIFF what to do next. Select a step for an example.
Your request
Describe what someone should be able to do and why. Codex can investigate the application and the technical choices.
“Let me save a recipe and find it later.”
5 fails → correction → check again
A formal failed check permits a focused correction and one repeat. If it still fails, RIFF records a blocker instead of completing the phase.
7 → 3: the work loop
Loop mode selects the next ready phase, even after updating a draft PR. Guided mode pauses between phases. After the last phase, RIFF verifies the connected whole version and completes the final review.
Brief + roadmap + progress ⇢ dashboard
The dashboard reads the planned work, saved state, and short explanations of intended and verified results. Completed phases and blockers both appear there.
This is a one-way display path. The dashboard does not start Codex, run a phase, or change the plan.
What makes a phase ready
Each phase lists earlier work it needs. Search may need saved recipes first. RIFF does not bypass that requirement because search has a higher priority. Among phases that are ready, it chooses the highest priority; roadmap order breaks a tie.
Priorities run from P0, an immediate critical blocker, through P1, a high-priority outcome, to P2, normal planned work, and P3, optional work. A blocked phase can leave independent work free to continue.
How much planning happens first
A new production application or an explicit complete-version request gets a complete scoped dossier before building. PROJECT.md indexes the stories and observable criteria, journeys, responsive ASCII wireframes, design references and tokens, data model and permissions, integration contracts, Mermaid diagrams, risks, and verification strategy. ROADMAP.yaml maps useful outcomes to those criteria.
You can hand the wireframes to another design model. Its returned design and tokens join the dossier before implementation. A promised reference that has not arrived keeps the plan incomplete; RIFF does not invent a substitute. An independent review checks the complete dossier, and discovery check verifies that the review matches its current content.
Scratch work and bounded changes can stay light. Existing projects are not silently enrolled in complete discovery. Once enrolled, a changed dossier needs a fresh review. The plan covers the committed version, not every possible future feature or file.
Evolve an existing application
$riff:map Understand the existing application and save its map. $riff:onboard Reuse the map and establish the current product baseline. $riff:evolve Plan team invitations while preserving individual accounts. $riff:wave
Run these as separate requests. Map records the existing system; onboard reuses it without inventing historical phases. Evolve challenges the need, checks the current code and consequences, and revises the affected phases. It never installs or onboards a project automatically and never starts a wave.
For team invitations, the plan explains who can invite, what members can access, how removal works, and how existing private data stays private. Related suggestions, such as shared billing, are evaluated rather than automatically accepted. An exploratory discussion can end without changing the roadmap.
Completed history and active phase contracts stay intact. If a change conflicts with active work, its proposal stays outside the live dossier until a safe boundary. Future phases can be revised or replaced with an explicit mapping and updated dependencies. A bounded legacy evolution stays light; an enrolled dossier needs a new planning review.
Use $riff:add-phase for one already-understood independent outcome, and $riff:quick for a small separate implementation.
One change, one branch, one pull request
Wave establishes one integration branch and one PR for the coherent evolution or initial version. After the first validated phase, it opens a draft PR when publication is authorized. Later phases update the same PR. Creating or updating a draft does not pause loop mode.
After whole-version verification, independent delivery review, and the applicable finish --check gates, RIFF marks the PR ready for review and returns its verified URL. A standalone quick change uses its own branch and PR with bounded checks. Without publication authorization, RIFF completes local work and prepares the PR description first. Merge and deployment require their own authorization.
Who does the work
Codex coordinates the work using RIFF's instructions. It can use additional agents for useful, separate assignments. These are responsibilities that the work needs, rather than a fixed group of agents launched for every request.
| Responsibility | What it contributes |
|---|---|
| You | The goal, important preferences, corrections to direction, and authorization for publication. |
| Codex coordinating | Reads the project, chooses the next valid action, keeps work within scope, combines results, and reports what happened. |
| Planning | Turns the request into a product brief and demonstrable phases, with priorities and prerequisites. |
| Implementation | Builds the selected outcome and handles ordinary development feedback. An independent assignment can be given to a worker with clear ownership. |
| Functional review | Takes a fresh look at whether the actual change satisfies the request and relevant project rules. |
| Security review | Examines sensitive changes such as access rights, user data, payments, or migrations. It focuses on the changed boundary. |
| Diagnosis | Investigates a concrete failure before choosing a focused correction. |
RIFF's automatic checks and dashboard are software tools, not extra AI teammates. The original “band of six” slogan is retained as RIFF's signature; it does not prescribe an agent count in RIFF Codex.
When work can happen in parallel
Separate research or review tasks may run alongside implementation when useful. Editing assignments need explicit, separate ownership so two agents do not overwrite the same work. The coordinating task still owns integration and the final judgment. Parallel work is optional, not a quota.
How models are chosen
RIFF's routing reference matches the work to the required level of reasoning. Model availability depends on the current Codex environment. The table describes the repository's policy, not a claim about which model is running this page or your current conversation.
| Work | Repository policy |
|---|---|
| Inventory and exact extraction | Luna with XHigh reasoning effort. |
| Bounded implementation and repeatable checks | Luna with XHigh reasoning effort. |
| Planning, product decisions, synthesis, and final judgment | Astra with Medium reasoning effort. |
| Visual direction and acceptance | Astra with Medium reasoning effort. |
| Major design work or exceptional architecture decisions | Astra Medium by default. Escalate to a bounded High pass for a concrete difficulty, then XHigh only if High is insufficient. |
Astra decides; Luna executes defined work. Start with Astra Medium for planning, architecture and final review. Luna X-High handles inventories, extraction, defined code changes and checks. Return unresolved decisions to Astra Medium; escalate to High, then exceptionally X-High, only while the difficult problem needs it. Return to Medium afterward.
Sol has no default role in this policy. These instructions do not automatically switch the model selected in your current conversation.
Fast is used for Luna when the runtime exposes it. RIFF does not claim that Fast is active when it cannot select it. Read the model routing reference for the full conditions.
Checks and failures
A phase is complete when its promised result has been checked, the required reviews have passed, and the reviewed code has been saved in Git. Selecting a phase or finishing an edit does not meet that standard on its own.
| Check | What it answers | Recipe app example |
|---|---|---|
| Changed behavior | Does the feature actually work in the conditions the phase promises? | Save a recipe, return to the list, and open the saved recipe. |
| Functional review | Does the change satisfy the request and the project's rules? | Check that saving works and that the empty or error state remains understandable. |
| Focused security review | Could a sensitive change expose data or give someone access they should not have? | If recipes are private, check that another account cannot read them. |
| Completion record | Do the saved code and progress refer to the same reviewed result? | Record the checked recipe feature as complete, with its local Git commit. |
Why a review belongs to one version
RIFF records which exact set of files was reviewed. If those files change afterward, the old approval no longer describes the new result. The changed version needs fresh evidence before completion. The technical records are kept in the project's local RIFF state.
What automatic checks do
Hooks run at specific points in the workflow. They can flag a concern for review or block a high-confidence destructive or security problem. Warnings about possible access or input issues are not, by themselves, proof of a vulnerability.
RIFF avoids running a full test suite after every edit. It collects what needs checking and validates the affected behavior at the appropriate point. A credible high or critical security finding stops the phase until corrected.
Evidence you can inspect
Phase completion requires executed validation for the version being delivered. Required browser and smoke checks need recorded outcomes. RIFF saves local verification reports with the checks and available screenshots; a missing external check stays unverified.
Who handles observations
The implementing agent reviews technical warnings before finishing. It fixes confirmed issues within scope and records the evidence for resolved items or false positives. Unverified and out-of-scope items stay pending with a reason. You can inspect decisions in the dashboard, expand processed history, and reopen an item. A new occurrence reopens its group automatically. Triage never clears a phase blocker or replaces required checks.
If a check fails
- Codex can correct ordinary errors while building the feature.
- Once a formal RIFF check fails, the workflow permits one focused correction and one repeat of that failed check.
- If the correction still fails, the phase is recorded as blocked from completion. Independent ready work may continue.
Other reasons loop mode stops
- Required credentials or access are missing.
- A required check depends on an outside service and cannot be completed.
- A destructive action is authorized, but its exact target cannot be identified safely.
- A required check or review has failed and the permitted correction did not resolve it.
Ordinary product or technical choices are handled conservatively in loop mode. Guided mode also pauses for the requested decisions. A missing service check is recorded as missing evidence, not reported as a successful result.
Local completion and publication
A local commit saves reviewed work. With publication authorization, wave pushes that completed phase and creates or updates the same draft PR while continuing ready work. Final verification makes the PR ready for review; an open PR is not a merge or a deployment. RIFF verifies GitHub status separately from local checks and does not infer merge or deployment authorization from permission to open a PR.
Commands
Use the $riff:... commands in a Codex conversation, or select their corresponding project skills. Add the result you want in your own words. Terminal commands are listed separately below.
| In Codex | When to use it | What it does |
|---|---|---|
$riff:start | A new product idea | Prepares the scoped plan; production applications get a complete dossier and independent readiness review. Stops before building. |
$riff:onboard | An existing application | Reuses the map to establish the existing product baseline without inventing past phases. |
$riff:evolve | A change to an onboarded product | Challenges the request, analyzes impacts, and revises the affected plan. Stops before implementation. |
$riff:wave | Ready to build or continue | Builds and verifies ready phases, maintains the authorized evolution PR, then verifies the whole version. |
$riff:status | You need an update | Reports current progress, blockers, and the next action. |
$riff:dashboard | You want a visual overview | Opens the local progress dashboard. |
$riff:quick | A small separate change | Builds, checks, reviews, and commits a change that does not need a new roadmap phase. |
$riff:debug | Something is broken | Investigates the failure and aims for a focused correction. |
$riff:add-phase | One clear independent outcome | Adds one justified phase without broader replanning. |
$riff:map | You need to understand existing code | Maps application behavior, structure, and boundaries. |
$riff:learn-stack | Reusable stack conventions need evidence | Researches version-aware rules and merges them into project taste. NowStack has a dedicated baseline; frontend work uses design skills and rendered browser checks. Taste and stack research. |
$riff:incident | An application incident is active | Contains and investigates the incident within project boundaries. |
$riff:deep-audit | You explicitly want an exhaustive security audit | Routes the audit to Codex Security, when available. |
$riff:promote | You explicitly request promotion to production | Handles the promotion boundary and required evidence. |
$riff:issue | You explicitly want a GitHub issue | Publishes grouped work from the current project plan. It is not an automatic wave step. |
$riff:debug I click Save after entering a recipe, but it never appears in the list. I expected to see it immediately.
For a small change, try $riff:quick Make the empty list explain how to add a recipe. For one clear outcome, try $riff:add-phase Let me share a recipe with a friend.
In Terminal
| Command | Purpose |
|---|---|
riff-codex init | Connect the current Git project to RIFF. |
riff-codex init --configure | Revisit languages, explanations, scope, and autonomy. |
riff-codex doctor | Check the installation without recording new approval. |
riff-codex resync | Refresh the managed links and hooks after an update. |
riff-codex status | Read saved project progress. |
riff-codex dashboard | Open the shared local dashboard, normally on port 4000. |
riff-codex dashboard --snapshot | Print the dashboard's data snapshot. |
riff-codex --help | List the available terminal operations. |
Terminal wave operations manage RIFF's records. The conversation skill $riff:wave coordinates the actual build. This repository has no riff-codex next command.
Progress and resuming work
The roadmap describes the work. RIFF's local state records where that work stands. Short explanations make the intended and verified results readable in the dashboard.
| Dashboard column | Meaning |
|---|---|
| Todo | Planned work. A phase can only be selected once the earlier work it needs is complete. |
| In progress | The phase is active. It has not yet met the completion checks. |
| Done | The required checks and reviews passed and the reviewed result was committed. |
| Blocked | A recorded problem prevents completion. The underlying state can be parked, blocked, or awaiting action. |
| Skipped | A status supported for imported older roadmaps. RIFF Codex does not silently skip committed work. |
Return to the same project
$riff:status
Read what is active or blocked. Once a real blocker is cleared, continue with the same wave command:
$riff:wave
RIFF resumes active work or chooses the next ready phase using the saved state. You do not need to recreate the plan or edit a progress file yourself.
What the dashboard reads
The shared dashboard is a local Bun application. It reads registered projects, their plans, and saved progress. It also shows explanations written before a phase and updated with verified results after completion. It does not call Codex or Claude, use an AI API, or execute a wave.
The usual address is http://127.0.0.1:4000. This documentation page is a separate manual; it is not the live project dashboard.
Resume the same delivery
Wave checkpoints preserve the phase context, next action, and references. On resume, RIFF reconciles the actual branch, remote head, and PR identity before continuing. It reuses the same open PR for the same change and never automatically reopens a closed PR. A completed local phase does not imply its PR was merged.
What is saved where
PROJECT.md and ROADMAP.yaml live with the application. Progress, review records, events, and dashboard explanations live in .riff-codex-state/. That local folder is excluded from Git.
Returning to the same working folder preserves that local context. A clone on another computer does not automatically contain those progress records. Do not treat the dashboard as a backup, or edit the saved state to mark work complete.
Using Claude RIFF in the same application
Claude RIFF and RIFF Codex can share the project brief and roadmap. Their tools and progress folders remain separate: Claude owns .riff and .riff-state/; Codex owns .riff-codex and .riff-codex-state/. Only one should execute a given phase at a time.
The Claude manual explains a different runner, with different commands and roles. This page retains the useful explanation topics but describes this RIFF Codex repository's actual behavior.
Reference
These files contain the detailed instructions behind the behavior described here. The project brief and roadmap remain the shared product sources; this manual is an explanation of how RIFF uses them.
- Discovery and readinessComplete version planning, design handoff, and independent review.
- Product evolutionBrownfield prerequisites, impact analysis, and roadmap preservation.
- Branches and pull requestsOne PR across waves, publication, resume, and final readiness.
- Installation guidePrerequisites, skills, hook approval, updates, and setup problems.
- Everyday useExamples for new ideas, existing applications, small changes, and fixes.
- How it worksThe project flow, who does what, and what completion means.
- Technical referenceFile locations, terminal commands, and coexistence with Claude RIFF.
- Operating contractPhase selection, autonomy, retries, reviews, and completion rules.
- Project framingWhen a larger project needs more detail about users, data, rights, and integrations.
- Model routingThe model and effort policy for different kinds of work.
- Security boundarySensitive changes, findings, and the required review.
- Dashboard contractHow readable phase explanations are produced and displayed.
- Dashboard setupThe standalone dashboard's configuration and operation.
Internal files
| Path in your application | Purpose |
|---|---|
.riff-codex | Link to the permanent RIFF checkout's framework folder. |
.agents/skills/riff-codex-* | Project entries that expose the RIFF skills. |
.codex/hooks.json | RIFF checks merged with the project's existing Codex hooks. |
.riff-codex-state/config.json | Preferences and recorded approval of the current hooks. |
.riff-codex-state/state.json | Current progress. Written only through RIFF's commands. |
.riff-codex-state/receipts/ | Check and review evidence tied to the reviewed code. |
.riff-codex-state/events.ndjson | A short history of events. |
.riff-codex-state/dashboard/phases/ | Explanations of planned and verified phase results. |
Initialization also chains existing Git pre-commit and commit-message hooks. It preserves foreign Claude files and does not rewrite an existing roadmap just to change its format.