PHPackages vormkracht10/agents - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Testing & Quality](/categories/testing) 4. / 5. vormkracht10/agents ActiveLibrary[Testing & Quality](/categories/testing) vormkracht10/agents =================== This is my package agents v0.0.10(1mo ago)0316[2 PRs](https://github.com/ux-nl/agents/pulls)MITPHPPHP ^8.4||^8.3||^8.2CI passing Since Jan 20Pushed 3mo agoCompare [ Source](https://github.com/ux-nl/agents)[ Packagist](https://packagist.org/packages/vormkracht10/agents)[ Docs](https://github.com/vormkracht10/agents)[ GitHub Sponsors](https://github.com/Vormkracht10)[ RSS](/packages/vormkracht10-agents/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (28)Versions (13)Used By (0) UX Agents for Laravel ===================== [](#ux-agents-for-laravel) [![Latest Version on Packagist](https://camo.githubusercontent.com/d93f51368e9fe1eba49ae95bf600e1ad6c54f89d282b733ca3cc0a5bdf8ef9e8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f766f726d6b726163687431302f6167656e74732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/vormkracht10/agents)[![GitHub Tests Action Status](https://camo.githubusercontent.com/de4ab6db35710ecfba486409101bd3eb6310800b29f15eb6f8056d572581039a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f766f726d6b726163687431302f6167656e74732f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/vormkracht10/agents/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/79f0d51d4b0c2aab6533d72b3376f3b47c2a99645260e3f3825a35f6cd6ba440/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f766f726d6b726163687431302f6167656e74732f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/vormkracht10/agents/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/5a5453850a746040daff3387d3ec4153204f30a16793bd39f0f9f74604bba238/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f766f726d6b726163687431302f6167656e74732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/vormkracht10/agents) **UX Agents** is a Laravel package that automatically configures AI coding assistants (Claude, Cursor, Gemini) with framework-specific rules, skills, and agents based on your project's installed packages. It bridges the gap between your Laravel application and AI assistants by providing contextual guidelines that help AI understand your codebase conventions and best practices. The Problem It Solves --------------------- [](#the-problem-it-solves) When working with AI coding assistants on Laravel projects, the AI often lacks context about: - Framework-specific conventions (Filament patterns, Pest testing standards) - Project-specific best practices and coding standards - Available testing utilities and helpers - Proper usage patterns for third-party packages This leads to AI-generated code that doesn't follow your project conventions, uses outdated patterns, or misses framework-specific optimizations. The Solution ------------ [](#the-solution) UX Agents automatically: 1. **Detects** installed packages in your `composer.lock` 2. **Matches** them against registered drivers (Filament, Pest, etc.) 3. **Provisions** AI-specific configuration directories (`.claude/`, `.cursor/`, `.gemini/`) 4. **Generates** instruction files (`CLAUDE.md`, `.cursorrules`, `GEMINI.md`, `AGENTS.md`) 5. **Links** rules, skills, and specialized agents that teach AI assistants about your stack Key Features ------------ [](#key-features) - **Auto-Discovery**: Automatically detects relevant packages from your composer dependencies - **Driver-Based Architecture**: Extensible system for adding support for new frameworks and tools - **Multi-AI Support**: Configures Claude Code, Cursor, and Gemini simultaneously - **Rules & Skills**: Provides both high-level rules and detailed skill documentation - **Specialized Agents**: Includes pre-configured AI agents for specific tasks (code quality, testing) - **Zero Configuration**: Works out of the box with sensible defaults - **Package Discovery Hook**: Automatically runs when you install/update composer packages Installation ------------ [](#installation) Install the package via composer: ``` composer require vormkracht10/agents ``` The package will automatically configure itself during composer's package discovery process. You can also manually trigger configuration: ``` composer dump-autoload ``` How It Works ------------ [](#how-it-works) ### Architecture Overview [](#architecture-overview) ``` ┌─────────────────────────────────────────────────────────┐ │ composer.lock │ │ (your project's installed packages) │ └─────────────────┬───────────────────────────────────────┘ │ │ Package Discovery Event │ ▼ ┌─────────────────────────────────────────────────────────┐ │ AgentsServiceProvider │ │ Listens for package:discover command │ └─────────────────┬───────────────────────────────────────┘ │ │ Triggers Configuration │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Agents Class │ │ - Scans composer.lock for installed packages │ │ - Matches packages against registered drivers │ │ - Collects rules, skills, and agents │ └─────────────────┬───────────────────────────────────────┘ │ │ Creates Resources │ ▼ ┌─────────────────────────────────────────────────────────┐ │ AI Provider Directories │ │ │ │ .claude/ │ │ ├── rules/ │ │ │ ├── filament.md │ │ │ └── pest.md │ │ ├── skills/ │ │ │ ├── filament/ │ │ │ │ ├── 01-overview.md │ │ │ │ └── 02-testing-resources.md │ │ │ └── pest/ │ │ │ └── testing-guide.md │ │ └── agents/ │ │ ├── code-quality-guardian.md │ │ └── unit-test-writer.md │ │ │ │ .cursor/ (same structure) │ │ .gemini/ (same structure) │ │ │ │ CLAUDE.md (instruction file with references) │ │ .cursorrules (instruction file for Cursor) │ │ GEMINI.md (instruction file for Gemini) │ │ AGENTS.md (cross-provider documentation) │ └─────────────────────────────────────────────────────────┘ ``` ### Component Breakdown [](#component-breakdown) #### 1. Service Provider (`AgentsServiceProvider`) [](#1-service-provider-agentsserviceprovider) The service provider is the entry point that: - Registers itself with Laravel's service container - Listens for the `package:discover` command via Laravel events - Triggers the configuration process automatically when packages are installed/updated - Registers the `AgentMap` singleton for managing drivers ``` Event::listen(CommandFinished::class, function (CommandFinished $event) { if ($event->command === 'package:discover') { Agents::configure($command); } }); ``` #### 2. Agents Class (`Agents`) [](#2-agents-class-agents) The main orchestrator that: **Package Detection** ``` protected function getInstalledPackages(): array { $lockPath = base_path('composer.lock'); $lock = json_decode(File::get($lockPath), true); return collect($lock['packages'] ?? []) ->merge($lock['packages-dev'] ?? []) ->pluck('name') ->toArray(); } ``` **Driver Matching** ``` public function listDrivers(): array { $installedPackages = $this->getInstalledPackages(); $drivers = AgentMap::getDrivers(); $foundDrivers = []; foreach ($drivers as $driver) { $driverInstance = AgentMap::driver($driver); if (in_array($driverInstance->getSlug(), $installedPackages)) { $foundDrivers[] = $driverInstance; } } return $foundDrivers; } ``` **Resource Provisioning** - Creates `.claude/`, `.cursor/`, `.gemini/` directories - Copies rules, skills, and agent files from package resources - Generates instruction files with references to all resources - Creates an `AGENTS.md` file documenting all configured resources #### 3. Driver System [](#3-driver-system) **AgentDriver (Abstract Base)** All drivers extend this base class and must implement: ``` abstract class AgentDriver implements DriverContract { // The composer package name to detect abstract public function getSlug(): string; // The directory name for resources (lowercase-hyphenated) abstract public function getPath(): string; // Human-readable name for display abstract public function getTitle(): string; // Returns path to rules file public function getRules(): string // Returns array of skill files public function getSkills(): array } ``` **Example: FilamentDriver** ``` class FilamentDriver extends AgentDriver { public function getSlug(): string { return 'filament/filament'; // Detects filament/filament in composer.lock } public function getPath(): string { return 'filament'; // Uses resources/rules/filament/ and resources/skills/filament/ } public function getTitle(): string { return 'Filament'; // Displayed in console output } } ``` #### 4. AgentMap (Driver Registry) [](#4-agentmap-driver-registry) Manages driver instances using Laravel's Manager pattern: ``` class AgentMap extends Manager { protected array $registeredDrivers = [ 'pest', 'filament', ]; // Factory methods protected function createPestDriver(): AgentDriver { return new \Vormkracht10\Agents\Drivers\PestDriver; } protected function createFilamentDriver(): AgentDriver { return new \Vormkracht10\Agents\Drivers\FilamentDriver; } } ``` ### Resource Types [](#resource-types) #### Rules (`resources/rules/{driver}/rules.md`) [](#rules-resourcesrulesdriverrulesmd) High-level guidelines and conventions that AI assistants should follow. These are typically: - Framework conventions (Laravel 11/12 patterns) - Project-specific coding standards - Architecture patterns and best practices - Security considerations - Naming conventions **Example Structure:** ``` # Filament v4 Guidelines ## General Principles - Target Filament v4 only - Prefer clarity over cleverness - Keep logic out of UI layer ## Resources - One Eloquent model = one Filament Resource - Resources must be thin (no business logic) ## Actions (MANDATORY RULE) - Every Action MUST be in its own stand-alone class file - ❌ Defining actions inline is forbidden ``` #### Skills (`resources/skills/{driver}/*.md`) [](#skills-resourcesskillsdrivermd) Detailed, tutorial-style documentation with code examples. Skills teach: - How to test specific framework features - Step-by-step implementation guides - Common patterns and their solutions - Testing utilities and helpers **Example Structure:** ``` --- title: Testing Filament Resources description: Guide to testing Filament v4 resources using Pest --- ## Introduction This guide covers testing Filament resources... ## Setup ```php use function Pest\Livewire\livewire; ``` Testing Resource Authorization ------------------------------ [](#testing-resource-authorization) ``` it('prevents unauthorized access', function () { livewire(UserResource\Pages\ListUsers::class) ->assertForbidden(); }); ``` ``` #### Agents (`resources/agents/*.md`) Specialized AI agent configurations with frontmatter that defines: - Agent name and description - When to invoke the agent - Model preference (sonnet, opus, haiku) - Color coding for UI - Detailed system prompt with responsibilities and processes **Example Structure:** ```markdown --- name: code-quality-guardian description: "Use this agent after writing new code..." model: opus color: blue --- You are an elite Laravel code quality specialist... ## Your Core Responsibilities 1. Laravel Pint - Code style formatting 2. PHPStan - Static analysis 3. Rector - Automated refactoring ... ## Your Review Process ### Step 1: Initial Assessment ### Step 2: Run Quality Tools ### Step 3: Manual Code Review ... ``` ### Generated Files [](#generated-files) #### Provider-Specific Instruction Files [](#provider-specific-instruction-files) **CLAUDE.md** ``` ## Agent Skills & Rules This project has the following agent configurations. ### Filament #### Rules Read and follow the rules in [.claude/rules/filament.md](.claude/rules/filament.md) #### Skills - [.claude/skills/filament/01-overview.md](.claude/skills/filament/01-overview.md) - [.claude/skills/filament/02-testing-resources.md](.claude/skills/filament/02-testing-resources.md) ### Agents - [.claude/agents/code-quality-guardian.md](.claude/agents/code-quality-guardian.md) ``` **.cursorrules** (same structure, different format) **GEMINI.md** (same structure) #### AGENTS.md (Cross-Provider Documentation) [](#agentsmd-cross-provider-documentation) A comprehensive overview of all configured resources across all AI providers: ``` ## AI Assistant Resources ### Claude #### Filament - **Rules**: [.claude/rules/filament.md](.claude/rules/filament.md) - **Skills**: - [.claude/skills/filament/01-overview.md](.claude/skills/filament/01-overview.md) ### Cursor #### Filament - **Rules**: [.cursor/rules/filament.md](.cursor/rules/filament.md) ... ``` Usage ----- [](#usage) ### Automatic Configuration [](#automatic-configuration) The package automatically configures itself when you: 1. Install the package: `composer require vormkracht10/agents` 2. Install/update any package: `composer install` or `composer update` 3. Manually refresh: `composer dump-autoload` You'll see output like: ``` Collecting packages... ┌───────────┐ │ Drivers │ ├───────────┤ │ Filament │ │ Pest │ └───────────┘ Setting rules for the selected driver... ``` ### Using with AI Assistants [](#using-with-ai-assistants) #### Claude Code [](#claude-code) Claude automatically reads `CLAUDE.md` and the `.claude/` directory. Start coding and Claude will: - Follow the rules defined in `.claude/rules/` - Reference skills from `.claude/skills/` when needed - Suggest using specialized agents from `.claude/agents/` Example interaction: ``` You: "Create a new Filament resource for managing products" Claude: "I'll create a Filament v4 resource following the project guidelines. Based on .claude/rules/filament.md, I need to ensure actions are in separate classes and follow the established patterns..." ``` #### Cursor [](#cursor) Cursor reads `.cursorrules` and the `.cursor/` directory automatically. The IDE will: - Apply rules during code generation - Suggest patterns from skills documentation - Integrate specialized agents into workflows #### Gemini [](#gemini) Gemini uses `GEMINI.md` and the `.gemini/` directory for context-aware assistance. ### Viewing Configuration [](#viewing-configuration) Check `AGENTS.md` in your project root to see all configured resources across all providers. Creating Custom Drivers ----------------------- [](#creating-custom-drivers) Adding support for new frameworks or tools is straightforward: ### Step 1: Create the Driver Class [](#step-1-create-the-driver-class) Create `src/Drivers/YourDriver.php`: ```