self/AGENTS.md

AGENTS Instructions

Package Management

Package Manager: Yarn

Commands to use: yarn install, yarn add, yarn remove

Note: Do not use npm or pnpm.

This repository is a Yarn v4 monorepo with several workspaces:

• app – mobile app (@selfxyz/mobile-app)
• circuits – zk-SNARK circuits (@selfxyz/circuits)
• common – shared utilities (@selfxyz/common)
• contracts – solidity contracts (@selfxyz/contracts)
• sdk/core – core TypeScript SDK (@selfxyz/core)
• sdk/qrcode – qrcode SDK (@selfxyz/qrcode)
• packages/mobile-sdk-alpha – alpha version of the SDK (@selfxyz/mobile-sdk-alpha)
• noir – noir circuits

Workflow

Setup

• Ensure Node.js 22.x is installed (see .nvmrc for exact version), then:
  • nvm use
  • corepack enable && corepack prepare yarn@stable --activate
  • Verify: node -v && yarn -v
• Run yarn install once before running any other commands. This installs root dependencies and sets up husky hooks.

Pre-PR Checklist

Before creating a PR, ensure:

Code Quality

• yarn nice (or equivalent) passes in affected workspaces
• yarn types passes across the repo
• yarn test passes in affected packages
• yarn build succeeds for all workspaces

AI Review Preparation

• Clear, imperative commit messages (e.g. Fix address validation)
• PR description includes context for AI reviewers
• Complex changes have inline comments explaining intent
• Security-sensitive changes flagged for special review
• Review/spec text is signal-only: remove non-actionable praise, back-patting, and generic commentary; keep concrete issues, risks, decisions, owners, next steps, and validation evidence

Follow-up Planning

• Identify any known issues that need separate PRs
• Note any performance implications
• Document any breaking changes

Post-PR Validation

After PR creation:

Automated Checks

• CI pipeline passes all stages
• No new linting/formatting issues introduced
• Type checking passes in all affected workspaces
• Build artifacts generated successfully

Review Integration

• Address CodeRabbitAI feedback (or document why not)
• Resolve any security warnings
• Verify performance benchmarks still pass
• Confirm no sensitive data exposed in logs/comments

Commit Checks

Before committing, run the following commands:

# Fix linting and formatting issues automatically (for packages that support it)
yarn workspaces foreach -A -p -v --topological-dev --since=HEAD run nice --if-present

# Lint all packages in parallel
yarn lint

# Build all workspaces except `contracts`
yarn build

# Compile Solidity contracts (may occasionally throw a Hardhat config error)
yarn workspace @selfxyz/contracts build

# Run type-checking across the repo
yarn types

Workflow Commands

Pre-PR Validation

# Run all checks before PR - only on changed workspaces since main
# Format and lint changed workspaces (workspace-specific scripts first, then fallback to root)
yarn workspaces foreach -A -p -v --topological-dev --since=origin/main run nice --if-present

# Run global checks across all workspaces
yarn lint && yarn types && yarn build && yarn test

# Alternative: Run workspace-specific checks for changed workspaces only
# yarn workspaces foreach -A -p -v --topological-dev --since=origin/main run lint --if-present
# yarn workspaces foreach -A -p -v --topological-dev --since=origin/main run types --if-present
# yarn workspaces foreach -A -p -v --topological-dev --since=origin/main run build --if-present
# yarn workspaces foreach -A -p -v --topological-dev --since=origin/main run test --if-present

Post-PR Cleanup

# After addressing review feedback
yarn nice  # Fix any formatting issues in affected workspaces
yarn test  # Ensure tests still pass
yarn types # Verify type checking

Tests

