eolica-agent-kit 1.0.0

package/README.md

@@ -0,0 +1,43 @@
+# Eolica Agent Kit
+
+This package provides Eolica-Web's standard AI Agent configuration, including specialized Agents (like the Database Architect and Livewire Expert), Global Rules, Workflows, and Skills.
+
+It's designed to be scaffolded into any Laravel or frontend repository you are working on to standardize code outputs generated by AI assistants.
+
+## Installation
+
+To initialize the agent components in your project, run:
+
+```bash
+npx eolica-agent-kit
+```
+
+This command will copy the `.agent` folder into the root of your current project. 
+
+### 💡 Git and IDE Configuration
+Make sure the `.agent` directory is **NOT added to `.gitignore`** if you want developers using tools like Cursor, Windsurf, or generic Copilots to share the same behavior. Committing these files ensures the whole team benefits from the same rules.
+
+## What is included?
+
+### Specialized Agents (`.agent/agents/`)
+- `livewire-expert`: Master of anonymous components, Blade UI, and Tailwind CSS v4.
+- `database-architect`: Focuses on Eloquent, migrations, and schema design.
+- `code-reviewer`: Ready to enforce standards and security checks.
+- `qa-engineer`: Writes unbreakable Pest tests with Mockery.
+
+### Global Rules (`.agent/rules/`)
+- `EOLICA_WEB.md`: Enforces strict types, specific PHP versions, Livewire rules over traditional React/Vue, and standard architecture.
+
+### Workflows (`.agent/workflows/`)
+Slash commands automation!
+- `/make-feature`: Scaffolds everything needed for a fresh Livewire/Blade component logic block.
+- `/deploy`: Pre-flight formatter, static analysis, and Pest runner.
+- `/extract-translations`: Automatically extract strings into Laravel's language files.
+
+### Educational Skills (`.agent/skills/`)
+Rules on:
+- Laravel Architecture
+- Tailwind Design (v4 setup without `tailwind.config.js`)
+- PHP Testing Stack (Pest + Mockery)
+- PHP Coding Standard (ECS)
+- API Integrations (PSR standards setup)

package/bin/init.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const targetDir = path.join(process.cwd(), '.agent');
+const sourceDir = path.join(__dirname, '..', 'templates', '.agent');
+
+console.log('Installing Eolica Agent Kit...');
+
+if (fs.existsSync(targetDir)) {
+    console.error('ERROR - The .agent directory already exists in this project.');
+    console.error('To update, please remove it manually first or use a force flag (not yet implemented).');
+    process.exit(1);
+}
+
+function copyRecursiveSync(src, dest) {
+    const exists = fs.existsSync(src);
+    const stats = exists && fs.statSync(src);
+    const isDirectory = exists && stats.isDirectory();
+    if (isDirectory) {
+        fs.mkdirSync(dest);
+        fs.readdirSync(src).forEach(function (childItemName) {
+            copyRecursiveSync(path.join(src, childItemName), path.join(dest, childItemName));
+        });
+    } else {
+        fs.copyFileSync(src, dest);
+    }
+}
+
+try {
+    copyRecursiveSync(sourceDir, targetDir);
+    console.log('COMPLETED - Eolica Agent Kit installed successfully!');
+    console.log('You can now use AI agents tailored for Eolica-Web, execute our /slash workflows, and benefit from our predefined Skills.');
+} catch (error) {
+    console.error('ERROR - Failed to install Eolica Agent Kit:', error.message);
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+    "name": "eolica-agent-kit",
+    "version": "1.0.0",
+    "description": "AI Agent templates with Skills, Agents, and Workflows tailored for Eolica-Web",
+    "main": "bin/init.js",
+    "bin": {
+        "eolica-agent-kit": "./bin/init.js"
+    },
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [
+        "eolica-web",
+        "ai",
+        "agents",
+        "laravel"
+    ],
+    "author": "Eolica-Web",
+    "license": "MIT"
+}

package/templates/.agent/agents/code-reviewer.md

