Boost Core Laravel Package

Getting Started

This is a dev-only CLI, not a runtime library — nothing ships to production and no service provider is required.

1. Read the machine-readable docs first. The README explicitly directs agents (and humans) to llms.txt (structured overview) and llms-install.md (step-by-step install). Read those before the docs site; they're the shortest path to exact command names. If you already use this package, read UPGRADING.md §1.12→1.13 before your next user-scope sync — that section is the difference between a working skill and a silent rename.
2. Install as a dev dependency: composer require --dev sandermuller/boost-core. It has no framework dependency, so it drops into Laravel, Symfony, or a plain PHP repo identically.
3. Scaffold .ai/. Your first real use case is one guideline and one agent: write a short guidelines/ file describing your coding conventions (test framework, naming, where things live), declare a single agent in withAgents() — the config surface is a fluent PHP builder, so start with whichever agent your team actually uses (Claude Code or Cursor are the usual entry points) — then run the sync command and inspect the generated files (typically CLAUDE.md or .cursor/rules/*.mdc). 4–5. Verify the artifact, then wire it into Composer. Confirm the generated file looks right in your agent, then add a composer ai:sync script (see below) so nobody has to remember the binary path.
4. Treat user scope as a second, later step. --scope=user is a different publishing model with its own paths, its own config file, and its own breaking-change history. Get project scope healthy first; then turn on user scope only if you install packages globally and want their skills available in every repo.

If you only do one thing: get a single guideline flowing to a single agent end-to-end before adding a second agent. The value of this package is the fan-out; debugging fan-out and source-of-truth problems simultaneously is miserable.

Implementation Patterns

Single-source authoring. Treat .ai/ as source and every agent's directory as build output. Skills, guidelines, and commands are authored once; the publisher rewrites them into each agent's expected format and path. Enforce this socially: PRs touch .ai/, never the generated files.

Know which scope you're in. Project scope writes into the repo (.ai/ → CLAUDE.md, .cursor/rules/, etc.) with names as authored. User scope writes into ~/.{agent}/skills/<skill>-user/SKILL.md — flat, one directory per skill, and suffixed so a user-scope copy can't hide a project skill of the same name. The two scopes have different naming, different ownership rules, and different cleanup behaviour; don't reason about one using the other's model.

Add agents incrementally. withAgents() is additive, so adoption can be per-developer rather than a team-wide migration. Start with one agent, add Cursor or Copilot when a specific teammate asks, and let the next sync produce only the new artifacts. This keeps diffs reviewable.

Curate user scope with ~/.boost/user-scope.php. This is the new allowlist for globally installed packages: list the skills a package should publish at user scope, and listing one also pulls in that package's metadata.boost-requires dependencies. A package with no entry still publishes every skill — so the file is opt-in narrowing, not opt-in publishing. BoostAutoSync::syncUserScopeOnce() re-syncs once after each edit to it, which makes the curation loop feel live.

Commit the output (recommended) or hook it. Two viable models for project scope:

• Commit generated files: teammates and CI agents get working config on clone without running sync, and drift shows up as a normal diff. Costs some repo noise and duplicate content.
• Gitignore + generate: cleaner history, but every clone needs a post-install step. Add "post-install-cmd"/"post-update-cmd" scripts calling the sync binary.

Pick one and put it in the README — mixed models produce phantom diffs that look like sync bugs. User-scope output should generally not be committed (it lives outside the repo) but should be reproducible from user-scope.php plus the installed global packages.

CI drift gate. Run the sync in CI and fail if git status --porcelain is non-empty afterward. Prefer --check where you can: it now predicts the same skill-name clashes a real --scope=user --all run would hit, so you get clash detection without writing to a HOME directory or racing other CI jobs.

Composer script as the ergonomic entry point:

"scripts": {
    "ai:sync": "@php vendor/bin/boost-core sync"
}

Guarded well enough that a --no-dev production install simply won't have the binary; don't call it from deploy hooks.

Upgrade as an explicit step. Because user-scope names are part of the public surface (slash commands, backticked skill names in prompts, links between skills), treat minor bumps as migrations: read UPGRADING.md, run a --check first, then a real sync, then inspect the reaped/renamed paths. A pinned version plus a drift gate turns a behavioural change into a visible diff.

Family packages for framework integration. The docs are organised one section per family package. If you're on Laravel and want Artisan-level integration, use the corresponding family package; boost-core is the framework-agnostic engine underneath. Don't reach for core if a family package already wires your framework's conventions.

Monorepos and shared guidelines. Because it's path-based and framework-free, you can run it from a subdirectory or compose a set of guideline sources — useful for keeping org-wide conventions in one place and project-specific rules in another, then publishing the union per package.

Gotchas and Tips

• 1.13.0 renames every user-scope skill — this is the breaking change. Nested ~/.{agent}/skills/<vendor>__<package>/<skill>/ is gone, replaced by flat ~/.{agent}/skills/<skill>-user/SKILL.md across all supported agents (nine at time of writing). /sandermuller__repo-init becomes /repo-init-user. Anything that hardcodes the old path, the old qualified name, or a saved slash-command invocation needs updating. Project-scope output is untouched: if you never pass --scope=user, the upgrade is a no-op for you.
• The nested layout was a real bug, not just a rename. Claude Code doesn't descend into nested skill folders, so most user-scope skills were invisible on 1.12.x — multi-skill packages silently published only partially. If user-scope skills "never worked" for you, that's why; don't go looking for a config problem that isn't there.
• Cleanup is best-effort — verify it. The first user-scope sync reaps the old nested copies, but a nested file you edited is left in place, as is a pre-0.4 ~/.{agent}/skills/<package-basename>/ folder (that migration was removed entirely). List the skills directory after upgrading and delete leftovers by hand.
• Ownership and symlinks are now enforced at user scope. A sync refuses to write over a file boost doesn't own, or over a symlink at a target path. Safe by default, but it means a hand-created ~/.claude/skills/foo-user/SKILL.md will silently block publication until you move it aside. Read the refusal, don't just re-run.
• Clashes are first-wins and order-dependent. Two packages publishing the same skill name: the alphabetically first package wins, the second reports the clash with the owner's name. --scope=user --all reaps removed packages before publishing, so a skill name can change owner in a single run — diff the output, don't assume a stable owner across package installs.
• Renamed cross-skill references only cover one package. Backticked names, slash commands, and relative .md skill links are rewritten for references between one package's published skills. A reference from package A's skill to package B's skill keeps the old name and breaks. Keep cross-package skill references out of your sources, or expect to fix them manually.
• An invalid ~/.boost/user-scope.php stops the sync and reaps nothing. Fail-safe, but it means an unrelated typo silently freezes all user-scope updates. If a sync "does nothing," check that file's error output first.
• Never hand-edit generated files. They are overwritten wholesale on the next sync. If you find yourself fixing CLAUDE.md (or a -user/SKILL.md), the fix belongs in .ai/ or user-scope.php. This is the single most common source of "my rule disappeared" confusion.
• Don't write agent-specific syntax in the source. Cursor rules use frontmatter, some agents expect plain Markdown, others JSON/TOML config. The publisher adapts format, so keep .ai/ sources format-neutral — or use explicit per-agent overrides if you genuinely need a Cursor-only glob. Mixing both silently produces mangled output on the agents you didn't test.
• Stale file cleanup still deserves a one-time test. When you remove an agent from withAgents(), confirm whether the previously generated project directory is pruned or orphaned. Test once with a throwaway agent entry before relying on config removal to clean up.
• Token budget is the real cost. Guidelines get prepended to prompts on every turn, and user-scope skills are now actually loaded — which means the bloat you carried invisibly on 1.12.x starts costing you on 1.13.x. Scope skills narrowly, keep guidelines terse, delete stale rules, and use user-scope.php to publish only the skills a package really needs. Adding an agent is cheap; bloating the source is not.
• Small-project risk profile. Pin the version deliberately, read the changelog on minor bumps (1.13.0 proves minor bumps can rename user-facing skill IDs), and keep the CI drift gate so a behavioural change shows up as a diff rather than as silently altered agent behaviour. It's MIT and self-contained, so forking is a realistic fallback.
• Line endings and .gitattributes. Generated Markdown on Windows/CRLF checkouts will fight your drift gate. Normalise * text=auto eol=lf for the generated paths.
• Don't symlink instead of publishing. Agents that read files by convention frequently don't resolve symlinks — and since 1.13.0 the user-scope sync actively refuses to overwrite a symlink target. You also lose the format translation that is the package's actual value.
• Debugging — project scope: run the sync verbosely (or dry-run), then inspect the actual file diff rather than the console summary. If output looks wrong, the problem is almost always an ambiguous or over-broad source file in .ai/, not the publisher.
• Debugging — user scope: ls ~/.{agent}/skills/ and confirm you see flat <skill>-user/SKILL.md directories. Seeing <vendor>__<package>/ nesting means a pre-1.13 artifact or a stale sync; seeing nothing means the skill wasn't selected, the clash went to another package, or the target file is owned by something else. Run --check before a real --all run to preview owners and clashes.
• Extension point: if your agent isn't among the supported set, the intended escape hatch is a custom publisher/agent class registered in config — cheaper than post-processing generated files with your own script.