@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

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

@@ -0,0 +1,415 @@
+---
+name: laravel-patterns
+description: Laravel architecture patterns, routing/controllers, Eloquent ORM, service layers, queues, events, caching, and API resources for production apps.
+origin: ECC
+---
+
+# Laravel Development Patterns
+
+Production-grade Laravel architecture patterns for scalable, maintainable applications.
+
+## When to Use
+
+- Building Laravel web applications or APIs
+- Structuring controllers, services, and domain logic
+- Working with Eloquent models and relationships
+- Designing APIs with resources and pagination
+- Adding queues, events, caching, and background jobs
+
+## How It Works
+
+- Structure the app around clear boundaries (controllers -> services/actions -> models).
+- Use explicit bindings and scoped bindings to keep routing predictable; still enforce authorization for access control.
+- Favor typed models, casts, and scopes to keep domain logic consistent.
+- Keep IO-heavy work in queues and cache expensive reads.
+- Centralize config in `config/*` and keep environments explicit.
+
+## Examples
+
+### Project Structure
+
+Use a conventional Laravel layout with clear layer boundaries (HTTP, services/actions, models).
+
+### Recommended Layout
+
+```
+app/
+├── Actions/            # Single-purpose use cases
+├── Console/
+├── Events/
+├── Exceptions/
+├── Http/
+│   ├── Controllers/
+│   ├── Middleware/
+│   ├── Requests/       # Form request validation
+│   └── Resources/      # API resources
+├── Jobs/
+├── Models/
+├── Policies/
+├── Providers/
+├── Services/           # Coordinating domain services
+└── Support/
+config/
+database/
+├── factories/
+├── migrations/
+└── seeders/
+resources/
+├── views/
+└── lang/
+routes/
+├── api.php
+├── web.php
+└── console.php
+```
+
+### Controllers -> Services -> Actions
+
+Keep controllers thin. Put orchestration in services and single-purpose logic in actions.
+
+```php
+final class CreateOrderAction
+{
+    public function __construct(private OrderRepository $orders) {}
+
+    public function handle(CreateOrderData $data): Order
+    {
+        return $this->orders->create($data);
+    }
+}
+
+final class OrdersController extends Controller
+{
+    public function __construct(private CreateOrderAction $createOrder) {}
+
+    public function store(StoreOrderRequest $request): JsonResponse
+    {
+        $order = $this->createOrder->handle($request->toDto());
+
+        return response()->json([
+            'success' => true,
+            'data' => OrderResource::make($order),
+            'error' => null,
+            'meta' => null,
+        ], 201);
+    }
+}
+```
+
+### Routing and Controllers
+
+Prefer route-model binding and resource controllers for clarity.
+
+```php
+use Illuminate\Support\Facades\Route;
+
+Route::middleware('auth:sanctum')->group(function () {
+    Route::apiResource('projects', ProjectController::class);
+});
+```
+
+### Route Model Binding (Scoped)
+
+Use scoped bindings to prevent cross-tenant access.
+
+```php
+Route::scopeBindings()->group(function () {
+    Route::get('/accounts/{account}/projects/{project}', [ProjectController::class, 'show']);
+});
+```
+
+### Nested Routes and Binding Names
+
+- Keep prefixes and paths consistent to avoid double nesting (e.g., `conversation` vs `conversations`).
+- Use a single parameter name that matches the bound model (e.g., `{conversation}` for `Conversation`).
+- Prefer scoped bindings when nesting to enforce parent-child relationships.
+
+```php
+use App\Http\Controllers\Api\ConversationController;
+use App\Http\Controllers\Api\MessageController;
+use Illuminate\Support\Facades\Route;
+
+Route::middleware('auth:sanctum')->prefix('conversations')->group(function () {
+    Route::post('/', [ConversationController::class, 'store'])->name('conversations.store');
+
+    Route::scopeBindings()->group(function () {
+        Route::get('/{conversation}', [ConversationController::class, 'show'])
+            ->name('conversations.show');
+
+        Route::post('/{conversation}/messages', [MessageController::class, 'store'])
+            ->name('conversation-messages.store');
+
+        Route::get('/{conversation}/messages/{message}', [MessageController::class, 'show'])
+            ->name('conversation-messages.show');
+    });
+});
+```
+
+If you want a parameter to resolve to a different model class, define explicit binding. For custom binding logic, use `Route::bind()` or implement `resolveRouteBinding()` on the model.
+
+```php
+use App\Models\AiConversation;
+use Illuminate\Support\Facades\Route;
+
+Route::model('conversation', AiConversation::class);
+```
+
+### Service Container Bindings
+
+Bind interfaces to implementations in a service provider for clear dependency wiring.
+
+```php
+use App\Repositories\EloquentOrderRepository;
+use App\Repositories\OrderRepository;
+use Illuminate\Support\ServiceProvider;
+
+final class AppServiceProvider extends ServiceProvider
+{
+    public function register(): void
+    {
+        $this->app->bind(OrderRepository::class, EloquentOrderRepository::class);
+    }
+}
+```
+
+### Eloquent Model Patterns
+
+### Model Configuration
+
+```php
+final class Project extends Model
+{
+    use HasFactory;
+
+    protected $fillable = ['name', 'owner_id', 'status'];
+
+    protected $casts = [
+        'status' => ProjectStatus::class,
+        'archived_at' => 'datetime',
+    ];
+
+    public function owner(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'owner_id');
+    }
+
+    public function scopeActive(Builder $query): Builder
+    {
+        return $query->whereNull('archived_at');
+    }
+}
+```
+
+### Custom Casts and Value Objects
+
+Use enums or value objects for strict typing.
+
+```php
+use Illuminate\Database\Eloquent\Casts\Attribute;
+
+protected $casts = [
+    'status' => ProjectStatus::class,
+];
+```
+
+```php
+protected function budgetCents(): Attribute
+{
+    return Attribute::make(
+        get: fn (int $value) => Money::fromCents($value),
+        set: fn (Money $money) => $money->toCents(),
+    );
+}
+```
+
+### Eager Loading to Avoid N+1
+
+```php
+$orders = Order::query()
+    ->with(['customer', 'items.product'])
+    ->latest()
+    ->paginate(25);
+```
+
+### Query Objects for Complex Filters
+
+```php
+final class ProjectQuery
+{
+    public function __construct(private Builder $query) {}
+
+    public function ownedBy(int $userId): self
+    {
+        $query = clone $this->query;
+
+        return new self($query->where('owner_id', $userId));
+    }
+
+    public function active(): self
+    {
+        $query = clone $this->query;
+
+        return new self($query->whereNull('archived_at'));
+    }
+
+    public function builder(): Builder
+    {
+        return $this->query;
+    }
+}
+```
+
+### Global Scopes and Soft Deletes
+
+Use global scopes for default filtering and `SoftDeletes` for recoverable records.
+Use either a global scope or a named scope for the same filter, not both, unless you intend layered behavior.
+
+```php
+use Illuminate\Database\Eloquent\SoftDeletes;
+use Illuminate\Database\Eloquent\Builder;
+
+final class Project extends Model
+{
+    use SoftDeletes;
+
+    protected static function booted(): void
+    {
+        static::addGlobalScope('active', function (Builder $builder): void {
+            $builder->whereNull('archived_at');
+        });
+    }
+}
+```
+
+### Query Scopes for Reusable Filters
+
+```php
+use Illuminate\Database\Eloquent\Builder;
+
+final class Project extends Model
+{
+    public function scopeOwnedBy(Builder $query, int $userId): Builder
+    {
+        return $query->where('owner_id', $userId);
+    }
+}
+
+// In service, repository etc.
+$projects = Project::ownedBy($user->id)->get();
+```
+
+### Transactions for Multi-Step Updates
+
+```php
+use Illuminate\Support\Facades\DB;
+
+DB::transaction(function (): void {
+    $order->update(['status' => 'paid']);
+    $order->items()->update(['paid_at' => now()]);
+});
+```
+
+### Migrations
+
+### Naming Convention
+
+- File names use timestamps: `YYYY_MM_DD_HHMMSS_create_users_table.php`
+- Migrations use anonymous classes (no named class); the filename communicates intent
+- Table names are `snake_case` and plural by default
+
+### Example Migration
+
+```php
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('orders', function (Blueprint $table): void {
+            $table->id();
+            $table->foreignId('customer_id')->constrained()->cascadeOnDelete();
+            $table->string('status', 32)->index();
+            $table->unsignedInteger('total_cents');
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('orders');
+    }
+};
+```
+
+### Form Requests and Validation
+
+Keep validation in form requests and transform inputs to DTOs.
+
+```php
+use App\Models\Order;
+
+final class StoreOrderRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()?->can('create', Order::class) ?? false;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'customer_id' => ['required', 'integer', 'exists:customers,id'],
+            'items' => ['required', 'array', 'min:1'],
+            'items.*.sku' => ['required', 'string'],
+            'items.*.quantity' => ['required', 'integer', 'min:1'],
+        ];
+    }
+
+    public function toDto(): CreateOrderData
+    {
+        return new CreateOrderData(
+            customerId: (int) $this->validated('customer_id'),
+            items: $this->validated('items'),
+        );
+    }
+}
+```
+
+### API Resources
+
+Keep API responses consistent with resources and pagination.
+
+```php
+$projects = Project::query()->active()->paginate(25);
+
+return response()->json([
+    'success' => true,
+    'data' => ProjectResource::collection($projects->items()),
+    'error' => null,
+    'meta' => [
+        'page' => $projects->currentPage(),
+        'per_page' => $projects->perPage(),
+        'total' => $projects->total(),
+    ],
+]);
+```
+
+### Events, Jobs, and Queues
+
+- Emit domain events for side effects (emails, analytics)
+- Use queued jobs for slow work (reports, exports, webhooks)
+- Prefer idempotent handlers with retries and backoff
+
+### Caching
+
+- Cache read-heavy endpoints and expensive queries
+- Invalidate caches on model events (created/updated/deleted)
+- Use tags when caching related data for easy invalidation
+
+### Configuration and Environments
+
+- Keep secrets in `.env` and config in `config/*.php`
+- Use per-environment config overrides and `config:cache` in production

