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 process-introspection library for Windows. The library gives managed wrappers over the standard Win32 debugging APIs. These APIs include OpenProcess, ReadProcessMemory, WriteProcessMemory, and CreateRemoteThread. Debuggers, profilers, diagnostic tools, and CLR hosts use the same APIs. Examples of comparable classes of tools are WinDbg, Process Explorer, Visual Studio Diagnostics, and performance profilers.

The consumer of the library is a diagnostic and automation client. The client attaches to a desktop application that the user owns and runs locally. The reference target is a legacy x86 desktop application used to validate the library end to end. 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 application-specific logic to the library. The library stays a general interop layer.
• Keep the library's operation transparent. Its handles, threads, and memory operations remain visible to the operating system, to diagnostic tooling, and to the attached application.
• Do not add code that circumvents 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.