do-dag

Bulldoze through complex tasks, at the cost of minimally attended time and several hundred USD worth of tokens, with minimal human validation.

do-dag executes an approved spec as a directed acyclic graph of agent tasks. The distribution also includes verify-rounds, which finds, reviews, and applies repairs to a completed artifact.

This repository provides an installer plugin. The plugin exposes only setup-do-dag. Setup copies the runtime skills and their supporting files into your repository. You can disable the installer plugin after setup.

Who this is for

Use do-dag when all three conditions apply:

• The work will exceed one Claude Code session.
• You cannot review every task by hand, but you cannot accept unvalidated output.
• You are willing to spend several hundred USD on model tokens for one large run.

Start with an approved spec. Using wayfinder to produce and challenge the spec before running do-dag is recommended.

Install

Run these commands in Claude Code:

/plugin marketplace add MegasKomnenos/do-dag
/plugin install do-dag@do-dag
/reload-plugins
/do-dag:setup-do-dag

The setup skill inspects the target repository before changing it. If setup finds existing runtime assets or configuration, it asks which local elements must be preserved. Setup agrees on a preservation method before installation when preservation is required.

After setup finishes, disable the installer plugin:

/plugin disable do-dag@do-dag
/reload-plugins

The installed local skills continue to work while the plugin is disabled.

Installation modes

claude-full is the standard installation. Claude runs the workflow and its workers.

If the Codex CLI is available, setup can offer mixed. Setup installs mixed mode only after explicit approval. Approval covers all of these changes:

• Claude project permissions use bypassPermissions.
• The permission mode applies to every Claude tool in the project, not only Codex calls.
• Codex workers run with -a never and danger-full-access.
• The target repository is marked trusted in the user's Codex configuration.

There is no auto fallback. If mixed mode is unavailable or rejected, setup uses claude-full.

Installed files

Setup installs or updates these runtime assets:

your-repository/
├── CLAUDE.md                         # managed instruction block at the tail
├── .mcp.json                         # dag-measure server entry
├── .claude/
│   ├── settings.json                 # do-dag hooks and agent caps
│   ├── agents/gp-matrix/
│   └── skills/
│       ├── do-dag/
│       └── verify-rounds/
├── .agents/
│   └── AGENTS.md                     # mixed mode only
└── .git/hooks/pre-commit             # managed do-dag marker block

Mixed mode also changes the project-local Claude permission mode and the user Codex trust entry. Setup preserves unrelated settings, instruction text, and pre-commit commands.

Glossary

• Phase: One complete do-dag run within a larger project.
• Row: One entry in a dispatch table.
• Dispatch table: The canonical record of rows, dependencies, status, and dispatch metadata for one phase.
• Ready row: An unstarted row whose predecessors have all completed.
• Dispatch row: A short-lived unit of execution. It performs its assigned task but creates no child rows.
• Expansion row: A row that decomposes its assignment into a child dispatch table instead of performing the target task directly.
• Node: An expansion row whose row file defines one sub-DAG.
• Execution node: A node marked isolation: worktree. It owns one Git worktree shared by every row beneath it.
• Verification row: A dispatch row that runs verify-rounds against another row or a cumulative change set.
• Gate: A row that pauses downstream execution until a required decision or approval is recorded.
• Sink: A convergence row that settles a node or phase. An execution-node sink merges its worktree when applicable.

How do-dag works

