AGENTS.md

1# Krayin CRM: Agent Instructions
2 
3This repository ships reusable **agent skills** for developing Krayin CRM. These
4instructions apply to all AI coding agents (Claude Code, Codex, Copilot, Cursor,
5Kilo Code, etc.).
6 
7---
8 
9## Framework Context
10 
11- **Product:** Krayin CRM (Webkul) — an open-source Laravel CRM.
12- **Stack:** Laravel `^12.0`, PHP `^8.3`, Pest `^3.0`, Laravel Pint `^1.18`.
13- **Follow Krayin's own conventions** — use the patterns already present in this
14  repository's modules; do not import patterns from other Laravel products.
15- **Module location:** `packages/Webkul/{ModuleName}/src/`
16- **Core modules (reference implementations):** `Lead`, `Contact`, `Activity`,
17  `Quote`, `Product`, `User`, `Attribute`, `Core`, `Admin`, `DataGrid`.
18 
19---
20 
21## Skills
22 
23Workspace skills live in `.github/skills/` (canonical source) and are symlinked
24into every agent runtime (`.ai`, `.claude`, `.codex`, `.cursor`, `.kilocode`).
25See [.github/skills/README.md](.github/skills/README.md) for the standard.
26 
27| Skill | Use when |
28|-------|----------|
29| `crm-package-development` | Creating a new CRM package/module or extending CRM functionality without touching core. |
30| `pest-testing` | Writing or debugging unit/feature tests with Pest. |
31 
32Read the relevant `SKILL.md` before starting work in its domain. Do not restate
33skill content here — keep details in the skills.
34 
35---
36 
37## Critical Conventions (Never Deviate)
38 
39- **Never modify core Krayin files** unless explicitly required. Extend behavior
40  through a package under `packages/Webkul/`.
41- **All schema changes go through migrations** — never edit the database directly.
42- **Follow the existing module layout** (Providers, Models, Contracts,
43  Repositories, Http/Controllers, Routes, Database/Migrations, Resources/views,
44  Config). The `crm-package-development` skill documents the full structure.
45- **Repository pattern:** models are accessed through repositories bound via
46  contracts in the service provider — match the surrounding modules.
47- **Translations follow the views:** a package gets its own `Resources/lang/`
48  **only if** it also has `Resources/views/`. Every view-less package keeps its
49  strings in the Admin package under `admin::app.*` — no lang directory, no
50  `loadTranslationsFrom()`. See the `crm-package-development` skill.
51- **Every fix and feature updates `CHANGELOG.md`** in the same change, under the
52  topmost unreleased version heading. Never invent a `#PR` number and never bump
53  `KRAYIN_VERSION` outside a release commit. See the `crm-package-development`
54  skill for the entry format and tags.
55- **Preserve backward compatibility** so the CRM stays upgrade-safe.
56 
57---
58 
59## Development Cycle
60 
61```bash
62composer install            # install PHP dependencies
63php artisan migrate          # run migrations
64php artisan test --compact   # run the Pest test suite
65./vendor/bin/pint            # format code (PSR-12 via Laravel Pint)
66```
67 
68- Add tests for new behavior; follow the `pest-testing` skill.
69- Run `./vendor/bin/pint` before committing — CI applies Pint formatting.
70- Validate the skills setup with `bash bin/validate-skills.sh`.
71