Scaffold WhiteMagic solution and add AGENTS.md
Create the WhiteMagic net8.0-windows class library and the WhiteMagicTest xUnit project, grouped in WhiteMagic.slnx (SDK 10 default format). Library enables nullable, unsafe blocks, x86/x64 platforms, warnings-as-errors. Empty solution builds clean (0 errors, 0 warnings). Add AGENTS.md (ASD-STE100) defining the build/test commands, the test-first rule, and the one-feature-one-branch workflow with review before merge to master. Mark project-setup tasks 1.1-1.3, 1.5 done; 1.4 (Native P/Invoke surface) is the first feature branch. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -0,0 +1,96 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,4 @@
|
||||
<Solution>
|
||||
<Project Path="WhiteMagic/WhiteMagic.csproj" />
|
||||
<Project Path="WhiteMagicTest/WhiteMagicTest.csproj" />
|
||||
</Solution>
|
||||
@@ -0,0 +1,12 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net8.0-windows</TargetFramework>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<Nullable>enable</Nullable>
|
||||
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
|
||||
<Platforms>x86;x64;AnyCPU</Platforms>
|
||||
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
|
||||
</PropertyGroup>
|
||||
|
||||
</Project>
|
||||
@@ -0,0 +1,25 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net8.0-windows</TargetFramework>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<Nullable>enable</Nullable>
|
||||
<IsPackable>false</IsPackable>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\WhiteMagic\WhiteMagic.csproj" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="coverlet.collector" Version="6.0.4" />
|
||||
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
|
||||
<PackageReference Include="xunit" Version="2.9.3" />
|
||||
<PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<Using Include="Xunit" />
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
@@ -93,7 +93,7 @@ A `static class MarshalCache<T>` computes and caches `Marshal.SizeOf`, `TypeCode
|
||||
|
||||
### D7: New projects, additive, test-first
|
||||
|
||||
`WhiteMagic/` (library, `net8.0-windows`, `AllowUnsafeBlocks`) and `WhiteMagicTest/` (xUnit). No solution file exists in the repo root today; task 1.3 creates a fresh `WhiteMagic.sln` (or builds the csproj directly). BlackMagic lives in a nested subdir with its own git and is not part of this build. Pure-logic components (assembler encodings, marshal cache, pattern matcher, stub builders, pump queue) get tests before implementation, mirroring the existing `inject-and-assemble` change's TDD discipline. Live-process behavior (RPM/WPM, injection, detours) is validated in integration tests gated on an available target.
|
||||
`WhiteMagic/` (library, `net8.0-windows`, `AllowUnsafeBlocks`) and `WhiteMagicTest/` (xUnit). Task 1.3 creates `WhiteMagic.slnx` (SDK 10's default solution format). The reference libraries live under `reference/` (git-ignored) and are not part of this build. Pure-logic components (assembler encodings, marshal cache, pattern matcher, stub builders, pump queue) get tests before implementation, mirroring the existing `inject-and-assemble` change's TDD discipline. Live-process behavior (RPM/WPM, injection, detours) is validated in integration tests gated on an available target.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
## 1. Project Setup
|
||||
|
||||
- [ ] 1.1 Create `WhiteMagic/WhiteMagic.csproj` targeting `net8.0-windows`, `AllowUnsafeBlocks=true`, nullable enabled
|
||||
- [ ] 1.2 Create `WhiteMagicTest/WhiteMagicTest.csproj` (xUnit, `net8.0-windows`) referencing `WhiteMagic`
|
||||
- [ ] 1.3 No solution file exists in the repo root. Create one (`dotnet new sln -n WhiteMagic`) and add both projects, OR skip the solution and build csproj directly (decide before 1.5). Do NOT reference `BlackMagic.slnx` — it does not exist.
|
||||
- [x] 1.1 Create `WhiteMagic/WhiteMagic.csproj` targeting `net8.0-windows`, `AllowUnsafeBlocks=true`, nullable enabled, `TreatWarningsAsErrors`, `Platforms=x86;x64;AnyCPU`
|
||||
- [x] 1.2 Create `WhiteMagicTest/WhiteMagicTest.csproj` (xUnit, `net8.0-windows`) referencing `WhiteMagic`
|
||||
- [x] 1.3 Create `WhiteMagic.slnx` (SDK 10 default solution format) and add both projects. (Built on SDK 10; `net8.0-windows` targeting pack auto-restored.)
|
||||
- [ ] 1.4 Add `WhiteMagic/Native/` P/Invoke surface (`LibraryImport`): OpenProcess, Read/WriteProcessMemory, VirtualAllocEx/FreeEx/ProtectEx, CreateRemoteThread, Wow64Get/SetThreadContext, Get/SetThreadContext, LoadLibrary, GetProcAddress; add `SafeMemoryHandle`
|
||||
- [ ] 1.5 Verify empty projects build: `dotnet build WhiteMagic.sln` (or `dotnet build WhiteMagic/WhiteMagic.csproj` if no solution) — zero errors
|
||||
- [x] 1.5 Verify empty projects build: `dotnet build WhiteMagic.slnx` — zero errors, zero warnings
|
||||
|
||||
## 2. Core Memory Access (spec: memory-access)
|
||||
|
||||
@@ -81,6 +81,6 @@
|
||||
## 9. Verification
|
||||
|
||||
- [ ] 9.1 Run full test suite: `dotnet test WhiteMagicTest/WhiteMagicTest.csproj` — all pass
|
||||
- [ ] 9.2 Run full build (`dotnet build WhiteMagic.sln` or the WhiteMagic csproj, per 1.3) — zero errors, zero new warnings in `WhiteMagic`
|
||||
- [ ] 9.2 Run full build (`dotnet build WhiteMagic.slnx`) — zero errors, zero new warnings in `WhiteMagic`
|
||||
- [ ] 9.3 Confirm existing BlackMagic/its tests are unchanged and still green
|
||||
- [ ] 9.4 Update `docs/memory-library-comparison.md` "WhiteMagic — synthesis" section with any deviations discovered during implementation
|
||||
|
||||
Reference in New Issue
Block a user