# AGENTS.md

This file gives rules to an AI agent that works in this repository.
The text uses ASD-STE100 Simplified Technical English.
Write short sentences. Use the active voice. Give one instruction in each sentence.

## 1. Purpose

WhiteMagic is a .NET 8 diagnostic library for Windows.
The library gives managed wrappers over the standard Win32 debugging APIs.
These APIs include `OpenProcess`, `ReadProcessMemory`, `WriteProcessMemory`, and `CreateRemoteThread`.
Debuggers, profilers, and modding tools use the same APIs.
Examples of comparable tools are Cheat Engine, ReClass.NET, and x64dbg.

The consumer of the library is a modding and automation client.
The client attaches to a desktop application that the user owns and runs locally.
The reference application is a legacy game client (WoW 3.3.5a).
The target CPU architecture is x86 or x64.

The library is a general-purpose interop layer.
It does the same class of work as a debugger extension:
read and write memory in an attached process, marshal managed types to raw bytes,
generate small trampoline routines, and invoke routines in the attached process.
All operations need the same access rights that a debugger needs.
All operations run on the local machine with the consent of the user.

## 2. Repository layout

- `WhiteMagic/` — the library. Write the product code here.
- `WhiteMagicTest/` — the xUnit test project. Write the tests here.
- `openspec/` — the design documents. Read these before you write code.
- `docs/` — the reference study `memory-library-comparison.md`.
- `reference/` — four older libraries. Git ignores this folder. Read these for study only. Do not build these projects. Do not reference these assemblies.

## 3. Build and test

Run each command from the repository root.

- Build the solution: `dotnet build WhiteMagic.slnx`
- Run the tests: `dotnet test WhiteMagicTest/WhiteMagicTest.csproj`

The build must show zero errors and zero warnings.
`TreatWarningsAsErrors` is on. A warning stops the build.

## 4. Code rules

- Target framework: `net8.0-windows`.
- Enable nullable reference types. Do not disable nullable.
- Enable unsafe blocks only where a pointer dereference needs them.
- Keep the library bitness-agnostic. Support x86 and x64.
- Use `LibraryImport` for a new P/Invoke declaration. Do not use `DllImport` for new code.
- Match the style of the code near your change.

## 5. Test-first rule

Write the test before you write the product code.

Do these steps in order:

1. Write a test that fails.
2. Write the smallest code that makes the test pass.
3. Clean the code. Keep the test green.

Test all pure logic. Pure logic includes the assembler bytes, the marshal cache, the pattern matcher, the stub builder, and the pump queue.
A test that needs a live process is an integration test. Gate an integration test on an available target.

## 6. Design source

The plan lives in `openspec/changes/whitemagic-foundation/`.

- Read `proposal.md` for the goal.
- Read `design.md` for the decisions.
- Read `tasks.md` for the ordered task list.
- Read the file in `specs/` that matches your feature. Each requirement uses SHALL. Each scenario uses WHEN and THEN.

Make the code agree with the specification.
If you must change the plan, update the specification first.
Validate the change: `openspec validate whitemagic-foundation --strict`.

## 7. Branch and review workflow

The team builds one feature at a time.

Obey these rules:

1. Make one branch for one feature. Name the branch `feature/<short-name>`.
2. Start the branch from `master`.
3. Write the tests and the code on the branch.
4. Keep the build green on the branch.
5. Request a review before a merge.
6. Do not merge your own feature without a review.
7. Merge to `master` only after the review passes.
8. Delete the feature branch after the merge.

`master` must always build. `master` must always pass the tests.

## 8. Commit rules

- Write a clear commit message. Use the present tense.
- Describe what the commit changes. Describe why the commit changes it.
- Make a small commit for one logical change.
- Do not commit build output. Git ignores `bin/` and `obj/`.

## 9. Scope limits

- Do not add application-specific constants to the library. The consumer holds the offsets.
- Do not add automation or gameplay logic to the library. The library stays a general interop layer.
- Do not add concealment logic. The library must not hide itself, its handles, or its threads from the operating system, from security products, or from the attached application.
- Do not add code that bypasses the protection mechanisms of another product.
- Add the optional Iced backend only behind the `IAssembler` seam. Keep the default backend free of a third-party dependency.