// Top-level skill for Claude Code sessions across any peat-* repo. Read first, then read the per-repo SKILL.md.
| name | peat-ecosystem |
| description | Top-level skill for Claude Code sessions across any peat-* repo. Read first, then read the per-repo SKILL.md. |
| when_to_use | Any session touching files in a defenseunicorns/peat-* repository, or coordinating changes across more than one peat repo. |
| verifies_with | Each affected repo's CI green, no architecture invariant violated, PR references its issue with the required sections. |
Peat is an interoperability-first mesh registry sync platform built for heterogeneous autonomous systems in defense and edge environments. Its core value proposition is interoperability that enables scale — Peat connects systems that don't speak the same language across transport and protocol boundaries. Peat is developed under the Defense Unicorns GitHub org: https://github.com/defenseunicorns
peat-* repo or the top-level peat crateAfter reading this file, read the relevant per-repo SKILL.md from the router below. Per-repo skills are authored against peat/SKILL_TEMPLATE.md.
Read only what's relevant to the current task. Do not preload every per-repo skill.
The ecosystem comprises one Rust workspace repo (peat) plus several sibling repos. Internal workspace subcrates do not have separate per-repo skills — they share this file.
Sibling repos (each its own git repo, each with its own per-repo skill):
| Repo | Purpose | Skill |
|---|---|---|
| peat | Rust workspace. Hosts the ecosystem skill (this file) and the per-repo skill for the workspace. Active. | This file |
| peat-mesh | Mesh networking; pluggable transport, peer discovery, topology, routing, optional Automerge/Iroh sync, optional HTTP/WS broker. Top-tier active. | peat-mesh/SKILL.md |
| peat-btle | BLE transport bridge. M5Stack/ESP32 integration. | peat-btle/SKILL.md |
| peat-lite | Lightweight implementation for constrained environments. | peat-lite/SKILL.md |
| peat-atak-plugin | One consumer-plugin integration (Android/Kotlin). Pure Kotlin/Gradle — no Rust here. Consumes pre-built JNI/UniFFI bindings from peat/peat-ffi. Repo name is historical; this repo treats it as a generic consumer surface. | peat-atak-plugin/SKILL.md |
| peat-sim | ContainerLab-based network simulation harness. Not on the production path. | peat-sim/SKILL.md |
Workspace subcrates (members of the peat repo, share this skill):
| Subcrate | Role |
|---|---|
peat | Top-level crate; eventual home for shared types and traits. Currently a placeholder (see "peat repo-specific skill" below). |
peat-schema | Schema definitions. |
peat-protocol | Protocol logic (Translator, ChangeEvent, etc.). |
peat-transport | Transport abstractions used by the workspace. |
peat-persistence | Persistence layer. |
peat-ffi | FFI bindings for Kotlin/Swift (UniFFI 0.28, proc-macro mode) + direct jni 0.21 for Android. The only routinely-unsafe Rust in the ecosystem. |
Status unknown — confirm with Kit before authoring skills. The following were listed in earlier drafts but aren't currently visible from this checkout: peat-registry, peat-node, peat-gateway, peat-rmw, peat-mavlink. They may be planned, renamed, deprecated, or in private repos. Per the active-repos record, only peat and peat-mesh are currently top-tier active.
These rules apply in every repo. Violating one without explicit user approval is out of scope, full stop.
Language. Rust everywhere except Kotlin in consumer plugins (currently peat-atak-plugin). No new language dependencies. No Python. No shell scripts for anything that belongs in Rust.
FIPS-approved cryptographic primitives only. Every algorithm used anywhere in the peat ecosystem must be on the FIPS 140-3 approved list. AEAD: AES-GCM (not ChaCha20-Poly1305). Signatures: Ed25519 (FIPS 186-5) or ECDSA-P256/P384. Key agreement: ECDH-P256/P384 (X25519 only with explicit review). KDF: HKDF-SHA-2. MAC: HMAC-SHA-2. TLS/QUIC must run under a FIPS-mode crypto provider (e.g. aws-lc-rs for rustls; the default ring is not FIPS-validated). MLS suites must be FIPS-aligned (e.g. MLS_128_DHKEMP256_AES128GCM_SHA256_P256). Existing ChaCha20-Poly1305 references in ADR-006/044/048/049 + spec docs are tracked for amendment; do not propagate them. Canonical reference: ADR-060 §5 "Cryptographic primitives (FIPS posture)" + CLAUDE.md § "Hard rule: FIPS-approved cryptographic primitives only".
No consumer-specific references in peat. peat is the generic mesh substrate; consumers (mobile-app plugins, wearable firmware, CLI tools, server bridges) live in sibling repos. Code, comments, examples, READMEs, operational docs, JNI symbol names, package paths, and test fixtures in this repo MUST NOT name a specific consumer (ATAK, WinTAK, iTAK, WearTAK, etc.) or vendor-derived identifiers. Use "consumer", "consumer plugin", "CoT consumer", "mobile-app plugin", "wearable", "CLI tool", or "server bridge". Protocol-name appearances (e.g. CoT, TAK Server wire protocol) are allowed where the protocol itself is structurally load-bearing; consumer-name appearances are not. The only exception is ADRs in docs/adr/ citing real-world use cases that motivated a design decision. See CLAUDE.md § "Hard rule: no consumer-specific references in peat" for the full rule + rationale. Verification gate (below) includes a grep check for ATAK / vendor names in new diffs.
Dependency flow. peat is the dependency anchor. Common types, traits, error handling flow down from peat. Repos depend on peat, never on each other directly. Circular dependencies are rejected.
Transport agnosticism. Peat protocol logic must not assume a transport. BLE, mesh, IP, serial are all interchangeable. Transport-specific code stays in transport repos (peat-btle, peat-mesh) or the peat-transport workspace subcrate — never in core / protocol / persistence layers or non-transport sibling repos.
Interoperability first. Every feature decision answers: does this make Peat more or less interoperable with external systems? Peat must never require a counterpart to run Peat software to integrate.
Unsafe Rust. Requires explicit justification in a code comment. The FFI boundary in peat-ffi (workspace subcrate inside the peat repo) is the only routinely legitimate unsafe zone.
FFI boundary direction. All Peat protocol logic stays in Rust (peat-ffi and the rest of the workspace). Kotlin in peat-atak-plugin is UI and Android lifecycle only — never a destination for protocol, mesh, transport, persistence, or serialization logic. Native libraries and Kotlin bindings flow from peat-ffi into peat-atak-plugin, not the reverse.
Async runtime. Tokio is the ecosystem standard. The peat workspace pins tokio = { version = "1", features = ["full"] } (or feature subsets where appropriate); sibling repos do the same. Do not introduce alternative async runtimes (async-std, smol) without explicit user approval.
Error handling. Library crates use thiserror for crate-level error enums. Application/binary code uses anyhow for ergonomic error chaining. Both are pinned at 1 in workspace deps and in sibling repos — use those, do not pull alternative error crates without justification.
Commit signing. GPG-signed commits are required across the ecosystem. Do not configure git to bypass signing or use --no-verify to skip pre-commit hooks. Fix the signing setup; do not work around it.
Branch + merge convention. Trunk-based development on main with short-lived feature branches. Every PR squash-merges to main — write the PR title as if it will become the merge commit subject (because it does).
For any task in a peat repo:
CLAUDE.md if present. Run git status and git log -10.Beyond the per-repo verify checklist, an ecosystem-level change is not done until:
peat does not depend on its consumers; sibling repos do not depend on each other)peat repo: the new diff is free of consumer-specific identifiers (ATAK, WinTAK, iTAK, WearTAK, etc.). Run git diff main -- ':!docs/adr' ':!docs/whitepaper' ':!CLAUDE.md' ':!SKILL.md' ':!CHANGELOG.md' | grep -E '^\+' | grep -iE '\b(atak|wintak|itak|weartak)\b' | grep -vE 'peat-atak-plugin|com\.atakmap|atakmap\.app|ATAKActivity' — must be empty before merge. The pipeline checks ADDITIONS only (^\+); excludes the rule documents themselves (which legitimately enumerate the forbidden names as part of the rule definition), the release-notes archive (CHANGELOG.md, which by purpose records the history of vendor-name removals and may need to name what was removed to be useful), and ADR / whitepaper material; and tail-filters the sibling repo name peat-atak-plugin (its actual repo name, historical) plus the third-party host app's real Android identifiers (com.atakmap.*, ATAKActivity) that operational adb commands genuinely target. If a citation is genuinely load-bearing it belongs in an ADR (docs/adr/) or a CHANGELOG entry, not in code or operational docs."Seems right" or "the diff looks correct" is never sufficient.
| Excuse | Rebuttal |
|---|---|
| "This change spans repos but they're tightly coupled — one big PR is cleaner." | One PR per repo, linked through a tracking issue. Atomicity across repos isn't real; reviewability is. |
"I'll just import directly from peat-mesh into peat-node for this." | Cross-repo direct deps are a circular-dependency factory. Add the trait to peat core. |
| "It's only a tiny shell script for a build helper." | No shell scripts for things that belong in Rust. Justify the language choice with the user first. |
| "I'll write a quick TS/Python utility for this." | No new language dependencies without explicit approval. |
"peat core doesn't have the type I need; I'll just put it in this repo for now." | Surface the gap as an issue against peat. Don't fork the type system. |
| "I'll move this Peat protocol logic into Kotlin to make the FFI simpler." | All Peat protocol logic stays in Rust. Kotlin is UI and Android lifecycle only. |
| "This change makes Peat assume the counterpart is also running Peat — fine for now, we'll generalize later." | Interoperability-first is the product. Generalize before merging, or don't merge. |
| "Just one mention of ATAK in the comment is fine — that's the consumer everyone knows about." | No consumer-specific references in peat. Ever. Use "consumer plugin" / "CoT consumer" / "mobile-app plugin". One mention becomes 382 mentions in two years. Verification gate greps for it. |
| "The JNI symbol name has to encode the Java package path of the calling class." | True for the suffix; the Java package path itself is a choice. Pick a generic namespace (com.defenseunicorns.peat.PeatJni), not a consumer-specific one (com.defenseunicorns.<vendor>.peat.PeatJni). |
peat core that assumes types or traits not yet stabilized — flag assumptions in the PR.Each issue used as a Claude Code spec must include:
## Context
Which repo(s) this touches and why.
## Scope
What is in scope. What is explicitly out of scope.
## Acceptance Criteria
Specific, testable conditions for done.
## Constraints
Architecture invariants, performance requirements, conventions.
## Dependencies
Links to related issues or PRs in other repos.
Populate as sessions run. One line per gotcha plus a Why: line.
[patch.crates-io] path overrides pointing at local sibling checkouts; run the release chain only after the change works end-to-end against the consumer.
Why: serializing through publish-per-layer (PR → merge → tag → crates.io → bump consumer) costs hours per round-trip and you can't iterate the consumer until the upstream publish lands; the override workflow caught a tokio::spawn concurrency race and a cross-version legacy-read BLOCKER before either reached a release (peat#864 chain).subscribe_progress emits no terminal frame") was three separate defects — a peat-mesh sync_cooldown silent-drop, a missing peat-protocol watcher, and a wholesale-scalar Automerge merge race — each fixed in a different repo; closing the issue after the first fix would have been wrong.peat repo-specific skillThis repo is a Rust workspace with seven internal subcrates plus example crates. It also hosts the ecosystem skill above.
Subcrates inherit the workspace Cargo.toml's pinned deps (Tokio, serde, thiserror, anyhow, etc.). Cross-subcrate changes coordinate within this repo; cross-repo changes follow the ecosystem skill's "one PR per repo" rule.
peat — top-level crate; eventual home for shared types and traits. Currently a placeholder (see below).peat-schema — schema definitions.peat-protocol — protocol logic (Translator, ChangeEvent, etc.).peat-transport — transport abstractions used by the workspace.peat-persistence — persistence layer.peat-ffi — FFI bindings (see "FFI conventions" below).examples/peat-tak-bridge, examples/peat-ble-test — workspace examples.examples/m5stack-core2-peat is excluded from the workspace (separate toolchain — embedded ESP32 / xtensa-esp-none-elf).peat top-level crate (placeholder)The peat subcrate is currently a placeholder. Its intended role is to be the shared dependency that gives the ecosystem a single source of truth for types, traits, and errors.
Intended contents:
Transport, Node)Does NOT belong in peat core:
peat-transport, peat-mesh, peat-btle)Until peat core stabilizes, sessions should be conservative about adding dependencies on it and must flag any assumptions about peat-core types in PR descriptions.
peat-ffi subcrate — FFI conventionsThe FFI boundary uses two complementary tools:
#[uniffi::export] etc. Async-supported via UniFFI's tokio feature.jni 0.21 bindings for Android native methods that bypass JNA's symbol-lookup issues. These coexist with UniFFI; use UniFFI as the default and jni only where JNA fails.JNA (net.java.dev.jna:jna:5.14.0@aar) is the runtime layer UniFFI depends on at the Kotlin side and is required in peat-atak-plugin/app/build.gradle.kts — do not remove it.
peat-atak-plugin consumes pre-built native libraries (copied into app/libs) and copied Kotlin bindings (into app/src/main/java/uniffi/peat_ffi) from this crate's build output. Do not duplicate FFI types or bindings inside peat-atak-plugin — peat-ffi is the single source of truth.
peat core or peat-ffipeat core requires a brief design note in the PR description.peat core or to peat-ffi's FFI surface requires a list of downstream consumers that need updating, in the PR description.cargo check -p <consumer> (and, for FFI, rebuilding peat-atak-plugin) that no consumer breaks, OR coordinating an update PR in each consumer first.Resolved in this PR: error handling (thiserror + anyhow), async runtime (Tokio), branch + merge convention (trunk-based + squash-merge), commit signing (GPG required), FFI tooling (UniFFI 0.28 + jni 0.21).
Still open:
peat-registry, peat-node, peat-gateway, peat-rmw, peat-mavlink. If they exist privately, the router should note that; if they were renamed, the router should reflect the current name; if deprecated, drop them.peat-atak-plugin or a separate repo?tokio feature in the peat-ffi section above.peat repo. Adopt CODEOWNERS, or document the review-routing convention in the ecosystem skill.Last updated: 2026-05-05 Maintained by: Kit Plummer, VP Data and Autonomy, Defense Unicorns