Mod Laravel Package

Product Decisions This Supports

• Architecture direction — "modular monolith now, DDD later" becomes a reversible decision. Layout is a config value (config/mod.php → layout), and built-in presets cover laravel, modules, features, slices, type-first and ddd. A PM can approve a lighter layout today knowing the migration path exists, rather than freezing an architecture in a roadmap doc.
• Build vs. buy for AI-assisted delivery. The package's real product is deterministic placement for coding agents: mod:list --json exposes the active layout, file types, scaffolds and discovery; --dry-run --json returns a machine-readable plan (files, inserts, warnings, would_write, and now an optional per-file state of unchanged or edited) that writes nothing and runs no subprocess. That is a governance primitive you would otherwise build in-house — a convention doc plus a custom tool — and it is the cheapest lever on agent-generated rework.
• Standardization without a framework opinion. It reuses Laravel's own generators and "ships no opinionated scaffolds," so adopting it does not commit the team to a business-logic pattern. This is attractive when product wants consistency but engineering wants to keep architectural freedom.
• Scoping and estimation of a DDD/modularization effort. mod:autoload adds missing PSR-4 entries (e.g. "Domain\\": "src/Domain/") and runs Composer, with --dry-run preview and --no-dump for scripted pipelines. That removes a chunk of the migration cost estimate that would otherwise sit in a "spike" line item.
• Golden-path scaffolding as a delivery accelerator. Application-registered recipes (e.g. mod:crud Knowledge:Document emitting model, migration, factory, requests, resource, policy, controller; the resource-tabs cluster) let a PM define "what a finished slice looks like" and have it reproducible. That directly compresses time-to-first-PR for a new squad member or a new feature area. Dry runs now distinguish kept-but-unchanged members from kept-but-edited ones, so a golden path can be audited without diffing by hand.
• Enforcing conventions at the point of creation, not in review. Every change to the package requires tests, PHPStan and Pint (CI matrix across PHP 8.3–8.5, Laravel 12–13), and the published-API snapshot is guarded — a signal that the contract the agents depend on is treated as a product surface. A PM can point at that as the reason review comments about file location should go to zero.
• Team-boundary decisions. modules (app/Modules/<Module>), features and slices layouts map naturally to squad ownership; custom layouts (Mod::layout('areas')->extends('modules'), ->path('src/Areas/{area}')) let you carve a domain out per team without a fork.

When to Consider This Package

Look at this when most of the following hold:

• The app is Laravel 12 or 13 on PHP 8.3+, and you are already or about to use coding agents against the repo.
• File placement is inconsistent or contested — review churn about "where does this class go," or agents writing files in plausible-but-wrong paths.
• You are planning a modular monolith, feature-sliced or DDD structure and want the option to change your mind cheaply.
• You want Laravel-native generation with no runtime framework lock-in — MIT, no vendor, no module loader to fight.
• You can treat layout config (service-provider Mod::layout(...) calls, config/mod.php) as reviewed code with an owner, and you can allow a generator to modify composer.json via mod:autoload under CI control.
• You need re-runnable, predictable scaffolding in CI or agent loops — dry runs now agree between human and JSON output, honor --force / --skip-existing on scaffold trees and parts, and preserve kept members and migration timestamps.

Look elsewhere, or pilot narrowly first, when:

• Your app already matches Laravel defaults. The default laravel layout "places files exactly like make:*," so the marginal value is near zero for a small single-squad app that is happy with app/.
• You need runtime module machinery — activating/disabling modules, per-module providers, assets, versioned module packages. mod "places files and discovers classes"; that is a different product than a module ecosystem.
• You need vendor accountability. Very early adoption (no dependents, single maintainer, no commercial support path) means you need a contribution or exit plan before making it load-bearing.
• Your conventions live outside the filesystem (event sourcing, CQRS frameworks, heavy codegen pipelines of your own) — mod only solves placement and discovery.
• You cannot absorb a moving target. Active release cadence and pre-1.0-style API churn (@api vs @internal marking is disciplined, but the surface is still evolving) argue for pinning versions and re-validating on upgrade.

How to Pitch It (Stakeholders)

To executives (one paragraph): This is a free, MIT-licensed Laravel package that makes our codebase layout an explicit, configurable decision instead of an accident, and it makes AI-generated code land in predictable, reviewable places. It is cheap to adopt, sits on top of Laravel's own tooling rather than replacing it, and lowers the cost of the two things we keep paying for: onboarding people to "where things go," and reworking agent-generated pull requests. Its latest release tightens the preview/re-run story — dry runs now tell reviewers whether an existing file is unchanged or would be edited, and scaffold trees respect the same --force / --skip-existing rules as single-file scaffolds. The risk is maturity — one maintainer, no external adopters yet — so the recommendation is a timeboxed pilot in one repository with a rollback path, not a company-wide standard.

To engineering leads: It is Laravel's ally, not a framework. Layout is declared in config or a service provider; built-in presets cover laravel, modules, features, slices, type-first and ddd; custom layouts extend a parent (->extends('modules')) and add file types (->generates('validator', in: 'Modules/{module}/Validators')). Agents get a machine inventory (mod:list --json) and a no-write plan (--dry-run --json) with stable warning codes and would_write, so a failed preview exits 0 and is safe to run in a loop. As of v0.7.2, that preview reports existing whole-file members as unchanged or edited by comparing bytes with what the recipe would write; scaffold trees and parts honor --force / --skip-existing, keep kept members and timestamped migration paths, and predict the same outcomes in human and JSON dry runs. Parts and insert placeholders reuse the root migration's resolved identity, including its written timestamp, so later part runs stay consistent. Collisions are refused rather than silently overwritten (--skip-existing, --force). mod:autoload manages PSR-4 for roots outside app/. The upstream repo enforces ~2,000 Pest tests, PHPStan, Pint and a published-API snapshot — the contract we would depend on is defended.

The ask, and how we would judge it: approve a 4–6 week pilot in one service. Success metrics: median time-to-first-merged-PR for new engineers; count of review comments about file placement; rework rate on agent-authored PRs; number of files written outside the declared layout; and whether any team needs a layout change we could not express in a service-provider customization. Decide at the end: adopt as standard, adopt per-repo, or revert — and record the exit cost (layout config is small and the code it generates is plain Laravel, so reverting is a config change plus cleanup, not a rewrite).