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.

Add the domain-specific harness spec, registry, and starter

dee2dbeeabbfb90
diff --git a/docs/plans/2026-09-14-003-domain-specific-harness-mvp-plan.md b/docs/plans/2026-09-14-003-domain-specific-harness-mvp-plan.md
new file mode 100644
index 000000000..43ab4909a
--- /dev/null
+++ b/docs/plans/2026-09-14-003-domain-specific-harness-mvp-plan.md
@@ -0,0 +1,196 @@
+# Domain-specific harnesses (DSH): MVP
+
+Status: in progress · 2026-09-14
+
+## Context
+
+Four Autonomous products — Workshop (3D CAD, the successor of Vibe), Circuit (PCB), TV (short
+drama) and Battle (robot training) — are each "a coding agent plus a domain": ~1k lines of SKILL.md
+prose that steers Claude Code or Codex, a deterministic pipeline and verifier the skills call, a
+local web viewer, and a hand-copied shell (a Node driver that spawns the agent, a chat UI, a
+catalog watcher, SSE). The shell is identical in every product and is what Harness already is.
+
+A **domain-specific harness** is that product minus its shell: a git repo with a manifest, an
+`AGENTS.md`, a skills folder, a workspace template, setup/doctor scripts, and an optional viewer.
+Harness reads the manifest, materializes the workspace, launches the base engine in a tmux pane,
+starts the viewer next to it, and watches one JSON file for the verdict.
+
+Decisions already made (see the conversation of 2026-09-14):
+
+- To the user a DSH is just another **engine tile** in Create Harness. Internally it is a
+ **decoration on the session** (`dsh` field), never a new `AgentEngine` — the CLI switches on the
+ engine in ~30 exhaustive sites and discovery cannot tell two engines that share one binary apart.
+- One fixed base per DSH: **Circuit runs on `claude`, Workshop Make runs on `codex`**.
+- Registry and spec live in this monorepo under `dsh/`. DSH repos stay separate.
+- MVP scope: Circuit + Workshop, install by git URL or local path, macOS webview pane, verdict
+ chip. Out of scope: registry UI, `progress.json`, remote-machine viewer tunneling, Linux webview.
+
+## Contract
+
+### `harness.json` (spec 1) — at the root of a DSH repo
+
+```jsonc
+{
+ "spec": 1,
+ "id": "autonomous/circuit", // owner/name; the install dir and the wire id
+ "name": "Circuit", // the picker tile
+ "description": "Chat with AI → a board you can order",
+ "engine": "claude", // base engine, one of ENGINES
+ "workspace": {
+ "template": "template", // copied into an EMPTY workspace (no marker present)
+ "marker": "product.json", // relative path; present = already materialized
+ "init": "toolchain/init-workspace.sh" // optional; run after the template copy, cwd = workspace
+ },
+ "agent": {
+ "instructions": "AGENTS.md", // copied to <workspace>/AGENTS.md, see below
+ "skills": ["skills"], // dirs whose SKILL.md-bearing subdirs are linked in
+ "env": { "CIRCUIT_TOOLCHAIN": "${dsh}/toolchain" }, // ${dsh} ${workspace} ${home} expand
+ "args": [] // appended to the base engine's argv
+ },
+ "toolchain": {
+ "setup": "toolchain/setup.sh", // run once at install, cwd = install dir
+ "doctor": "toolchain/doctor.sh" // exit 0 = ready; stdout lines are shown to the user
+ },
+ "viewer": { // optional (tier 2)
+ "command": "toolchain/viewer.sh", // long-running; env HARNESS_VIEWER_PORT, HARNESS_WORKSPACE
+ "url": "http://127.0.0.1:${port}/?file=${artifact}", // ${port} ${artifact} (url-encoded)
+ "artifactExtensions": [".step", ".stl"] // newest such file under the workspace
+ },
+ "verdict": ".harness/verdict.json" // relative to the workspace; optional (tier 1+)
+}
+```
+
+Materialization, in order, at every create (idempotent):
+
+1. If `workspace.marker` is absent: copy `workspace.template/*` into the workspace, then run
+ `workspace.init` if declared.
+2. `AGENTS.md`: copy if absent; else append the DSH file under a marker line
+ `<!-- harness:dsh <id> -->` if that marker is not already present. For a `claude` base also
+ ensure `CLAUDE.md` contains `@AGENTS.md` (Claude Code reads `CLAUDE.md`, imports the rest).
+3. Skills: symlink each skill dir into `<workspace>/.claude/skills/<name>` (claude) or
+ `<workspace>/.agents/skills/<name>` (codex). Symlinks, so a DSH update is live.
+4. Create `<workspace>/.harness/`.
+
+Launch env, always: `HARNESS_DSH=<id>`, `HARNESS_DSH_DIR=<install dir>`,
+`HARNESS_WORKSPACE=<workspace>`, plus `agent.env` expanded. Set through tmux `-e`, the same channel
+grids and Codex profiles use, on create AND on every relaunch (`buildLaunchOverrides`).
+
+### `.harness/verdict.json` (spec 1) — written by the DSH's own scripts
+
+```jsonc
+{
+ "spec": 1,
+ "ready": false, // the one machine fact: fab.ready, gates passed, exam passed
+ "summary": "3 errors, 2 warnings", // one line for the pane header
+ "findings": [
+ { "severity": "error", "kind": "source_trace_not_connected", "message": "…", "ref": "U3.pin7" }
+ ], // severity ∈ error | warning | info; kind is open
+ "artifact": "boards/main.board.json", // optional; primary thing to view, workspace-relative
+ "updatedAt": "2026-09-14T20:00:00Z"
+}
+```
+
+Lifted from Circuit's `.board.json` and TV's `.episode.json` sidecars (same severity gate). Circuit
+writes it beside the sidecar in `circuitpy.generation`; Workshop writes it from `verify_project`.
+
+### Wire (daemon ↔ desktop)
+
+- `agent_create` payload gains `dsh?: string`. Refused with `INVALID_DSH` when not installed on
+ this machine or when `engine` is not the DSH's base.
+- `AgentFrame` gains `dsh: string | null`, `dshName: string | null`, `viewerUrl: string | null`,
+ `verdict: { ready, summary, errors, warnings, artifact, updatedAt } | null`. Null is a real answer
+ (see `agentFrame.ts`'s doc on erased fields).
+- `dsh_list` → `{ dsh: [{ id, name, description, engine, installed, viewer, tier }] }`: installed
+ DSHs on this machine merged with the bundled registry (`dsh/registry/**/*.json`).
+- `dsh_install { id?, url?, ref? }` → runs clone → setup → doctor; pushes
+ `dsh_install_status { id, phase: clone|setup|doctor|done|failed, detail? }`; replies `{ ok }` at
+ the end (the desktop uses a 10-minute timeout for this one request).
+- Discovery reads `HARNESS_DSH` off the live process (`probeDsh`, same cached env read as
+ `probeCodexHome`) so a pane the daemon did not create, or re-minted after a restart, is labelled.
+
+### On disk
+
+```
+~/.harness/dsh/
+ installed.json # [{ id, dir, source, ref, commit, installedAt }]
+ autonomous/circuit/ # clone, or a symlink when installed with --link (dev loop)
+ autonomous/workshop/
+```
+
+CLI: `harness dsh install <git-url|path> [--link] [--ref <ref>]`, `harness dsh list`,
+`harness dsh doctor <id>`, `harness dsh remove <id>`.
+
+### In the monorepo
+
+```
+dsh/
+ README.md what a DSH is, the tiers, how to publish
+ spec/README.md this contract, frozen; CHANGES.md is append-only
+ spec/schema/ harness.schema.json, verdict.schema.json
+ registry/autonomous/ circuit.json, workshop.json (bundled into the CLI at build time)
+ starter-dsh/ tier 0: manifest + AGENTS.md + one skill; the CLI's test fixture
+cli/src/dsh/ manifest, install, materialize, viewer, verdict, probe
+desktop/lib/dsh/ catalog, web pane, verdict chip
+```
+
+## Changes
+
+### 1. CLI (`cli/src/dsh/`)
+
+- `manifest.ts`: zod schema for `harness.json`; `loadInstalledDsh()` reads `installed.json` and
+ each manifest; `expandDshEnv()`.
+- `install.ts`: `installDsh({ url|path, ref, link })` → clone or symlink → `toolchain.setup` →
+ `toolchain.doctor` → write `installed.json`. `removeDsh`, `dshDoctor`.
+- `materialize.ts`: steps 1–4 above; pure over an injected fs for the spec.
+- `registry.ts`: `RegisteredSession.dsh?: string | null` + validators; `openPendingAgent` accepts it.
+- `agentFrame.ts`: the four new fields; `AgentFrameContext` gains `viewerUrl`, `verdict`.
+- `backendSocket.ts`: `agent_create` validation, `dsh_list`, `dsh_install`.
+- `cli.ts` `onCreateAgent`: materialize before `createAndRegisterPane`, env through
+ `createAndRegisterPane({ env })`; `launchOverrides.ts` adds the same env for restart/restore.
+- `probe.ts`: `probeDsh(identity)`; `terminalAgentDiscovery.ts` attaches `dsh`; the reconciler's
+ `onDiscovered`/`onObserved` carry it into the registry.
+- `viewer.ts`: `DshViewerManager` — one child process per DSH agent with a viewer: free port,
+ spawn, wait for the port, publish `viewerUrl`; re-publish when the newest artifact changes;
+ bounded restart on exit; torn down in `cancelAgent`/delete.
+- `verdict.ts`: `DshVerdictWatcher` — chokidar on the verdict file; parse; publish.
+- `cli.ts` subcommands: `dsh install|list|doctor|remove`.
+- Registry JSON files imported into the bundle (`dsh/registry/autonomous/*.json`).
+
+### 2. Desktop
+
+- `core/models.dart`: `Agent.dsh`, `dshName`, `viewerUrl`, `verdict`.
+- `widgets/engine_identity.dart`: identities for `autonomous/circuit` and `autonomous/workshop`
+ with PNG marks in `assets/engine-icons/`; `agentIdentity(agent)` = `dsh ?? engine`.
+- `state/app_state.dart`: per-machine DSH catalog (`dsh_list`), `dsh_install` with status panel,
+ create sends `{engine: base, dsh: id}`; `_handleEvent` opens/updates/closes the viewer pane.
+- `widgets/agent_picker.dart` + `new_agent_dialog.dart`: quick row = Codex, Claude Code, Circuit,
+ Workshop; overflow lists everything; "Harness will install Circuit on <machine>" note.
+- `state/terminal_pane.dart`: `PaneKind { terminal, web }`, `url`, `ownerAgentId`. Web panes are
+ derived from agents and not persisted.
+- `widgets/web_pane_panel.dart`: `webview_flutter` (macOS via `webview_flutter_wkwebview`), the
+ one native plugin this work adds; `_PaneContent` dispatches on kind.
+- `widgets/terminal_panel.dart`: verdict chip in the status slot; add to `_headerPresentation`.
+
+### 3. Circuit (`autonomous-circuit`, branch `harness-dsh`)
+
+- `harness.json`, `AGENTS.md` (the driver's PLAN/IMPLEMENT/REVIEW prompts as a file),
+ `template/` (the project skeleton), `toolchain/{setup,doctor,viewer}.sh`.
+- Viewer-only mode: `CIRCUIT_WORKSPACE=<dir>` serves that one workspace; client hides chat and
+ onboarding when the server says `viewerOnly`.
+- `circuitpy.generation` writes `.harness/verdict.json` beside the sidecar.
+- SKILL.md paths `~/.claude/skills/<x>` → `${CIRCUIT_SKILLS_DIR:-~/.claude/skills}/<x>`.
+
+### 4. Workshop (`autonomous-workshop`, branch `harness-dsh`)
+
+- `harness.json` (engine `codex`), `AGENTS.md` (Make only), `template/`, `toolchain/{setup,doctor,viewer}.sh`.
+- `viewer/`: Vibe's prebuilt CAD viewer runtime (`skills/cad-viewer/scripts/viewer/{backend,dist}`)
+ vendored; `viewer.sh` runs it with `VIEWER_LOCAL_WORKSPACE_ROOT=$HARNESS_WORKSPACE`.
+- `verify_project` writes `.harness/verdict.json`.
+
+## Verification
+
+- `make cli-test` green; new specs for manifest, materialize, verdict, viewer URL.
+- `flutter test` green minus the two pre-existing failures noted in the branches memory.
+- On this Mac: `harness dsh install --link` both repos; `make install-cli`; run the desktop from the
+ worktree; Create Harness → Circuit → prompt → board appears in the pane, ready chip flips; same
+ for Workshop with a STEP in the 3D pane.
diff --git a/dsh/README.md b/dsh/README.md
new file mode 100644
index 000000000..6ba152304
--- /dev/null
+++ b/dsh/README.md
@@ -0,0 +1,57 @@
+# Domain-specific harnesses
+
+A **domain-specific harness (DSH)** turns Harness into a product for one domain: PCB design,
+3D CAD, short drama, robot training. It is a git repo that Harness installs on a machine. Users see
+it as one more engine tile in Create Harness — pick **Circuit**, choose a folder, prompt — and get
+the domain's skills in the agent, its toolchain on the machine, its viewer in a pane next to the
+terminal, and its verdict in the pane header.
+
+Harness never imports a DSH's code. It reads one manifest, copies files into the workspace, runs
+the commands the manifest declares, and watches one JSON file. That is the whole coupling, and it
+is what lets hundreds of DSHs exist without any of them touching this repo.
+
+## Anatomy
+
+```
+harness.json manifest: id, name, base engine, workspace, agent, toolchain, viewer, verdict
+AGENTS.md appended to the agent's instructions in every workspace
+skills/ SKILL.md bundles, linked into the workspace
+template/ copied into an empty workspace
+toolchain/ setup.sh (once, at install) · doctor.sh (exit 0 = ready) · viewer.sh (optional)
+viewer/ optional: whatever viewer.sh serves
+```
+
+## Tiers
+
+| Tier | Ships | Harness shows |
+|---|---|---|
+| 0 | manifest, AGENTS.md, skills | the tile, the terminal |
+| 1 | + scripts that write `.harness/verdict.json` | + a ready chip and findings in the pane header |
+| 2 | + a viewer server | + a web pane next to the terminal |
+
+[`starter-dsh/`](starter-dsh/) is tier 0 and the copy-me template. Circuit and Workshop are tier 2.
+
+## The contract
+
+[`spec/README.md`](spec/README.md) is the whole contract: the manifest, the verdict file, what
+Harness does at create time, and what it sets in the engine's environment. The JSON Schemas in
+[`spec/schema/`](spec/schema/) are normative. The spec is frozen; changes are appended to
+[`spec/CHANGES.md`](spec/CHANGES.md).
+
+## Installing
+
+```bash
+harness dsh install https://github.com/autonomous-ai/autonomous-circuit # by git URL
+harness dsh install /path/to/checkout --link # symlink, for development
+harness dsh list
+harness dsh doctor autonomous/circuit
+```
+
+The desktop app offers the same install from the Create Harness dialog: a DSH the machine does not
+have yet shows "Harness will install Circuit on this machine before starting".
+
+## Publishing
+
+Add one file under [`registry/<owner>/<name>.json`](registry/) with the repo URL and pinned ref. CI
+clones it and runs the conformance check; green merges. First-party entries carry `verified: true`;
+everything else shows its git URL and an unverified note on install.
diff --git a/dsh/registry/autonomous/circuit.json b/dsh/registry/autonomous/circuit.json
new file mode 100644
index 000000000..e06d05463
--- /dev/null
+++ b/dsh/registry/autonomous/circuit.json
@@ -0,0 +1,10 @@
+{
+ "id": "autonomous/circuit",
+ "name": "Circuit",
+ "description": "Chat with AI → a board you can order. Golden blocks, two independent DRC substrates, a JLCPCB-ready packet.",
+ "repo": "https://github.com/autonomous-ai/autonomous-circuit",
+ "ref": "harness-dsh",
+ "engine": "claude",
+ "tier": 2,
+ "verified": true
+}
diff --git a/dsh/registry/autonomous/workshop.json b/dsh/registry/autonomous/workshop.json
new file mode 100644
index 000000000..68f732c44
--- /dev/null
+++ b/dsh/registry/autonomous/workshop.json
@@ -0,0 +1,10 @@
+{
+ "id": "autonomous/workshop",
+ "name": "Workshop",
+ "description": "Describe a 3D object; get a validated, printable STEP part or assembly with a live 3D view.",
+ "repo": "https://github.com/autonomous-ai/autonomous-workshop",
+ "ref": "harness-dsh",
+ "engine": "codex",
+ "tier": 2,
+ "verified": true
+}
diff --git a/dsh/spec/CHANGES.md b/dsh/spec/CHANGES.md
new file mode 100644
index 000000000..bcb82b2cd
--- /dev/null
+++ b/dsh/spec/CHANGES.md
@@ -0,0 +1,7 @@
+# Changes to the DSH contract
+
+Append-only. Each entry: Change / Why / Backward compatible / Mechanism.
+
+## 2026-09-14 — spec 1
+
+Initial contract. Lifted from the `.board.json` (Circuit) and `.episode.json` (TV) sidecars and the Vibe viewer's `serve:ensure` handoff.
diff --git a/dsh/spec/README.md b/dsh/spec/README.md
new file mode 100644
index 000000000..342927758
--- /dev/null
+++ b/dsh/spec/README.md
@@ -0,0 +1,114 @@
+# Domain-specific harness contract (spec 1)
+
+Frozen 2026-09-14. Changes go to [CHANGES.md](CHANGES.md), append-only.
+
+A DSH is a git repo. Harness reads `harness.json` at its root and nothing else about its code.
+
+
+## `harness.json`
+
+```jsonc
+{
+ "spec": 1,
+ "id": "autonomous/circuit", // owner/name; the install dir and the wire id
+ "name": "Circuit", // the picker tile
+ "description": "Chat with AI → a board you can order",
+ "engine": "claude", // base engine, one of ENGINES
+ "workspace": {
+ "template": "template", // copied into an EMPTY workspace (no marker present)
+ "marker": "product.json", // relative path; present = already materialized
+ "init": "toolchain/init-workspace.sh" // optional; run after the template copy, cwd = workspace
+ },
+ "agent": {
+ "instructions": "AGENTS.md", // copied to <workspace>/AGENTS.md, see below
+ "skills": ["skills"], // dirs whose SKILL.md-bearing subdirs are linked in
+ "env": { "CIRCUIT_TOOLCHAIN": "${dsh}/toolchain" }, // ${dsh} ${workspace} ${home} expand
+ "args": [] // appended to the base engine's argv
+ },
+ "toolchain": {
+ "setup": "toolchain/setup.sh", // run once at install, cwd = install dir
+ "doctor": "toolchain/doctor.sh" // exit 0 = ready; stdout lines are shown to the user
+ },
+ "viewer": { // optional (tier 2)
+ "command": "toolchain/viewer.sh", // long-running; env HARNESS_VIEWER_PORT, HARNESS_WORKSPACE
+ "url": "http://127.0.0.1:${port}/?file=${artifact}", // ${port} ${artifact} (url-encoded)
+ "artifactExtensions": [".step", ".stl"] // newest such file under the workspace
+ },
+ "verdict": ".harness/verdict.json" // relative to the workspace; optional (tier 1+)
+}
+```
+
+Materialization, in order, at every create (idempotent):
+
+1. If `workspace.marker` is absent: copy `workspace.template/*` into the workspace, then run
+ `workspace.init` if declared.
+2. `AGENTS.md`: copy if absent; else append the DSH file under a marker line
+ `<!-- harness:dsh <id> -->` if that marker is not already present. For a `claude` base also
+ ensure `CLAUDE.md` contains `@AGENTS.md` (Claude Code reads `CLAUDE.md`, imports the rest).
+3. Skills: symlink each skill dir into `<workspace>/.claude/skills/<name>` (claude) or
+ `<workspace>/.agents/skills/<name>` (codex). Symlinks, so a DSH update is live.
+4. Create `<workspace>/.harness/`.
+
+Launch env, always: `HARNESS_DSH=<id>`, `HARNESS_DSH_DIR=<install dir>`,
+`HARNESS_WORKSPACE=<workspace>`, plus `agent.env` expanded. Set through tmux `-e`, the same channel
+grids and Codex profiles use, on create AND on every relaunch (`buildLaunchOverrides`).
+
+## `.harness/verdict.json`
+
+```jsonc
+{
+ "spec": 1,
+ "ready": false, // the one machine fact: fab.ready, gates passed, exam passed
+ "summary": "3 errors, 2 warnings", // one line for the pane header
+ "findings": [
+ { "severity": "error", "kind": "source_trace_not_connected", "message": "…", "ref": "U3.pin7" }
+ ], // severity ∈ error | warning | info; kind is open
+ "artifact": "boards/main.board.json", // optional; primary thing to view, workspace-relative
+ "updatedAt": "2026-09-14T20:00:00Z"
+}
+```
+
+Lifted from Circuit's `.board.json` and TV's `.episode.json` sidecars (same severity gate). Circuit
+writes it beside the sidecar in `circuitpy.generation`; Workshop writes it from `verify_project`.
+
+## Wire (daemon ↔ desktop)
+
+- `agent_create` payload gains `dsh?: string`. Refused with `INVALID_DSH` when not installed on
+ this machine or when `engine` is not the DSH's base.
+- `AgentFrame` gains `dsh: string | null`, `dshName: string | null`, `viewerUrl: string | null`,
+ `verdict: { ready, summary, errors, warnings, artifact, updatedAt } | null`. Null is a real answer
+ (see `agentFrame.ts`'s doc on erased fields).
+- `dsh_list` → `{ dsh: [{ id, name, description, engine, installed, viewer, tier }] }`: installed
+ DSHs on this machine merged with the bundled registry (`dsh/registry/**/*.json`).
+- `dsh_install { id?, url?, ref? }` → runs clone → setup → doctor; pushes
+ `dsh_install_status { id, phase: clone|setup|doctor|done|failed, detail? }`; replies `{ ok }` at
+ the end (the desktop uses a 10-minute timeout for this one request).
+- Discovery reads `HARNESS_DSH` off the live process (`probeDsh`, same cached env read as
+ `probeCodexHome`) so a pane the daemon did not create, or re-minted after a restart, is labelled.
+
+## On disk
+
+```
+~/.harness/dsh/
+ installed.json # [{ id, dir, source, ref, commit, installedAt }]
+ autonomous/circuit/ # clone, or a symlink when installed with --link (dev loop)
+ autonomous/workshop/
+```
+
+CLI: `harness dsh install <git-url|path> [--link] [--ref <ref>]`, `harness dsh list`,
+`harness dsh doctor <id>`, `harness dsh remove <id>`.
+
+## In the monorepo
+
+```
+dsh/
+ README.md what a DSH is, the tiers, how to publish
+ spec/README.md this contract, frozen; CHANGES.md is append-only
+ spec/schema/ harness.schema.json, verdict.schema.json
+ registry/autonomous/ circuit.json, workshop.json (bundled into the CLI at build time)
+ starter-dsh/ tier 0: manifest + AGENTS.md + one skill; the CLI's test fixture
+cli/src/dsh/ manifest, install, materialize, viewer, verdict, probe
+desktop/lib/dsh/ catalog, web pane, verdict chip
+```
+
+Normative schemas: [`schema/harness.schema.json`](schema/harness.schema.json), [`schema/verdict.schema.json`](schema/verdict.schema.json).
diff --git a/dsh/spec/schema/harness.schema.json b/dsh/spec/schema/harness.schema.json
new file mode 100644
index 000000000..6ecc7490e
--- /dev/null
+++ b/dsh/spec/schema/harness.schema.json
@@ -0,0 +1,72 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://harness.autonomous.ai/dsh/spec/1/harness.schema.json",
+ "title": "Domain-specific harness manifest (harness.json), spec 1",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["spec", "id", "name", "engine"],
+ "properties": {
+ "spec": { "const": 1 },
+ "id": {
+ "type": "string",
+ "pattern": "^[a-z0-9][a-z0-9-]{0,63}/[a-z0-9][a-z0-9-]{0,63}$",
+ "description": "owner/name. The install directory under ~/.harness/dsh and the id on the wire."
+ },
+ "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The picker tile." },
+ "description": { "type": "string", "maxLength": 300 },
+ "engine": {
+ "type": "string",
+ "description": "The base engine this harness runs on: claude, codex, cursor, … (one of the CLI's ENGINES)."
+ },
+ "workspace": {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "template": { "type": "string", "description": "Directory copied into an empty workspace." },
+ "marker": { "type": "string", "description": "Workspace-relative file whose presence means 'already materialized'." },
+ "init": { "type": "string", "description": "Command run after the template copy, cwd = workspace." }
+ }
+ },
+ "agent": {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "instructions": { "type": "string", "description": "File copied to <workspace>/AGENTS.md (appended under a marker if one exists)." },
+ "skills": {
+ "type": "array",
+ "items": { "type": "string" },
+ "description": "Directories whose SKILL.md-bearing subdirectories are linked into the workspace's skills folder."
+ },
+ "env": {
+ "type": "object",
+ "additionalProperties": { "type": "string" },
+ "description": "Set on the engine process. Values may use ${dsh}, ${workspace}, ${home}."
+ },
+ "args": { "type": "array", "items": { "type": "string" }, "description": "Appended to the base engine's argv." }
+ }
+ },
+ "toolchain": {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "setup": { "type": "string", "description": "Run once at install, cwd = install dir." },
+ "doctor": { "type": "string", "description": "Exit 0 = ready. Each stdout line is shown to the user." }
+ }
+ },
+ "viewer": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["command", "url"],
+ "properties": {
+ "command": { "type": "string", "description": "Long-running; env HARNESS_VIEWER_PORT, HARNESS_WORKSPACE, HARNESS_DSH_DIR; cwd = install dir." },
+ "url": { "type": "string", "description": "Template with ${port} and ${artifact} (url-encoded workspace-relative path, or empty)." },
+ "artifactExtensions": {
+ "type": "array",
+ "items": { "type": "string", "pattern": "^\\.[A-Za-z0-9]+$" },
+ "description": "The newest file under the workspace with one of these extensions is ${artifact} when the verdict names none."
+ }
+ }
+ },
+ "verdict": { "type": "string", "description": "Workspace-relative path of the verdict file. Default .harness/verdict.json." }
+ }
+}
diff --git a/dsh/spec/schema/verdict.schema.json b/dsh/spec/schema/verdict.schema.json
new file mode 100644
index 000000000..fd10e25d0
--- /dev/null
+++ b/dsh/spec/schema/verdict.schema.json
@@ -0,0 +1,29 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://harness.autonomous.ai/dsh/spec/1/verdict.schema.json",
+ "title": "Domain-specific harness verdict (.harness/verdict.json), spec 1",
+ "type": "object",
+ "additionalProperties": true,
+ "required": ["spec", "ready"],
+ "properties": {
+ "spec": { "const": 1 },
+ "ready": { "type": "boolean", "description": "The one machine fact: fab.ready, all gates passed, exam passed." },
+ "summary": { "type": "string", "maxLength": 200, "description": "One line for the pane header." },
+ "findings": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "required": ["severity", "message"],
+ "additionalProperties": true,
+ "properties": {
+ "severity": { "enum": ["error", "warning", "info"] },
+ "kind": { "type": "string", "description": "Open set; never switched on by Harness." },
+ "message": { "type": "string" },
+ "ref": { "type": "string", "description": "What it is about: a part, a gate, a file." }
+ }
+ }
+ },
+ "artifact": { "type": "string", "description": "Workspace-relative path of the primary thing to view." },
+ "updatedAt": { "type": "string", "format": "date-time" }
+ }
+}
diff --git a/dsh/starter-dsh/AGENTS.md b/dsh/starter-dsh/AGENTS.md
new file mode 100644
index 000000000..20715553c
--- /dev/null
+++ b/dsh/starter-dsh/AGENTS.md
@@ -0,0 +1,4 @@
+# Starter harness
+
+You are working inside a Harness workspace for the Starter domain. Keep a running log of what you
+did in `NOTES.md`, one line per change. The `hello` skill explains the one command this domain has.
diff --git a/dsh/starter-dsh/harness.json b/dsh/starter-dsh/harness.json
new file mode 100644
index 000000000..708528a3a
--- /dev/null
+++ b/dsh/starter-dsh/harness.json
@@ -0,0 +1,20 @@
+{
+ "spec": 1,
+ "id": "autonomous/starter",
+ "name": "Starter",
+ "description": "The smallest domain-specific harness: a manifest, an AGENTS.md, and one skill.",
+ "engine": "claude",
+ "workspace": {
+ "template": "template",
+ "marker": "NOTES.md"
+ },
+ "agent": {
+ "instructions": "AGENTS.md",
+ "skills": ["skills"],
+ "env": { "STARTER_DSH_DIR": "${dsh}" }
+ },
+ "toolchain": {
+ "setup": "toolchain/setup.sh",
+ "doctor": "toolchain/doctor.sh"
+ }
+}
diff --git a/dsh/starter-dsh/skills/hello/SKILL.md b/dsh/starter-dsh/skills/hello/SKILL.md
new file mode 100644
index 000000000..49b447d1c
--- /dev/null
+++ b/dsh/starter-dsh/skills/hello/SKILL.md
@@ -0,0 +1,12 @@
+---
+name: hello
+description: Greet the workspace. Use when the user asks the Starter harness to say hello or to prove the skill is loaded.
+---
+
+# hello
+
+Run this from the workspace root and paste the output back to the user:
+
+```bash
+sh "$STARTER_DSH_DIR/skills/hello/scripts/hello.sh"
+```
diff --git a/dsh/starter-dsh/skills/hello/scripts/hello.sh b/dsh/starter-dsh/skills/hello/scripts/hello.sh
new file mode 100755
index 000000000..2bff02442
--- /dev/null
+++ b/dsh/starter-dsh/skills/hello/scripts/hello.sh
@@ -0,0 +1,2 @@
+#!/bin/sh
+echo "hello from the Starter harness in $(pwd)"
diff --git a/dsh/starter-dsh/template/NOTES.md b/dsh/starter-dsh/template/NOTES.md
new file mode 100644
index 000000000..69c943f0e
--- /dev/null
+++ b/dsh/starter-dsh/template/NOTES.md
@@ -0,0 +1,3 @@
+# Notes
+
+(the agent appends one line per change)
diff --git a/dsh/starter-dsh/toolchain/doctor.sh b/dsh/starter-dsh/toolchain/doctor.sh
new file mode 100755
index 000000000..9f63d2547
--- /dev/null
+++ b/dsh/starter-dsh/toolchain/doctor.sh
@@ -0,0 +1,3 @@
+#!/bin/sh
+# Exit 0 when this machine can run the harness. Print one line per check; Harness shows them.
+command -v sh >/dev/null 2>&1 && echo "ok sh" || { echo "miss sh"; exit 1; }
diff --git a/dsh/starter-dsh/toolchain/setup.sh b/dsh/starter-dsh/toolchain/setup.sh
new file mode 100755
index 000000000..7cde2e31f
--- /dev/null
+++ b/dsh/starter-dsh/toolchain/setup.sh
@@ -0,0 +1,3 @@
+#!/bin/sh
+# Nothing to install: the Starter harness has no toolchain. Kept so the shape matches a real one.
+exit 0