<p align="center"> <img src="assets/logo.png" alt="Cursor rules" width="280"> </p>

Cursor Rules for PHP and Laravel — Composer Plugin

<p align="center"> <a href="https://packagist.org/packages/pekral/cursor-rules"><img src="https://img.shields.io/packagist/v/pekral/cursor-rules" alt="Packagist Version"></a> <a href="https://packagist.org/packages/pekral/cursor-rules"><img src="https://img.shields.io/packagist/dt/pekral/cursor-rules" alt="Total Downloads"></a> <a href="https://packagist.org/packages/pekral/cursor-rules"><img src="https://img.shields.io/packagist/php-v/pekral/cursor-rules" alt="PHP Version"></a> <a href="https://github.com/pekral/cursor-rules/blob/master/LICENSE"><img src="https://img.shields.io/packagist/l/pekral/cursor-rules" alt="License"></a> <a href="https://pekral.cz"><img src="https://img.shields.io/badge/by-pekral.cz-blue" alt="by pekral.cz"></a> </p>

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.

Why This Package

• a Composer plugin: PHP/Laravel cursor rules + agent skills in one composer require --dev package
• unified PHP coding guidelines for PHP 8.4 projects
• Pest-based testing with mandatory code analysis and 100% coverage
• strong focus on clean code: typed properties, SRP, no redundant comments
• 63 comprehensive Agent skills for automated workflows (v0.9.1)
• fast onboarding inside development repositories

Installation

composer require pekral/cursor-rules --dev
vendor/bin/cursor-rules install --editor=cursor

The --editor flag is required. Use it to choose the target agent:

• cursor: .cursor/rules, .cursor/skills
• claude: .claude/rules, .claude/skills, and when HOME/USERPROFILE is set also ~/.claude/skills
• codex: .codex/rules, .codex/skills, and when HOME/USERPROFILE is set also ~/.codex/skills
• all: all of the above (Cursor, Claude, Codex in project + home)

Editor compatibility

| Feature | Cursor | Claude | Codex | |---------|--------|--------|-------| | Rules | ✅ | ✅ | experimental / unverified | | Skills | ✅ | ✅ | ✅ | | Agents | — | ✅ | — |

Agents are installed only for --editor=claude and --editor=all; they are skipped for cursor and codex because only Claude Code has a native subagent format. Codex 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.

When the package is required via Composer, sources are read from vendor/pekral/cursor-rules/rules and vendor/pekral/cursor-rules/skills.

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.

Automatic Installation via Composer Plugin

By 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:

{
  "extra": {
    "cursor-rules": {
      "auto-install": true,
      "editor": "claude"
    }
  }
}

| Option | Description | Default | |----------------|----------------------------------------------------------|-----------| | auto-install | Enable automatic install on composer install/update. | false | | editor | Target editor for auto-install (cursor, claude, codex, all). | cursor |

If you prefer manual control, simply call vendor/bin/cursor-rules install in your Composer post-update-cmd scripts with the desired flags.

Installing rules from GitHub (Cursor only)

You can use this repository as a Remote Rule in Cursor without installing the package via Composer:

1. Open Cursor Settings → Rules.
2. In the Project Rules section, click Add Rule.
3. Select Remote Rule (Github).
4. Enter the repository URL: https://github.com/pekral/cursor-rules.

Cursor 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.

Available Commands

vendor/bin/cursor-rules help                                  # print help
vendor/bin/cursor-rules install --editor=cursor               # install for Cursor
vendor/bin/cursor-rules install --editor=claude               # install for Claude
vendor/bin/cursor-rules install --editor=codex                # install for Codex
vendor/bin/cursor-rules install --editor=all                  # install for Cursor, Claude, and Codex
vendor/bin/cursor-rules install --editor=cursor --force       # overwrite existing files
vendor/bin/cursor-rules install --editor=cursor --symlink     # prefer symlinks (fallback to copy)
vendor/bin/cursor-rules install --editor=claude --allow-bundled-scripts   # whitelist this package's bundled scripts in ~/.claude/settings.json

Installer Flow

1. Determine the project root by walking up from the current directory until composer.json is found.
2. Resolve the rules source (local rules/ or vendor/pekral/cursor-rules/rules).
3. Install rules into the target directory(ies) for the chosen editor (see --editor).
4. If present, resolve the skills source and install into the corresponding skill directory(ies).
5. For --editor=claude or --editor=all: copy CLAUDE.md to the project root (never overwrites existing).
6. Optionally overwrite existing files with --force; use --symlink to prefer symlinks (fallback to copy on Windows).
7. Surface explicit errors for missing directories, removal failures, and copy/symlink failures.

CLI Switches

| Option | Description | |-------------------|-----------------------------------------------------------------------------| | --editor=EDITOR | Target editor (required): cursor, claude, codex, all. | | --force | Overwrite files that already exist in the target directory. | | --symlink | Create symlinks when the OS permits; automatically falls back to copy. | | --prune | Remove files in target that no longer exist in source. | | --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. | | (default) | Only copy missing files and keep existing content untouched. |

---

🎯 Skills Overview — v0.9.1

Current release includes 63 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.

Agent 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.

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).

Issue Resolution & Delivery

| Skill | Description | |---|---| | analyze-problem | Structured problem analysis for debugging, root cause identification, and breaking down complex issues. | | 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. | | autoresolve-oldest-github-issue | Picks the oldest open GitHub issue (optionally filtered by label, default Resolve_by_AI) and chains resolve-issue → code-review-github → process-code-review → merge-github-pr against the resulting PR. Stops on any documented blocker (merge conflict, failing CI, residual Critical/Moderate findings). | | merge-github-pr | Safely merge GitHub pull requests that are ready for deployment. | | 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). | | create-issue | Create a tracker issue from provided task text while preserving original meaning and structure. | | create-issues-from-text | Batch-create issues from provided text with automatic structure detection. | | 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. | | skill-creator | Scaffold a new Agent skill that follows project conventions and passes skill-check validation. | | 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. | | 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. | | 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. | | product-capability | Turn a clear-but-underspecified PRD into an engineerin