c64bridge 0.7.4 → 0.8.0

package/.github/prompts/README.md

@@ -1,6 +1,16 @@
-## Copilot Base Prompts
+## Copilot Prompt Modes
 
-This directory contains base prompts that are used if specific chat modes are
-enabled in Copilot.
+These files define repo-local prompt entry points.
 
-They are not end user prompts which you can find in the `doc/prompts` directory instead.
+Shared guidance lives in `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`.
+Execution logic lives only in `.github/skills/*/SKILL.md`.
+
+## Prompts vs Skills
+
+Prompts in this folder decide when and why a workflow should run.
+
+Skills in `.github/skills/` define how the workflow executes: MCP tool choice, sequencing,
+validation, and safety constraints.
+
+Keep prompt files short, intent-shaped, and routing-only. If a prompt starts describing tool
+calls or step-by-step execution, move that content into the matching skill.

package/.github/prompts/assembly-routine-session.prompt.md

@@ -1,13 +1,13 @@
 ---
-mode: 'agent'
-model: GPT-4o
-tools: ['c64bridge/*']
-description: 'Author and validate Commodore 64 assembly routines with proper safety checks.'
+mode: "agent"
+tools: ["c64bridge/*"]
+description: "Author and validate Commodore 64 assembly routines with proper safety checks."
 ---
+
 Your goal is to help an experienced user craft a 6502/6510 routine for the Commodore 64 while maintaining safe workflows.
 
-1. Determine the hardware focus (VIC-II, SID, CIA, mixed) and confirm whether interrupts or zero-page areas are already in use. Reference [`assembly-spec.md`](../../data/assembly/assembly-spec.md) and the safety rules in [`bootstrap.md`](../../data/context/bootstrap.md).
-2. Sketch a plan that lists target addresses, registers, and any required initialisation. Pull supporting references with `c64_rag` (op `asm`) when needed for timing tables or register maps.
-3. Generate assembly source with clear labels. Assemble and run using `c64_program` (op `upload_run_asm`). Capture assembler diagnostics and surface them if compilation fails.
-4. Provide verification steps: `c64_memory` (ops `read`, `read_screen`) for installed code or hardware register dumps, and instructions for acknowledging IRQ flags (`$D01A`, `$D019`) when applicable. Emphasise pausing via `c64_system` (op `pause`) before invasive memory edits and resuming afterward.
-5. Offer follow-up options such as exporting to disk (`c64_disk` op `create_image`), integrating with BASIC loaders, or resetting the machine (`c64_system` op `reset`) once the user confirms.
+Use the skill defined in `../skills/assembly-program/SKILL.md` as the single source of truth for execution.
+
+This prompt only identifies the intent: custom 6502/6510 routine work with hardware-aware safety requirements.
+
+Extract the hardware focus and any missing constraints from the user request, execute the skill, and summarize the result, validation, and any blockers.

package/.github/prompts/basic-program-session.prompt.md

@@ -1,13 +1,15 @@
 ---
-mode: 'agent'
-model: GPT-4o
-tools: ['c64bridge/*']
-description: 'Plan, write, and validate a Commodore BASIC v2 program with MCP tooling.'
+mode: "agent"
+tools: ["c64bridge/*"]
+description: "Plan, write, and validate a Commodore BASIC v2 program with MCP tooling."
 ---
+
 Your goal is to help the user design and run a BASIC v2 program on the Commodore 64.
 
