111 lines
4.8 KiB
Markdown
111 lines
4.8 KiB
Markdown
# 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 `develop` 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.
|