Laravel AI skill bundle for architecture, validation, Eloquent, performance, security, Livewire, testing, daily workflow, secure memory orchestration, and lazy-minimization gate.
Use Actions and Services as deliberate Laravel application boundaries for use cases, integrations, and reusable workflows.
# Actions And Services
Actions and Services create application boundaries. Use them based on need, not because every controller method needs another layer.
## When To Use An Action
Use an Action for one named use case:
- `CreateRecord`
- `ApproveRecord`
- `CancelRecord`
- `GenerateRecordDocument`
Actions fit workflows with clear input and output.
```php
final class CreateRecord
{
public function handle(User $actor, array $data): Record
{
return DB::transaction(function () use ($actor, $data) {
return Record::create([
'owner_id' => $actor->id,
'name' => $data['name'],
]);
});
}
}
```
## When To Use A Service
Use a Service when a component owns a broader capability:
- integration client;
- document generation;
- pricing/calculation policy;
- import/export workflow;
- reusable application workflow.
```php
final class GatewayService
{
public function createLink(Record $record): string
{
$response = Http::baseUrl(config('services.gateway.url'))
->timeout(5)
->retry(2, 200, throw: false)
->post('/links', [
'reference' => $record->public_reference,
'amount' => $record->total,
]);
throw_unless($response->successful(), RuntimeException::class);
return $response->json('url');
}
}
```
## Integration Boundaries
Keep provider calls in focused services or adapters. The boundary should own:
- request mapping;
- authentication/signing details;
- timeouts and retries;
- response parsing;
- provider error translation;
- sanitized structured logging;
- fake-driven tests.
Do not globalize provider endpoints, payload quirks, status maps, or customer copy.
## Interfaces And Repositories
Do not create an interface for every service.
Add an interface only when:
- multiple implementations exist;
- provider swapping is likely;
- configuration selects implementations;
- the contract is shared across modules;
- the boundary protects domain code from infrastructure.
Do not require Repository Pattern for normal Eloquent CRUD. Add a repository only for real data-access complexity or storage-provider variation.
## Context Efficiency
Layer: 3 (Implementation)
Load this skill only when application boundaries need design. Do not load with unrelated skills. Keep the diff minimal: one Action per use case, one Service per integration or workflow, no interface until a second implementation exists.Build AI features with the first-party Laravel AI SDK (Laravel 13+); agents, embeddings, images, audio, and tool calling with provider-agnostic APIs
# Ai Sdk
Use this skill when a Laravel task involves ai sdk.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `ai-sdk` topic from `jpcaparas/superpowers-laravel` into the local `ai-sdk` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to use API Resources with pagination and conditional fields; keep response shapes stable and cache-friendly
# Api Resources And Pagination
Use this skill when a Laravel task involves api resources and pagination.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `api-resources-and-pagination` topic from `jpcaparas/superpowers-laravel` into the local `api-resources-and-pagination` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to evolve APIs safely using versioned DTOs/transformers, deprecations, and compatibility tests
# Api Surface Evolution
Use this skill when a Laravel task involves api surface evolution.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `api-surface-evolution` topic from `jpcaparas/superpowers-laravel` into the local `api-surface-evolution` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Apply Laravel-native architecture decisions without forcing unnecessary repositories, interfaces, DTOs, or custom layers.
# Architecture
Use Laravel conventions before adding custom architecture. A good default request path is:
```text
Route -> Controller -> Form Request -> Action/Service -> Eloquent/Integration -> Response
```
Do not force every layer into every feature. Add a boundary only when it makes behavior easier to test, reuse, reason about, or change.
For multi-menu dashboards, admin systems, or copied prototype apps, also use `module-per-menu`: default to one menu or page per module, small controllers, per-page views, shared layouts/components, and DB-backed dynamic data.
## Layer Decisions
Use a controller for HTTP orchestration:
- receive the request;
- delegate validation and authorization;
- call the application workflow;
- return redirect, response, resource, view, or stream.
Use a Form Request when validation or authorization is complex, reused, or important enough to test independently.
Use an Action when a single use case needs a named command-style object.
Use a Service when a workflow coordinates multiple models, integrations, files, jobs, events, generated documents, or transactional writes.
Use a Policy or Gate for authorization rules. Keep authorization close to the boundary, but do not bury model-state rules in routes.
## Avoid Overengineering
Do not add repositories, interfaces, DTOs, feature folders, or value objects by default.
Add an interface when:
- there are multiple implementations;
- a provider may be swapped;
- the domain should not depend on a concrete integration;
- a stable contract is shared across modules;
- a test boundary is meaningful and not just mocking for its own sake.
Add a repository only when query/data-access complexity is real or storage implementation may vary. Plain Eloquent in an Action or Service is fine for normal CRUD.
## Version And Stack Detection
Before applying version-specific patterns, check:
- Laravel version in `composer.json` or `php artisan --version`;
- PHP version and supported syntax;
- installed testing framework;
- queue driver and Horizon presence;
- Blade, Livewire, Inertia, React, Vue, Tailwind, or Vite usage;
- Sail/container workflow versus host commands.
## Implementation Checklist
- Keep the public behavior small and testable.
- Prefer Laravel-native APIs over custom plumbing.
- Keep project-specific business names out of shared standards.
- Write focused tests around the behavior being changed.
- Run available quality checks before handoff.
## Context Efficiency
Layer: 3 (Implementation)
Load this skill only when architecture decisions are needed. Do not load with unrelated skills. Keep the implementation checklist minimal: public behavior, Laravel-native APIs, focused tests, quality checks.Laravel guidance to compose UIs with Blade components, slots, and layouts; keep templates pure and testable
# Blade Components And Layouts
Use this skill when a Laravel task involves blade components and layouts.
When the app has multiple menus/pages, also use `module-per-menu`: keep one Blade view per page or page state, share layout/components, and avoid a single Blade file full of menu-condition blocks.
When the Blade work includes UI/UX design, frontend implementation, browser inspection, or backend contract alignment, also use `ui-agent-browser`. Keep this skill focused on template structure, component boundaries, slots, layouts, and rendering purity.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `blade-components-and-layouts` topic from `jpcaparas/superpowers-laravel` into the local `blade-components-and-layouts` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `ui-agent-browser`
- `module-per-menu`
- `testing`
- `security`Interactive design refinement tailored to Laravel projects; clarify domain, data, interfaces, testing, and quality gates while accounting for Sail/non‑Sail environments
# Brainstorming
Layer: 2-3 (Design + Implementation)
Use this skill when a Laravel task involves design refinement before implementation.
This skill assumes Layer 0-1 have already run. If you have not run `memory-management` preflight and `least-code` minimization yet, do so before loading this skill.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Confirm memory preflight and least-code minimization are active.
2. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
3. Identify the smallest local skill set that overlaps this topic.
4. Design or review the change using Laravel-native APIs first.
5. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
6. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards` - entrypoint and skill selection
- `architecture` - layer decisions
- `testing` - test strategy
- `security` - security reviewRequest effective code reviews-specify focus areas, provide context, ask for architectural feedback, reference Laravel conventions
# Code Review Requests
Use this skill when a Laravel task involves code review requests.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `code-review-requests` topic from `jpcaparas/superpowers-laravel` into the local `code-review-requests` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to keep cyclomatic complexity low; flatten control flow, extract helpers, and prefer table-driven/strategy patterns over large switches
# Complexity Guardrails
Use this skill when a Laravel task involves complexity guardrails.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `complexity-guardrails` topic from `jpcaparas/superpowers-laravel` into the local `complexity-guardrails` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to portable storage configuration across S3/R2/MinIO with optional CDN-env toggles, path-style endpoints, and URL generation
# Config Env Storage
Use this skill when a Laravel task involves config env storage.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `config-env-storage` topic from `jpcaparas/superpowers-laravel` into the local `config-env-storage` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Replace hardcoded values with constants, enums, and configuration for maintainability; use PHP 8.1+ enums and config files
# Constants And Configuration
Use this skill when a Laravel task involves constants and configuration.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `constants-and-configuration` topic from `jpcaparas/superpowers-laravel` into the local `constants-and-configuration` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Keep Laravel controllers focused on HTTP orchestration by moving validation, authorization, and business workflows outward.
# Controller Cleanup
Use this skill when controllers become difficult to understand, test, or maintain.
When a Laravel app has several menus/pages, also use `module-per-menu`: avoid one broad controller for the whole app, and split by menu, page group, or resource boundary.
Controllers should stay thin and focused on HTTP orchestration. They should not contain long business workflows, provider payload construction, repeated query logic, or file-processing loops.
## Responsibilities
A controller may:
- receive route-bound models and requests;
- call `$this->authorize()` or rely on middleware/Form Request authorization;
- call a Form Request's `validated()` data;
- invoke an Action or Service;
- return redirects, views, JSON resources, streams, or downloads;
- attach session flash messages.
A controller should not:
- build external provider payloads inline;
- contain multi-step write workflows without a transaction boundary;
- duplicate validation rules;
- hide authorization inside unrelated branches;
- contain heavy report/query logic that is reused elsewhere.
## Route Boundaries
Keep coarse access requirements visible in routes or route groups.
```php
Route::middleware(['auth', 'verified'])->group(function () {
Route::resource('records', RecordController::class)
->middlewareFor('index', 'can:viewAny,' . Record::class)
->middlewareFor(['create', 'store'], 'can:create,' . Record::class)
->middlewareFor(['edit', 'update'], 'can:update,record')
->middlewareFor('destroy', 'can:delete,record');
});
```
Use Policies for model-state rules and Form Request `authorize()` for request-input-dependent authorization.
## Route Order And Cache Safety
Use controller actions for committed production endpoints that need middleware, sessions, tests, cache headers, or deployment route caching.
Route closures are acceptable for static views, simple redirects, prototypes, and temporary debugging.
Place static or specific routes before broad resource routes when URI patterns could collide.
```php
Route::get('records/export', ExportRecordsController::class)
->name('records.export');
Route::resource('records', RecordController::class);
```
Verify collision-prone route changes with `php artisan route:list` or a feature test.
## Generic Store Pattern
```php
final class RecordController
{
public function store(StoreRecordRequest $request, CreateRecord $create): RedirectResponse
{
$record = $create->handle($request->user(), $request->validated());
return redirect()
->route('records.show', $record)
->with('status', 'Record created.');
}
}
```
## Guardrails
- Do not extract one-line code merely to create more layers.
- Do not require Repository Pattern by default.
- Keep framework-specific HTTP concerns in controllers.
- Keep reusable business operations outside controllers.
## Context Efficiency
Layer: 3 (Implementation)
Load this skill only when controllers need cleanup. Do not load with unrelated skills. Keep the diff minimal: inline validation only when rules are tiny, otherwise Form Request; one Action per use case; no repository by default.Laravel guidance to write focused controller tests using HTTP assertions; keep heavy logic in Actions/Services and unit test them
# Controller Tests
Use this skill when a Laravel task involves controller tests.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `controller-tests` topic from `jpcaparas/superpowers-laravel` into the local `controller-tests` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to create and register small, pure helper functions when they improve clarity; keep them organized and tested
# Custom Helpers
Use this skill when a Laravel task involves custom helpers.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `custom-helpers` topic from `jpcaparas/superpowers-laravel` into the local `custom-helpers` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Practical daily checklist for Laravel projects; bring services up, run migrations, queues, quality gates, and tests
# Daily Workflow
Use this skill when a Laravel task involves daily workflow.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `daily-workflow` topic from `jpcaparas/superpowers-laravel` into the local `daily-workflow` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to process large datasets efficiently using chunk(), chunkById(), lazy(), and cursor() to reduce memory consumption and improve performance
# Data Chunking Large Datasets
Use this skill when a Laravel task involves data chunking large datasets.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `data-chunking-large-datasets` topic from `jpcaparas/superpowers-laravel` into the local `data-chunking-large-datasets` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Keep Laravel writes atomic and consistent with transactions, locks, retries, idempotency, side-effect boundaries, and after-commit dispatch.
# Database Transactions
Use database transactions for write operations that must be atomic.
This is the canonical transaction skill. It consolidates the former `transactions-and-consistency` topic.
Transaction boundaries usually belong inside an Action or Service, not spread across controllers.
## Required Transaction Cases
Use `DB::transaction()` when a workflow:
- writes multiple related records;
- updates counters, balances, inventory, or state machines;
- coordinates audit records with domain writes;
- creates records and related child rows;
- must not partially succeed.
```php
final class CreateRecord
{
public function handle(User $actor, array $data): Record
{
return DB::transaction(function () use ($actor, $data) {
$record = Record::create([
'owner_id' => $actor->id,
'name' => $data['name'],
]);
$record->items()->createMany($data['items'] ?? []);
return $record->fresh(['items']);
});
}
}
```
## Filesystem Side Effects
Database rollbacks do not roll back files. Track stored paths and clean them up when the database write fails.
```php
$storedPaths = [];
try {
DB::transaction(function () use ($request, &$storedPaths) {
$record = Record::create([...]);
foreach ($request->file('attachments', []) as $file) {
$storedPaths[] = $file->store("records/{$record->id}", 'public');
}
});
} catch (Throwable $exception) {
Storage::disk('public')->delete($storedPaths);
throw $exception;
}
```
For delete flows, prefer committing database/audit changes first, then deleting files after the successful transaction unless the product explicitly requires the opposite failure mode.
## Locks And Retries
Use row locks for concurrent updates to shared counters, balances, or ordered state.
```php
DB::transaction(function () use ($recordId) {
$record = Record::query()
->whereKey($recordId)
->lockForUpdate()
->firstOrFail();
$record->increment('sequence');
});
```
Keep transactions short. Make retry behavior idempotent when deadlock retries are used.
## After-Commit Work
Dispatch queued jobs/events after commit when they depend on committed records.
Do not hold a database transaction open during slow HTTP calls, mail delivery, document generation, or other remote side effects. Persist the state needed to continue, commit it, and dispatch after commit. Use an outbox or equivalent durable handoff when losing the side effect would be unacceptable.
## Idempotency And Consistency
- Protect retried commands, webhooks, and queued jobs with a stable idempotency key or a domain state check.
- Enforce uniqueness in the database when duplicate prevention is a data invariant.
- Make retry behavior return or recover the original result instead of repeating side effects.
- Keep lock ordering consistent across workflows to reduce deadlocks.
- Use optimistic checks when conflicts should be reported rather than serialized.
- Prefer explicit compensating behavior for filesystem or provider operations that cannot participate in the database transaction.
Test:
- success path;
- rollback path;
- duplicate or retried execution;
- concurrent updates when locking matters;
- filesystem cleanup when applicable;
- after-commit behavior for important workflows.
## Context Efficiency
Layer: 3 (Implementation)
Load this skill only when writes need atomicity or consistency. Do not load with unrelated skills. Keep transactions short, idempotent, and after-commit for side effects. No open transaction during slow HTTP calls or mail delivery.Laravel guidance to create effective debugging prompts-include error messages, stack traces, expected vs actual behavior, logs, and attempted solutions
# Debugging Prompts
Use this skill when a Laravel task involves debugging prompts.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `debugging-prompts` topic from `jpcaparas/superpowers-laravel` into the local `debugging-prompts` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to remove unneeded Composer packages and assets to improve boot time, memory, and security surface
# Dependencies Trim Packages
Use this skill when a Laravel task involves dependencies trim packages.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `dependencies-trim-packages` topic from `jpcaparas/superpowers-laravel` into the local `dependencies-trim-packages` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to write meaningful documentation that explains why not what; focus on complex business logic and self-documenting code
# Documentation Best Practices
Use this skill when a Laravel task involves documentation best practices.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `documentation-best-practices` topic from `jpcaparas/superpowers-laravel` into the local `documentation-best-practices` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel E2E testing with official Playwright patterns for locators, auth state, seeds, traces, screenshots, CI, and cross-browser workflows.
# E2E Playwright
Use this skill when a Laravel task involves Playwright E2E tests, browser workflow coverage, regression tests, screenshots, traces, auth setup, or converting manual browser findings into durable tests.
Use the official `microsoft/playwright` repository as the source for current Playwright behavior when APIs, CLI, MCP, browser support, locators, traces, or configuration details matter: https://github.com/microsoft/playwright. Prefer the linked Playwright docs and API reference over remembered APIs.
## Workflow
1. Detect how the project runs Laravel, assets, queues, database, and browser tests: host, Sail, Docker, package manager, Vite, Playwright config, existing test helpers, and CI commands.
2. Reuse project-local Playwright patterns first: auth helpers, seed scripts, storage state, route helpers, page objects, fixtures, test IDs, screenshots, and trace settings.
3. Seed deterministic data through Laravel factories, seeders, HTTP setup routes, API helpers, or existing test bootstrap. Avoid fragile production-like data dependencies.
4. Write tests with user-facing locators first: `getByRole`, `getByLabel`, `getByText`, `getByPlaceholder`, and `getByTestId` only when semantic locators are not stable enough.
5. Prefer Playwright web-first assertions such as `toBeVisible`, `toHaveText`, `toHaveURL`, `toHaveValue`, and `toHaveScreenshot` over fixed sleeps.
6. Cover the high-value user workflow, not every implementation detail. Include success, validation failure, authorization-dependent UI, empty state, loading or queued state, and destructive confirmation when relevant.
7. Capture traces, screenshots, videos, or console/network evidence only when they help debug failures or support handoff.
8. Run the smallest meaningful Playwright command locally and report skipped browsers, missing services, or environment blockers explicitly.
## Laravel Setup Rules
- Authenticate through existing Laravel test helpers when available. If the project uses storage state, create it from a safe test user and never commit real cookies, tokens, or session files.
- Keep `.env`, credentials, tokens, private URLs, raw customer data, and real auth state out of tests, screenshots, traces, and fixtures.
- Use Laravel fakes for mail, notifications, queues, files, events, and HTTP integrations when the browser flow does not need the real external system.
- Wait for app-specific readiness: Vite assets loaded, Livewire requests settled, Inertia navigation finished, queued job state visible, fonts ready, and network idle only when it is meaningful.
- Add stable `data-testid` attributes only when accessible locators are not reliable and the project accepts test IDs.
## Playwright And Agent Browser
Use `ui-agent-browser` when UI/UX design or implementation is still being explored. Use `agent-browser` for low-token browser inspection, then convert the accepted workflow into Playwright when it should become a repeatable regression test.
## Completion Gate
Do not call Playwright coverage complete unless:
- the tested workflow is tied to real Laravel routes, Livewire actions, Inertia pages, or API contracts;
- deterministic setup and teardown exist or the dependency on local state is explicit;
- locators are resilient and user-facing where possible;
- assertions prove behavior and state, not only that the page loads;
- auth, validation, authorization, loading, empty, and success states are covered when relevant;
- screenshots/traces are enabled or captured where failure diagnosis needs them;
- the exact command run and any skipped checks are reported.
## Related Skills
- `using-laravel-standards`
- `ui-agent-browser`
- `responsive-ui-testing`
- `testing`
- `runner-selection`Provide comprehensive context in prompts-files, errors, Laravel version, dependencies, and monorepo details-for accurate AI responses
# Effective Context
Use this skill when a Laravel task involves effective context.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `effective-context` topic from `jpcaparas/superpowers-laravel` into the local `effective-context` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to keep Eloquent models explicit, query shapes intentional, relationship loading visible, and production data access bounded.
# Eloquent Patterns
Keep models explicit, query shape intentional, and relationship loading visible near the code that renders or returns data.
## Model Contracts
Models should declare mass-assignment boundaries, casts, and concrete relationship return types.
```php
class Record extends Model
{
protected $fillable = [
'owner_id',
'number',
'total',
'issued_at',
'is_active',
];
protected function casts(): array
{
return [
'issued_at' => 'date',
'total' => 'decimal:2',
'is_active' => 'boolean',
'metadata' => 'array',
];
}
public function owner(): BelongsTo
{
return $this->belongsTo(User::class);
}
}
```
Use accessors sparingly for simple derived values. Move heavy behavior into Actions or Services.
## Relationship Loading
Prevent N+1 queries by eager loading the relations a surface needs.
Before rendering Blade reports, printable views, exports, or PDFs, explicitly load the relation graph.
```php
public function show(Record $record): View
{
$record->load([
'owner',
'items.product',
'approvals.user',
]);
return view('records.show', ['record' => $record]);
}
```
Do not add new relation dependencies inside templates without updating the load list and render tests.
## Query Volume
Do not process unbounded production datasets with `all()` or broad `get()` calls.
Use:
- `paginate()` for normal UI/API lists;
- cursor pagination for large append-only lists;
- `chunkById()` or `lazyById()` when updating rows during iteration;
- `cursor()` or lazy collections for streaming;
- selected columns and indexed filters for high-volume paths.
## Bounded Values
Keep bounded validation/display values in one source of truth.
Prefer enums when supported.
```php
enum RecordStatus: string
{
case Draft = 'draft';
case Approved = 'approved';
case Cancelled = 'cancelled';
public function label(): string
{
return match ($this) {
self::Draft => 'Draft',
self::Approved => 'Approved',
self::Cancelled => 'Cancelled',
};
}
}
```
Use config files for deployment-level options and constants for small legacy/model-owned maps.
## Historical Data
Use soft deletes with `withTrashed()` when historical records must remain readable after related reference data is removed from active use.
Do not use this as a blanket rule for personal data or records subject to hard-delete compliance.
Snapshot attributes that must remain true for a historical document.
```php
DocumentLine::create([
'reference_id' => $reference->id,
'reference_snapshot' => $reference->only(['code', 'name']),
]);
```
Store only fields needed for historical correctness and avoid unnecessary sensitive data.
## Context Efficiency
Layer: 3 (Implementation)
Load this skill only when models or queries need review. Do not load with unrelated skills. Keep changes minimal: explicit casts, eager-loaded relations, paginated queries, no unbounded `all()` or broad `get()` in production paths.Laravel guidance to define clear relationships and load data efficiently; prevent N+1, use constraints, counts/sums, and pivot syncing safely
# Eloquent Relationships
Use this skill when a Laravel task involves eloquent relationships.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `eloquent-relationships` topic from `jpcaparas/superpowers-laravel` into the local `eloquent-relationships` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to use reportable/renderable exceptions, structured logs, and channel strategy for observability and graceful failures
# Exception Handling And Logging
Use this skill when a Laravel task involves exception handling and logging.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `exception-handling-and-logging` topic from `jpcaparas/superpowers-laravel` into the local `exception-handling-and-logging` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Execute Laravel plans in small batches with checkpoints-TDD first, migrations safe, queues verified, and quality gates enforced
# Executing Plans
Use this skill when a Laravel task involves executing plans.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `executing-plans` topic from `jpcaparas/superpowers-laravel` into the local `executing-plans` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Audit completed Laravel projects and propose reusable updates to personal Laravel standards without importing project-specific details.
# Extract Laravel Standards
Use this skill after a Laravel project, feature set, or major module has been completed and the user wants to turn proven patterns into reusable personal standards.
## Workflow
1. Inspect the project structure, Laravel version, PHP version, test stack, formatter, static analysis, CI checks, queue setup, frontend stack, and deployment-sensitive configuration.
2. Identify repeated implementation patterns in controllers, Form Requests, Actions, Services, models, migrations, jobs, policies, Livewire components, tests, and quality tooling.
3. Compare findings against the currently installed Laravel standards before proposing any update.
4. Classify each finding as `NEW`, `UPDATE`, `DUPLICATE`, `CONFLICT`, `PROJECT_ONLY`, or `REJECT`.
5. Promote only conventions that are reusable across unrelated Laravel applications and improve correctness, security, testability, maintainability, consistency, or operational reliability.
6. Remove client names, company names, domains, URLs, credentials, internal identifiers, provider-specific payload quirks, business terminology, and accidental technical debt.
7. Create a proposal in `proposals/pending/` before editing any global skill files.
8. Display the proposed diff and wait for acceptance before moving accepted proposals into standards.
9. Never edit upstream third-party skills or copy external skill text wholesale.
## Proposal Format
Use this structure for each proposal:
~~~markdown
# <Project or Module> Laravel Standards Proposal
## Source Scope
- Audited area:
- Date:
- Verification reviewed:
## Findings
### NEW
- Finding:
- Reason:
- Suggested target file:
### UPDATE
- Existing standard:
- Proposed change:
- Reason:
### PROJECT_ONLY
- Pattern:
- Why it should not become global:
## Sanitization
- Removed identifiers:
- Removed business rules:
- Removed secrets or sensitive details:
## Proposed Diff
```diff
```
~~~
## Global Standard Eligibility
A convention may become global only when it is:
- consistently applied in completed work;
- supported by tests, quality checks, or production feedback;
- aligned with Laravel conventions;
- useful outside the source project;
- free of secrets and project-specific business rules.
Reject temporary workarounds, one-off provider details, accidental complexity, and rules that only make sense for one client or domain.Laravel guidance to store and serve files via Storage; set visibility, generate URLs, and handle streaming safely
# Filesystem Uploads
Use this skill when a Laravel task involves filesystem uploads.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `filesystem-uploads` topic from `jpcaparas/superpowers-laravel` into the local `filesystem-uploads` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Use Laravel Form Requests for non-trivial validation and authorization while keeping controllers thin and testable.
# Form Requests
Use Form Requests for HTTP validation and request-bound authorization when rules are complex, reused, sensitive, or likely to grow.
Inline controller validation is acceptable for tiny prototypes or legacy maintenance, but it is not the global standard for new or heavily edited workflows.
## Responsibilities
A Form Request may:
- authorize the HTTP operation;
- normalize input in `prepareForValidation()`;
- return validation rules;
- use custom messages and attribute labels;
- expose small helper methods for typed validated data.
It should not:
- perform database writes;
- send external requests;
- dispatch jobs;
- contain long business workflows.
## Input Normalization
Normalize human-formatted inputs before applying numeric/date/boolean rules. Keep locale assumptions explicit.
```php
final class StoreRecordRequest extends FormRequest
{
protected function prepareForValidation(): void
{
$this->merge([
'amount' => NumberInput::normalize($this->input('amount')),
]);
}
public function rules(): array
{
return [
'amount' => ['required', 'numeric', 'min:0'],
'status' => ['required', Rule::enum(RecordStatus::class)],
];
}
}
```
Shared parsers should be small helpers or value objects with unit tests.
## Authorization
Use `authorize()` when the decision depends on request context or validated input. Use Policies when the decision depends on model state.
```php
public function authorize(): bool
{
return $this->user()?->can('create', Record::class) === true;
}
```
## Array And Conditional Rules
Validate nested arrays explicitly.
```php
public function rules(): array
{
return [
'items' => ['required', 'array', 'min:1'],
'items.*.name' => ['required', 'string', 'max:120'],
'items.*.quantity' => ['required', 'integer', 'min:1'],
];
}
```
Prefer named custom rule objects when validation has reusable domain meaning.
## Testing
Test validation failures and authorization failures. Cover request normalization when human-formatted values are accepted.
## Context Efficiency
Layer: 3 (Implementation)
Load this skill only when validation or request authorization is nontrivial. Inline tiny validation in controllers only for prototypes or legacy maintenance. Keep Form Requests focused: rules, authorize, prepareForValidation, no database writes or business workflows.Laravel guidance to operate Horizon with confidence-naming, tags, concurrency, failure handling, actionable metrics, and dashboards
# Horizon Metrics And Dashboards
Use this skill when a Laravel task involves horizon metrics and dashboards.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `horizon:metrics-and-dashboards` topic from `jpcaparas/superpowers-laravel` into the local `horizon-metrics-and-dashboards` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to use the HTTP client with sensible timeouts, retries, and backoff; capture context and handle failures explicitly
# Http Client Resilience
Use this skill when a Laravel task involves http client resilience.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `http-client-resilience` topic from `jpcaparas/superpowers-laravel` into the local `http-client-resilience` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Integrate WhatsApp through a secure Baileys sidecar with Laravel, including tests and reusable local Windows and Linux VPS setup documentation.
# Integrate WhatsApp With Baileys And Laravel
Build Baileys as a private Node.js sidecar and keep Laravel as the application, authorization, queue, and user-facing boundary.
## Required references
Read both references before changing the target project:
- [architecture-and-implementation.md](references/architecture-and-implementation.md) for package selection, service boundaries, security, reliability, and tests.
- [deployment-and-documentation.md](references/deployment-and-documentation.md) for Windows, VPS, process management, verification, and the required documentation artifact.
## Workflow
### 1. Inspect before designing
1. Read the target repository instructions and relevant existing documentation.
2. Detect the Laravel and PHP versions, Node package manager and lockfile, Node runtime policy, test framework, queue driver, process manager, deployment layout, and quality tools.
3. Search for existing WhatsApp clients, notification contracts, jobs, admin routes, configuration keys, Baileys services, and documentation. Extend a sound boundary instead of creating a competing integration.
4. Record assumptions. Default an unspecified VPS to Ubuntu/Debian, but label that assumption in the generated documentation.
5. Consult current official Baileys documentation and package metadata before choosing a package or API. Baileys changes frequently; do not rely on remembered package names, versions, exports, or migration behavior.
### 2. Agree on the smallest feature surface
Derive scope from the request. A normal outbound integration needs:
- one private Baileys session;
- connection status and QR or pairing-code lifecycle;
- connect and disconnect operations;
- text-message sending;
- Laravel configuration and a focused integration client;
- authorized admin controls only when the project needs them;
- queued delivery for business workflows when latency or retry behavior warrants it.
Do not add inbound message handling, media, groups, bulk messaging, chat storage, multi-session tenancy, webhooks, or a new admin UI unless requested or already required by project behavior.
### 3. Design before editing
Use this default boundary:
```text
authorized browser or application workflow
-> Laravel
-> private authenticated HTTP API
-> Node.js Baileys sidecar
-> WhatsApp Web socket
```
Keep the sidecar on the same host or a private network. Bind to loopback by default. Never point a public reverse proxy directly at it.
Before implementation, define:
- the sidecar directory and runtime;
- the package/version strategy and lockfile;
- the internal versioned endpoint contract;
- authentication and secret ownership;
- development and production auth-state storage;
- connection states and reconnect rules;
- sync versus queued send behavior;
- duplicate-delivery and retry policy;
- the exact test and smoke-check plan.
### 4. Implement the sidecar
Create or adapt a focused service such as `services/baileys/`. Keep socket state and HTTP transport separated when that materially improves testing; do not create ceremonial layers.
Require the sidecar to provide:
- explicit environment validation and a safe `.env.example`;
- loopback binding by default;
- authenticated, versioned endpoints for status, session operations, and sending;
- bounded JSON bodies and validated phone/message input;
- one connection attempt at a time and one active socket per session;
- credential persistence on every auth update;
- explicit handling for restart-required, logged-out, replaced, transient, and fatal disconnects;
- bounded reconnect backoff with jitter and no reconnect after deliberate logout;
- redacted structured logs, graceful shutdown, and useful exit codes;
- no secrets, QR values, auth state, or full message bodies in logs.
Treat file-based multi-file auth as development/demo storage. Follow the production decision rules in the architecture reference.
### 5. Implement the Laravel boundary
Use Laravel-native configuration and HTTP APIs:
- put environment reads in config files and add placeholders to `.env.example`;
- keep provider request mapping, authentication, timeouts, response parsing, and error translation in a focused client/service;
- add an interface only when multiple drivers or a meaningful domain boundary justify one;
- keep controllers limited to authorization, validated input, orchestration, and responses;
- authorize every admin/session action and retain CSRF protection for browser routes;
- use safe structured logs without tokens, QR data, message content, or unnecessary phone numbers;
- separate connection timeout from total request timeout;
- retry safe status reads only; never blindly retry message sends;
- queue business notifications when appropriate and make retry semantics explicit.
Preserve existing project conventions for routes, responses, translations, admin UI, and tests.
### 6. Verify behavior
Run the smallest meaningful set supported by the project:
1. Node syntax/type, lint, and unit/integration tests.
2. Laravel tests using `Http::fake()` for success, validation failure, unauthorized access, sidecar unavailability, and provider rejection.
3. Queue dispatch and job behavior tests when queued delivery exists.
4. Formatter/static analysis and affected frontend checks.
5. A local smoke check for health/status, connect, QR or pairing code, reconnect, send, disconnect, and restart persistence.
Do not claim an end-to-end WhatsApp send was verified unless a real test account was paired and the result was observed. Report skipped checks and why.
### 7. Write the mandatory project documentation
After implementation and verification, create or update `docs/BAILEYS_SETUP.md` in the target Laravel project. If the project already has a canonical WhatsApp setup document, update that file instead and report the chosen path.
The document must be project-specific, safe to commit, and contain complete local Windows and Linux VPS instructions. Use the required outline and completion rules in the deployment reference. Never place real tokens, session data, phone numbers, domains, usernames, or private paths in it.
### 8. Handoff
Report:
- architecture and scope implemented;
- files changed;
- chosen Baileys package and pinned version;
- development and production auth-state choices;
- tests and smoke checks run;
- documentation path;
- operational or compliance risks that remain.
State clearly that Baileys is unofficial and is not affiliated with Meta or WhatsApp. Do not imply guaranteed delivery, protocol stability, or freedom from account restrictions.Laravel guidance to use interfaces and dependency injection to decouple code; bind implementations in the container
# Interfaces And Di
Use this skill when a Laravel task involves interfaces and di.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `interfaces-and-di` topic from `jpcaparas/superpowers-laravel` into the local `interfaces-and-di` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Build with i18n in mind from day one using Laravel translation helpers, JSON files, Blade integration, and locale management
# Internationalization And Translation
Use this skill when a Laravel task involves internationalization and translation.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `internationalization-and-translation` topic from `jpcaparas/superpowers-laravel` into the local `internationalization-and-translation` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to refine AI-generated code through specific feedback-point out errors, identify gaps, show desired changes, reference style guides
# Iterating On Code
Use this skill when a Laravel task involves iterating on code.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `iterating-on-code` topic from `jpcaparas/superpowers-laravel` into the local `iterating-on-code` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Work in Laravel 11 or 12 apps with stack detection, Boost-aware docs lookup, frontend conventions, tests, and Pint formatting.
# Laravel 11/12 App Guidelines
Use this skill when implementing, fixing, or reviewing Laravel 11 or Laravel 12 applications.
## Start Here
1. Read repository instructions and local docs before making architectural decisions.
2. Confirm Laravel and PHP versions from `composer.json`, `composer.lock`, or `php artisan about` when available.
3. Detect whether commands should run through Sail, Docker Compose, Herd, Valet, or host PHP.
4. Detect app mode: API-only, Blade, Livewire, Inertia, Vue, React, or a mixed legacy stack.
5. Reuse existing conventions for naming, language, layout, components, testing, and error responses.
## Laravel 11/12 Conventions
- Configure middleware, exception handling, and routing in `bootstrap/app.php` when the app follows the modern skeleton.
- Register service providers through `bootstrap/providers.php` when that file exists.
- Place scheduled commands in `routes/console.php` unless the project has an explicit scheduler abstraction.
- Prefer named routes and `route()` generation for internal links and redirects.
- Use Form Requests for non-trivial HTTP validation and request-bound authorization.
- Use API Resources for public JSON response shape when the repo already follows resource patterns.
- Ask before destructive database commands such as `migrate:fresh`, `db:wipe`, reset, rollback, or seed operations that overwrite data.
## Stack-Specific Notes
- API-only apps: work in `routes/api.php`, follow the existing auth stack, and avoid frontend build assumptions.
- Inertia apps: use existing page/component locations and server-side route conventions; prefer the project's form helper pattern.
- Livewire apps: pair this with `livewire-development`.
- Blade apps: keep templates presentational and move reusable decisions out of views.
- Tailwind v4 apps: follow the existing token and import pattern; avoid deprecated utility names when editing nearby UI.
- Wayfinder apps: follow existing generated route import patterns and regenerate route artifacts when the project requires it.
## Laravel Boost
When Laravel Boost MCP tools are available, use them to reduce guessing:
- search Laravel ecosystem docs before changing framework-specific behavior;
- list Artisan commands before assuming command options;
- inspect routes before adding overlapping routes;
- use read-only database inspection for debugging query shape;
- inspect browser logs for frontend failures.
If Boost is unavailable, fall back to local project files and official Laravel documentation.
## Verification
Run targeted tests first, then formatting or static checks that match the touched area. Prefer `vendor/bin/pint --dirty` for changed PHP files when available.Optimize Laravel database work across N+1 queries, indexes, selective columns, caching, pagination, large data, locks, and migrations.
# Laravel Database Optimization
Use this skill when improving query performance, reviewing migrations, debugging slow pages, or reducing memory and database load in Laravel apps.
This skill coordinates existing performance skills and adds an optimization workflow.
## Priority Order
1. Prove the bottleneck with logs, query inspection, profiling, `EXPLAIN`, tests, or realistic data volume.
2. Fix query shape before adding infrastructure: eager loading, constraints, selective columns, aggregates, pagination, and bounded datasets.
3. Add indexes that match actual filters, joins, sorts, and uniqueness rules.
4. Cache only stable or expensive work with explicit invalidation.
5. Review transaction scope, lock behavior, and retry strategy for write-heavy paths.
6. Plan migrations with production data size and lock risk in mind.
## Query Shape
- Prevent N+1 problems with intentional eager loading.
- Select only needed columns on hot paths, including constrained relationship columns.
- Use `withCount`, `withSum`, `exists`, subqueries, or aggregates instead of loading full relations for summaries.
- Avoid unbounded `all()`, broad `get()`, and collection-side filtering on large tables.
- Use cursor pagination or chunking for large ordered datasets and background processing.
## Indexes And Migrations
- Add indexes for foreign keys, common filters, common sort paths, and composite access patterns.
- Match composite index order to the real query pattern.
- Avoid adding indexes speculatively without a query path that needs them.
- For production-scale tables, plan additive and reversible migrations; ask before destructive changes.
- When altering existing columns, preserve existing attributes required by the database platform.
## Caching
- Cache expensive reads behind stable keys and short, intentional TTLs.
- Invalidate cache near the writes that change the underlying data.
- Use tags only when the configured cache store supports them.
- Do not cache user-specific or authorization-sensitive data without including the scope in the key.
## Transactions And Locks
- Keep transactions short and free of slow external calls.
- Use row locks only around data that must remain consistent during the write.
- Use retry logic for known deadlock-prone flows.
- Dispatch jobs, events, notifications, and file cleanup after commit when correctness depends on committed data.
## Related Skills
- `performance-eager-loading`
- `performance-select-columns`
- `performance-caching`
- `data-chunking-large-datasets`
- `migrations-and-factories`
- `database-transactions`Use Laravel-specific vocabulary-Eloquent patterns, Form Requests, API resources, jobs/queues-to get idiomatic framework code
# Laravel Prompting Patterns
Use this skill when a Laravel task involves laravel prompting patterns.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `laravel-prompting-patterns` topic from `jpcaparas/superpowers-laravel` into the local `laravel-prompting-patterns` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Coordinate full Laravel feature work across models, APIs, auth, queues, Livewire, tests, and quality checks by routing to focused skills.
# Laravel Specialist
Layer: 3 (Implementation Orchestrator)
Use this skill for broad Laravel implementation, refactoring, review, or bug-fixing tasks that touch several parts of an application.
This skill assumes Layer 0-2 have already run. If you have not run `memory-management` preflight, `least-code`, and `using-laravel-standards` skill selection yet, do so before loading this skill.
## Workflow
1. Confirm the task shape and primary workflow boundary: HTTP, console, queue, scheduled task, Livewire, API, integration, or data migration.
2. Apply `least-code` minimization: reuse existing helpers, stdlib, native features, installed dependencies before writing new code.
3. Select the smallest focused skills for the task and load only their `SKILL.md`.
4. Apply existing project conventions before introducing new patterns.
5. Verify with the smallest meaningful tests and quality checks.
## Skill Routing
- New feature architecture: `architecture`, `actions-and-services`
- Controllers and routes: `controller-cleanup`, `routes-best-practices`
- Validation and authorization: `form-requests`, `policies-and-authorization`
- Models and queries: `eloquent-patterns`, `eloquent-relationships`
- API responses: `api-resources-and-pagination`, `api-surface-evolution`
- Database writes and consistency: `database-transactions`
- Database performance: `laravel-database-optimization`
- Queues, workers, and Horizon: `queues-and-jobs`
- Livewire implementation, architecture, and tests: `livewire-development`
- Security: `security`, `rate-limiting`, `request-forgery-protection`
- Tests and handoff: `testing`, `tdd-with-pest`, `quality-checks`
## Guardrails
- Keep controllers focused on HTTP orchestration.
- Put reusable workflows in Actions or Services only when they reduce real complexity.
- Use Eloquent relationships, scopes, casts, policies, resources, jobs, events, and framework fakes before custom infrastructure.
- Queue slow external calls, email, exports, imports, and other work that should not block the request.
- Never skip validation, authorization, transaction boundaries, or failure handling because a task is "small".
- Avoid raw SQL unless Eloquent or the query builder cannot express the needed shape clearly or efficiently.
- Keep secrets, client names, private URLs, and one-off business rules out of reusable guidance.
## Handoff
Report the files changed, checks run, and any checks that could not run. If the task touches data shape, include migration and rollback risk in the handoff.Force the laziest working solution before any Laravel skill writes code. Question YAGNI, reuse existing helpers, prefer stdlib/native features, and keep the shortest working diff.
# Least Code
You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
Apply this skill before any focused Laravel implementation, review, or refactor skill. It governs what you build, not how you talk.
## Persistence
ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if unsure. Off only: "stop least-code" / "normal mode". Default: **full**.
Switch:
- `lite`: build what's asked, but name the lazier alternative in one line.
- `full`: the ladder enforced. Stdlib and native first. Shortest diff, shortest explanation. Default.
- `ultra`: YAGNI extremist. Deletion before addition. Ship the one-liner and challenge the rest of the requirement in the same breath.
## Risk classification
Classify the task before implementation. Risk level determines trace depth, verification depth, and review strictness.
- **LOW**: typo, Blade text, CSS kecil, rename lokal.
- Inspect the affected file or component only.
- Syntax/static check is enough.
- No broad trace needed.
- **MEDIUM**: validation, query, Livewire state, controller/service refactor, non-destructive action.
- Trace the affected flow: controller/component → service/model → view/response.
- Targeted feature/unit test plus affected callers.
- Check authorization boundary and regression surface.
- **HIGH**: migration, auth, permission, payroll, financial calculation, concurrency, destructive action, data-shape change.
- Full trace: route → component/controller → validation → service/model → DB → event/job → response/view.
- Architecture/data/security review before patch.
- Regression + failure-path verification required.
- Explicit behavior preservation check mandatory.
## Behavior preservation check
Identify preservation constraints before editing. This is internal mandatory reasoning.
Expose it in user-visible output only when useful for handoff or HIGH-risk work. For LOW tasks, do not output a preservation list; just honor the constraints silently.
Preserve:
- input/output contract
- authorization boundary
- side effects and events
- response shape and redirects
- existing tests that are not explicitly obsolete
## Least-code vs least-risk
Smallest code is not always safest. Prefer the smallest change that preserves existing contracts and minimizes regression risk.
Rule:
- Reuse only when semantics match, not merely because code looks similar.
- A slightly longer existing abstraction is better than a clever one-liner that breaks an implicit contract.
- Mark deliberate simplifications that cut a real corner with a `least-code:` comment naming the ceiling and upgrade path.
## Change surface budget
Prefer, in order:
1. existing line/local expression
2. existing method
3. existing class/component
4. existing module boundary
5. new abstraction/file only when justified
Escalate the change surface only when the lower level cannot solve the root cause safely.
Example: 4 lines touching 5 files is usually worse than 8 lines inside 1 existing component.
## The ladder
Stop at the first rung that holds:
1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
2. **Already in this codebase?** A helper, util, trait, policy, or pattern that already lives here -> reuse it. Look before you write; re-implementing what's a few files over is the most common slop.
3. **Stdlib does it?** Use it.
4. **Native platform feature covers it?** PHP/Laravel built-in, database constraint, HTML input type, queue driver, cache store, auth guard, schedule event -> use it.
5. **Already-installed dependency solves it?** Use it. Never add a new one for what a few lines can do.
6. **Can this be one line?** One line.
7. **Only then:** the minimum code that works.
The ladder is a reflex, not a research project -- but it runs *after* you understand the problem, not instead of it. Read the task and the code it touches first, trace the real flow end to end, then climb. Two rungs work -> take the higher one and move on. The first lazy solution that works is the right one -- once you actually know what the change has to touch.
## Root-cause workflow
Formalize debugging as flow tracing, not symptom patching.
```
symptom
→ entrypoint
→ state/data flow
→ implementation
→ callers
→ persistence
→ rendering/output
```
For Laravel/Livewire specifically:
```
route
→ component/controller
→ validation
→ service/model
→ DB
→ event/job
→ response/view
```
**Bug fix = root cause, not symptom.** A report names a symptom. Before you edit, grep every caller of the function you're about to touch. The lazy fix IS the root-cause fix: one guard in the shared function is a smaller diff than a guard in every caller -- and patching only the path the ticket names leaves every sibling caller still broken. Fix it once, where all callers route through.
### Root-cause confidence
After tracing, classify confidence before patching:
- **CONFIRMED** — Evidence directly proves root cause.
- **LIKELY** — Evidence strongly suggests root cause but reproduction/test is incomplete.
- **UNKNOWN** — Insufficient evidence; do not perform speculative invasive fixes.
Never state "root cause is X" when confidence is LIKELY or UNKNOWN. Say so explicitly.
## Stop condition
Stop exploration once the execution path, affected callers, contract, and verification surface are sufficiently understood.
Do not grep the entire repository to feel safe. Trace the real call graph and the real data flow. If the change touches 3 files and you understand why, stop.
## Test creation rules
Do not add tests mechanically.
Add or update a regression test when:
- fixing a reproducible bug;
- changing business-critical behavior;
- changing authorization or validation boundaries;
- the affected behavior is not already adequately covered.
Prefer extending the nearest existing test over creating a new test structure.
Trivial one-liners need no test. YAGNI applies to tests too.
## Rules
- No unrequested abstractions: no interface with one implementation, no repository for one model, no service for one method, no config for a value that never changes.
- No boilerplate, no scaffolding "for later", later can scaffold for itself.
- Deletion over addition. Boring over clever, clever is what someone decodes at 3am.
- Fewest files possible. Shortest working diff wins -- but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
- Complex request? Ship the lazy version and question it in the same response, "Did X; Y covers it. Need full X? Say so." Never stall on an answer you can default.
- Two stdlib options, same size? Take the one that's correct on edge cases. Lazy means writing less code, not picking the flimsier algorithm.
- Mark deliberate simplifications that cut a real corner with a `least-code:` comment naming the ceiling and upgrade path.
## Anti-pattern: false reuse
Reuse only when semantics match, not merely because code looks similar.
Bad:
- Reusing a payroll helper for reimbursement just because both involve money math.
- Reusing a filter scope for an admin report just because both filter by date.
Good:
- Reusing a session-persisted filter helper when the new feature explicitly uses session state.
- Reusing a notification channel when the delivery contract is identical.
If the abstraction was designed for a different domain, cost, or invariant, it is not a match.
## Boundaries
Never simplify away: input validation at trust boundaries, error handling that prevents data loss, security measures, accessibility basics, anything explicitly requested. User insists on the full version -> build it, no re-arguing.
Never lazy about understanding the problem. The ladder shortens the solution, never the reading. Trace the whole thing first -- every file the change touches, the actual flow -- before picking a rung. Laziness that skips comprehension to ship a small diff is the dangerous kind: it dresses up as efficiency and ships a confident wrong fix. Read fully, then be lazy.
Lazy code without its check is unfinished. Non-trivial logic (a branch, a loop, a parser, a money/security path) leaves ONE runnable check behind, the smallest thing that fails if the logic breaks: an `assert`-based `demo()`/`__main__` self-check or one small `tests/Feature/*Test.php`. No frameworks, no fixtures, no per-function suites unless asked. Trivial one-liners need no test, YAGNI applies to tests too.
## Output
Routine task: maksimal 3-5 baris.
Complex/debug/high-risk: boleh lebih panjang.
Selalu prioritaskan:
- changed
- verified
- remaining risk
Pattern:
```
Fixed filter persistence in PaymentTable.
Reused existing session-state pattern; no new abstraction.
Verified search -> payment -> reload flow and unauthorized path.
```
If the explanation is longer than the code, delete the explanation. Every paragraph defending a simplification is complexity smuggled back in as prose. Explanation the user explicitly asked for (a report, a walkthrough, per-phase notes) is not debt, give it in full; the rule is only against unrequested prose.Build, refactor, secure, optimize, and test Laravel Livewire v2-v4 components, including state, forms, events, uploads, pagination, Alpine, and v4 formats.
# Livewire Development
Use this skill for Laravel Livewire implementation, refactoring, debugging, security review, performance work, and tests.
This is the canonical Livewire skill in this repository. It consolidates the former `livewire-patterns` guidance and the public `laravel-livewire` topic into one version-aware workflow.
When the Livewire work is primarily UI/UX design, visual browser iteration, frontend flow shaping, or backend contract alignment, also use `ui-agent-browser`. Use `e2e-playwright` when browser behavior needs durable Playwright coverage.
## Detect The Project First
1. Read `composer.json` and `composer.lock` or run `composer show livewire/livewire` to confirm the installed major version.
2. Inspect existing components, routes, tests, layouts, and `config/livewire.php` before choosing syntax.
3. Detect whether the project uses class-based components, Volt, Livewire v4 single-file components, multi-file components, or a mixture maintained for compatibility.
4. Follow the project's Blade, Alpine, Tailwind, Flux, Filament, and testing conventions when present.
5. Use documentation for the installed major version. Do not introduce v4-only attributes, directives, component paths, or routing into v2/v3 projects.
Read [references/livewire-4.md](references/livewire-4.md) when the project uses Livewire v4 or the task involves v4 migration, component formats, directives, attributes, or routing.
## Implementation Workflow
1. Define one interactive surface and its user-visible states.
2. Choose the component format already used by the project; change formats only for a concrete maintenance benefit.
3. Model the smallest public state needed by the template.
4. Add validation and authorization before persistence or external side effects.
5. Delegate reusable domain workflows to Actions or Services.
6. Shape queries deliberately, add loading and error feedback, and keep DOM identity stable.
7. Test validation, authorization, persistence, events, redirects, and browser-only behavior at the appropriate level.
## Component Boundaries
A component may:
- hold UI and request-shaped state;
- validate input and authorize actions;
- call an Action or Service;
- dispatch focused events;
- coordinate rendering, pagination, uploads, and browser feedback.
A component should not:
- contain long multi-model workflows;
- build provider payloads inline;
- duplicate model-state authorization that belongs in Policies;
- keep secrets, unbounded collections, or large serialized graphs in public state;
- perform slow external calls during rendering;
- bypass a transaction for atomic writes.
## State And Security
- Treat every public property and action parameter as untrusted client input.
- Validate input and authorize the resolved model or operation inside every mutating action.
- Prefer model binding or explicit model lookup followed by a Policy check; never trust a submitted identifier by itself.
- Use `#[Locked]` only where supported to prevent client mutation of identifiers, but keep authorization because locking is not access control.
- Keep helper methods `protected` or `private` when they must not be callable as component actions.
- Store secrets and service credentials in configuration or injected services, never component state.
- Restrict mass-assignment payloads to validated, explicitly selected fields.
Read [references/testing-and-security.md](references/testing-and-security.md) for a secure action pattern, testing matrix, and browser-test boundaries.
## Forms And Data Binding
- Use Livewire validation for component-local forms.
- Use Form objects when a form has substantial state or rules; move reusable domain rules to shared rule objects or services.
- Normalize localized numbers, dates, booleans, and text before applying validation rules.
- Use plain `wire:model` when synchronization on the next action is sufficient.
- Use `.live`, `.blur`, `.change`, debounce, or throttle deliberately; avoid extra requests without a UX requirement.
- Reset or pull state after successful submission when the interaction should return to a clean form.
- Show field-level errors and disable or style in-flight actions to prevent accidental duplicate submissions.
## Queries, Rendering, And Performance
- Eager load relationships used by the view and select only required columns on hot paths.
- Paginate lists instead of storing unbounded Eloquent collections in public properties.
- Keep `render()` and computed properties free of hidden repeated or unbounded queries.
- Cache computed results across requests only when keys, authorization scope, invalidation, and staleness are understood.
- Add stable `wire:key` values to repeated components and dynamic list items.
- Re-key dependent controls when their available options depend on another field.
- Lazy-load below-the-fold or expensive components only when the installed Livewire version supports the chosen API.
- Prefer the project's existing loading-state pattern; Livewire v4 can style automatic `data-loading` attributes, while `wire:loading` remains useful for targeted visibility.
## Events, Nesting, And JavaScript
- Prefer direct props and actions for parent-child relationships; use events for decoupled UI coordination.
- Keep event names local, intention-revealing, and payloads small.
- Use reactive/modelable props only when the installed version supports them and the parent-child synchronization is necessary.
- Use Alpine for truly client-local state such as disclosure, focus, or transitions.
- Use Livewire JavaScript hooks or component scripts for browser APIs and third-party widgets; isolate initialization and cleanup so DOM morphing does not duplicate handlers.
- Use browser tests for focus management, modals, uploads, previews, drag/drop, navigation, and third-party JavaScript integration.
## Testing And Handoff
Test the smallest behavior that proves the risk:
- component rendering and initial state;
- validation failures and normalized input;
- authorization denial for properties and action parameters;
- successful database changes and transaction boundaries;
- dispatched events, redirects, pagination, uploads, and query-string state;
- loading, focus, modal, navigation, and JavaScript behavior in a browser test when component tests cannot prove it.
Use factories and Laravel fakes for files, queues, notifications, mail, and HTTP integrations. Run targeted tests, formatting, static analysis, and frontend checks supported by the project before handoff.
## Related Skills
- `actions-and-services` for reusable workflows and integrations.
- `database-transactions` for atomic multi-write actions.
- `filesystem-uploads` for storage and file lifecycle rules.
- `policies-and-authorization` for model access decisions.
- `ui-agent-browser` for stack-aware UI/UX implementation and browser inspection.
- `e2e-playwright` for durable browser workflow coverage.
- `responsive-ui-testing` for viewport and browser-state coverage.
- `testing` for test selection and handoff verification.Provide automatic long-term Laravel AI memory preflight, recall, checkpointing, and secure cross-project context across conversation, project, user, workflow, and codebase scopes.
# Memory Management
Layer: 0 (Preflight)
Use this skill as the mandatory first layer before any Laravel skill writes code. It loads only the memory needed for the current task, then hands off to the next layer.
## Core Principles
- Remember only what remains useful.
- Retrieve only what is relevant.
- Verify before trusting.
- Anonymize before sharing across projects.
- Never persist secrets.
- Preserve provenance for every durable entry.
- Prefer continuity without context overload.
## Mandatory Preflight
Run this before any broad exploration or skill selection:
```bash
node <skill-dir>/scripts/memory.mjs auto --cwd <project-root> --query "<task intent>" --limit 5
```
This returns compact relevant memory. Do not load every memory file by default.
## Recall Budget
Default recall budget:
- User memory: ~200 tokens
- Conversation memory: ~500 tokens
- Project memory: ~800 tokens
- Workflow memory: ~400 tokens
- Codebase context: remaining budget up to ~2200 tokens
- Reserve: ~400 tokens
Stop retrieving when marginal relevance is lower than token cost.
## Graph Memory
When `memory-graph.json` exists, query the graph before opening Markdown evidence:
```bash
node <skill-dir>/scripts/memory.mjs graph query "<task intent>" --limit 5
node <skill-dir>/scripts/memory.mjs graph path <from-id> <to-id>
node <skill-dir>/scripts/memory.mjs graph explain <memory-id>
```
Use graph edges with confidence tags:
- `EXTRACTED` = explicit in source
- `INFERRED` = derived by reasoning
- `AMBIGUOUS` = weak or conflicting evidence
## Memory Staleness
Memory is not forever. Every memory entry should carry a lifecycle:
- `CURRENT` - actively valid and aligned with current codebase.
- `STALE` - likely outdated; verify before trusting.
- `SUPERSEDED` - replaced by newer memory or current code.
- `TEMPORARY` - valid only for the current session or short horizon.
When the codebase or architecture changes, mark older project memories as `STALE` or `SUPERSEDED` rather than deleting them. Prefer current code over old memory.
## Source Precedence
When memory and current evidence conflict, trust this order:
1. Current code
2. Current config
3. Project docs
4. Explicit project memory
5. Conversation memory
6. Inferred memory
This prevents memory poisoning during implementation.
## Selective Checkpointing
Do not checkpoint everything. Store only reusable durable knowledge:
- architectural decision
- non-obvious constraint
- bug root cause that is reusable
- project convention
- environment quirk
Do not store:
- line-number changes
- temporary debug notes
- short-lived branches
- one-time grep results
## Decision Memory
Prefer storing the decision, not just the fact.
Good:
- Chose session-persisted filters instead of query-string persistence because existing project convention uses session state.
Bad:
- Search filter uses session.
Decision memory helps the next agent understand why, not just what.
## Checkpoint At Handoff
Run checkpoint after meaningful work:
```bash
node <skill-dir>/scripts/memory.mjs checkpoint --project <alias> --summary "<handoff summary>" --pending "<open questions>" --files "app/Actions/Foo.php,tests/Feature/FooTest.php"
```
## Security Pipeline
Before writing memory, pass data through:
```text
raw input -> secret detection -> personal-data classification -> scope classification -> anonymization -> retention policy -> encryption at rest -> memory storage
```
Never store secrets, raw emails, phone numbers, .env contents, or customer personal data.
## References
- Graph memory commands and formats: `references/graph-memory.md`
- Hermes-style orchestrator profile: `references/hermes-orchestrator-profile.md`
- MCP/hook installation targets: `references/install-targets.md`Laravel guidance to safe database change patterns; when to modify vs add migrations; always pair models with migrations and factories; seeding guidance
# Migrations And Factories
Use this skill when a Laravel task involves migrations and factories.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `migrations-and-factories` topic from `jpcaparas/superpowers-laravel` into the local `migrations-and-factories` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Build Laravel projects with one menu or page per module, using small controllers, per-page views, shared layouts/components, and dynamic DB-backed data.
# Module Per Menu
Use this skill whenever creating, copying, refactoring, or expanding a Laravel web application with multiple menus, pages, dashboards, reports, or admin screens.
Default to a module-per-menu structure unless the existing project already has a stronger convention.
## Standard Pattern
Use this shape for Laravel apps with menus or pages:
```text
Route -> Small Page/Resource Controller -> Action/Service/Query Service when needed -> Eloquent -> View/API Response
```
Organize UI work so one menu or page maps to one clear module:
```text
app/Http/Controllers/<Domain>/
AuthController.php
DashboardController.php
GateInController.php
GateOutController.php
CustomerController.php
ReportController.php
app/Services/<Domain>/
DashboardReportService.php
BillingService.php
DailyReportService.php
resources/views/<domain>/
layouts/app.blade.php
pages/dashboard.blade.php
pages/gate-in/index.blade.php
pages/gate-in/create.blade.php
pages/gate-out/index.blade.php
pages/gate-out/process.blade.php
components/filters.blade.php
components/table.blade.php
```
## Controller Rules
- Keep controllers small and readable.
- Create one controller per menu, page group, or resource boundary.
- Let controllers orchestrate HTTP only: receive request, call validation/authorization, call service/action/query, return view/redirect/JSON.
- Move repeated query/report calculations to a Service or query object.
- Move multi-step writes to Actions or Services with explicit transactions when needed.
- Do not put unrelated menus into one controller just because they share a layout.
- Do not use one giant `PageController` or one giant `DepoWebController` for a full admin system.
## View Rules
- Use one Blade view per page or page state.
- Use a shared layout for sidebar, topbar, shell, asset loading, and page header.
- Use Blade components or partials for repeated filters, tables, badges, stats, modals, and form controls.
- Keep page Blade files focused on rendering one menu/page.
- Do not put all menus into one Blade file with large `@if ($active === ...)` blocks.
- Keep display data dynamic from Eloquent/model-backed services. Avoid hardcoded metrics except placeholders explicitly marked as prototype/demo.
## Route Rules
- Keep route files as mappings only.
- Use route groups for middleware, prefixes, and shared names.
- Place static routes before broad parameter routes.
- Prefer invokable controllers for single-page modules and normal controllers for page groups.
- Add route/render tests for every important menu or page.
## Dynamic Data Rules
- Build page metrics, summaries, charts, tables, and select options from database queries or model-backed services.
- Derive counts and totals from Eloquent collections or queries instead of duplicating numbers in Blade.
- Use Services for dashboards, financial reports, daily reports, billing quotes, sync contracts, or other reusable calculations.
- Keep seeded/demo data in seeders and factories, not embedded in views.
## Verification
Before handoff, run the smallest meaningful checks available:
- route list for changed route groups;
- feature tests that open each authenticated menu/page;
- API contract tests for new endpoints;
- `php artisan test`;
- Blade compile check such as `php artisan view:cache` followed by `php artisan view:clear`;
- frontend build when assets changed.
Report any checks that cannot run and why.Laravel guidance to consistent Nova resources-fields, actions, metrics, lenses, filters, authorization-and how to evolve resources alongside schema changes
# Nova Resource Patterns
Use this skill when a Laravel task involves nova resource patterns.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `nova:resource-patterns` topic from `jpcaparas/superpowers-laravel` into the local `nova-resource-patterns` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to use framework caches and value/query caching to reduce work; add tags, locks, and explicit invalidation strategies for correctness
# Performance Caching
Use this skill when a Laravel task involves performance caching.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `performance-caching` topic from `jpcaparas/superpowers-laravel` into the local `performance-caching` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to prevent N+1 queries by eager loading; enable lazy-loading protection in non-production; choose selective fields
# Performance Eager Loading
Use this skill when a Laravel task involves performance eager loading.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `performance-eager-loading` topic from `jpcaparas/superpowers-laravel` into the local `performance-eager-loading` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to select only required columns to reduce memory and transfer costs; apply to base queries and relations
# Performance Select Columns
Use this skill when a Laravel task involves performance select columns.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `performance-select-columns` topic from `jpcaparas/superpowers-laravel` into the local `performance-select-columns` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Use first-party PHP attributes (Laravel 13+) for controllers, authorization, queue jobs, and models; declarative configuration colocated with code
# Php Attributes
Use this skill when a Laravel task involves php attributes.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `php-attributes` topic from `jpcaparas/superpowers-laravel` into the local `php-attributes` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to enforce access via Policies and Gates; use authorize() and authorizeResource() to standardize controller protections
# Policies And Authorization
Use this skill when a Laravel task involves policies and authorization.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `policies-and-authorization` topic from `jpcaparas/superpowers-laravel` into the local `policies-and-authorization` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to use hexagonal architecture for external systems; define ports (interfaces) and per-provider adapters; select adapter at composition edge
# Ports And Adapters
Use this skill when a Laravel task involves ports and adapters.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `ports-and-adapters` topic from `jpcaparas/superpowers-laravel` into the local `ports-and-adapters` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to structure prompts for clarity-separate concerns, prioritize requests, specify acceptance criteria, and break work into testable increments
# Prompt Structure
Use this skill when a Laravel task involves prompt structure.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `prompt-structure` topic from `jpcaparas/superpowers-laravel` into the local `prompt-structure` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Unified quality gates for Laravel projects; Pint, static analysis (PHPStan/Psalm), Insights (optional), and JS linters; Sail and non-Sail pairs provided
# Quality Checks
Use this skill when a Laravel task involves quality checks.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `quality-checks` topic from `jpcaparas/superpowers-laravel` into the local `quality-checks` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
## Context Efficiency
Layer: 4 (Verification)
Load this skill only when quality gates are needed. Do not load with unrelated skills. Run the smallest meaningful check set: Pint, static analysis, tests. Skip checks that cannot run and report the command.
- `security`Design and operate Laravel queues, jobs, workers, and Horizon with retry safety, idempotency, failure handling, tests, and production visibility.
# Queues And Jobs
Use queues for work that can happen outside the request cycle: notifications, imports, exports, media processing, integration callbacks, long-running calculations, and retryable external operations.
This is the canonical queue skill. It consolidates the former `queues-and-horizon` topic while keeping `horizon-metrics-and-dashboards` for focused observability work.
## Detect The Queue Stack
Confirm the queue connection, worker manager, Horizon installation, failed-job storage, deployment process, and local runner before changing configuration or issuing operational commands. Do not assume Horizon is installed merely because Redis is used.
## Job Design
Queued jobs should be safe to retry.
Prefer:
- passing IDs or small scalar payloads;
- reloading models in `handle()`;
- explicit `tries`, backoff, timeout, and failure behavior when the job is important;
- idempotency keys or state checks for external side effects;
- after-commit dispatch when jobs depend on committed records.
```php
final class ProcessRecord implements ShouldQueue
{
public function __construct(public int $recordId)
{
}
public function handle(): void
{
$record = Record::query()->findOrFail($this->recordId);
if ($record->processed_at !== null) {
return;
}
// Perform idempotent work.
}
}
```
## Dispatching
Dispatch after commit when a queued job needs database writes to be visible.
```php
ProcessRecord::dispatch($record->id)->afterCommit();
```
## Failure Handling
Separate transient failures from permanent failures. Retry network and temporary provider issues; fail fast for invalid state or bad input.
Log failures with redacted context. Do not log secrets, tokens, signatures, full payloads, or unnecessary personal data.
## Horizon And Workers
Do not force Horizon on every project. Use Horizon or equivalent visibility when queue volume, failed jobs, throughput, or production support justifies it.
Worker configuration should account for:
- queue priorities;
- memory limits;
- timeouts;
- retry/backoff;
- graceful restarts;
- failed job storage.
When Horizon is installed:
- align supervisors with real queue names and priorities;
- keep worker timeout below the queue driver's retry-after window;
- balance processes based on workload behavior rather than one global queue;
- tag jobs with low-cardinality identifiers that help operators diagnose failures;
- protect the dashboard with production authorization;
- terminate or restart workers through the deployment lifecycle so new code is loaded safely.
Without Horizon, apply the same timeout, memory, retry, graceful-restart, and failed-job expectations to the selected process manager.
## Scheduling
Scheduled tasks should use overlap protection for long-running or non-reentrant work.
```php
Schedule::command('records:process')
->everyFiveMinutes()
->withoutOverlapping()
->onOneServer();
```
Keep scheduled commands testable independently from cron.
## Testing
Use `Queue::fake()` or `Bus::fake()` to assert dispatching. Test job behavior directly when the job contains meaningful logic.
Also verify retry/idempotency behavior, failure callbacks, batch or chain behavior when used, and after-commit dispatch for jobs that depend on newly written data. For operational changes, inspect the effective worker/Horizon configuration and perform a safe local smoke test when the required services are available.Laravel guidance to apply per-user and per-route limits with RateLimiter and throttle middleware; use backoffs and headers for clients
# Rate Limiting
Use this skill when a Laravel task involves rate limiting.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `rate-limiting` topic from `jpcaparas/superpowers-laravel` into the local `rate-limiting` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Configure CSRF and origin-aware request forgery protection; PreventRequestForgery middleware (Laravel 13+) with token fallback and exclusions
# Request Forgery Protection
Use this skill when a Laravel task involves request forgery protection.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `request-forgery-protection` topic from `jpcaparas/superpowers-laravel` into the local `request-forgery-protection` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Audit Laravel responsive UI with Playwright across mobile, tablet, desktop, Livewire states, overflow, clipping, forms, tables, modals, and navigation.
# Responsive UI Testing
Use this skill when asked to test whether a Laravel application interface is responsive, mobile-friendly, or visually stable across screen sizes.
Do not conclude that a page is responsive merely because it loads on one mobile viewport or has no JavaScript errors.
When the request is to design, redesign, or implement the frontend before auditing it, use `ui-agent-browser` first. This skill is the final responsive and visual-stability gate after the UI and backend contract are already wired.
Use `e2e-playwright` when responsive findings should become durable Playwright regression tests.
## Primary Goals
Verify that the application remains usable and visually correct across:
- small mobile
- standard mobile
- large mobile
- tablet portrait
- laptop
- desktop
- wide desktop when the project has wide layouts or dashboards
## Required Viewports
Test at least these viewports:
| Target | Width | Height |
|---|---:|---:|
| Small mobile | 320 | 568 |
| Standard mobile | 375 | 812 |
| Large mobile | 430 | 932 |
| Tablet portrait | 768 | 1024 |
| Laptop | 1366 | 768 |
| Desktop | 1920 | 1080 |
Also test Playwright mobile device profiles when available, such as an iPhone and a Pixel device.
## Required Checks
For every tested page and viewport:
1. Navigate to the page and wait until network, fonts, images, and Livewire activity settle.
2. Check for horizontal document overflow.
3. Check whether visible elements extend outside the viewport.
4. Detect clipped, overlapping, or unreadable text.
5. Verify the navbar does not stack into unusable controls.
6. Verify the sidebar can open and close on small screens.
7. Verify forms can be completed without horizontal scrolling.
8. Verify buttons and links remain visible, clickable, and large enough for touch.
9. Verify tables have deliberate mobile behavior such as horizontal scroll, stacked cards, hidden secondary columns, or a redesigned mobile layout.
10. Verify modals, dropdowns, date pickers, and select menus fit inside the viewport.
11. Verify fixed and sticky elements do not cover important content.
12. Verify images keep their intended aspect ratio and do not stretch or crop important content accidentally.
13. Interact with Livewire components and repeat layout checks after state changes, validation errors, pagination, filtering, sorting, loading states, and empty states.
14. Test dark mode when the project supports it.
15. Capture screenshots for review.
16. Report failures with page, viewport, browser or device, selector, and evidence.
## Horizontal Overflow Check
Use a browser-side assertion like this:
```ts
const overflow = await page.evaluate(() => ({
scrollWidth: document.documentElement.scrollWidth,
clientWidth: document.documentElement.clientWidth,
hasOverflow:
document.documentElement.scrollWidth >
document.documentElement.clientWidth + 1,
}));
expect(
overflow.hasOverflow,
`Horizontal overflow: ${overflow.scrollWidth}px > ${overflow.clientWidth}px`,
).toBeFalsy();
```
## Element Boundary Check
Inspect visible elements and report those extending outside the viewport:
```ts
const offenders = await page.evaluate(() => {
const viewportWidth = window.innerWidth;
const viewportHeight = window.innerHeight;
return Array.from(document.querySelectorAll("body *"))
.filter((element) => {
const htmlElement = element as HTMLElement;
const style = window.getComputedStyle(htmlElement);
const rect = htmlElement.getBoundingClientRect();
if (
style.display === "none" ||
style.visibility === "hidden" ||
rect.width === 0 ||
rect.height === 0
) {
return false;
}
return (
rect.left < -1 ||
rect.right > viewportWidth + 1 ||
rect.top < -1 ||
rect.bottom > viewportHeight + 1
);
})
.slice(0, 50)
.map((element) => ({
tag: element.tagName.toLowerCase(),
id: element.id,
className: String((element as HTMLElement).className),
text: element.textContent?.trim().slice(0, 80),
rect: element.getBoundingClientRect().toJSON(),
}));
});
expect(offenders).toEqual([]);
```
Treat fixed-position overlays and intentionally scrollable containers carefully. Do not automatically mark deliberate off-canvas navigation as a failure.
## Playwright Test Skeleton
Create or update a project-local browser test such as `tests/e2e/responsive.spec.ts` when the project uses Playwright:
```ts
import { expect, test } from "@playwright/test";
const viewports = [
{ name: "mobile-320", width: 320, height: 568 },
{ name: "mobile-375", width: 375, height: 812 },
{ name: "mobile-430", width: 430, height: 932 },
{ name: "tablet-768", width: 768, height: 1024 },
{ name: "laptop-1366", width: 1366, height: 768 },
{ name: "desktop-1920", width: 1920, height: 1080 },
];
const routes = ["/dashboard", "/settings"];
for (const viewport of viewports) {
test.describe(viewport.name, () => {
test.use({ viewport });
for (const route of routes) {
test(`${route} is responsive`, async ({ page }, testInfo) => {
await page.goto(route);
await page.waitForLoadState("networkidle");
await page.evaluate(() => document.fonts?.ready);
const overflow = await page.evaluate(() => ({
documentWidth: document.documentElement.scrollWidth,
viewportWidth: document.documentElement.clientWidth,
}));
expect(
overflow.documentWidth,
`Horizontal overflow on ${route}`,
).toBeLessThanOrEqual(overflow.viewportWidth + 1);
await expect(page).toHaveScreenshot(
`${route.replaceAll("/", "-") || "home"}-${testInfo.project.name}.png`,
{ fullPage: true, animations: "disabled" },
);
});
}
});
}
```
Adapt routes to the real Laravel app. Seed deterministic data and authenticate through existing project helpers before asserting protected pages.
## Visual Regression Rules
Use screenshots for stable pages after:
- disabling animations
- freezing or mocking dynamic timestamps
- using deterministic seed data
- hiding unstable third-party widgets
- waiting for fonts and images
- avoiding screenshot comparison across inconsistent operating systems
## Laravel-Specific Checks
Inspect:
- Blade layouts and components
- Livewire components after state changes
- validation error messages
- authorization-dependent navigation
- paginated tables
- flash messages
- file-upload components
- loading indicators
- empty states
- long translated strings
- Tailwind or FlyonUI breakpoint classes
- dark mode variants when configured
## Reporting Format
Group findings by severity:
- Critical: the page cannot be used at a tested viewport.
- Major: important content or controls are clipped, inaccessible, overlapping, or impossible to operate.
- Minor: visual spacing or alignment is degraded but functionality remains usable.
For every issue include:
- route or page
- viewport
- browser or device
- affected component
- expected behavior
- actual behavior
- screenshot path
- probable source file
- recommended fix
## Completion Gate
Do not declare the application responsive unless:
- all required viewports were tested
- no unexplained horizontal document overflow exists
- navigation, sidebars, and core forms remain usable
- tables and modals have deliberate mobile behavior
- interactive Livewire states were tested
- dark mode was tested when supported
- failures and untested pages are explicitly reportedLaravel guidance to keep routes clean and focused on mapping requests to controllers; avoid business logic, validation, or database operations in route files
# Routes Best Practices
Use this skill when a Laravel task involves routes best practices.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `routes-best-practices` topic from `jpcaparas/superpowers-laravel` into the local `routes-best-practices` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Bootstrap Laravel projects by detecting Sail or host tooling, verifying dependencies and services, and choosing consistent PHP, Composer, Node, and test commands.
# Runner Selection
Use this skill before executing Laravel commands in an unfamiliar repository. It consolidates the former `bootstrap-check` skill into one environment-detection workflow.
## Detection Order
1. Read project instructions for required containers, wrappers, or task runners.
2. Check for `vendor/bin/sail`, Docker Compose files, and a Sail dependency in `composer.json`.
3. Check whether the expected containers are already running and whether required services are healthy.
4. If Sail is absent, verify host `php`, `composer`, `node`, and the selected package manager.
5. Inspect `composer.json`, lock files, `package.json`, and test configuration before choosing commands.
Prefer Sail when the project is configured around it and its services are available. Use host tooling when the repository is intentionally non-Sail or the user has chosen the host workflow.
Do not silently mix runners within one verification sequence. Container and host PHP versions, extensions, environment variables, databases, and filesystem permissions may differ.
## Command Map
| Task | Sail | Host |
| --- | --- | --- |
| Artisan | `./vendor/bin/sail artisan ...` | `php artisan ...` |
| Composer | `./vendor/bin/sail composer ...` | `composer ...` |
| PHP tests | `./vendor/bin/sail artisan test ...` | `php artisan test ...` |
| Pint | `./vendor/bin/sail pint ...` | `vendor/bin/pint ...` |
| Node script | `./vendor/bin/sail npm run ...` | `npm run ...` |
Use the package manager selected by the lock file. Do not replace npm, pnpm, Yarn, or Bun merely because another tool is installed globally.
## Bootstrap Checks
- Required PHP and Node versions match project constraints.
- Composer and frontend dependencies are installed.
- `.env` exists when runtime commands need it, without printing secrets.
- The application key and writable directories are ready when relevant.
- Database, cache, queue, mail, search, and browser-test services required by the task are reachable.
- Pending migrations are understood before applying them.
- Test environment configuration points to safe, non-production services.
Starting containers or applying migrations changes local state. Do it when the requested workflow requires it; otherwise report the exact readiness issue and the command that would resolve it.
## Output
State the selected runner once, then use it consistently. When handing off, report environment limitations that prevented a check from running.Run focused Laravel security checks for authorization, request forgery, rate limits, uploads, secrets, APIs, and configuration.
# Security
Run a focused security pass whenever work touches authentication, authorization, input handling, uploads, external integrations, payment-like flows, public APIs, or sensitive data.
## Access Control
Every route/action that reads or mutates protected data needs authorization.
Use:
- route middleware for coarse access boundaries;
- Policies for model actions;
- Gates for cross-cutting checks;
- Form Request `authorize()` for request-input-dependent checks.
Test both allowed and denied paths.
## Request Forgery And Rate Limits
Use CSRF protection for browser forms. Exclude webhooks only deliberately, and authenticate webhook requests through signatures, shared secrets, IP allowlists, or provider verification as appropriate.
Apply rate limits to abuse-prone routes such as login, password reset, public forms, file uploads, and expensive API endpoints.
## Input And Output Safety
Validate all request input at the boundary. Use query builder bindings or Eloquent instead of interpolated raw SQL.
Escape output in Blade. Be deliberate about HTML rendering.
For frontend stacks, expose only the props needed by the page. Do not send hidden sensitive data because it is "not displayed."
## Uploads And Files
Validate uploaded files for:
- required/optional state;
- MIME/type;
- extension if relevant;
- size;
- count;
- image dimensions when needed.
Store files through Laravel `Storage`. Do not trust original filenames for storage paths. Keep visibility explicit.
## Secrets And Logs
Keep credentials in environment/config, not database-backed admin settings or source files.
Do not log:
- tokens;
- signatures;
- passwords;
- card data;
- full provider payloads;
- unnecessary personally identifiable information.
Use structured logs with safe identifiers and sanitized summaries.
```php
Log::info('integration.gateway.create.completed', [
'record_id' => $record->id,
'reference' => $record->public_reference,
'provider_status' => $response->status(),
]);
```
## API Security
For APIs:
- return consistent errors;
- hide stack traces;
- validate input;
- authorize every action;
- apply rate limits;
- avoid leaking internal IDs when public identifiers are needed;
- add compatibility tests for consumed response shapes.
## Dependency And Configuration Review
When dependency or deployment configuration changes are in scope:
- check for known advisories;
- remove unused packages;
- avoid exposing frontend env values that are not meant for browsers;
- verify production debug settings are safe.Laravel guidance to define clear constraints-performance, security, testing, architecture, dependencies-so AI generates code that meets your project standards
# Specifying Constraints
Use this skill when a Laravel task involves specifying constraints.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `specifying-constraints` topic from `jpcaparas/superpowers-laravel` into the local `specifying-constraints` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to use the Strategy pattern to select behavior at runtime; bind multiple implementations to a shared interface
# Strategy Pattern
Use this skill when a Laravel task involves strategy pattern.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `strategy-pattern` topic from `jpcaparas/superpowers-laravel` into the local `strategy-pattern` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to schedule tasks with safety; use withoutOverlapping, onOneServer, and visibility settings for reliable cron execution
# Task Scheduling
Use this skill when a Laravel task involves task scheduling.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `task-scheduling` topic from `jpcaparas/superpowers-laravel` into the local `task-scheduling` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to apply RED-GREEN-REFACTOR with Pest or PHPUnit; use factories, feature tests for HTTP, and parallel test runners; verify failures before implementation
# Tdd With Pest
Use this skill when a Laravel task involves tdd with pest.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `tdd-with-pest` topic from `jpcaparas/superpowers-laravel` into the local `tdd-with-pest` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
## Context Efficiency
Layer: 4 (Verification)
Load this skill only when TDD is needed. Do not load with unrelated skills. RED-GREEN-REFACTOR, but keep it tight: one failing test, smallest passing implementation, refactor only when it simplifies. No per-function suites unless asked.
- `security`Laravel guidance to stabilize workflows with Template Method or Strategy; extend by adding new classes instead of editing core logic
# Template Method And Plugins
Use this skill when a Laravel task involves template method and plugins.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `laravel:template-method-and-plugins` topic from `jpcaparas/superpowers-laravel` into the local `template-method-and-plugins` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Choose focused Laravel tests and quality checks that prove behavior without mirroring implementation details.
# Testing
Tests should prove behavior, not mirror implementation. Prefer the smallest test type that catches the risk.
## Test Selection
Use feature tests for:
- routes and controllers;
- authorization and middleware;
- validation;
- redirects;
- sessions;
- database writes;
- user-facing workflows.
Use unit tests for:
- pure helpers;
- value objects;
- complex Actions/Services without HTTP behavior;
- parsing and normalization rules.
Use browser E2E tests for:
- JavaScript-dependent behavior;
- Livewire/SPA interactions;
- modals, uploads, previews, drag/drop, and browser state;
- critical accessibility-sensitive flows.
Use `ui-agent-browser` while a frontend workflow is still being explored or implemented. Use `e2e-playwright` when that workflow should become repeatable Playwright coverage.
## Framework Fakes
Use Laravel fakes for external or filesystem side effects.
```php
Http::fake([
'api.example.test/*' => Http::response(['ok' => true]),
]);
$this->post(route('records.send', $record))
->assertRedirect()
->assertSessionHasNoErrors();
Http::assertSent(fn ($request) => $request->method() === 'POST');
```
Common fakes:
- `Http::fake()`;
- `Storage::fake()`;
- `Mail::fake()`;
- `Notification::fake()`;
- `Queue::fake()` or `Bus::fake()`;
- `Event::fake()`.
## Workflow Tests
For important user-facing workflows, cover the full route behavior.
```php
$this->actingAs($user)
->post(route('records.store'), [
'name' => 'Example',
])
->assertRedirect(route('records.index'))
->assertSessionHasNoErrors();
$this->assertDatabaseHas('records', [
'name' => 'Example',
]);
```
When rebuilding or porting an app, add feature parity tests for critical happy paths. Parity tests are a regression net, not a replacement for focused tests.
## Render And Document Tests
For pure Blade/report rendering, unsaved Eloquent graphs may be built with `forceFill()` and `setRelation()`.
Use this only when persistence, middleware, authorization, route model binding, database constraints, queries, and events are not part of the behavior.
```php
$owner = (new User)->forceFill(['name' => 'Example User']);
$record = (new Record)->forceFill(['number' => 'DOC-001']);
$record->setRelation('owner', $owner);
$html = view('reports.record', ['record' => $record])->render();
$this->assertStringContainsString('DOC-001', $html);
```
For generated documents, assert both stable source content and artifact validity.
```php
$html = view('reports.record', $viewData)->render();
$output = Pdf::loadView('reports.record', $viewData)->output();
$this->assertStringContainsString('Document Number', $html);
$this->assertStringStartsWith('%PDF-', $output);
```
Avoid broad snapshots unless the project intentionally uses snapshot or visual-regression testing.
## Browser E2E
For Playwright or similar tools:
- prefer role and label locators;
- use web-first assertions;
- avoid fixed sleeps;
- use deterministic auth setup when appropriate;
- keep E2E focused on high-value browser behavior.
For Laravel Playwright details, load `e2e-playwright` instead of re-deriving setup, auth state, locator, trace, and screenshot rules.
## Handoff Verification
Before work is complete, run the relevant checks:
- targeted PHP tests;
- affected browser tests;
- Pint/style check;
- static analysis;
- frontend build/lint;
- route checks;
- queue/job smoke tests.
If a check cannot run, report the command and reason.
## Context Efficiency
Layer: 4 (Verification)
Load this skill only when writing or reviewing tests. Do not load with unrelated skills. Keep tests behavior-focused: smallest test type that catches the risk, no per-function suites unless asked, no frameworks/fixtures for trivial logic.Build and refine Laravel UI/UX/frontends with stack-aware implementation, backend contract alignment, Playwright handoff, and agent-browser inspection.
# UI Agent Browser
Use this skill when a Laravel task asks to build, redesign, implement, inspect, or judge frontend/UI/UX quality before the final responsive audit.
Treat the browser as the design surface and the backend contract as the source of truth. A UI is not done because the code compiles; it is done when the page communicates its purpose quickly, supports the real workflow, is wired to real routes or API contracts, and survives visual inspection in meaningful states.
## Workflow
1. Detect the target stack: Blade, Livewire, Inertia, Filament, Nova, Flux, Alpine, React, Vue, Tailwind, Bootstrap, component library, icon library, build tool, route structure, and test runner.
2. Inspect the existing frontend in a browser before designing: current route, layout shell, navigation, component language, visual density, interaction pattern, console errors, and rendered DOM or accessibility tree.
3. Read the backend surface that the UI must connect to: routes, controllers, Form Requests, policies, API Resources, DTOs, Inertia props, Livewire public state/actions, model relationships, events, files, and pagination.
4. Define the UI contract before styling: data needed, user actions, request payloads, validation errors, authorization-dependent controls, loading states, empty states, success states, and failure states.
5. Design to the detected stack, browser baseline, and project conventions. Reuse existing layouts, tokens, components, tables, forms, modals, navigation, and icons before introducing a new visual language.
6. Implement the UI in the target stack, wired to real backend routes, Livewire actions, Inertia props, or API clients. Avoid static-only screens unless the requested artifact is explicitly a mockup.
7. Inspect the result in a real browser with realistic data, screenshots, console output, interaction states, and at least mobile and desktop viewports.
8. Iterate on hierarchy, spacing, alignment, text fit, color, controls, and backend state mapping until the interface feels intentional and works through the real workflow.
9. Use `responsive-ui-testing` for the final viewport matrix when responsiveness, overflow, clipping, modals, tables, or visual regression matters.
## Browser Tool Strategy
Combine `agent-browser` and Playwright deliberately:
- Use the official `vercel-labs/agent-browser` repository as the source for current command behavior when agent-browser details matter: https://github.com/vercel-labs/agent-browser. Prefer its README or bundled `skills/agent-browser` guidance over remembered flags.
- Use the official `microsoft/playwright` repository as the source for current Playwright behavior when test, locator, browser, trace, CLI, or MCP details matter: https://github.com/microsoft/playwright. Prefer its README, docs, and API reference over remembered APIs.
- Use `agent-browser` for low-token exploration, quick interaction, screenshots, accessibility-tree snapshots, annotated screenshots, visual inspection, and short browser loops.
- Use Playwright for durable cross-browser tests, web-first assertions, resilient locators, auth setup, deterministic seeds, traces, screenshots in CI, regression coverage, and repeated workflows.
- Use `agent-browser read` on the active tab when rendered text/DOM is enough, then escalate to `snapshot` or screenshots only when structure or visual quality needs it.
- Prefer `agent-browser snapshot -i -c -d 5 --json` or a scoped selector snapshot for planning interactions; ask for full snapshots only when structure is genuinely unclear.
- Use annotated screenshots when visual layout, unlabeled icon buttons, canvas content, or spacing cannot be understood from the accessibility tree alone.
- Use `agent-browser batch --bail` for multi-step navigation, wait, snapshot, screenshot, and interaction flows to reduce command overhead.
- Use the default `agent-browser mcp` or `--tools core` profile when available; expand to `network`, `debug`, `react`, or `mobile` only when the task needs that surface.
- Fall back to Playwright when `agent-browser` is unavailable, when the project already has Playwright helpers, or when the result must become a committed test.
Use this division of labor:
- agent-browser discovers the current UI, explores states, captures compact evidence, and helps decide what to build.
- Playwright codifies the accepted workflow as repeatable browser coverage with `@playwright/test`, user-facing locators, isolation, deterministic data, traces, and screenshots.
- Convert agent-browser observations into Playwright assertions only after the UI/BE contract and visual behavior have stabilized.
## Backend Contract Alignment
Before implementing visible UI:
- Map every user action to a route, Livewire method, Inertia visit, form submit, API request, job trigger, file upload, or modal-only local action.
- Confirm required fields, validation rules, authorization rules, response shape, pagination metadata, filters, sort keys, and error format.
- Keep templates focused on rendering and interaction. Put queries, authorization, validation, side effects, and provider calls in Laravel boundaries.
- Use model-backed factories, seeders, fakes, or local API fixtures to make the browser state realistic without hardcoding fake UI-only data.
- Show backend states honestly: forbidden actions hidden or disabled, validation errors near fields, failed requests recoverable, queued/background work visible, and empty states useful.
## Design Rules
- Make the primary entity or task obvious in the first viewport.
- Prefer quiet, work-focused density for admin, CRM, ERP, SaaS, and operational pages.
- Use cards only for repeated items, modals, or genuinely framed tools. Do not nest cards inside cards.
- Keep section layouts full-width or unframed with constrained inner content.
- Use familiar controls: icon buttons for tool actions, tabs for view switching, segmented controls for modes, checkboxes or toggles for binary settings, menus for option sets, and inputs or sliders for numbers.
- Use the existing icon library when available. Prefer named icons over hand-drawn SVG controls.
- Keep border radii restrained unless the project design system says otherwise.
- Avoid one-note color palettes. Combine neutral surfaces with purposeful accent colors, semantic states, and enough contrast.
- Avoid decorative blobs, generic gradients, and stock-like visuals that do not clarify the product, place, object, or workflow.
- Do not add visible instructional copy that explains obvious UI mechanics. Let labels, affordances, grouping, and state do the work.
## Laravel UI Boundaries
- Use `blade-components-and-layouts` when the work touches reusable Blade layout or component structure.
- Use `livewire-development` when state, uploads, pagination, modals, filters, or dynamic interactions are Livewire-driven.
- Use `module-per-menu` when a multi-page admin app needs one page per module instead of conditional menu blocks in one Blade file.
- Use `e2e-playwright` when the browser workflow should become a durable test.
- Keep database queries, authorization, validation, and side effects out of templates.
- Build summaries, metrics, filters, tables, and select options from real model-backed data when the page is not a static mockup.
- Keep client names, private branding, internal URLs, sample customer data, phone numbers, and credentials out of reusable UI standards and screenshots intended for handoff.
## Browser Inspection Loop
When changing visible UI:
1. Start the project through its documented runner.
2. Visit the affected routes as the intended user role.
3. Capture screenshots for at least a narrow mobile viewport and a desktop viewport.
4. Check console errors, failed assets, missing fonts, broken images, hydration issues, and Livewire or Alpine errors.
5. Interact with primary controls, navigation, filters, forms, dropdowns, modals, pagination, and destructive confirmations.
6. Inspect the data contract while interacting: submitted payloads, response status, validation messages, optimistic updates, redirects, flash messages, and refreshed table or form data.
7. Re-check layout after loading, empty, validation-error, long-content, and success states when those states can be reached locally.
Do not rely only on static code review for visual quality.
## State Checklist
Cover the states that matter for the page:
- default data
- empty data
- long names, long translated strings, and large numbers
- loading or disabled controls
- validation errors
- success or flash messages
- unauthorized or hidden actions
- destructive confirmation
- filter or search results
- dark mode when supported
## Token Budget Rules
- Start with stack and contract discovery using `rg`, route lists, component names, and scoped browser snapshots.
- Prefer targeted file reads over loading whole frontend trees.
- Capture the existing frontend baseline with `agent-browser read`, scoped snapshots, or one screenshot before proposing broad UI changes.
- Prefer compact browser snapshots before screenshots; use screenshots when visual judgment matters.
- Keep browser evidence small: route, viewport, screenshot path, key console errors, and the exact failing or changed component.
- Convert repeated manual browser checks into Playwright only after the workflow stabilizes.
## Completion Gate
Do not call the UI finished unless:
- the page matches the existing project design language or intentionally introduces a coherent new one;
- the main workflow is visible and usable without reading explanatory text;
- frontend behavior is wired to the intended backend route, Livewire action, Inertia prop, or API contract;
- spacing, alignment, typography, icon use, and color look deliberate;
- text fits its containers on mobile and desktop;
- interactive states have been exercised in the browser;
- backend-driven states such as validation, authorization, loading, empty data, success, and failure are represented;
- screenshots or browser observations support the handoff;
- high-value or regression-prone browser flows are handed off to `e2e-playwright` when the project supports it;
- remaining visual risks are named explicitly.Upgrade an app from Laravel 12.x to 13.x safely; PHP 8.3 baseline, dependency bumps, breaking-change checklist, and verification steps
# Upgrade 13
Use this skill when a Laravel task involves upgrade 13.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `upgrade-13` topic from `jpcaparas/superpowers-laravel` into the local `upgrade-13` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Laravel guidance to provide concrete examples-existing code patterns, style samples, input/output pairs-to guide AI toward your project's conventions
# Using Examples In Prompts
Use this skill when a Laravel task involves using examples in prompts.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `using-examples-in-prompts` topic from `jpcaparas/superpowers-laravel` into the local `using-examples-in-prompts` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Read first in Laravel repositories to detect the stack and select the smallest relevant Syarif standards skills for implementation, review, testing, and audits.
# Using Syarif Laravel Standards
Layer: 2 (Orchestrator)
Use this skill as the mandatory entrypoint for all Laravel work. It enforces the layered protocol that keeps token usage low and output quality high.
## Mandatory Layered Protocol
Every task MUST pass through these layers in order. Do not skip a layer.
### Layer 0: Memory Preflight
Run `memory-management` automatic preflight before anything else:
```bash
node <memory-skill-dir>/scripts/memory.mjs auto --cwd <project-root> --query "<task intent>" --limit 5
```
If `memory-graph.json` exists, run one graph query instead of loading all memory:
```bash
node <memory-skill-dir>/scripts/memory.mjs graph query "<task intent>" --limit 5
```
Use the compact output as orientation only. Do not dump full memory files into context.
### Layer 1: least-code Minimization
Activate `least-code` before any code change. Apply the ladder:
1. Does this need to exist? (YAGNI)
2. Already in this codebase? Reuse it.
3. Stdlib does it? Use it.
4. Native platform feature covers it? Use it.
5. Installed dependency solves it? Use it.
6. Can this be one line? Make it one line.
7. Only then: minimum code that works.
The ladder runs after you understand the problem. Read the task and the code it touches first, then climb. Bug fix = root cause, not symptom. Grep every caller before editing.
### Layer 2: Risk Classification and Skill Selection
Before implementation, classify the task risk:
- **LOW**: typo, Blade text, CSS kecil, rename lokal.
- Inspect affected file only.
- Syntax/static check is enough.
- **MEDIUM**: validation, query, Livewire state, controller/service refactor, non-destructive action.
- Trace affected flow.
- Targeted test + affected callers.
- Check authorization boundary and regression surface.
- **HIGH**: migration, auth, permission, payroll, financial calculation, concurrency, destructive action, data-shape change.
- Full trace required.
- Architecture/data/security review before patch.
- Affected regression surface + failure-path verification required.
- Explicit behavior preservation check mandatory.
Risk level determines verification depth and exploration breadth.
### Layer 3: Focused Implementation
Apply the selected focused skills. Each skill governs its own domain:
- Architecture and layer decisions: `architecture`
- Thin controllers: `controller-cleanup`
- HTTP validation and auth: `form-requests`
- Actions and Services: `actions-and-services`
- Atomic writes: `database-transactions`
- Eloquent models and queries: `eloquent-patterns`
- Broad Laravel feature work: `laravel-specialist`
### Layer 4: Verification and Handoff
Verify with the smallest meaningful tests and quality checks the project supports.
Match verification to risk level:
- **LOW**: syntax/static check.
- **MEDIUM**: targeted feature/unit test + affected callers.
- **HIGH**: targeted verification + affected regression surface + failure paths + relevant data/security/concurrency checks.
Run the full test suite only when it is cheap or explicitly justified.
Memory checkpoint is never a requirement for task completion. It occurs only when durable reusable knowledge was produced. If no reusable knowledge was generated, finish without checkpointing.
## Context Efficiency Rules
These rules apply to every skill in this repository:
- Load only the focused `SKILL.md` files needed for the task.
- Never load all skills into context at once.
- Prefer scripts and references over long skill bodies.
- Keep explanations shorter than the code they explain.
- If a skill body exceeds 500 lines, move details to `references/`.
- Mark deliberate simplifications with `least-code:` comments naming the ceiling and upgrade path.
## Skill Selection
Load the smallest relevant skill set:
- Architecture and layer decisions: `architecture`
- Multi-menu/page app structure: `module-per-menu`
- Thin controllers and route boundaries: `controller-cleanup`
- HTTP validation and request authorization: `form-requests`
- Actions, Services, integrations, interfaces, and repositories: `actions-and-services`
- Atomic writes and side effects: `database-transactions`
- Eloquent models, relationships, and query shape: `eloquent-patterns`
- Broad Laravel feature work: `laravel-specialist`
- Persistent conversation, project, user, workflow, and codebase context: `memory-management`
- Laravel 11/12 app workflow: `laravel-11-12-app-guidelines`
- Database performance and query tuning: `laravel-database-optimization`
- UI/UX design, frontend implementation, agent-browser inspection, Playwright checks, and backend contract alignment: `ui-agent-browser`
- Livewire components, architecture, security, performance, and tests: `livewire-development`
- Responsive UI, mobile layout, overflow, modals, tables, and visual regression: `responsive-ui-testing`
- Queues, jobs, workers, schedules, and Horizon: `queues-and-jobs`
- WhatsApp integration through a Baileys sidecar with Windows/VPS setup docs: `integrate-whatsapp-baileys-laravel`
- Security review: `security`
- Feature, unit, render, document, browser, and handoff tests: `testing`
- Extract reusable standards from a completed project: `extract-laravel-standards`
Project-specific `AGENTS.md` rules override these defaults when explicitly documented.
## Skill Conflict Resolution
When multiple skills could apply:
1. Choose one primary skill that owns the main change.
2. Choose at most two supporting skills unless HIGH risk requires more.
3. Prefer the skill with the narrowest scope that still covers the task.
4. Do not load every related skill to feel thorough.
## Skill Override Hierarchy
When rules conflict, apply in this order:
1. User instruction
2. Repository rules (`AGENTS.md`, project-specific instructions)
3. Project skill
4. Framework skill
5. Generic coding skill
Safety/security rules remain non-negotiable regardless of hierarchy.
## Definition of Done
A task is complete only when:
- requested behavior works,
- unrelated behavior is preserved,
- targeted verification passes,
- no unnecessary abstraction/dependency was added,
- durable knowledge is checkpointed only if reusable.
## Completion
Before declaring work complete, run the smallest meaningful verification set the project supports. If a check cannot run, report the command and reason.Add semantic search with native vector queries (Laravel 13+); pgvector similarity clauses, embedding workflows, and hybrid search patterns
# Vector Search
Use this skill when a Laravel task involves vector search.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `vector-search` topic from `jpcaparas/superpowers-laravel` into the local `vector-search` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`Create an actionable Laravel implementation plan-bite-sized tasks with TDD-first steps, migrations, services, jobs, and validation points
# Writing Plans
Use this skill when a Laravel task involves writing plans.
This skill is adapted to the personal Laravel standards in this repository. It maps the public `writing-plans` topic from `jpcaparas/superpowers-laravel` into the local `writing-plans` catalog without copying third-party skill body text.
## Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
## Workflow
1. Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
2. Identify the smallest local skill set that overlaps this topic.
3. Implement or review the change using Laravel-native APIs first.
4. Add abstractions only when they reduce real complexity or protect a meaningful boundary.
5. Run targeted tests and available quality checks before handoff.
## Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
## Related Skills
- `using-laravel-standards`
- `architecture`
- `testing`
- `security`