---
language: "en"
title: "For AI agents"
canonical: "https://harnesspm.tenphi.me/agents/"
source: "docs/guide/agents.mdx"
version: "0.5.1"
index: true
---

# For AI agents

**In short**

* This part of the site is for you, an AI coding agent that a person asked to work with harnesspm. It has every step.
* In a project that already uses harnesspm, read what is installed first. It matches the installed version. This site describes the latest one.
* Never give yourself permissions. Trust and approval belong to the person.
* [llms.txt](https://harnesspm.tenphi.me/llms.txt) lists every page of this site with a Markdown copy.

## What is installed

A project that uses harnesspm already gives you this:

| Where                                                                     | What                                                                                                                 |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| The managed block in `AGENTS.md`                                          | Always-on rules, pointers to other rules, a docs index and scripts for each package. Every line ends with a unit ID. |
| The skills `harnesspm-import`, `harnesspm-export` and `harnesspm-improve` | The steps for using, sharing and improving a harness.                                                                |
| `node_modules/.harnesspm/docs/harnesspm/llms.txt`                         | The specification, at the installed version.                                                                         |

No block in `AGENTS.md` means the project does not use harnesspm yet:

* To use the harness of its dependencies, start with [Set up a project](/guides/setup/).
* To share a harness from a library, start with [Share a harness from your library](/guides/share/). It needs only the dev dependency. The skills are then files in `node_modules/@tenphi/harnesspm/harness/skills/`.

## Rules that always apply

1. **Never edit an output.** The managed block, `CLAUDE.local.md`, and the files and links in `.claude/`, `.codex/` and `.agents/skills/` are generated. Change the source that `npx harnesspm why <ID>` names.
2. **Sync after a change.** After you change `harnesspm.json` or a harness file, and after `npm install <pkg>` or `pnpm add <pkg>`, run `npx harnesspm sync`.
3. **Ask before you trust.** Do not add a package to `trust` in `harnesspm.json` without the person's agreement. Say what each pending tool does: `harness/plugin.json` of its package has each script's `description`, and `"allow": true` when it asks to run without a prompt.
4. **Do not grant permissions.** When you run harnesspm, new allow rules, hooks and MCP servers stay pending. Ask the person to run `npx harnesspm approve` in their own terminal. In a Claude Code cloud session, where the person has no terminal, ask them to run the install in the environment's setup script instead. Do not edit agent settings files to work around it.
5. **Save a change the owner's way.** Read `AGENTS.md` and `CONTRIBUTING.md` of the repository that owns the unit. When they say nothing, show the change, ask, and use a branch and a pull request.
6. **Keep added harnesses out of the project.** Their outputs are per machine. Never commit them.
7. **Report at the end.** Say what you wrote, what is pending, and what the person has to do.

Why rules 3 and 4 are strict: a harness can ship scripts, hooks and MCP servers. They run code on the person's machine, some of them without a prompt. [Trust and safety](/guides/trust/) has the full model.

## Pick the task

| The person asks to                                  | Read                                                                                                       |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Set up harnesspm, or use what the dependencies ship | [Set up a project](/guides/setup/), then [Use a package's harness](/guides/use/)                           |
| Turn on a package's tools                           | [Trust and safety](/guides/trust/)                                                                         |
| Fix or drop a rule that comes from a dependency     | [Change upstream units](/guides/change-upstream/)                                                          |
| Remember something, or improve a harness            | [Change upstream units](/guides/change-upstream/#improve-a-harness-with-an-agent)                          |
| Share a harness from a library                      | [Share a harness from your library](/guides/share/), with the [package format](/reference/package-format/) |
| Add their own or their team's harness               | [Add your own or your team's harness](/guides/add-your-own/)                                               |
| Work in a monorepo                                  | [Monorepos](/guides/monorepos/)                                                                            |
| Work in a Claude Code cloud session                 | [Cloud sessions](/guides/cloud/)                                                                           |
| See how agents use the harness                      | [Telemetry](/guides/telemetry/)                                                                            |
| Look up a command or a field                        | [CLI](/reference/cli/), [harnesspm.json](/reference/config/)                                               |

The [specification](https://github.com/tenphi/harnesspm/blob/main/docs/spec/README.md) has every rule behind these pages.
