Cursor Rules for PHP and Laravel

Cursor rules for PHP and Laravel — 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

• cursor rules for PHP and Laravel in one Composer-installable 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
• 59 comprehensive Agent skills for automated workflows (v0.8.3)
• 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)

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"
    }
  }
}

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

🎯 Skills Overview — v0.8.3

Current release includes 59 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

Code Review, Security & Architecture

Testing & Quality Automation

Platform & Data

Frontend & UI

Content & Writing

Claude Code Subagents

Agents are a thin orchestration layer over the existing skills — they don't replace them and they don't duplicate their prompts. The roster is named after Greek mythology by function (see docs/agents.md).

Rules  = long-lived project standards
Skills = reusable workflows
Agents = specialised orchestration roles over multiple skills

How to use argos in practice

1. Install for Claude Code (or every editor):

   vendor/bin/cursor-rules install --editor=claude   # or --editor=all
   

   Agents land in .claude/agents/. They are not installed for --editor=cursor or --editor=codex.

2. Invoke it with a source — a GitHub PR/issue, a JIRA key, a Bugsnag error, or just the current branch/PR:

   @argos review PR #123
   @argos review https://your.atlassian.net/browse/PROJ-42
   @argos review the current diff
   

3. argos detects the tracker, runs the matching code-review-* skill, lets it post the review to the PR, then returns a handoff: CR done + PR link + source link + Critical/Moderate/Minor counts + assignment-conformance verdict.

argos is read-only — it never applies fixes, commits, pushes, or merges. Those belong to separate agents.

How to use talos in practice

1. Install for Claude Code (or every editor), exactly as for argos — agents land in .claude/agents/ and are skipped for --editor=cursor / --editor=codex.

2. Invoke it with a source — a GitHub issue/PR, a JIRA key, a Bugsnag error, or just the task you want implemented:

   @talos implement #123
   @talos implement https://your.atlassian.net/browse/PROJ-42
   @talos implement the failing upload validation
   

3. talos detects the source, runs resolve-issue to implement the change with tests and open a PR, then returns a handoff: Impl done + PR link + source link + branch + a summary of what changed and the test result.

talos stops at the PR — it never reviews its own work or merges. Hand the PR to argos for review next.

If talos reports Blocked: sandbox denied file write: dispatched subagents run non-interactively, so a write is denied unless the path is pre-allowed. Add scoped Edit / Write entries for the project tree to permissions.allow in .claude/settings.local.json ("Edit(//Users/me/Projects/my-app/**)", "Write(//Users/me/Projects/my-app/**)") — or run the installer with --allow-subagent-writes to add them for you — then re-run. See docs/agents.md Troubleshooting — subagent file writes blocked. The run correctly stops instead of silently finishing the work in the main thread.

How to use metis in practice

1. Install for Claude Code (or every editor), exactly as for argos / talos — agents land in .claude/agents/ and are skipped for --editor=cursor / --editor=codex.

2. Invoke it with a subject — a GitHub issue/PR, a JIRA key, a Bugsnag error, or just a problem you want thought through:

   @metis analyse #123
   @metis analyse https://your.atlassian.net/browse/PROJ-42
   @metis analyse why the nightly export job times out
   

3. metis runs analyze-problem, then returns a handoff: Analysis done + a link to the published plan-artifact issue + the subject link + a one-line root cause + the recommended solution.

metis is read-only — it analyses and plans, but never edits code, commits, or implements. Hand its plan issue to talos to build next.

How to use daidalos in practice

daidalos is the front door — the agent you address with a free-form request when you don't want to pick a specialist yourself.

1. Install for Claude Code (or every editor), exactly as for the other agents.

2. Invoke it with a request — it resolves the source and chooses the route:

   @daidalos resolve a random Resolve_by_AI issue
   @daidalos resolve https://github.com/owner/repo/issues/123
   @daidalos implement a dark-mode toggle for the settings page
   

3. daidalos resolves a concrete source, then dispatches the matching specialist agent through the Task tool: ambiguous / large work → metis (analysis → plan) → talos; clear work → talos directly; then argos for the review-and-fix loop to convergence. It returns a handoff naming the chosen route and reason, written in the same language as your request.

daidalos is a read-only orchestrator — it never analyses, implements, or reviews itself; it delegates every step by dispatching the matching specialist agent, and (per the one-level subagent-nesting rule) it runs as the top-level agent you talk to, spending that single nesting level on the dispatch rather than being a nested subagent itself. A future top-level zeus will sit above it to coordinate non-engineering domains too.

Rules Overview

Rules included in this package:

All .mdc and .md files are ready for automatic injection by Cursor so every PHP and Laravel edit stays aligned with the enforced standards.

Development & Testing

Composer Scripts

composer check              # run full quality check (skill-check, normalize, phpcs, pint, rector, phpstan, audit, tests)
composer fix                # run all automatic fixes (skill-check-fix, normalize, rector, pint, phpcs)
composer build              # install (cursor-rules install --force) then fix then check
composer analyse            # run PHPStan static analysis
composer test:coverage      # run tests with 100% coverage
composer coverage           # alias for test:coverage
composer security-audit     # run security audit of dependencies

Individual Commands

composer skill-check                # SKILL.md linter (validation + scoring across every skill)
composer skill-check-fix            # SKILL.md linter with auto-fix
composer composer-normalize-check   # validate composer.json normalization (dry-run)
composer composer-normalize-fix     # apply composer.json normalization
composer phpcs-check                # PHP CodeSniffer check
composer phpcs-fix                  # PHP CodeSniffer fix
composer pint-check                 # Laravel Pint check
composer pint-fix                   # Laravel Pint fix
composer rector-check               # Rector check (dry-run)
composer rector-fix                 # Rector fix

Testing

./vendor/bin/pest           # run all tests
composer test:coverage      # run tests with coverage (min. 100%)

Remove coverage.xml before committing if it was produced locally.

Author

Petr Král — PHP Developer & Laravel programmer, open source contributor (pekral.cz).

License

MIT — free to use, modify, and distribute.