chore: Add AI review guidelines and shared agent skills

.agents/skills/spec-from-rippled/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: spec-from-rippled
+description: Update an XLS specification to match changes made in rippled. Use when asked to sync a spec with a rippled PR or commit, update an XLS from the implementation, reconcile a spec against rippled code, or check whether a spec still matches what was built.
+---
+
+# Update a spec from rippled changes
+
+Reconcile an `XLS-NNNN-slug/README.md` in this repo against a change in rippled, and propose the minimal spec edits that make the two agree.
+
+The implementation is the evidence. Every proposed edit cites a rippled `path:line`. Never describe behavior that is not in the code you read.
+
+## 1. Get the diff
+
+**From a PR or commit URL** (no checkout needed):
+
+```bash
+gh pr diff XRPLF/rippled <number>
+gh pr view XRPLF/rippled <number> --json title,body,files
+# or, for a commit:
+gh api repos/XRPLF/rippled/commits/<sha> --jq '.files[].filename'
+```
+
+**From a local checkout** (e.g. `~/Documents/rippled-all/develop`):
+
+```bash
+git -C <rippled> diff develop...<branch> --stat
+git -C <rippled> diff develop...<branch>
+```
+
+Ask which one to use if the request is ambiguous. For a large diff, work from `--stat` first and read individual files as needed.
+
+## 2. Identify the target spec
+
+In order of preference: the XLS number in the PR title or body; the amendment name added to `include/xrpl/protocol/detail/features.macro`, matched against this repo; or ask. Do not guess between two candidate specs.
+
+## 3. Map changed files to spec sections
+
+Read `references/rippled-map.md`.
+
+rippled's tree moves — transactors and invariants were recently relocated under `src/libxrpl/tx/`. Treat every path in that table as a hint and confirm it before relying on it:
+
+```bash
+git -C <rippled> ls-files '*transactors*' | head
+git -C <rippled> grep -n "TxName" -- include src | head -30
+```
+
+## 4. Read the spec, then propose edits
+
+For each mapped change:
+
+1. Read the current spec text for that section.
+2. Decide whether the spec is wrong, incomplete, or already correct. Say so for each — "already correct" is a useful result.
+3. Propose the smallest edit that fixes it, quoting the rippled `path:line` that justifies it.
+
+Do not restructure sections the diff does not touch. Do not infer a failure condition, a default value, or an invariant that you did not read in the code.
+
+## 5. Update the preamble
+
+- Bump `updated:` to today's date.
+- Add or refresh `implementation:` if this PR is the reference implementation.
+- Do not change `status:` — an Amendment or System XLS reaching `Final` is a separate decision, and needs the rippled PR merged first.
+
+## 6. Verify
+
+Run the `xls-template-conformity` skill on the edited spec, or at minimum:
+
+```bash
+python scripts/validate_xls_template.py XLS-NNNN-slug/README.md
+```
+
+## 7. Report what did not map
+
+List every changed rippled file you could not tie to a spec section, with a one-line reason. Some are genuinely spec-invisible (refactors, build files, logging); others mean the spec is missing a section. That call belongs to the author, so surface it rather than deciding it.

.agents/skills/spec-from-rippled/references/rippled-map.md

