Language: English | 中文

dev-flow

Engineering discipline for coding agents.

Small, focused, and opinionated. dev-flow gives coding agents structure — lightweight documents, disciplined phases, and hard constraints that turn raw coding ability into reliable engineering delivery.

Quick Start

One-Line Install

# npm (Node.js 16+, auto-downloads platform binary + runs dow setup)
npm install -g @xin_yue/dev-flow

# Cargo (Rust toolchain required)
cargo install dev-flow &amp;&amp; dow setup

# macOS arm64 / Linux x86_64 / Linux aarch64
brew install daphnee-ovo/tap/dev-flow &amp;&amp; dow setup

# Linux / macOS / WSL
curl -fsSL https://raw.githubusercontent.com/daphnee-ovo/dev-flow/main/install/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/daphnee-ovo/dev-flow/main/install/install.ps1 | iex

The install scripts run dow setup automatically. For Cargo and Homebrew installs, dow setup registers dev-flow with your preferred agent (Claude Code, Codex, Kiro, or Pi). Project initialization happens later with /init inside the target project.

First Run

cd your-project

Then ask your coding agent:

/init
/task

dev-flow creates a .dev-doc/ workspace, tracks the current phase in STATUS.yaml, generates structured task files, and uses hooks to remind or block the agent when workflow rules are violated.

See examples/quickstart-demo.md for a concrete before/after walkthrough, or inspect examples/sample-project for static .dev-doc output.

Why dev-flow

Coding agents are good at editing code, but weak at keeping requirements, implementation, tests, and delivery state aligned over a long task. dev-flow adds a small workflow layer around Claude Code and Codex CLI:

clarify requirements before changing code
split design, task planning, implementation, and QA into explicit phases
keep .dev-doc/ synchronized with the real project state
use hooks to stop agents from skipping checks, writing to unsafe temp paths, or losing changelog context
archive each delivery so later iterations have traceable history

Use it when an agent is doing feature work, refactors, audits, or multi-step fixes that need more discipline than a single prompt.

When Not To Use It

dev-flow is intentionally opinionated. It is probably too much for one-line edits, throwaway scripts, or projects where you do not want workflow files in the repository. It is useful when the cost of agent drift is higher than the cost of lightweight process.

Supported Agents

Agent	Status	Manual setup
Claude Code	Supported	`dow setup --agent claude`
Codex	Supported	`dow setup --agent codex`
Kiro-Cli	Supported	`dow setup --agent kiro`
Pi	Testing	`dow setup --agent pi`

Agent Compatibility

All four agents deliver the same workflow experience — identical commands, hooks, sub-agents, and state management. The only differences are platform-level implementation details:

Aspect	Claude Code	Codex CLI / App	Kiro	Pi
Command interface	Slash commands	Skill commands	Skill commands	Skill commands
Sub-agent invocation	`Agent` tool	`spawn_agent`	subagent	`Agent` tool
Project instructions	`CLAUDE.md`	`AGENTS.md`	`.kiro/steering/`	`AGENTS.md`

Kiro: Enabling Hooks

Kiro's default agent does not support hook configuration. After setup, set the dev-flow agent as default:

kiro-cli agent set-default --name dev-flow

dow setup --agent kiro reminds you of this step. Without it, hooks will not fire.

Philosophy

dev-flow is not trying to become a large all-in-one project management system. Its job is to stay lightweight while helping agents clarify ideas before implementation and giving them enough structure and constraints to work like a disciplined engineering team.

Core principles:

Think before building — clarify goals, boundaries, approach, and acceptance criteria before changing code.
Lightweight — keep only the documents and commands that move delivery forward.
Structured — PRD, SPEC, TASK, issues, and archives use stable formats that are easy to inspect and reuse.
Constrained — phases, hooks, checks, and task loops prevent agents from skipping requirements, specs, verification, and delivery gates.
Goal-necessary — every capability must answer whether it serves the current goal. Keep necessary constraints; do not import ceremony.
Synchronized — process documents must stay aligned with the real project state: code, tasks, versions, tests, and iterations. Once management docs drift, they become noise.
Mode-aware — rapid validation and long-term engineering need different gates. MVP work can focus on running functionality and obvious bugs; standard development can raise testing, review, and release requirements.

