Workflow

Branching & PRs

• Branch off main. Small, focused branches.
• Open a PR early; CI runs lint + typecheck + build + test on every push.
• Squash-merge into main. main is always deployable — CD workflow deploys API + Web on every merge.

OpenSpec — spec-driven changes

Non-trivial features go through the OpenSpec workflow (see openspec/). The abbreviated loop:

Current active change: openspec/changes/bridge-production-setup.

Package management

• pnpm for JS deps: pnpm --filter @gringo-pay/<pkg> add <dep>.

• expo install for anything in apps/mobile that touches Expo/RN — it picks an SDK-compatible version. Never use pnpm add in apps/mobile for Expo-adjacent packages.

  # Correct
  cd apps/mobile && pnpm exec expo install <package>
  
  # Wrong — may install SDK-incompatible version
  pnpm add <package>

• Audit/fix Expo package versions:

  pnpm exec expo install --check
  pnpm exec expo install --fix

Turbo & caching

Turborepo caches build/lint/typecheck/test outputs. If you get stale results, pnpm turbo <task> --force bypasses the cache. Delete .turbo/ per package to reset local cache entirely.

Documentation lookups

Before implementing anything against a third-party dep (Privy, Bridge, Expo modules, Hyperdrive drivers, Vitest pool config), check context7 for the current recommended pattern — even if the answer feels obvious. See the CLAUDE.md "Documentation lookups" section for the full rationale. The cost of one lookup is small; the cost of shipping the wrong pattern and re-doing it is large.

Where to add code

Kind of change	Where
New API endpoint	apps/api/src/<domain>/routes.ts + Zod schema in shared
New DB column	Add to apps/api/src/db/schema/<table>.ts + pnpm db:generate
Shared type/schema	packages/shared/src/<domain>/schemas.ts + export in index.ts
New mobile screen	apps/mobile/app/<route>.tsx (Expo Router file-based)
Third-party mobile SDK	expo install + wire in the appropriate _layout.tsx
Shared ESLint / TS rule	packages/config/
New docs page	apps/docs/docs/<section>/<page>.md + update sidebars.ts

Documentation site

Docs changes preview on every PR (the docs deploy workflow runs a build check). Merges to main auto-deploy to gringo-pay-docs.pages.dev.