@@ -0,0 +1,55 @@
+# rippled artifact → XLS section map
+
+Section numbers refer to `templates/AMENDMENT_TEMPLATE.md`.
+
+Paths are **hints, not constants** — rippled reorganizes its tree periodically. Confirm each with `git -C <rippled> ls-files` or `git grep` before relying on it. The paths below were current as of the post-rearchitecture `develop` layout (transactors and invariants under `src/libxrpl/tx/`, RPC handlers under `src/xrpld/rpc/handlers/`).
+
+## Protocol definitions
+
+| rippled artifact                                                      | Spec section                        | What to extract                                                                |
+| --------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------ |
+| `include/xrpl/protocol/detail/features.macro`                         | preamble, §1 Abstract               | amendment name, `Supported::yes/no`, `VoteBehavior`                            |
+| `include/xrpl/protocol/detail/sfields.macro`                          | §2.2 / §3.1 Fields                  | field name, internal type (`UINT32`, `AMOUNT`, `ACCOUNT`, …), `SField` code    |
+| `include/xrpl/protocol/detail/ledger_entries.macro`                   | §2 Ledger Entry, §2.10 RPC Name     | entry type name and value, `snake_case` RPC name, required/optional field list |
+| `include/xrpl/protocol/detail/transactions.macro`                     | §3 Transaction                      | transaction type name and value, required/optional field list                  |
+| `include/xrpl/protocol/detail/permissions.macro`                      | §4 Permission                       | granular permission name and value                                             |
+| `include/xrpl/protocol/TxFlags.h`                                     | §3.2 Flags                          | `tf` values; confirm powers of two and no collision                            |
+| `include/xrpl/protocol/LedgerFormats.h`                               | §2.3 Flags                          | `lsf` values                                                                   |
+| `include/xrpl/protocol/Indexes.h`, `src/libxrpl/protocol/Indexes.cpp` | §2.1 Object Identifier              | keylet function, key space value, hashed inputs                                |
+| `include/xrpl/protocol/TER.h`                                         | §3.4 Failure Conditions             | `tem`/`tec`/`ter`/`tef`/`tel` codes, including newly added ones                |
+| `include/xrpl/protocol/ErrorCodes.h`                                  | §5.3 RPC Failure Conditions         | RPC error codes                                                                |
+| `include/xrpl/protocol/InnerObjectFormats.h`                          | §2.2 / §3.1 Fields                  | shape of any new inner object / array element                                  |
+| `include/xrpl/protocol/Fees.h`, `Protocol.h`                          | §2.5 Reserves, §3.3 Transaction Fee | reserve increments, non-standard fee logic                                     |
+
+## Transaction behavior
+
+| rippled artifact                                                              | Spec section                   | What to extract                                                                |
+| ----------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------ |
+| `src/libxrpl/tx/transactors/<TxName>.cpp` — `preflight`                       | §3.4.1 Data Verification       | every `tem` return: the malformed-input conditions, in order                   |
+| same — `preclaim`                                                             | §3.4.2 Protocol-Level Failures | every `tec`/`ter` return that needs ledger state                               |
+| same — `doApply`                                                              | §3.5 State Changes, §3.4.2     | entries created/modified/deleted, owner count changes, remaining `tec` returns |
+| same — `calculateBaseFee`                                                     | §3.3 Transaction Fee           | any non-standard fee                                                           |
+| same — `makeTxConsequences`                                                   | §3.5 State Changes             | consequences declared for queueing                                             |
+| `src/libxrpl/tx/invariants/InvariantCheck.cpp`, `include/xrpl/tx/invariants/` | §2.9 Invariants                | new or extended invariant checks                                               |
+| `src/libxrpl/tx/applySteps.cpp`                                               | §3 Transaction                 | transactor registration, privilege / delegation wiring                         |
+| account-deletion blocker lists (grep `deleteAccount`, `AccountDelete`)        | §2.6 Deletion                  | whether the new entry blocks account deletion                                  |
+| `adjustOwnerCount` call sites                                                 | §2.5 Reserves                  | whether the entry consumes an owner reserve                                    |
+
+## API surface
+
+| rippled artifact                                                         | Spec section                   | What to extract                                |
+| ------------------------------------------------------------------------ | ------------------------------ | ---------------------------------------------- |
+| `src/xrpld/rpc/handlers/<Name>.cpp`                                      | §5 RPC                         | request fields, response fields, error returns |
+| `include/xrpl/protocol/ApiVersion.h`, `API-CHANGELOG.md`                 | §5, §5 Backwards Compatibility | API version gating of any new field            |
+| transaction metadata emission (grep the new `sf` names in metadata code) | §3.6 Metadata Fields           | new metadata fields and when they appear       |
+
+## Tests
+
+| rippled artifact                  | Spec section | What to extract                                                                              |
+| --------------------------------- | ------------ | -------------------------------------------------------------------------------------------- |
+| `src/test/app/<Feature>_test.cpp` | §6 Test Plan | scenarios covered; useful for confirming failure conditions you inferred from the transactor |
+| `src/test/rpc/<Name>_test.cpp`    | §5.3, §6     | RPC error cases                                                                              |
+
+## Changes that are usually spec-invisible
+
+Build files, `CMakeLists.txt`, conan deps, logging, `#include` churn, formatting, unit-test refactors that add no new scenario, and internal helper renames that do not change a wire-visible name. Still list them in the "did not map" report rather than dropping them silently.

