Statamic Boost Laravel Package

Getting Started

chrisvasey/statamic-boost is a dev-only bridge that teaches Laravel Boost (and the AI assistants wired into it) about Statamic: it ships offline Statamic 5/6 documentation, generates AI guidelines for your project's fields, fieldtypes and Antlers usage, and registers Statamic-aware MCP tooling.

composer require --dev chrisvasey/statamic-boost
php artisan boost:install     # or: php artisan boost:update on an existing Boost setup

Where to look first:

1. The generated guidelines directory (typically .ai/guidelines/ or boost/guidelines/) — this is the artifact the assistant actually reads. Open the Statamic file and skim it before you trust any AI output; if the Antlers examples look wrong, nothing downstream will be right.
2. Boost configuration (config/boost.php / the Boost install manifest) — confirm the Statamic environment is recorded correctly, especially if you pass --env to Statamic commands.
3. The bundled offline docs in the package's docs/ or resources/ directory — they're pinned to a specific upstream Statamic version and are the source of truth for what the assistant "knows".
4. php artisan list | grep -E 'boost|mcp' — confirms which Boost/MCP commands your installed combination actually exposes.

First use case: after boost:install, ask your assistant to scaffold a new fieldset with a custom fieldtype and its Antlers template. Compare the output against the generated guideline file. That single loop tells you whether the integration is wired correctly and whether the docs match your Statamic version — if either is off, you'll see it immediately rather than three files deep in a refactor.

v1.3.0 is a good baseline to start on: it explicitly supports Boost 2 installations on laravel/mcp ^1.0.1, and CI now covers fresh installs on PHP 8.5 / Laravel 13 / Statamic 6.

Implementation Patterns

Commit the generated guidelines. Treat AI guidelines like migrations — regenerate deliberately, review the diff, commit. This gives you a reviewable record of what your assistant was told and makes guideline drift visible in PRs. If you'd rather not commit, at minimum regenerate in CI and diff against a cached copy to catch unexpected changes after a composer update.

Regenerate after every content-model change. New fieldtype, renamed field handle, changed Antlers partial convention, new collection — regenerate and commit in the same PR as the change. Stale guidelines are worse than no guidelines because the assistant argues with you confidently.

Layer project guidelines on top of the package's output. The package generates Statamic-domain knowledge (fieldtypes, Antlers syntax, docs). Keep your house rules — naming conventions, where partials live, which addons are banned — in a separate, hand-written guideline file that the generator never touches. This survives regeneration and is the extension point you'll actually use.

Wire it into CI as an installation smoke test. The release notes added fresh-install CI upstream; mirror that cheaply in your own pipeline: install the package on a throwaway app, run the installer, assert the exit code is 0 and the expected guideline files exist. v1.3.0 fixed installer failures not being returned correctly, so exit-code checks are now meaningful — before this, a broken install could look green.

- run: composer require --dev chrisvasey/statamic-boost
- run: php artisan boost:install --no-interaction
- run: test -f .ai/guidelines/statamic.md

Use the MCP server for day-to-day work, the files for review. Point your editor's MCP client at the Boost MCP process so the assistant can query Statamic's schema live (collections, fieldsets, blueprints) rather than guessing. Keep the generated markdown as the human-auditable artifact and as the fallback when the MCP process isn't running.

Schedule the docs updates. Since v1.3.0, documentation refreshes ship as weekly minor releases. A weekly composer update chrisvasey/statamic-boost --with-dependencies in dev keeps the offline docs aligned with upstream Statamic without you thinking about it — and because it's a require-dev package, that churn never reaches production.

Multi-environment setups: verify after every rebuild. Boost rewrites its configuration when it regenerates; v1.3.0 fixed the case where your selected Statamic environment was lost. If you run boost:install against a non-default environment (staging, a multisite config, a .env.statamic variant), check the config immediately after any regeneration step in CI or local setup scripts.

Gotchas and Tips

• It's a dev dependency — keep it there. --dev and nothing else. Shipping it to production drags MCP tooling and a docs tree into your deploy artifact. If a shared host or a naive deploy script runs composer install --no-dev, the package correctly vanishes; make sure nothing in your app references generated guideline paths at runtime.
• Version-constraint friction is the historical failure mode. v1.3.0 specifically fixes "current Laravel Boost 2 installations with laravel/mcp ^1.0.1" — meaning older releases could hard-conflict during composer update. If you're pinned to an older tag and see an MCP constraint conflict, upgrading to v1.3.0 is the fix, not --ignore-platform-reqs.
• Regeneration overwrites; edits to generated files disappear. Never hand-edit a generated guideline. Put customizations in a separate file, or in a post-generation script. Debugging "the AI keeps doing X" almost always ends here.
• Environment preservation is fixed, not impossible to re-break. The release preserves the selected Statamic environment across config rebuilds. Still treat it as a thing to assert: a one-line check in your setup script that the environment value in the Boost config matches $STATAMIC_ENV costs nothing and catches regressions on the next upgrade.
• Installer exit codes now mean something. Before v1.3.0, installer failures weren't returned correctly, so set -e scripts and CI steps could pass on a broken install. If you have existing CI that ran the installer without checking the code, it wasn't actually testing anything — revisit it.
• Fieldtype discovery and Antlers examples were both broken pre-1.3.0. If you previously gave up on AI-generated Antlers because the output used the wrong tag syntax, or your custom fieldtype never appeared in the generated guidelines, retest on this release before building workarounds. Check that your custom fieldtypes are registered through the normal Statamic addon/fieldtype mechanism — discovery reads registration, not directory layout.
• Offline docs are pinned, and pinning cuts both ways. The bundled docs point at fixed upstream source links and carry their licenses, which is great for reproducibility and offline use — but it means the assistant's knowledge is only as fresh as your last composer update. When the assistant cites Antlers behavior that contradicts current Statamic docs, the package is stale, not the model.
• Expect weekly minor releases. v1.3.0 establishes the automatic documentation release baseline: weekly doc refreshes, a tracking issue per newly detected upstream major, read-only doc dry runs on PRs. Pin with a caret constraint, update weekly in dev, and never be surprised by a 1.x bump — they're documentation changes, not API changes.
• Verify your own matrix before assuming support. The CI additions cover fresh installs on PHP 8.5 / Laravel 13 / Statamic 6 / Boost 2, and earlier lines cover Statamic 5. If you're on Statamic 4, or a PHP version outside the tested set, install once on a branch and confirm the generated guidelines actually contain your Statamic version's docs — the package will install happily on combinations it doesn't test.
• Debugging checklist when output looks wrong: (1) which Statamic version do the bundled docs claim? (2) does the generated guideline file list your fieldtypes? (3) did you regenerate after the last blueprint change? (4) is the MCP process serving a cached config? Restart the MCP process after regeneration — clients hold the old schema happily.