Commands

Command	Description
`/init`	Initialize project (create dev-doc, select mode, validate specs)
`/brainstorm`	Collaborative requirement exploration & design before implementation
`/prd`	PRD phase — main agent produces PRD.md, then audit agent reviews
`/spec`	SPEC phase — main agent produces SPEC.md, then audit agent reviews
`/task`	TASK phase — decompose into task files (challenger agent for complex cases)
`/issue`	Manually create issue files
`/test`	Run dow test for full project verification
`/fix`	User-triggered workflow to read, claim, fix, verify, and close open issues
`/status`	Report current project status & progress
`/check`	Check if dev work is synced with .dev-doc
`/iterate`	Start new iteration after delivery (archive + reset)
`/mode`	Select development mode (full/quick/fast/mvp; audit is auto-triggered)

Development Modes

Mode	Flow	Use Case
`full`	prd → spec → task → dev → test → iterate	New projects, unclear requirements
`quick`	spec → task → dev → test → iterate	Clear requirements, feature development
`fast`	task → dev → test → iterate	Small changes, known technical approach
`mvp`	spec → task → dev → iterate	Quick idea validation, skip TEST

> audit mode is triggered automatically when issues are created outside DEV phase. Format: audit/. Auto-restores after iterate.

Core Features

Role Isolation

Main agent drives each phase directly; independent audit/challenger sub-agents review the output:

Phase	Execution	Review
BRAINSTORM	Main agent	brainstorm-audit-agent
PRD	Main agent	prd-audit-agent
SPEC	Main agent	spec-audit-agent
TASK	Main agent	task-challenger-agent (complex cases)
DEV	Main agent	—
TEST	`dow test` CLI	test-agent (failure analysis)

Automated Hooks

No manual operations needed:

Context injection — injects current phase status and spec reminders on every message
Task close test gate — dow task done TASK-ID runs dow test TASK-ID before changing the Task file
Doc sync check — reminds you to sync documentation when code changes
Changelog save — automatically saves changelog on conversation end
System temp blocking — prevents writing to system temp directories; project-local tmp and temp are allowed, and new projects default to tmp

Document-Driven Development

The plugin maintains a .dev-doc/ directory in your project, organized by branch:

.dev-doc/
├── archive.db             # SQLite archive queried by `dow archive ...`
├── preIterate.ci          # Pre-iteration CI steps (optional)
└── /              # Current branch workflow documents (main/beta/...)
    ├── STATUS.yaml        # Project status
    ├── CHANGELOG.md       # Session changelog (append-only)
    ├── BRAINSTORM.md      # Brainstorming notes
    ├── PRD.md             # Product requirements
    ├── SPEC.md            # Technical specification
    ├── task/              # Task files (task__.md)
    └── issue/             # Issue tracking (issue___.md)

Iteration Management

/iterate archives completed tasks, closed issues, changelog entries, and phase documents including BRAINSTORM, PRD, and SPEC into .dev-doc/archive.db, then starts a new development cycle. Use dow archive list/show/tasks/issues/doc to query historical iterations.

If .dev-doc/preIterate.ci exists, dow iterate --confirm runs its steps before archive, commit, tag, and bump. A failing step stops the whole iteration. Supported steps are sync-version: for explicit Cargo/npm/uv project manifests and run: for project-local checks, lockfile updates, or generators.

run: bash tests/test_all.sh
sync-version: dow/Cargo.toml
sync-version: npm/dev-flow/package.json
run: cargo update -p dev-flow --manifest-path dow/Cargo.toml

dow rollback --version is the inverse of iterate — it restores archived tasks, issues, and documents from the database, handles file sequence conflicts, and marks the iteration as rolled back. Use dow rollback --list to see rollback-able versions.

