--- slug: "superpowers-laravel" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/jpcaparas/superpowers-laravel@main/README.md" repo: "https://github.com/jpcaparas/superpowers-laravel" source_file: "README.md" branch: "main" --- # Laravel Superpowers

Laravel Superpowers Logo

Laravel-focused skills for Claude Code and AI coding assistants. Brings proven workflows (TDD, debugging, planning) plus Laravel‑specific guidance that works with or without Sail. ## What You Get

image

- **Laravel Skills** – Runner selection (Sail/non‑Sail), TDD with Pest/PHPUnit, migrations + factories, queues + Horizon, quality gates (Pint/Insights/PHPStan), pragmatic architecture (Ports & Adapters, Template Method), and complexity guardrails. - Can be used on its own; also compatible with the base Superpowers plugin. Overlapping generic skills are removed here to avoid conflicts. Plus: - **Slash Commands** - `/superpowers-laravel:brainstorm`, `/superpowers-laravel:write-plan`, `/superpowers-laravel:execute-plan` - **Automatic Integration** - Skills activate automatically when relevant - **Consistent Workflows** - Systematic approaches to common engineering tasks ## SessionStart Preview Below shows the startup message rendered when this plugin detects Laravel apps. The assistant now supports monorepos and adapts guidance based on which app is active and whether Sail is available. ### When Sail is detected - use Sail wrappers

SessionStart with Sail detected

### When Sail is NOT detected - use host machine commands

SessionStart without Sail

