We want to introduce a PI_EXPERIMENTAL environment variable that opts into unfinished or unbaked features while keeping main releasable by default.

Problem

We want main to stay releasable at all times, but we also need a way to test features with the team and, occasionally, external users before they are fully ready. Recent and upcoming examples include the project_trust workflow, pi.dev sign-in, and first-time setup changes.

Today these features either need to be kept out of main, merged only once they are already polished, or risk exposing incomplete UX to all users.

Proposal

Add PI_EXPERIMENTAL=1 as an explicit opt-in for experimental functionality. By default, Pi behaves as production-ready software. Experimental flows, prompts, commands, or UI should not appear unless the flag is set.

Experimental features should be guarded at product boundaries such as command registration, setup flow selection, auth provider availability, UI entry points, or workflow activation.

Implementation

Keep the implementation simple. Add one shared helper for checking PI_EXPERIMENTAL, use localized conditionals near feature entry points, avoid persistent config for experimental state, avoid migrations tied only to experimental behavior, and avoid public documentation until the feature graduates.

Guidelines

PI_EXPERIMENTAL is not a long-term feature flag system. It is a short-lived baking mechanism.

Experimental work should be small, isolated, easy to remove, owned by someone, tested for roughly one or two weeks, and then either shipped, revised, or deleted. If an experiment does not graduate quickly, the default should be to unship it rather than let stale experimental code accumulate.

This is not intended to provide gradual percentage rollouts, per-user targeting, remote feature flags, long-term compatibility guarantees, or a registry of dormant features.