Web Dashboard & Dependency Graph

dow dashboard launches a local web dashboard with:

Kanban board — tasks grouped by status (In Progress / Pending / Done), issues by (In Progress / Open / Closed)
Dependency graph — visualizes explicit and implicit task/issue dependencies using D3 force simulation. Implicit edges are inferred from file intersections between tasks. In-progress nodes blink.
Document viewer — browse BRAINSTORM, PRD, SPEC docs inline
Filtering — filter by priority (P0/P1/P2) and status
Status overview — current phase, mode, and iteration state

Claim System

dow claim lets agents claim a task or issue before working on it:

Dependency check — blocks claiming if upstream dependencies are unresolved
File scope enforcement — guard hook warns when writing outside declared files
Claim lock — stored in .dev-doc//claim.lock, prevents concurrent claims
In Progress visibility — claimed items appear in the dashboard's In Progress column

Issue Tracking

Issues support a full lifecycle beyond tasks:

Nested file scope: create/update use --file '{"create":[],"modify":["src/a.rs"]}'; stdin JSON uses a top-level files object. create and modify are individually optional, but at least one must contain a non-empty path.
JSON batches: creation accepts one nested JSON object or a batch JSON array.
Multi-line values: description/reproduce/fix support YAML indented continuation format
Close enforcement: closing requires a non-empty fix field
Incremental file updates: dow issue update I001 --file '{"modify":["+src/foo.rs","-src/bar.rs"]}'
Output contract: JSON detail output uses nested files; issue Markdown keeps its existing files_modify/files_create representation.
Fix workflow: /fix runs only after explicit user invocation. It reads and claims open issues, applies scoped fixes, records each fix with dow issue update --fix, verifies the result, and closes the issue with dow issue close.

Multi-Branch VERSION

The VERSION file supports independent version tracking per branch:

(main)0.2.4
(beta)0.3.5

build.rs detects the current branch via git rev-parse and selects the correct version line at compile time. Both dow version and the built binary report the branch-specific version.

Cross-Platform Support

dev-flow supports both Claude Code and OpenAI Codex CLI through a shared plugin core with per-agent adapters:

Component	Claude Code	Codex CLI
Plugin manifest	`.claude-plugin/plugin.json`	`.codex-plugin/plugin.json`
Hooks config	`targets/claude/hooks.json`	`targets/codex/hooks.json`
Project instructions	`CLAUDE.md`	`AGENTS.md`
Sub-agent API	`Agent({...})`	`spawn_agent`

Commands, skills, and agents are shared across platforms. Hooks call the global dow CLI directly.

dow CLI

dow is the unified dispatcher that powers all hooks and automation:

Command	Description
`dow setup [--agent claude\|codex\|all]`	Register plugin with agents (interactive TUI)
`dow update`	Self-update binary + plugins
`dow doctor [--fix]`	Diagnose .dev-doc structure, spec, and consistency
`dow status`	Read/write STATUS.yaml
`dow claim`	Claim a task or issue (with dependency check)
`dow task create/update/show/list`	Task lifecycle management
`dow issue create/update/close/show/list`	Issue lifecycle management
`dow fix`	Compatibility alias for `dow doctor --fix`
`dow test`	Full project-level test suite
`dow test`	Task-level test for the Task's files.test
`dow scan`	Project structure scan
`dow version [--set X.Y.Z] [--bump patch]`	Read/write multi-branch VERSION
`dow iterate [--confirm]`	Delivery: archive + commit + tag + bump
`dow rollback --version`	Undo an iteration: restore tasks/issues/docs from archive
`dow task/issue/prd/spec/brainstorm/changelog schema`	Query the current document schemas
`dow dashboard [--port PORT]`	Launch local web dashboard (dependency graph, kanban, docs)
`dow hooks ...`	Hook dispatch (context, guard, post-write)
`dow archive list/show/tasks/issues/doc`	Query historical iterations from archive.db

