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 header, on every page

• CODEREALM — back to the project list.
• Projects · Executors · Competencies — the three main areas. GMs also get Users. Everyone can open Executors and Competencies; only a GM can change anything there.
• Guide — this document. It is the only link you see before signing in.
• A small counter appears for GMs and leaders when tasks are waiting for a human verdict. It refreshes every thirty seconds; click it to go straight to them. A task counts when its oracle wants a person, when a human submitted it and a reviewer must look, or when the automatic GM gave up on it.
• A notices badge, for GMs and leaders, whenever something went wrong lately — a host that stopped answering, a runner that refused an update, a background run that failed, runs paused after a fault. It includes what the platform fixed by itself: a dispatcher pass that failed and was skipped, a host that came back after being silent. Click it for the list, and Mark all seen when you have read it. A fault that keeps happening shows a count instead of repeating.
• Your username, Sign out, a theme switch and the platform version.
• The theme switch — the sun or moon between Sign out and the version. CodeRealm opens dark; press it once for the light theme, which is the readable one outdoors or with a window behind you. The choice is remembered in that browser and applies to every page.

The Projects page — your control room

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

• Banners. They appear only when something needs you. Four exist:
  • Agent runs paused on ‘host’ — the subscription’s usage window there is spent, in blue, with “resuming by itself in about N min”. Nothing is lost and nothing is asked of you; other hosts keep working.
  • KEY: its agents’ host is offline, in amber, naming the agents and the machine: everyone who could take the work sits on a host that is not reporting in. Wake the machine or start CodeRealmRunner there.
  • KEY: no implementer can take this work: competency Ln (N tasks) — the best implementer is Lm, or — no implementer has it at all, in amber. Somebody must be given that skill; section 17.
  • KEY: pipeline stalled — silent for 3h 56m, in amber. The project has tasks ready, nobody working, and nothing has happened for fifteen minutes. Section 17 lists the causes.
  Amber means act; blue means wait.
• Verification Queue. Every task, across all projects, that is waiting on a decision. This is your to-do list. Columns: the task, its level, its oracle (judgement or automated), who holds it, the latest check (passed, failed, running, no run) and how long it has waited. Click a row to open it.
• Projects. One card per project with its key, name, status badge and how many tasks are ready to start. New via Storyteller starts the interview; + Manual creates an empty project for people who already have a specification to import. Both are shown to leaders and GMs only.
• Executor Pool. Every executor, their skills, their load against their limit (load 1/2), idle or inactive, and exactly what each one is working on right now.

+ Manual, 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 its Import tab.

Inside a project

A sidebar (a row of chips on a phone) with ten tabs, under a breadcrumb Projects / name / tab and the project’s status badge. On a desktop the Artifacts entry also has three sub-filters with counts — Requirements, User Stories, Test Cases; on a phone you reach the same documents through the Artifacts tree. Section 7 covers each tab:

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.

10

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 on the Bugs tab 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

Artifacts

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?”.

V-Model

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

The line above the board reads, for example, 64 tasks · 58 accepted · verification queue 2 · judge overruled 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 Executors 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 8, 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.

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:

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.

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 + Manual has no repository until its first agent task runs; the tab says so.

RealRun

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.

Party

The Balance table (see step 5) 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 (Executors → 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.

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.

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

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.

Executors

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.

Competencies

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.

Users (GM 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 Verification Queue 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 verification queue 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 Projects page shows an amber its agents’ host is offline banner naming the machine, the executor’s card on the Executors 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 Executors → Your Storyteller, 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.

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 Executors 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 Projects 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 Users page, 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 on the Repository tab. 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 on the Import tab, 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.