@loop-lang/loop 0.1.0 → 0.2.0

package/README.md

@@ -1,34 +1,90 @@
 # @loop-lang/loop
 
-Install **Loop** — a small natural-language DSL for self-correcting, human-gated coding loops — into any repo, so **Claude Code or any agent** can author and run `.loop` files.
+**Loop** is a small natural-language DSL for *loop engineering* — a `.loop` file describes a
+self-correcting, human-gated coding workflow: its goal, what it may read, how it verifies
+itself, when it stops, and where a human steps in. Your agent then **runs that loop**,
+cycling plan → act → observe and reflecting on failures until the goal is met.
+
+This package drops Loop into any repo so **Claude Code — or any agent** — can author and run
+`.loop` files.
 
 ```sh
 npx @loop-lang/loop init
 ```
 
-That scaffolds, into the current repo:
+## What a `.loop` looks like
+
+```loop
+loop "fix the failing checkout tax test":
+  goal: the tax line on the cart is correct
+  look at: src/cart, and the last failure
+  done when "pnpm test checkout" passes
+  also: a security scan
+  after 6 tries: stop and warn "still red — needs a human"
+```
+
+Plain words, but precise: `done when` is how the loop checks itself, `also:` adds a quality
+pass once the goal is met, and the guard stops a thrashing loop instead of looping forever.
+Bigger jobs scale up to a **`pipeline`** (an epic → ordered stages) or a **`flow`** (a chain
+of whole `.loop` files — discover → design → build each story).
+
+## What `init` scaffolds
 
-- **`AGENTS.md`** — the full Loop language reference. Any agent that opens the repo (Claude Code, Cursor, Copilot, Codex…) now knows how to write a `.loop`.
-- **`.claude/skills/loop`** — the Claude Code `/loop` skill (author + run loops natively in a chat).
+- **`AGENTS.md`** — the full language reference. Any agent that opens the repo (Claude Code,
+  Cursor, Copilot, Codex…) now knows how to write a `.loop`.
+- **`.claude/skills/loopflow`** — the Claude Code **`/loopflow`** skill (author + run loops
+  natively in a chat). *Invoked as `/loopflow`, not `/loop` — the latter is Claude Code's
+  built-in scheduler.*
+- **`CLAUDE.md`** pointer — a standing nudge so Claude Code reaches for a `.loop` instead of
+  doing the work ad hoc. (Written by default; `--no-claude-md` to skip.)
 - **`examples/fix_test.loop`** — a starter loop to run.
 
-### Options
+## The `/loopflow` skill — a guided tour
+
+You don't need to know the language first. In a Claude Code chat, just describe the work:
+
+```
+/loopflow build a rate limiter — done when the burst test passes, and run a security pass
+```
+
+The skill **interviews you** — it scopes the purpose first (a one-test fix? a feature? a
+whole app?), offers the quality passes worth adding (tests, security, code review, clean
+architecture), then writes the `.loop` *in front of you*, naming each keyword as it goes.
+By the end of one loop you've learned the language by building. Then it runs the loop right
+in the chat, so you watch every step and answer any gate inline.
+
+Already have a `.loop`? Run it directly:
+
+```
+/loopflow run examples/fix_test.loop
+```
+
+## Options
 
 ```
 loop init [--dir <path>] [--global] [--no-skill] [--no-example]
-          [--claude-md] [--cursor] [--copilot] [--all-agents] [--force]
+          [--no-claude-md] [--cursor] [--copilot] [--all-agents] [--force]
 ```
 
 - `--global` — install the skill into `~/.claude/skills` instead of the repo.
-- `--all-agents` — also drop memory pointers for Cursor + Copilot (and `CLAUDE.md`).
+- `--no-claude-md` — skip the `CLAUDE.md` pointer (written by default).
+- `--cursor` / `--copilot` / `--all-agents` — also drop memory pointers for those agents.
+- `--no-skill` / `--no-example` — skip the skill or the starter loop.
 - `--force` — overwrite an existing skill / example.
 
