Files
Quadrapassel/docs/VCC_PLUS_WORKFLOW.md
T
Brian Holman d412e35c4e Implement CoCo 3 Quadrapassel and deliver build 01
Add gameplay, keyboard/joystick controls, disk-backed high scores and settings,
standard CMOC effects, and the approved C graphics renderer. Include the clearer
attributed font, title/credits updates, source-verified Modern and Classic (40.2)
scoring, meaningful regression fixtures, and recorded guest validation.

Deliver QUADPSL01.DSK with fresh high scores. Retain source, licenses and selected
guest evidence; exclude personal disks, private connections and build scratch.

Host rules/input/persistence/video checks and memory guards pass. Official
512 KB playtests pass the recorded checks; actual 128 KB/physical joystick
qualification and the normal-window buzzing retest remain pending.
2026-11-11 03:14:14 -07:00

9.0 KiB

VCC Plus development workflow

Required installed app

Use /Applications/VCC Plus.app, version 3.6.0, build 51, explicitly approved by Brian on November 11, 2026 for reconnection and isolated build/playtest. The installed Info.plist was verified. Earlier build-48 evidence remains historical. Verify again at implementation start. If the app differs, report it and wait for Brian to approve a different version. Do not downgrade, overwrite, or build a replacement app.

Use the official app's supported MCP sharing/export flow for the Quadrapassel project. No custom VCC Plus executable, private helper protocol, substitute MCP server, injected code, private endpoints or emulator modifications are authorized. The fact that a binary or source checkout exists on the machine is not permission to use it. This game is a client of the installed product.

Reference access through MCP

  1. Discover the tools advertised by the intended connection. Query capabilities and confirm the selected project/root, files, revision, approved build recipe, available build configurations and runtime controls.
  2. Use search_help and read_topic for the installed manuals and API reference. Suggested first queries: hscreen hset palette, joystick, keyboard, CMOC graphics memory, sound, disk project DOS and MCP playtest. Search/read may need separate short queries; follow the returned schema.
  3. Use the advertised historical archive search and document-reading tools when present. Consult relevant CMOC, CoCo graphics, keyboard, joystick and disk references. Read cited sections rather than relying on search snippets.
  4. Record the actual tool names and document/topic identities in the implementation notes. Tool availability may differ from this planning-time inventory.

Planning-time limitation: the available older project-specific connection returned host_unavailable. Its advertised documentation tools were search_help/read_topic; a live build-48 archive search was not verified during specification preparation. This is not a claim that build 48 lacks archive support. The implementation chat must discover and use the correct official connection. Report unavailable access and ask for that connection to be enabled if necessary; do not request emulator features or create a replacement integration to fill a gap.

Allowed fallback references include the public manuals in /Applications/VCC Plus.app/Contents/Resources/ManualLibrary, public headers in /Applications/VCC Plus.app/Contents/Resources/Toolchain/share/cmoc/include, and public examples shipped in the official app. Read public API contracts, not private headers or library implementation files. The installed public manual's programming-in-c/examples/beacon.c demonstrates hscreen, hset, palette and standard BGraph use; it is a reference, not permission to copy raw register access from an example without the exception review.

Pierre's programs and other examples under /Users/bholman/Development/Personal/VCC/CMOC/Repositories/ are also permitted read-only references. Inspect the selected example's license before reusing code. Search within that folder or an individual example, not the parent VCC directory. Do not read the Mac Quadrapassel implementation or private VCC Plus material.

Useful public references include the XRoar author's manual for CoCo 2 validation and Chris Lomont's CoCo hardware reference when a public hardware description is needed. Reading these is allowed; implementing raw hardware access still requires the approval process in AGENTS.md.

Standard APIs before optimization

Begin with the public CMOC coco.h interface:

Need Initial public API candidates
CoCo 3 display hscreen, hset, palette, paletteRGB, rgb / cmp
CoCo 2 display pmode, pcls, screen; documented standard graphics-library routines
Keyboard isKeyPressed, inkey, documented keyboard helpers
Joystick readJoystickPositions, readJoystickButtons, named port/button constants
Timing/speed getTimer, setTimer, setHighSpeed with their documented contracts
Sound sound or documented standard CMOC sound-library APIs
Disk Documented standard CMOC disk/file libraries selected through Project Settings

