@event4u/agent-config 1.9.1

package/.agent-src/skills/laravel/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: laravel
+description: "Writes Laravel code following framework conventions, project architecture, and modern best practices for controllers, requests, services, jobs, events, policies, and application structure."
+source: package
+---
+
+# laravel
+
+## When to use
+
+Use this skill for all Laravel-specific code generation and editing tasks, especially when working with:
+
+- Controllers
+- Form Requests
+- Middleware
+- Service Providers
+- Jobs / Queued Jobs
+- Events / Listeners
+- Policies / Gates
+- Notifications
+- Console Commands
+- Config, Routing, and Application Structure
+
+This skill extends the base `php-coder` skill and applies Laravel conventions on top of the project's general PHP rules.
+
+## Procedure: Write Laravel code
+
+→ **First apply the `php-coder` skill** — it handles project docs, module docs, patterns, and quality tools.
+
+Then add these **Laravel-specific** checks:
+
+1. **Confirm this is a Laravel app** — check whether `artisan` exists.
+2. **Inspect app structure** — classic Laravel, modules (`app/Modules/`), or domain folders.
+3. **Check routes and HTTP flow** — understand how requests enter the application and where logic belongs.
+4. **Check test conventions** — inspect existing tests in the same domain before writing new code.
+
+## Core Laravel principles
+
+- Follow **Laravel conventions first** unless the project explicitly does otherwise.
+- Keep **controllers thin** — delegate business logic to services/actions.
+- Keep **Form Requests responsible for validation and authorization**.
+- Use **dependency injection** through the container.
+- Prefer **framework features** over custom infrastructure when the built-in solution is sufficient.
+- Avoid hidden magic when explicit code is clearer for the project.
+- Respect the existing architecture — do not force "pure Laravel" if the project uses modules or service layers.
+
+## HTTP layer rules
+
+- Controllers should:
+    - accept the request
+    - delegate business logic
+    - return a response / resource / redirect
+- Do not put business logic, calculations, or large data transformations in controllers.
+- Use **Form Request** classes for validation instead of inline controller validation when the request is non-trivial.
+- Use route model binding when it improves clarity and matches existing patterns.
+- Keep controller actions focused and small.
+
+## Validation rules
+
+- Use **Form Requests** for reusable or non-trivial validation.
+- Prefer explicit validation rules over implicit behavior.
+- Reuse existing custom rules when available.
+- Keep validation close to the HTTP boundary.
+- Do not mix validation with persistence or business decisions.
+
+## Service layer rules
+
+- Put orchestration and business logic into dedicated services/actions.
+- Services should be framework-light when possible.
+- A service should have one clear responsibility.
+- Prefer constructor injection for dependencies.
+- Do not move trivial one-line controller behavior into a service unless the project consistently does that.
+
+## Routing rules
+
+- Follow the existing route organization:
+    - `routes/web.php`
+    - `routes/api.php`
+    - module-specific route files
+- Keep route definitions readable and grouped logically.
+- Use route names consistently.
+- Apply middleware explicitly and according to project conventions.
+- Do not introduce route patterns that differ from the surrounding code without a good reason.
+
+## Response rules
+
+- Use the response style already established in the project:
+    - Blade views
+    - JSON responses
+    - API Resources
+    - Redirects with flash messages
+- For APIs, prefer:
+    - consistent status codes
+    - structured JSON payloads
+    - API Resources when the project uses them
+- Do not return raw models directly unless that is already the established project pattern.
+
+## Queues, jobs, and async work
+
+- Use Jobs for clearly asynchronous or deferred work.
+- Keep Jobs focused on a single responsibility.
+- Pass only the data needed by the job.
+- Avoid putting excessive domain logic directly into the Job class — delegate to services where appropriate.
+- Be mindful of serialization when passing models or objects.
+
+## Events and listeners
+
+- Use events for meaningful domain or application events, not for every small action.
+- Name events clearly in the past tense when something already happened.
+- Keep listeners focused and side-effect oriented.
+- Do not introduce event-driven complexity unless it is already part of the project architecture.
+
+## Auth, policies, and authorization
+
+- Use Laravel authorization features consistently:
+    - policies
+    - gates
+    - request authorization
+- Keep authorization logic out of controllers where possible.
+- Reuse existing policies and permission patterns.
+- Do not hardcode role checks in multiple places if a policy/gate already exists.
+
+## Config and environment
+
+- Read configuration from config files, not directly from `env()` outside config files.
+- Do not introduce new environment variables unless necessary.
+- Reuse existing config structure and naming patterns.
+
+## Database interaction
+
+- Prefer Eloquent for normal application data access unless the project uses repositories or query objects.
+- Use transactions when multiple writes must succeed or fail together.
+- Avoid N+1 problems — eager load when appropriate.
+- For heavy data access logic, follow the dedicated `eloquent` skill.
+
+## Migrations and schema changes
+
+- Keep migrations focused and reversible.
+- Follow existing naming conventions for columns, foreign keys, and indexes.
+- Do not mix unrelated schema changes in a single migration.
+- Be careful with destructive changes on existing production tables.
+
+## Blade and view rules
+
+- Keep views dumb — presentation only.
+- Avoid embedding business logic in Blade templates.
+- Extract reusable UI pieces into components/partials when it matches project patterns.
+- Escape output by default and use raw output only when safe and intentional.
+
+## What NOT to do
+
+- Do not put business logic into controllers, models, or Blade templates.
+- Do not validate large requests inline in controllers when Form Requests are more appropriate.
+- Do not call `env()` outside config files.
+- Do not introduce new architectural layers unless the project already uses them.
+- Do not bypass Laravel features already used consistently in the project.
+- Do not return inconsistent API response shapes in an established API.
+
+## Output expectations
+
+When generating Laravel code:
+
+- follow Laravel naming conventions
+- use dependency injection
+- keep classes small and focused
+- match the surrounding project structure
+- prefer explicit, readable code over clever abstractions
+- integrate with existing requests, resources, services, policies, and tests
+
+## Output format
+
+1. Laravel code following framework conventions and project architecture
+2. All related files (controller, service, request, resource, test) as needed
+
+## Do NOT
+
+- Do NOT put business logic in controllers — delegate to services.
+- Do NOT use facades in service classes — use dependency injection.
+- Do NOT skip middleware for route groups that need authentication.
+
+## Gotcha
+
+- `env()` only works in config files — use `config()` everywhere else.
+- Don't mix `Route::resource()` with single-action controllers — pick the project's convention.
+- Don't return Eloquent models directly — always use API Resources.
+- Don't bypass existing middleware stacks when adding new routes.
+
+## Auto-trigger keywords
+
+- Laravel
+- controller
+- service
+- middleware
+- route
+- application structure

