---
title: "§2 Pack model"
description: "Normative requirements for the pack directory, its three files, identity, planes, and the invariants every pack satisfies."
canonical: https://harnesscontextprotocol.io/docs/specification/pack-model
---

# §2 Pack model

> Normative requirements for the pack directory, its three files, identity, planes, and the invariants every pack satisfies.

## 2.1 Package

1. A Harness Pack is a directory (the **pack root**).
2. A pack MUST contain these three files at the pack root: `surface.json`,
   `policy.json`, `HARNESS.md`. Filenames are exact and case-sensitive.
3. A pack MAY contain additional files. Runtimes MUST NOT assign protocol
   semantics to files other than the three above.
4. Runtimes MUST reject a pack root lacking any of the three files.
5. Paths declared in the manifest as relative (`wrap.bin` beginning with `.`,
   `openapi.path`) MUST be resolved against the pack root.

*Informative.* Path containment (rejecting relative paths that resolve outside
the pack root) is proposed for HCP/1.2. Runtimes SHOULD enforce it today.

## 2.2 Identity

1. A pack's identity is its `pack_id`, given by manifest field `id`.
2. `pack_id` MUST be 1 to 128 characters, lower-case, and stable across the pack's
   lifetime.
3. Policy `surface_id` MUST equal `pack_id`. Runtimes MUST reject a pack where
   they differ.
4. If the manifest carries protocol metadata (`hcp`, `pack_id`, …), its
   `pack_id` MUST equal `id`.
5. One `pack_id` SHOULD correspond to one maintained source repository.

## 2.3 Commands

1. A pack declares its commands in the manifest `verbs` map. Each key is a
   `verb_key`.
2. `verb_key` MUST be non-empty, lower-case, and MAY contain `.` as a family
   separator. It MUST NOT contain whitespace or `/`.
3. A pack SHOULD declare between 5 and 12 commands. A pack MAY declare fewer.
   A pack declaring more than 12 SHOULD be split.
4. A pack MUST NOT expose a generic pass-through command (a command whose
   arguments are forwarded as an arbitrary argv). Such a command is
   non-conforming.
5. Every `verb_key` MUST have a Policy entry (§4.4).

## 2.4 Triggers

1. A pack MAY declare triggers in the manifest as `stimulusTriggers[]`, each
   with a `ref`.
2. Every declared `ref` MUST have a Policy `stimuli` entry (§4.4).
3. A pack MUST NOT declare a trigger for a condition it can only observe by
   polling.

## 2.5 Planes

1. `plane` is `runtime` (default) or `control`.
2. A `control` pack MUST use Binding mode `mothership` (§8.2). Runtimes MUST
   fail lint otherwise.
3. Capabilities requiring different Binding modes MUST be separate packs.
4. Runtimes MUST NOT activate a `control` pack for a Principal lacking an
   explicit operator or elevation grant.

## 2.6 Protocol affinity

1. A pack targets a protocol version with metadata field `hcp`. For HCP/1.x the
   value MUST be `1`.
2. Runtimes MUST reject a pack whose `hcp` value they do not support and SHOULD
   report the unsupported version.
3. When the manifest does not carry explicit metadata, runtimes MUST derive it
   from the manifest fields (`id` → `pack_id`, `kind` → `adapter_kind`, …) and
   validate the derived object.

## 2.7 Invariants

A conforming pack satisfies all of the following.

| # | Invariant |
|---|-----------|
| P1 | Declares; never executes |
| P2 | Contains no secrets, tokens, or credential material |
| P3 | Contains no user allow-lists, roles, or tenant identifiers |
| P4 | Passes lint (§14.1) on a conforming runtime |
| P5 | Declares a closed, named command set |
| P6 | Has one Binding mode |
| P7 | One Policy file covers every command and every trigger |
| P8 | Adapter is replaceable without changing `verb_key` or Policy |

## 2.8 What is not part of the pack

*Informative.* Catalog metadata, runtime grants, Principal mappings, sink
configuration, UI catalogs, and delivery transports are runtime concerns. A pack
that embeds them is not portable and SHOULD be rejected in review even if it
passes lint.

## Sitemap

- [Documentation](https://harnesscontextprotocol.io/docs)
- [Packs](https://harnesscontextprotocol.io/packs)
- [Glossary](https://harnesscontextprotocol.io/docs/reference/glossary)
- [llms.txt](https://harnesscontextprotocol.io/llms.txt)
- [llms-full.txt](https://harnesscontextprotocol.io/llms-full.txt)
- [OpenAPI](https://harnesscontextprotocol.io/openapi.json)
- [MCP](https://harnesscontextprotocol.io/mcp)