Consolidate the AGENTS.md rules into a rulebook

README.md

@@ -152,6 +152,22 @@ CGP is a collection of small, layered crates, arranged so that low-level primiti
 
 Contributions, questions, and bug reports are welcome. Open an [issue](https://github.com/contextgeneric/cgp/issues) or a pull request, and see the [website](https://contextgeneric.dev/) to get oriented first. Unless stated otherwise, contributions are made under the terms of the Apache-2.0 license below.
 
+### Development
+
+Run the checks from the repository root. The toolchain is pinned in `rust-toolchain.toml`, and most
+crates are `#![no_std]`, so keep new code `no_std`-compatible.
+
+```sh
+cargo +nightly fmt --all
+cargo clippy --all-features --all-targets -- -D warnings
+cargo clippy --no-default-features --all-targets -- -D warnings
+cargo nextest run --all-features --no-fail-fast --workspace
+```
+
+The suite covers `cgp-tests` for behavior and expansion snapshots and `cgp-macro-tests` for the macro
+internals. Post-codegen compile failures are UI fixtures in
+[`cargo-cgp`](https://github.com/contextgeneric/cargo-cgp).
+
 ## License
 
 Licensed under the [Apache License, Version 2.0](LICENSE).

crates/macros/AGENTS.md

@@ -0,0 +1,27 @@
+# AGENTS.md
+
+The root [cgp/AGENTS.md](../../AGENTS.md) rules apply. Invoke the `/cgp` skill before working here.
+
+## Shared rules
+
+- Parse input by implementing `syn::parse::Parse`; emit code by implementing `quote::ToTokens`.
+- Build AST nodes with `parse_internal!`, inside a `syn::Result`-returning function.
+- Emit every CGP item through an `exports` marker; add a new item to `export_constructs!`.
+- Keep the staged `preprocess` → `eval` → `to_items` pipeline.
+- Define a custom keyword with `define_keyword!` and `IsKeyword`.
+- Rewrite ASTs with `VisitMut` visitors, never with string manipulation.
+- Add a one-line `///` to every public struct, trait, and function that lacks one.
+- Put parser corner cases and expansion snapshots in `cgp-macro-tests`.
+
+## Core rules
+
+- `cgp-macro-core` has no `#[proc_macro]` entrypoints and does not depend on `proc-macro`.
+- The crate's module map and pipeline are documented in the knowledge base's implementation
+  documents.
+
+## Extra-core rules
+
+- Lower through `cgp-macro-core`'s intermediate representation, not by emitting a nested macro call.
+- Reuse `cgp-macro-core`'s `exports` markers rather than declaring a duplicate.
+- Build each intermediate node with `parse_internal!`.
+- The crate's module map is documented in the knowledge base's implementation documents.