Project check reference
Skills run no preflight step. Every rota verb that needs .rota/ exits 3 when it cannot find one, so a skill learns about a missing init from the verb itself. rota init check is the explicit check, for the few places that want one up front and for scripts. Before a parallel round, rota doctor checks the machine instead of the project.
rota init check
rota init check
rota init check --json
| Exit | Meaning | What to do |
|---|---|---|
0 |
.rota/ and its core files are present. |
Proceed. |
1 |
Not initialized: .rota/ or one of the core files is missing. --json lists every missing path in data.missing. |
Tell the user to run rota init, then stop. Never auto-init: initialization needs the user’s consent. |
rota init check acts on the working directory (after -C) with no walk-up, so it also runs where there is no .rota/ yet.
Core files it checks under .rota/:
DECISIONS.mdBACKLOG.mdKNOWLEDGE.mdMILESTONES.mdcounters.jsonconfig.jsonstatus.json
Advisory findings come back as warnings, never as a failure: an umbrella flag that disagrees with the registry, and version drift between the project’s stamped rota.version (the old hvSkills.version is read as a fallback until rota init / rota config fill moves it) and the installed binary (rota version --drift reports the same thing on its own).
rota doctor
rota init check asks whether the project is set up. rota doctor asks whether the machine can run a round: git, jq, the terminal host, the tracker login, accounts, the orchestrator hooks, the installed skills and Codex.
rota doctor
rota doctor --json
It is read-only, spends no usage quota, and runs without .rota/ (it falls back to default config). Each check reports pass, fail or skip; a disk line and a go-cache-disk line (both warn) appear only when free disk space is low (on the project volume, and on the volume holding the Go build cache) and never fail the run, a repo config line (warn) naming repo-scope git config keys that changed since the baseline rota round start recorded (with no baseline yet, it lists the program-running and identity keys already set, such as core.hooksPath, core.fsmonitor, diff.external, user.name; doctor never writes the baseline), and a verify line (warn) only while test.full and test.e2e are both empty. A fail carries a hint with the one command or edit that fixes it, and detail says what was found (herdr 0.8.2, need 0.9.x).
| Exit | Meaning | What to do |
|---|---|---|
0 |
Every check passed or was skipped. | Proceed. |
1 |
At least one check failed. --json gives the same data, with ok: false. |
Run each failed check’s hint, then run rota doctor again. |
A missing tool is a failed check, never exit 5.
The checks, in the order they run:
| Check | Passes when | Skipped when |
|---|---|---|
git |
git is on PATH and .worktrees/ is gitignored |
never |
jq |
jq is on PATH (the skills read rota --json output with it) |
never |
host |
the host a round would run on is usable: round.dispatch as named, or with it unset or subagent, herdr inside a herdr pane, else tmux inside tmux. herdr on PATH and 0.9.x, or tmux on PATH |
no host is detected (solo) |
tracker |
gh or glab is on PATH and logged in for the project’s provider |
the project has no remote |
accounts |
every account in round.accounts has a dir whose credentials file holds an access token. On macOS the login Keychain entry is read when the file is missing, unusable or expired. Warns when the orchestrator’s CLAUDE_CONFIG_DIR is not one of the accounts |
no accounts configured |
hook |
herdr’s agent integration is installed for each configured account (herdr integration install claude) |
the host is not herdr, or no account is configured |
statusline |
the effective statusline runs rota statusline dump |
the orchestrator hooks are not installed (opt-in) |
stop-hook |
a Stop and a SessionStart hook installed by rota hook install exist and their command resolves |
the orchestrator hooks are not installed (opt-in) |
guard-hook |
a PreToolUse hook installed by rota hook install sits in project or user scope (project-local never reaches a worker worktree) and its command resolves |
the orchestrator hooks are not installed (opt-in) |
switch |
with orchestrator.switchOnUsage on: two or more accounts have a dir and the Stop hook is installed |
orchestrator.switchOnUsage is off |
skills |
every installed skills root (user and project, Claude and Codex, including each round.accounts config dir) matches the binary’s skill set, and has no missing or edited files |
no root has a .rota-manifest.json (run rota skills install) |
codex |
codex runs, and the default Codex home (or each codex account in round.accounts) is logged in and has the herdr integration |
codex is not on PATH and no codex account is in round.accounts |
agents |
the subagent files rota agents write generates are present and current |
nothing to report: the line appears only as a warn, when a file is missing or stale (fix: rota agents write) |
milestones |
with milestones on the tracker, .rota/milestones/ holds no files left from file mode |
nothing to report: the line appears only as a warn, when stale files exist (fix: rota migrate milestone-files --apply) |
config dir |
nothing to fail: the line shows the global config dir in use and where it came from (ROTA_CONFIG_DIR override, XDG_CONFIG_HOME or the default). Warns when a relative ROTA_CONFIG_DIR was ignored |
never |
state dir |
nothing to fail: the line shows the state dir that holds the project registry | never |
external knowledge |
the path in knowledge.external is a git clone with a remote and a rota-knowledge.json. Fails when the path is missing, not a git repository or has no remote; warns when the policy file is missing (writes then default to push). See External knowledge |
nothing to report: the line appears only when knowledge.external is set |
test |
nothing to fail: the line shows the test lock width (test.slots) and the smoke shard count bash test/gate.sh would use here: ROTA_SMOKE_SHARDS, else one shard per two cores, at most four |
never; the line appears only inside a project |
verify |
test.full or test.e2e is set, so the merge gate has something to run |
nothing to report: the line appears only as a warn, when both are empty under a local verify (fix: rota config set test.full '[...]') |
The three hook checks are opt-in. Until something rota hook install writes is present, they skip rather than fail a project that never installed the hooks; once it is, a partial or broken install fails. skills follows the same rule: it skips until rota skills install has written a manifest.
See unattended rounds for the hooks and parallel rounds for what a round does after a clean rota doctor.
Missing .rota/ from any other verb
Exit 3 (resolution), with the message no .rota/ directory here or in any parent and the hint run: rota init. Skills surface the verb’s error and hint, and the user runs rota init. rota update runs without a project, and rota init bootstraps one.
All exit codes: rota verb reference.