Guidelines Skills Laravel Package

Technical Evaluation

Architecture Fit

• Lightweight & Non-Intrusive: The package is designed as a set of AI-driven coding guidelines (skills) for Laravel Boost and skills.sh, making it a non-invasive addition to existing Laravel projects. It does not modify core Laravel functionality but instead enforces best practices via AI-assisted tooling (e.g., Laravel Boost’s IDE integration or skills.sh CLI).
• Complementary to Existing Workflows: Aligns with Spatie’s established coding guidelines, which are already battle-tested in their own projects. This reduces friction for teams already familiar with Spatie’s standards.
• Skill-Based Modularity: The package’s modular structure (e.g., spatie-laravel-php, spatie-security) allows selective adoption, making it adaptable to projects with varying maturity levels.

Integration Feasibility

• Laravel Boost Integration:
  • Requires Laravel 12+ (Boost is a new feature in Laravel 12).
  • Installation is streamlined via php artisan boost:install, but assumes the team is using Boost for IDE tooling (e.g., PHPStan, Pest, etc.).
  • Risk: Boost is still evolving; long-term stability depends on Laravel’s roadmap.
• skills.sh Integration:
  • Works as a standalone CLI tool, reducing Laravel-specific dependencies.
  • Risk: skills.sh is a newer tool; adoption may vary across teams.
• Compatibility:
  • No hard dependencies on other Spatie packages (unlike laravel-permission or laravel-medialibrary).
  • Assumes modern PHP (8.1+) and Composer for dependency management.

Technical Risk

• Tooling Dependency:
  • Relies on Laravel Boost or skills.sh for enforcement. Teams not using these tools will need to adopt them, adding ramp-up time.
  • If Boost or skills.sh changes their API, the package may require updates.
• False Positives/Negatives:
  • AI-driven guidelines (e.g., via Boost) may misinterpret legacy code or edge cases, requiring manual overrides.
• Limited Documentation:
  • Only a README and changelog exist; no detailed migration guides or troubleshooting docs for complex projects.
• No Direct Laravel Hooks:
  • Unlike validation rules or middleware, this package doesn’t integrate into Laravel’s core lifecycle (e.g., request handling, migrations). Its impact is pre-commit or IDE-level.

Key Questions

1. Adoption Strategy:
   • Will the team use Laravel Boost (IDE-focused) or skills.sh (CLI-focused)? Does the project already have a preferred linter/IDE tool (e.g., PHPStan, PSalm, ESLint)?
2. Enforcement Mechanism:
   • How will violations be handled? Will they block commits (via Git hooks) or be logged for review?
3. Customization Needs:
   • Does the project require deviations from Spatie’s guidelines (e.g., legacy code, team-specific conventions)?
4. Tooling Stack Alignment:
   • Will this replace existing tools (e.g., php-cs-fixer, laravel-pint) or run alongside them?
5. Performance Impact:
   • For large codebases, will Boost’s AI analysis introduce noticeable slowdowns during development?

Integration Approach

Stack Fit

• Best Fit:
  • New Laravel 12+ Projects: Ideal for teams adopting Boost or seeking standardized guidelines out-of-the-box.
  • Greenfield Projects: Low-risk addition to enforce consistency from day one.
  • Teams Using skills.sh: CLI-first workflows benefit from seamless integration.
• Less Ideal:
  • Legacy Laravel Projects: May conflict with existing tooling (e.g., custom PSR-12 rules) or require significant refactoring.
  • Non-Laravel PHP Projects: Limited value outside Laravel’s ecosystem (e.g., Symfony, plain PHP).
  • Teams Without IDE Support: If Boost isn’t used, the package’s IDE features (e.g., real-time feedback) are inaccessible.

Migration Path

1. Assessment Phase:
   • Audit existing codebase against Spatie’s guidelines to identify gaps/conflicts.
   • Document deviations (e.g., "We use snake_case for DB columns, not camelCase").
2. Tooling Setup:
   • Option A (Boost):
     • Install Laravel Boost: composer require laravel/boost.
     • Run php artisan boost:install and select Spatie’s guidelines.
     • Configure Boost to integrate with existing tools (e.g., PHPStan).
   • Option B (skills.sh):
     • Install globally: npx skills add spatie/guidelines-skills.
     • Configure Git hooks or CI/CD to run skills check.
3. Pilot Phase:
   • Enable guidelines for a subset of developers or a single module.
   • Monitor false positives/negatives and adjust configurations.
4. Full Rollout:
   • Integrate into CI/CD (e.g., GitHub Actions) to block violations.
   • Train the team on overriding guidelines where necessary.

Compatibility

• Laravel Boost:
  • Requires Laravel 12+ and PHP 8.1+. Test compatibility with other Boost plugins (e.g., laravel/boost:phpstan).
  • May conflict with custom Boost configurations.
• skills.sh:
  • Works with any PHP project but is Laravel-agnostic. Test with existing linters (e.g., php-cs-fixer).
• Existing Tooling:
  • Overlap with php-cs-fixer: Spatie’s PHP guidelines may duplicate or conflict with existing .php-cs-fixer.dist.php rules.
  • Git Hooks: Ensure skills.sh doesn’t interfere with existing pre-commit hooks.

Sequencing

1. Pre-Integration:
   • Align with the team on which guidelines to adopt (e.g., skip spatie-security if using a dedicated security team).
   • Backup existing .editorconfig, composer.json scripts, and linter configs.
2. Integration:
   • Start with non-breaking changes (e.g., spatie-version-control for Git workflows).
   • Gradually introduce stricter rules (e.g., spatie-laravel-php for naming conventions).
3. Post-Integration:
   • Automate updates: Add composer update spatie/guidelines-skills to CI/CD.
   • Monitor performance impact (e.g., Boost analysis time).

Operational Impact

Maintenance

• Low Ongoing Effort:
  • Updates are minimal (run composer update or skills add periodically).
  • Guidelines are maintained by Spatie; no custom maintenance required.
• Configuration Drift:
  • Risk of teams disabling guidelines or creating local overrides, leading to inconsistency.
  • Mitigation: Enforce via CI/CD and document approved exceptions.

Support

• Limited Official Support:
  • Package has no dependents and minimal stars, suggesting low community adoption.
  • Issues should be raised on the GitHub repo, but response time may be slow.
• Workarounds:
  • Leverage Spatie’s main guidelines for troubleshooting.
  • Fall back to manual reviews or existing tools (e.g., PHPStan) for complex cases.

Scaling

• Performance:
  • Laravel Boost: AI analysis may slow down IDE operations for large codebases. Test with a sample project first.
  • skills.sh: CLI checks are lightweight but may add ~1–5 seconds to CI pipelines.
• Team Size:
  • Small Teams: Easy to adopt and enforce.
  • Large Teams: Requires clear documentation and training to avoid resistance.
• Multi-Repo Workflows:
  • skills.sh supports multi-repo setups, but Boost is project-specific.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Time: 1–2 hours to understand guidelines and tooling.
  • Training:
    • Share Spatie’s guidelines as a reference.
    • Document how