How it works

Zurdo turns a PRD into a dependency-ordered task list and runs the tasks one at a time. An agent does the work, and zurdo checks the result itself. It never asks the agent whether it passed.

The verification loop

1. Pre-flight. The task's criteria run against the tree before any agent call. If they all pass, the task is done for free. The verdicts are recorded once, so later you can tell the agent did this apart from this was already true.
2. Agent iteration. Zurdo renders a prompt from the task description, the evidence paths, and any matching lessons. It then shells out to claude, codex, or copilot.
3. Independent verification. Zurdo runs every hint itself: shell, HTTP, file, grep, and structural. A change to a frozen path fails the iteration.
4. Coverage gate (on by default). Once every criterion passes and no frozen path was touched, the coverage gate measures the task's changed lines against the tests that ran, and fails the attempt below the configured threshold — the one failure an attempt can still hit with every criterion green.
5. Retry or settle. On failure, the retry prompt carries the exact failing checks. When Max-Attempts runs out, the task is marked failed.
6. Stall detection. When two attempts fail the same way, the task is marked stalled. With [reason] on, one diagnosis call can guide the next attempt, hand the hint to zurdo heal, or halt the task. See Diagnosis & lessons.
7. Completion gate (optional). After every task passes, completion_command (for example, your full test suite) runs once. If it fails, zurdo exits 9. See The completion gate.

Here's a real run. The first task already passed at pre-flight. The second missed twice, stalled, then passed:

─── task-greet: Write the greeter ─── effort=low, deps=[]
  ✓ task-greet: passed in 0 iterations (—)
─── task-docs: Document the greeter ─── effort=low, deps=[task-greet]
  → iteration 1 of 3 (max-attempts=3, agent-timeout=30m 00s)
  ✓ agent completed: exit=0, 273ms
    ✗ file-exists: README.md
      stderr tail: path does not exist
  → iteration 2 of 3
  ✓ agent completed: exit=0, 54ms
    ✗ file-exists: README.md
  ⚠ task-docs: stalled — attempt 2 repeats fingerprint sha256:9a5a07c7… (2 consecutive attempts)
  → iteration 3 of 3
  ✓ agent completed: exit=0, 55ms
    ✓ file-exists: README.md
  ✓ task-docs: passed in 3 iterations (459ms)
═══ Run Summary ═══
  task-greet           passed (pre-flight)    0/3   —       —
  task-docs            passed                 3/3   459ms   1/1
  passed-at-preflight  2 criteria — proved nothing about this run

Task statuses

• passed-pending-review: the automated checks passed, and at least one [manual] criterion is waiting for sign-off in zurdo review.
• failed: Max-Attempts ran out. A resume leaves it failed. See When a run fails.
• blocked-by-dependency: zurdo re-derives this on every resume, from the dependencies that are still failed.

How state is stored, how evidence is protected and how locks work: Internals.

Skills

zurdo init installs eight bundled skills into your provider's discovery path (.claude/skills/ or .agents/skills/). They teach your agent the zurdo-specific parts.

See Your first PRD for where each one fits.

What zurdo deliberately does not do

• No git automation. Zurdo never commits, branches, or opens PRs.
• No API keys. Zurdo drives provider CLIs already on your PATH, using your existing auth.
• No trusting the agent. Agent output is saved for the audit trail, but only zurdo's own checks decide pass or fail.
• No issue tracker. Zurdo never touches GitHub issues or boards. Its companion, Carol, mirrors your planning files and zurdo's run state onto GitHub, reading only zurdo's published JSON.