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

.
├── AGENTS.md
├── README.md
├── .env-example (and/or .env.example)
└── docs/
    └── ai-agent-guide.id.md

Recommended additions:

docs/architecture.md
docs/testing.md
docs/database.md
docs/api-contracts.md

Operational Commands (Current Repo)

Install dependencies:

composer install
npm install
cd frontend/dashboard && yarn install
cd ../client-portal && yarn install

Run locally:

php artisan serve
npm run dev
cd frontend/dashboard && yarn start
cd ../client-portal && yarn start

Backend tests:

php artisan test

Frontend lint:

cd frontend/dashboard && yarn lint
cd ../client-portal && yarn lint

Frontend build:

npm run production
cd frontend/dashboard && yarn build
cd ../client-portal && yarn build

Migrations:

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

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

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

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

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:

Summary:
- ...

Files changed:
- ...

Commands run:
- ...

Risks / notes:
- ...