Package Boost Laravel Package

Getting Started

Minimal Steps

1. Installation:

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

   (Note: Use the successor packages as per the deprecation notice.)

2. Configure Testbench (if not already set up):

   • Add to testbench.yaml:

     providers:
       - SanderMuller\PackageBoost\PackageBoostServiceProvider
     

3. Sync AI Tooling:

   vendor/bin/testbench package-boost:sync
   

   This generates .ai/ structure and syncs skills/guidelines to agent-specific directories (e.g., .claude/skills/, CLAUDE.md).

4. First Use Case:

   • Create a custom skill:

     vendor/bin/testbench package-boost:new skill my-skill --description="Custom skill for my package."
     

   • Edit .ai/skills/my-skill/SKILL.md with your instructions.
   • Sync again to propagate changes to all agents.

Implementation Patterns

Workflows

1. Skill Development:

   • Scaffold a skill with metadata:

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

   • Populate .ai/skills/my-skill/SKILL.md with:

     ---
     name: my-skill
     description: "One-line auto-activation hook."
     ---
     # Instructions for AI agents
     

   • Sync to agents:

     vendor/bin/testbench package-boost:sync
     

2. Guideline Management:

   • Create a guideline file:

     vendor/bin/testbench package-boost:new guideline my-guidelines
     

   • Edit .ai/guidelines/my-guidelines.md.
   • Sync to agent-specific files (e.g., CLAUDE.md):

     vendor/bin/testbench package-boost:sync --guidelines
     

3. CI Integration:

   • Add a drift check to CI (e.g., GitHub Actions):

     - name: Check sync drift
       run: vendor/bin/testbench package-boost:sync --check
     

   • Fail builds if drift is detected (e.g., unsynced skills/guidelines).

4. Laravel-Specific Features:

   • Use cross-version-laravel-support skill for multi-version compatibility:

     # In .ai/skills/cross-version-laravel-support/SKILL.md
     ---
     name: cross-version-laravel-support
     description: "Teach AI about Laravel version constraints."
     ---
     

   • Sync to enable AI assistance for Laravel-specific tasks.

Integration Tips

• Testbench as Harness: Use Testbench for dev-only tasks (e.g., testing, scaffolding) without runtime dependencies.
• Agent Selection: Configure supported agents in config/package-boost.php:

  'agents' => ['claude_code', 'cursor', 'github_copilot'],
  

• MCP Integration: If using Laravel Boost, .mcp.json is auto-generated for Boost-MCP compatibility.
• Lean Dist: Integrate with stolt/lean-package-validator for .gitattributes hygiene:

  vendor/bin/testbench package-boost:sync --skills=lean-dist
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • The original package-boost is deprecated. Migrate to:
     • package-boost-php (framework-agnostic).
     • package-boost-laravel (Laravel-specific).
   • Run:

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

2. Skill Naming Collisions:

   • Avoid naming conflicts with default skills (e.g., package-development). Use unique names like my-package-skill.
   • Validate names with:

     vendor/bin/testbench package-boost:doctor
     

3. Frontmatter Requirements:

   • Skills must include name and description in frontmatter. Missing fields cause sync failures:

     ---
     name: my-skill  # Required
     description: "Description."  # Required
     ---
     

4. Agent-Specific Paths:

   • Sync writes to agent-specific directories (e.g., .claude/skills/). Ensure these paths are .gitignored if not needed in production:

     .claude/
     .cursor/
     .github/
     .junie/
     .kiro/
     

5. MCP Generation:

   • .mcp.json is only generated if laravel/boost is installed. Check for:

     { "action": "skipped", "reason": "laravel-boost-not-installed" }
     

Debugging

• Drift Checks:

  • Use --check to detect unsynced changes:

    vendor/bin/testbench package-boost:sync --check
    

  • JSON output helps automate CI checks:

    vendor/bin/testbench package-boost:sync --check --format=json | jq '.skills.updated'
    

• Skill Validation:

  • Run package-boost:doctor to validate skills/guidelines:

    vendor/bin/testbench package-boost:doctor
    

  • Fix errors (e.g., missing frontmatter) before syncing.

Extension Points

1. Custom Skills:

   • Extend existing skills by adding to .ai/skills/. Example:

     # .ai/skills/my-custom-skill/SKILL.md
     ---
     name: my-custom-skill
     description: "Teach AI about my package's quirks."
     ---
     # Add instructions here...
     

2. Agent-Specific Overrides:

   • Override agent-specific files (e.g., CLAUDE.md) by manually editing them after sync. Changes will be overwritten on the next sync unless excluded via --exclude-guidelines.

3. CI Matrix Troubleshooting:

   • Use the ci-matrix-troubleshooting skill to diagnose failing CI cells:

     vendor/bin/testbench package-boost:sync --skills=ci-matrix-troubleshooting
     

4. Release Notes Automation:

   • Leverage the release-notes skill to draft GitHub release bodies:

     vendor/bin/testbench package-boost:sync --skills=release-notes
     

   • Edit .ai/skills/release-notes/SKILL.md to customize templates.

Config Quirks

• Agent Selection:

  • Defaults to all 9 agents. Restrict via:

    // config/package-boost.php
    'agents' => ['claude_code', 'cursor'],
    

  • Re-sync after changes:

    vendor/bin/testbench package-boost:sync
    

• Excluding Files:

  • Skip syncing specific guidelines/skills:

    vendor/bin/testbench package-boost:sync --exclude-guidelines=old-guidelines.md
    

• Testbench Compatibility:

  • Ensure Testbench is installed (orchestra/testbench) for command-line access to package-boost commands.