Chapter 9 of 9
Start a project you can hand off
An idea can fit in one sentence: make a falling-block game, catalogue a disk, or teach the capitals. A project needs a few more decisions. Which CoCo will run it? Which controls must work? What may the assistant change? Where should it look when it does not know an API?
Write those decisions down once. They give your first chat a useful starting point and let another chat continue without reconstructing the whole conversation. You can change them as you learn; keep the changes visible.
Copy the starter, then make it yours
Download the Project Starter folder into your new project. These are editable documents, not a finished program or an approved build recipe. Replace the bracketed fields, remove irrelevant sections, and review the rules before adopting them.
| File | What belongs there |
|---|---|
PROJECT_BRIEF.md |
The program you want, target machine, controls, scope and acceptance checks. |
AGENTS.md |
Working rules that the owner has reviewed and adopted. |
START_HERE.md |
A short first request referring to those documents. |
MCP_SETUP.md |
Connection checks and limitations, without private grants or credentials. |
TESTING.md |
The exact program, machine and results actually tested. |
DECISIONS.md |
Measured limitations, approved exceptions and the reasons for them. |
Keep the project's public README.md about the program: what it does, how to build and run it, its original sources and licenses, and its known limitations. Readers do not need the history of your local folders or the chat that prepared them. The starter folder's README explains the templates; replace it with your program's introduction when appropriate.
Copy an editable first prompt
After saving a connection in VCC Plus's assistant panel, choose Copy Project Setup Prompt. Paste it into your project chat and add your completed START_HERE.md request. Edit… opens the starter text before copying. You can change the language, controls and working rules to suit your project, or choose Reset to Starter. Your edits remain while that connection panel stays open, including when you close and reopen the editing sheet. Keep a durable project-specific version in your project documents.
The copied text includes the current connection name, installed helper path and exported connection-file path. It does not include the file's contents. Copying only changes the clipboard. Review the prompt before sending it: the setup permission takes effect when you give it to the assistant.
The permission lets the assistant register, check and restart the named VCC Plus connection through supported setup tools and make read-only requests to verify access. It stays within the permissions you exported. It does not create a new grant, authorize a different build recipe, or give access to unrelated projects. If a required native permission is missing, the assistant should explain the particular choice you need to make in VCC Plus.
The plain-text starter contains the same working rules without your connection details. It is also useful when preparing a project before opening its workspace. Copy First Prompt remains the smaller choice for checking just the current editor connection.
Check three kinds of access
A project connection and a documentation connection are not always separate servers. BASIC, C and assembly connections include Manual Library tools. Archive Search has its own read-only connection, exported from the Archive Library's connection panel. Verify the three kinds of access independently:
| Scope | Ask for evidence |
|---|---|
| Project | Read the actual shared title and revision, using the advertised project tools. |
| Manual Library | Use search_help, then read_topic on one returned topic. |
| Archive Library | Search through its advertised tools and retrieve a relevant citation or document. |
A configured server, tools visible in this chat and a successful request are three different facts. Record them separately in MCP_SETUP.md. If the project works but Archive tools are unavailable, continue project work that does not need the Archive while repairing that connection. Do not conclude that VCC Plus lacks a feature just because a chat has not discovered it.
Keep exported grants outside Git and out of messages. A setup record can say which workspace and permissions were checked without copying private connection files. The connection chapter explains supported reconnection and direct helper checks.
Use the local reference shelf first
The installed manuals describe the environment you are actually using. Start there:
- Read the relevant VCC Plus BASIC or assembly manual, or the C API reference. Prefer the documented workspace workflow and bundled APIs.
- For compiler switches, assembler directives and linker options, consult the complete CMOC and LWTools references. They retain the authors' manuals and identify the matching tool versions. The accompanying command-line help records options offered by the bundled tools, including options not covered in the upstream prose.
- Use Archive Library for historical manuals, magazines and original hardware material. Preserve the publication and page citation.
- If these sources leave a gap, describe it and consult the original author's website or another appropriate primary source. Record which version the answer covers.
For example, an unfamiliar CMOC switch is a reason to search the bundled compiler manual and help, not immediately change the Makefile to match a web example. An old magazine may describe another ROM, processor or video mode. If the installed API, manual and observed program disagree, record that disagreement and investigate it. None of them should silently disappear from the explanation.
Choose a machine you can prove
Write memory sizes in KB and distinguish the guest processor from the Mac's processor. A useful target might read: “CoCo 3, MC6809, 128 KB, keyboard and joystick, disk boot.” A CoCo 2 edition could have its own 64 KB target, colors and acceptance checks. These are different builds or configurations until you prove otherwise.
Record the official installed VCC Plus version and build agreed for the project. Application projects normally treat the emulator as a black box: public MCP tools, the manuals and documented APIs are available; changing the emulator or using its private internals is outside that scope. Name any additional source examples or artwork the owner has approved as references.
A successful 512 KB test does not establish 128 KB compatibility. Keyboard input does not establish joystick support. If the available automated run cannot select the required machine, mark that check pending and use an approved compatible test environment or owner-assisted check. Do not change the requirement to make the test pass.
For a joystick project, the setup prompt and templates ask for separate input acceptance. Discover the current controls, then use owned joystick input for the required port, axes and fire buttons. Include neutral/release intervals and pause/menu behavior; compare delivery traces with actual movement in captured frames. Shared input diagnostics distinguish controller preview, last submission and actual core values. An emulated analog test does not qualify a physical gamepad or high-resolution interface. If a small C reproducer is needed, run the compiled target at the project's optimization level as well as any host tests.
Begin with one runnable slice
For multi-disk software, plan the owned disk-exchange tests as part of the project brief: which disk boots, which drives hold Home and Data, where a one-drive fallback asks to swap, where saves belong, and how wrong, empty, corrupt and write-protected game data should behave. Declare every test image as a reviewed build product. Verify independent writable copies, per-drive save/read activity, save/reload across swaps and explicit retained-set resumption. Match the program's actual drive choices, including nonzero Home drives; a successful mount alone is not an acceptance test.
Ask for the smallest program that proves an important part of the experience. For a game, that might be one object you can move and stop. For a disk utility, it might be listing one known directory without altering the disk. Agree on the expected result before running it.
For a C project, start with standard CMOC functions and the documented libraries. Ordinary application logic belongs in C. If the requested experience seems to require assembly, direct hardware access or drawing outside those APIs, first measure the actual limitation. Put the proposed exception in DECISIONS.md: the missing capability, evidence, alternatives, smallest change and checks needed. The owner or named reviewer decides whether to approve it. An assembly project naturally starts with its agreed instruction set and hardware scope; it does not need a separate exception for every assembly instruction.
Use the project's approved build recipe. Test a source revision and its resulting artifact together. Compilation proves that a program was accepted by the tools; playing it, using its controls and checking its output establish its behavior.
Prove which physical code overlay is loaded
A packed game can replace code in the same physical RAM, rather than merely switching between different RAM banks. Discover the installed C connection's get_capabilities first: banked_debug_manifest_versions includes 2 and verified_code_overlays identifies this support. Use the approved Make workflow and configure debugManifest to name the build-produced evidence. The project needs its own source and recipe, the installed tools and public MCP interface; it does not need the emulator's private source tree.
Manifest version 2 adds explicit overlayGroups and an overlay identity on each member module. This structural fragment shows two code owners reusing the same physical page. It is not a complete manifest or runnable project: keep the required entry point, binary/disk/linker identities, complete source set, artifact hashes and remaining modules in the real manifest.
{
"version": 2,
"overlayGroups": [{"id": "stages", "owners": ["stage-a", "stage-b"]}],
"modules": [
{
"id": "stage-a-code",
"sections": ["stage_a_code"],
"codeSections": ["stage_a_code"],
"image": {"path": "build/debug/stage-a.raw", "logicalAddress": 16384},
"pages": [{"logicalPage": 2, "physicalPage": 30}],
"overlay": {"group": "stages", "owner": "stage-a"}
},
{
"id": "stage-b-code",
"sections": ["stage_b_code"],
"codeSections": ["stage_b_code"],
"image": {"path": "build/debug/stage-b.raw", "logicalAddress": 16384},
"pages": [{"logicalPage": 2, "physicalPage": 30}],
"overlay": {"group": "stages", "owner": "stage-b"}
}
]
}
An owner may contain several modules. All of that owner's code-bearing modules must be mapped concurrently and every executable guard byte must match the current RAM snapshot. Exactly one matching owner establishes residency. Zero matches, partially installed code or multiple matching owners withhold that group's source locations, functions and variables. A familiar address or matching first opcode is insufficient. Different groups and ordinary resident modules cannot claim the same physical storage; same-owner modules cannot overlap it.
Keep executable bytes immutable in codeSections. Mutable data and BSS belong in separately declared sections/modules with the same group/owner identity. They inherit the uniquely proven code owner rather than being compared with old initial values; their storage must still have the declared current RAM mapping. A data/BSS-only owner cannot prove residency, and BSS needs no invented raw zeros.
Hashes still bind the complete declaration to its retained build, with independent object/relocation verification. Bounds remain explicit: 1 MiB manifest, 32 MiB per compiler .s file, 8 MiB per other evidence file and 128 MiB aggregate evidence; at most 64 groups, 256 owners and 256 modules. Group/owner identities are at most 128 UTF-8 bytes and contain no NUL. Declaring an overlay does not relax these checks or grant memory/register edits.
At verified owned stops, inspection reports the current module and residency_fingerprint. Source stepping and cached inspection receipts check fresh residency; the previous owner is not retained after code replacement. Test the real loader's A-to-B-to-A transitions, partial/wrong data and required processors using ordinary guest execution. Do not write guest RAM or registers through a debugger to manufacture a successful load or test.
Keep results another person can use
For each completed stage, record the source revision, build options, artifact name, target configuration and observed result. Use writable test copies of media. Obtain an idle-desktop window before automation that moves the user's pointer or types. Use direct MCP captures where supported; a screenshot of the CoCo display is often more useful than the surrounding Mac interface.
When measuring speed, repeat the same action on the same configuration and state the units. A redraw time, emulated cycle count and wall-clock startup time answer different questions. Keep the baseline result and any remaining limits alongside the improved result.
Finish with a reader-facing README, reproducible source, the agreed runnable artifact and useful screenshots. Preserve original attribution and file-specific license notices. Keep credentials, private ROMs, raw personal captures and temporary logs out of the repository. Commit, push, publish or message another chat only within the owner's actual authorization; do not repeatedly ask for a routine action already authorized for the same work.
For exact build delivery, separately approve a local folder through the C Assistant panel's Allow Build Output Export. Ask the assistant to export the original declared Release/Debug products, retain their build/artifact identities, and independently compare all receipt hashes. It can retrieve an earlier Release set after building Debug without another build. Keep delivered build bytes separate from retained writable test disks. Deliver an existing build
For a manual demonstration, the emulator header's camera saves the actual CoCo picture using the remembered None/5/10-second screenshot timer. Selecting a timer changes the setting; clicking the camera takes the picture. The separate video control records the CoCo picture and optional generated sound to MP4 when stopped. Screenshots and videos share one remembered Save To folder, Desktop by default. Both exclude System artwork, Mac controls and the desktop. The local shutter and recording-start cues never enter the output. Capture controls and recovery
A video-enabled MCP connection also lets your assistant record a short gameplay demonstration from its own disposable playtest. Ask it to use normal keyboard or joystick input, record the relevant route or interaction, retrieve the completed MP4 and verify its byte count and SHA-256 before adding it to your manual assets. Choose CoCo audio per clip. Mac windows, microphone and capture feedback sounds are excluded. Check the recording's field count and truncation status so the description matches what the clip actually shows. Waiting between tool calls adds no footage. These tools serve any project; they require no game-specific support in VCC Plus. Inspect live capabilities before requesting a recording.
A local working disk can also become a Personal Library entry without uploading or publishing it. For wider distribution, the software creator can deliberately choose Library Actions → Submit Software…, review the permission terms and offer the package for editorial inclusion. Include the required notices and obtain permission for every supplied asset; adding a private entry is not permission to redistribute purchased software. Private imports and public submissions
Before handing the project to another chat, update the brief, connection checks, decisions and tests. Then ask the new chat to read them, verify its own access and continue from the last demonstrated working stage. That is a more reliable starting point than asking it to infer the project from a long conversation.