README

Build Laravel apps faster with AI-powered agentic development.

What is this?

An opinionated Laravel starter kit fine-tuned for agentic development with Claude Code. Instead of writing every line yourself, you collaborate with specialized AI agents that understand Laravel conventions, Livewire patterns, and testing best practices.

This kit provides:

Multi-agent orchestration — Three specialized agents (backend, UI, QA) that handle different aspects of development
Structured workflow — A 4-phase development cycle (Explore → Plan → Validate → Implement) that ensures quality
Domain-specific skills — Pre-loaded knowledge for Livewire 4, Flux UI, Pest testing, and Fortify authentication
MCP integrations — Laravel Boost for app introspection and Playwright for browser testing

Think of it as pair programming where your partner already knows Laravel inside and out.

Features

Pre-configured Claude Code agents
- backend-engineer — APIs, database, Eloquent, services, authentication
- ui-engineer — Livewire components, Blade templates, Flux UI, Tailwind
- qa-expert — Test strategy, E2E testing, quality metrics
Domain-specific skills that activate automatically
- Livewire 4 single-file components
- Flux UI Free component library
- Pest 4 testing framework
- Laravel Fortify authentication
Structured development workflow
- Mandatory exploration before implementation
- Plan approval gates
- Subagent delegation rules
Modern Laravel stack
- Laravel 12 with streamlined structure
- Livewire 4 with islands, async actions, and new directives
- Tailwind CSS 4 with CSS-first configuration
- Flux UI Free for polished components
Ready-to-use authentication
- Login, registration, password reset
- Email verification
- Two-factor authentication (2FA)
- Profile management

Tech Stack

Technology	Version	Purpose
Laravel	12.x	PHP framework
Livewire	4.x	Reactive components
Tailwind CSS	4.x	Utility-first CSS
Flux UI	2.x (Free)	Component library
Pest	4.x	Testing framework
Fortify	1.x	Authentication backend
PHP	8.2+	Runtime

Prerequisites

Before you begin, make sure you have:

PHP 8.2+ with required extensions
Composer for PHP dependencies
Node.js 18+ and npm for frontend assets
Claude Code CLI installed and authenticated
SQLite (default) or MySQL/PostgreSQL

Install Claude Code

If you haven't already, install Claude Code:

npm install -g @anthropic-ai/claude-code

Then authenticate:

claude login

Quick Start

Option 1: Laravel Installer (Recommended)

laravel new my-app --using=laravel-agent-kits/claude-livewire-starter-kit

Option 2: Composer Create-Project

composer create-project laravel-agent-kits/claude-livewire-starter-kit my-app
cd my-app

Post-Installation

# Install frontend dependencies
npm install

# Build assets
npm run build

# Start the development server
composer run dev

Then open your browser to http://localhost:8000.

MCP Server Setup

This starter kit is designed to work with two MCP (Model Context Protocol) servers that supercharge Claude Code's capabilities.

1. Laravel Boost (Required)

Laravel Boost gives Claude Code deep insight into your Laravel application — database schemas, routes, configurations, error logs, and version-specific documentation.

Installation

# It's already included as a dev dependency
composer require laravel/boost --dev

What it provides

Tool	Purpose
`application-info`	App overview, packages, environment
`database-schema`	Table structures and relationships
`list-routes`	All registered routes
`search-docs`	Version-specific Laravel documentation
`tinker`	Execute PHP in app context
`last-error`	Recent application errors
`browser-logs`	Frontend console output

Configuration

Laravel Boost is auto-configured via the mcp.json file in your project root. No additional setup required.

2. Playwright MCP (Recommended)

Playwright MCP enables Claude Code to interact with your application in a real browser — taking screenshots, filling forms, clicking buttons, and verifying visual output.

Installation

# Add Playwright MCP to Claude Code
claude mcp add playwright npx @playwright/mcp@latest

That's it! Claude Code will handle the rest.

What it provides

Tool	Purpose
`browser_navigate`	Load pages
`browser_click`	Click elements
`browser_fill_form`	Complete forms
`browser_take_screenshot`	Capture visual state
`browser_console_messages`	Check for JS errors
`browser_resize`	Test responsive design

Project Structure

.claude/
├── agents/                 # Subagent definitions
│   ├── backend-engineer.md    # Backend/API specialist
│   ├── ui-engineer.md         # Frontend/Livewire specialist
│   └── qa-expert.md           # Testing/QA specialist
├── rules/                  # Workflow rules
│   ├── structured-workflow.md # 4-phase development cycle
│   └── subagents-delegation.md # When to use which agent
└── skills/                 # Domain-specific knowledge
    ├── livewire-development/
    ├── fluxui-development/
    ├── pest-testing/
    └── developing-with-fortify/

