WellFit-now

Imported from Bernds-tech/WellFit-now (AGENTS.md). Install upstream with npx skills add Bernds-tech/WellFit-now. Copyright stays with the author.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

WellFit Repository Agent Rules

0. Mandatory project-memory preflight

Before answering project-state questions or making any code, configuration, runtime, mobile, backend, UI-supporting or repository change, read:

1. project-memory/PROTOCOL.md
2. project-memory/PROJECT_COORDINATION.json
3. project-memory/CURRENT_STATE.md
4. project-memory/FINISHLINE_STATE.json
5. project-memory/NEXT_BEST_ACTION.md
6. project-memory/AUTO_HANDOFF.md
7. project-memory/OWNER_ACTION_INBOX.md
8. project-memory/SESSION_HANDOFF.md
9. project-memory/STARTED_WORK.md
10. project-memory/WORK_LOCKS.md
11. project-memory/OPEN_LOOPS.md
12. project-memory/TASK_LEDGER.md
13. project-memory/DEPENDENCIES.md
14. project-memory/DECISIONS.md
15. project-memory/FAILED_ATTEMPTS.md
16. project-memory/CHANGE_REQUESTS.md
17. the current runtime/canonical truth files relevant to the task.

For cross-repository work also reconcile the authoritative WellFit program master in Bernds-tech/WellFit:project-memory/WELLFIT_MASTER_STATE.json plus the relevant WF-CONTRACT-*, WF-XDEP-*, integration-gate, convergence and cross-repo-lock records.

Then check current branch/main, git status, recent commits/PRs/CI and relevant current runtime/provider evidence. Search for an existing task/change ID and prior attempt before starting a new path. Chat memory is a navigation hint only and never overrides Project Memory, current code/tests or current external evidence.

Repository authority boundary

This repository is the WellFit technical-product authority: web/backend, auth, data, APIs, mission/economy/server authority, security/runtime and general technical application/mobile logic. Bernds-tech/WellFit owns graphical/UI/UX truth. Bernds-tech/WellFit-Buddy owns only Buddy-specific behavior, presentation/animation and Buddy-specific AR/camera interaction. Do not infer general technical mobile/application ownership from the Buddy repository.

1. Project overview

WellFit is a Move-Learn-Social-Earn platform that combines movement, learning, social challenges, gamification, an AI buddy, AR experiences, PvP/challenge mechanics, a planned token/NFT economy, and future B2B modules.

The current codebase is an existing product baseline. Do not restart or rewrite the app. Extend the current architecture in small, reviewable steps and preserve existing working behavior unless a task explicitly requests a change.

Current runtime reference

Before runtime, roadmap, readiness or planning work, read docs/status/WELLFIT_RUNTIME_STATE_2026-07-24.md in addition to the protected Beta-1 Canonical Truth files. The runtime-state document records the actual merged implementation and current execution order. Historical May 2026 status/TODO files remain preserved for context but must not override newer tested runtime behavior.

When sources conflict:

1. use main code and passing tests for actual runtime behavior;
2. use the current runtime-state document for execution context;
3. use the owner-controlled Beta-1 Canonical Truth for product/economy boundaries;
4. treat historical TODOs and older concept/whitepaper material as background only.

Do not silently reconcile terminology or scope conflicts. In particular, the runtime currently uses WFXP while the protected Beta-1 Canonical Truth defines spendable WFP and separate non-spendable avatar XP; that migration requires a dedicated owner-reviewed task.

2. Branching rules

• Do not work directly on main.
• Create a task-specific branch before making changes.
• Keep each branch focused on one clear goal.
• Do not merge or close old Unity PR #13 unless the repository owner explicitly instructs you to do so.
• Do not merge PR #13 into current work as a shortcut.
• Before committing, verify git status and ensure only intentional files are changed.

3. Pull request rules

• Keep pull requests minimal, reviewable, and scoped to the requested task.
• Summarize changed files, checks run, known risks, and the next recommended task.
• Do not hide failing checks. If a command fails, include the command, failure reason, and whether it is an environment limitation or a code issue.
• Do not include secrets, local-only machine paths, generated build output, or unrelated .vscode changes.
• If documentation or TODO state changes, update only the relevant planning/register files and do not delete historical context.

4. Build, lint, and test rules

• Run npm install only when dependencies are missing or clearly out of sync.
• Prefer the existing package scripts:
  • npm run lint
  • npm run build
  • npm run agent:quality-gate when project governance or broader quality checks are relevant
  • npm --prefix functions run check for Firebase Functions syntax checks
• Emulator-based tests may require Firebase emulators, Java, ports, and local environment setup. If they cannot run, document the limitation clearly.
• For Next.js code changes, read the relevant guide in node_modules/next/dist/docs/ before changing APIs, routing, rendering behavior, metadata, caching, or build configuration.

