Add Laravel 11.x/12.x skills and commands reflecting stable patterns. Include focused docs, intersection summaries, and updated caching guidance with tags and locks. De-duplicate overlapping subagents and streamline workflows.

jpcaparas · jpcaparas · commit 60ff91ba4b1b · 2025-11-05T09:55:51.000+13:00
diff --git a/README.md b/README.md
@@ -110,6 +110,23 @@ Skills live in `skills/` and are designed for everyday Laravel work. Core exampl
 
 This fork focuses on Laravel skills and removes overlapping generic skills so it can be used independently without conflicts. It is also compatible with the base Superpowers plugin if you choose to install both. Use the Laravel‑specific commands here, or continue using the base plugin’s generic workflows.
 
+#### Docs Intersection (Laravel 11.x + 12.x)
+
+We added a focused set of skills that reflect patterns stable across both 11.x and 12.x:
+
+- Form Requests & Validation (`laravel:form-requests`)
+- Policies & Authorization (`laravel:policies-and-authorization`)
+- Eloquent Relationships & Loading (`laravel:eloquent-relationships`)
+- Transactions & Consistency (`laravel:transactions-and-consistency`)
+- HTTP Client Resilience (`laravel:http-client-resilience`)
+- Task Scheduling (`laravel:task-scheduling`)
+- API Resources & Pagination (`laravel:api-resources-and-pagination`)
+- Blade Components & Layouts (`laravel:blade-components-and-layouts`)
+- Filesystem Uploads & URLs (`laravel:filesystem-uploads`)
+- Rate Limiting & Throttle (`laravel:rate-limiting`)
+- Exception Handling & Logging (`laravel:exception-handling-and-logging`)
+
+
 ### Commands
 
 Commands are thin wrappers that activate skills. Key examples:
@@ -120,6 +137,20 @@ Commands are thin wrappers that activate skills. Key examples:
 - `laravel-check.md` → `laravel:quality-checks`
 - `laravel-tdd.md` → `laravel:tdd-with-pest`
 
+Additional wrappers for the new docs‑intersection skills:
+
+- `laravel-form-requests.md` → `laravel:form-requests`
+- `laravel-policies.md` → `laravel:policies-and-authorization`
+- `laravel-eloquent-relationships.md` → `laravel:eloquent-relationships`
+- `laravel-transactions.md` → `laravel:transactions-and-consistency`
+- `laravel-http-client.md` → `laravel:http-client-resilience`
+- `laravel-scheduling.md` → `laravel:task-scheduling`
+- `laravel-api-resources.md` → `laravel:api-resources-and-pagination`
+- `laravel-blade-components.md` → `laravel:blade-components-and-layouts`
+- `laravel-filesystem-uploads.md` → `laravel:filesystem-uploads`
+- `laravel-rate-limiting.md` → `laravel:rate-limiting`
+- `laravel-exceptions-logging.md` → `laravel:exception-handling-and-logging`
+
 ### Skills Overview
 
 - Onboarding & Runner
diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
@@ -1,5 +1,39 @@
 # Laravel Superpowers — Release Notes
 
+## v0.1.2 (2025-11-04)
+
+Docs sweep across Laravel 11.x and 12.x, with new skills matching the intersection of stable patterns. Also consolidated duplicates and kept commands thin.
+
+### Added (Skills)
+
+- Form Requests & Validation (`laravel:form-requests`)
+- Policies & Authorization (`laravel:policies-and-authorization`)
+- Eloquent Relationships & Loading (`laravel:eloquent-relationships`)
+- Transactions & Consistency (`laravel:transactions-and-consistency`)
+- HTTP Client Resilience (`laravel:http-client-resilience`)
+- Task Scheduling (`laravel:task-scheduling`)
+- API Resources & Pagination (`laravel:api-resources-and-pagination`)
+- Blade Components & Layouts (`laravel:blade-components-and-layouts`)
+- Filesystem Uploads & URLs (`laravel:filesystem-uploads`)
+- Rate Limiting & Throttle (`laravel:rate-limiting`)
+- Exception Handling & Logging (`laravel:exception-handling-and-logging`)
+
+Matching command wrappers were added under `commands/` using the existing convention.
+
+### Changed
+
+- Unified caching guidance into `laravel:performance-caching` (added tags, locks, invalidation best‑practices). Removed the duplicate cache strategies skill/command.
+- De‑duplicated Eloquent guidance: relationships skill now references `laravel:performance-eager-loading` for N+1 detection/measurement.
+
+### Removed
+
+- Subagents that duplicated skills (Form Request Builder, Policy Planner, Transaction Auditor, API Resource Designer). The repo keeps subagents minimal; the controller cleaner remains.
+- Redundant Sail prompt skill (covered by runner selection and integration docs).
+
+### Docs
+
+- Summary of 11.x/12.x intersection captured within the new skills themselves.
+
 ## v0.1.1 (2025-11-04)
 
 Smarter Laravel detection, Sail via binary presence, and safer command guidance.
