@mohammadhprp/system-prompt 0.12.2 → 0.12.3

package/framework/commands/README.md

@@ -14,7 +14,7 @@ Commands define repeatable workflows that agents execute on demand, triggered by
 | [`/pr`](./pr.md) | Create a GitHub PR for the current branch. | pull-requests standard |
 | [`/mr`](./mr.md) | Create a GitLab MR for the current branch. | pull-requests standard |
 | [`/release`](./release.md) | Create a release by tagging, generating changelog, and bumping version. | — |
-| [`/review`](./review.md) | Perform comprehensive code quality review. | code-review skill, naming/testing/security/performance standards |
+| [`/review`](./review.md) | Perform comprehensive code quality review. | naming/testing/security/performance standards |
 | [`/summarize-changes`](./summarize-changes.md) | Summarize uncommitted changes and flag risky patterns. | — |
 
 ## Command Entry Structure

package/framework/commands/review.md

@@ -9,7 +9,7 @@ Perform comprehensive code quality review.
 
 ## Process
 
-1. **Review conversation and diff** - Read conversation history, run `git diff` for staged/unstaged changes, identify the problem being solved and the behavior being modified. Load [`skills/code-review/SKILL.md`](../skills/code-review/SKILL.md) and related standards: [`references/standards/naming.md`](../references/standards/naming.md), [`references/standards/testing.md`](../references/standards/testing.md), [`references/standards/security.md`](../references/standards/security.md), [`references/standards/performance.md`](../references/standards/performance.md).
+1. **Review conversation and diff** - Read conversation history, run `git diff` for staged/unstaged changes, identify the problem being solved and the behavior being modified. Read related standards: [`references/standards/naming.md`](../references/standards/naming.md), [`references/standards/testing.md`](../references/standards/testing.md), [`references/standards/security.md`](../references/standards/security.md), [`references/standards/performance.md`](../references/standards/performance.md).
 
 2. **Check correctness** - Edge cases, concurrency, error handling, state transitions, backward compatibility. Read contracts and interfaces before implementation.
 

package/framework/mcps/README.md

@@ -11,7 +11,6 @@ This catalog is framework-agnostic: each entry documents what the server does, w
 | [Excalidraw MCP](./excalidraw/README.md) | Stream hand-drawn Excalidraw diagrams with interactive fullscreen editing — architecture diagrams, flowcharts, wireframes. | Any project that benefits from visual diagrams, architecture visualization, or design sketching. |
 | [Figma MCP Go](./figma-mcp-go/README.md) | Full read/write access to Figma designs via plugin bridge — no API token or rate limits. | Any project that works with Figma designs. |
 | [Laravel Boost](./laravel-boost/README.md) | Gives AI agents Laravel application context, Laravel ecosystem documentation search, and safe local inspection tools. | Laravel applications. |
-| [Notion MCP](./notion-mcp/README.md) | Search, read, and write content in a Notion workspace — pages, databases, views, comments, and more via remote HTTP MCP. | Any project that uses Notion for documentation, tracking, or collaboration. |
 | [Playwright MCP](./playwright-mcp/README.md) | Cross-browser automation via accessibility snapshots — navigate, click, type, screenshot, evaluate, network control, storage management. | Any project needing browser automation or end-to-end testing. |
 | [Supabase MCP](./supabase-mcp/README.md) | Manage Supabase projects, query databases, design schema, run migrations, deploy Edge Functions, manage Auth/Storage/Realtime, and search docs. | Any project using Supabase as backend. |
 

package/framework/plugins/ponytail/README.md

@@ -39,6 +39,5 @@ Avoid when the task explicitly needs complex scaffolding, heavy abstractions, or
 
 Relevant skills in this repository:
 
