## What this is

AI coding agents (Claude Code, Cursor, and the like) will happily run `python train.py` for you — as a bare command, with no lineage captured. `roar init agents` installs a small amount of guidance that teaches an agent to reach for `roar run` instead, and to avoid the handful of things that make a lineage fail to reproduce.

It writes plain Markdown, not a plugin or a hook. Nothing about `roar`'s behavior changes; the guidance just puts the right instructions where agents already look for them.

```bash
roar init agents            # install both targets (below)
```

## What it installs

Two targets, either or both:

| Target | Path | Scope | Read by |
|---|---|---|---|
| **Claude skill** | `~/.claude/skills/roar/SKILL.md` | User-global (all your projects) | Claude Code / Claude agents |
| **`AGENTS.md` section** | `./AGENTS.md` | This project | Any agent that follows the [agents.md](https://agents.md) convention |

```bash
roar init agents --skill      # only the user-global Claude skill
roar init agents --project    # only this project's AGENTS.md
```

The `AGENTS.md` content is written inside managed markers:

```markdown
<!-- roar:begin (managed by `roar init agents` — edits inside this block will be overwritten) -->
<!-- roar version: 0.3.7 -->
## roar (provenance tracker)
...
<!-- roar:end -->
```

Everything outside the markers is yours and is left untouched. Everything inside is owned by `roar` and is replaced on the next `roar init agents`. The skill file is treated as fully managed — pass `--force` to overwrite it if you've hand-edited it.

## What the guidance says

The installed text is short and practical. It tells the agent to:

- Prefer `roar run <cmd>` over a bare command, and **not** to modify your code to do so — capture is transparent.
- Keep a clean git tree, because `roar run` refuses to execute with uncommitted or untracked files (there is no `--dirty` bypass).
- Avoid staging real inputs or wanted outputs under `/tmp`, which is filtered by default (see [Filtering](/docs/filtering)).
- Watch for **unsourced inputs** — the most common reason a lineage doesn't reproduce elsewhere — and inspect lineage with `roar show`, `roar dag`, and `roar log`.
- Treat `roar --help` as the source of truth for current command behavior.

## Keeping it current

The managed blocks are stamped with the `roar` version that wrote them. That makes staleness detectable, which matters in CI or a pre-commit hook:

```bash
roar init agents --check      # exit nonzero if the installed guidance is missing or out of date
roar init agents --dry-run    # print what would change, write nothing
```

Use `--check` to fail a build when someone upgrades `roar` but forgets to refresh the guidance; use `--dry-run` to preview a diff before committing it.

> **This is guidance, not enforcement.** `roar init agents` makes the right thing more likely by putting instructions in front of the agent — it does not force any command to run under `roar`. If you need a hard guarantee that a script only runs when traced, add `from roar import require` at the top of the script, which aborts execution when it isn't launched under `roar run`.