xiv-operator

Babysits a long-running stack build: polls triage, auto-resumes transient failures, escalates the rest.

Use it when a xiv stack build runs long — typically overnight — and you want a cheap agent keeping it alive instead of a human watching a terminal. The agent's job is deliberately narrow and mechanical: observe → classify → take ONE action → report. It is not a coder; it never edits files, never reviews code, never decides product questions.

The human hands it a feature slug, and everything runs as --feature <slug>. The skill's first instruction is to run xiv how-to once — the canonical runbook for the stack lifecycle — because this skill is only the recovery layer on top of that runbook.

The loop

1. Observe. xiv stack triage --feature <slug> --json returns structured status: phase, action, counts, inFlight, staleBranches, summary, hint, and activeRuns (raw smithers ps text). See Stack map & triage.
2. Classify. Match against the decision table, using the action field as the baseline and error text for a more specific row.
3. Act — exactly one of two kinds: SAFE-RESUME (do it, keep watching) or STOP + ESCALATE (stop touching the run, report to the human). When in doubt, escalate.
4. Report or wait. Healthy and progressing means wait ~5–10 minutes and re-poll. No change across two polls means escalate.

What it resumes vs. what it escalates

Resumes are capped at 3 per run with the same failure — after that the failure is not transient, and the agent escalates.

Structure

• SKILL.md — the loop, the summary decision table, and the hard guardrails.
• references/commands.md — the only commands the agent may run, with exact flags.
• references/failure-playbook.md — the full signal → diagnosis → action table.
• references/error-signatures.md — case-insensitive text snippets that identify each failure category (auth, rate-limit, quota, crash/stale, jj-conflict, network/disk, waiting-on-human).
• references/escalation-template.md — the fixed report shape for handing back: what happened, where, evidence, progress counts, resumes tried, and a suggested fix.
• scripts/triage.sh <slug> — a read-only one-shot snapshot: structured triage plus smithers ps --all, for when a single command beats two.

Allowed-tools allowlisting

The frontmatter allowlists individual Bash commands rather than whole binaries — xiv how-to, xiv stack triage/status/build/preview, xiv ps, xiv logs, smithers ps/why/events/inspect/supervise, and cat. Notably absent: xiv stack push, xiv stack amend, git, gh, and jj — the agent mechanically cannot publish PRs, change code, or touch version control, which is what makes it safe to leave running unattended.

Notable design decisions

• Resume with the original launch flags. xiv stack build is idempotent (finished entries are skipped), but flags do not persist: a resume must repeat --max-iterations, --skip-acceptance-review, --repo, and any XIV_* env prefix verbatim, or the remaining entries silently build under different settings. If the agent doesn't know how the build was launched, it asks instead of guessing.
• Never raise the tier or iteration cap. Both cost real money; a run burning passes is a reason to escalate, not to buy more of them.
• Auth failures are never retried — retrying just fails again; the escalation names the exact re-login command instead.
• Failing tests on a built entry don't stop the build. They are noted for the human's review of that PR; the stack keeps building.

Related

stack-plan runs before the build; this skill runs during it; the stack workflows page covers what the build itself does. For one-off "is it stuck?" questions (not ongoing supervision), the xiv skill's smithers-ops.md reference is enough.