app/
├── Livewire/              # Livewire action classes
├── Models/                # Eloquent models
└── ...

resources/
└── views/
    └── pages/             # Livewire single-file components (⚡ prefix)

tests/
├── Feature/               # Feature tests
└── Unit/                  # Unit tests

The Agent System

This starter kit uses a multi-agent orchestration pattern. You (or the main Claude instance) act as the orchestrator, delegating work to specialized agents.

How It Works

You (Orchestrator)
    │
    ├── Analyze request
    ├── Break into subtasks
    ├── Delegate to agents
    │
    ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│ backend-engineer│  │   ui-engineer   │  │    qa-expert    │
│                 │  │                 │  │                 │
│ • APIs          │  │ • Livewire      │  │ • Test strategy │
│ • Database      │  │ • Blade/Flux UI │  │ • E2E tests     │
│ • Auth/Authz    │  │ • Tailwind      │  │ • Bug hunting   │
│ • Queues        │  │ • Accessibility │  │ • Performance   │
└─────────────────┘  └─────────────────┘  └─────────────────┘

The 4-Phase Workflow

Every non-trivial task follows this cycle:

Explore — Gather context, read files, understand existing patterns
Plan — Design the implementation approach, present for approval
Validate — Wait for explicit user approval before writing code
Implement — Delegate to appropriate agents, execute the plan

This prevents wasted effort and ensures alignment with your vision.

Example Delegation

User: "Add a contact form to the site"

Orchestrator thinking:
  → This needs a Livewire component (ui-engineer)
  → Might need email sending logic (backend-engineer)
  → Should have tests (qa-expert)

Orchestrator: "I'll coordinate this across agents:
  1. backend-engineer for email service
  2. ui-engineer for the form component
  3. qa-expert for test coverage"

Available Scripts

Composer Scripts

# Start development (server + queue + logs + vite)
composer run dev

# Run all tests with linting
composer run test

# Format code with Pint
composer run lint

# Initial setup (install, migrate, build)
composer run setup

NPM Scripts

# Build assets for production
npm run build

# Start Vite dev server with HMR
npm run dev

Artisan Commands

# Run tests
php artisan test --compact

# Run specific test
php artisan test --filter=ProfileUpdateTest

# Create a Livewire component
php artisan make:livewire ComponentName

# List all routes
php artisan route:list

Skills Reference

Skills activate automatically based on what you're working on:

Skill	Activates When
`livewire-development`	Creating Livewire components, using `wire:` directives, debugging reactivity
`fluxui-development`	Building with Flux UI components, forms, modals, buttons
`pest-testing`	Writing tests, TDD, assertions, debugging test failures
`developing-with-fortify`	Authentication features, 2FA, password reset, email verification

You can also manually invoke skills:

/livewire-development
/pest-testing

Tips for Best Results

Be specific about what you want — "Add a contact form with name, email, and message fields that sends an email" is better than "add a form"
Let the workflow guide you — Don't skip the exploration and planning phases; they prevent rework
Trust the agents — Each agent is specialized; let them do their job
Review the plans — The validation phase exists for a reason; use it to catch misunderstandings early
Use the MCP tools — Laravel Boost's search-docs tool provides version-specific documentation that's invaluable

Troubleshooting

Vite manifest error

Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest

Run npm run build or start the dev server with npm run dev.

MCP server not connecting

Ensure the MCP server is installed (npm list -g @anthropic-ai/mcp-playwright)
Check your settings.json configuration
Restart Claude Code

Tests failing after changes

# Clear config cache
php artisan config:clear

# Run tests
php artisan test --compact

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is open-sourced software licensed under the MIT license.

Built with Laravel, Livewire, and Claude Code.

laravel-agent-kits / claude-livewire-starter-kit

Maintainers

Package info

Statistics

Security

README

What is this?

Features

Tech Stack

Prerequisites

Install Claude Code

Quick Start

Option 1: Laravel Installer (Recommended)

Option 2: Composer Create-Project

Post-Installation

MCP Server Setup

1. Laravel Boost (Required)

Installation

What it provides

Configuration

2. Playwright MCP (Recommended)

Installation

What it provides

Project Structure

The Agent System

How It Works

The 4-Phase Workflow

Example Delegation

Available Scripts

Composer Scripts

NPM Scripts

Artisan Commands

Skills Reference

Tips for Best Results

Troubleshooting

Vite manifest error

MCP server not connecting

Tests failing after changes

Contributing

License