package/.agent-src/skills/laravel-horizon/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: laravel-horizon
+description: "Use when working with Laravel queues in production — Horizon dashboard, worker supervision, job metrics, balancing strategies — even when the user just says 'my jobs are piling up'."
+source: package
+---
+
+# laravel-horizon
+
+## When to use
+
+Use this skill for anything related to Laravel Horizon:
+- Queue worker configuration and supervision
+- Horizon dashboard setup and access control
+- Job metrics, throughput, and failure monitoring
+- Balancing strategies and scaling workers
+- Production tuning and deployment
+
+For **writing queue jobs** themselves, see [jobs-events](../jobs-events/SKILL.md).
+
+## Procedure: Configure Horizon
+
+### config/horizon.php
+
+```php
+'environments' => [
+    'production' => [
+        'supervisor-1' => [
+            'maxProcesses' => 10,
+            'balanceMaxShift' => 1,
+            'balanceCooldown' => 3,
+            'connection' => 'redis',
+            'queue' => ['default', 'high', 'low'],
+            'balance' => 'auto',  // auto, simple, or false
+            'tries' => 3,
+            'timeout' => 60,
+            'maxTime' => 3600,
+            'maxJobs' => 1000,
+            'memory' => 128,
+        ],
+    ],
+    'local' => [
+        'supervisor-1' => [
+            'maxProcesses' => 3,
+            'connection' => 'redis',
+            'queue' => ['default', 'high', 'low'],
+            'balance' => 'auto',
+            'tries' => 3,
+            'timeout' => 60,
+        ],
+    ],
+],
+```
+
+### Queue priority
+
+```php
+// Higher priority queues are listed first
+'queue' => ['high', 'default', 'low'],
+```
+
+## Running Horizon
+
+```bash
+# Start Horizon (foreground)
+php artisan horizon
+
+# Pause / Continue
+php artisan horizon:pause
+php artisan horizon:continue
+
+# Terminate gracefully (for deployments)
+php artisan horizon:terminate
+
+# Check status
+php artisan horizon:status
+```
+
+## Deployment
+
+**Always terminate and restart Horizon after deploying new code:**
+
+```bash
+php artisan horizon:terminate
+# Supervisor will auto-restart Horizon
+```
+
+### Supervisor config (production)
+
+```ini
+[program:horizon]
+process_name=%(program_name)s
+command=php /path/to/artisan horizon
+autostart=true
+autorestart=true
+user=www-data
+redirect_stderr=true
+stdout_logfile=/var/log/horizon.log
+stopwaitsecs=3600
+```
+
+## Dashboard access
+
+```php
+// HorizonServiceProvider
+protected function gate(): void
+{
+    Gate::define('viewHorizon', function (User $user): bool {
+        return $user->isSuperuser();
+    });
+}
+```
+
+## Balancing strategies
+
+| Strategy | Behavior |
+|---|---|
+| `auto` | Distributes workers based on queue workload (recommended) |
+| `simple` | Round-robin across queues |
+| `false` | Fixed worker count per queue |
+
+## Metrics and monitoring
+
+- **Throughput** — jobs processed per minute per queue
+- **Runtime** — average job execution time
+- **Wait time** — time jobs spend waiting in queue
+- **Failed jobs** — track and retry from dashboard
+- **Tags** — auto-tagged by Eloquent models, custom tags via `tags()` method
+
+```php
+// Custom tags on a job
+public function tags(): array
+{
+    return ['customer:' . $this->customer->getId(), 'report'];
+}
+```
+
+## Core rules
+
+- **Always use Supervisor** in production — Horizon is a long-running process.
+- **Terminate on deploy** — `horizon:terminate` ensures workers pick up new code.
+- **Use `auto` balancing** — it adapts to workload automatically.
+- **Set `maxTime`** — prevents workers from running forever (memory leaks).
+- **Set `maxJobs`** — recycles workers after N jobs to prevent memory bloat.
+- **Tag jobs** — makes debugging and filtering in the dashboard much easier.
+
+## Output format
+
+1. Updated Horizon configuration with supervisor and queue settings
+2. Environment-specific balancing strategy rationale
+
+## Auto-trigger keywords
+
+- Horizon
+- queue worker
+- queue dashboard
+- job monitoring
+- supervisor
+- queue balancing
+
+## Gotcha
+
+- Horizon config changes require `php artisan horizon:terminate` and restart — they don't hot-reload.
+- Don't set `maxProcesses` too high — each process holds a DB connection. Monitor your connection pool.
+- The model forgets that Horizon only works with Redis queues — not database or SQS.
+
+## Do NOT
+
+- Do NOT run Horizon without Supervisor/systemd in production.
+- Do NOT expose the Horizon dashboard without access control.

