@event4u/agent-config 14.23.0 → 15.0.0

package/dist/agent-src/guidelines/php/jobs.md

@@ -0,0 +1,111 @@
+# Job Guidelines
+
+> Queue job conventions. Horizon tags, uniqueness, retries, rate limiting.
+
+**Related Skills:** `jobs-events`, `performance`
+**Related Guidelines:** [patterns/service-layer.md](patterns/service-layer.md)
+
+## Constructor
+
+- Pass model **IDs** (not model instances) to reduce serialized job size
+- Always set queue via `$this->onQueue()` — queue names from backed enums
+
+```php
+public function __construct(public int $productId)
+{
+    $this->onQueue(Queue::SEARCH->value);
+}
+```
+
+## Tags (Horizon)
+
+Always add `tags()` for filtering in Horizon:
+
+```php
+public function tags(): array
+{
+    return [
+        self::class,
+        Product::class . ':' . $this->productId,
+    ];
+}
+```
+
+## Uniqueness
+
+- Add `uniqueId()` if the job should not run twice concurrently
+- **Must** also set `$uniqueFor` to prevent stuck locks:
+
+```php
+public int $uniqueFor = 3600;
+
+public function uniqueId(): string
+{
+    return (string) $this->productId;
+}
+```
+
+## Error Handling & Retries
+
+- Set `$maxExceptions` to limit unhandled exceptions before failing
+- Define `backoff()` for retry intervals:
+
+```php
+public int $maxExceptions = 3;
+
+/** @return int[] */
+public function backoff(): array
+{
+    return [5, 10, 30];
+}
+```
+
+## Rate Limiting (External APIs)
+
+Use `WithoutOverlapping` middleware for per-customer sequential execution:
+
+```php
+public function middleware(): array
+{
+    return [new WithoutOverlapping($this->customerId)];
+}
+```
+
+## Serialization
+
+- Pass IDs or compact DTOs — not full Eloquent models with loaded relations.
+- Model may change between dispatch and execution — design for this.
+- Never serialize closures, service instances, or large nested structures.
+
+## Idempotency
+
+- Assume queued jobs may run more than once.
+- Design handlers so retries don't create duplicate side effects.
+- Especially careful with: emails, external APIs, payments, imports, record creation.
+- Add explicit guards when duplicate execution would be harmful.
+
+## Events
+
+- Use events for meaningful occurrences, not every internal method call.
+- Past-tense naming: `OrderPlaced`, `InvoicePaid`, `UserRegistered`.
+- Keep event payloads focused.
+- **Laravel 11+:** automatic event/listener discovery — no manual registration.
+
+## Listeners
+
+- One responsibility per listener.
+- Delegate large business logic to services.
+- Avoid deep hidden chains of listeners.
+
+## Dispatching
+
+- Be explicit: immediately, after response, or on queue.
+- Don't change sync/async behavior casually in existing flows.
+
+## General
+
+- Avoid batches unless truly needed (relies on MySQL)
+- Use Service classes for complex business logic inside `handle()`
+- `ShouldQueue` is required for queued execution — without it, runs synchronously
+- Set `$tries` and `$backoff` — unlimited retries can overwhelm the queue
+

package/dist/agent-src/guidelines/php/livewire.md

@@ -0,0 +1,71 @@
+# Livewire Guidelines
+
+> Livewire component conventions — state, actions, forms, performance, Alpine.js, templates.
+
+**Related Skills:** `livewire`, `flux`, `blade-ui`
+
+## Component Structure (Livewire 3.x)
+
+```php
+#[Layout('layouts.app')]
+#[Title('User List')]
+final class UserList extends Component
+{
+    public string $search = '';
+
+    public function render(): \Illuminate\View\View
+    {
+        return view('livewire.user-list', [
+            'users' => User::query()->where('name', 'like', '%' . $this->search . '%')->paginate(20),
+        ]);
+    }
+}
+```
+
+## State Management
+
+- Use typed public properties for component state.
+- Keep state minimal — only what the UI needs.
+- `#[Locked]` for properties that must not be tampered with from frontend.
+- `#[Url]` for properties that should sync with URL query string.
+
+## Actions
+
+- Public methods are callable from frontend.
+- Validate input before processing: `$this->validate()`.
+- `$this->dispatch()` for cross-component communication (Livewire 3).
+
+## Forms
+
+- Use Livewire Form Objects (`Livewire\Form`) for complex forms (Livewire 3).
+- `wire:model` for two-way binding.
+- `wire:model.live` for real-time updates, `wire:model.debounce` for delayed.
+- Validate with Laravel validation rules.
+
+## Performance
+
+- `wire:key` on list items for DOM tracking.
+- `#[Computed]` for derived data cached per request (Livewire 3).
+- Avoid large datasets — paginate or filter.
+- `wire:loading` for loading indicators.
+
+## Alpine.js Integration
+
+- `@entangle` to share state between Livewire and Alpine.
+- `$wire` in Alpine to call Livewire methods.
+- Alpine for client-side-only interactions (dropdowns, animations).
+
+## Template Rules
+
+- Every Livewire view must have **one root element** (usually `<div>`).
+- Use `wire:key` on dynamic lists.
+- Use `wire:loading` for user feedback.
+
+## Do NOT
+
+- Put heavy business logic in components — delegate to services.
+- Use Livewire for purely static pages — use Blade.
+- Expose sensitive data as public properties.
+- Nest Livewire components deeply — keep tree shallow.
+- Put heavy computation in `render()` — runs on every update.
+- Skip `wire:key` on list items — causes DOM diffing issues.

