Code standards

Code Standards

Every rule here is checkable by reading the code — no vibes. Generators comply; reviewers cite CS-n. A rule that can't be verified by inspection doesn't belong in this file.

Naming

• CS-1 Class names carry their type suffix: Controller, Job, Service, Event, Listener, Factory.
• CS-2 Queued classes carry the Job suffix; trigger-listeners are named {Verb}On{Event}Listener.
• CS-3 Service primary methods are intent-named (check, create, process, store) — handle() is reserved for framework contracts.
• CS-4 Enum cases are ALL_CAPS_SNAKE_CASE.
• CS-5 A name states what comes out, not how it works (priorComposites, not loopAndFilterList).

Structure

• CS-6 Guard clauses and early returns over nested conditionals; no else after a return.
• CS-7 A self-contained block of 4+ lines (input → transform → one output) becomes an intent-named private method.
• CS-8 Never extract: guard clauses, single statements, or blocks mutating 2+ enclosing-scope locals — over-extraction reads worse than inline code.
• CS-9 One responsibility per class; a method reads top-to-bottom at one level of abstraction.
• CS-10 Paired classes (sibling drivers, mirrored paths) stay symmetric: same shape, same extractions.

Comments

• CS-11 No inline what-comments — the code self-explains through names; a comment restating the next line is deleted.
• CS-12 A genuine why (race condition, idempotency gate, security rationale, external quirk) lives in the method PHPDoc, never inline.
• CS-13 Commented-out code never ships.

Simplicity

• CS-14 No interface with a single implementation — unless a swap requirement exists today, in which case use the driver pattern.
• CS-15 No config entry for a value that never changes; constants live where they're used.
• CS-16 Framework feature over hand-rolled equivalent: if Laravel ships it (validation, throttling, casting, scheduling), use it.
• CS-17 Fewest files that work — no scaffolding, folders, or base classes "for later".

Framework Idiom

• CS-18 Validation lives in FormRequests, never inline in controllers.
• CS-19 Authorization lives in Policies/Gates, never inline role checks scattered in controllers or views.
• CS-20 Relationships via Eloquent (hasMany, belongsTo), not manual joins; no raw SQL with user input.
• CS-21 Slow or external work (mail, HTTP, image processing) is queued, never inline in a request.

Data Safety

• CS-22 Every trust boundary (user input, webhook payload, CSV cell, query param) validates before use; mass assignment stays guarded.
• CS-23 Multi-write operations wrap in one transaction; partial writes are a bug.
• CS-24 Any new query path eager-loads its relations — an N+1 is a defect, not a style issue.

Errors & Tests

• CS-25 No swallowed exceptions, no empty catch — fail loud or handle for real.
• CS-26 Every behavior change ships with a test named by the behavior it proves.
• CS-27 A bug fix starts with a red regression test (see red-first skill); no fix commits without one.

Placement

• CS-28 Class placement follows the vsa skill's rules — slice-first, events as seams; not restated here.

Formatting

• CS-29 PSR-12 compliance, enforced by Pint (vendor/bin/pint) — formatting is the tool's job; never hand-format against it, never argue style Pint already settles.
• CS-30 Static analysis must pass: PHPStan — Larastan in Laravel projects (vendor/bin/phpstan analyse). New code introduces zero new errors at the project's configured level; never fix an error by adding a baseline entry or @phpstan-ignore without a PHPDoc why.

Consumers

• Generation agents (task-backend, task-frontend, tuhin twin) read this file before writing code.
• The review skill cites CS-n in findings; readability-sweep enforces CS-1..13 mechanically.
• If this file conflicts with a target project's docs/conventions.md, the project wins — flag the delta instead of silently following either.