Add AGENTS.md for AI coding agent guidance #357

2026-03-31T07:24:35Z

ye0man commented

2026-03-31 07:24:35 +00:00

(Migrated from github.com)

No description provided.

❤️ 1

joemphilips (Migrated from github.com) reviewed

2026-04-03 08:15:54 +00:00

AGENTS.md

					
				@ -0,0 +32,4 @@

				- **Filename**: Zero-padded two-digit number matching the NUT number (e.g. `30.md` for NUT-30).

				- **Title**: `# NUT-NN: Title` as the first line.

				- **Status badge**: `` `mandatory` `` or `` `optional` `` on its own line after the title.

				- **Dependencies** (if any): `` `depends on: NUT-NN` `` and/or `` `uses: NUT-NN` `` on separate lines.

There is also used in: NUT-NN notation which is widely used (04, 05, 07, 09, 10, 21). Don't we need this?

There is also `used in: NUT-NN` notation which is widely used (04, 05, 07, 09, 10, 21). Don't we need this?

AGENTS.md

					
				@ -0,0 +36,4 @@

				- **Horizontal rule**: `---` separating the header block from the body.

				- **RFC 2119 language**: Use `MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, `MAY`, and `CAN` (capitalized) per RFC 2119 when specifying protocol requirements.

				- **API endpoints**: All REST endpoints use the `/v1/` prefix. Show the HTTP method and URL in a ` ```http ` code block, followed by request/response bodies in ` ```json ` blocks.

				- **Type annotations in JSON**: Use angle-bracket placeholders for types: `<str>`, `<int>`, `<bool>`, `<Array[Type]>`, `<optional>`.

There are also other types used in the existing documents. Here's the list

Primitives: <str>, <int>, <bool>, <hex_str>, <bigint>
Nullable: <type|null> (e.g. <str|null>, <int|null>, <Object|null>)
Enums: <str_enum[NAME]> (e.g. <str_enum[STATE]>, <str_enum[UNIT]>)
Arrays: <Array[Type]> (e.g. <Array[Proof]>, <Array[BlindSignature]>)
Named objects: <Proof>, <BlindedMessage>, <BlindSignature>, etc.
Domain-specific: <keyset_id_hex_str>, <public_key_str>, <amount_int>
Optional marker: <optional> (marks a field as optional)

I think just saying "Use angle brackets to annotate type in the JSON document instead of an actual value" is fine. You don't need to specify possible types here. Since it seems like types are loosely deifned/used in the existing documents.

There are also other types used in the existing documents. Here's the list - Primitives: `<str>`, `<int>`, `<bool>`, `<hex_str>`, `<bigint>` - Nullable: `<type|null>` (e.g. `<str|null>`, `<int|null>`, `<Object|null>`) - Enums: `<str_enum[NAME]>` (e.g. `<str_enum[STATE]>`, `<str_enum[UNIT]>`) - Arrays: `<Array[Type]>` (e.g. `<Array[Proof]>`, `<Array[BlindSignature]>`) - Named objects: `<Proof>`, `<BlindedMessage>`, `<BlindSignature>`, etc. - Domain-specific: `<keyset_id_hex_str>`, `<public_key_str>`, `<amount_int>` - Optional marker: `<optional>` (marks a field as optional) I think just saying "Use angle brackets to annotate type in the JSON document instead of an actual value" is fine. You don't need to specify possible types here. Since it seems like types are loosely deifned/used in the existing documents.

realmeylisdev commented

2026-04-24 14:30:38 +00:00

(Migrated from github.com)

Nice, this is a clean AGENTS.md. For context I just opened the same for cdk-flutter (#15), so this was front-of-mind.

Two thoughts from the implementer side:

1. Adding to the implementation support matrix. The README's Optional table is populated by named implementations ([Nutshell], [cdk], etc.), not ✓/✗. The AGENTS.md says new NUTs start with - until implementations adopt — but it doesn't cover the reverse workflow: "I've implemented NUT-N, I'd like to add my wallet/mint to the matrix." Useful to document:

Whether self-claim is the norm (I'd assume yes, since the matrix is curated by implementers themselves).
What "implementing" means for a given NUT — fully (both directions), test-vector-conformant, happy path, or partial with notes? NUT-13 currently shows wallets only and - for mints — the asymmetry is informative, which suggests partial claims are OK but it's not spelled out.
Where the implementation links at the bottom of README are defined and how to add a new one.

2. +1 to @joemphilips on type annotations. The existing NUTs loosely use <hex_str>, <type|null>, <str_enum[...]>, domain-specific like <keyset_id_hex_str>. A single "use `` placeholders for types" rule — without enumerating kinds — keeps the guidance honest and avoids drift as future NUT authors invent appropriate placeholders.

Happy to open a follow-up PR for either.

Nice, this is a clean AGENTS.md. For context I just opened the same for `cdk-flutter` ([#15](https://github.com/cashubtc/cdk-flutter/pull/15)), so this was front-of-mind. Two thoughts from the implementer side: **1. Adding to the implementation support matrix.** The README's Optional table is populated by named implementations (`[Nutshell]`, `[cdk]`, etc.), not ✓/✗. The AGENTS.md says new NUTs start with `-` until implementations adopt — but it doesn't cover the reverse workflow: "I've implemented NUT-N, I'd like to add my wallet/mint to the matrix." Useful to document: - Whether self-claim is the norm (I'd assume yes, since the matrix is curated by implementers themselves). - What "implementing" means for a given NUT — fully (both directions), test-vector-conformant, happy path, or partial with notes? NUT-13 currently shows wallets only and `-` for mints — the asymmetry is informative, which suggests partial claims are OK but it's not spelled out. - Where the implementation links at the bottom of README are defined and how to add a new one. **2. +1 to @joemphilips on type annotations.** The existing NUTs loosely use `<hex_str>`, `<type|null>`, `<str_enum[...]>`, domain-specific like `<keyset_id_hex_str>`. A single "use \`<angle-bracket>\` placeholders for types" rule — without enumerating kinds — keeps the guidance honest and avoids drift as future NUT authors invent appropriate placeholders. Happy to open a follow-up PR for either.

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin ye0man/add-agents-md:ye0man/add-agents-md

git switch ye0man/add-agents-md

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main

git merge --no-ff ye0man/add-agents-md

git switch ye0man/add-agents-md

git rebase main

git switch main

git merge --ff-only ye0man/add-agents-md

git switch ye0man/add-agents-md

git rebase main

git switch main

git merge --no-ff ye0man/add-agents-md

git switch main

git merge --squash ye0man/add-agents-md