Skip to main content
Run the checks directly and give the writer their output when the work needs another pass. Use it for tests, builds, format checks or commands that check a deployed system. The command’s exit code decides what happens next. It can return the work to the writer or select the next part of the workflow, without a model interpreting the result. When the check needs judgement, get a second opinion.

Shape

The two commands

The tests run as a command with a target. When the command exits non-zero, the step returns a revision request aimed at implement, with the captured output as the finding:
examples/command-kickback.ts (excerpt)
Pass a command as an array when an argument has spaces or quotes of its own. Each entry is one argument. The string form splits on spaces and refuses a quote. The graph then puts a second command, size, between the test and two reviews, and each review carries a when:
examples/command-kickback.ts (excerpt)
passed('size') runs one review when the command exited 0, failed('size') the other when it didn’t. Both read the named dependency’s outcome through ctx.needs; a name the node doesn’t need is a configuration error, not a quiet false. The deciding node is optional: true, so its red result blocks nothing and the branches decide. Without that, a red result would block every step that needs it and the failed branch could never run; the dag refuses that shape and says why. The step whose condition isn’t met is skipped and recorded as skipped. Leave when off any branch that must run, because a skip doesn’t fail the run. failed means the command ran and failed; a dependency that never got to decide meets neither condition. implement’s refine: review({ rounds: 1 }) allows one send-back to it: when the count is spent, the run fails with the last output as its reason instead of looping. review({ judge }) on a node hands the same call to a judge. The test node lists implement in sendsBackTo: a node names every step it can send work back to, a send-back anywhere else fails it with an error that names both steps, and a target with no refine cannot take one at all.

What the run did

The writer here is a function that gets add wrong once, so the red test has something to carry. Run it with npx tsx command-kickback.ts:
Output
implement ran twice: the first attempt subtracted, the test exited 1, and its output went to implement, which ran again with it in hand. The change was small, so size exited 0 and only quick-review ran. No agent read the test output to decide any of that. The exit code did.
examples/command-kickback.ts

A failed check runs again

A commandJob with a target runs a failed command once more on the same tree before the failure counts. When the second run passes, the step passes, and the record marks the check as flaky. Both runs’ output is kept. When it fails twice, it goes to the target as a finding. The writer there may answer it with no change: its reply says the change does not cause the failure, with its evidence. The check then runs once more on the same tree. When it passes, the run goes on. When it fails again, the run pauses, names the check and quotes the writer’s evidence. The answer covers only the check it answers: every other check still runs once more before a failure counts, and one that fails twice is a new finding. A review finding answered with no change still fails, as before.

What a failed check keeps

The finding and the record’s output quote the failure: the failing tests a test runner names (vitest’s FAIL and × lines, node’s not ok), the lines that report the failure, then the end of stdout and the end of stderr, each on its own. The send-back’s reason names the command and how it ended; the output rides the finding alone, so the writer reads it once. outputLimit caps the reason and the output together, in characters, the line that names the whole output’s file included. Without it, both streams are kept whole. When the run writes a record, the whole output of each failed run goes in a file beside it: <record>.checks/round-<n>-<check>-run-<m>.log. The finding names the file.

Next steps

  • Feature delivery: a test command that sends a red result back to the builder, as one of seven steps.
  • Feedback loops: the limit, and the other shapes a check can take.
  • Runtime: commandJob, passed, failed and dag.