1. One do-dag run executes one phase. The run name becomes the phase identifier.
2. The main session opens .sdd/dag/<run-name>/ and starts one resident orchestrator.
3. The orchestrator dispatches row 0. Row 0 creates six top-level rows: baseline measurement, a frame gate, decomposition, an execution-DAG gate, end-of-phase validation, and a phase sink.
4. The baseline row reads the canonical sources and measures the repository status. The frame gate then asks you to approve the frame and profile.
5. The decomposition row builds the execution DAG and runs independent planning reviews. The execution-DAG gate asks you to approve that DAG.
6. The orchestrator reads the dispatch table, dispatches every ready row, and records each row's status.
7. Each execution node opens one Git worktree. Every dispatch, verification, and expansion row beneath that node uses the same worktree.
8. Verification rows run after edits to knowledge assets. They also run before a sink in a node with at least three non-verification dispatch rows and at phase end.
9. Every node's child rows converge on one sink. An execution-node sink validates the completed work and squash-merges the worktree branch into the main checkout.
10. Downstream nodes depend on the completed sink instead of individual child rows.
11. End-of-phase validation covers the cumulative phase changes. The phase sink closes the phase.
12. The main session moves the completed run record to dag/<run-name>/ and commits it.

The dispatch table is the canonical record of run status. A replacement orchestrator reads the same table and continues from the remaining rows.

Key properties

• Expansion rows split large goals into nested sub-DAGs during the run.
• Dispatch status and decisions stay in Markdown. A replacement orchestrator resumes from the next ready rows.
• Execution nodes isolate changes in Git worktrees. Sink rows merge completed work.
• Deterministic Python scripts check nine dispatch-table invariants before work continues.
• Verification rows run after asset edits, before qualifying node sinks, and at phase end.
• Two gates require approval of the frame and the execution DAG. Scope changes and irreversible actions return to the user.
• The model_preset values claude-full, mixed, and codex-full assign models by role. The installer offers claude-full and mixed installation modes.
• Context usage is measured before execution. Work that exceeds a model's context budget must be split.

Use do-dag

Use do-dag after the goal, constraints, and approval points are settled. Invoke it in the language you want the workflow to use.

/do-dag Execute the approved migration spec in docs/migration.md.

do-dag uses one resident orchestrator and short-lived row agents. It tracks dependencies, worktrees, gates, commits, and recovery.

The Model parameters section defines model_preset and verification_model_preset. After installation, see .claude/skills/do-dag/SKILL.md, section Model parameters, for values and inheritance.

Use verify-rounds

Use verify-rounds when an artifact exists and accepting unvalidated repairs is not acceptable.

/verify-rounds Review and repair docs/design.md.

Each round has four stages: repair, merge, review, and apply. Every accepted change must meet the configured review_quorum.

A standalone default run uses four repairers and three reviewers. It runs at least two rounds. A verification row inside do-dag runs one round. Multiple verification rows repeat the process with fresh context. After installation, see .claude/skills/verify-rounds/SKILL.md, section Parameters, for profiles, caps, floors, and model_preset values.

Output language

The distributed workflow uses English for its registered fixed schema. The schema includes file names, headings, field names, status values, return tokens, CLI terms, and code identifiers.

Both skills use the invocation language for free-form prose and user-facing artifacts. An explicit language request overrides the invocation language. The language request does not change the registered fixed schema.

Architecture

Claude Code main session
|
+-- do-dag
|   |
|   +-- resident orchestrator
|   |   +-- expansion agents
|   |   +-- task agents in Git worktrees
|   |   +-- gate and verification rows
|   |
|   +-- dispatch table and decision files
|
+-- verify-rounds
    +-- repairers
    +-- mergers
    +-- independent reviewers
    +-- scripted apply stage

Optional Codex workers
+-- selected do-dag and verify-rounds roles

The plugin is an installer. Setup copies the runtime skills and supporting files into the consumer repository. The runtime does not depend on an enabled plugin.

Requirements

Required:

• Claude Code
• Git
• Python 3.10 or later
• A POSIX shell with sh, test, mkdir, mv, sed, and find

Optional Codex support requires the Codex CLI. Codex rows also use tr, grep, and paste to prepare their execution environment.

The setup skill installs repository settings, hooks, and local skill files. It does not install Claude Code, Python, Git, shell tools, or the Codex CLI.

Update

Update the marketplace plugin, enable it, and run setup-do-dag again. Setup inspects the current installation and asks about local elements before replacing installer-owned runtime directories. Disable the plugin again after setup.

License

Released under the MIT License. See LICENSE.