Package Boost Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev sandermuller/package-boost-php orchestra/testbench
   

   (Note: Use package-boost-php instead of the deprecated package-boost per the migration guide.)

2. Configure Testbench: Add to testbench.yaml:

   providers:
     - SanderMuller\PackageBoost\PackageBoostServiceProvider
   

3. First Sync:

   vendor/bin/testbench package-boost:sync
   

   This generates AI agent directories (e.g., .claude/skills/) and guidelines files (CLAUDE.md, AGENTS.md) from .ai/.

Where to Look First

• .ai/ Directory: Core source for skills (skills/) and guidelines (guidelines/).
• Testbench Commands: Run vendor/bin/testbench package-boost: to see available commands.
• Default Skills: Pre-installed skills like package-development, cross-version-laravel-support, and lean-dist (Laravel-specific by default but safe to ignore for non-Laravel packages).

First Use Case

Create a Custom Skill:

vendor/bin/testbench package-boost:new skill my-custom-skill --description="Describe the skill's purpose."

This scaffolds a SKILL.md in .ai/skills/my-custom-skill/ with frontmatter. Sync it:

vendor/bin/testbench package-boost:sync

Implementation Patterns

Workflows

1. Skill Development Cycle:

   • Write: Edit .ai/skills/<name>/SKILL.md (frontmatter + content).
   • Validate: Run vendor/bin/testbench package-boost:doctor to check frontmatter and naming.
   • Sync: package-boost:sync propagates to agent directories.
   • Test: Verify skills appear in .claude/skills/ or AGENTS.md.

2. Guideline Management:

   • Add custom guidelines to .ai/guidelines/my-conventions.md.
   • Sync with package-boost:sync --guidelines to update AGENTS.md/CLAUDE.md.

3. CI Integration:

   • Add a drift-check step:

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

   • Fail builds if skills/guidelines are out of sync.

Integration Tips

• Laravel-Specific Packages: Use package-boost-laravel alongside package-boost-php for Laravel-specific skills (e.g., McpJsonEmitter). Install both:

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

• Framework-Agnostic Packages: Ignore Laravel-specific skills (they auto-deactivate). Focus on:

  • package-development (Testbench setup).
  • lean-dist (Git hygiene).
  • skill-authoring (skill naming conventions).

• Selective Sync: Sync only skills or guidelines in CI to reduce noise:

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

• MCP.json Generation: Only works if laravel/boost is installed. Skip with --no-mcp if irrelevant.

Laravel-Specific Patterns

1. Cross-Version Support: Use the cross-version-laravel-support skill to handle:

   • Dynamic composer.json constraints.
   • Feature detection (e.g., if (class_exists(\Illuminate\Contracts\...))).
   • Testbench compatibility matrices.

2. CI Matrix Troubleshooting: Run package-boost:sync --ci-matrix to diagnose failing CI cells (e.g., prefer-lowest conflicts).

3. Boost-MCP Integration: If using Laravel Boost, package-boost auto-generates .mcp.json pointing to vendor/bin/testbench boost:mcp.

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • The original sandermuller/package-boost is deprecated. Always use package-boost-php (or package-boost-laravel).
   • Migration:

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

2. Skill Naming Collisions:

   • Avoid names like readme or release-notes (reserved by shipped skills).
   • Validate with package-boost:doctor before syncing.

3. Agent Directory Permissions:

   • Ensure .claude/, .cursor/, etc., are writable. Sync may fail silently if permissions are restrictive.

4. Frontmatter Requirements:

   • Every SKILL.md must include name: and description: in frontmatter.
   • Example:

     ---
     name: my-skill
     description: "One-line purpose."
     ---
     

5. CI Drift Checks:

   • --check fails on host skill/guideline issues (e.g., missing frontmatter) but only warns on shipped skill problems.
   • Use in CI to catch "forgot to sync" errors:

     - run: vendor/bin/testbench package-boost:sync --check || exit 1
     

Debugging

1. Sync Failures:

   • Run with --verbose:

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

   • Check for:
     • Missing .ai/ directory.
     • Invalid frontmatter (e.g., missing name:).
     • Permission errors on .claude/skills/.

2. JSON Output Parsing:

   • Use --format=json to debug drift:

     vendor/bin/testbench package-boost:sync --check --format=json | jq
     

   • Look for:
     • "drift": true (files need syncing).
     • "skipped" reasons (e.g., laravel-boost-not-installed).

3. Skill Activation Issues:

   • Claude Code requires SKILL.md files in .claude/skills/.
   • Other agents (e.g., GitHub Copilot) primarily use AGENTS.md. Verify content appears in the correct file.

Tips

1. Skill Authoring Best Practices:

   • Use the skill-authoring skill to avoid silent collisions.
   • Prefer kebab-case names (e.g., my-skill.md).
   • Test skills locally with Claude Code or Copilot before syncing.

2. Guideline Customization:

   • Override shipped guidelines by placing files in .ai/guidelines/.
   • Example: .ai/guidelines/custom-coding.md → merged into AGENTS.md.

3. Lean Dist Integration:

   • Pair with stolt/lean-package-validator for Git hygiene:

     composer require --dev stolt/lean-package-validator
     

   • The lean-dist skill auto-configures .gitattributes to ignore .ai/ and agent directories.

4. Laravel-Specific Shortcuts:

   • Use cross-version-laravel-support to auto-generate version guards:

     if (version_compare(app()->version(), '10.0', '<')) {
         // Fallback for Laravel <10
     }
     

5. Agent-Specific Quirks:

   • Claude Code: Only agent that natively reads .claude/skills/ as activatable tools.
   • GitHub Copilot: Ignores .github/skills/; relies on AGENTS.md.
   • Cursor: Prefers .cursor/skills/ but falls back to AGENTS.md.

Extension Points

1. Custom File Emitters:

   • Extend boost-core by declaring the boost-extension tag in your boost.php:

     withTags(['boost-extension']);
     

   • This unlocks the writing-file-emitter skill for custom file generation (e.g., .mcp.json).

2. Skill Frontmatter Hooks:

   • Add auto-activate: true to SKILL.md frontmatter to force activation in Claude Code:

     ---
     name: my-skill
     description: "Auto-activated skill."
     auto-activate: true
     ---
     

3. Agent Filtering:

   • Disable specific agents via config/package-boost.php:

     return [
         'agents' => ['claude_code', 'cursor'], // Exclude others
     ];
     

   • Or use the interactive installer:

     vendor/bin/testbench package-boost:install --agents=claude_code,cursor
     

4. MCP.json Customization:

   • Override .mcp.json by publishing the config:

     vendor/bin/testbench vendor:publish --tag=package-boost-config