Koamistarterkit Laravel Package

Technical Evaluation

Architecture fit KoamiStarterKit is a Laravel application scaffold distributed as a Composer project template (composer create-project) plus a prebuilt container image (ghcr.io/koamishin/KoamiStarterKit). It is not a library you require into an existing codebase — it is the codebase. That makes the architecture decision binary: adopt it as the foundation for a greenfield Laravel service, or don't adopt it at all. Retrofitting it into an existing application would mean a full re-platform, not an integration.

The v1.4.0-beta.3 contents confirm the scope is full-stack app plumbing: layout shell rendering (dashboard/settings), authentication/authorization bootstrap (default roles seeded, user role assigned at signup), and frontend build tooling (Vite-Plus format scope). These are opinionated, cross-cutting defaults.

Integration feasibility Feasible only as a project bootstrap. The Quick Start path (create-project → composer run dev) assumes a clean environment with Composer, Node, and PHP toolchain available. The Docker path gives a faster evaluation loop but produces an opaque artifact — the image is built from the same source, so divergence risk is low, yet the image is tagged dev-latest as a rolling alias, which is not a safe deployment reference.

Practical evaluation effort: half a day to stand up, two to three days for a TPM-plus-engineer spike to judge whether the opinionated defaults (roles, auth flow, layout) match our product shape.

Technical risk

• Pre-release stability. 1.4.0-beta.3 is the third beta of an unreleased minor. The dev-latest alias means anyone pulling that tag silently receives a moving target. Pin explicit version tags only.
• Governance and provenance. Release notes are auto-generated from a single commit hash with an automated agent-docs chore in the same batch as functional fixes. Chore and fix are co-mingled — a mild signal of loose change discipline.
• Unverified quality signals. No test results, coverage, CI status beyond a build link, supported Laravel/PHP version matrix, or upgrade/CHANGELOG policy are disclosed. The three fix: entries (double layout shell, missing role on signup, Vite scope) suggest defects were reaching beta, which is normal for beta but relevant to how much validation we must do ourselves.
• AI-agent tooling in the repo. Commits touch "agent docs, skills, and project rules." This is likely harmless, but it means the repository carries opinionated developer-tooling configuration we would need to review or strip to avoid conflicting with our own engineering standards and any policy on AI tooling in the SDLC.
• Single-maintainer / small-project signal. Low ecosystem leverage; if upstream stalls, we own the fork.

Key questions

1. What Laravel and PHP versions are supported, and what is the support window per release?
2. Is there a versioned upgrade path — CHANGELOG, deprecation policy, and a stable (non-beta) release cadence?
3. What is the test suite and CI coverage, and does the image build run the suite as a gate?
4. Are the seeded default roles and signup role assignment configurable, or do we fork to change them?
5. Which portions are intended as "starter you delete" versus "framework you keep current"? That boundary determines our long-term maintenance burden.
6. Is the Docker image intended for production or evaluation only? Any SBOM, base-image, or CVE scanning policy?
7. License terms and contribution/governance model.

Integration Approach

Stack fit Fits teams already on Laravel 11/12-era conventions with Vite-based frontend tooling. Poor fit if we run a different PHP framework, a separate frontend SPA with its own build pipeline, or an established internal Laravel template with house standards — adopting this would mean discarding those standards or re-implementing them on top.

Migration path There is no incremental migration. The credible approaches are:

• Pilot scaffold: generate a throwaway project from the beta, evaluate defaults, then decide whether to build the real service on it. Lowest commitment.
• Reference implementation: use it to harvest patterns (role seeding, layout shell structure) without adopting the repo. Zero lock-in, but also zero upstream benefit.
• Foundation fork: fork at a pinned tag, strip agent tooling and unused defaults, and own it. Highest control, highest cost.

Compatibility Pin the exact tag 1.4.0-beta.3 and the corresponding image digest. Do not use dev-latest outside local evaluation. Verify PHP extension and database requirements before committing — none are stated in the notes, so this is a discovery item.

Sequencing

1. Spike: scaffold locally, run the Quick Start, confirm it boots and auth/roles work as described.
2. Standards review: diff the repo against our Laravel conventions, security baseline, and dependency policy; note the agent-tooling footprint.
3. Docker review: image provenance, base image, size, non-root user, secret handling, and whether it is dev-only.
4. Decision gate: adopt-as-foundation, reference-only, or reject. Do not proceed to a real service until a stable 1.4.0 is available or we accept fork ownership.
5. If adopting: pin tag, remove tool configs, wire into our CI, and document the fork/upstream sync policy.

Operational Impact

Maintenance If we fork, we inherit the entire application's maintenance — framework upgrades, dependency CVE patching, and the beta-to-stable delta. If we track upstream, we depend on a small project's release cadence and a changelog that currently mixes chores with functional fixes. Budget ongoing effort either way; this is not a "set and forget" dependency.

Support No stated support model, SLA, or maintainer responsiveness commitment. Internal support capability should be assumed for anything shipped to production on this base.

Scaling Nothing in this release speaks to scaling characteristics — no queue, cache, session, or horizontal-scaling guidance. Beta-stage starter kits typically target single-instance dev/demo deployments. Production scaling would be our design work, not inherited from the package.

Failure modes

• Silent drift via dev-latest: an unpinned pull changes behaviour with no version change. Highest-severity, easiest to prevent.
• Upstream abandonment: no security patches; we fork and patch ourselves.
• Beta regression in core auth/roles: the signup role-assignment fix in this very release shows authorization bootstrap was broken — an auth bug class we cannot afford to discover in production.
• Divergence debt: local customizations make upstream merges progressively harder until syncing stops.
• Tooling conflict: bundled agent docs and project rules collide with internal engineering standards or tooling policy.

Ramp-up Low technical ramp-up — it's standard Laravel with a documented two-command start, and the Docker path shortens first-run to minutes. The real ramp-up cost is evaluation and hardening: reviewing opinionated defaults, deciding the fork boundary, and establishing a patching process. Estimate one engineer-spike of two to three days for the technical verdict, plus a half-day of standards/security review before any production commitment. Recommend evaluating on a throwaway project only; no production decision until a stable release exists or fork ownership is explicitly accepted.