How the system works

Tenwhy is how a company should become. Each customer gets a workforce of named role-agents that runs a real business on their behalf — backed by a dashboard, a database, and a "brain" (a private folder of living documents every agent reads and writes). The agents themselves are produced upstream by a separate software factory: an Executor and a Reviewer that build the tools the workforce consumes.

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.

how this relates to the build plan  The engineering MVP on the build page runs Maestro plus one hand-written specialist (Jon) against a hand-seeded brain — that's the smallest loop that proves the job contract, the audit trail, and the orchestration wiring. v0.1 here is the product milestone: Maestro alone, interviewing real customers and writing real brains. The MVP loop is scaffolding on the way to it; Jon's early presence is a test fixture, not a hiring decision.

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 · Action history & audit

Every external action — Sac lowering a Meta bid, Jon publishing a product, Vic uploading generated media — leaves a durable, customer-readable trail. Three stores hold it, each with its own job:

The customer-facing layer

Every department gets its own log, and Maestro aggregates them into a chronological cross-company timeline.

One entry, in detail

Each action becomes a self-contained article appended to the agent's history file:

Write flow — the platform finalizes

The µVM does not write the audit itself. It returns its result envelope, its artifacts, and proposed brain updates; the platform finalizes. It validates the envelope against the job contract, dedupes the delivery (a re-sent or replayed webhook can't double-write), verifies the plan checksum, writes the action_log row, renders the canonical history.html and timeline.html entries from a trusted template over the validated data, and commits them to the customer's brain repo with a scoped token. The tool authors report content and proposes updates; only authority over the canonical record lives with the platform. So the signed commit attests "a validated action occurred" — not merely "a µVM holding our token wrote this text." (Mechanics: §11.)

Why brain HTML beats Postgres-alone for audit

Roll-over

Once an agent's history.html grows past ~500 entries it rolls into monthly archives — /sac/history/2026-05.html — and the active history.html shows the latest month with links back to the archives. The customer experience stays the same; the underlying files just don't grow unbounded.

9 · The job contract

Maestro fires specialists by sending a structured request into the µVM, and the specialist returns a structured response via webhook. The wire protocol (Sapiom + HMAC-signed POST) is already locked (decision #9). The shape of the JSON inside it — the cargo — is what this section pins down.

Without a fixed schema, every new specialist would force a Maestro code change to parse its outputs. With one, the workforce stays pluggable: any factory-built tool that conforms to the contract slots into Maestro without modification.

Request — Maestro → µVM

Passed into the µVM at boot, via Sapiom job env plus a small JSON init file:

Response — µVM → Maestro webhook

POSTed when the job finishes (success, partial, or failure):

Why each non-obvious field earns its place

Enforcement

The Reviewer in the factory checks every tool's emitted output against this schema as part of the build, same gate as lint/test failures — a tool that doesn't conform doesn't ship. The schema itself lives in the platform (not duplicated in each tool repo) so it can evolve: tools declare which schema version they target via contract_version in their spec.yaml, and Maestro routes accordingly.

10 · 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.

Bash as a secondary capability

Inside the µVM the specialist also has access to bash for ancillary work: reading downloaded files, running a jq filter on a payload, exploring transient state. Bash is never the path to external APIs. Read-only, bounded-cost calls (LLM, scraping) run through the tool's structured CLI inside the µVM; money-moving or state-mutating actions (Meta, Stripe, Render deploys, etc.) are only proposed by the CLI — the platform's broker executes the approved plan (§11), so the gate, the validator, and the audit layer always apply. Think of it the way Claude Code itself ships both Edit/Read/Grep and a Bash tool: structured tools for the hot path, bash for the long tail.

The factory–workforce wall

11 · Durable orchestration & the control plane

The job contract (§9) says what Maestro and a µVM exchange. It does not say how a job survives a crash, a lost webhook, or a retry without double-acting. "Fire a µVM, await its HMAC webhook" is enough for read-only work and the MVP — and it fails the first time an apply moves money and the completion webhook is lost to a deploy or a restart, leaving an effect that happened but a record that didn't. The three hardest guarantees — crash/re-run with zero loss and no double-effect, no tool moves money outside policy, results comparable across the fleet — all rest on a layer that has to be specified, not assumed.

The control plane owns durability; the µVM stays disposable

Between Maestro's decision and the µVM sits a durable control plane. The µVM is modelled as an external async activity — never a durable worker. Durability lives in the platform that dispatches, waits, dedupes, validates, and finalizes.

backend  For v0.1 this is a Postgres-backed state machine with a transactional outbox/inbox — no new vendor. A durable engine (Inngest, Restate) is a later swap behind the same interface, justified when approvals sit for days or specialist chains grow. The caveat that keeps us honest: an engine buys timers, retries, and waits — it does not buy exactly-once external effects, trustworthy audit, or spend caps. Those come from idempotency keys, credential scoping, and platform-side ledgers regardless of engine.

The gate: deterministic, platform-side, recomputes its own numbers

Money-moving and state-mutating work follows plan → gate → apply. A µVM plan emits a changeset; the gate sits between plan and apply and is deterministic and platform-side. Crucially it recomputes the bound from the raw params plus a live external read-back — it never trusts a tool-authored projected_impact, because a tool that under-reports its impact would otherwise walk through. Within standing policy it auto-approves; outside it, an Approve card. Plans carry an expiry and are re-validated at apply time, so an approval that sat for days can't act on stale external state.

The broker: execution authority never enters the µVM

A µVM proposes; the platform broker executes the approved plan, by idempotency key, item by item — partial success is a first-class state, not an exception. The gate validates the proposal, never the proposer, so a smarter agent never weakens the guardrail. Spend is enforced the same way: a preflight monthly-cap check before dispatch, plus provider-side hard limits on both implementations; self-reported cost_usd is reconciliation only.

The whole system, assembled

Everything from §1–§10 with the control plane (this section) at its center. The worker (dashed) is the only temporary piece — it spins up per job and disappears; Maestro, the brain, and the stores are the permanent project.

12 · Evaluation & the improvement loop

"Evaluation" in this system isn't one component — it's gates at four points in the lifecycle, each checking a different thing. Together they hold quality up; what they do not yet form is a loop that makes the system better over time. This section names what exists and marks what is deliberately still open.

The gates that exist today

Notice the absence: each gate checks the tool, the action, or the system — none checks whether the work achieved its goal.

The seam — outcome eval

The one place real outcome measurement already appears is inside a tool: a domain specialist that scores its own output. Max auditing a site with Lighthouse — a concrete SEO/performance number — is an outcome eval. The proposal judge above then evaluates what Max suggests — but only the proposal, not the result: nothing applies the change or re-measures the site afterward. The audit layer (§8) already records every action, so the data to close that gap exists — nothing consumes it yet.

The loop that isn't closed yet

Self-improvement is what closes it:

The substrate is already here: the audit trail is the feedback store, and the Reviewer, verify, and the policy gate/broker are the gates a change would pass through. What's missing is two things — (a) a standing outcome-eval layer per domain (Max + Lighthouse is the template), and (b) an auto-proposer that turns eval misses into specs the factory builds.

The stance holds even when it closes: it stays propose → gate → decide, not autonomous self-modification — the same posture as customer-approved hires and gated actions everywhere else here. Today the system grows (the factory commissions new tools and hires — §13) and refines a tool within a build (the Reviewer's three rounds); it does not yet learn from outcomes across time.

13 · 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

14 · Decisions locked

Each one is now a constraint on everything downstream.

15 · Still on the grill

how this was reviewed  This architecture was pressure-tested by two independent adversarial reviews (Codex + AMP). Verdict: sound-with-changes — keep the shape, close one gap. That gap (durable orchestration / execution authority) became §11 and the diagram above; the changes are captured as decisions #28–#32; and it left the two decisions below genuinely open.

What naturally comes next

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