--- name: loop-forge description: | Turn a one-line description of a repetitive task into a reusable, self-guarding slash command. loop-forge diagnoses the task into one of 5 loop shapes (Batch / Pipeline / Refine / Watch / Explore), interviews for the blanks, and auto-injects two safety devices the user didn't know they needed — an independent verifier (maker ≠ checker) and a hardstop (a budget/count/cooldown ceiling) — then previews the result and stamps it as a `/command` they can run forever. Use when the user says "/loop", "/loop-forge", "/make-it-loop", "automate this", "make this repeatable", "turn this into a command", "do this for all 100 items", "do X every time Y happens", "generate several and pick the best", or otherwise wants to capture a recurring task as a reusable slash command instead of re-typing the prompt by hand. Works in any language: it interviews the user and writes the stamped command in the user's own language. Non-goal — it does not schedule unattended runs (launchd/cron) or publish externally on its own; it stamps the reusable command and stops there. ---

# 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

--- name: loop-forge description: | Turn a one-line description of a repetitive task into a reusable, self-guarding slash command. loop-forge diagnoses the task into one of 5 loop shapes (Batch / Pipeline / Refine / Watch / Explore), interviews for the blanks, and auto-injects two safety devices the user didn't know they needed — an independent verifier (maker ≠ checker) and a hardstop (a budget/count/cooldown ceiling) — then previews the result and stamps it as a `/command` they can run forever. Use when the user says "/loop", "/loop-forge", "/make-it-loop", "automate this", "make this repeatable", "turn this into a command", "do this for all 100 items", "do X every time Y happens", "generate several and pick the best", or otherwise wants to capture a recurring task as a reusable slash command instead of re-typing the prompt by hand. Works in any language: it interviews the user and writes the stamped command in the user's own language. Non-goal — it does not schedule unattended runs (launchd/cron) or publish externally on its own; it stamps the reusable command and stops there. ---

# 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

--- name: loop-forge description: | Turn a one-line description of a repetitive task into a reusable, self-guarding slash command. loop-forge diagnoses the task into one of 5 loop shapes (Batch / Pipeline / Refine / Watch / Explore), interviews for the blanks, and auto-injects two safety devices the user didn't know they needed — an independent verifier (maker ≠ checker) and a hardstop (a budget/count/cooldown ceiling) — then previews the result and stamps it as a `/command` they can run forever. Use when the user says "/loop", "/loop-forge", "/make-it-loop", "automate this", "make this repeatable", "turn this into a command", "do this for all 100 items", "do X every time Y happens", "generate several and pick the best", or otherwise wants to capture a recurring task as a reusable slash command instead of re-typing the prompt by hand. Works in any language: it interviews the user and writes the stamped command in the user's own language. Non-goal — it does not schedule unattended runs (launchd/cron) or publish externally on its own; it stamps the reusable command and stops there. ---

# 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

--- name: loop-forge description: | Turn a one-line description of a repetitive task into a reusable, self-guarding slash command. loop-forge diagnoses the task into one of 5 loop shapes (Batch / Pipeline / Refine / Watch / Explore), interviews for the blanks, and auto-injects two safety devices the user didn't know they needed — an independent verifier (maker ≠ checker) and a hardstop (a budget/count/cooldown ceiling) — then previews the result and stamps it as a `/command` they can run forever. Use when the user says "/loop", "/loop-forge", "/make-it-loop", "automate this", "make this repeatable", "turn this into a command", "do this for all 100 items", "do X every time Y happens", "generate several and pick the best", or otherwise wants to capture a recurring task as a reusable slash command instead of re-typing the prompt by hand. Works in any language: it interviews the user and writes the stamped command in the user's own language. Non-goal — it does not schedule unattended runs (launchd/cron) or publish externally on its own; it stamps the reusable command and stops there. ---

# 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