first commit
This commit is contained in:
npc0-hue
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-07
|
||||
@@ -0,0 +1,82 @@
|
||||
## Context
|
||||
|
||||
The repository already has a completed baseline architecture stream plus many completed implementation changes. The delivery plan is now out of date because it still calls `implement-server-management-workflows` active, while `openspec list` shows it as complete. The only currently open implementation item is `fix-env-profile-settings`, where the remaining task is browser walkthrough evidence for the personal settings page.
|
||||
|
||||
The user wants a workflow that can be continued in fresh chats: run the plan, create one OpenSpec, implement or close it, then open the next chat and generate or execute the next OpenSpec. The queue must be practical for this repository and must keep the platform focused on game server management, not billing, cloud sales, or unrelated SaaS features.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Keep a single source of truth for the ordered architecture delivery queue.
|
||||
- Make the next step obvious for a new chat without requiring a full rediscovery pass.
|
||||
- Ensure each fresh chat creates or implements exactly one concrete OpenSpec unless the user explicitly asks to continue.
|
||||
- Require verification evidence before tasks are marked complete.
|
||||
- Prioritize proving real, end-to-end behavior over adding more demo-only surfaces.
|
||||
- Preserve the existing ownership boundaries between `platform/`, `run/`, `platform_web/`, and `plugins/`.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- This change does not implement product features.
|
||||
- This change does not redesign the interface directly.
|
||||
- This change does not create billing, host sales, cloud-provider, or agent-provider workflows.
|
||||
- This change does not allow browser or game management plugins to connect directly to run.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: Use the existing architecture stream as the queue record
|
||||
|
||||
The canonical queue will remain under `openspec/changes/architecture-delivery-stream/` because that location already contains `delivery-plan.md`, the handoff template, and the architecture workflow spec.
|
||||
|
||||
Alternative considered: create a new top-level `openspec/delivery/` folder. That would be cleaner long-term, but it would split the current history and require extra structural rules before the workflow itself is corrected.
|
||||
|
||||
### Decision 2: Add a next-change pointer for fresh chats
|
||||
|
||||
The refreshed stream will add `openspec/changes/architecture-delivery-stream/NEXT_CHANGE.md`. It will contain the current state guard, next change name, exact creation prompt, exact implementation prompt, and stop condition. A fresh chat can read that file first and continue without scanning every historical change.
|
||||
|
||||
Alternative considered: keep only the queue table. A table is useful for planning, but it is too easy for a new chat to pick the wrong pending item when one change is blocked or partially closed.
|
||||
|
||||
### Decision 3: Separate generator chats from implementation chats
|
||||
|
||||
A generator chat may create exactly one new OpenSpec change and validate its artifacts. It must not implement that change unless the user explicitly asks. An implementation chat may implement exactly one concrete change and then update the queue pointer when complete.
|
||||
|
||||
Alternative considered: let one chat generate and implement many changes. That is faster in the short term but recreates the current problem: broad scope, stale status, and unclear closure evidence.
|
||||
|
||||
### Decision 4: Treat incomplete verification as an active guard
|
||||
|
||||
The queue must not advance past `fix-env-profile-settings` until its browser walkthrough task is closed or explicitly marked blocked with evidence. This avoids pretending the platform is accepted when the UI was not walked through.
|
||||
|
||||
Alternative considered: ignore the open task because the code and CLI checks passed. That would violate the repository verification rules for frontend changes.
|
||||
|
||||
### Decision 5: Seed the next queue with proof-oriented OpenSpecs
|
||||
|
||||
The next changes should first prove current behavior, then close real gaps. The seed queue is:
|
||||
|
||||
1. `verify-current-platform-e2e-baseline`: browser/API/run walkthrough proving which required platform flows work and which are still demo-only.
|
||||
2. `implement-real-game-plugin-lifecycle-proof`: make a local game management plugin create and manage multiple server instances through platform-mediated actions.
|
||||
3. `harden-log-artifact-channel-isolation`: prove log ingest remains durable while file/artifact operations are active.
|
||||
4. `implement-local-debug-workspace`: make local debugging easy for platform, run, frontend, and game management plugins.
|
||||
5. `implement-browser-acceptance-suite`: automate browser walkthroughs for the required first-party areas.
|
||||
6. `polish-platform-interaction-design`: address interface dissatisfaction through concrete interaction proposals and browser-reviewed improvements aligned with the existing visual direction.
|
||||
|
||||
The first generated change should be `verify-current-platform-e2e-baseline` because the user is questioning whether the project is still only a demo. Implementation should be guided by observed behavior, not assumptions.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- Stale queue risk -> Mitigation: require every completed implementation chat to update `NEXT_CHANGE.md` and `delivery-plan.md` before closing.
|
||||
- Oversized change risk -> Mitigation: split a pending item before product code is written if it cannot be completed in one focused chat.
|
||||
- False completion risk -> Mitigation: keep task boxes unchecked until commands, browser walkthrough notes, screenshots, or test results are recorded.
|
||||
- UI churn risk -> Mitigation: put interface dissatisfaction into a specific design OpenSpec instead of mixing visual redesign into backend or protocol work.
|
||||
- Scope creep risk -> Mitigation: every handoff repeats the platform boundaries and excludes billing, cloud sales, unrelated marketplace features, raw AI key exposure, and direct plugin/run access.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Update `architecture-delivery-stream/delivery-plan.md` to reflect the actual completed and active states.
|
||||
2. Add `NEXT_CHANGE.md` with the immediate guard and next generated OpenSpec prompt.
|
||||
3. Validate this planning change with `openspec validate refresh-architecture-delivery-stream --strict`.
|
||||
4. Run `scripts/check-structure.sh` to ensure repository structure expectations still pass.
|
||||
5. In the next fresh chat, finish `fix-env-profile-settings` browser walkthrough if still open; then generate `verify-current-platform-e2e-baseline`.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- None for this planning change. The detailed product gaps must be discovered by the first proof-oriented OpenSpec.
|
||||
@@ -0,0 +1,28 @@
|
||||
## Why
|
||||
|
||||
The existing architecture delivery stream is stale: it still points at `implement-server-management-workflows` as active even though the repository now contains many completed changes, while `fix-env-profile-settings` remains open only because browser walkthrough evidence is missing. The project also needs a repeatable "one OpenSpec per fresh chat" queue so future work stops feeling like a demo and advances through verifiable platform capabilities instead of broad, mixed-scope conversations.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Refresh the architecture delivery stream so it reflects the current OpenSpec state and no longer names completed work as active.
|
||||
- Add a serial OpenSpec delivery queue that records the next concrete change to create, the prompt to use in a fresh chat, and the stopping rule for that chat.
|
||||
- Add a next-change pointer so a new chat can continue from the queue without rediscovering the whole plan.
|
||||
- Define a generator protocol: finish or unblock the current active change, create exactly one next OpenSpec, validate it, update the pointer, then stop.
|
||||
- Seed the queue with product-readiness OpenSpecs focused on proving and completing real platform behavior: server creation, run-mediated operations, durable logs, artifact transfer, plugin marketplace, user management, AI provider settings, local debugging, and browser acceptance.
|
||||
- Preserve the platform scope: no billing, cloud host sales, unrelated SaaS marketplace features, raw AI key exposure, or direct plugin/browser access to run.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `serial-openspec-delivery-queue`: Defines the queue, next-change pointer, generator rules, handoff prompts, and verification gates for creating one future OpenSpec at a time.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- None.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affects OpenSpec planning files under `openspec/changes/architecture-delivery-stream/`.
|
||||
- Creates planning artifacts only; this change does not implement platform, run, frontend, or plugin product code.
|
||||
- Future generated changes will touch `platform/`, `run/`, `platform_web/`, and `plugins/` according to their own OpenSpec scopes and verification gates.
|
||||
+71
@@ -0,0 +1,71 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Serial OpenSpec Queue
|
||||
The repository SHALL maintain a serial OpenSpec queue that identifies the current guard, the next change to create or implement, the affected roots, and the verification gate for each item.
|
||||
|
||||
#### Scenario: Fresh chat needs the next item
|
||||
- **WHEN** a contributor opens a fresh chat to continue the architecture stream
|
||||
- **THEN** the queue identifies the single next OpenSpec action and the files that must be read first
|
||||
|
||||
#### Scenario: Queue has stale completed work
|
||||
- **WHEN** an OpenSpec change is marked complete by `openspec list`
|
||||
- **THEN** the queue no longer lists that change as active
|
||||
|
||||
### Requirement: Next Change Pointer
|
||||
The repository SHALL maintain a next-change pointer document that contains the current guard condition, next change name, creation prompt, implementation prompt, and stop condition for the next fresh chat.
|
||||
|
||||
#### Scenario: Generator chat starts
|
||||
- **WHEN** the next-change pointer says the next action is to create a change
|
||||
- **THEN** the chat creates exactly one OpenSpec change, validates its artifacts, updates the pointer, and stops
|
||||
|
||||
#### Scenario: Implementation chat starts
|
||||
- **WHEN** the next-change pointer says the next action is to implement a change
|
||||
- **THEN** the chat implements only that change and does not start the next queue item unless the user explicitly asks
|
||||
|
||||
### Requirement: Active Guard Before Advancement
|
||||
The queue SHALL block creation of a new concrete OpenSpec while an existing active change has unchecked required tasks or missing verification evidence.
|
||||
|
||||
#### Scenario: Frontend walkthrough evidence is missing
|
||||
- **WHEN** `fix-env-profile-settings` still has an unchecked browser walkthrough task
|
||||
- **THEN** the queue requires closing or explicitly blocking that task before generating the next concrete OpenSpec
|
||||
|
||||
#### Scenario: User explicitly reprioritizes
|
||||
- **WHEN** the user asks to skip or reprioritize the active guard
|
||||
- **THEN** the queue records the reason and updates the pointer before creating a different next OpenSpec
|
||||
|
||||
### Requirement: Proof-Oriented Backlog
|
||||
The queue SHALL prioritize proof-oriented changes that verify real game server management behavior before adding broad new product scope.
|
||||
|
||||
#### Scenario: User says the project feels like a demo
|
||||
- **WHEN** the next concrete OpenSpec is generated after current guards are closed
|
||||
- **THEN** the first generated change focuses on end-to-end baseline verification across platform, run, frontend, and game management plugins
|
||||
|
||||
#### Scenario: A proof change finds missing behavior
|
||||
- **WHEN** a proof-oriented change discovers a required flow is demo-only or broken
|
||||
- **THEN** the queue records the follow-up implementation OpenSpec needed to close that gap
|
||||
|
||||
### Requirement: Channel and Scope Boundaries
|
||||
Every queued OpenSpec SHALL preserve the platform channel boundaries and product scope boundaries from `AGENTS.md`.
|
||||
|
||||
#### Scenario: Plugin needs to operate files or configs
|
||||
- **WHEN** a game management plugin needs file, config, log, or run operation capability
|
||||
- **THEN** the OpenSpec routes the capability through platform-mediated contracts instead of direct browser/plugin access to run
|
||||
|
||||
#### Scenario: Logs and artifacts are both active
|
||||
- **WHEN** a queued change touches log ingest or artifact transfer
|
||||
- **THEN** the OpenSpec includes verification that file/artifact transfer does not block log ingest, control heartbeat, job ack, or job result delivery
|
||||
|
||||
#### Scenario: Unrelated SaaS scope appears
|
||||
- **WHEN** a queued change introduces billing, cloud host sales, agent-provider workflows, or unrelated marketplace behavior
|
||||
- **THEN** the change is considered out of scope unless a future user-approved OpenSpec explicitly requires it
|
||||
|
||||
### Requirement: Interface Satisfaction Handoff
|
||||
The queue SHALL include a dedicated path for interface dissatisfaction that turns subjective UI feedback into a concrete interaction-design OpenSpec.
|
||||
|
||||
#### Scenario: User dislikes an interface
|
||||
- **WHEN** the user says a page or flow is unsatisfactory
|
||||
- **THEN** the queue uses a design-change prompt that asks for target workflows, pain points, reference interactions, and browser acceptance criteria before implementation
|
||||
|
||||
#### Scenario: Interface work is implemented
|
||||
- **WHEN** a UI or interaction change touches `platform_web`
|
||||
- **THEN** browser walkthrough evidence is required before the tasks can be marked complete
|
||||
@@ -0,0 +1,28 @@
|
||||
## 1. Refresh Current Queue State
|
||||
|
||||
- [x] 1.1 Update `openspec/changes/architecture-delivery-stream/delivery-plan.md` so completed changes from `openspec list` are marked complete and no completed change remains active.
|
||||
- [x] 1.2 Record `fix-env-profile-settings` as the current guard until its browser walkthrough task is closed or explicitly blocked with evidence.
|
||||
- [x] 1.3 Replace the stale pending tail with the proof-oriented backlog from this design.
|
||||
|
||||
## 2. Add Next-Change Pointer
|
||||
|
||||
- [x] 2.1 Create `openspec/changes/architecture-delivery-stream/NEXT_CHANGE.md` with the current guard, next change name, creation prompt, implementation prompt, and stop condition.
|
||||
- [x] 2.2 Add a generator prompt that creates exactly one new OpenSpec and stops after strict validation.
|
||||
- [x] 2.3 Add an implementation prompt that implements exactly one OpenSpec and updates the queue before closing.
|
||||
|
||||
## 3. Seed The Next Concrete OpenSpec Prompt
|
||||
|
||||
- [x] 3.1 Record `verify-current-platform-e2e-baseline` as the first concrete OpenSpec to generate after the active guard is closed or explicitly reprioritized.
|
||||
- [x] 3.2 Ensure the generation prompt requires browser walkthrough, platform APIs, run-mediated server lifecycle, durable log history, artifact transfer, plugin marketplace, user management, and AI provider settings coverage.
|
||||
- [x] 3.3 Record that the next generator chat must validate `verify-current-platform-e2e-baseline` and update `NEXT_CHANGE.md` to point at implementing it.
|
||||
|
||||
## 4. Verification
|
||||
|
||||
- [x] 4.1 Run `openspec validate refresh-architecture-delivery-stream --strict`.
|
||||
- [x] 4.2 Run `scripts/check-structure.sh`.
|
||||
- [x] 4.3 Record verification evidence in this task file before marking this change complete.
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- 2026-07-08: `openspec validate refresh-architecture-delivery-stream --strict` passed. OpenSpec telemetry flush reported restricted DNS for `edge.openspec.dev`; the command still exited 0 and the change was valid.
|
||||
- 2026-07-08: `scripts/check-structure.sh` passed with `structure check passed`.
|
||||
Reference in New Issue
Block a user