How to get a working product out of CodeRealm

1 · What CodeRealm is

CodeRealm is a place where a description turns into software. You write, in ordinary language, what you want to exist. The platform interviews you until that description has no holes left in it, writes the specification and the technical plan, breaks the work into small pieces, gives those pieces to AI agents that write real code, and then checks every piece before it is allowed to count as finished.

You are not asked to program. You are asked to decide — over and over, in small, answerable questions. That is the whole trade: the platform does the building, you supply the judgement about what “correct” means for your product.

What you need to bring

• An idea you can describe in a few sentences — what it does, who uses it, what would make it good.
• Patience for an interview. Storyteller, the orchestrator, will ask questions before it writes anything.
• Willingness to answer “which of these two behaviours do you want”. Every unanswered question is a guess someone else makes for you.
• A Claude subscription on some machine you control — either the server already has one, or you install a small program on your own computer (section 12). The agents are paid for by that subscription; nothing in this platform spends anyone else’s.
• spec-kit on that same machine. It is the public, open-source toolkit that writes the specification, the plan and the task list; the platform drives it exactly as it is and ships no copy of it. Installing it is one command (section 12).

What it is not

• Not a chatbot that pastes code at you. The output is a git repository with history, tests and documentation — the same thing a development team would hand over.
• Not a drag-and-drop app builder. There are no templates. What gets built is what your specification says.
• Not a machine that removes you from the loop. It stops and asks whenever a decision is genuinely yours, and it refuses to invent an answer quietly.

Why the fantasy names

The method is called DoD — Deploy or Die, and its vocabulary comes from tabletop role-playing games. You are the GM (Game Master): the person who runs the game and decides what counts. The workers on a project are a party. What each worker is trusted to do is a competency at a level, and they earn XP for work that is accepted. The names are playful; the mechanics underneath are ordinary, strict project management.

The method’s name is the part that is not playful. Deployed is the only definition of finished this platform accepts — not written, not reviewed, not merged. Every rule in section 9 exists to stop work being called done one step earlier than that.

2 · How it works, start to finish

Everything below is one long loop. It is worth reading once before you start, because every screen in the platform is a window onto one of these stages.

Whose Claude session pays

There are no API keys anywhere in this platform. Every run — an agent, the Storyteller, a reviewer — is started through the claude command-line tool signed in on some machine, and that sign-in is a person’s own Claude subscription. The platform never holds it, never copies it and never lends it:

• On your own Mac (CodeRealmApp, or a site you run for yourself) everything runs on the claude signed in there. Yours.
• On a shared site each person connects their own computer as a host (section 12) and their work runs there. A project’s runs go to its owner’s hosts; a chat runs on the host it was started on. If none of your hosts is online, your work waits — it never moves to someone else’s machine.
• The server’s own claude, if there is one, belongs to the person who set the site up. Only they run on it. A second GM is a second subscription and needs their own host.
• A spent usage window pauses one host — the one whose subscription hit the limit — for ten minutes at a time. Everyone else’s hosts keep working.

If you have never used an AI agent before

An agent here is an AI model that is given a task, a copy of the code, and a terminal, and works on its own for a while — reading files, writing files, running the tests — until it decides the task is done. It is not a person and it does not remember yesterday. Two things follow that matter for you: it does exactly what the written task says, so the words of the task are everything; and it can be wrong with complete confidence, which is why nothing it produces counts until the checks in section 8 have run.

3 · The words you will meet

Skim this now; come back when a word bites.

People and roles

Work

Words from the world of code, in one paragraph each

4 · Getting an account

5 · A tour of the screen

The menu, on every page

On a computer the menu sits on the left; on a phone it opens from the button at the top left. It has three main entries, two for the workspace, and the rest at the bottom:

• Search or jump to… (or ⌘K / Ctrl K) — type part of a page or project name and press Enter.
• Home — what needs you, and your projects.
• Inbox — everything that waits for a person, with a counter. Only things nothing moves past without you are counted: a task whose verdict is yours, a project whose work nobody can take, an interview waiting for your answer.
• Projects — every project, with filters and a search box.
• Agents & machines — the assistant, the machines agents run on, the agents and people who take tasks (section 7).
• Insights — which agent to trust with what, and what finished work costs.
• Help — this guide. Signed out, it is the only entry, next to Sign in.
• Settings — the theme, your account, the skills list, and for the owner the people of the site.
• Light theme / Dark theme — CodeRealm opens dark; the light theme is the readable one outdoors. The choice is remembered in that browser.
• Your name, with a key button to change your password and a button to sign out.

Home

It refreshes itself every thirty seconds. From top to bottom:

• A note when agents are paused because a machine’s Claude usage window is spent, with the minutes until they resume by themselves. Nothing is lost and nothing is asked of you.
• Needs you. The things waiting for a person, oldest first, each with one button: a task waiting for your verdict (Check), a project whose ready work no agent can take — the skill is missing or not deep enough (Choose a fix, section 17), a project whose agents sit on a machine that is offline (See machines), a pipeline silent for fifteen minutes with work queued, and an interview waiting for your answer. Five are shown; the rest are in Inbox.
• Projects. One line per project: its name and key, how many tasks are accepted out of how many, and its state in words — Stuck · needs you and Waiting for your check in amber, Building, Done, Paused. Filter by Active, Paused or Done. New project starts the interview with the assistant; Create manually makes an empty project for people who already have a specification to import. Both are shown to leaders and the owner only.
• Agents at work, folded: every task an agent holds right now, and who holds it.

A site with no projects shows a short Get started list instead: connect a computer, describe your first project, answer when you are asked.

Inbox

