# VCC Plus development workflow ## Required installed app Use `/Applications/VCC Plus.app`, **version 3.6.1, build 54**. Brian requested the final Quadrapassel test after Core installed it on November 11, 2026. Earlier build53 checks remain historical. 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](https://www.6809.org.uk/xroar/doc/xroar.shtml) for CoCo 2 validation and [Chris Lomont's CoCo hardware reference](https://www.lomont.org/software/misc/coco/Lomont_CoCoHardware.pdf) 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.