boost-config-shape

name	boost-config-shape
description	Author a boost.php config file. Covers all five with* methods, when each matters, and what NOT to put in there.

boost.php config shape

When to apply

• Editing a project's boost.php by hand
• Asked "how do I configure boost-core?"
• Reviewing a PR that touches boost.php

The fluent shape

<?php

declare(strict_types=1);

use SanderMuller\BoostCore\Config\BoostConfig;
use SanderMuller\BoostCore\Enums\Agent;

return BoostConfig::configure()
    ->withAgents([Agent::CLAUDE_CODE, Agent::CURSOR])
    ->withAllowedVendors([
        'sandermuller/project-boost',
    ])
    ->withDisabledEmitters([])
    ->withSkillsPath(__DIR__ . '/.ai/skills')
    ->withGuidelinesPath(__DIR__ . '/.ai/guidelines');

Method semantics

• withAgents([]) — which of the 9 agents to fan out to. Empty array = skip fan-out (boost:sync becomes a no-op). Order doesn't matter.
• withAllowedVendors([]) — Composer package names whose resources/boost/{skills,guidelines}/ boost-core may read from. Empty = host-only. Non-allowlisted vendors are silently ignored even if they publish.
• withDisabledEmitters([]) — FQCNs of FileEmitter classes to skip even if their vendor is allowlisted. Use for opting out of optional emissions (e.g. you want skills from package-boost-laravel but not .mcp.json).
• withSkillsPath(...) / withGuidelinesPath(...) — host-authored content locations. Default to <project-root>/.ai/skills and <project-root>/.ai/guidelines. Override only if your project uses a non-conventional layout.

What NOT to put here

• Environment branching. if (env('CI')) { ... } works, but boost:install and boost:scan AST-edit this file and refuse on unexpected shape. Keep the file a single straight return.
• External require calls. Same reason — AST writer can't preserve side effects.
• Header docblocks above return. PHP-Parser's pretty-printer strips them on boost:install / boost:scan. Inline them in the starter template boost:install generates on first run instead.

Anti-patterns

• Catch-all agents list. Adding all 9 agents to a project you don't actually use is just file churn. Pick the ones you actually run.
• Allowlisting third-party vendors without inspecting them. Skills from allowlisted vendors influence AI behavior in your project — same trust boundary as any code dep. Use composer boost:doctor to see what would be published before allowlisting.
• Hand-editing during interactive commands. If you run composer boost:install and then hand-edit boost.php before the next boost:sync, your hand-edits win. But the AST writer's next invocation may not preserve formatting choices — commit before hand-editing so you can diff.

See also

• The starter boost.php template generated by composer boost:install on first run
• writing-file-emitter skill for emitter authoring