Two lists. Needs you is the same list as on Home, with the selected item opened on the right: why it waits, and buttons to open the task or the project. Updates is everything the platform reports that needs no action from you — a machine that stopped answering, a runner that refused an update, a background run that failed, what the platform repaired by itself, and every verdict passed on work lately. Mark all as seen clears the count. A fault that keeps happening shows a count instead of repeating.

Create manually, in detail

A small form: Key (a short code, forced to capitals, and permanent — it is the prefix of every task number, like PHOTO-T012), Name, Description, then Create. The project is empty: no artifacts, no tasks, no repository yet. Your next stop is Specification › Import.

Inside a project

Under the project’s name, key and state, seven tabs. Three of them hold a second row of views. Section 7 covers each:

The address remembers the tab, so a link can open a project straight on its tasks, or on one task.

6 · Your first project, step by step

Read this section once through before doing it. The whole run, for something small, is an evening of your attention spread over a few hours of the platform working.

11

Let it converge, then read the bugs

When every task is accepted, two things happen by themselves, in order. First Convergence: the code is assessed against the specification, and anything asked for but never built comes back as new tasks (priority P1, level L2, in a phase called Convergence N), classified and dispatched at once. Its report lands in Artifacts as Convergence — commit. When it reports converged for the current main, the Golden User runs: an agent instructed to behave like a newcomer — clone the project, follow the README, install it, run it on real data, and compare what happens against your requirements, not against the code.

Anything that does not match is filed on Bugs with a reproduction. From there: Create fix task sends one back into the pipeline, or Send all to tasks sends every open one. A fix is only accepted with a test that catches the defect — so the same bug cannot come back unnoticed.

The button Send in the Golden User in Activity › Bugs forces a run right now — even if convergence has not finished and even if this commit was already examined. It costs a run of the strongest model; press it when you want a fresh outside look, not as a way to skip convergence.

Why this step exists

A real project once passed 122 tasks with every gate green and still did not do the one thing it was for. Every gate reads code; none of them had ever used the product. That is what the Golden User is for, and it is why the last word belongs to someone who only looks at the outside.

7 · Every screen, in detail

Specification — the documents

The project’s documents, as a tree. Pick one to read it; markdown is rendered. Each carries a status badge — draft, approved or obsolete — which is a label for people, nothing in the pipeline reads it. Documents that came out of the specification pipeline — the spec, the plan, requirements, stories, test cases, the constitution, and imported design notes — are read-only: their Edit button is absent and the title says why. Notes you add yourself stay editable. Reports the platform writes (acceptance reports, the specification analysis, convergence and Golden User reports) appear here too.

• + New Artifact — status, parent, title and body of a note. That is the only type you can create by hand: every spec-kit type would be read-only the moment it was saved, and nothing would link it to any task.
• Delete — on notes you wrote. Spec-kit artifacts have no Delete: removing one is an edit of the specification too, and the platform refuses it the same way.
• Traceability — the links to other artifacts. + link asks for a direction (this → or → this), a type and a target found by title. Types: derives (a story comes from a requirement), implements (a task or note realises it), verifies (a test case checks it), relates (anything else). Links may not point at themselves, be duplicated, or cross into another project. Hover a link for its ✕.
• History — every saved version, with Revert to this version on any version but the latest. A new version is stored on every change; identical saves do not create noise. Reverting is for the project’s GM or leader.
• Baselines — pin the current version of every artifact under a name (for example v1.0-spec-freeze). Opening a baseline later shows how many documents changed since, and which are changed or deleted. Creating one is for the project’s GM or leader; the ✕ next to a baseline removes it without asking. This is how you answer “what did we agree to, exactly?”.

Specification › Traceability

A picture of the project shaped like a V: what was asked for on the way down (specification, user stories, requirements, plan), what checks it on the way up (acceptance count, test cases), and the tasks along the bottom with four counters — pending, in work, verifying, accepted. Everything is clickable — a requirement opens the artifact, a task opens the task. The bottom row shows twelve tasks and says +N more in Tasks for the rest. Use it to find requirements nothing verifies.

Tasks

Three views of the same tasks. List, the one that opens, groups them top-down by what is happening — waiting for a check, in progress, ready, backlog, accepted, rejected — and hides an empty group; long groups show their first rows and a button for the rest. Board is the same as columns, Table a sortable table with checkboxes for changing many tasks at once. A click on any task opens it.

The line above the tasks reads, for example, 64 tasks · 58 accepted · 2 waiting for a check · reviews overturned 1/25 · came back 3/58 · $41.20 spent of $60. The two fractions are the trust numbers explained in section 10.

Banners that can sit above the board:

• Specification findings, in amber, with the analysis text and two buttons: Analyse again re-runs the check after you changed something, and Start anyway… asks for a reason of at least ten characters and lifts the hold. After a waiver a grey line stays: Specification findings waived by name: reason.
• Budget spent — $X of $Y. Nothing more is dispatched until the cap is raised in Settings. Work in flight finishes.

Board shows the seven columns (on a phone: chips, one column at a time, the first non-empty one by default). Table shows everything at once with a checkbox per row and one to select all; the bar N selected · Class · Level · Priority · Apply · Clear changes the selected tasks in one go, leaving any field set to keep alone. Top-right buttons:

• Dispatch all — hand out everything that can currently be handed out. Greyed out, with the reason on hover, while the specification gate or the budget holds the project.
• Classify — run the arbiter over the tasks again to set competency, level and oracle. It runs in the background with a counter (Classifying 12/122…) and ends with a summary: how many were classified, levels, competencies, New competencies created and — the line that matters — No active executor has a skill in: … These tasks will not dispatch until you grant skills on the Agents & machines page. Note that a re-run overwrites the oracle too, including a requires judgement you set by hand.
• New Task — add work by hand, with title, description, class, level, priority and oracle. Create stays grey until there is a title. A task with class (none) is never dispatched: give it a class, or run Classify.