.agents/skills/xls-template-conformity/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: xls-template-conformity
+description: Check that an XLS specification conforms to the XRPL-Standards templates. Use when asked to check an XLS against the template, validate a spec's structure or preamble, review a draft's format before opening a PR, or review changes to an XLS-*/README.md file.
+---
+
+# XLS template conformity
+
+Check one or more `XLS-NNNN-slug/README.md` documents against `templates/XLS_TEMPLATE.md` and, for Amendment specs, `templates/AMENDMENT_TEMPLATE.md`.
+
+The templates are the source of truth. Read them at run time and compare — never work from a remembered copy of their contents.
+
+## 1. Resolve targets
+
+Use the paths given. If none were given, use the changed specs on this branch:
+
+```bash
+git diff --name-only master...HEAD -- 'XLS-*/README.md'
+```
+
+## 2. Run the validator first
+
+The repo already machine-checks preamble fields, required sections, Amendment subsection presence, and leftover template placeholders. Run it; do not reimplement it.
+
+```bash
+pip install -r scripts/requirements.txt
+python scripts/validate_xls_template.py XLS-NNNN-slug/README.md   # or --all
+```
+
+Report every error it prints verbatim, as `blocking`. Do not restate those findings in your own words or add a second comment about the same line.
+
+If the validator cannot run (no Python, no network — it does HEAD requests to xrpl.org), say so explicitly and continue with the manual passes.
+
+## 3. Compare against the templates
+
+Read `templates/XLS_TEMPLATE.md`. If the preamble says `category: Amendment`, also read `templates/AMENDMENT_TEMPLATE.md`.
+
+Check that the spec's section structure, ordering, numbering, and per-section content match what the template asks for. The validator only checks that required sections _exist_; you are checking that each one actually does its job, and that optional sections were omitted deliberately rather than forgotten.
+
+## 4. Apply the checks the template and validator cannot express
+
+Read `references/beyond-the-template.md` and work through it. It also lists the exemptions the validator already applies, so you do not re-flag them.
+
+## 5. Report
+
+One table, grouped by severity, most severe first:
+
+| Severity | Location                      | Finding | Suggested fix |
+| -------- | ----------------------------- | ------- | ------------- |
+| blocking | `XLS-NNNN-slug/README.md:120` | ...     | ...           |
+
+- `blocking` — validator errors, missing required content, an unsafe or unimplementable statement.
+- `should-fix` — real defect that does not block merge.
+- `nit` — wording or consistency.
+
+Never report anything CI already owns: whitespace, line endings, EOF newlines, markdown table alignment (prettier owns it), or the presence of fields and sections the validator checks.
+
+## 6. Offer to fix
+
+Offer to apply the mechanical fixes (renumbering, missing table columns, JSON/table mismatches). Leave design questions to the author — state the question, do not answer it for them.

.agents/skills/xls-template-conformity/references/beyond-the-template.md

