@tenphi/harnesspm 0.0.0-snapshot.376310a

package/docs/spec/06-trust.md

@@ -0,0 +1,72 @@
+# 6. Trust and lock
+
+**In short**
+
+- Text units (rules, docs, skills, sub-agents) need no trust. Executable units and allow rules do.
+- A project trusts a package in `harnesspm.json`. Adding a harness on top is the person trusting it. Trust never passes through `extends`.
+- An agent never grants permissions through harnesspm: new allow rules, hooks and MCP servers wait for a person.
+- `harnesspm.lock.json` records every unit's hash, so pull requests show what changed.
+
+## 6.1 What needs trust
+
+| Unit | Needs trust? | Why |
+| --- | --- | --- |
+| Rules, docs, sub-agent definitions, skills | No | Text. The agent still asks before running commands, unless a permission allows them. |
+| The `Skill(<name>)` allow rule that lets an unattended session run a skill | **Yes** | It removes a prompt. Written only for skills from the project, an added harness or a trusted package. |
+| Scripts, hooks, MCP servers | **Yes** | They run code, some of them automatically. |
+| Allow permissions | **Yes** | They remove a prompt. |
+| Deny and ask permissions | No | They only restrict. |
+
+## 6.2 Trusting a package
+
+```json
+{
+  "trust": {
+    "@cube-dev/ui-kit": true,
+    "some-third-party": "pin"
+  }
+}
+```
+
+| Value | Meaning |
+| --- | --- |
+| `true` | Executable units are active, also after upgrades. The lock diff shows changes. For the team's own packages. |
+| `"pin"` | Active only in the version approved in the lock. Adding the entry approves the installed version. A new version stays off until `harnesspm approve`. For packages the team does not control. |
+| missing | Executable units stay off. `harnesspm sync` lists them as **pending** and does not fail. |
+
+Rules:
+
+1. Trust MUST NOT pass through `extends`. Trusting UI Kit does not trust Tasty.
+2. `harnesspm add` is the person's trust decision for that harness. Added harnesses need no `trust` entry.
+3. `harnesspm run` checks the lock before running a script, so the rules also hold when an agent calls a script directly.
+4. harnesspm MUST NOT add or widen allow rules, hooks or MCP servers when the agent's model runs it, for example through an install the model starts. Agents keep the model from granting itself permissions, and harnesspm must not be a way around that.
+   - Claude Code marks who runs a command: `AI_AGENT` ends in `_agent` for commands the model runs and in `_harness` for hooks and MCP servers. Setup scripts get neither. harnesspm treats `_agent`, or `CLAUDECODE=1` without `AI_AGENT`, as a model run.
+   - Codex sets `CODEX_CI=1` and `CODEX_TOOL_CALL_ID` in commands the model runs, and in neither hooks nor commands a person runs. harnesspm treats either as a model run. Codex's workspace-write sandbox also keeps `.codex/` and `~/.codex` read-only for model runs ([research](../research/agent-capabilities.md#codex)).
+   - These markers are advisory: a model can unset them. They stop accidents, such as an install the model starts, not a model that works around them.
+   - A hook runs from settings a person wrote, so a hook run may add entries.
+   - A model run keeps the entries a person granted before, and never removes a deny or ask rule. Held-back entries stay pending until a person runs `harnesspm sync` or `harnesspm approve`, or a setup script or a hook runs harnesspm. Text units, skill links and other removals are written as usual.
+
+## 6.3 The lock
+
+`harnesspm.lock.json` is committed. It covers the dependency and project layers and records:
+
+- every harness package: name, version, plugin name, tarball URL and integrity, so `harnesspm fetch` can download it without an install; for a `"pin"` package, also the approved version;
+- every unit: ID, kind, content hash;
+- every patch: a hash of each section it replaces or removes, so an upgrade that changes one is reported.
+
+The lock holds no per-machine state, so every machine writes the same lock. `harnesspm status` shows which executable units are pending on this machine, and why.
+
+People do not edit it. Added harnesses are not locked. They follow their branch or version range, and `harnesspm update` refreshes them.
+
+## 6.4 CI
+
+`harnesspm sync --check` and every run with `CI=true` ignore added harnesses. `--check` writes nothing and fails when:
+
+- a committed output or the lock is out of date;
+- a `"pin"` package has a version that nobody approved.
+
+## 6.5 Not covered
+
+- **A trusted package is compromised.** `true` follows new versions. The lock diff and normal dependency review are the protection. Use `"pin"` for packages the team does not control.
+- **Prompt injection in text units.** Rules and skills are instructions. Review them like code.
+- **An agent ignores a rule.** harnesspm delivers instructions. Hooks and deny permissions can enforce some of them.

package/docs/spec/07-added.md

