@event4u/agent-config 14.23.0 → 16.0.0

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

@@ -0,0 +1,208 @@
+# Eloquent Model Guidelines
+
+> Project-specific Eloquent conventions. Getter/setter pattern, casts, fillable, defaults.
+
+**Related Skills:** `eloquent`, `database`, `migration-creator`
+**Related Guidelines:** [patterns/repositories.md](patterns/repositories.md)
+
+## Core Rules
+
+- Add `$attributes` array for all columns with database defaults
+- Use `$casts` for type casting (encrypted, arrays, enums, dates, booleans)
+- Every model attribute MUST have a **getter** and a **fluent setter**
+- Fluent setters: prefer `static` as return type (preserves subclass types). Use `self` when the class is `final` or when `self` is intentionally more precise.
+
+## Getter/Setter Architecture
+
+There are **two layers** — inside the model vs. outside the model. Never mix them up.
+
+### Inside the model (implementing getters/setters)
+
+**ALWAYS** use `getAttribute()` / `setAttribute()` — these are the Eloquent internals
+that respect `$casts`, accessors, and mutators. **NEVER** use `$this->column_name`
+magic property access inside the model — not for attributes, not for relationships.
+
+**Cast the return value** when the attribute is NOT in `$casts`:
+
+```php
+// ✅ Good — getAttribute() with explicit cast (attribute NOT in $casts)
+public function isActive(): bool
+{
+    return (bool) $this->getAttribute('active');
+}
+
+// user_id is not in $casts, so cast explicitly
+public function getUserId(): ?int
+{
+    $value = $this->getAttribute('user_id');
+
+    return null === $value ? null : (int) $value;
+}
+
+// ✅ Good — NO manual cast needed (attribute IS in $casts)
+// protected $casts = ['is_paused' => 'boolean'];
+public function isPaused(): bool
+{
+    return $this->getAttribute('is_paused');
+}
+
+// ❌ Bad — magic property access
+public function isActive(): bool
+{
+    return (bool) $this->active;
+}
+```
+
+Fluent setter pattern:
+```php
+public function setUserId(?int $userId): static
+{
+    $this->setAttribute('user_id', $userId);
+    return $this;
+}
+```
+
+### Outside the model (calling code: services, controllers, jobs, tests, etc.)
+
+**Always use getters and setters. Never use `getAttribute()` / `setAttribute()` directly.**
+
+```php
+// ✅ Good — use getters/setters
+$config->isPaused();
+$config->setIsPaused(true)->save();
+$name = $customer->getName();
+
+// ❌ Bad — calling getAttribute/setAttribute from outside the model
+$config->getAttribute('is_paused');
+$config->setAttribute('is_paused', true)->save();
+
+// ❌ Bad — direct property access
+$config->is_paused;
+$config->is_paused = true;
+```
+
+**Why:** Getters/setters provide type safety, IDE autocompletion, and a stable API.
+If the underlying column changes, only the model internals need updating.
+
+## Relationship Getters
+
+Every relationship MUST have a **typed getter method** placed directly **above** the relationship method.
+Outside the model, always use the getter — never access the magic property.
+
+```php
+// ✅ Good — getter uses getAttribute(), placed above the relationship method
+public function getEquipment(): ?Equipment
+{
+    return $this->getAttribute('equipment');
+}
+
+public function equipment(): BelongsTo
+{
+    return $this->belongsTo(Equipment::class, 'item_id', 'item_id');
+}
+
+// ✅ Good — calling code uses getter
+$equipment = $repair->getEquipment();
+
+// ❌ Bad — magic property inside getter
+public function getEquipment(): ?Equipment
+{
+    return $this->equipment;  // NEVER do this
+}
+
+// ❌ Bad — accessing magic property from outside the model
+$equipment = $repair->equipment;
+```
+
+When checking if a relationship result exists, use `instanceof` instead of `null ===`:
+
+```php
+// ✅ Good — type-safe check
+if (!$equipment instanceof Equipment) {
+    return;
+}
+
+// ❌ Bad — less type-safe
+if (null === $equipment) {
+    return;
+}
+```
+
+## Observers over `booted()`
+
+Do NOT use `booted()` / `boot()` for model lifecycle hooks (`saving`, `saved`, `deleted`, etc.).
+Use a dedicated **Observer** class registered via the `#[ObservedBy]` attribute.
+
+```php
+// ✅ Good — Observer registered via attribute
+#[ObservedBy([RepairObserver::class])]
+class Repair extends Model { /* ... */ }
+
+// ❌ Bad — lifecycle logic in booted()
+class Repair extends Model
+{
+    protected static function booted(): void
+    {
+        static::saving(static function (Repair $repair): void { /* ... */ });
+    }
+}
+```
+
+**Why:** Observers keep models slim, make lifecycle logic testable and discoverable,
+and follow the established project pattern (all other models use `#[ObservedBy]`).
+
+## Default Attributes
+
+```php
+protected $attributes = [
+    'options' => [],
+    'default_role' => 'staff',
+    'verified' => false,
+];
+```
+
+### Expressive Setters
+
+Prefer expressive method names over generic setters when they improve readability:
+
+```php
+// ✅ Better — intent is clear
+$model->activate();
+
+// 🆗 OK but less expressive
+$model->setActive(true);
+```
+
+## Model Updates
+
+Always use validated data — never `$request->all()`:
+
+```php
+// ✅ Good
+$model->update($request->validated());
+
+// ❌ Bad — passes unvalidated data
+$model->update($request->all());
+```
+
+## Prefer Model Casts — No Redundant Manual Casting
+
+When an attribute is defined in `$casts` (or `casts()` method), do **not** manually cast it again
+in getters. The model already handles the conversion.
+
+```php
+// ✅ Good — no manual cast needed, model handles it
+public function isPaused(): bool
+{
+    return $this->getAttribute('is_paused');
+}
+
+// ❌ Bad — redundant (bool) cast when already in $casts
+public function isPaused(): bool
+{
+    return (bool) $this->getAttribute('is_paused');
+}
+```
+
+This applies to all cast types: `boolean`, `integer`, `float`, `array`, `datetime`, enums, etc.
+If the attribute is cast, trust the cast — do not re-cast in PHP.

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

