Fresh Package Laravel Package

Technical Evaluation

Architecture fit

• This is a repository template, not a Composer dependency. Nothing ships into production applications; generated code is owned from commit one. That eliminates the usual third-party runtime risk profile (transitive dependency surface, CVE exposure, version pinning conflicts) and replaces it with a conventions decision.
• Fit is strongest where we expect to author multiple Laravel packages and want a pre-decided layout: service provider seam, config merge + publish tags, migrations, test harness, static analysis, CI, Composer metadata.
• Supports backend-only and full-stack from one starting point, which lets us defer the delivery-shape decision until a package actually has a surface.
• Misaligned if our stack is framework-agnostic PHP, or if we already run a monorepo/path-repository layout with its own release pipeline that this skeleton would fight.

Integration feasibility

• Feasible in a single sprint for a pilot: clone/template → placeholder sweep → composer dump-autoload → full suite green.
• The real feasibility gate is toolchain alignment: the skeleton presumes modern PHP, PHPStan, Rector, Pint, Pest/PHPUnit, and a Testbench-style workbench/ sandbox. If our team has not standardized on those, adoption becomes a tooling migration disguised as a scaffolding decision.
• Extension points ranked by safety: Composer scripts (safe to customize — CI, lint, registry steps), config/publish tags, service provider (additive only), directory structure (last resort — deep forks make future rebases expensive).

Technical risk

• Template drift is the dominant risk, not runtime risk. There is no propagation mechanism from upstream into already-generated packages; the upgrade path is manual diff, selective cherry-pick, or regenerate. Teams that fork, customize, and diverge quietly erode the entire standardization benefit.
• Bus factor and support posture: pre-1.0, single maintainer, ~33 stars, no declared dependents, no SLA or deprecation policy. Plan to own the fork.
• Signal-quality caveats: the zero-dependents figure structurally understates usage (scaffolding repos are cloned, not required), and the v0.4.0 release timestamp appears future-dated — verify against actual repository state before citing momentum or pinning to it.
• Documentation depth is deliberately minimal (further decluttered in v0.4.0); expect to read source, composer.json, service provider, and commit history.
• Placeholder cleanup is where skeletons break — markers hide in namespaces, class names, config keys, publish tag strings, README, and SKILL.md. v0.4.0 shipped a fix for exactly this failure mode ("broken structure after marker cleanup").

Key questions

1. How many Laravel packages do we realistically author in the next two quarters? Fewer than two, and the learning cost likely does not repay.
2. Who is the named internal owner of our fork, and which upstream tag are we pinned to?
3. Do we already have a scaffolding generator or monorepo release pipeline this would duplicate or conflict with?
4. Is "opinionated structure" something the team has bought into before package #1, or will every repo diverge within a month?
5. Do we want adopter-facing, machine-readable integration guidance (SKILL.md) as part of a package's definition of done?
6. What is our willingness to absorb Laravel/PHP major upgrades as a scheduled review activity rather than a CI discovery?

Integration Approach

Stack fit

• Targets Laravel with Composer PSR-4 autoloading; the psr-4 map in composer.json determines namespace and therefore every use statement in generated code.
• Bundled quality gates (PHPStan, Rector, Pint, Pest/PHPUnit) and a runnable workbench/ sandbox match a modern Laravel team's expected inner loop; v0.4.0 enabled parallel sandbox runs, so concurrent/long test runs are supported.
• Package discovery is wired via extra.laravel.providers; config publishing via a publish tag paired with mergeConfigFrom.

Migration path

• Do not migrate mature, stable packages into this layout. Use it for greenfield only; selectively backport the structure, Composer scripts, static-analysis config, and sandbox pattern into existing repos. A forced rewrite of a working package is pure churn.
• Adopt a two-repo posture (the important call): upstream is a source of ideas; our internal golden template — with our CI config, license headers, coding standards, and registry settings baked in — is what teams actually scaffold from.
• Fork-and-pin, not track-loose. Pin an upstream tag, diff periodically, cherry-pick deliberately.