-1. Clarify the program requirements, expected inputs/outputs, and whether the user wants to preserve existing state. Use [`basic-spec.md`](../../data/basic/basic-spec.md) for quick syntax reminders.
-2. Outline a short plan before coding, citing helpful docs like [`basic-spec.md`](../../data/basic/basic-spec.md) for keywords or [`bootstrap.md`](../../data/context/bootstrap.md) for workflow rules.
-3. Generate uppercase, token-friendly BASIC with line numbers. Run `c64_program` (op `upload_run_basic`) and include the code in the response with brief comments if needed.
-4. Immediately capture results with `c64_memory` (op `read_screen`), and suggest `c64_memory` (op `read`) on the program area when validation is required. Flag any disruptive steps (like `c64_system` op `reset`) and request confirmation first.
-5. Offer iteration tips: tweaking constants, persisting output to disk via `c64_printer` (op `print_text`) and `c64_disk` (op `create_image`), or expanding the program using relevant RAG lookups (`c64_rag` op `basic`).
+Use the skill defined in `../skills/basic-program/SKILL.md` as the single source of truth for execution.
+
+This prompt only identifies the intent: a bespoke Commodore BASIC v2 program rather than a generic quick demo.
+
+If the request collapses to a tiny hello-world or smoke-test program, reroute to `../skills/hello-world/SKILL.md` instead of treating it as bespoke BASIC.
+
+Extract missing requirements from the user request, execute the skill, and summarize the result and validation.

package/.github/prompts/drive-management-session.prompt.md

@@ -1,13 +1,13 @@
 ---
-mode: 'agent'
-model: GPT-4o
-tools: ['c64bridge/*']
-description: 'Manage Ultimate 64 disk images and drives safely.'
+mode: "agent"
+tools: ["c64bridge/*"]
+description: "Route disk-image and drive requests to the canonical drive-management skill."
 ---
+
 Your goal is to help the user mount, create, or remove disk images on the Ultimate hardware without disrupting active programs.
 
-1. Start by listing drives via `c64_disk` (op `list_drives`) and confirming which slot the user wants to touch. 
-2. Clarify the desired action: mount an existing image, create a new blank disk, or eject/reset hardware. Offer options (`c64_disk` ops `mount`, `unmount`, `file_info`, `find_and_run`; `c64_drive` ops `reset`, `power_on`, `power_off`, `set_mode`, `load_rom`).
-3. For new media, walk through `c64_disk` (op `create_image`), documenting output paths. Suggest using `c64_disk` (op `file_info`) to confirm image contents when needed.
-4. After any mutation, rerun `c64_disk` (op `list_drives`) to verify state. Warn before power cycling or resetting drives that might be in active use by running software.
-5. Provide cleanup guidance: closing with `c64_disk` (op `unmount`), backing up created images, and resuming normal operation (`c64_system` ops `resume`, `reset`) if a pause was required.
+Use the skill defined in `../skills/drive-manager/SKILL.md` as the single source of truth for execution.
+
+This prompt only identifies the intent: disk-image or drive-state changes that must be handled safely.
+
+Extract the requested drive action, execute the skill, and summarize the resulting drive state and validation.

package/.github/prompts/hello-world-session.prompt.md

@@ -0,0 +1,17 @@
+---
+mode: "agent"
+tools: ["c64bridge/*"]
+description: "Run the fastest hello-world or smoke-test workflow with MCP tooling."
+---
+
+Your goal is to run a fast hello-world or greeting workflow on one or more Commodore 64 backends.
+
+Use the skill defined in `../skills/hello-world/SKILL.md` as the single source of truth for execution.
+
+This prompt only identifies the intent: a trivial greeting, smoke test, or hello-world confirmation.
+
+When the request is already backend-pinned and low ambiguity, execute immediately through the skill instead of re-reading general docs.
+
+When the skill selects a grouped MCP tool such as `c64_program`, always include its `op` discriminator in the call arguments.
+
+Extract missing requirements from the user request, execute the skill, and summarize the result and validation.

package/.github/prompts/petscii-art-session.prompt.md

@@ -1,13 +1,13 @@
 ---
-mode: 'agent'
-model: GPT-4o
-tools: ['c64bridge/*']
-description: 'Design PETSCII or sprite-based visuals using Commodore 64 MCP tools.'
+mode: "agent"
+tools: ["c64bridge/*"]
+description: "Design PETSCII or sprite-based visuals using Commodore 64 MCP tools."
 ---
+
 Your goal is to help the user create PETSCII scenes or sprite showcases on the Commodore 64.
 
