dd-flow — local flow orchestrator for Mini protocol automation
npm install @dd-flow/clidd-flow — локальный флоу-оркестратор для автоматизации AI‑KOD Mini протокола через Codex (TypeScript SDK).
- 🧾 Создаёт .protocols/NNNN- и просит агента сгенерировать plan-mini.md.
- 🧩 Компилирует plan-mini.md в compiled-plan.json (Plan IR) и строит action-plan.json (набор действий оркестратора).
- 🛠️ Выполняет шаги плана как последовательность Actions (step/checkpoint/verify/fix/commit) по режиму движка (см. ниже).
- ✅ Делает verification (semantic review) шагов в режиме read-only (без запуска команд) как AgentCheck.
- 🧯 Если checks/verification требуют исправлений — запускает fix-flow (fix agent), затем сохраняет “handoff_for_main” в main session.
exec → checks → fix-loop (до зелёного) → commit.step X exec → commit, затем step X+1 exec → commitHEAD после X+1:union(checks[X], checks[X+1]) с dedup по строке команды,HEAD до зелёного,checks → verify → fix → recheck → re-verify.dd-flow сохраняет контекст обсуждения в main session, но делает планирование детерминированным через plan-mini.md и compiled-plan.json.
Plan review теперь живёт в главном TUI (pi‑tui) внутри экрана Protocol Feed.
Пользователь видит ленту карточек действий (ledger) и может открыть details‑панель с plan-mini.md / agent logs.
Важный инвариант: до принятия плана dd-flow не делает git commit — коммит плана является итогом процесса планирования (после “Plan review: accepted”).
Во время Plan review доступны действия (через hotkeys в footer):
- ✅ Принять план: dd-flow делает commit .protocols/ и переводит протокол в “ready to execute”.
- 📝 Remarks + rebuild: встроенный remarks‑editor (home SoT) → sync plan-mini.md по чату+remarks → compile.
- 💬 Обсудить план с агентом: dd-flow показывает/копирует команду codex resume и умеет открыть терминал (iterm2/Terminal.app).
- ⏸️ Pause: остановиться на plan review и вернуться позже.
Remarks — технический SoT (home): ~/.dd-flow/projects/.
В главном TUI remarks редактируются во встроенном modal‑editor (без $EDITOR).
- 🧰 Home dir dd-flow: ~/.dd-flow/ (можно переопределить через DD_FLOW_ROOT)
- DD_FLOW_ROOT=/tmp/dd-flow-test удобно для e2e/локальных экспериментов: весь SoT окажется в одной папке, без влияния на “боевой” ~/.dd-flow.
- 🧩 Шаблоны промптов (repo-owned): apps/dd-flow/prompts/*/.md (Handlebars {{VARS}})
- По умолчанию dd-flow читает промпты из своей папки prompts/ внутри пакета.
- При желании можно переопределить paths.promptsDir через DD_FLOW_ROOT/config.yaml.
- 🧾 Runs / логи: ~/.dd-flow/runs/
- logs/timings.jsonl — JSONL‑тайминги ключевых блоков (stages/steps/checks/verify/agent/total).
- 🧠 Protocol runtime (source of truth): ~/.dd-flow/projects/
- state.json — SoT состояния протокола (cursor/progress/baseCommit)
- timing.execution.totalActiveMs и timing.actions[ — накопленное “активное” время по протоколу и по action
- compiled-plan.json — скомпилированный план (Plan IR)
- action-plan.json — план действий оркестратора (Actions)
- protocol-ledger.jsonl — append-only события (debug/observability)
- workspace/ACT-XXXX/... — артефакты действий (prompts, reports, logs)
- 📝 Plan remarks (SoT): ~/.dd-flow/projects/
- редактирование через $EDITOR (по умолчанию nano, fallback vi), плюс inline fallback.
- 🧾 Репозиторий: .protocols/ — человеко‑читабельный слой (plan/context/log/research) и попадает в git‑историю.
- 🧠 Codex sessions:
- основная сессия (main) — dd-flow
- fix agent создаёт отдельную сессию; при ручном вмешательстве dd-flow даёт команду codex resume
dd-flow трактует качество и контекст как артефакты, которые нужно довести до целевого состояния (converge loop):
- ✅ checkpoint_gates: process checks + verify (hard) + общий fix-loop до зелёного.
- 🔎 step_research: fork‑sessions для исследовательских артефактов → validate → копирование в .protocols/.../research/ до step_exec.
dd-flow сохраняет baseCommit.originMain (SHA origin/main на момент старта протокола). Это заготовка под Full‑протокол:
- Full можно стартовать от последнего стабильного origin/main, даже если в рабочей ветке в данный момент идёт mini/merge.
Также в home создаётся директория ~/.dd-flow/projects/ как заготовка под будущую очередь merge’ей (в MVP не используется).
``bash`
dd-flow
dd-flow
`bash`
dd-flow run
Флаги:
- --allow-push: разрешить git push origin main (по умолчанию false)--checks-mode
- : sync или async (дефолт: async)--verify-mode
- : sync или async (дефолт: async)--concurrency
- : параллелизм checks (по умолчанию берётся из DD_FLOW_ROOT/config.yaml, дефолт 5)--terminal
- : адаптер терминала для manual fix (iterm2 по умолчанию)
`bash`
dd-flow codex-ping
`bash`
dd-flow verify-demo
Если fix не удаётся после auto-retry, dd-flow показывает STOP-меню:
1) открыть терминал и запустить команду вида cd
2) 📋 скопировать команду в буфер обмена
3) ✍️ сделать ещё один retry фикса с сообщением пользователя (в той же fix-session)
4) остановить dd-flow
- Ожидается запуск из корня проекта (git repo).
- Mini flow ориентирован на ветку main.DD_FLOW_ROOT/config.yaml
- Таймауты checks настраиваются через (idle/max).task_name
- Имя задачи () должно быть валидным kebab-case (ASCII, длина ограничена); при невалидном ответе naming-агента dd-flow делает retry и может применить безопасный fallback.pnpm install
- Оркестратор не делает (bootstrap — detect-only). Если проверки требуют окружения — это решается через fix-loop (agent + повтор checks).
Если dd-flow предлагает ручной фикс, запускай именно команду dd-flow (она включает cd ), чтобы правки точно попали в основной worktree проекта.
По умолчанию один turn агента имеет:
- base timeout: 3m
- auto-extend: +2m каждый раз, когда от агента приходят streamed события (progress), пока он “живой”.
Перекрытие через env vars:
- DDFLOW_AGENT_TIMEOUT_MS — base timeout в миллисекундах (например 180000).DDFLOW_AGENT_EXTEND_MS
- — размер авто‑продления в миллисекундах (например 60000).
Сейчас dd-flow — один процесс: engine + UI.
Цель следующего этапа (Full протокол и параллельные линии) — вынести engine в локальный server:
- server: state machine + TaskManager + resource locking + ledger,
- cli: UI/интерактив (prompts/spinners/menus) + thin client.
Скрипты (root package.json):
`bash`
pnpm test:dd-flow
pnpm test:dd-flow:unit
pnpm test:dd-flow:e2e
Полезные “fixtures” для тестов (Source of Truth — внутри репозитория):
- apps/dd-flow/src/testing/fixtureAgent.ts — FixtureAgentProvider (LLM/Codex заглушка) + Codex‑like артефакты (prompt.md, stream.jsonl, stream.md, response.json, …).apps/dd-flow/src/testing/fixtureGit.ts
- — FixtureGitClient` (Git заглушка для unit/integration тестов).