Running coding agents on a task graph instead of one long chat

The idea

A feature usually breaks down into slices like this:

graph LR
  T1[1. Data model] --> T2[2. API endpoint]
  T1 --> T3[3. Background job]
  T2 --> T4[4. UI page]
  T3 --> T4
  T4 --> V[Validate merged result]
  V --> R[Code reviewer + live tester]
  R --> F[Fixer]

Tasks 2 and 3 don't depend on each other, so there is no reason for them to wait. Task 4 needs both. Once everything is merged, the result as a whole gets checked.

Each task is a small JSON file:

{
  "id": "4",
  "content": "## Export endpoint\n\nImplement `GET /export` ...\n\n## Acceptance criteria\n- ...",
  "dependencies": ["2", "3"]
}

The content is meant to be a full, self-contained issue, because the agent working on it doesn't get to ask you questions mid-run.

How a run works

1. Spec first. You start from a PRD. graph-execution ships agent skills for this: to-spec writes the spec and asks you every question that would otherwise need a human during the run, then waits for your approval. to-tasks turns the approved spec into the task folder and a test plan.
2. Parallel agents. Independent tasks run at the same time, each agent in its own git worktree. When a task finishes it merges into an integration branch, graph/<run-id>, and only then do the tasks that depend on it start. Concurrency defaults to 3.
3. A validation check on every task. By default, each task has to pass your gate (whatever you put in validate: build, lint, tests) before it merges.
4. One review of the whole result. After all tasks have merged, the gate runs again on the merged branch, because tasks that pass on their own can still break together. Then one code reviewer and one live tester run in parallel, each in a fresh throwaway worktree. They get the full spec. The reviewer also gets the diff, and the tester gets the changed files and the test plan. This happens once for the merged graph, not on each task.
5. Fixer. If there are open blockers or majors, a fixer agent gets both reports and the spec, commits fixes, validation runs again, and the reviewers re-check. That repeats for up to 3 fix passes by default. Minor findings go into the summary and never trigger a fix.

The run is resumable. If something dies halfway, graph-execution --resume picks it up, with git as the source of truth: a task counts as merged only if its merge commit is still on the branch.

Any agent

It works with Claude Code, Codex, OpenCode or Qwen Code, chosen per run with --provider claude|codex|opencode|qwen. The provider CLI just needs to be on your PATH and already logged in. graph-execution stores no credentials.

The web app

The CLI is the engine, but most of the time I use the web app that comes in the same package:

npm install -g graph-execution && graph-execution manager

It listens on http://127.0.0.1:7420, prints a generated password and opens the browser. From there you connect GitHub or GitLab with a personal access token, clone a repo into a workspace, and open a terminal in it (Claude Code, Codex, OpenCode, Qwen Code or a plain shell). You plan the tasks from a PRD in that terminal while the spec file opens next to it as it's written.

Start run takes the spec and the tasks folder. Then you watch the run live: the graph draws every task plus the validate, reviewer and tester, fixer and apply steps as nodes. When the run is applied, Create PR (or Create MR on GitLab) opens the pull request.

Human review, if you want it

Human review is off by default. Turn it on with --human-review, "humanReview": true in the config, or the human review option in Start run. The run then pauses before applying anything and shows the final diff in a Review tab.

You don't edit the result yourself. You leave comments: line comments, file comments, general comments, even GitHub-style suggestions. Then you press Request changes. Your comments become blocker findings, the fixer works on them first, and validation, the code reviewer and the live tester run again. The next pause shows how each comment was handled: the fixer's note and the reviewer's verdict with evidence. You decide whether to resolve or reopen.

If you know what you care about up front, put it in a REVIEW.md at the repo root. The code reviewer reads it in its prompt, along with TESTING.md for the tester.

Quick start with the CLI

You need Node.js 20+, git with a commit identity, and one logged-in provider CLI. In the repo you want to change:

mkdir -p tasks
printf '# Hello\n\nThe repo has a hello.txt file that says "Hello, world".\n' > PRD.md
cat > tasks/1.json <<'JSON'
{ "id": "1", "content": "Create hello.txt containing exactly: Hello, world" }
JSON

npx graph-execution ./tasks --spec PRD.md --provider claude

For real work, let your agent write the spec and tasks:

graph-execution install skills --target claude

Then add --web to a run to follow it in the browser.

Built with itself

graph-execution is developed with graph-execution. Every feature started as a spec and shipped as a run. The specs are in docs/prd/done/ and the task graphs in .agents/tasks/ in the repo, if you want to see what real inputs look like.

Feedback welcome

I'd really like to hear from people running agents on bigger features. How do you split the work today? Where would a graph like this get in your way? Bug reports and "this didn't work on my repo" are just as useful.

• npm: graph-execution
• GitHub: romm0109/graph-execution