Project setup
Seeding the working model
Your coding agent writes the first body of all six working model documents on one change request. The team reviews it, and one merge writes the documents.
A new project starts with six empty working model documents. This page shows how to fill them for the first time, so that every agent that works on the project starts from what the team has decided.
The working model
The working model is the set of documents that record what the team has decided about a project: why it exists, whom it serves, what it is made of, how it behaves and what quality bar a change must clear. Roko Platform stores the documents in its database, not in a repository. Agents read them before they plan or write code. A document changes only through a change request: somebody proposes a new body as a model change, another member accepts it, and the merge writes it. See Working model for the full picture.
The project's sidebar lists the documents under Blueprint → Working Model.
Why, and for whom
What winning looks like, and the measures that prove it.
Who is served, and the job each of them is trying to get done.
What the system is
The things this project is made of, and the rules that always hold.
How the system behaves, step by step, including where it fails.
The decisions that are hard to reverse, and why they were taken.
The bar a change has to clear, and how that is checked.
| Document | It holds | A good document has |
|---|---|---|
| Goals & Metrics | What winning looks like, and the measures that prove it. | ## Objective, ## Key results, ## How we measure |
| Users & Needs | Who is served, and the job each of them is trying to get done. | ## Personas, ## Job stories, ## Pains |
| Domain Model | The things this project is made of, and the rules that always hold. | ## Entities, ## Relationships, ## Invariants, ## Vocabulary |
| Flows | How the system behaves, step by step, including where it fails. | At least three sections, one per flow |
| Architecture | The decisions that are hard to reverse, and why they were taken. | Entries under ## Decisions |
| Quality Plan | The bar a change has to clear, and how that is checked. | At least two sections, typically ## Guardrails and ## Non-functionals |
Reference material
Reference material is anything the team already has that describes the project: a product brief, a slide deck, interview notes, an existing architecture document. Upload it on the project's Artifacts page, where an agent connected to the project can read it.
The Setup page counts reference material as done when the project has at least one artifact. When there is none, select There is none on that row.
Seed the working model
Your agent writes the first body of every document on one change request. The change request carries one model change per document, so the team reviews the whole working model together and one merge writes all six documents.
Open your coding agent
Start your agent in a checkout of the project's code, connected to Roko Platform over MCP. See Connect over MCP.
Point it at all existing context
In the prompt, name the project and tell the agent to read everything the team already has: the artifacts, the code, and any document that already has a body. Add what only you know: decisions, constraints, the people the project serves.
I'm working in the Roko Platform project acme / widget. Open one change request that seeds the working model. Add one model change for each document: Goals & Metrics, Users & Needs, Domain Model, Flows, Architecture and Quality Plan. Read every artifact in the project and the code in this checkout first. Context the material does not cover: <your notes>.Review and iterate
Read each model change the agent proposes. Correct it and ask for changes until each document says what the team believes. When the material says nothing about a document, tell the agent to leave that model change out rather than guess.
Send for review and merge
An agent opens the change request in review. Another project member accepts it, because the platform refuses a verdict on your own change request. Then somebody selects Merge model changes. The platform writes every document, and the Setup rows for those documents close.
Project setup readiness
The Setup page lists what a project needs before an agent can do useful work on it. The page opens from Setup in the sidebar, or from Open setup in the amber banner that shows on every project page while setup is open. The page groups the rows into five areas:
| Area | Rows |
|---|---|
| Connections | Connect a code host, Register a repository, Set the agent's git identity, Connect a ticket tracker (optional) |
| Agents | Configure a model provider, Register and choose the default model |
| Team | Add the team |
| Working model | Supply reference material, then one row per document |
| First loop | Open the first change request, Merge the first implementation |
A document row is done when its document has any content.
When every required row is done, the banner shows Mark project ready. Select it to leave setup mode. Reopen setup on the Setup page, or the Project setup section on the project's Settings → Project page, returns the project to setup mode.
Best practices
- Start with Goals & Metrics and Users & Needs. The other four documents build on them.
- Give the agent everything first. Upload reference material before you seed, and name it in the prompt. An agent that has read the brief and the code proposes a better first draft.
- Correct, don't dictate. For the code-facing documents, let the agent read the code and fix its proposal instead of describing the system from memory.
- Review as the team. Iterate with the person who owns the decision. The document records what the team has decided.
- Keep each document short and specific. Agents read these documents on every run. A rule that nobody enforces is a wish: record it as one, or leave it out.
- Ask a different member to accept. The reviewer is the check that the document says what the team believes.