Download the PHP package sandermuller/boost-core without Composer

boost-core

AI agent configuration sync for any PHP project. Write skills, guidelines, and commands once in .ai/; boost-core publishes them to ten agents: Claude Code, Cursor, Copilot, Codex, Gemini, Junie, Kiro, OpenCode, Amp, Antigravity. No framework dependency.

Documentation: https://sandermuller.github.io/boost-core/ — the guide, one section per family package, and the full CLI and config reference.

What it does

• One .ai/ source, ten agents. Add an agent to withAgents() and its files appear on the next sync. You never maintain a per-agent copy.
• Skills distributed as Composer packages. Any package shipping resources/boost/skills/ becomes a skill source once you allowlist its vendor. Author a team's skill set once, composer require it everywhere.
• Per-project scoping. Tag filtering keeps a jira-triage skill out of repos with no Jira work, including out of the agent's skill-selection index, where every unwanted description costs attention.
• Skills that depend on skills. metadata.boost-requires makes a hand-off ("then run code-review") ship as a unit instead of breaking silently.
• Skills straight from GitHub. boost remote <owner>/<repo> reads a repo and lets you pick from a checklist.
• Nothing hand-written gets clobbered. boost-core tracks what it owns in a manifest. Adopting it in a repo that already has a CLAUDE.md won't wipe it.

It runs on any PHP project: Laravel, Symfony, plain PHP, or a package.

How sync works

You author three kinds of content under .ai/, and boost sync fans each out to every agent you selected in withAgents(...):

Skills and commands land in gitignored per-agent directories; the guidance files stay tracked. See File ownership for why.

Install

boost-core is the engine. You rarely install it directly. Instead you install the family package (a thin wrapper that bundles boost-core with a curated skill set) that matches what you're building, and it pulls boost-core in.

Only the last row installs the bare engine:

Don't want to pick? Paste this prompt to your coding agent from the repo root. It picks the right family member, installs it, configures agents + tags, and verifies. Nothing installs until it runs composer require:

Quickstart

Config lives at boost.php (repo root) or .config/boost.php; see File ownership for the layout details. A minimal config:

boost-core is a plain library and runs no install-time code of its own. Run vendor/bin/boost sync yourself (e.g. in CI), or wire the autosync hook to re-sync on composer install.

Skill sources

Skills come from three places, all resolved on the same composer install / update lifecycle and fanned out side by side:

1. Host — your project's own .ai/skills/.

2. Vendor packages — any Composer package that ships resources/boost/skills/<name>/SKILL.md. Allowlist the vendor to pick it up:

   This is how a team distributes one curated skill set across many repos: author once in a package, allowlist everywhere. sandermuller/boost-skills is one example of the pattern.

3. Remote sources — GitHub repos shipping .skill release bundles or skill subdirs, declared with withRemoteSkills() or picked with boost remote.

Remote skill sources

Point boost remote at a GitHub repo and pick what you want:

It resolves the ref and works out whether the repo ships .skill release assets or skill directories. Then it reads each skill's frontmatter and shows a checklist with descriptions, tags, and any clash with a skill you already receive. Checked skills land in withRemoteSkills(); unchecked ones are removed. The command also adds any dependencies the same repo publishes, and offers to declare the tags a picked skill needs to survive your withTags() filter.

See the remote skills docs for writing withRemoteSkills() entries by hand, the --ref and --mode flags, the cache, offline behavior, rate limits, the trust model, and publishing a source.

Tag filtering

Tags scope a vendor skill to the projects that want it, so a project with no Jira work never receives a jira-triage skill, and its description never pollutes the agent's skill-selection index.

A skill declares tags in its SKILL.md frontmatter:

A project declares the tags it wants in boost.php:

The rule: a vendor skill ships only when every tag in its boost-tags is among the project's withTags() (skillTags ⊆ projectTags). An untagged skill always ships, so the feature is inert until skills and projects opt in. Vendor guidelines filter the same way. vendor/bin/boost tags lists every tag your installed packages declare and what you'd unlock by adding it.

[!WARNING] Adding a tag to an already-shipped skill is consumer-breaking: every project that hasn't declared that tag loses the skill. Treat it as a breaking change.

Skill dependencies

A skill that hands off to another skill ("then run the code-review skill") breaks silently when that other skill doesn't ship. Declare the dependency and boost ships the two together:

The rule: whenever a skill ships, every name in its boost-requires ships too. A dependency that tag filtering would have dropped is rescued: the author's "this skill is broken without it" outranks topic scoping, so it ships anyway. Rescue is transitive, and sync reports each one as an INFO diagnostic.

Declare only hard hand-offs, meaning flows that invoke the other skill. A conditional reference ("where the project has quality-check skills synced, delegate to them") must stay undeclared, or rescue drags unrelated tooling into projects that scoped it out.

See the tags and dependencies docs for both features in full: the guideline sidecar manifest, withExcludedSkills() precedence, missing and malformed requires, cycles, and tracing with boost where.

Commands