Check actual header/manual contracts and return codes. Do not infer exact behavior from names. In particular, the public coco.h joystick button prose and its named bit constants have inconsistent ordering in the inspected header; confirm both physical ports in the API probe instead of hardcoding a guess.

hscreen/hset use BASIC's graphics workspace. They are distinct from the VCC-specific vcc/gime.h helper whose documented contract requires at least 512 KB. The latter is not the baseline and would need exception review. Do not infer that 128 KB needs a custom renderer just because that helper needs more RAM.

Compose ordinary game rendering with standard APIs first, update changed cells, and measure. Direct framebuffer access, custom register code, assembly or a nonstandard extension remains gated even when an example contains it. Prefer a manual machine/target choice to an unapproved raw detection routine.

Project, build and playtest sequence

Create the game project using the installed C Development workflow and its public project template. Keep source and settings in this repository. The official app can create a standard disk-project recipe; keep that recipe and its resource/DOS configuration reproducible. Do not add game code to the emulator repository.

The previously advertised MCP pattern is listed below as a discovery aid, not a promise that every build-48 connection has the identical tool set:

  1. get_capabilities and project input/file readers identify the shared project.
  2. Make normal repository edits or use the advertised reviewed edit proposal flow. New files, assembly (only after approval), or Make changes must use a supported project update/review path. Refresh and inspect the resulting revision.
  3. build_project takes the current project/revision, an advertised build or disk action and declared configuration. Poll get_build; inspect the build log. Do not invent target names or bypass recipe review.
  4. Start an isolated playtest from the returned artifact. Poll its run status. Match source revision and artifact identity before accepting a result.
  5. Exercise keyboard input, capture the guest screen/graphics and capture bounded guest audio with the advertised tools. Use documented guest debugger inspection when useful. Do not reach into emulator implementation state.
  6. Stop the owned run through the supported tool. Preserve writable disk results and useful evidence. Do not operate another project's connector or live session.

A CLI invocation of the installed bundled toolchain can supplement diagnosis if documented, but it is not a substitute for building and running through the official VCC Plus workflow. Do not silently substitute Homebrew or another compiler.

Memory and input qualification

The planning-time start_playtest contract described a fixed 512 KB isolated machine with a 6809/6309 choice. Recheck build 48's actual advertised schema. If it still cannot select 128 KB, test that memory size through the official app's normal Machine Settings interface in an isolated user-approved session. Its installed user manual lists 128 KB as a supported memory selection. A 512 KB playtest alone does not establish 128 KB compatibility.

No joystick injection tool was present in the planning-time inventory. Check the actual build-48 connection. Use normal supported app input or Brian's joystick / XRoar testing where MCP cannot supply it. Keyboard events are not evidence that analog sampling, dead zones or both joystick ports work.

Before desktop pointer/keyboard automation, obtain Brian's current idle-desktop grant. Use only supported isolation and preserve active media/settings. Do not launch another ordinary instance that competes for the same saved state. If a safe isolation path is unavailable, continue independent work and request a specific manual check rather than changing the installed app.

For XRoar, give Brian a pristine DSK copy, exact machine/RAM/clock/ROM requirements, loading steps, controls, expected results and an evidence checklist. Do not redistribute private ROMs. Separate user-confirmed CoCo 2 results from VCC Plus CoCo 3 compatibility runs. Keep screenshots limited to the guest display.

Numbered game delivery

Brian's latest November 11 convention is QUADPSLxx.DSK, beginning with 01, with empty high scores/default preferences for each new delivery. Keep the official recipe and MCP artifact at its existing staging name, Quadrapassel.DSK. Verify no QPSAVE data is present, copy to a new numbered filename without overwriting, compare hashes, and record it in BUILDS.md. Old personal disks remain untouched; automatic score migration is no longer part of delivery.