Purpose: This file briefs AI coding agents (e.g., Codex) on how to work in this repo safely and effectively: how to set up, run, test, follow guardrails, and ship changes.
Sign in to like and favorite skills
Purpose: This file briefs AI coding agents (e.g., Codex) on how to work in this repo safely and effectively: how to set up, run, test, follow guardrails, and ship changes.
src/services/taca-da-pingapreview-taca-da-pingadevelop-taca-da-pingasrc/services/leaderboard.jssrc/services/teams.jsfeature/*developproductiondevelopproductionWhen implementing a task:
Create a feature branch
feature/<short-slug>developInstall & validate
corepack enable yarn install yarn lint yarn typecheck || echo "no TS yet" yarn test yarn build
Use the services layer for data access
Never import Firestore in components or pages.
Add/modify functions under src/services/* and unit-test them.
Follow coding guardrails
Write tests
Unit tests for services and hooks (Vitest).
Component tests with React Testing Library.
Firestore rules tests using the emulator.
E2E (Playwright) for happy paths when affected.
Run the full suite locally (same as CI) and ensure green before opening a PR.
Open a PR to develop
Include test updates and doc updates when behavior/config changes.
Request multi-file suggestions review from Codex Cloud.
Install deps: corepack enable && yarn install
Start dev server: yarn dev → http://localhost:5173 (Vite)
Preview prod build: yarn preview
Start emulators: firebase emulators:start --only firestore,auth
Lint: yarn lint
Typecheck: yarn typecheck (noop acceptable until TS lands)
Unit/Component: yarn test
Unit/Component (CI): yarn test:ci
Rules (emulator): yarn test:rules
E2E (Playwright): yarn e2e
File/Folder Map
src/ components/ # Presentational & container components (NO Firestore imports) pages/ # Route-level components (NO Firestore imports) services/ # All Firestore/Auth I/O lives here hooks/ lib/ assets/
Public READ for leaderboard & audit events.
Admin-only WRITE to leaderboard/events/app_config.
“Add pinga” increments must be positive and bounded (e.g., 1..5).
Update or add Firestore rules only with emulator tests in the same PR.
App invariants are enforced both at service layer (validation) and Firestore rules (authoritative); verify via
yarn test:rulesDo NOT commit secrets. Use .env (dev only), Firebase project config for prod.
See docs/CONFIG.md for required env keys and environment separation.
Commit messages: concise imperative (“fix: correct delta validation”).
PR description: summary, scope, test plan, screenshots if UI.
If you modify behavior, update README.md and docs/* accordingly.
GitHub Actions workflow name must be: CI / Lint / Typecheck / Test / Build
Job should: install, lint, typecheck, test (CI mode), build.
Your PR must pass CI before merge.
Additional workflows:
pr-preview.ymlhttps://preview-taca-da-pinga.web.appdeploy-develop.ymlhttps://develop-taca-da-pinga.web.appRequired secrets (set once in GitHub → Settings → Secrets): the
VITE_FIREBASE_*FIREBASE_SERVICE_ACCOUNTFIREBASE_PROJECT_IDRelease steps in docs/RELEASE.md.
If a bad deploy ships, revert the merge commit and redeploy per docs.
Don’t broaden Firestore rules without emulator tests.
Don’t access Firestore in components/pages.
Don’t commit or rotate secrets; escalate to a human maintainer.
CODING_GUARDRAILS.md — style, structure, review checklist.
docs/DEV.md — local dev & emulator guide.
docs/CONFIG.md — env variables & environments.
docs/TESTING.md — test pyramid & commands.
docs/RELEASE.md — release & rollback process.