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 nine agents: Claude Code, Cursor, Copilot, Codex, Gemini, Junie, Kiro, OpenCode, Amp. No framework dependency.

Contents

• What you get
• Skill rendering
• File ownership
• Versioning & stability

How sync works

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

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.

Let your AI agent install it

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:

Prefer to choose yourself? Use the table below.

Most users install a wrapper from the table above. Only when you want the bare engine — the last row, where you supply your own skills — install boost-core directly:

Coexists with laravel/boost in Laravel projects via project-boost-laravel.

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.

What you get

The MCP server (Model Context Protocol) + Laravel docs API are laravel/boost's domain, so boost-core defers to them in Laravel projects (see project-boost-laravel for coexistence).

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() (below).

Remote skill sources

Each fetched skill fans out exactly like host and vendor skills: same layout, same withTags() filtering, same withExcludedSkills(['<owner>/<repo>:<name>']) deny-list. Removing an entry prunes its output on the next sync.

• Cache. Bundles and tarballs land under ${BOOST_CACHE_HOME:-${XDG_CACHE_HOME:-$HOME/.cache}}/boost/remote-skills/. Pinned refs (a tag or 40-char SHA) cache forever; moving refs (main, a branch) re-resolve every 24h.
• Offline. boost sync --check never hits the network. boost doctor lists every source, flags moving refs, and reports cache presence.
• Rate limit. Anonymous GitHub caps at 60 req/h. Set BOOST_GITHUB_TOKEN (any token with public_repo scope) to lift it to 5000/h. Cold CI runs and boost doctor over many sources need it.
• Trust. Sources are opt-in by full path: peterfox/agent-skills:composer-upgrade grants access to nothing else in the repo. Pin to a tag or SHA in production; moving refs are convenient, but a source-side push silently changes what lands. Archive extraction rejects path traversal, absolute paths, symlinks, and oversized payloads (200 MB total / 50 MB per file / 10000 entries), and any violation rejects the whole source rather than extracting part of it.
• Strict mode. BOOST_REMOTE_STRICT=1 escalates any source failure to a sync-aborting error. Default is warn-and-skip.

Publishing a source for remote consumption: treat the SKILL.md frontmatter name as durable public API (renaming breaks moving-ref consumers), keep source dirs symlink-free (extraction rejects any symlinked entry), and align metadata.boost-tags with the family's tag vocabulary.

Tag filtering

Vendor skills can be scoped to projects that want them, 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. One exception: a tag-dropped skill that a shipping skill declares in its boost-requires is pulled back in — see Skill dependencies. withExcludedSkills() drops a specific vendor/package:skill-name regardless of tags. Vendor guidelines filter the same way, tagged either by metadata.boost-tags or a sidecar resources/boost/guidelines/.boost-tags.yaml manifest (for guidelines that must stay frontmatter-free for laravel/boost).

The Tag enum is just a convenience; the vocabulary is open, and any string is a valid tag. vendor/bin/boost tags lists every tag installed skills/guidelines declare, which your withTags() filters out, and what to add to receive them; boost install's interactive picker offers the same. When sync drops tagged skills because withTags() is empty, it prints a one-line nudge at boost tags.