VS Code Extension

The Dow Dashboard extension embeds the dev-flow dashboard directly in VS Code as a webview panel.

Install

cd vscode-extension
npm install
npm run compile

Then press F5 in VS Code to launch the Extension Development Host, or package it:

npx vsce package
code --install-extension dow-dashboard-0.1.0.vsix

Usage

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run:

Dow: Open Dashboard

The dashboard displays your project's task/issue dependency graph, kanban board, document viewer, and status overview — the same content served by dow dashboard, but integrated into your editor.

Requirements

The dow CLI must be installed and available in your PATH
A .dev-doc/ directory must exist in the workspace (run /init first)

Project Structure

dev-flow/
├── dow/                           # Rust CLI source (the dow binary)
│   ├── src/
│   │   ├── main.rs
│   │   ├── cli.rs
│   │   ├── commands/              # 24 subcommand modules
│   │   │   ├── setup.rs          # dow setup
│   │   │   ├── doctor.rs         # dow doctor
│   │   │   ├── claim.rs          # dow claim
│   │   │   ├── dashboard.rs      # dow dashboard
│   │   │   ├── issue.rs          # dow issue
│   │   │   ├── task.rs           # dow task
│   │   │   ├── iterate.rs        # dow iterate
│   │   │   ├── rollback.rs       # dow rollback
│   │   │   ├── version.rs        # dow version
│   │   │   └── ...
│   │   ├── hooks/                # Hook implementations
│   │   │   ├── context.rs
│   │   │   ├── guard.rs
│   │   │   ├── post_write.rs
│   │   │   ├── post_bash.rs
│   │   │   └── save_changelog.rs
│   │   └── core/                 # Shared libraries
│   │       ├── config.rs         # ~/.config/dow/config.toml
│   │       ├── platform.rs       # XDG paths, platform detection
│   │       ├── github.rs         # Release API, self-update
│   │       ├── archive_db.rs     # SQLite archive queries
│   │       ├── doc_validator.rs  # Document format validation
│   │       ├── doc_root.rs       # .dev-doc root resolution
│   │       ├── task_store.rs     # Task file I/O
│   │       ├── version.rs        # Multi-branch VERSION
│   │       ├── claim.rs          # Claim lock management
│   │       ├── yaml.rs           # YAML frontmatter utilities
│   │       └── agent_registry.rs # Plugin deployment
│   ├── dashboard-frontend/       # Web dashboard (graph, kanban, viewer)
│   │   ├── graph.js
│   │   ├── views.js
│   │   ├── style.css
│   │   └── vendor/
│   ├── references/               # Inject prompts &amp; document specs
│   └── Cargo.toml
├── plugin/                       # Shared plugin content (agent-agnostic)
│   ├── commands/                 # Slash command markdown files
│   └── agents/                   # Sub-agent prompt definitions
├── targets/                      # Per-agent adapter layer
│   ├── claude/
│   │   ├── plugin.json
│   │   └── hooks.json
│   └── codex/
│       ├── plugin.json
│       └── hooks.json
├── npm/dev-flow/                 # npm package (@xin_yue/dev-flow)
├── install/                      # One-line install scripts
│   ├── install.sh                # curl | bash
│   └── install.ps1               # irm | iex
├── examples/                     # Quickstart and workflow walkthroughs
├── devtools/                     # Development helpers
│   ├── assemble.sh               # Assemble dist//
│   └── deploy-local.sh           # Build + deploy locally
├── scripts/                      # Utility shell scripts
├── .github/workflows/
│   ├── release.yml               # CI: tag → build → GitHub Release
│   ├── build-dow.yml             # Build verification
│   └── test.yml                  # Test suite
├── VERSION
├── CLAUDE.md
├── AGENTS.md
├── README.md
└── LICENSE

Contributing

See CONTRIBUTING.md for local development setup and conventions.

Credits

The /brainstorm command is inspired by superpowers.

License

MIT

dev-flow xin_yue

README