diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..dde841fb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,182 @@ +# AGENTS.md + +File ini berisi instruksi untuk AI coding agent yang bekerja di repository ini. + +## Project Overview + +Project name: ASO (Laravel + Modules) +Purpose: Platform operasional health insurance/managed care untuk pengelolaan member, corporate policy, claim, monitoring, livechat, dan pelaporan. +Main users: Tim internal operasional, portal client corporate, portal hospital. +Business domain: Healthtech / asuransi kesehatan / manajemen klaim dan layanan kesehatan. + +## Tech Stack + +Backend: PHP 8+, Laravel 9, `nwidart/laravel-modules`. +Frontend: React + TypeScript + Vite (utama di `frontend/dashboard` dan `frontend/client-portal`), plus aset root Laravel (`resources/`, Vite/Mix). +Database: MySQL/MariaDB (via Eloquent ORM + Laravel migrations). +Queue/background jobs: Laravel Queue (`jobs` table tersedia; default testing `sync`). +Cache: Laravel cache (driver mengikuti `.env`, testing pakai `array`). +Auth: Laravel Sanctum, Spatie Permission (`role`/`permission` middleware), sebagian flow JWT untuk integrasi tertentu. +Deployment: Build frontend ke `public/dashboard` dan `public/client-portal`; backend Laravel standar. +Package manager: Composer (PHP), npm/yarn/pnpm (frontend, mixed antar subproject). + +## Local Setup + +Install dependencies: + +```bash +composer install +npm install +cd frontend/dashboard && yarn install +cd ../client-portal && yarn install +``` + +Run app: + +```bash +php artisan serve +npm run dev +cd frontend/dashboard && yarn start +cd ../client-portal && yarn start +``` + +Run tests: + +```bash +php artisan test +``` + +Run lint: + +```bash +cd frontend/dashboard && yarn lint +cd ../client-portal && yarn lint +``` + +Run typecheck: + +```bash +# Belum ada script typecheck standar di root/subproject. +# Jika diperlukan, gunakan tsc manual per frontend setelah konfirmasi tim. +``` + +Run build: + +```bash +npm run production +cd frontend/dashboard && yarn build +cd ../client-portal && yarn build +``` + +Run migrations: + +```bash +php artisan migrate +``` + +## Repository Structure + +```text +app/ # Core Laravel app (models, services, middleware, controllers) +routes/ # Root web/api routes +Modules/ # Domain/module-based backend (Client, Internal, Linksehat, Primaya, HospitalPortal) +Modules/*/Routes/ # Route entry point tiap module +Modules/*/Http/Controllers/Api/ +database/migrations/ # Root migrations +frontend/dashboard/ # React TS admin/internal dashboard +frontend/client-portal/ # React TS client portal +resources/ # Blade/views/assets untuk app Laravel utama +public/ # Public assets + output build frontend +tests/ # PHPUnit tests (Feature/Unit) +``` + +## Architecture Rules + +- Tempatkan business logic di layer service/domain yang sudah ada (`app/Services`, `Modules/*/Services`) dan jaga controller tetap tipis. +- API layer mengikuti pemisahan module: endpoint module didefinisikan di `Modules//Routes/api.php` dengan controller module terkait. +- Untuk perubahan schema, gunakan migration baru; jangan ubah migration lama kecuali ada instruksi eksplisit. +- Untuk frontend, ikuti pattern existing per app (`src/pages`, `src/components`, `src/hooks`, `src/sections`) dan hindari cross-import antar app dashboard/client-portal. +- Testing backend utama menggunakan PHPUnit (`tests/Feature`, `tests/Unit`); tambah regression test untuk perubahan behavior penting. + +## Coding Standards + +- Ikuti pattern existing project sebelum membuat pattern baru. +- Buat perubahan kecil dan fokus. +- Jangan lakukan refactor yang tidak berhubungan. +- Jangan hardcode secrets. +- Jangan bypass validation. +- Jangan bypass auth/permission checks. +- Pilih code yang eksplisit dan mudah dibaca dibanding code yang terlalu clever. +- Tambahkan atau update test jika behavior berubah. + +## Git Rules + +- Jangan commit kecuali user secara eksplisit meminta. +- Jangan push kecuali user secara eksplisit meminta. +- Jangan rewrite git history kecuali user secara eksplisit meminta. +- Tampilkan file yang berubah di final response. + +## Security Rules + +- Jangan pernah print secrets. +- Jangan ubah nilai `.env` asli kecuali diminta secara eksplisit. +- Gunakan `.env-example`/`.env.example` untuk dokumentasi environment variables. +- Validasi auth, permissions, dan scoping corporate/member untuk protected data. +- Untuk endpoint API, pertahankan middleware auth yang ada (`auth:sanctum`, role/permission, middleware khusus module). +- Minta konfirmasi sebelum destructive data changes. + +## Database Rules + +- Gunakan migration system project ini. +- Jangan edit historical migrations kecuali project ini memang mengizinkan. +- Sertakan rollback/safety notes untuk schema changes. +- Pertimbangkan existing production data. +- Perhatikan migrasi dapat berasal dari root `database/migrations` dan modul tertentu. + +## Testing Rules + +Sebelum selesai, jalankan command yang relevan: + +```bash +php artisan test +cd frontend/dashboard && yarn lint +cd frontend/client-portal && yarn lint +``` + +Jika command tidak bisa dijalankan, jelaskan alasannya dan command apa yang harus dijalankan manual. + +## AI Agent Workflow + +Untuk feature work: + +1. Baca file ini. +2. Inspect pattern yang sudah ada. +3. Tulis plan singkat untuk pekerjaan non-trivial. +4. Tanya klarifikasi jika requirement kurang jelas. +5. Implement perubahan kecil dan fokus. +6. Jalankan test/lint/typecheck/build yang relevan. +7. Rangkum file yang berubah, command yang dijalankan, dan risiko. + +Untuk debugging: + +1. Reproduce atau inspect issue. +2. Identifikasi root cause sebelum mengubah code. +3. Buat fix minimal yang aman. +4. Tambahkan regression test jika memungkinkan. +5. Jalankan verification. + +## Final Response Format + +```text +Summary: +- ... + +Files changed: +- ... + +Commands run: +- ... + +Risks / notes: +- ... +``` diff --git a/docs/ai-agent-guide.id.md b/docs/ai-agent-guide.id.md new file mode 100644 index 00000000..fa296147 --- /dev/null +++ b/docs/ai-agent-guide.id.md @@ -0,0 +1,242 @@ +# Panduan Penggunaan AI Agent (ASO) + +Panduan ini menjelaskan cara tim ASO menyiapkan dan memakai AI coding agent secara aman di repository ini. + +Tujuan utamanya adalah memberi AI konteks project, command yang benar, dan batasan safety agar AI membantu lebih cepat tanpa merusak codebase. + +## Prinsip Utama + +1. Human tetap pemilik keputusan final. +2. AI wajib mengikuti konvensi project ASO. +3. AI tidak boleh commit/push kecuali diminta eksplisit. +4. AI harus membuat rencana singkat sebelum perubahan besar/berisiko. +5. AI harus menjalankan verifikasi relevan sebelum menyatakan selesai. +6. Human wajib review area kritikal: security, auth/permission, scoping corporate/member, migration, payments, data deletion, production config. +7. Repository ini wajib memiliki `AGENTS.md` di root. + +## Konteks Project Ini + +ASO adalah platform operasional health insurance/managed care untuk pengelolaan corporate, member, claim, monitoring, livechat, dan pelaporan. + +Stack utama saat ini: + +- Backend: Laravel 9 (`app/`) + modular backend `nwidart/laravel-modules` (`Modules/`) +- Frontend: `frontend/dashboard` dan `frontend/client-portal` (React + TS + Vite), plus assets root Laravel (`resources/`, Vite/Mix) +- Auth/Permission: Sanctum + Spatie Permission (`role`, `permission`) + beberapa flow JWT untuk integrasi tertentu +- Testing backend: PHPUnit (`tests/Feature`, `tests/Unit`) + +## AI Agent Ready untuk Repo ASO + +Repository ini dianggap AI Agent Ready jika AI bisa cepat menjawab: + +- Struktur backend modular dan batas tiap module +- Command setup/run/test/lint/build yang benar untuk root + dua frontend app +- Aturan peletakan business logic +- Aturan auth/permission/scoping corporate-member pada endpoint terlindungi +- Aturan migration aman +- Aturan git (tidak commit/push tanpa instruksi) + +## File Minimum yang Harus Ada + +```text +. +├── AGENTS.md +├── README.md +├── .env-example (dan/atau .env.example) +└── docs/ + └── ai-agent-guide.id.md +``` + +Disarankan ditambah: + +```text +docs/architecture.md +docs/testing.md +docs/database.md +docs/api-contracts.md +``` + +## Command Operasional (Aktual Repo Ini) + +Install dependencies: + +```bash +composer install +npm install +cd frontend/dashboard && yarn install +cd ../client-portal && yarn install +``` + +Menjalankan aplikasi lokal: + +```bash +php artisan serve +npm run dev +cd frontend/dashboard && yarn start +cd ../client-portal && yarn start +``` + +Testing backend: + +```bash +php artisan test +``` + +Lint frontend: + +```bash +cd frontend/dashboard && yarn lint +cd ../client-portal && yarn lint +``` + +Build frontend: + +```bash +npm run production +cd frontend/dashboard && yarn build +cd ../client-portal && yarn build +``` + +Migration: + +```bash +php artisan migrate +``` + +Catatan: + +- Script `typecheck` standar belum tersedia konsisten di root/subproject; jika perlu, jalankan `tsc` manual sesuai kebutuhan task. +- Repo ini memiliki lockfile campuran (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`). Ikuti lockfile dan package manager yang sudah dipakai pada subproject yang disentuh. + +## Struktur Repository Penting + +```text +app/ # Core Laravel app +routes/ # Root routes (web/api) +Modules/ # Module domain (Client, Internal, Linksehat, Primaya, HospitalPortal) +Modules/*/Routes/api.php # API route per module +database/migrations/ # Root migrations +frontend/dashboard/ # Internal/admin frontend +frontend/client-portal/ # Client portal frontend +resources/ # View/assets Laravel utama +public/ # Public assets + output build frontend +tests/ # PHPUnit tests +``` + +## Aturan Arsitektur untuk Agent + +- Gunakan pattern yang sudah ada sebelum menambah pattern baru. +- Jaga controller tetap tipis; letakkan logic di service/domain yang sudah ada (`app/Services`, `Modules/*/Services`). +- Untuk API module, tambahkan route dan controller dalam module yang sesuai; hindari menaruh logic module di tempat acak. +- Jangan cross-import antar frontend app (`dashboard` vs `client-portal`) kecuali memang sudah ada kontrak eksplisit. +- Jika mengubah perilaku endpoint protected, review middleware terkait (`auth:sanctum`, role/permission, middleware custom module). + +## Workflow AI Harian + +### 1. Mulai Task + +- Baca `AGENTS.md`. +- Pahami pattern existing di area yang akan diubah. +- Buat plan singkat untuk task non-trivial. +- Klarifikasi requirement jika masih ambigu. + +### 2. Feature Work + +- Implement perubahan kecil dan fokus. +- Hindari refactor unrelated. +- Tambah/update test saat behavior berubah. +- Jalankan verifikasi relevan. + +### 3. Bug Fixing + +- Reproduce/inspeksi issue terlebih dahulu. +- Temukan root cause. +- Terapkan fix minimal dan aman. +- Tambah regression test jika memungkinkan. + +### 4. Review Sebelum PR + +Periksa: + +- correctness +- security +- auth/permission/scoping +- migration safety +- missing tests +- lint/type/build impact +- perubahan unrelated + +## Definition of Done untuk Task AI + +Task AI belum selesai sampai: + +- Perubahan mengikuti pattern existing. +- Tidak ada perubahan unrelated. +- Test/lint/build relevan sudah dijalankan atau alasannya dijelaskan. +- Risiko migration/auth/scoping dijelaskan jika relevan. +- File berubah dan command yang dijalankan dicatat. + +## Safety Rules (Wajib) + +AI agent tidak boleh: + +- Commit/push/rewrite history tanpa instruksi eksplisit. +- Mengubah `.env` asli tanpa instruksi eksplisit. +- Print secrets ke output/chat. +- Menghapus data/folder besar tanpa konfirmasi. +- Mengubah schema DB tanpa migration baru dan catatan safety. +- Menambah dependency besar tanpa alasan jelas dan dampak. + +## Prompt Siap Pakai untuk Repo Ini + +### Setup / Sinkronisasi Dokumentasi + +```text +Baca AGENTS.md dan docs/ai-agent-guide.id.md. +Sinkronkan dokumentasi AI agent dengan kondisi codebase saat ini. +Validasi command setup/test/lint/build berdasarkan file konfigurasi aktual. +Jangan commit perubahan. +``` + +### Feature Work + +```text +Implement feature berikut: [jelaskan]. +Rules: +- Baca AGENTS.md terlebih dahulu. +- Ikuti pattern existing repo ASO. +- Jangan commit. +- Jalankan verifikasi relevan. +Output akhir wajib: Summary, Files changed, Commands run, Risks/notes. +``` + +### Bug Fixing + +```text +Fix bug berikut: [jelaskan]. +Gunakan systematic debugging: +1. Reproduce/inspeksi issue +2. Temukan root cause +3. Terapkan fix minimal aman +4. Tambah regression test jika memungkinkan +5. Jalankan verifikasi +Jangan commit. +``` + +## Format Final Response Standar + +Gunakan format ini: + +```text +Summary: +- ... + +Files changed: +- ... + +Commands run: +- ... + +Risks / notes: +- ... +``` diff --git a/docs/ai-agent-guide.md b/docs/ai-agent-guide.md new file mode 100644 index 00000000..291a8fc7 --- /dev/null +++ b/docs/ai-agent-guide.md @@ -0,0 +1,242 @@ +# AI Agent Usage Guide (ASO) + +This guide explains how the ASO team should prepare and use AI coding agents safely in this repository. + +The main goal is to provide the AI with correct project context, commands, and safety boundaries so it can help faster without damaging the codebase. + +## Core Principles + +1. Humans make the final decisions. +2. AI must follow ASO project conventions. +3. AI must not commit/push unless explicitly asked. +4. AI should create a short plan before large/risky changes. +5. AI must run relevant verification checks before saying work is done. +6. Humans must review critical areas: security, auth/permission, corporate/member scoping, migrations, payments, data deletion, and production config. +7. This repository must have `AGENTS.md` at the root. + +## Project Context + +ASO is an operational health insurance/managed-care platform for managing corporates, members, claims, monitoring, livechat, and reporting. + +Current main stack: + +- Backend: Laravel 9 (`app/`) + modular backend with `nwidart/laravel-modules` (`Modules/`) +- Frontend: `frontend/dashboard` and `frontend/client-portal` (React + TypeScript + Vite), plus Laravel root assets (`resources/`, Vite/Mix) +- Auth/Permission: Sanctum + Spatie Permission (`role`, `permission`) + some JWT flows for specific integrations +- Backend testing: PHPUnit (`tests/Feature`, `tests/Unit`) + +## AI Agent Ready in ASO Repo + +This repository is considered AI Agent Ready when an AI can quickly answer: + +- Modular backend structure and module boundaries +- Correct setup/run/test/lint/build commands for root + both frontend apps +- Where business logic should live +- Auth/permission/corporate-member scoping rules on protected endpoints +- Safe migration rules +- Git rules (no commit/push without instruction) + +## Minimum Required Files + +```text +. +├── AGENTS.md +├── README.md +├── .env-example (and/or .env.example) +└── docs/ + └── ai-agent-guide.id.md +``` + +Recommended additions: + +```text +docs/architecture.md +docs/testing.md +docs/database.md +docs/api-contracts.md +``` + +## Operational Commands (Current Repo) + +Install dependencies: + +```bash +composer install +npm install +cd frontend/dashboard && yarn install +cd ../client-portal && yarn install +``` + +Run locally: + +```bash +php artisan serve +npm run dev +cd frontend/dashboard && yarn start +cd ../client-portal && yarn start +``` + +Backend tests: + +```bash +php artisan test +``` + +Frontend lint: + +```bash +cd frontend/dashboard && yarn lint +cd ../client-portal && yarn lint +``` + +Frontend build: + +```bash +npm run production +cd frontend/dashboard && yarn build +cd ../client-portal && yarn build +``` + +Migrations: + +```bash +php artisan migrate +``` + +Notes: + +- A standard `typecheck` script is not consistently available across root/subprojects; run manual `tsc` only when needed for the task. +- This repo has mixed lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`). Follow the lockfile and package manager already used in the touched subproject. + +## Key Repository Structure + +```text +app/ # Core Laravel app +routes/ # Root routes (web/api) +Modules/ # Domain modules (Client, Internal, Linksehat, Primaya, HospitalPortal) +Modules/*/Routes/api.php # API route entry per module +database/migrations/ # Root migrations +frontend/dashboard/ # Internal/admin frontend +frontend/client-portal/ # Client portal frontend +resources/ # Main Laravel views/assets +public/ # Public assets + frontend build output +tests/ # PHPUnit tests +``` + +## Architecture Rules for Agents + +- Follow existing patterns before introducing new ones. +- Keep controllers thin; place logic in existing service/domain layers (`app/Services`, `Modules/*/Services`). +- For module APIs, add routes/controllers within the correct module; avoid placing module logic in random locations. +- Do not cross-import between frontend apps (`dashboard` vs `client-portal`) unless there is an explicit existing contract. +- When changing protected endpoint behavior, review related middleware (`auth:sanctum`, role/permission, module-specific middleware). + +## Daily AI Workflow + +### 1. Start a Task + +- Read `AGENTS.md`. +- Understand existing patterns in the area you will change. +- Create a short plan for non-trivial work. +- Clarify ambiguous requirements. + +### 2. Feature Work + +- Keep changes small and focused. +- Avoid unrelated refactors. +- Add/update tests when behavior changes. +- Run relevant verification commands. + +### 3. Bug Fixing + +- Reproduce/inspect the issue first. +- Find the root cause. +- Apply a minimal, safe fix. +- Add a regression test when possible. + +### 4. Pre-PR Review + +Check: + +- correctness +- security +- auth/permission/scoping +- migration safety +- missing tests +- lint/type/build impact +- unrelated changes + +## Definition of Done for AI Tasks + +AI work is not done until: + +- Changes follow existing patterns. +- No unrelated files are changed. +- Relevant test/lint/build checks are run or failures are explained. +- Migration/auth/scoping risks are explained when relevant. +- Changed files and commands run are documented. + +## Safety Rules (Mandatory) + +AI agents must not: + +- Commit/push/rewrite history without explicit instruction. +- Modify real `.env` values without explicit instruction. +- Print secrets in chat/output. +- Delete large data/folders without confirmation. +- Change DB schema without new migrations and safety notes. +- Add major dependencies without clear justification and impact. + +## Ready-to-Use Prompts for This Repo + +### Setup / Documentation Sync + +```text +Read AGENTS.md and docs/ai-agent-guide.id.md. +Sync AI-agent documentation with the current codebase state. +Validate setup/test/lint/build commands against actual config files. +Do not commit changes. +``` + +### Feature Work + +```text +Implement this feature: [describe]. +Rules: +- Read AGENTS.md first. +- Follow existing ASO repository patterns. +- Do not commit. +- Run relevant verification commands. +Final output must include: Summary, Files changed, Commands run, Risks/notes. +``` + +### Bug Fixing + +```text +Fix this bug: [describe]. +Use systematic debugging: +1. Reproduce/inspect issue +2. Find root cause +3. Apply minimal safe fix +4. Add regression test if possible +5. Run verification +Do not commit. +``` + +## Standard Final Response Format + +Use this format: + +```text +Summary: +- ... + +Files changed: +- ... + +Commands run: +- ... + +Risks / notes: +- ... +```