Guidelines Skills Laravel Package

Product Decisions This Supports

Treat it as a content artifact, not a dependency. The package ships four markdown skill files (spatie-laravel-php, spatie-javascript, spatie-version-control, spatie-security) that an AI coding agent reads. There is no service provider, no config file, no runtime code path. That framing drives every decision below: this is a low-cost, fully reversible process intervention, not an architectural commitment.

• Build vs. buy vs. fork. For "how our team writes Laravel," the options are (a) write and maintain our own convention docs, (b) adopt a vendor's codified conventions, or (c) fork and own. This package makes (b) the cheap default and (c) a genuinely viable fallback — MIT license, plain markdown, trivial to vendor into a repo. Decide explicitly which of the two you're doing; a half-forked setup where some skills come from vendor/ and some are local is the worst configuration.
• The real product problem it addresses: AI-generated code review churn. As AI-authored diffs grow as a share of our output, review time shifts from correctness to style archaeology. Codifying conventions upstream in the agent's context reduces the volume of style noise reviewers have to flag. That's a measurable throughput decision, not a tooling preference.
• Onboarding and contractor consistency. Written conventions inside the tool engineers already use beat a wiki page nobody opens. For a team with contractors or rotating contributors, this is the fastest lever on "code that looks like it came from us."
• Roadmap input: it's a floor, not a ceiling. Four skills cover Laravel/PHP, JS, git, and security. Nothing covers testing conventions, accessibility, CI configuration, deployment, or infrastructure. Treat the shipped set as a working template and put "author our own skills for the gaps" on the roadmap if we standardize on this pattern.
• Governance decision on updates. A guideline bump is a behavior change with no failing build to alert us. That means pinning the version, reviewing the markdown diff, and treating releases like a policy change rather than a patch bump.
• Distribution-channel decision. Composer gives a pinned version; npx skills add gives latest. Standardize on Composer for Laravel repos so every machine behaves the same.

What it does not do: it enforces nothing. It won't fail a build, won't catch env() in a controller, won't stop an agent from ignoring it. Do not let a compliance or quality-gate narrative attach to it — Pint and PHPStan remain the source of truth. Migrating the highest-value rules into CI gates is the durable play; the skill carries the stylistic residue.

When to Consider This Package

Adopt when most of these are true:

• We're a Laravel/PHP shop already using AI coding agents (Copilot, Cursor, Claude Code, similar) on real work.
• We're adopting or already using Laravel Boost — in which case the marginal cost is one composer require --dev and a prompt selection.
• Code review is a bottleneck and a meaningful share of review comments are style, not correctness.
• We have multiple squads, contractors, or new hires producing diffs that don't look uniform.
• Our conventions are currently tacit, stale, or scattered across old PR comments.

Look elsewhere, or skip, when:

• The stack isn't Laravel/PHP. Three of four skills assume it; the JS skill is a thin style layer.
• We already have strong, codified, CI-enforced conventions. The skill adds conflict surface with little upside — unless we're deliberately using it as a reviewer.
• We don't use AI coding agents at all. Value is zero; this is not a human-readable style guide (that's spatie.be/guidelines, free, and separate).
• We require vendor artifacts with support terms, SLAs, or an adoption base to point at. This is ~98 stars, 0 dependents, a handful of releases, single-vendor, no published roadmap for testing/accessibility/infra. It's a well-maintained content artifact from a respected source, not an industry standard. The mitigation is that forking is trivial — but go in knowing we may end up owning a fork.
• Our git conventions are entrenched and different (Conventional Commits, gitmoji). The version-control skill will contradict them. Cheap to resolve, but resolve it before enabling.

Evaluation cost: fifteen minutes. Install only the Laravel/PHP and security skills, ask an agent for a small conventional feature, and diff the output against the stated rules. That diff is the adoption decision.

How to Pitch It (Stakeholders)

To executives — one paragraph:

Spatie, a well-known Laravel consultancy, has published their internal coding standards as instruction files that our AI coding assistants read automatically. Installing it takes one dev dependency and about fifteen minutes, costs nothing, carries no runtime risk, and is reversible with a single revert. The payoff is less review churn on AI-generated code, faster onboarding for new engineers and contractors, and conventions that live in the tools people already use rather than in a document nobody reads. The risk is low and bounded: the license is MIT, the content is plain text we could fork and own, and nothing in our build or production system depends on it.

To engineering — the honest version:

• It's advisory. It shapes what the agent proposes; it does not enforce. Pint, PHPStan, Prettier, and CI gates stay exactly as they are and remain the source of truth.
• Precedence must be stated explicitly on day one. One line at the top of CLAUDE.md / AGENTS.md: project conventions override the skill; where silent, follow the skill; Laravel framework conventions override both. Undefined precedence is the most common real-world failure and it's a one-line fix.
• Two operational rules: pin the version and treat guideline bumps as reviewed changes (read the markdown diff), and pick one install channel per repo — Composer for Laravel repos.
• Align Prettier to the skill's four-space / 120-char / single-quote settings, or edit the skill's reference copy to match ours. Don't leave the mismatch — the agent and the formatter will fight on every file.
• If we disagree with specific rules, forking is cheap. Decide between tracking upstream and owning a fork, and budget a quarterly review pass if we own it.
• Don't let this become the only home for our conventions. Link the human-readable guidelines in onboarding docs.

Success signals to watch: review comment volume on style, Pint/PHPStan finding counts on AI-authored diffs, time-to-first-merged-PR for new hires, and the share of AI diffs that need style rework.