superloopy-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.

Load on demand

These references hold the situational detail. Read the one a row names when its condition holds; the rules above and below apply to every run.

Read	When
CLI flow	Running Superloopy commands beyond the loop engineer's begin → guide → prove → check → finish path: create, capture, manual evidence, trace, report, a blocked check repair plan, custom review/checkpoint gate workflows, or a cache-satisfied final proof.
Continuation engine	The Stop hook re-prompted you ("Superloopy continuation"), a loop shown blocked or paused in superloopy loop status, a quota/usage limit, or scheduling an auto-resume.
Evidence audit	Running superloopy loop audit, dispatching assayer, or handling a failed, inconclusive, or blocked audit.
Crew	Before dispatching any subagent (solo light delegation or loopy team/crew): parent responsibilities, handoff/fleet bookkeeping, the self-contained dispatch contract, subagent lifecycle, and agent allocation.
Reassurance copy	The reassurance-copy condition below applies.

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. After a loopy prompt, the packaged Stop hook keeps this session going while criteria remain, until the user sends a plain prompt (SUPERLOOPY_STOP_HOOK=on drives every session, off disables it). If it reports a worker that stopped without proof, treat that worker's reply as unproven.

Execution discipline

The loop engineer directive carries three rules distilled from a component-level harness study (arXiv 2609.20804). For strong models, most avoidable cost is redundant verification, unchanged re-runs of a failing check, and many small re-patches.

• Prove each criterion once with the narrowest command that decides it, then move on. Do not re-run passing proof or broad suites between criteria; loop finish re-runs every passed command-backed criterion before it completes (trusted commands only; commandless proof gets an artifact-existence check). loop check validates artifacts and does not re-run anything.
• When a proof fails, its output is already in the capture artifact. Read the failing part (tail or search), then change the code or the proof command before proving again; if the criterion itself is wrong, ask the user to revise it with a revise_criterion steer. After 3 consecutive failures of one criterion with the same command, exit, and normalized output tail, prove, capture, trace, check, and report emit a repeated-failing-proof warning. Normalization ignores run-to-run noise (timestamps, durations, labeled PIDs and ports, UUIDs, hashes, temp paths, stack positions, numbers of 10+ digits such as epoch times) but keeps other numbers, so a changed assertion value or pass/fail count breaks the streak. Any other evidence for that criterion, including a pass, a manual loop evidence record, or a revised criterion, resets it. The warning is advisory and never blocks; with SUPERLOOPY_STOP_HOOK=on, the Stop hook's no-progress cap (3 iterations without a new pass) still marks a stalled loop blocked.
• Batch independent reads and shell steps into one call, and land each file change as one coherent edit.
• After compaction, the recovery capsule lists failing proof with its artifact path. Re-read that artifact instead of re-running the command to see the error again.

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: forge to build, sentinel to review, probe to test, arbiter to gate, assayer to audit, and pathfinder 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.

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.

Before dispatching any worker, read Crew: it carries the parent agent responsibilities, the dispatch contract, the subagent lifecycle, and agent allocation.

Quality Gate

Every listed artifact must exist, be non-empty, and live under the active evidence root. Superloopy also accepts strict review gates and matrix gates when reviewer/architect, executor QA, rerun, artifact, and coverage fields validate. loop review and loop finish always write the default gate. A review gate is JSON you write by hand and pass to loop checkpoint --quality-gate; write one only when sentinel, probe, and arbiter each actually ran, and sign it as Crew describes under "Review gate actors".

For executor receipts, use the active evidence root. A global loop normally records under .superloopy/evidence/; a scoped loop records under .superloopy/sessions/<id>/evidence/. If a receipt is missing or invalid, the receipt block message names the active evidence root to repair.

Keep the human final gate report and the Superloopy quality gate artifact separate. A arbiter report is Markdown evidence (for example .superloopy/evidence/arbiter-final-gate-report.md). The superloopy loop review and superloopy loop finish --artifact flag writes the machine-validated quality gate artifact and must point to JSON, normally .superloopy/evidence/gate.json. Never pass the Markdown report path as the finish artifact.

Steering

Accept only structured prompt-level steering:

SUPERLOOPY_STEER: {"kind":"annotate","evidence":"fact","rationale":"why it matters"}
SUPERLOOPY_STEER: {"kind":"add_goal","title":"New slice","objective":"Concrete objective","rationale":"why it changed"}
SUPERLOOPY_STEER: {"kind":"revise_criterion","goalId":"G001","criterionId":"C002","scenario":"New scenario.","rationale":"why it changed"}
SUPERLOOPY_STEER: {"kind":"reorder_pending","goalIds":["G003","G002"],"rationale":"why this order"}

After any accepted steering, follow the returned guide; run superloopy loop status --json when you need a fresh reorientation.

Doctor

superloopy doctor --json checks the package, hooks, bundled skills, CLI, dependency-free boundary, runtime ignore policy, file inventory, gate notes, design audit, generic comparison scan status, dispatch coherence, model policy, and reviewability.

Use superloopy doctor --comparison-path /path/to/comparison --json only when you need copied-block evidence against an external folder. The generic comparison scan compares code-shaped files for substantial contiguous blocks without naming or coupling Superloopy to any source project.