agent-fleet/AGENTS.md

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