Skip to content
Roook
Try Roook
Menu

Docs

Roook documentation

How Roook gets from your repo to a verified fix in six steps, then a guide for each part: installing, rules, counterexamples, the GitHub Action, and what is sent to IBM Bob.

How it works

Bob agents propose and explain; the deterministic engine decides. Only the engine marks a rule broken or a fix verified, and you approve the rules and the fix.

  1. Step 1

    Understand

    Bob agents read your repo, start the app in a sandbox and map its HTTP API.

    • Scout reads the repo.
    • Mechanic starts the app in a sandbox (Docker on the CLI).
    • Mapper turns its HTTP API into actions and state readers.

  2. Step 2

    Rules

    Bob proposes business rules with evidence from the code, and you approve them.

    • The Lawmaker proposes business rules (invariants) with evidence from the code.
    • The Rule Critic rejects weak ones.
    • You approve them. They're saved in rook/rook.yaml in your repo.

  3. Step 3

    Search

    The deterministic engine runs seeded sequences of valid actions against the real running app.

    • Seeded, reproducible sequences of valid actions run against the real running app.
    • Every approved rule is checked after every step with a safe expression evaluator (no eval).
    • Strategist weights and Test Designer scenarios steer the search. Concurrent steps catch races.

  4. Step 4

    Shrink and prove

    A failing sequence is shrunk to a minimal one and replayed on the real app.

    • Delta debugging shrinks the steps, then the values.
    • The minimal sequence is replayed on the real app, 10 times by default, and flaky results are reported.
    • It's saved as a counterexample JSON file plus a regression test.

  5. Step 5

    Diagnose and fix

    Bob finds the root cause, and after you approve, writes the fix in a workspace copy.

    • The Detective finds the root cause; the Diagnosis Reviewer checks it against the evidence.
    • After you approve, the Surgeon writes the fix, only in a workspace copy and only in the approved files.
    • The Fix Reviewer checks the fix.

  6. Step 6

    Verify and ship

    The fix counts only if four engine checks pass. Then it ships on its own branch, as a pull request for a GitHub repo.

    • Four engine checks: exact replay, your project's tests, the generated regression test, and a fresh search with a new seed.
    • Then the fix ships on a rook/fix-* branch: for a GitHub repo, a pull request with the steps, diagnosis, fix, test and results; for a local folder, a local branch.

Guides

Start with Getting started. Each guide states what Roook does today, including what is limited or not built yet.

CLI commands

Every command takes --help. The guides show each one in use.

rook
Open the interactive session.
rook run [repo]
Search a repo for broken business rules. Add --ci for plain output, report files and exit codes (0 every approved rule held, 1 a rule is broken, 2 the run did not finish), and --auto to let Roook answer its own questions.
rook replay <cx> --base-url <url>
Replay a counterexample against your running app (exit 1 while the rule is still broken).
rook verify <cx> --base-url <url>
Check a fix on your running app: the exact replay plus a fresh search (exit 0 when both pass).
rook explain <cx>
Explain a counterexample in plain words: the rule, the minimal steps and what was observed.
rook init
Set up a repo: the rook/ folder and a starter GitHub workflow that runs rook run . --ci --auto. It never overwrites a file that exists unless you pass rook init --force.
rook serve
Start the Roook API server (the web app's backend).
rook login
Sign in with Google (saved to ~/.rook/credentials.json, readable only by you).
rook logout
Sign out: revoke the session on the server and delete the saved credentials on this machine.
Docs · Roook