Agent Skills
IFM ships a set of agent skills under .agents/skills/ — structured SKILL.md workflows that activate when a coding agent begins a specific class of task. Each skill encodes the inspection checklist, architectural boundaries, and verification commands for its domain, so agents produce changes that respect IFM invariants by construction rather than by accident.
This page is the human-readable index of those skills. The SKILL.md files remain the authoritative source.
Skill Navigation Pattern
When an AI coding agent begins a task:
- Read root
AGENTS.mdfor global operating rules & invariants. - Locate the task in the routing table.
- Read the specified repository/package
AGENTS.md. - Load the relevant
SKILL.mdfor step-by-step workflow procedures. - Refer to deep context docs for domain-specific formulas or specs.
- Execute the listed verification commands to validate changes.
Task Routing
| Task | Skill | Deep Context | Verification |
|---|---|---|---|
| Architecture review & refactoring | architecture-review | invariants, overview | cargo test --workspace |
| Audio pipeline & Opus codec | ifm-audio-development | audio.md, docs/audio/ | cargo test -p ifm-audio |
| Wire protocol & binary packets | ifm-protocol-change | docs/protocol/ | cargo test -p ifm-protocol |
| Transport — QUIC/WebRTC/TCP/gossip/DHT | transport-development | docs/transport/ | cargo test -p ifm-transport |
| Relay plane & mesh forwarding | relay-development | docs/rendezvous/ | cargo test -p ifm-transport |
| TypeScript SDK | sdk-development | docs/sdk/ | npm run build && npm run test:cli |
| Bug fixing & packet diagnostics | debugging | docs/developer-tools | npm run test:cli, cargo test |
| Test-driven development | test-driven-development | this page | cargo test --workspace, npm run test:cli |
| Cross-repo schema change | ifm-cross-repository-change | invariants | cargo test --workspace, npm run build |
| Hardware modules & baseboards | ifm-hardware-development | hardware.md | — |
| Historical context & precedents | historian-analyst | ADRs, commit history, issue threads | — |
| Literature review (arXiv + web) | sibyl-literature | — | — |
architecture-review
Location: .agents/skills/architecture-review/SKILL.md
Activate when reviewing proposed code changes, refactorings, or new features for compliance with IFM architectural boundaries and invariants. Ensures transport-audio separation, protocol single-source-of-truth, relay neutrality, and headless core isolation.
Inspection checklist:
- Protocol single source of truth —
crates/protocolis the sole definition of binary packet structures (Packet,Header,EncodedAudioFrame,PayloadType).@ifm/sdkand apps MUST NOT redefine or fork wire schemas. - Audio ↔ transport separation —
crates/audioimportsifm-protocol, neverifm-transport/libp2p. Transport handles opaque datagrams, never Opus/PCM. Device I/O stays in app layers. - Relay neutrality — relay logic inspects only public headers (Topic ID, TTL, Packet ID, Ed25519 signature). Never decrypts protected payloads.
- Headless core isolation —
crates/corecontains zero UI/terminal/browser assumptions.crates/rendezvousstays an isolated discovery service.
Dependency direction (lower layers never import higher):
debugging
Location: .agents/skills/debugging/SKILL.md
Activate when diagnosing bugs, investigating packet drops, troubleshooting audio stutter or latency, analyzing connection failures, or tracing protocol behavior across Rust and TypeScript.
Workflow: Reproduce → Isolate Layer → Trace → Identify Cause → Regression Test → Minimal Fix → Verify.
| Symptom | Probable Layer | Target Module |
|---|---|---|
| Signature verification fails | Crypto / wire format | crates/crypto, crates/protocol |
| Audio stutters / drops / desync | Jitter buffer / codec / media lane | crates/audio, crates/transport/src/{libp2p_quic,libp2p_browser}.rs |
| Peer can't find frequency or connect | Discovery / transport / relay | crates/discovery, crates/transport, crates/rendezvous |
| CLI fails command execution | CLI frontend / core IPC | crates/cli |
| PWA sound blocked or silent | Web Audio autoplay / MediaSource | packages/ifm-pwa/src/App.tsx |
Diagnostic tools: cargo run --example sniff_voice -p ifm-core, cargo run --example node_ui -p ifm-core, npm run test:cli, RelayApp dashboard at ws://localhost:8790.
ifm-audio-development
Location: .agents/skills/ifm-audio-development/SKILL.md
Activate when modifying the IFM audio pipeline, Opus encoder/decoder, adaptive jitter buffer, Voice Activity Detection (VAD), audio frame boundaries (EncodedAudioFrame), or Web Audio streaming.
Pipeline invariant:
- Separation: production ≠ mixer ≠ DSP ≠ codec ≠ record ≠ transport ≠ discovery.
- Mixer optional & replaceable; MUST NOT contain networking/transport/relay/recording logic.
- Recording independently buffered and non-blocking — slow disks never stall live broadcast.
- Frame constants: 48 kHz mono; 10 ms real-time default (5/20 ms runtime-selectable; 20 ms for recording); 480 samples/frame; 100 FPS;
MediaFrame(wire) +EncodedAudioFrame(in-memory) fromifm-protocol.
Core components (crates/audio): codec.rs (10 ms Opus @ 48 kHz; FEC + DTX), jitter.rs (reorder, adaptive 20→30→50 ms targets, PLC), vad.rs (energy-based).
Boundary (SDK/PWA): no content is cached — the protocol is transfer-only (stations own data, listeners convert locally). The station re-broadcasts the WebM/Opus voice init segment periodically (every ~5s), so a mid-stream listener receives the next live init and MediaSource initializes before the clusters that follow.
Verification: cargo test -p ifm-audio — round-trip (encode_decode_roundtrip_preserves_waveform), PLC (decode_empty_returns_plc_silence), boundary (codec_frames_jitter_decoder_boundary). Ensure zero heap allocations inside encode()/decode() sample loops.
ifm-cross-repository-change
Location: .agents/skills/ifm-cross-repository-change/SKILL.md
Activate when executing changes that span multiple packages or crates (e.g. updating a protocol field, extending SDK capabilities, modifying shared discovery formats, or updating cross-app APIs).
Dependency order (execute in this sequence):
Rules: verify all consumers before changing an exported symbol; clean cutover — update all callers in the same change set, no deprecated shims; build & test both stacks (cargo test --workspace, npm run build && npm run test:cli).
ifm-hardware-development
Location: .agents/skills/ifm-hardware-development/SKILL.md
Activate when designing, prototyping, or implementing IFM-compatible hardware or modules.
Invariants: modular baseboard + expansion module architecture; firmware hardware-agnostic (MCU-independent); capability-driven networking (nodes advertise capabilities, not fixed-function sets); network signals cannot dynamically install arbitrary firmware; reference implementations prioritize portability.
References: hardware.md, invariants.
ifm-protocol-change
Location: .agents/skills/ifm-protocol-change/SKILL.md
Activate when adding, modifying, or refactoring IFM binary wire packets, frame structures, payload types, topic hashing, or serialization schemes. Ensures single-source-of-truth compliance, wire compatibility, and cross-language alignment.
Single source of truth: crates/protocol defines Packet (version, frequency, id, sender, timestamp, ttl, sequence, payload_type, payload, signature), EncodedAudioFrame, and PayloadType (TEXT, VOICE, VIDEO, IMAGE, FILE, JSON, PING, PRESENCE, CONTROL, PLUGIN). Zero type duplication — never create separate struct definitions or JSON mocks in SDK/apps that contradict crates/protocol.
Change checklist: wire compatibility (version increment if needed, append-only/tagged enum deserialization); signature view covers all header fields + payload; BLAKE3 topic ID (BLAKE3(namespace + ":" + channel)); cross-language alignment (update TS SDK deserializers in packages/sdk/src/utils/encoding.ts).
Verification: cargo test -p ifm-protocol, cargo test -p ifm-crypto, npm run test:cli.
relay-development
Location: .agents/skills/relay-development/SKILL.md
Activate when modifying the relay plane (shared relay pool, gossiped relay control topic), relay dashboard, or relay metric reporting.
Rules: station-agnostic — relays don't bind to stations/frequencies; passive forwarding via public headers only, never decrypt protected payloads; real-time media forwarding (voice-lane MediaFrame at MEDIA priority, no decode/encode at relays, never wait on missing packets); dashboards are passive observers (boot the web core and join the same mesh as the desktop apps).
Verification: cargo test -p ifm-transport, cargo test -p ifm-core, bun packages/sdk/examples/smoke.mjs, bun --cwd packages/sdk/examples/relay dev.
sdk-development
Location: .agents/skills/sdk-development/SKILL.md
Activate when modifying the TypeScript SDK (@ifm/sdk), public JavaScript API, event emitter interfaces, in-process node factory, or cross-tab synchronization.
Design rules: ergonomic radio metaphor (IFM.create(), radio.tune(), radio.broadcast(), radio.listen()) — hide socket primitives behind the frequency abstraction; type safety (packages/sdk/src/types.ts mirrors Rust crates/protocol); build to packages/sdk/dist, always bun run build in packages/sdk after modifying source so demo apps see the updated build.
Verification: npm run build, npm run test:cli, bun packages/sdk/examples/smoke.mjs.
sibyl-literature
Location: .agents/skills/sibyl-literature/SKILL.md
Activate when conducting systematic literature reviews using arXiv and Web searches.
Framework: arXiv for academic papers (decentralized protocols, audio streaming, cryptography, networking); Web for industry whitepapers, blogs, docs. Corroborate key claims with multiple sources; prefer primary sources; document all cited sources.
test-driven-development
Location: .agents/skills/test-driven-development/SKILL.md
Activate when adding features, refactoring existing code, or fixing bugs using TDD. Guides writing reproducible tests before or alongside implementation changes across Rust and TypeScript.
Workflow: Understand → Locate Layer & Contracts → Failing Test (Red) → Minimal Code (Green) → Refactor (Clean) → Full Workspace (Pass).
Test placement:
| Stack | Unit Tests | Integration / Selftest |
|---|---|---|
| Rust | Inline mod tests at bottom of source file | tests/ dir per crate |
| TS SDK | Beside target file (*.test.ts) | bun packages/sdk/scripts/selftest.mjs (two in-process radios) |
| CLI | — | cargo test -p ifm-cli |
| Relay | — | cargo test -p ifm-transport |
Use InMemoryMesh for fast, zero-socket networking tests.
Verification: cargo test --workspace, cargo test -p <crate>, npm run test:cli.
transport-development
Location: .agents/skills/transport-development/SKILL.md
Activate when modifying transport layers (QUIC, WebRTC, TCP), in-memory mesh abstractions, GossipSub broadcast fanout, Kademlia DHT peer discovery, NAT traversal, or connection management.
Principles: transport agnosticism (ifm-transport abstracts QUIC/WebRTC/TCP/InMemoryMesh; core works identically regardless); gossip TTL max 16 hops, fanout 6 peers, BLAKE3 packet ID dedup; priority QUIC → WebRTC → TCP fallback; zero audio codec dependencies (handles binary datagrams without parsing Opus).
Testing: InMemoryMesh / SharedMeshTransport (crates/transport/src/memory.rs) for full multi-peer mesh tests without real sockets.
Verification: cargo test -p ifm-transport, cargo test -p ifm-gossip, cargo test -p ifm-discovery.
historian-analyst
Location: .agents/skills/historian-analyst/SKILL.md
Activate when understanding historical context, identifying precedents, and analyzing changes over time in the IFM Protocol.
Framework: source analysis (primary documents — ADRs, commit history, issue discussions); comparative history (how similar features/decisions were handled before); contextualization (technical & operational constraints at decision time). Validate causation claims against project history; account for both continuity and change.