{"id":"d5f19517-991e-4bc5-8848-7054a3cfd80c","slug":"pekral-cursor-rules","kind":"skill","name":"cursor-rules","summary":"PHP and Laravel Cursor rules — coding standards, testing, and conventions for the Cursor editor. Install via Composer.","owner":"pekral","repoUrl":"https://github.com/pekral/cursor-rules","license":"MIT","licenseTier":"permissive","trust":"community","stars":11,"match":null,"fewStars":false,"format":"skill","createdAt":null,"addedAt":"2026-10-14T06:09:25.672Z","logoUrl":"https://avatars.githubusercontent.com/u/9308589?u=b2b7806e190c0082b0ae80340bcb99dcbb248fa7&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["cursor-rules","laravel","php","ai","claude-code","coding-standards","composer-plugin","cursor"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T07:30:09.053Z","sample":false,"url":"https://conduits.dev/tools/pekral-cursor-rules","language":"PHP","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"

\n \"Cursor\n

\n\n# Cursor Rules for PHP and Laravel — Composer Plugin\n\n

\n \"Packagist\n \"Total\n \"PHP\n \"License\"\n \"by\n

\n\n**Cursor rules for PHP and Laravel** — a **Composer plugin** for PHP/Laravel projects that installs a complete set of `.mdc` rule files and Agent skills for Cursor, Claude Code, and Codex. One package for PHP and Laravel cursor rules: coding standards, testing, and conventions. The installer discovers the project root (via `composer.json` lookup from the current directory), mirrors the `rules/` directory into the editor's rules path and the `skills/` directory into the editor's skills path, and copies or symlinks every file into the target project. Use cursor rules for PHP and Laravel to keep every edit aligned with enforced standards, plus comprehensive Agent skills for issue resolution, bug fixing, code review, security analysis, refactoring, testing, frontend and UI, platform and data, and package review.\n\n## Why This Package\n\n- a Composer plugin: PHP/Laravel cursor rules + agent skills in one `composer require --dev` package\n- unified PHP coding guidelines for PHP 8.4 projects\n- Pest-based testing with mandatory code analysis and 100% coverage\n- strong focus on clean code: typed properties, SRP, no redundant comments\n- **62 comprehensive Agent skills** for automated workflows (v0.9.1)\n- fast onboarding inside development repositories\n\n## Installation\n\n```bash\ncomposer require pekral/cursor-rules --dev\nvendor/bin/cursor-rules install --editor=cursor\n```\n\nThe `--editor` flag is **required**. Use it to choose the target agent:\n\n- **cursor**: `.cursor/rules`, `.cursor/skills`\n- **claude**: `.claude/rules`, `.claude/skills`, and when `HOME`/`USERPROFILE` is set also `~/.claude/skills`\n- **codex**: `.codex/rules`, `.codex/skills`, and when `HOME`/`USERPROFILE` is set also `~/.codex/skills`\n- **all**: all of the above (Cursor, Claude, Codex in project + home)\n\n### Editor compatibility\n\n| Feature | Cursor | Claude | Codex |\n|---------|--------|--------|-------|\n| Rules | ✅ | ✅ | experimental / unverified |\n| Skills | ✅ | ✅ | ✅ |\n\nCodex rules support is listed as experimental / unverified — the installer copies the files into `.codex/rules`, but native rule loading by Codex has not been confirmed; report your findings in [#663](https://github.com/pekral/cursor-rules/issues/663).\n\nWhen the package is required via Composer, sources are read from `vendor/pekral/cursor-rules/rules` and `vendor/pekral/cursor-rules/skills`.\n\n**Important:** By default, the installer only copies missing files and keeps existing content untouched. Use the `--force` flag to overwrite existing files: `vendor/bin/cursor-rules install --force`. This is particularly useful when you want to update rules to their latest versions or when you've made local changes that should be replaced. The file `.cursor/rules/project.mdc` and `CLAUDE.md` are never overwritten once they exist in the target project, so you can safely customize them.\n\n### Automatic Installation via Composer Plugin\n\nBy default, the Composer plugin does **not** auto-install rules on `composer install` or `composer update`. To enable automatic installation, add the following to your project's `composer.json`:\n\n```json\n{\n \"extra\": {\n \"cursor-rules\": {\n \"auto-install\": true,\n \"editor\": \"claude\"\n }\n }\n}\n```\n\n| Option | Description | Default |\n|----------------|----------------------------------------------------------|-----------|\n| `auto-install` | Enable automatic install on `composer install/update`. | `false` |\n| `editor` | Target editor for auto-install (`cursor`, `claude`, `codex`, `all`). | `cursor` |\n\nIf you prefer manual control, simply call `vendor/bin/cursor-rules install` in your Composer `post-update-cmd` scripts with the desired flags.\n\n### Installing rules from GitHub (Cursor only)\n\nYou can use this repository as a **Remote Rule** in Cursor without installing the package via Composer:\n\n1. Open **Cursor Settings** → **Rules**.\n2. In the **Project Rules** section, click **Add Rule**.\n3. Select **Remote Rule (Github)**.\n4. Enter the repository URL: `https://github.com/pekral/cursor-rules`.\n\nCursor will fetch and apply the rules from the repository. Note: this method provides rules only; Agent skills are installed into your project when you use the Composer-based installation above.\n\n### Available Commands\n\n```bash\nvendor/bin/cursor-rules help # print help\nvendor/bin/cursor-rules install --editor=cursor # install for Cursor\nvendor/bin/cursor-rules install --editor=claude # install for Claude\nvendor/bin/cursor-rules install --editor=codex # install for Codex\nvendor/bin/cursor-rules install --editor=all # install for Cursor, Claude, and Codex\nvendor/bin/cursor-rules install --editor=cursor --force # overwrite existing files\nvendor/bin/cursor-rules install --editor=cursor --symlink # prefer symlinks (fallback to copy)\nvendor/bin/cursor-rules install --editor=claude --allow-bundled-scripts # whitelist this package's bundled scripts in ~/.claude/settings.json\n```\n\n### Installer Flow\n\n1. Determine the project root by walking up from the current directory until `composer.json` is found.\n2. Resolve the rules source (local `rules/` or `vendor/pekral/cursor-rules/rules`).\n3. Install rules into the target directory(ies) for the chosen editor (see `--editor`).\n4. If present, resolve the skills source and install into the corresponding skill directory(ies).\n5. For `--editor=claude` or `--editor=all`: copy `CLAUDE.md` to the project root (never overwrites existing).\n6. Optionally overwrite existing files with `--force`; use `--symlink` to prefer symlinks (fallback to copy on Windows).\n7. Surface explicit errors for missing directories, removal failures, and copy/symlink failures.\n\n### CLI Switches\n\n| Option | Description |\n|-------------------|-----------------------------------------------------------------------------|\n| `--editor=EDITOR` | Target editor (required): `cursor`, `claude`, `codex`, `all`. |\n| `--force` | Overwrite files that already exist in the target directory. |\n| `--symlink` | Create symlinks when the OS permits; automatically falls back to copy. |\n| `--prune` | Remove files in target that no longer exist in source. |\n| `--allow-bundled-scripts` | Opt-in. With `--editor=claude` or `--editor=all`, idempotently appends a narrow allow-list for this package's bundled scripts (`load-issue.sh` for GitHub and JIRA) to `~/.claude/settings.json`, so Claude Code stops prompting on every run. Other entries in `settings.json` are preserved. No effect when the editor target is `cursor` / `codex` or when `HOME` / `USERPROFILE` is not set. |\n| *(default)* | Only copy missing files and keep existing content untouched. |\n\n---\n\n# 🎯 Skills Overview — **v0.9.1**\n\n> Current release includes 62 skills for issue resolution, planning, code review, refactoring, testing, performance benchmarking, security, SQL performance, frontend and UI, platform and data, content writing, and delivery workflows.\n\nAgent skills are installed into the chosen editor’s skill directory (see `--editor`). Use `--editor=all` to install for Cursor, Claude, and Codex at once. They can be invoked when relevant. Each skill follows project conventions, ensures code quality, and maintains 100% test coverage where applicable.\n\n> **Note:** Skill files use relative paths (e.g. `@rules/…`, `@skills/…`) without any editor-specific prefix, so they work with any supported editor (`--editor=cursor`, `--editor=claude`, `--editor=codex`, `--editor=all`).\n\n## Issue Resolution & Delivery\n\n| Skill | Description |\n|---|---|\n| `analyze-problem` | Structured problem analysis for debugging, root cause identification, and breaking down complex issues. |\n| `resolve-issue` | Unified issue resolution for GitHub, JIRA, and Bugsnag. Detects the tracker from the provided link, runs `analyze-problem` before implementation, validates with tests, and creates a PR. |\n| `merge-github-pr` | Safely merge GitHub pull requests that are ready for deployment. |\n| `pr-staged-merge-plan` | Propose how to merge and deploy a large PR in safe parts instead of all at once — groups its commits into atomic, independently shippable units, orders them by dependency and rollback risk, proposes squashes for a clean history, and proposes corrected subjects for vague or inaccurate commit messages (read-only; never rewrites history or merges). |\n| `create-issue` | Create a tracker issue from provided task text while preserving original meaning and structure. |\n| `create-issues-from-text` | Batch-create issues from provided text with automatic structure detection. |\n| `pr-summary` | Summarize current PR changes for development and product teams as a short two-section comment (Summary of changes + How to test), rendered as GitHub Markdown for PR comments or JIRA Wiki Markup for JIRA issue comments. |\n| `skill-creator` | Scaffold a new Agent skill that follows project conventions and passes `skill-check` validation. |\n| `refresh-claude-md` | Regenerate or create the project `CLAUDE.md` from the current codebase — re-detect tech stack, verified build/test commands, directory structure, and conventions while preserving every human-authored section. Adapted from the ECC `codebase-onboarding` skill; runs only when `CLAUDE.md` is stale or missing. |\n| `cleanup-local-branches` | Prune dead local Git branches — those whose upstream was deleted on origin (gone) and those with no origin counterpart inactive for more than six months — while protecting the current and default branches and previewing every deletion. |\n| `git-workflow` | Choose a Git branching strategy and handle merge vs rebase, conflicts, stashing, undoing mistakes, and release tagging — complements the commit/PR conventions in `@rules/git/general.mdc`, `cleanup-local-branches`, and `merge-github-pr`. |\n| `product-capability` | Turn a clear-but-underspecified PRD into an engineering-ready capability plan that exposes invariants, interfaces, and unresolved decisions before any code is written, then hands off to `blueprint` or `create-issues-from-text`. |\n| `blueprint` | Turn a large objective into a sequenced construction plan of 3–12 one-PR steps with dependency edges, cold-start context briefs, and exit criteria — reviewed adversarially and registered as Markdown so a fresh agent can pick up any step. |\n| `autonomous-loops` | Reference catalog of loop patterns for running Claude Code autonomously — from a single sequential pipeline to multi-agent DAG orchestration — anchored to this repo's real skills with `composer build` / `composer skill-check` as the gate between iterations. |\n| `record-project-memory` | Write side of compound engineering's per-project memory. At task convergence, distils only the lessons that clear a strict promotion bar and appends them — after a dedup/supersede/prune curation pass — to the project's `docs/memory/PROJECT_MEMORY.md`, so a recurring review finding or a non-obvious decision stops being re-derived on the next task. |\n\n## Code Review, Security & Architecture\n\n| Skill | Description |\n|---|---|\n| `assignment-compliance-check` | Plain-language check that the PR implementation fulfills the linked issue's business requirements; reports only Critical functional gaps as a dedicated comment on the originating issue tracker — no local file written and never embedded in the PR comment. |\n| `prepare-issue-context` | Pre-flight data + codebase prep before `/resolve-issue`, TDD, or CR. Extracts every assignment scenario, maps each to a code path, seeds the dev DB with the records the scenario depends on, and surfaces gaps so the implementing agent never has to guess. |\n| `code-review` | Senior PHP code review focused on architecture, risk, and behavior (read-only). |\n| `code-review-github` | Review GitHub pull requests; posts technical findings on the PR and a non-technical `pr-summary` comment on every linked GitHub issue (read-only on the codebase; publishes only comments via `gh`). |\n| `code-review-jira` | Review changes linked to a JIRA ticket; posts technical findings on the GitHub PR and a non-technical `pr-summary` comment on the JIRA ticket (read-only on the codebase; publishes only comments via `gh` and `acli`). |\n| `code-review-bugsnag` | Review a fix linked to a Bugsnag error; posts technical findings on the linked GitHub PR and a non-technical `pr-summary` comment on the Bugsnag error (read-only on the codebase; publishes only comments via `gh` and the Data Access API, needs `BUGSNAG_TOKEN`). |\n| `process-code-review` | Process existing review feedback, resolve comments, and prepare next review cycle. |\n| `security-review` | OWASP-focused security review (injection, auth, SSRF, exposure, misconfigurations) — read-only. |\n| `api-review` | API design contract review (`@rules/api/general.mdc`) — resource-oriented REST, HTTP method/idempotence, idempotency keys, precise status codes, validation at the trust boundary. Self-scopes to API-surface diffs and runs on every CR — read-only. |\n| `security-threat-analysis` | Analyze a specific security threat from a referenced source (CVE, GHSA, advisory, blog post). Produces a human-readable remediation report with ordered, agent-actionable steps and a verification check. |\n| `laravel-security` | Condensed Laravel 11 / PHP 8.3 secure-defaults reference — authentication, authorization, Eloquent safety, CSRF/XSS, API security, file uploads, secrets, and production hardening. |\n| `laravel-authorization-review` | Laravel-native authorization / IDOR (BOLA) reviewer. Walks the authorization chain of every HTTP route (middleware → authorize/policy/gate → query scoping → API Resource output), anchors every finding to real `php artisan route:list --json` output plus a cited `file:line`, classifies by confidence, and produces a per-route coverage map — read-only / advise-only. |\n| `security-bounty-hunter` | Hunt for exploitable, remotely reachable vulnerabilities in a PHP/Laravel codebase for responsible disclosure — biases toward user-controlled attack paths and discards low-signal noise. |\n| `penetration-tester` | Authorized, methodology-driven penetration test — runs only on an explicit pentest request against an in-scope target, validates exploitability with safe proofs of concept, and delivers a risk-rated remediation report (read-only, non-destructive). |\n| `codebase-simplification-audit` | Coordinator-driven, read-only sweep for materially useful simplifications in data structures, state representation, control flow, algorithms, and ownership. Inventories every subsystem as a coverage contract, reviews each within a non-overlapping boundary, independently verifies every finding, then audits its own coverage, duplication, materiality, schema, and ranking. Proposes only — never edits, tests, commits, or pushes. |\n| `class-refactoring` | Refactor PHP classes using SOLID and Laravel best practices with testability focus. |\n| `refactor-entry-point-to-action` | Refactor controller/job/command/listener entry-point logic into Action classes. |\n| `smartest-project-addition` | Propose one high-impact, low-risk project improvement. |\n| `understand-propose-implement-verify` | Enforce a strict 4-step loop: understand, propose, implement, verify. |\n| `production-audit` | Read-only production-readiness audit from cheap local git/code/CI/config evidence — risk lenses across auth, data integrity, payments, jobs, and deployment — returning a scored ship/block verdict with specific fixes and hard caps for critical gaps. |\n| `automation-audit-ops` | Evidence-first, read-only inventory of every automation in the repo (GitHub Actions, Claude Code hooks/settings, MCP servers, composer scripts, the installer, the skills catalog, scheduler) classified live/broken/redundant with keep/merge/cut/fix recommendations. |\n\n## Testing & Quality Automation\n\n| Skill | Description |\n|---|---|\n| `create-test` | Add tests following project rules with deterministic behavior and high coverage. |\n| `create-missing-tests-in-pr` | Validate review recommendations and add missing tests for current PR changes. |\n| `rewrite-tests-pest` | Rewrite tests to PEST style while preserving behavior and conventions. |\n| `test-like-human` | Validate PR behavior from user perspective using scenario-driven testing. |\n| `test-driven-development` | Enforce strict red-green-refactor flow for bugfixes and features. |\n| `tester-cookbook` | Turn a JIRA task and its linked PRs into a concise QA report for a non-technical tester — focused on what to report back to the dev team, optionally with brief steps to reach the result — delivered as a JIRA Wiki Markup comment. |\n| `e2e-testing` | Write or stabilize Playwright end-to-end browser tests against a Laravel app — gated on Playwright already being present, otherwise defers to manual testing or Pest/Dusk. |\n| `benchmark` | Measure performance baselines and detect regressions in a Laravel app — page Core Web Vitals, API latency percentiles, build/test velocity, and DB query timing — stored as git-tracked baselines for team comparison. |\n| `benchmark-optimization-loop` | Turn a vague speed goal (\"make it faster\", \"reduce p95\") into a bounded, measured optimization loop that promotes only verified, correctness-preserving wins via a baseline, a variant ledger, and a promotion gate. |\n\n## Platform & Data\n\n| Skill | Description |\n|---|---|\n| `composer-update` | Analyze composer updates, conflicts, and changelog impact. |\n| `mysql-problem-solver` | Diagnose and optimize MySQL queries, indexes, and execution plans. |\n| `laravel-telescope` | Analyze Laravel Telescope request data from URL, match entries in DB, and propose concrete optimizations. |\n| `mysql-patterns` | Advanced MySQL patterns in Laravel — upserts, JSON columns, full-text search, partitioning, replication/read-write splitting, and deadlock handling — beyond the query tuning in `@rules/sql/optimalize.mdc`. |\n| `postgres-patterns` | Advanced PostgreSQL patterns in Laravel — GIN/BRIN/partial/covering indexes, jsonb, `ON CONFLICT` upserts, `SKIP LOCKED` queue workers, cursor pagination, RLS, and `timestamptz`/`numeric` typing — the Postgres counterpart to `mysql-patterns`. |\n| `redis-patterns` | Redis in Laravel — caching strategies, atomic/distributed locks, rate limiting, stampede protection, pub/sub, pipelines, and key/TTL design. |\n| `docker-patterns` | Docker and docker-compose for a Laravel app — multi-stage PHP-FPM images, services (nginx, MySQL, Redis, queue worker, scheduler, Vite build), healthchecks, secrets, and image hardening. |\n| `latency-critical-systems` | Latency-sensitive Laravel paths — realtime dashboards, streaming, queues, and caches — where p95 latency and data freshness matter (Octane, Horizon, Redis, read replicas). |\n\n## Frontend & UI\n\n| Skill | Description |\n|---|---|\n| `frontend-design-direction` | Choose a deliberate, polished design direction for a Laravel/Blade/Livewire/Filament interface instead of generic, templated UI. |\n| `design-system` | Generate, audit, or review the visual design system of a Laravel app — Tailwind tokens, Filament theming, Blade/Livewire component consistency, and visual-polish audits. |\n| `frontend-patterns` | Livewire/Blade/Alpine UI patterns — component composition, state placement, performance, forms, and loading/empty/error states. |\n| `frontend-a11y` | Accessible UI in a Laravel app — semantic Blade markup, accessible forms, keyboard navigation with Alpine, focus and live-region management for Livewire, contrast, and Filament a11y. |\n| `vite-patterns` | Configure or optimize Vite (laravel-vite-plugin) asset bundling — entrypoints, the `@vite` Blade directive, HMR, env vars, aliases, manifests, code splitting, and production builds. |\n| `seo` | Audit, plan, or implement SEO in a Laravel app — crawlability, indexability, JSON-LD structured data in Blade, Core Web Vitals, on-page tags, keyword mapping, competitor gap analysis, E-E-A-T content quality, and measurement. |\n| `frontend-slides` | Build standalone HTML/CSS/JS presentation decks — self-contained single-file decks with viewport-fit layout, keyboard navigation, and browser Print-to-PDF export. |\n\n## Content & Writing\n\n| Skill | Description |\n|---|---|\n| `article-writing` | Write long-form content (blog posts, guides, tutorials, essays, newsletters) in a distinctive voice derived from supplied examples or a default operator voice. Leads with concrete proof, bans hollow AI phrasing, and tailors structure to the medium. |\n\n---\n\n## Rules Overview\n\nRules included in this package:\n\n| File | Description | Scope |\n|-------------------------------|------------------------------------------------------------|----------|\n| `php/core-standards.mdc` | Project context, AI behavior, and unified PHP/Laravel coding standards | Always |\n| `compound-engineering/general.mdc` | Compound engineering — make future work easier and build durable per-project compound memory | Always |\n| `git/general.mdc` | Unified git workflow, commits, and pull request rules | Always |\n| `code-review/general.mdc` | Code review conventions and output rules | Always |\n| `code-testing/general.mdc` | Testing conventions and quality standards | Always |\n| `refactoring/general.mdc` | Shared refactoring definition (legacy → modern, incremental migration) | Refactor |\n| `jira/general.mdc` | JIRA CLI usage and formatting rules | JIRA |\n| `reports/general.mdc` | Language rule for reports published to issue trackers (assignment language) | Always |\n| `laravel/architecture.mdc` | Laravel architecture and conventions | Laravel |\n| `laravel/laravel.mdc` | Laravel-specific rules and patterns | Laravel |\n| `laravel/filament.mdc` | Filament v4 specific rules | Filament |\n| `laravel/livewire.mdc` | Livewire component rules and conventions | Livewire |\n| `laravel/queue-debouncing.mdc`| Safe Laravel queue debouncing, urgency separation, and replaceable work | Laravel |\n| `laravel/dynamodb.mdc` | DynamoDB query safety: scan prevention, key-targeted reads, Tinker debug | Laravel |\n| `sql/optimalize.mdc` | SQL query optimization, index design, schema standards | Always |\n| `security/backend.md` | Backend security rules and OWASP Top 10 checks | Always |\n| `security/frontend.md` | Frontend security rules (XSS, CSRF, CSP) | Frontend |\n| `security/mobile.md` | Mobile-specific security rules and WebView checks | Mobile |\n| `security/untrusted-content.md`| Untrusted Content Boundary — trusted instructions outrank instructions found inside issues, comments, tool outputs, and fetched pages | Always |\n\nAll `.mdc` and `.md` files are ready for automatic injection by Cursor so every PHP and Laravel edit stays aligned with the enforced standards.\n\n## Development & Testing\n\n### Composer Scripts\n\n```bash\ncomposer check # run full quality check (skill-check, normalize, phpcs, pint, rector, phpstan, audit, tests)\ncomposer fix # run all automatic fixes (skill-check-fix, normalize, rector, pint, phpcs)\ncomposer build # install (cursor-rules install --force) then fix then check\ncomposer analyse # run PHPStan static analysis\ncomposer test:coverage # run tests with 100% coverage\ncomposer coverage # alias for test:coverage\ncomposer security-audit # run security audit of dependencies\n```\n\n### Individual Commands\n\n```bash\ncomposer skill-check # SKILL.md linter (validation + scoring across every skill)\ncomposer skill-check-fix # SKILL.md linter with auto-fix\ncomposer composer-normalize-check # validate composer.json normalization (dry-run)\ncomposer composer-normalize-fix # apply composer.json normalization\ncomposer phpcs-check # PHP CodeSniffer check\ncomposer phpcs-fix # PHP CodeSniffer fix\ncomposer pint-check # Laravel Pint check\ncomposer pint-fix # Laravel Pint fix\ncomposer rector-check # Rector check (dry-run)\ncomposer rector-fix # Rector fix\n```\n\n### Testing\n\n```bash\n./vendor/bin/pest # run all tests\ncomposer test:coverage # run tests with coverage (min. 100%)\n```\n\nRemove `coverage.xml` before committing if it was produced locally.\n\n## Author\n\n**Petr Král** — PHP Developer & Laravel programmer, open source contributor ([pekral.cz](https://pekral.cz)).\n\n## License\n\nMIT — free to use, modify, and distribute.\n"}