package/.agent/skills/laravel-plugin-discovery/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: laravel-plugin-discovery
+description: Discover and evaluate Laravel packages via LaraPlugins.io MCP. Use when the user wants to find plugins, check package health, or assess Laravel/PHP compatibility.
+origin: ECC
+---
+
+# Laravel Plugin Discovery
+
+Find, evaluate, and choose healthy Laravel packages using the LaraPlugins.io MCP server.
+
+## When to Use
+
+- User wants to find Laravel packages for a specific feature (e.g. "auth", "permissions", "admin panel")
+- User asks "what package should I use for..." or "is there a Laravel package for..."
+- User wants to check if a package is actively maintained
+- User needs to verify Laravel version compatibility
+- User wants to assess package health before adding to a project
+
+## MCP Requirement
+
+LaraPlugins MCP server must be configured. Add to your `~/.claude.json` mcpServers:
+
+```json
+"laraplugins": {
+  "type": "http",
+  "url": "https://laraplugins.io/mcp/plugins"
+}
+```
+
+No API key required — the server is free for the Laravel community.
+
+## MCP Tools
+
+The LaraPlugins MCP provides two primary tools:
+
+### SearchPluginTool
+
+Search packages by keyword, health score, vendor, and version compatibility.
+
+**Parameters:**
+- `text_search` (string, optional): Keyword to search (e.g. "permission", "admin", "api")
+- `health_score` (string, optional): Filter by health band — `Healthy`, `Medium`, `Unhealthy`, or `Unrated`
+- `laravel_compatibility` (string, optional): Filter by Laravel version — `"5"`, `"6"`, `"7"`, `"8"`, `"9"`, `"10"`, `"11"`, `"12"`, `"13"`
+- `php_compatibility` (string, optional): Filter by PHP version — `"7.4"`, `"8.0"`, `"8.1"`, `"8.2"`, `"8.3"`, `"8.4"`, `"8.5"`
+- `vendor_filter` (string, optional): Filter by vendor name (e.g. "spatie", "laravel")
+- `page` (number, optional): Page number for pagination
+
+### GetPluginDetailsTool
+
+Fetch detailed metrics, readme content, and version history for a specific package.
+
+**Parameters:**
+- `package` (string, required): Full Composer package name (e.g. "spatie/laravel-permission")
+- `include_versions` (boolean, optional): Include version history in response
+
+---
+
+## How It Works
+
+### Finding Packages
+
+When the user wants to discover packages for a feature:
+
+1. Use `SearchPluginTool` with relevant keywords
+2. Apply filters for health score, Laravel version, or PHP version
+3. Review the results with package names, descriptions, and health indicators
+
+### Evaluating Packages
+
+When the user wants to assess a specific package:
+
+1. Use `GetPluginDetailsTool` with the package name
+2. Review health score, last updated date, Laravel version support
+3. Check vendor reputation and risk indicators
+
+### Checking Compatibility
+
+When the user needs Laravel or PHP version compatibility:
+
+1. Search with `laravel_compatibility` filter set to their version
+2. Or get details on a specific package to see its supported versions
+
+---
+
+## Examples
+
+### Example: Find Authentication Packages
+
+```
+SearchPluginTool({
+  text_search: "authentication",
+  health_score: "Healthy"
+})
+```
+
+Returns packages matching "authentication" with healthy status:
+- spatie/laravel-permission
+- laravel/breeze
+- laravel/passport
+- etc.
+
+### Example: Find Laravel 12 Compatible Packages
+
+```
+SearchPluginTool({
+  text_search: "admin panel",
+  laravel_compatibility: "12"
+})
+```
+
+Returns packages compatible with Laravel 12.
+
+### Example: Get Package Details
+
+```
+GetPluginDetailsTool({
+  package: "spatie/laravel-permission",
+  include_versions: true
+})
+```
+
+Returns:
+- Health score and last activity
+- Laravel/PHP version support
+- Vendor reputation (risk score)
+- Version history
+- Brief description
+
+### Example: Find Packages by Vendor
+
+```
+SearchPluginTool({
+  vendor_filter: "spatie",
+  health_score: "Healthy"
+})
+```
+
+Returns all healthy packages from vendor "spatie".
+
+---
+
+## Filtering Best Practices
+
+### By Health Score
+
+| Health Band | Meaning |
+|-------------|---------|
+| `Healthy` | Active maintenance, recent updates |
+| `Medium` | Occasional updates, may need attention |
+| `Unhealthy` | Abandoned or infrequently maintained |
+| `Unrated` | Not yet assessed |
+
+**Recommendation**: Prefer `Healthy` packages for production applications.
+
+### By Laravel Version
+
+| Version | Notes |
+|---------|-------|
+| `13` | Latest Laravel |
+| `12` | Current stable |
+| `11` | Still widely used |
+| `10` | Legacy but common |
+| `5`-`9` | Deprecated |
+
+**Recommendation**: Match the target project's Laravel version.
+
+### Combining Filters
+
+```typescript
+// Find healthy, Laravel 12 compatible packages for permissions
+SearchPluginTool({
+  text_search: "permission",
+  health_score: "Healthy",
+  laravel_compatibility: "12"
+})
+```
+
+---
+
+## Response Interpretation
+
+### Search Results
+
+Each result includes:
+- Package name (e.g. `spatie/laravel-permission`)
+- Brief description
+- Health status indicator
+- Laravel version support badges
+
+### Package Details
+
+The detailed response includes:
+- **Health Score**: Numeric or band indicator
+- **Last Activity**: When the package was last updated
+- **Laravel Support**: Version compatibility matrix
+- **PHP Support**: PHP version compatibility
+- **Risk Score**: Vendor trust indicators
+- **Version History**: Recent release timeline
+
+---
+
+## Common Use Cases
+
+| Scenario | Recommended Approach |
+|----------|---------------------|
+| "What package for auth?" | Search "auth" with healthy filter |
+| "Is spatie/package still maintained?" | Get details, check health score |
+| "Need Laravel 12 packages" | Search with laravel_compatibility: "12" |
+| "Find admin panel packages" | Search "admin panel", review results |
+| "Check vendor reputation" | Search by vendor, check details |
+
+---
+
+## Best Practices
+
+1. **Always filter by health** — Use `health_score: "Healthy"` for production projects
+2. **Match Laravel version** — Always check `laravel_compatibility` matches the target project
+3. **Check vendor reputation** — Prefer packages from known vendors (spatie, laravel, etc.)
+4. **Review before recommending** — Use GetPluginDetailsTool for a comprehensive assessment
+5. **No API key needed** — The MCP is free, no authentication required
+
+---
+
+## Related Skills
+
+- `laravel-patterns` — Laravel architecture and patterns
+- `laravel-tdd` — Test-driven development for Laravel
+- `laravel-security` — Laravel security best practices
+- `documentation-lookup` — General library documentation lookup (Context7)