Skip to content

AGENTS.md

Latest commit

 

History

History
164 lines (121 loc) · 7.08 KB

AGENTS.md

File metadata and controls

164 lines (121 loc) · 7.08 KB

AGENTS.md

Single source of truth for agents working in this repo. CLAUDE.md imports this file via @AGENTS.md, so Claude Code, Codex, and any other agent that reads AGENTS.md share the same instructions.

Behavioral Guidelines

Behavioral guidelines to reduce common LLM coding mistakes. (Adapted from Andrej Karpathy's CLAUDE.md.)

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

  • State your assumptions explicitly. If uncertain, ask.
  • If multiple interpretations exist, present them — don't pick silently.
  • If a simpler approach exists, say so. Push back when warranted.
  • If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

  • No features beyond what was asked.
  • No abstractions for single-use code.
  • No "flexibility" or "configurability" that wasn't requested.
  • If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

  • Don't "improve" adjacent code, comments, or formatting.
  • Don't refactor things that aren't broken.
  • Match existing style, even if you'd do it differently.
  • Remove imports/variables YOUR changes made unused; leave pre-existing dead code unless asked.

The test: every changed line should trace directly to the request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

  • "Add validation" → "Write tests for invalid inputs, then make them pass."
  • "Fix the bug" → "Write a test that reproduces it, then make it pass."

For multi-step tasks, state a brief plan with a verify step for each item.

Third-Party Library Docs

For any third-party library, use the context7 MCP to fetch up-to-date documentation rather than relying on training data, which lags real library APIs. If the context7 MCP server is not available, set it up: https://context7.com/install

Key libraries in this repo to pull docs for: react-native, react-native-builder-bob, turbo, @0xtrails/api, @0xtrails/wallet, 0xtrails.

Project Overview

@0xsequence/oms-react-native-sdk is a React Native SDK (Turbo Module) for the OMS platform, bridging native iOS (Swift) and Android (Kotlin) SDKs to TypeScript. It exposes wallet auth (email OTP, OIDC redirect), transaction signing, balance queries, and session management to React Native and Expo apps.

Repository Structure

  • src/ — TypeScript public API and native module bindings
  • lib/ — built output (CommonJS, ESM, TypeScript declarations); generated by yarn prepare
  • android/ — Kotlin native module
  • ios/ — ObjC/Swift native module
  • examples/sdk-example/ — React Native CLI example app
  • examples/trails-actions-example/ — Trails demo with redirect auth
  • examples/expo-example/ — standalone Expo example (not in Yarn workspace; uses npm)
  • .github/workflows/ — CI (lint, typecheck, Android + iOS builds)

Tech Stack

  • Language: TypeScript (React Native Turbo Module; native layers in Kotlin + Objective-C/Swift)
  • Package manager: Yarn 4 (Berry) with workspaces; examples/expo-example uses npm standalone
  • Build tool: react-native-builder-bob + Turbo
  • Linting: ESLint 9 flat config + Prettier
  • Node version: v24.13.0 (see .nvmrc)

Build & Run

# Install dependencies
yarn install

# Build the library
yarn prepare

# Typecheck
yarn typecheck

# Lint
yarn lint

# Run SDK example (React Native CLI)
yarn sdk-example start

# Run Expo example (standalone — uses npm, not yarn workspace)
cd examples/expo-example && npm install && npm start

Testing

See TESTING.md for testing conventions, manual verification checklist, and the plan for when automated tests are added.

Documentation

API.md at the repo root documents the full public TypeScript API for consumers.

Conventions

  • Commit messages and PR titles follow Conventional Commits, e.g. feat(auth): add OIDC refresh token support.
  • The public API surface is documented in API.md — update it whenever src/index.tsx exports change.
  • The lib/ directory is generated; never edit it by hand.
  • examples/expo-example is intentionally outside the Yarn workspace (!examples/expo-example in package.json#workspaces) — install its deps with npm, not yarn.
  • Native builds (Android/iOS) are slow; validate JS-layer changes with yarn lint && yarn typecheck first; leave full native builds to CI.
  • The resolutions block in package.json pins 0xtrails / @0xtrails/* — update all three entries together when bumping the trails version.
  • Pre-release versions use the 0.x.y-alpha.N scheme. Publishing steps are in PUBLISHING.md.

CI/CD

Two workflows in .github/workflows/:

  • ci.yml — runs on pull requests, workflow dispatch, and pushes to master: lint, typecheck, library build, Android build, iOS build.
  • quick-checks.yml — runs on push to non-master branches: lint + typecheck only.

Pull requests run full CI, including native builds. If the native layer changed, make sure the Android and iOS PR checks pass before merging; validate locally when you need faster feedback.

Common Pitfalls

  • Running yarn inside examples/expo-example will fail — it's not a Yarn workspace member. Use npm there, or yarn expo-example <script> from the root.
  • yarn prepare regenerates lib/ — if builds look stale, run yarn clean && yarn prepare.
  • The podspec resolves oms-client-swift-sdk and the Android module resolves io.github.0xsequence:oms-client-kotlin-sdk — bump native SDK versions in the podspec and android/build.gradle together.
  • Turbo cache can mask failures: if something seems wrong, run with --force to skip the cache.
  • Signed commits are required (enforced by branch protection) — configure git commit -S locally.

Maintenance Matrix

When this changes… Also update…
src/index.tsx exports API.md, lib/ (run yarn prepare)
Native SDK version (Swift / Kotlin) OmsClientReactNativeSdk.podspec, android/build.gradle
package.json scripts or test commands TESTING.md, .github/workflows/ci.yml
Node version (.nvmrc) turbo.json#globalDependencies, CI setup action
resolutions (0xtrails / @0xtrails/*) All three resolution entries together
Repo structure (new top-level dirs) AGENTS.md structure section
Contributing workflow CONTRIBUTING.md, README.md