Each card shows its code, priority, level, class in short form (auto, agent → you, judged for the three oracles), who holds it, and — once it has cost anything — a dollar amount.

Opening a task gives you its full record:

• the description, and its phase from the task list;
• Class / Level / Priority / Oracle as drop-downs that apply the moment you change them, no Save. Once an oracle has been lowered from requires judgement it cannot be raised back from here;
• Depends on — chips with ✓ for accepted blockers and … for open ones, a ✕ to remove, and + add dependency… listing this project’s tasks. Cycles, self-dependencies and other projects are refused;
• the branch, the blue or amber banner from step 9, and the button row;
• Mark ready — releases a Backlog task without dispatching it. Shown only while Auto-dispatch is off; with it on, Dispatch is the button;
• for a human executor: Start, then a field for the branch or commit they worked on and Submit;
• the acceptance report, Verification runs (newest first, each passed / failed / not run with its kind — local for the test command, smoke, manual), and History, the complete event trail with the data each event carried. Money spent on this task is shown here as model spend on this task.

The oracle deserves a moment. It answers “who decides this is done”:

A requires judgement task offers two waivers instead of the drop-down: let an agent do it… (the agent produces the result, you still accept it) and fully automate… (a machine check is declared sufficient). Both demand a written reason of at least ten characters, and the reason is kept in the record and printed in the acceptance report. That is deliberate: downgrading a check is allowed, doing it invisibly is not. The one exception is Classify, which re-decides every oracle by itself — run it before you set oracles by hand, not after.

Activity › Bugs

A defect found after acceptance belongs here, not in a new task — here it keeps its reproduction, its link to the requirement it breaks, and the proof that it is gone. The header counts N open · M total; each card is BUG-id, its state, its severity and, once one exists, its fix task.

Report a defect asks for what is wrong, detail, severity (low to critical), where it was found (a commit, a version, a run), how to reproduce it, what you expected, and what actually happened. A bug moves new → triaged → fixing → resolved → verified, or is closed as wontfix with a reason. The buttons follow the state:

Every reported bug is assessed right away by spec-kit's bug-assess skill, on the project owner's host, against a fresh checkout of main: the bug's detail shows the suspected root cause, the files, a proposed remediation and a suggested severity with its confidence, and the full assessment under a fold. It is advice, not a verdict — triage still sets the severity — and it is handed to the fix task so the executor starts from it. assess again repeats it after main moved or when a run failed.

Create fix task makes a P1 task tied to the bug; Send all to tasks appears when there are new or triaged bugs and does it for every one, reporting any it skipped. The fix task is held to the proof rule in section 9. At the bottom of a bug, the Trail lists every state change with who made it and their note.

Code › Repository

The actual code. A branch selector (main by default), Files to walk the tree with breadcrumbs, file sizes and a viewer (binary files are named, very large ones truncated), and Commits listing the last sixty with what each changed — click one for its diff, ← commits to go back. You do not need to understand any of it — but it is here, it is yours, and it is not a rendering of something that lives elsewhere. A project created with Create manually has no repository until its first agent task runs; the tab says so.

Code › Run it

Start does not exist until the product is expected to show something. When tasks are imported the Storyteller names the task after whose acceptance a person can first use the product — usually the end of the MVP phase — and the tab says which task that is and where it stands. Ask the Storyteller again re-judges it; the owner can also set it in the project's settings. Once that task is accepted and the product still does not work,Report: RealRun does not work files a critical bug with everything the platform saw and creates its fix as an urgent task: nothing else is dispatched while that fix waits, and the next executor to finish — by acceptance or rejection — takes it. Running work is never interrupted.

Pressing Start then answers a question the frame cannot: should it work? The platform says whether the product is expected to work at this point of the project, and if it should but does not, why. It reads the run itself (did the process start, did anything answer on the port, does the page name files the server does not have), the host's environment (are the project's tools installed where it runs) and the project's progress by phase — a product whose MVP phase has no accepted task is expected to show nothing, and the panel says so rather than leaving you to guess. Openphases under it for the accepted count of each.

Start / Stop / Reload, an open in a tab link, and Show log. It runs the accepted code from main, at the commit shown in the corner, and reports up 3m 12s while alive. Finished cleanly (exit 0) is a success for a tool that does its job and stops; a red exit code means it fell over and the log says why. If the project has no run command yet, this tab tells you so and points at Settings. Starting needs the owner or GM; looking does not.

From any machine other than the server itself, the product is shown through a proxy and the tab says proxied — deep links inside the app may break: a web product that jumps to an absolute address inside itself will lose the frame. Everything else works. From a phone this is always the case.

Settings › Team

The Balance table (see step 6) with a Party coverage column naming who covers each competency and an Unreachable count — open tasks above the best implementer’s level; then the current party as cards (kind, inactive if so, queue 1/2 against the WIP limit, skills with XP, Remove), and the executors available to Add. Each party member can hold two roles, toggled on the card:

• implementer — receives dispatched tasks. Without it, nothing is ever handed to them.
• reviewer — may verify, accept or reject other people’s tasks in this project. Never their own. A human needs to be linked to their account for this (Agents & machines → Edit → Linked user); until then the button is greyed with the reason. A local-model agent cannot take this role; a GM executor shows no role buttons at all.

Activity › Log

Every event in the project, newest first, loaded a hundred at a time (Load more). Filter by type with the chips (each shows its count; several can be on at once), by task number, and by free text in the event data; Clear resets. When you want to know why something happened three hours ago, this is where the answer is. Every submission and every review also carries what it cost — tokens read, written and served from cache, and dollars — so the log answers “where did the budget go” as well as “what happened”. Section 19 lists the event types worth knowing.

