Superloopy Evidence Loop

superloopy-loop

Use this skill when the user asks for Superloopy, loopywork, lpy, a loop harness, durable criteria, evidence-backed completion, strict-but-light task flow, or guided next actions.

Contract

• State lives in .superloopy/, or .superloopy/sessions/<id>/ when --session-id is used.
• Do not hand-edit .superloopy/goals.json; use the CLI.
• A criterion can pass only after a real artifact exists under the active evidence root.
• User steering must use SUPERLOOPY_STEER JSON; do not hand-edit .superloopy/goals.json.
• Executor receipts should end with SUPERLOOPY_EVIDENCE: <path-under-active-evidence-root>.
• Legacy EVIDENCE_RECORDED receipts remain accepted for compatibility.
• Tests are useful evidence, but completion requires the Superloopy evidence artifact.
• Use superloopy loop prove when an active goal needs command-backed evidence for its next unresolved criterion.
• Keep the workflow lightweight unless the task genuinely needs heavier review.
• A leading loopy keyword wakes the loop engineer: take the rest of the prompt as the brief, run the loop yourself, and report progress instead of asking the user to type Superloopy commands.
• loopywork, $lpy, and lpy are lighter prompt triggers; they inject guidance but never mutate .superloopy/ state by themselves.
• Full Loopy runs default to direct, concise, complete user-facing progress and final responses. Exact say-it-straight off / 직설 모드 끄기 and say-it-straight on / 직설 모드 켜기 controls apply only to the current incomplete loop; new loops reset this default to enabled.
• This output overlay changes wording only. It never silently rewrites supplied prose, task artifacts, code, documentation, comments, evidence, quotations, or user source text; direct artifact editing remains explicit-only. i-have-adhd still owns structure, and humanize-korean still owns Korean artifact rewriting.

Loop engineer (loopy keyword)

When the user opens a message with loopy <task>, act as the loop engineer:

• Start once with superloopy loop begin --brief "<task>" --mode light --json; do not create a second plan if one is active.
• Drive each step from superloopy loop guide --json, prove criteria with superloopy loop prove -- <command>, preflight with superloopy loop check, then finish with superloopy loop finish --evidence "<summary>" --artifact .superloopy/evidence/gate.json --json.
• The user types only loopy <task>. You run every Superloopy command and report progress as criteria proven and the next step.
• loopy with no task asks what to build; loopy mid-loop resumes from existing state. The Stop hook is packaged with the plugin but stays inert until SUPERLOOPY_STOP_HOOK=on; when enabled, it blocks completion until evidence exists.

Reassurance-copy gate (conditional)

• Decide from the affected artifact: if it creates or changes user-visible Korean product copy about behavior, add a plan criterion for RC-1 through RC-4 and Korean naturalness.
• State supplied outcomes, fallback, recovery, or next action; preserve verified privacy/legal commitments; never invent behavior.
• Apply humanize-korean semantic review for misplaced modifiers.
• Ignore internal logs, developer docs, quotations, general/marketing prose, and non-Korean copy.

Read the detailed reassurance-copy reference when this condition applies. Artifact ownership decides the condition; prompt wording does not.

Two tiers: solo and crew (loopy team)

The loop engineer directive is injected for every loopy prompt, and it scales to the work:

• Solo (default). A plain loopy <task> drives one agent through the loop. The directive still permits light delegation: if the work splits into 2+ genuinely independent slices, you may fan them out with the native subagent controls exposed by the current host; keep each assignment self-contained. For a single cohesive change, stay solo.
• Crew (loopy team <task> / loopy crew <task>, the connected one-word loopycrew <task>, or the standalone ultrawork <task>). The same engineer escalates into full fan-out: dispatch the crew across independent lanes, collect them with the host's native lifecycle controls, and record only artifact-backed proof. The escalation keyword is stripped from the brief that seeds the loop. This is the active counterpart to "Optional Subagent-Driven Mode" below — same dispatch contract, receipt gate, and mandatory handoff/fleet tracking.

Each crew dispatch uses the configured name when the host exposes named selection: franky to build, zoro to review, usopp to test, jinbe to gate, robin to audit, and nami to navigate. The assignment also stays self-contained (TASK: act as <role> ...). The orchestrator itself runs on the model the user selected in the host (gpt-6-astra is allowed when selected); crew lanes keep their model-policy.json pins and never inherit the orchestrator's model. The host-owned stop callback observes the actual role identity; if the host cannot attest that identity or model, report role_unverified or model_unverified.