5. UI/UX rules

• Preserve the current visual identity, header, sidebar, footer, routes, navigation structure, and existing working pages unless a task explicitly requests otherwise.
• Do not introduce a parallel design system or duplicate UI shell.
• Keep mobile, dashboard, mission, buddy, legal, and settings flows consistent with the existing app structure.
• Avoid broad restyling when a small targeted fix is enough.
• If a perceptible UI change is made to a runnable web page, capture or request a screenshot/preview when the environment supports it.

6. Safety and compliance rules

Do not modify compliance-critical logic without explicit instruction and a clear review plan. This includes:

• token, NFT, wallet, payment, purchase, payout, marketplace, staking, presale, or trading logic
• health data, watch data, location data, camera data, child-safety, privacy, consent, or medical-adjacent logic
• betting, PvP stakes, competition payouts, anti-cheat, reward authorization, mission completion authority, or financial-equivalent mechanics
• legal, AGB, Datenschutz, Impressum, or compliance messaging

Default product safety stance:

• Mobile must not activate token/NFT/trading/presale features.
• Rewards, XP, points, mission completion, anti-cheat, inventory unlocks, and rare-item grants must not be final-authorized by the client.
• Internal points/XP simulations may exist for beta UX, but final ledger authority must remain server-side or explicitly marked as draft/preview.
• Never expose secrets or server API keys to the frontend.

7. Unity / WellFitBuddyAR protection rules

• Do not delete native/unity/WellFitBuddyAR or any local Unity files under it.
• Treat native/unity/WellFitBuddyAR/Assets/Scripts/ as potentially important local Unity work.
• Do not overwrite Unity scripts with templates unless explicitly instructed.
• Do not merge, close, or depend on old Unity PR #13 without explicit owner instruction.
• Keep Unity AR work separate from web beta work unless the task explicitly bridges them.
• Unity may emit AR events, but backend/app logic must decide rewards, mission completion, and anti-cheat.

8. TODO, list, and planning file protection rules

• Do not delete TODO, list, roadmap, status, planning, register, or handoff files.
• If a TODO/list file is stale, mark it as stale and link to the leading file instead of removing it.
• If a TODO/list file duplicates another file, mark it as duplicate and point to the canonical source.
• Important planning areas include todolist/, project-register/, docs/architecture/, and agents/.
• Keep planning edits small and preserve historical decisions unless a task explicitly asks for consolidation.

9. Reporting completed work

When finishing a task, report:

• branch name
• concise summary of changed files
• commands/checks run and their results
• known risks, skipped checks, or environment limitations
• whether dependencies were installed or left unchanged
• next recommended task

For code changes, cite the affected files and keep the summary tied to the actual diff.

10. Staged roadmap before continuing mission development

Before continuing larger mission development, prepare WellFit in staged, low-risk steps:

1. Repository baseline: confirm branch state, dependency state, lint/build status, and current route/API inventory.
2. Governance alignment: ensure AGENTS.md, the current runtime-state document, TODO index, project registers, and handoff/status files agree on safe working rules.
3. UI shell stability: preserve and verify landing, dashboard, sidebar, footer, mobile navigation, legal/help pages, and existing mission routes.
4. Safety wording pass: remove or clearly defer premature token/NFT/wallet/payment/betting language from beta-facing mobile and mission flows unless explicitly approved.
5. Economy guardrails: keep internal balances and rewards non-monetary; maintain server authority and do not infer WFP/WFXP/XP equivalence without a dedicated migration decision.
6. Data protection review: confirm health, child-safety, camera, location, and consent flows are documented and not expanded without explicit instruction.
7. Backend readiness: validate Firebase Functions syntax, Firestore rules guardrails, callable authority, emulator evidence, and persistence status before moving more protected authority.
8. Unity AR isolation: inventory WellFitBuddyAR state without deleting or overwriting local Unity assets; plan AR work separately from web beta work.
9. Current execution order: registration/consent hardening, remaining legacy users writer migration, compatibility-rule removal, account lifecycle, pilot telemetry, partner redemption, device evidence, then a small adult Closed Beta.

11. Canonical Truth owner-only protection

The WellFit Beta-1 canonical truth is owner-controlled and read-only for normal agent/autonomous/Codex work.

Protected owner-only concept files:

• project-register/wellfit-beta1-canonical-truth.json
• docs/architecture/WELLFIT_BETA1_CANONICAL_TRUTH.md
• todolist/CODEX_CONTEXT_WELLFIT_BETA1.md

Rules:

• Agents must read these files before Beta-1 governance, roadmap, register, or planning changes that depend on Beta-1 concept truth.
• Agents must not modify these files unless the prompt contains explicit Bernd/owner approval for that change.
• If a task would require edits there without approval, stop and document a blocker plus proposed patch in a non-protected planning/register handoff artifact.