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.

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.