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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Docs: PRODUCT.md and ENGINEERING.md, the product direction and the code standards (#2772)
0xken158955928f9a23
diff --git a/ENGINEERING.md b/ENGINEERING.mdnew file mode 100644index 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.mdnew file mode 100644index 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).