--- name: camus description: Run the Camus closed-loop on one task — discovery, plan, implement, then loop fix↔Codex-review until no P0/P1/P2 findings remain, then verify with type-check + tests. Manual-invoke only via /camus. disable-model-invocation: true --- # Camus — closed-loop task runner This skill is the **playbook**, not the engine. The engine is the pair of dynamic workflows (`camus-loop` for one task, `camus-feat` for an ordered task list) installed alongside it; this file holds the *standard that keeps it honest*. See `CAMUS-SPEC.md` at the repo root for the full design and run-targets. **Install:** `npx camus-cli install` (from a repo checkout: `./install.sh` in `packages/cli/`) — copies skill + workflows into `~/.claude`; `npx camus-cli check` detects source↔installed drift — run it before any auto/feat run. ## What this does Given one task, run a bounded closed loop: ``` discovery → plan → implement → [ Codex review → fix ]* → verify ↑ loop while priority<=2 findings, up to ROUND_CAP ``` - **Implementation** is done by Claude (cheap model for bulk work). - **Review** is done by **Codex** (a competitor) — this is deliberate, to sidestep self-preferential bias. Claude must NOT re-judge Codex's verdict. - **Verification** is deterministic and **stack-agnostic**: `verify.sh` auto-detects the repo's build/test commands (node/python/rust/go/foundry/make) with zero per-project config, or honours `CAMUS_VERIFY_CMD` as an explicit override. If nothing is detected it fails loud (`no_verifier_detected`) — absence of a verifier is never a pass. ## Severity model (the gate) Codex returns findings tagged `priority` 0–3. The loop blocks on **priority ≤ 2**. | Priority | Meaning | Blocks the loop? | |---|---|---| | **P0** | Critical: breaks build/tests, data loss, security hole, wrong core logic, regression | Yes | | **P1** | High: likely bug, missing error handling, broken contract, untested critical path | Yes | | **P2** | Medium: correctness/maintainability risk, unhandled edge case, logic that will bite | Yes | | **P3** | Nit: style, naming, cosmetic | No (recorded, never loops) | **Exit conditions** (whichever comes first): 1. No findings with priority ≤ 2 → loop is clean → proceed to verify. 2. `rounds == ROUND_CAP` → stop, surface remaining P2s to the human. Never loop on a P3. Defaults: `ROUND_CAP = 3`. ## review_unresolved is a decision, not always a failure (2026-06-11) When review doesn't converge, the loop **consults deterministic verify before reporting** so the human sees both independent axes. A green suite is necessary evidence, but it does not clear an unresolved finding or prove untested contract behavior. Two behaviors: - **Verify is run on a non-converged review.** A `review_unresolved` carries `verifyClean`: `true` (type-check/lint/tests pass → a DECISION POINT: accept the worktree as-is, or refine), `false` (genuinely not done), or `null` (verify couldn't run). camus-feat surfaces a verify-clean halt as a decision, never a plain failure. - **A finding re-raised after a fix STOPS the loop early.** Same `code_location + title` in two consecutive rounds (a fix was dispatched between) → stop and surface it (`stuck`) for a human to resolve *stale-re-flag vs real disagreement*, instead of burning the rest of `roundCap`. - **Confidence trend disambiguates accept-vs-refine.** Each finding's `confidence_score` is tracked across rounds; a re-raised finding whose confidence FALLS (the reviewer losing conviction) → most likely a stale re-flag → the halt leans ACCEPT; steady/rising → a consistent disagreement → leans REFINE. Guidance only — never a hard auto-pass gate (a real P1 was observed starting at 0.82 and rising to 0.92, so an absolute confidence cut would misfire). - **ACCEPT executes via land mode** (run-5 fix: the loop's weakest link was landing code it had already proven — resume re-entered plan→implement→review and a flaky review infra_errored before ever committing an already-clean staged diff). Re-run the feat with `land: [""]` (or the loop with `land: true`): it resolves the EXISTING worktree and goes straight to commit → prep → verify → merge. No re-plan/re-implement/re-review; deterministic verify remains the unskippable arbiter (verify red under land → `verify_failed`, never a silent ship). An already-committed worktree (empty stage) proceeds to verify rather than failing. REFINE = re-run normally with `answers:{:"…"}`. - **The commit→merge death window auto-recovers** (audit P2): the feat persists `ready_to_merge` the moment the loop returns done (review clean + committed + verify green) and BEFORE the merge runs. A resume that finds a task in `ready_to_merge` AUTO-lands it — no `land` list needed — because the work is fully proven and only the merge was missing; re-running the full loop there would re-enter review for nothing and collide on the existing branch/worktree. The post-merge half of the window is covered too: if the crash hit AFTER the merge landed (before `done` persisted), the resume's re-merge reports already-up-to-date and the merge runner checks feat history for this task's deterministic merge-commit message — evidence found → recorded DONE; check ran and found nothing (explicit null/empty) → the original no-op guard stands (an empty branch never upgrades itself). An INCOMPLETE or SELF-CONTRADICTORY merge report — verdict fields (`committed`/`alreadyUpToDate`) omitted, before/after SHAs missing (required non-null on a successful merge), flags contradicting HEAD movement (the SHAs are ground truth), or the evidence check omitted — fails loud (`feat_integration_failed`, task stays `ready_to_merge` for an idempotent merge retry): missing or contradictory evidence is an infra condition, never a verdict (noop or done). - **Land is authorized by prior state, not by the request** (audit P1): the feat forwards `land` ONLY for a task whose persisted prior status is `needs_decision` — proof that review ran and deterministic verify was green. An unproven land request downgrades LOUDLY to the full loop (a worktree from a run killed pre-review must never skip codex review just because verify passes). Standalone `camus-loop {land:true}` is the deliberate manual override — the human invoking it directly takes the reviewer's place. `land` is part of the canonical `resumeArgs` (dropping it on a resume would re-enter the full loop — the exact failure land exists to avoid). ## Hard rules 1. **Bound everything.** Round cap on review/fix; soft token target per task; rely on the runtime's enforced 16-concurrent / 1,000-total agent caps as the outer backstop. (The `"use Nk tokens"` budget is model-respected, not a runtime kill-switch — do not trust it as the guarantee.) 2. **Infra failure ≠ findings.** If Codex fails to run (nonzero exit, empty/unparseable output, rate-limit, auth blip), that is `ran:false` — retry with backoff, and NEVER feed it into the fix loop as if it were a rejection, and NEVER treat it as clean. This is the #1 cause of runaway loops. The adapter enforces this; do not bypass it. 3. **Fresh reviewer each round.** Spawn a new Codex session per review (not `resume`) so it re-raises issues it might otherwise decline to repeat. 4. **Thin reviewer.** The reviewer's only job is to run Codex and return JSON. No Claude re-judgement of the verdict. 5. **Deterministic ground truth wins.** A clean Codex verdict does not ship code that fails `type-check`/`test`. Verification is the final, non-negotiable gate. 6. **Execution model.** The workflow script never runs shell/files. Reviewer and verifier *agents* run the commands (`scripts/codex_review.sh`, `scripts/verify.sh`) and return strict JSON; the script only evaluates the JSON and branches. ## How the pieces fit - `review-prompt.md` — the adversarial audit persona + severity rubric handed to Codex. - `REVIEW-CONTRACT.md` — the versioned (rc1) agreement for what a review carries: contract version, scope (full/light), reviewer qualification (builtin1/qual1), and origin/operator/transport/connection provenance. `asGate` compares every field against workflow-computed expectations and refuses drift; terminal provenance comes only from an accepted binding. The hardened `builtin1` tier also excludes user/project/system/managed configuration and custom model catalogs; managed hosts fail closed unless the run explicitly requests a configurable (`qual1`) reviewer. - `sev.schema.json` — the Codex `--output-schema` (findings[] with priority 0–3 + verdict). - `scripts/codex_review.sh` — reviewer agent runs this → normalized gate JSON. - `scripts/verify.sh` — verifier agent runs this → `{pass, failures}` JSON. - `scripts/adapter.py` — normalizes Codex output, enforces the infra guard, maps to/from v1's `APPROVED/REJECTED` contract. Pure stdlib; unit-tested in `scripts/test_adapter.py`. ## Run surface - `/camus-plan ` — OPTIONAL pre-step. Reframes a raw/vague/large request into a quality-gated camus-feat task list: ground (explore the repo read-only) → clarify (ask on a genuine ambiguity) → architect → decompose to camus standards → adversarially critique → emit. Writes `~/.camus/plans/.json` (the exact camus-feat args) + a readable `.md`; never writes code. Args: `{request, targetPath?, policy?, model?, modelTier?, answers?}`. Same ask posture as the feat (`policy`; resume with `answers:{:"…"}`). Use it to get smaller, clearer tasks BEFORE running — better plans converge in fewer review rounds. - `/camus-loop ` — one task. Args: a string, or `{task, targetPath, model, modelTier, skipPlan, policy, humanAnswer, branchPrefix, idSalt, identitySalt, roundCap, land}`. `idSalt` means feat ownership (feat heartbeat + parent-tree containment). `identitySalt` is the mutually exclusive standalone-custody seam used by Studio: deterministic branch/worktree + heartbeat, idempotent replay of that exact worktree, and no feat-only containment precondition. `roundCap` (1..10, default 3) raises/lowers the review↔fix budget for a known-large task (run feedback 2026-06-10: a big task that converges P1→P2 can run out of rounds at the default cap). `land: true` = land mode (run-5 fix): commit the task's EXISTING, already-proven worktree → verify → done, skipping plan/implement/review entirely. STANDALONE-loop land is the manual override (the human invoking it takes the reviewer's place). Under a feat, land is state-authorized instead: explicit `land: ["", …]` executes an ACCEPT on a `needs_decision` halt, and a task persisted as `ready_to_merge` (died between commit and merge) AUTO-lands on resume with no land list at all. - `/camus-feat` — an ordered task list as one feature: preflight → feat branch → env + baseline verify → per-task loop (merge on `done`) → env re-check + integration verify → report at `~/.camus/reports/.json`. Forwards `policy`/`model`/`modelTier`/`skipPlan`/`roundCap`/`answers`. - `camus status [featId]` — one-shot dashboard for a run, from ANY terminal, read-only and token-free: feat header, per-task board (rounds/tokens/model), the last 10 run-log steps, recent Codex review rounds (audit-file timeline), and any pending steer note. - `camus watch [featId]` — the LIVE interactive version: the same dashboard auto-refreshing on the alternate screen, with one-key steering through the same audited steer.py path (`p` pause · `g` guidance · `c` clear · `q` quit). Degrades to a one-shot status print when there is no TTY. Backbone = camus's own stable state; `transcripts.py` adds a best-effort **live-agents** section read from the workflow's on-disk transcripts (per-agent model/tokens/tool calls), so the deep per-loop detail works from ANY terminal — and degrades to the backbone alone when Claude Code's internal transcript format shifts. - `camus steer` — redirect a RUNNING feat at its next task boundary: `camus steer ""` (steers the next task, threaded in exactly like a `needs_human` answer), `--task ""` (a specific task), `--pause` (graceful resumable halt), `--show` / `--clear`. A note is consumed ONCE. Live mid-task injection is deliberately unsupported — the engine is a deterministic, resumable script; the boundary is the safe redirect point. ## Outer-agent operator loop When another agent operates Camus for a human, keep that layer thin. Camus owns task execution, review rounds, custody, and receipts; the outer agent chooses the surface, supplies the complete contract, watches host-owned evidence, and hands the result back. 1. **Choose the smallest useful surface.** Use Studio when the human benefits from visible seat selection, live phase/status controls, stop/resume, or receipt inspection. Use `/camus-loop` directly for one already-bounded task and `/camus-feat` for an ordered package. Use `/camus-plan` only when the request genuinely needs decomposition. Studio must accept the full acceptance contract and supported controls; never replace them with a narrower UI preset. 2. **Set outcomes, then allow bounded freedom.** Bind the source/spec, exact scope, exclusions, deterministic verify command, and handoff condition. Leave implementation choices open where that contract permits them. Pick the smallest credible `roundCap` and model/effort pairing for the stakes; do not spend review rounds to optimize style. 3. **Let a healthy run solve the task.** Observe `camus watch`/`camus status` or Studio's phase, process, worktree, and receipt signals. Do not inspect live reviewer-handle artifacts, add a third polling loop, re-judge every clean verdict, or implement the task outside Camus while the run is viable. 4. **Interrupt only for material invalidation.** Stop and repair Camus when custody is wrong, the task/contract drifts, a round cap is ignored, a process is orphaned, verification is bypassed, or a receipt/provenance claim is false. Record cosmetic UI friction, minor copy, token/latency waste, and non-blocking ergonomics for the retrospective instead of restarting the run. 5. **Close from evidence.** Require a terminal state, the intended clean worktree/commit, head-bound deterministic verification, and an honest valid receipt. Resume with the same persisted identity after an infra repair; do not create a parallel worktree or silently finish the code by hand. 6. **Feed back without self-modifying.** Run `camus retro` after meaningful dogfood sessions and combine its read-only history with the operator's bugs/UX/efficiency notes. Prioritize recurring or result-invalidating problems. Retro recommends; it never edits Camus or run configuration. ## Shipped hardening (all live, all tested) - **Target guard** (`_guard.sh`): every gate script binds to the caller's repo, `camus/*` branches, and `camus-wt-*` worktrees — fail-closed, 3 Codex review rounds, probe-verified. - **Auto mode, zero-click**: `npx camus-cli auto-setup` (in-repo: `install.sh --auto-setup`) installs a narrow scoped profile (egress trust for the Codex review + allow rules for the 5 gate scripts only). Proven live: full feat runs with zero permission prompts. - **HITL policy dial**: `policy: autonomous | ask_on_ambiguity (default) | ask_on_major`. Plan phase rates clarity; `needs_human` halts the feat with a question; resume re-runs with the answer. Always-on **decisions log** lands in the report. - **Model control**: classifier sets the floor (trivial→Sonnet, else Opus); `model`/`modelTier` args force it; reviewer-persistence escalation bumps the fix model on round ≥ 2 or a P0. `skipPlan` is opt-in and only effective under `autonomous` (never silently disables the ask-gate). - **Codex audit trail**: every review round persists raw+parsed Codex output to `~/.camus/reviews/-r.json` — a missing file means the binary never ran. - **Auto-resume**: `resume_scan.py` finds interrupted (`running`, idle ≥ 30 min) feats and emits canonical `resumeArgs` verbatim. - **Worktree dep-prep** (`prep.sh`): fresh worktrees install deps before verify; a toolchain that can't run returns `verify_inconclusive`, never `verify_failed`. - **Out-of-tree worktrees + cleanup**: task worktrees live under `~/.camus/worktrees/-/` (never inside or beside the user's project — game-engine asset importers scan the tree, and sibling folders read as per-task trash). `camus-feat` removes each worktree once its branch is merged (branches kept for audit); failed/paused tasks keep theirs for inspection. - **Watch & steer**: the feat persists a run-log event ring (last 20 steps, carried across resumes) + per-task telemetry into its state file; `status.py` renders it together with the per-round Codex audit mtimes. `steer.py` writes a once-consumed note the feat checks at every task boundary (pause / guidance / per-task answers); `paused_by_user` is terminal for the auto-resumer — only a human resumes a human pause. - **Review input completeness**: `codex_review.sh` intent-to-adds (`git add -N`) the worktree before reviewing, so NEW files appear in the diff Codex reads (run feedback 2026-06-10: a task built mostly of new files was near-invisible to plain `git diff`). It also forces `