Conduit Spotify Laravel Package

Product Decisions This Supports

• Agent / AI tool integration (primary unlock). --format=json plus --non-interactive turns each Spotify command into a machine-callable tool with a predictable envelope (timestamp, command, success, data). This is the difference between "a CLI a human types" and "a capability an LLM or workflow engine can invoke." Any roadmap item involving an assistant that controls playback now has a viable substrate without new service code.
• Automation and scripting use cases. Concrete near-term features: auto-pause on meeting start, "now playing" surfaced in a dashboard, Slack/status-bar presence, focus-mode playlists triggered by calendar or CI events. spotify:current returning track, playback.progress_ms, and device in one call makes polling cheap and avoids N+1 API calls in our own code.
• CI/automation reliability as a product requirement. Standardized exit codes and structured error responses mean scripts can branch on failure type instead of scraping stderr. Treat consistent exit codes as a contract we depend on, not a nicety.
• Platform decision: standardize the CLI pattern. The new HandlesSpotifyOutput trait is evidence Conduit is converging on a house CLI style (--format, --non-interactive, smart mode detection). If we own or plan to own other command packages, the PM decision is whether to adopt this pattern org-wide now — cheaper than retrofitting JSON output command-by-command later.
• Build vs. buy: adopt, but wrap. Recommendation is adopt rather than build a Spotify CLI ourselves, and rather than fork. Insert a thin internal adapter that maps the JSON envelope to our own schema so downstream features aren't welded to a third-party CLI's field names.
• Upgrade decision: take it. Explicitly backward compatible, no migration, additive flags only. Low-risk, high-leverage; there is no product reason to defer.
• Scope gap to note on the roadmap. Command surface is still narrow (current, play, pause). If the product story is "assistant controls music," expect next asks for search, queue, playlists, and device transfer — plan for those as incoming requirements rather than surprises.

When to Consider This Package

Adopt when:

• You are already on Conduit (or an Artisan-based CLI) and want Spotify control without standing up a service.
• Your consumer is a script, cron job, agent, or dashboard — i.e., you will actually use --format=json.
• Single-user / local-credential Spotify control is sufficient; you are not building multi-tenant OAuth.
• You can tolerate a fast-moving dependency and are willing to pin versions.

Look elsewhere or defer when:

• You need a web app, multi-user token storage, or per-end-user Spotify authorization — use the Spotify Web API via a dedicated SDK (e.g., a maintained PHP Spotify client) directly.
• You need rich library management (playlists, saved tracks, search, queue) today; this package does not cover it.
• You require a formally versioned, documented API contract with SLAs. The JSON shape here is new, undocumented as a schema, and has no schema_version field — treat it as unstable until that exists.
• Your automation path has no tolerance for interactive defaults. interactive remains the default format, so every scripted call must pass both --format=json and --non-interactive explicitly; anything that forgets can block on a prompt. Validate "smart mode detection" in a non-TTY context before relying on it.
• Test depth is a gating concern. 13 passing tests is thin for something becoming an automation dependency; ask what is covered versus mocked.

Open questions worth resolving before deep investment:

• Is the JSON envelope versioned or guaranteed? Request a schema_version field — cheap now, painful later.
• data.track.artist appears singular; confirm how multi-artist tracks, podcasts, and ad/local playback are represented before building UI on it.
• How are token refresh, expired credentials, and Spotify 429/rate-limit responses surfaced in the structured error shape? Standardized auth errors are mentioned; rate limiting is not.
• How tightly does this track "Conduit's evolving system"? Interface churn in the host CLI is a real upgrade cost.

How to Pitch It (Stakeholders)

To executives: A low-risk, no-migration upgrade to an existing internal Spotify CLI that converts it from a human-only tool into an automatable one. Every command can now emit structured JSON and run without prompts, which is the prerequisite for agent/AI integration. Zero breaking changes, existing workflows untouched, small engineering surface. The strategic value is optionality: it unlocks assistant-driven and automated music control without new services, and it establishes a reusable CLI convention we can apply to other tooling.

To engineering: Purely additive release — new --format=json|interactive and --non-interactive flags, a HandlesSpotifyOutput trait for consistent envelopes and error handling, and standardized exit codes across spotify:current, spotify:play, and spotify:pause. Backward compatible; 13/13 tests pass; Pint-formatted. Two asks before we build on it: (1) confirm non-TTY mode detection actually bypasses prompts, since interactive is still the default; (2) we wrap the output in a thin adapter rather than consuming its field names directly, so schema drift doesn't leak into our features. Also flag the narrow command surface — assume new commands will be requested.