Claudavel

Laravel + Claude Code, configured to work together.

One command installs a complete Laravel stack with AI-powered code review, consistent coding standards that Claude actually follows, and GitHub workflows that let you @mention Claude in issues and PRs.

composer require stumason/claudavel
php artisan claudavel:install

Why This Exists

Claude Code is powerful, but it works better when your project has clear conventions. Claudavel gives you:

• Coding standards Claude follows - Published to docs/standards/ and referenced in CLAUDE.md. No more explaining the same patterns every session.
• AI code review on every PR - Claude reviews your code automatically via GitHub Actions. Catches bugs, suggests improvements, checks against your standards.
• @claude in issues and PRs - Mention Claude anywhere in GitHub and it responds with context about your codebase.
• A complete stack - Fortify, Sanctum, Horizon, Reverb, Telescope, Pail, Wayfinder, Sqids. All configured, all working together.

Quick Start

laravel new my-app
cd my-app
composer require stumason/claudavel
php artisan claudavel:install
createdb my_app
composer run dev

Then set up Claude's GitHub integration:

claude /install-github-app

This adds the CLAUDE_CODE_OAUTH_TOKEN secret to your repository, enabling AI code review and @claude mentions.

What Gets Installed

Packages

Claude Code Assets

The CDR pattern: every non-trivial /commit writes a short markdown record of the reasoning, trade-offs, and rejected alternatives from the conversation that produced the change, then backfills the commit SHA into it. Six months later, git log tells you what changed and docs/context/ tells you why. Trivial commits (typos, dep bumps, formatting) skip the record.

GitHub Workflows

Note: The unified ci.yml workflow runs three parallel jobs:

• Lint (~55s): PHP Pint, Wayfinder types, TypeScript, ESLint, Prettier
• Test (~1m20s): PostgreSQL 16, frontend build, Pest with coverage
• Security (~20s): Composer + npm audit

@claude Workflow Security

The claude.yml workflow gives Claude write access to your repository. This is intentional - it allows Claude to create branches, push commits, and open PRs on your behalf.

Who can trigger Claude:

• Only repository owners and collaborators can trigger Claude via @mentions
• External contributors and random users cannot trigger Claude, even on public repos

What Claude can do:

• Create and push branches
• Create pull requests (gh pr create)
• Merge pull requests (gh pr merge)
• Comment on issues and PRs
• Close issues

What Claude cannot do:

• Delete branches or force push
• Modify repository settings
• Access secrets beyond CLAUDE_CODE_OAUTH_TOKEN
• Trigger on comments from non-collaborators

If you need stricter controls, you can modify the workflow's if condition or remove claude.yml entirely with --no-workflows.

Coding Standards

Published to docs/standards/ with conventions that matter:

• Actions pattern - Business logic in app/Actions/{Domain}/
• DTOs - Type-safe data containers in app/DataTransferObjects/
• Money as integers - Store cents, not dollars
• Lowercase imports - @/components/button not @/Components/Button

These get referenced in your CLAUDE.md so every Claude session knows your conventions.

Environment

DB_CONNECTION=pgsql
SESSION_DRIVER=redis
CACHE_STORE=redis
QUEUE_CONNECTION=redis
ADMIN_EMAILS=you@example.com,team@example.com

Configuration

Claudavel publishes config/claudavel.php for package settings:

// config/claudavel.php
return [
    'admin_emails' => env('ADMIN_EMAILS'),  // Comma-separated list
];

Admin emails control access to Horizon and Telescope in production. In local environment, everyone has access.

Features

ID Obfuscation

Never expose sequential IDs. Add the trait to any model:

use App\Models\Traits\HasUid;

class User extends Model
{
    use HasUid;
}

$user->uid;  // "K4x9Pq" instead of "1"
User::findByUid('K4x9Pq');  // Works
Route::get('/users/{user}', ...);  // Binds automatically

Generator Commands

php artisan make:action User/UpdateProfile
php artisan make:dto UserProfile --properties=id:int,name:string,email:?string
php artisan types:generate  # Generates TypeScript interfaces from DTOs

Health Check

The /health endpoint verifies database, Redis, cache, queue, and storage. Use it for load balancer checks.

Installation Options

php artisan claudavel:install                      # Install everything (default)
php artisan claudavel:install --horizon            # Only Horizon (skip Reverb, Telescope)
php artisan claudavel:install --no-workflows       # Skip GitHub workflows
php artisan claudavel:install --force              # Overwrite existing files

The command is idempotent - run it on existing projects and it only installs what's missing.

Development Server

composer run dev runs everything concurrently:

• Laravel dev server
• Horizon (queue worker)
• Reverb (WebSockets)
• Scheduler (schedule:work)
• Pail (log tailing)
• Vite (frontend)

Repository Setup

Claudavel installs comprehensive GitHub repository setup scaffolding:

Issue Templates

• Bug Report - Structured bug reports with area classification
• Feature Request - Feature requests with MVP priority tracking
• Config - Links to project board for roadmap visibility

Pull Request Template

Laravel-specific compliance checklist:

• Code standards verification (docs/standards/)
• Type generation check (php artisan types:generate)
• Pint formatting (vendor/bin/pint --dirty)

CODEOWNERS

Template file for automatic PR reviewer assignment.

Husky + lint-staged Pre-commit Hooks

Automatically formats code before commits:

• PHP files → Laravel Pint
• JS/TS files → ESLint + Prettier
• CSS/JSON/MD/YAML → Prettier

Setup:

npm install --save-dev husky lint-staged
npx husky init

The installer creates .husky/pre-commit and adds lint-staged config to package.json.

Branch Protection (Recommended)

Configure branch protection rules for main:

• Require status checks: Lint, Test, Security
• Dismiss stale reviews
• Don't enforce on admins (allows maintainer override)
• No force pushes or deletions

Note: Branch protection requires GitHub Pro for private repositories.

ESLint Configuration

The ESLint config automatically ignores Wayfinder generated files:

• resources/js/actions/**
• resources/js/routes/**

This prevents import order and unused variable warnings for generated code.

Keeping Stubs Updated

The workflow files, templates, and configs installed by Claudavel are static copies. To get updates:

composer update stumason/claudavel
php artisan claudavel:install --force

The --force flag overwrites existing files with the latest versions. Review the changes before committing.

Note: Dependabot monitors your project's composer.json, package.json, and workflow files - but not the stub templates in the Claudavel package itself. Updating Claudavel is how you get improved stubs.

Requirements

• PHP 8.3+
• Laravel 12+
• Postgres
• Redis

License

MIT