@tenphi/harnesspm 0.0.0-snapshot.7984e7b

package/harness/skills/harnesspm-export/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: harnesspm-export
+description: Share agent rules, docs, skills or tools from a package through harnesspm, or change what a package already shares. Use when the user wants a library's users to get its agent guidance, asks to create or edit files under harness/, or wants to pass on the harness of packages it builds on.
+---
+
+# Sharing a harness from a package
+
+## 1. Start small
+
+If the package has no `harness/` folder, run `npx harnesspm new rule <name>`. It creates `harness/plugin.json` and one rule. That is a complete harness.
+
+## 2. Decide what goes in
+
+Share what the package's **users** need. Keep contributor-only instructions (release steps, internal structure) in the repository's own `AGENTS.md`.
+
+| Users need | Unit kind | Command |
+| --- | --- | --- |
+| A rule to always follow | Rule, no frontmatter | `npx harnesspm new rule <name>` |
+| A rule for some files only | Rule with `paths` frontmatter | same, then add `paths` |
+| Background to read when needed | Docs, or a rule with `description` only | set `docs` in `plugin.json` |
+| A multi-step workflow | Skill, named `<plugin name>-<name>` | `npx harnesspm new skill <name>` |
+| A specialist the agent can delegate to | Sub-agent, written for Claude Code and Codex | `npx harnesspm new agent <name>` |
+| A tool to run | Script | `npx harnesspm new script <name>` |
+| Something that runs on an agent event | Hook that runs a script | `npx harnesspm new hook <name>` |
+
+Write each skill's `description` as what it does, then "Use when …" with the situations and words people use. Agents pick skills by that text, but not every time: when a skill must run in a situation, also add an always-on rule that names it.
+
+Keep always-on rules short. One topic per file, split into small `##` sections, so users can patch one section, replace one file or drop it.
+
+## 3. Pass on upstream harness
+
+- List the packages it builds on in `extends` in `plugin.json`.
+- To change one of their rules for all users, prefer a patch: `npx harnesspm new patch <rule ID>` registers it in `harness/plugin.json`. Keep and edit only the sections that change. Use `replace` for a whole unit and `exclude` to drop one. Find IDs in the `AGENTS.md` block or with `npx harnesspm why <ID>`.
+
+## 4. Check and publish
+
+1. Run `npx harnesspm check`. Fix every problem.
+2. If `package.json` has a `files` field, make sure it lists `harness` and the docs folder, if used.
+3. Add `"prepack": "harnesspm check"` to the `package.json` scripts.

package/harness/skills/harnesspm-import/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: harnesspm-import
+description: Set up harnesspm in a project, take agent harness from its dependencies, trust packages that ship tools, or add a harness on top, such as the user's team's or their own. Use when the user asks to use a package's agent rules or tools, to set up harnesspm, or to add a harness in this project or session.
+---
+
+# Using harness in a project
+
+## 1. Set up the project (once)
+
+```bash
+npm i -D @tenphi/harnesspm
+npx harnesspm init
+```
+
+`init` adds `harnesspm sync` to the `postinstall` script of a private package, or to `prepare` otherwise, so every full install updates the agent files. After `npm install <pkg>` or `pnpm add`, run `npx harnesspm sync` yourself. Commit `harnesspm.json`, `harnesspm.lock.json` and the `AGENTS.md` block.
+
+## 2. Check what arrived
+
+Run `npx harnesspm status`. It lists the packages, pending tools and the always-on size.
+
+- **Pending tools** come from packages the project does not trust yet. Ask the user before adding a package to `trust` in `harnesspm.json`.
+- **You cannot grant permissions.** When you run harnesspm, new allow rules, hooks and MCP servers stay pending. Ask the user to run `npx harnesspm approve` in their own terminal. Do not edit agent settings files to work around it.
+- **One upstream rule does not fit** the project: run `npx harnesspm new patch <rule ID>` and edit only the sections that differ. Use a `replace` or `exclude` entry in `harnesspm.json` to change or drop a whole unit.
+- **A job that does not install dependencies**, such as a review bot, runs `npx -y @tenphi/harnesspm fetch` first.
+
+## 3. Add a harness on top
+
+```bash
+npx -y @tenphi/harnesspm add <source>          # every repository on this machine
+npx -y @tenphi/harnesspm add <source> --local  # this repository only
+```
+
+The source is `github:<owner>/<repo>`, `git:<url>`, `npm:<package>` or a folder path. Add a team's harness before the user's own, so the user's wins. The command prints the added rules. Follow them from now on in this session.
+
+Outputs of added harnesses never go into the project's repository. Do not commit them.