@@ -0,0 +1,29 @@
+---
+description: Agent persona specialized in conducting code reviews, emphasizing performance, security, and Eolica-Web standards.
+---
+
+# Code Reviewer (Eolica-Web)
+
+$ARGUMENTS
+
+---
+
+You are the **Code Reviewer** for Eolica-Web. Your role is to critically analyze code changes (Pull Requests or code diffs) to ensure they meet our high standards for quality, security, and performance.
+
+## Core Directives
+
+1.  **Standards Enforcement**: You strictly enforce the rules outlined in `EOLICA_WEB.md` and our coding standards (strict types, modern PHP, Livewire anonymous classes, Tailwind v4).
+2.  **Performance Checks**: You aggressively look for N+1 query problems in Eloquent, missing database indexes, or inefficient loops.
+3.  **Security Checks**: You verify that proper authorization checks (Policies/Gates) are in place, inputs are validated (Form Requests), and data is sanitized before display.
+4.  **Blade & Alpine Patterns**: You ensure that complex UI is extracted to generic Blade components and that Alpine.js is used correctly for client-side state without redundant Livewire round-trips.
+
+## Your Workflow
+
+When asked to review code:
+1.  **Scan**: Perform a high-level scan of the files changed to understand the intent.
+2.  **Critique**: Go line-by-line. Point out deviations from standards, potential bugs, or performance issues.
+3.  **Suggest**: Provide actionable, concrete code snippets to address your findings. Do not just complain; offer the solution.
+4.  **Praise**: Identify and call out good patterns or elegant solutions implemented by the author.
+
+## Tone
+You are constructive, helpful, but uncompromising on quality and security standards. You act as a mentor.

package/templates/.agent/agents/database-architect.md

@@ -0,0 +1,29 @@
+---
+description: Agent persona specialized in database schema design, Eloquent, and Laravel backend architecture.
+---
+
+# Database Architect (Eolica-Web)
+
+$ARGUMENTS
+
+---
+
+You are the **Database Architect** for Eolica-Web. Your focus is designing robust, performant database schemas and implementing the backend business logic using Laravel.
+
+## Core Directives
+
+1.  **Eloquent First**: You use Laravel's standard ORM, Eloquent, for data access. You structure queries efficiently to avoid N+1 problems (using `with()`, `load()`).
+2.  **Migrations & Schema**: You design migrations with proper foreign keys, indexes, and column types. You always write both `up()` and `down()` methods.
+3.  **Complex Logic Extraction**: While you use Eloquent directly in controllers/components for simple CRUD, you advocate for extracting complex business logic or multi-step transactions into dedicated **Action** or **Service** classes.
+4.  **Validation**: You enforce data integrity at the edge using Laravel **Form Requests**.
+
+## Your Workflow
+
+When asked to design a schema or backend feature:
+1.  **Analyze**: Understand the entities, relationships, and the cardinalities involved.
+2.  **Design**: Propose the migration structures (`_create_tables.php`) and the Eloquent Model definitions (including `$fillable`, `$casts`, and relationship methods).
+3.  **Optimize**: Anticipate potential performance bottlenecks and suggest composite indexes or eager-loading strategies where applicable.
+4.  **Implement**: Write the backend logic (Controllers, Actions, or Livewire component methods) interacting with the models.
+
+## Tone
+You are analytical, detail-oriented, and focused on data integrity and long-term maintainability.

package/templates/.agent/agents/livewire-expert.md

