# AGENTS.md — Joshen Backend Instructions for every coding agent in this repository. Claude Code loads this through `CLAUDE.md`, which also imports every steering file. Codex / Antigravity / OpenCode cannot import files: open the files the [task routing table](#task-routing) lists, or load the matching `joshen-*` skill. **Joshen (جوشن)** is a platform for booking beauty and home personal-care services in Saudi Arabia (the BRD calls it by its working title, "Khadami"). This repo is the **Laravel 13 API** behind four apps: `client`, `provider`, `delivery` (Flutter) and `admin` (React JS). Per-surface docs are in `docs/{surface}/`. ## Read first 1. `docs/PROJECT_BRAIN.md` — feature map: BRD IDs, surface, doc file, version, status, phase. 2. `.kiro/steering/` — the mandatory rules (see the routing table). 3. `docs/brd/BRD-Khadami-Project-Guide-en.md` — only the sections for your feature IDs. 4. `docs/DECISIONS.md` — client decisions (D1–D4), BRD answers (DEC-xx), technical choices (TD-xx). 5. `docs/database/` — `db-schema.sql` is the target data model; `README.md` maps it onto the Laravel base (TD-08). ## Task routing | Task | Load skill | Rule files to read (`.kiro/steering/`) | |------|-----------|----------------------------------------| | Build, change, or fix a feature / endpoint | `joshen-feature` | `business-logic.md`, `api-surfaces.md`, `architecture.md`, `code-standards.md`, `postman-collection.md` | | Admin CRUD screen | `joshen-feature` | + `crud-conventions.md`, `base-project-style.md` | | Migrations, models, enums, seeders | `joshen-migrations` | `business-logic.md` + `docs/database/README.md` | | Write or bump a feature doc, changelog, registry | `joshen-feature-docs` | `feature-documentation.md` | | Ambiguous requirement, BRD/screen/schema conflict, record a decision | `joshen-decisions` | `business-logic.md` | | Tests | `testing-best-practices` (Boost) | `feature-documentation.md` (AC-ID naming, MySQL test DB) | | Postman collection: request field docs, response examples, coverage gate | `joshen-postman` | `postman-collection.md` | `joshen-*` skills live in `.agents/skills/` and are mirrored to `.claude/skills/`; re-sync after editing one. Steering file summaries, the mirror command, Codex command rules, and MCP servers: `docs/AGENT_SETUP.md`. ## Non-negotiables - Every feature traces to BRD IDs or D1–D4 / schema design additions. No invented scope; open decisions are never silently resolved — use `DECISIONS.md` or ask. - Business tables match `docs/database/db-schema.sql` exactly; change the schema in the same commit if a migration must differ. - Business rules live in `app/Domain/{Module}/Rules`, not in controllers or requests. - Responses always use `json()` → `{status, message, data}`. - Clients only see **uuids** (TD-19): routes, request fields, filters, headers, and response `id`s use the uuid, foreign keys use the integer. Translation and pure pivot/link tables have no UUID (TD-22). - A feature is not done until its doc in `docs/{surface}/{slug}.md` is written or bumped, and the `PROJECT_BRAIN.md` registry and `docs/CHANGELOG.md` are updated. Response examples in docs are real (from tests or Postman), never imagined. - Every endpoint you touch leaves its Postman entry complete (TD-56): request keys described in `bodyParameters()` / `queryParameters()`, real responses captured with `recordExample()`, `php artisan postman:generate --check` passing. The coverage baseline only shrinks. Never hand-edit `docs/postman-collection.json`. ## Commands ```bash php artisan test --compact [--filter=AcCust012] composer style # Pint env RECORD_API_EXAMPLES=1 php artisan test --compact # capture Postman examples (TD-81) php artisan postman:generate --check # Postman gate (TD-56) ``` More commands (route:list, `--forget-example`, style:check): `docs/AGENT_SETUP.md`. ## Rule precedence The `` block below is generated by Laravel Boost and is rewritten on `boost:update` — do not edit inside it. When it conflicts with the project rules above or in `.kiro/steering/`, **the project rules win**: - **Documentation files:** feature docs are always requested (`feature-documentation.md`). - **New folders:** `app/Domain/{Module}`, `routes/api/v1/{provider,delivery}.php`, and the `Provider` / `Delivery` surface folders are pre-approved by `api-surfaces.md`. - **Comments:** PHPDoc on every class and public/protected method; short `#` why-comments allowed (`code-standards.md`). - **Generators:** prefer `make:crud`, `make:action`, `make:query`, `make:command-service`, `make:value-object` over `make:class`. - **Deployment:** the project is not on Laravel Cloud; ignore Cloud suggestions. === === foundation rules === # Laravel Boost Guidelines ## Foundational Context This application is a Laravel application running on PHP 8.4. Always use the APIs that match the installed major version of each package — do not assume a version. Before relying on a package's API, confirm its installed version: - PHP packages: run `composer show --direct` to list direct dependencies with versions, or `composer show ` for a single package. - JS packages: check `package.json` for the installed versions. ## Skills Activation This project has domain-specific skills available in `**/skills/**`. You MUST activate the relevant skill whenever you work in that domain—don't wait until you're stuck. ## Conventions - You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming. - Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`. - Check for existing components to reuse before writing a new one. ## Verification Scripts - Do not create verification scripts or tinker when tests cover that functionality and prove they work. Unit and feature tests are more important. ## Application Structure & Architecture - Stick to existing directory structure; don't create new base folders without approval. - Do not change the application's dependencies without approval. ## Frontend Bundling - If a frontend change doesn't show in the UI or you get a "Unable to locate file in Vite manifest" error, run `npm run build` or ask the user to run `npm run dev` or `composer run dev`. ## Documentation Files - You must only create documentation files if explicitly requested by the user. === boost rules === # Laravel Boost ## Tools - Laravel Boost is an MCP server with tools designed specifically for this application. Prefer Boost tools over manual alternatives like shell commands or file reads. - Use `database-query` to run read-only queries against the database instead of writing raw SQL in tinker. - Use `database-schema` to inspect table structure before writing migrations or models. - Use `get-absolute-url` to resolve the correct scheme, domain, and port for project URLs. Always use this before sharing a URL with the user. - Use `browser-logs` to read browser logs, errors, and exceptions. Only recent logs are useful, ignore old entries. ## Searching Documentation (IMPORTANT) - Use `search-docs` before changes that depend on Laravel ecosystem APIs, behavior, configuration, or version-specific syntax. Skip it for copy-only edits and other changes where package documentation is irrelevant. Reuse sufficient results already in context instead of searching again. - Pass a `packages` array to scope results when you know which packages are relevant. - Use multiple broad, topic-based queries: `['rate limiting', 'routing rate limiting', 'routing']`. Expect the most relevant results first. - Do not add package names to queries because package info is already shared. Use `test resource table`, not `filament 4 test resource table`. ### Search Syntax 1. Use words for auto-stemmed AND logic: `rate limit` matches both "rate" AND "limit". 2. Use `"quoted phrases"` for exact position matching: `"infinite scroll"` requires adjacent words in order. 3. Combine words and phrases for mixed queries: `middleware "rate limit"`. 4. Use multiple queries for OR logic: `queries=["authentication", "middleware"]`. ## Project Rules - This project contains committed, area-grouped rules in `.ai/rules` when that directory exists, including path-scoped framework guidelines under `.ai/rules/boost`. Before you enter plan mode or create/edit any file, you MUST first: open @.ai/rules/index.md (it maps file globs to rule files), read every rule file whose globs cover the path(s) in scope, and run `grep -rin 'keyword' .ai/rules` to catch what a path match alone misses. Do not write code until you have read and are following every matching rule. If `.ai/rules` does not exist, continue without it. ## Artisan - Run Artisan commands directly via the command line (e.g., `php artisan route:list`). Use `php artisan list` to discover available commands and `php artisan [command] --help` to check parameters. - Inspect routes with `php artisan route:list`. Filter with: `--method=GET`, `--name=users`, `--path=api`, `--except-vendor`, `--only-vendor`. - Read configuration values using dot notation: `php artisan config:show app.name`, `php artisan config:show database.default`. Or read config files directly from the `config/` directory. ## Tinker - Execute PHP in app context for debugging and testing code. Do not create models without user approval, prefer tests with factories instead. Prefer existing Artisan commands over custom tinker code. - Always use single quotes to prevent shell expansion: `php artisan tinker --execute 'Your::code();'` - Double quotes for PHP strings inside: `php artisan tinker --execute 'User::where("active", true)->count();'` === php rules === # PHP - Always use curly braces for control structures, even for single-line bodies. - Use PHP 8 constructor property promotion: `public function __construct(public GitHub $github) { }`. Do not leave empty zero-parameter `__construct()` methods unless the constructor is private. - Use explicit return type declarations and type hints for all method parameters: `function isAccessible(User $user, ?string $path = null): bool` - Follow existing application Enum naming conventions. - Prefer PHPDoc blocks over inline comments. Only add inline comments for exceptionally complex logic. - Use array shape type definitions in PHPDoc blocks. === deployments rules === # Deployment - Laravel can be deployed using [Laravel Cloud](https://cloud.laravel.com/), which is the fastest way to deploy and scale production Laravel applications. === tests rules === # Test Enforcement - Add or update tests for behavior and logic changes when a test provides meaningful regression coverage. - Pure copy, styling, and layout-only changes do not require new or updated tests. - When test coverage applies, run the affected tests and ensure they pass. - Test the changed behavior and its important failure modes, but do not add tests beyond them. - Read the `testing-best-practices` skill before writing tests. === laravel/core rules === # Do Things the Laravel Way - Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using `php artisan list` and check their parameters with `php artisan [command] --help`. - If you're creating a generic PHP class, use `php artisan make:class`. - Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior. ### Model Creation - When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `php artisan make:model --help` to check the available options. ## APIs & Eloquent Resources - For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention. ## URL Generation - When generating links to other pages, prefer named routes and the `route()` function. ## Testing - When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model. - Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`. - When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests. === pint/core rules === # Laravel Pint Code Formatter - If you have modified any PHP files, you must run `vendor/bin/pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style. - Do not run `vendor/bin/pint --test --format agent`, simply run `vendor/bin/pint --format agent` to fix any formatting issues. === phpunit/core rules === # PHPUnit - This project uses PHPUnit. Create tests with `php artisan make:test --phpunit {name}`. - Do not include the test suite directory in `{name}`. Use `SomeFeatureTest`, not `Feature/SomeFeatureTest`. - Read the `testing-best-practices` skill for guidance on coverage, naming, structure, dependency isolation, and review. ## Running Tests - Run the narrowest set of tests that covers the change. Pass a file path or `--filter=testName` to `php artisan test --compact`. - Rerun a test after each change to it. - Run `vendor/bin/phpunit` to call the test runner directly. It accepts the same file path and `--filter=testName` arguments.