Deck Laravel Package

Product Decisions This Supports

• Treating prompts as a product surface rather than a string literal. Every prompt change is a behavior change to a shipped feature. Deck's version directories (v1/, v2/) combined with prompt:activate give you a rollback story that a config/prompts.php array or an inline heredoc does not. That is a real product decision: do we ship prompt changes with the same confidence as code changes?
• Who owns prompt iteration. Because prompts live as files in resources/prompts/, edits flow through pull requests, code review, and git blame. This is a deliberate choice to keep prompts an engineering-owned artifact. If your roadmap says "support ops tunes the tone without a deploy," this package is the wrong shape — that decision belongs to a DB-backed or SaaS prompt CMS.
• Release sequencing: draft in production, promote deliberately. The documented guarantee that creating a version never changes what is served lets you merge prompt work continuously while controlling exposure. That decouples deploy from launch — useful when a prompt change is tied to a marketing moment, a pricing change, or a support policy update.
• Cheap, reversible experimentation. Deck::activate() flipping active_version plus Deck::track() gives you sequential A/B testing: run v1 for a window, run v2 for a window, compare tracked outcomes. This is enough to support an MVP decision like "does a friendlier tone reduce escalations?" It is not a split-testing engine — there is no per-user bucketing, no holdout assignment, no significance testing. Scope the decision accordingly.
• Build vs. buy on prompt infrastructure. The alternative is a prompt-observability SaaS (PromptLayer, Langfuse, Helicone) or an in-house prompt table. Deck is MIT, composer require, one config file, one migration. For a Laravel shop with a small AI surface area, this collapses a "should we buy a vendor?" debate into an afternoon.
• Instrumenting prompt performance as a product metric. Tracking writes to prompt_versions so you can connect version → cost, latency, and downstream outcome. That enables roadmap conversations like "v3 costs 18% more tokens than v2; is the quality gain worth it?" — a trade-off PMs should be in the room for, not a decision buried in an engineering PR.
• Keeping the AI SDK integration from becoming bespoke glue. The HasPromptTemplate trait means agents don't hand-roll instructions(), and make:agent scaffolds a matching prompt directory. This reduces the "every agent does prompt loading slightly differently" drift that makes later migration expensive.

When to Consider This Package

Adopt when most of these are true:

• You are on Laravel and already use (or plan to use) the Laravel AI SDK.
• Your AI surface is bounded — roughly a handful up to a few dozen prompts, owned by engineers who are comfortable editing Markdown in a PR.
• You want prompt versioning, review, and rollback without introducing a new vendor, new credentials, or a new system of record.
• You need a defensible answer to "how do we roll back a bad prompt at 2am?" and "what changed between these two runs?"
• You are pre-scale on experimentation: sequential comparisons are adequate; you are not yet running concurrent multivariate tests with statistical rigor.

Look elsewhere when any of these are true:

• Non-engineers must edit prompts. File-based storage is the opposite of a content-management workflow. Choose a DB-backed or hosted prompt CMS.
• You need real experiment infrastructure. Per-user bucketing, simultaneous variants, guardrail metrics, and significance testing belong in your experimentation platform or a dedicated tool, not a file-activation switch.
• You need an eval harness. Deck does not ship datasets, regression suites, or LLM-as-judge scoring. Pair it with something that does, or accept manual QA.
• Procurement, compliance, or support SLAs matter. Single maintainer, pre-1.0, 117 stars, zero dependents. That is not a supply-chain you put behind a revenue-critical path without a stated exit plan (and the exit is cheap — it is just files).
• You need multi-provider or non-Laravel portability. The core idea is portable, but the value here is the Laravel/Artisan/AI SDK ergonomics.

Treat these as adoption gates, not footnotes. The 0.4.6 changelog is candid and worth reading as a maturity signal: tracking defaulted on in production while its tables were a separate opt-in step, so the natural production install threw no such table on first Deck::get(); Deck::activate() never actually wrote rows, so runtime version switching silently did not work; and prompt names were interpolated into filesystem paths without validation, patched into InvalidPromptNameException. All three are fixed, and the maintainer's transparency is a genuine positive. But it means pin a version, read the changelog on every bump, and validate activation + tracking end-to-end in staging before you rely on either. The tracking-default change also creates a behavioral trap: once a version is activated with tracking on, the database outranks metadata.json, so editing the file and deploying no longer changes what is served. Decide explicitly which of those is your source of truth before launch, not after.

How to Pitch It (Stakeholders)

For executives (60 seconds): Prompt changes are product changes, and today they ship with no version history, no rollback, and no way to tell whether the new prompt was better. This is a free, MIT-licensed Laravel package that turns prompts into reviewed, versioned files with a one-command rollback and a record of which version served which traffic. Cost is one composer require and one migration; there is no vendor, no contract, and no lock-in — the prompts stay as plain Markdown in our repo, so walking away costs us nothing. The trade-off is that prompts remain engineer-owned and experimentation is basic (run a version for a window, compare results). For our current AI scope that is the right trade.

For engineering: It formalizes what you are probably already doing ad hoc. Prompts become resources/prompts/<name>/vN/*.md with {{ $variable }} interpolation, Artisan commands for create/list/test/diff/activate, and Deck::get()->toMessages() returning an API-ready messages array. If you are on the Laravel AI SDK, HasPromptTemplate removes boilerplate instructions() methods. Known costs: pin the version (pre-1.0, active namespace rename from veeqtoh/prompt-deck to promptphp/deck at 0.4.0, so check your imports), tracking is now off by default and needs its migration published if you want it, and DB-backed activation state can diverge from metadata.json — pick one as authoritative and document it.

For product/ops: You get a rollback button and a version history with descriptions and diffs. You do not get a self-serve editor — prompt changes still go through a PR. Plan your request queue accordingly, and set expectations that A/B results are comparative-over-time, not simultaneous.