// Use when developing Laravel packages with Orchestra Testbench. Activates: writing package code, running package tests, working with testbench, configuring service providers; mentions: package, testbench, package development, service provider.
Use when prepping package release, `.gitattributes` missing/thin, or keeping `composer archive` / Packagist `--prefer-dist` tarballs lean. Activates: lean dist, gitattributes, export-ignore, dist size, packagist tarball, composer archive bloat, lean-package-validator, stolt lpv, AI files in dist, .ai shipping to dist, .claude in tarball, CLAUDE.md in tarball, AGENTS.md in tarball.
MUST USE when authoring an AI skill — creating a new SKILL.md, naming a skill, or deciding where one lives. Covers namespacing across host/vendor/shipped skills, auto-activating frontmatter, `.ai/skills/` vs `resources/boost/skills/` choice, and `boost sync` regen. Activates: creating a skill, adding a skill, drafting a SKILL.md, naming a skill, choosing where a skill lives, editing `.ai/skills/**/SKILL.md` or `resources/boost/skills/**/SKILL.md`; mentions: skill, SKILL.md, skill name, skill namespace, skill collision, vendor skill, shipped skill.
Pre-push / pre-release checklist. Local quality gates → docs audit → commit + push → watch CI → draft release notes once CI is green. Activate before: pushing release-bound commits, tagging a release, drafting release notes, or when user mentions: pre-release, pre-push, release checklist, ship, cut release, release notes.
Use when CI matrix has gone red and needs diagnosis. Activates: ci matrix fail, matrix red, prefer-lowest fail, prefer-stable fail, dependency conflict, composer resolve, version excluded, security-advisories floor, testbench phpunit interlock, matrix cell regression; mentions: a specific cell failing in GitHub Actions.
Use when writing/reviewing package code spanning multiple Laravel or PHP majors. Activates: adding dependency, framework API across range, composer constraints, version-guarded code; mentions: composer constraint, illuminate/support version, laravel version matrix, backwards compatibility, version guard, feature detection, minimum laravel version, support older laravel, testbench.
Use when writing or improving README files. Covers required sections, structure, voice, staleness-audit pattern. Laravel-package conventions in `references/laravel-package.md`. Activates: writing a README, improving an existing README, auditing a README for staleness; mentions: readme, README.md, project documentation, package docs.
| name | package-development |
| description | Use when developing Laravel packages with Orchestra Testbench. Activates: writing package code, running package tests, working with testbench, configuring service providers; mentions: package, testbench, package development, service provider. |
This is a Laravel package, not a full application. There is no artisan, no app/ directory, no database by default.
vendor/bin/testbench Instead of artisan| Do NOT use | Use instead |
|---|---|
php artisan test | The package's configured test runner (vendor/bin/pest or vendor/bin/phpunit) |
php artisan tinker | vendor/bin/testbench tinker |
php artisan make:* | Create files manually in src/ |
laravel/boostSkip these rows if the package doesn't depend on laravel/boost.
| Do NOT use | Use instead |
|---|---|
php artisan boost:install | vendor/bin/testbench boost:install |
php artisan boost:mcp | vendor/bin/testbench boost:mcp |
src/ — package source code (PSR-4 autoloaded)tests/ — test suiteconfig/ — publishable config files (if any)resources/ — views, translations, Boost skillsdatabase/ — migrations and factories (if any)Check composer.json autoload.psr-4 for the exact namespace mapping.
Tests run via Pest or PHPUnit with Orchestra Testbench providing the Laravel application context. The base test case is typically Orchestra\Testbench\TestCase.
To register the package's service provider for tests, look for getPackageProviders() in the test base class or testbench.yaml providers.
Activate the cross-version-laravel-support skill when writing or
reviewing version-sensitive code. ci-matrix-troubleshooting covers
the workflow once a matrix cell has gone red.
The .ai/ directory is the source of truth for AI tooling:
.ai/
├── guidelines/ # Always-loaded context (*.md)
└── skills/ # On-demand skills
└── {name}/SKILL.md
After editing files in .ai/, sync to agent directories:
vendor/bin/boost sync
This copies skills to every selected agent's skill dir (.claude/skills/, .cursor/skills/, .agents/skills/, .github/skills/, .junie/skills/, .kiro/skills/) and writes guidelines into CLAUDE.md, AGENTS.md, and GEMINI.md. Use package-boost:install to narrow the agent set if you don't need all 9. Commit the generated files alongside the .ai/ sources — they ship with the package.
Verify CI and local state are in sync:
vendor/bin/boost sync --check
Exits non-zero when generated files drift from sources. Use in CI to catch commits where .ai/* was edited but generated files weren't re-synced.
Register the sync as a post-autoload-dump composer hook so composer install / update / dump-autoload catch "forgot to sync" mistakes on the contributor's machine — see the Composer auto-sync hook section in the package README for the recommended strict / auto-fix / Boost-less snippets.
Quick reference for adding content under .ai/.
.ai/guidelines/*.md. No frontmatter
required.sortByName across the sources dir).<package-boost-guidelines> block
in CLAUDE.md / AGENTS.md / GEMINI.md..ai/skills/{name}/SKILL.md — one directory per skill.name and description (required); body is
markdown.description is the trigger surface: list the natural-language
phrases that should activate the skill. Claude Code's matcher
scores against this text, so be explicit about intent.Inside the block, package-boost's shipped foundation renders first,
then a --- horizontal rule separator, then the host package's own
.ai/guidelines/*.md in filename order. Only one source present?
Divider is omitted.
Add the unwanted guideline's key to excluded_boost_guidelines in
the published config/package-boost.php. Keys match Boost's
GuidelineComposer convention (foundation, livewire/core, etc.).
See the README's Customising excluded guidelines section for the
publish command and config path.
readme skill — generic and Laravel-specific README authoring + staleness audit pattern.release-notes skill — drafting GitHub release bodies / release notes for tagged versions.