Add AGENTS.md for AI coding agent guidance#357
Conversation
| - **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 was a problem hiding this comment.
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.
| - **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 was a problem hiding this comment.
There is also used in: NUT-NN notation which is widely used (04, 05, 07, 09, 10, 21). Don't we need this?
- Trim CTF.md from 706 to 533 lines, CTF-split-merge.md from 525 to 218 lines - Move supplementary material (Q&A, rationale, witness comparison, complete example) to suppl/ - Align with PR cashubtc#357 conventions: http code blocks, curl examples, Alice/Bob framing - Keep normative content intact; no behavioral changes
|
Nice, this is a clean AGENTS.md. For context I just opened the same for Two thoughts from the implementer side: 1. Adding to the implementation support matrix. The README's Optional table is populated by named implementations (
2. +1 to @joemphilips on type annotations. The existing NUTs loosely use Happy to open a follow-up PR for either. |
3 participants
No description provided.