Why zurdo

Zurdo changes what a day of engineering attention produces. You scope the work, spend 30–60 minutes authoring a PRD, and hand it to zurdo run — implementation happens on machine time, often on a remote server, while you scope the next piece or get on with your day. You come back to a report and evidence, not a chat transcript to babysit.

Walking away is safe because the loop never grades itself. After every iteration zurdo — never the agent — executes every acceptance criterion’s hint and decides pass/fail; zurdo validate and zurdo analyze lint the PRD before tokens are spent; Max-Attempts budgets and stall detection bound the cost of failure; crash-safe state under .zurdo/<slug>/ means an interrupted run resumes instead of restarting. When a string match isn’t proof enough, opt-in structural hints verify code facts against the Lumen code index, and the reason subsystem turns every diagnosed stall into a lesson future runs are told about up front. (The design descends from the Ralph technique — run an agent in a loop against a persistent plan — with each of Ralph’s documented gaps closed by the runtime.)

That safety is what buys the productivity. An interactive chat workflow consumes engineer attention per iteration, so throughput stays chained to implementation time. Zurdo consumes it per design and per verdict:

throughput ≈ available attention ÷ (authoring timebox + review timebox)

Implementation duration drops out of the equation entirely — and nothing forces the loop to be serial: author the next PRD while the last one runs, review both when you’re free. The operating rhythm walks the full loop phase by phase and maps it onto agile, ceremony by ceremony — a sprint compressed to hours, with every rule agile enforces socially enforced mechanically instead.

Two deliberate non-features keep it predictable: provider-agnostic (shells out to the claude, codex, and copilot CLIs — no SDKs, no API keys handed to zurdo) and no git automation (branching, committing, and PRs stay yours).

Quick start

# 0. Install (see the installation guide for all methods):
brew install ElOrlis/zurdo/zurdo

# 1. From the root of the repo you want zurdo to drive:
zurdo init                            # writes .zurdo/config.toml, installs bundled skills

# 2. Write a PRD (see Writing PRDs for the full grammar):
cat > prds/hello.md <<'EOF'
# PRD: Hello

## Task: task-build — Write the greeter
**Effort**: low
**Depends-on**: []

### Description
Create `src/greeter.txt` containing the single line `hello world`.

### Acceptance Criteria
- [ ] greeter file exists [file-exists: src/greeter.txt]
- [ ] greeter says hello world [grep: hello world in src/greeter.txt]
EOF

# 3. Validate the grammar before paying for tokens:
zurdo validate prds/hello.md

# 4. (optional) Static + LLM analysis of the PRD itself:
zurdo analyze prds/hello.md

# 5. Drive the loop:
zurdo run prds/hello.md

# 6. Inspect what happened:
zurdo report prds/hello.md           # JSON by default; --format md for markdown
zurdo state list                     # every .zurdo/<slug>/ at this repo root

A bare zurdo <prd> is sugar for zurdo run <prd>.

Support

• Zurdo bugs and feature requests: github.com/ElOrlis/zurdo-dist/issues
• Documentation feedback: github.com/NumeronAI/zurdo.github.io/issues

License

Zurdo is proprietary software, distributed as pre-built binaries. It is an independent reimplementation inspired by the Ralph technique as documented in ClaytonFarr/ralph-playbook. Copyright © 2026 Numeron Technologies Inc.