ferrus AGENTS.md

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. Coordination uses MCP as an implementation detail.

Licensed under Apache 2.0.

Runtime behavior for a Ferrus-managed agent is defined by its initial prompt and exposed MCP 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.

Use em dashes sparingly.

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.

Build and Test

cargo build                        # compile
cargo build --release              # optimized build
cargo test                         # run all tests
cargo test <name>                  # run a single test by name
cargo clippy -- -D warnings        # lint (warnings are errors)
cargo fmt                          # format
cargo fmt --check                  # check formatting without writing
cargo check                        # fast type-check

Before submitting, cargo clippy -- -D warnings, cargo fmt --check, and cargo test must all pass.