laravel-flow-admin

Anchor skill for the padosoft/laravel-flow-admin package. Read FIRST when opening this repo to understand stack (Laravel 13 + PHP 8.3/8.4 + Blade + Vite + Alpine.js + Playwright), where the design source lives (.design-source/), the read-model contract from padosoft/laravel-flow we consume, and the macro/subtask branch + Copilot review loop. Trigger when starting any work in this repo, when restarting a session, or when a sub-agent is dispatched.

BEFORE every `git push`, run a systematic self-review on the diff against a checklist of the recurring footguns Copilot has flagged in this codebase. The goal is to catch issues that would otherwise consume Copilot review cycles. Trigger BEFORE typing `git push`, after `git commit`, when about to open a PR with `gh pr create`, when running the local test gate, or when the user asks to "review my changes" / "lint diff" / "check diff".

Use to implement the backend slice of a complex Laravel admin page (controller, view-model factories, query layer with eager loading, FormRequest validation, action handlers gated by authorizer, pagination/sorting/filtering DTOs). Trigger when adding/modifying any controller under `src/Http/Controllers/` or `routes/flow-admin.php`, when wiring a new admin route, or when working on a Macro 5/6/7 backend slice per `docs/IMPLEMENTATION_PLAN.md`.

Use BEFORE building or refactoring any admin page to inventory existing Blade components, partials, design tokens, and reusable Alpine stores so the new work composes existing primitives instead of duplicating them. Trigger at the start of every Macro 3/5/6/7 UI slice, before adding a new Blade component, or when Copilot flags duplication during review.

Use to implement the frontend slice of a complex Laravel admin page using Blade + Vite + Alpine.js (no SPA framework). Covers Blade partials/components, Alpine stores for client state, design-token CSS hygiene, status badges, JSON syntax-highlight, sparklines, charts, drawer, modal, ⌘K palette interactions. Trigger when adding/modifying templates under `resources/views/`, CSS under `resources/css/`, or JS under `resources/js/`, and when implementing a Macro 3/5/6/7/8 UI slice per `docs/IMPLEMENTATION_PLAN.md`.

Orchestrator skill for creating or refactoring complex Laravel admin pages with KPI tiles, filters, tables, drawers, modals, charts, exports. Coordinates the audit → backend → frontend → test phases by dispatching to `admin-interface-component-audit`, `admin-interface-backend`, `admin-interface-frontend`, and `playwright-enterprise-tester`. Trigger when user asks to "build an admin page", "add a dashboard view", "refactor the admin shell", or when starting any Macro 5/6/7 page implementation in `docs/IMPLEMENTATION_PLAN.md`.

Use when creating a JSON endpoint under `/flow/api/*` (e.g. `/flow/api/search`, `/flow/api/live`) backing the admin UI. Covers route registration, FormRequest validation, JSON resource shape, authorizer gating, CSRF or session-based auth (no Sanctum tokens for browser-held UI), pagination contract, and Feature test coverage. Trigger when adding/modifying any AJAX or polling endpoint in `routes/flow-admin.php`.

Use to introduce a new Laravel controller in this package following the FormRequest → DTO → Service → ViewModel → Blade pipeline. Covers route registration in `routes/flow-admin.php`, view namespace usage (`flow-admin::`), CSRF on POST forms, authorizer gating for mutations, and Feature test coverage via Testbench. Trigger when adding/modifying any class under `src/Http/Controllers/`.

Use when creating a small focused service or action object in this Laravel package (no fat services, no static helpers). Covers single-responsibility design, constructor DI, immutable inputs/outputs (DTOs, view models), explicit exceptions, and unit-test scaffolding. Trigger when adding/modifying any class under `src/Support/`, `src/Adapters/`, or any non-controller orchestration class.

Use when introducing PHPUnit Unit / Feature / Architecture tests for new Laravel package code. Covers Testbench TestCase setup, SQLite fixtures, RefreshDatabase, snapshot DTO assertions, architecture pins for `Padosoft\LaravelFlowAdmin\Contracts\*` and config-key invariants. Pair with `playwright-enterprise-tester` for new UI behaviour. Trigger before pushing any PR that adds/modifies behaviour without a corresponding test.

Use when adding, fixing, or hardening Playwright end-to-end scenarios for Laravel admin UIs. Covers selector hygiene (data-testid + role/label, no brittle text), enterprise patterns (page objects, fixtures, retries, accessibility checks), CI matrix (chromium + firefox + webkit), visual regression with sensible tolerance, and triage of cross-browser flakiness. Trigger when creating tests under `tests/e2e/`, when CI Playwright job goes red, or when a UI page goes from prototype to v0.x and needs scenario coverage.