Workspace vs release
Where you edit your specs versus what coding agents implement.
OriginAI keeps a hard line between the specs you're editing and the specs you've handed off. Most of the product follows from that.
The workspace
The workspace is the live set of project files you edit in the OriginAI workbench (internally, the rpml_files tree).
- You refine it with the canvas, the file tree, and the in-app agent.
- Before your first release, a coding agent may also write to it through the CLI (
write-document). - After your first release, coding agents still write through the API, but those writes become a change request a human applies in Origin (they do not mutate the live tree until then).
The release
A release is an immutable snapshot of the file tree taken at publish time, identified by a content hash.
- It's the default target for agent reads (
list-documents,get-document,get-diff, and so on). - It can be served as a public HTML preview under
spec.getoriginai.com. - Its history of hashes is the record of exactly what was handed to implementation, and when.
After the first release
Agents still read the latest published release. A write no longer mutates the workspace — it stages a change request that a human applies in Origin, then publishes.
| Who | Writes to the workspace? |
|---|---|
| A human in the workbench | Yes, directly |
| A coding agent via the CLI or origin-api | Stages a change request (suggested: true). Apply happens in Origin. |
Why: agents read release snapshots. Direct writes would overwrite in-progress workbench edits from a stale understanding. Staging keeps authorship with you without turning the discovery into a 403.
The loop after your first release looks like this:
- Agent (or teammate) stages a change request;
submit-proposalmarks it ready. - You review the diff, apply or dismiss (dismissals carry a reason the next agent will read).
- Publish a new release.
- Agents run
get-diff, implement the changes, andsync. A GitHub PR can bindproposal_idin.origin.jsonso spec-review judges the code against that change request.syncdoes not clearproposal_iduntil a new release hash exists.
Reading a specific source with the CLI
By default the CLI reads the latest release. Two flags let you read something else:
# Default — the latest published release
npx originai list-documents
# The live workspace (for pre-release indexing, or to verify a write)
npx originai list-documents --read-type workspace
# A specific historical release, pinned by hash
npx originai list-documents --release-tag <hash>