DevFlow

Agent-agnostic development workflow automation.

DevFlow automates the mechanical steps of AI-assisted development — branching, monitoring, verifying, documenting, shipping — so you and your coding agents can focus on building.

The Problem

You use AI coding agents (Claude Code, Codex, OpenCode) to build features. But every phase requires the same tedious mechanical work:

1. Create a feature branch
2. Launch the agent with the right command
3. Wait for it to finish
4. Run tests and lints
5. Update docs
6. Bump the version
7. Create a release branch and PR
8. Merge to main/develop
9. Clean up merged branches

DevFlow handles all of this. You say devflow start --phase 3 --agent claude --mode auto and walk away.

Quick Start

# Install
curl -fsSL https://raw.githubusercontent.com/denniyahh/devflow/main/scripts/install.sh | bash

# Or build from source
cargo install devflow

# Start working on Phase 3 with Claude Code in auto mode — no init step required
cd your-project
devflow start --phase 3 --agent claude --mode auto

# Check status anytime
devflow status

Pipeline

Define → Plan → Code → Validate → Ship

The 5-stage pipeline is driven by GSD-native execution. State is persisted per-phase to .devflow/state-NN.json and survives restarts. --mode auto advances through Ship unattended (gating only on repeated Validate failure or an unexpected stage crash); --mode supervise also gates at Validate for human review.

Architecture

crates/
├── devflow-core/     ← Library: state machine, config, git, versioning, agent adapters
└── devflow-cli/      ← Binary: thin CLI wrapper around core

Key design decisions:

• Agent-agnostic — Claude, Codex, and OpenCode all implement the same Agent trait. Adding a new agent follows a small checklist (see ARCHITECTURE.md).
• Worktree isolation by default — agents run in isolated git worktrees (.worktrees/phase-NN/) unless --no-worktree is passed, preventing cross-phase contamination.
• Monitor daemon — optional background process detects agent completion and auto-advances the state machine. No cron, no polling, no tmux.
• Three-layer evaluation — agents self-report via DEVFLOW_RESULT markers in stdout; fallback layers: exit code + commit count, then a commit-count heuristic.
• Shared prompts — all agents receive the same prompt via phase_prompt(). No agent-specific prompt logic.

Agent Protocol

Agents communicate completion through the DEVFLOW_RESULT marker in stdout:

DEVFLOW_RESULT: {"status": "success", "commits": 3, "summary": "added tests"}

The Validate stage additionally requires a verdict field ("pass" or "gaps") — a bare status: success is not enough to advance to Ship; only verdict: "pass" is.

DevFlow evaluates agent output in three layers:

Rate-limit detection: if an agent's stdout contains rate-limit messages (429), DevFlow writes .devflow/cron-instructions.json for rescheduling.

Commands

Core Workflow

Multi-Agent

Quality

Setup & Recovery

Configuration

DevFlow stores runtime state per-phase in .devflow/state-NN.json (git-ignored). No config file or init step is required — all workflow options are supplied as CLI flags to devflow start.

Key flags:

Gate responses and unattended-run notifications are file-based: a fired gate writes .devflow/gates/{phase}-{stage}.json and (if DEVFLOW_GATE_NOTIFY_CMD is set) runs that command with DEVFLOW_GATE_PHASE/DEVFLOW_GATE_STAGE/DEVFLOW_GATE_CONTEXT in its environment. Respond by writing .devflow/gates/{phase}-{stage}.response.json with {"approved": true|false, "note": "..."}. The poll timeout defaults to 7 days and is configurable via DEVFLOW_GATE_TIMEOUT_SECS.

Supported Agents

Agents must be installed separately. Run devflow doctor to verify availability.

Requirements

• Rust stable, edition 2024 (build from source) — see rust-toolchain.toml
• git 2.30+
• gh CLI 2.0+ (for PR creation, shipping)
• A POSIX shell (sh/bash)

Agents (Claude Code, Codex, OpenCode) must be installed separately. See DEPENDENCIES.md for the full matrix.

Installation

# Option 1: One-command install (recommended)
curl -fsSL https://raw.githubusercontent.com/denniyahh/devflow/main/scripts/install.sh | bash

# Option 2: Cargo install
cargo install devflow

# Option 3: Build from source
git clone https://github.com/denniyahh/devflow.git
cd devflow
cargo build --release
cp target/release/devflow ~/.local/bin/

Verify your setup:

devflow doctor

Documentation

• DEPENDENCIES.md — full dependency matrix
• ARCHITECTURE.md — design documentation
• OPERATIONS.md — operator reference (gate protocol, env vars, .devflow/ file inventory)
• CONTRIBUTING.md — how to contribute
• CHANGELOG.md — version history

Contributing

See CONTRIBUTING.md. PRs welcome.

License

MIT OR Apache-2.0 — see LICENSE.