Crate devflow_core

Expand description

DevFlow — Agent-agnostic development workflow automation.

The core library returns structured types and performs workflow mechanics; frontends such as the CLI format output for humans or machines.

§Logging

DevFlow uses the tracing crate for structured, level-aware logging. All log output goes to stderr so stdout remains available for agent output, structured results, and machine-readable data.

§Log Levels

Set the RUST_LOG environment variable to control verbosity:

Level	Use case
`error`	Fatal conditions that abort the workflow
`warn`	Unexpected but recoverable conditions (e.g., force operations)
`info`	Normal workflow events (state transitions, git operations)
`debug`	Detailed I/O and git commands
`trace`	Full tracing subscriber internals

RUST_LOG=info devflow start --phase 3 --agent claude --mode auto   # Default: shows state transitions
RUST_LOG=debug devflow start --phase 3 --agent claude --mode auto  # Also shows git commands and file I/O
RUST_LOG=warn devflow status                           # Suppress info, show only warnings

The default log level is info when RUST_LOG is not set.

§JSON Output

Set DEVFLOW_LOG_FORMAT=json for machine-readable JSON log lines on stderr:

DEVFLOW_LOG_FORMAT=json RUST_LOG=info devflow status 2>log.json

Each line is a JSON object with timestamp, level, fields, and target keys. Structured events like step_entered/step_exited include phase and step-name fields.

§Structured Events

State machine transitions emit structured tracing events:

step_exited — emitted when leaving a step, with phase and step name
step_entered — emitted when entering a step, with phase and step name

These events are at INFO level and include the phase number as a named field, making them filterable and parseable by external tooling.

Re-exports§

pub use mode::Mode;
pub use stage::Stage;
pub use state::AgentKind;
pub use state::State;

Modules§

agent: Agent process helpers.
agent_result: Agent completion detection — parses DEVFLOW_RESULT markers and evaluates exit codes to determine whether a coding agent succeeded or failed.
agents: Agent adapter trait and implementations.
config: Git-flow branch model.
events: Append-only workflow event log — .devflow/events.jsonl.
gates: Gate file protocol — the handoff between DevFlow and a human (via Hermes).
git: Git-flow operations implemented with plain git commands.
hooks: Stage-transition hooks.
lock: File-based lock to prevent concurrent devflow advance invocations for the same phase.
mode: Execution mode and the mode-driven gate decision.
monitor: Background monitor daemon.
prompt: Stage-specific agent prompts.
recover: State recovery and stale-state detection.
ship: Ship bookkeeping.
stage: DevFlow stage machine.
state: DevFlow state machine.
version: Hybrid Git-based SemVer.
workflow: Workflow state persistence helpers.
worktree: Git worktree operations implemented with plain git worktree commands.