Add CLAUDE.md and consolidate AI agent conventions

.claude/commands/check-ci.md

@@ -0,0 +1,8 @@
+Run the full CI gate checks locally before pushing. Run all four commands sequentially and report any failures:
+
+1. `cargo fmt --all -- --check`
+2. `cargo clippy --workspace --all-targets --all-features -- -D warnings`
+3. `cargo test --workspace --all-targets`
+4. `cargo check --workspace --all-targets --features "fastly cloudflare"`
+
+If any step fails, show the errors and suggest fixes. Do not proceed to the next step until the current one passes.

.claude/commands/review-changes.md

@@ -0,0 +1,15 @@
+Review the current uncommitted changes as a staff engineer would. Run:
+
+1. `git diff` to see all changes
+2. `git diff --cached` to see staged changes
+3. `git status` to see untracked files
+
+Then provide a thorough code review covering:
+
+- Correctness: are the changes logically sound?
+- WASM compatibility: do changes avoid Tokio/runtime-specific deps in core/adapters?
+- Convention compliance: matchit `{id}` syntax, `edgezero_core` imports, `#[action]` macros?
+- Test coverage: are new code paths tested?
+- Minimal scope: are there unnecessary changes beyond what was requested?
+
+Be critical. Flag anything that would fail CI or violate project conventions from CLAUDE.md.

.claude/commands/test-all.md

@@ -0,0 +1,7 @@
+Run the full workspace test suite:
+
+```
+cargo test --workspace --all-targets
+```
+
+If tests fail, analyze the failures and suggest fixes. Group failures by crate for clarity.

.claude/commands/test-crate.md

@@ -0,0 +1,11 @@
+Run tests for a specific crate. Usage: /test-crate <crate-name>
+
+Run `cargo test -p $ARGUMENTS` and report results. If no crate name is provided, ask which crate to test from the workspace members:
+
+- edgezero-core
+- edgezero-macros
+- edgezero-adapter
+- edgezero-adapter-fastly
+- edgezero-adapter-cloudflare
+- edgezero-adapter-axum
+- edgezero-cli

.claude/commands/verify.md

@@ -0,0 +1,9 @@
+Prove that the current changes work correctly. Compare behavior between the current branch and main:
+
+1. Run `git diff main...HEAD --stat` to understand the scope of changes
+2. Run `cargo test --workspace --all-targets` to verify tests pass
+3. Run `cargo clippy --workspace --all-targets --all-features -- -D warnings` to verify no lint warnings
+4. If changes touch handlers/routing, run the dev server and test affected endpoints
+5. If changes touch adapters, run targeted tests: `cargo test -p <adapter-crate>`
+
+Summarize what works, what doesn't, and any risks. Don't say "it works" without evidence.

.gitignore

@@ -11,7 +11,8 @@ target/
 .DS_Store
 
 # Editors