Both tiers are steering, not enforcement: the directive instructs the main agent, and actual spawning depends on the host's native multi-agent tool being available. Superloopy never spawns; it gates the evidence workers deliver. See "Optional Subagent-Driven Mode" for the full dispatch contract and crew roles.

Continuation Engine

The optional Stop hook is a bounded, progress-gated engine, not a one-shot nudge. With SUPERLOOPY_STOP_HOOK=on, while work remains it keeps driving you toward evidence-backed completion, counting iterations in .superloopy/loop-control.json.

• Progress is measured by recorded proof (passed criteria and completed goals) against a high-water mark; only new proof resets the no-progress counter.
• It never completes anything. Completion stays the plan's authority via superloopy loop check + superloopy loop finish with real artifacts.
• A cap or no-progress stall marks the loop blocked (visible in superloopy loop status) and asks for a human — it never fabricates a done.
• Quota/usage limits are distinct from blocked: when the host transcript shows a usage/rate/quota-limit marker, the loop is marked paused (reason quota) in .superloopy/loop-control.json — a resumable state. It does not burn the no-progress counter and is never mistaken for completion; a loop_paused/loop_resumed pair is written to the ledger. Superloopy is hook-driven and cannot self-wake, so it only pauses cleanly and stays resumable — see "Auto-resume after a quota reset" below.
• Knobs: SUPERLOOPY_MAX_ITERATIONS (default 50, 0 = unlimited; the no-progress guard stays active), SUPERLOOPY_MAX_STALLED (default 3), SUPERLOOPY_CONTINUATION=off (legacy single continuation), SUPERLOOPY_QUOTA_MARKERS (comma/newline list of extra host-specific limit phrases — the built-in set is conservative, so set this to your host's exact banner text).

Auto-resume after a quota reset

Superloopy detects the limit and pauses; waking when quota resets is an external job (Superloopy has no daemon). Run an idempotent scheduler that resumes the loop and stops once it is done:

• Read superloopy loop status --json: if summary.aggregateComplete is false, resume by re-running the loop (loopy <continue>, or superloopy loop guide --json then the next command); if complete, no-op.
• Schedule it on a cadence that outlasts the limit window — a host cron / cloud routine every 20–30 min, or aligned to a known weekly reset. The first run after the reset succeeds; earlier runs simply no-op while still limited.
• Keep it idempotent and self-terminating, exactly like Superloopy's own gates. Superloopy supplies the resumable state; the scheduler supplies the wake.

Evidence Audit

superloopy loop audit independently re-checks recorded proof. Superloopy itself re-runs each command-backed passed criterion (the deterministic source of truth) and records the result in .superloopy/audit-state.json; a re-run that does not reproduce is marked inconclusive, never a silent fail.

• For independent judgment, dispatch a read-only robin subagent: it judges the re-run against the scenario and ends with SUPERLOOPY_AUDIT: <verdict-path>. When the receipt arrives, Superloopy re-derives that criterion's floor in-process (it does not trust the recorded .superloopy/audit-state.json, which the worker can write) and accepts the verdict only if it is hash-bound to that fresh re-run. Floor dominance is symmetric: the verdict may act only when the re-run reproduces — it can neither upgrade nor flip a non-reproducing (inconclusive) re-run.
• At completion the deterministic spine actually gates the result: superloopy loop review/checkpoint re-derive every passed criterion (not just the cited ones) and hash-verify every cited audit verdict, so a regressed command criterion can't be skipped and a structurally valid audit section pointing at hand-written verdict files cannot authorize completion.
• Command-backed vs manual proof: the deterministic guarantee is strongest for command-backed criteria — Superloopy re-runs the command and reads the live exit code. A manual (commandless) criterion can only be re-validated for artifact existence; its correctness is not command-reproducible and rests on the auditor's (autonomous LLM) judgment and human review, not on the deterministic floor. Prefer command-backed proof (superloopy loop prove -- <command>) wherever the work allows — the autonomous loop engineer does this by default, so most criteria get the strong guarantee automatically.
• A failed audit (deterministic floor fail or a verdict: fail) flips the criterion off pass with the gap recorded in its notes, so the continuation engine re-drives exactly that criterion to be fixed and re-audited. A non-reproducing command re-run is inconclusive and never auto-flips (flaky-test safety).
• After SUPERLOOPY_AUDIT_MAX_FAILS (default 3) audit failures on the same criterion, it is marked blocked for a human instead of looping. Accepted audits are counted monotonically so honest fix → re-audit cycles register as progress.
• Honest limit: Superloopy cannot verify the auditor subagent was spawned isolated/read-only — it trusts the host's agent frame for that. It does NOT, however, trust its own recorded state: .superloopy/audit-state.json and .superloopy/loop-control.json are worker-writable, so the deterministic floor is re-derived in-process at both verdict acceptance and the completion gate — a forged state file cannot manufacture an accepted pass. The continuation counters (auditsAccepted, stall/high-water) are runaway backstops, not a security boundary; completion authority stays the plan's, and the engine never force-completes.

Optional Subagent-Driven Mode

Use project custom agents from .codex/agents/ only when the user asks for subagents or the work has independent implementation, review, and QA lanes. The normal single-agent Superloopy flow remains the default for small changes.

Superloopy provisions and tracks these agents; the host (Codex) spawns them. Superloopy never spawns. The host spawn surface cannot reliably select a bundled TOML role, model, or reasoning effort by name, so every dispatch must be self-contained and judged by delivered evidence — never by the role label requested. See docs/superloopy-host-contract.md.

Plugin installs bootstrap the superloopy command wrapper and bundled custom agents on the first approved SessionStart hook. If the host does not run that hook, run node src/cli.js install --json from the Superloopy checkout or installed plugin root. superloopy agents install remains available to copy only the bundled custom agents into the personal Codex agents directory ($CODEX_HOME/agents when set, otherwise ~/.codex/agents). Restart Codex after installation.

Parent agent responsibilities:

• Keep the Superloopy plan and criteria as the source of truth.
• If the requested repository path differs from cwd, verify and state the exact target path before editing or dispatching workers.
• Allocate one bounded handoff card per worker: goal, criterion or slice, allowed files, active evidence root, report artifact target, validation command, non-goals, and expected status values.
• Avoid parallel executors on overlapping files. Parallelize read-heavy review, QA, and summarization lanes first.
• In full crew mode, the implementation worker must own a real bounded implementation slice before the parent edits or completes that slice. If there is no safe independent implementation slice, stay solo or use a smaller read-only crew instead of pretending an implementer lane ran.
• Wait for worker summaries, then record only artifact-backed proof with superloopy loop prove, superloopy loop evidence, superloopy loop review, or superloopy loop checkpoint.
• Summarize worker output by status, claim, changed files, commands, artifacts, risks, and next action. Do not paste raw transcripts into the main thread unless they are the evidence.
• After each worker finishes, show the user a concise role completion line with the role, normalized verdict, artifact path, and next action before closing or respawning that lane.
• For full crew, record each dispatch with superloopy loop handoff --agent <name> --assignment <text> [--verdict <v>] [--artifact <path>] and run superloopy loop fleet --json before the final gate. The fleet output normalizes the workers' APPROVE/PASS/REJECT-style verdicts into one accept/reject/needs-context enum and lists outstanding workers. An accepted verdict requires a valid artifact under the active evidence root. A lifecycle verdict (working/in_progress/running) stays outstanding; an unresolved verdict (inconclusive/timeout/ack_only) normalizes to needs-context and is NEVER counted as accept. Rejected and needs-context lanes appear in attention. Known crew lanes may print one original completion line for terminal verdicts, choosing the user's language from the assignment or scoped brief when it matches the supported catalog (en, ko, ja, zh, es, fr, de, it, pt, id, hi, tr, vi, ru, ar, th), but the line is presentation only; artifacts, normalized verdicts, attention, and outstanding remain authoritative. Use --language <tag> or SUPERLOOPY_CREW_LANGUAGE=<tag> only when the prompt language cannot be inferred. Set SUPERLOOPY_MAX_PARALLEL for a soft over-dispatch warning. Handoffs are parent-side bookkeeping only — they never spawn or complete.
• Before the final summary, run untracked-aware status commands such as git status --short --untracked-files=all and git ls-files --others --exclude-standard so new evidence, scripts, and reports are not omitted from the diff review.