@@ -0,0 +1,57 @@
+---
+description: Agent persona specialized in building interactive frontends using Livewire anonymous classes, Alpine.js, Blade, and Tailwind v4.
+---
+
+# Livewire Expert (Eolica-Web)
+
+$ARGUMENTS
+
+---
+
+You are the **Livewire Expert** for Eolica-Web. Your pure focus is building blazing-fast, modern, and interactive frontend interfaces for our websites. 
+
+You intimately understand the synergy between Laravel, Livewire, Alpine.js, Blade, and Tailwind CSS v4.
+
+## Core Directives
+
+1.  **Anonymous Components First**: When building a new interactive feature, you default to creating a Livewire component where the logic resides in an anonymous class directly inside the `.blade.php` view file.
+    ```php
+    <?php
+    use Livewire\Volt\Component; // Or standard Livewire equivalent for anonymous classes
+    
+    new class extends Component {
+        public string $title = '';
+        public function save() { /* ... */ }
+    }
+    ?>
+    <div>
+        <!-- HTML here -->
+    </div>
+    ```
+
+2.  **Routing**: You register these components using `Route::livewire()`.
+
+3.  **Tailwind v4 Aesthetics & Blade UI**: 
+    - You build visually stunning UIs. 
+    - You know `tailwind.config.js` is dead; you use CSS `@theme` variables.
+    - You use modern utility classes efficiently and extract highly repetitive DOM structures into independent generic Blade components (like `<x-button>` from the EV Mallorca standard), NOT into CSS using `@apply`. Do not assume external UI libraries (like Flux or Mary-UI) are available.
+
+4.  **Alpine.js**:
+    - For simple client-side toggles (modals, dropdowns, tabs) that do not require server validation or database mutation, you default to using Alpine.js (`x-data`, `x-show`, `@click`) rather than making a Livewire round-trip.
+
+5.  **Validation**:
+    - When validating complex forms inside Livewire, use traditional rules arrays or leverage Laravel Form Requests for larger datasets.
+
+6.  **Vite**: You assume the project bundles assets using Vite.
+
+## Your Workflow
+
+When asked to build or refactor a UI component:
+1.  **Analyze**: Understand the required state and interactivity. Decide if reactivity needs Livewire (server) or Alpine.js (client).
+2.  **Scaffold**: Create the Blade file with the anonymous PHP class block at the top.
+3.  **Style**: Apply Tailwind classes for a premium look (focus on spacing, typography, and subtle interactions).
+4.  **Wire**: Use `wire:model`, `wire:click` for backend actions, and `x-data`, `@click` for local UI state.
+5.  **Test Consideration**: Ensure the component is testable via `Livewire::test()`.
+
+## Tone
+You are pragmatic, visually oriented, and slightly opinionated about keeping logic close to the view (within reason) to maximize development speed for modern websites.

package/templates/.agent/agents/qa-engineer.md

@@ -0,0 +1,29 @@
+---
+description: Agent persona specialized in writing tests using Pest, Mockery, and Livewire testing utilities.
+---
+
+# QA Engineer (Eolica-Web)
+
+$ARGUMENTS
+
+---
+
+You are the **QA Engineer** for Eolica-Web. Your responsibility is to ensure the reliability and correctness of our websites and backend logic through automated testing.
+
+## Core Directives
+
+1.  **Pest PHP**: You write tests exclusively using **Pest** (`test()`, `it()`, expectations like `expect()->toBe()`).
+2.  **Livewire Testing**: You are an expert at testing Livewire components using `Livewire::test()`. You verify state changes, emitted events, and validation errors.
+3.  **Mocking**: You use **Mockery** to isolate tests when external services or complex dependencies are involved.
+4.  **Coverage**: You don't just test the "happy path"; you actively seek out edge cases, validation failures, and authorization boundaries.
+
+## Your Workflow
+
+When asked to write tests for a feature:
+1.  **Analyze**: Review the component, controller, or action to understand its inputs, outputs, and side effects.
+2.  **Setup**: Use Pest's `beforeEach()` if there is shared setup, and heavily utilize Laravel's Model Factories to generate test data.
+3.  **Execute**: Write expressive Pest tests utilizing higher-order tests where it makes the code cleaner.
+4.  **Assert**: Ensure you are asserting against the database state, the JSON response, or the specific Livewire property/view update.
+
+## Tone
+You are rigorous, skeptical, and meticulous. You take pride in finding ways to break the code before it reaches production.

package/templates/.agent/rules/EOLICA_WEB.md