package/dist/agent-src/guidelines/php/logging.md

@@ -0,0 +1,79 @@
+# Logging Guidelines
+
+> Logging conventions — levels, structured context, what to log, Sentry patterns.
+
+**Related Skills:** `logging-monitoring`, `grafana`
+
+## Use Laravel's Log Facade
+
+```php
+use Illuminate\Support\Facades\Log;
+
+// Standard logging
+Log::info('Import completed', ['customer_id' => $customerId, 'count' => $count]);
+
+// Channel-specific
+Log::channel('loki')->info('Import snapshot', ['data' => $snapshotData]);
+```
+
+## Structured Context — Always
+
+```php
+// ✅ Correct — structured context
+Log::warning('Import failed', ['customer_id' => $id, 'error' => $message]);
+
+// ❌ Wrong — interpolated message
+Log::warning("Import failed for customer {$id}: {$message}");
+```
+
+Context keys must be `snake_case` — consistency matters for Loki queries.
+
+## Log Levels
+
+| Level | When | Example |
+|---|---|---|
+| `emergency` | System unusable | Database unreachable |
+| `critical` | Immediate action required | Payment gateway down |
+| `error` | Needs investigation | Import failed for customer |
+| `warning` | Unusual, may need attention | Rate limit approaching |
+| `info` | Significant business events | Import completed, user created |
+| `debug` | Diagnostic (dev/staging only) | Query params, intermediate values |
+
+## What to Log
+
+- Business events: imports, state transitions, user actions
+- Error context: what was happening, with which data, for which customer
+- External interactions: API calls, webhook receipts
+- Performance markers: long operations, batch sizes, durations
+
+## What NOT to Log
+
+- Passwords, tokens, API keys, PII (GDPR)
+- Entire request/response bodies — log summary or hash
+- Expected conditions at high levels (validation failures ≠ `error`)
+- Every loop iteration — log the summary
+
+## Correlation IDs
+
+For multi-step operations:
+
+```php
+$correlationId = Str::uuid()->toString();
+Log::info('Import started', ['correlation_id' => $correlationId, ...]);
+Log::info('Import completed', ['correlation_id' => $correlationId, ...]);
+```
+
+## Sentry
+
+- Use `MonitoringHelper::captureException()` — never Sentry SDK directly.
+- Breadcrumbs: use `BreadcrumbType` and `BreadcrumbLevel` enums.
+- Context names: use `ContextName` enum.
+- Sentry has 200KB event size limit — large context gets truncated.
+
+## Do NOT
+
+- Use `var_dump()`, `print_r()`, `dd()` — disallowed by PHPStan.
+- Use Sentry SDK directly — use `MonitoringHelper`.
+- Hardcode log channel names in business logic — use config.
+- Log at `error` for expected/handled conditions — use `warning` or `info`.
+- Interpolate variables into log messages — use context array.

package/dist/agent-src/guidelines/php/naming.md

