Agents should not start blind, and they should not grade themselves.
RoyceOS is a small, model-agnostic set of operating primitives for running AI coding agents on real work, across sessions, devices, and production systems.
It is not a framework you install. It is a way of operating that you can adopt incrementally: a boot order, a role split, an evidence bar, and a handoff format. The pieces are intentionally simple Markdown + shell templates so they work with any agent (Claude, GPT/Codex, local models) and any stack.
shared truth -> independent verification -> durable handoff
Most agent failures are not reasoning failures. They are operating failures:
- The agent starts a session with no memory of what is true, so it re-derives (and re-breaks) context every time.
- The agent that wrote a change is the same one that declares it "done", with no independent check and no runtime evidence.
- Work finishes, but nothing durable is written down, so the next session starts from zero again.
RoyceOS fixes these with four primitives that compose.
| Step | Primitive | What it guarantees |
|---|---|---|
| 01 Boot | Session Bootstrap | Every session starts informed, from a fixed source-of-truth order. |
| 02 Roles | Two-model split | One agent plans/builds; a different one verifies. |
| 03 Evidence | Codex Judge | "Done" requires runtime proof, not a claim. |
| 04 Handoff | Durable Handoff | The next session inherits decisions, proof, blockers, and the next action. |
Pick a strict order and put it in every agent's startup instructions. Example:
1. Project management (the human-owned plan: priorities, owners, gates)
2. Shared memory (durable docs, prior handoffs, decisions)
3. Live runtime (what the system is actually doing right now)
4. Chat history (lowest priority, it is lossy and ungoverned)
When sources conflict, the higher one wins. The agent verifies volatile facts (health, counts, status) against live runtime before acting on them.
Planner / Operator -> long-context synthesis, UX, orchestration, handoffs
Builder / Verifier -> repo + shell work, diffs, tests, runtime probes
The agent that implemented a change does not get to declare it done. A second agent reviews the diff and the evidence and returns a verdict.
A change is not complete until it produces proof appropriate to its risk:
- builds / typecheck / lint pass
- tests pass (and the relevant ones actually exercise the change)
- service health + smoke checks
- exposed ports / public routes are what you expect (and nothing more)
- owner approval for anything irreversible
Every unit of work ends with a short, durable record: what changed, the proof, open blockers, the next owner, and the next concrete action. The next session reads this first.
Some actions are never taken by an agent without explicit human approval:
- DNS cutover, domain moves
- payment / checkout activation, anything that moves money
- ad spend
- external account creation or mutation
- public launch / publishing
- secret rotation or printing
These stay NEEDS HUMAN regardless of how confident the agent is.
royceos/
├── README.md # this file
├── web/ # the public one-page explainer (static HTML)
├── primitives/
│ ├── agentos-bootstrap/ # session boot order, start rules, handoff format
│ └── codex-judge/ # independent PASS / BLOCK review loop
├── docs/
│ └── operating-loop.md # the full operating model, in depth
└── examples/ # copy-paste snippets for common agents
- Copy
primitives/agentos-bootstrap/session-bootstrap.mdinto your agent's startup instructions and fill in the placeholders. - Adopt the Codex Judge loop: never let the author of a change be the one who declares it done.
- End every task with the handoff template.
You do not need all four at once. Each primitive is useful on its own.
- Model-agnostic. Nothing here depends on a specific vendor or SDK.
- Plain text. Markdown + shell, so it is auditable and portable.
- Evidence over confidence. A claim is worth nothing without proof.
- Human gates for irreversible actions. Speed everywhere except where it bites.
MIT. Use it, fork it, adapt it.