Ephesus
The architecture

The City

Ephesus was a working city: a harbour that moved goods in and out, an agora where business was coordinated, the Library of Celsus that held its knowledge, an odeon where the council met and heard reports, and the Temple of Artemis watching over all of it. Every subsystem here is named for the part of the city that does the same job.

How work moves

You talk to one agent. The company does the rest.

You describe intent to Artemis — by text, or by voice once the Herald is wired. She decomposes it and assigns self-contained task specs. Agents collaborate through Hermes over the Agora, which is plain files in a local git repository. When an agent finishes a turn, a stop-hook drains its inbox, so mail never waits for a human to notice it.

The company reports back on its own initiative: decision memos queue for your sign-off, milestone reviews archive as slide decks, and Artemis briefs you on schedule or on demand. Everything is watchable on the floor while it happens.

Four agents at their desks on the Terraces floor, with a live agent terminal alongside
Four hired agents at their desks, one live in a real terminal. A development build: the floor is drawing procedural tiles because the licensed sprite sheets are deliberately kept out of the repository.
The subsystems

Eleven parts of one city

Artemis

Patron deity

The orchestrator, and the one agent you talk to. She decomposes intent into self-contained task specs, checks the roster, assigns work, adjudicates between agents, and escalates only what genuinely needs you. What she may decide without asking is not a matter of taste — it is declared in a file, and anything outside it queues for your signature.

Hermes

The messenger

The routing layer. Agents write only into their own outbox; the harness delivers into recipients’ inboxes. Messages are speech acts rather than free text, which is what makes anti-livelock rules possible: a request, an answer and a refusal are different things the router can reason about.

The Agora

The marketplace

Shared coordination on disk — roster, blackboard, task ledger, append-only event log. It is a git repository with exactly one committer: the main process. Agents write plain files and never run git, which is why there are no index.lock wars.

The Library

Library of Celsus

Memory. Per-agent markdown plus semantic recall over the company archive, with reflection and condensation so it never grows without bound. An agent that has been running for weeks does not carry weeks of transcript.

The Odeon

Council theatre

Accountability made mechanical. Decision memos queue for your verdict, milestone reviews archive as slide decks, briefings are compiled from facts before they are narrated, and meetings enforce turn order and file their own minutes. A task that owes a deck cannot be closed until the deck exists.

The Terraces

Terrace houses

The two-dimensional floor. Every agent is an avatar at a desk. Walking means a tool class is in use and the destination names which. An envelope in flight is a message, coloured by speech act. Waving at the Watch post means a gate is open. Watchability as observability.

The Watch

City walls

Safety. Human approval gates, spend budgets read from a durable ledger rather than an in-memory counter, a three-rung circuit breaker that steers before it constrains and constrains before it stops, and a secret broker that injects credentials as environment variables and never returns them over IPC.

The Gymnasium

Training grounds

The self-improvement loop, and the company’s primary standing mission. Proposals rise from the company’s own operating records, must carry a falsifiable success metric before a human ever sees them, pass the same gate machinery as any other change, and are measured after they land. Rejections and rollbacks stay in the ledger too.

The Stoa

Colonnade of scholars

Research. Studies external repositories you register by URL, at a pinned commit, read-only and secret-free by construction. Every finding must cite a path at that commit or the whole brief is refused before it reaches you.

The Harbor

The port

Everything in and out — GitHub ingestion, incidents, chat bridges, the company’s own git identity. An instance watching no repository still hires its crew, but it says so as a visible degradation rather than sitting silent.

The Herald

Town crier

The voice interface: a spoken, understated chief-of-staff presence with wake word, barge-in and approvals by voice. Built and tested, deliberately unwired — and the repository records that as a decision rather than leaving it as a mystery.

Accountability

The company argues in front of you

Agents do not merely do work — they account for it. A non-trivial decision becomes a memo with what, why, blast radius and rollback, and it waits for a verdict. Artemis countersigns within her delegated classes; everything else queues for you, and a rejection reverses the action rather than merely noting disapproval.

A meeting in progress in the Odeon panel, with turn order enforced
A meeting in the Odeon. Turn order is enforced — an answer given early is held, not lost — and the minutes file themselves.
An open approval gate awaiting the architect's decision
An open gate. Every item shows what, why, blast radius and rollback before the approve and deny controls appear.
The rules

Invariants, not preferences

Violating one of these is a defect even when everything appears to work. They are checked against every diff before it is committed, and several are enforced mechanically in CI.

Strict TypeScriptNo any outside a boundary type wrapped by a validator.
The renderer is untrustedNo Node APIs in renderer code, ever. Context isolation on, sandbox on, every mutation through a typed IPC handler that validates in main.
Atomic writesAnything another process reads is written temp-file-then-rename. A bare write onto a live path is a bug.
Single committerOnly the main process runs git in the Agora.
Append-only means append-onlyThe event log, the cost ledger and the Odeon archives are never rewritten or compacted in place.
Secrets are write-onlyNo IPC returns a secret value. Secrets reach agents only as declared environment variables.
Every degradation is visibleMissing keys, missing index, schema drift, heuristic-grade engines — a visible UI state, never a silent fallback.
Prompt text is configNo LLM-facing prose as string literals in code. It lives in prompts/ and is loaded.
Cost comes from the ledgerNever from an in-memory counter, so the restart-reset bug class is impossible by construction.
Watched content is dataAnything read from a registered source is untrusted input. Embedded directives are reported as findings, never followed.