@event4u/agent-config 1.9.1

package/.agent-src/guidelines/php/general.md

@@ -0,0 +1,191 @@
+# PHP Guidelines
+
+> PHP conventions and coding standards.
+
+**Related Skills:** `php`, `php-coder`, `php-service`
+**Related Rules:** `php-coding.md`
+
+## Quick Reference
+
+| Topic           | Rule                                                  |
+|-----------------|-------------------------------------------------------|
+| Strict types    | `declare(strict_types=1);` in every file              |
+| Variables       | `camelCase`                                           |
+| Array keys      | `snake_case`                                          |
+| Constants       | `UPPER_SNAKE_CASE`                                    |
+| Strings         | Single quotes (no interpolation), prefer concatenation (`.`), `sprintf()` only when complex |
+| Comparisons     | Always `===` / `!==`, Yoda style (`null === $var`)    |
+| Types           | Explicit types for properties, parameters, returns    |
+
+## Naming
+
+- Method names must be **expressive**, not declarative. No abbreviations.
+- Boolean checks: `isValid()`, `hasPermission()` — not `valid()`, `check()`
+- Retrieving: `getUser()`, `fetchUserData()` — not `user()`, `userData()`
+- Actions: `sendEmail()`, `processPayment()` — not `email()`, `payment()`
+
+## Strings
+
+- Single quotes when no interpolation: `$table = 'users';`
+- Prefer concatenation with `.` operator: `'Hi ' . $name . '!'`
+- Use `sprintf()` only when concatenation becomes unreadable (many placeholders, formatting): `sprintf('There are %d items in %s', $count, $location)`
+
+## Control Structures
+
+- **No one-liner IF** statements
+- **Prefer early return** over `else` / nested `if`
+- Ternary for short statements only
+
+```php
+// ✅ Early return
+if (!$conditionA) {
+    return;
+}
+// conditionA passed...
+```
+
+## Typed Properties
+
+- Always use typed properties. Nullable with default `null`:
+
+```php
+// ✅ Good
+public ?int $age = null;
+
+// ❌ Bad
+public int | null $age;
+```
+
+## Typed Arguments
+
+- Prefer typed method arguments over arrays. Named arguments with spread for bulk:
+
+```php
+// ✅ Type-safe
+public function createUser(int $id, string $name): void {}
+
+// Call with array via spread
+$data = ['id' => 1, 'name' => 'John'];
+createUser(...$data);
+```
+
+## DocBlocks
+
+- **Only** use DocBlocks to explain complex logic or when type hints are insufficient
+- **Must** add DocBlock for iterable types: `@param array<int, MyObject> $items`
+- Do NOT add DocBlocks that just repeat the type signature
+
+## Arrays
+
+- Short syntax only (`[]`, not `array()`)
+- Trailing comma on each line
+- Each item on a separate line
+- Keys in `snake_case`
+
+## Enums
+
+- Cases must be **UPPERCASE**: `case MONDAY;`
+- Use [backed enums](https://www.php.net/manual/en/language.enumerations.backed.php) for database values
+
+## Operator Precedence — Always Use Parentheses
+
+When mixing `?:` (ternary/elvis), `??` (null coalessce), or `.` (concatenation),
+**always use explicit parentheses** to make the intended evaluation order unambiguous.
+
+```php
+// ❌ Bad — ambiguous: is it ($a ?: 'index ') . $i  or  $a ?: ('index ' . $i)?
+$label = $a ?: 'index ' . $i;
+
+// ✅ Good — explicit and unambiguous
+$label = $a ?: ('index ' . $i);
+
+// ❌ Bad — nested ternary/elvis without grouping
+$value = $a ?: $b ?: $c . $d;
+
+// ✅ Good
+$value = $a ?: ($b ?: ($c . $d));
+```
+
+This applies to **any** combination of operators where precedence is not immediately obvious.
+When in doubt, add parentheses — readability beats brevity.
+
+## Performance Tips
+
+### ❌  Avoid `array_merge()` in Loops
+
+`array_merge()` inside a loop copies the entire array each iteration → **O(n²)**.
+
+```php
+// ❌ Bad — O(n²)
+$all = [];
+foreach ($pages as $page) {
+    $all = array_merge($all, $page->items());
+}
+
+// ✅ Good — O(n)
+$all = [];
+foreach ($pages as $page) {
+    array_push($all, ...$page->items());
+}
+```
+
+## Traits
+
+- One `use` statement per line:
+
+```php
+// ✅ Good
+use TraitA;
+use TraitB;
+```
+
+## Interfaces
+
+- Namespace: `App\Contracts` (grouped in subfolders)
+- No `Interface` suffix: `SmsProvider`, not `SmsProviderInterface`
+
+## Return Types — `static` vs `self`
+
+- **Prefer `static`** for fluent methods (setters, builders, chainable methods) — it preserves the actual class type in subclasses.
+- **Use `self`** when it is intentionally more precise — e.g., `final` classes, named constructors, or when you explicitly want to lock the return type to the declaring class.
+- This is especially important for Eloquent models, DTOs, and any class that may be extended.
+
+```php
+// ✅ Preferred — preserves subclass type
+public function setName(string $name): static
+{
+    $this->name = $name;
+    return $this;
+}
+
+// ✅ Also fine — class is final, self is more precise
+final class Config
+{
+    public function setName(string $name): self
+    {
+        $this->name = $name;
+        return $this;
+    }
+}
+```
+
+## Constructor Property Promotion
+
+- Each property on a separate line, trailing comma on last property
+- Preferred over manual assignment in constructor body
+
+## JSON Handling
+
+- **Always validate** — `json_decode()` with `JSON_THROW_ON_ERROR`, never silent failure.
+- **Fix malformed JSON** — trailing commas, single quotes, unquoted keys. Clean before parsing.
+- **Pretty-print** — `JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE` for readability.
+- **Type safety** — decode to typed DTOs or interfaces, not untyped arrays/objects.
+
+```php
+// ✅ Safe JSON decoding
+$data = json_decode($jsonString, true, 512, JSON_THROW_ON_ERROR);
+
+// ❌ Silent failure
+$data = json_decode($jsonString);
+```
+

package/.agent-src/guidelines/php/git.md

@@ -0,0 +1,96 @@
+# Git & Version Control Guidelines
+
+> Project-specific Git conventions. Branch naming, commit messages, PR workflow.
+
+**Related Skills:** `git-workflow`, `conventional-commits-writing`
+**Related Rules:** `commit-conventions.md`
+
+## Branch Naming
+
+```
+{type}/{ticket-id}/{short-description}
+```
+
+Types: `feat/`, `fix/`, `hotfix/`, `chore/`, `docs/`, `test/`
+
+```
+feat/DEV-1234/user-notification-preferences
+fix/DEV-5678/null-pointer-in-import
+chore/refactor-agent-setup
+hotfix/DEV-999/critical-payment-bug
+```
+
+## Commit Messages
+
+See `commit-conventions` rule for base format. Key type selection:
+
+- `feat` — new capability. `fix` — bug/regression. `refactor` — structure only, NO behavior change.
+- `docs` — docs only. `test` — tests only. `ci` — CI/workflows. `chore` — maintenance/cleanup.
+- `perf` — performance. `build` — build tooling. `style` — formatting only.
+
+**Scope:** Jira ID or area name (`api`, `auth`, `skills`). Only add when it improves clarity.
+
+**Description:** Intent, not implementation. Imperative mood. Max 72 chars. No generic filler.
+
+**Breaking:** `!` after type/scope or `BREAKING CHANGE:` footer.
+
+```
+feat(api)!: rename invoice status values
+refactor(auth)!: remove legacy session flow
+```
+
+**Splitting:** Mixed concerns → split commits. Don't hide unrelated changes in one.
+
+```
+refactor(skills): remove duplicate routing helpers
+ci(lint): add skill-lint workflow
+docs(readme): document new lint tasks
+```
+
+**Squash merge titles:** Conventional Commit format, describe net effect, not every internal commit.
+
+### Anti-patterns
+
+- `update stuff` / `fix bug` / `changes`
+- `refactor` for bug fixes, `chore` for behavior changes
+- Multiple unrelated concerns in one commit
+
+### Decision checklist
+
+1. Behavior changed? → `feat` or `fix`
+2. Structure only? → `refactor`
+3. Only docs/tests/CI? → `docs`/`test`/`ci`
+4. Scope useful or noise?
+5. Multiple commits hiding in one?
+
+### Examples by area
+
+```bash
+# Features
+feat(DEV-2133): send email to customer when product is shipped
+
+# Bug fixes
+fix(import): handle null values in equipment JSON
+
+# Refactoring
+refactor: extract user sync logic into dedicated service
+
+# Skills / Rules / Agent config
+refactor(skills): merge duplicate analysis skills
+feat(rules): add analysis routing quality gate
+fix(skills): restore concrete validation in skill reviewer
+
+# CI / Tooling
+ci(lint): add skill linter workflow
+feat(linter): detect pointer-only skills
+
+# Docs
+docs(roadmap): add phase 3 implementation plan
+docs(readme): clarify source-of-truth workflow
+```
+
+## Pull Requests
+
+- PR title: Conventional Commit format — `feat(DEV-1234): short description`
+- Fill PR template, link Jira ticket, ensure quality gates pass
+

package/.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/.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/.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/.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/.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
+