Specification › Import

For projects that already have a specification. Four tabs — constitution.md, spec.md, plan.md, tasks.md — each taking a pasted text or an uploaded .md/.txt file (a dot marks the filled ones). Under Design docs, + Files adds any number of supporting documents, guessing their place from the file name (research, data model, quickstart, contracts, checklists), and + Paste takes a path and text. Import becomes active once anything is filled and ends with Imported: N artifacts, N links, N tasks. Everything becomes artifacts, links and tasks exactly as if Storyteller had produced them — including the specification analysis, which starts at once and holds dispatch until it answers.

Settings › Project

Every field is applied by Save at the bottom; the labels in the interface are the long versions of this table.

Below the fields, Environment lists the tools the project needs on the machine its agents run on — your host. The line Checked and installed on names that host (a drop-down when you have several). Each tool shows its state there — present, missing, installing, install failed, unknown — with Check and, where possible, Install and its Log. Both run on that host, through your runner, as your user: nothing is installed on the server. The install command was written by a model from the project’s documents, so it is shown on the card and again in a confirmation before anything runs. The same tool can be present on one leader’s laptop and missing on another’s; each sees their own answer. + Tool adds one by hand (key, name, check command, install command, manual steps) to the shared list; ✕ unlinks it from this project. Extract from docs rebuilds the list from the plan and quickstart. Generate scaffold commits a portable editor workspace and a setup document to the repository. The list refreshes every five seconds.

At the bottom, the danger zone. Deleting a project removes its artifacts, tasks and events from the database and requires typing the project key to confirm. It is refused while an agent is still working on a task of this project — Stop run first. The git repository on disk is left untouched, and your Storyteller chats stay in History — your code survives even this.

Agents & machines

The registry of workers — yours. A leader sees and runs their own executors: creates them, gives them skills, puts them on their own hosts, deletes them. Another leader’s executors do not appear at all. A GM sees everyone’s. A member only looks.

• Each card: a robot or a person, the kind, GM if it never receives tasks, on hostname — with (server) when that host is the server itself — in red when the host is offline, inactive, WIP limit N · queue M, one tile per competency showing the level and the XP behind it (click a tile to change it), and the buttons Edit, + Skill, Delete.
• + New Executor / Edit — the form: Name; Kind (human or agent); WIP limit, how many tasks it may hold at once (default 2); GM (never receives tasks) — with it on, the WIP limit disappears, there is nothing to limit; Active; for a human, Linked user, which ties the executor to an account — without it the reviewer role cannot be given; for an agent, Host (a drop-down of the registered machines, opening on — pick a host — until you choose one; a host that is offline, or the server when its session is not yours, is listed greyed with the reason; with none the form says No host registered yet — add one above). An agent cannot be saved without a host: it runs on a machine, and a server that only serves the site is not one. Then either CLI and Model for a cloud agent, or, for a local model, Context window (never below 32768) and Unload after idle in seconds (default 1800). CLI is the program on that host the agent drives: claude, or qwen where Qwen Code is signed in there.Model is a drop-down filled from the chosen host: for claude the CLI’s aliases (opus, sonnet, haiku) and the ids of the current family, for qwen the models that host’s own Qwen Code settings name (the runner reports the ids and nothing else from that file); other id… opens a field for one not listed. With claude the first row picks the model by task level (L1 haiku, L2–3 sonnet, L4–5 opus); with qwen it leaves the CLI its own default. A qwen agent implements and never reviews — switching an executor to qwen takes the reviewer role off it in every party it sits in. Moving an agent to another host is refused while it has a run in flight.
• + Skill — competency, level (a GM correction), XP, and Remove skill. This is what makes an executor eligible for tasks.
• Delete — type DELETE to confirm. Refused while the executor holds an assigned, in-progress or verifying task. Accepted work stays in the history.
• Your Storyteller panel — the host your Storyteller sits on and the model it speaks with. Host: automatic (the server if its session is yours, else the runner heard from last) or one of your machines; a machine that cannot take the seat right now is listed with the reason (offline, claude not signed in, spec-kit not installed, a probe plugged in), and a chosen machine that loses the seat is stood in for by the automatic choice until it can take it again — the panel says where the seat actually is. Model: the CLI’s own default or one from the same list as an executor’s. Judging runs of your projects follow the same seat.
• Hosts and Local models panels — sections 12 and 13.

Settings › Skills

The list of skill kinds: key, name, description, each marked global or private. Global ones are the site’s defaults, kept by the GM. Private ones belong to the leader who made them:+ New private (the key in lower-case with dashes, like avr-firmware) adds one that only you see and only your executors and projects use — another leader cannot see it and a newcomer’s registration form does not offer it. Keys are unique across the site: if a global one already has the key you want, use the global one. Edit and Delete appear on what is yours. When the arbiter invents a competency for one of your projects, it lands in your private list. Delete is refused while any executor holds the skill or any task carries the class, naming how many — deleting would strip the skill from everyone and leave those tasks classless. When the arbiter meets work that fits no existing competency it creates one here on the spot — as a real entry, not a proposal — and the Classify summary names it. Look at this page after a Classify run: a competency nobody holds is a task nobody will ever get.

Settings › People (owner only)