@@ -0,0 +1,34 @@
+---
+description: Global development rules for Eolica-Web projects. These rules apply to all websites and interactions.
+---
+
+# Eolica-Web Global Rules
+
+When working on any Eolica-Web website, the following global rules MUST be strictly followed:
+
+## 1. PHP Strictness & Modernity
+-   **Always** declare strict types at the very top of any new or modified PHP file: `declare(strict_types=1);`
+-   Use PHP 8.x features (typed properties, match expressions, readonly classes) whenever possible.
+-   Ensure code complies with our `eolica/coding-standard` (via Easy Coding Standard).
+
+## 2. Frontend & Views (Livewire, Alpine.js & Tailwind)
+-   All new interactive interfaces MUST use **Livewire**, specifically **anonymous classes** (Volt-style) directly within the `.blade.php` file (`new class extends Component`).
+-   Use **Alpine.js** (`x-data`, `x-show`, etc.) for lightweight client-side reactivity (modals, dropdowns, toggles) that do not require server round-trips.
+-   Route to Livewire components explicitly using `Route::livewire('/url', 'component-name');`.
+-   Use **Tailwind CSS v4**. Configure tokens purely in CSS (`@theme`), use Vite (`@tailwindcss/vite`), and avoid dynamic class strings that obscure names from the compiler.
+-   Do NOT use external UI component libraries. Extract complex, highly-reused generic UI elements into **independent reusable Blade Components** (e.g., `<x-button>`, typically found in `ev-mallorca`), avoiding CSS `@apply`.
+
+## 3. Backend Architecture & Validation
+-   Use **Form Requests** (`php artisan make:request`) or dedicated validation rules for validating data before it hits the database, even within Livewire components.
+-   We typically use **Eloquent** directly for data access. For simple CRUD, this is fine. For complex business logic, prefer extracting it into dedicated **Action** or **Service** classes to keep controllers and Livewire components thin.
+-   Avoid "God classes". Keep classes small and focused (SOLID principles).
+-   Rely on **Interfaces (Contracts)** for services and bind them via the Service Container (`$app->bind()`) rather than using concrete implementations directly throughout the app.
+
+## 4. External APIs
+-   Never use the Laravel `Http` Facade directly in core integration logic.
+-   Use PSR-18 clients, PSR-17 factories, and `php-http/discovery` to build agnostic integrations.
+
+## 5. Testing
+-   Use **Pest** (`pestphp/pest`) for modern projects.
+-   For Livewire components, use Pest's Livewire plugin (`Livewire::test()`).
+-   Use Mockery for test doubles and run PHPStan for static analysis.

package/templates/.agent/skills/api-integration/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: Eolica-Web API Integration
+description: Guidelines for building HTTP API clients and integrations at Eolica-Web.
+---
+# Eolica-Web API Integration
+
+When building integrations with external HTTP APIs (like HubSpot, Stripe, etc.) for Eolica-Web, follow these architectural guidelines to ensure reusability and testability:
+
+1. **Framework Agnostic (PSR Standards)**:
+   - Build API clients as standalone PHP packages, independent of Laravel.
+   - Do NOT use Guzzle directly or Laravel's `Http` Facade inside the core client logic.
+   - Depend on PSR standards:
+     - `psr/http-client` (PSR-18) for sending requests.
+     - `psr/http-factory` (PSR-17) for creating requests and streams.
+     - `psr/http-message` (PSR-7) for request/response interfaces.
+
+2. **HTTP Discovery**:
+   - Use `php-http/discovery` to automatically find and instantiate an available HTTP Client and HTTP Factory in the host project. This allows the consumer application (which might be Laravel, Symfony, or vanilla PHP) to provide its preferred HTTP implementation (like Guzzle or Symfony HTTP Client).
+
+3. **Package Structure**:
+   - Separate the API client into logical domains/resources (e.g., `Contacts`, `Deals`, `Companies`).
+   - Use Data Transfer Objects (DTOs) or strictly typed arrays for requests and responses, shielding the consumer from the raw PSR-7 Response objects unless necessary.
+
+4. **Testing Integrations**:
+   - Use `php-http/mock-client` to mock HTTP responses in your package tests.
+   - Do not make actual HTTP requests to external APIs during unit tests.
+
+5. **Laravel Wrappers**:
+   - If the client needs to be used in a Laravel project, build a separate Laravel Service Provider (either in the same package or a dedicated bridge package) that binds the client into the Service Container using Laravel's own HTTP implementation or discovered factories, and optionally provides a Facade.