## Learn More Read the introduction to the original Superpowers: [Superpowers for Claude Code](https://blog.fsck.com/2025/10/09/superpowers/) ## Installation ### Claude Code (via Plugin Marketplace) ```bash # In Claude Code /plugin marketplace add jpcaparas/superpowers-laravel /plugin install superpowers-laravel@superpowers-laravel-marketplace ``` ### Verify Installation ```bash # Check that commands appear /help # Should see Laravel commands, e.g.: # /superpowers-laravel:brainstorm # /superpowers-laravel:write-plan # /superpowers-laravel:execute-plan # /superpowers-laravel:laravel-check # /superpowers-laravel:laravel-tdd ``` ### Codex (Experimental) Codex support is experimental. Use the skills from this repo directly or copy the `skills/` subfolders you want into your project’s `.claude/skills`. ## Quick Start ### Using Slash Commands **Brainstorm a design (Laravel-specific):** ``` /superpowers-laravel:brainstorm ``` **Create an implementation plan (Laravel-specific):** ``` /superpowers-laravel:write-plan ``` **Execute the plan (Laravel-specific):** ``` /superpowers-laravel:execute-plan ``` ### Automatic Skill Activation Skills activate automatically when relevant. For example: - `test-driven-development` activates when implementing features - `systematic-debugging` activates when debugging issues - `verification-before-completion` activates before claiming work is done ### Runner Guidance (Sail vs host) - Prefer running commands with Sail when it is available (`vendor/bin/sail` or a top‑level `./sail` helper); fall back to host tools otherwise. - When Sail is declared but containers are not running, the assistant will ask whether to start Sail (`sail up -d`) or proceed with host tools. It will not run host `php`/`composer`/DB/Node commands until you choose. - When Sail containers are running, use `sail` for all PHP/Composer/Node/DB commands to avoid environment drift; do not mix host and container installs in the same session. - Portable alias: ``` alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)' ``` ### Monorepos and Multiple Apps When multiple Laravel apps exist (for example `apps/api`, `apps/admin`), the SessionStart hook: - Scans the repository recursively (ignores `vendor/`, `node_modules/`, `storage/`, and VCS/IDE folders) to find every `artisan` entrypoint. - Detects Laravel version per app (prefers `composer.lock` via `jq`, falls back to `composer.json` constraint or a portable parser). - Shows a summary list of all detected apps with version and Sail availability; marks the app in your current working directory as the “active” app. - Emits Sail guidance and interactive safety ONLY for the active app. Tip: `cd` into the app you intend to work on before starting your session to make it the active app. ## What's Inside ### Skills Library Skills live in `skills/` and are designed for everyday Laravel work. Core examples include `runner-selection`, `tdd-with-pest`, `migrations-and-factories`, `quality-checks`, `queues-and-horizon`, and `ports-and-adapters` — with many more patterns ready for larger teams. 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. #### Laravel 13 Support Laravel 13 (released March 2026, PHP 8.3+) is fully covered. Stable skills carry clearly-marked "Laravel 13+" sections, and dedicated skills cover the headline features: - Laravel AI SDK — agents, embeddings, images, audio (`laravel:ai-sdk`) - Semantic / Vector Search with pgvector (`laravel:vector-search`) - First-Party PHP Attributes — `#[Middleware]`, `#[Authorize]`, `#[Tries]`, and friends (`laravel:php-attributes`) - Request Forgery Protection — origin-aware CSRF via `PreventRequestForgery` (`laravel:request-forgery-protection`) - Upgrade Guide 12.x → 13.x — breaking-change checklist (`laravel:upgrade-13`) Existing skills also gained 13.x guidance: JSON:API resources, `Queue::route()`, job attributes, `Interruptible` jobs, `Cache::touch()`, the `storage` cache driver, `Schedule::group()`, `FailOnUnknownFields` strict validation, JSON Schema rules, the `@fonts` directive, `php artisan dev`, and more. #### Docs Intersection (Laravel 11.x–13.x) We added a focused set of skills that reflect patterns stable across 11.x, 12.x, and 13.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: - `brainstorm.md` → `laravel:brainstorming` - `write-plan.md` → `laravel:writing-plans` - `execute-plan.md` → `laravel:executing-plans` - `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` Laravel 13 wrappers: - `laravel-ai-sdk.md` → `laravel:ai-sdk` - `laravel-vector-search.md` → `laravel:vector-search` - `laravel-attributes.md` → `laravel:php-attributes` - `laravel-csrf.md` → `laravel:request-forgery-protection` - `laravel-upgrade-13.md` → `laravel:upgrade-13` ### Skills Overview - Onboarding & Runner - Planning & Execution - Data & Schema - Quality & Ops - Architecture - Performance - Testing - Utilities - Best Practices ## How It Works 1. **SessionStart Hook** – Adds Laravel onboarding (`laravel:using-laravel-superpowers`) when a Laravel repo is detected 2. **Skills System** - Uses Claude Code's first-party skills system 3. **Automatic Discovery** - Claude finds and uses relevant skills for your task 4. **Mandatory Workflows** - When a skill exists for your task, using it becomes required ## Philosophy - **Test-Driven Development** - Write tests first, always - **Systematic over ad-hoc** - Process over guessing - **Complexity reduction** - Simplicity as primary goal - **Evidence over claims** - Verify before declaring success - **Domain over implementation** - Work at problem level, not solution level ## Contributing Skills live directly in this repository. To contribute: 1. Fork the repository 2. Create a branch for your skill 3. Follow existing skill patterns (frontmatter name/description and focused, testable guidance) 4. Submit a PR with a short release-notes entry ### Run checks locally Validate structure and conventions before pushing: ``` # Requires Node.js 18+ (20 recommended) npx tsx scripts/validate_skills.ts ``` This verifies that: - `skills/` contains only one-level directories, each with `SKILL.md` - `SKILL.md` files have frontmatter with `name` (starting with `laravel:`) and `description` - `.claude-plugin/plugin.json` has required fields - `commands/*.md` have frontmatter `description` ## Updating Update via the plugin menu or pull the latest changes if you cloned this repo. ## Related Tools - Laravel Boost: a Laravel‑focused MCP server that augments AI‑powered local development (Cursor, Claude Code, etc.). See https://github.com/laravel/boost and https://boost.laravel.com/. This skill catalogue is designed to complement Boost if you install both. ## License MIT License - see LICENSE file for details ## Support - **Issues**: https://github.com/jpcaparas/superpowers-laravel/issues - **Marketplace**: https://github.com/jpcaparas/superpowers-laravel