browser/openspec/changes/architecture-delivery-stream/design.md

Context

bootstrap-game-server-platform-architecture established the repository roots, ownership boundaries, and architecture contracts, but it intentionally did not build the full platform. The remaining work touches all four roots and needs to be delivered as a sequence of small OpenSpec changes so each implementation chat has a narrow scope, concrete verification commands, and clear handoff to the next change.

The delivery stream is a process and governance layer. It does not replace the bootstrap specs. Each follow-up change must treat the bootstrap change and any archived specs as the baseline.

Goals / Non-Goals

Goals:

• Define one ordered backlog for the architecture implementation.
• Keep each OpenSpec change small enough for one focused implementation chat.
• Require a standard handoff block for every concrete change so the user can open a new chat and paste a precise implementation prompt.
• Require closing evidence before the next OpenSpec is created or implemented.
• Cover platform/, run/, platform_web/, and plugins/ without mixing ownership boundaries.

Non-Goals:

• Do not add billing, cloud host sales, provider marketplace, or agent-provider workflows.
• Do not implement product code inside this stream change.
• Do not require automated creation or closing of chats; chat boundaries are user-operated.
• Do not redefine product scope already covered by the bootstrap architecture.

Decisions

Decision 1: Use a serial backlog, not parallel feature branches

Only one concrete implementation OpenSpec should be active at a time unless the user explicitly pauses or reprioritizes the stream. This keeps validation evidence simple and prevents later changes from depending on unverified assumptions.

Alternative considered: create all detailed OpenSpecs at once. Rejected because later specs would likely become stale after the first implementation changes discover concrete package, runtime, and data model constraints.

Decision 2: Start with development runtime baseline

The first concrete implementation change is establish-development-runtime-baseline. It defines the executable skeleton, package managers, local commands, and test/verification entry points before any business capability is implemented.

Alternative considered: start with platform domain APIs. Rejected because there is not yet a runnable backend or frontend baseline to attach tests and browser walkthroughs to.

Decision 3: Split the stream by dependency, not by team label

Backlog items may touch multiple roots when the contract is cross-cutting, but each item must name its primary root ownership and forbid casual cross-root imports. Shared contracts must be generated, copied through explicit contract packages, or duplicated as documented API contracts until generation exists.

Alternative considered: one backlog per root. Rejected because platform-run protocols, plugin bridge contracts, and frontend API clients require coordinated changes.

Decision 4: Every concrete change gets a handoff prompt

Each concrete OpenSpec must end with a short implementation handoff containing the change name, exact target, required reads, verification commands, and stopping conditions. The prompt is the practical bridge between chats.

Alternative considered: rely on OpenSpec files alone. Rejected because a new chat needs a compact instruction that prevents it from reopening already-settled scope.

Decision 5: Closing evidence gates progression

A change is not considered closed until its tasks are checked with evidence. The minimum evidence is scripts/check-structure.sh plus openspec validate <change> --strict; frontend page changes also require a browser walkthrough, and executable code changes require the relevant tests/builds documented by that change.

Alternative considered: create the next change after implementation edits are made. Rejected because unverified work compounds defects into downstream specs.

Initial Delivery Queue

Order	Change	Primary Roots	Purpose
0	bootstrap-game-server-platform-architecture	all	Completed architecture baseline and repository skeleton.
1	establish-development-runtime-baseline	all	Add runnable project/tooling baselines and common verification commands.
2	implement-platform-core-domain	platform/	Add core domain, DTO, model, repository, service, validator, and route contracts for users, plugins, server instances, AI providers, jobs, artifacts, logs, and audit.
3	implement-platform-api-surface	platform/	Add HTTP API handlers, validation, error envelopes, and initial persistence wiring for the core resources.
4	implement-ai-provider-management	platform/, platform_web/	Store AI provider metadata safely, redact secrets, and expose first-party management APIs and UI.
5	implement-run-control-registration	run/, platform/	Add run hello, heartbeat, capability, version, and capacity registration.
6	implement-run-job-channel	run/, platform/	Add job claim, ack, progress, result, cancel, reconcile, and idempotent local journal behavior.
7	implement-log-ingest-pipeline	run/, platform/	Add local spool, compressed batch upload, sequence ack, retry, and platform log query metadata.
8	implement-artifact-transfer-channel	run/, platform/	Add chunked, resumable, checksummed, throttled artifact upload/download.
9	implement-plugin-registry-and-manifest-validation	plugins/, platform/	Validate plugin manifests, register installed game management plugins, and expose marketplace metadata.
10	implement-plugin-bridge-and-sdk	plugins/, platform_web/, platform/	Add safe plugin page bridge, SDK types, scoped platform abilities, and no raw key/run/path exposure.
11	implement-platform-web-console-shell	platform_web/	Add frontend app shell, routes, API client structure, theme tokens, and required first-party pages.
12	implement-server-management-workflows	all	Create server instances from plugins, dispatch lifecycle jobs to run, and show job/log/artifact state.
13	implement-dev-game-plugin-proof	plugins/, all	Add one development game management plugin proving multi-instance creation, logs, files, jobs, and AI assistance.
14	implement-end-to-end-acceptance-suite	all	Add cross-root acceptance checks and browser walkthrough coverage for the first complete workflow.

Risks / Trade-offs

• [Risk] The backlog may need to change after tooling decisions are implemented. Mitigation: update this stream through a new OpenSpec change if ordering or scope materially changes.
• [Risk] A change may grow too large for one chat. Mitigation: split it before implementation and keep the original change as a coordination parent only if needed.
• [Risk] Generated contracts may not exist early. Mitigation: use explicit copied contract files with documented ownership until generation is introduced by its own OpenSpec.
• [Risk] Chat handoff can omit important context. Mitigation: require each handoff to name exact files to read and exact commands to run.

Migration Plan

1. Validate this stream change and use it as the current implementation queue.
2. Create establish-development-runtime-baseline as the first concrete OpenSpec.
3. In a new chat, implement only that change, run its verification, and check its tasks with evidence.
4. After closure, create or refine the next concrete OpenSpec from the queue.

Open Questions

• Whether the initial persistence backend should be SQLite-first for local development or Postgres-first for production parity remains for the platform API changes.
• Whether log body storage starts as local compressed segments or a query engine adapter remains for the log ingest change.
• Whether run job transport starts as long polling or streaming remains for the run job channel change.