Compatibility

• Verify at pin time: supported Laravel/PHP version ranges, PHPStan and Rector config compatibility with our versions, and whether extra.laravel.providers discovery matches our Composer/Laravel setup.
• Confirm the pinned tag actually exists and its date is accurate before recording it as the baseline.
• Treat SKILL.md as part of the public API contract — scoped to adopter integration only, never package internals — and update it in the same PR that changes public surface.

Sequencing

1. Pilot (1 package, boring on purpose): backend-only package that merges a config file, binds one thing in the service provider, and has one passing test in the sandbox. Instrument time-to-first-green-test — that metric is the entire value proposition.
2. Harden the rename pass: do the placeholder sweep as one deliberate, atomic pass, then immediately run tests and static analysis. Document the checklist.
3. Fork into an internal golden template: bake in our CI, licenses, standards, registry. Record the pinned version and adoption rationale in the generated repo (README or CONTRIBUTING), not in someone's head.
4. Pilot the SKILL.md convention on that first package to test whether machine-readable adopter guidance is worth the definition-of-done cost.
5. Generalize to greenfield packages only, with a named owner and a scheduled upstream diff cadence.
6. Reassess at 1.0 (or on maintainer/support signals) before any standardization mandate.

Operational Impact

Maintenance

• Runtime maintenance burden: zero. No production dependency, no version pinning, no CVE surface in deployed applications.
• Template maintenance burden: real but bounded. Budget a recurring (e.g., quarterly) upstream diff against the pinned tag, plus a scheduled review activity for Laravel/PHP major upgrades. There is no automated propagation from upstream to generated repos — that gap is the job.
• Keep Rector/automated refactors in their own commits, separate from feature diffs, or review becomes useless and rebases against the next upstream tag become painful.

Support

• No vendor support, SLA, or deprecation policy: we own our fork. That is acceptable because the downside is bounded — walking away costs one repo's worth of scaffolding, not a production migration.
• Internal support model required: named owner, documented pinned version, documented divergence from upstream, and a place to ask questions that is not the upstream issue tracker.
• Don't plan around upstream responsiveness; treat upstream as an idea source with best-effort engagement.

Scaling

• The value is explicitly marginal cost of the nth package: pre-decided namespaces, provider wiring, config publishing, test harness, and static analysis make package #5 cost roughly what package #1 cost, and remove repeated code-review debate.
• Consistency benefits compound only if generated repos stay close to the golden template. Divergence is the scaling failure, not load or performance.
• Scales poorly as a mandate — "opinionated" is a conventions decision. Get buy-in before package #1, not after package #3 when everyone has quietly forked.

Failure modes

• Half-renamed skeleton — most common. Symptoms: package not discovered in the sandbox (check extra.laravel.providers, re-run composer dump-autoload), config not publishing (publish tag name disagreeing with the mergeConfigFrom path). Often fails at autoload time and passes silently until the sandbox boots.
• Template drift / quiet divergence — standardization benefit evaporates without anyone noticing.
• Stale pin — packages scaffolded a year apart use incompatible conventions; onboarding docs go out of date.
• Mixed automated refactors — Rector churn buried in feature diffs, making review and future rebases expensive.
• Overreach — migrating stable packages or starting full-stack "just in case," carrying publish tags and asset pipelines never exercised.
• Future-dated release / thin docs read as momentum — verify repository state before quoting it as evidence or pinning.

Ramp-up

• Technically shallow: one deliberate placeholder sweep plus a green test run is the whole onboarding. Learning cost is concentrated in conventions, not code.
• Expect a slow first package (fighting the harness) and a fast second — capture the first package's friction log as the golden-template backlog.
• Do not require reading mature documentation; budget time to read source, composer.json, the service provider, and commit history. Bookmark those three plus the test bootstrap — they answer most "how does this work?" questions.
• Onboarding new engineers is a net win if conventions hold: one layout to learn across every internal package, plus SKILL.md giving their coding agents scoped, public-API-only integration guidance.