# Quick start

> Install the harness, check it works, and set up the tools it uses.

The harness ships as a Claude Code plugin. Install it once per product repo, at
project scope, and commit the settings file. Everyone who opens that repo in
Claude Code and trusts the folder then gets the same skills, the same design
reviewer, and the same catalogue.

## Before you start

You need [Claude Code](https://claude.com/claude-code) installed and signed in.
Open a session at the root of your product repo, not a subdirectory — skills
read the repo they run in, and a session opened deeper may not trigger them.

## Add the harness

These are the steps for Claude Code in the terminal or a code editor. On the
desktop app, follow the [desktop steps](#install-on-the-claude-code-desktop-app)
instead.

Run two commands in your Claude Code session, one at a time — send the first
and wait for it to finish before you send the second. Pasted together they
read as a single command and the install never runs.

First, register the harness repository as a plugin marketplace:

```
/plugin marketplace add transformteamsg/dx-harness
```

Then install the `dx-harness` plugin from it:

```
/plugin install dx-harness@dx-harness
```

The command opens the plugin's details and asks you to choose a scope. Select
**Install for all collaborators on this repository (project scope)**. Claude
Code records the plugin in `.claude/settings.json`.

That gives you the [skills](/harness/skills), the design reviewer agent, and
the [catalogue](/standards/catalog). The catalogue ships inside the
plugin, so your repo never carries its own copy of the standard.

## Verify the installation

Type `/dx-harness:dx-design`. It asks what you want and routes you to the
right skill; if it responds, the install worked.

If nothing happens:

- Confirm `dx-harness` appears and is enabled — run `/plugin` in the
  terminal, or in the desktop app select **+** next to the prompt box, then
  **Plugins**.
- Confirm your session is open at the repo root, not a subdirectory.
- Restart Claude Code and try again.

## Share it with your team

The install turns the plugin on in `.claude/settings.json`. Add the harness
marketplace to the same file, so it holds both entries:

```json
{
  "extraKnownMarketplaces": {
    "dx-harness": {
      "source": { "source": "github", "repo": "transformteamsg/dx-harness" }
    }
  },
  "enabledPlugins": {
    "dx-harness@dx-harness": true
  }
}
```

Commit the file. When a teammate opens the repo in Claude Code and accepts the
workspace trust dialog, Claude Code registers the marketplace and loads the
plugin from it. They don't run an install command.

If the plugin doesn't load for a teammate, they can install it once, in a
terminal:

```
claude plugin marketplace add transformteamsg/dx-harness
```

```
claude plugin install dx-harness@dx-harness --scope project
```

Teammates on the desktop app follow the
[desktop steps](#install-on-the-claude-code-desktop-app) instead.

## Install on the Claude Code desktop app

In the desktop app, plugins live in the **Code** tab's local sessions, under the
**+** button next to the prompt box. A local session also has an integrated
terminal, which opens in your session's folder. Open it from the **Views** menu.

A cloud session, including Claude Code in the browser at claude.ai/code, has
no plugin browser. It doesn't load the plugins you install on your machine or
the ones your repo's `.claude/settings.json` turns on.

1. In the **Code** tab, start a local session and pick your product repo's root
   folder.
2. Register the harness marketplace. Open the integrated terminal and run:

   ```
   claude plugin marketplace add transformteamsg/dx-harness
   ```

   This needs the `claude` command. If the terminal can't find it, install
   Claude Code for the terminal with its
   [setup guide](https://code.claude.com/docs/en/setup). The app's local
   sessions read the same settings files as the terminal.

3. Select **+** next to the prompt box, then **Plugins**, then **Add plugin**.
   The plugin browser lists plugins from the marketplaces you've added. Select
   **dx-harness** and choose this project as the scope.
4. Type `/` in a chat to choose a skill, or send `/dx-harness:dx-design`.

**+** → **Plugins** also lists your installed plugins, and **Manage plugins**
enables, disables, or uninstalls one. To update, run the
[Stay current](#stay-current) terminal commands in the integrated terminal.
Where this page says restart Claude Code, quit and reopen the app.

Then continue with the one-time machine setup below.

## Set up your machine, once

You don't have to do this before you start. The plugin is turned on per repo,
but a few tools are per machine. When you ask `/dx-harness:dx-design` to shape
something, it checks two things first: that the `agent-browser`
command is available, and that your repo has a `DESIGN.md`. If the command is
missing, it sends you to setup. If `DESIGN.md` is missing, it offers to define
your design language.

It doesn't check the rest of your machine. Run `/dx-harness:dx-design-setup` to
verify the complete checklist. It runs each check and asks before it installs
anything. The checklist includes:

- **agent-browser** — captures the screenshots the verify phase grades.
- **`gh`, authenticated** — lets `/dx-harness:dx-design-feedback` file an issue the
  moment the harness confuses you.
- **Python with PyYAML** — runs the deterministic check scripts.
- **Commit signing** — set up once per machine.
- **The design-ticket tracker** — wired to your repo.

## Stay current

Plugin updates are manual: auto-update is off by default for a third-party
marketplace like this one. When the catalogue or the skills change, update in two
steps. On the desktop app, run the terminal commands in the integrated terminal.

First, refresh the marketplace's listing. This updates the list of plugins,
not the plugin you installed. Run this in a Claude Code session:

```
/plugin marketplace update dx-harness
```

Or run this in a terminal:

```
claude plugin marketplace update dx-harness
```

Then update the plugin itself. Open it on the **Installed** tab in `/plugin` and
select **Update now**, or run this in a terminal:

```
claude plugin update dx-harness@dx-harness
```

On Claude Code versions before 2.1.281, add `--scope project` to that command.
The new version loads in your next session, or after you run `/reload-plugins`.

The skills and the catalogue are versioned together, so one update moves both.

## Adopt the harness for a whole product repo

Installing gives you the tools. Making a repo harness-ready is six more items:
declared product context, a component manifest, skills verified, deterministic checks,
record locations, and a named waiver approver. Work through them once per repo.

If you work on the harness itself, open Claude Code in the harness repo and
skip all of this — its skills load automatically from the repo.