symfonia-ai-tools 1.0.0

package/templates/packs/laravel/_ai/skills/migration/SKILL.md

@@ -0,0 +1,172 @@
+# Skill: Database Migration (Laravel)
+
+## Trigger
+Use when creating or modifying database schema.
+
+## Input
+- Operation: create table / add columns / modify column / rename / drop
+- Table name
+- Column definitions
+- Foreign keys / indexes
+
+## Steps
+
+### 1. Analyze current schema
+
+```bash
+# Check existing table structure
+docker exec {{DOCKER_CONTAINER}} php artisan db:show --table=[table_name]
+
+# Check existing migrations for context
+docker exec {{DOCKER_CONTAINER}} find Modules/*/Database/Migrations -name "*.php" | sort
+```
+
+Review the related Model to understand current column constants and casts.
+
+### 2. Create migration
+
+```bash
+docker exec {{DOCKER_CONTAINER}} php artisan make:migration [action]_[table]_table --path=Modules/[Module]/Database/Migrations
+```
+
+Naming conventions:
+- `create_invoices_table` — new table
+- `add_status_to_invoices_table` — add columns
+- `modify_amount_in_invoices_table` — change column type
+- `drop_legacy_field_from_invoices_table` — remove column
+
+### 3. Write migration
+
+```php
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        // Use Model constants for table/column names
+        Schema::create(InvoiceModel::TABLE_NAME, function (Blueprint $table) {
+            $table->id();
+            $table->string(InvoiceModel::COLUMN_TITLE);
+            $table->decimal(InvoiceModel::COLUMN_AMOUNT, 12, 2);
+            $table->foreignId(InvoiceModel::COLUMN_USER_ID)
+                ->constrained('users')
+                ->cascadeOnDelete();
+            $table->timestamps();
+            $table->softDeletes();
+
+            // Indexes for frequent queries
+            $table->index([InvoiceModel::COLUMN_USER_ID, InvoiceModel::COLUMN_STATUS]);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists(InvoiceModel::TABLE_NAME);
+    }
+};
+```
+
+Rules:
+- Always include `down()` that fully reverses `up()`
+- Use Model column constants (not raw strings)
+- Add `timestamps()` and `softDeletes()` on new tables
+- Add indexes for columns used in WHERE/ORDER BY
+- Use `constrained()` for foreign keys
+- `decimal(name, precision, scale)` for money — never float
+
+### 4. Test migration runs both ways
+
+```bash
+# Run migration
+docker exec {{DOCKER_CONTAINER}} php artisan migrate
+
+# Verify table structure
+docker exec {{DOCKER_CONTAINER}} php artisan db:show --table=[table_name]
+
+# Rollback
+docker exec {{DOCKER_CONTAINER}} php artisan migrate:rollback --step=1
+
+# Run again (confirms both up and down work)
+docker exec {{DOCKER_CONTAINER}} php artisan migrate
+```
+
+### 5. Update Model
+
+Add/update in the Model:
+- Column constants (`COLUMN_*`)
+- `$fillable` array
+- `$casts` array
+- Getter methods
+- Relation methods (if foreign key added)
+
+```php
+// New constants
+public const COLUMN_STATUS = 'status';
+
+// Update $fillable
+protected $fillable = [
+    // ... existing
+    self::COLUMN_STATUS,
+];
+
+// Update $casts
+protected $casts = [
+    // ... existing
+    self::COLUMN_STATUS => InvoiceStatus::class,
+];
+
+// New getter
+public function getStatus(): InvoiceStatus
+{
+    return $this->getAttribute(self::COLUMN_STATUS);
+}
+```
+
+### 6. Update Factory
+
+Add the new columns to the Factory definition:
+
+```php
+public function definition(): array
+{
+    return [
+        // ... existing
+        InvoiceModel::COLUMN_STATUS => $this->faker->randomElement(InvoiceStatus::cases()),
+    ];
+}
+
+// Add state for specific values
+public function active(): static
+{
+    return $this->state(fn () => [
+        InvoiceModel::COLUMN_STATUS => InvoiceStatus::ACTIVE,
+    ]);
+}
+```
+
+### 7. Run tests
+
+```bash
+# Full test suite — migration changes can break anything
+docker exec {{DOCKER_CONTAINER}} php artisan test
+```
+
+Fix any broken tests (missing columns in factories, changed types, etc.).
+
+### 8. Verification checklist
+
+- [ ] Migration has `declare(strict_types=1)`
+- [ ] `down()` fully reverses `up()`
+- [ ] Uses Model column constants
+- [ ] Foreign keys use `constrained()` with cascade rules
+- [ ] Indexes added for queried columns
+- [ ] Money uses `decimal`, never `float`
+- [ ] Migration runs and rollback works
+- [ ] Model updated: constants, fillable, casts, getters
+- [ ] Factory updated with new columns + states
+- [ ] All tests pass

