Nova Aegis Laravel Package

Agents

Guidance for AI coding agents (Claude Code, Codex, Junie, Cursor) working in this repository.

claude-code

cursor

aegis-security

Security checklist for the Aegis suite. Use for any change to what an outside value can do or who may reach something: an API route or controller in src/Http, the Authorize middleware or the viewAegis gate, a Vue component that prints a value, a setting and its validation rules, a probe or the Scanner (network connections), the hardening applied at boot (session, password policy, HTTPS, HSTS), the composer audit process, a console command, caching of settings, or a security review of this package.

claude-code

application-layer

Where business logic lives and how entry points hand work to it. Use when adding or changing a use case (create, publish, suspend, import, send…), when a controller, console command, job, Nova action, Livewire/Inertia handler or listener grows beyond input → call → response, when two entry points need the same behaviour, when writing a service/action class or its input DTO, when a FormRequest should produce data for a service, when deciding where a DB transaction belongs, or when a method takes Request, an array of input or a boolean flag that switches behaviour.

claude-code

dependency-injection

How classes get their collaborators and configuration. Use when writing a constructor, adding a dependency to an application/domain class, calling a facade or helper (DB::, Cache::, Http::, Mail::, Event::, now(), config(), auth(), app()) outside a controller, introducing or naming an interface, binding something in a service provider (bind, singleton, when()->needs()->give(), contextual attributes), reaching for inheritance, a Base* class or a trait to share behaviour, writing a static method, or when a class becomes hard to unit test or its constructor grows past four or five parameters.

claude-code

domain-layer-cqrs

When and how to give business rules their own layer, and how to separate reads from writes. Use when business rules start repeating across services, when an entity needs invariants (an aggregate with children that must stay consistent), when considering entities with behaviour, value objects, domain events recorded by entities, UUID identities, Doctrine/data mapper, read models, query classes, reporting queries, caching of reads, read replicas, or event sourcing — and before introducing any of these, to check that the project needs them.

claude-code

error-handling

How failures travel from the code that detects them to the user, the log and the caller. Use when a method could fail (not found, not allowed in this state, limit reached, external service down), when tempted to return false/null/-1 or a status array for failure, when creating an exception class, writing try/catch, mapping exceptions to HTTP status codes, Nova action responses or console exit codes, editing the exception handling in bootstrap/app.php, deciding what is logged or shown to the user, or reviewing code that swallows exceptions.

claude-code

events

Side effects and reactions to what the application did. Use when a use case must also send mail, notify, clear or warm a cache, regenerate a sitemap, sync a search index, call an external API or start a follow-up job; when creating an event, listener, subscriber or queued job; when touching model observers, $dispatchesEvents or the booted() hooks; when something is dispatched inside DB::transaction; when choosing between a direct call, a job and an event; or when a listener receives an Eloquent model in its payload.

claude-code

laravel-best-practices

Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns.

claude-code

nova-component-testing

Use whenever you write, run or change the Vitest specs of the Aegis page and card: resources/js/**/*.spec.js, resources/js/testing.js, vitest.config.js, or when a Vue component in resources/js needs tests or coverage. Captures the Vitest + happy-dom + @vue/test-utils setup, how the Nova global is faked, the stubs for Nova's components and the 90/85 coverage gate.

claude-code

nova-development

Use whenever you create or edit the Nova side of Aegis: src/Nova (AegisTool, AegisCard), routes/api.php and routes/inertia.php, src/Http (controllers, Authorize, TransportSecurity), the Inertia page and components in resources/js, resources/css/tool.css, vite.config.js, dist/, the menu entry, the viewAegis gate, or the way the service provider wires Nova. Use it with aegis-security for anything about access, and nova-component-testing for the specs.

claude-code

package-boundaries

Extra rules for reusable Laravel/Nova packages (Composer libraries other applications install), on top of the architecture skills. Use when changing a package's public classes, contracts, events, config keys, routes, migrations, service provider bindings or extension points, when a package needs something from the host application (user model, gate, cache store, queue), or when deciding what is public API versus internal.

claude-code

package-testing

How the PHP side of Aegis is tested. Use when writing or changing anything in tests/ (Pest files, tests/TestCase.php, tests/Pest.php, tests/Fixtures, tests/Support), phpunit.xml.dist or stubs/nova (the Nova test double), when code or a test uses a Nova class or method not used before, when a test needs Nova, a user, the network or the console, when a test fails only in the suite, or when PHPStan complains about a test.

claude-code

package-upgrades

How a change reaches the Laravel applications that already run Aegis. Use before changing a migration, a stored setting (its key, type or meaning), a default value, a cache key or what is cached, the module contract (Aegis, Contracts, CheckResult, Field, SettingsSaved, section keys, routes, the gate), composer.json constraints, dist/, or when preparing a release or a tag.

claude-code

testing-architecture

What kind of test to write for which code, and what to fake. Use when deciding between a unit test and a feature test, writing tests for a use case, an entity, a value object, a pure function, a listener or a job, when reaching for Mockery/createMock or facade fakes (Event::fake, Mail::fake, Http::fake, Queue::fake), when a test asserts the database directly, when a class is hard to test, or when a test breaks after a refactoring that did not change behaviour. Pest/PHPUnit syntax and naming live in the testing-best-practices / pest-testing skills.

claude-code

testing-best-practices

Laravel test design and review. Use when selecting coverage, naming or structuring tests, choosing assertions or test data, isolating dependencies, testing HTTP or security boundaries, improving suite performance, or reviewing test value. Use framework guidance or search-docs for Pest and PHPUnit syntax.

claude-code

validation

Which check goes where. Use when writing FormRequest rules or a Validator call, adding a rule that queries the database (exists, unique, Rule::exists/unique), checking a state or limit before an action (category archived, campaign already sent, max 10 items, email taken), validating input of a console command, job payload, Nova action or API, designing a DTO or a value object (Email, Money, Locale, Url, DateRange), or deciding whether a service should trust the data it receives.

claude-code