loop-forge

# loop-forge — stamp a guarded, reusable loop (`/loop-forge`) > Picture an engraving shop. A customer who can't engrave walks in and just > *describes* the seal they keep needing — "I want to do this over and over." > The artisan ① recognizes which of 5 standard molds (loop shapes) it is, ② asks > what letters to cut (the blanks), ③ cuts them into a proven mold, ④ automatically > fits a "misprint detector" (the verifier) and an "out-of-ink stop" (the hardstop), > ⑤ pulls one test impression to show the customer, and ⑥ once they approve, hands > back a reusable `/command` they can stamp again any time — the same in Claude Code > and in any other agent via a paste-able prompt. ## What this tool actually does Someone who doesn't code can't author a reusable `/command` that makes an AI repeat a task reliably. loop-forge closes that gap. It takes a vague one-liner and stamps it into a **reusable slash command**, while automatically attaching the two safety devices a non-developer doesn't even know to ask for: - **Verifier (maker ≠ checker)** — the loop's output is re-checked in a pass that is *separate* from the pass that produced it, so the loop can't grade its own homework. - **Hardstop** — a budget/count/cooldown ceiling, so a loop can't quietly break while burning tokens. That auto-injection is the decisive difference from a plain prompt generator or a developer-facing skill builder. **Before → after (the elevator demo):** ``` User: "I want to summarize 100 shop reviews into 3 lines each" │ loop-forge: 1. Diagnoses → Batch loop 2. Interviews → where are the items? per-item task? where does output land? a cap? 3. Auto-injects → verifier (count in == count out + independent spot re-check) + hardstop (max_items budget + per-item fail cap + abort at 20% failure) 4. Previews → "here's how it will run" (+ optional 1-item sample) 5. Stamps → /review-summary (reusable forever; safety baked in) ``` ## When it triggers - `/loop` or `/loop "<one-line situation>"` (full command `/loop-forge`; alias `/make-it-loop`) - "automate this" / "make this repeatable" / "turn this into a command" - "summarize all 100 reviews" / "do this for every item" - "do X every time an email arrives" / "alert me when a condition is met" - "generate a few options and pick the best one" - any time you'd rather capture a recurring task as a reusable `/command` than re-type the prompt by hand Triggers are matched on **intent, in any language** — the same phrasing in Korean, Spanish, Japanese, etc. activates the skill, and the whole interaction then runs in that language (see "Runs in your language" below). ## Runs in your language (English asset, multilingual behavior) Every file in this skill is English — there is no per-language copy. At runtime the orchestrator detects the user's language from their one-liner and conducts the *entire* interaction in it: the analogy, every interview question, the missing-slot re-asks, the default-value confirmations, and the dry-run preview. The stamped `/command`'s human-readable prose (description, procedure, verifier/hardstop explanations) is written in the user's language, while the structural tokens (frontmatter keys, the archetype id, registry field names, and the ASCII slug `name`) stay canonical so any teammate's harness can still parse it. This is LLM-driven — there is no translation table. ## The 5 loop shapes (everything this tool stamps) Non-developer work reduces to five shapes. There is **no sixth** — never invent one (YAGNI). If a request doesn't fit, diagnose the nearest shape or ask one branch question. | Shape | One line | Catalog | |---|---|---| | **Batch** | Same task across N items, none skipped | `references/archetypes/batch.md` | | **Pipeline** | Pass through ordered stages A→B→C | `references/archetypes/pipeline.md` | | **Refine** | Make → evaluate → fix, repeated | `references/archetypes/refine.md` | | **Watch** ⚠ most dangerous | Watch a target, act when a condition fires | `references/archetypes/watch.md` | | **Explore** | Diverge into N candidates → converge to best K | `references/archetypes/explore.md` | --- ## 6-stage orchestration (the main flow) Follow the flow exactly; each stage calls a specific asset (lazy-loaded). > **Helper-script paths (install-portable)**: the `tools/` and `references/` paths > below are relative to *this skill's own directory*. If a relative call can't find a > file, resolve it under the skill root — `$HOME/.claude/skills/loop-forge/…` for > `install.sh` installs, or `${CLAUDE_PLUGIN_ROOT}/skills/loop-forge/…` for marketplace > (`/plugin install`) installs. Every helper is **optional**: if it's still > unavailable (or `python3` is missing), perform the step yourself from the referenced > doc — `classify_signals.py` is only a hint and `check_safety.py` only re-checks what > Stage 4 already injected, so the flow degrades gracefully without them. ### Stage 1 — Entry - Receive the one-line situation via `$ARGUMENTS`. - If it's empty, ask first (in the user's language): **"What task do you keep doing by hand? Describe it in one line."** (e.g. "I want to summarize 100 shop reviews into 3 lines each.") ### Stage 2 — Diagnose the shape - First-pass hint: run `tools/classify_signals.py "<situation>"` to get `ranked` (per-shape signal scores) and `ambiguous` (a tie flag). **This is only a hint — the LLM makes the final call** using the semantic signal table in `references/classifier.md`. The scorer ships an English keyword set; for non-English input it returns no signal, and the LLM classifies from meaning (language-agnostic), so classification never depends on surface keywords. - If one candidate is clear, name it in plain language ("This is a **Batch** loop"). - If `ambiguous` (a top-2 tie) or a known conflict pair, fire the **branch question** from `classifier.md` — e.g. "All 100 at once? → Batch. Or each time a new one arrives? → Watch." ### Stage 3 — Interview for the blanks - Pull the confirmed shape's slot questions from `references/interviewer.md` (each shape has its own set) and ask them with AskUserQuestion, in plain language. - Apply the **missing-slot re-ask rule**: if the output location (`output_format`/`final_artifact`), the hardstop inputs (`max_items`/`max_iterations`/`period_limit`), or the eval criteria are left as "you decide," re-ask; if still blank, offer conservative defaults explicitly (Batch max 50 · Refine 4 iterations · Watch 20 actions/day, 5-min cooldown). - For a **Watch** loop whose triggered action is external (sending/posting), ask "Preview before sending, or approve each one yourself?" to set `external_action=true` and the gate. - Two common questions: **scope** ("Just this project, or usable anywhere?" → `project｜global`) and **name** (propose a slug, then confirm; a non-Latin answer is transliterated to an ASCII slug and confirmed). ### Stage 4 — Assemble (+ auto-inject safety + static check) - Use `references/assembler.md` to substitute the slot values into the shape's skeleton (the `{slot}` placeholders), producing a **neutral loop spec JSON** (`references/loop-spec-schema.md`, 9 fields: `name / archetype / label / situation / scope / slots / skeleton / external_action / registry`). - **Auto-inject safety**: copy the "default verifier" and "default hardstop" text from the chosen `archetypes/<shape>.md` into `registry.verifier` / `registry.hardstop`, and fill `registry.trigger / gate / accepted_signal` from the shape's mapping. For Watch (or any `external_action == true`), set the **language-independent** `registry.external_gate` to `dry_run` or `human_approval` (never `none`), matching the Stage-3 answer. - **Static gate**: run `tools/check_safety.py <spec.json>`. Exit 2 (missing verifier or hardstop, or a Watch/external loop without an `external_gate`) → **bounce back to Stage 3** to fill the gap. Only exit 0 proceeds. **This gate is non-bypassable.** > The loop-registry's 5 cells — **trigger / gate / verifier / hardstop / > accepted_signal** — are first-class under `registry`, so every stamped loop is born > registry-shaped. The added `external_gate` enum is what makes the Watch safety > check pass in any language (it gates on the enum, not on prose markers). ### Stage 5 — Dry-run preview (the approval gate) - Follow `assembler.md`'s **per-shape dry-run depth**: default = a text description ("here's how it will run": skeleton + slots + a summary of the injected safety); Batch/Explore may optionally run a 1-item sample (state the cost); **Watch = description only — running a real poll could fire a real send, so never sample it**; Pipeline/Refine = description plus, optionally, the first stage or one iteration. - Show the preview and get **explicit approval**. **No approval, no stamping.** ### Stage 6 — Stamp (equivalent outputs) - **Primary — Claude Code**: render with `references/renderers/claude-code.md`, then save by scope to `<cwd>/.claude/commands/<name>.md` (project) or `~/.claude/commands/<name>.md` (global). Invoke with `/<name>` + `$ARGUMENTS`. - **Optional — Portable Prompt**: render with `references/renderers/portable-prompt.md` into a harness-agnostic, paste-able prompt block (works in any agent — paste the body into the session). This is an opt-in bonus, not required. - **Equivalence contract**: the skeleton, verifier, hardstop, and accepted-signal text are **byte-identical** across both outputs; the only allowed difference is the invocation/variable syntax. - Finish by telling the user how to run it (Claude Code: `/<name> <input>`; Portable Prompt: paste the block into your agent). --- ## Never do this (CRITICAL) - ❌ **Never stamp without the Stage-5 approval.** Creating the command file is an irreversible artifact — a person sees the preview and says yes first. - ❌ **Never stamp a spec missing a verifier or hardstop.** If `check_safety.py` exits 2, bounce to the interview; never bypass it. Auto-injecting the two safety devices a non-developer doesn't know to ask for is this tool's whole reason to exist. - ❌ **Never stamp a Watch/external action without a dry-run or human-approval gate.** A monitor whose action is outbound (sending, posting, hitting a webhook) must carry "preview or human-approve first" — `registry.external_gate ∈ {dry_run, human_approval}`. It's the most dangerous shape, and the principle is "outbound action = independent gate" (the way email is drafted, then a human sends). - ❌ **Never invent a sixth shape.** Reduce everything to Batch / Pipeline / Refine / Watch / Explore (YAGNI). If it doesn't fit, diagnose the nearest shape or ask one branch question. - ❌ **Don't reimplement skill-creator / writing-skills.** Those are developer-facing authoring engines. loop-forge is the non-developer layer on top: a plain-language interview + shape diagnosis + safety injection. --- ## Dependent references (lazy load — call per stage) | Asset | Purpose | Stage | |---|---|---| | `references/loop-spec-schema.md` | The 9-field loop spec + the 5 registry cells (+ `external_gate`) | 4 | | `tools/loop_spec.schema.json` | Machine-validation schema (jsonschema) for the spec | 4 | | `references/classifier.md` | Semantic signal table + branch-question rules | 2 | | `tools/classify_signals.py` | Lightweight first-pass signal scorer (CLI hint) | 2 | | `tools/corpus.jsonl` | Classifier regression corpus (50+ cases) | (tests) | | `references/interviewer.md` | Per-shape slot questions + missing-slot re-asks + defaults | 3 | | `references/archetypes/batch.md` | Batch shape (the 6-section structure template) | 2·3·4 | | `references/archetypes/pipeline.md` | Pipeline shape | 2·3·4 | | `references/archetypes/refine.md` | Refine shape | 2·3·4 | | `references/archetypes/watch.md` | Watch shape (external-action gate) | 2·3·4 | | `references/archetypes/explore.md` | Explore shape | 2·3·4 | | `references/assembler.md` | Assembly, safety auto-injection, dry-run depth | 4·5 | | `tools/check_safety.py` | Static safety check (exit 2 on a missing guard) | 4 | | `references/renderers/claude-code.md` | Claude Code slash-command render rules | 6 | | `references/renderers/portable-prompt.md` | Portable paste-able prompt render rules | 6 | | `tools/examples/batch/{spec.json, claude-command.md, portable-prompt.md}` | Golden outputs (render ground truth) | 6 | ## Disabling Uninstall or disable the plugin through Claude Code's plugin manager (`/plugin`), or remove `skills/loop-forge` from `~/.claude/skills/` and `commands/loop-forge.md` from `~/.claude/commands/` for a manual install. ## Related - `docs/DESIGN.md` — the architecture and decision record for this plugin. - The **loop-registry frame** (trigger / gate / verifier / hardstop / accepted) — every stamped loop is born matching it, so it's diagnosable at a glance. - `skill-creator` / `writing-skills` — developer-facing authoring engines that loop-forge layers on top of (it is the non-developer layer, not a reinvention).