Prepare public CoCo 3 documentation and portable VCC Plus workflow

This commit is contained in:
Brian Holman committed 2026-11-11 16:43:19 -07:00
1 parent e9574b6f0d
commit 4aa739780c
16 files changed
+572 -913

No files matched your search

+57 -114
View File
@@ -1,128 +1,71 @@
# Implementation prompt — for review before starting the new chat
# Develop an existing checkout with ChatGPT
Paste the following prompt into a **new chat within the existing VCC Plus
project** after Brian has reviewed it. This document does not start that chat.
You can study or change this game with the downloaded VCC Plus app, a local
checkout and a supported ChatGPT connection. The setup below uses the public
app, project files and installed documentation.
Requested implementation model: **ChatGPT-6.1 Sol**, reasoning **High**.
## Prepare the project
---
1. Download or clone the complete [public repository](https://vccplus-git.brianholman.com/VCCPlusApps/Quadrapassel)
into your own writable folder. Keep the folder structure, Makefile and
`vccplus-project.json` together.
2. Open the installed [VCC Plus for Mac](https://vccplus.brianholman.com/downloads/).
Its bundled toolchain supplies the game's build tools; Homebrew is not needed.
3. In **Develop → C Development…**, open the existing game project and select
**Release**. Read `docs/VCC_PLUS_WORKFLOW.md` before building or launching.
4. To work with ChatGPT, open the C workspace's **Assistant…** panel. Review the
shared inputs and enable **Use Project Makefile** for this project's recipe.
Enable **Allow Disposable Playtests** if you want isolated game tests.
5. Save the connection privately and connect it using the installed manual's
supported process. Keep the app and shared workspace open. Confirm a real
project request succeeds before asking the assistant to edit/build anything.
Implement **Quadrapassel for CoCo** in this repository:
The [MCP setup guide](docs/MCP_SETUP.md) distinguishes game-project access,
installed manuals and the separately shared Archive Library. Grant only the
scopes you intend to use. Never paste connection tokens or private grants into
this repository or a conversation.
`/Users/bholman/Development/Personal/VCC/CMOC/Repositories/Quadrapassel`
## A starting prompt
Remote: `https://vccplus-git.brianholman.com/VCCPlusApps/Quadrapassel`
Adapt this prompt to the change you want. Your working folder is your own clone;
no machine-specific path or model selection is required.
This chat belongs to the VCC Plus project for organization, but its implementation
scope is exclusively the Quadrapassel repository. Set the working directory to
that repository before running commands. Explicitly read its `AGENTS.md`,
`README.md`, `SPECIFICATION.md`, `docs/VCC_PLUS_WORKFLOW.md`, and
`docs/IMPLEMENTATION_PLAN.md`. Do not assume the project's primary folder is the
repository to edit. Preserve existing work and verify the branch and remote.
```text
Work on the Quadrapassel for CoCo checkout I have opened in VCC Plus.
First verify the repository, branch and existing changes, then read README.md,
AGENTS.md, SPECIFICATION.md and docs/VCC_PLUS_WORKFLOW.md.
Use **only the official `/Applications/VCC Plus.app`, version 3.5.5, build 48**,
and its supported MCP integration for the CoCo development workflow. Verify the
installed version before testing. Do not build VCC Plus, launch a custom build,
replace its tools, create an alternative MCP server, call private integration
endpoints, or request changes to the emulator. A different build requires Brian's
explicit approval. Normal game code and tests belong in this repository.
Use the independently written CoCo source and its behavioral specification.
Do not consult or import the Linux/Mac application's implementation or emulator
internals. Prefer documented standard CMOC APIs and preserve the existing narrow
C graphics exception and memory bounds.
Treat VCC Plus as a black box. **Do not read, search, copy, disassemble, or modify
VCC Plus implementation source or private development material. Do not read the
Quadrapassel Mac source or its development chat.** Shared project access and
inherited context do not authorize using those internals. Do not follow general
VCC Plus repository instructions into its implementation guides for this task.
This repository's specification and reference data replace the need for the Mac
source. Its provenance links are attribution, not an instruction to inspect it.
Discover the connected C project's actual capabilities and verify that it
matches this checkout, its current revision and the Release configuration.
Verify manual access separately; use Archive Library's own connection when a
historical reference is needed. Ask for a missing scope instead of inventing a
private endpoint or using another project's connection.
You may also consult Pierre's programs and the other example repositories under
`/Users/bholman/Development/Personal/VCC/CMOC/Repositories/` as read-only references.
Keep searches scoped to that folder or the particular example; do not search
its parent directory. Preserve each example's attribution and license. Access to
an example does not approve adopting assembly or another nonstandard API route.
Implement this change: [describe the desired behavior here].
Use MCP as the primary route to the installed manuals, public API documentation,
and historical archive. Discover the tools actually exposed by build 48, search
for the relevant material, and read the returned topics. Public CMOC headers,
public examples, and manuals shipped in the installed app are allowed references
when MCP cannot provide the needed detail. Historical CoCo manuals and documented
hardware references are allowed. Private emulator source is not. Report missing
MCP access instead of inventing an endpoint or substituting a custom build.
Preserve unrelated edits, personal disks, high scores and the normal guest
session. Use disposable test media. Build the declared Release disk, inspect
its diagnostics/memory check, and test the changed behavior with ordinary guest
input and real screenshots. Identify what passed and anything not observed.
Do not change guest memory/registers to manufacture a test result. Stop owned
tests and retain their disk receipts when finished. Commit or publish only if
I have requested it.
```
**Use standard CMOC APIs first.** Start with `coco.h` graphics, palette, keyboard,
joystick, timing and sound functions and documented standard CMOC libraries.
Ordinary C game logic, data structures, menus, tests and drawing compositions
that call these APIs are in scope. Do not presume a custom renderer is needed.
## Read next
**Approval gate:** before implementing or using hand-written assembly, raw
hardware/register access, direct framebuffer routines, private ROM entry calls,
custom interrupt handlers, VCC-specific extensions, or another route outside the
standard CMOC APIs, stop that part of the work and request review in the
coordinating chat **“Deploy VCC Plus Gitea” within the VCC Plus project**. Brian
has requested that this chat receive such proposals. Use the available chat
messaging tool to send a concise request with the standard API attempt, the
measured problem or documented missing capability, alternatives, proposed
implementation, affected files, and test plan. Do not read that chat's history
for implementation knowledge. If the destination cannot be identified reliably,
present the request to Brian for forwarding. Wait for an explicit decision from
Brian, or the coordinating chat relaying their agreed decision. Silence and an
agent's recommendation alone are not approval. Continue independent C/API work
while waiting. Record the approved scope in this repository before using it.
Compiler-generated assembly and already-shipped libraries behind public standard
APIs do not need this exception; custom assembly or modifications do.
- [Player's manual](https://vccplus.brianholman.com/games/quadrapassel/): the
delivered game's screens, controls, scoring, settings and disk records.
- [Behavioral specification](SPECIFICATION.md): implementation rules and fixtures.
- [Build workflow](docs/VCC_PLUS_WORKFLOW.md): the existing C project, Release
build, disk products and safe launch.
- [MCP setup](docs/MCP_SETUP.md): live discovery and scoped connection checks.
- [Provenance](docs/PROVENANCE.md): behavioral lineage and component notices.
The primary target is a **128 KB CoCo 3 with seven distinct piece colors**, the
complete game, keyboard controls, and a standard one-button analog joystick.
Also provide a **64 KB CoCo 2** version with the accepted color compromise.
512 KB is optional for a demonstrated improvement, not a prerequisite for color,
hold, preview, scoring or normal gameplay. Use ordinary CoCo speeds; report the
clock and memory configuration in performance results. All variants must fit
on one floppy with a DOS launcher, automatic machine selection where safely
supported by the standard API, and a manual selection fallback.
Implement from the self-contained specification: exact piece states, movement,
rotation, hold, next preview, landing shadow, scoring, difficulty, settings,
high scores, sounds and a title screen inspired by the supplied reference.
Use the documented intentional CoCo adaptations. Do not import a modern Tetris
ruleset or silently simplify the scoring. Preserve attribution and licenses.
Begin with a small **standard-CMOC API probe** for the 128 KB CoCo 3: select the
16-color screen, display seven colors, draw and erase moving blocks, read keyboard
and joystick, and measure responsiveness. Use a documented memory layout that
preserves BASIC's graphics and disk workspace. The installed `vcc/gime.h` helper
has a 512 KB contract; that does not mean standard CMOC graphics require 512 KB.
Do not choose that helper or a custom renderer as a shortcut around the target.
Discover the correct MCP connection and verify that it exposes this project,
its files and current revision before building. Do not operate a connector
sharing another project. Use MCP builds, isolated playtests, guest
screen captures and audio captures where advertised. Record the actual playtest
machine configuration: a fixed 512 KB playtest is not a 128 KB pass. Test 128 KB
in the official app through its normal supported interface if MCP cannot select
it. Brian can perform actual CoCo 2 checks in XRoar. Running the CoCo 2 executable
on an emulated CoCo 3 is useful but is not CoCo 2 qualification.
Work in coherent, runnable stages. Keep source and reproducible build settings in
this repository, with a top-level `Quadrapassel.DSK` once a working build exists.
Use writable test copies of disks; preserve users' media and active emulators.
Obtain an idle-desktop window before pointer/keyboard automation unless Brian
has granted one for these checks. Do not treat the original setup chat's desktop
permissions as a new grant.
Deliver actual CoCo-only screenshots, a readable README with controls and loading
instructions, a memory/disk budget, and an honest compatibility matrix. Report
passed, failed and pending checks separately. Document limitations within the
allowed APIs and bring exceptions back for review instead of bypassing them.
Keep implementation changes reviewable; commit/push implementation when Brian
authorizes it. The initial permission to publish these planning documents is not
blanket authorization to publish the finished game or change repo visibility.
---
## Folder access
The checkout is a separate Git repository, even though its chat will be in the
VCC Plus project. If the new chat cannot write there, add the exact checkout
folder to the project's allowed folders. Do not move the game into VCC Plus or
change the primary repository to work around permissions. Its own `AGENTS.md`
must be read explicitly in a project with multiple folders.
Dated investigation logs are historical evidence. They are not prerequisites for
using the current public game, toolchain or connection workflow.