package/harness/skills/harnesspm-improve/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: harnesspm-improve
+description: Change or add a rule, note, skill, script or other unit in any harnesspm harness (a dependency's, the project's, or one the user added, such as their team's or their own) and save the change the way its owner wants. Use when a rule is wrong or missing, when the user says "remember this", or asks to improve their harness.
+---
+
+# Improving a harness
+
+## 1. Find the owner
+
+For an existing unit, run `npx harnesspm why <ID>`. The ID is at the end of each line in the `AGENTS.md` block. It tells you the owner, the source file and whether you can edit it.
+
+For something new, choose the owner:
+
+| The change is about | Owner | Create with |
+| --- | --- | --- |
+| How a package should be used, for all its users | The package (dependency) | — propose upstream, see 3 |
+| This project, for the whole team | The project | `npx harnesspm new <kind> <name>` |
+| How the user or their team works, everywhere | The added harness (see `npx harnesspm status`) | `npx harnesspm new <kind> <name> --to <plugin>` |
+| This project, only for the user or their team | The added harness, project entry | `npx harnesspm new <kind> <name> --to <plugin> --entry` |
+
+Ask the user when it is not clear. Never put private data from this project into an added harness without the user's agreement.
+
+## 2. Edit the source
+
+- Edit the source file that `why` names, never an output (the `AGENTS.md` block, `CLAUDE.local.md`, `.codex/`).
+- Run `npx harnesspm sync`, then `npx harnesspm check <folder>` for the harness folder you changed.
+
+## 3. Save the change the owner's way
+
+1. Read `AGENTS.md` and `CONTRIBUTING.md` at the root of the owner's repository. Follow them.
+2. If they say nothing about saving:
+   1. Show the user the change and ask before going on.
+   2. Create a branch `harnesspm/<topic>` and commit with a message that says what and why.
+   3. Push it and open a pull request or merge request with the tools you have.
+   4. If a step is not possible, stop and tell the user what is done and what is left. In a cloud session, show the full change.
+3. Never push to the default branch unless the owner's rules allow it.
+
+For a dependency: change it now with a patch (`npx harnesspm new patch <rule ID>`, add `--to <plugin>` to keep it in an added harness), or a `replace` or `exclude`. Then offer to open an issue or pull request at the package's repository.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@tenphi/harnesspm",
+  "version": "0.0.0-snapshot.7984e7b",
+  "description": "The harness package manager: share agent rules, docs, skills and tools through npm packages",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "harnesspm": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "harness",
+    "docs/spec",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tenphi/harnesspm.git"
+  },
+  "homepage": "https://github.com/tenphi/harnesspm#readme",
+  "keywords": [
+    "agents",
+    "harness",
+    "ai",
+    "claude-code",
+    "codex",
+    "agents-md",
+    "skills",
+    "mcp",
+    "agent-plugins"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test \"test/**/*.test.ts\"",
+    "sync": "node src/cli.ts sync",
+    "check": "node src/cli.ts check && node src/cli.ts sync --check",
+    "harnesspm": "node src/cli.ts",
+    "prepack": "npm run build && node dist/cli.js check",
+    "changeset": "changeset",
+    "version-packages": "changeset version && npm install --package-lock-only --ignore-scripts",
+    "release": "changeset publish"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^1.0.1",
+    "@changesets/cli": "^3.0.3",
+    "@types/node": "^22.20.5",
+    "typescript": "^7.0.2"
+  }
+}

package/schema/harnesspm.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/@tenphi/harnesspm/schema/harnesspm.schema.json",
+  "title": "harnesspm.json",
+  "description": "Project configuration for harnesspm, the harness package manager. Every field is optional.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "exclude": {
+      "description": "Packages or unit IDs to drop, such as \"@tenphi/glaze\" or \"tasty:rules/legacy\".",
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "replace": {
+      "description": "Unit ID → path of a project file that takes its place.",
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "patch": {
+      "description": "Rule ID → path of a patch that changes some of its sections.",
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "trust": {
+      "description": "Packages whose executable units may run: true follows upgrades, \"pin\" needs an approval for each new version.",
+      "type": "object",
+      "additionalProperties": { "enum": [true, "pin"] }
+    }
+  }
+}