diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..0fbbc34
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,43 @@
+# Agent Fleet - Codex Working Instructions
+
+## Project Overview
+Agent Fleet Platform: a multi-agent orchestration system built with Rust + axum.
+- Forgejo (Issue/PR) = task source of truth
+- Matrix = real-time ChatOps
+- Orchestrator = single binary (Rust + zigbuild)
+
+## Code Style
+- Rust 2024 edition
+- Use `thiserror` for error types
+- Use `serde` for serialization
+- All DB operations go through `EventStore` methods (never expose `conn` directly outside EventStore)
+- `Arc<Mutex<EventStore>>` is the shared state pattern
+- axum handlers use `State<Arc<Mutex<EventStore>>>` or custom AppState
+
+## Architecture
+- `src/core/` - business logic (models, event_store, state_machine, task_queue, timeout, retry)
+- `src/api/` - axum HTTP handlers
+- `src/integrations/` - Forgejo API client, Matrix bot
+- `src/adapters/` - Agent adapter interface + concrete implementations
+- `src/config.rs` - TOML config loading
+
+## Current State
+- Core data models, event store, state machine, task queue, timeout checker, retry policy are implemented
+- API handlers in `main.rs` are stubs returning "TODO"
+- Need to implement: Agent Registry API, Receipt API, Forgejo webhook handler, Matrix bot, Agent adapters
+
+## Key Files
+- `openspec/changes/agent-fleet-platform/specs/` - per-capability specs with WHEN/THEN scenarios
+- `openspec/changes/agent-fleet-platform/design.md` - architecture decisions
+- `openspec/changes/agent-fleet-platform/tasks.md` - implementation checklist
+
+## Forgejo Config
+- URL: https://git.0x08.org
+- Token: see .env.local (not in git)
+- Webhook secret: TBD
+
+## Important
+- Always run `cargo check` after changes
+- Always run `cargo test` after adding tests
+- Do not modify files in `openspec/` directory
+- Keep changes small and focused