-1. Gather the artistic direction (theme, colours, animation needs) and whether output should be static PETSCII, sprite demo, or both. Consult the VIC reference in [`vic-spec.md`](../../data/video/vic-spec.md) and the character map in [`character-set.csv`](../../data/video/character-set.csv).
-2. Decide on the rendering path: `c64_graphics` (op `create_petscii`) for automatic art, `c64_graphics` (op `render_petscii`) for text layouts, or `c64_graphics` (op `generate_sprite`) for sprite visuals. Outline the plan before executing.
-3. When generating BASIC routines, call `c64_program` (op `upload_run_basic`). For assembly-driven demos, guide the user through `c64_program` (op `upload_run_asm`). Mention palette registers (`$D020`, `$D021`) and mode bits (`$D011`, `$D016`, `$D018`).
-4. Validate the output using `c64_memory` (op `read_screen`) or by capturing sprite memory with `c64_memory` (op `read`). Offer adjustments such as recolouring, adding animation loops, or exporting assets via `c64_disk` (ops `create_image`, `mount`).
-5. Encourage saving or sharing results, and remind the user how to reset or restore the display when finished (`c64_system` op `reset`).
+Use the skill defined in `../skills/graphics-demo/SKILL.md` as the single source of truth for execution.
+
+This prompt only identifies the intent: PETSCII, sprite, bitmap, or frame-capture work.
+
+Extract the requested visual mode and style constraints, execute the skill, and summarize the resulting output and validation.

package/.github/prompts/play-classic-game.prompt.md

@@ -1,13 +1,13 @@
 ---
-mode: 'agent'
-model: GPT-4o
-tools: ['c64bridge/*']
-description: 'Load and run existing Commodore 64 software via the MCP server.'
+mode: "agent"
+tools: ["c64bridge/*"]
+description: "Load and run existing Commodore 64 software via the MCP server."
 ---
+
 Your goal is to guide the user through playing an existing Commodore 64 title using the Ultimate hardware and the `c64bridge` tool suite.
 
-1. Clarify what media the user has (single PRG, CRT, or full disk image) and gather any Ultimate filesystem paths. When unsure, suggest listing drives with `c64_disk` (op `list_drives`).
-2. Verify connectivity by calling `c64_config` (ops `version`, `info`) before attempting to load software. If hardware is offline, point to the environment checklist in the [developer guide](../../doc/developer.md).
-3. For loose PRG or CRT files, prefer `c64_program` (ops `run_prg`, `run_crt`). For disk images, mount them with `c64_disk` (op `mount`), then launch the correct program via `c64_program` (op `run_prg`) or the autostart feature. Always confirm the target drive slot with the user.
-4. After launching the program, capture the initial screen with `c64_memory` (op `read_screen`). If the user wants livestream output, mention the optional `c64_stream` (op `start`) audio/video bridge.
-5. Offer follow-up support such as saving snapshots with `c64_disk` (op `create_image`) or cleanly unmounting media with `c64_disk` (op `unmount`) when finished.
+Use the skill defined in `../skills/software-launch/SKILL.md` as the single source of truth for execution.
+
+This prompt only identifies the intent: launching existing PRG, CRT, or disk-based software.
+
+Extract the media type and target backend from the user request, execute the skill, and summarize the launch result and validation.

package/.github/prompts/pr-converge.prompt.md

@@ -0,0 +1,13 @@
+---
+description: Converge a pull request to merge-ready state
+---
+
+# Pull Request Convergence
+
+Bring the current pull request to a **merge-ready state**.
+
+Use the skill defined in `../skills/pr-converge/SKILL.md` as the single source of truth for execution.
+
+This prompt only identifies the intent: bringing the current pull request to merge-ready state.
+
+Execute the skill, keep iterating until convergence criteria are satisfied, and summarize fixes, validation, and CI status.

package/.github/prompts/sid-music-session.prompt.md

@@ -1,13 +1,13 @@
 ---
-mode: 'agent'
-model: GPT-4o
-tools: ['c64bridge/*']
-description: 'Compose, play, and iterate on SID music using MCP tooling.'
+mode: "agent"
+tools: ["c64bridge/*"]
+description: "Compose, play, and iterate on SID music using MCP tooling."
 ---
+
 Your goal is to help the user create expressive SID music on the Commodore 64.
 
