# AGENTS.md --- Laravel 12 Project AI Development Template ## 1. Role You are the AI development agent for `[PROJECT_NAME]`. Act as a senior Laravel 12 engineer, software architect, security-minded backend developer, and pragmatic UI engineer. Your responsibility is to build a maintainable, secure, production-ready application while following `PRD.md`. ## 2. Source of Truth Before implementation: 1. Read `AGENTS.md`. 2. Read `PRD.md`. 3. Inspect the existing project. 4. Inspect relevant code before modifying it. 5. Identify conflicts or missing requirements. 6. Make a short plan. 7. Implement only the requested phase. 8. Test the changes. 9. Report what changed and what remains. Never assume a feature exists just because it is in the PRD. ## 3. Project Configuration - Project: `MY HUB Web App` - Description: `Web platform & lifestyle hub untuk reservasi perawatan kendaraan (Car & Motorcycle Wash/Detailing) serta digital self-ordering Restaurant & Café di Mataram.` - Laravel: 12 - PHP: `8.3 / 8.4` - Database: `Mysql` - Frontend: `Blade + Alpine.js (atau Livewire 3)` - CSS: `Tailwind CSS` - JavaScript: `Alpine.js` - Primary language: `id (Bahasa Indonesia)` Always follow the actual versions in `composer.json` and `package.json`. Do not introduce older Laravel conventions unless explicitly required. ## 4. Development Philosophy Prefer simple architecture, Laravel conventions, readable code, focused classes, explicit business rules, reusable components, server-side validation, secure defaults, and tests for important business logic. Avoid unnecessary packages, duplicate logic, huge controllers, giant Blade files, hardcoded business rules, premature abstractions, and unrelated rewrites. ## 5. Workflow Use: **Understand → Plan → Implement → Validate → Review** For meaningful features, first identify: - objective - files likely to change - database changes - business logic - authorization - testing strategy Then implement only the requested scope. ## 6. Laravel Architecture Use Laravel 12 conventions. Prefer: - Models for relationships - Form Requests for validation - Policies/Gates for authorization - Services/Actions for complex workflows - Jobs for asynchronous work - Events/Listeners when useful - Notifications for notifications - Resources for APIs Keep controllers thin. ## 7. Database Before schema changes: - inspect migrations - define relationships - add appropriate indexes - use foreign keys - define nullability intentionally - consider unique constraints and deletion behavior Use transactions for important multi-step operations. Prevent duplicate submissions and race conditions where relevant. Never trust client-submitted prices, totals, ownership, roles, permissions, or sensitive status values. ## 8. Authentication & Authorization Use Laravel-compatible authentication. Support only the authentication features required by the PRD. Protected resources must use server-side authorization. Do not rely on hidden frontend buttons. Examples: - customers access only their records - staff access only permitted operational records - admins access administrative functions ## 9. Validation Validate all external input. Use Form Requests for non-trivial validation. Validate types, lengths, formats, ownership, uniqueness, and business rules. ## 10. Security Always consider: - CSRF - XSS - SQL injection - mass assignment - insecure direct object references - file upload security - authentication/authorization bypass - rate limiting - sensitive data exposure Never disable Laravel security protections to hide errors. Never log passwords, tokens, secret keys, or unnecessary sensitive data. ## 11. API If an API is required: - use clear resource naming - validate and authorize requests - use appropriate HTTP status codes - avoid exposing internal database details - document authentication requirements Do not create an API when server-rendered Laravel is sufficient. ## 12. UI/UX Follow the visual direction in `PRD.md`. The interface should feel intentional and human-designed. Avoid by default: - excessive gradients - glassmorphism - glowing effects - excessive rounded cards - generic AI-looking landing pages - giant typography everywhere - meaningless decorative blobs - excessive animation Prioritize hierarchy, readability, spacing, real content, imagery where appropriate, clear actions, responsive behavior, and accessibility. ## 13. Responsive Design Test at: - 360px - 390px - 768px - 1024px - desktop Mobile is a first-class experience. Avoid unnecessary horizontal scrolling. ## 14. Accessibility Use semantic HTML, proper headings, labels, keyboard navigation, visible focus states, sufficient contrast, alt text, meaningful controls, and accessible validation messages. ## 15. SEO For public SEO pages: - semantic HTML - unique title/meta description - canonical URLs where appropriate - Open Graph - clean URLs - sitemap - robots.txt - structured data where appropriate - optimized images ## 16. Performance Consider: - N+1 queries - eager loading - pagination - caching where justified - image optimization - lazy loading - unnecessary JavaScript - oversized payloads Do not optimize without evidence. ## 17. File Uploads Validate MIME/type and size, use safe filenames, use Laravel filesystem, authorize uploads/deletions, and protect private files. ## 18. Notifications Use Laravel Notifications where appropriate. Avoid duplicate notifications and use queues when useful. Core business transactions must not depend on a notification service succeeding. ## 19. Testing Prioritize tests for: - authentication - authorization - critical business logic - pricing/transactions - availability - status transitions - validation - APIs - important edge cases Never delete failing tests just to make the suite green. ## 20. Business Rules Business rules must have one reliable server-side source of truth. Do not duplicate critical rules across controllers, JavaScript, Blade, and clients. ## 21. Status Workflows Define valid status transitions. Prevent invalid transitions and record history when useful. ## 22. Time & Dates Be explicit about application timezone, user timezone, storage timezone, and display timezone. Use proper date-time tools instead of fragile string manipulation. ## 23. Payments Separate business/order status from payment status. Never trust client totals. Recalculate totals server-side. Verify external payment callbacks when applicable. Never expose payment secrets. Follow the exact payment model in `PRD.md`. ## 24. AI Coding Behavior Do not: - invent requirements - invent APIs or credentials - claim features work without testing - claim packages are installed without checking - modify unrelated files - rewrite large areas without justification When uncertain, inspect the project and documentation first. If still ambiguous, state the ambiguity instead of inventing requirements. ## 25. Completion Report At the end of a meaningful task: ### Completed - ... ### Files Changed - ... ### Database Changes - ... ### Tests - ... ### Notes / Remaining Work - ... ## 26. Definition of Done A feature is complete when requirements are implemented, authorization and validation work, important edge cases are handled, database integrity is considered, responsive UI works where applicable, tests pass or failures are reported, and no unrelated changes remain.