Add your own or your team's harness
In short
npx -y @tenphi/harnesspm add <source>adds a harness on top of the repository’s, on your machine only. It is never committed.- With user scope, it applies in every repository on the machine. With
--local, in one repository. npx harnesspm doctorchecks that your per-machine files stay out of git.
An added harness is an ordinary harness, with a plugin.json and units, in a git repository, a folder or an npm package. A team’s harness and a person’s own harness work the same way. Only their owners differ.
| Content | Unit kind | Example |
|---|---|---|
| How you or your team work | Always-on rule | Commit style, review habits, preferred tools |
| Context the agent reads when needed | Docs (notes) | Which repositories exist and how they relate |
| Repeated workflows | Skills | Releasing a package, a weekly update |
| Tools | Scripts, hooks, MCP servers | A local preview of linked repositories |
| Changes for one repository | Project entry | A local staging address, a replaced team rule |
To give a harness to everyone who works on a repository, make it a dependency instead: a harness-only package in devDependencies.
A harness of your own starts as a folder with git. new writes its manifest and first unit:
mkdir -p ~/dev/my-harness && cd ~/dev/my-harness && git init
npx -y @tenphi/harnesspm new rule workflownewcreatesharness/plugin.json, with the folder’s name as the plugin name, andharness/dev.harnesspm/rules/workflow.md, an always-on rule. Ignore theinitit suggests: your harness is not a project.- Write the rule, then run
npx -y @tenphi/harnesspm check, and commit. - A folder works on this machine. To use the harness on other machines and in cloud sessions, push it to a repository of yours and add it from there.
- The person adds it, as below. An agent that starts a harness for someone stops before
add.
npx -y @tenphi/harnesspm add github:<owner>/<repo>| Source | Example | Where it lives |
|---|---|---|
| Git repository | github:alex/harness, git:https://git.example.com/team/harness.git |
A working copy in ~/.harnesspm/harnesses/ |
| Folder | ~/dev/alex-harness |
In place |
| npm package | npm:@alex/harness |
A cache in ~/.harnesspm/cache/, read-only |
add prints the added always-on rules, so an agent that runs it follows them at once:
$ npx -y @tenphi/harnesspm add ~/dev/alex-harness
Added alex (/home/alex/dev/alex-harness) with user scope
Rules from /home/alex/dev/alex-harness, to follow from now on in this session:
### Workflow (alex:rules/workflow)
- Use Conventional Commits.
- Run the tests before you open a pull request.add also installs a SessionStart hook for each agent. It runs npx -y @tenphi/harnesspm sync when a session starts, so your harness applies in every repository, also in ones that do not use harnesspm. Pass --no-hook to skip it.
| Scope | Command | Recorded in | Applies |
|---|---|---|---|
| User | add <source> |
~/.harnesspm/config.json |
In every repository on this machine |
| Local | add <source> --local |
harnesspm.local.json, excluded from git |
In this repository |
You can add several harnesses, for example your team’s, then your own. They apply in the order you added them: user scope first, then local scope. When two of them ship a skill with the same name, the later one wins.
An added harness can hold units for one repository. projects in its plugin.json maps a git remote to a folder with the same layout as harness/:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "alex",
"extensions": {
"dev.harnesspm": {
"docs": "./notes",
"projects": {
"github.com/acme/app": "./projects/app"
}
}
}
}The entry applies wherever the repository’s origin remote matches, also in a fresh clone in a cloud session. To write a new unit into it, run npx harnesspm new rule <name> --to alex --entry.
- Units of an added harness never go into a tracked file. They go into
CLAUDE.local.md,.claude/settings.local.json,.codex/and your user-level agent folders. - harnesspm lists per-machine files in
.git/info/exclude, which belongs to your clone and is never committed. It never edits.gitignore. - CI and
sync --checkignore added harnesses. npx harnesspm statuslists every change an added harness makes to the repository’s units.
doctor checks that a repository is ready for a harness of your own, and that no per-machine file can reach a commit:
$ npx harnesspm doctor
🔒 Local files
✅ 12 per-machine files: ignored by git and not tracked
➕ Harnesses of your own
✅ .git/info/exclude can be written, so harnesspm keeps per-machine files out of git
✅ Added: alex (/home/alex/dev/alex-harness, user)
📦 Outputs
✅ Committed outputs are up to date
✅ 14 per-machine outputs in place
✅ Ready. Nothing to fix.When a file is tracked or not ignored, doctor fails and names the fix, such as git rm --cached CLAUDE.local.md. It never changes anything itself.
- Ask your agent to “remember” something, and it can write a rule into your harness with
npx harnesspm new rule <name> --to <plugin>. It saves the change the way your harness’sAGENTS.mdsays. See Change upstream units. npx harnesspm updatefetches new versions of your added harnesses. It skips a working copy with uncommitted changes or unpushed commits, and says so.npx harnesspm remove <source>removes a harness and its outputs.
- Added harnesses in the specification: the full rules.
- Cloud sessions: the same harness in Claude Code cloud sessions.