package/templates/packs/laravel/_ai/skills/new-endpoint/SKILL.md

@@ -0,0 +1,165 @@
+# Skill: New API Endpoint (Laravel)
+
+## Trigger
+Use when adding a new API endpoint to an existing module.
+
+## Input
+- Module name
+- HTTP method + URL (e.g. POST /api/invoices/export)
+- Request payload
+- Response format
+- Authorization rules
+
+## Steps
+
+### 1. Create Form Request
+
+```bash
+docker exec {{DOCKER_CONTAINER}} php artisan make:request [Action][Entity]Request --path=Modules/[Module]/Http/Requests
+```
+
+Define `authorize()` and `rules()`. Use `Rule::in()` for enums, `exists:` for foreign keys.
+
+### 2. Create/Update Controller method
+
+If action fits CRUD (index/store/show/update/destroy) → add to existing controller.
+If custom action → create new controller:
+
+```php
+class Export[Entity]Controller extends Controller
+{
+    public function __invoke(Export[Entity]Request $request): JsonResponse
+    {
+        $dto = Export[Entity]DTO::fromRequest($request);
+        $result = $this->service->export($dto);
+        return Export[Entity]Resource::make($result)->response();
+    }
+}
+```
+
+For non-CRUD: prefer single-action controller with `__invoke`.
+
+### 3. Create DTO (if needed)
+
+```php
+readonly class Export[Entity]DTO
+{
+    public function __construct(
+        public int $userId,
+        public Carbon $dateFrom,
+        public Carbon $dateTo,
+        public string $format,
+    ) {}
+
+    public static function fromRequest(Export[Entity]Request $request): self
+    {
+        return new self(
+            userId: $request->user()->getId(),
+            dateFrom: Carbon::parse($request->validated('date_from')),
+            dateTo: Carbon::parse($request->validated('date_to')),
+            format: $request->validated('format'),
+        );
+    }
+}
+```
+
+### 4. Add Service method
+
+Add method to existing service. Keep it focused on one operation.
+
+```php
+public function export(Export[Entity]DTO $dto): ExportResult
+{
+    $items = $this->queryRepository->getByDateRange(
+        $dto->userId,
+        $dto->dateFrom,
+        $dto->dateTo,
+    );
+
+    // Business logic...
+
+    return new ExportResult($items, $dto->format);
+}
+```
+
+### 5. Create Resource (if new response format)
+
+```php
+class Export[Entity]Resource extends JsonResource
+{
+    public function toArray($request): array
+    {
+        return [
+            'url' => $this->getUrl(),
+            'filename' => $this->getFilename(),
+            'size' => $this->getSize(),
+        ];
+    }
+}
+```
+
+### 6. Update Policy (if new permission)
+
+Add method to existing policy. Register in ServiceProvider via `Gate::define()`.
+
+### 7. Add Route
+
+```php
+// In existing Routes/api.php group
+Route::post('/export', [Export[Entity]Controller::class, '__invoke'])
+    ->can('export', [Entity]::class);
+```
+
+### 8. Write Feature Test
+
+```php
+public function test_user_can_export(): void
+{
+    $response = $this->actingAs($this->user)
+        ->postJson('/api/[module]/export', [
+            'date_from' => '2025-01-01',
+            'date_to' => '2025-12-31',
+            'format' => 'pdf',
+        ]);
+
+    $response->assertOk()
+        ->assertJsonStructure(['data' => ['url', 'filename', 'size']]);
+}
+
+public function test_export_validates_input(): void
+{
+    $response = $this->actingAs($this->user)
+        ->postJson('/api/[module]/export', []);
+
+    $response->assertUnprocessable()
+        ->assertJsonValidationErrors(['date_from', 'date_to', 'format']);
+}
+
+public function test_unauthorized_user_cannot_export(): void
+{
+    $response = $this->actingAs($this->unauthorizedUser)
+        ->postJson('/api/[module]/export', $this->validPayload());
+
+    $response->assertForbidden();
+}
+```
+
+### 9. Verify
+
+```bash
+docker exec {{DOCKER_CONTAINER}} php artisan route:list --path=[module]/export
+docker exec {{DOCKER_CONTAINER}} php artisan test --filter=test_user_can_export
+docker exec {{DOCKER_CONTAINER}} php artisan optimize:clear
+```
+
+### 10. Verification checklist
+
+- [ ] Form Request validates all fields
+- [ ] Controller delegates to service (no business logic)
+- [ ] DTO used for data transfer (not raw arrays)
+- [ ] Service method is focused and testable
+- [ ] Resource formats response (no raw model)
+- [ ] Policy checks authorization
+- [ ] Route uses `->can()` for authorization
+- [ ] 3 tests minimum: happy path, validation, authorization
+- [ ] `declare(strict_types=1)` in all new files

