Files and README
Organize your specs across the file tree, the README, and structured screen files.
Your product context lives in files. Keeping your rules and screens in well-organized files gives people and coding agents a single, shared structure to work from. This guide covers how those files are typically arranged and how to keep them consistent.
How the files fit together
| Kind of file | Typical name | Its role |
|---|---|---|
| Product design doc | README.rpml (mode="doc") | The overview: modules, routes, flows, and permissions. |
| Screen or region | *.rpml | A single page or region, with its states and annotations. |
| Supporting files | other project files | Notes and references to assets, as needed. |
The README is your map. Each screen file is a location on that map. When they stay aligned, anyone can navigate your product from the README alone.
The detailed RPML syntax that agents use lives in the skill's rpml/ references, which are installed when you run originai link --skill.
Keep your files aligned
- Open the file tree in the workbench.
- Read
README.rpml(or its equivalent) for the product map. - Open each critical route's
.rpmlfile and confirm it's covered on the canvas. - Edit in the UI or with the in-app agent, and keep the README's route list in sync with the files that actually exist.
- Publish once the file tree matches what you want agents to implement.
Writing files with an agent before your first release
A coding agent writes the workspace directly only before the first release is published. During that window, a typical loop looks like this:
npx originai validate --content "<rpml>"
npx originai write-document --name "README.rpml" --content "<rpml>"
npx originai list-documents --read-type workspaceAfter your first release, the write guard takes over: agent writes stage a change request instead of mutating the live tree. You still edit the workspace directly in the workbench.
You're in good shape when…
- Your critical rules live in files, not only in an agent's chat history.
- Every page the README plans has a matching
.rpmlfile.