Package Boost Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Alignment: The package is Laravel-aware but framework-agnostic via Testbench, making it a strong fit for Laravel packages or PHP packages leveraging Testbench for testing. The split into package-boost-php (agnostic) and package-boost-laravel (Laravel-specific) ensures modular adoption.
• AI-Assisted Workflow: The .ai/ directory structure and agent-specific sync (Claude, Cursor, GitHub Copilot, etc.) aligns with modern AI-driven development, reducing manual configuration for AI tooling.
• Skill-Based Design: The modular "skills" (e.g., package-development, cross-version-laravel-support) are composable and Laravel-specific by design, auto-activating only when relevant. This avoids bloat in non-Laravel contexts.
• Testbench Integration: Leverages Testbench as a dev-only harness, ensuring no runtime dependencies for end users.

Integration Feasibility

• Low Friction: Requires only composer require + Testbench (if not already present) and minimal testbench.yaml config. No Laravel-specific runtime dependencies.
• Backward Compatibility: Existing composer.lock references to 0.15.x remain functional, but migration to successors (package-boost-php/package-boost-laravel) is straightforward.
• Agent-Specific Sync: Supports selective agent sync (e.g., skip Claude if unused), reducing noise in CI/CD pipelines.
• CI/CD Readiness: --check mode enables drift detection in CI, preventing "forgot to sync" issues.

Technical Risk

• Deprecation Risk: The package is deprecated in favor of successors. Migration is low-effort but requires proactive updates to avoid future breakage.
• Testbench Dependency: Non-Laravel packages must adopt Testbench as a dev dependency, which may introduce minor overhead (e.g., PHPUnit version constraints).
• Agent-Specific Quirks: Some agents (e.g., Claude Code) natively consume skills dirs, while others rely on guidelines files. This duality requires careful sync management.
• Skill Collisions: Shared skill namespaces (e.g., .ai/skills/ vs resources/boost/skills/) could cause conflicts if not managed via frontmatter or explicit naming.

Key Questions

1. Laravel vs. Agnostic: Is the package Laravel-specific or framework-agnostic? If the latter, does the team need Laravel-specific skills (e.g., cross-version-laravel-support)?
2. Agent Coverage: Which AI agents are actively used in the team’s workflow? Should all 9 be synced, or a subset?
3. CI/CD Integration: Should --check mode be enforced in CI to catch sync drift? If so, how will failures be handled (e.g., GitHub Actions annotations)?
4. Testbench Adoption: Is Testbench already used in the project, or will it require new dev dependencies?
5. Skill Customization: Are custom skills/guidelines needed, or will the shipped defaults suffice?
6. Migration Path: Should the team migrate to package-boost-php/package-boost-laravel immediately, or defer until forced by breaking changes?

Integration Approach

Stack Fit

• Laravel Packages: Ideal for Laravel packages needing AI tooling, Testbench integration, and cross-version support.
• PHP Packages with Testbench: Works for any Composer package using Testbench for testing, with optional Laravel-specific skills.
• Non-Testbench Packages: Not directly supported; Testbench is a hard dependency for the sync workflow.
• Laravel Boost Users: Seamlessly integrates with laravel/boost via .mcp.json generation (if Boost is installed).

Migration Path

1. Assess Scope:
   • For Laravel packages: Use package-boost-laravel (successor).
   • For framework-agnostic packages: Use package-boost-php.
   • For non-package PHP apps: Use project-boost.
2. Replace Dependency:

   composer remove sandermuller/package-boost
   composer require --dev sandermuller/package-boost-php  # or -laravel
   

3. Update Config:
   • Replace PackageBoostServiceProvider in testbench.yaml if using custom providers.
   • Migrate workbench/config/package-boost.php if agent selection was customized.
4. Verify Sync:
   • Run vendor/bin/testbench package-boost:sync --check to confirm no drift.
5. Deprecation Handling:
   • Monitor successors for breaking changes; the legacy 0.15.x tag remains on Packagist for existing installs.

Compatibility

• Laravel Versions: Compatible with Laravel 10+ (via Testbench). Check orchestra/testbench constraints for PHP version support.
• PHP Versions: Aligns with Testbench’s PHP requirements (typically 8.1+).
• Composer: Requires Composer 2.x. No conflicts with modern Laravel tooling (e.g., Pest, Boost).
• Agent Tools: Syncs to paths expected by Claude, Cursor, GitHub Copilot, etc. No runtime dependencies on these tools.

Sequencing

1. Prerequisites:
   • Install Testbench (if not present):

     composer require --dev orchestra/testbench
     

   • Configure testbench.yaml with the provider.
2. Install Package Boost:

   composer require --dev sandermuller/package-boost-php  # or -laravel
   

3. Optional: Agent Selection:

   vendor/bin/testbench package-boost:install  # Interactive picker
   

4. Scaffold Skills/Guidelines (if needed):

   vendor/bin/testbench package-boost:new skill my-skill
   vendor/bin/testbench package-boost:new guideline my-conventions
   

5. Sync:

   vendor/bin/testbench package-boost:sync
   

6. CI Integration:
   • Add a step to run vendor/bin/testbench package-boost:sync --check in CI.
   • Example GitHub Actions:

     - name: Check Package Boost Sync
       run: |
         if ! vendor/bin/testbench package-boost:sync --check --format=json | jq -e '.drift == false'; then
           echo "::error::Sync drift detected"
           exit 1
         fi
     

Operational Impact

Maintenance

• Low Overhead: The package is self-contained and self-documenting (skills/guidelines live in .ai/). Updates are handled via Composer.
• Skill Management:
  • Custom skills/guidelines require manual updates but follow a clear structure (kebab-case names, frontmatter validation).
  • Shipped skills (e.g., package-development) are maintained by the package authors.
• Deprecation: Migration to successors is one-time and involves dependency replacement. No ongoing maintenance burden beyond standard Composer updates.

Support

• Troubleshooting:
  • --check mode provides structured JSON output for CI drift detection, easing debugging.
  • Errors are explicit (e.g., missing frontmatter, skill collisions) and actionable.
• Agent-Specific Issues:
  • If an agent fails to consume skills (e.g., Claude Code vs. Copilot), the package provides clear paths for forward compatibility.
  • Logs from package-boost:sync help diagnose sync failures.
• Community: Limited adopters (0 dependents) may reduce community support, but the codebase is small and well-documented.

Scaling

• Performance:
  • Sync operations are file-system bound (copying .ai/ to agent dirs). No database or heavy computation.
  • --check mode is fast (compares files without writing).
• Team Adoption:
  • Scales well for multi-developer teams due to explicit .ai/ source control and CI checks.
  • Agent-specific directories (e.g., .claude/skills/) are explicitly committed, avoiding "works on my machine" issues.
• Monorepos: Works in monorepos if Testbench is configured per-package (via testbench.yaml in each package root).

Failure Modes