---
name: project-laravel
metadata:
  compatible_agents: [claude-code]
  tags: [laravel, php, kickoff, conventions, scaffold, project]
description: >
  Laravel project conventions enforcer and code scaffolder for Kickoff-based projects — ensures
  all generated code follows Kickoff's opinionated conventions including UUID models extending Base,
  Enums with Contract and InteractsWithEnum, modular routes with require_all_in(), helper functions
  in support/, Spatie permission with config-driven access control, architecture test rules, and
  Docker-based local development. Covers model generation, enum creation, action classes with Builder
  pattern, route modules, helper files, and full module scaffolding. Use this skill whenever the user
  asks to scaffold code, generate models, create enums, add routes, write helpers, check conventions,
  or build new modules in a Kickoff Laravel project — including: "scaffold a new module", "generate a
  model", "create an enum", "buat model baru", "tambah enum", "scaffold module untuk users", "buat
  action class", "tambah route", "buat helper function", "check convention", "audit code ni", or
  "ikut convention kickoff". Assumes Laravel Kickoff as the baseline with all conventions pre-configured.
---

# Laravel Project Conventions

Enforce Kickoff's opinionated Laravel conventions and scaffold production-ready code that follows
all project standards — models, enums, actions, routes, helpers, permissions, and architecture rules.

## Command Reference

| Command | Description |
|---|---|
| `/project scaffold` | Scaffold a new module (model + migration + factory + seeder + policy + controller + routes + tests) |
| `/project model` | Generate a model extending Base with correct traits and conventions |
| `/project enum` | Generate an enum implementing Contract with InteractsWithEnum |
| `/project action` | Generate an action class with Builder pattern |
| `/project helper` | Generate a helper function file in support/ |
| `/project route` | Add a modular route file in routes/web/ or routes/api/ |
| `/project check` | Audit existing code against Kickoff conventions |

---

## 1. `/project scaffold` — Full Module Scaffold

### Step 1: Gather Module Info

Ask the user:
1. **Module name** (singular, e.g., `Invoice`)
2. **Fields** (name:type pairs, e.g., `title:string`, `amount:decimal`, `status:enum`)
3. **Relationships** (belongsTo, hasMany, belongsToMany)
4. **Needs API routes?** (yes/no)
5. **Needs web routes?** (yes/no — default yes)

### Step 2: Generate Files

Create the following files in order:

1. **Migration** — UUID PK, uuid column, timestamps, soft deletes (see `references/database-conventions.md`)
2. **Model** — Extends `App\Models\Base`, uses correct traits (see `references/model-conventions.md`)
3. **Factory** — Matches model fields with appropriate Faker methods (see `references/database-conventions.md`)
4. **Seeder** — Uses factory with reasonable count (see `references/database-conventions.md`)
5. **Policy** — Standard CRUD methods with Spatie permission checks (see `references/access-control.md`)
6. **Controller** — Resource controller with policy authorization (suffix "Controller")
7. **Form Request** — Store and Update request classes with validation rules
8. **Route file** — Modular route in `routes/web/` or `routes/api/` (see `references/route-conventions.md`)
9. **Pest tests** — Feature tests for all CRUD operations (delegate to pest-testing skill patterns)
10. **Permission config** — Add entries to `config/access-control.php` (see `references/access-control.md`)

### Step 3: Register

- Add seeder call to `DatabaseSeeder.php`
- Verify route file is in the correct directory (auto-loaded via `require_all_in()`)
- Add permission entries to access-control config

### Output

Display a checklist of all created files with paths.

---

## 2. `/project model` — Model Generation

### Step 1: Gather Info

Ask:
1. **Model name** (singular PascalCase)
2. **Fields** (for fillable array)
3. **Relationships** (belongsTo, hasMany, morphTo, etc.)
4. **Traits needed** (HasHashId, SoftDeletes, HasFactory, etc.)

### Step 2: Generate

Follow all conventions from `references/model-conventions.md`:

- Extend `App\Models\Base` (NEVER `Illuminate\Database\Eloquent\Model`)
- Include `HasFactory` trait
- Define `$fillable` array
- Define `$casts` array for dates, enums, booleans
- Add relationship methods with return types
- Add query scopes if applicable

### Step 3: Generate Migration

Follow `references/database-conventions.md`:
- `$table->id()` + `$table->uuid('uuid')->index()`
- All fields from model
- `$table->timestamps()` + `$table->softDeletes()` (if model uses SoftDeletes)

---

## 3. `/project enum` — Enum Generation

### Step 1: Gather Info

Ask:
1. **Enum name** (PascalCase, e.g., `InvoiceStatus`)
2. **Cases** (list of cases with values)
3. **Backing type** (string or int — default string)

### Step 2: Generate

Follow all conventions from `references/enum-conventions.md`:

