# Tools for agents

Coding agents look things up through the compiler rather than by browsing
folders. Before an agent writes a helper, it reads what already exists;
before it changes something shared, it asks what the change reaches.

- **The library catalogue** (`build/catalogue/libraries.md`): every
  library function with its signature, `///` description and callers, and
  every library constant with its type, value, description and readers
  ([Logic](/docs/logic.md)). An agent reads it before writing a helper or a
  constant.
- **The similar-helper check**: when a new helper looks like an existing
  one, `jadpo check` reports `library.similar_exists` and names it. Two
  constants of the same type holding the same value are
  `constant.similar_exists` ([Two constants holding one
  value](/docs/constants.md#two-constants-holding-one-value)). Both are errors
  you can decline, not warnings: make the fix, or write a
  `decline <rule>: "<reason>"` line above the declaration ([Declining a
  judgement call](/docs/declining-a-judgement-call.md)).
- **The failure catalogue** (`build/catalogue/failures.md`): every failure
  with its code, kind, status and client fields.
- **The schema and query reports** (`build/report/`): every table, column
  and index with the query that needed it, and each query call's store,
  row bound and query count.
- **`jadpo impact <name>`**: what a change to a declaration reaches.

```text
$ jadpo impact rounding.half_even
rounding.half_even   shared/libraries/rounding.jadpo:4
  called from   ordering (3 calls), payments (1 call)
  entry points  POST /orders, POST /payments/refunds, schedule nightly_invoices
  tests         ordering/actions/place_order.test.jadpo, payments/actions/refund.test.jadpo
  public        no
```

- **`jadpo domain rename`, `split` and `merge`**: move files and update
  every call. A new or renamed domain appears in the approval review
  ([Project layout and modules](/docs/project-layout-and-modules.md)).
- **The Jadpo agent skill** (`skills/jadpo/SKILL.md` in the docs bundle, and
  `https://jadpo.dev/.well-known/agent-skills/jadpo/SKILL.md`, which
  `https://jadpo.dev/llms.txt` links): tells an agent to read the primer, find
  the page for its task, run `jadpo check --json` and `jadpo test --json` after
  each connected change, and report a bug in Jadpo through you. It points at
  these pages for syntax. Three things are still to go in it:
  - Read the catalogues before adding code, and run `jadpo impact <name>`
    before changing or removing anything shared or public.
  - The routine for agents working in parallel workspaces: before
    pushing, merge `main`, run `jadpo check` (it builds nothing), fix any
    clash, then push. Private functions and types need only be unique
    within their domain, so two domains' helpers don't clash. A name
    another agent took in the same domain, or across the project, does.
  - The rule for a fixed value: if a deployment could ever need a
    different value it is a setting in `config.jadpo`, otherwise a
    `constant` ([A constant or a setting](/docs/constants.md#a-constant-or-a-setting)).
    Never both, so a `default:` never names a constant. A constant that
    turns out to need a value per deployment is moved with
    `jadpo config move <constant>`, not by hand.
- **Generated CI runs `jadpo check` first**, so a name clash or any other
  check error fails in seconds, before tests or a build. No page says yet
  what generates a project's CI (`jadpo new` creates none); whatever does
  must follow this.

Not built yet: the schema and query reports, `jadpo impact`, the
`jadpo domain` commands, those three parts of the agent skill and generated
CI. The catalogues, the similar-helper check and the rest of the skill are
built.

| Page | What it covers |
|---|---|
| [Everything as JSON](/docs/everything-as-json.md) | Every command on this page takes `--json` (Tools for agents), and each kind of evidence has one versioned schema: the fault event, the request timeline, `why` answers, the graph and the review report. |
| [What an agent runs](/docs/what-an-agent-runs.md) | Every command takes `--json`, and `jadpo help --json` describes them all (Tools for agents). |