diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..a12d9e8
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,42 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`GFramework.sln` is the entry point for the full .NET solution. Runtime code lives in `GFramework.Core/`,
+`GFramework.Game/`, `GFramework.Godot/`, and `GFramework.Ecs.Arch/`. Interface-only contracts stay in the paired
+`*.Abstractions/` projects. Roslyn generators are split across `GFramework.SourceGenerators/`,
+`GFramework.Godot.SourceGenerators/`, and `GFramework.SourceGenerators.Common/`. Tests mirror the runtime modules in
+`GFramework.Core.Tests/`, `GFramework.Game.Tests/`, `GFramework.Ecs.Arch.Tests/`, and
+`GFramework.SourceGenerators.Tests/`. Documentation is under `docs/`, Godot templates under `Godot/script_templates/`,
+and repository utilities under `scripts/` and `refactor-scripts/`.
+
+## Build, Test, and Development Commands
+
+- `dotnet build GFramework.sln` builds the full solution from the repo root.
+- `dotnet test GFramework.sln --no-build` runs all NUnit test projects after a build.
+- `dotnet test GFramework.Core.Tests --filter "FullyQualifiedName~CommandExecutorTests.Execute"` runs a focused NUnit
+  test.
+- `bash scripts/validate-csharp-naming.sh` checks PascalCase namespace and directory rules used by CI.
+- `cd docs && bun install && bun run dev` starts the VitePress docs site locally.
+
+## Coding Style & Naming Conventions
+
+Use standard C# formatting with 4-space indentation and one public type per file. The repository keeps `ImplicitUsings`
+disabled and `Nullable` enabled, so write explicit `using` directives and annotate nullability carefully. Follow
+`PascalCase` for types, methods, namespaces, directories, and constants; use `_camelCase` for private fields and
+`camelCase` for locals and parameters. Keep namespaces aligned with folders, for example
+`GFramework.Core.Architectures`.
+
+## Testing Guidelines
+
+Tests use NUnit 4 with `Microsoft.NET.Test.Sdk`; some suites also use Moq. Place tests in the matching module test
+project and name files `*Tests.cs`. Prefer directory parity with production code, for example `GFramework.Core/Logging/`
+and `GFramework.Core.Tests/Logging/`. Add or update tests for every behavior change, especially public APIs, source
+generators, and integration paths.
+
+## Commit & Pull Request Guidelines
+
+Recent history follows Conventional Commit style such as `feat(events): ...`, `refactor(localization): ...`,
+`docs(guide): ...`, and `test(localization): ...`. Keep commits scoped and imperative. PRs should explain the
+motivation, implementation, and validation commands run; link related issues; and include screenshots when docs, UI, or
+Godot-facing behavior changes.