-1. Ask about musical goals: style, instruments, tempo, duration, and whether they prefer BASIC playback or SIDWAVE composition. Reference the best-practice notes in [`sid-programming-best-practices.md`](../../data/audio/sid-programming-best-practices.md).
-2. Draft a composition plan with phrasing guidance. When gathering inspiration or technique snippets, use `c64_rag` (op `basic`/`asm`) targeting SID resources.
-3. Generate either a BASIC music program (triangle/pulse focus) or a SIDWAVE definition. Execute playback with `c64_program` (op `upload_run_basic`), `c64_sound` (op `generate`), or `c64_sound` (op `compile_play`) depending on the chosen format.
-4. Encourage verification by calling `c64_sound` (ops `record_analyze` or `analyze`), summarising detected notes and timing. Offer manual tweaks via `c64_sound` (ops `note_on`, `note_off`, `set_volume`) where appropriate.
-5. Provide exporting and archival options: saving PRGs/SIDs to disk (`c64_disk` op `create_image`, then `c64_disk` op `mount`) and noting how to restore the SID state (`c64_sound` ops `reset`, `silence_all`).
+Use the skill defined in `../skills/sid-music/SKILL.md` as the single source of truth for execution.
+
+This prompt only identifies the intent: preset playback, custom SID composition, or audio verification.
+
+Extract the musical goal and any missing constraints, execute the skill, and summarize the playback path and validation.

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Agent Integration Guide
 
-LLM-facing reference for using this MCP server. Keep it simple: start the server, discover tools, call them safely.
+LLM-facing reference for using this MCP server. Keep it simple: start the server, discover tools safely, and route execution through `.github/skills`.
 
 ## Quick Start
 
@@ -25,6 +25,22 @@ Example:
 
 When Ultimate firmware network protection is enabled, `networkPassword` is sent as the `X-Password` header on every REST request.
 
+### Runtime Backend Switching
+
+When both `c64u` and `vice` are configured, the server can keep both backends live at the same time.
+Use `c64_select_backend` to switch the active backend without restarting the MCP server.
+The `c64://platform/status` resource always reports the currently active backend and the configured backend set.
+State the desired backend directly in the prompt when you want to pin execution, for example: `use vice`, `vice: load this PRG`, `use c64u`, or `run this on hardware`.
+When using the VS Code `C64` agent, keep the backend request in the same prompt so tool routing can call `c64_select_backend` before backend-specific operations.
+
+### Fast Discovery Rules
+
+When the prompt is already specific and backend-pinned, execute the matching skill immediately instead of re-reading general documentation.
+Example: `vice: write a small BASIC program that clears the screen and prints HELLO VICE` should route straight to `.github/skills/hello-world/SKILL.md` and use that skill's minimal path.
+If the current agent cannot directly see `c64bridge` MCP tools such as `c64_program`, immediately hand the request to the `C64` agent instead of inspecting repository files or MCP manifests first.
+For a visible single-backend VICE greeting, prefer a no-probe fast path and avoid screenshot capture or Binary Monitor verification unless the user explicitly requests confirmation artifacts.
+Once the MCP server is connected and tools are available in-session, do not spend extra turns inspecting README sections or tool manifests for routine `c64_select_backend`, `c64_program`, or `c64_memory` operations.
+
 3) VS Code Copilot Chat (MCP)
 
 Add to Settings (JSON):
@@ -41,51 +57,58 @@ Add to Settings (JSON):
 
 Keep the server running; tools are discovered automatically in the chat session.
 
-## MCP Discovery & Calling
+4) Shared agent instructions
 
-- Discover tools: use the client’s ListTools. You will see domains like `c64_program`, `c64_memory`, `c64_system`, etc., each with an `op` multiplexing parameter.
-- Discover resources/prompts: use ListResources and ListPrompts for knowledge and reusable patterns.
-- Call pattern (all tools): pass a JSON object with `op` plus operation‑specific inputs shown by ListTools.
+`AGENTS.md` is the canonical cross-tool contract for this repository.
+`CLAUDE.md` imports it for Claude Code, and Copilot/Codex-style agents can read it directly.
 
-Examples (MCP tool calls; HTTP only for illustration):
+5) Skill architecture
 
