PHPackages                             gracjankubicki/laravel-architecture-kit - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. gracjankubicki/laravel-architecture-kit

ActiveLibrary[Utility & Helpers](/categories/utility)

gracjankubicki/laravel-architecture-kit
=======================================

Laravel architecture guidance, application audit, and guard tooling for AI coding agents.

v0.1.10(yesterday)119↑200%MITPHP ^8.3

Since Jul 7Compare

[ Source](https://github.com/gracjankubicki/laravel-architecture-kit)[ Packagist](https://packagist.org/packages/gracjankubicki/laravel-architecture-kit)[ RSS](/packages/gracjankubicki-laravel-architecture-kit/feed)WikiDiscussions Synced today

READMEChangelog (10)Dependencies (24)Versions (10)Used By (0)

 [![Laravel Architecture Kit](https://raw.githubusercontent.com/gracjankubicki/laravel-architecture-kit/main/art/banner.png)](https://raw.githubusercontent.com/gracjankubicki/laravel-architecture-kit/main/art/banner.png)

 [ ![Tests](https://github.com/gracjankubicki/laravel-architecture-kit/actions/workflows/tests.yml/badge.svg?branch=main) ](https://github.com/gracjankubicki/laravel-architecture-kit/actions/workflows/tests.yml) [![Coverage](https://raw.githubusercontent.com/gracjankubicki/laravel-architecture-kit/main/art/coverage.svg)](https://raw.githubusercontent.com/gracjankubicki/laravel-architecture-kit/main/art/coverage.svg) [ ![Latest Version on Packagist](https://camo.githubusercontent.com/d5f1285b601891525c3e637dbb47412137167e71019929fcc5be1bac84b240c3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f677261636a616e6b756269636b692f6c61726176656c2d6172636869746563747572652d6b69742e7376673f7374796c653d666c61742d737175617265) ](https://packagist.org/packages/gracjankubicki/laravel-architecture-kit) [ ![Total Downloads](https://camo.githubusercontent.com/35c9bdaeb3228fbae05427f1d591ef0253ab478a584688ca788982c4db535589/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f677261636a616e6b756269636b692f6c61726176656c2d6172636869746563747572652d6b69742e7376673f7374796c653d666c61742d737175617265) ](https://packagist.org/packages/gracjankubicki/laravel-architecture-kit) [ ![License](https://camo.githubusercontent.com/4638771d4096e7c1b451f7cc33221831174a5b3d0892ab7526faa18987759e87/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f677261636a616e6b756269636b692f6c61726176656c2d6172636869746563747572652d6b69742e7376673f7374796c653d666c61742d737175617265) ](https://packagist.org/packages/gracjankubicki/laravel-architecture-kit) [![PHP Version](https://camo.githubusercontent.com/9712fe03b9016afd85a6db2925af9a04862c364da0da03fae5ac17190a49b2b2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f677261636a616e6b756269636b692f6c61726176656c2d6172636869746563747572652d6b69742e7376673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/9712fe03b9016afd85a6db2925af9a04862c364da0da03fae5ac17190a49b2b2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f677261636a616e6b756269636b692f6c61726176656c2d6172636869746563747572652d6b69742e7376673f7374796c653d666c61742d737175617265) [![Laravel 12 and 13](https://camo.githubusercontent.com/9e9b743bcbf97a29fe735334a4a8e906d05d60310969905af6607cef8da30138/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d313225323025374325323031332d4646324432303f7374796c653d666c61742d737175617265266c6f676f3d6c61726176656c266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/9e9b743bcbf97a29fe735334a4a8e906d05d60310969905af6607cef8da30138/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d313225323025374325323031332d4646324432303f7374796c653d666c61742d737175617265266c6f676f3d6c61726176656c266c6f676f436f6c6f723d7768697465) [![MCP enabled](https://camo.githubusercontent.com/e3bebed896ca4a689200d7fea632b841b2b61f97e1c3f16bd453cf03eab2ffae/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d43502d656e61626c65642d3666343263313f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/e3bebed896ca4a689200d7fea632b841b2b61f97e1c3f16bd453cf03eab2ffae/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d43502d656e61626c65642d3666343263313f7374796c653d666c61742d737175617265)

Laravel Architecture Kit
========================

[](#laravel-architecture-kit)

Laravel tooling for three explicit capabilities: generated architecture guidance, AST-backed audit, and an optional guard for selected enforceable rules.

This package is meant to be installed as a development dependency. It lets a project choose the architecture patterns it uses, then generates commit-ready Laravel Boost guidelines and skills so AI agents code closer to the project's conventions.

Capabilities and enforcement
----------------------------

[](#capabilities-and-enforcement)

CapabilityWhat it providesEnforced by guard?GuidanceGenerated guidelines, skills, and MCP resourcesNo — prose is advice for agents and reviewers.AuditDeterministic AST and filesystem findingsYes, for implemented audit rules.GuardDoctor plus audit as a CI/hook gateYes, according to selected architectures and strict mode.Guidance is intentionally broader than the rules that can be verified deterministically. Add project-specific custom audit rules when a local policy, such as bilingual documentation, must be enforced.

Installation
------------

[](#installation)

```
composer require --dev gracjankubicki/laravel-architecture-kit
php artisan architecture-kit:install
```

The install command is interactive. It asks which architecture patterns the project uses, writes `config/architectures.php`, and generates:

```
.ai/guidelines/architecture-kit.md
.ai/skills/architecture-kit-{architecture}/SKILL.md

```

It can also install agent integration without manual file editing:

```
.codex/config.toml
.mcp.json
.codex/hooks.json
.claude/settings.json
.architecture-kit/hooks/guard.sh

```

If Laravel Boost is installed, the command can also run:

```
php artisan boost:update --discover
```

Boost then syncs the generated `.ai` resources into agent files such as `AGENTS.md`, `CLAUDE.md`, and other configured AI instructions.

The generated `.ai/guidelines/architecture-kit.md` file is a compact index, not the full rulebook. It lists enabled architectures, folders, hard rules, global rules, and the guard command. Agents should expand details only when needed through:

```
php artisan architecture-kit:guidelines actions --agent
```

The same full guidance is also available through the generated `architecture-kit-{architecture}` skills, the MCP tool `architecture-rules`, and the MCP resource `architecture-kit://guideline`.

Commands
--------

[](#commands)

```
php artisan architecture-kit:install
php artisan architecture-kit:install-agents
php artisan architecture-kit:install-agents --hooks
php artisan architecture-kit:mcp
php artisan architecture-kit:doctor
php artisan architecture-kit:guidelines
php artisan architecture-kit:guidelines actions --agent
php artisan architecture-kit:guard --changed --strict
php artisan architecture-kit:guard --changed --base=origin/main --strict
php artisan architecture-kit:audit --changed --strict
php artisan architecture-kit:audit --changed --base=origin/main --strict
php artisan architecture-kit:audit --update-baseline
php artisan architecture-kit:audit --agent
php artisan architecture-kit:guard --agent
php artisan architecture-kit:doctor --agent
php artisan architecture-kit:explain E_THIN_CONTROLLER_MODEL_WRITE --agent
```

`architecture-kit:install` is idempotent. Re-run it to change the selected architectures, the PHP runtime, or regenerate outdated `.ai` resources.

`architecture-kit:install-agents` bootstraps MCP and hook configuration for selected AI agents. It writes Codex MCP config to `.codex/config.toml` and Claude Code MCP config to `.mcp.json`, using the runtime from `config/architectures.php` as the initial wrapper command.

Agent integration files are developer-owned after creation. Re-running the command preserves existing Architecture Kit MCP entries, hook entries, `.architecture-kit/hooks/guard.sh`, and its README byte-for-byte. A valid existing config without the integration is merged safely; invalid JSON or incompatible configuration blocks installation instead of being overwritten. If the runtime or project-specific behavior changes later, edit these files directly.

In contrast, `.ai/guidelines/**` and `.ai/skills/**` are package-generated resources and may be regenerated by `architecture-kit:install`. `.architecture-kit/install.json` is internal package state.

`architecture-kit:doctor` is read-only. It reports missing, outdated, stale, or blocked generated resources and, when agents were installed, verifies that selected agent MCP and hook integrations still exist and remain parseable. Valid developer customizations are not treated as outdated.

`architecture-kit:guidelines` is read-only. Without an argument it lists known architectures with a one-line summary. With a slug it returns the full guideline for one architecture, even when that architecture is available but not enabled.

`architecture-kit:audit` is read-only. It scans application code against the enabled architecture rules. Use `--changed --strict` before finishing AI-generated code so warnings and errors block the final handoff. In CI or after committing, pass `--base=origin/main` or another base ref to audit the committed diff.

Use `architecture-kit:audit --update-baseline` when adopting Architecture Kit in a legacy project. It writes the current findings to `.architecture-kit/baseline.json`; future audits suppress only the matching existing findings and still report new violations. Use `--no-baseline` to ignore the baseline for one run.

`architecture-kit:guard` is read-only. It combines `doctor`-equivalent generated-resource checks with the deterministic audit rules that are actually implemented. Guidance without a corresponding audit rule remains reviewer- and agent-enforced. Use `--json` for hooks and MCP tools.

### Agent Output

[](#agent-output)

Human-facing command output stays descriptive. Existing `--json` output stays compatible for hooks and integrations. AI agents can use `--agent` for compact, single-line JSON:

```
php artisan architecture-kit:audit --agent --limit=20
```

Example:

```
{"v":1,"ok":false,"cmd":"audit","scope":"changed","err":1,"warn":0,"sup":{"inline":0,"baseline":0},"trunc":false,"find":[{"r":"thin-controller","s":"err","p":"app/Http/Controllers/InvoiceController.php","l":27,"m":"E_THIN_CONTROLLER_MODEL_WRITE","n":1}],"next":["fix_findings","rerun:audit --agent"]}
```

By default, `--agent` returns finding codes instead of full messages to reduce token usage. Use `--full` when the agent needs full text, or ask for one code:

```
php artisan architecture-kit:explain E_THIN_CONTROLLER_MODEL_WRITE --agent
```

`--limit=0` returns only the summary. When findings or doctor issues are truncated, the payload contains `trunc`, `total`, and `shown`.

Agents can inspect the contract without running the audit:

```
php artisan architecture-kit:audit --agent --schema
```

For cheap on-demand rule expansion:

```
php artisan architecture-kit:guidelines --agent
php artisan architecture-kit:guidelines actions --agent
php artisan architecture-kit:guidelines --schema
```

To install only hook integration through the merge-aware agent installer, use `architecture-kit:install-agents --hooks`:

```
.architecture-kit/hooks/guard.sh
.codex/hooks.json
.claude/settings.json

```

The generated hooks run:

```
php artisan architecture-kit:guard --changed --strict --json
```

Existing valid agent config is merged and unrelated MCP servers or hooks are preserved. Invalid JSON/TOML, or incompatible unmanaged `architecture-kit` entries, block installation with a clear error.

Docker, Sail, and Custom PHP Runtimes
-------------------------------------

[](#docker-sail-and-custom-php-runtimes)

`config/architectures.php` stores how the project runs PHP. When `runtime` is omitted, Architecture Kit uses local PHP as the default runtime.

```
return [
    'enabled' => [
        Architecture::Actions,
    ],
    'runtime' => [
        'driver' => 'docker', // local | sail | docker | custom
        'service' => 'app',
        'php' => 'php',
        'command' => null,
    ],
];
```

For Docker Compose and Sail, generated hooks and MCP configs use raw non-TTY compose commands:

```
docker compose exec -T app php artisan architecture-kit:guard --changed --strict --json
docker compose exec -T app php artisan architecture-kit:mcp
```

Sail is treated as detection convenience only. Architecture Kit reads `APP_SERVICE` from `.env` and defaults to `laravel.test`, but still generates `docker compose exec -T ...` so hooks and MCP stdio stay deterministic.

For `--changed` audits inside Docker or Sail, the PHP runtime must have:

- `git` installed in the container,
- the repository mounted with `.git`,
- the same project files available where artisan runs.

If those requirements are missing, `architecture-kit:doctor` reports runtime warnings. Hooks are fail-closed for every runtime: if the runtime is unavailable and no Architecture Kit JSON payload is returned, the agent turn is blocked with a runtime message.

Mixed teams can commit a small wrapper and use `driver: custom`:

```
#!/usr/bin/env bash
set -euo pipefail

if command -v docker >/dev/null 2>&1 && [ -f compose.yaml ]; then
    exec docker compose exec -T app php "$@"
fi

exec php "$@"
```

```
'runtime' => [
    'driver' => 'custom',
    'service' => null,
    'php' => 'php',
    'command' => ['bin/php-runner'],
],
```

Architectures
-------------

[](#architectures)

The architecture catalog:

PatternDefault placementFocusThin Controllers`app/Http/Controllers`Controllers as HTTP adapters onlyForm Requests`app/Http/Requests`Request validation and authorizationActions`app/Actions`Application use cases with a single public `handle()`Services`app/Services`Aggregated application APIs over several ActionsQuery Objects`app/Queries`Encapsulated read use casesCustom Eloquent Builders`app/Models/Builders`Reusable model-level query scopesData Objects`app/Data`Typed immutable input and result carriersValue Objects`app/ValueObjects`Validated immutable domain valuesEnumsdomain-firstClosed sets with exhaustive `match`API Resources`app/Http/Resources`Read output shapingEloquent Lifecycle`app/Observers`, `app/Lifecycle`Model lifecycle boundaries: thin observers, handlers, after-commit eventsSaloon`app/Http/Integrations`External HTTP integrations through Saloon connectorsPorts And Adaptersnear the owning boundaryExplicit outbound seams for providers and infrastructureModern PHP 8.5cross-cuttingStrict modern PHP runtime contractLaravel AI`app/Ai`Typed `laravel/ai` agents, tools, and promptsLaravel Best Practicescross-cuttingLaravel-native defaults composed with the other enabled patternsSome patterns have hard requirements, validated by `architecture-kit:install` and `architecture-kit:doctor`:

- `Modern PHP 8.5` is a strict runtime contract. The consuming project must require PHP 8.5 or newer in `composer.json`; otherwise the configuration is reported as invalid.
- `Saloon` requires `saloonphp/saloon` `^4.0`, `saloonphp/laravel-plugin`, and `saloonphp/rate-limit-plugin`. The install command offers to `composer require` the missing packages. Constraints that still allow Saloon 3 are reported as invalid because Saloon 4 fixes security issues in v3.
- `Laravel AI` requires `laravel/ai` in `composer.json`.

On the first install (before `config/architectures.php` exists), `Services` is preselected when the project already has an `app/Services` folder, and `Laravel AI` is preselected when `composer.json` already requires `laravel/ai`.

The install command also warns about weak pattern combinations, for example Thin Controllers, Eloquent Lifecycle, or Saloon enabled without Actions as the application boundary.

The project source of truth is `config/architectures.php`:

```