Running a PRD · Zurdo

one PRD

$ zurdo validate prd.md   # grammar and graph, free
$ zurdo run prd.md        # the loop
$ zurdo review prd.md     # sign off [manual] criteria
$ zurdo report prd.md     # JSON, or --format md

A bare zurdo <prd> is short for zurdo run <prd>. zurdo help workflow prints the lifecycle offline.

Run

zurdo run opens with a banner, then prints a header per task, a line per criterion and a summary. Here the agent never delivered:

zurdo run docs/greeter/prds/prd-02-changelog.md

═══════════════════════════════════════════════════════════════
  Zurdo v1.30.1
  PRD:      docs/greeter/prds/prd-02-changelog.md
  Slug:     prd-02-changelog-6c9f
  Executor: anthropic (effort_map: high=claude-opus-4-7, low=claude-haiku-4-5, …)
  Tasks:    2 (2 pending, 0 passed, 0 blocked-by-dependency)
═══════════════════════════════════════════════════════════════
─── task-changelog: Add a changelog ─── effort=low, deps=[]
  → iteration 1 of 2 (max-attempts=2, agent-timeout=30m 00s)
  ✓ agent completed: exit=0, 56ms, 6 B stdout, 0 B stderr
    ✗ file-exists: CHANGELOG.md (0ms)
      stderr tail: path does not exist
    ✗ grep: ^## 0\.1\.0 in CHANGELOG.md (0ms)
  → iteration 2 of 2 …
  ⚠ task-changelog: stalled — attempt 2 repeats fingerprint sha256:f4c74337… (2 consecutive attempts)
  ✗ task-changelog: failed in 2 iterations (154ms)
  ⊘ task-release: blocked-by-dependency in 0 iterations (—)
═══ Run Summary ═══
  task-id              status                   attempts   wall-clock   criteria
  task-changelog       failed                   2/2        154ms        0/2
  task-release         blocked-by-dependency    0/3        —            —
  totals               0 passed, 0 pending-review, 1 failed, 1 blocked     327ms
  iterations           2 used (of unlimited)
Next: fix root causes and re-run — zurdo run docs/greeter/prds/prd-02-changelog.md
run failed: 1 task(s) failed, 1 blocked-by-dependency

The agent said "Done!" both times. The file never appeared: exit 5.

Glyph	Meaning
`→`	action
`•`	agent step
`✓` / `✗`	pass / fail
`⊘`	skipped or manual
`⚠`	warning

With a real agent, each step shows as a • line (• tool Bash: …, • edit: …), and the summary adds a tokens & cost row. The raw stream is saved under .zurdo/<slug>/iterations/, and every event goes to progress.log as JSONL. --quiet-agent hides the agent's lines, --raw-agent shows its raw bytes, and --no-color strips ANSI.

Read the summary

status passed, passed-pending-review, failed or blocked-by-dependency. See task statuses.

attempts Used of Max-Attempts. A failed task has spent them all.

criteria Passing of total, on the last attempt.

Next: The command zurdo suggests. On a failure, go to When a run fails.

A task whose criteria were already green before the run passes with zero attempts:

zurdo run --reset

  task-changelog       passed (pre-flight)      0/2        —            —
  task-release         passed                   1/3        56ms         1/1
  totals               2 passed, 0 pending-review, 0 failed, 0 blocked     243ms
  passed-at-preflight  2 criteria — proved nothing about this run
warning: 1 tasks passed at pre-flight without any agent work — task-changelog. Their criteria were already satisfied before the run started; confirm this is a re-run and not a vacuous criterion set.

That's fine on a re-run. On a first run it means the criteria don't test the work. The warning never changes the exit code. If [verification] completion_command is set, it runs once after every task passes, and a failure exits 9.

Resume

Ctrl-C once: zurdo finishes the current iteration, prints the summary and exits. Twice kills it, and the unfinished attempt doesn't count. Run the same command again and zurdo offers to resume:

zurdo run prd.md

What would you like to do?
  [R] Resume from current state           (default)
  [X] Reset — archive state and start over
  [A] Abort

zurdo run prd.md --resume   # no prompt
zurdo run prd.md --reset    # archive .zurdo/<slug>/ and start over

Resume keeps every finished status, failed included, and runs what's still pending. Without a TTY, or with --no-prompt, it resumes. If you edited the PRD since the last run, zurdo refuses with exit 4 until you pass --reset.

After hand edits or a rebase, zurdo verify <prd> re-checks every passed task against the current tree, without the agent.

In CI

Pass --no-prompt plus --resume or --reset, gate the PRD first with zurdo validate --strict, and branch on the exit code: 5 a task failed, 6 the iteration budget ran out, 9 the completion gate failed. The full table is in Commands.

Next: When a run fails