-```json
-// c64_program — upload and run BASIC
-{
-  "op": "upload_run_basic",
-  "program": "10 PRINT \"HELLO\"\n20 GOTO 10"
-}
-```
+Execution logic lives only in `.github/skills/*/SKILL.md`.
+Prompt files under `.github/prompts/` and MCP prompts from `src/prompts/registry.ts` are routing-only.
+If a workflow description starts listing tool calls outside `.github/skills`, treat that as stale and move it into the matching skill.
 
-```json
-// c64_memory — wait for output on the screen (ASCII)
-{
-  "op": "wait_for_text",
-  "pattern": "HELLO"
-}
-```
+## MCP Discovery & Calling
 
-```json
-// c64_rag — retrieve BASIC or ASM references from local knowledge
-{
-  "op": "basic",
-  "q": "draw a bouncing sprite"
-}
-```
+- Discover tools with the client’s ListTools.
+- Discover resources and prompts with ListResources and ListPrompts.
+- Use the matching skill in `.github/skills/` to decide the actual tool sequence, validation, and safety behavior.
+- After discovery has already happened for the active session, prefer execution over repeated rediscovery for unambiguous requests.
+- Treat `c64_program`, `c64_memory`, `c64_graphics`, `c64_sound`, `c64_system`, `c64_config`, `c64_rag`, `c64_extract`, and similar grouped MCP tools as discriminated unions: every direct call must include `op`.
+- Never call a grouped tool with `{}` or with only secondary arguments. Choose the sub-operation first, then send `{ op: "...", ... }`.
+- When a skill tells you to execute a grouped tool, copy the exact `op` string from the skill instead of inferring it from the tool name.
 
 ## Capabilities
 
 - Program runners: `c64_program` (`upload_run_basic`, `upload_run_asm`, `run_prg`, `run_crt`, `bundle_run`, `batch_run`)
+- Fast demo workflow: `c64_program` (`cross_platform_greeting`) for one-call greetings on VICE and/or C64U with screenshot capture and verification
 - Screen & memory: `c64_memory` (`read`, `write`, `read_screen`, `wait_for_text`)
 - System control: `c64_system` (`pause`, `resume`, `reset`, `reboot`, `poweroff`, `menu`, tasks)
 - Configuration: `c64_config` (get/set, `batch_update`, `snapshot`, `restore`, `diff`, `shuffle`)
 - Drives & files: `c64_disk`, `c64_drive`
-- SID / music: `c64_sound` (playback, generate, analyze)
+- SID / music: `c64_sound` (`play_preset`, playback, generate, analyze)
 - Graphics: `c64_graphics` (PETSCII, sprites)
 - Knowledge & RAG: `c64_rag` (BASIC and ASM lookups)
 
 Tools and parameters are listed dynamically via ListTools.
 
+## Skill Routing
+
+| Intent | Skill |
+| --- | --- |
+| Ultra-fast hello world or smoke test | `.github/skills/hello-world/SKILL.md` |
+| Quick visible greeting or smoke test | `.github/skills/cross-platform-demo/SKILL.md` |
+| Custom BASIC program | `.github/skills/basic-program/SKILL.md` |
+| Custom assembly routine | `.github/skills/assembly-program/SKILL.md` |
+| SID demo or composition | `.github/skills/sid-music/SKILL.md` |
+| Graphics workflow | `.github/skills/graphics-demo/SKILL.md` |
+| Memory inspection or patching | `.github/skills/memory-debug/SKILL.md` |
+| Disk and drive management | `.github/skills/drive-manager/SKILL.md` |
+| Existing software launch | `.github/skills/software-launch/SKILL.md` |
+| Printer workflow | `.github/skills/printer-job/SKILL.md` |
+| Streaming workflow | `.github/skills/stream-control/SKILL.md` |
+| Machine or config control | `.github/skills/system-control/SKILL.md` |
+
 ## Knowledge Resources
 
 Use ListResources to discover built-in knowledge, then read specific URIs to enrich context before coding:
