Feature Package

.gitignore

@@ -1 +1,23 @@
-.idea
+# Dependencies
+/vendor/
+node_modules/
+
+# Composer
+composer.lock
+composer.phar
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# PHP / Testing
+.phpunit.result.cache
+.php-cs-fixer.cache
+coverage/
+.phpunit.cache/

LICENSE.md

@@ -0,0 +1,21 @@
+# The MIT License (MIT)
+
+Copyright (c) codebar-ag
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,19 +1,33 @@
 # Coding Guidelines
 
-Shared Cursor AI rules and skills for codebar-ag Laravel projects. The AI uses these to follow consistent conventions for PHP, Laravel, testing, frontend, and services.
+Shared Laravel AI coding guidelines and skills for codebar-ag projects. A Boost-first Composer package that ships 30+ skills for consistent conventions across PHP, Laravel, testing, frontend, and services.
 
 **Rule index:** See [RULES.md](RULES.md) for the full rule structure and file reference.
 
 ---
 
-## Prerequisites
+## Skills Summary
 
-- A Laravel project where you want to use these guidelines
-- [Laravel Boost](https://github.com/laravel/boost) (for syncing rules/skills into your project)
+| Category | Skills | Description |
+|----------|--------|-------------|
+| **Laravel** | General, HelperFunctions, Models, Controllers, Migrations, Routing, FormRequests | Framework conventions, config/logging, Eloquent, routes, validation |
+| **Backend** | Actions, Commands, DTO, Enums, Events, Exceptions, Helpers, Interfaces, Jobs, Middleware, Observers, Policies, Requests, Resources, Services, Traits | PHP architecture, single-purpose classes, API resources, queue jobs |
+| **Frontend** | Blade, Livewire | Templates, components, reactive UI |
+| **Testing** | PHPUnit, PestTesting, PHPStan, Dusk | Unit/feature tests, static analysis, browser tests |
+| **Services** | Saloon | External API integrations (Saloon pattern) |
+
+**Total: 30 skills.** Each skill includes Rules, Examples, Anti-Patterns, and References.
 
 ---
 
-## 1. Install Laravel Boost (if not already)
+## Implementation Guide
+
+### Prerequisites
+
+- A Laravel project where you want to use these guidelines
+- [Laravel Boost](https://github.com/laravel/boost) (required for skill discovery)
+
+### Step 1: Install Laravel Boost
 
 In your Laravel project:
 
@@ -22,34 +36,70 @@ composer require laravel/boost --dev
 php artisan boost:install
 ```
 
----
+### Step 2: Add this package
+
+**Option A — Composer (recommended for version pinning):**
+
+```bash
+composer require codebar-ag/coding-guidelines --dev
+```
 
-## 2. Activate the MCP server
+**Option B — GitHub via Boost:**
 
-If your editor supports MCP (Model Context Protocol), configure it to use the Boost MCP server so the AI has full context. See the [Laravel Boost documentation](https://github.com/laravel/boost) for your editor’s setup.
+```bash
+php artisan boost:add-skill codebar-ag/coding-guidelines
+```
 
----
+### Step 3: Sync skills
 
-## 3. Add and sync the guidelines
+```bash
+php artisan boost:update
+```
 
-Choose one of the following depending on how you work with this repo.
+Boost automatically discovers skills from `vendor/codebar-ag/coding-guidelines/resources/boost/skills/` when the package is installed.
 
-### When you are **not** pulling from `main`
+### Step 4: Activate MCP (optional)
 
-1. Copy the **`skills`** folder from this repo into your AI config folder (e.g. `.cursor/skills` or your editor’s equivalent).
-2. In your Laravel project, run:
+If your editor supports MCP (Model Context Protocol), configure it to use the Boost MCP server for full context. See the [Laravel Boost documentation](https://laravel.com/docs/boost) for your editor’s setup.
 
-   ```bash
-   php artisan boost:update
-   ```
+### Step 5: Override skills locally (optional)
 
-### When you **are** pulling from the `main` branch (recommended)
+To customize a skill for your project, create a file at `.ai/skills/{skill-name}/SKILL.md`. Your local version takes precedence over the package default.
 
-In your Laravel project, add this repo as a Boost skill source and update:
+Example: override the Models skill:
+
+```
+your-project/
+├── .ai/
+│   └── skills/
+│       └── models/
+│           └── SKILL.md    ← Your custom version
+```
+
+---
+
+## How It Works
+
+This package places skills in `resources/boost/skills/{skill-name}/SKILL.md`. Laravel Boost v2.2+ automatically discovers skills from vendor packages when you run `boost:update`. No custom sync commands — Boost handles everything.
+
+| Source | Path |
+|--------|------|
+| This package | `vendor/codebar-ag/coding-guidelines/resources/boost/skills/` |
+| Project overrides | `.ai/skills/{skill-name}/SKILL.md` |
+
+---
+
+## Updating
+
+When using Composer:
 
 ```bash
-php artisan boost:add-skill codebar-ag/coding-guidelines
+composer update codebar-ag/coding-guidelines
 php artisan boost:update
 ```
 
-After this, the AI in your project will automatically use the rules and skills from this repository.
+When using `boost:add-skill`:
+
+```bash
+php artisan boost:update
+```

RULES.md

@@ -1,113 +1,50 @@
 # Rules Structure
 
-This file defines the folder structure and conventions for adding new Cursor rules.
+This file defines the folder structure and conventions for skills in this package.
 
-## Folder Layout
+## Package Layout
+
+Skills live in `resources/boost/skills/{skill-name}/SKILL.md` — the path Laravel Boost discovers for vendor packages.
 
 ```
-rules/
-  testing/          # Test framework and quality tool rules
-  frontend/         # Blade, Livewire, CSS, and JS rules
-  backend/          # General PHP conventions
-  laravel/          # Laravel framework conventions
-  services/         # External API integration rules
+resources/boost/skills/
+  general/           # Laravel conventions
+  models/            # Eloquent models
+  actions/           # Action pattern
+  blade/             # Blade templates
+  livewire/          # Livewire components
+  phpunit/           # PHPUnit tests
+  saloon/            # Saloon API integrations
+  ...                # See README for full list
 ```
 
-## Categories
-
-### testing/
-
-Rules for test frameworks and static analysis tools.
-
-| File | Scope | Description |
-|------|-------|-------------|
-| `phpunit.mdc` | `tests/**/*.php` | PHPUnit test structure, naming, assertions, and factory conventions |
-| `phpstan.mdc` | Always | PHPStan Level 9 static analysis compliance |
-| `pest-testing.mdc` | Laravel Testing Framework Pest 4 |
-
-
-### frontend/
-
-Rules for frontend technologies and templating.
-
-| File | Scope | Description |
-|------|-------|-------------|
-| `blade.mdc` | `resources/views/**/*.blade.php` | Blade template conventions and best practices |
-| `design.mdc` | `resources/views/**/*.blade.php` | Component-first design system and responsive UI conventions |
-| `livewire.mdc` | `app/Livewire/**/*.php` | Livewire component patterns and conventions |
-| `tailwind.mdc` | `resources/css/**` | Tailwind CSS v4 styling conventions |
-| `translations.mdc` | `lang/**/*.php,lang/**/*.json,resources/views/**/*.blade.php,app/**/*.php` | Translation and localization conventions |
-
-### backend/
-
-Rules for general PHP backend conventions (not Laravel-specific).
-
-| File | Scope | Description |
-|------|-------|-------------|
-| `actions.mdc` | `app/Actions/**/*.php` | Action conventions — single-purpose business logic classes |
-| `commands.mdc` | `app/Console/Commands/**/*.php` | Command conventions — command classes, how to use them, and what belongs in them |
-| `dto.mdc` | `**/DataObjects/**/*.php` | Readonly Data Transfer Object conventions with fromArray factory |
-| `enums.mdc` | `app/Enums/**/*.php` | PHP backed enum conventions with label and color helpers |
-| `events-listeners.mdc` | `app/Events/**/*.php,app/Listeners/**/*.php` | Event & Listener conventions — decoupled communication between application layers |
-| `exceptions.mdc` | `app/Exceptions/**/*.php` | Exception conventions — custom exceptions for domain and application errors |
-| `helpers.mdc` | `app/Helpers/**/*.php` | Helper conventions — helper classes how to use and what belongs into it |
-| `interfaces-contracts.mdc` | `app/Contracts/**/*.php` | Interface & Contract conventions — defining contracts between components |
-| `jobs.mdc` | `app/Jobs/**/*.php` | Queued job conventions with retries, backoff, and structured logging |
-| `middleware.mdc` | `app/Http/Middleware/**/*.php` | Middleware conventions — HTTP request and response pipeline |
-| `observers.mdc` | `app/Observers/**/*.php` | Observer conventions — reacting to Eloquent model lifecycle events |
-| `php.mdc` | `app/**/*.php` | General PHP conventions -- strict typing, formatting, language |
-| `policies.mdc` | `app/Policies/**/*.php` | Policy conventions — authorization logic for models and resources |
-| `requests.mdc` | `app/Http/Requests/**/*.php` | Form Request validation conventions |
-| `resources.mdc` | `app/Http/Resources/**/*.php` | Resource conventions — API resources, collections, and response shaping |
-| `services.mdc` | `app/Services/**/*.php` | Service conventions — complex orchestration across multiple domains |
-| `traits.mdc` | `app/Traits/**/*.php` | Trait conventions — when to use traits, how to write them, and what belongs in them |
+## How to Add a New Skill
 
-### laravel/
-
-Rules for Laravel framework conventions.
-
-| File | Scope | Description |
-|------|-------|-------------|
-| `general.mdc` | Always | Project-wide Laravel conventions that always apply |
-| `laravel-helperfunctions.mdc` | Always | Laravel Helper Functions – Always use Arr::, Str:: and Collection methods instead of native PHP equivalents |
-| `models.mdc` | `app/Models/**/*.php` | Eloquent model conventions -- guarded, casts, sections, activity log |
-| `controllers.mdc` | `app/Http/Controllers/**/*.php` | Controller conventions -- thin controllers, invokable, service delegation |
-| `migrations.mdc` | `database/migrations/**/*.php` | Database migration conventions -- always new files, naming, structure |
-| `form-requests.mdc` | `app/Http/Requests/**/*.php,app/Http/Controllers/**/*.php` | Dedicated Form Request validation classes for all controller input |
-| `routing.mdc` | `routes/**/*.php` | Route file conventions -- api vs web, grouping, model binding |
-
-### services/
-
-Rules for external API integrations. Add a new file for each service.
-
-| File | Scope | Description |
-|------|-------|-------------|
-| `saloon.mdc` | `app/Services/**/*.php` | Saloon-based service layer pattern for external API integrations |
-| `docuware.mdc` | `app/Services/DocuWare/**/*.php` | DocuWare integration patterns -- connector, webhook, import lifecycle |
-| `albatros.mdc` | `app/Services/Albatros/**/*.php` | Albatros accounting API integration -- Saloon connector, DTOs, pagination |
-
-## How to Add a New Rule
-
-1. Choose the correct category folder (or create a new one if needed)
-2. Create a `.mdc` file with YAML frontmatter:
+1. Create `resources/boost/skills/{skill-name}/SKILL.md`
+2. Add YAML frontmatter with `name` and `description` (required by [Agent Skills format](https://agentskills.io/what-are-skills)):
 
 ```markdown
 ---
-description: Brief description of what this rule covers
-globs: app/Path/**/*.php
-alwaysApply: false
+name: my-skill
+description: Brief description of when to use this skill
 ---
 
-# Rule Title
+# Skill Title
+
+## Rules
+- Rule 1
+- Rule 2
 
-Your rule content here...
+## Examples
+...
+
+## Anti-Patterns
+...
 ```
 
-3. Set the frontmatter:
-   - `description`: shown in Cursor's rule picker
-   - `globs`: file pattern -- rule activates when matching files are open
-   - `alwaysApply: true`: rule applies to every conversation (use sparingly)
+3. Use lowercase kebab-case for folder names: `my-skill`
+4. Keep skills concise with clear Rules, Examples, and Anti-Patterns
+
+## Overriding Skills
 
-4. Keep rules concise (under 50 lines of content)
-5. Include code examples showing the preferred pattern
-6. Use lowercase kebab-case for filenames: `my-service.mdc`
+Projects can override any skill by creating `.ai/skills/{skill-name}/SKILL.md` in their Laravel project. The local file takes precedence over the package default.

composer.json

@@ -0,0 +1,41 @@
+{
+    "name": "codebar-ag/coding-guidelines",
+    "description": "Shared Laravel AI coding guidelines and skills for codebar-ag projects. Boost-first Composer package.",
+    "keywords": [
+        "laravel",
+        "boost",
+        "ai",
+        "cursor",
+        "coding-guidelines",
+        "skills"
+    ],
+    "license": "MIT",
+    "require": {
+        "php": "^8.2"
+    },
+    "suggest": {
+        "laravel/boost": "Required for skill discovery. Install in your Laravel project."
+    },
+    "autoload": {
+        "psr-4": {
+            "CodebarAg\\CodingGuidelines\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "CodebarAg\\CodingGuidelines\\Tests\\": "tests/"
+        }
+    },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "CodebarAg\\CodingGuidelines\\CodingGuidelinesServiceProvider"
+            ]
+        }
+    },
+    "config": {
+        "sort-packages": true
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true
+}

skills/Actions/SKILL.md → resources/boost/skills/actions/SKILL.md

@@ -1,4 +1,7 @@
-# Actions
+---
+name: actions
+description: Single-purpose business logic classes that encapsulate one well-defined business operation. Actions are the primary location for business logic in Laravel applications, invoked from controllers, commands, or jobs.
+---
 
 **Name:** Actions
 **Description:** Single-purpose business logic classes that encapsulate one well-defined business operation. Actions are the primary location for business logic in Laravel applications, invoked from controllers, commands, or jobs.

skills/Blade/SKILL.md → resources/boost/skills/blade/SKILL.md

@@ -1,4 +1,7 @@
-# Blade
+---
+name: blade
+description: Laravel Blade template conventions covering components, output escaping, security, structure, and formatting.
+---
 
 **Name:** Blade Templates
 **Description:** Laravel Blade template conventions covering components, output escaping, security, structure, and formatting.