README

claude-kit

Set up Claude Code — and any AI coding agent — on a Laravel project in one command.
Engineering rules, a quality gate (PHPStan · Pint · Pest), skills, feature-doc scaffolding, and stack-aware frontend tooling.

claude-kit packages a battle-tested setup so every Laravel project — and every developer — gets the same guardrails instead of hand-copying config between repos: a Stop-hook + pre-commit quality gate, reusable Claude Code skills, PHPStan level 7 + strict-rules, Pint, Pest with an 80% coverage gate, an architecture test suite, feature-doc scaffolding, and stack-aware frontend tooling (Vue, React, Blade, or none).

Who it's for

• Teams putting Claude Code, Cursor, or GitHub Copilot to work on a Laravel codebase and wanting consistent, enforced conventions.
• Anyone who wants one command for PHPStan + Pint + Pest + git hooks instead of wiring them by hand.
• Projects that need AI coding guardrails an agent can't skip — the same gate runs at commit time, at the end of every Claude turn, and in CI.

Table of contents

• Requirements
• Installation
• What it installs
• Choosing what to install
• The hybrid update model
• The quality gate
• Documentation
• Contributing
• Security
• License

Requirements

• PHP 8.2+
• Laravel 11, 12, or 13
• Claude Code (to use the rules, hooks, and skills)
• A coverage driver (pcov or Xdebug) to enforce the 80% coverage gate

Installation

composer require --dev mohamed-ashraf-elsaed/claude-kit
php artisan claude-kit:install

The installer detects your frontend stack (Inertia + Vue, Inertia + React, Blade/Livewire, or API-only), asks which parts to scaffold, and writes them into your project. Then:

composer install   # installs the dev tooling and wires the git pre-commit hook
npm install        # only if a frontend stack was set up

Not published to Packagist yet? Install straight from GitHub by adding this to your composer.json and running composer require --dev mohamed-ashraf-elsaed/claude-kit:dev-main:

{
    "repositories": [
        { "type": "vcs", "url": "https://github.com/mohamed-ashraf-elsaed/claude-kit" }
    ]
}

What it installs

Existing files are never clobbered — the installer skips them unless you pass --force. composer.json and package.json are merged, preserving your entries.

Choosing what to install

claude-kit:install is a fully interactive configurator — it asks what you want rather than assuming:

• Code style: Pint on/off
• Static analysis: PHPStan on/off → level (0–9) → strict-rules on/off
• Tests: on/off → runner (Pest / PHPUnit) → coverage minimum → architecture tests
• Hooks: Claude Stop hook, git pre-commit hook, feature-doc requirement
• Skills: which bundled skills to install — plus optional search & install of more via skills.sh (npx skills find / add)
• Extras: CLAUDE.md rules, feature-doc templates, .editorconfig, MCP, CI

Your answers are recorded in .claude-kit.json, which the quality gate reads.

php artisan claude-kit:install                      # interactive (recommended)
php artisan claude-kit:install --stack=inertia-react # preselect the stack
php artisan claude-kit:install --no-interaction      # accept sensible defaults
php artisan claude-kit:install --force               # overwrite existing files

• Stacks: inertia-vue, inertia-react, blade, none

The hybrid update model

• Machinery — quality-checks.sh and the Stop hook — lives in vendor/mohamed-ashraf-elsaed/claude-kit/runtime/ and is referenced, so composer update propagates fixes to every project automatically.
• Content you own — CLAUDE.md, the skills, the feature templates, the linter configs, and the generated phpstan.neon — is written into your repo so you can customise it freely.

The quality gate

vendor/mohamed-ashraf-elsaed/claude-kit/runtime/quality-checks.sh is the single source of truth. It runs Pint, PHPStan (level 7 + strict-rules), and Pest (+80% coverage), then the frontend checks your package.json actually defines. The same script backs the git pre-commit hook, Claude's Stop hook, and CI — so the gate is identical everywhere.

• Coverage needs the pcov or Xdebug extension; without it, the gate warns instead of blocking on coverage only.
• Disable the feature-doc requirement with CLAUDE_KIT_FEATURE_DOCS=0.

Documentation

Full guides live in the wiki and the docs/ directory:

• Installation
• Usage
• Configuration
• Frontend stacks
• Quality gate
• Skills
• Architecture
• Publishing to Packagist
• Upgrading
• FAQ

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and the Code of Conduct. Releases follow SemVer; see RELEASING.md.

Security

Please report vulnerabilities privately — see SECURITY.md.

License

The MIT License. See LICENSE.