[!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.

Use boost where to trace where every resolved skill, guideline, and command comes from (host / vendor / remote), with host-override shadowing annotated inline. boost where --diff=<name> prints a unified diff between a host override and the vendor copy it shadows.

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. Sync reports every rescue as an INFO diagnostic, and rescue is transitive — a rescued skill's own requires ship as well.

The details:

• Bare names, not vendor/package: keys. Dependencies bind to the name: a host .ai/skills/ override of the dep satisfies it, and any provider can.
• withExcludedSkills() wins. An exclude removes that provider's copy from consideration; if no other provider holds the name, sync warns and the dependent ships degraded — rescue never overrides an explicit deny.
• Missing deps warn, never fail. A require naming a skill that exists nowhere is a sync warning + boost doctor finding, not an error.
• Cycles are legal. a ⇄ b simply co-ships.
• Malformed boost-requires (not a string) warns at sync and is an error in boost validate --strict — unlike boost-tags, it does not fail closed, because requires gate completeness, not scoping.

Authoring guidance: declare only hard hand-offs — flows that invoke the other skill. Conditional references ("where the project has quality-check skills synced, delegate to them") and routing notes ("NOT for X — use Y") must stay undeclared, or rescue drags unrelated tooling into projects that scoped it out via tags. boost validate -v flags requires that cross a tag boundary, so the choice stays deliberate.

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 with a command surface:

Codex and Gemini have no committable command target boost-core can write into (Codex's prompts are deprecated/personal-only, Gemini uses TOML). When .ai/commands/ is populated and one of those agents is selected, boost doctor prints the manual authoring path so the gap isn't silent. Override the source dir with ->withCommandsPath(...).

Argument placeholders are transpiled per-agent. Author once using the canonical syntax: $ARGUMENTS (unsplit), $1/$2/… (positional), $name (named, optionally declared in frontmatter arguments:), and \$ escapes for literals. On sync, boost-core converts each to the agent's native shape (Claude $0-indexed, Copilot ${input:…}, and so on). Cursor and Amp have no placeholder support and emit verbatim with a warning. The bundled command-arguments skill documents the full 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. Render failures default to warn-and-skip (recorded in SyncResult::errors); BOOST_RENDER_STRICT=1 escalates the first failure to a sync-aborting error. A source whose extension has no registered renderer (e.g. a SKILL.blade.php with no BladeRenderer) is flagged by boost sync and boost doctor. Register a renderer for it, or rename it to SKILL.md.

The SkillRenderer contract is @api (locked at 1.0). Plugin authors writing renderers, FileEmitters, or a BoostWrapperContract should work from PUBLIC_API.md, which pins the frozen contract surface.

Automating the sync

boost-core ships no Composer plugin, so a composer install re-sync is opt-in. Pick the entry point that fits:

All three honor BOOST_SKIP_AUTOSYNC=1.

Composer hook (consumer project)

run checks Event::isDevMode(), resolves the bin-dir, runs vendor/bin/boost sync, surfaces non-zero exits through Composer's IO, and is silent on a true no-op (wrote=0, deleted=0). Output appears only when something changed or errored. runWithSummary prints the one-line success summary on every sync, including the no-ops run keeps quiet (useful when debugging "did the hook fire?"). Both work on Windows + Unix.

[!IMPORTANT] On Laravel + project-boost-laravel, use @php artisan project-boost:sync instead of BoostAutoSync::run. 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 project-boost-laravel's install guide for the canonical scripts shape.

CLI tool you publish (self-sync from bin script)

A tool installed with composer global require keeps its own bundled skills current by self-syncing from its bin script:

syncUserScopeOnce() runs a user-scope sync the first time it sees a given version, then writes a per-version sentinel so later runs are free. syncUserScope() is the ungated form. Both never throw, so the tool keeps running even if its sync fails.

After composer global require-ing skill-bearing packages, run vendor/bin/boost sync --scope=user --all once to user-scope-sync every globally installed package that ships resources/boost/skills/, into ~/.{agent}/skills/<vendor>__<package>/<skill>/SKILL.md. User scope publishes a package's skills wholesale: there's no boost.php, so tag filters and the vendor allowlist (both project-scope controls) don't apply. Removed packages are reaped on the next --all run; see File ownership.

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; boost slots / boost where --conventions audit what's set.

See docs/conventions.md for the full reference: inline tokens, the paired visible-default form (survives resolver-less engines like laravel/boost), 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/).
• 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 docs/file-ownership.md for the manifest, lifecycle reap, 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. The promise covers the public surface only:

• Config authoring API — BoostConfig::configure(), the BoostConfigBuilder with*() methods, the Agent / Tag enums, and RemoteSkillSource.
• CLI — command names, documented options, and exit codes.
• Composer hooks — BoostAutoSync::run / runWithSummary (new parameters always optional-with-default).
• Plugin contracts — FileEmitter, SkillRenderer, BoostWrapperContract and their DTOs. Parameterless constructors only.

Everything marked @internal (the whole engine) and on-disk regenerable state (the sync manifest, ledgers, runtime dirs) may change in any release. The full committed surface is enumerated in PUBLIC_API.md. From 1.0.0 on, breaking changes land only in a MAJOR bump and are called out in UPGRADING.md.

More

• 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.