@@ -100,34 +123,10 @@ Use ListResources to discover built-in knowledge, then read specific URIs to enr
 
 Pull RAG snippets via `c64_rag` (ops `basic`/`asm`) for targeted examples.
 
-## Expert Workflow (recommended)
-
-- Plan → Run → Verify: generate code, run via `c64_program`, then verify with `c64_memory.read_screen`/`wait_for_text` and optional RAM checks.
-- Prefer stdio transport; only use the HTTP bridge for manual inspection.
-- Use `c64_rag` to fetch relevant BASIC/ASM snippets and specs before coding.
-- BASIC tips: tokenised keywords, short variable names, careful quoting; keep lines ≤ 2 screen rows; prefer `PRINT` with explicit spacing.
-- ASM tips: avoid unstable rasters; use zero page consciously; confirm register maps via `c64://specs/assembly`, `c64://specs/memory-map`, `c64://specs/vic` resources.
-- Safety: only call reset/power/drive operations intentionally; confirm preconditions for mounts/writes; log reversible steps in chat.
-
-Error handling patterns:
+## Operating Rule
 
-- If a run stalls, `c64_system.reset` then re-run; verify with `wait_for_text`.
-- On memory write validation failure, re-read with `c64_memory.read` and compare.
-- For long tasks, prefer background tasks (`c64_system.start_task`) and poll.
-
-## HTTP Examples (optional)
-
-The stdio transport is preferred. The legacy HTTP bridge is deprecated and disabled by default; enable manually before using curl.
-
-```bash
-curl -s -X POST -H 'Content-Type: application/json' \
-  -d '{"op":"upload_run_basic","program":"10 PRINT \"HELLO\"\n20 GOTO 10"}' \
-  http://localhost:8000/tools/c64_program | jq
-
-curl -s -X POST -H 'Content-Type: application/json' \
-  -d '{"op":"read_screen"}' \
-  http://localhost:8000/tools/c64_memory | jq
-```
+Prefer stdio transport end to end.
+For execution details, follow the matching skill rather than duplicating tool steps in prompts, agent files, or ad hoc instructions.
 
 ## Safety Notes
 
@@ -140,9 +139,9 @@ Use these starting points to seed agent context. Templates live in `.github/prom
 
 | Persona | Focus | Starter prompt |
 | --- | --- | --- |
-| BASIC Agent | Commodore BASIC v2, PETSCII, simple I/O, printing | [.github/prompts/basic-program-session.prompt.md](.github/prompts/basic-program-session.prompt.md) |
+| BASIC Agent | Commodore BASIC v2 and simple I/O | [.github/prompts/basic-program-session.prompt.md](.github/prompts/basic-program-session.prompt.md) |
 | ASM Agent | 6502/6510 assembly, raster, sprites, IRQs | [.github/prompts/assembly-routine-session.prompt.md](.github/prompts/assembly-routine-session.prompt.md) |
-| SID Composer | SID playback/composition, ADSR, waveforms | [.github/prompts/sid-music-session.prompt.md](.github/prompts/sid-music-session.prompt.md) |
-| Drive Manager | Disk images, drive modes, resets | [.github/prompts/drive-management-session.prompt.md](.github/prompts/drive-management-session.prompt.md) |
-| VIC Painter | PETSCII/bitmap art, sprites | [.github/prompts/petscii-art-session.prompt.md](.github/prompts/petscii-art-session.prompt.md) |
-| Memory Debugger | RAM inspection, screen/colour RAM checks | Use `c64_memory` tools + `c64://specs/memory-map` |
+| SID Composer | SID playback and composition | [.github/prompts/sid-music-session.prompt.md](.github/prompts/sid-music-session.prompt.md) |
+| Drive Manager | Disk images and drive state | [.github/prompts/drive-management-session.prompt.md](.github/prompts/drive-management-session.prompt.md) |
+| VIC Painter | PETSCII, bitmap art, and sprites | [.github/prompts/petscii-art-session.prompt.md](.github/prompts/petscii-art-session.prompt.md) |
+| Software Launcher | Existing PRG, CRT, or disk software | [.github/prompts/play-classic-game.prompt.md](.github/prompts/play-classic-game.prompt.md) |