Repo Init Laravel Package

Getting Started

repo-init is a scaffolding/consistency tool for Laravel repositories: it writes stubs (agents, Boost config, skills, CI files) into a repo and can re-run over an existing one to bring it up to the current template. Day-to-day it replaces "copy the setup from that other project" with a single command.

1. Install it as a dev dependency (composer require --dev sandermuller/repo-init) so it never ships to production.
2. Run the init command against a target preset — for a Laravel app that's the laravel-project preset, which is where all of 1.20.0's changes land.
3. Read UPGRADING.md before the first run on an existing repo, not after. The 1.19.x → 1.20.0 section describes what the upgrade will ask you about (the project-boost-laravel wrapper, the new skills, the voice tag), and knowing the prompts ahead of time turns a confusing interactive run into a two-minute task.
4. Keep references/remote-skills.md open in a tab for the first week. It's the canonical explanation of how remote skills are declared, pinned, and excluded — every "why did this skill get added?" question is answered there.

First use case: scaffold a brand-new Laravel app and immediately get a working Boost setup — correct agent names (copilot, codex), the Cloudflare security-audit skill pinned, and sandermuller/boost-skills present with the voice tag applied. That's the fastest way to see what the package actually produces before you point it at a repo you care about.

Second use case, and the one that pays for the package: run the upgrade path on an older scaffolded repo and let it reconcile config instead of hand-editing boost.json.

Implementation Patterns

Treat presets as the unit of standardisation. Pick one preset (laravel-project) and use it everywhere. The value of this package is uniformity across repos; mixing presets or hand-tweaking generated files per repo destroys that and makes upgrades non-deterministic.

Declare skills centrally, pin deliberately. Remote skills go in via withRemoteSkills() with a commit SHA. Put your team's standard set there rather than adding skills ad hoc in individual repos — that's the whole point of the 1.20.0 change. When a skill needs updating, bump the SHA in one place and let the upgrade flow propagate it.

Use withExcludedSkills() as the pressure valve. The new security-audit skill is added by default and the audit flags its absence as MEDIUM severity. If a repo genuinely shouldn't have it (e.g. an internal tool with no web surface), exclude it explicitly rather than deleting the generated file — the explicit exclusion survives upgrades, a deletion doesn't.

Sequence the upgrade correctly. The 1.20.0 upgrade for project-boost-laravel has an order that matters: it runs project-boost:reconcile first, then adds the wrapper, and it preserves your existing agents, tags, and vendor skills. Don't short-circuit this by adding the wrapper to composer.json yourself beforehand — you'll end up with a wrapper around an unreconciled config and the upgrade prompt will behave unexpectedly.

Two-phase adoption for existing repos. Run the upgrade in a throwaway branch first, diff the output, then apply. The upgrade rewrites boost.json and adds a .config/boost.php stub; reviewing that diff is where you catch a preset mismatch before it spreads.

CI drift check. Run the tool in dry-run/check mode in CI on scaffolded repos and fail the build when output differs from what's committed. This catches "someone hand-edited boost.json six months ago" before it becomes a merge conflict during the next upgrade.

Keep upgrade prompts out of automation. The 1.20.0 upgrade path is deliberately interactive (it asks before adding the wrapper). Drive upgrades manually or via a scripted --no-interaction path with answers pre-decided — don't let an unattended pipeline hit a prompt and hang.

Gotchas and Tips

• SHA pinning is a double-edged sword. Pinning to a commit means skills are reproducible, but if upstream force-pushes or deletes the commit your scaffold breaks with a confusing fetch error. When a skill fails to install after an upgrade, check the SHA first.
• The voice tag is always-on for laravel-project. You can't toggle it off via the skill-tag picker — the picker now applies to this preset, but voice is unconditional. Don't waste time looking for the switch; exclude or accept it at the skill level.
• Agent name drift is a real failure mode. 1.20.0 fixed stubs/laravel-project/boost.json to use the current laravel/boost names (copilot, codex). If you have a fork or a local override of that stub from before, it still carries the old names and Boost will silently ignore the agent. Re-publish the stub rather than patching it.
• Preserve-before-add is intentional. The upgrade keeps existing agents, tags, and vendor skills. If you want a clean slate, say so explicitly — the default won't give it to you, and assuming otherwise leads to "the upgrade did nothing" reports.
• project-boost:reconcile is the recovery lever. If a repo's Boost config is inconsistent after a partial upgrade, run reconcile directly instead of hand-editing. Nearly every state the upgrade can leave you in is fixable by reconcile plus a re-run.
• Audit severity is MEDIUM, not fatal. Missing security-audit won't break anything at runtime — it shows up in the audit report. Don't let it block a release; do let it show up in your drift check.
• Extension points: the stubs/laravel-project/ directory is the thing to read when you want to understand or fork behaviour. .config/boost.php is the project-level stub the upgrade writes — that's your hook for per-project overrides that survive re-runs.
• Debugging tip: when the upgrade reports "nothing to do" but you expected changes, compare the committed stub to the shipped stub. The tool diffs against what's on disk; a stale stub looks like a satisfied condition.