jlpoole/reticiulum-specification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
reticiulum-specification/templates/AGENTS.md
Rob c3795cb24c docs: add playbook.md + AGENTS.md template for new Reticulum impls 
Two new files plus pointers from README.md and agent.md.

playbook.md — companion to agent.md. Where agent.md governs what
evidence is admissible as you add to the spec, playbook.md covers
how to navigate the work itself: triage checklist for wire-format
bugs, common debugging anti-patterns (the stale-sibling-binary trap,
trusting LLM training data on Reticulum specifics, chasing
intermittent symptoms with retries), the three layers of test
trustworthiness, and how to work productively in a code-as-spec
domain. Includes an incident registry seeded with the §6.2/§6.6
signed_data signalling bug surfaced in mobile-app today plus older
HEADER_2, REQUEST path_hash, DEST_LINK, and stale-binary incidents.
Append-only — every future interop fix gets a registry entry per §8.

templates/AGENTS.md — drop-in boilerplate for new Reticulum
implementation projects in any language. Uppercase plural matches
the emerging AGENTS.md convention (Claude Code, Codex, Cursor,
Copilot Workspace). Sections: read-these-first reading list,
cardinal rules summary, project-specific FILL-IN placeholders,
contributing-findings-back obligation, attribution. Project-specific
bits use HTML comments so they're obvious to edit. §5 attribution
points back to this repo and is mandatory per CC BY 4.0.

templates/README.md — names the template, says where to put it,
restates the attribution expectation.

agent.md and README.md updated with pointers to the new files so
anyone reading the front door of the repo finds them.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-10 20:05:22 -04:00

8.8 KiB
Raw Blame History

`.

If you keep this file, you must keep the attribution to https://github.com/thatSFguy/reticulum-specifications intact. The spec repo is where the wire-format knowledge that makes your project possible lives; pointing back to it is how that knowledge stays maintained and how downstream agents find it.

Source: reticulum-specifications/templates/AGENTS.md License: CC BY 4.0 -->

AGENTS.md — guidance for contributors and AI agents

This project is a Reticulum implementation. The byte-level protocol it implements is specified in reticulum-specifications — that is the authoritative reference for every wire format, framing rule, and signature input touched by this codebase.

If you are an AI agent (Claude Code, Codex, Cursor, Copilot Workspace, etc.) working in this repo: read the four files linked below before reading any source in this project. Same for human contributors who haven't worked on a Reticulum stack before.

1. Read these first

Every Reticulum implementation builds on the same set of documents. Read in this order:

  1. reticulum-specifications/SPEC.md — the byte-level spec. Section-numbered. Cite it in commit messages and code comments by section (e.g. "SPEC §6.4.3"). When this project's behavior disagrees with the spec, the spec wins until proven otherwise.
  2. reticulum-specifications/playbook.md — how to troubleshoot interop bugs, design tests that don't lie to you, and navigate a protocol whose primary documentation is its source code. Includes an incident registry of past wire-format bugs — skim it; one of them is probably your bug. Includes the cardinal rules summarized in §2 below.
  3. reticulum-specifications/agent.md — verification discipline (markers, tools/, test-vectors) for contributions back to the spec repo. Relevant whenever you discover something the spec doesn't yet cover.
  4. This file — project-specific conventions for the codebase in front of you. The sections below either point at the project's README.md / build files or contain project-specific rules the implementer has chosen.

These four documents together are the working set. Loading any subset of them produces shallow work.

2. Cardinal rules

These apply to every Reticulum implementation regardless of language. See playbook.md for the long form; the short form is:

  1. Spec before code. Before debugging a wire-format bug, identify the spec section that governs the failing byte path and read it. Two minutes of spec-reading saves two hours of code-reading. Per playbook.md §2.1.
  2. Rebuild sibling-impl binaries before assuming your code is wrong. A pre-built artifact in a sibling repo's build/ directory may lag the source by months. Run go build / cargo build / make in the sibling repo first and confirm the version constant matches the source. Per playbook.md §2.2 — this trap costs hours every time it isn't caught.
  3. Self-round-trip tests are insufficient for wire formats. They pass when both sides agree on the wrong thing. Any code that produces or consumes wire bytes must also have at least one byte-equality test against upstream Python RNS (see reticulum-specifications/tools/). Per playbook.md §5.
  4. Symptom mapping: silent drops are not random. Common interop symptoms have specific spec-section root causes:
    • Multi-hop drops → SPEC §2.3 originator HEADER_2 conversion
    • Link establishes then silently drops DATA → SPEC §6.4.2 (LRRTT missing) or §6.4.3 (header rules)
    • Signature invalid → SPEC §4.2, §5.6.1, §6.2/§6.6 (signed_data construction)
    • Returns large message truncated → SPEC §10 Resource Read the registry in playbook.md §7 before designing a debugging plan from scratch.
  5. Write up what you learn. When you discover a wire-format detail the spec doesn't cover, open an issue or PR against reticulum-specifications with a source citation. The spec stays useful only because the people who debug interop bugs feed their findings back. Even an "I found this, marked ⚠️ UNVERIFIED, here's where in upstream RNS it lives" contribution is high-value.

3. This project

3.1 Build and test

3.2 Architecture

3.3 Where this project deviates from the spec

3.4 Project-specific conventions

4. Contributing findings back upstream

If you find a wire-format detail that isn't documented in reticulum-specifications/SPEC.md, you have an obligation to write it up. The spec repo's existence depends on it. Process:

  1. In your commit message for this project's code change, cite the SPEC section the fix relates to (or note "not yet in SPEC"). This makes future git blame archaeology productive.
  2. Open an issue or PR against reticulum-specifications with the finding. Even a one-paragraph description with a source citation (file + line in upstream RNS or in this project) is useful. Mark as ⚠️ UNVERIFIED per the spec repo's agent.md §1 if you haven't written a tools/verify_*.py for it yet.
  3. Append an incident registry entry to playbook.md §7 if your fix corresponds to a non-obvious wire-format trap — symptom, spec section, fix, one-sentence lesson. Future contributors will pattern-match symptoms against this list before they start debugging from scratch.

This isn't bureaucracy — it's the only mechanism that keeps the spec from rotting into the same opaque code-only state every alternative implementation had to reverse-engineer through. The hour you spend writing up a finding saves the next implementer a day.

5. Attribution

This file is a template from reticulum-specifications/templates/AGENTS.md, licensed CC BY 4.0.

The wire-format knowledge that makes this project possible lives at https://github.com/thatSFguy/reticulum-specifications. If you find this template useful, please:

  • Keep this attribution section intact in your project's AGENTS.md.
  • Link the spec repo prominently in your project's README.md.
  • Contribute findings back per §4.

Reticulum the protocol is by Mark Qvist (RNS and LXMF). The spec repo, this template, and the cross-implementation interop work are community-maintained on top of his protocol.