Readiness
Before a repo spends agent time on claim discovery, evaluation, or improvement, the user needs to know whether Cautilus can safely operate there and what setup is still missing.
Using the cautilus doctor CLI command and the cautilus-agent skill, a user can have an agent inspect setup, explain or fix blockers, choose whether to inspect claims or run a first eval, and stop before spending workflow budget on a repo that is not ready.
Readiness means the repo has enough Cautilus setup to choose and run the next bounded workflow. It is not evidence that the repo's behavior promises are already true; proof status is handled by Evidence Gaps.
A user can see that readiness starts from a valid repo-owned adapter.
Cautilus does not guess a host repo's prompts, runners, baselines, or acceptance policy. Instead, it uses a repo-owned adapter so the user can declare how Cautilus should inspect and evaluate that repo.
A repo becomes ready for Cautilus only after cautilus doctor can find and parse a valid adapter for the selected workflow.
A valid Cautilus adapter is YAML generated or maintained by the host repo, usually at .agents/cautilus-adapter.yaml.
It names the repo and declares enough workflow wiring for the selected Cautilus work.
Host-specific adapter ownership is covered in Host Ownership. This repo's production adapter is .agents/cautilus-adapter.yaml.
Create a deterministic sample skill adapter repo and standalone Cautilus CLI.
tmp=$(mktemp -d)
bin="$tmp/cautilus"
go build -o "$bin" ./cmd/cautilus
git -C "$tmp" init -q
git -C "$tmp" config user.email test@example.com
git -C "$tmp" config user.name "Cautilus Spec"
printf '# sample skill repo\n' > "$tmp/README.md"
git -C "$tmp" add README.md
git -C "$tmp" commit -q -m init
"$bin" init adapter --repo-root "$tmp" --repo-name sample-skill-repo --scenario skill >/dev/null
printf '%s\n%s\n' "$tmp" "$bin"For the generated sample repo, the adapter names this repo and declares an evaluation surface:
A user can see the exact setup checks before choosing the next Cautilus workflow.
doctor reports workflow-relevant checks with machine-readable meaning.
Each check has an id, an ok result, a stable meaning, and a run-specific detail.
The tables verify the stable readiness contract through id, ok, and meaning; the folded raw packet keeps run-specific details such as resolved paths visible.
A ready setup does not mean every next action is complete; doctor can still point to the next bounded setup branch, such as runner assessment.
Show the raw doctor packet for the generated sample adapter.
"/tmp/tmp.hHJUVDWRAs/cautilus" doctor --repo-root "/tmp/tmp.hHJUVDWRAs"Repo-Owned Adapter
Command: ${sample_cautilus} doctor --repo-root ${sample_repo}
| path | equals | meaning |
|---|---|---|
checks[id=adapter_found].ok | true | Cautilus can find repo-owned configuration. |
checks[id=adapter_valid].ok | true | Cautilus can parse and trust the adapter shape enough to continue. |
checks[id=repo_name].ok | true | The adapter identifies the host repo whose behavior is being evaluated. |
First Bounded Eval
Command: ${sample_cautilus} doctor --repo-root ${sample_repo}
| path | equals | meaning |
|---|---|---|
checks[id=evaluation_surfaces].ok | true | The repo names the behavior surfaces Cautilus may evaluate. |
checks[id=baseline_options].ok | true | Eval and improve work have explicit comparison targets. |
checks[id=execution_surface].ok | true | Cautilus can point the user to an executable first run. |
A user can see the exact blocker and next setup action.
doctor reports the actual status, failed check, suggestions, and next action for setup blockers.
The examples below use generated repos so the report shows actual command behavior instead of a guessed setup checklist.
Missing Git Repository
Create a directory that is not a git repo.
repo=$(mktemp -d)
printf '%s\n' "$repo"Show doctor output before the target directory is a git repo.
"/tmp/tmp.hHJUVDWRAs/cautilus" doctor --repo-root "/tmp/tmp.ph0ZvX2YoU" || true| command | path | equals |
|---|---|---|
/tmp/tmp.hHJUVDWRAs/cautilus doctor --repo-root /tmp/tmp.ph0ZvX2YoU | status | missing_git |
No Commits
Create a git repo with no commits.
repo=$(mktemp -d)
git -C "$repo" init -q
printf '%s\n' "$repo"Show doctor output before the repo has its first commit.
"/tmp/tmp.hHJUVDWRAs/cautilus" doctor --repo-root "/tmp/tmp.qHEfttQiQQ" || true| path | equals |
|---|---|
status | no_commits |
next_action.kind | manual |
Missing Adapter
Create a committed repo with no Cautilus adapter.
repo=$(mktemp -d)
git -C "$repo" init -q
git -C "$repo" config user.email test@example.com
git -C "$repo" config user.name "Cautilus Spec"
printf '# missing adapter\n' > "$repo/README.md"
git -C "$repo" add README.md
git -C "$repo" commit -q -m init
printf '%s\n' "$repo"Show doctor output when no Cautilus adapter exists.
"/tmp/tmp.hHJUVDWRAs/cautilus" doctor --repo-root "/tmp/tmp.0BhajOtqMr" || true| path | equals | includes |
|---|---|---|
status | missing_adapter | |
next_action.kind | run_command | |
next_action.command | cautilus init adapter |
Invalid Adapter
Create a committed repo with malformed adapter fields.
repo=$(mktemp -d)
git -C "$repo" init -q
git -C "$repo" config user.email test@example.com
git -C "$repo" config user.name "Cautilus Spec"
mkdir -p "$repo/.agents"
printf '# invalid adapter\n' > "$repo/README.md"
printf 'version: one\nrepo: sample\nevaluation_surfaces: smoke\n' > "$repo/.agents/cautilus-adapter.yaml"
git -C "$repo" add README.md
git -C "$repo" commit -q -m init
printf '%s\n' "$repo"Show doctor output when the adapter is present but invalid.
"/tmp/tmp.hHJUVDWRAs/cautilus" doctor --repo-root "/tmp/tmp.5942yDYPJZ" || true| path | equals |
|---|---|
status | invalid_adapter |
next_action.kind | edit_adapter |
Incomplete Adapter
Create a committed repo with a parseable adapter that lacks a runnable eval surface.
repo=$(mktemp -d)
git -C "$repo" init -q
git -C "$repo" config user.email test@example.com
git -C "$repo" config user.name "Cautilus Spec"
mkdir -p "$repo/.agents"
printf '# incomplete adapter\n' > "$repo/README.md"
printf 'version: 1\nrepo: sample\n' > "$repo/.agents/cautilus-adapter.yaml"
git -C "$repo" add README.md
git -C "$repo" commit -q -m init
printf '%s\n' "$repo"Show doctor output when adapter setup is incomplete.
"/tmp/tmp.hHJUVDWRAs/cautilus" doctor --repo-root "/tmp/tmp.DKA0kGkwRN" || true| path | equals | meaning |
|---|---|---|
status | incomplete_adapter | |
checks[id=evaluation_surfaces].ok | false | The repo names the behavior surfaces Cautilus may evaluate. |
next_action.kind | edit_adapter |
A user can see the next bounded action for the current readiness state.
Readiness is useful only if it points to bounded next work.
For the generated sample adapter, doctor keeps the first bounded eval loop visible but first asks the user to create a runner assessment for the declared runner.
| path | equals | includes |
|---|---|---|
status | ready | |
next_action.kind | runner_readiness | |
runnerReadiness.nextBranch.id | create_runner_assessment | |
first_bounded_run.summary | bounded eval | |
first_bounded_run.discoveryCommand | cautilus discover scenarios --json | |
first_bounded_run.decisionLoopCommands[0] | cautilus evaluate fixture | |
first_bounded_run.decisionLoopCommands[1] | cautilus evaluate observation |
A user can get a safe next workflow branch before spending workflow budget.
A ready setup still needs a safe next branch before the agent spends workflow budget.
doctor gives the human-facing readiness result: whether setup is ready and what a user should fix or run next.
doctor status --json gives Cautilus Agent an orientation packet so it can choose an allowed next branch, such as claim discovery, eval, improve, setup, inspection, or stop, before running discovery, evaluation, improvement, edits, or commits.
Show the raw agent orientation packet for this repo.
"/tmp/tmp.hHJUVDWRAs/cautilus" doctor status --repo-root . --json| path | equals | min_number | includes |
|---|---|---|---|
schemaVersion | cautilus.agent_status.v1 | ||
mode | orientation | ||
nextBranches.length | 1 | ||
notice | before running discovery, evaluation, review, improvement, edits, or commits |