new

The goal is: $ARGUMENTS. Self-contained; run shell via the Bash tool.

Shell discipline: the Bash tool's cwd persists across calls — never bare-cd. Wrap any worktree-scoped command in a subshell ( cd "$WT" && … ), or use git -C "$WT" … / absolute paths. (A leaked cd makes later relative-path find/check-ignore resolve in the wrong tree.)

Preflight (do this first). Run node "${CLAUDE_PLUGIN_ROOT}/bin/seeks.mjs" preflight. If ok is false, surface the hint and offer to fix it before going further (the loop is dead without it): for a version-manager node, either symlink it onto a system PATH (sudo ln -s "$(command -v node)" /usr/local/bin/node) or add "env": { "PATH": "<dir-of-node>:/usr/bin:/bin" } to ~/.claude/settings.json (you may edit that file with consent). Re-run preflight until ok:true, then continue. (This is the #1 install failure — catch it here, not as a cryptic "Stop hook error" mid-run.)

1. Name the loop (<name>). If $ARGUMENTS is empty → ask "what should this loop achieve?" and use the answer as the goal. If $ARGUMENTS is a single bare token with no spaces → treat it as the name and ask for the goal. Otherwise derive a short kebab-case <name> (≤4 words) from the goal — e.g. "fix the auth timeout bug" → fix-auth-timeout, "raise test coverage to 90%" → raise-coverage. Tell the user the chosen name and that they can rename ("call it X instead"). Use that literal <name> everywhere below.
2. Intake (one question at a time): you already have the goal — confirm/sharpen it. Disclose what seeks will do to their code and pick the level (→ spec.md frontmatter, default L2): say it plainly — "I'll edit your code and commit on an isolated branch seeks/<name> that I never push or merge — that's L2, the default. Prefer report-only with no edits? say L1." These levels are now hard-enforced by a PreToolUse hook (not just guidance): at L1 the maker truly cannot edit source or commit, and at no level can the edit tools touch denylist paths, leave the worktree, or hand-write loop state — nor can Bash git push/merge/rebase. (Bash is otherwise unpoliced; reads are never blocked.) Want it to deliver on its own? L3 — on done it pushes seeks/<name> and opens a PR for you to merge (it still never merges to main itself); if gh/a remote aren't available it keeps the branch locally. For fully unattended L3 runs people often launch claude in bypassPermissions — say plainly what that costs: the seeks PreToolUse denials still fire (edits, loop state, git push/merge/rebase), but every other Bash command is auto-approved with no human in the loop, and Bash is not otherwise policed by default. If the goal or the repo is not fully trusted, offer SEEKS_STRICT_BASH=1 (or set strict_bash:true in the init JSON at step 6, plus strict_bash_allow for any extra commands the done-conditions need) — Bash then becomes deny-by-default against an allowlist. Say honestly that it is an allowlist and not a sandbox (node -e is still reachable), and that a container is the only real guarantee. Then get executable done-conditions (each: id, command, expected exit/output). Detect first, don't interview cold — by READING the repo, not a hardcoded language list: look at the CI config (.github/workflows/*.yml, .gitlab-ci.yml — the run: steps are the project's own definition of passing), then any command-runner the author defined (package.json scripts, Makefile/justfile/Taskfile targets), then the language's own test/build invocation if obvious from the manifest. This works for any language — infer it, don't rely on a built-in toolchain table. Propose what you found in one line ("CI runs npm test and tsc --noEmit — use these? [Y]") and only fall back to interviewing if you genuinely can't find a runnable check. Subjective acceptance → mark human-required. Refuse to proceed until ≥1 runnable check exists (or all are human-required).
   • Effort / time budget. Ask: "How hard should this run — quick, thorough (default), or overnight/?" Map: quick → low cap, no clock; thorough → defaults; overnight/custom → parse the duration (e.g. 8h→28800) and put time_budget_sec + effort:"overnight" in the init JSON (step 6). A time budget is a hard ceiling enforced by the Stop + PreToolUse hooks regardless of whether the agent yields — /seeks:start stamps the clock, so it counts from each start. As the deadline nears (last ~15%), the loop enters a wind-down: it stops new work, writes summary.md, and commits, then the clock halts it with a ⏰ summary banner (found / open / depth). Warn the user if the chosen budget is under ~3 minutes — that's shorter than one pass, so it may halt before any finding lands; suggest a larger budget but proceed if they insist.
   • Artifact/report goals (e.g. "find bugs", audits — no runnable oracle, only a produced artifact): a "report exists + contains file:line" check proves shape, not truth, and a naive user over-trusts the green. So additionally require in spec.md: (a) a report template — every finding cites file:line + reasoning + a repro/anchor (the triggering input, or the exact code path); (b) a verifier spot-check condition — the verifier opens the cited source for ≥N findings (default 3, or all if fewer), confirms each claim is actually supported there, and rejects the artifact if any cited location doesn't back the finding. Tell the user plainly: seeks certifies the artifact (shape + spot-check); the human owns full validity.
   • Open-ended goals ("fix all bugs", "fix/find every X" — no single terminating oracle): EXPAND them so the loop READS the code and hunts real defects, not just chases a green tool. (a) Discovery = creative code review. Each per-pass sweep reads the source in the blast radius and reasons about correctness like a skeptical reviewer — logic / off-by-one, boundary/operator mistakes, unhandled None/empty/error paths, bad parsing, timezone/encoding/locale bugs, resource leaks, races, auth/injection gaps. The toolchain (ruff+mypy+pytest; dotnet build; npm test) is the regression floor — fixes must keep it green — it is NOT the bug finder. (b) Set min_dry_sweeps (default 2): the loop must do two consecutive creative read-throughs through different lenses that surface no new real bug before it can certify (the engine rotates lenses — concurrency, error-handling, boundary, resource-lifecycle, serialization, input-trust — and a repeated lens won't count toward "dry"). Optionally set sweep_lenses to tailor/weight the set per language. (c) Raise max_iters (e.g. 200) and optionally a wall-clock time_budget. For an overnight/exhaustive run set exhaustive:true + min_dry_depth_rounds:2 and seed sweep_lenses = the base catalog plus 3-6 goal-tailored views (a scraper → time-timezone,encoding-locale,relative-url; a web app → security-authz,session,csrf) — the loop then covers every view and deepens (depth 1 logic → 2 dataflow → 3 adversarial/probing-tests) until the time budget halts it, instead of stopping after two dry sweeps. In exhaustive mode the certification bar is dry_depth_rounds (a full-catalog-dry pass, twice) — the gate ignores min_dry_sweeps there, so any min_dry_sweeps you also set is informational only. The driver decides when to verify via seeks sweep-status (the gate's own predicate), so the two never diverge; tell the user an exhaustive run usually ends at the time budget (⏰ halt with a findings summary), not a clean ✅ done — reaching done requires the whole catalog to come up dry at increasing depth, which a rich codebase rarely does before the clock. Also set goal_mode:"open_ended" (a targeted goal stays goal_mode:"targeted", min_dry_sweeps:0, no catalog sweep). (d) Require the verifier to spot-check that each fixed bug was real (cite file:line + why), per the artifact-goal rule above. (e) Rewrite the terse goal into a rich spec.md — blast radius, the creative-review strategy, the regression floor, the budget. Tell the user: seeks reads the code and keeps hunting until two review passes come up empty — it will not stop after one fix or settle for "tests pass".
3. Recipe .seeks/loops/<name>/spec.md with frontmatter level (default L2) and a ## Done-conditions list (+ a ## Report template section for artifact/report goals, per step 1). Also pass the conditions as structured data in the init JSON: conditions: [{id, cmd, expect, human_required}] (subjective acceptance → human_required:true, no cmd). init refuses a loop with no runnable check and no human_required fallback, and the gate never lets a no-check loop report done — it escalates to needs-human. (If oracle_globs would match zero files for a "make tests pass" goal, flag it.)
4. Tier + config. Resolve the usage tier: node "${CLAUDE_PLUGIN_ROOT}/bin/seeks.mjs" tier-get. If it prints none, this is the user's first loop — explain the three tiers (Light = conserve usage: all-sonnet + haiku triage, low caps; Balanced (default) = maker & verifier on opus, intake/analyzer on sonnet; All-out = opus everywhere, verifier at max effort, high caps + deeper sweeps) and ask them to pick, then node "${CLAUDE_PLUGIN_ROOT}/bin/seeks.mjs" tier-set <light|balanced|all-out> and re-run tier-get. (You may also ask "use a different tier for just this loop?" and use that tier's preset instead — affects only this project.) The tier-get JSON gives roles, max_iters, max_iters_openended, min_dry_sweeps. Then — if .seeks/config.json is absent, create it with defaults: {"default_level":"L2","max_iters":<the tier's max_iters — open-ended/"fix all" goal ? max_iters_openended : max_iters>,"stuck_threshold":3,"condition_reject_threshold":3,"lock_stale_ttl_sec":600,"base_ref":"<current branch from git rev-parse --abbrev-ref HEAD>","denylist":["**/.env","**/secrets/**",".git/**"],"roles":<the active tier's rolesobject fromtier-get>}. The loop's level, oracle_globs (defaults to common test patterns), and denylist are persisted into status.json at init so the PreToolUse enforcement hook can read them.
5. Analyze — dispatch the analyzer as a subagent using the analyzer role's model (node "${CLAUDE_PLUGIN_ROOT}/bin/seeks.mjs" role analyzer → {model,effort}): edge-trace imports/refs/call-sites from the goal (not a keyword scan); write .seeks/run/<name>/context.md (depth-capped).
6. Worktree — git worktree add .claude/worktrees/<name> -b seeks/<name> "$(git rev-parse --abbrev-ref HEAD)". Ensure .gitignore contains /.seeks/run/ and /.claude/worktrees/ (append any missing line).
7. Scaffold — node "${CLAUDE_PLUGIN_ROOT}/bin/seeks.mjs" init <name> '{"loop":"<name>","armed":false,"done":false,"verifier_certified":false,"open_items":0,"items_closed_total":0,"no_progress_count":0,"condition_rejects":{},"dry_sweeps":0,"min_dry_sweeps":<the tier's min_dry_sweeps for an open-ended/"fix all" goal; else 0>,"base_ref":"<current branch from git rev-parse --abbrev-ref HEAD>","worktree_path":"<ABS path of .claude/worktrees/<name>>","max_iters":<the tier's max_iters_openended for an open-ended goal; else its max_iters>,"stuck_threshold":3,"condition_reject_threshold":3,"lock_stale_ttl_sec":600,"level":"<L1 or L2 from spec frontmatter; default L2>","denylist":<the denylist array from config.json>}'. Then backlog-add each starter item; reconcile node "${CLAUDE_PLUGIN_ROOT}/bin/seeks.mjs" status-set <name> "{\"open_items\":<count>,\"open_items_prev\":<count>}"; pin the base node "${CLAUDE_PLUGIN_ROOT}/bin/seeks.mjs" base-record <name> (records base_sha for the freshness check). Write an initial state.md.
8. On any failure, roll back via Node: node "${CLAUDE_PLUGIN_ROOT}/bin/seeks.mjs" gc <name> (removes worktree+branch+run dir; keeps spec.md). Report the failure.