aso/docs/ai-agent-guide.md

# 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:
- ...
```