package/.agent-src/skills/laravel-mail/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: laravel-mail
+description: "Use when building Laravel emails — Mailables, Markdown templates, queued sending, attachments, previews — even when the user says 'send this as an email' without naming Mailables."
+source: package
+---
+
+# laravel-mail
+
+## When to use
+
+Use this skill when building email functionality:
+- Mailable classes with HTML/Blade or Markdown templates
+- Queued email sending
+- Attachments and inline images
+- Mail testing and previewing
+
+For **simple notification emails** (one-off messages), see [laravel-notifications](../laravel-notifications/SKILL.md).
+Use Mailables when you need full control over the email template.
+
+## Procedure: Create a Mailable
+
+1. **Generate class** — `php artisan make:mail InvoiceMail --markdown=emails.invoice`.
+2. **Configure** — Set subject, from, attachments, queuing (`ShouldQueue`).
+3. **Create template** — Markdown template in `resources/views/emails/`.
+4. **Verify** — Send test email, confirm rendering and delivery.
+
+### Example
+
+```bash
+php artisan make:mail InvoiceMail --markdown=emails.invoice
+```
+
+```php
+declare(strict_types=1);
+
+namespace App\Mail;
+
+use App\Models\Invoice;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Mail\Mailable;
+use Illuminate\Mail\Mailables\Content;
+use Illuminate\Mail\Mailables\Envelope;
+use Illuminate\Queue\SerializesModels;
+
+class InvoiceMail extends Mailable implements ShouldQueue
+{
+    use Queueable;
+    use SerializesModels;
+
+    public function __construct(
+        private readonly Invoice $invoice,
+    ) {}
+
+    public function envelope(): Envelope
+    {
+        return new Envelope(
+            subject: 'Invoice #' . $this->invoice->getNumber(),
+            replyTo: ['billing@example.com'],
+        );
+    }
+
+    public function content(): Content
+    {
+        return new Content(
+            markdown: 'emails.invoice',
+            with: [
+                'invoice' => $this->invoice,
+                'url' => route('invoices.show', $this->invoice->getId()),
+            ],
+        );
+    }
+
+    /** @return array<int, \Illuminate\Mail\Mailables\Attachment> */
+    public function attachments(): array
+    {
+        return [
+            Attachment::fromPath('/path/to/invoice.pdf')
+                ->as('invoice-' . $this->invoice->getNumber() . '.pdf')
+                ->withMime('application/pdf'),
+        ];
+    }
+}
+```
+
+## Markdown templates
+
+```blade
+{{-- resources/views/emails/invoice.blade.php --}}
+<x-mail::message>
+# Invoice {{ $invoice->getNumber() }}
+
+Thank you for your order. Here is your invoice summary:
+
+<x-mail::table>
+| Item | Amount |
+|:-----|-------:|
+@foreach ($invoice->getItems() as $item)
+| {{ $item->getName() }} | {{ $item->getFormattedAmount() }} |
+@endforeach
+| **Total** | **{{ $invoice->getFormattedTotal() }}** |
+</x-mail::table>
+
+<x-mail::button :url="$url">
+View Invoice
+</x-mail::button>
+
+Thanks,<br>
+{{ config('app.name') }}
+</x-mail::message>
+```
+
+## Sending mail
+
+```php
+// Send immediately
+Mail::to($user)->send(new InvoiceMail($invoice));
+
+// Queue for background sending (preferred)
+Mail::to($user)->queue(new InvoiceMail($invoice));
+
+// Send later
+Mail::to($user)->later(now()->addMinutes(10), new InvoiceMail($invoice));
+
+// Multiple recipients
+Mail::to($users)
+    ->cc($manager)
+    ->bcc('archive@example.com')
+    ->send(new InvoiceMail($invoice));
+```
+
+## Testing
+
+```php
+// Assert mail was sent
+Mail::fake();
+
+// ... trigger action ...
+
+Mail::assertSent(InvoiceMail::class, function (InvoiceMail $mail) use ($user) {
+    return $mail->hasTo($user->getEmail());
+});
+
+Mail::assertNotSent(InvoiceMail::class);
+Mail::assertNothingSent();
+Mail::assertQueued(InvoiceMail::class);
+```
+
+## Previewing in browser
+
+```php
+// routes/web.php (local only)
+Route::get('/mail-preview', function () {
+    $invoice = Invoice::factory()->create();
+    return new InvoiceMail($invoice);
+});
+```
+
+## Core rules
+
+- **Always queue emails** — implement `ShouldQueue` to avoid blocking requests.
+- **Use Markdown templates** for consistent styling across email clients.
+- **Use Envelope + Content** pattern (Laravel 11+) — not the old `build()` method.
+- **Test with `Mail::fake()`** — verify recipients, content, and queuing.
+- **Keep Mailables focused** — one Mailable per email type.
+
+## Output format
+
+1. Mailable class with envelope, content, and attachments
+2. Blade/Markdown email template
+3. Queued mail dispatch integration
+
+## Auto-trigger keywords
+
+- Mailable
+- email template
+- send mail
+- Mail::to
+- markdown email
+- mail attachment
+
+## Gotcha
+
+- Always queue emails (`ShouldQueue`) — synchronous sending blocks the request.
+- The model forgets that mail templates are Blade files — they need to be published/created.
+- Don't test email content with `Mail::fake()` alone — it doesn't render the template. Use `Mail::assertSent()` with closure.
+
+## Do NOT
+
+- Do NOT send emails synchronously in request lifecycle — always queue.
+- Do NOT use `build()` method — use `envelope()`, `content()`, `attachments()`.
+- Do NOT hardcode email addresses — use config or environment variables.
+- Do NOT put HTML in Mailable classes — use Blade templates.