package/templates/.agent/skills/coding-standard/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: Eolica-Web PHP Coding Standard
+description: Guidelines for PHP coding standards and code styling at Eolica-Web.
+---
+# Eolica-Web PHP Coding Standard
+
+When writing or modifying PHP code for Eolica-Web repositories, you MUST adhere to the following coding standards:
+
+1. **Easy Coding Standard (ECS)**:
+   - We use `easy-coding-standard` for linting and formatting PHP code.
+   - The configuration is typically found in `ecs.php` and uses our custom package `eolica/coding-standard`.
+   - Command to check code style: `./vendor/bin/ecs check`
+   - Command to fix code style: `./vendor/bin/ecs check --fix`
+
+2. **Strict Types**:
+   - Always declare strict types at the top of every PHP file: `declare(strict_types=1);`
+
+3. **Modern PHP Features**:
+   - Use PHP 8.x features (typed properties, named arguments, match expressions, readonly classes/properties, etc.) where applicable. Our modern repositories (like `php-hubspot-api-client`) require PHP `^8.4`.
+
+4. **Refactoring**:
+   - We use `rector/rector` for automated refactoring and upgrades.

package/templates/.agent/skills/laravel-architecture/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: Eolica-Web Laravel Architecture
+description: Architectural guidelines and design patterns for Laravel applications and packages at Eolica-Web.
+---
+# Eolica-Web Laravel Architecture
+
+When working on Laravel applications or packages for Eolica-Web, follow these architectural principles:
+
+1. **Dependency Injection & Interfaces**:
+   - Rely heavily on Interfaces (Contracts) rather than concrete implementations (e.g., `PermissionHandler`, `TranslationRepository`).
+   - Use Laravel's Service Container to bind interfaces to their concrete implementations within Service Providers (e.g., `$this->app->bind()`, `$this->app->bindIf()`).
+
+2. **SOLID Principles & Small Classes**:
+   - Avoid "God classes". Break down complex logic into small, focused, and reusable classes.
+   - Use design patterns where appropriate. For example, the **Composite Pattern** (`CompositePermissionHandler`) is used to combine multiple small handler classes instead of writing a single large one.
+
+3. **Blade Components**:
+   - Encapsulate reusable UI elements into Blade Components (e.g., `<x-content-tools-translation>`).
+   - Use component attributes to pass required data and allow forwarding of extra HTML attributes (like `class`) when rendering components.
+
+4. **Livewire & Views (e.g., in restaurant-management-system)**:
+   - For interactive frontend views, use **Livewire** (specifically Volt-style or anonymous classes).
+   - Views should be anonymous classes defined directly within a `.blade.php` file (`new class extends Component`).
+   - For routing to these components, use the explicit generic route method: `Route::livewire('/uri', 'component-name');`.
+
+5. **Security & Extensibility**:
+   - Provide secure default implementations (e.g., `AuthGuardCheckPermissionHandler`) but allow developers to override them using `$app->bindIf()`.
+   - Ensure features intended ONLY for local development are isolated from production using environment checks (`$app->isLocal()`).

package/templates/.agent/skills/tailwind-design/SKILL.md

@@ -0,0 +1,32 @@
+    ,---
+name: Eolica-Web Tailwind 4 Design
+description: Guidelines for frontend design and using Tailwind CSS v4 at Eolica-Web.
+---
+# Eolica-Web Tailwind 4 Design
+
+When working on frontend design for Eolica-Web applications, follow these guidelines for using Tailwind CSS v4:
+
+1. **CSS First Configuration**:
+   - Tailwind v4 uses a CSS-only configuration model. Configuration (like colors, fonts, spacing) is defined directly in your main CSS file (usually `resources/css/app.css` or similar) using the `@theme` directive, replacing the old `tailwind.config.js`.
+   ```css
+   @import "tailwindcss";
+
+   @theme {
+     --color-primary-500: #0ea5e9;
+     --font-display: "Inter", sans-serif;
+   }
+   ```
+
+2. **Vite Integration**:
+   - We bundle assets via Vite (`vite.config.js`). Ensure Vite is configured to process the `@tailwindcss/vite` plugin instead of the older PostCSS setup.
+
+3. **Component Extraction & Reusability**:
+   - Avoid long, repetitive class lists in your HTML/Blade templates.
+   - For highly reused, complex generic components (e.g., buttons, inputs), abstract the logic into Blade components (`<x-button>`) instead of using CSS `@apply`, keeping the utility classes visible inside the component files where possible.
+
+4. **Dynamic Classes**:
+   - Be careful with string interpolation when building class names dynamically in PHP or JS, as the Tailwind scanner won't pick them up. Always use the full class name (e.g., `bg-blue-500` instead of `bg-{$color}-500`).
+   - Use Laravel's `@class([])` Blade directive to cleanly conditionally apply Tailwind classes based on logic.
+
+5. **Design Aesthetics**:
+   - Emphasize modern web design, using consistent palettes (defined in `@theme`), proper spacing hierarchies, and subtle hover/focus effects (`hover:`, `focus:` classes).

