tyro-dashboard - SKILL.md Agent Skill

name: tyro-dashboard description: "Use for Tyro Dashboard framework or app integration work: admin pages, routes, sidebar/menu changes, settings, CRUD resources, Blade overrides, RBAC, media, plugins, service providers, public APIs, and upgrade-safe framework maintenance for hasinhayder/tyro-dashboard, hasinhayder/tyro, tyro-login, or Laravel apps consuming Tyro Dashboard." version: 2.1.1 target: "hasinhayder/tyro-dashboard ^1.34" peers: "Filament, Nova, Orchid, Backpack"

Tyro Dashboard Agent Guide

Tyro Dashboard is an admin panel framework. Treat package code like framework surface area and app-level published overrides like consumer customization. Your job is to preserve one clear pattern, stable extension contracts, and upgrade safety while still shipping the user's requested change.

First Decision

Before editing, classify the work:

App integration: routes, controllers, views, config overrides, published resources/views/vendor/tyro-dashboard/*, project-specific dashboard pages. Prefer local app code and existing project patterns.
Framework internals: package source, service providers, config defaults, route names, Blade sections, public/protected methods, traits, commands, migrations, publishable assets. Apply strict compatibility rules.
Plugin/ecosystem work: anything a third-party package might call, override, publish, or extend. Preserve extension points and document migration paths.

If unsure, inspect the local code first. Do not assume package internals need changing when a published view, config override, menu hook, route, middleware, or event listener can solve it.

Core Rules

One intended pattern: follow the pattern already used nearest to the change.
Extension over modification: in consuming apps, avoid editing vendor/package internals; use published views, config, routes, middleware, events, and menu injection.
Public surface is sticky: route names, config keys, Blade sections, view composer variables, public/protected method signatures, publish tags, commands, and env keys require backward compatibility.
Security is default: admin features need auth plus Tyro admin middleware or the established Tyro authorization layer. Never expose secrets, tokens, private keys, or raw .env values in diagnostic UI.
Small blast radius: keep changes scoped to the subsystem and avoid opportunistic framework redesign.

Agent Loop

Use this loop for coding tasks:

Inspect: read nearby routes, controllers, views, config, and tests before choosing a pattern.
Classify: decide app integration, framework internals, or plugin/ecosystem work.
Load rules: read only the relevant rule files.
Implement narrowly: use the nearest established convention and avoid unrelated refactors.
Verify: run the smallest meaningful syntax, route, Blade, or test checks.
Report: name changed files, verification, and any residual risk.

Fast File Maps

Use rg first. Typical app-level locations:

Admin routes: routes/web.php
App controllers: app/Http/Controllers
Published admin layout: resources/views/vendor/tyro-dashboard/layouts/admin.blade.php
Published admin sidebar: resources/views/vendor/tyro-dashboard/partials/admin-sidebar.blade.php
App dashboard views: resources/views/dashboard
Tyro config override: config/tyro-dashboard.php

Typical package/framework locations:

Service providers: src/*ServiceProvider.php
Routes: routes/*.php
Config defaults: config/*.php
Framework views: resources/views
Support APIs: src/Support
Traits/concerns: src/Concerns, src/Traits
Controllers/resources: src/Http, src/Resources

Common publish tags:

tyro-dashboard-sidebar: publishes partials/admin-sidebar.blade.php and partials/user-sidebar.blade.php only.
tyro-dashboard-essentials: publishes dashboard shell partials (admin-bar, sidebars, topbar) plus resources/views/dashboard.

Recipes

Add an app-level admin page

Inspect nearby dashboard routes/controllers/views.
Add an app controller unless a closure/view route is already the local convention.
Use admin middleware, usually ['auth', 'tyro-dashboard.admin'], or the existing dashboard group.
Name routes consistently, e.g. dashboard.system.environment.
Extend tyro-dashboard::layouts.admin.
Add sidebar/menu entry only through a published sidebar override or menu extension point.
Verify with php -l, php artisan route:list --name=..., and php artisan view:cache.

Add or change a sidebar item

Prefer configured/menu-injected items if the project uses them.
If the app has a published sidebar override, edit that override, not vendor package files.
Use request()->routeIs(...) or the local $dashboardRoute::pattern(...) pattern consistently.
Keep labels short and icons consistent with surrounding links.
Do not make the sidebar query-heavy; guard expensive checks behind config/schema checks.

Add a settings page

Read the existing settings controller/view pattern first.
Validate inputs server-side.
For .env writes, whitelist keys and treat secrets carefully.
Do not display secret values unless masked.
Provide config-cache guidance or a clear-cache action if changed settings require it.
Read rules/settings-system.md and rules/configuration.md for framework-level settings.

Add a CRUD resource

Check whether the local project uses Tyro resource config, custom controllers, or both.
Follow the nearest CRUD pattern for route names, redirects, validation, and Blade structure.
Protect admin routes with Tyro authorization.
Keep relationship loading explicit to avoid N+1 regressions.
Read rules/crud-resources.md, rules/controllers.md, and rules/authorization.md for framework resources.

Override or create Blade UI

Extend the established Tyro layout.
Use existing CSS variables and component classes before adding new styles.
Keep view section names stable.
Avoid card-in-card layouts; use cards for actual panels/items.
Check mobile wrapping for long labels, paths, and generated values.
Read rules/user-experience.md, rules/views-and-blade.md, and rules/dashboard-ui.md for framework UI.

Change framework package behavior

Identify public API impact before editing.
Read the relevant rule files listed below.
Preserve existing routes/config/view names unless adding a deprecation path.
Prefer optional config flags and additive APIs.
Add or update tests for the contract.
Document migration notes for any behavior change.

Rule Index

Load only the rule files needed for the task.

Ecosystem Integrity

rules/public-api-surface.md: public/protected signatures, config keys, route names, Blade directives, view data
rules/plugin-safety.md: extension point stability, view override precedence, middleware stacking
rules/upgrade-path.md: deprecations, migrations, update commands
rules/coupling-boundaries.md: dependencies, internals access, Laravel version assumptions

Security and Authorization

rules/authorization.md: RBAC pipeline, HasTyroRoles, caching, enforcement hierarchy
rules/security.md: impersonation, sessions, brute force, 2FA reset, audit integrity

Extension and Configuration

rules/app-integration.md: consuming-app routes, controllers, published views, sidebar overrides, diagnostics
rules/extensibility.md: publishing, config overrides, menu injection, page scaffolding
rules/configuration.md: config structure, env variables, system settings, feature flags
rules/service-provider.md: boot order, view namespace, middleware aliases

Core Subsystems

rules/crud-resources.md: resources, fields, relationships
rules/media-management.md: uploads, processing, stock photos, media picker
rules/controllers.md: base controllers, actions, audit safety, redirects
rules/user-experience.md: admin UX hierarchy, states, forms, tables, responsive behavior, accessibility
rules/dashboard-ui.md: CSS variables, theming, sidebar, admin bar, notifications
rules/views-and-blade.md: layouts, sections, partials, components
rules/middleware.md: admin/auth middleware, impersonation, order
rules/routes.md: prefix/name prefix, feature gates, route model binding
rules/settings-system.md: env editor, settings tabs, validation, persistence
rules/artisan-commands.md: command naming, installer/update safety

Maintainability

rules/models-and-database.md: models, migrations, pivots, accessors
rules/traits-and-concerns.md: reusable behavior and schema checks
rules/events-and-listeners.md: audit/login/logout and feature gating
rules/error-handling.md: audit-safe behavior and graceful degradation
rules/support-classes.md: DashboardRoute, colors, notices
rules/agent-testing.md: safe verification commands, non-destructive testing boundaries, database protection
rules/testing.md: integration tests and security scenarios
rules/naming-conventions.md: PHP, config, routes, CSS, JS, env/session names

Anti-Patterns

Avoid these unless the user explicitly asks and you explain the tradeoff:

Editing files in vendor/.
Modifying framework internals when an app-level route/controller/view/config override works.
Adding admin pages without Tyro admin authorization.
Changing route names, config keys, Blade section names, or public method signatures casually.
Introducing a second pattern for menus, settings, CRUD, or route naming.
Reading or displaying secrets from .env, storage keys, OAuth tokens, API keys, or private keys.
Running expensive system checks on every sidebar render.
Replacing established Tyro UI/layout conventions with one-off design systems.
Adding dependencies to the framework package for convenience without evaluating downstream impact.

Validation Checklist

Choose checks proportional to the change:

New/changed PHP file: php -l path/to/file.php
New route: php artisan route:list --name=<route-fragment>
Blade changes: php artisan view:cache
Config changes: php artisan config:clear or targeted config assertion when safe
Tests exist and risk is meaningful: run the focused Pest/PHPUnit test
Package API behavior changed: add/update tests and read rules/public-api-surface.md
Security/auth changed: read rules/security.md and rules/authorization.md
Before running migrations, seeders, queue workers, destructive Artisan commands, or broad tests, read rules/agent-testing.md

Review Stance

For reviews, lead with risks:

Security/authorization leaks
Breaking public API or plugin contracts
Upgrade path regressions
Route/config/view naming drift
Missing tests for changed behavior
Performance issues in shared UI, middleware, or service providers

If no issues are found, say so clearly and mention any residual test gap.