@@ -0,0 +1,56 @@
+# Checks the templates and the validator cannot express
+
+`templates/XLS_TEMPLATE.md` and `templates/AMENDMENT_TEMPLATE.md` define the required structure, and `scripts/validate_xls_template.py` checks that structure mechanically. This file holds only what neither of them can check: agreement _between_ parts of a spec, and whether the prose actually says something.
+
+Nothing here duplicates a template section list. If a check below ever becomes expressible in the template or the validator, delete it from this file.
+
+## Cross-artifact agreement
+
+- **Example JSON vs. field table.** Every field marked required in the Fields table appears in the Example JSON. Every field in the Example JSON appears in the table. Values are of the declared JSON type. This applies to ledger entries (§2.2 vs §2.11), transactions (§3.1 vs §3.7), and RPCs (§5.1/§5.2 vs §5.4/§5.5).
+- **Field names.** Spelled identically in the table, the prose, the failure conditions, and the JSON. `MPTokenIssuanceID` in one place and `MPTIssuanceID` in another is a defect, not a style choice.
+- **Internal type vs. JSON type.** A `UINT64` rendered in JSON as a string, an `AMOUNT` as an object or string, an `ACCOUNT` as an r-address — the pair has to be coherent.
+- **Failure conditions vs. fields.** Every conditionally-required field has a failure condition covering its absence, and every failure condition names a field or state that exists in the spec.
+- **State changes vs. ledger entries.** Everything §3.5 says the transaction creates, modifies, or deletes is a ledger entry the spec defines, or an existing one it names.
+
+## Values that have to be checked against reality
+
+Do not assert any of these from memory. Check rippled or xrpl.org and cite what you checked.
+
+- **Flag values** are distinct powers of two, and do not collide with existing values for the same object or transaction type. Existing values: `include/xrpl/protocol/TxFlags.h` and `include/xrpl/protocol/LedgerFormats.h` in rippled.
+- **Error codes** referenced in Failure Conditions exist in `include/xrpl/protocol/TER.h` (transactions) or `include/xrpl/protocol/ErrorCodes.h` (RPCs). A spec that proposes a _new_ code has to say why the existing codes are insufficient — flag it if it does not.
+- **`tem` vs `tec`.** Data-verification failures (malformed input, checkable without ledger state) are `tem` and belong in §3.4.1. Failures that need ledger state are `tec`/`ter`/`tef`/`tel` and belong in §3.4.2. A `tem` that requires reading the ledger, or a `tec` for a purely malformed field, is misplaced.
+- **Key space value** (§2.1) is not already taken by another entry type — see `include/xrpl/protocol/Indexes.h` and any pending XLS in this repo.
+- **`requires:` preamble field** names XLS numbers that exist in this repo and that the spec genuinely depends on.
+- **Referenced XLS numbers** in prose exist. Relative links and internal anchors resolve.
+
+## Substance, not presence
+
+The validator confirms a section exists. These need a reader:
+
+- **Security Considerations** is specific to this proposal — threats, failure modes, what an adversary gains. A generic paragraph about "users should be careful" is a `blocking` finding: XLS-1 forbids `Final` without a sufficient one.
+- **Rationale** explains _why_ this design over the alternatives, and names the alternatives.
+- **Abstract** is readable standalone and matches what the spec actually does.
+- **Invariants** (§2.9) are stated over before/after state and are actually checkable, not restatements of the field table.
+- **Amendment activation.** Where behavior differs before and after activation, the spec says so. Silence about pre-activation behavior on a change to an existing transaction or entry is a `should-fix`.
+- **Backwards compatibility.** If the change breaks an existing client, the section exists and says how.
+- **RFC 2119.** If the spec declares RFC 2119 / RFC 8174, normative statements use MUST / SHOULD / MAY, not "will" or "should probably". If it does not declare them, do not demand them.
+
+## Naming
+
+- Transaction names follow `<LedgerEntryName><Verb>`, e.g. `VaultSet`, `VaultDelete`.
+- RPC method names are `snake_case`; the §2.10 RPC Name (for `account_objects` / `ledger_data` filtering) is `snake_case` too.
+- Ledger entry and field names are `PascalCase`.
+- `title` is at most 44 characters and carries no "XLS" prefix or number.
+- `description` is one short sentence, at most 140 characters.
+
+## Exemptions — do not flag these
+
+The validator already applies these, and so should you:
+
+- For a **ledger entry type already live on XRPL mainnet**, these subsections are optional: Object Identifier (2.1), Ownership (2.4), Reserves (2.5), Deletion (2.6), RPC Name (2.10). Only require them if the spec changes that aspect.
+- For a **transaction type already live on mainnet**, Transaction Fee (3.3) is optional.
+- A spec that predates the Amendment template and uses no `Ledger Entry:` / `Transaction:` / `RPC:` sections at all is treated as legacy — the validator skips Amendment structure checks. Do not demand a wholesale restructure of a legacy spec in a PR that only touches a few lines; say it is out of scope for the diff.
+
+## Owned by CI — never report
+
+Trailing whitespace, line endings, missing EOF newline, markdown or table formatting and alignment (prettier owns tables — never propose realigning one), missing preamble fields, missing required sections, missing Amendment subsections, leftover template placeholders. These all fail CI on their own.

.ai-review/instructions.md

@@ -0,0 +1 @@
+../.github/copilot-instructions.md

.claude/skills/spec-from-rippled

@@ -0,0 +1 @@
+../../.agents/skills/spec-from-rippled

.claude/skills/xls-template-conformity

@@ -0,0 +1 @@
+../../.agents/skills/xls-template-conformity