Bundle Ai Kit Laravel Package

Product Decisions This Supports

• Standardizing AI-assisted development across our PHP/Symfony bundle portfolio. This package ships a versioned, machine-readable standard (SOLID, AbstractBundle, Contract pattern, PHPStan 9, GrumPHP, Infection, Deptrac, CI) that installs into a repo via a Composer plugin and syncs to .cursor/rules, .cursor/skills/*, .cursor/agents, and AGENTS.md. That replaces the current de facto practice of copying prompts and lint configs between repos.
• Build vs. buy (adopt) for our engineering conventions. We would otherwise spend internal time writing and maintaining house rules, a sync script, and a quality baseline. This is a ready-made artifact we can fork or pin — a classic "adopt with an escape hatch" call rather than a strategic dependency.
• Roadmap acceleration for new Symfony bundles. New bundles get an opinionated, CI-ready skeleton of quality gates on day one: make quality (cs-check + phpstan + deptrac + test + infection), a PHP 8.2–8.4 × Composer 2–3 matrix, mutation-testing thresholds, and composer audit --abandoned=report.
• A concrete policy lever: "AI contributions pass the same gates as human ones." The rules encode this directly (no phpstan-baseline.neon, no @phpstan-ignore without justification, no mixed without a comment, no setter injection). It turns a vague governance aspiration into checkable configuration.
• Architecture enforcement without hand-written review. Deptrac codifies the Contract → Context → Installer → Root layering, so erosion is caught in CI rather than in code review.
• Onboarding. New engineers and new AI agents get the same "After Every Change" loop (make cs-fix, make phpstan, make test, make infection) and the same anti-pattern list — reduces variance in first PRs.
• Decision it does not support: it is Symfony-bundle-centric, not Laravel. If a roadmap item is "unify Laravel and Symfony tooling," this is a partial input only for the Symfony side.

When to Consider This Package

Consider it when:

• The team ships Symfony bundles (not Laravel apps) and uses Cursor, Claude Code, or Windsurf — the sync targets are fixed paths (AiRulesInstaller), with .mdc bodies designed to render as plain Markdown for the non-Cursor tools.
• You want a consistent, versioned convention set instead of ad-hoc prompts copied per repo, and you're willing to accept the author's opinions wholesale to start.
• You are greenfield or early-stage on a bundle, where PHPStan 9 with no baseline, MSI ≥ 70%, and Deptrac layering are cheap to satisfy.
• You value the merge-only installer — it never deletes user files, which makes a trial low-risk.
• You have a small team with low process overhead; the "Makefile as single entry point" model is a good fit and avoids per-engineer tooling drift.
• You want the Contract seam (SyncContextResolverInterface only, with DefaultSyncContextResolver / SkillNamesDiscoverer / SyncContext) so context resolution can be swapped or stubbed in tests.

Look elsewhere when:

• Laravel-first shop. Despite the "Laravel/PHP" framing, everything here — AbstractBundle, Symfony-oriented layering, bundle CI matrix — assumes Symfony bundles.
• Maturity is a hard requirement. 3 stars, 0 dependents, and a single apparent maintainer mean bus-factor and long-term support risk. The 8.23 score is a quality heuristic, not adoption evidence. Adopt pinned/forked as a template, not as a runtime-critical dependency.
• Legacy codebases that cannot tolerate no-baseline static analysis, MSI thresholds, or the forbidden-patterns list without a large remediation budget.
• Monorepos with entrenched custom tooling (existing static analysis, existing hooks); the integration and retrofit cost likely exceeds the benefit.
• Editor-agnostic requirements beyond the three supported tools — there is deliberately no editor abstraction layer.
• Teams that need configurable, policy-driven gates. The package is opinionated by design; if you need to negotiate thresholds per team, you'll be forking the rules and the GrumPHP/Deptrac config anyway.

How to Pitch It (Stakeholders)

For executives: This is a low-cost, opinionated starter kit that makes AI-generated PHP code conform to our engineering standards on the first attempt. It front-loads quality — maximum-strictness static analysis, mutation testing, architecture rules — so code review time and rework go down, and "the AI wrote it" stops being a quality caveat. The risk is maintenance and bus factor, so we would pin a version, treat it as a template rather than a critical dependency, and validate it on one new bundle before broadening.

For engineering: One Composer plugin syncs rules, skills, and AGENTS.md into the repo on install; nothing is deleted (merge-only). Quality is Makefile-first — make cs-fix, make phpstan (level 9, no baselines), make deptrac, make test, make infection (MSI ≥ 70), make security-check, make quality, make ci — and pre-commit hooks mirror CI. Architecture is enforced as Contract → Context → Installer → Root, with a single SyncContextResolverInterface seam so we can inject a stub resolver or installer in tests. CI runs security/cs/phpstan/deptrac in parallel, then a PHP 8.2–8.4 × Composer 2–3 matrix, then infection.

Proposed next step: pilot on one new bundle for a sprint. Success metrics: share of AI-assisted PRs passing make quality on first run, review turnaround on those PRs, and hours saved versus hand-rolling conventions. Decision gate: expand, fork-and-own, or drop.