ddflow-mcp

# 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](#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 `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](#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 "<their test 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](#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

| Without it | With ddflow |
|---|---|
| You decide what each agent does next, and keep the plan in your head or a chat. | The plan is a queue of phases and tasks with dependencies. `ddflow next` says what can start now and **why everything else is blocked**. |
| Parallel agents step on each other. | `ddflow claim` gives each task a lease and its own git worktree; tasks that declare overlapping files are refused, not merged over. |
| "Done" means the agent said so. | Every task passes a gate pipeline you configure. A gate that could not run is recorded **unavailable, never passed**; at least one reviewer must come from a **different model family** than the author; a bug cannot be closed without a regression test that failed first. |
| A crash loses work. | `ddflow recover` finds orphaned worktrees and reports what each holds. It never deletes work. |
| Every session starts from zero. | Lessons, decisions, research verdicts, bugs and your own prompts are recorded as you go. `ddflow brief` hands the agent the ones relevant to *this* task in a bounded amount of context, and `ddflow recall` searches all of it. The same brief also names the project's own skills, commands and rules files (`.claude/skills`, `.claude/commands`, `.cursor/rules`, `.clinerules`, AGENTS.md/CLAUDE.md) that bear on the task, by name and path only. |
| History is a transcript. | An append-only event log, committed in git. The board, the index and the reports are rebuilt from it; `ddflow replay` reconstructs the project's decisions from the log alone. |

### 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

```sh
# 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 arc