Devflow

DevFlow

DevFlow is a CLI-driven progressive disclosure workflow. You advance one verified step at a time.

When to Use

• Task requires writing requirements, design docs, or code in stages
• You need gate-based verification (tests must pass before advancing)
• User mentions devflow commands or .devflow/ directory
• Structured feature development or systematic debugging is needed

When NOT to use: The task is a simple one-off change that doesn't need staged workflow.

Quick Start

devflow --help          # Verify CLI is installed

If devflow is not found, install first:

pip install agent-devflow     # From PyPI

Or from source:

pip install -e .

If the project does not have a .devflow/ directory, initialize it:

devflow init --language <language> --name "<project-name>"

Then start the workflow:

devflow list-workflows              # See available workflows
devflow select-workflow MODE-A      # Pick one
devflow current                     # Read current step

Core Loop (ALWAYS follow this)

1. devflow current     → Read what to do
2. Execute the step    → Write code, create docs, run tests
3. devflow done        → Check gates → advance or retry
4. Repeat until "Workflow complete!"

Core rule: Only advance through devflow done. Never skip steps. Never create files for future steps.

Commands

Gate Types

Gates block advancement until satisfied:

• file_exists:path — File must exist
• file_contains:path:content — File must contain text
• command_success:{test_command} — Command exits 0
• user_approved:ITEM — Requires devflow approve ITEM
• state_set:var — State variable must be set

Fail Routes

When gates fail, the workflow may route based on failure count:

fails 1-2 → retry or fallback step
fails 3+  → escalate to human

Fail count persists across visits (resets only when gates pass).

Common Mistakes