Devflow

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

| Command | Purpose | |---------|---------| | devflow current | Show current step instruction | | devflow done | Check gates and advance | | devflow back | Go back one step | | devflow approve ITEM | Mark item as user-approved | | devflow set KEY VALUE | Set state variable | | devflow list-workflows | List available workflows | | devflow select-workflow ID | Select and start a workflow | | devflow run | Start autonomous Ralph Loop |

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

| Workflow | Steps | |----------|-------| | MODE-A (Feature) | req-create -> req-approve -> brainstorm -> write-plan -> implement-sdd -> code-review -> test-run -> verify -> finish | | MODE-B (Debug) | debug-root-cause -> debug-pattern -> debug-hypothesis -> debug-fix -> debug-question -> debug-verify -> debug-finish -> (auto -> MODE-A:write-plan) |

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

5 Iron Laws

| # | Law | Severity | |---|-----|----------| | 1 | Read using-superpowers skill first | Rigid | | 2 | TDD: Test before code | Rigid | | 3 | Verify before claim | Rigid | | 4 | Root cause before fix | Strong | | 5 | Debug -> Repeat full cycle | Strong |

Common Mistakes

| Mistake | Fix | |---------|-----| | Writing code before devflow current | Stop. Run devflow current first | | Creating files for future steps | Only create what the current step asks for | | Skipping devflow done | All advancement must go through devflow done | | Ignoring gate failures | Fix the issue, then devflow done again |

Project Context

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

Constraints

{% if constraints.zerowarnings %}- ZERO warnings — All builds must have zero warnings{% endif %} {% if constraints.zeromocks %}- 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dqz00116
• Source: Dqz00116/skill-lib
• License: MIT

Install and usage instructions live in the source repository linked above.