• Each row: username, e-mail if known, role, deactivated, (you). The role drop-down applies immediately. Reset password asks for a new one of ten characters or more and signs that person out everywhere. Deactivate / Activate — the second is how a new registration is approved. Deactivating also deactivates the person’s executor, so no task can reach them. The last active GM cannot be demoted or deactivated; their controls are greyed out.
• Disable registration — the sign-in page loses its Register tab. A completely empty site still lets the first person register, so a fresh server can get its GM.
• Mail — an SMTP server (host, port, user, password, from-address, encryption: STARTTLS on 587, SSL on 465, or none). Save and send a test asks for an address and reports sent to … or mail failed: …. Without mail the platform still works; it just cannot send account details.
• + Add user — an e-mail and a role. The login is the part before the @ (with a digit added if taken), the password is twelve random characters, and the account is active at once with a human executor attached. The result is shown once — Site / Login / Password / Role — with an amber note if it could not be e-mailed. Copy it before closing.

8 · What happens after an agent submits

This is the automatic GM — the part of the platform that judges work while you sleep. Knowing its steps is what lets you read an acceptance report or a task’s History without guessing.

The sequence

Which model reviews

The LLM review gate switch turns all of this on or off; there is no finer setting. Judging a change costs about as much as making a trivial one, which is why the cheapest cases are read cheaply or not at all.

Sent back, and how often

• Every sent back above is an automatic rejection: the reason is written into the task, the executor is charged, the task returns to Ready, and — with Auto-dispatch on — it is handed out again at once, with the rejection reasons in the new prompt.
• Each run leaves a handover for the next one. An agent finishes by writing at most a dozen lines about the repository — where things live, how the tests are really run, what is already installed, what tripped it up — and the next agent to work in that project reads them before it starts. It is a shortcut, not evidence: the note says so, and an agent that relies on it is told to check it. Every delivering run rewrites it.
• An agent is also told what it keeps getting wrong. Beside the reasons this particular task came back, its prompt carries at most three lines drawn from that executor’s own record across the board — scope it was charged for, rejections, red verifications, runs that changed nothing — each written as a check to run before submitting rather than as history. An executor with a clean record is told nothing.
• Three rejections, or three red test runs, and the automatic GM stops: the task goes to the Needs you list with auto_gm_gave_up and the reason. Three consecutive platform errors (a crashed run, a timeout) do the same, without charging anyone.
• The same objection twice in a row is not a strike: it means the task’s own rules cannot all be satisfied at once. The automatic GM stops immediately, refunds every charge on the task, and files rule_deadlock. A repeated merge conflict does not count — that is two tasks racing for a file, cured by redoing on current main.

Things that pause the whole pipeline

• A host’s usage window is spent. Recognised from the run’s output (usage limit, rate limit, 429, quota, overloaded). The task returns to the queue without penalty (rate_limited), runs on that host pause for ten minutes, the dashboard shows the blue banner naming it, and the pulse picks the work up again afterwards. Agents on other hosts are not affected.
• The budget is reached. Nothing new is dispatched; runs in flight finish. Section 10.
• The project is frozen. Nothing is dispatched at all; the task's Log says so.

The pulse

Every ten seconds the platform picks up assigned tasks. Once a minute it hands out every unblocked task in every active project with Auto-dispatch on, to every eligible executor with room — this is what revives a project after a restart, a rate limit or a re-classification without anyone pressing anything. Every five minutes it checks whether a project has earned convergence or a Golden User run. Eligible means: the competency at that level or higher, an implementer in this party, active, below their WIP limit, on a host that is online and whose usage window is not spent, and no file overlap with a task already in flight.

9 · The rules the platform will not bend

When the platform refuses something, it is almost always one of these. They exist because each one was bought with a real failure. Where a rule has an edge, the edge is written here too.

A specification is checked before anyone works to it

Spec, plan and task list are read against each other before the first task is dispatched: requirements nobody turned into work, tasks tracing to no requirement, requirements that contradict each other, promises with no measurable meaning. A critical finding — made by one model and confirmed by a stronger one — holds dispatch until a person either fixes the documents or waives it in writing, with a reason that is kept. Nothing dispatches while that check is still running, either. If the check itself crashes, dispatch is not held: a broken audit is the platform’s fault, not your specification’s. The report lands in Artifacts as Specification analysis.

The specification does not drift

Documents the pipeline produced cannot be edited afterwards. Every check judges against them; a hand-edit would make the judge and the builders disagree. Changing your mind is a new task, a returned task, or a new project — never a quiet edit.

A full board is not a finished product

When every task is accepted, the code is assessed against the specification, and anything that was asked for but never built comes back as new tasks. That repeats until it reports that nothing is left — and that verdict, for the current main, is what finished means. Three rounds that still do not converge stop and call you: at that point the specification is asking for something the work cannot reach, and another round would only say so again.

Tests decide; where there are none, a person does

Every submission runs the project’s test command. If there is no test runner in the project yet, or the suite is empty, the run is recorded as not run rather than quietly counted as a pass — so you can always tell the difference between “checked” and “nobody checked”. And a not run is never accepted by the platform on its own: the reviewer still reads the diff and says what it thinks, but the task then waits in the Needs you list for a person, with that review in front of them. On a new project that is the first few tasks — the foundation — which is exactly where an opinion about a diff is the weakest evidence there is. The way out is the obvious one: make the test runner one of the first tasks.

A product that does not start is not finished

With the smoke gate on and a run command set, the product is started with the exact command its own documentation gives a human, and knocked on. A suite can be green while the application cannot boot; this is the check that notices. Without a run command the switch is idle.

Work stays inside the task it was given

The files a change touches are compared against what the task described. Wandering outside is not an automatic verdict — a task may authorise it in its own words — so it is put to the reviewer as a question, and only charged when confirmed. With the review gate off there is no reviewer to ask, and the parser’s verdict stands.

A second opinion before acceptance

With the review gate on, a second model reads every change that is more than a short piece of documentation. A rejection, or a finding the reviewer marks blocking, sends the work back with the findings; only after three such returns, or a deadlock, is a human called. The table in section 8 says which model reads which change.

A fix is not accepted without proof

