Agent operating manual

This is a minimal consumer-app foundation: Expo mobile, Next.js/tRPC backend, Supabase Auth/Postgres, Drizzle, and shared packages in a pnpm/Turborepo workspace. Product behavior is intentionally undefined.

Read the relevant contract

• Setup and commands: README.md, getting started.
• Data access and auth: architecture, authentication.
• Schema, migrations, RLS, grants: database.
• UI work: design principles.
• Builds, environments, submissions, updates: releases.
• Skill selection and sources: skills.

Read existing code before editing. State the intended scope. Keep changes focused and preserve work you did not create. Follow the owner's request; do not invent an app concept, business schema, onboarding flow, guest policy, or visual brand.

Development

Run commands from the repository root. Use pnpm dev for the development environment. Check whether the relevant servers are already running before starting another instance. The default ports are API 3001 and Metro 8081. The dev script refuses occupied ports and never kills an arbitrary listener. Set PORT, EXPO_PORT, and EXPO_PUBLIC_API_URL for another instance. Restart after editing .env.

Use EAS development clients for native work. Native builds are EAS-only in this starter: no expo run:ios, expo run:android, or local Xcode/Gradle builds. This is a project convention; bundled upstream examples do not override it. Do not create builds or provision services just to inspect source.

Architecture

• Supabase owns authentication. Keep provider secrets in Supabase, never the client.
• Direct application data access uses the Supabase client through React Query, protected by grants and RLS. tRPC is available for server operations. Do not rewrite one path into the other without a reason tied to the requested behavior.
• Server code uses Drizzle. A privileged Postgres connection can bypass RLS; authenticated tRPC middleware does not establish row ownership. Check ownership in every applicable server operation.
• Never expose a database URL or service secret with an EXPO_PUBLIC_ or NEXT_PUBLIC_ prefix.
• Supabase { error } values must be handled. A failed read must render a failure with retry, never an empty result. Keep user data out of logs.
• React Query keys come from the shared key factory. Invalidate affected views after writes and clear user-specific cache when identity changes.
• Route files compose screens. Share code when there is a real consumer; do not introduce a feature hierarchy before a feature exists.
• Use kebab-case filenames. Keep CLAUDE.md as a one-line import of this file.

React and UI

Use no-use-effect, native data fetching, and native UI in their domains.

No new direct useEffect in app code. Prefer derived state, event handlers, React Query, and declarative navigation. The documented mount helper is for true external lifecycle synchronization; it is not an escape hatch for fetching or state mirroring. ESLint enforces the import convention.

Apply Apple HIG principles to React Native: accessibility, Dynamic Type, touch targets, safe areas, platform navigation, and reduced motion. Upstream SwiftUI/UIKit examples are guidance, not instructions to generate an Xcode project. Product-specific design decisions belong in docs once the owner makes them.

Verify UI through an available browser or simulator tool. Exercise the actual interaction, inspect resulting state and a screenshot, and report what was checked. Prefer the project's registered UI tools when available. Do not assume a particular MCP server, IDE, paid service, or simulator is installed. If native testing is unavailable, report that limit instead of claiming a native pass.

Database changes

Read Supabase Postgres guidance. Edit the Drizzle schema and generate migrations in the same change. Never use schema push or apply untracked production DDL. Keep migration testing on disposable databases. Add ownership/RLS assertions when the first user-owned tables are introduced. Never recreate Supabase's auth schema in application migrations.

Mobile clients and databases release separately: use additive changes first, ship compatible clients, and retire old columns only when installed clients are safe. This empty starter does not claim an app-specific compatibility scanner; add checks for the schema and client selects as the product grows.

Verification and handoff

• Run the narrowest useful checks for the change. pnpm check covers formatting, lint, types, tests, and skill snapshots. pnpm build checks Next.js and iOS bundling. Schema changes also need pnpm db:test.
• Make small focused commits as changes land. Explain what changed, why, and what was verified.
• Update docs alongside command, environment, architecture, or workflow changes.
• Keep durable documentation in docs/. Keep transient plans and session notes out of the repository.

Authorization

Use existing explicit user authorization; do not ask twice for the same action. Read-only checks and reversible local work can proceed within the task.

Get authorization before new spending, provisioning external services, destructive data changes, production migrations/deployments, EAS submissions or updates, and merging PRs. A request to prepare a change does not authorize publishing it. Changing app identity after release also requires owner approval. Never commit secrets or personal tool permissions.