# 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