package/templates/packs/laravel/_ai/skills/new-module/SKILL.md

@@ -0,0 +1,208 @@
+# Skill: New Module (Laravel)
+
+## Trigger
+Use when creating a new business domain module.
+
+## Input
+- Module name (PascalCase, e.g. "Invoice")
+- Main entity name
+- API endpoints needed
+- Relations to other modules
+
+## Steps
+
+### 1. Generate module skeleton
+
+```bash
+docker exec {{DOCKER_CONTAINER}} php artisan module:make [ModuleName]
+```
+
+### 2. Create directory structure
+
+```
+Modules/[ModuleName]/
+├── Config/
+│   └── config.php
+├── Console/
+├── Database/
+│   ├── Filters/
+│   ├── Migrations/
+│   ├── Repositories/
+│   │   ├── [Entity]CommandRepository.php        # Interface
+│   │   ├── [Entity]QueryRepository.php          # Interface
+│   │   ├── Eloquent[Entity]CommandRepository.php
+│   │   └── Eloquent[Entity]QueryRepository.php
+│   ├── Factories/
+│   │   └── [Entity]Factory.php
+│   └── Scopes/
+├── Domain/
+│   ├── DTO/
+│   │   └── [Entity]DTO.php
+│   ├── Services/
+│   │   └── [Entity]Service.php
+│   ├── Events/
+│   └── ValueObjects/
+├── Entities/
+│   └── [Entity]Model.php
+├── Http/
+│   ├── Controllers/
+│   │   └── [Entity]Controller.php
+│   ├── Policies/
+│   │   └── [Entity]Policy.php
+│   ├── Requests/
+│   │   ├── Store[Entity]Request.php
+│   │   ├── Update[Entity]Request.php
+│   │   └── Index[Entity]Request.php
+│   └── Resources/
+│       ├── [Entity]Resource.php
+│       └── [Entity]Collection.php
+├── Providers/
+│   ├── [ModuleName]ServiceProvider.php
+│   └── RouteServiceProvider.php
+├── Routes/
+│   └── api.php
+├── Tests/
+│   ├── Feature/
+│   │   └── [Entity]ControllerTest.php
+│   ├── Unit/
+│   │   └── [Entity]ServiceTest.php
+│   └── Fixtures/
+│       └── [Entity]Fixtures.php
+└── module.json
+```
+
+### 3. Create Eloquent Model
+
+```php
+declare(strict_types=1);
+
+namespace Modules\[ModuleName]\Entities;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+
+class [Entity]Model extends Model
+{
+    use HasFactory;
+    use SoftDeletes;
+
+    public const TABLE_NAME = '[table_name]';
+    public const COLUMN_ID = 'id';
+    public const COLUMN_NAME = 'name';
+    // ... column constants
+
+    public const RELATION_AUTHOR = 'author';
+
+    protected $table = self::TABLE_NAME;
+
+    protected $fillable = [
+        self::COLUMN_NAME,
+        // ...
+    ];
+
+    protected $casts = [
+        'created_at' => 'datetime',
+    ];
+
+    // Getters
+    public function getName(): string { return $this->getAttribute(self::COLUMN_NAME); }
+
+    // Relations
+    public function author(): BelongsTo { return $this->belongsTo(User::class, 'user_id'); }
+
+    // Allowed filters (Spatie)
+    public static function allowedFilters(): array { return []; }
+    public static function allowedSorts(): array { return []; }
+}
+```
+
+### 4. Create Migration
+
+```bash
+docker exec {{DOCKER_CONTAINER}} php artisan make:migration create_[table]_table --path=Modules/[ModuleName]/Database/Migrations
+```
+
+Use column constants from model. Always include `timestamps()` and `softDeletes()`.
+
+### 5. Create Repository interfaces + implementations
+
+Follow CQRS pattern - separate Command (write) and Query (read) repositories.
+See `service-repository.instructions.md` for patterns.
+
+### 6. Create Service
+
+`readonly class` with constructor injection. Business logic only - no HTTP concerns.
+
+### 7. Create DTO
+
+`readonly class` with `static fromRequest()` factory method.
+
+### 8. Create Controller
+
+CRUD methods only: `index`, `store`, `show`, `update`, `destroy`.
+Delegate to service, return Resources.
+
+### 9. Create Form Requests
+
+- `Store[Entity]Request` - create validation
+- `Update[Entity]Request` - update validation
+- `Index[Entity]Request` - list/filter validation
+
+### 10. Create Resources
+
+- `[Entity]Resource` - single entity
+- `[Entity]Collection` - paginated list
+
+### 11. Create Policy
+
+CRUD methods: `viewAny`, `view`, `create`, `update`, `delete`, `admin`.
+
+### 12. Create Routes
+
+```php
+Route::middleware(['auth:api'])->prefix('[module]')->group(function () {
+    Route::get('/', [[Entity]Controller::class, 'index']);
+    Route::post('/', [[Entity]Controller::class, 'store']);
+    Route::get('/{id}', [[Entity]Controller::class, 'show']);
+    Route::put('/{id}', [[Entity]Controller::class, 'update']);
+    Route::delete('/{id}', [[Entity]Controller::class, 'destroy']);
+});
+```
+
+### 13. Register ServiceProvider
+
+- Bind repository interfaces to implementations
+- Register policies via Gate
+- Register artisan commands
+- Load migrations
+
+### 14. Create Tests
+
+- Feature test for each endpoint (CRUD)
+- Unit test for service logic
+- Use `DatabaseTransactions` trait
+- Create `[Entity]Fixtures` trait with helpers
+
+### 15. Run and verify
+
+```bash
+docker exec {{DOCKER_CONTAINER}} php artisan migrate
+docker exec {{DOCKER_CONTAINER}} php artisan test --filter=[ModuleName]
+docker exec {{DOCKER_CONTAINER}} php artisan route:list --path=[module]
+```
+
+### 16. Verification checklist
+
+- [ ] `declare(strict_types=1)` in all PHP files
+- [ ] Model uses column constants, getters, relation constants
+- [ ] CQRS: separate Command and Query repositories
+- [ ] Service is `readonly class` with constructor injection
+- [ ] DTO is `readonly class` with `fromRequest()`
+- [ ] Controller delegates to service, returns Resources
+- [ ] Form Requests validate all input
+- [ ] Policy covers all CRUD operations
+- [ ] Routes use tuple notation `[Controller::class, 'method']`
+- [ ] ServiceProvider binds interfaces and registers everything
+- [ ] Feature + Unit tests pass
+- [ ] `php artisan optimize:clear` after changes