Skip to content
harnesspmv0.5.1
Color scheme
Contrast
Color scheme
Contrast

Package format reference

In short

  • A harness is a harness/ folder at the package root: an Agent Plugins 1.0 plugin plus the dev.harnesspm extension.
  • Every file is optional except plugin.json.
  • Every unit has an ID, <plugin name>:<kind>/<name>, which projects use to exclude, replace or patch it.

The specification’s chapters on the package format and executables, on GitHub, have every rule.

Layout

harness/
├── plugin.json              Agent Plugins manifest (required)
├── skills/
│   └── acme-ui-review/
│       └── SKILL.md         Agent Skills
├── mcp.json                 Agent Plugins MCP configuration
└── dev.harnesspm/           harnesspm extension folder
    ├── rules/
    │   └── usage.md
    ├── patches/
    │   └── acme-colors-usage.patch.md
    ├── agents/
    │   └── acme-ui-reviewer.md
    ├── scripts/
    │   └── tokens.mjs
    ├── hooks.json
    └── permissions.json

plugin.json

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "acme-ui",
  "description": "Rules, docs and tools for building UIs with @acme/ui",
  "extensions": {
    "dev.harnesspm": {
      "extends": ["@acme/colors", "@acme/styles"],
      "docs": "../docs",
      "scripts": {
        "tokens": {
          "file": "./dev.harnesspm/scripts/tokens.mjs",
          "description": "Find a color token by a part of its name, with its light and dark values",
          "allow": true
        }
      },
      "exclude": ["acme-styles:hooks/check-edit"],
      "replace": { "acme-styles:rules/components": "./dev.harnesspm/rules/components.md" },
      "patch": { "acme-colors:rules/usage": "./dev.harnesspm/patches/acme-colors-usage.patch.md" }
    }
  }
}
Field Required Meaning
$schema Yes The Agent Plugins schema.
name Yes The plugin name: lowercase letters, digits, - and .. It starts every unit ID.
version No Defaults to version in package.json.
description, author, homepage, repository, license, keywords No Agent Plugins metadata.

extensions["dev.harnesspm"]

Field Type Meaning
extends string[] Packages whose harness this one passes on, resolved from this package’s folder.
exclude string[] Units or packages to drop from what it passes on.
replace object Unit ID → a file that takes the unit’s place.
patch object Rule ID → a patch that changes some of its sections.
docs string The docs folder, relative to harness/, inside the package.
scripts object Script name → { file, description?, allow? }.
projects object Git remote → a folder with units for that repository. Read only in added harnesses.

harnesspm check fails on an unknown field, so typos do not ship.

Unit kinds and IDs

Kind Location ID
Rule dev.harnesspm/rules/<name>.md acme-ui:rules/<name>
Skill skills/<name>/SKILL.md acme-ui:skills/<name>
Sub-agent dev.harnesspm/agents/<name>.md acme-ui:agents/<name>
Docs The folder in docs acme-ui:docs
Script scripts in plugin.json acme-ui:scripts/<name>
Hook dev.harnesspm/hooks.json, by id acme-ui:hooks/<id>
MCP server mcp.json, by server name acme-ui:mcp/<name>
Permissions dev.harnesspm/permissions.json acme-ui:permissions

Commands name scripts and MCP servers as <plugin>:<name>: npx harnesspm run acme-ui:tokens. Agents see an MCP server as <plugin>-<server>, such as acme-ui-docs.

Rules

Frontmatter Activation
None Always on. The text goes into the managed block.
paths, with or without description File-scoped. Active when the agent works on matching files.
description only On demand. Listed with its description.

paths are globs from the project root. A pattern without a leading / also matches at any depth. Start it with /, such as /harness/**, to match only at the root.

Patches

---
remove: ["Contrast"]
---

## Where colors come from

- In an app on Acme UI, colors are Acme UI tokens: follow the Acme UI rule.

A section is a heading and everything up to the next heading of the same or a higher level. A section in the patch replaces the one with the same heading and level, or is added at the end. remove lists sections to remove.

Sub-agents

---
name: acme-ui-reviewer
description: Reviews UI changes against the Acme UI rules. Use for UI pull requests.
claude: { tools: "Read, Grep, Glob", model: "sonnet" }
codex: { model_reasoning_effort: "medium" }
---

Review the change like an owner. Do not edit files.

name, description and the body are portable. Settings for one agent go under its own key.

Scripts

Field Required Meaning
file Yes Path inside harness/, starting with ./.
description No Shows the script to agents. Without it, only hooks and MCP servers use it.
allow No Asks that agents may run it without a prompt, in projects that trust the package.

The runner sets PLUGIN_ROOT, PLUGIN_DATA, HARNESSPM_PROJECT_DIR and HARNESSPM_AGENT. It runs .js, .mjs and .cjs files with node, .sh files with sh, and other files directly.

Hooks

{
  "hooks": {
    "PostToolUse": [
      { "id": "check-styles", "matcher": { "claude": "Edit|Write" }, "run": "check-styles", "timeout": 30 }
    ]
  }
}
Field Required Meaning
id Yes The unit name.
run Yes A script name from scripts.
matcher No A string for both agents, or an object with claude and codex keys.
timeout No Seconds.

Events: SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SubagentStart, SubagentStop, Stop. A hook script reads the agent’s JSON on stdin, exits 0 to continue and 2 to block, with the reason on stderr.

MCP servers

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "docs": { "type": "stdio", "command": "node", "args": ["${PLUGIN_ROOT}/dev.harnesspm/scripts/docs-mcp.mjs"] },
    "figma": { "type": "streamable-http", "url": "https://example.com/mcp" }
  }
}

stdio servers start through npx harnesspm mcp <plugin>:<server>. Remote servers are written as they are. Never put secrets in mcp.json.

Permissions

{
  "deny": [["git", "push", "--force"]],
  "ask": [["npm", "publish"]]
}

Deny and ask rules are command prefixes. They pass through from any package. Allow rules come only from "allow": true on a trusted package’s own scripts.