@@ -0,0 +1,89 @@
+# Naming Guidelines
+
+> Naming conventions — PHP classes, database, routes, variables, modules, agent infrastructure.
+
+**Related Skills:** none (naming is a convention — use this guideline directly)
+**Related Guidelines:** [controllers.md](controllers.md), [resources.md](resources.md)
+
+## PHP Classes
+
+| Type | Pattern | Example |
+|---|---|---|
+| Controller | `{Action}{Entity}Controller` | `CreateProjectController` |
+| FormRequest | `{Action}{Entity}Request` | `UpdateProjectRequest` |
+| Resource | `{Entity}Resource` | `ProjectResource` |
+| Minimal Resource | `{Entity}MinimalResource` | `ProjectMinimalResource` |
+| Simple Resource | `Simple{Entity}Resource` | `SimpleUserResource` |
+| Service | `{Domain}Service` | `ImportService` |
+| DTO | `{Entity}{Purpose}Dto` | `ProjectCreateDto` |
+| Job | `{Action}{Entity}Job` | `SyncCustomerJob` |
+| Event | `{Entity}{PastTense}` | `ProjectCreated` |
+| Enum | `{Entity}{Concept}` | `ImportStatus` |
+| Policy | `{Entity}Policy` | `ProjectPolicy` |
+| Interface | `{Capability}` (no suffix) | `SmsProvider` |
+
+**Controller special cases:** List uses **plural** (`ListProjectsController`), all others singular.
+
+## Database
+
+| Element | Convention | Example |
+|---|---|---|
+| Tables | snake_case, plural | `projects`, `import_rows` |
+| Columns | snake_case | `created_at`, `user_id` |
+| Foreign keys | `{entity}_id` | `project_id` |
+| Booleans | `is_` or `has_` prefix | `is_active`, `has_permission` |
+| Timestamps | `_at` suffix | `synced_at`, `imported_at` |
+| Pivot tables | Alphabetical, singular | `project_user` |
+
+## Routes
+
+| Element | Convention | Example |
+|---|---|---|
+| URL segments | kebab-case, plural | `/api/v1/import-uploads` |
+| Route names | dot notation | `v1.import-uploads.index` |
+| Route params | camelCase | `{importUpload}` |
+| API versioning | Prefix | `/api/v1/`, `/api/v2/` |
+
+## Variables
+
+| Element | Convention | Example |
+|---|---|---|
+| Variables | camelCase | `$projectId` |
+| Constants | UPPER_SNAKE_CASE | `MAX_RETRIES` |
+| Array keys | snake_case | `['user_id' => 1]` |
+| Config keys | snake_case, dot notation | `config('import.max_rows')` |
+| Env vars | UPPER_SNAKE_CASE | `APP_ENV` |
+
+## Modules
+
+| Element | Convention | Example |
+|---|---|---|
+| Directory | PascalCase | `app/Modules/Import/` |
+| Namespace | `App\Modules\{Name}\App\` | `App\Modules\Import\App\Services\` |
+| Route prefix | kebab-case | `import`, `client-software` |
+
+## Agent Infrastructure
+
+| Element | Convention | Example |
+|---|---|---|
+| Skills | kebab-case | `bug-analyzer` |
+| Rules | kebab-case | `php-coding` |
+| Commands | kebab-case | `feature-plan` |
+| Guidelines | kebab-case | `controllers.md` |
+
+## Enums
+
+- PascalCase class name
+- UPPERCASE cases: `case PENDING;`, `case IN_PROGRESS;`
+- Backed enums for DB values: `case PENDING = 'pending';`
+
+## Interfaces
+
+- Namespace: `App\Contracts\{Subdomain}\`
+- No `Interface` suffix: `SmsProvider`, not `SmsProviderInterface`
+
+## Do NOT
+
+- Use abbreviations that aren't universally understood.
+- Mix naming conventions within the same context.
+- Use generic names (Manager, Helper, Utils) without specificity.

package/dist/agent-src/guidelines/php/patterns/dependency-injection.md

@@ -0,0 +1,57 @@
+# Dependency Injection & Interfaces
+
+> Decouple classes from concrete implementations.
+
+## Idea
+
+Classes depend on **interfaces** (contracts), not on concrete classes.
+Laravel's Service Container resolves the binding at runtime.
+
+## When to Use
+
+✅ Multiple implementations possible (e.g., payment gateways, notification channels)
+✅ External services that need mocking in tests
+✅ Repository pattern (contract + database implementation)
+
+## When NOT to Use
+
+❌ Only one implementation exists and is unlikely to change — just inject the concrete class
+❌ Simple utility classes with no side effects
+
+## Example
+
+```php
+// Contract
+interface PaymentGateway
+{
+    public function charge(int $amountInCents): PaymentResult;
+}
+
+// Implementation
+final class StripePaymentGateway implements PaymentGateway
+{
+    public function charge(int $amountInCents): PaymentResult
+    {
+        // Stripe API call...
+    }
+}
+```
+
+## Binding in ServiceProvider
+
+```php
+$this->app->bind(PaymentGateway::class, StripePaymentGateway::class);
+```
+
+## Naming
+
+- Interfaces (contracts): descriptive name without suffix — `PaymentGateway`, `SmsProvider`
+- Implementations: prefixed with technology — `StripePaymentGateway`, `TwilioSmsProvider`
+- Namespace: `App\Contracts\` for interfaces
+
+## Rules
+
+- One interface = one responsibility (Interface Segregation)
+- Bind in the module's ServiceProvider, not in AppServiceProvider
+- Do **NOT** mark implementation classes `final` if they need mocking in tests
+

package/dist/agent-src/guidelines/php/patterns/dtos.md

@@ -0,0 +1,199 @@
+# DTOs & Value Objects
+
+> Typed data instead of untyped arrays.
+
+## DTO (Data Transfer Object)
+
+Structured, immutable data container for passing data between layers.
+
+### When to Use
+
+✅ Passing validated request data to a service/action
+✅ Returning structured data from a service
+✅ Replacing `array<string, mixed>` in method signatures
+
+### Prefer a DTO base class (if available)
+
+If the project uses a DTO package with attribute-based mapping (e.g., `SimpleDto`, `spatie/data-transfer-object`),
+new DTOs **should extend the project's base class**. Check `composer.json` for DTO-related packages.
+
+#### Attribute-based DTO Example
+
+```php
+use App\Models\Equipment;
+use Vendor\DataHelpers\SimpleDto;
+use Vendor\DataHelpers\SimpleDto\Attributes\ConvertEmptyToNull;
+use Vendor\DataHelpers\SimpleDto\Attributes\DateTimeFormat;
+use Vendor\DataHelpers\SimpleDto\Attributes\Decimal;
+use Vendor\DataHelpers\SimpleDto\Attributes\HasModel;
+use Vendor\DataHelpers\SimpleDto\Attributes\Length;
+use Vendor\DataHelpers\SimpleDto\Attributes\Map;
+use Vendor\DataHelpers\SimpleDto\Attributes\Unsigned;
+use Carbon\Carbon;
+
+#[ConvertEmptyToNull]
+#[HasModel(Equipment::class)]
+class EquipmentDto extends SimpleDto
+{
+    public function __construct(
+        // Primary Key
+        #[Map('id_equipment')]
+        public ?int $id = null,
+
+        // Equipment identification
+        #[Map('equipment_nr'),
+            Length(50)]
+        public string $equipmentNumber = '',
+
+        #[Map('bezeichnung'),
+            Length(250)]
+        public string $title = '',
+
+        // External IDs (from client software)
+        #[Map('ext_uid'),
+            Length(250)]
+        public ?string $externalUid = null,
+
+        // Status
+        #[Map('is_active'),
+            Unsigned,
+            Length(1)]
+        public bool $isActive = true,
+
+        // Financial
+        #[Map('hourly_rate'),
+            Unsigned,
+            Decimal(10, 2)]
+        public float $hourlyRate = 0.0,
+
+        // Timestamps
+        #[Map('created_at'),
+            DateTimeFormat('Y-m-d H:i:s')]
+        public ?Carbon $createdAt = null,
+
+        #[Map('updated_at'),
+            DateTimeFormat('Y-m-d H:i:s')]
+        public ?Carbon $updatedAt = null,
+    ) {}
+}
+```
+
+#### Key attribute-based DTO features
+
+- **`#[Map('db_column')]`** — Maps a readable property name to a database column or API field name
+- **`#[Length(n)]`** — Validates max string length
+- **`#[Decimal(precision, scale)]`** — Validates decimal format
+- **`#[Unsigned]`** — Validates non-negative values
+- **`#[DateTimeFormat('Y-m-d H:i:s')]`** — Casts to/from Carbon with the given format
+- **`#[Email]`** — Validates email format
+- **`#[ConvertEmptyToNull]`** — Class-level: converts empty strings to `null`
+- **`#[HasModel(Model::class)]`** — Links the DTO to an Eloquent model for `fromModel()` / `toModel()`
+
+#### Creating and using DTOs
+
+```php
+// From array (e.g. API response, request data)
+$dto = EquipmentDto::fromArray($data);
+
+// From Eloquent model (requires #[HasModel] + DtoMappingTrait on the model)
+$dto = EquipmentDto::fromModel($equipment);
+
+// To array (uses #[Map] names as keys)
+$array = $dto->toArray();
+
+// To Eloquent model
+$model = $dto->toModel(Equipment::class);
+
+// Collections
+$dtos = EquipmentDto::collection($arrayOfData);
+```
+
+#### Attribute-based DTO rules
+
+- Extend the project's DTO base class
+- Use constructor property promotion with public properties
+- Use `#[Map('column_name')]` to map properties to database/API field names
+- Use validation attributes (`#[Length]`, `#[Decimal]`, `#[Email]`, etc.) for constraints
+- Use `#[ConvertEmptyToNull]` at class level when empty strings should become `null`
+- Use `#[HasModel(Model::class)]` when the DTO maps to an Eloquent model
+- No business logic — just data and mapping
+- Check if the base class requires mutable or immutable properties
+
+### Plain DTO (Fallback)
+
+When no DTO package is available or attribute-based mapping is not suitable (e.g. for very simple
+value transfer between methods), a plain readonly DTO is acceptable:
+
+```php
+final readonly class CreateOrderDTO
+{
+    public function __construct(
+        public int $customerId,
+        public string $description,
+        public int $totalInCents,
+    ) {}
+
+    public static function fromRequest(CreateOrderRequest $request): self
+    {
+        /** @var array{customer_id: int, description: string, total: int} $data */
+        $data = $request->validated();
+
+        return new self(
+            customerId: $data['customer_id'],
+            description: $data['description'],
+            totalInCents: $data['total'],
+        );
+    }
+}
+```
+
+#### Plain DTO Rules
+
+- Always `final readonly class`
+- Constructor property promotion
+- Static factory method `fromRequest()`, `fromArray()`, etc.
+- No business logic — just data
+
+## Value Object
+
+Represents a domain concept with validation and equality semantics.
+
+### When to Use
+
+✅ Domain concepts: `Money`, `Email`, `DateRange`, `Coordinates`
+✅ Value needs validation on creation
+✅ Two instances with same values should be considered equal
+
+### Example
+
+```php
+final readonly class Money
+{
+    public function __construct(
+        public int $amountInCents,
+        public string $currency = 'EUR',
+    ) {
+        if ($this->amountInCents < 0) {
+            throw new InvalidArgumentException('Amount must not be negative');
+        }
+    }
+
+    public function add(self $other): self
+    {
+        if ($this->currency !== $other->currency) {
+            throw new InvalidArgumentException('Cannot add different currencies');
+        }
+
+        return new self(
+            amountInCents: Math::add($this->amountInCents, $other->amountInCents),
+            currency: $this->currency,
+        );
+    }
+}
+```
+
+## When NOT to Use
+
+❌ Data only used in one place and structure is obvious — a simple array is fine
+❌ Wrapping a single primitive with no validation or behavior
+

