Core Laravel Package

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.

How to install and enable the PCOV coverage driver for Pest mutation testing (`--mutate`) and code coverage (`composer test-coverage`) under Laravel Herd on macOS and Windows, and how to run and triage a mutation run once a driver is present. Activate when coverage or mutation runs are slow or falling back to Xdebug (`herd coverage`), when `--mutate` errors with "Mutation testing requires code coverage to be enabled" or reports "0 Mutations for 0 Files created", when every `php` on a Mac suddenly dies with `Killed: 9`, when setting up a new machine for the adversarial-review mutation step, or when the user asks how to get fast coverage. Covers the Herd static-PHP constraint, building and signing the extension, wiring it into Herd's PHP config, diagnosing a machine where php is killed on start, the invocation traps, and survivor triage.

Use this skill for Pest PHP testing in this Laravel package (Pest 5 on Orchestra Testbench). Trigger whenever any test is being written, edited, fixed, or refactored — including fixing tests that broke after a code change, adding assertions, converting PHPUnit to Pest, adding datasets, and TDD workflows. Always activate when the user asks how to write something in Pest, mentions test files or the tests/ directory, tests/Pest.php, tests/TestCase.php, or tests/ArchTest.php, or needs architecture tests. Covers: test()/it()/expect() syntax, running tests with composer test or vendor/bin/pest, datasets, mocking and facade-mock cleanup, console command assertions, arch(), and the Testbench TestCase. Do not use for factories, migrations, service providers, or non-test PHP code.

Package-wide PHP coding standards: type hints, method/function call formatting (multi-line parameters at 2+ arguments, PSR-12 `elseif` placement), arrow vs anonymous functions and first-class callables, `sprintf()`/concatenation for literal+variable strings, PHP 8.3+ typed class constants, imports and Pint's import ordering, leading-backslash native function calls, constructor property promotion, contract vs concrete type hints, avoiding "magic" macros / `__call`, SRP, DRY, and long-running-loop `unset()` / `gc_collect_cycles()` discipline. Activate whenever writing or editing first-party PHP under `src/`, `config/`, `database/`, or `tests/` — service providers, facades, console commands, closures/callables, conditionals, and any refactor that touches method signatures, properties, imports, or constants.

PHP documentation discipline: PHPDoc coverage (every class/interface/trait/enum and each top-level constant, property, method, enum case), `@param` / `@var` / `@return` tag spacing and wrapping rules (two spaces for `@param`, single spaces for `@var` and `@return`, no bare `@return void`), the `@command` tag on test files, per-action single-line `//` comments before each logical step in multi-step code, the "only revise docs for impacted code" rule with the 80-char wrap exception, and `Illuminate\Support\Facades\Log` level selection (emergency/alert/critical/error/warning/notice/info/debug). Activate when adding or revising PHPDoc, docblocks, inline comments, or `Log::*` calls in PHP source, tests, config, or any script touched in the same change.

Run a multi-agent security audit of the first-party code in the robot-council Laravel package (`src/`, `config/`, `database/`, `resources/views/`, `routes/`). Fans out one finder agent per security domain (XSS, SSTI, path traversal, SSRF, XXE/DoS, authz, injection, secrets, deserialization, validation/mass-assignment), adversarially verifies every candidate against the package's trust model (end users reach it only through what the service provider registers, Blade `{{ }}` escapes while `{!! !!}` does not, consuming-app developers and Artisan operators are trusted), then writes a severity-ranked report to the gitignored `build/` directory. After you review it, it discloses approved vulnerabilities privately as draft GitHub security advisories (never as public issues) and files approved non-sensitive hardening items as issues following the `writing-issues` conventions. Activate when the user asks to "run a security audit", "audit the codebase for vulnerabilities", "find security bugs", "turn Claude loose on security", "scan for XSS/SSRF/injection", or invokes `/security-audit`. This is a broader, whole-repo complement to the diff-scoped `/security-review` command.

