C64-dev/newLang/AGENTS.md

AGENTS.md — Nova128 Project Rules

This file applies to every file below newLang/.

Mission

Build an object-oriented language and an on-machine compiler for the Commodore 128. The compiler is written in documented 8502/6502 assembly, runs in C128 native mode, reads source written by the repository's existing Vim clone, and emits native C128 PRG files.

Nova128 and the .n8 suffix are working names until the user approves them.

Start Every Work Session Here

Read these files in order before changing implementation files:

1. README.md
2. docs/decisions.md
3. docs/language-spec.md
4. docs/architecture.md
5. planning/epics-and-stories.md
6. planning/agent-workflow.md

Also read the repository-root AGENTS.md and the relevant skills under ../skills/. Compiler work requires ../skills/compiler-design/SKILL.md. Emulator work also requires ../skills/vice-emulator/SKILL.md.

Authority and Change Control

The canonical order is:

1. The user's latest instruction.
2. docs/decisions.md for accepted and provisional product decisions.
3. docs/language-spec.md for source-language behavior.
4. docs/architecture.md for compiler/runtime implementation contracts.
5. planning/epics-and-stories.md for scope and acceptance criteria.

Do not silently change syntax, type rules, object layout, the interface ABI, file formats, or memory ownership. Record a proposed change in docs/decisions.md and obtain user approval when it changes visible behavior or project scope.

Story Ownership

• Work from a story ID in planning/epics-and-stories.md.
• Before implementation, create planning/claims/<story-id>.md from the template in planning/agent-workflow.md.
• One agent owns one active story unless coordination is explicit.
• Check existing claims and git status before editing.
• Do not take a story whose dependencies are incomplete.
• Keep changes inside the story's listed file areas when possible.
• Never discard, reset, or overwrite another agent's uncommitted work.

Definition of Done

A story is complete only when:

• Every acceptance criterion has evidence.
• Relevant automated tests pass.
• VICE behavior is verified when the story touches C128 execution.
• Documentation matches the implementation.
• Generated files are not confused with authoritative source files.
• The claim records files changed, commands run, results, and remaining risks.

Platform Constraints

• Target C128 native mode on the 8502. C64 and Z80 targets are out of scope for version 1.
• Use documented 6502/8502 instructions; do not depend on illegal opcodes.
• Use ca65 and ld65 for host assembly/linking.
• Test C128 programs with VICE x128.exe, not x64sc.exe.
• Use explicit MMU wrapper routines. Compiler modules must not perform ad hoc bank switching.
• Keep the hardware stack for calls, interrupts, and short-lived internals. Language frames and substantial compiler stacks belong in software-managed memory.
• KERNAL entry must occur through wrappers that install a compatible memory configuration and restore the compiler configuration afterward.
• Exact memory addresses remain provisional until the E01 platform probes pass.

Editor and Disk Safety

• The current Vim clone is a C64-mode application. Version 1 integrates by exchanging PETSCII SEQ files on a copied D81 image.
• Never run x64sc and x128 against the same writable D81 simultaneously.
• Never modify ../vim/work.d81 or a reference disk image in place.
• Build and test scripts must make a working copy under newLang/build/.
• Human-readable host source is authoritative. PETSCII files and disk images are generated artifacts unless a fixture explicitly says otherwise.

Source and Output Contracts

• Nova128 source is PETSCII SEQ with $0D line endings.
• The supported editor profile is at most 80 bytes per logical line, about 18,999 source bytes, and 599 lines per file.
• Keep source base names at 12 characters or fewer so .n8, .err, and .map variants fit Commodore DOS's 16-character filename limit.
• Compiler outputs are .prg, .err, and .map files as specified in the architecture document.

Repository Hygiene

• Put all new project work under newLang/.
• Do not edit ../vim/ merely to make the compiler easier to build.
• Do not commit generated build/ contents unless a release story explicitly requires a packaged artifact.
• Prefer small, reviewable ca65 modules and deterministic test fixtures.