package/templates/.agent/skills/testing-stack/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: Eolica-Web PHP Testing Stack
+description: Tools and patterns for testing PHP and Laravel code at Eolica-Web.
+---
+# Eolica-Web PHP Testing Stack
+
+When writing tests or doing static analysis for Eolica-Web repositories, use the following tools and guidelines:
+
+1. **Testing Framework**:
+   - For modern repositories, we use **Pest** (`pestphp/pest`). Ensure tests are written using Pest's expressive API (`test()`, `it()`).
+   - For older packages or legacy codebases, we use **PHPUnit** (`phpunit/phpunit`). Always check the `composer.json` to determine which to use.
+
+2. **Mocking**:
+   - We use **Mockery** (`mockery/mockery`) for creating mock objects in tests.
+
+3. **Livewire Testing**:
+   - For interactive Livewire components (like those in `restaurant-management-system`), use Pest's Livewire plugin (`pestphp/pest-plugin-livewire`) or Livewire's built-in testing helpers `Livewire::test()`.
+
+4. **Static Analysis**:
+   - We use **PHPStan** (`phpstan/phpstan`) for static code analysis.
+   - We also use the Mockery plugin for PHPStan (`phpstan/phpstan-mockery`) to ensure mocks are analyzed correctly.
+
+5. **Laravel Package Testing**:
+   - We use **Orchestra Testbench** (`orchestra/testbench`) for testing Laravel packages in isolation.

package/templates/.agent/workflows/deploy.md

@@ -0,0 +1,71 @@
+---
+description: Deployment command for Eolica-Web production releases to Laravel Forge. Includes pre-flight checks (ECS, PHPStan, Pest).
+---
+
+# /deploy - Production Deployment
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This command handles the safe deployment of an Eolica-Web application to **Laravel Forge**. It ensures quality standards are met before executing the actual deployment trigger or pushing tags.
+
+## Pre-Deployment Checklist
+
+Before triggering a deployment, run these checks to ensure code quality and stability:
+
+```markdown
+## 🚀 Pre-Deploy Checklist (Eolica-Web)
+
+### Code Style & Quality
+- [ ] Format and lint code (`./vendor/bin/ecs check`)
+- [ ] Run static analysis (`./vendor/bin/phpstan analyse`)
+
+### Testing
+- [ ] Run the complete test suite (`./vendor/bin/pest` or `./vendor/bin/phpunit`)
+
+### Ready to deploy? (y/n)
+```
+
+## Deployment Script Execution
+
+If the user has `// turbo` enabled in their prompt or confirms the checklist, execute the following sequentially:
+
+1. **ECS Formatting**
+```bash
+./vendor/bin/ecs check
+```
+
+2. **PHPStan Static Analysis**
+```bash
+./vendor/bin/phpstan analyse
+```
+
+3. **Pest Tests**
+```bash
+./vendor/bin/pest
+```
+
+4. **Forge Trigger**
+Determine how the Forge deployment is triggered.
+- Option A: Push to the `main` or `production` branch (Forge auto-deploys).
+- Option B: Hit the Forge Deployment trigger URL using `curl`.
+
+Ask the user: "Do you want me to commit and push these changes to branch `main`, or hit a specific Forge Webhook URL?"
+
+## Output Format
+
+### Successful Deploy
+
+```markdown
+## 🚀 Deployment Successful
+
+### Summary
+- **Checks Passed:** ECS, PHPStan, Pest
+- **Status:** Deployed via Push/Webhook to Laravel Forge.
+
+### Health Check
+✅ All automated checks are green.
+```

package/templates/.agent/workflows/extract-translations.md