• Run unit tests where available:

  • yarn workspace @selfxyz/common test
  • yarn workspace @selfxyz/circuits test # may fail if OpenSSL algorithms are missing
  • yarn workspace @selfxyz/mobile-app test
  • yarn workspace @selfxyz/mobile-sdk-alpha test
  • For Noir circuits, run nargo test -p <crate> in each noir/crates/* directory.
  • Tests for @selfxyz/contracts are currently disabled in CI and may be skipped.

• E2E tests (mobile app) - Run automatically in CI/CD, not required locally:

  • E2E tests execute automatically in GitHub Actions on PRs and main branch
  • Local E2E testing is optional (see app/AGENTS.md for local setup if needed)
  • Commands available: yarn workspace @selfxyz/mobile-app test:e2e:ios / test:e2e:android

Test Memory Optimization

CRITICAL: Never create nested require('react-native') calls in tests. This causes out-of-memory (OOM) errors in CI/CD pipelines.

• Use ES6 import statements instead of require() when possible
• Avoid dynamic require() calls in beforeEach/afterEach hooks
• Prefer top-level imports over nested requires
• See .cursor/rules/test-memory-optimization.mdc for detailed guidelines

CI Caching

Use the shared composite actions in .github/actions when caching dependencies in GitHub workflows. They provide consistent cache paths and keys:

• cache-yarn for Yarn dependencies
• cache-bundler for Ruby gems
• cache-gradle for Gradle wrappers and caches
• cache-pods for CocoaPods

Each action accepts an optional cache-version input (often combined with GH_CACHE_VERSION and a tool-specific version). Avoid calling actions/cache directly so future workflows follow the same strategy.

Formatting

• Use Prettier configuration from .prettierrc files.
• Follow .editorconfig for line endings and indentation.

Commit Guidelines

• Write short, imperative commit messages (e.g. Fix address validation).
• The pull request body should summarize the changes and mention test results.

Workspace-Specific Instructions

Some workspaces have additional instructions in their own AGENTS.md files:

• app/AGENTS.md - Mobile app development, E2E testing, deployment
• packages/mobile-sdk-alpha/AGENTS.md - SDK development, testing guidelines, package validation
• noir/AGENTS.md - Noir circuit development

These workspace-specific files override or extend the root instructions for their respective areas.

Troubleshooting

Common Issues

Yarn Install Fails

• Ensure Node.js 22.x is installed: nvm use
• Clear Yarn cache: yarn cache clean
• Remove node_modules and reinstall: rm -rf node_modules && yarn install

Build Failures

• Run yarn build:deps in affected workspace first
• Check workspace-specific AGENTS.md for platform requirements
• For mobile app: ensure iOS/Android prerequisites are met (see app/AGENTS.md)

Test Failures

• Check workspace-specific test setup requirements
• For mobile app tests: ensure native modules are properly mocked
• See .cursor/rules/test-memory-optimization.mdc for test memory issues

Type Errors

• Run yarn types to see all type errors across workspaces
• Some packages may need to be built first: yarn build:deps

SDK Specs

The specs/ folder contains architecture and implementation specs for the Self SDK project (WebView engine + native shells). These specs are designed to serve as both human documentation and AI agent prompts.

Spec Structure & Naming Rules

• Do not create one-file folders. If a folder would contain only one markdown file, keep that file at the parent project level.
• File names should describe doc type, not repeat project name when already inside the project folder.
• Preferred project-level names: INDEX.md, OVERVIEW.md, PLAN.md, STATUS.md, HANDOFF.md, REVIEW.md, ARCHITECTURE.md, INITIATIVE.md.
• INDEX.md is navigation only (entrypoint/table of contents for that folder).
• OVERVIEW.md is substantive context (architecture/scope/status summary), not just a link list.
• Do not use INDEX.md and OVERVIEW.md as synonyms for the same purpose.
• Workstream docs under workstreams/<scope>/ use SPEC.md (context + implementation in one file).
• PR execution docs belong under workstreams/<scope>/plans/<BACKLOG-ID>-<slug>.md; use one plan file per PR.
• Use suffixed variants (for example SPEC-<TOPIC>.md) only when multiple specs of the same type are required in the same folder.
• When renaming/moving spec files, update all references in specs/, AGENTS.md, and CLAUDE.md in the same change.

Spec Writing Rules

• Qualify coverage claims. Distinguish unit-tested/shared-utility coverage from handler-level, integration, or end-to-end coverage; do not say "tested" without naming the actual coverage level.
• Flag invariant departures. If a spec intentionally departs from active architecture rules or repo invariants, call out the conflict explicitly, justify the departure, and list the docs that must be updated if the direction is accepted.

Start here: specs/README.md — table of contents and reading order.

Key files:

• specs/projects/sdk/INDEX.md — SDK project entry point, workstream links
• specs/projects/sdk/OVERVIEW.md — Architecture, bridge protocol, module table, execution status
• specs/projects/sdk/workstreams/*/SPEC.md — Durable workstream context, invariants, backlog, active plan links
• specs/projects/sdk/workstreams/*/plans/*.md — PR-sized execution plans
• specs/projects/sdk/paused/*/SPEC.md — Paused workstreams retained for future reuse (native-shells, integrations, rn-sdk, native-consolidation)

Before implementing SDK work: Read CLAUDE.md Key Rules and the relevant workstream SPEC.md under specs/projects/sdk/workstreams/. These specs contain explicit constraints ("You will NOT..."), validation commands, and file ownership boundaries that prevent common mistakes.

Scope

These instructions apply to the entire repository unless overridden by a nested AGENTS.md.