# AGENTS.md — rules for an agent using this kit

This repository ships a system prompt, not a program. An agent working with it must keep two things
true: the prompt stays structurally complete, and the two language versions never diverge.

Read `PROMPT.md` before anything else. Module identifiers (`M0`…`M13`) are stable addresses: they are
used in reviews, in `docs/` and in `tools/prompt_lint.py`.

## Verification

```bash
python tools/prompt_lint.py            # exit 0 = structural contracts hold
python tools/prompt_lint.py --json     # machine-readable findings
python tools/experience.py selftest    # the store rejects what it claims to reject
python tools/experience.py check       # schema, secrets, duplicates, staleness
python tools/install.py --runtime autoclaw2 --check   # installed files and registration
```

The linter fails on: a missing module, a module out of order, a missing `**Check:**` line, a
translation without its English twin, an unresolved `{{placeholder}}` outside a code fence, a broken
relative link, a secret-shaped literal, an absolute machine path, a dangling `M<number>` reference,
a version mismatch between the prompt header and the changelog, an incomplete M13, a gate with the
wrong number of tests, and a missing store, tool or skill section.

## Editing the prompt

1. Change `PROMPT.md`. Do not renumber modules: numbering is an interface.
2. Change `PROMPT.ru.md` in the same commit, keeping the same module set.
3. Bump `version` in both front matters and add a `CHANGELOG.md` entry.
4. Run the linter until it exits `0`.
5. If a rule needs a tool to be followable, ship the tool: M13 works because retrieval is one command,
   not because the prompt asks politely.

Never edit a `.ru.md` file alone. Never translate a module differently in substance: a translation
that softens an invariant is a defect, not a style choice.

## What the prompt itself requires of you

When you operate *under* this prompt, these hold:

| Rule | Source |
|---|---|
| Declare the subject before acting | M0, M1 |
| Write the Task Card and the Domain Card | M1, M2 |
| Keep a Context Ledger; no unsourced claim | M3 |
| Label every non-trivial statement | M4 |
| Smallest verifiable step, verify after acting | M5 |
| Sandbox irreversible actions; never print secrets | M6 |
| Answer in five sections, in the user's language | M7 |
| Report the twelve-item gate as one line | M8 |
| Search the store before planning; record after verifying | M13 |

## Traps when using this kit

| Trap | Symptom | Action |
|---|---|---|
| Editing the prompt to add a domain | the file grows by a page per project | fill a Domain Card instead (M2, M10) |
| Naming a tool in the prompt | the prompt stops working in another runtime | use a capability class (M6) |
| Treating retrieved experience as truth | an old recipe applied to a changed environment | run the six-question applicability check (M13) |
| Reporting a workspace or skill as installed without registration | files exist, the next session sees nothing | gate 12: name the registration step or the id |
| Describing specialization as a session persona | the user asked for a working environment and got a tone change | M10: the deliverable is a directory plus a handoff |
| Recording every task | the store becomes noise and retrieval stops finding anything | record only reusable, general, verified work |
| Deleting an outdated record | the audit trail vanishes and the wrong approach returns | deprecate with `superseded_by` |
| Reporting a gate line without running the gate | the answer looks auditable and is not | run M8, then print the line |
| Translating a module loosely | the two versions state different rules | translate in the same commit, same module set |
| Renumbering modules | every reference in docs and reviews breaks | keep `M0`…`M13` stable |
| Treating the linter as a quality proof | it checks structure, not judgement | use `docs/QA.md` for the content |

## Do not

- Add a domain to the prompt itself. Domains belong in a Domain Card and in `examples/`.
- Add tool names to the prompt. Capabilities are classes; the runtime maps them (M6).
- Present the gate line without running the gate. A reported pass that was not earned is the exact
  failure the kit exists to prevent.
- Publish a version whose `version` field and changelog disagree.

## Portability targets

| Runtime | How to load |
|---|---|
| AutoClaw2 | paste the body of `PROMPT.md` into the agent's system prompt; `AGENTS.md` covers repository work |
| HARNESS | same, via its project rules |
| SagaAI | same, via its system prompt field |
| Any other agent | paste the body; if a capability is missing, expect M6 to degrade explicitly |

## Layout

```text
PROMPT.md            the prompt, English (canonical)
PROMPT.ru.md         the prompt, Russian
AGENTS.md            this file
docs/                design, adaptation, QA, validation
examples/            three worked domains
skills/experience-reuse/  the M13 skill: templates, examples, policy
memory/              the experience store (records live here)
tools/prompt_lint.py the document's contracts
tools/experience.py  the store and its one-command retrieval
```

## License

MIT.