@@ -0,0 +1,104 @@
+# 7. Added harnesses
+
+**In short**
+
+- An **added harness** is an ordinary harness that a person adds on their machine, on top of the repository's. It is never committed.
+- Add any number, in order: for example, your team's shared harness, then your own. A later one wins on a skill name.
+- **User scope** applies a harness in every repository on the machine, including its entries for single repositories. **Local scope** applies it in one repository.
+- Agents can improve an added harness, as described in [08-improving.md](08-improving.md).
+
+## 7.1 What goes in it
+
+An added harness holds what should not live in every project repository:
+
+| Content | Unit kind | Example |
+| --- | --- | --- |
+| How a team or a person works | Always-on rule | Commit style, review habits, preferred tools |
+| Context the agent reads when needed | Docs (notes) | Which repositories exist and how they relate, environments, people to ask |
+| Repeated workflows | Skills | Releasing a package, preparing a weekly update |
+| Tools | Scripts, hooks, MCP servers | A script that opens a local preview of linked repositories |
+| Changes for one repository | Project entry | A local staging address, a replaced team rule |
+
+A team's harness and a person's own harness use the same format and the same commands. Only their owners differ, and each owner's rules decide how its changes are saved ([08-improving.md](08-improving.md#83-the-owner-decides-how-to-save)). To give a harness to everyone who works on a repository, make it a dependency instead (S6).
+
+A person's own added harness is the "memory" they keep across projects and machines. Notes that an agent saves by itself, such as Claude Code auto memory, stay with the agent and are not part of harnesspm.
+
+## 7.2 Example
+
+```text
+alex-harness/                    a git repository, on any host
+├── AGENTS.md                      how to change this repository, including how to save changes
+└── harness/
+    ├── plugin.json
+    ├── dev.harnesspm/rules/
+    │   └── workflow.md            always on
+    ├── notes/                     read on demand
+    │   ├── llms.txt               index of the notes
+    │   └── projects.md            repositories and how they relate
+    ├── skills/
+    │   └── alex-release/SKILL.md
+    └── projects/
+        └── cube-ui-kit/           same layout as harness/; plugin.json is optional
+            └── dev.harnesspm/rules/local-setup.md
+```
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "alex",
+  "extensions": {
+    "dev.harnesspm": {
+      "docs": "./notes",
+      "projects": {
+        "github.com/cube-js/cube-ui-kit": "./projects/cube-ui-kit"
+      }
+    }
+  }
+}
+```
+
+A project entry is matched by the repository's `origin` remote, written as `<host>/<path>` without `.git`, for SSH and HTTPS URLs alike. So it also works in a fresh clone in a cloud session.
+
+Units in an entry belong to the added harness, so their IDs start with its plugin name. An entry's unit wins over one with the same ID in the rest of the harness. The entry's optional `plugin.json` uses the same name and may hold `exclude`, `replace` and `patch` for the repository's units.
+
+## 7.3 Sources
+
+| Source | Example | Editable | Where it lives |
+| --- | --- | --- | --- |
+| Git repository | `github:alex/harness`, `git:https://git.example.com/team/harness.git` | yes | A working copy in `~/.harnesspm/harnesses/<name>/` |
+| Folder | `~/dev/alex-harness` | yes | In place |
+| npm package | `npm:@alex/harness` | no | A cache in `~/.harnesspm/cache/` |
+
+Git sources work with any host. npm and git sources never touch the project's `package.json` or lockfile.
+
+## 7.4 Scopes and order
+
+| Scope | How to add | Recorded in | Outputs |
+| --- | --- | --- | --- |
+| **User** | `npx harnesspm add <source>` | `~/.harnesspm/config.json` | User-level folders, see [04-outputs.md](04-outputs.md#44-outputs-of-added-harnesses-user-scope) |
+| **Local** | `npx harnesspm add <source> --local` | `harnesspm.local.json` in the repository, excluded from git | Project outputs, see [04-outputs.md](04-outputs.md#43-project-outputs) |
+
+Both files have one field:
+
+```json
+{ "harnesses": ["github:cube-js/frontend-harness", "github:alex/harness"] }
+```
+
+`add` appends, so harnesses apply in the order they were added: user scope first, then local scope. A project entry comes right after its harness. `harnesspm new --to <plugin>` names the harness to write into.
+
+## 7.5 Applying in every repository
+
+`harnesspm add` also installs one user-level `SessionStart` hook for each agent. The hook runs `npx -y @tenphi/harnesspm sync` at the start of every session. In a repository that does not use harnesspm, or whose dependencies are not installed yet, `sync` writes only the per-machine outputs of added harnesses, including their project entries, and changes only git-excluded files.
+
+- Claude Code runs the hook with `AI_AGENT=…_harness`, so this sync may write hooks and permissions ([06-trust.md](06-trust.md#62-trusting-a-package), rule 4).
+- Claude Code uses what the hook writes in the same session: a `CLAUDE.local.md` and a `.claude/settings.local.json` written by a `SessionStart` hook were both read in cloud sessions.
+- Codex asks the person to review a new hook once, in `/hooks`.
+- `--no-hook` skips the hook. Project entries then apply only where `harnesspm sync` runs.
+- `harnesspm remove` takes the hook away with the last harness with user scope.
+
+## 7.6 Keeping the project clean
+
+1. Added units are never written into tracked files. Per-machine files are excluded through `.git/info/exclude`.
+2. CI ignores added harnesses.
+3. `harnesspm status` lists every change that an added harness makes to the repository's units, so it stays visible.
+4. In a cloud environment shared by several people, add harnesses in your own environment. See [09-cloud.md](09-cloud.md).

package/docs/spec/08-improving.md

@@ -0,0 +1,77 @@
+# 8. Improving a harness
+
+**In short**
+
+- Every unit has an **owner**: a dependency, the project, or an added harness.
+- `harnesspm why <ID>` tells the agent where the source is and whether it can edit it.
+- The owner's own `AGENTS.md` and `CONTRIBUTING.md` decide how a change is saved. Without them, the default is a branch and a pull request.
+- harnesspm finds sources and grants write access. It does not push or talk to git hosts. The agent does that with its own tools.
+
+## 8.1 Find the source
+
+```text
+$ npx harnesspm why tasty:rules/state-maps
+owner       dependency @tenphi/tasty 3.17.1 (via @cube-dev/ui-kit)
+source      node_modules/.harnesspm/pkgs/@tenphi/tasty/harness/dev.harnesspm/rules/state-maps.md
+repository  https://github.com/tenphi/tasty
+editable    no. Add a `patch`, `replace` or `exclude` in harnesspm.json, or propose the change upstream.
+
+$ npx harnesspm why alex:rules/workflow
+owner       added github:alex/harness (user scope)
+source      ~/.harnesspm/harnesses/alex/harness/dev.harnesspm/rules/workflow.md
+rules       ~/.harnesspm/harnesses/alex/AGENTS.md
+editable    yes
+```
+
+## 8.2 Three owners
+
+| Owner | Where the source is | How the agent changes it |
+| --- | --- | --- |
+| 📦 Dependency | `node_modules`, read-only | Now: a `patch` for a small change, or a `replace` or `exclude`, in the project (for the team) or in an added harness (for its owner). Later: a proposal to the package's `repository`. |
+| 🏢 Project | The project repository | Edit the file, like any other change in that repository. |
+| ➕ Added harness | Its working copy or folder | Edit the file there. |
+
+To create a new unit instead of changing one, use `npx harnesspm new <kind> <name>`: without a flag for the project harness, `--to <plugin>` for an added harness, and `--to <plugin> --entry` for its entry for this repository.
+
+## 8.3 The owner decides how to save
+
+A harness is a repository, or lives in one. That repository's root `AGENTS.md` and `CONTRIBUTING.md` are its rules for changes. These are existing conventions, so harnesspm adds no setting for them.
+
+Before changing a source, the agent reads those files in the source repository and follows them. They can say anything that fits the owner, for example:
+
+- "Commit and push to `main`."
+- "Open a merge request on our GitLab and assign me."
+- "Leave the change uncommitted. I review it myself."
+
+## 8.4 Default when the owner says nothing
+
+1. Show the person the change and the reason, and ask before going on.
+2. Create a branch from the default branch, named `harnesspm/<topic>`.
+3. Commit with a message that says what changed and why.
+4. Push the branch and open a pull request or merge request with the tools the agent has, such as the GitHub CLI or an MCP server for the host.
+5. If a step is not possible, stop there and tell the person what is done and what is left: the branch, the commit, or the diff itself.
+
+The agent never pushes to the default branch unless the owner's rules allow it.
+
+For a dependency, the proposal goes to the package's `repository`, following that repository's rules. It is usually an issue or a pull request that the person reviews first.
+
+## 8.5 Access
+
+| Owner | Write access |
+| --- | --- |
+| Dependency | Never. `node_modules` is not a source. |
+| Project | As for any file in the project. |
+| Added harness | harnesspm adds the working copy to the agent's writable folders: `permissions.additionalDirectories` for Claude Code, `sandbox_workspace_write.writable_roots` for Codex. |
+
+## 8.6 Checks before saving
+
+1. Run `npx harnesspm check <harness folder>`. It validates the harness and warns about files that look like secrets.
+2. Never copy private data from the current project into an added harness without the person's agreement.
+
+## 8.7 Shared working copies
+
+Several projects and sessions on one machine use the same working copy of an added harness. `harnesspm update` never changes a working copy that has uncommitted changes or unpushed commits. It reports them instead.
+
+## 8.8 What harnesspm ships for this
+
+harnesspm's own harness has the skill `harnesspm-improve`, which walks the agent through 8.1 to 8.6. See [12-dogfooding.md](12-dogfooding.md).

package/docs/spec/09-cloud.md

@@ -0,0 +1,47 @@
+# 9. Cloud sessions
+
+**In short**
+
+- v1 supports **Claude Code cloud sessions**. Codex Cloud is not supported in v1 ([13.12](13-open-questions.md#1312-removed-in-review)); Codex on a person's computer is.
+- A cloud session starts from a clean clone. Team outputs appear when the project's install runs `harnesspm sync`, as on a laptop. Run the install in the setup script: when the agent runs it, new hooks, MCP servers and allow rules stay pending ([06-trust.md](06-trust.md#62-trusting-a-package), rule 4).
+- Added harnesses need one command in the container: in the setup script of the person's own environment, or asked of the agent.
+- Improving an added harness from the cloud needs push access to its repository. Without it, the agent shows the change in the session.
+
+## 9.1 Adding harnesses
+
+```bash
+npx -y @tenphi/harnesspm add github:alex/harness
+```
+
+| Way | How it works |
+| --- | --- |
+| **Setup script** of the person's own environment | ✅ Runs after the clone and before Claude Code starts, once per cached snapshot (about 7 days). Later sessions start from the snapshot, and the `SessionStart` hook refreshes the outputs in each one. |
+| **Ask the agent** in a session | ✅ Rules and skills apply at once; Claude Code loads new skills live. Hooks and MCP servers stay pending, because an agent cannot grant itself permissions ([06-trust.md](06-trust.md#62-trusting-a-package)). Built-in tools need no allow rule there; MCP tools do ([05-executables.md](05-executables.md#55-what-the-agents-still-decide)). Tip: a small skill on claude.ai can hold the command, because claude.ai skills load in every cloud session. |
+
+Add harnesses in your own environment: anyone who uses an environment can read its setup script and variables. A committed repository hook is not the place either, because it belongs to the team.
+
+When the command runs inside a session, it prints the added always-on rules so the agent follows them at once. New sessions read them from the files.
+
+In a setup script, `harnesspm add` adds the harness with user scope and installs the `SessionStart` hook ([07-added.md](07-added.md#75-applying-in-every-repository)). The hook applies project entries and writes per-machine outputs in every session, so the setup script does not depend on the repository.
+
+A `~/.claude/settings.json` written by the setup script is read in cloud sessions: its `env` values and deny rules apply. Deny rules are the way to restrict a cloud session.
+
+## 9.2 Private sources
+
+| Source | How to reach it |
+| --- | --- |
+| Public git repository or npm package | Works |
+| Private git repository | Add it under the environment's repositories, or attach it to the session. Setup scripts cannot read variables or secrets. |
+| Private npm package | Inside a session only: a network secret for `registry.npmjs.org` |
+
+Never write tokens into setup scripts or environment variables: anyone who uses the environment can read them.
+
+## 9.3 Improving from the cloud
+
+The flow is the one in [08-improving.md](08-improving.md). Pushing needs the added harness's repository attached to the session with push access.
+
+A cloud container is discarded later. When the agent cannot push, it shows the full change in the session, so the person can apply it elsewhere.
+
+## 9.4 What a probe confirmed
+
+In November 2026 a probe confirmed in Claude Code cloud sessions every output that added harnesses use: user-level rules, skills and settings written by a setup script, `CLAUDE.local.md` and `.claude/settings.local.json` written by a `SessionStart` hook, hooks, MCP servers from the cached snapshot, and skills added during a session. Details are in [research/agent-capabilities.md](../research/agent-capabilities.md#cloud-sessions). The proof of concept checks them again ([13.11](13-open-questions.md#1311-agent-behavior-not-confirmed-yet)).

package/docs/spec/10-cli.md

@@ -0,0 +1,60 @@
+# 10. CLI
+
+**In short**
+
+- Projects use `init`, `sync`, `status`, `why`, `approve` and `run`. Jobs that do not install dependencies use `fetch`.
+- Authors use `check` and `new`.
+- People use `add`, `remove` and `update` for harnesses on top of the repository's.
+- Saving changes to a harness is not a harnesspm command. The owner's rules decide it ([08-improving.md](08-improving.md)).
+
+The npm package is `@tenphi/harnesspm`, and the command it installs is `harnesspm`. Use `npx harnesspm …` in a project that depends on it. Use `npx -y @tenphi/harnesspm …` anywhere else, so npx downloads the package by its full name. Outputs follow the same split, and an allow rule always has the prefix of the command it allows.
+
+## 10.1 Projects
+
+| Command | What it does |
+| --- | --- |
+| `harnesspm init` | Creates `harnesspm.json`, adds `harnesspm sync` to the `postinstall` script of a private package or to `prepare` otherwise, makes `CLAUDE.md` import `AGENTS.md`, then runs `harnesspm sync`. |
+| `harnesspm sync` | Resolves the layers and writes all outputs. Runs on every install. In a repository that does not use harnesspm (it has no `harnesspm.json`), or whose dependencies are not installed, it writes only the per-machine outputs of added harnesses, so it never wipes the committed block. When an agent runs it, new allow rules, hooks and MCP servers stay pending ([06-trust.md](06-trust.md#62-trusting-a-package)). |
+| `harnesspm sync --check` | Writes nothing and ignores added harnesses, as every run with `CI=true` does. Fails when a committed output or the lock is out of date. For CI. |
+| `harnesspm status` | Layers, packages, versions, pending trust, changes that added harnesses make to the repository's units, always-on size per agent. |
+| `harnesspm why <ID>` | Owner, source, repository and whether the unit is editable ([08-improving.md](08-improving.md#81-find-the-source)). |
+| `harnesspm approve [<package>]` | Writes the entries that a model run left pending, and records a `"pin"` package's new version as approved in the lock. A person runs it, not an agent. |
+| `harnesspm run [--agent <agent>] <plugin>:<script> [-- args]` | Runs a script ([05-executables.md](05-executables.md#51-scripts)). Hooks pass `--agent`, which sets `HARNESSPM_AGENT`. |
+| `harnesspm fetch` | Downloads only the harness packages in the lock, without a full install, and checks their integrity ([04-outputs.md](04-outputs.md#42-stable-package-paths)). For review bots and CI jobs that do not install dependencies. |
+
+Package managers run these scripts on a full install, but not on `npm install <pkg>`, `npm uninstall` or `pnpm add`, so run `npx harnesspm sync` after those. `sync --check` in CI catches a missed one. `postinstall` would also run when others install a published package, so `init` uses it only in a private package; Yarn 2 and later run `postinstall` but not `prepare` ([research](../research/package-managers.md)).
+
+`harnesspm mcp [--agent <agent>] <plugin>:<server>` also exists. Agents call it to start stdio MCP servers. People do not need it.
+
+```text
+$ npx harnesspm status
+📦 dependencies  @cube-dev/ui-kit 0.206.1 → @tenphi/tasty 3.17.1, @tenphi/glaze 2.0.0
+🏢 project       harnesspm.json: 1 replace · 1 patch
+➕ added         github:cube-js/frontend-harness (user) · github:alex/harness (user), project entry cube-ui-kit
+⏳ pending       some-third-party: 1 hook (not trusted)
+📏 always-on     Codex 18.4 KiB of 32 KiB · Claude Code 212 lines
+```
+
+## 10.2 Authors
+
+| Command | What it does |
+| --- | --- |
+| `harnesspm check [<folder>]` | Validates a harness ([02-package-format.md](02-package-format.md#210-validation)) and warns about files that look like secrets. Run it at `prepack`. |
+| `harnesspm new <kind> <name> [--to <plugin>] [--entry]` | `<kind>` is `rule`, `skill`, `agent` (a sub-agent), `script`, `hook` or `mcp`. Writes a valid unit from a template, and creates `harness/plugin.json` when the project has none. A skill's name gets the plugin name in front. `--to <plugin>` writes it into an added harness, `--to <plugin> --entry` into its entry for this repository, which holds rules, skills, sub-agents and docs. |
+| `harnesspm new patch <rule ID> [--to <plugin>] [--entry]` | Writes a patch with a copy of the rule's sections, or of the whole rule when it has none, and registers it: in `harness/plugin.json` (file in `harness/dev.harnesspm/patches/`) when the rule reaches the project through its own harness's `extends`, so users get the change too; otherwise in `harnesspm.json` (file in `harnesspm/patches/`); with `--to <plugin>`, in that added harness. Edit the sections to change and delete the others. |
+
+## 10.3 People
+
+| Command | What it does |
+| --- | --- |
+| `harnesspm add <source> [--local] [--no-hook]` | Adds a harness on top of the repository's: with user scope, or with `--local` for this repository only. Installs the `SessionStart` hook ([07-added.md](07-added.md#75-applying-in-every-repository)) and prints the added always-on rules. |
+| `harnesspm remove <source> [--local]` | Removes it and its outputs. With the last harness with user scope, the hook and write access go too. |
+| `harnesspm update` | Fetches new versions of added harnesses and rewrites their outputs. Skips working copies with uncommitted changes or unpushed commits and lists them. |
+
+## 10.4 Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. Pending trust is not an error. |
+| `1` | Error: invalid harness, failed check. |
+| `2` | `harnesspm run` refused a script ([05-executables.md](05-executables.md#51-scripts)). When a hook calls it, `2` also blocks the event: harnesspm fails closed. |

package/docs/spec/11-standards.md

@@ -0,0 +1,49 @@
+# 11. Standards
+
+**In short**
+
+- The package format is **Agent Plugins 1.0**. Skills are **Agent Skills**. The main output is **AGENTS.md**. MCP servers use the Agent Plugins `mcp.json`.
+- harnesspm adds only what no standard covers yet: `extends`, trust, rules, hooks, scripts, overrides and added harnesses.
+- harnesspm should propose its additions upstream once they are proven.
+
+## 11.1 Standards harnesspm uses
+
+| Standard | Steward | Status (Nov 2026) | How harnesspm uses it |
+| --- | --- | --- | --- |
+| [Agent Plugins](https://agent-plugins.org/) | Vendor-neutral steering committee (Amazon, Cursor, Microsoft, OpenAI, Vercel) | 1.0.0 published; 1.1.0 working draft | **The package format.** `harness/` is a plugin: `plugin.json`, `skills/`, `mcp.json`, `${PLUGIN_ROOT}` and `${PLUGIN_DATA}`. harnesspm data lives in the client-extension namespace, as §8 of the standard requires. |
+| [Agent Skills](https://agentskills.io/specification) | Agentic AI Foundation (Linux Foundation) | Published; contributed to the foundation in Oct 2026 | **Skills.** `SKILL.md` with `name` and `description`. harnesspm never renames a skill, because `name` must match the folder name. |
+| [AGENTS.md](https://agents.md/) | Agentic AI Foundation | Widely adopted | **The main instructions output** for every agent that reads it. harnesspm writes a marked block in it. A harness repository's own `AGENTS.md` is also where its owner says how changes are saved. |
+| `CONTRIBUTING.md` | Community convention, recognized by GitHub and GitLab | Widely used | **How to propose changes** to a harness repository, read together with its `AGENTS.md` ([08-improving.md](08-improving.md#83-the-owner-decides-how-to-save)). |
+| [Model Context Protocol](https://modelcontextprotocol.io/) | Agentic AI Foundation | Published | **MCP servers.** harnesspm does not touch the protocol. It configures servers through the Agent Plugins `mcp.json` format. |
+| [llms.txt](https://llmstxt.org/) | Community convention | Widely used | **Docs index.** A package's `llms.txt` is its docs index. |
+| [Semantic Versioning](https://semver.org/), [SPDX](https://spdx.org/licenses/), [JSON Schema](https://json-schema.org/) | — | Stable | Versions, licenses and the schemas for `harnesspm.json` and the harnesspm extension. |
+
+## 11.2 What no standard covers yet
+
+| Need | Standard today | What harnesspm does |
+| --- | --- | --- |
+| Dependencies between plugins | Agent Plugins lists "dependency resolution" as a future consideration | `extends`, resolved through npm |
+| Trust, permissions, approvals | Agent Plugins lists "permission and approval UX" as a future consideration | `trust`, hash locks, allow rules only for a package's own scripts |
+| Always-on and file-scoped rules | None. Each agent has its own format | Markdown rules with `paths` and `description` frontmatter |
+| Hooks | Agent Plugins [PR #89](https://github.com/agentplugins/agent-plugins-spec/pull/89) proposes portable hooks for 1.1. It is open, and one reviewer objects to putting hook execution in the core spec | Hooks in the shape Claude Code and Codex share |
+| Sub-agents | None. Claude Code uses Markdown files, Codex uses TOML files | One Markdown file with portable `name`, `description` and body, plus per-agent keys, converted for each agent |
+| Scripts for agents | Agent Skills allows `scripts/` inside a skill, with no runner or permission model | Named scripts, one runner, generated permissions |
+| Overrides across packages | None | `exclude` and `replace` by unit ID, and `patch` by Markdown section |
+| Harnesses added on top of a repository | None | Added harnesses with two scopes, improved under their owner's rules |
+
+## 11.3 Proposing upstream
+
+harnesspm is a working example of what Agent Plugins lists as future work. Once harnesspm has real users, the project SHOULD propose:
+
+1. a `dependencies` (or `extends`) field, based on [03-resolution.md](03-resolution.md);
+2. a trust and approval model, based on [06-trust.md](06-trust.md);
+3. feedback on the hooks proposal, based on running the same hooks in two agents.
+
+## 11.4 Watch list
+
+| Item | Why it matters | Action when it changes |
+| --- | --- | --- |
+| Agent Plugins 1.1 | May add hooks and other fields | Read the new files. Keep the harnesspm format working during a migration period. |
+| Claude Code and Codex reading Agent Plugins directly | harnesspm could then write plugins instead of native files for some units | Re-check [04-outputs.md](04-outputs.md#48-why-native-files-and-not-plugins). |
+| A standard for rules | Would replace the harnesspm rule format | Map frontmatter, keep IDs. |
+| pnpm and the `skills` CLI linking skills from `node_modules` | Overlaps with harnesspm's skill outputs | Avoid double links. harnesspm reads `harness/skills/`, which they do not. |

package/docs/spec/12-dogfooding.md

@@ -0,0 +1,51 @@
+# 12. Dogfooding
+
+**In short**
+
+- This repository consumes its own harness and publishes it with the npm package.
+- Every project that installs harnesspm gets three skills that match the three flows: `harnesspm-export`, `harnesspm-import` and `harnesspm-improve`.
+- A format change in the spec MUST update these files in the same change.
+
+## 12.1 What this repository has
+
+| File | Role |
+| --- | --- |
+| [`AGENTS.md`](../../AGENTS.md) | How to work on this repository, including how to save changes. Ends with the harnesspm block that `npm run sync` writes. |
+| [`CLAUDE.md`](../../CLAUDE.md) | Imports `AGENTS.md` for Claude Code. |
+| [`harnesspm.json`](../../harnesspm.json) | This repository's project configuration. |
+| [`harness/`](../../harness/) | The harness that ships to everyone who installs `harnesspm`. Part of the project layer here, the dependency layer for users. |
+
+The proof of concept runs on these files: `npm run sync` writes the block and `harnesspm.lock.json`, and `npm run check` validates them. A change to the format MUST keep them working, or change them and this chapter together.
+
+## 12.2 What harnesspm's harness gives its users
+
+| Unit | Kind | Purpose |
+| --- | --- | --- |
+| `harnesspm:rules/generated-files` | Always-on rule | Outputs are generated. To change one, find its source with `harnesspm why`. |
+| `harnesspm:rules/harnesspm-config` | File-scoped rule | How to change `harnesspm.json`, `harnesspm.local.json` and harness files safely. |
+| `harnesspm-export` | Skill | Share a harness from a package: units, IDs, `extends`, checks, publishing. |
+| `harnesspm-import` | Skill | Set up harnesspm in a project, trust packages, add a harness on top. |
+| `harnesspm-improve` | Skill | Change any harness: find the owner, edit the source, save under the owner's rules. |
+| Docs index | Docs | This specification, at the installed version. |
+
+It is also a small reference example for package authors.
+
+## 12.3 Publishing
+
+```json
+{
+  "name": "harnesspm",
+  "files": ["dist", "schema", "harness", "docs/spec", "CHANGELOG.md"],
+  "scripts": { "prepack": "harnesspm check" }
+}
+```
+
+`harnesspm check` runs against the package itself, so a broken harness cannot be published.
+
+## 12.4 Checks
+
+| Check | When |
+| --- | --- |
+| `harnesspm check` | Every pull request and `prepack` |
+| `harnesspm sync --check` | Every pull request |
+| `harnesspm sync` on fixture projects, checked for Claude Code and Codex outputs | Every pull request |

package/docs/spec/13-open-questions.md

@@ -0,0 +1,85 @@
+# 13. Open questions
+
+**In short**
+
+- 13.1 to 13.8 are **decided**. They stay here as a record of why. A cloud probe settled 13.8.
+- 13.9 to 13.11 wait for the **proof of concept**. Each names the test or signal that settles it.
+- 13.12 lists options that were removed and may come back.
+
+## Decided
+
+### 13.1 Memory
+
+"Memory" here means everything a person wants agents to know that should live outside a project's repository: how they work, context, how their projects relate. It is the content of a person's own added harness ([07-added.md](07-added.md#71-what-goes-in-it)). Agents keep it current by improving that harness ([08-improving.md](08-improving.md)).
+
+Notes that Claude Code or Codex save by themselves (Claude Code auto memory, Codex memories) are part of each agent's own harness. harnesspm does not move or merge them.
+
+### 13.2 Partial edits of rules
+
+**Decision:** rules can be patched by Markdown section ([02-package-format.md](02-package-format.md#25-rules)). A patch replaces, adds or removes sections and keeps the rest. Upgrades that change a patched section are reported.
+
+Variables and slots were the other options. A patch covers the same cases, including "change a few words", when authors split rules into small sections. One mechanism is enough. Patches work on rules only. Extend them to skills if people start replacing whole skills to change one step.
+
+### 13.3 Extension namespace
+
+**Decision:** `dev.harnesspm`, based on the domain `harnesspm.dev`. Agent Plugins requires the namespace to be based on a domain the client controls.
+
+**Before the first public release:** register `harnesspm.dev`. It was not registered when checked through RDAP in November 2026. The namespace cannot change after release, because every published harness uses it as a folder name.
+
+### 13.4 Sub-agents for Codex
+
+**Decision:** sub-agents are written for both agents. Codex reads custom agents from `.codex/agents/*.toml` and `~/.codex/agents/` ([research/agent-capabilities.md](../research/agent-capabilities.md)). The format is in [02-package-format.md](02-package-format.md#26-sub-agents).
+
+### 13.5 Plugin output mode
+
+**Decision:** not in v1. Native files work in Claude Code cloud sessions, which do not install repository-declared plugins, and they show up in pull request review. Revisit if cloud sessions start installing such plugins, or as an option for local-only use. Codex Cloud may need one: see 13.12.
+
+
+### 13.6 CI without an install
+
+**Decision:** `harnesspm fetch` downloads only the harness packages in the lock and fills `node_modules/.harnesspm/pkgs/` ([04-outputs.md](04-outputs.md#42-stable-package-paths)). The lock records each package's tarball URL and integrity for this, from `package-lock.json`. Without them, as with pnpm and Yarn lockfiles, `fetch` downloads `<name>@<version>` from the registry and says the download is not checked.
+
+### 13.7 Team lock on rules (rejected)
+
+A team cannot mark a rule as one a person cannot exclude. Nothing could enforce it on a person's machine, and `harnesspm status` already shows the changes that added harnesses make.
+
+### 13.8 Committed Claude Code settings (settled)
+
+Not needed. A cloud probe in November 2026 showed that a `.claude/settings.local.json` written in the clone, also by a `SessionStart` hook, is read in the same session: its `env` applies and its hooks fire. Team hooks and permissions stay in that per-machine file.
+
+## Waiting for the proof of concept
+
+### 13.9 Upgrade report
+
+After an upgrade, the diff of the managed block and the lock shows what changed. **Signal:** reviewers find the raw diff hard to read. **Then:** add `harnesspm diff`.
+
+### 13.10 Structured project relations
+
+A person's notes describe how repositories relate, such as "UI Kit builds on Tasty". v1 keeps them as plain notes. **Signal:** a task in the proof of concept needs harnesspm itself to act on relations, such as finding local clones of related repositories.
+
+### 13.11 Agent behavior not confirmed yet
+
+Every ❓ in [research/agent-capabilities.md](../research/agent-capabilities.md) that v1 relies on must be tested, and the 🔍 rows behind [9.4](09-cloud.md#94-what-a-probe-confirmed) checked again. The Codex Cloud rows are out of scope (13.12). Settled by the proof of concept:
+
+- Yarn 4 runs `postinstall` but not `prepare`, so `init` uses `postinstall` in a private package ([research](../research/package-managers.md)).
+- Codex marks commands its model runs with `CODEX_CI=1` and `CODEX_TOOL_CALL_ID`, so rule 4 in [6.2](06-trust.md#62-trusting-a-package) covers Codex too.
+- Codex reads `developer_instructions` from a trusted project's `.codex/config.toml`.
+- A real agent improves a harness the intended way. A headless Claude Code run, asked to fix a dependency's rule for the team, used the `harnesspm-improve` skill, `why`, `new patch` and `sync`; asked to remember a preference for all projects, it wrote a rule into the person's added harness with `new rule --to` and saved it the way that harness's `AGENTS.md` said: a commit with the required prefix, pushed to `main` ([research](../research/agent-capabilities.md#claude-code)).
+- A headless Claude Code run uses what harnesspm writes: hooks, allow and deny rules, local-scope MCP servers, sub-agents, and skills linked from inside or outside the repository ([research](../research/agent-capabilities.md#claude-code)). Codex outputs are checked only against its source and docs, because no Codex CLI was available.
+
+## 13.12 Removed in review
+
+| Removed | Why | Comes back if |
+| --- | --- | --- |
+| Four layers, with a global personal layer below dependencies | Hard to explain. Three layers and two scopes say the same thing. | A real case needs a person's defaults that team rules override by ID. |
+| `include` and `self` in `harnesspm.json` | No scenario needed them. `exclude` covers narrowing. | A project needs an allowlist. |
+| Committed Claude Code settings and `.mcp.json` entries | Two rules for two agents. Now: commit only the block and the lock. | Per-machine settings stop working (13.8). |
+| `AGENTS.override.md` as a copy of `AGENTS.md` for Codex | Copies go stale. `developer_instructions` adds rules of added harnesses without a copy. | `developer_instructions` is not read from project config. |
+| `harnesspm personal save`, `push`, `pull`, `diff`, `status`, `extend` and a patch outbox | harnesspm does not need to wrap git. The owner's rules decide how changes are saved, and agents have their own git tools. | Agents turn out unable to follow owner rules reliably. |
+| A folder picked up automatically as an added harness | One more rule to learn. `add --local` does the same. | — |
+| A separate lock for added harnesses | Added harnesses follow their branch or range. | People need reproducible setups of added harnesses. |
+| Variables and slots in rules | Patches by section cover the same cases with one mechanism. | Patches copy most of a rule to change a word. |
+| Options without a scenario: `agents` in `harnesspm.json`, `sync --no-local`, the hook field `agents`, `docs` as an object with `exclude`, a package-root `skills/` folder | Each had a simpler equivalent or served no scenario. | A scenario needs one of them. |
+| A "personal layer" with `personal add`, `remove`, `update`, `sync --personal` and `new --personal` | A team's harness on top of a repository works the same way as a person's own. One general mechanism, "added harnesses", covers both, and `sync` itself handles repositories that do not use harnesspm. | — |
+| Approving a `"pin"` package unit by unit, by hash | A script's hash misses the code it imports. Approving a version is simpler and covers it. | A team needs to approve part of a release. |
+| Codex Cloud support | Its agent runs outside the task's VM. In a probe, no file written in the VM during a task reached it, and skills came only from cloud plugins ([research](../research/agent-capabilities.md#cloud)). A setup step that prepares files never reached a task in five tries. Codex on a person's computer stays supported. | Codex Cloud is shown to load files that the setup prepares, or harnesspm gains a Codex plugin output (13.5). |

package/docs/spec/README.md

@@ -0,0 +1,33 @@
+# harnesspm specification
+
+**Version:** 0.7 draft
+**Status:** Under discussion. Everything here can change before the first release.
+
+## Reading order
+
+| If you want to | Read |
+| --- | --- |
+| Understand harnesspm in five minutes | [1. Overview](01-overview.md) |
+| Share a harness from a package | [2. Package format](02-package-format.md), then [5. Executables](05-executables.md) if it ships tools |
+| Use harness in a project | [3. Resolution](03-resolution.md), [6. Trust and lock](06-trust.md) |
+| Keep your own workflow and context | [7. Added harnesses](07-added.md), [9. Cloud sessions](09-cloud.md) |
+| Let agents improve a harness | [8. Improving a harness](08-improving.md) |
+| Implement harnesspm | Everything, including [4. Outputs](04-outputs.md) and [10. CLI](10-cli.md) |
+
+Also: [11. Standards](11-standards.md), [12. Dogfooding](12-dogfooding.md), [13. Open questions](13-open-questions.md).
+
+Every chapter starts with **In short**: the few points an agent or a person needs to act on it.
+
+## Conformance language
+
+The words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT** and **MAY** have the meaning given in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). They appear only where a rule is meant to be strict.
+
+## Verification markers
+
+Statements about how an agent behaves are marked in [research/agent-capabilities.md](../research/agent-capabilities.md):
+
+| Marker | Meaning |
+| --- | --- |
+| ✅ | Documented by the agent's vendor |
+| 🔍 | Observed in a real session |
+| ❓ | Not confirmed. The proof of concept must test it |

package/harness/dev.harnesspm/rules/generated-files.md

@@ -0,0 +1,4 @@
+# Files generated by harnesspm
+
+- Files and links that harnesspm writes, such as `.claude/agents/`, `.codex/agents/`, `.claude/skills/` and `.agents/skills/`, are outputs like the managed block. Never edit them. Change the source that `npx harnesspm why <ID>` names, with the `harnesspm-improve` skill.
+- After changing `harnesspm.json` or a harness file, or after `npm install <pkg>` or `pnpm add`, run `npx harnesspm sync`.

package/harness/dev.harnesspm/rules/harnesspm-config.md

@@ -0,0 +1,11 @@
+---
+description: How to change harnesspm configuration and harness files safely
+paths: ["harnesspm.json", "harnesspm.local.json", "harness/**"]
+---
+
+# Changing harnesspm configuration
+
+- `harnesspm.json` and `harness/` belong to the team and are committed. `harnesspm.local.json` lists harnesses added for this repository only and is never committed.
+- To change a few sections of an upstream rule, create a patch with `npx harnesspm new patch <rule ID>`, keep only the sections you change, and edit them. To change a whole unit, use `replace`. To drop it, use `exclude`. Do not copy the whole upstream harness.
+- Executable units (scripts, hooks, MCP servers, allow permissions) run only for trusted packages. Do not add a package to `trust` without the user's agreement.
+- After a change, run `npx harnesspm sync`, and `npx harnesspm check <folder>` for a changed harness folder. Fix every reported problem.

package/harness/plugin.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "harnesspm",
+  "description": "How to work with harnesspm: generated files, configuration, harness authoring and added harnesses",
+  "homepage": "https://github.com/tenphi/harnesspm",
+  "repository": "https://github.com/tenphi/harnesspm",
+  "keywords": ["harnesspm", "harness", "agents"],
+  "extensions": {
+    "dev.harnesspm": {
+      "docs": "../docs/spec"
+    }
+  }
+}