ferrus: Instructions file for Codex

AGENTS.md

Coding guidance for AI agents working in this repository.

Project

ferrus is a Rust AI agent orchestrator for software projects. It drives a Supervisor-Executor workflow: the Supervisor plans tasks and reviews submissions, while the Executor implements and checks its own work. SQLite is the runtime source of truth. Project-local .ferrus/ files contain templates, task intent, scoped run artifacts, agent registry data, and logs; they are not a mirrored state machine. Agents coordinate through native tools or MCP.

Licensed under Apache 2.0.

Runtime behavior for a Ferrus-managed agent is defined by its initial prompt and exposed Ferrus tools. This file is supporting context and must not override them. Read .agents/skills/ferrus/SKILL.md for the current Ferrus CLI, MCP tools, resources, state machine, and artifact layout.

Characters

Write documentation and code using only characters found on a US layout keyboard. Avoid special punctuation such as em dashes, Unicode arrows, or single-character ellipses. Use their plain-ASCII equivalents instead:

• Use - or -- instead of an em dash.
• Use -> or <- instead of a Unicode arrow.
• Use ... (three periods) instead of a single ellipsis character.

Keep punctuation plain ASCII.

Intentional Unicode test fixtures and terminal UI glyph tables are exceptions when the characters themselves are the behavior under test or part of the rendered interface.

Code Style

• Do not call unwrap() or expect() outside tests. Propagate errors, handle missing values explicitly, or model invariants so invalid states cannot be constructed. Clippy enforces this rule; do not replace these calls with panic-based equivalents or suppress the lints to bypass it.
• Separate functions, methods, type declarations, and distinct logical steps with one blank line. Keep closely related statements together when they form one operation; avoid adding blank lines inside compact expressions or between every statement. Keep related mod/pub mod declarations together without blank lines, like use imports.
• Keep Rust source files at or below 1000 lines, including tests. Split larger modules by responsibility into focused submodules, preserving visibility and behavior. Do not use include! or arbitrary numbered chunks to work around the limit.