A task that fixes a bug must come with a test that fails without the fix and passes with it. A test that passes either way proves nothing and the fix is sent back. Two edges: the proof needs a verify command — a project with none cannot run it, so the fix goes to a person instead of being blamed on the executor; and the proof is part of the automatic path only — a person pressing Accept is trusted to have looked.

Only green work reaches main

Merging happens after the checks, not before. If another task changed the same files first, the platform tries once to keep both sides and runs the tests on the result; if that is green the merge stands and the report says union. If it is red, or there are no tests to ask, the merge is rolled back and the task is sent back to be redone on current main. The platform never guesses that a merge is correct without a test saying so.

Three strikes, and a deadlock is not a strike

The automatic GM may reject and requeue a task three times, then it stops and asks a human. But if it raises the same objection twice in a row, that is not a careless executor — it is a task whose own rules contradict each other. It stops immediately, refunds what was charged, and says so.

Nobody judges their own work

A GM executor never receives tasks. A reviewer may not accept their own. A project owner may not accept a task they hold. The person who did the work is never the person who signs it off.

An empty change is audited, not trusted

If an agent claims a task was already done and produces no change, the platform audits the current code against the task’s criteria instead of taking its word.

Nobody spends anyone else’s subscription

Every run happens on a host, and a host belongs to one account. A project’s runs go to its owner’s hosts. If none is online the work waits; it never switches to another person’s machine.

10 · Money and trust

What a run costs

Every run of a cloud model reports what it cost, in dollars at the model’s list price. The platform keeps that number on the task (model spend on this task, and the dollar figure on its card), adds it up per project ($41.20 spent above the board and on the Settings label), and writes the tokens and dollars into every submission and review event in the Log.

• The project total counts the runs of executors and their reviews. The arbiter, the specification analysis, convergence, the Golden User and the Storyteller chat are not in it.
• A local model’s run costs zero, and is recorded as zero.
• A qwen run’s price is left blank, not guessed: a free quota and a paid key are the same call from here. Its tokens are recorded; the dollars are the account holder’s to know.
• If the host’s Claude is on a subscription, no invoice for these dollars ever arrives — the subscription pays in usage windows, not money. The figure is still the honest price of the work, and above all of the waste: a task that was rejected twice shows three runs’ worth.

The budget

Settings → Budget, USD. Zero means no cap. When the project’s spend reaches the cap, the dispatcher stops handing out work: the Tasks tab shows Budget spent — $X of $Y, the Log gets one budget_block event, and runs already going are allowed to finish. Raise the number (or set it to zero) and the next pulse continues. Set one on every project: an agent that keeps being sent back is otherwise limited only by the three-strike rule, per task.

Two numbers no vendor shows you

Above the board, next to the counts, sit two fractions. They are there so you can decide how much of this to trust.

11 · Levels, XP and penalties

Every executor holds a level from L1 to L5 in each competency, and is only offered tasks at or below that level. Accepted work earns XP; enough XP raises the level. This is not decoration — it is how the dispatcher decides who is allowed to touch the hard parts.

12 · Hosts and CodeRealmRunner

Every run — an agent implementing a task, the Storyteller drafting a specification, a reviewer reading a diff — happens on a host: a machine with the claude command-line tool signed in. Your own computer becomes one when you install CodeRealmRunner on it, and from then on everything you start on the site is done there, by your own Claude session. Nobody spends anyone else’s account: the runner connects outward to the site, keeps no password, opens no port, and the session never leaves your machine.

What you need on your computer

• A Mac with Apple silicon (M1 or later), a Linux machine (x86_64) or Windows (x86_64). The Linux and Windows builds come from the pipeline; the macOS build is still made on a Mac. No Intel Mac build exists.
• git. Open Terminal and type git --version; if macOS offers to install the command-line developer tools, accept.
• The claude command-line tool, signed in. Install it from Anthropic’s documentation (Claude Code), then run claude once and sign in with your Claude account. Check with claude auth status — it must say "loggedIn": true. A Claude subscription (Pro or Max) is what pays for the agents. The runner looks for the tool in the usual places (~/.local/bin, Homebrew, ~/.claude/local).
• spec-kit, the specification toolkit the Storyteller drives. Install uv first if you do not have it, then spec-kit:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  uv tool install specify-cli
  specify version

  The last line prints a box with a CLI version; that is the check. Without spec-kit a host can still run agents on tasks, but the Storyteller will not start a chat there and the audits (specification analysis, convergence) will not run there — the platform never substitutes its own copy for the one on the host.
• Qwen Code — optional, a second CLI a host can offer. Install it with npm install -g @qwen-code/qwen-code, run qwen once and finish its sign-in; the host then reports qwen signed in and its executors can be set to that CLI. An agent on qwen develops only — every verdict in the pipeline stays on claude, because the gates are calibrated on its readers. The platform runs it in safe mode with a reduced tool set: your own QWEN.md, hooks, extensions, skills and MCP servers take no part in a pipeline run, and the agent gets the six tools it works with. That is deliberate — the task text is the whole contract — and it is also what a run costs: measured on qwen 0.23.2, the CLI as it comes carries about 34,000 tokens of system prompt and tool schemas into every turn, and about 10,000 this way.
• LM Studio — optional, only for local models (section 13).

Connecting, step by step

cd ~/Downloads
chmod +x CodeRealmRunner-macos-arm64
./CodeRealmRunner-macos-arm64 connect https://your-site.example --token XXXXXXXX

xattr -d com.apple.quarantine CodeRealmRunner-macos-arm64

