Implementation
Working model
The working model is six documents that record why the project exists, whom it serves and the rules it follows. People and agents read them before they change anything.
Purpose
A team decides many things that the code does not show: whom the product serves, what counts as success, which words mean what, and why the architecture looks the way it does. When those decisions live in chat threads and in people's heads, every new person and every agent guesses them again.
The working model writes those decisions down in one place, in a fixed shape. People read it before they propose a change. Agents read it over MCP before they write a spec, review a change request, or build one. A spec describes one change and is done when that change ships. The working model evolves more slowly and lives with the project for its whole life. It works as a living PRD: the team updates it whenever the reasons behind the project change.
The six documents
Every project has the same six documents. You find them in the sidebar under Blueprint, in the Working Model group.
- 01 · OKRsGoals & Metrics
Objectives, key results, and how each is measured.
What does winning look like?
- 02 · Jobs to be doneUsers & Needs
Personas, job stories, and pains.
Whose job are we doing?
- 03 · DomainDomain Model
Entities, relationships, invariants, and vocabulary.
What are the things and rules?
- 04 · BehaviorFlows
Step-by-step behavior, including failure paths.
How should it act?
- 05 · DecisionsArchitecture
Hard-to-reverse decisions, with context and consequence.
Why is it built this way?
- 06 · QualityQuality Plan
The bar a change must clear, and how it is checked.
When is it good enough?
| Document | What it holds | Written as |
|---|---|---|
| Goals & Metrics | The objective, its key results, and the source and cadence of each measure. | Objectives and key results. |
| Users & Needs | Personas, their pains, and the jobs they try to get done. | Job stories: "When [situation], I want [motivation], so that [outcome]." |
| Domain Model | The core entities, how they relate, the rules that always hold, and the one name for each concept. | Entities, invariants, and a glossary, including banned words. |
| Flows | How the system behaves, step by step, including where it fails. | Numbered steps with failure paths. |
| Architecture | Decisions that are hard to reverse, and why the team took them. | Context, decision, and consequence for each entry. |
| Quality Plan | The bar a change has to clear, and how the team checks it. | Guardrails, non-functional requirements, and tests. |
Each document follows the same house pattern: one line that says why it exists, one principle as a blockquote, then the sections for its type.
How the working model changes
A document page is read-only. Nobody edits a document in place. A document changes only through a change request that carries a model change.
Change request
Model change
The full proposed body of one document, written against a base revision.
On completion
Merge
- Document unchanged since the base: applied as is.
- Document moved: three-way merge.
- Conflict: nothing is written. Rebase first.
Working model
New revision
Every changed document gets a new revision in one transaction.
- A model change holds the full proposed body of one document, not a diff. Roko Platform records the document revision it was written against.
- Members review the model change on the change request's Model Changes tab, beside any spec. See Change requests.
- The platform writes the document only when the change request completes. If the document has not changed since the base revision, the platform applies the proposal as it is. If the document has changed, the platform does a three-way merge.
- If the merge conflicts, the platform writes nothing and the change request does not complete.
Rebase
A model change goes stale when another change request updates the same document first. The model change card then shows a Base is stale tag and a Rebase button. Rebase replays the proposal onto the latest revision of the document.
- When the merge is clean, Rebase updates the model change in place.
- When the merge conflicts, a resolver opens with one card per conflict. Each card offers Keep mine, Keep theirs, Keep both, and Keep both and edit. "This change request" is your side and "Current document" is the other. Press Done when no conflicts are left.
- If completion fails with a conflict, the platform opens the Model Changes tab with the resolver on the first conflicting document.
The platform also rebases clean merges on its own when an implementation run starts and when an agent pushes. You resolve only real conflicts.
A new project
A new project starts with six empty documents. Ask your agent to seed the working model, and it opens one change request that carries a model change for each document. Seed the working model covers this step.
Writing guidance
These rules apply to every model change. Your agent follows them when it drafts one:
- Say it in one line. A single bullet usually beats a paragraph. If a line could be deleted without loss, delete it.
- Write principles that rule things out. A principle is one sentence you can hold a decision against. "No flow ships without a test covering its failure path" is a principle. "We value quality" is a slogan.
- Write needs as job stories. A form field is a solution. The job is the need.
- Give each architecture entry its context, decision, and consequence, so a later reader can tell whether the choice still holds.
- Use one name per concept. Define it once in the Domain Model and reuse it exactly everywhere.
- Prefer numbers to adjectives. Write "under 200 ms", not "fast".
- Mark what is provisional, and date it. Write "we do not know yet" where it is true.
| Smell | Fix |
|---|---|
| A principle nobody could violate | Sharpen it until it rules something out. |
| A paragraph where a bullet would do | Cut it to the one load-bearing line. |
| A feature disguised as a need | Restate it as a job story. |
| A decision with no reasoning | Add the context and the consequence. |
| Two words for one concept | Pick one and add it to the glossary. |
| A confident claim with no evidence | Mark it provisional, or cut it. |
Best practices
- Read before you propose. Have your agent read the relevant documents before it drafts a change request. A small change that fits an existing principle needs no model change.
- Change the model when the reasons change. A new goal, persona, concept, flow, architectural decision, or quality bar belongs in a model change, not only in a spec.
- Keep the model and the spec in their lanes. The model holds the why and the principles. The spec holds the how.
- Keep changes small. A model change that touches one or two documents is easier to review and less likely to conflict.
- Rebase early. When a card shows Base is stale, rebase before you ask for review, so reviewers read the text that will land.