ddflow

ddflow

A portable, agent-agnostic work-queue kernel for AI coding agents.

You keep a queue of phases and tasks with declared dependencies. You say *"implement phase P2"*. Independent tasks fan out to parallel agents in isolated git worktrees; dependent ones wait. Every task passes a quality pipeline whose gates cannot be passed by assertion. If an agent crashes, its work is found rather than lost. If everything except the log is destroyed, the project's decision history rebuilds from the log alone.

Two dependencies beyond `python3` and `git` (Jinja2, for the prompt templates, see Extending it by writing text, not code; and tomlkit, which edits .ddflow/config.toml without losing its comments). Everything else is an optional extra, none needed for the core: ddflow[search] (rapidfuzz) and ddflow[rag] (model2vec) are in use, with BM25 and difflib as the fallback; sqlite-vec (also in ddflow[rag]), ddflow[watch] (watchfiles) and ddflow[mcp-sdk] (the MCP SDK, for a future network transport) are declared and not yet used. A check that needs an absent extra is recorded unavailable, never passed. Works with Claude Code, Gemini CLI, Codex, Copilot, Cursor, Kimi, opencode, Aider, a CI job, a Makefile, or a human at a terminal — over a CLI and an MCP server that are the same implementation.

Instruction for an agent reader

*If you are an AI agent and were asked to read this README, this section is your shorthand. Everything below it is detail.*

What ddflow is. A work queue with rules the tools enforce, for projects that agents build. Work is phases and tasks with dependencies and declared file globs. Each task gets a lease and its own git worktree, then passes a gate pipeline: a check that could not run is unavailable, never passed; one reviewer must be from another model family; a bug closes only with a regression test that failed first. Everything is recorded in an append-only log in .ddflow/events/, committed with the code. ddflow writes none of your project's code — you do; it adds only its own config, a rules block and git hooks. Every operation is both a shell command (ddflow …) and an MCP tool (ddflow_…).

If the project already uses it (.ddflow/ exists): call ddflow_brief (or run ddflow brief) first and follow it. It replaces reading the project's rule and lesson files. Then: ddflow_next → ddflow_claim → work only in the worktree it returns → ddflow_gate_status, satisfy each gate → ddflow_merge → ddflow_complete. The full driver is docs/ddflow/drivers/implement-phase.md in that project.

To onboard a project, ask the user first: it installs a tool, registers an MCP server and writes files in their repository.