-- [`code-review`](../../skills/code-review/SKILL.md): review backend changes for correctness and maintainability, complementary to ponytail's over-engineering focus.
 - [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for refactoring and behavior-preserving cleanup.
 - [`pr`](../../commands/pr.md): prepare small, reviewable changes aligned with ponytail's minimal-diff philosophy.

package/framework/plugins/ponytail/capabilities.md

@@ -90,7 +90,7 @@ Or in `~/.config/ponytail/config.json` (`%APPDATA%\ponytail\config.json` on Wind
 - Use `/ponytail-review` after a coding session to catch over-engineering the agent missed.
 - Mark intentional shortcuts with `ponytail:` comments naming the ceiling and upgrade path.
 - Review `/ponytail-debt` regularly to track deferred improvements.
-- Pair with `code-review` and the `/pr` command for a complete quality workflow.
+- Pair with the `/pr` command for a complete quality workflow.
 
 ## Common Workflows
 

package/framework/references/standards/api.md

@@ -39,5 +39,4 @@ Define reusable backend engineering rules for API decisions across projects. Thi
 
 ## Related Skills
 
-- `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/api-design.md`

package/framework/references/standards/architecture.md

@@ -38,5 +38,4 @@ Define reusable backend engineering rules for architecture decisions across proj
 
 ## Related Skills
 
-- `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/architecture-review.md`

package/framework/references/standards/database.md

@@ -38,5 +38,4 @@ Define reusable backend engineering rules for database decisions across projects
 
 ## Related Skills
 
-- `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/database-design.md`

package/framework/references/standards/debugging.md

@@ -39,5 +39,4 @@ Define reusable backend engineering rules for debugging decisions across project
 
 ## Related Skills
 
-- `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/debugging.md`

package/framework/references/standards/documentation.md

@@ -38,4 +38,3 @@ Define reusable backend engineering rules for documentation decisions across pro
 
 ## Related Skills
 
-- `skills/code-review/SKILL.md`

package/framework/references/standards/logging.md

@@ -38,5 +38,4 @@ Define reusable backend engineering rules for logging decisions across projects.
 
 ## Related Skills
 
-- `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/observability.md`

package/framework/references/standards/naming.md

@@ -38,5 +38,4 @@ Define reusable backend engineering rules for naming decisions across projects.
 
 ## Related Skills
 
-- `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/refactoring.md`

package/framework/references/standards/observability.md

@@ -38,5 +38,4 @@ Define reusable backend engineering rules for observability decisions across pro
 
 ## Related Skills
 
-- `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/observability.md`

package/framework/references/standards/performance.md

@@ -38,5 +38,4 @@ Define reusable backend engineering rules for performance decisions across proje
 
 ## Related Skills
 
-- `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/performance.md`

package/framework/references/standards/pull-requests.md

@@ -38,5 +38,4 @@ Define reusable backend engineering rules for pull request decisions across proj
 
 ## Related Skills
 
-- `skills/code-review/SKILL.md`
 - `commands/pr.md`

package/framework/references/standards/security.md

@@ -38,5 +38,4 @@ Define reusable backend engineering rules for security decisions across projects
 
 ## Related Skills
 
-- `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/security.md`

package/framework/references/standards/testing.md

@@ -38,5 +38,4 @@ Define reusable backend engineering rules for testing decisions across projects.
 
 ## Related Skills
 
-- `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/testing.md`

package/framework/skills/README.md

@@ -10,34 +10,23 @@ This catalog is framework-agnostic: each skill defines when to activate, a step-
 | --- | --- | --- |
 | [agent-browser](./agent-browser/SKILL.md) | Automate browser and Electron workflows for navigation, testing, screenshots, and data extraction. | Website interaction, browser automation, exploratory testing, QA, and Electron desktop app workflows. |
 | [backend-best-practices](./backend-best-practices/SKILL.md) | Consolidated backend engineering practices for API design, architecture, data, security, testing, observability, performance, debugging, and refactoring. | Any backend task that benefits from structured domain guidance across multiple backend disciplines. |
-| [brainstorming](./brainstorming/SKILL.md) | Turn ideas into fully formed designs and specs through collaborative dialogue before any implementation. | Starting a new feature, component, or project; any work that benefits from design before code. |
-| [code-review](./code-review/SKILL.md) | Review backend changes for correctness, readability, maintainability, tests, performance, and security. | Reviewing pull requests, evaluating code quality, or mentoring. |
-| [codenavi](./codenavi/SKILL.md) | Investigate unfamiliar codebases with precision, implement surgically, and keep a `.notebook/` knowledge base that grows across sessions. | Fixing bugs, implementing features, refactoring, or investigating flows in unfamiliar territory. |
-| [create-adr](./create-adr/SKILL.md) | Create Architecture Decision Records (ADRs) that capture the context, decision, and consequences of significant architectural choices. | Documenting a finalized technical decision, or recording why a choice was made for future team members. |
-| [design-like-damien](./design/SKILL.md) | Apply premium, editorial-quality UI design philosophy and Lovable prompting system to produce interfaces that never look “AI-generated.” | Building apps, landing pages, or dashboards in Lovable; UI/UX design for premium SaaS, dark mode, typography, and scroll animations. |
 | [diagram-design](./diagram-design/SKILL.md) | Create technical and product diagrams as standalone HTML files with inline SVG and an opinionated editorial design system. | Architecture, data, process, and other diagrams that communicate more clearly than prose or tables. |
 | [docs-writer](./docs-writer/SKILL.md) | Write, review, and edit documentation files with consistent structure, tone, and technical accuracy. | Creating docs, reviewing markdown files, writing READMEs, or updating `/docs` directories. |
 | [effective-html](./effective-html/SKILL.md) | Create self-contained HTML artifacts with routed guidance for design, wireframes, prototypes, plans, and diagrams. | Standalone HTML reports, explainers, interfaces, wireframes, prototypes, plans, and diagrams. |
 | [find-skills](./find-skills/SKILL.md) | Discover, evaluate, and install skills from the open agent skills ecosystem. | Finding an installable skill for a specialized task or extending an agent's capabilities. |
 | [frontend-design](./frontend-design/SKILL.md) | Distinctive, intentional visual design for new UI or reshaping existing UI — aesthetic direction, typography, and choices that don't read as templated defaults. | Building new interfaces, reshaping existing UI, or escaping generic AI-generated design looks. |
 | [glab](./glab/SKILL.md) | Use the GitLab CLI (glab) to manage merge requests, issues, pipelines, and repositories from the command line. | Any project hosted on GitLab (SaaS or self-hosted). |
-| [great-interface](./great-interface/SKILL.md) | Build, explain, review, and refine product interfaces across accessibility, layout, writing, typography, color, and UI polish. | Creating frontend interfaces, reviewing interface quality, explaining interface behavior, or comparing UI directions. |
 | [humanizer](./humanizer/SKILL.md) | Remove signs of AI-generated writing from text — inflated importance, promotional language, em dash overuse, rule of three, AI vocabulary, and filler phrases. | Editing or reviewing prose to make it sound more natural and human-written. |
 | [improve](./improve/SKILL.md) | Audit repositories as a read-only senior advisor and produce prioritized implementation plans for another agent. | Repository-wide audits, improvement roadmaps, and implementation handoffs. |
 | [jira-cli](./jira-cli/SKILL.md) | Use the Jira CLI (jira) to manage issues, sprints, epics, comments, transitions, and worklogs from the command line. | Any project using Jira (Cloud or self-hosted) for issue tracking. |
 | [laravel-best-practices](./laravel-best-practices/SKILL.md) | Apply Laravel PHP patterns for Eloquent, validation, security, testing, caching, and architecture. | Writing, reviewing, or refactoring Laravel PHP code. |
-| [learning-opportunities](./learning-opportunities/SKILL.md) | Facilitate deliberate skill development during AI-assisted coding with short, optional interactive exercises. | After architectural work, schema changes, refactors, or when the user asks to understand code better. |
-| [notion-mcp](./notion-mcp/SKILL.md) | Work with the Notion MCP server tools for pages, databases, comments, search, and workspace management. | Any project that uses Notion for documentation, tracking, or collaboration. |
 | [perf-web-optimization](./perf-web-optimization/SKILL.md) | Optimize web performance: bundle size, images, caching, lazy loading, and overall page speed. | A slow site, large bundles, layout shifts, poor Time to Interactive, or low Lighthouse scores. |
 | [security-best-practices](./security-best-practices/SKILL.md) | Perform language- and framework-specific security best-practice reviews and suggest improvements, with support for Python, JavaScript/TypeScript, and Go. | Explicit security reviews or reports, secure-by-default coding, or auditing existing code for major vulnerabilities. |
 | [sentry](./sentry/SKILL.md) | Inspect Sentry issues, summarize production errors, and pull health data via the Sentry API (read-only). | Checking production errors, summarizing recent crashes, or pulling a production error report. |
 | [show-me](./show-me/SKILL.md) | Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts. | Explaining logic, control flow, UI structure, file responsibility, or data flow with the smallest useful visual. |
 | [skill-creator](./skill-creator/SKILL.md) | Create new skills, modify and improve existing skills, and measure skill performance. | Designing new skills, optimizing existing skills, or running evals. |
-| [spec-driven-eval](./spec-driven-eval/SKILL.md) | Score how completely an implementation fulfills a PRD/spec, case by case, producing a single comparable final grade. | Benchmarking spec-driven implementations, grading acceptance criteria, or auditing implementation and test coverage against a spec. |
-| [technical-design-doc-creator](./technical-design-doc-creator/SKILL.md) | Create comprehensive Technical Design Documents (TDDs) with mandatory and optional sections through interactive discovery, in the user's language. | Writing a design doc, TDD, technical spec, or architecture document before implementing a significant change. |
 | [tlc-spec-driven](./tlc-spec-driven/SKILL.md) | Feature planning and implementation with adaptive phases, EARS testable requirements, atomic Conventional Commits, and independent verification. | Planning features, implementing with verification and atomic commits, or validating an implementation against a spec. |
 | [taste](./taste/SKILL.md) | Unified design-quality skill spanning anti-slop frontend design, image generation and image-to-code, brand kits, minimalist and industrial UI, redesigns, and Google Stitch design systems. | Landing pages, portfolios, redesigns, website/mobile/brand imagery, or any UI that must not look AI-generated. |
-| [web-design-guidelines](./web-design-guidelines/SKILL.md) | Review UI code for Web Interface Guidelines compliance — accessibility, focus, forms, animation, typography, and interaction patterns. | Reviewing UI, checking accessibility, auditing design or UX, or checking a site against best practices. |
 
 ## How Skills Are Organized
 
@@ -60,7 +49,7 @@ Use the skill table above to find the entry closest to the task at hand. Skills
 Before activating a skill, check:
 
 - **Fit**: does the skill's purpose match the current task?
-- **Scope**: some skills are general (CodeNavi), others are narrow (Laravel Best Practices).
+- **Scope**: some skills are general, others are narrow (Laravel Best Practices).
 - **Combination**: complex tasks may need multiple skills (e.g., API Design + Security + Testing).
 - **Sequence**: some skills are best used in order (e.g., Architecture Review before Database Design).
 

package/framework/skills/improve/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: improve
-description: Audit an entire repository as a read-only senior advisor, identify evidence-backed bugs, security risks, performance issues, test gaps, technical debt, DX/docs problems, and grounded roadmap opportunities, then produce prioritized handoff plans for another agent. Use for repository-wide audits, improvement roadmaps, and implementation planning from existing code. Do not use for reviewing a specific diff or pull request (use code-review), security-only audits (use security-best-practices), documentation-only edits (use docs-writer), greenfield feature design or implementation (use brainstorming or tlc-spec-driven), or creating and evaluating agent skills (use skill-creator).
+description: Audit an entire repository as a read-only senior advisor, identify evidence-backed bugs, security risks, performance issues, test gaps, technical debt, DX/docs problems, and grounded roadmap opportunities, then produce prioritized handoff plans for another agent. Use for repository-wide audits, improvement roadmaps, and implementation planning from existing code. Do not use for reviewing a specific diff or pull request, security-only audits (use security-best-practices), documentation-only edits (use docs-writer), greenfield feature design or implementation (use tlc-spec-driven), or creating and evaluating agent skills (use skill-creator).
 license: MIT
 metadata:
   author: shadcn
@@ -28,10 +28,8 @@ The economics of this skill: an expensive, high-ceiling model does the part wher
 
 Use this skill when the user wants a broad assessment of an existing repository or wants possible improvements prioritized across multiple engineering concerns. Keep the audit advisory and read-only; implementation belongs to a separate executor or to the skill that owns the narrower task.
 
-- Review a specific diff, branch, or pull request with `code-review`.
 - Perform a security-only assessment with `security-best-practices`.
 - Edit or restructure documentation with `docs-writer`.
-- Explore an unresolved product or UI direction with `brainstorming`.
 - Specify or implement an approved feature with `tlc-spec-driven`.
 - Create, evaluate, or optimize an agent skill with `skill-creator`.
 

package/framework/skills/improve/examples.md

@@ -16,4 +16,4 @@
 
 **User:** Review the changes in my pull request for authorization bugs and missing tests.
 
-**Expected behavior:** Do not use `improve` for this narrow diff review. Route the request to `code-review`, optionally combining it with `security-best-practices` when a security-only review is explicitly requested.
+**Expected behavior:** Do not use `improve` for this narrow diff review. Decline the broad audit and review the pull request directly, combining it with `security-best-practices` when a security-only review is explicitly requested.

package/framework/skills/laravel-best-practices/SKILL.md

@@ -1,229 +1,69 @@
 ---
 name: laravel-best-practices
-description: "Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code."
-version: 0.1.0
+description: "Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns."
+license: MIT
+metadata:
+  author: laravel
 ---
 
 # Laravel Best Practices
 
-Best practices for Laravel, prioritized by impact. Each rule teaches what to do and why. For exact API syntax, verify with `search-docs`.
+Best practices for Laravel, organized as an index of reference files. Each reference file teaches what to do and why. For exact API syntax, verify with `search-docs`.
 
 ## Consistency First
 
-Before applying any rule, check what the application already does. Laravel offers multiple valid approaches — the best choice is the one the codebase already uses, even if another pattern would be theoretically better. Inconsistency is worse than a suboptimal pattern.
+Before applying any reference, check what the application already does. Laravel offers multiple valid approaches, and the best choice is the one the codebase already uses, even if another pattern would be theoretically better. Inconsistency is worse than a suboptimal pattern.
 
-Check sibling files, related controllers, models, or tests for established patterns. If one exists, follow it — don't introduce a second way. These rules are defaults for when no pattern exists yet, not overrides.
-
-## Quick Reference
-
-### 1. Database Performance → `references/db-performance.md`
-
-- Eager load with `with()` to prevent N+1 queries
-- Enable `Model::preventLazyLoading()` in development
-- Select only needed columns, avoid `SELECT *`
-- `chunk()` / `chunkById()` for large datasets
-- Index columns used in `WHERE`, `ORDER BY`, `JOIN`
-- `withCount()` instead of loading relations to count
-- `cursor()` for memory-efficient read-only iteration
-- Never query in Blade templates
-
-### 2. Advanced Query Patterns → `references/advanced-queries.md`
-
-- `addSelect()` subqueries over eager-loading entire has-many for a single value
-- Dynamic relationships via subquery FK + `belongsTo`
-- Conditional aggregates (`CASE WHEN` in `selectRaw`) over multiple count queries
-- `setRelation()` to prevent circular N+1 queries
-- `whereIn` + `pluck()` over `whereHas` for better index usage
-- Two simple queries can beat one complex query
-- Compound indexes matching `orderBy` column order
-- Correlated subqueries in `orderBy` for has-many sorting (avoid joins)
-
-### 3. Security → `references/security.md`, `references/passport.md`, `references/spatie-laravel-permission.md`
-
-- Define `$fillable` or `$guarded` on every model, authorize every action via policies or gates
-- No raw SQL with user input — use Eloquent or query builder
-- `{{ }}` for output escaping, `@csrf` on all POST/PUT/DELETE forms, `throttle` on auth and API routes
-- Validate MIME type, extension, and size for file uploads
-- Never commit `.env`, use `config()` for secrets, `encrypted` cast for sensitive DB fields
-
-### 4. Caching → `references/caching.md`
-
-- `Cache::remember()` over manual get/put
-- `Cache::flexible()` for stale-while-revalidate on high-traffic data
-- `Cache::memo()` to avoid redundant cache hits within a request
-- Cache tags to invalidate related groups
-- `Cache::add()` for atomic conditional writes
-- `once()` to memoize per-request or per-object lifetime
-- `Cache::lock()` / `lockForUpdate()` for race conditions
-- Failover cache stores in production
-
-### 5. Eloquent Patterns → `references/eloquent.md`
-
-- Correct relationship types with return type hints
-- Local scopes for reusable query constraints
-- Global scopes sparingly — document their existence
-- Attribute casts in the `casts()` method
-- Cast date columns, use Carbon instances in templates
-- `whereBelongsTo($model)` for cleaner queries
-- Never hardcode table names — use `(new Model)->getTable()` or Eloquent queries
-
-### 6. Validation & Forms → `references/validation.md`
-
-- Form Request classes, not inline validation
-- Array notation `['required', 'email']` for new code; follow existing convention
-- `$request->validated()` only — never `$request->all()`
-- `Rule::when()` for conditional validation
-- `after()` instead of `withValidator()`
-
-### 7. Configuration → `references/config.md`
-
-- `env()` only inside config files
-- `App::environment()` or `app()->isProduction()`
-- Config, lang files, and constants over hardcoded text
-
-### 8. Testing Patterns → `references/testing.md`, `references/pest-testing.md`
-
-- `LazilyRefreshDatabase` over `RefreshDatabase` for speed
-- `assertModelExists()` over raw `assertDatabaseHas()`
-- Factory states and sequences over manual overrides
-- Use fakes (`Event::fake()`, `Exceptions::fake()`, etc.) — but always after factory setup, not before
-- `recycle()` to share relationship instances across factories
-
-### 9. Queue & Job Patterns → `references/queue-jobs.md`
-
-- `retry_after` must exceed job `timeout`; use exponential backoff `[1, 5, 10]`
-- `ShouldBeUnique` to prevent duplicates; `ShouldBeUniqueUntilProcessing` for early lock release
-- Always implement `failed()`; with `retryUntil()`, set `$tries = 0`
-- `RateLimited` middleware for external API calls; `Bus::batch()` for related jobs
-- Horizon for complex multi-queue scenarios
-
-### 10. Routing & Controllers → `references/routing.md`
-
-- Implicit route model binding
-- Scoped bindings for nested resources
-- `Route::resource()` or `apiResource()`
-- Methods under 10 lines — extract to actions/services
-- Type-hint Form Requests for auto-validation
-
-### 11. HTTP Client → `references/http-client.md`
-
-- Explicit `timeout` and `connectTimeout` on every request
-- `retry()` with exponential backoff for external APIs
-- Check response status or use `throw()`
-- `Http::pool()` for concurrent independent requests
-- `Http::fake()` and `preventStrayRequests()` in tests
-
-### 12. Events, Notifications & Mail → `references/events-notifications.md`, `references/mail.md`
-
-- Event discovery over manual registration; `event:cache` in production
-- `ShouldDispatchAfterCommit` / `afterCommit()` inside transactions
-- Queue notifications and mailables with `ShouldQueue`
-- On-demand notifications for non-user recipients
-- `HasLocalePreference` on notifiable models
-- `assertQueued()` not `assertSent()` for queued mailables
-- Markdown mailables for transactional emails
-
-### 13. Error Handling → `references/error-handling.md`
-
-- `report()`/`render()` on exception classes or in `bootstrap/app.php` — follow existing pattern
-- `ShouldntReport` for exceptions that should never log
-- Throttle high-volume exceptions to protect log sinks
-- `dontReportDuplicates()` for multi-catch scenarios
-- Force JSON rendering for API routes
-- Structured context via `context()` on exception classes
-
-### 14. Task Scheduling → `references/scheduling.md`
-
-- `withoutOverlapping()` on variable-duration tasks
-- `onOneServer()` on multi-server deployments
-- `runInBackground()` for concurrent long tasks
-- `environments()` to restrict to appropriate environments
-- `takeUntilTimeout()` for time-bounded processing
-- Schedule groups for shared configuration
-
-### 15. Architecture → `references/architecture.md`
-
-- Single-purpose Action classes; dependency injection over `app()` helper
-- Prefer official Laravel packages and follow conventions, don't override defaults
-- Default to `ORDER BY id DESC` or `created_at DESC`; `mb_*` for UTF-8 safety
-- `defer()` for post-response work; `Context` for request-scoped data; `Concurrency::run()` for parallel execution
-
-### 16. Migrations → `references/migrations.md`
-
-- Generate migrations with `php artisan make:migration`
-- `constrained()` for foreign keys
-- Never modify migrations that have run in production
-- Add indexes in the migration, not as an afterthought
-- Mirror column defaults in model `$attributes`
-- Reversible `down()` by default; forward-fix migrations for intentionally irreversible changes
-- One concern per migration — never mix DDL and DML
-
-### 17. Collections → `references/collections.md`
-
-- Higher-order messages for simple collection operations
-- `cursor()` vs. `lazy()` — choose based on relationship needs
-- `lazyById()` when updating records while iterating
-- `toQuery()` for bulk operations on collections
-
-### 18. Blade & Views → `references/blade-views.md`, `references/tailwindcss.md`
-
-- `$attributes->merge()` in component templates
-- Blade components over `@include`; `@pushOnce` for per-component scripts
-- View Composers for shared view data
-- `@aware` for deeply nested component props
-
-### 19. Conventions & Style → `references/style.md`
-
-- Follow Laravel naming conventions for all entities
-- Prefer Laravel helpers (`Str`, `Arr`, `Number`, `Uri`, `Str::of()`, `$request->string()`) over raw PHP functions
-- No JS/CSS in Blade, no HTML in PHP classes
-- Code should be readable; comments only for config files
-
-### 20. Feature Flags → `references/pennant.md`
-
-- `Feature::define()` to define features with resolver callbacks
-- `Feature::active()` / `@feature` Blade directive to check features
-- Scope features to specific users/entities with `Feature::for()`
-- `Feature::activate()` / `deactivate()` for runtime control
-
-### 21. Monitoring → `references/pulse.md`
-
-- Gate-protect the dashboard with `viewPulse` gate
-- Configure built-in recorders in `config/pulse.php` (SlowQueries, SlowRequests, Exceptions, Queues, etc.)
-- Redis ingest for production performance; run `pulse:work` to drain the stream
-- Custom cards via Livewire components extending `Pulse\Card`
-- `Pulse::filter()` to exclude entries; `Pulse::resolveAuthenticatedUserId()` for multi-model apps
-- `pulse:check` daemon required for Servers card
-
-### 22. Full-Text Search → `references/scout.md`
-
-- Add `Searchable` trait to models for automatic index sync
-- Choose engine: Database, Collection, Algolia, Meilisearch, Typesense
-- `toSearchableArray()` to control indexed data; `searchableAs()` for custom index names
-- `Model::search('query')->where(...)->paginate()` for search queries
-- `scout:import` / `scout:flush` for index management; `scout:sync-index-settings` for engine config
-- `Model::withoutSyncingToSearch()` / `SCOUT_DRIVER=null` for testing
-
-### 23. Backup → `references/spatie-laravel-backup.md`
-
-- Schedule `backup:run`, `backup:clean`, `backup:monitor` in console kernel
-- Configure sources, destinations, notifications in `config/backup.php`
-- Custom cleanup strategies extending `CleanupStrategy`
-- Custom health checks extending `HealthCheck`
-- Enable encryption and Gzip compression via config
-
-### 24. Media Library → `references/spatie-medialibrary.md`
-
-- Implement `HasMedia` interface + `InteractsWithMedia` trait on models
-- `addMedia()` / `addMediaFromRequest()` for file uploads
-- Media collections to organize related files per model
-- Conversions for image processing (thumbnails, crops, etc.)
-- Responsive images via conversion `withResponsiveImages()`
+Check sibling files, related controllers, models, or tests for established patterns. If one exists, follow it. Don't introduce a second way. These references are defaults for when no pattern exists yet, not overrides.
 
 ## How to Apply
 
-Always use a sub-agent to read rule files and explore this skill's content.
-
-1. Identify the file type and select relevant sections (e.g., migration → §16, controller → §1, §3, §5, §6, §10)
-2. Check sibling files for existing patterns — follow those first per Consistency First
-3. Verify API syntax with `search-docs` for the installed Laravel version
+1. Check the changed files, nearby code, project configuration, and relevant tests for established patterns. Deviate only for a correctness or security defect, and call the deviation out.
+2. Map every affected concern to the reference index below. Read each mapped reference file before editing. Skip unrelated reference files.
+3. Make the smallest coherent change. Keep the application's architecture and naming instead of introducing a second pattern for the same job.
+4. Verify version-sensitive Laravel APIs for the installed version with `search-docs`, or inspect the installed framework when it is unavailable.
+5. Run the narrowest relevant tests first, then the project's formatting and static-analysis checks when the change warrants them.
+6. Re-read the diff against every mapped reference before finishing.
+
+## References Index
+
+Cross-cutting changes often need more than one reference file.
+
+| Concern | Read |
+| --- | --- |
+| Query count, eager loading, indexes, large datasets | [`references/db-performance.md`](references/db-performance.md) |
+| Production monitoring, slow queries, exception dashboards | [`references/pulse.md`](references/pulse.md) |
+| Subqueries, aggregates, complex ordering and query plans | [`references/advanced-queries.md`](references/advanced-queries.md) |
+| Models, relationships, scopes, casts | [`references/eloquent.md`](references/eloquent.md) |
+| Full-text search, indexing, searchable models | [`references/scout.md`](references/scout.md) |
+| Authentication, authorization, input safety, secrets, uploads | [`references/security.md`](references/security.md) |
+| OAuth2 servers, clients, token authentication | [`references/passport.md`](references/passport.md) |
+| Roles and permissions with spatie/laravel-permission | [`references/spatie-laravel-permission.md`](references/spatie-laravel-permission.md) |
+| Model media uploads, conversions, responsive images | [`references/spatie-medialibrary.md`](references/spatie-medialibrary.md) |
+| Form Requests and validation references | [`references/validation.md`](references/validation.md) |
+| Controllers, route binding, resources, middleware | [`references/routing.md`](references/routing.md) |
+| Schema changes, columns, foreign keys, indexes | [`references/migrations.md`](references/migrations.md) |
+| Jobs, retries, uniqueness, batches, Horizon | [`references/queue-jobs.md`](references/queue-jobs.md) |
+| Cache lifetime, invalidation, locks, memoization | [`references/caching.md`](references/caching.md) |
+| Outbound requests, retries, timeouts, fakes | [`references/http-client.md`](references/http-client.md) |
+| Exceptions, reporting, rendering, log context | [`references/error-handling.md`](references/error-handling.md) |
+| Events and notifications | [`references/events-notifications.md`](references/events-notifications.md) |
+| Mailables and mail assertions | [`references/mail.md`](references/mail.md) |
+| Scheduled tasks and overlap protection | [`references/scheduling.md`](references/scheduling.md) |
+| Database backups, cleanup, monitoring, notifications | [`references/spatie-laravel-backup.md`](references/spatie-laravel-backup.md) |
+| Collections, lazy iteration, bulk operations | [`references/collections.md`](references/collections.md) |
+| Blade components, attributes, composers | [`references/blade-views.md`](references/blade-views.md) |
+| Tailwind CSS classes, v4 configuration, extraction | [`references/tailwindcss.md`](references/tailwindcss.md) |
+| Environment values and application configuration | [`references/config.md`](references/config.md) |
+| Feature flags and per-user feature checks | [`references/pennant.md`](references/pennant.md) |
+| Pest/PHPUnit patterns, factories, fakes | [`references/testing.md`](references/testing.md) |
+| Pest 4 syntax, datasets, browser and architecture tests | [`references/pest-testing.md`](references/pest-testing.md) |
+| Naming, helpers, file boundaries, PHP style | [`references/style.md`](references/style.md) |
+| Actions, services, dependencies, application structure | [`references/architecture.md`](references/architecture.md) |
+| Detecting and recording this app's conventions as rules | [`references/infer-conventions.md`](references/infer-conventions.md) |
+
+## Decision rule
+
+- Prefer framework features and existing application abstractions over new helpers or dependencies.
+- Avoid speculative abstractions. Extract code when it creates a clear domain boundary, removes meaningful duplication, or makes behavior independently testable.
+- Keep database access out of Blade views and prevent hidden N+1 queries across controllers, resources, jobs, and serialization.

package/framework/skills/laravel-best-practices/references/architecture.md

@@ -9,7 +9,7 @@ class CreateOrderAction
 {
     public function __construct(private InventoryService $inventory) {}
 
-    public function execute(array $data): Order
+    public function handle(array $data): Order
     {
         $order = Order::create($data);
         $this->inventory->reserve($order);