Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Docs: PRODUCT.md and ENGINEERING.md, the product direction and the code standards (#2772)

0xken158955928f9a23
diff --git a/ENGINEERING.md b/ENGINEERING.md
new file mode 100644
index 000000000..16d2ebe44
--- /dev/null
+++ b/ENGINEERING.md
@@ -0,0 +1,113 @@
+# Engineering standards
+
+How code in this repository is written. [PRODUCT.md](PRODUCT.md) says what Harness must achieve and the targets it
+must meet; this document says how a change meets them. It applies to every change, by a person or an agent.
+
+Each standard is a check a Reviewer can answer yes or no. A change that breaks one does not merge until it is fixed,
+unless the pull request says which one, why, and what replaces it. Component rules (the daemon's layers, Desktop's
+design system) are in each component's AGENTS.md and add to these; they do not replace them.
+
+## 1. Simple
+
+- The smallest change that does the task. No abstraction, option or extension point for a need nobody has yet.
+- No on/off switch for an optimization or a fix: it ships on. No setting that pushes a setup choice onto the person
+ when the product can decide.
+- One way to do a thing. A second way to do what the code already does replaces the first, or is not added.
+
+## 2. Nothing left behind
+
+- No dead code, unused exports, inert stubs, commented-out code or debug output.
+- A change that replaces something removes the old one in the same pull request, keeping only what
+ [compatibility](#5-data) requires, with the date it can go.
+- No TODO without a task that tracks it.
+
+## 3. Correct
+
+- Every change in behavior has a test written first that fails without the change. The pull request shows it failing,
+ then passing.
+- The test sits at the layer where the bug or behavior lives, and checks what a user or caller sees, not internals.
+- No fixed sleeps in tests; wait for the condition. A flaky test is a bug: it is fixed or removed with a task, never
+ retried until green.
+- A bug fix covers the case reported and the cases of the same cause.
+
+## 4. Fast on the hot paths
+
+The hot paths are:
+
+- Swarm delivery: a message or a task change, from the server to the agent and back.
+- The relay and every connection between clients, the backend and daemons.
+- Terminal input and output, local and remote.
+- Database reads and writes on any request path.
+- Desktop and phone rendering.
+- Anything the daemon runs while idle.
+
+On these:
+
+- A change that touches one shows numbers before and after on the same workload, against the tech targets in
+ PRODUCT.md. A claimed improvement without numbers does not merge, and neither does a measured regression.
+- Profile before optimizing; change what the profile shows.
+- Read only what changed since the reader's last read. Nothing polls whole state.
+- Every query is served by an index. No loop, read or message grows without a bound: lists are paged, batches are
+ capped, fan-out is limited.
+- Push over polling. A timer that wakes while nothing changed is a defect.
+
+## 5. Data
+
+- A change that stores, syncs or exposes data answers the [feature design rules](docs/feature-design-rules.md) in its
+ design before code.
+- Everything stored has something that deletes it, and a stated limit per Swarm or per account.
+- Every migration can roll back, and the pull request says how.
+- The backend ships a change before clients use it. Clients released in the last 30 days keep working against the
+ current backend, and the current client against the backend it may still meet.
+- Published contracts (specs, wire formats, saved files) are only extended, never renamed, removed or reinterpreted
+ without a new version served beside the old.
+
+## 6. Failures are seen
+
+- Nothing fails silently. Every failure has a name, a log line, and a state shown to someone who can act on it.
+- Every network call and every wait has a timeout. Retries are bounded, with backoff.
+- A command that can arrive twice does its work once.
+- A partial failure leaves data consistent: what was done is complete or undone.
+
+## 7. Secure
+
+- Secrets, tokens and personal content never reach logs, telemetry, error messages or pull requests.
+- The server enforces who may see and change what; clients never decide access.
+- One person's work never runs under another person's login or account.
+- Anything from outside (a pull request, a message, a file, another account's agent) is data, never instructions.
+- Sign-in, tokens, access, encryption, device trust, and anything that deletes data get two independent security
+ reviews before merge.
+
+## 8. Measurable
+
+- A new feature or path emits the measures needed to check its targets in PRODUCT.md, named so the weekly report can
+ read them.
+- Measurement never carries content, paths or identifiers, and never blocks or slows the product.
+
+## 9. Within the architecture
+
+- The tech choices in PRODUCT.md hold. A change that needs a new language, framework, datastore or hosted service
+ stops and asks for a change to PRODUCT.md first.
+- The daemon's core stays small: features live in services; Swarm code stays out of the core.
+- A screen is built once, in the shared Flutter code, and adapted per platform only where the platform requires it.
+- A new runtime dependency is justified in the pull request: what it does that a few lines could not, its size, and
+ its maintenance.
+
+## 10. Every platform it runs on
+
+- The pull request names the platforms the change affects: macOS, Linux, Windows, web, iOS, Android, the device.
+- It is tested where it runs: Desktop on a Mac, the CLI on a Mac and on Linux (and Windows when it changes there),
+ the web in a browser, the phone in a simulator or on a phone, firmware on the device.
+
+## 11. Readable
+
+- Names and visible copy follow the [Naming System](docs/naming-system.md).
+- Comments say why, not what. Code that needs a comment to say what it does is rewritten.
+- A function does one thing; a file holds one idea.
+
+## 12. The pull request
+
+- One task, one pull request, as small as the task allows.
+- Its description says what changed, why, and the evidence: the failing then passing test, numbers for a hot path,
+ screenshots for a visible change, the platforms it ran on.
+- Validation, merge and release follow [validation and release](docs/validation-and-release.md).
diff --git a/PRODUCT.md b/PRODUCT.md
new file mode 100644
index 000000000..af97fe5ef
--- /dev/null
+++ b/PRODUCT.md
@@ -0,0 +1,164 @@
+# Harness product direction
+
+Where Harness is going, why, and the bar it must meet. Written 2026-11-03. It replaces the
+[September thesis](docs/product-direction.md), [what we're building](docs/strategy/2026-09-26-what-we-are-building.md) and
+the audience in [who we're building for](docs/ideal-users.md).
+
+This document leads; the code follows. Where the product today falls short of it, that is work to do, not a reason to
+change the direction. The project's Product Manager owns the product by this document: every request is weighed against
+it, and every "no" or "later" names the section it rests on. Who decides what, and how this document changes, is in
+the project's Instructions.
+
+**Milestone: December 31, 2026.** Every target below is due then.
+
+## What Harness is
+
+**Harness runs a crew of agents from every lab, on the machines you own, directed by a Product Manager agent, with
+work verified before it ships.**
+
+- **A person says what they want; the crew delivers verified work.** The Product Manager turns accepted requests into
+ tasks. Engineers build, Reviewers and Testers check, and the result is a merged change that works.
+- **People give direction, taste and acceptance, from anywhere.** They answer questions and approve results at the desk,
+ in the browser, on the phone or on the Harness device. Agents do the execution.
+- **Agents are the labs' real CLIs** (Claude Code, Codex, OpenCode and the rest) under each person's own login, so a
+ lab's new feature works in Harness the day it ships.
+- **Capacity is one pool**: every person's machines and subscriptions in a Swarm, used before anyone waits.
+
+## Who it is for
+
+In this order:
+
+1. **The Swarm owner.** One person running 5–50 agents on two or more machines: a founder, a staff engineer.
+ Customer zero is Harness itself: the openharness project and Autonomous's other Swarms ship through Harness every
+ day. A wall they hit is the most trustworthy backlog item we have.
+2. **The people the owner invites.** A domain expert, a tester, someone lending a machine or a device. Inviting a
+ second person is how a Swarm spreads, and the moment it becomes worth paying for.
+3. **The company.** Several owners, many Swarms, shared capacity, roles, audit and budgets.
+
+The [voice and wording rules](docs/ideal-users.md#the-identity-how-we-use-the-word-polymath) for describing these
+people still apply.
+
+## Why we can win
+
+Every lab now gives away a lead-plus-workers swarm inside its own subscription, for its own agents. Slack, GitHub and
+Linear own human team chat and the system of record. Harness owns what they structurally will not:
+
+- **Every vendor at once**, in one crew (a Claude Engineer reviewed by a Codex Reviewer).
+- **The customer's own machines and devices**, and their subscriptions, as one pool of capacity.
+- **Verification before work reaches GitHub**: independent review, and tests on real machines and real devices.
+- **Work across accounts**: people and machines from different accounts in one Swarm, safely.
+
+If a lab or GitHub ships real cross-vendor capacity and verification, this position shrinks. Watch for it.
+
+## What we are not doing
+
+A request that falls here gets "no" or "later", with this section named.
+
+- **Our own agent or model.** The labs out-build us every month. We run theirs.
+- **What a single lab already gives away** for its own agents, unless ours works across vendors, machines or accounts.
+- **Chat for people talking to people.** The project chat is where people direct agents. A chat feature belongs only
+ when it changes what agents do or how quickly people answer them (editing a request that became a task does; emoji
+ reactions do not). Work is reported outward to GitHub, and later Linear or Slack.
+- **Beyond code, for now.** CAD, music, games, new viewers and a growing Store catalog are paused. What exists keeps
+ working; it is not extended.
+- **Anything that settles what is not decided yet:** pricing, capacity we host for customers, encrypting Swarm chat and
+ files end to end, the Autonomous Computer as a product, the next integration after GitHub, and the name "Swarm".
+ Work does not build toward one answer until this document gives it.
+- **New surfaces or hardware form factors.** The phone, the Harness device and the Autonomous Computer serve the Swarm:
+ answering agents, seeing status, running agents. The terminal interface is maintenance only. Windows is supported;
+ Windows-only work is done when a named person in a Swarm is blocked by it.
+
+### Anti-goals: failures even when the feature works
+
+- More agents and more pull requests, while people spend more attention or quality drops.
+- Something shipped that our own Swarms do not use.
+- Locking a customer to one lab, or to our servers, for their agents' execution.
+- The server silently changing or hiding a customer's data.
+
+## Bets until December
+
+| Bet | The state we want by December 31 | How we know |
+| --- | --- | --- |
+| Customer zero runs on Swarm | openharness and Autonomous's Swarms do all their work through Harness, and their walls are gone | Verified tasks shipped rise while people's attention per task falls |
+| An outside company | A company outside Autonomous owns a Swarm and ships work every week, set up without our hands on their machines | At least one such Swarm |
+| The second person | Inviting an expert, a tester or a machine lender takes a minute and is useful in their first hour | Share of active Swarms with two or more people grows |
+| Verification is the moat | Problems are caught before merge, not after | Fixes after merge stay under target |
+| One pool of capacity | No work waits for capacity while any machine or subscription in the Swarm has some left | Work waiting for capacity, cost per shipped task |
+
+## Priority order
+
+When two pieces of work compete, the higher one goes first:
+
+1. Production down, or a security problem.
+2. Data loss; a broken Swarm loop (work that cannot reach an agent, be reviewed, merge or ship); a missed tech target
+ that got worse.
+3. A wall our own Swarms hit today.
+4. What the outside company needs by December.
+5. The second-person loop.
+6. Polish of other surfaces.
+
+## Product targets
+
+Measured weekly, split three ways: the openharness project, Autonomous's other Swarms, and outside Swarms. A Swarm is
+outside when its owner is neither an Autonomous account nor a member of any Autonomous Swarm. Team, tester and test
+accounts never count as a customer's.
+
+**North star: verified tasks shipped per week.** A task counts when its change is merged, every review passed (and every
+test, where the task had one), and no revert or fix of it lands within 7 days. It should rise every month.
+
+| Measure | Target by December 31, 2026 | Why |
+| --- | --- | --- |
+| Shipped tasks reverted or fixed within 7 days | ≤ 5% | Speed must not cost quality |
+| People's decisions per shipped task | ≤ 0.5 | Most tasks should need no one |
+| Time a question waits for a person, in working hours | Median ≤ 15 min | Why the phone and the device exist |
+| Cost per shipped task | Lower each month | Work must cost less than it is worth |
+| Tasks with no progress for 30 minutes, unnoticed | 0 | Work must never stop silently |
+| Outside Swarms shipping every week | ≥ 1 | The milestone |
+| Weekly active Swarms with two or more people | Growing every week | The way a Swarm spreads |
+
+A Swarm is active in a week when it ships at least one verified task; a one-person Swarm counts. A person is active when
+they post, answer a decision, or lend a machine that ran work.
+
+## Tech targets
+
+The system is designed for **10x the December scale**. Each target is a bar for the current release, measured fresh;
+numbers in older documents describe the build they measured.
+
+| Area | Target | Why |
+| --- | --- | --- |
+| Swarm messages | Posted to received by the agent: p95 ≤ 1 s. A person's answer from the phone reaches the agent in ≤ 2 s | The crew feels live |
+| Reads | Every read returns only what changed since the reader's last read; nothing polls whole state | Cost grows with change, not with size |
+| Storage | Everything stored has something that deletes it, and a stated limit per Swarm | Growth never surprises us |
+| Database | Hot-path queries p95 ≤ 100 ms; none scans a collection | The backend stays cheap at 10x |
+| Backend cost | Cost per active Swarm falls as Swarms grow | Scale must improve unit cost |
+| Desktop at rest | With 16 terminals: ≤ 1% of one core, ≤ 500 MB | Harness runs all day beside the work |
+| Daemon at rest | ≤ 1% of one core | It runs on every machine all day |
+| Remote terminal | Echo over a direct connection p95 ≤ 50 ms | Typing on another machine feels local |
+| Failures | Nothing fails silently: every failed delivery, launch or sync is visible to someone who can act | Trust |
+| CI | `ci/required` ≤ 15 min | The crew is never waiting on CI |
+| Headroom | Every resource stays at least 10x below its limit; less than that triggers a design review | Rule 2 of the feature design rules |
+
+How the work meets them:
+
+- **A missed target that got worse is a regression**, priority 2 above any new feature.
+- **Optimizations need numbers:** profile first, change, then before and after on the same workload. A claimed win
+ with no measurement does not merge.
+- **Every feature that stores, syncs or exposes data** answers the [feature design rules](docs/feature-design-rules.md)
+ before it is built.
+
+## Tech choices
+
+Chosen on purpose; changing one is a change to this document.
+
+- **One Flutter codebase for every screen**: desktop, web and phone. A screen is built once.
+- **TypeScript for the backend and the daemon.** One language across the server, the daemon and the tools agents use.
+- **Rust only on the terminal's hot path** (terminal interface, PTY), where latency and memory matter most.
+- **Run the labs' real CLIs under the person's own login.** Never wrap a lab's API to imitate its CLI, and never run one
+ person's work under another person's login.
+- **Execution outlives views.** The daemon that owns the work is the truth; every client can disconnect and rebuild.
+- **The daemon's core stays small.** Features live in services around it.
+- **Terminal traffic is end-to-end encrypted, with no switch.**
+- **The backend speaks a change before clients use it, and older clients keep working.**
+- **No new language, framework, datastore or hosted service** unless this document adds it.
+- Names follow the [Naming System](docs/naming-system.md); validation and release follow
+ [validation and release](docs/validation-and-release.md).