claude CLI: /Users/you/.local/bin/claude (signed in)
git: ok
spec-kit CLI: /Users/you/.local/bin/specify
qwen CLI: not installed (optional)
LM Studio: not installed (optional)
registered as host 'Your-Mac' (#3) at https://your-site.example
LaunchAgent dev.coderealm-runner installed; it starts at login and restarts if it stops

Living with it

• Online means heard from in the last ninety seconds. The runner reports in every twenty seconds or so. Close the laptop lid and it goes offline; open it and the dot is green again within a minute or two. After a reboot the autostart brings it back at login. When the server restarts, every host shows offline for a few seconds until it reports again.
• A run on a host that vanishes is lost. If the runner stops reporting for ninety seconds in the middle of a task, the run ends with host went offline, and the task is returned to the queue without penalty.
• Your executors live on your host. Every agent you own is created on one of your hosts. An agent on an offline host takes nothing: the task waits in Ready, the Home page shows an amber its agents’ host is offline banner naming the machine, the executor’s card on the Agents & machines page shows its host in red, and the task’s Log has a dispatch_gap event.
• Your browser is not a host. Sign in from a phone or another computer and you see and manage everything exactly as before; the work still runs on whichever of your hosts is online.
• A chat belongs to its host. A Storyteller chat runs on the host it was created on, for good. Wake that machine to continue it.
• spec-kit lives on the host, not on the server. Every specification workspace — a chat, an analysis, a convergence run — is laid down with the spec-kit that is installed on the machine doing the work. What you install is what runs; update it there when you want a newer one.
• Judging runs go to the project owner’s host — the one chosen in Agents & machines → Your assistant, or with nothing chosen the server if the owner is a GM and the server has claude, otherwise the owner’s most recently heard-from runner.
• One runner, one site. The runner keeps one configuration. To move it to another site, disconnect and connect again.
• GM sees every host; everyone else sees only their own. The server’s row is shown to the person whose session it is and to GMs, nobody else. Renaming is possible through the API but has no button.

Updating the runner

The runner only knows the host functions it was built with. When the site moves on, the runner notices on its next poll, downloads the site’s current build into its own directory and restarts on it — nothing to do on your side; the Hosts panel shows runner vX is older than the site’s vY only for the minute this takes. CodeRealmRunner update does the same by hand. The token and the registration stay; only the program changes.

The file you downloaded is only the installer: connect copies it into ~/Library/Application Support/CodeRealmRunner/bin/ (Linux: ~/.config/CodeRealmRunner/bin/, Windows: %APPDATA%\CodeRealmRunner\bin\) and the autostart runs that copy — with --no-autostart too, since only that copy is replaced when the site moves on. You may delete the download afterwards. A runner connected by an older build that still runs from Downloads is moved there by CodeRealmRunner install.

On the machine itself

Its files live in ~/Library/Application Support/CodeRealmRunner/: bin/ (the program it actually runs), config.json (the token — keep it private), runner.log, and work/, where the copies of repositories it works on are kept. The autostart entry is ~/Library/LaunchAgents/dev.coderealm-runner.plist. To uninstall completely: disconnect, then delete that folder and the downloaded binary.

Remove on the site’s Hosts panel is the other direction: it forgets the host and its token, and is refused while executors still live on it — move or delete them first.

Boards, probes and targets

Plug a debug probe into a machine that runs CodeRealmRunner — an ST-LINK on a NUCLEO, a J-Link, a CMSIS-DAP — and the host card on Executors lists it within a minute, together with the microcontroller it reads behind it: the core (from CPUID) and, for an STM32, the part (from DBGMCU_IDCODE), e.g. ST-LINK (STLink V3) 003B…3431 → STM32U535/545 · Cortex-M33 r0p4 · DEV_ID 0x455 · NUCLEO-U545RE · /dev/cu.usbmodem1403. The probe's serial port and USB drive are found under the probe itself, so two boards on one Mac are never mixed up. Replugged something? read the MCUs again on the card.

A firmware project says which microcontrollers it runs on in Settings → Targets: one row per role — main, slave, sensor-1 — with its part (STM32U545RE), and the probe that reaches it, picked from the list of every probe on your runners. Bound to a probe, a target is that probe wherever it is plugged in; left unbound, any probe wired to that MCU (or that board) will do, on whichever runner has it — unplug it from one Mac, plug it into another, and the other runner takes the runs. The console is the probe's virtual COM port, RTT, or a serial port you name.

From there the roles go through the project. The Storyteller asks which microcontroller is which and creates the targets; the documents of every target's MCU are fetched; every task names the target it is about (the Target field on the task); agents are told where each target is and reach it only through bench; and before a task is accepted the Bench Judge runs the on-target images on the boards — tests/target/<role>/<suite> on that role's probe, and a suite with the same name under two roles as one joint run, the slave flashed first, the main last, every console required to say END. A host whose probes are all a project's targets runs that project's agents beside them; any other probe plugged in still holds agent runs there.

Components: a driver written once per board

When a task's work has passed on the board — a display driver, a flash driver — open the accepted task and press Save as a component: pick its files (lib/… is preselected), give it a key and a name. The component remembers the board and MCU it was proved on and the board's verdict. Every later project with a target on that MCU or board lists it under Settings → Components; Add to project commits it to lib/ with a COMPONENT.md saying where it was proved, and the agents are told it is there and proved, so they use it instead of writing their own. A component published again shows as Update in the projects that have the older version.

13 · Local models as developers

A machine that can run a language model of its own can put it to work at no cloud cost. LM Studio is a free desktop application (lmstudio.ai) that downloads and runs open models on your computer. Install it, and inside it download a model — look for one marked as supporting tool use, and one that fits your memory with room to spare. The platform never downloads a model itself.

The Local models on host panel on the Agents & machines page lists what LM Studio holds on the selected host; it appears once there is a model or more than one host. For the server it is read directly (the list is cached for twenty seconds — reload the page a moment after installing a model); for a runner host the models arrive with its regular report. Each row: provider, name, parameters, size, and either Add as developer, added, or no tool use — will not work as an agent with a greyed button.

• Add as developer turns a model into an agent of yours on that host with a WIP limit of one. Give it skills like any other executor.
• Developers only. A local model implements tasks; it never judges. Review, arbitration, convergence and the Golden User stay on cloud models, and the platform refuses to give a local agent the reviewer role. Its work is reviewed by Sonnet like anyone else’s — in our first live run the reviewer caught a real defect in a local model’s diff before the merge.
• What it costs: nothing. A local run consumes no cloud tokens and none of the subscription window — the trail records its cost as zero. The cloud is spent only on judging the result. In practice a local developer is the right worker for L1–L2 tasks: scaffolding, small fixes, documentation.
• Load parameters are the executor’s. Edit a local agent and you set its context window (never below 32768 — an agent prompt is large, and below that the runtime cuts the task off before the model sees it) and how long the model stays loaded when idle before its memory is returned to the machine (default thirty minutes). The platform starts LM Studio’s server itself and loads the model with these settings at dispatch time; the load is recorded on the task.
• Memory is the limit. A model too large to load next to whatever else the machine is running is refused by LM Studio, and the executor sits idle with the reason in the task’s Log. A 27-billion-parameter model does not fit beside a running platform in 24 GB; a 4-to-9-billion one does.
• Deleting the agent frees the model. The weights stay installed; Add as developer comes straight back.

14 · CodeRealmApp — the platform as a Mac application

CodeRealmApp is the same platform packed into one application for one person on one Mac. Start it and a window opens on the Home page; nothing else to install, no server to run.

• No accounts. Whoever opened the app is the GM. There is no sign-in, no Sign out, no People section, no registration. Executors are always agents.
• The host is this Mac. The app uses the claude command signed in on this computer and the specify command installed on it. Install both exactly as in section 12; without claude nothing runs, and without spec-kit the first chat stops with spec-kit is not installed on this host. Runner hosts cannot be added to the app — it has no runner builds to hand out — so the app is a single-machine affair.
• Only from this screen. The app listens on this computer alone; a phone or another computer cannot open it.
• Your data — the database and the repositories — lives in ~/Library/Application Support/CodeRealm/. Back that folder up and you have everything.
• Updating is replacing the application with a newer copy; it does not update itself. Like the runner, it is not notarised: the first start may need Open Anyway in System Settings → Privacy & Security.

Everything else in this guide — the interview, the board, the gates, the reports — is identical.

15 · For the administrator

Hosting the shared version for others — the compose file, the four containers, the two volumes, deploying from GitLab, backups and restore, the variables the API reads — is its own document, written for the person who runs the machine: the administrator's guide. Nothing in it is needed to use the platform.

16 · Who may do what

An invisible project answers as if it did not exist. A button you may not press is still drawn; pressing it answers with a red 403 line, and nothing changes.

17 · When nothing moves

Nine times out of ten it is one of these. The dashboard usually names the cause itself in an amber banner; the task’s Log names the rest.

18 · Questions people actually ask

Do I really not need to know how to program?

To get a product built: no. To judge whether a finished product is what you asked for: no, and that is deliberate — the Golden User and the acceptance reports exist so the last word can be given by someone who only sees the outside. What you do need is the willingness to answer questions precisely, and to type three lines into a terminal once, to connect your computer.

What does it cost me?

The agents run on a Claude subscription on your host. The platform shows you the list price of every run anyway, so you can see where the effort went and set a budget per project. Local models cost nothing to run.

Where is my code, and can I take it away?

In an ordinary git repository the platform keeps for the project, browsable in Code › Repository. It is standard git; any developer or tool can pick it up. Deleting a project does not delete it.

How long does a project take?

The interview is an hour of your attention at most. After that it depends on how many tasks the specification produced and how many can run at once — tasks that touch the same files run one after another. Small projects finish in hours, larger ones over days, and the board tells you the truth at any moment.

What if I disagree with what Storyteller wrote?

Say so in the chat before the handover — that is the last moment the specification can change. After it, the documents are read-only — until you bring a changed specification through Re-spec in Specification › Import, which revises them in place and reopens only the tasks whose text changed. If a task is already built on the wrong understanding, use Return — task at fault so nobody is charged for following bad instructions, and write the task you meant with New Task. For a change bigger than a few tasks, start a new project with a better description.

Can I add something after the project has started?

Yes. New Task on the Tasks tab, with the dependencies you need and a class, then Dispatch. Anything larger than a handful of tasks deserves a new project so that the specification and the product do not drift apart.

An agent broke something that used to work. Now what?

Nothing is ever lost: every change is a commit and every accepted task is a merge. File it on Bugs with how to reproduce it, then Create fix task. The fix will only be accepted with a test that catches that exact defect.

Can several people work on one project?

Yes. A GM or the project owner invites executors into the party and gives them the implementer or reviewer role. Human executors get tasks on the same board as agents, and pick them up with Start and Submit; a human’s submission waits for a person to press Verify passed and Accept.

Who can see my project?

GMs see everything. A leader sees the projects they own. Everyone else sees only projects whose party they are in — an invisible project answers as if it did not exist.

Does the server see my Claude account?

No. The runner connects outward and runs claude locally; your sign-in never leaves your machine. The server sees the results and the cost figures, nothing else.

19 · Quick reference

Task statuses

Bug states

Artifact statuses and link types

Events worth recognising in a Log

Priorities and levels

Time limits

If something in this guide does not match what the platform does, the platform is right and the guide is stale — say so, and it gets fixed. A guide that disagrees with reality is worse than no guide.