Scenario Core Laravel Package

Product Decisions This Supports

• Build vs. buy for workflow/business-rule orchestration. scenario-core is an abstraction layer for defining and executing scenarios (conditions → transitions → actions) rather than a finished product feature. That makes it a candidate to replace a bespoke internal state-machine/rule-engine effort, or to serve as the skeleton we build on. The decision is less "adopt this library" and more "adopt this vocabulary and core loop, then own the domain layer."
• Where scenario logic lives. It supports a roadmap decision we will face repeatedly: do approval chains, onboarding gates, pricing rules, and order-lifecycle transitions live as scattered if statements in controllers/jobs, or as declarative scenario definitions in one place? This package points at the latter, which is a precondition for ever exposing those flows to ops/config rather than shipping code.
• Feature candidates it de-risks. Multi-step conditional journeys (KYC/onboarding gating, checkout/eligibility rules, subscription state transitions, internal approval workflows, feature gating by account state). If two or more of these are on the roadmap, a shared scenario core avoids building the same guard-and-transition logic three times with three different bugs.
• Auditability and explainability roadmap. Scenario frameworks are usually the natural seam for "why did this user/order end up in this state?" If support burden or compliance asks that question, a scenario core is where the answer gets recorded. Worth flagging as a design intent now, not a promise.
• Extensibility strategy. A "core" package implies we'd supply domain packages on top. That's a real product decision: one internal platform package consumed by several squads, versus each squad rolling its own. This is the cheap way to test whether the shared-platform model earns its keep.

When to Consider This Package

Consider it when most of the following hold:

• We are on PHP/Laravel and already have multi-step, condition-heavy flows that are drifting into duplicated conditional logic across services.
• We are pre-scale on this concern — a spike or an internal tool — and want a small, BSD-3-licensed core we can read end-to-end and vendor into our repo if needed. Permissive license keeps the fork-and-own option open.
• The team is comfortable treating this as a starting point, not a dependency with a support contract. Expect to write our own tests, docs, and domain adapters.
• We want the abstraction (scenario/state vocabulary) more than we want the implementation, and we're prepared to swap the implementation later behind our own interface.
• Someone owns it internally. The bus factor here is effectively one maintainer.

Look elsewhere when any of these are true:

• We need vendor SLA, security response commitments, or a documented public API with a deprecation policy. Two stars, zero dependents, and a single recent release are diligence signals, not disqualifiers — but they mean no ecosystem safety net.
• The workflow is high-volume, long-running, or needs durable execution, retries, and observability across services. That's Temporal/Cadence or queue-based territory, not a core abstraction in one app.
• The flows are simple (one or two states). Plain Laravel events, policies, or Illuminate\Pipeline will be cheaper to read and cheaper to hand over.
• We need an admin UI for non-engineers to author scenarios on day one — this gives us the core, not the product.
• The team would be uncomfortable reading framework internals to debug. Low-adoption packages mean we are the documentation.

Recommended posture if we proceed: timeboxed spike (1–2 weeks), wrapped behind our own ScenarioRunner interface, with an explicit exit plan to Symfony Workflow or an in-house implementation. Success criteria up front: does it remove duplicated conditional logic in ≥2 real flows, and can a mid-level engineer change a flow without reading the package source?

How to Pitch It (Stakeholders)

For executives — one paragraph. We have repeated conditional-logic problems (onboarding gates, approval chains, eligibility rules) that we currently rebuild per feature. A small, permissively licensed PHP package, stateforge/scenario-core, gives us a standard way to express those flows and a single place to change and explain them. The financial exposure is near zero — BSD-3 license, no paid tier, no data leaving our systems — and the real cost is a short engineering spike. The real risk is maturity: it has two GitHub stars and no downstream users, so we would own it, not depend on it. Recommendation: fund a two-week spike behind our own interface, measure whether it removes duplicated logic in two live flows, and keep a documented fallback. Treat this as a cheap experiment in shared platform thinking, not a vendor commitment.

For engineering. We'd consume the core as an internal library, pin the version, vendor it if we need to patch, and never call it directly from controllers — everything goes through our own thin interface so the implementation is replaceable. We write the tests and the docs. If the spike doesn't pay for itself in two flows, we delete it and keep the vocabulary.