README

Engineering conventions for Laravel projects, designed to enforce a professional architecture, faster refactors, and AI-assisted development that stays on-rails.

What This Enables

Consistent structure across teams and projects
Refactors that are predictable, safe, and fast
Clean separation of concerns (Actions, Requests, Resources)
Strong testing posture with clear boundaries
AI outputs aligned with your standards, not random guesses

Refactor Impact (Example)

Before: mixed responsibilities in controllers, implicit rules, inconsistent naming.
After: Actions own business logic, Requests handle validation, Resources define API shape, and naming stays in English across the stack.

Installation

composer require hisoft/laravel-conventions --dev

Usage

This package supports two types of Laravel projects:

API Projects

For backend/REST API projects:

php artisan vendor:publish --tag=hisoft-api

Publishes:

Shared conventions (architecture, exceptions, testing, PHPDocs, static analysis)
API-specific conventions (CRUD, Resources)

Inertia Projects

For modern monolith projects with Vue/React:

php artisan vendor:publish --tag=hisoft-inertia

Publishes:

Shared conventions (architecture, exceptions, testing, PHPDocs, static analysis)
Inertia-specific conventions (Pages, Forms, Props, Components)

Published Structure

AGENTS.md          # Global agent rules (published to project root)
.ai/
  upstream/          # Package conventions (do not edit)
    conventions.md
    exceptions.md
    testing.md
    phpdocs.md
    static-analysis.md
    # API: crud.md, resources.md
    # Inertia: pages.md, forms.md, props.md, components.md
  local/             # Project-specific overrides (editable)
    overrides.md

AI Tools Integration

Cursor IDE

Install Cursor rules so the editor loads Hisoft conventions when editing matching files.

API project (conventions only):

php artisan hisoft:cursor --api

Inertia project (conventions only):

php artisan hisoft:cursor --inertia

Conventions + RPI workflow (recommended for complex work in Cursor):

php artisan hisoft:cursor --api --rpi
# or
php artisan hisoft:cursor --inertia --rpi

RPI only (e.g. you already manage conventions elsewhere):

php artisan hisoft:cursor --rpi

This creates:

.cursor/rules/hisoft.mdc — points the AI to .ai/upstream/* and .ai/local/overrides.md (when --api or --inertia is used)
.cursor/rules/rpi.mdc — lightweight always-on overview of the RPI process (when --rpi is used)
.cursor/skills/<phase>/SKILL.md — native Cursor skills for each RPI phase (brainstorm, research, plan, iterate, implement, investigate), with templates under brainstorm/, research/, and plan/ subfolders

How to use RPI in Cursor

After install, rpi.mdc is always applied so the model knows the workflow exists.
In Chat, run a slash command like /brainstorm, /research, /plan, /iterate, /implement, or /investigate (same idea as Claude Code). You can also attach a skill as context with @brainstorm, etc.
Describe your goal or paste paths to artifacts under docs/rpi/.
Artifacts are written under docs/rpi/{brainstorm,research,plan,investigate}/.

Full detail: resources/cursor/README.md.

Globs

API: rules apply when editing PHP (**/*.php)
Inertia: PHP and frontend (**/*.{php,vue,ts,tsx,js,jsx})

hisoft:cursor options

Option	Purpose
`--api`	Install API `hisoft.mdc`
`--inertia`	Install Inertia `hisoft.mdc`
`--rpi`	Install RPI overview rule + `.cursor/skills/` (native skills)
`--force`	Overwrite without confirmation

With no options, the command interactively asks for project type and whether to install RPI. In non-interactive mode you must pass at least one of --api, --inertia, or --rpi.

The same RPI methodology is also authored for Claude Code under resources/claude/ (agents + skills); Cursor uses native skills plus rpi.mdc under resources/cursor/ (see resources/cursor/README.md).

GitHub Copilot

Install Copilot instructions to guide AI-assisted development:

For API projects:

php artisan hisoft:copilot --api

For Inertia projects:

php artisan hisoft:copilot --inertia

This creates .github/copilot-instructions.md which GitHub Copilot automatically reads to understand project conventions.

Copilot options

--api — Install for API projects (PHP only)
--inertia — Install for Inertia projects (PHP + Vue/React)
--force — Overwrite existing file without confirmation

If no option is provided, the command prompts for project type.

Global Agent Rules

The publish tags also install AGENTS.md in the project root, providing global rules that work across all AI tools.

Other Tools

The conventions in .ai/ are compatible with any AI-assisted development tool. Reference the files in your tool's context as needed.

Updating to a Newer Package Version

When a new release of hisoft/laravel-conventions is published:

Update Composer

composer update hisoft/laravel-conventions

Republish convention files from the package
```
php artisan vendor:publish --tag=hisoft-api --force
# or
php artisan vendor:publish --tag=hisoft-inertia --force
```
--force overwrites every path in that tag, including .ai/upstream/* and .ai/local/overrides.md. Back up .ai/local/overrides.md first if you customized it, then restore or merge after publishing.
Without --force, Laravel skips existing files (safe for local edits, but upstream will not refresh).

Refresh Cursor rules and RPI assets (if you use Cursor)

php artisan hisoft:cursor --api --rpi --force
# or --inertia --rpi

Refresh Copilot instructions (if you use Copilot)

php artisan hisoft:copilot --api --force
# or --inertia

Re-run only the steps that apply to your team’s tooling.

Priority Order

When conventions conflict:

.ai/local/* (project-specific rules)
.ai/upstream/* (package conventions)

Conventions Overview

Shared (both API and Inertia)

File	Description
`conventions.md`	Architectural principles and layer responsibilities
`exceptions.md`	Domain exception handling patterns
`testing.md`	Testing strategy with Pest
`phpdocs.md`	PHPDoc conventions for code documentation
`static-analysis.md`	PHPStan/Larastan level 5 conventions

API-specific

File	Description
`crud.md`	CRUD implementation guidelines
`resources.md`	Laravel Resources and API response patterns

Inertia-specific

File	Description
`pages.md`	Page component structure and naming
`forms.md`	Form handling with useForm
`props.md`	Data sharing and HandleInertiaRequests
`components.md`	Reusable component conventions

Development

Run tests:

docker compose run --rm test

Run static analysis:

composer analyse

License

MIT

hisoft / laravel-conventions

Maintainers

Package info

Statistics

Security