core-standards

Project Context

• The project tech stack is defined in composer.json.
• Use the PHP version and major package versions defined in composer.json as the source of truth.
• Prefer existing project conventions over introducing new patterns.

AI Behavior

• Do not apologize.
• Do not invent changes, files, implementations, or results.
• Preserve existing code and do not remove unrelated logic.
• Verify visible context before proposing changes.
• Do not speculate when the answer can be derived from the repository context.
• Do not ask the user to verify something that is already visible in the provided code or files.
• Do not suggest file changes when no actual modification is needed.
• Fix obvious grammatical issues in user-facing text you modify.
• Default to autonomous execution: proceed without asking when the answer can be inferred from the issue, the codebase, the project configuration, or prior conversation context.
• Only ask the user when the next step is genuinely ambiguous and the ambiguity cannot be resolved from the available context. State the specific ambiguity that blocks the work.
• Never ask the user to confirm a fact the agent can verify itself (tests passing, fixers clean, branch up-to-date, file exists, etc.) — verify it directly instead.
• Never gate on user approval for work the assignment already authorizes (creating commits, opening PRs, applying review fixes mandated by the calling skill).
• When user input is genuinely required, batch all questions into a single round; do not serialize one question at a time.

Naming

• Use clear, descriptive names that reveal purpose.
• Prefer descriptive method and variable names over comments.
• Classes: PascalCase.
• Methods and variables: camelCase.
• Routes: kebab-case URLs and dot notation route names.
• Config keys: snake_case.
• Controllers: plural noun + Controller.
• Jobs: action-oriented names.
• Events: past-tense or domain-event names.
• Enums: descriptive case names.

Structure

• Keep one clear responsibility per class and per method.
• Avoid god classes and mixed responsibilities.
• Prefer composition over inheritance unless inheritance is clearly justified.
• Expose clear interfaces and keep implementation details internal.
• Extract deeply nested conditionals into well-named methods where it improves readability.
• Prefer small, simple classes or functions unless state is genuinely needed.
• Prefer typed DTOs over raw arrays across important boundaries.
• When a method, function, closure, constructor, __invoke(), or other callable requires more than 4 parameters, introduce a dedicated typed DTO (preferably final readonly with promoted constructor properties) and pass it as a single argument instead of a long parameter list. Promoted constructor properties count as parameters; a variadic (...$args) counts as one. The only exempt cases are entry-point signatures fixed by an external framework / vendor contract that the project cannot change — controller actions whose argument list is resolved by the service container, magic methods bound by the framework, event listeners whose signature is dictated by the dispatched event, and methods overriding a parent / interface owned by vendor/. The exemption must be cited explicitly wherever the rule is enforced (CR finding, refactoring proposal) with the parent class / interface and a one-line reason.
• When a public method returns a structured set of values — an associative array representing a record, a multi-key payload, or an array shape with named string keys — return a typed DTO (preferably final readonly with promoted constructor properties) instead of the raw array. A DTO names and types each field, turning an opaque array return type into a self-documenting contract the caller can rely on. This does not apply to: a single scalar / bool / string / int / enum / void return; a homogeneous list or collection of one type (list<int> of IDs, array<int, OrderData>, Collection<int, UserModel>); or a return whose array shape is fixed by an external framework / vendor contract the project cannot change — toArray(), jsonSerialize(), Arrayable::toArray(), Eloquent casts() / $attributes, FormRequest rules(), a config callback the framework invokes, or a method overriding a parent / interface owned by vendor/. The exemption must be cited explicitly wherever the rule is enforced (CR finding, refactoring proposal) with the contract and a one-line reason.
• Use readonly for immutable data where practical.
• Use PHP attributes when they provide a cleaner and more idiomatic solution than manual wiring.