diff --git a/commands/laravel-api-resources.md b/commands/laravel-api-resources.md
@@ -0,0 +1,6 @@
+---
+description: Use API Resources and pagination; use the laravel:api-resources-and-pagination skill exactly as written
+---
+
+Use the laravel:api-resources-and-pagination skill exactly as written
+
diff --git a/commands/laravel-blade-components.md b/commands/laravel-blade-components.md
@@ -0,0 +1,6 @@
+---
+description: Compose UIs with Blade components; use the laravel:blade-components-and-layouts skill exactly as written
+---
+
+Use the laravel:blade-components-and-layouts skill exactly as written
+
diff --git a/commands/laravel-eloquent-relationships.md b/commands/laravel-eloquent-relationships.md
@@ -0,0 +1,6 @@
+---
+description: Define and load relationships efficiently; use the laravel:eloquent-relationships skill exactly as written
+---
+
+Use the laravel:eloquent-relationships skill exactly as written
+
diff --git a/commands/laravel-exceptions-logging.md b/commands/laravel-exceptions-logging.md
@@ -0,0 +1,6 @@
+---
+description: Improve observability of failures; use the laravel:exception-handling-and-logging skill exactly as written
+---
+
+Use the laravel:exception-handling-and-logging skill exactly as written
+
diff --git a/commands/laravel-filesystem-uploads.md b/commands/laravel-filesystem-uploads.md
@@ -0,0 +1,6 @@
+---
+description: Store and serve files safely; use the laravel:filesystem-uploads skill exactly as written
+---
+
+Use the laravel:filesystem-uploads skill exactly as written
+
diff --git a/commands/laravel-form-requests.md b/commands/laravel-form-requests.md
@@ -0,0 +1,6 @@
+---
+description: Extract validation to Form Requests; use the laravel:form-requests skill exactly as written
+---
+
+Use the laravel:form-requests skill exactly as written
+
diff --git a/commands/laravel-http-client.md b/commands/laravel-http-client.md
@@ -0,0 +1,6 @@
+---
+description: Harden outbound HTTP calls; use the laravel:http-client-resilience skill exactly as written
+---
+
+Use the laravel:http-client-resilience skill exactly as written
+
diff --git a/commands/laravel-policies.md b/commands/laravel-policies.md
@@ -0,0 +1,6 @@
+---
+description: Enforce access via Policies; use the laravel:policies-and-authorization skill exactly as written
+---
+
+Use the laravel:policies-and-authorization skill exactly as written
+
diff --git a/commands/laravel-rate-limiting.md b/commands/laravel-rate-limiting.md
@@ -0,0 +1,6 @@
+---
+description: Apply per-user throttle; use the laravel:rate-limiting skill exactly as written
+---
+
+Use the laravel:rate-limiting skill exactly as written
+
diff --git a/commands/laravel-scheduling.md b/commands/laravel-scheduling.md
@@ -0,0 +1,6 @@
+---
+description: Schedule tasks safely; use the laravel:task-scheduling skill exactly as written
+---
+
+Use the laravel:task-scheduling skill exactly as written
+
diff --git a/commands/laravel-transactions.md b/commands/laravel-transactions.md
@@ -0,0 +1,6 @@
+---
+description: Make multi-write flows atomic; use the laravel:transactions-and-consistency skill exactly as written
+---
+
+Use the laravel:transactions-and-consistency skill exactly as written
+
diff --git a/docs/laravel/DERIVED_PATTERNS.md b/docs/laravel/DERIVED_PATTERNS.md
@@ -0,0 +1,36 @@
+# Laravel 11.x and 12.x — Common Good Patterns (Skills Map)
+
+This document summarizes patterns present in both Laravel 11.x and 12.x documentation and maps them to skills, subagents, and commands provided by this plugin. It focuses on stable areas that change little between versions and are broadly applicable.
+
+## Core Skills (Docs Intersection)
+
+- Form Requests and Validation → `skills/form-requests-and-validation/SKILL.md`
+- Policies and Authorization → `skills/policies-and-authorization/SKILL.md`
+- Eloquent Relationships and Loading → `skills/eloquent-relationships-and-loading/SKILL.md`
+- Transactions and Consistency → `skills/transactions-and-consistency/SKILL.md`
+- HTTP Client Resilience → `skills/http-client-resilience/SKILL.md`
+- Task Scheduling → `skills/task-scheduling/SKILL.md`
+- API Resources and Pagination → `skills/api-resources-and-pagination/SKILL.md`
+- Blade Components and Layouts → `skills/blade-components-and-layouts/SKILL.md`
+- Performance Caching (with tags/locks/invalidation) → `skills/performance-caching/SKILL.md`
+- Exception Handling and Logging → `skills/exception-handling-and-logging/SKILL.md`
+- Filesystem Uploads and URLs → `skills/filesystem-uploads-and-urls/SKILL.md`
+- Rate Limiting and Throttle → `skills/rate-limiting-and-throttle/SKILL.md`
+
+These complement existing skills such as runner selection, migrations/factories, queues/Horizon, performance (eager loading, select columns, caching), and TDD.
+
+## Subagents
+
+This repo keeps subagents minimal to avoid overlap with skills. Use the existing controller-focused subagent:
+
+- Controller Cleaner → `agents/laravel-controller-cleaner.md`
+
+Other topics above are covered as skills rather than subagents.
+
+## Command Wrappers
+
+Each new skill has a matching command in `commands/` following the existing convention. For example, `commands/laravel-form-requests.md` activates `laravel:form-requests`.
+
+## Notes on Source Material
+
+The above patterns are stable across 11.x and 12.x. Version‑specific features like Pulse, MCP, or newer concurrency helpers are intentionally excluded from the intersection.
diff --git a/skills/api-resources-and-pagination/SKILL.md b/skills/api-resources-and-pagination/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: laravel:api-resources-and-pagination
+description: Use API Resources with pagination and conditional fields; keep response shapes stable and cache-friendly
+---
+
+# API Resources and Pagination
+
+Represent models via Resources; keep transport concerns out of Eloquent.
+
+## Commands
+
+```
+# Resource
+sail artisan make:resource PostResource    # or: php artisan make:resource PostResource
+
+# Controller usage
+return PostResource::collection(
+    Post::with('author')->latest()->paginate(20)
+);
+
+# Resource class
+public function toArray($request)
+{
+    return [
+        'id' => $this->id,
+        'title' => $this->title,
+        'author' => new UserResource($this->whenLoaded('author')),
+        'published_at' => optional($this->published_at)->toAtomString(),
+    ];
+}
+```
+
+## Patterns
+
+- Prefer `Resource::collection($query->paginate())` over manual arrays
+- Use `when()` / `mergeWhen()` for conditional fields
+- Keep pagination cursors/links intact for clients
+- Version resources when contracts change; avoid breaking fields silently
+
diff --git a/skills/blade-components-and-layouts/SKILL.md b/skills/blade-components-and-layouts/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: laravel:blade-components-and-layouts
+description: Compose UIs with Blade components, slots, and layouts; keep templates pure and testable
+---
+
+# Blade Components and Layouts
+
+Encapsulate markup and behavior with components; prefer slots over includes.
+
+## Commands
+
+```
+sail artisan make:component Alert              # or: php artisan make:component Alert
+
+// Use component
+<x-alert type="warning" :message="$msg" class="mb-4" />
+
+// Layouts + stacks
+@extends('layouts.app')
+@push('scripts')
+    <script>/* page script */</script>
+@endpush
+```
+
+## Patterns
+
+- Keep components dumb: pass data in, emit markup out
+- Use `merge()` to honor passed classes/attributes in components
+- Prefer named slots for readability
+- Extract small, reusable atoms rather than giant organisms
+
diff --git a/skills/eloquent-relationships-and-loading/SKILL.md b/skills/eloquent-relationships-and-loading/SKILL.md
@@ -0,0 +1,33 @@
+---
+name: laravel:eloquent-relationships
+description: Define clear relationships and load data efficiently; prevent N+1, use constraints, counts/sums, and pivot syncing safely
+---
+
+# Eloquent Relationships and Loading
+
+Model relationships express your domain; load only what you need.
+
+## Commands
+
+```
+# Typical loading
+Post::with(['author', 'tags'])->withCount('comments')->paginate(20);
+
+# Constrained eager loading
+User::with(['posts' => fn($q) => $q->latest()->where('published', true)])->find($id);
+
+# Pivot ops (many-to-many)
+$post->tags()->sync([1,2,3]);       // atomic replace
+$post->tags()->syncWithoutDetaching([4]);
+
+# Chunking large reads
+Order::where('status', 'open')->lazy()->each(fn($o) => ...);
+```
+
+## Patterns
+
+- See `laravel:performance-eager-loading` for N+1 detection and measurement
+- Use `whereHas()` / `has()` to filter by related existence
+- Prefer `withCount`, `withSum`, `withMax` for simple aggregates
+- Apply global / local scopes for recurring constraints
+- Keep relationship names consistent and pluralized where appropriate
diff --git a/skills/exception-handling-and-logging/SKILL.md b/skills/exception-handling-and-logging/SKILL.md
@@ -0,0 +1,34 @@
+---
+name: laravel:exception-handling-and-logging
+description: Use reportable/renderable exceptions, structured logs, and channel strategy for observability and graceful failures
+---
+
+# Exception Handling and Logging
+
+Treat errors as first-class signals; provide context and paths to remediation.
+
+## Commands
+
+```
+// app/Exceptions/Handler.php
+public function register(): void
+{
+    $this->reportable(function (DomainException $e) {
+        Log::warning('domain exception', ['code' => $e->getCode()]);
+    });
+
+    $this->renderable(function (ModelNotFoundException $e, $request) {
+        if ($request->expectsJson()) {
+            return response()->json(['message' => 'Not Found'], 404);
+        }
+    });
+}
+```
+
+## Patterns
+
+- Use domain-specific exceptions for expected error paths
+- Add structured context to logs; avoid logging secrets
+- Route noisy logs to separate channels; keep defaults actionable
+- Convert to API-appropriate responses in `renderable()`
+
diff --git a/skills/filesystem-uploads-and-urls/SKILL.md b/skills/filesystem-uploads-and-urls/SKILL.md
@@ -0,0 +1,28 @@
+---
+name: laravel:filesystem-uploads
+description: Store and serve files via Storage; set visibility, generate URLs, and handle streaming safely
+---
+
+# Filesystem Uploads and URLs
+
+Use the Storage facade consistently; abstract away the backend (local, S3, etc.).
+
+## Commands
+
+```
+$path = Storage::disk('public')->putFile('avatars', $request->file('avatar'));
+
+// Temporary URLs (S3, etc.)
+$url = Storage::disk('s3')->temporaryUrl($path, now()->addMinutes(10));
+
+// Streams
+return Storage::disk('backups')->download('db.sql.gz');
+```
+
+## Patterns
+
+- Keep user uploads under a dedicated disk with explicit `visibility`
+- Avoid assuming local paths; always go through Storage
+- For public assets, run `storage:link` and serve via web server / CDN
+- Validate mime/types and size limits at upload boundaries
+
diff --git a/skills/form-requests-and-validation/SKILL.md b/skills/form-requests-and-validation/SKILL.md
diff --git a/skills/http-client-resilience/SKILL.md b/skills/http-client-resilience/SKILL.md
diff --git a/skills/performance-caching/SKILL.md b/skills/performance-caching/SKILL.md
diff --git a/skills/policies-and-authorization/SKILL.md b/skills/policies-and-authorization/SKILL.md
diff --git a/skills/rate-limiting-and-throttle/SKILL.md b/skills/rate-limiting-and-throttle/SKILL.md
diff --git a/skills/task-scheduling/SKILL.md b/skills/task-scheduling/SKILL.md
diff --git a/skills/transactions-and-consistency/SKILL.md b/skills/transactions-and-consistency/SKILL.md

-Original file line number
+Diff line change
@@ @@ -0,0 +1,6 @@ @@
 +---
 +description: Use API Resources and pagination; use the laravel:api-resources-and-pagination skill exactly as written
 +---
++
 +Use the laravel:api-resources-and-pagination skill exactly as written
++