README

Cippus

Mark the line. Build with confidence.

Cippus gives a Laravel application an editable baseline for AI-assisted development. It lays down clear instructions, practical skills, local services, and a quality toolbelt so agents can write application code with precision—without locking the application into opaque package conventions. Everything it installs belongs to your application and is meant to be adapted.

What Cippus marks

Cippus starts with a pragmatic architecture: Form Requests validate HTTP input, thin controllers translate requests into responses, and focused Actions hold each business use case. Actions use Eloquent directly, keep reusable constraints in model scopes, and wrap related writes in transactions. This keeps behavior reusable from controllers, commands, and jobs without adding repository or service layers by default.

The installer adds:

AGENTS.md, CLAUDE.md, and starter skills for implementation, testing, requirements, and pull-request descriptions;
a FrankenPHP and PostgreSQL Docker setup;
Pint, PHPStan/Larastan, and Rector configuration; and
Composer scripts and compatible development dependencies for the quality suite.

Read the generated AGENTS.md before handing work to an AI agent. It is a strong starting line, not a rigid rulebook.

Installation

Install Cippus as a development dependency, then run the installer from the application root:

composer require --dev mdecode/cippus
php artisan cippus:install

When AGENTS.md or CLAUDE.md already exists, Cippus asks whether to attach its baseline or replace the file; attaching is the default. Other existing files, Composer constraints, and scripts are preserved.

Use --force only when you intentionally want to replace generated resources:

php artisan cippus:install --force

For an offline or staged setup, --no-composer writes resources and Composer scripts without installing dependencies:

php artisan cippus:install --no-composer

Run the installer again without this option when Composer is available.

Make it yours

The installed files are application-owned. Customize the instructions, skills, Docker files, and quality configuration for the application you are building. Re-running Cippus preserves them unless --force is supplied.

The shipped templates are available here for review:

AGENTS.md — architecture, clean-code rules, and testing strategy.
CLAUDE.md — equivalent project instructions for Claude.
laravel-actions — focused use-case implementation.
laravel-testing — efficient Pest coverage.
requirements-to-gh-issue — repository-grounded issue planning.
pr-description — evidence-based pull-request descriptions.

Running the quality gate

# Apply Rector and Pint fixes
composer lint

# Check Rector and Pint without changing files
composer lint:check

# Check Pest type coverage
composer test:type-coverage

# Run Pest with exact coverage
composer test:unit

# Run PHPStan/Larastan
composer test:types

# Run the complete quality suite
composer test

The included Docker setup runs FrankenPHP and PostgreSQL:

docker compose up --build

The exact-coverage command requires Xdebug, which is included in the generated FrankenPHP image.

Changelog

Please see CHANGELOG for recent changes.

Contributing

Thank you for considering contributing to Cippus. Please review the contributing guide to get started.

mdecode / cippus

Package info

Security

Fund package maintenance!

Statistics