loop-forge

Files (27)

• SKILL.md
• batch.md · references/archetypes/
• explore.md · references/archetypes/
• pipeline.md · references/archetypes/
• refine.md · references/archetypes/
• watch.md · references/archetypes/
• assembler.md · references/
• classifier.md · references/
• codex-prompt-mechanism.md · references/
• interviewer.md · references/
• loop-spec-schema.md · references/
• claude-code.md · references/renderers/
• portable-prompt.md · references/renderers/
• check_safety.py · tools/
• classify_signals.py · tools/
• corpus.jsonl · tools/
• claude-command.md · tools/examples/batch/
• portable-prompt.md · tools/examples/batch/
• spec.json · tools/examples/batch/
• spec.json · tools/examples/explore/
• spec.json · tools/examples/pipeline/
• spec.json · tools/examples/refine/
• spec.json · tools/examples/watch/
• loop_spec.schema.json · tools/
• smoke_e2e.sh · tools/
• test_check_safety.py · tools/
• test_classify_signals.py · tools/

SKILL.md (first lines)

# 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

From sangrokjung/claude-forge, MIT.

More from sangrokjung/claude-forge