Add Quadrapassel CoCo specification and reviewed implementation workflow

This commit is contained in:
Brian Holman committed 2026-11-10 15:15:49 -07:00
commit 8a4b44bc73
13 files changed
+2250

No files matched your search

+82
View File
@@ -0,0 +1,82 @@
# Implementation stages and review checkpoints
Status at handoff: **planning documents only**. No game probe, executable or disk
has been built, and no CoCo compatibility check has passed yet. The implementation
prompt is for a separate VCC Plus project chat using ChatGPT-6.1 Sol with High
reasoning, after Brian reviews the prompt.
## Stage 1 — establish the supported API path
- Verify official 3.5.5 build 48 and the correct Quadrapassel MCP connection.
- Read manuals/API/archive material through the advertised tools; record access.
- Create a minimal standard CMOC project in this repo and reproduce its disk build.
- Prove seven-color graphics, text, moving/erased blocks, keyboard, both joystick
ports, timing, short sound, disk access and return to text using standard APIs.
- Run on actual 128 KB configuration; measure draw time and input response.
- Produce an initial linked memory budget and capture the actual guest display.
This stage decides whether standard APIs satisfy the target. It does not presume
custom graphics code. If an API gap or measured cost requires an exception,
request the review described below before implementing it.
## Stage 2 — playable shared rules engine
Implement the 10 by 20 board, exact piece definitions, spawn/collision, rotation
and kicks, gravity and controls, simultaneous clears, scoring and levels, next,
hold, shadow and game over. Use small deterministic fixtures from this repo.
Add normal weighted selection, seed repeatability and the optional difficult-piece
mode. Test invalid states and score widths appropriate to CMOC.
Keep rules independent of rendering and input sampling so CoCo 2 and CoCo 3 share
them. Host tests may complement guest tests; they do not replace a real CMOC build.
## Stage 3 — complete player experience
Add the title treatment, menus, all-keyboard and all-joystick operation, settings,
styles, sound, credits, and bounded persistent scores with the reset semantics
in the specification. Test sound-enabled latency, pause transitions, read-only
media and recoverable writes. Refine within standard APIs before considering
approved low-level alternatives.
## Stage 4 — CoCo 2 and single-disk packaging
Add the lower-color display using standard APIs with patterns/clear outlines.
Keep all game rules and essential controls. Package the supported launcher and
both targets (if separate executables) on one disk. Verify DOS and manual boot,
safe machine selection, free disk space and score saving.
Provide the exact CoCo 2 test checklist to Brian for XRoar, preserving pending
status until results return. Verify baseline behavior on a 512 KB CoCo 3 too;
do not add an enhanced variant merely to fill a third tier.
## Stage 5 — acceptance and handoff
Run the specification's relevant acceptance cases with version/configuration
records. Add selected actual guest screenshots to `docs/screenshots/`, the built
disk at `Quadrapassel.DSK`, source/build settings, loading instructions, controls,
credits and a compatibility table. Record measured memory/disk use and timing.
Do not mark the project complete while required target checks remain pending.
Keep implementation commits/pushes within Brian's authorization. Initial planning
document publication does not authorize a public release or visibility change.
## Required exception proposal
Before any assembly or implementation outside standard CMOC APIs, send a concise
proposal to the coordinating chat **Deploy VCC Plus Gitea** for Brian and that chat
to review. This is a user-requested permission step, not a routine stage gate.
Use this structure:
1. **Need:** player-visible problem and affected target.
2. **Standard API evidence:** functions/configuration tried, reproducible check,
measurement or documented missing capability.
3. **Alternatives:** options that remain within standard APIs and their tradeoffs.
4. **Proposed exception:** exact routine/API/assembly, files, size and memory effects.
5. **Validation:** correctness, responsiveness, both target machines, restoration
of display/input/disk state, and fallback.
6. **Decision requested:** smallest useful approval scope.
Wait for an explicit decision from Brian or a decision relayed after their joint
review. Continue unaffected work. Record approvals in `docs/DECISIONS.md` when
there is an approved exception; do not create a fictional approval record.