-Re-running `init` is safe: the `AGENTS.md` block is managed between markers and updated in place, not duplicated.
+Re-running `init` is safe: the `AGENTS.md` block is managed between markers and updated in
+place, never duplicated.
+
+## After install
+
+- **Claude Code:** open a chat in the repo → `/loopflow run examples/fix_test.loop`, or just
+  describe the work and let the skill write the `.loop`.
+- **Any agent:** it reads `AGENTS.md` and authors + runs loops the same way.
+- **Headless:** install the full runtime to run loops from the CLI with `loop run <file>`.
 
-### After install
+## Learn more
 
-- **Claude Code:** open a chat in the repo → `/loop run examples/fix_test.loop`, or just describe the work and the agent writes the `.loop`.
-- **Any agent:** it reads `AGENTS.md` and can author + run loops the same way.
-- **Headless:** install the full runtime for `loop run <file>`.
+The [loop-lang repo](https://github.com/tickets-forge-dev/loop-lang) — tutorial, full keyword
+reference, and the playable Loop Lab.
 
-Learn the language: the [tutorial](https://github.com/tickets-forge-dev/loop-lang), the keyword reference, and the playable Loop Lab.
+Apache-2.0.

package/assets/AGENTS.md

@@ -4,7 +4,7 @@ This file teaches an AI assistant (Claude Code, Copilot, Cursor, etc.) how to wr
 **Loop** flows. When a user asks you to design a staged, self-correcting, or human-gated
 coding workflow — "set up a loop to fix X", "turn this epic into a pipeline", "automate
 this multi-step task" — author a `.loop` file using the grammar below, then let the user
-run it with `loop run file.loop`.
+run it with `loop-run run file.loop`.
 
 Loop is a small natural-language DSL. A `.loop` file describes the *movement* of an AI
 coding loop: its objective, the context it may read, the actions it's allowed, how it
@@ -59,7 +59,7 @@ a human approves the plan first        (human authors/approves the plan before a
 a human reviews before stopping        (human judges the result before the loop stops)
 a human approves before <action>       (a blocking gate before a stage, e.g. deploy)
 
-plan from the archon project "<name>"  (source the plan from Archon instead of generating)
+plan from "<file>"        (read the plan from a file you control instead of generating it)
 
 use the <method> method   schedule: <when>   runner: <agent>   target: <dir>   (config tier)
 models: fast <model>, strong <model>   model tiering: plan/reflect/also→fast, act→strong (cascades; override e.g. `act fast`, `all strong`)
@@ -232,18 +232,17 @@ loop "add a healthcheck endpoint":
 ## Show the flow — every time it changes
 
 Whenever you create or edit a `.loop`, print its flow so the user sees the shape.
-Run `loop show file.loop`, or render the compact ASCII yourself: the cycle
+Run `loop-run show file.loop`, or render the compact ASCII yourself: the cycle
 (`plan → act → observe`), the `↺` reflect back-edge, the `✓ done when` check, the
 `⛔` thrash guard, and any `👤` gates. For a pipeline, list stages in order; for a
-flow, show the file chain. `loop ls` lists every loop in the repo.
+flow, show the file chain. `loop-run ls` lists every loop in the repo.
 
 ## Running what you wrote
 
-- `loop run file.loop` — execute it on Claude Code (plan/act/observe, reflect on failure,
+- `loop-run run file.loop` — execute it on Claude Code (plan/act/observe, reflect on failure,
   verify with `done when`, pause at human gates).
-- `loop show file.loop` — print the loop's flow as compact ASCII (and `loop ls` to list them).
-- `loop viz file.loop` — open a visual HTML schematic of the flow.
-- `loop export file.loop` — emit an Archon workflow YAML (optional interop).
+- `loop-run show file.loop` — print the loop's flow as compact ASCII (and `loop-run ls` to list them).
+- `loop-run viz file.loop` — open a visual HTML schematic of the flow.
 
 ## Authoring checklist
 

package/assets/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: loop
-description: Create and run Loop (.loop) flows — a natural-language DSL for loop engineering. Use when the user wants to author, write, run, or execute a self-correcting or human-gated AI coding loop, turn an epic into a pipeline, fix a bug "as a loop", or mentions a .loop file or "loop engineering".
+name: loopflow
+description: Create and run Loop (.loop) flows — a natural-language DSL for loop engineering. Use when the user wants to author, write, run, or execute a self-correcting or human-gated AI coding loop, turn an epic into a pipeline, fix a bug "as a loop", build a feature or whole app "as a loop", learn what Loop is or how to use it, or mentions a .loop file or "loop engineering". Invoked as /loopflow (the name avoids colliding with the built-in /loop scheduler).
 ---
 
 # Loop
@@ -62,36 +62,76 @@ start with `#`. An epic → a `pipeline`; each story → a `stage`.
 
 ---
 
-## Creating a .loop — interview the user first
-
-Don't silently guess the loop. **Walk the five decisions with the user**, asking
-the high-leverage questions out loud and offering a default for the rest, so a
-confident user can accept everything in one reply. Ask one topic at a time:
-
-1. **Goal (objective)** — "What's the goal — what does *done* look like?"
-   Required; never guess this one.
-2. **Verification — `done when`** — "How do we know it's done: a test passing, a
-   shell command passing, a scan that must *find nothing*, or a human confirming?"
-   The most important answer — always ask.
-3. **Context — `look at`** — "What should it read first?" Offer to infer the files
-   from the repo; append `and the last failure`.
-4. **Actions — policy** — "Anything risky to gate — migrations, pushes, deploys?"
-   Default offered: edits automatically, nothing else gated.
-5. **Stopping — transitions + guard** — confirm the default (reflect on failure,
-   `after N tries: stop and warn`); ask for N only if they care.
-
-Then two more that shape the run:
-
-6. **Human gates** — "Approve the plan before any work? Review before it stops?"
-   Default: none unless the work is risky.
-7. **Git strategy** — state the safe default ("work on a branch, commit when the
-   goal is met, never push to `main`") and ask if they want a PR, a worktree, or
-   to work in place.
-
-Offer the defaults inline (e.g. *"I'll gate nothing, add a 6-try guard, and work
-on a branch — ok?"*) so the whole interview can be one exchange. Then **write the
-`.loop`**, scoping it with `look at:` and always giving it a real `done when` and a
-thrash guard. Finally **print its flow** (below) and offer to run it.
+## Creating a .loop — be a guide, not a guesser
+
+Most people reaching for this skill don't yet know what Loop can do. Your job is to
+**guide them to the right loop for their purpose** — and teach the language by writing
+it in front of them. Never silently guess the loop; interview first, then author. Ask
+one topic at a time, and always offer a default so a confident user can accept it all
+in one reply.
+
+### Step 0 — scope the purpose first (ask this before anything else)
+
+Open with **"What do you want the loop to accomplish?"** and show the range, so the
+user sees what's possible and picks a scale:
+
+| Scale | Example purpose | Shape in Loop |
+|-------|-----------------|---------------|
+| **Tiny** | "Make this one failing test pass." | a single `loop` |
+| **Small** | "Fix this bug across a few files; gate the migration." | a `loop` + policy + gate |
+| **Medium** | "Build the checkout feature — a few stories, each tested." | a `pipeline` of `stage`s |
+| **Large** | "Build a whole app, A-to-Z." | a `flow`: discover → design → build each story |
+
+Name the shape their answer implies (*"that's a **pipeline** — a sequence of stages"*)
+so the vocabulary attaches to their own goal. This one question turns a vague request
+into a scoped loop and teaches the three top-level forms at once.
+
+### Step 1 — do they already have a plan?
+
+Ask **"Do you have a spec, plan, ticket, or epic already?"**
+- **Yes** → point `look at:` at it; if it's an epic / story list, turn each story into a
+  `stage` of a `pipeline` (or `for each` over the plan file).
+- **No, and it's medium/large** → begin the flow with a **discovery loop** whose
+  `done when` is "the plan file exists and validates" — it interviews them, writes the plan.
+- **No, and it's small** → skip planning; go straight to the loop.
+
+### Step 2 — which quality passes? (offer the menu — don't wait to be asked)
+
+This is what makes Loop worth running. Proactively offer the quality sub-loops:
+
+> "Want the loop to enforce quality every cycle too? Common ones: **tests** (write/keep
+> green), **security** (a scan that must find nothing), **code review**, **clean
+> architecture** (boundary checks). I can add these as `also:` finishing passes on one
+> loop, or as their own gated `stage`s in a pipeline."
+
+Translate their picks into syntax in front of them so they see the mapping:
+- tests → `done when "<test cmd>" passes`
+- security → `also: a security scan`, or `done when "semgrep --severity=high" finds nothing`
+- review / architecture → `also: <pass>`, or a `stage` with `a human approves before <X>`
+
+### Step 3 — the remaining decisions (defaults offered, one reply to accept)
+
+Walk these quickly, naming the keyword each time so they learn it:
+1. **Goal** → `goal:` — "what does *done* look like?" Required; never guess this one.
+2. **Verification** → `done when` — a test passing, a command passing, a scan finding
+   nothing, or a human confirming. The most important line; always pin it down.
+3. **Context** → `look at:` — offer to infer the files from the repo; append `and the last failure`.
+4. **Actions** → policy — "anything risky to gate: migrations, pushes, deploys?" Default:
+   `allow edits automatically`, nothing else gated.
+5. **Stopping** → `after N tries: stop and warn` (default 6) + `when it fails: reflect … then plan again`.
+6. **Human gates** → `a human approves the plan first` / `a human reviews before stopping`
+   — default none unless the work is risky.
+7. **Git** → state the safe default ("branch, commit when the goal is met, never push to
+   `main`"); ask if they want a PR, a worktree, or to work in place.
+
+Offer the defaults inline (*"I'll add a tests + security pass, gate the migration, a
+6-try guard, work on a branch — sound right?"*) so the whole interview is one exchange.
+Then **write the `.loop`**, always with a real `done when` and a thrash guard, **print
+its flow** (below), and offer to run it.
+
+> **Teach by building.** As you write each clause, say what it is (*"`done when` is how
+> the loop checks itself"*). By the end of one loop the user has seen the whole language —
+> that is the point of authoring it here, in the open, rather than headless.
 
 ## Show the flow — every time it changes
 
@@ -223,7 +263,7 @@ Two protections are unconditional and cannot be overridden by any `git:` block:
 
 ### In-chat runner note
 
-When you run a loop *inside this conversation* (the `/loop` skill), you are the git
+When you run a loop *inside this conversation* (the `/loopflow` skill), you are the git
 operator — you execute plan/act/observe yourself. Before acting, check the `git:` block
 and honor the policy: if `push when done` is set and the current branch is `main` or
 `master`, refuse with a clear message rather than pushing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loop-lang/loop",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Install Loop (.loop) into any repo so Claude Code — or any agent — can author and run self-correcting, human-gated coding loops.",
   "license": "Apache-2.0",
   "publishConfig": { "access": "public" },

package/src/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // @loop-lang/loop — the installer CLI. `loop init` drops Loop into a repo so any
 // agent can author + run .loop files. Running loops happens in your agent (the
-// /loop skill) or headless via the full @loop/runtime CLI.
+// /loopflow skill) or headless via the full @loop/runtime CLI.
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
 import { init } from "./init.mjs";
@@ -17,17 +17,17 @@ usage:
 
 init options:
   --dir <path>     install into <path> (default: current directory)
-  --global         install the /loop skill into ~/.claude/skills (not the repo)
-  --no-skill       don't install the Claude Code /loop skill
+  --global         install the /loopflow skill into ~/.claude/skills (not the repo)
+  --no-skill       don't install the Claude Code /loopflow skill
   --no-example     don't write examples/fix_test.loop
-  --claude-md      also write a CLAUDE.md pointer
+  --no-claude-md   don't write the CLAUDE.md pointer (written by default)
   --cursor         also write .cursor/rules/loop.md
   --copilot        also write .github/copilot-instructions.md
   --all-agents     CLAUDE.md + Cursor + Copilot pointers
   --force          overwrite the skill / example if they already exist
 
 after init:
-  • Claude Code: open a chat in the repo and say  /loop run examples/fix_test.loop
+  • Claude Code: open a chat in the repo and say  /loopflow run examples/fix_test.loop
   • any agent:   it reads AGENTS.md and can author + run .loop files
   • headless:    install @loop/runtime for  loop run <file>`;
 
@@ -45,7 +45,9 @@ async function main(argv) {
   if (cmd === "init") {
     const agents = [];
     if (flag(argv, "--all-agents")) agents.push("claude", "cursor", "copilot");
-    if (flag(argv, "--claude-md") && !agents.includes("claude")) agents.push("claude");
+    // CLAUDE.md pointer is on by default (gives Claude Code a standing "author a .loop"
+    // nudge); --no-claude-md opts out. --claude-md still accepted as an explicit yes.
+    if (!flag(argv, "--no-claude-md") && !agents.includes("claude")) agents.push("claude");
     if (flag(argv, "--cursor") && !agents.includes("cursor")) agents.push("cursor");
     if (flag(argv, "--copilot") && !agents.includes("copilot")) agents.push("copilot");
 
@@ -62,14 +64,14 @@ async function main(argv) {
     console.log(`\n  Loop installed into ${targetDir}\n`);
     for (const s of steps) console.log(`  ✓ ${s}`);
     console.log(`\n  Next:`);
-    console.log(`    • In a Claude Code chat here:  /loop run examples/fix_test.loop`);
+    console.log(`    • In a Claude Code chat here:  /loopflow run examples/fix_test.loop`);
     console.log(`    • Or describe the work and the agent writes the .loop for you.`);
     console.log(`    • Any other agent reads AGENTS.md and can do the same.\n`);
     return;
   }
 
   if (["run", "parse", "export", "viz", "show", "ls"].includes(cmd)) {
-    console.error(`\`loop ${cmd}\` runs in your agent (the /loop skill) or via the full runtime CLI (@loop/runtime).\nThis package installs Loop — try \`loop init\`. See \`loop help\`.`);
+    console.error(`\`loop ${cmd}\` runs in your agent (the /loopflow skill) or via the full runtime CLI (@loop/runtime).\nThis package installs Loop — try \`loop init\`. See \`loop help\`.`);
     process.exit(2);
   }
 

package/src/init.mjs

@@ -11,13 +11,13 @@ const MARK_END = "<!-- loop:end -->";
 /** Short pointer dropped into an agent's memory file so it knows Loop lives here. */
 export function pointer({ skill }) {
   const run = skill
-    ? "run it — in Claude Code via the `/loop` skill (installed at `.claude/skills/loop`), or headless with `loop run <file>`"
+    ? "run it — in Claude Code via the `/loopflow` skill (installed at `.claude/skills/loopflow`; note: it's `/loopflow`, not the built-in `/loop` scheduler), or headless with `loop run <file>`"
     : "run it headless with `loop run <file>`";
   return [
     "## Loop (`.loop`)",
     "",
     "This repo uses **Loop** — a small natural-language DSL for self-correcting, human-gated coding workflows.",
-    "When the user asks to set up a loop, turn an epic into a pipeline, or automate a multi-step task, **author a `.loop` file** using the grammar in [`AGENTS.md`](./AGENTS.md), then " + run + ".",
+    "Whenever the user wants to build, fix, automate, or ship something as a repeatable/self-correcting workflow — a bug fix, a feature, an epic, even a whole app — **default to authoring a `.loop` file** rather than doing the work ad hoc. Use the grammar in [`AGENTS.md`](./AGENTS.md), interview the user for the goal/verification/gates first, then " + run + ".",
     "Every time you create or change a `.loop`, print its flow so the user can see the shape.",
   ].join("\n");
 }
@@ -66,13 +66,13 @@ export async function init(targetDir, opts, assetsDir) {
   const verb = await mergeMarkered(join(targetDir, "AGENTS.md"), agentsBody.trim());
   steps.push(`${verb} AGENTS.md  (the Loop language reference — any agent)`);
 
-  // 2. The Claude Code /loop skill.
+  // 2. The Claude Code /loopflow skill.
   if (withSkill) {
     const dst = skill === "global"
-      ? join(homedir(), ".claude", "skills", "loop")
-      : join(targetDir, ".claude", "skills", "loop");
+      ? join(homedir(), ".claude", "skills", "loopflow")
+      : join(targetDir, ".claude", "skills", "loopflow");
     const r = await copyInto(join(assetsDir, "skill"), dst, { force });
-    steps.push(`${r === "skipped" ? "skipped (exists)" : "wrote"} ${skill === "global" ? "~/.claude/skills/loop" : ".claude/skills/loop"}  (the /loop skill)`);
+    steps.push(`${r === "skipped" ? "skipped (exists)" : "wrote"} ${skill === "global" ? "~/.claude/skills/loopflow" : ".claude/skills/loopflow"}  (the /loopflow skill)`);
   }
 
   // 3. Opt-in per-agent memory pointers.