jlpoole/reticiulum-specification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add playbook.md + AGENTS.md template for new Reticulum impls

Browse source 
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>
This commit is contained in:
Rob 2026-05-10 20:05:22 -04:00
commit c3795cb24c
5 changed files with 398 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

3
README.md
View file

@ -18,6 +18,9 @@ Each finding is grounded in upstream source citations (file + line) so it can be
## What's here
- [`SPEC.md`](SPEC.md) — the single combined spec document, organized by protocol layer
- [`playbook.md`](playbook.md) — how to troubleshoot interop bugs, design tests that don't lie to you, and navigate the protocol's code-as-spec parts. **Read this if you're starting any Reticulum implementation work, not just contributing to this repo.** Includes an incident registry of past wire-format bugs and their fixes.
- [`agent.md`](agent.md) — verification rules for adding to this repo (markers, tools/, test-vectors)
- [`templates/`](templates/) — drop-in `AGENTS.md` for new Reticulum implementation projects in any language. Copy into your project root, edit the marked sections, and the next agent or contributor lands on the right docs automatically.
- [`flows/`](flows/) — chronological end-to-end narratives (e.g. "send a message"), cross-referencing SPEC.md sections
- [`tools/`](tools/) — self-contained Python verifier scripts that test SPEC.md claims against upstream RNS / LXMF. Pinned via [`tools/requirements.txt`](tools/requirements.txt) to the upstream versions the scripts were last re-verified against
- [`test-vectors/`](test-vectors/) — known-good byte sequences each implementation should be able to round-trip (intent: grow into a compliance suite)