Skip to content

AGENTS.md

Latest commit

 

History

History
60 lines (43 loc) · 2.67 KB

AGENTS.md

File metadata and controls

60 lines (43 loc) · 2.67 KB

AGENTS.md

This file provides guidance to AI coding agents working with code in this repository.

Project

hw-core is a Rust workspace for host-to-hardware crypto wallet communication. The first target is Trezor Safe 7 over BLE using the Trezor Host Protocol (THP). The transport/core stack is designed to be shared across wallet vendors.

Skills

All skills are mandatory reading before making changes.

  • Project Overview – Crate architecture, dependency graph, feature flags, and key design patterns
  • Development Commands – Building, testing, linting, running the CLI, and generating bindings
  • Code Style – Module organization, async patterns, and trait design
  • Error Handling – Layered thiserror enums, Result returns, and no panics in production
  • Defensive Programming – Type safety, exhaustive matching, and safe defaults
  • Naming – Rust naming conventions and project-specific terminology
  • Tests – Test organization, MockBackend, proptest, and fixture patterns
  • Comments – When and how to write comments and doc comments
  • Git and Commit Guidelines – Conventional Commits format and PR checklist
  • Common Issues – Known build, BLE, and platform-specific issues

Formatting (mandatory)

After any code changes, run formatting before finishing:

just fmt && just lint

Or explicitly:

cargo fmt --all
cargo clippy --workspace --all-targets --all-features -- -D warnings

Comments and Docstrings

  • Comments and docstrings are opt-in, not default.
  • When needed, keep them to a single line.
  • Prefer no comment unless it explains intent, invariants, or safety that the code cannot make obvious on its own.

Source of Truth for Behavior

  • When debugging protocol/flow mismatches, always check the Trezor Suite implementation first: ~/workspace/github/trezor-suite
  • Treat Trezor Suite app behavior as the reference for:
    • request payload shapes
    • derivation path/account handling
    • signing request construction
    • user-facing pairing/connect/address/sign flows

Other Notes

  • Build times: Initial build takes several minutes; incremental builds are fast with sccache
  • Linux BLE: Requires sudo apt-get install -y libdbus-1-dev pkg-config
  • Pairing state: Stored at ~/.hw-core/thp-host.json; use pair --force to reset
  • License: Apache-2.0
  • Development status: See docs/roadmap.md and docs/plan.md