agents.md

AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md
+
+## Project Goal
+Build a reliable, maintainable salon booking platform with Django (backend) and React (frontend), optimized for KSA needs (phone auth, local payments) while keeping a clean path to scale.
+
+## Current Plan (Roadmap)
+### Phase 1: Core MVP Reliability
+- Phone-first auth with OTP (SMS/WhatsApp), rate limits, and social login.
+- Booking integrity (availability, staff schedules, overlap prevention).
+- Payments via Moyasar (payment creation, webhooks, reconciliation).
+- Notifications for booking lifecycle.
+- Tests for critical flows.
+
+### Phase 2: Manager Ops
+- Salon/staff/service management.
+- Calendar view + rescheduling/cancellation rules.
+- Reviews/ratings with moderation and recompute.
+- Reports (revenue, popular services, customer trends).
+
+### Phase 3: Scale & Compliance
+- Audit logs and data export.
+- PDPL/GDPR retention policy.
+- Observability and performance baselines.
+
+## Reliability Standards (Non‑Negotiable)
+- Every new feature ships with tests.
+- Avoid introducing regressions without covering a fix or guardrail.
+- Payment and booking flows must be idempotent and auditable.
+- Phone auth must be rate‑limited and safe from abuse.
+
+## Testing Expectations
+### Backend
+- Use `pytest` + `pytest-django`.
+- Tests live beside apps (`apps/<app>/tests/`).
+- Minimum coverage: auth, booking validation, payment state transitions.
+
+### Frontend
+- Use `vitest` + Testing Library.
+- Critical flows covered: search, booking form, auth state.
+
+## Code Style & Practices
+- Keep business logic in services (avoid fat views).
+- Use explicit, readable model fields and serializers.
+- Small, well‑named functions > monolithic handlers.
+- Prefer predictable error responses (HTTP status + `detail`).
+
+## Known Gaps (Tracked)
+- See `docs/risks.md` for current gaps/risks to address.
+
+## Environment Notes
+- Python is invoked as `python3`.
+- A virtualenv is in use.
+- DB: PostgreSQL in production, SQLite allowed for local dev.
+
+## Collaboration Rules for Agents
+- Don’t delete or rewrite unrelated work.
+- Avoid destructive git commands unless explicitly asked.
+- Update `docs/risks.md` when adding or closing a significant gap.
+- Keep README instructions current when tooling changes.