.ai/commands/*.md holds reusable prompt templates: the slash-command files agents surface in their palette. boost sync fans each out to the seven agents that have a command surface: Claude Code, Cursor, Copilot, Junie, OpenCode, Amp, and Kiro. Codex and Gemini have no committable command target, so boost doctor prints the manual authoring path when you select one of them.

You author argument placeholders once in the canonical syntax ($ARGUMENTS, $1/$2, $name, and \$ for a literal $), and sync converts each to the agent's native shape.

See the commands docs for the per-agent target paths and the full placeholder table.

Skill rendering

Skill files default to plain markdown (SKILL.md). For template-flavored content (Blade, Twig, anything needing a render step), register a SkillRenderer in boost.php:

The dispatcher matches longest-extension-first, so a BladeRenderer claiming blade.php handles SKILL.blade.php. The built-in PassthroughRenderer always handles .md. A source whose extension has no registered renderer is flagged by boost sync and boost doctor instead of silently vanishing.

See the skill rendering docs for failure handling, BOOST_RENDER_STRICT=1, and writing your own renderer against the @api contract.

Automating the sync

boost-core ships no Composer plugin, so a composer install re-sync is opt-in. Wire the hook yourself:

run is silent on a true no-op, so output appears only when something changed or errored. BOOST_SKIP_AUTOSYNC=1 turns it off.

[!IMPORTANT] On Laravel + project-boost-laravel, use @php artisan project-boost:sync instead. The artisan path runs through the Laravel container, which bootstraps BladeRenderer and delivers laravel/boost's bundled skills to every agent. The bare-CLI path bypasses both.

See the automating sync docs for the other entry points: runWithSummary for user-invoked scripts, syncUserScopeOnce for a globally-installed CLI tool that self-syncs, and the --scope=user sync.

Project Conventions

Vendor skills often need project-specific context: a Jira key, a branch pattern, a test runner. Project Conventions injects it via a JSONSchema slot fill-in. Vendors declare slots in resources/boost/conventions-schema.json; consumers fill them in boost.php:

Skills consume a slot either with an inline <!--boost:conv path="…" mode="…"--> token, resolved into the emitted file, or via the rendered ## Project Conventions block in CLAUDE.md. boost validate --strict hard-fails CI on a leaked token.

See the conventions docs for the full reference: inline tokens, the paired visible-default form, observability, legacy-ref migration, and migrating vendor skills.

File ownership

boost-core generates files into your repo and home directory and tracks what it owns in a manifest, so a sync never silently overwrites hand-written content:

• Guidance files (CLAUDE.md, AGENTS.md, GEMINI.md, Copilot) are wholesale boost-owned, markerless, and regenerated from .ai/guidelines/ on every sync, but kept tracked so output is reviewable in diffs. Author guidance in .ai/guidelines/, never by hand-editing the target.
• Skill + command directories are gitignored (100% generated from .ai/). boost deletes only what its manifest records there, so a file another tool installed alongside its own — laravel/boost puts its bundled skills in the same directories — is preserved, not swept.
• A file you've hand-edited (sha diverged from the manifest) is never blanked or reaped. Adopting boost-core in a repo with an existing CLAUDE.md won't wipe it.
• Removing a vendor dep or de-selecting an agent reaps the now-orphaned files it owned.

See the file ownership docs for the manifest, lifecycle reap, files another tool wrote into a managed directory, the empty-assembly guard, .config/ layout + relocation, managed .gitignore, and user-scope cleanup-on-remove.

CLI reference

Exit codes: 0 ok, 1 failure, 2 usage. boost doctor is advisory, so gate CI on sync --check / validate --strict instead.

Environment variables

Every variable is opt-in; unset = default behavior.

Versioning & stability

boost-core follows Semantic Versioning, and the promise covers the public surface only: the config authoring API, the CLI (command names, documented options, exit codes), the BoostAutoSync Composer hooks, and the plugin contracts. Everything marked @internal (the whole engine) and all on-disk regenerable state may change in any release.

PUBLIC_API.md enumerates the committed surface in full. From 1.0.0 on, breaking changes land only in a MAJOR bump and are called out in UPGRADING.md.

More

Full documentation for boost-core and every family package is at https://sandermuller.github.io/boost-core/.

• Guide — how sync works, skill sources, tags, conventions, file ownership
• CLI reference — every command, option, and exit code
• Configuration reference — every BoostConfig method
• Remote skills — remote GitHub skill sources in full
• Tags and dependencies — tag filtering and boost-requires in full
• Commands — command fan-out targets and argument placeholders
• Skill rendering — SkillRenderer dispatch, failure modes, authoring
• Automating the sync — Composer hooks, self-syncing CLI tools, user scope
• Project Conventions — the slot reference
• File ownership — the manifest, reaping, .config/ layout
• llms.txt — structured overview for AI agents (what this package is, key docs)
• llms-install.md — step-by-step install guide an agent can execute
• UPGRADING.md — breaking-change migrations between versions
• releases page has per-version notes)
• CONTRIBUTING.md — dev setup, test conventions, pre-release gauntlet
• PUBLIC_API.md — the frozen semver surface in full

Testing

Security

Email security issues to [email protected] rather than filing a public issue. See SECURITY.md for the disclosure policy.

Credits

• Sander Muller
• All contributors

Heavily inspired by laravel/boost. It's the framework-free sibling.

License

MIT. See LICENSE.