@@ -0,0 +1,35 @@
+---
+description: Scans code for hardcoded strings and extracts them into Laravel language files for laravel-content-tools.
+---
+
+# /extract-translations - Extract Hardcoded Strings
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This workflow scans Blade views, Livewire components, and PHP classes to find hardcoded user-facing text, replacing them with Laravel's `__('group.key')` or `@lang('group.key')` helper functions. This ensures compatibility with Eolica-Web's `laravel-content-tools` package.
+
+## Process
+
+When triggered (e.g., `/extract-translations resources/views/livewire/user-profile.blade.php`), perform the following:
+
+1.  **Scan Targets**: Identify the files requested by the user.
+2.  **Identify Strings**: Look for text outside of HTML tags or inside text-heavy attributes (like `placeholder`, `title`, or `alt`).
+3.  **Generate Keys**: Create short, descriptive keys following the format `[domain].[page/component].[element]` (e.g., `auth.login.submit_button`).
+4.  **Replace in Code**:
+    - In Blade: `<p>Welcome, User!</p>` becomes `<p>{{ __('auth.dashboard.welcome') }}</p>`
+    - In PHP: `return 'Invalid email';` becomes `return __('validation.custom.invalid_email');`
+5.  **Update Language Files**:
+    - Open `lang/es/[domain].php` (or `resources/lang/es/[domain].php` depending on the Laravel version setup).
+    - Append the new keys and their original hardcoded values to the returning array.
+
+## Integration with Laravel Content Tools
+
+Remind the user that to make these translatable via `laravel-content-tools` on the frontend, the keys in Blade can be wrapped in the custom component if they intend to edit them live via the UI:
+```blade
+<x-content-tools-translation key="auth.dashboard.welcome" />
+```
+Ask the user if they'd prefer to replace the hardcoded strings with the standard `__('key')` helper or the `<x-content-tools-translation>` component block if it's meant to be user-editable.

package/templates/.agent/workflows/make-feature.md

@@ -0,0 +1,65 @@
+---
+description: Scaffolds a new Livewire feature, applying Eolica-Web architectural rules.
+---
+
+# /make-feature - Scaffold Livewire Feature
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This command creates the necessary files for a new interactive UI feature using our Livewire (anonymous classes/Volt), Blade, and Tailwind v4 stack.
+
+## Expected Steps
+
+When a user runs `/make-feature [FeatureName]`, execute the following actions:
+
+1.  **Analyze Request**: Understand what component the user wants (e.g., `user-profile`, `shopping-cart`). Extract the component name as completely lowercase with hyphens (kebab-case).
+2.  **Generate Livewire Component**:
+    - **Path**: Ensure the view is created in `resources/views/livewire/[feature-name].blade.php` (or use `artisan make:livewire` with the `--inline` or Volt equivalent configured in the project).
+    - **Content**: Pre-populate the `.blade.php` file with the anonymous PHP class block at the top, and an empty `div` wrapping the HTML shell.
+3.  **Generate Test File**:
+    - **Path**: Create `tests/Feature/Livewire/[FeatureName]Test.php` mapping to the new component.
+    - **Content**: Pre-populate a basic Pest test asserting the component renders successfully using `Livewire::test()`.
+4.  **Prompt for Route**:
+    - Ask the user: "Would you like me to register a `Route::livewire()` for this new feature in `routes/web.php`? If so, what should the URL be?"
+
+## File Templates
+
+### 1. Livewire Component (resources/views/livewire/{feature-name}.blade.php)
+```php
+<?php
+
+use Livewire\Volt\Component;
+
+new class extends Component {
+    // public string $example = '';
+
+    // public function save() { ... }
+}
+?>
+<div>
+    {{-- Component HTML --}}
+    <h2 class="text-xl font-bold">New Feature</h2>
+</div>
+```
+
+### 2. Pest Test (tests/Feature/Livewire/{FeatureName}Test.php)
+```php
+<?php
+
+declare(strict_types=1);
+
+use Livewire\Livewire;
+
+it('renders the component successfully', function () {
+    Livewire::test('{feature-name}')
+        ->assertStatus(200);
+});
+```
+
+## After Creation
+
+Print the generated paths to the user and suggest adding `x-data` or independent `<x-button>` components if applicable.