life-companion/AGENTS.md

Life Companion Engineering Guide

Product Contract

Life Companion is an offline-first React Native app in which real-life actions shape one permanent companion and its habitat. The app is not a streak tracker, fitness score, or gacha product.

Non-negotiable rules:

• one relationship advances by at most one shared day per local calendar day;
• activity volume, devices, repeated taps, and payment never accelerate the relationship;
• the four visible directions are Activity, Calm, Focus, and Vitality;
• no rarity, paid rerolls, visible XP, health judgment, hunger, illness, guilt, or streak loss;
• no sound in the current product;
• every accepted real-life event has inspectable provenance and can be corrected;
• absence never harms the companion or creates catch-up work;
• animations, markings, discoveries, or world interactions must make growth visible.

The authoritative scope and acceptance criteria live in docs/PRODUCT_SCOPE.md.

Architecture

• React Native bare workflow with TypeScript.
• Feature code lives in src/modules/<feature>/.
• Shared UI lives in src/components/; design tokens live in src/theme/.
• Navigation names and param types live in src/navigation/.
• Durable domain rules are pure TypeScript under src/domain/ and require tests.
• Device integrations live behind interfaces in src/services/; screens never import native health packages directly.
• Zustand owns durable app state. Persisted schema changes require a migration.
• All user-facing text uses i18next keys in Simplified Chinese and English.
• Use StyleSheet.create for stable styles and token-driven inline styles only when dynamic.

Quality Gates

Before committing a logical change, run the narrowest relevant checks. Before delivery, all of these must pass:

npm run typecheck
npm test -- --runInBand
npm run lint

Native dependencies or configuration changes additionally require CocoaPods, an iOS simulator build, and an Android debug build before final delivery.

Git

• Keep commits focused and use <type>: <Chinese description> messages.
• Never commit secrets, signing credentials, generated build output, or local health data.
• Do not modify the sibling life-companion-prototype or KnoKno repositories.