Guidance for Coding Agents (Claude Code, Codex, etc.) collaborating in this monorepo. This file is the routing layer plus the non-negotiable rules. Everything else lives in a skill, a platform guide, or a design doc; load only what the task needs.
The user's task defines scope and authorization. Shared rules apply to both agents; platform guides specialize them, not silently contradict them. Current subsystem contracts govern design; nearby code provides examples, not permission to copy a known violation. Agent memory and external skills are advisory and must be checked against these sources. When guidance disagrees, resolve it from the current contract and source, fix the stale rule, and ask only if a product or security decision remains unresolved.
task-workflow.md, cross-platform-awareness.md, and engineering-principles.md apply to every task. The rest are load-on-demand; the one-line description tells you when.
- Task Workflow — Scope, investigation, cross-stack order (Core → bindings → iOS/Android), verification, cleanup rounds, handoff, and guide maintenance
- Cross-Platform Awareness — Rules for changes that can affect both apps
- Engineering Principles — Ownership, reuse, minimal abstractions, and test intent
- Project Overview — Repo layout, layer architecture, and ownership boundaries
- Development Commands — Root build, generate, localization, and platform entrypoint commands
- Quality Checks — Iteration and closing check matrices per change type
- Code Review — Review checklist for correctness, conventions, parity, and adversarial security hardening
- Security — Wallet-critical security rules for key material, signing, auth, and transaction handling
- Localization — Fluent sources, generation, and generated output locations for both apps
- Translation Review — Context, approved terminology, compact labels, and scheduled localization audits
- Maestro UI Testing — When to use Maestro flows vs unit or native UI tests, and cross-platform authoring rules
- Release Process — Branching, versioning, commits, publication boundaries, store builds, and removing or disabling support
- Guidance Refresh — How lessons become shared guidance, budgets, skill format, and the local sweep each teammate runs
Read the relevant platform guide(s) before editing code in that area:
- iOS — SwiftUI, MVVM, SPM modules, testing conventions
- Android — Kotlin, Compose, Hilt, Gradle workflow
- Core — Rust crates, UniFFI, generated models, clippy, defensive programming
If a task spans platforms, read every affected guide. Generation and parity requirements live in Cross-Platform Awareness; verification commands live in Quality Checks.
Cross-platform subsystem references live in docs/. Read the relevant one before changing that area:
- Product — User-facing rules and their reasons, failure behavior, platform differences, and open decisions, organized by area under docs/product/
- Architecture — Ownership contracts, worked examples, and the screen-service map
- Open work — Every open item, ordered, with the exemplar to copy for each; delete an item's line in the commit that lands it
- Performance — responsiveness principles, budgets, and testing for wallet, asset, transaction, confirmation, and swap screens on both apps
- Deep links — deep link URL contract, support-chat links, and the web association requirements
- Device — device authentication, registration and subscription sync, and the WebSocket stream
- WalletConnect Pay — payment links: gateway protocol, actions, identity verification, on-chain settlement, activity record and tracking
- Dynode — local proxy usage and configuration
Core-owned subsystems (keystore, device and wallet authentication, WebSockets, provider coverage) are listed in core/AGENTS.md.
This is a crypto wallet. Treat security-sensitive changes as high risk by default.
- Read skills/security.md before changing key management, wallet import/export, seed phrases, signing, transaction construction, auth, secure storage, or cryptographic flows
- Never log, print, persist, snapshot, or expose secret material unless the feature explicitly requires secure handling and existing patterns already support it
- Preserve transaction integrity: amounts, addresses, chain IDs, signatures, simulation data, and confirmation flows must stay explicit and verifiable
- Prefer existing secure-storage and auth layers over inventing new persistence or authentication paths
Follow Task Workflow for verification, both cleanup rounds, and handoff; Quality Checks defines the required commands. Review wallet-critical changes with Security.