# 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.