devflow-core 1.2.0

# DevFlow

**Agent-agnostic development workflow automation.**

[![CI](https://github.com/denniyahh/devflow/actions/workflows/ci.yml/badge.svg)](https://github.com/denniyahh/devflow/actions/workflows/ci.yml)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-stable-orange.svg)](https://www.rust-lang.org)

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

```bash
# 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](ARCHITECTURE.md#extension-points--adding-an-agent)).
- **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:

| Layer | Method | Authority |
|---|---|---|
| 1. Marker | Parse `DEVFLOW_RESULT` JSON from stdout | Authoritative |
| 2. Exit code + commits | Exit 0 **and** commits on the feature branch = success; otherwise failed | Fallback |
| 3. Commit heuristic | Exit code unknown: commits exist = probable success (with warning) | Last resort |

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

## Commands

### Core Workflow

| Command | Description |
|---|---|
| `devflow start --phase N --agent X [--mode auto\|supervise] [--no-worktree]` | Begin a phase: branch/worktree → launch agent → monitor pipeline |
| `devflow status` | Show current stage, phase, agent, PID, age |
| `devflow list` | List all feature branches with divergence from develop |
| `devflow gate list\|approve\|reject <phase> [--stage STAGE] [--note "..."]` | Inspect and answer human gates — the pause points where the workflow waits for approval |
| `devflow logs [--phase N] [--follow] [--stderr]` | Print or follow an agent's captured output for a phase |
| `devflow cleanup` | Remove phase worktrees and their feature branches |

### Multi-Agent

| Command | Description |
|---|---|
| `devflow parallel --phases 7,8 [--agents claude,codex]` | Run multiple phases concurrently in isolated worktrees |
| `devflow sequentagent --phase 7 --agents claude,codex` | Run two agents sequentially on one phase with worktree isolation |
| `devflow reference [--refresh]` | Create a static reference worktree for multi-agent handoff |

### Quality

| Command | Description |
|---|---|
| `devflow test` | Run local quality checks: `cargo test`, clippy, and `fmt --check` |

### Setup & Recovery

| Command | Description |
|---|---|
| `devflow recover` | Inspect or clean up stale/abandoned workflow state |
| `devflow doctor` | Check that required tools and agents are installed |

## 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:

| Flag | Description |
|---|---|
| `--phase N` | Phase number to execute |
| `--agent claude\|codex\|opencode` | Agent to launch |
| `--mode auto\|supervise` | `auto` advances through Ship unattended; `supervise` also gates at Validate for human review |
| `--no-worktree` | Run directly in the primary checkout instead of an isolated worktree (worktree is the default) |

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

| Agent | CLI | Flag |
|---|---|---|
| Claude Code | `claude` | `--agent claude` |
| OpenAI Codex | `codex` | `--agent codex` |
| OpenCode | `opencode` | `--agent opencode` |

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](DEPENDENCIES.md) for the full matrix.

## Installation

```bash
# 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:

```bash
devflow doctor
```

## Documentation

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

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome.

## License

MIT OR Apache-2.0 — see [LICENSE](LICENSE).