Guidelines Skills Laravel Package

Technical Evaluation

Architecture Fit

• Developer Tooling Layer: Designed as a non-invasive package that augments existing workflows (IDE, CLI, CI/CD) without modifying core application logic. Ideal for teams prioritizing coding standards without architectural refactoring.
• Laravel Ecosystem Alignment: Built for Laravel 12+ and integrates natively with Laravel Boost (AI-driven) and skills.sh (CLI-based), ensuring compatibility with modern Laravel DX improvements. Avoids reinventing wheel for teams already invested in Spatie’s other packages (e.g., laravel-permission).
• Modular Skill Architecture: Skills are independent yet composable, allowing teams to adopt only what’s relevant (e.g., spatie-security for compliance, spatie-version-control for GitOps). Reduces risk of over-engineering for smaller teams.
• Standardization with Escape Hatches: Enforces PSR-12, OWASP Top 10, and Prettier but permits custom overrides via config files (e.g., .boost/skills.json). Critical for teams with legacy codebases or niche requirements (e.g., custom naming conventions).
• AI-Enhanced Feedback: Leverages Laravel Boost’s AI to provide context-aware suggestions (e.g., "Use whereHas() instead of join() for this query"), reducing manual review cycles by 20–40% (per Spatie’s benchmarks).

Technical Risk

Key Questions for Stakeholders

1. Team Alignment:

   • Does the team have entrenched internal guidelines that conflict with Spatie’s conventions? If so, which rules would need overriding?
   • What’s the current process for code reviews? How would this tool reduce friction (e.g., fewer debates, faster onboarding)?

2. Tooling Maturity:

   • Is the team ready to adopt Laravel Boost (early access) or prefers skills.sh for stability? What’s the backup plan if Boost introduces breaking changes?
   • How would this integrate with existing linters (e.g., PHPStan, ESLint)? Should it replace them or run in parallel?

3. Security and Compliance:

   • Are there regulatory requirements (e.g., SOC 2, ISO 27001) that mandate specific security checks beyond OWASP Top 10? Would Spatie’s rules suffice?
   • How would this tool reduce audit findings? Can we quantify the expected impact (e.g., "X% fewer security issues in PRs")?

4. Scalability:

   • How would this support onboarding new engineers? Can we measure a reduction in ramp-up time (e.g., "From 4 weeks to 2 weeks")?
   • For distributed teams, how would consistent guidelines improve collaboration (e.g., fewer merge conflicts, clearer PR feedback)?

5. Long-Term Viability:

   • What’s the exit strategy if Spatie’s guidelines become incompatible with future Laravel versions or team needs?
   • How would we customize or extend the skills (e.g., add product-specific rules) without forking the package?

6. Resource Impact:

   • What’s the estimated time to configure and roll out (e.g., 1 day for pilot, 2 weeks for full team)?
   • Who would own maintenance (e.g., updating skills, resolving conflicts)? Would this require a dedicated "code quality" role?

Integration Approach

Stack Fit

• Primary Use Case: Laravel 12+ applications leveraging Laravel Boost or skills.sh for AI-driven/CLI-based developer tooling.

• Secondary Use Case: PHP/JavaScript projects using Composer and seeking standardized conventions without framework lock-in.

• Compatibility Matrix:

  Component	Supported Versions	Notes
  Laravel	12.x+	Requires Boost for full AI integration.
  PHP	8.1+	Skills include PHP 8.x features (e.g., named arguments).
  JavaScript	ES6+	Uses Prettier v3+ for formatting.
  Git	Any	Enforces conventional commits and branch naming.
  CI/CD	GitHub Actions, GitLab CI	CLI checks (skills.sh lint) can be added to any pipeline.
  IDEs	VS Code, PhpStorm	Real-time feedback via Boost’s language server.

• Stack Exclusions:

  • Non-Laravel PHP: Skills like spatie-laravel-php are Laravel-specific (e.g., whereHas() vs. join()). Use spatie-php for generic PHP.
  • Node.js Monorepos: JavaScript skills may conflict with ESLint/Prettier configs. Audit existing tooling first.
  • Legacy Systems: Codebases with pre-PSR-12 or custom architectures may require extensive overrides.

Migration Path

1. Assessment Phase (1–2 weeks):

   • Audit existing conventions (e.g., review 10 PRs, check php-cs-fixer rules).
   • Identify conflicts (e.g., custom security policies, legacy naming).
   • Select skills to adopt (e.g., start with spatie-security + spatie-version-control).

2. Pilot Phase (2–4 weeks):

   • Option A (Low Risk): Install via skills.sh in a single repo (e.g., a microservice).

     npx skills add spatie/guidelines-skills
     

   • Option B (High Risk/High Reward): Install via Laravel Boost in a pilot project.

     composer require spatie/guidelines-skills --dev
     php artisan boost:install
     

   • Configure IDE/CLI for feedback (e.g., VS Code extensions for Boost).
   • Run in warning-only mode initially to gauge impact.

3. **Gradual Roll