The lifecycle of a workaround this repository carries for a defect in a dependency: write the workaround, report the defect upstream, offer the fix as a pull request, then remove the workaround once a fixed tag ships. Covers the four-ticket GitHub chain that tracks it, the `afk`/`hitl` mode of each ticket, the native `blocked_by` edges including the cross-repo REST recipe that makes an upstream issue a blocker on the removal ticket, where to file when the dependency's tracker has issues turned off (as `pestphp/*` plugins do), verifying the fix against this repository's own suite with a restored-vendor negative control, checking for the fix by tags and Packagist rather than GitHub Releases, and the request variant where nothing local is carried. Activate when a dependency release breaks something here and a workaround is being added (a step in CI or a `composer` script, a version constraint, a `conflict` entry), when filing or wiring the tickets for one, when reporting a dependency defect upstream or opening a pull request to a dependency, when checking whether an upstream fix has shipped, or when retiring a workaround.

Compute the WCAG 2.x contrast ratio between two colors and report AA/AAA pass-fail for normal and large text. Bundles `check-contrast.mjs`, a dependency-free Node CLI that parses `oklch()`, hex, and `rgb()` colors (converting OKLCH→sRGB via the OKLab matrix), so it works directly on the values browser DevTools report for OKLCH-based themes such as Tailwind v4. Activate whenever checking color contrast or accessibility compliance, reviewing dark-mode or light-mode text legibility, picking an accessible text/border color against a known background, verifying a WCAG AA criterion, or when the user mentions contrast ratio, WCAG, AA/AAA, `oklch`, or whether text is readable.

Commit message conventions: Conventional Commits prefix (`feat:`, `fix:`, `docs:`, `refactor:`, `perf:`, `style:`, `test:`, `build:`, `ci:`), 50-character subject limit including the prefix, no forced body line wrapping, single blank line between paragraphs, unordered `-` bullets with nested indented bullets, inline code markup for technical terms, no closing keyword at a line end above an issue reference, and the final commit message presented in a Markdown code block. Also covers what to stage — explicit paths, never `git add -A`. Activate whenever drafting, rewriting, or critiquing a commit message — including in-place edits, PR descriptions derived from commit messages, or rewording an existing commit — and whenever staging changes for a commit.

GitHub issue conventions for this repository: imperative verb-first titles (or symptom-first for bugs) with aggressive inline-code markup and no trailing period; a 1–3-sentence lede that often opens with a provenance line (`Follow-up to #N.`, `Spun off from #N.`, `Part of #N.`); ordered section inventory (`## Why` / `## Background`, `## Current state` / `## Current behavior` / `## The bug` / `## Root cause` / `## Reproduction`, `## What we're building` / `## Scope` / `## Approach` / `## Proposed fix`, mandatory `## Acceptance criteria` GitHub task-list of observable outcomes ending in a test item, `## Out of scope`, `## References`, `## Notes`); archetypes for bug / feature / research-spike / follow-up-cleanup issues; the duplicate check (including pull requests, and reading the match total before the rows); labels; the mutually-exclusive `afk`/`hitl` execution-mode convention flipped as forks are decided, with `epic` containers exempt; epics and sub-issues; dependencies expressed ONLY as native GitHub dependency edges and never restated in the body; cross-repo `owner/repo#N` refs; linked absolute-branch file paths; and the standing rule to NEVER add a "generated by AI" disclaimer. Activate whenever drafting, filing, rewriting, or critiquing the title or body of a GitHub issue for this repository.

Pull-request title and body conventions for this repository. The title is imperative verb-first, has no Conventional-Commit prefix and no internal-process references (batch or merge-order hints), with correct acronym casing and inline-code handles — it renders verbatim into GitHub Release notes. The body: a one-paragraph lede opening with `Closes #N.`, optional `## Approach` / `## Commits` / `## Files` / `## Verification` / `## The bug` / `## Out of scope` / `## Follow-up` / `## Companion PRs` sections, a mandatory `## Test plan` GitHub task-list naming the real checks, `##`/`###` headings, `-` bullets with 2-space nesting and em-dash separators, aggressive inline-code markup, linked file paths whose target is the absolute branch URL, and a canonical `Closes #N.` reference — with cross-repo references rendered as a backticked owner/repo#N link. Covers closing-keyword traps (negation, code spans, cross-line pairs) and how they map onto squash, merge, and rebase merges, plus the PR lifecycle: draft until ready for review, the `CI` workflow, and its required `ci-passed` check. Activate whenever drafting, rewriting, opening, or critiquing a GitHub pull request for this repository.

