DevFlow

CLI-driven progressive disclosure workflow. Advance one verified step at a time.

Overview

DevFlow enforces a disciplined development process where each step must be completed and verified before advancing. It uses TOML workflow definitions, gate-based verification, and a devflow done checkpoint system.

When to Use

• Project has .devflow/workflows/*.toml files
• You see devflow commands in project docs
• Task requires writing requirements, design docs, or code in stages
• You need gate-based verification (tests must pass before advancing)

When NOT to use: Project has no .devflow/ directory — this is a standard project, use normal development.

Quick Start

devflow --help          # Verify CLI is installed

If devflow is not found, install first:

pip install agent-devflow     # From PyPI

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).

Built-in Workflows

Cross-workflow references use WORKFLOW-ID:STEP-ID format.

5 Iron Laws

Common Mistakes

Project Context

Language: {{ project.language }} Stack: {{ project.stack }} Version: {{ project.version }}

Constraints

{% if constraints.zero_warnings %}- ZERO warnings — All builds must have zero warnings{% endif %} {% if constraints.zero_mocks %}- ZERO mocks — Use real instances only in tests{% endif %} {% if constraints.nullable %}- Nullable enabled — Use nullable reference types{% endif %}

Project Structure

{{ project.name }}/
├── .devflow/              # DevFlow configuration
│   ├── workflows/         # Workflow definitions (TOML)
│   ├── prompts/           # Reusable prompt files
│   ├── config.toml        # Project config
│   └── state.toml         # Current state (gitignored)
├── {{ paths.src }}/       # Source code
├── {{ paths.tests }}/     # Tests
├── {{ paths.docs }}/      # Documentation
│   ├── requirements/      # REQ files
│   ├── features/          # FEAT files
│   ├── superpowers/specs/ # Design docs
│   ├── superpowers/plans/ # Implementation plans
│   ├── evidence/          # Verification evidence
│   ├── debug/             # Debug analysis
│   └── completion/        # Workflow completion summaries
└── SKILL.md               # This file

Commands Reference

# Build
{{ commands.build }}

# Test
{{ commands.test }}
{{ commands.test_unit }}
{{ commands.test_integration }}

# Lint
{{ commands.lint }}

Generated by DevFlow v2.0