Nova Aegis Ip Blocker Laravel Package

Agents

Guidance for coding agents working in this repository.

claude-code

cursor

aegis-security

Security checklist for the Aegis IP Blocker. Use for any change to what an outside value can do or who may reach something: the BlockListedIps middleware or its place in the middleware groups, how the visitor's address is read (Request::ip(), trusted proxies), the address normalization and matching (IpAddress, BlockList), a setting and its validation rules, the lock-out rule, the 403 page or a view, the settings memo and its invalidation, a console command, 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-development

Use whenever you change how the IP Blocker meets Nova and Laravel's HTTP layer: the section the Aegis page draws from IpBlockerModule::fields(), the dashboard status, the BlockListedIps middleware and the groups it joins, the 403 view, the service provider's wiring, or anything Nova-version specific. Use it with aegis-security for anything about access.

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 IP Blocker is tested. Use when writing or changing anything in tests/ (Pest files, tests/TestCase.php, tests/Pest.php, tests/Fixtures), 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 a visitor address, a proxy, Nova, the console or a view, 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 the IP Blocker. Use before changing a stored setting (its key, type or meaning), a default value, the section key, what is memoized, a public name (middleware alias, command, view, publish tag, lang keys), the Aegis core API the module uses, composer.json constraints, 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