@@ -0,0 +1,80 @@
+# Flux UI Guidelines
+
+> Flux component conventions — usage, variants, forms, icons, Livewire integration.
+
+**Related Skills:** `flux`, `livewire`, `blade-ui`
+
+## Component Usage
+
+- Use Flux components (`<flux:*>`) instead of raw HTML where a Flux equivalent exists.
+- Follow the project's existing Flux usage patterns.
+- Check Flux docs at https://fluxui.dev/docs for latest API.
+
+## Common Components
+
+```blade
+{{-- Button --}}
+<flux:button variant="primary">Save</flux:button>
+<flux:button variant="danger" wire:click="delete">Delete</flux:button>
+
+{{-- Input --}}
+<flux:input wire:model="name" label="Name" placeholder="Enter name" />
+
+{{-- Select --}}
+<flux:select wire:model="status" label="Status">
+    <flux:option value="active">Active</flux:option>
+    <flux:option value="inactive">Inactive</flux:option>
+</flux:select>
+
+{{-- Modal --}}
+<flux:modal name="confirm-delete">
+    <flux:heading>Delete item?</flux:heading>
+    <flux:text>This action cannot be undone.</flux:text>
+    <flux:button variant="danger" wire:click="delete">Confirm</flux:button>
+</flux:modal>
+
+{{-- Table --}}
+<flux:table>
+    <flux:columns>
+        <flux:column>Name</flux:column>
+    </flux:columns>
+    <flux:rows>
+        @foreach($items as $item)
+            <flux:row :key="$item->id">
+                <flux:cell>{{ $item->name }}</flux:cell>
+            </flux:row>
+        @endforeach
+    </flux:rows>
+</flux:table>
+```
+
+## Variants and Styling
+
+- Use `variant` prop: `primary`, `danger`, `ghost`, `subtle`, `outline`.
+- Use `size` prop: `sm`, `base`, `lg`.
+- Add custom Tailwind via `class` only when Flux doesn't cover the need.
+- Don't override Flux's built-in styling with conflicting classes.
+
+## Forms
+
+- Use `<flux:input>`, `<flux:textarea>`, `<flux:select>`, `<flux:checkbox>`.
+- Use `label` prop — Flux handles the `<label>` element.
+- Use `wire:model` for Livewire binding.
+- Flux components automatically display validation errors.
+
+## Icons
+
+- `<flux:icon name="heroicon-name" />` — Heroicons naming convention.
+
+## Livewire Integration
+
+- `wire:click`, `wire:submit`, `wire:model` work directly on Flux components.
+- Modals: `$this->modal('name')->show()`.
+
+## Do NOT
+
+- Use raw `<button>`, `<input>`, `<select>` when Flux equivalent exists.
+- Override Flux component styles globally — use variants or slots.
+- Mix Flux with a different UI library in the same view.
+- Skip `label` prop on form fields — accessibility matters.
+- Add manual error rendering alongside Flux (it's built-in).

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

@@ -0,0 +1,207 @@
+# 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()`
+
+## Variables
+
+- **Don't assign single-use values to a variable** — pass the expression
+  directly to the call. Universal rule with carve-outs (side effects,
+  loops, debugger, type narrowing) lives in
+  [`code-clarity.md`](../code-clarity.md) § Don't assign single-use
+  values to a variable.
+
+## 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);
+```
+
+## Comments and DocBlocks
+
+A code comment earns its place only by stating a constraint the code
+cannot show — a non-obvious invariant, a workaround for a known bug, a
+hidden dependency. Never write comments that narrate ("added for X",
+"this calls Y"), repeat the next line, or justify the change to the
+reviewer. Full clause: [`code-clarity.md § Comment discipline`](../code-clarity.md#comment-discipline--state-a-constraint-not-a-narration).
+
+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/dist/agent-src/guidelines/php/git.md

@@ -0,0 +1,164 @@
+# 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}
+```
+
+| Type | When |
+|---|---|
+| `feat/` | New feature |
+| `fix/` | Bug fix |
+| `hotfix/` | Urgent production fix |
+| `chore/` | Maintenance, refactoring, tooling |
+| `docs/` | Documentation changes |
+| `test/` | Test additions/changes |
+
+### Examples
+
+```
+feat/DEV-1234/user-notification-preferences
+fix/DEV-5678/null-pointer-in-import
+chore/refactor-agent-setup
+hotfix/DEV-999/critical-payment-bug
+```
+
+### Rules
+
+- Always include the Jira ticket ID when one exists
+- Use kebab-case for the description part
+- Keep branch names short but descriptive
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+See `commit-conventions` rule for the base format and type table.
+
+### Type selection rules
+
+**`feat`** — a new capability is added; user or system can do something new.
+
+**`fix`** — existing behavior was wrong; bug, regression, or broken edge case corrected.
+
+**`refactor`** — structure changes, readability/maintainability improves, behavior unchanged.
+Do NOT use `refactor` if behavior changes — use `feat` or `fix` instead.
+
+**`docs`** — only documentation changes, no runtime or behavior change.
+
+**`test`** — only tests added/updated, no production behavior changes.
+
+**`ci`** — GitHub Actions, pipelines, CI checks, automation workflows, release jobs.
+
+**`chore`** — maintenance, repo housekeeping, dependency bumps, non-functional cleanup
+that is not better classified as `build`, `ci`, or `docs`.
+
+**`perf`** — measurable performance improvement.
+
+**`build`** — build tooling, packaging, Docker changes.
+
+**`style`** — formatting only, no logic change (e.g. ECS/Rector auto-fixes).
+
+### Scope guidance
+
+Use a scope when it adds clarity. Good scopes:
+
+- Jira ticket ID: `DEV-1234`
+- Module/area: `api`, `auth`, `skills`, `rules`, `ci`, `frontend`, `linter`
+
+Do not add a scope if it adds no value. `fix(core): fix typo` → just `fix: fix typo`.
+
+### Description rules
+
+- Describe **intent**, not implementation detail
+- Describe **what changed**, not every low-level step
+- Avoid generic wording: `update stuff`, `fix issue`, `changes`
+
+Good: `fix(routes): preserve middleware order for api endpoints`
+Bad: `fix: fix things`
+
+### Breaking changes
+
+Use `!` after type/scope or `BREAKING CHANGE:` in footer:
+
+```
+feat(api)!: rename invoice status values
+refactor(auth)!: remove legacy session flow
+```
+
+### Commit splitting
+
+If a change contains multiple unrelated concerns, split into multiple commits.
+
+Bad: `refactor: cleanup skills and fix ci and update docs`
+
+Better:
+```
+refactor(skills): remove duplicate routing helpers
+ci(lint): add skill-lint workflow
+docs(readme): document new lint tasks
+```
+
+### Squash merge titles
+
+- Use Conventional Commit format
+- Summarize the **net effect** of the PR
+- Do not copy vague branch names
+- Do not include issue noise if it hurts readability
+
+### 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
+```
+
+### Decision checklist
+
+Before writing the commit message:
+
+1. Did behavior change? → `feat` or `fix`
+2. Was it only structure/cleanup? → `refactor`
+3. Was it only docs, tests, or CI? → `docs`, `test`, `ci`
+4. Is the scope useful or just noise?
+5. Is this actually multiple commits hiding in one?
+
+### Anti-patterns
+
+- `update stuff` / `fix bug` / `changes` / `refactor everything`
+- Using `chore` for meaningful behavior changes
+- Using `refactor` for bug fixes
+- Using one commit for multiple unrelated concerns
+- Vague squash merge titles that don't describe the net effect
+
+## Pull Requests
+
+- PR title follows commit message format: `feat(DEV-1234): short description`
+- Fill in the PR template (checklist, description, testing notes)
+- Link the Jira ticket in the PR description
+- Ensure all quality gates pass before requesting review
+