ferrus

ferrus is a deterministic orchestration system for real software execution.

Instead of treating agents as autonomous chat participants, ferrus models them as workers in a controlled lifecycle — with explicit state, enforced transitions, and restartable execution.

Projects are registered locally and maintain isolated runtime state, task execution, and recovery metadata through a dedicated orchestration database.

Design principles

• Explicit state machines over conversational flow
• Restartable execution
• Stateless agents
• Human-in-the-loop orchestration
• Deterministic lifecycle transitions
• Recoverable runtime state

Runtime model

ferrus operates as a Supervisor → Executor → Reviewer loop.

Tasks execute independently through isolated runtime runs tracked by a local orchestration database. Runtime state, task metadata, retries, review cycles, and recovery information remain explicit and recoverable across crashes or interrupted sessions.

Repository state lives under .ferrus/, while global project metadata and runtime coordination are maintained separately in the local ferrus registry.

State machine

Idle
→ Executing
→ Reviewing
→ Complete / Failed

Additional runtime states support consultation, human interaction, retries, review cycles, and recovery flows.

The execution model is designed around deterministic transitions rather than autonomous long-running sessions.

Why it exists

Most AI coding workflows are fundamentally conversational.

That works well for exploration, but becomes difficult to reason about once tasks span retries, reviews, crashes, partial execution, or long-running implementation cycles.

ferrus explores a different direction: treating agent workflows as explicit runtime systems.

The goal is not to simulate autonomous developers, but to build predictable orchestration around real software work.