whitemagic/AGENTS.md

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 (WoW 3.3.5a).

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