package/dist/agent-src/guidelines/php/patterns/events.md

@@ -0,0 +1,67 @@
+# Event / Listener Pattern
+
+> Decouple side effects from core logic.
+
+## Idea
+
+A core process dispatches an **Event**, other parts of the system react via **Listeners**.
+The core process doesn't know (or care) who listens.
+
+## Typical Use Cases
+
+✅ Notifications (email, push) after an action
+✅ Logging, audit trails
+✅ Syncing data to external systems
+✅ Cache invalidation
+✅ Triggering follow-up jobs
+
+## Example
+
+```php
+// Event — immutable data container
+final readonly class OrderPlaced
+{
+    public function __construct(
+        public int $orderId,
+        public int $customerId,
+    ) {}
+}
+
+// Listener
+final class SendOrderConfirmation
+{
+    public function handle(OrderPlaced $event): void
+    {
+        // send email...
+    }
+}
+```
+
+## Dispatching
+
+```php
+// In a service or action
+OrderPlaced::dispatch($order->getId(), $order->getCustomerId());
+
+// Or via event helper
+event(new OrderPlaced($order->getId(), $order->getCustomerId()));
+```
+
+## Laravel Discovery
+
+Since Laravel 11, events and listeners are auto-discovered — no manual registration
+needed. Configured in `bootstrap/app.php`.
+
+## Rules
+
+- Events are `final readonly` — immutable data containers
+- Pass **IDs**, not model instances (smaller payload, avoids serialization issues)
+- One listener per side effect — don't cram multiple things into one listener
+- Use queued listeners (`ShouldQueue`) for slow operations (emails, API calls)
+
+## When NOT to Use
+
+❌ Direct, synchronous flow where caller needs the result — just call the service directly
+❌ Only one "listener" that always runs — a direct method call is simpler and easier to follow
+❌ Everything — too many events make the application flow hard to trace
+