# 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 library for Windows.
The library reads and writes the memory of another process.
The library also injects code, hooks functions, and calls remote functions.
The target process is a game client or any modern game.
The target CPU architecture is x84 or x64.

## 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 game offsets to the library. The consumer holds the offsets.
- Do not add bot logic to the library.
- Do not add anti-cheat evasion.
- Add the optional Iced backend only behind the `IAssembler` seam. Keep the default backend free of a third-party dependency.