- Implement `CleaniqueCoders\Traitify\Contracts\Enum`
- Use `CleaniqueCoders\Traitify\Concerns\InteractsWithEnum` trait
- Define `label(): string` method
- Define `description(): string` method
- Place in `app/Enums/` directory

---

## 4. `/project action` — Action Class Generation

### Step 1: Gather Info

Ask:
1. **Action name** (PascalCase, e.g., `CreateInvoice`)
2. **Input parameters** (what data the action needs)
3. **Return type** (Model, bool, void, etc.)

### Step 2: Generate

Follow all conventions from `references/action-conventions.md`:

- Place in `app/Actions/` directory
- Use Builder pattern with fluent setters
- Single `execute()` method
- Return typed result

---

## 5. `/project helper` — Helper Function Generation

### Step 1: Gather Info

Ask:
1. **Function name(s)**
2. **Purpose / description**
3. **Parameters and return types**

### Step 2: Generate

Follow all conventions from `references/helper-conventions.md`:

- Place in `support/` directory
- Guard EVERY function with `if (! function_exists('name'))` check
- Add PHPDoc blocks
- Keep functions pure where possible

---

## 6. `/project route` — Modular Route File

### Step 1: Gather Info

Ask:
1. **Route type** — web or api
2. **Resource name** (plural kebab-case)
3. **Controller class**
4. **Middleware** (auth, role, permission, etc.)

### Step 2: Generate

Follow all conventions from `references/route-conventions.md`:

- Create file in `routes/web/` or `routes/api/`
- Use `Route::resource()` or explicit route definitions
- Apply middleware via `->middleware()`
- Follow naming conventions

---

## 7. `/project check` — Convention Audit

### What to Check

Scan the project and report violations against all conventions:

1. **Models** — Must extend `App\Models\Base` (see `references/model-conventions.md`)
2. **Enums** — Must implement Contract, use InteractsWithEnum (see `references/enum-conventions.md`)
3. **Migrations** — Must have uuid column (see `references/database-conventions.md`)
4. **Routes** — Must be in modular files (see `references/route-conventions.md`)
5. **Helpers** — Must have `function_exists()` guard (see `references/helper-conventions.md`)
6. **Architecture** — No banned functions (see `references/architecture-rules.md`)
7. **Naming** — Controllers end in "Controller", Policies end in "Policy" (see `references/architecture-rules.md`)
8. **Directory structure** — Files in correct locations (see `references/project-structure.md`)

### Output Format

```
## Convention Audit Report

### ✅ Passing
- Models: 12/12 extend Base
- Enums: 5/5 implement Contract

### ❌ Violations
- app/Models/Legacy.php — extends Eloquent Model instead of Base
- app/Helpers/utils.php — missing function_exists() guard on format_currency()

### 💡 Suggestions
- Consider adding uuid column to legacy_table migration
```

---

## Key Conventions Summary

These conventions MUST be followed in ALL generated code:

1. **Models** — Always extend `App\Models\Base`, never `Illuminate\Database\Eloquent\Model`
2. **Enums** — Implement `CleaniqueCoders\Traitify\Contracts\Enum`, use `InteractsWithEnum`
3. **UUID PKs** — `$table->id()` + `$table->uuid('uuid')->index()` in every migration
4. **Routes** — Modular files in `routes/web/*.php`, loaded via `require_all_in()`
5. **Helpers** — In `support/` directory, guarded with `function_exists()` check
6. **Permissions** — `module.action.target` format, config-driven via `access-control.php`
7. **Architecture** — No `dd`/`dump`/`ray`, no `url()`, no raw `DB::` queries, `env()` only in config
8. **Concerns** — Traits in `app/Concerns/`, must be traits
9. **Contracts** — Interfaces in `app/Contracts/`, must be interfaces
10. **Policies** — In `app/Policies/`, suffix "Policy", standard CRUD methods
11. **Controllers** — Suffix "Controller"
12. **Composer scripts** — `composer test`, `composer format`, `composer analyse`, `composer rector`
13. **Docker** — MySQL, Redis, Mailpit, Meilisearch, MinIO

---

## Reference Files

| File | Description |
|---|---|
| `references/model-conventions.md` | Base model, UUID, traits, relationships, casts |
| `references/enum-conventions.md` | Enum contract, InteractsWithEnum, label/description methods |
| `references/action-conventions.md` | Builder pattern, Actions directory, execute() method |
| `references/route-conventions.md` | Modular routes, require_all_in, naming conventions |
| `references/helper-conventions.md` | support/ directory, function_exists guard, helper patterns |
| `references/access-control.md` | Roles, permissions, policies, middleware, config |
| `references/database-conventions.md` | UUID PKs, migrations, seeders, factories |
| `references/architecture-rules.md` | Banned functions, naming suffixes, strict rules |
| `references/project-structure.md` | Directory layout, config files, Docker, stubs |
| `references/frontend-conventions.md` | TailwindCSS v4, Alpine, Tippy, Vite |