DevFlow

An opinionated take on AI-driven development — not a universal agent platform, just the workflow that actually holds up under real, unattended use.

DevFlow bakes in the specific methods and guardrails one developer converged on after running coding agents against real work: worktree isolation, gated human checkpoints, never-silent failure handling, and durable state that survives a crash or a kill -9. It isn't trying to be a lowest-common-denominator platform for every agent and every workflow — it's the system that solved the pain points that kept recurring with looser, more "flexible" tooling.

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.

Where the automation stops. Steps 1–6 and 9 are automated end to end. The release cut itself — opening the develop → main PR, tagging, and publishing — is deliberately still manual; devflow release --check runs the preflight but does not execute the release.

If you squash-merge develop → main, be aware that the squash commit has no parent link back to develop, so develop never learns main moved and your next release will conflict against a stale merge-base. devflow release --check detects this (origin/main is NOT an ancestor of HEAD), but DevFlow does not yet ship the repair. Until it does, merge main back into develop after each release with a real merge commit:

git checkout develop
git merge -X ours origin/main      # -X ours: develop's content wins; history-link only
# verify this changed nothing:
git diff --stat origin/main..HEAD  # inspect before pushing

Confirm it worked with git merge-base --is-ancestor origin/main origin/develop. A real merge is required — squashing this step collapses the two parents and discards the link, which is the whole point.

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:

• Opinionated, not universal — Claude Code, Codex, and OpenCode are supported today through a shared AgentAdapter trait, but DevFlow is built around specific workflow decisions, not a lowest-common-denominator abstraction over every agent. Full agent-neutral modularity is a deliberate future direction, not a current guarantee (adding a supported agent today 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.
• Four-layer evaluation — operator-declared external post-conditions can fail a stage before agent-controlled signals; ordinary work then uses DEVFLOW_RESULT, exit code + commit count, and the final commit heuristic.
• Per-stage prompts — stage_prompt(stage, phase) builds a dedicated prompt per pipeline stage (not one shared instruction template); the same prompt text is used across agents for a given stage, with adapter-specific logic limited to CLI launch flags, not prompt content.

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 four layers:

Rate-limit detection: if an agent's stdout contains rate-limit messages (429), DevFlow writes a per-phase .devflow/cron-instructions-{phase:02}.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 init step is required. Workflow choices remain CLI flags; an optional minimal devflow.toml configures reliability knobs only.

capture_retention = 5
review_angles = ["doc accuracy", "security", "CI correctness", "external state"]
external_verify_enabled = true

PLAN-declared verification shell is agent-writable and requires explicit operator authorization bound to the reviewed bytes, for example DEVFLOW_TRUST_EXTERNAL_VERIFY='["test -f shipped.txt"]'. Changed commands fail closed without execution.

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.

DEVFLOW_CAPTURE_RETENTION, DEVFLOW_REVIEW_ANGLES, and DEVFLOW_EXTERNAL_VERIFY_ENABLED override the corresponding TOML values.

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.