1. Install: uv tool install git+https://github.com/delian/ddflow-mcp (not on PyPI yet).
2. In the project root: ddflow adopt --agents claude (your agent's name; see Wiring it into your agent). It writes .ddflow/, the MCP registration, the commit hook and a rules block in AGENTS.md. Restart the agent session so it loads the MCP server.
3. ddflow import lists the plans, lessons, decisions and unmerged branches the repository already has, and writes nothing. Run ddflow import --apply only once the user agrees with that list.
4. ddflow config --set gate.unit_tests.command " ". Then ddflow companions lists the tools the gates expect that are missing: propose them, never install one unasked.
5. Put the user's plan in the queue (ddflow phase add …, ddflow task add … --globs …) and finish with ddflow doctor.

Exit codes, everywhere: 0 ok · 1 failure · 2 could not run / nothing to do · 3 refused. Never treat 2 as 0.

Everything is yours to change, per project

ddflow ships defaults, never a fixed process. **Every part of how it works is a file or a setting in *your* repository, and each project can differ from the next:** the gate pipeline and each gate's command or prompt, which reviewers run, the rules your agents follow, every prompt an agent is handed (including the instructions it receives the moment it connects), the slash-command workflows, your own [[macro]] modes, the export document templates, the branching and release model, parallelism and lease limits, cadences, enforcement strictness, and the per-agent driver docs. Nothing is hard-wired except the four enforced rules at the top of this page, and even those are tuned through documented knobs, never silently bypassed.

Three ways to change anything, all validated before anything is written:

• Edit the file. It is plain TOML or Markdown under .ddflow/ (committed, shared by every clone) or .ddflow/local/ (git-ignored, yours alone).
• Use the CLI (ddflow config --set, ddflow workflow …, ddflow prompts eject, ddflow rule …, ddflow export eject).
• Ask your agent, which has the same operations as MCP tools (ddflow_configure, ddflow_workflow_*, ddflow_rule_*). It changes a project's workflow only with your agreement.

The complete list of what can be changed, and where, is the Customisation reference at the end of this page.

Introduction

The problem it solves

An AI coding agent is good at a task and weak at a project. One agent in one session mostly works. Run it for weeks, or run three at once, and the same failures come back:

• Work disappears. A session crashes or is closed mid-task, and the half-finished change sits in a directory nobody remembers.
• Agents collide. Two of them edit the same file, and the second merge quietly undoes the first.
• Checks that never ran look like checks that passed. The linter was missing, the reviewer endpoint was down, the tests were "run" in a summary. The agent reports *done*, and nothing on record says otherwise.
• The project forgets. Last week's hard-won lesson, the reason behind a design choice, the bug that was already fixed once — gone at the next session, or at the next context compaction in this one.
• Nobody can say what happened. Which instruction led to which change, and which review looked at it, lives in a chat transcript that no longer exists.

ddflow is the layer between you and your agents that makes those failures structurally hard rather than a matter of discipline. It does not write code and it is not an agent. It is a queue, a set of rules the tools enforce, and a log of everything that happened.

What changes for you

Who it is for

• One developer with one agent. A plan that survives the session, a memory that survives compaction, and a record of which checks really ran. The queue is useful even with no parallelism at all.
• Several agents in parallel — subagents, several terminals, several vendors. The dependency graph says which tasks are independent, worktrees keep them apart, and the merge step lands them without anyone switching the main checkout's branch.
• A team or a CI pipeline. The log is committed with the code, so a fresh clone knows the queue and its history. Read commands have a machine-readable --json form and every command returns the same four exit codes, so a Makefile or a CI job can drive it exactly as an agent does.

It works with the agent you already use, because everything it does is reachable both ways: as a shell command and as an MCP tool. Use whichever your agent, script or CI job has. Your workflow is text, not code — the gate pipeline, the reviewer instructions and the agent-facing prompts are files in your repository that you can edit.

What it is not

• Not an agent or a model. Your agent does the work; ddflow decides what may start, checks what was claimed, and remembers.
• Not a hosted service. Everything is files in your repository and a disposable local cache. No account, no server to run beyond the local MCP process.
• Not a replacement for your tests or CI. It runs the commands you configure and records their real exit codes and output.

A first run

# ddflow-mcp is not on PyPI yet; until the first release, install from the repository:

uv tool install git+https://github.com/delian/ddflow-mcp # or: pipx install git+https://github.com/delian/ddflow-mcp cd /path/to/your/project ddflow adopt # registers the MCP server with your agents, writes .ddflow/ and a block in AGENTS.md ddflow phase add P1 --title "Password reset" ddflow task add P1.T1 --phase P1 --title "Reset-token endpoint" --globs 'src/auth/**' ddflow next # what can start now, and why the rest is blocked

adopt registers the server you just installed, by its full path: an install that did not come from a package index (from git, a local directory or an archive) carries a direct_url.json in its metadata (PEP 610), and for one of those adopt writes the ddflow-mcp installed beside its interpreter rather than uvx ddflow-mcp, which would fetch from PyPI. Only an install from an index gets uvx. --launch python still forces the interpreter-plus-PYTHONPATH form.

Then tell your agent *"implement phase P1"*. The driver adopt installed tells it to start with ddflow_brief, claim the task, work in its own worktree, satisfy each gate and land the change. ddflow cannot make an agent follow instructions, but it makes skipping them visible: the commit hook adopt installs flags a commit made without a lease (or refuses it, if you set [enforce].commit_without_lease = "block"), and ddflow complete refuses an item whose gates carry no outcome. Watch it with ddflow board, and ask ddflow doctor at any point whether the project is healthy.

How do I…?

Every row is a command you can run in a terminal and a tool an agent can call over MCP — the same implementation, so neither drifts from the other.

| **the pre-pus