# Project Guidelines

Este repositorio es una app Laravel con panel admin en Filament v3 y control de acceso con Spatie Permission + Filament Shield. También incluye un flujo de trabajo **spec-driven** (OpenSpec) en `openspec/` y prompts/skills en `.github/`.

## Architecture

- **Laravel app**: código principal en `app/`.
- **Admin panel (Filament v3)**: recursos/páginas/widgets en `app/Filament/`.
- **RBAC**: roles/permisos con `spatie/laravel-permission` y UI/ayudas con `bezhansalleh/filament-shield`.
- **Specs (OpenSpec)**: especificaciones en `openspec/specs/` (por ejemplo `openspec/specs/admin-filament-mysql.yaml`).

## Build and Test

Prioriza los scripts del proyecto (evitan pasos faltantes):

- **Setup inicial**: `composer run setup`
- **Dev (servidor + cola + logs + Vite)**: `composer run dev`
- **Tests**: `composer run test` (o `composer test`)
- **Frontend**:
  - Dev: `npm run dev`
  - Build: `npm run build`

Notas:
- PHP objetivo: `^8.2` (ver `composer.json`).
- La spec de OpenSpec puede mencionar otra versión de Laravel; toma `composer.json` como fuente de verdad para dependencias/versiones.
- Si tocas dependencias o autoload, recuerda que `composer install/update` dispara scripts (por ejemplo `php artisan filament:upgrade`).

## Code Style

- **PHP**: sigue convenciones de Laravel. Para formato usa Pint: `vendor/bin/pint`.
- **JS/CSS**: Vite + Tailwind (ver `package.json`). Mantén cambios de frontend compatibles con el pipeline de Vite.

## Conventions

- **Cambios guiados por spec (OpenSpec)**:
  - Antes de implementar features grandes, revisa la spec relevante en `openspec/specs/`.
  - Si estás trabajando en un “change” (artefactos delta), usa la carpeta `openspec/changes/`.
  - En vez de inventar requisitos, apóyate en la spec o pide aclaraciones.
- **Filament**:
  - Prefiere Resources/Pages/Widgets de Filament sobre controladores ad-hoc para el admin.
  - Aplica permisos/políticas de forma consistente con Spatie (y evita bypass en queries).

## Docs to Prefer Linking

- Specs: `openspec/specs/admin-filament-mysql.yaml`
- OpenSpec config: `openspec/config.yaml`
- Prompts/Skills del repo: `.github/prompts/` y `.github/skills/`
