Laravibe Standards Laravel Package

Getting Started

• Install with composer require --dev thesoftpulze/laravibe-standards, then run the package's publish/install command to emit its config, stubs, and guideline files into your app (php artisan vendor:publish --tag=laravibe-standards is the usual shape — confirm the exact tags in the README, as v0.5.0 changed what gets published).
• Read the upgrade guide first. v0.5.0 ships a dedicated upgrade doc (docs: add upgrade guide from softpulze/laravibe-standards) because the migration from the old softpulze/laravibe-standards namespace is not a straight composer update. Follow it before touching a working project.
• Where to look first:
  1. The published config file — it drives which standards/skills are active.
  2. The generated guideline file(s) — this is the artifact your team and your AI tooling actually consume.
  3. The stubs/ directory — the templates new classes/files are scaffolded from.
• First use case: point it at a single, small Laravel app, publish the standards + Boost guideline, and diff the generated output against your existing conventions. That one diff tells you whether the package's defaults match your house style before you roll it out repo-wide.

Implementation Patterns

• Treat published files as project-owned code. Commit them. Once published, they are yours to edit; the package is a source of defaults, not a runtime dependency. This is the single biggest determinant of whether the package helps or fights you.
• Baseline-then-override. Publish the full default set, then narrow in config. Avoid editing generated files by hand in ways you can't re-derive — you'll need to re-apply those edits on the next release (see Gotchas).
• Boost guideline as the team contract. The new Boost guideline file is the natural place to codify "how we write Laravel here." Wire it into your AI assistant config (Laravel Boost / your agent's instructions file) and into onboarding docs so humans and tooling read the same rules.
• Skills are now split. v0.5.0 splits skills into separate units rather than one monolith. Consume them individually — pull only the skills relevant to a given repo instead of copying everything. This makes monorepos and multi-service setups much cleaner: a queue-worker service can take a different skill subset than an HTTP app.
• CI integration. Run whatever lint/format/analysis the published standards imply as a CI step. The stubs and collections define shape; your CI enforces it. Don't rely on reviewers catching drift.
• Pair it with Pint/PHPStan, don't replace them. Standards packages encode conventions; static analysis and formatting encode mechanics. Let each do its job.
• Upgrade ritual. On each release: read release notes → check for breaking changes → re-publish into a scratch branch → git diff against committed files → manually merge only the changes you want. Never blanket-overwrite.

Gotchas and Tips

• v0.5.0 is a breaking release. The changes are bundled into one commit (feat!: add Boost guideline, split skills, fix stubs and collections), so the blast radius spans three separate surfaces at once: guidelines, skills, and stubs/collections. Budget real time; don't slot this into a busy sprint.
• Package rename / namespace migration. The upgrade guide explicitly covers moving from softpulze/laravibe-standards. If you're on the old name, the install path, published tags, and possibly the config key all change. Remove the old package explicitly rather than leaving both installed — duplicate published tags produce confusing "file already exists" prompts.
• vendor:publish will silently skip existing files unless you pass --force. This is a feature, not a bug — it protects your edits. But it also means a naive re-publish after upgrading looks like nothing happened. Use a scratch branch + --force + diff, then cherry-pick.
• Stubs and collections changed. If you had customized stub files, expect merge conflicts or stale output. Regenerate a sample class after upgrading and eyeball it — broken stubs fail at scaffold time, not at test time, so they can slip through CI.
• Split skills means moved paths. Any hard-coded paths in your scripts, editor config, agent instructions, or CI that referenced the old monolithic skill file will 404. Grep your repo for the old paths as part of the upgrade.
• Debugging checklist when the generated output looks wrong: (1) config cache — php artisan config:clear; (2) stale published files from a previous version; (3) both old and new package installed; (4) wrong publish tag.
• Extension points: prefer config overrides and your own published copies over subclassing or monkey-patching package internals. Internal namespaces are the most likely thing to shift again in a 0.x series.
• It's still 0.x. Pre-1.0 packages in this space move fast and break things — v0.5.0 already proves it. Pin the version in composer.json ("thesoftpulze/laravibe-standards": "0.5.*") and upgrade deliberately, not via composer update on a Friday.