How the system works

alphatwo-ten is a software factory. Two agents inside the factory (an Executor and a Reviewer) build tools. Those tools get consumed by a workforce of named role-agents that operates a real business on behalf of a customer. Each customer gets a dashboard, a database, and a "brain" — a private folder of living documents that every agent reads from and writes to.

This page is the comprehensive design reference. The homepage shows the interactive build pipeline, and the stack map covers what runs where.

1 · North star

2 · The two layers

The whole system splits cleanly in two. The factory is shared infrastructure (one of these exists for all customers). The workforce is per-customer (one of these exists per customer we sign up).

3 · v0.1 — what we build first

The big realization of this grill: Maestro is the first agent we build, not one of the 12 listed specialists. Every future agent depends on Maestro's output to be useful. Building a specialist first would just be a chatbot in costume.

4 · Maestro's job

Maestro interviews the customer and writes their findings into a structured "brain." The customer can show up with as little as an idea, a description, or a URL — Maestro takes it from there.

The first decision Maestro makes

Before anything else, Maestro figures out whether this is an idea or an established business. The two flows produce different brain content (aspirational vs. inventory-heavy), so the differentiation has to happen early.

What Maestro can see (established businesses)

5 · The customer's brain — 8 living documents

Maestro's output is a folder of HTML documents (not bare markdown), styled like this page. They live in the customer's private GitHub repo and update as Maestro and future specialists learn more.

Every future agent we hire (Max, Tom, John…) reads from this brain before doing any work. That's why Maestro had to be first — without these documents, no specialist has context.

• business.htmlWhat the business / idea is. Problem, value prop, what it does and doesn't do.
• customer.htmlWho the founder is. Role, background, working style, what they want from the system.
• product.htmlWhat they sell (or want to sell). Offerings, pricing, format.
• audience.htmlWho they sell to. Personas, jobs-to-be-done, channels they live on.
• voice.htmlBrand voice, tone, vocabulary. Words they use, words they avoid.
• assets.htmlWhat they already have. Existing site, accounts, files, audiences, traffic.
• goals.htmlWhat they're trying to achieve. North-star metric, near-term targets, time horizons.
• status.htmlStage marker — idea vs. established, runway, momentum, current bottleneck.

Format note  Documents are rendered as HTML in the style of this page (Thariq's "concept explainer" pattern — serif headings, monospace eyebrows, ivory background, clay accents). HTML is what the customer sees; the source-of-truth file committed to git is the same HTML.

6 · How the customer experiences it

The dashboard is a live split-screen: Maestro's chat on the left, the brain documents on the right. As the conversation produces facts, the right side updates in real-time — the customer watches their own "brain" form.

Conversation style  Guided + open-ended follow-ups. Maestro works through the 8 documents as an agenda (predictable enough to ship), but each section is conversation, not a form. He validates, summarizes, asks follow-ups, and lets the customer steer.

The dashboard is generative

One dashboard application serves every customer (multi-tenant), but the layout itself isn't fixed. After the interview, Maestro emits a JSON spec describing which widgets, metrics, and panels this customer needs. json-render.dev renders that JSON into React UI from a constrained component catalog.

Result: a content business and a product business get different dashboards out of the same app. Maestro keeps updating the spec as the brain evolves and as specialists get hired — adding Max means SEO widgets appear, adding Tom means a media library appears.

7 · Where the data lives

Two stores, each with a clear job. Nothing lives in both.

Why a git repo for the brain (not the database)

Three reasons: it's portable (the customer can clone or export their brain at any time — they own it), it's versioned for free (every change is a commit, with attribution to whichever agent made it), and it forces clear ownership boundaries (one folder per agent, no fighting over rows).

8 · What a tool actually is

A "tool" is the unit of work the factory produces and a specialist consumes. It's not just an API or a widget — it's a self-contained pair.

One tool = one GitHub repo (tenwhy-tools/<name>). Built by the factory (Executor + Reviewer in a Sapiom µVM), versioned independently, consumed by exactly one specialist role.

How an agent uses a tool

When a specialist is hired, the platform loads the tool's Skill into that agent's context. The agent reads the skill, decides when to invoke the CLI (based on its shift schedule, a Maestro task, or an event), and runs it. Output gets committed to the agent's folder in the customer's brain repo.

The factory–workforce wall

9 · The hiring roadmap

Once Maestro is live, the factory's job is to build the next specialist's tool and ship it into the catalog. When the customer (or Maestro) decides they need that role, Maestro "hires" them — the specialist's folder appears in the brain repo and they start doing their job.

The 12 candidates from the original brief, ordered roughly by likely-first-to-hire. Names marked ? are still unnamed.

All 12 are unhired in v0.1 — only Maestro ships. The factory will build each tool when Maestro suggests the hire and the customer approves (decision #21). Top 4 rows represent the earliest-likely hires.

Also future: Consigliere (strategic advisor sitting alongside Maestro, advises only — decision #19).

Renames from the original brief

10 · Decisions locked in this grill

Each one is now a constraint on everything downstream.

11 · Still on the grill

What naturally comes next

Not "open questions" — just the obvious work that follows from what we decided: