@mohammadhprp/system-prompt 0.12.2 → 0.12.4

package/framework/skills/laravel-best-practices/SKILL.md

@@ -1,229 +1,69 @@
 ---
 name: laravel-best-practices
-description: "Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code."
-version: 0.1.0
+description: "Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns."
+license: MIT
+metadata:
+  author: laravel
 ---
 
 # Laravel Best Practices
 
-Best practices for Laravel, prioritized by impact. Each rule teaches what to do and why. For exact API syntax, verify with `search-docs`.
+Best practices for Laravel, organized as an index of reference files. Each reference file teaches what to do and why. For exact API syntax, verify with `search-docs`.
 
 ## Consistency First
 
-Before applying any rule, check what the application already does. Laravel offers multiple valid approaches — the best choice is the one the codebase already uses, even if another pattern would be theoretically better. Inconsistency is worse than a suboptimal pattern.
+Before applying any reference, check what the application already does. Laravel offers multiple valid approaches, and the best choice is the one the codebase already uses, even if another pattern would be theoretically better. Inconsistency is worse than a suboptimal pattern.
 
-Check sibling files, related controllers, models, or tests for established patterns. If one exists, follow it — don't introduce a second way. These rules are defaults for when no pattern exists yet, not overrides.
-
-## Quick Reference
-
-### 1. Database Performance → `references/db-performance.md`
-
-- Eager load with `with()` to prevent N+1 queries
-- Enable `Model::preventLazyLoading()` in development
-- Select only needed columns, avoid `SELECT *`
-- `chunk()` / `chunkById()` for large datasets
-- Index columns used in `WHERE`, `ORDER BY`, `JOIN`
-- `withCount()` instead of loading relations to count
-- `cursor()` for memory-efficient read-only iteration
-- Never query in Blade templates
-
-### 2. Advanced Query Patterns → `references/advanced-queries.md`
-
-- `addSelect()` subqueries over eager-loading entire has-many for a single value
-- Dynamic relationships via subquery FK + `belongsTo`
-- Conditional aggregates (`CASE WHEN` in `selectRaw`) over multiple count queries
-- `setRelation()` to prevent circular N+1 queries
-- `whereIn` + `pluck()` over `whereHas` for better index usage
-- Two simple queries can beat one complex query
-- Compound indexes matching `orderBy` column order
-- Correlated subqueries in `orderBy` for has-many sorting (avoid joins)
-
-### 3. Security → `references/security.md`, `references/passport.md`, `references/spatie-laravel-permission.md`
-
-- Define `$fillable` or `$guarded` on every model, authorize every action via policies or gates
-- No raw SQL with user input — use Eloquent or query builder
-- `{{ }}` for output escaping, `@csrf` on all POST/PUT/DELETE forms, `throttle` on auth and API routes
-- Validate MIME type, extension, and size for file uploads
-- Never commit `.env`, use `config()` for secrets, `encrypted` cast for sensitive DB fields
-
-### 4. Caching → `references/caching.md`
-
-- `Cache::remember()` over manual get/put
-- `Cache::flexible()` for stale-while-revalidate on high-traffic data
-- `Cache::memo()` to avoid redundant cache hits within a request
-- Cache tags to invalidate related groups
-- `Cache::add()` for atomic conditional writes
-- `once()` to memoize per-request or per-object lifetime
-- `Cache::lock()` / `lockForUpdate()` for race conditions
-- Failover cache stores in production
-
-### 5. Eloquent Patterns → `references/eloquent.md`
-
-- Correct relationship types with return type hints
-- Local scopes for reusable query constraints
-- Global scopes sparingly — document their existence
-- Attribute casts in the `casts()` method
-- Cast date columns, use Carbon instances in templates
-- `whereBelongsTo($model)` for cleaner queries
-- Never hardcode table names — use `(new Model)->getTable()` or Eloquent queries
-
-### 6. Validation & Forms → `references/validation.md`
-
-- Form Request classes, not inline validation
-- Array notation `['required', 'email']` for new code; follow existing convention
-- `$request->validated()` only — never `$request->all()`
-- `Rule::when()` for conditional validation
-- `after()` instead of `withValidator()`
-
-### 7. Configuration → `references/config.md`
-
-- `env()` only inside config files
-- `App::environment()` or `app()->isProduction()`
-- Config, lang files, and constants over hardcoded text
-
-### 8. Testing Patterns → `references/testing.md`, `references/pest-testing.md`
-
-- `LazilyRefreshDatabase` over `RefreshDatabase` for speed
-- `assertModelExists()` over raw `assertDatabaseHas()`
-- Factory states and sequences over manual overrides
-- Use fakes (`Event::fake()`, `Exceptions::fake()`, etc.) — but always after factory setup, not before
-- `recycle()` to share relationship instances across factories
-
-### 9. Queue & Job Patterns → `references/queue-jobs.md`
-
-- `retry_after` must exceed job `timeout`; use exponential backoff `[1, 5, 10]`
-- `ShouldBeUnique` to prevent duplicates; `ShouldBeUniqueUntilProcessing` for early lock release
-- Always implement `failed()`; with `retryUntil()`, set `$tries = 0`
-- `RateLimited` middleware for external API calls; `Bus::batch()` for related jobs
-- Horizon for complex multi-queue scenarios
-
-### 10. Routing & Controllers → `references/routing.md`
-
-- Implicit route model binding
-- Scoped bindings for nested resources
-- `Route::resource()` or `apiResource()`
-- Methods under 10 lines — extract to actions/services
-- Type-hint Form Requests for auto-validation
-
-### 11. HTTP Client → `references/http-client.md`
-
-- Explicit `timeout` and `connectTimeout` on every request
-- `retry()` with exponential backoff for external APIs
-- Check response status or use `throw()`
-- `Http::pool()` for concurrent independent requests
-- `Http::fake()` and `preventStrayRequests()` in tests
-
-### 12. Events, Notifications & Mail → `references/events-notifications.md`, `references/mail.md`
-
-- Event discovery over manual registration; `event:cache` in production
-- `ShouldDispatchAfterCommit` / `afterCommit()` inside transactions
-- Queue notifications and mailables with `ShouldQueue`
-- On-demand notifications for non-user recipients
-- `HasLocalePreference` on notifiable models
-- `assertQueued()` not `assertSent()` for queued mailables
-- Markdown mailables for transactional emails
-
-### 13. Error Handling → `references/error-handling.md`
-
-- `report()`/`render()` on exception classes or in `bootstrap/app.php` — follow existing pattern
-- `ShouldntReport` for exceptions that should never log
-- Throttle high-volume exceptions to protect log sinks
-- `dontReportDuplicates()` for multi-catch scenarios
-- Force JSON rendering for API routes
-- Structured context via `context()` on exception classes
-
-### 14. Task Scheduling → `references/scheduling.md`
-
-- `withoutOverlapping()` on variable-duration tasks
-- `onOneServer()` on multi-server deployments
-- `runInBackground()` for concurrent long tasks
-- `environments()` to restrict to appropriate environments
-- `takeUntilTimeout()` for time-bounded processing
-- Schedule groups for shared configuration
-
-### 15. Architecture → `references/architecture.md`
-
-- Single-purpose Action classes; dependency injection over `app()` helper
-- Prefer official Laravel packages and follow conventions, don't override defaults
-- Default to `ORDER BY id DESC` or `created_at DESC`; `mb_*` for UTF-8 safety
-- `defer()` for post-response work; `Context` for request-scoped data; `Concurrency::run()` for parallel execution
-
-### 16. Migrations → `references/migrations.md`
-
-- Generate migrations with `php artisan make:migration`
-- `constrained()` for foreign keys
-- Never modify migrations that have run in production
-- Add indexes in the migration, not as an afterthought
-- Mirror column defaults in model `$attributes`
-- Reversible `down()` by default; forward-fix migrations for intentionally irreversible changes
-- One concern per migration — never mix DDL and DML
-
-### 17. Collections → `references/collections.md`
-
-- Higher-order messages for simple collection operations
-- `cursor()` vs. `lazy()` — choose based on relationship needs
-- `lazyById()` when updating records while iterating
-- `toQuery()` for bulk operations on collections
-
-### 18. Blade & Views → `references/blade-views.md`, `references/tailwindcss.md`
-
-- `$attributes->merge()` in component templates
-- Blade components over `@include`; `@pushOnce` for per-component scripts
-- View Composers for shared view data
-- `@aware` for deeply nested component props
-
-### 19. Conventions & Style → `references/style.md`
-
-- Follow Laravel naming conventions for all entities
-- Prefer Laravel helpers (`Str`, `Arr`, `Number`, `Uri`, `Str::of()`, `$request->string()`) over raw PHP functions
-- No JS/CSS in Blade, no HTML in PHP classes
-- Code should be readable; comments only for config files
-
-### 20. Feature Flags → `references/pennant.md`
-
-- `Feature::define()` to define features with resolver callbacks
-- `Feature::active()` / `@feature` Blade directive to check features
-- Scope features to specific users/entities with `Feature::for()`
-- `Feature::activate()` / `deactivate()` for runtime control
-
-### 21. Monitoring → `references/pulse.md`
-
-- Gate-protect the dashboard with `viewPulse` gate
-- Configure built-in recorders in `config/pulse.php` (SlowQueries, SlowRequests, Exceptions, Queues, etc.)
-- Redis ingest for production performance; run `pulse:work` to drain the stream
-- Custom cards via Livewire components extending `Pulse\Card`
-- `Pulse::filter()` to exclude entries; `Pulse::resolveAuthenticatedUserId()` for multi-model apps
-- `pulse:check` daemon required for Servers card
-
-### 22. Full-Text Search → `references/scout.md`
-
-- Add `Searchable` trait to models for automatic index sync
-- Choose engine: Database, Collection, Algolia, Meilisearch, Typesense
-- `toSearchableArray()` to control indexed data; `searchableAs()` for custom index names
-- `Model::search('query')->where(...)->paginate()` for search queries
-- `scout:import` / `scout:flush` for index management; `scout:sync-index-settings` for engine config
-- `Model::withoutSyncingToSearch()` / `SCOUT_DRIVER=null` for testing
-
-### 23. Backup → `references/spatie-laravel-backup.md`
-
-- Schedule `backup:run`, `backup:clean`, `backup:monitor` in console kernel
-- Configure sources, destinations, notifications in `config/backup.php`
-- Custom cleanup strategies extending `CleanupStrategy`
-- Custom health checks extending `HealthCheck`
-- Enable encryption and Gzip compression via config
-
-### 24. Media Library → `references/spatie-medialibrary.md`
-
-- Implement `HasMedia` interface + `InteractsWithMedia` trait on models
-- `addMedia()` / `addMediaFromRequest()` for file uploads
-- Media collections to organize related files per model
-- Conversions for image processing (thumbnails, crops, etc.)
-- Responsive images via conversion `withResponsiveImages()`
+Check sibling files, related controllers, models, or tests for established patterns. If one exists, follow it. Don't introduce a second way. These references are defaults for when no pattern exists yet, not overrides.
 
 ## How to Apply
 
-Always use a sub-agent to read rule files and explore this skill's content.
-
-1. Identify the file type and select relevant sections (e.g., migration → §16, controller → §1, §3, §5, §6, §10)
-2. Check sibling files for existing patterns — follow those first per Consistency First
-3. Verify API syntax with `search-docs` for the installed Laravel version
+1. Check the changed files, nearby code, project configuration, and relevant tests for established patterns. Deviate only for a correctness or security defect, and call the deviation out.
+2. Map every affected concern to the reference index below. Read each mapped reference file before editing. Skip unrelated reference files.
+3. Make the smallest coherent change. Keep the application's architecture and naming instead of introducing a second pattern for the same job.
+4. Verify version-sensitive Laravel APIs for the installed version with `search-docs`, or inspect the installed framework when it is unavailable.
+5. Run the narrowest relevant tests first, then the project's formatting and static-analysis checks when the change warrants them.
+6. Re-read the diff against every mapped reference before finishing.
+
+## References Index
+
+Cross-cutting changes often need more than one reference file.
+
+| Concern | Read |
+| --- | --- |
+| Query count, eager loading, indexes, large datasets | [`references/db-performance.md`](references/db-performance.md) |
+| Production monitoring, slow queries, exception dashboards | [`references/pulse.md`](references/pulse.md) |
+| Subqueries, aggregates, complex ordering and query plans | [`references/advanced-queries.md`](references/advanced-queries.md) |
+| Models, relationships, scopes, casts | [`references/eloquent.md`](references/eloquent.md) |
+| Full-text search, indexing, searchable models | [`references/scout.md`](references/scout.md) |
+| Authentication, authorization, input safety, secrets, uploads | [`references/security.md`](references/security.md) |
+| OAuth2 servers, clients, token authentication | [`references/passport.md`](references/passport.md) |
+| Roles and permissions with spatie/laravel-permission | [`references/spatie-laravel-permission.md`](references/spatie-laravel-permission.md) |
+| Model media uploads, conversions, responsive images | [`references/spatie-medialibrary.md`](references/spatie-medialibrary.md) |
+| Form Requests and validation references | [`references/validation.md`](references/validation.md) |
+| Controllers, route binding, resources, middleware | [`references/routing.md`](references/routing.md) |
+| Schema changes, columns, foreign keys, indexes | [`references/migrations.md`](references/migrations.md) |
+| Jobs, retries, uniqueness, batches, Horizon | [`references/queue-jobs.md`](references/queue-jobs.md) |
+| Cache lifetime, invalidation, locks, memoization | [`references/caching.md`](references/caching.md) |
+| Outbound requests, retries, timeouts, fakes | [`references/http-client.md`](references/http-client.md) |
+| Exceptions, reporting, rendering, log context | [`references/error-handling.md`](references/error-handling.md) |
+| Events and notifications | [`references/events-notifications.md`](references/events-notifications.md) |
+| Mailables and mail assertions | [`references/mail.md`](references/mail.md) |
+| Scheduled tasks and overlap protection | [`references/scheduling.md`](references/scheduling.md) |
+| Database backups, cleanup, monitoring, notifications | [`references/spatie-laravel-backup.md`](references/spatie-laravel-backup.md) |
+| Collections, lazy iteration, bulk operations | [`references/collections.md`](references/collections.md) |
+| Blade components, attributes, composers | [`references/blade-views.md`](references/blade-views.md) |
+| Tailwind CSS classes, v4 configuration, extraction | [`references/tailwindcss.md`](references/tailwindcss.md) |
+| Environment values and application configuration | [`references/config.md`](references/config.md) |
+| Feature flags and per-user feature checks | [`references/pennant.md`](references/pennant.md) |
+| Pest/PHPUnit patterns, factories, fakes | [`references/testing.md`](references/testing.md) |
+| Pest 4 syntax, datasets, browser and architecture tests | [`references/pest-testing.md`](references/pest-testing.md) |
+| Naming, helpers, file boundaries, PHP style | [`references/style.md`](references/style.md) |
+| Actions, services, dependencies, application structure | [`references/architecture.md`](references/architecture.md) |
+| Detecting and recording this app's conventions as rules | [`references/infer-conventions.md`](references/infer-conventions.md) |
+
+## Decision rule
+
+- Prefer framework features and existing application abstractions over new helpers or dependencies.
+- Avoid speculative abstractions. Extract code when it creates a clear domain boundary, removes meaningful duplication, or makes behavior independently testable.
+- Keep database access out of Blade views and prevent hidden N+1 queries across controllers, resources, jobs, and serialization.

package/framework/skills/laravel-best-practices/references/architecture.md

@@ -9,7 +9,7 @@ class CreateOrderAction
 {
     public function __construct(private InventoryService $inventory) {}
 
-    public function execute(array $data): Order
+    public function handle(array $data): Order
     {
         $order = Order::create($data);
         $this->inventory->reserve($order);

package/framework/skills/laravel-best-practices/references/checklist.md

@@ -0,0 +1,139 @@
+# Detection Checklist
+
+Every dimension here is a genuine fork: Laravel offers two or more valid approaches, the app's choice changes what the next agent writes, and no active project tool can pick for you. Left out on purpose: pure formatting (Pint owns it), any form an installed and enabled Rector rule rewrites to one canonical shape (`$casts` to `casts()`, `$fillable` to attributes, pipe-string rules to arrays, named to anonymous migrations, `$signature` to `#[Signature]`), and framework defaults any agent writes unprompted (`ShouldQueue` jobs, relation return types, `HasFactory`).
+
+Each item gives the fork, then a hint (a grep or dir to spot which side the app takes). Hints are only a start. Read the matched files, never record on a raw count. Apply the ground rules to every verdict: a consistent choice that is a default or a tool's target form is not a pattern. Rows tagged (architecture) are the highest-signal, so record presence and deliberate absence.
+
+---
+
+## A. Validation & HTTP input
+
+1. Validation entry point: inline `$request->validate()` vs Form Request classes vs `Validator::make()`.
+   - Hint: `ls app/Http/Requests`; grep `->validate(` / `Validator::make(` in `app/Http/Controllers`.
+2. Custom rule location: invokable rule objects in `app/Rules` vs inline closures vs `Validator::extend()` in a provider. Rule objects are the default `make:rule` path, so record only if the app leans on closures or `Validator::extend` instead. "No rule objects" alone is just no-signal.
+   - Hint: `ls app/Rules`; grep `Validator::extend` in `app/Providers`.
+3. Typed input retrieval: typed getters (`$request->string()`, `->integer()`, `->enum()`, `->date()`) vs raw `$request->input()` / dynamic properties.
+   - Hint: grep `->string(` / `->integer(` / `->enum(` vs `->input(` in `app/Http`.
+4. Custom messages/attributes: `lang/*/validation.php` vs Form Request `messages()` / `attributes()` methods.
+   - Hint: `ls lang`; grep `function messages`, `function attributes` in `app/Http/Requests`.
+
+## B. Controllers & routing
+
+1. Controller shape: invokable single-action (`__invoke`) vs resource controllers vs plain multi-method.
+   - Hint: grep `__invoke` in controllers; `Route::resource` / `apiResource` vs verb routes.
+2. Business-logic location (architecture): fat controllers vs delegated to Actions / Services / Jobs.
+   - Hint: read a few controller methods; `ls app/Actions app/Services`.
+3. Route handler style: closures in `routes/*.php` vs controller classes.
+   - Hint: count `function ()` vs `::class` in `routes/web.php`, `routes/api.php`.
+4. Middleware assignment: route/group `->middleware()` vs controller `HasMiddleware::middleware()` vs `#[Middleware]` attribute.
+   - Hint: grep `implements HasMiddleware`, `#[Middleware(` in controllers vs `->middleware(` in routes.
+5. Route model binding: implicit (type-hinted models) vs explicit `Route::bind` vs manual `findOrFail`.
+   - Hint: typed model params in signatures vs `findOrFail(` in controllers; grep `Route::bind`.
+6. Rate limiting: named `RateLimiter::for()` + `throttle:name` vs inline `throttle:60,1`.
+   - Hint: grep `RateLimiter::for` in providers vs `throttle:` in route files.
+
+## C. Authorization
+
+1. Authorization home: Gates (`Gate::define`) vs Policy classes in `app/Policies`.
+   - Hint: `ls app/Policies`; grep `Gate::define` in `app/Providers`.
+2. Authorization call site: `$this->authorize()` / `Gate::authorize()` vs `$user->can()` vs `can` middleware vs `#[Authorize]` vs `@can` in Blade.
+   - Hint: grep `authorize(`, `->can(`, `middleware('can:`, `#[Authorize(`, `@can(`.
+
+## D. Eloquent & models
+
+1. Mass assignment: `$fillable` allow-list vs `$guarded` block-list.
+   - Hint: grep `protected $fillable` / `protected $guarded` in `app/Models`.
+2. Accessors/mutators: modern `Attribute` class vs legacy `getXxxAttribute()` / `setXxxAttribute()`. Record a legacy hold, it goes against the tool's grain.
+   - Hint: grep `: Attribute` / `Attribute::make` vs `function get[A-Z].*Attribute` in `app/Models`.
+3. Primary keys: auto-increment vs `HasUuids` vs `HasUlids`.
+   - Hint: grep `HasUuids` / `HasUlids` in `app/Models`; migration `id()` vs `uuid('id')`.
+4. Custom casts: dedicated `CastsAttributes` classes (`app/Casts`) vs inline `Attribute` vs built-in cast strings.
+   - Hint: `ls app/Casts`; grep `Cast::class`, `AsStringable::class` in models.
+5. Data/query layer (architecture): Eloquent directly in controllers vs repositories vs dedicated query objects (e.g. classes exposing `builder(): Builder`).
+   - Hint: `ls app/Repositories app/Queries`; see where non-trivial queries are built.
+6. Query scopes: local `scope`/`#[Scope]` methods vs dedicated builder classes.
+   - Hint: grep `function scope` / `#[Scope]` in models; `ls app/*/Builders`.
+7. Model events: observers (`app/Observers`, `#[ObservedBy]`) vs `booted()` closures vs event classes.
+   - Hint: `ls app/Observers`; grep `booted`, `::observe`, `#[ObservedBy]`.
+8. Eager-load posture: explicit per-query `->with()` vs model-level `$with` defaults. Treat `preventLazyLoading()` separately as a development guard because it can complement either posture.
+   - Hint: grep `protected $with`, `->with(`, and separately `preventLazyLoading` in `app/`.
+
+## E. Architecture & organization
+
+1. Action/Service structure (architecture): Action classes (invoked via `handle` / `execute` / `__invoke`) vs service objects vs neither. Cross-check the Step 0 `app/` map: any `Actions`/`Services`/`Pipelines`/`Jobs`-as-actions folder is this pattern, so record how it is invoked.
+   - Hint: `ls app/` (the whole tree, not just `Actions`/`Services`); grep the invocation method in the folder you find.
+2. DTOs (architecture): spatie/laravel-data vs plain readonly classes vs arrays everywhere.
+   - Hint: `ls app/Data`; grep `extends Data`, `readonly class` in `app/`.
+3. Dependency acquisition: constructor/method injection vs `app()` / `resolve()` / `App::make()` service location.
+   - Hint: grep `app(` / `resolve(` / `::make(` in `app/` vs promoted constructor deps.
+4. Decoupling: events + listeners vs direct service calls.
+   - Hint: `ls app/Events app/Listeners`; grep `event(`, `::dispatch(`.
+5. Helper vs facade idiom: global helpers (`config()`, `auth()`, `response()`) vs facades (`Config::`, `Auth::`, `Response::`).
+   - Hint: ratio of `config(` vs `Config::` (etc.) across `app/`.
+6. Namespace layout (architecture): default `app/` skeleton vs domain/module folders (`app/Domain/**`, modules).
+   - Hint: `ls app/`, look for `Domain/`, `Modules/`, bounded-context folders.
+7. Enums: backed vs pure; case naming; where they live.
+   - Hint: `ls app/Enums`; grep `enum .*: string`, `enum .*: int`.
+
+## F. Frontend & views
+
+This app ships a frontend stack, so the items below apply.
+
+1. Frontend stack: Blade+Livewire vs Inertia (Vue/React/Svelte) vs Blade-only / API + separate SPA.
+   - Hint: `composer.json` + `package.json`; `ls resources/js/pages`, `resources/views`.
+2. Blade composition: class `<x-*>` components vs anonymous components (`@props`) vs `@include` partials.
+   - Hint: `ls app/View/Components`; grep `<x-`, `@include` in `resources/views`.
+3. Livewire component format: Volt functional/class components, native Livewire 4 single-file (SFC), multi-file (MFC), view-based, or class-based components. Evaluate full-page vs nested separately because it is an independent usage choice.
+   - Hint: check the installed Livewire major and `livewire/volt`; inspect `app/Livewire`, `resources/views/livewire`, and Livewire 4 component/page directories for `@volt`, SFC, MFC, view-based, and class-based formats.
+4. Localization: short keys (`lang/*/*.php` + `__('messages.welcome')`) vs JSON string keys (`lang/*.json` + `__('Full sentence')`).
+   - Hint: `ls lang`; grep dotted `__('` vs sentence keys.
+
+## G. Database & migrations
+
+1. Foreign keys: `foreignId()->constrained()` vs `foreignIdFor(Model::class)` vs manual `foreign()->references()->on()`.
+   - Hint: grep `foreignId(`, `foreignIdFor(`, `->foreign(` in `database/migrations`.
+2. `down()` methods: real reverse logic vs omitted / one-way migrations.
+   - Hint: grep `function down` vs the migration count.
+3. Enum storage: DB `enum()` column vs `string()` + PHP-enum cast on the model.
+   - Hint: grep `->enum(` in migrations vs string columns cast to enums.
+4. Transactions: `DB::transaction(fn ...)` closure vs manual `beginTransaction` / `commit` / `rollBack`.
+   - Hint: grep `DB::transaction`, `beginTransaction` in `app/`.
+5. Idempotent writes: `upsert` / `updateOrCreate` / `firstOrCreate` vs find-then-save.
+   - Hint: grep `upsert(`, `updateOrCreate(`, `firstOrCreate(` in `app/`.
+
+## H. Testing
+
+1. Framework: Pest (`it()` / `test()` / `expect()`) vs PHPUnit classes.
+   - Hint: `ls tests/Pest.php`; grep `it(` / `test(` vs `extends TestCase`.
+2. DB reset: `RefreshDatabase` vs `DatabaseTruncation` vs `DatabaseMigrations`.
+   - Hint: grep those trait names in `tests/`.
+3. Fixtures: compare how equivalent test-owned records are created, such as factories vs manual inserts. Track seeders separately for shared reference data because `$this->seed()` commonly and legitimately coexists with factories.
+   - Hint: grep `::factory(` and direct inserts in `tests/`; separately inspect `$this->seed(` calls and what those seeders provide.
+4. Collaborator isolation: how the app doubles its own classes, Mockery `mock()` / `spy()` vs real integration. Ignore facade fakes like `Mail::fake()` here, they isolate framework services by default and are not a fork against Mockery.
+   - Hint: grep `->mock(`, `->spy(`, `Mockery::` in `tests/`.
+5. Endpoint assertions: array `assertJson([...])` / `assertJsonFragment` vs fluent `AssertableJson`.
+   - Hint: grep `AssertableJson`, `assertJsonFragment` in `tests/`.
+
+## I. Responses & API resources
+
+1. Response shape: API Resource classes vs `response()->json()` vs returning models/arrays directly.
+   - Hint: `ls app/Http/Resources`; grep `JsonResource`, `->json(` in controllers.
+2. Resource relationship inclusion: `whenLoaded()` guards vs unconditional relationship access. Do not count ordinary scalar attributes as rivals to conditional relationships, and evaluate general `when()` fields separately.
+   - Hint: compare relationship fields using `whenLoaded(` with unconditional relationship property access in `app/Http/Resources`.
+3. Pagination contracts: within comparable endpoint categories, length-aware `paginate()` vs `simplePaginate()` vs `cursorPaginate()`. These have different totals, navigation, ordering, and performance contracts, so record only a stable path-scoped API policy, never a project-wide majority.
+   - Hint: grep those in `app/`, then group matches by endpoint type and client contract before comparing them.
+4. Web redirects/URLs: `route('name')` vs `url('/path')` vs `action([...])`.
+   - Hint: grep `route('`, `url('/`, `action([` in `app/Http` and views.
+
+## J. Strings, collections & dates
+
+1. Iteration idiom: `collect()->map()->filter()` pipelines vs `array_map` / `foreach`.
+   - Hint: grep `collect(`, `->map(` vs `array_map`, `foreach` density in `app/`.
+2. String API: fluent `Str::of()->...` (Stringable) vs static `Str::` vs native (`trim`, `strtoupper`).
+   - Hint: grep `Str::of(` vs `Str::` vs native string funcs.
+3. Dates: compare equivalent construction call styles (`now()` / `today()` helpers vs `Carbon::`) separately from the application's mutable/immutable date policy. `Date::use(CarbonImmutable::class)` can make helpers return immutable dates, so those signals are complementary rather than conflicting.
+   - Hint: grep `now(` and `Carbon::` for call style; separately inspect `CarbonImmutable` and `Date::use` for mutability policy.
+
+---
+
+Genuine forks only. Every row survived the "no tool can decide this, and it isn't the default" filter. Give each applicable dimension exactly one verdict: pattern, conflict, default, no-signal, tooling-owned, or already-recorded. The rows tagged (architecture) are where the highest-value rules come from.

package/framework/skills/laravel-best-practices/references/eloquent.md

@@ -30,7 +30,8 @@ $articles = Article::whereHas('user', function ($q) {
 
 Correct:
 ```php
-public function scopeActive(Builder $query): Builder
+#[Scope]
+protected function active(Builder $query): Builder
 {
     return $query->where('verified', true)->whereNotNull('activated_at');
 }
@@ -58,7 +59,8 @@ class PublishedScope implements Scope
 
 Correct (local scope you opt into):
 ```php
-public function scopePublished(Builder $query): Builder
+#[Scope]
+protected function published(Builder $query): Builder
 {
     return $query->where('published', true);
 }

package/framework/skills/laravel-best-practices/references/infer-conventions.md

@@ -0,0 +1,97 @@
+
+# Infer Conventions
+
+Learn how this application writes Laravel, then record what you learn as durable, path-scoped rules other agents will read. You are documenting reality, not improving it.
+
+## Ground Rules (read before you start)
+
+- Consistency first. The codebase's majority style is the convention. Never judge it, never propose a "better" pattern, never record what the code should do. If the app validates inline everywhere, that is the rule, even if Form Requests would be nicer.
+- Skip what an active tool produces, keep what a tool would fight. Inspect the project's Pint and Rector configuration first; a Rector transformation is tooling-owned only when its package and relevant rule or set are installed and enabled. Active tools may rewrite code toward one canonical form: `$casts` to `casts()`, `$fillable` to attributes, magic accessors to the `Attribute` class, pipe-string rules to arrays, `$signature` to `#[Signature]`, named migrations to anonymous, and many more. When the app already sits at an active tool's target form, the tool owns it, so record nothing. But when the app deliberately holds a form an active tool would refactor away, such as legacy `getXxxAttribute()` accessors the `Attribute` class would replace, no tool can reproduce that choice and an agent defaults the other way. That against-the-grain hold is exactly what to record.
+- Record decisions, not defaults. A consistent pattern earns a rule only when it reflects a choice: the app took one valid option where the framework or common practice offered others, or the pattern would surprise a competent agent. Framework defaults steer nothing, so skip them: anonymous migrations, `$signature` commands, `ShouldQueue` jobs, `casts()` on Laravel 11+, named routes, Rule objects in `app/Rules`, and `Mail::fake()` or `Bus::fake()` to isolate framework services. A real fork is not enough on its own. Weigh the side the app took, and record only the side an agent would not reach for by itself: inline closures everywhere, legacy accessors, a bespoke query layer. Watch for the false fork too. "No Mockery" next to facade fakes is not a choice against Mockery, because they double different things. The test for every candidate: without this rule, would the next agent plausibly write it differently? Only "yes" earns a rule.
+- Architecture choices are the gold. Record presence and deliberate absence. The structural pattern the app commits to is the highest-signal convention and the one no tool can decide: Action classes and how they are invoked (`handle` / `execute` / `__invoke`), service objects, dedicated query objects exposing `builder()`, DTOs (spatie/laravel-data vs readonly classes), Form Request validation vs inline, an events and listeners spine vs direct calls, and domain or module folders. Also record a consistent non-pattern, such as "query Eloquent directly in controllers, no repository layer", so the next agent matches the app's altitude instead of over-engineering.
+- Never duplicate `.ai/rules`. Read `.ai/rules/index.md` and the area files before the sweep. A dimension already covered there is marked done and skipped.
+- Evidence or silence. A convention needs at least 3 consistent examples and no meaningful rival to become a candidate. Every Step 1 verdict applies this bar.
+- The recorded rule states the convention, nothing else. One or two imperative lines: this project does X, so do X here. Keep detection evidence out. No counts, ratios, current usage, file lists, or example paths, because that is proof for the confirm step, not part of the rule. One short syntax fragment at most, and point to `search-docs` for API details.
+
+## Process
+
+Each step ends on a checkable completion criterion. Do not advance until it holds.
+
+Fan out when you can. The sweep is embarrassingly parallel. If your environment can spawn subagents (a Task, dispatch, or equivalent tool), do Step 0 yourself, then hand each checklist group (A to J) and the architecture map to its own subagent. Each subagent runs the greps, reads a few representative files, and returns structured verdicts (dimension, verdict, evidence, proposed glob / title / note). You aggregate, dedupe, then run Steps 3 to 5. It is far faster on a real app. No subagents available? Run the steps in sequence, with the same bar and the same output.
+
+### Step 0: Orient
+
+Read `composer.json` (installed packages tell you which checklist groups apply), the `pint.json` / PHPStan / Rector config, `.ai/rules/index.md` if present, and most important, map the `app/` tree. List every directory under `app/` (and any `Modules/`, `src/`, `packages/`, or domain root). Every folder beyond Laravel's default skeleton (`Http`, `Models`, `Providers`, `Console`, `Exceptions`) is a structural pattern the app committed to and a high-value rule waiting to be written: `Actions`, `Services`, `Data` or DTOs, `Queries`, `Repositories`, `ViewModels`, `Pipelines`, `Support`, `Enums`, `Contracts`, `Observers`, or `Domain` and module roots. Note each one. You will confirm how it is used in Step 2.
+
+This app ships a frontend stack, so the frontend checklist group applies. Sweep it.
+
+Done when: you have the applicable checklist groups, the dimensions already recorded in `.ai/rules`, and a list of every non-default `app/` directory mapped to the pattern it represents.
+
+### Step 1: Predefined sweep
+
+Open `references/checklist.md` and work every applicable dimension using its search hints. Give each exactly one verdict:
+
+- Pattern. Clears the bar, rival under ~20% of sites, and reflects a real choice (passes the decisions-not-defaults test). A recording candidate. Cite 2 to 3 example files.
+- Conflict. Both styles present in meaningful numbers. Report the split with counts and example files. Never record a preferred winner while the code remains mixed, even in yolo, because that would describe an aspiration rather than reality. Record only if the user identifies a stable path or context boundary that explains both styles; otherwise defer until the code is reconciled.
+- Default. Consistent, but a framework or common-practice default the agent already writes unprompted. Skip it as a no-op, not a convention.
+- No signal. Under the bar: feature unused, or too few examples. Skip silently (one summary line at most).
+- Tooling-owned or Already-recorded. Skip per the ground rules.
+
+Done when: every applicable dimension carries exactly one of those verdicts.
+
+### Step 2: Open-ended pass
+
+First, close out the architecture map from Step 0. For every non-default `app/` directory you listed, confirm how the pattern is used and apply the same evidence and decisions-not-defaults tests as Step 1. Generator-standard or sparsely used directories such as `Rules`, `Observers`, `Mail`, and `Notifications` are signals to inspect, not automatic conventions. Make genuine structural patterns candidates: Action classes invoked via `handle` / `execute` / `__invoke`, Services constructor-injected, `Queries` objects exposing `builder(): Builder`, DTOs as readonly classes or spatie/laravel-data, module or domain folders as the unit of organization. Scope each qualifying pattern to its own directory glob. Also record a consistent deliberate absence, such as "no repository layer, controllers query Eloquent directly", so the next agent matches the app's altitude.
+
+Then find what else makes this codebase itself: base or abstract classes most code extends, traits used everywhere, tenancy or authorization scoping woven through queries, naming schemes, and custom helpers. Same evidence bar, cite files. Record every genuine structural pattern, and cap the other house findings at ~5 so the pass stays high-signal.
+
+Done when: every non-default `app/` directory from Step 0 has a verdict, and the pass has produced its cited house findings (or concluded there are none).
+
+### Step 3: Confirm
+
+Present every candidate in one batch. Per item: dimension, verdict, evidence (counts and files), and the exact proposed `glob` or `globs` / `title` / `note`. Conflicts are presented as questions about an existing context boundary or deferred cleanup, not as a choice of future style.
+
+Default mode is confirm: record only what the user approves. Switch to yolo only when the invocation said so ("yolo", "don't ask", "just record them"), then record all pattern candidates without asking. Conflicts still go to the user in yolo.
+
+Done when: every candidate is approved, rejected, or (conflicts) decided.
+
+### Step 4: Record
+
+Make one `record-rule` call for each glob an approved convention applies to. Choose the most specific globs that cover the cited evidence from the mapping table below; if a convention spans models and migrations, record it under both domains so agents discover it from either path. The `note` is the bare convention: strip every trace of detection (see the ground rule). If `record-rule` is unavailable (rules disabled), report the full rule text so the user can enable `BOOST_RULES_ENABLED` or add it by hand.
+
+Record this:
+
+> Accessors and mutators: use the legacy magic-method style (`getXxxAttribute()` / `setXxxAttribute()`), not the `Attribute` class. Match it in models.
+
+Not this:
+
+> Accessors/mutators use the legacy magic-method style; the `Attribute`-class style is not used anywhere (13 legacy, 0 Attribute-class), e.g. `app/Models/Post.php`. Match the legacy style in existing models.
+
+Done when: every approved item has a successful tool response, and any failure is reported with its rule text.
+
+### Step 5: Summarize
+
+List recorded rules (file and title), conflicts the user deferred, notable no-signals, and remind the user to commit `.ai/rules` so their team and agents share the conventions.
+
+## Glob mapping
+
+Attach each rule to the most specific path that covers its evidence. Never a lazy `app/**` when a subtree fits. Match the glob to where the code actually lives, which is not the same in a default skeleton and in a modular or DDD layout. Use the Step 0 `app/` map to pick the real path.
+
+Examples:
+
+- Models: `app/Models/**` in a default app, or `app/Modules/Blog/Models/**` / `src/Domain/Blog/**` in a modular one.
+- Controllers, routing, validation, responses: `app/Http/**`, or `app/Modules/*/Http/**` when each module owns its HTTP layer.
+- Actions, Services, DTOs: `app/Actions/**`, `app/Services/**`, `app/Data/**`, or the module path the app actually uses.
+- Tests: `tests/**`.
+- Migrations and database: `database/migrations/**`.
+- Truly app-wide (rare, e.g. auth retrieval): `app/**`.
+
+`record-rule` takes one glob. When a convention genuinely spans two domains (e.g. UUID keys touch models and migrations), call it once per domain with the same title and note; mentioning another path in the note does not make the rule discoverable there.
+
+## Edge cases
+
+- Rules disabled or `record-rule` missing: detection is read-only, so Steps 0 to 3 still run, and recording falls back to the manual path in Step 4.
+- Tiny or fresh app: most dimensions land on no-signal. Say so honestly ("not enough code to infer conventions yet") and record nothing.
+- Huge app: each dimension is a bounded grep plus a handful of file reads. Sample representative files, do not read everything.
+- Re-runs: reading `.ai/rules` in Step 0 makes re-runs incremental, so only new or undecided dimensions surface.
+- Non-standard layout (modules, DDD): the open-ended pass catches the layout itself as convention #1. Adapt the globs in the mapping table to the observed paths.