-.claude
+.claude/*
+!.claude/commands/
 .idea
 .specstory
 .vscode/*

AGENTS.md

@@ -1,83 +1,25 @@
 # Agent Notes
 
-This repository is currently tended by an automated assistant (Codex) that helps
-craft the EdgeZero workspace. A few conventions are worth remembering when the
-agent is asked to make additional changes:
-
-## Standard Workflow
-
-1. First think through the problem, read the codebase for relevant files, and write a plan to the file: TODO.md. If the TODO.md file does not yet exist, go ahead and create it.
-2. The plan should have a list of todo items that you can check off as you complete them
-3. Before you begin working, show me the full plan of the work to be done and get my approval before commencing any coding work
-4. Then, begin working on the todo items, marking them as complete as you go.
-5. As you complete each todo item, give me a high level explanation of what changes you made
-6. If you cannot complete a todo, mark it as blocked in TODO.md and explain why.
-7. Make every task and code change you do as simple as possible. We want to avoid making any massive or complex changes. Every change should impact as little code as possible.
-8. Finally, add a review section to the TODO.md file with a summary of the changes you made, assumptions made, any unresolved issues or errors you couldn't fix, and any other relevant information. Add the date and time showing when the job was finished.
-
-## Tools
-
-### Context7 MCP
-
-- Use Context7 MCP to supplement local codebase knowledge with up-to-date library documentation and coding examples
-
-### Playwright MCP
-
-- use the Playwright MCP in order to check and validate any user interface changes you make
-- you can also use this MCP to check the web browser console for any error messages which may come up
-- iterate up to a maximum of 5 times for any one particular feature; an iteration = one cycle of code change + Playwright re-run
-- if you can't get the feature to work after 5 iterations then you're likely stuck in a loop and you should stop and let me know that you've hit your max of 5 iterations for that feature
-- Save any failing test cases or console errors in a debug.md file so we can review them together.
-
-## Testing
-
-always run `cargo test` after touching code. Individual crates
-can be scoped via `cargo test -p <crate-name>` when a partial run is faster.
-
-## Routing syntax
-
-route definitions must use matchit 0.8 style
-parameters (`/resource/{id}` or `/static/{*rest}`); we intentionally do not
-support legacy `:id` syntax.
-
-## Adapters – Fastly and Cloudflare adapters expose request context helpers
-
-in `context.rs` and translation helpers in `request.rs` / `response.rs`.
-Tests for adapter behaviour live beside those modules.
-
-## Examples
-
-the demo crates under `examples/app-demo/` share router
-logic via `app-demo-core`. Local smoke testing flows through
-`cargo run -p edgezero-cli --features dev-example -- dev`, which serves the demo
-router on http://127.0.0.1:8787. Build provider targets with
-`app-demo-adapter-fastly` / `app-demo-adapter-cloudflare` when you need Fastly
-or Cloudflare binaries.
-
-## Style– prefer colocating tests with implementation modules, favour
-
-async/await-friendly code that compiles to Wasm, and avoid runtime-specific
-dependencies like Tokio.
-
-- Use the HTTP aliases exported from `edgezero_core` (`Method`, `StatusCode`,
-  `HeaderMap`, etc.) instead of importing types directly from the `http` crate.
-- Prefer the `#[edgezero_core::action]` macro for new handlers so extractor
-  arguments (`Json<T>`, `Query<T>`, `ValidatedJson<T>`, etc.) stay declarative.
-  Extractors live under `edgezero_core::` and integrate with the `validator`
-  crate for `Validated*` variants.
-
-## Logging
-
-- Platform logging helpers live in the adapters: use `edgezero_adapter_fastly::init_logger()` / `edgezero_adapter_cloudflare::init_logger()` and
-  fall back to something like `simple_logger` for local builds.
-
-## Proxy helpers
-
-- Use `edgezero_core::proxy::ProxyService` with the adapter clients
-  (`edgezero_adapter_fastly::FastlyProxyClient`, `edgezero_adapter_cloudflare::CloudflareProxyClient`)
-  when wiring proxy routes so streaming and compression handling stay consistent.
-- Keep synthetic local proxy behaviour lightweight so examples can run without
-  Fastly/Cloudflare credentials; rely on the proxy test clients in `edgezero-core` for unit coverage.
-
-When in doubt, keep changes minimal, document behaviour in `README.md`, and
-ensure the workspace stays Wasm-friendly.
+**Before doing anything else, read `CLAUDE.md` in this repository root.** It
+contains all project conventions, coding standards, build commands, workflow
+rules, and CI requirements. Everything in `CLAUDE.md` applies to you.
+
+This file exists because Codex looks for `AGENTS.md` by convention. All shared
+rules are maintained in `CLAUDE.md` to avoid duplication and drift. If you
+cannot access `CLAUDE.md`, the critical rules are summarized below as a
+fallback.
+
+## Fallback Summary
+
+If `CLAUDE.md` is unavailable, these are the minimum rules:
+
+1. Write a plan to `TODO.md` before coding. Get approval first.
+2. Keep changes minimal — every change should impact as little code as possible.
+3. Run `cargo test` after every code change.
+4. Run `cargo fmt --all -- --check` and `cargo clippy --workspace --all-targets --all-features -- -D warnings`.
+5. Run `cargo check --workspace --all-targets --features "fastly cloudflare"`.
+6. Use matchit `{id}` syntax, never legacy `:id`.
+7. Use `#[action]` macro for handlers, import types from `edgezero_core`.
+8. Don't add Tokio deps to core/adapter crates — WASM compatibility first.
+9. Append a review section to `TODO.md` when done (summary, assumptions,
+   unresolved issues, UTC timestamp).