ddflow MCP server

ddflow

<!-- mcp-name: io.github.delian/ddflow-mcp -->

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.

One dependency beyond python3 and git (Jinja2, for the prompt templates; see Extending it by writing text, not code). 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 ddflowbrief (or run ddflow brief) first and follow it. It replaces reading the project's rule and lesson files. Then: ddflownext → ddflowclaim → work only in the worktree it returns → ddflowgatestatus, satisfy each gate → ddflowmerge → 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.

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.

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

repository already has, and writes nothing. Run ddflow import --apply only once the user agrees with that list.

1. ddflow import lists the plans, lessons, decisions and unmerged branches the

ddflow companions lists the tools the gates expect that are missing: propose them, never install one unasked.

1. ddflow config --set gate.unit_tests.command "". Then

and finish with ddflow doctor.

1. Put the user's plan in the queue (ddflow phase add …, ddflow task add … --globs …)

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

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:

Shortened. The full README is on GitHub.