# TenantPilot - Agent Guidelines ## Context TenantPilot is an Intune Management application built with **Laravel** and **Filament**. It re-implements and extends key features inspired by the IntuneManagement project, with a focus on admin productivity, safe change management, and auditability. This repo uses GitHub Spec Kit. Primary spec artifacts live in `.specify/`. **Sail-first for local development. Dokploy-first for staging/production.** ## Product Goals - Provide **Intune policy version control** (diff, history, rollback). - Enable reliable **backup and restore** of Intune configurations. - Extend Intune with **admin-focused features** that improve visibility, safety, and velocity. - Prioritize **auditability**, **least privilege**, and predictable operations. ## Scope Reference When designing or implementing features, align with: - Policy inventory & metadata normalization - Change tracking and version snapshots - Safe restore flows (dry-run, validation, partial restore) - Reporting, dashboards, and operational insights - Tenant-scoped RBAC and audit logs ## Workflow (Spec Kit) 1. Read `.specify/constitution.md` 2. For new work: create/update `specs/-/spec.md` 3. Produce `specs/-/plan.md` 4. Break into `specs/-/tasks.md` 5. Implement changes in small PRs If requirements change during implementation, update spec/plan before continuing. ## Workflow (SDD in diesem Repo) ### Branching - Default / Integrations-Branch: `dev` - Neue Arbeit läuft über Feature-Branches von `dev`: - `feat/-` (Code + Spec im selben PR) - optional: `spec/-` (nur wenn wir Specs getrennt reviewen wollen) ### Wo liegen Specs? - `.specify/` enthält SpecKit Tooling und die Constitution (Prozessregeln). - Feature-Specs liegen **immer** im Repo unter: - `specs/-/plan.md` - `specs/-/tasks.md` - `specs/-/spec.md` - `specs/` muss im `dev`-Branch immer existieren (Baseline). ### Variante B Standard (Spec + Code in einem PR) 1) Branch von `dev` erstellen: `feat/-` 2) Zuerst Specs erstellen/aktualisieren → erster Commit (`spec:`) 3) Dann implementieren → weitere Commits (`feat:`, `fix:`, `test:`) 4) PR/MR: `feat/...` → `dev` 5) Merge nach `dev` (empfohlen: Squash) ### Gate-Regel - Wenn Code geändert wird (z.B. `app/`, `config/`, `database/`, `resources/`), muss der PR auch `specs/-/` enthalten oder aktualisieren. ## Multi-Agent Coordination **Problem:** Multiple AI agents working simultaneously on the same branch can create conflicts and confusion. **Solution:** Each agent session works on its own isolated branch. ### Before Starting Work 1. **Check branch status:** ```bash git status ``` Must be clean. If dirty, stash or commit first. 2. **Note current state:** ```bash git log -1 --oneline ``` Record the latest commit hash for reference. 3. **Create session branch:** ```bash # From feature branch (e.g., 001-filament-json) git checkout -b $(git branch --show-current)-session-$(date +%s) ``` Example: `001-filament-json-session-1734789123` 4. **Confirm isolation:** ```bash git branch --show-current ``` ### During Work - Make commits normally on your session branch - Session branch is throwaway - commit messages can be informal - Run tests frequently to validate changes ### After Completing Work 1. **Switch back to feature branch:** ```bash # Get the original branch name (remove -session-timestamp suffix) ORIGINAL_BRANCH=$(git branch --show-current | sed 's/-session-[0-9]*$//') git checkout $ORIGINAL_BRANCH ``` 2. **Merge session work:** ```bash SESSION_BRANCH=$(git branch | grep session | tail -1 | xargs) git merge $SESSION_BRANCH --no-ff -m "merge: agent session work" ``` 3. **Clean up session branch:** ```bash git branch -d $SESSION_BRANCH ``` ### Alternative: Git Worktree (Advanced) For completely isolated work environments: ```bash # Create worktree for session git worktree add ../TenantAtlas-session-$(date +%s) $(git branch --show-current) # Work in separate directory cd ../TenantAtlas-session-* # After completion, merge back and remove worktree cd /path/to/main/TenantAtlas git merge worktree-branch git worktree remove ../TenantAtlas-session-* ``` ### Emergency: Undo Conflicting Changes If two agents accidentally worked on the same branch: ```bash # Reset to before the conflict git log --oneline -10 # Find the safe commit git reset --hard # Or stash conflicting changes git stash push -m "conflicting-agent-work-$(date +%s)" ``` ## Solo + Copilot Workflow (Konflikte vermeiden) Wenn du alleine arbeitest (du + Copilot), sind große Konflikt-Stürme fast immer „Branch drift“: `dev` bewegt sich weiter, das Feature hängt hinterher. Diese Regeln halten Feature-Branches mergebar. ### Regel 1: Vor jeder Troubleshooting-Änderung zuerst `dev` ins Feature holen Bevor du einen kleinen Fix auf einem Feature-Branch machst (z.B. `config/`, `tests/`, shared Services), synchronisiere: ```bash git fetch origin git checkout feat/- git merge origin/dev ``` ### Regel 2: Kurzlebige „Session Branches“ auch im Solo-Setup Auch wenn du alleine bist: nutze Session-Branches für gezielte Fixes, damit du jederzeit sauber abbrechen kannst. ```bash git checkout feat/- git checkout -b $(git branch --show-current)-session-$(date +%s) ``` Danach wie gewohnt committen, testen, zurück-merge: ```bash SESSION_BRANCH=$(git branch --show-current) ORIGINAL_BRANCH=$(git branch --show-current | sed 's/-session-[0-9]*$//') git checkout $ORIGINAL_BRANCH git merge $SESSION_BRANCH --no-ff -m "merge: agent session work" ``` ### Regel 3: „Globale“ Fixes als Mini-PR nach `dev` Wenn ein Fix nicht wirklich feature-spezifisch ist (z.B. `config/graph_contracts.php`, Test-Bootstrap, allgemeine Graph-Validation), dann: - Mini-Branch von `dev` erstellen und PR → `dev` mergen. - Danach im Feature-Branch einfach wieder `origin/dev` mergen. Das reduziert Add/Add-Konflikte drastisch, weil `dev` die gemeinsame Wahrheit bleibt. ### Regel 4: Kein Rebase auf geteilten Branches Wenn du und Copilot über längere Zeit auf demselben Feature-Branch arbeiten, bleib bei `merge origin/dev` (kein Rebase), damit die Historie stabil bleibt. ## Architecture Assumptions - Backend: Laravel (latest stable) - Admin UI: Filament - Auth: Microsoft identity integration (Entra ID/Azure AD) when applicable - External API: Microsoft Graph for Intune Do not assume additional services unless stated in spec. --- ## DevOps & Environments ### Local Development - Local dev & testing use **Laravel Sail** (Docker). - Prefer Sail commands when referencing setup or running tests. - PostgreSQL is used locally via Sail. - **Drizzle** is used locally for PostgreSQL tooling (e.g., schema inspection, dev workflows) **if configured in the repo**. ### Repository - Repository is hosted on **Gitea**. - Do not assume GitHub-specific features (Actions, GH-specific PR automation) unless explicitly added. - CI suggestions should be compatible with Gitea pipelines or external CI runners. ### Deployment - Deployed via **Dokploy** on a **VPS**. - Two environments: - **Staging** - **Production** - Assume container-based deployments. - Changes that affect runtime must consider: - environment variables - database migrations - queue/cron workers - storage persistence/volumes - reverse proxy/SSL likely handled by Dokploy ### Release & Promotion Rules - Staging is the mandatory validation gate for Production. - Prefer: - feature flags for risky admin operations - staged rollout for backup/restore/versioning changes - Schema changes must be validated on Staging before Production. ### Release Safety - For schema changes: - provide safe, incremental migrations - avoid long locks - document rollback/forward steps - For Intune-critical flows: - prefer dry-run/preview - require explicit confirmation - ensure audit logs --- ## Data Layer - Database: **PostgreSQL** - Prefer **JSONB** to store raw Graph policy snapshots and backup payloads. - Add appropriate indexes (e.g., **GIN** on JSONB where search/filter is expected). - Migrations must be reversible where possible. ## Versioning Storage Strategy - Store **immutable** policy snapshots. - Track metadata separately (tenant, policy type, platform, created_by, created_at). - Prefer **full snapshots first** for correctness and simplicity. - Consider retention policies to prevent unbounded growth. --- ## Engineering Rules - PHP: follow PSR-12 conventions. - Prefer Laravel best practices (Service classes, Jobs, Events, Policies). - Keep Microsoft Graph integration isolated behind a dedicated abstraction layer. - Use dependency injection and clear interfaces for Graph clients. - No breaking changes to data structures or API contracts without updating: - `specs/-/spec.md` - migration notes - upgrade steps - If a TypeScript/JS tooling package exists, use strict typing rules there too. ## Intune Data & Safety Rules - Treat Intune resources as **critical configuration**. - Every destructive action must support: - explicit confirmation UI - audit log entry - optional dry-run/preview mode if feasible - Restore must be defensive: - validate inputs - detect conflicts - allow selective restore - show a clear pre-execution summary ## Version Control Semantics - A "version" should be reproducible and queryable: - what changed - when - by whom - source tenant/environment - Provide diff outputs where possible: - human-readable summary - structured diff (JSON) ## Observability & Audit - Log Graph calls at a high-level (no secrets). - Maintain an audit trail for: - backups created - restores executed/attempted - policy changes detected/imported - Ensure logs are tenant-scoped and RBAC-respecting. ## Security - Enforce least privilege. - Never store secrets in config or code. - Use Laravel encrypted storage or secure secret management where applicable. - Validate all tenant identifiers and Graph scopes. --- ## Commands ### Sail (preferred locally) - `./vendor/bin/sail up -d` - `./vendor/bin/sail down` - `./vendor/bin/sail composer install` - `./vendor/bin/sail artisan migrate` - `./vendor/bin/sail artisan test` - `./vendor/bin/sail artisan` (general) ### Drizzle (local DB tooling, if configured) - Use only for local/dev workflows. - Prefer running via package scripts, e.g.: - `pnpm drizzle:generate` - `pnpm drizzle:migrate` - `pnpm drizzle:studio` (Agents should confirm the exact script names in `package.json` before suggesting them.) ### Non-Docker fallback (only if needed) - `composer install` - `php artisan serve` - `php artisan migrate` - `php artisan test` ### Frontend/assets/tooling (if present) - `pnpm install` - `pnpm dev` - `pnpm test` - `pnpm lint` --- ## Where to look first - `.specify/` - `AGENTS.md` - `README.md` - `app/` - `database/` - `routes/` - `resources/` - `config/` --- ## Definition of Done - Spec + Plan + Tasks aligned with implementation. - Tests added/updated. - UI includes clear admin-safe affordances for backup/restore/versioning. - Audit logging implemented for sensitive flows. - Documentation updated (README or in-app help). - Deployment impact assessed for: - Staging - Production - migrations, env vars, queues --- ## AI Usage Note All AI agents must read: - `AGENTS.md` - `.specify/*` before proposing or implementing changes. ## Reference Materials - PowerShell scripts from IntuneManagement are stored under `/references/IntuneManagement-master` for implementation guidance only. - They must not be treated as production runtime dependencies. === === .ai/filament-v5-blueprint rules === ## Source of Truth If any Filament behavior is uncertain, lookup the exact section in: - docs/research/filament-v5-notes.md and prefer that over guesses. # SECTION B — FILAMENT V5 BLUEPRINT (EXECUTABLE RULES) # Filament Blueprint (v5) ## 1) Non-negotiables - Filament v5 requires Livewire v4.0+. - Laravel 11+: register panel providers in `bootstrap/providers.php` (never `bootstrap/app.php`). - Global search hard rule: If a Resource should appear in Global Search, it must have an Edit or View page; otherwise it will return no results. - Destructive actions must execute via `Action::make(...)->action(...)` and include `->requiresConfirmation()` (no exceptions). - Prefer render hooks + CSS hook classes over publishing Filament internal views. Sources: - https://filamentphp.com/docs/5.x/upgrade-guide - https://filamentphp.com/docs/5.x/panel-configuration - https://filamentphp.com/docs/5.x/resources/global-search - https://filamentphp.com/docs/5.x/actions/modals - https://filamentphp.com/docs/5.x/advanced/render-hooks - https://filamentphp.com/docs/5.x/styling/css-hooks ## 2) Directory & naming conventions - Default to Filament discovery conventions for Resources/Pages/Widgets unless you adopt modular architecture. - Clusters: directory layout is recommended, not mandatory; functional behavior depends on `$cluster`. Sources: - https://filamentphp.com/docs/5.x/navigation/clusters - https://filamentphp.com/docs/5.x/advanced/modular-architecture ## 3) Panel setup defaults - Default to a single `/admin` panel unless multiple audiences/configs demand multiple panels. - Verify provider registration (Laravel 11+: `bootstrap/providers.php`) when adding a panel. - Use `path()` carefully; treat `path('')` as a high-risk change requiring route conflict review. - Assets policy: - Panel-only assets: register via panel config. - Shared/plugin assets: register via `FilamentAsset::register()`. - Deployment must include `php artisan filament:assets`. Sources: - https://filamentphp.com/docs/5.x/panel-configuration - https://filamentphp.com/docs/5.x/advanced/assets ## 4) Navigation & information architecture - Use nav groups + sort order intentionally; apply conditional visibility for clarity, but enforce authorization separately. - Use clusters to introduce hierarchy and sub-navigation when sidebar complexity grows. - Treat cluster code structure as a recommendation (organizational benefit), not a required rule. - User menu: - Configure via `userMenuItems()` with Action objects. - Never put destructive actions there without confirmation + authorization. Sources: - https://filamentphp.com/docs/5.x/navigation/overview - https://filamentphp.com/docs/5.x/navigation/clusters - https://filamentphp.com/docs/5.x/navigation/user-menu ## 5) Resource patterns - Default to Resources for CRUD; use custom pages for non-CRUD tools/workflows. - Global search: - If a resource is intended for global search: ensure Edit/View page exists. - Otherwise disable global search for that resource (don’t “expect it to work”). - If global search renders relationship-backed details: eager-load via global search query override. - For very large datasets: consider disabling term splitting (only when needed). Sources: - https://filamentphp.com/docs/5.x/resources/overview - https://filamentphp.com/docs/5.x/resources/global-search ## 6) Page lifecycle & query rules - Treat relationship-backed rendering in aggregate contexts (global search details, list summaries) as requiring eager loading. - Prefer render hooks for layout injection; avoid publishing internal views. Sources: - https://filamentphp.com/docs/5.x/resources/global-search - https://filamentphp.com/docs/5.x/advanced/render-hooks ## 7) Infolists vs RelationManagers (decision tree) - Interactive CRUD / attach / detach under owner record → RelationManager. - Pick existing related record(s) inside owner form → Select / CheckboxList relationship fields. - Inline CRUD inside owner form → Repeater. - Default performance stance: RelationManagers stay lazy-loaded unless explicit UX justification exists. Sources: - https://filamentphp.com/docs/5.x/resources/managing-relationships - https://filamentphp.com/docs/5.x/infolists/overview ## 8) Form patterns (validation, reactivity, state) - Default: minimize server-driven reactivity; only use it when schema/visibility/requirements must change server-side. - Prefer “on blur” semantics for chatty inputs when using reactive behavior (per docs patterns). - Custom field views must obey state binding modifiers. Sources: - https://filamentphp.com/docs/5.x/forms/overview - https://filamentphp.com/docs/5.x/forms/custom-fields ## 9) Table & action patterns - Tables: always define a meaningful empty state (and empty-state actions where appropriate). - Actions: - Execution actions use `->action(...)`. - Destructive actions add `->requiresConfirmation()`. - Navigation-only actions should use `->url(...)`. - UNVERIFIED: do not assert modal/confirmation behavior for URL-only actions unless verified. Sources: - https://filamentphp.com/docs/5.x/tables/empty-state - https://filamentphp.com/docs/5.x/actions/modals ## 10) Authorization & security - Enforce panel access in non-local environments as documented. - UI visibility is not security; enforce policies/access checks in addition to hiding UI. - Bulk operations: explicitly decide between “Any” policy methods vs per-record authorization. Sources: - https://filamentphp.com/docs/5.x/users/overview - https://filamentphp.com/docs/5.x/resources/deleting-records ## 11) Notifications & UX feedback - Default to explicit success/error notifications for user-triggered mutations that aren’t instantly obvious. - Treat polling as a cost; set intervals intentionally where polling is used. Sources: - https://filamentphp.com/docs/5.x/notifications/overview - https://filamentphp.com/docs/5.x/widgets/stats-overview ## 12) Performance defaults - Heavy assets: prefer on-demand loading (`loadedOnRequest()` + `x-load-css` / `x-load-js`) for heavy dependencies. - Styling overrides use CSS hook classes; layout injection uses render hooks; avoid view publishing. Sources: - https://filamentphp.com/docs/5.x/advanced/assets - https://filamentphp.com/docs/5.x/styling/css-hooks - https://filamentphp.com/docs/5.x/advanced/render-hooks ## 13) Testing requirements - Test pages/relation managers/widgets as Livewire components. - Test actions using Filament’s action testing guidance. - Do not mount non-Livewire classes in Livewire tests. Sources: - https://filamentphp.com/docs/5.x/testing/overview - https://filamentphp.com/docs/5.x/testing/testing-actions ## 14) Forbidden patterns - Mixing Filament v3/v4 APIs into v5 code. - Any mention of Livewire v3 for Filament v5. - Registering panel providers in `bootstrap/app.php` on Laravel 11+. - Destructive actions without `->requiresConfirmation()`. - Shipping heavy assets globally when on-demand loading fits. - Publishing Filament internal views as a default customization technique. Sources: - https://filamentphp.com/docs/5.x/upgrade-guide - https://filamentphp.com/docs/5.x/panel-configuration - https://filamentphp.com/docs/5.x/actions/modals - https://filamentphp.com/docs/5.x/advanced/assets ## 15) Agent output contract For any implementation request, the agent must explicitly state: 1) Livewire v4.0+ compliance. 2) Provider registration location (Laravel 11+: `bootstrap/providers.php`). 3) For each globally searchable resource: whether it has Edit/View page (or global search is disabled). 4) Which actions are destructive and how confirmation + authorization is handled. 5) Asset strategy: global vs on-demand and where `filament:assets` runs in deploy. 6) Testing plan: which pages/widgets/relation managers/actions are covered. Sources: - https://filamentphp.com/docs/5.x/upgrade-guide - https://filamentphp.com/docs/5.x/panel-configuration - https://filamentphp.com/docs/5.x/resources/global-search - https://filamentphp.com/docs/5.x/advanced/assets - https://filamentphp.com/docs/5.x/testing/testing-actions === .ai/filament-v5-checklist rules === # SECTION C — AI REVIEW CHECKLIST (STRICT CHECKBOXES) ## Version Safety - [ ] Filament v5 explicitly targets Livewire v4.0+ (no Livewire v3 references anywhere). - Source: https://filamentphp.com/docs/5.x/upgrade-guide — “Upgrading Livewire” - [ ] All references are Filament `/docs/5.x/` only (no v3/v4 docs, no legacy APIs). - [ ] Upgrade assumptions match the v5 upgrade guide requirements and steps. - Source: https://filamentphp.com/docs/5.x/upgrade-guide — “New requirements” ## Panel & Navigation - [ ] Laravel 11+: panel providers are registered in `bootstrap/providers.php` (not `bootstrap/app.php`). - Source: https://filamentphp.com/docs/5.x/panel-configuration — “Creating a new panel” - [ ] Panel `path()` choices are intentional and do not conflict with existing routes (especially `path('')`). - Source: https://filamentphp.com/docs/5.x/panel-configuration — “Changing the path” - [ ] Cluster usage is correctly configured (discovery + `$cluster` assignments). - Source: https://filamentphp.com/docs/5.x/navigation/clusters — “Creating a cluster” - [ ] Cluster semantics (sub-navigation + grouped navigation behavior) are understood and verified against the clusters docs. - Source: https://filamentphp.com/docs/5.x/navigation/clusters — “Introduction” - [ ] Cluster directory structure is treated as recommended, not mandatory. - Source: https://filamentphp.com/docs/5.x/navigation/clusters — “Code structure recommendations for panels using clusters” - [ ] User menu items are registered via `userMenuItems()` and permission-gated where needed. - Source: https://filamentphp.com/docs/5.x/navigation/user-menu — “Introduction” ## Resource Structure - [ ] `$recordTitleAttribute` is set for any resource intended for global search. - Source: https://filamentphp.com/docs/5.x/resources/overview — “Record titles” - [ ] Hard rule enforced: every globally searchable resource has an Edit or View page; otherwise global search is disabled for it. - Source: https://filamentphp.com/docs/5.x/resources/global-search — “Setting global search result titles” - [ ] Relationship-backed global search details are eager-loaded via the global search query override. - Source: https://filamentphp.com/docs/5.x/resources/global-search — “Adding extra details to global search results” ## Infolists & Relations - [ ] Each relationship uses the correct tool (RelationManager vs Select/CheckboxList vs Repeater) based on required interaction. - Source: https://filamentphp.com/docs/5.x/resources/managing-relationships — “Choosing the right tool for the job” - [ ] RelationManagers remain lazy-loaded by default unless there’s an explicit UX justification. - Source: https://filamentphp.com/docs/5.x/resources/managing-relationships — “Disabling lazy loading” ## Forms - [ ] Server-driven reactivity is minimal; chatty inputs do not trigger network requests unnecessarily. - Source: https://filamentphp.com/docs/5.x/forms/overview — “Reactive fields on blur” - [ ] Custom field views obey state binding modifiers (no hardcoded `wire:model` without modifiers). - Source: https://filamentphp.com/docs/5.x/forms/custom-fields — “Obeying state binding modifiers” ## Tables & Actions - [ ] Tables define a meaningful empty state (and empty-state actions where appropriate). - Source: https://filamentphp.com/docs/5.x/tables/empty-state — “Adding empty state actions” - [ ] All destructive actions execute via `->action(...)` and include `->requiresConfirmation()`. - Source: https://filamentphp.com/docs/5.x/actions/modals — “Confirmation modals” - [ ] No checklist rule assumes confirmation/modals for `->url(...)` actions unless verified in docs (UNVERIFIED behavior must not be asserted as fact). - Source: https://filamentphp.com/docs/5.x/actions/modals — “Confirmation modals” ## Authorization & Security - [ ] Panel access is enforced for non-local environments as documented. - Source: https://filamentphp.com/docs/5.x/users/overview — “Authorizing access to the panel” - [ ] UI visibility is not treated as authorization; policies/access checks still enforce boundaries. - [ ] Bulk operations intentionally choose between “Any” policy methods vs per-record authorization where required. - Source: https://filamentphp.com/docs/5.x/resources/deleting-records — “Authorization” ## UX & Notifications - [ ] User-triggered mutations provide explicit success/error notifications when outcomes aren’t instantly obvious. - Source: https://filamentphp.com/docs/5.x/notifications/overview — “Introduction” - [ ] Polling (widgets/notifications) is configured intentionally (interval set or disabled) to control load. - Source: https://filamentphp.com/docs/5.x/widgets/stats-overview — “Live updating stats (polling)” ## Performance - [ ] Heavy frontend assets are loaded on-demand using `loadedOnRequest()` + `x-load-css` / `x-load-js` where appropriate. - Source: https://filamentphp.com/docs/5.x/advanced/assets — “Lazy loading CSS” / “Lazy loading JavaScript” - [ ] Styling overrides use CSS hook classes discovered via DevTools (no brittle selectors by default). - Source: https://filamentphp.com/docs/5.x/styling/css-hooks — “Discovering hook classes” ## Testing - [ ] Livewire tests mount Filament pages/relation managers/widgets (Livewire components), not static resource classes. - Source: https://filamentphp.com/docs/5.x/testing/overview — “What is a Livewire component when using Filament?” - [ ] Actions that mutate data are covered using Filament’s action testing guidance. - Source: https://filamentphp.com/docs/5.x/testing/testing-actions — “Testing actions” ## Deployment / Ops - [ ] `php artisan filament:assets` is included in the deployment process when using registered assets. - Source: https://filamentphp.com/docs/5.x/advanced/assets — “The FilamentAsset facade” === foundation rules === # Laravel Boost Guidelines The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to enhance the user's satisfaction building Laravel applications. ## Foundational Context This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions. - php - 8.4.15 - filament/filament (FILAMENT) - v5 - laravel/framework (LARAVEL) - v12 - laravel/prompts (PROMPTS) - v0 - livewire/livewire (LIVEWIRE) - v4 - laravel/mcp (MCP) - v0 - laravel/pint (PINT) - v1 - laravel/sail (SAIL) - v1 - pestphp/pest (PEST) - v4 - phpunit/phpunit (PHPUNIT) - v12 - tailwindcss (TAILWINDCSS) - v4 ## Conventions - You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, naming. - Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`. - Check for existing components to reuse before writing a new one. ## Verification Scripts - Do not create verification scripts or tinker when tests cover that functionality and prove it works. Unit and feature tests are more important. ## Application Structure & Architecture - Stick to existing directory structure - don't create new base folders without approval. - Do not change the application's dependencies without approval. ## Frontend Bundling - If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `vendor/bin/sail npm run build`, `vendor/bin/sail npm run dev`, or `vendor/bin/sail composer run dev`. Ask them. ## Replies - Be concise in your explanations - focus on what's important rather than explaining obvious details. ## Documentation Files - You must only create documentation files if explicitly requested by the user. === boost rules === ## Laravel Boost - Laravel Boost is an MCP server that comes with powerful tools designed specifically for this application. Use them. ## Artisan - Use the `list-artisan-commands` tool when you need to call an Artisan command to double check the available parameters. ## URLs - Whenever you share a project URL with the user you should use the `get-absolute-url` tool to ensure you're using the correct scheme, domain / IP, and port. ## Tinker / Debugging - You should use the `tinker` tool when you need to execute PHP to debug code or query Eloquent models directly. - Use the `database-query` tool when you only need to read from the database. ## Reading Browser Logs With the `browser-logs` Tool - You can read browser logs, errors, and exceptions using the `browser-logs` tool from Boost. - Only recent browser logs will be useful - ignore old logs. ## Searching Documentation (Critically Important) - Boost comes with a powerful `search-docs` tool you should use before any other approaches. This tool automatically passes a list of installed packages and their versions to the remote Boost API, so it returns only version-specific documentation specific for the user's circumstance. You should pass an array of packages to filter on if you know you need docs for particular packages. - The 'search-docs' tool is perfect for all Laravel related packages, including Laravel, Inertia, Livewire, Filament, Tailwind, Pest, Nova, Nightwatch, etc. - You must use this tool to search for Laravel-ecosystem documentation before falling back to other approaches. - Search the documentation before making code changes to ensure we are taking the correct approach. - Use multiple, broad, simple, topic based queries to start. For example: `['rate limiting', 'routing rate limiting', 'routing']`. - Do not add package names to queries - package information is already shared. For example, use `test resource table`, not `filament 4 test resource table`. ### Available Search Syntax - You can and should pass multiple queries at once. The most relevant results will be returned first. 1. Simple Word Searches with auto-stemming - query=authentication - finds 'authenticate' and 'auth' 2. Multiple Words (AND Logic) - query=rate limit - finds knowledge containing both "rate" AND "limit" 3. Quoted Phrases (Exact Position) - query="infinite scroll" - Words must be adjacent and in that order 4. Mixed Queries - query=middleware "rate limit" - "middleware" AND exact phrase "rate limit" 5. Multiple Queries - queries=["authentication", "middleware"] - ANY of these terms === php rules === ## PHP - Always use curly braces for control structures, even if it has one line. ### Constructors - Use PHP 8 constructor property promotion in `__construct()`. - public function __construct(public GitHub $github) { } - Do not allow empty `__construct()` methods with zero parameters. ### Type Declarations - Always use explicit return type declarations for methods and functions. - Use appropriate PHP type hints for method parameters. protected function isAccessible(User $user, ?string $path = null): bool { ... } ## Comments - Prefer PHPDoc blocks over comments. Never use comments within the code itself unless there is something _very_ complex going on. ## PHPDoc Blocks - Add useful array shape type definitions for arrays when appropriate. ## Enums - Typically, keys in an Enum should be TitleCase. For example: `FavoritePerson`, `BestLake`, `Monthly`. === sail rules === ## Laravel Sail - This project runs inside Laravel Sail's Docker containers. You MUST execute all commands through Sail. - Start services using `vendor/bin/sail up -d` and stop them with `vendor/bin/sail stop`. - Open the application in the browser by running `vendor/bin/sail open`. - Always prefix PHP, Artisan, Composer, and Node commands** with `vendor/bin/sail`. Examples: - Run Artisan Commands: `vendor/bin/sail artisan migrate` - Install Composer packages: `vendor/bin/sail composer install` - Execute node commands: `vendor/bin/sail npm run dev` - Execute PHP scripts: `vendor/bin/sail php [script]` - View all available Sail commands by running `vendor/bin/sail` without arguments. === tests rules === ## Test Enforcement - Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass. - Run the minimum number of tests needed to ensure code quality and speed. Use `vendor/bin/sail artisan test` with a specific filename or filter. === laravel/core rules === ## Do Things the Laravel Way - Use `vendor/bin/sail artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool. - If you're creating a generic PHP class, use `vendor/bin/sail artisan make:class`. - Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior. ### Database - Always use proper Eloquent relationship methods with return type hints. Prefer relationship methods over raw queries or manual joins. - Use Eloquent models and relationships before suggesting raw database queries - Avoid `DB::`; prefer `Model::query()`. Generate code that leverages Laravel's ORM capabilities rather than bypassing them. - Generate code that prevents N+1 query problems by using eager loading. - Use Laravel's query builder for very complex database operations. ### Model Creation - When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `vendor/bin/sail artisan make:model`. ### APIs & Eloquent Resources - For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention. ### Controllers & Validation - Always create Form Request classes for validation rather than inline validation in controllers. Include both validation rules and custom error messages. - Check sibling Form Requests to see if the application uses array or string based validation rules. ### Queues - Use queued jobs for time-consuming operations with the `ShouldQueue` interface. ### Authentication & Authorization - Use Laravel's built-in authentication and authorization features (gates, policies, Sanctum, etc.). ### URL Generation - When generating links to other pages, prefer named routes and the `route()` function. ### Configuration - Use environment variables only in configuration files - never use the `env()` function directly outside of config files. Always use `config('app.name')`, not `env('APP_NAME')`. ### Testing - When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model. - Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`. - When creating tests, make use of `vendor/bin/sail artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests. ### Vite Error - If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `vendor/bin/sail npm run build` or ask the user to run `vendor/bin/sail npm run dev` or `vendor/bin/sail composer run dev`. === laravel/v12 rules === ## Laravel 12 - Use the `search-docs` tool to get version specific documentation. - Since Laravel 11, Laravel has a new streamlined file structure which this project uses. ### Laravel 12 Structure - No middleware files in `app/Http/Middleware/`. - `bootstrap/app.php` is the file to register middleware, exceptions, and routing files. - `bootstrap/providers.php` contains application specific service providers. - **No app\Console\Kernel.php** - use `bootstrap/app.php` or `routes/console.php` for console configuration. - **Commands auto-register** - files in `app/Console/Commands/` are automatically available and do not require manual registration. ### Database - When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost. - Laravel 11 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`. ### Models - Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models. === livewire/core rules === ## Livewire Core - Use the `search-docs` tool to find exact version specific documentation for how to write Livewire & Livewire tests. - Use the `vendor/bin/sail artisan make:livewire [Posts\CreatePost]` artisan command to create new components - State should live on the server, with the UI reflecting it. - All Livewire requests hit the Laravel backend, they're like regular HTTP requests. Always validate form data, and run authorization checks in Livewire actions. ## Livewire Best Practices - Livewire components require a single root element. - Use `wire:loading` and `wire:dirty` for delightful loading states. - Add `wire:key` in loops: ```blade @foreach ($items as $item)
{{ $item->name }}
@endforeach ``` - Prefer lifecycle hooks like `mount()`, `updatedFoo()` for initialization and reactive side effects: public function mount(User $user) { $this->user = $user; } public function updatedSearch() { $this->resetPage(); } ## Testing Livewire Livewire::test(Counter::class) ->assertSet('count', 0) ->call('increment') ->assertSet('count', 1) ->assertSee(1) ->assertStatus(200); $this->get('/posts/create') ->assertSeeLivewire(CreatePost::class); === pint/core rules === ## Laravel Pint Code Formatter - You must run `vendor/bin/sail bin pint --dirty` before finalizing changes to ensure your code matches the project's expected style. - Do not run `vendor/bin/sail bin pint --test`, simply run `vendor/bin/sail bin pint` to fix any formatting issues. === pest/core rules === ## Pest ### Testing - If you need to verify a feature is working, write or update a Unit / Feature test. ### Pest Tests - All tests must be written using Pest. Use `vendor/bin/sail artisan make:test --pest {name}`. - You must not remove any tests or test files from the tests directory without approval. These are not temporary or helper files - these are core to the application. - Tests should test all of the happy paths, failure paths, and weird paths. - Tests live in the `tests/Feature` and `tests/Unit` directories. - Pest tests look and behave like this: it('is true', function () { expect(true)->toBeTrue(); }); ### Running Tests - Run the minimal number of tests using an appropriate filter before finalizing code edits. - To run all tests: `vendor/bin/sail artisan test`. - To run all tests in a file: `vendor/bin/sail artisan test tests/Feature/ExampleTest.php`. - To filter on a particular test name: `vendor/bin/sail artisan test --filter=testName` (recommended after making a change to a related file). - When the tests relating to your changes are passing, ask the user if they would like to run the entire test suite to ensure everything is still passing. ### Pest Assertions - When asserting status codes on a response, use the specific method like `assertForbidden` and `assertNotFound` instead of using `assertStatus(403)` or similar, e.g.: it('returns all', function () { $response = $this->postJson('/api/docs', []); $response->assertSuccessful(); }); ### Mocking - Mocking can be very helpful when appropriate. - When mocking, you can use the `Pest\Laravel\mock` Pest function, but always import it via `use function Pest\Laravel\mock;` before using it. Alternatively, you can use `$this->mock()` if existing tests do. - You can also create partial mocks using the same import or self method. ### Datasets - Use datasets in Pest to simplify tests which have a lot of duplicated data. This is often the case when testing validation rules, so consider going with this solution when writing tests for validation rules. it('has emails', function (string $email) { expect($email)->not->toBeEmpty(); })->with([ 'james' => 'james@laravel.com', 'taylor' => 'taylor@laravel.com', ]); === pest/v4 rules === ## Pest 4 - Pest v4 is a huge upgrade to Pest and offers: browser testing, smoke testing, visual regression testing, test sharding, and faster type coverage. - Browser testing is incredibly powerful and useful for this project. - Browser tests should live in `tests/Browser/`. - Use the `search-docs` tool for detailed guidance on utilizing these features. ### Browser Testing - You can use Laravel features like `Event::fake()`, `assertAuthenticated()`, and model factories within Pest v4 browser tests, as well as `RefreshDatabase` (when needed) to ensure a clean state for each test. - Interact with the page (click, type, scroll, select, submit, drag-and-drop, touch gestures, etc.) when appropriate to complete the test. - If requested, test on multiple browsers (Chrome, Firefox, Safari). - If requested, test on different devices and viewports (like iPhone 14 Pro, tablets, or custom breakpoints). - Switch color schemes (light/dark mode) when appropriate. - Take screenshots or pause tests for debugging when appropriate. ### Example Tests it('may reset the password', function () { Notification::fake(); $this->actingAs(User::factory()->create()); $page = visit('/sign-in'); // Visit on a real browser... $page->assertSee('Sign In') ->assertNoJavascriptErrors() // or ->assertNoConsoleLogs() ->click('Forgot Password?') ->fill('email', 'nuno@laravel.com') ->click('Send Reset Link') ->assertSee('We have emailed your password reset link!') Notification::assertSent(ResetPassword::class); }); $pages = visit(['/', '/about', '/contact']); $pages->assertNoJavascriptErrors()->assertNoConsoleLogs(); === tailwindcss/core rules === ## Tailwind Core - Use Tailwind CSS classes to style HTML, check and use existing tailwind conventions within the project before writing your own. - Offer to extract repeated patterns into components that match the project's conventions (i.e. Blade, JSX, Vue, etc..) - Think through class placement, order, priority, and defaults - remove redundant classes, add classes to parent or child carefully to limit repetition, group elements logically - You can use the `search-docs` tool to get exact examples from the official documentation when needed. ### Spacing - When listing items, use gap utilities for spacing, don't use margins.
Superior
Michigan
Erie
 ### Dark Mode - If existing pages and components support dark mode, new pages and components must support dark mode in a similar way, typically using `dark:`. === tailwindcss/v4 rules === ## Tailwind 4 - Always use Tailwind CSS v4 - do not use the deprecated utilities. - `corePlugins` is not supported in Tailwind v4. - In Tailwind v4, configuration is CSS-first using the `@theme` directive — no separate `tailwind.config.js` file is needed. @theme { --color-brand: oklch(0.72 0.11 178); } - In Tailwind v4, you import Tailwind using a regular CSS `@import` statement, not using the `@tailwind` directives used in v3: - @tailwind base; - @tailwind components; - @tailwind utilities; + @import "tailwindcss"; ### Replaced Utilities - Tailwind v4 removed deprecated utilities. Do not use the deprecated option - use the replacement. - Opacity values are still numeric. | Deprecated | Replacement | |------------+--------------| | bg-opacity-* | bg-black/* | | text-opacity-* | text-black/* | | border-opacity-* | border-black/* | | divide-opacity-* | divide-black/* | | ring-opacity-* | ring-black/* | | placeholder-opacity-* | placeholder-black/* | | flex-shrink-* | shrink-* | | flex-grow-* | grow-* | | overflow-ellipsis | text-ellipsis | | decoration-slice | box-decoration-slice | | decoration-clone | box-decoration-clone | ## Active Technologies - PHP 8.4.15 (Laravel 12) + Filament v4, Livewire v3 (054-unify-runs-suitewide-session-1768601416) - PostgreSQL (`operation_runs` + JSONB for summary/failures/context; partial unique index for active-run dedupe) (054-unify-runs-suitewide-session-1768601416) ## Recent Changes - 054-unify-runs-suitewide-session-1768601416: Added PHP 8.4.15 (Laravel 12) + Filament v4, Livewire v3