GitHub Release conventions for the `robot-council/core` Composer package: the em-dash release title (`vX.Y.Z — Theme`), a one-sentence milestone lead with an optional `**Breaking change**` callout, and a CLOSED, ordered heading vocabulary (`## Breaking changes`, `## What's new`, `## What's fixed`, `## Security`, `## Maintenance and tooling`) with one bullet per change formatted as `- <PR title> [#N](…/pull/N)` — using the API PR title (never a merge or squash commit subject), no `by @author`, inline code preserved. Covers the routing cascade and the bundled generator, semantic versioning for a library consumers resolve by tag (below 1.0 the minor is the Composer caret's breaking boundary), cutting a release (the `CHANGELOG.md` pull request, then the tag and a pre-release GitHub Release published through REST, then the wiki refresh), and the retroactive-tag footer. Activate whenever drafting, rewriting, or critiquing a GitHub Release title or body, generating release notes, or cutting a tag for this repo.

Two things reach other people: a change that ships, and a claim that is published. Do not release either on the strength of your own checking alone. First run an adversarial review — an independent, skeptical pass whose job is to break the thing, not confirm it — then triage its findings, fix the...

A check that returns nothing has told you about the check, not about the world. Before reading silence as an absence (no matching process, no duplicate issue, no leaked string, no failing test), show the same instrument, unchanged, finding something it is known to be able to find. Until then,...

A defect found in a dependency — a Composer package, a GitHub Action, a tool — or in any other repository gets an issue in that repository. Not a note in a pull-request body, and not a comment on an issue that is already closed.

Before a branch is validated and before its pull request is opened, bring it current with origin/main.

A release is cut by one seat, at one of three times a day, under one lock. Every other seat merges pull requests and leaves the tag alone. The mechanics of cutting one (the notes, the changelog pull request, the tag) are writing-release-notes; this file says who may start them, and when.

Branch work happens in one of two long-lived worktrees, called slots. Each is bootstrapped once and kept current. Do not create a worktree for a ticket and throw it away afterward. The primary checkout, the main clone, is the reference tree and is not a work surface. Its absolute path differs per...

Every surface this package renders targets WCAG 2.2 level AAA. Apply this whenever you build, extend, or touch one, in the same change as the slice. Accessibility is part of "done," not a later pass. The surfaces today:

First-party prose in this repository is written in American English — code comments, docblocks, README and other documentation, test descriptions, console command descriptions and output, config comments, view copy, commit messages, and issue, pull-request, and release-note bodies. The arbiter is...

Work is not done when the code works. It is done when the branch has merged, the acceptance criteria are ticked or their absence is explained, any board card has moved, and whatever the work surfaced but did not do has a ticket of its own. Each of those is a place where a finished change quietly...

When an issue is hitl because it carries a genuine design fork — an unresolved choice a human must make — or live work surfaces a fork you should not decide alone, do the analysis first, hand the human a complete, comparable packet, then ask. Lead with the compare/contrast in the same turn; don't...

GitHub meters REST and GraphQL separately — 5,000 points per hour each, tracked independently. Prefer the REST endpoint for anything REST can do, and reserve GraphQL for the work that has no alternative. If a GitHub Projects (V2) board is in use, that means protecting it above all: Projects V2 is...

This repository is worked from a single account, although the robot-council organization owns it, and the same is true of its sibling. Every pull request, issue, and comment posts under that one account: the same account authors the change, files the ticket, reviews the branch, and posts the...

A command that may run for minutes gets an explicit bound inside the command itself, and any process you are about to kill gets identified first. Neither the Bash tool's timeout parameter nor runinbackground stops work. They detach it. When the tool timeout fires, you get exit 143 and a...

Before you compare a measurement against a prior one, such as a suite time, a CI pass/fail, or a figure quoted in an issue, read the harness that produced the baseline and reproduce its whole job, not just its headline command. A number measured under different setup is not a comparison, and...

Emoji do not appear in anything this repo keeps. That covers issue and pull-request titles, bodies, and comments; commit messages; release titles and bodies, and the CHANGELOG.md entries made from them; every file under .claude/; and the README.

The required check answers one question: does the change pass tests, analysis, and style on the state it will merge into? Merging asks a different one: should this land on main? No check can answer that. Before merging any pull request, work the three steps below.