Prompt Deck Laravel Package

Product Decisions This Supports

• Build vs. buy for prompt infrastructure. The recurring question "do we roll our own prompt config or adopt something?" now has a cheap middle option. Deck gives you versioned prompt directories, an Artisan authoring workflow, activation, and optional performance tracking without a SaaS vendor, a database-first CMS, or a homegrown config layer to maintain.
• Prompt iteration cadence as a product constraint. Because prompts live in resources/prompts and ship with the app, "tweak the support agent's tone" is a deploy, not a config change. That's a deliberate trade — git review, code review, and rollback for prompt content — and it should be an explicit roadmap decision, not an accident. If prompt changes must ship faster than your deploy cadence, this approach is the wrong primitive.
• Quality measurement per prompt version. Tracking (latency, token/cost, per-version outcomes) turns "the new prompt feels better" into a comparison you can put in a review. This supports concrete decisions: which model to run, whether a v2 is actually worth promoting, and whether prompt work is paying for itself.
• Rollout and rollback policy. prompt:activate + the active_version key gives you a one-command promote/rollback story for prompt changes. That's a genuine incident-response lever: when an agent starts behaving badly, you revert the prompt instead of hotfixing code.
• Sequential prompt testing, not full experimentation. Activation flips the served version for the whole environment, so the supported pattern is "run v1 for a week, run v2 for a week, compare tracked metrics." Treat it as cohort-over-time comparison, not a live traffic split. If a roadmap item requires a concurrent holdout with per-user bucketing, that is a build decision on top of this package, not a feature it hands you — confirm against the tracking docs before committing.
• Team workflow and ownership. Prompts become first-class, reviewable artifacts with make:prompt, prompt:list, and prompt:diff. This is what makes it viable to have more than one engineer touching agent behavior, and it makes prompt changes auditable in PR history.
• SDK consolidation. The HasPromptTemplate trait removes hand-written instructions() methods from agents, which reduces drift between "the prompt we think is running" and "the prompt that is running."

When to Consider This Package

Adopt when most of these are true:

• You have multiple prompts (roughly five or more) or multiple people editing them, and the current state is inline strings scattered across agent classes.
• Your team is Laravel-native and comfortable with Artisan and file-based configuration; nobody outside engineering needs to edit prompts.
• Prompt changes reasonably tracking your deploy pipeline is acceptable — a PR plus a release is a fine way to change a prompt.
• You want low lock-in: MIT, files on disk, no vendor, no data leaving your infrastructure. Exit cost is a copy of the prompts directory.
• You are on the Laravel AI SDK, or willing to use toMessages() as a plain array builder for any chat-completion API.
• You can absorb pre-1.0 churn: the package renamed itself (veeqtoh/prompt-deck → promptphp/deck, namespace Veeqtoh\PromptDeck → PromptPHP\Deck) at v0.4.0, and v0.4.6 was a substantial correctness release. Budget for reading upgrade guides on minor bumps and pinning versions.

Look elsewhere or build when:

• Non-engineers (support ops, marketing, domain experts) need to edit prompts. There is no admin UI, no database-backed editor, and no approval workflow. A hosted prompt platform or a small internal CMS is the right answer.
• You need true A/B experiments with traffic splitting, statistical significance, and per-user assignment.
• You need evaluation harnesses, guardrails, PII redaction, or output scoring. Deck versions and interpolates prompts; it does not evaluate them. Pair it with an eval/observability tool rather than expecting this to cover it.
• You need runtime-mutable prompts independent of deploys, multi-region config divergence, or per-tenant prompt variants. The active_version file is bootstrap state, and once tracking is enabled the database takes precedence — environment state and git state can diverge, which is a governance problem for regulated or multi-tenant products.
• You have one prompt and one engineer. Inline it and revisit later; the ceremony isn't worth it.

Adoption caveats worth a written note: install from the new package name (promptphp/deck), not the old one, and check config/deck.php rather than relying on defaults — tracking now defaults off after 0.4.6, so if you want the metrics that justify the adoption, set DECK_TRACKING_ENABLED=true and run the tracking migrations as a deliberate step. Also confirm your migration and config publishing steps in staging first: the 0.4.6 fixes describe exactly the failure mode (no such table on first Deck::get() in a production-shaped install) that erodes trust in a first rollout.

How to Pitch It (Stakeholders)

For executives: We are shipping AI features whose behavior is largely determined by prompt text, and today that text is buried in application code with no versioning, no review trail, and no way to tell whether a change made things better or worse. Deck is a small, MIT-licensed Laravel package that makes prompts versioned, reviewable files with a promote/rollback command and optional per-version performance tracking. The value is risk reduction and decision quality: every prompt change becomes a reviewable diff with a one-command rollback, and we can compare cost, latency, and quality between prompt versions instead of guessing. It is not a platform commitment — prompts stay as files in our repository and we can walk away at any time. Cost is integration time plus a small amount of ongoing upgrade maintenance; the package is pre-1.0 and recently renamed, so we should pin versions and plan for occasional upgrade work.

For engineering: Low-risk, Laravel-idiomatic addition. Prompts become files under resources/prompts managed by Artisan commands; the Deck facade renders them with {{ $variable }} interpolation and returns a ready-made messages array, with an optional trait that supplies instructions() for Laravel AI SDK agents. Tracking is opt-in and must degrade gracefully — verify in staging that a missing tracking table logs a warning rather than throwing, and confirm the database-vs-metadata.json precedence for active_version before enabling it in production, since that changes what "edit the file and deploy" means. Pin the version, read the 0.4.x upgrade guides, and treat the prompt directory as reviewable source of truth.

For the product team: Prompt changes will follow the release train unless we invest in something more. If sub-day prompt iteration or non-engineer editing is on the roadmap, flag it now — that's a different (larger) investment than this package represents.