@loop-lang/loop 0.2.0 → 0.3.0

package/assets/AGENTS.md

@@ -1,12 +1,12 @@
-# AGENTS.md — authoring Loop (`.loop`) flows
+# AGENTS.md — authoring LoopFlow (`.loop`) flows
 
 This file teaches an AI assistant (Claude Code, Copilot, Cursor, etc.) how to write
-**Loop** flows. When a user asks you to design a staged, self-correcting, or human-gated
+**LoopFlow** 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 run file.loop`.
 
-Loop is a small natural-language DSL. A `.loop` file describes the *movement* of an AI
+LoopFlow 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
 verifies itself, when it stops, and where a human steps in. The five knobs —
 **objective, context, actions, verification, stopping rules** — are first-class instead
@@ -19,6 +19,16 @@ bug fixes with a test, refactors gated by a check, an epic broken into stories,
 migration with a verification step. Don't write one for a one-off question or a trivial
 edit — just do those directly.
 
+Before building a loop, run the four-condition test — build one only when all four hold:
+
+1. **Does the task repeat?** A one-time task is just a normal prompt.
+2. **Is there a clear definition of "done"?** You must be able to verify completion — a
+   `done when` predicate (a test, a command, or a review skill). No check, no loop.
+3. **Can you afford the iterations?** A loop re-prompts itself until done; that costs tokens.
+   Keep the `done when` check fast and add an `after N tries` thrash guard.
+4. **Does the loop have the tools to verify itself?** It needs a way to implement *and* check
+   its own work — the predicate command or the review skill must actually be runnable.
+
 **Interview the user before writing it.** Walk the five decisions, asking the
 high-leverage questions and offering defaults for the rest: (1) the **goal**;
 (2) the **`done when`** check (test / command / scan finds-nothing / human);
@@ -48,6 +58,8 @@ look at: <files>, and the last failure   context the agent reads before acting (
 allow edits automatically, but ask me before <classes>   action policy
 each cycle: plan, then act, then observe   the repeated steps (any subset, in order)
 also: <pass>, <pass>      extra finishing passes run after the goal is met
+use skills: <a>, <b>      named skills the loop may invoke during plan/act
+remember in "<file.md>"   cross-run memory: read lessons on start, append an outcome on stop
 reflect                   turn a failure into context for the next plan (the back-edge)
 
 when it passes and the goal is met: stop
@@ -72,11 +84,49 @@ done when the test "billing.spec.ts::apostrophe" passes   # a named test
 done when "pnpm test" passes                               # a shell command, exit 0
 done when "semgrep --severity=high" finds nothing          # a shell command, empty output
 done when a human confirms "looks right at 375px"          # a human check
+done when the skill "email-review" approves                # a review skill: approved / not
+done when the skill "email-review" scores 8 or more        # a review skill: numeric threshold
 ```
 
 The command in a predicate runs in the user's shell with their privileges (like an npm
 script). It IS meant to be a real command. Prefer a fast, deterministic check.
 
+The **skill** predicate bridges an abstract goal to a verifiable one: when "done" isn't a
+test or a command (a good email, a sound design), have a review skill return an
+approved/rejected verdict or a numeric score. Build that review skill manually first and
+confirm it judges well, then wire it in as the loop's check.
+
+### `use skills` — coordinate proven skills
+
+Instead of one giant prompt, a loop can name skills it may call while planning and acting:
+
+```loop
+loop "decide whether to cancel the morning run":
+  goal: a clear go / no-go call the runner trusts
+  use skills: check-weather, analyze-workout
+  done when the skill "workout-review" approves
+```
+
+This is **skill-driven development**: build and battle-test each skill on its own first,
+then have the loop coordinate them. Don't invent a loop around skills that don't exist yet —
+prove the skill manually, then wire it in (as an execution skill via `use skills:`, or as a
+verifier via `done when the skill "…" approves`). See `examples/skills_memory.loop`.
+
+### `remember in` — cross-run memory
+
+A loop forgets everything between runs unless you give it a memory file. `remember in` makes
+the loop read the file's lessons into its first plan and append a dated outcome entry when it
+stops — so it improves run over run instead of repeating mistakes.
+
+```loop
+loop "...":
+  goal: ...
+  remember in "morning-run.memory.md"
+```
+
+`reflect` is *within-run* memory (a failure feeds the next plan); `remember` is its
+*across-run* counterpart. The file is plain markdown — readable and editable by a human.
+
 ### `flow` — chaining loops across files
 
 A `flow` sequences multiple `.loop` files. Each step runs the whole file (plan→act→observe

package/assets/skill/SKILL.md

@@ -40,6 +40,8 @@ look at: <files>, and the last failure   context to read before acting
 allow edits automatically, but ask me before <classes>   action policy
 each cycle: plan, then act, then observe   the repeated steps (any subset, in order)
 also: <pass>, <pass>      extra finishing passes after the goal is met
+use skills: <a>, <b>      named skills the loop may invoke during plan/act
+remember in "<file.md>"   cross-run memory: read lessons on start, append an outcome on stop
 when it fails: reflect on <focus>, then plan again
 when it passes and the goal is met: stop
 when blocked: ask a human
@@ -47,6 +49,14 @@ after <N> tries: stop and warn "<message>"   thrash guard
 a human approves the plan first              human plan gate
 a human reviews before stopping              human review gate
 a human approves before <action>             stage gate (in a stage)
+
+# config tier (top of file): how the loop is powered & scheduled
+use the <method> method      pull a preset (e.g. BMAD) as the base
+models: fast <m>, strong <m> model tiering — plan/reflect/also→fast, act→strong
+                             (cascades; override e.g. `act fast`, `all strong`)
+schedule: <when>             run unattended on a cadence
+runner: <agent>              which agent executes the loop
+target: <dir>                operate on another directory/repo
 ```
 
 Predicates:
@@ -55,6 +65,8 @@ done when the test "file.spec.ts::name" passes
 done when "pnpm test" passes              # shell command, exit 0
 done when "semgrep --severity=high" finds nothing   # empty output
 done when a human confirms "looks right"
+done when the skill "email-review" approves         # a review skill: approved / not
+done when the skill "email-review" scores 8 or more # a review skill: numeric threshold
 ```
 
 Rules: indentation is structural (two spaces); `loop`/`pipeline` at column 0; comments
@@ -122,10 +134,23 @@ Walk these quickly, naming the keyword each time so they learn it:
 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.
+   `main`"); ask if they want a PR, a worktree, or to work in place. (Full grammar below.)
+8. **Models (LLM policy)** → `models:` — which model does the work. Default: one model
+   throughout (the session's). Offer **tiering** for cost/speed: `models: fast <model>,
+   strong <model>` → plan/reflect/also run on *fast*, act runs on *strong*; cascades, and
+   you can override per phase (`act fast`, `all strong`).
+9. **Schedule / runner / target (config tier — only if automating)** → ask only when the
+   loop runs unattended or against another repo: `schedule: <when>` (run on a cadence),
+   `runner: <agent>` (which agent executes), `target: <dir>` (operate on another directory).
+   Skip silently for a normal in-session loop.
+
+Don't forget the menu in Step 2 also covers `use the <method> method` — pull a whole
+preset (e.g. BMAD) instead of hand-picking passes.
 
 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.
+6-try guard, work on a branch, one model throughout, no schedule — sound right?"*) so the
+whole interview is one exchange. Name every topic once even when you default it, so the
+user knows the knob exists and can override it.
 Then **write the `.loop`**, always with a real `done when` and a thrash guard, **print
 its flow** (below), and offer to run it.
 
@@ -162,10 +187,19 @@ the user explicitly asks for the headless runner.)
 1. **Read the file.** (Or, if the `loop` CLI is installed: `loop parse <file> --json` to
    get the structured spec.)
 2. **Execute the loop's semantics, narrating each step:**
+   - **memory** — if the loop has `remember in "<file>"`, read that file first (skip if it
+     doesn't exist yet) and let its lessons inform your first plan. When the loop stops,
+     append a dated entry: `## <date> — <outcome>` with the goal, attempts, and the run's
+     lesson (your last reflection). This is how the loop improves across runs.
    - **plan** — inspect the `look at:` files; decide the smallest change toward the goal.
+     If the loop declares `use skills:`, you may invoke those named skills (via the Skill
+     tool) to do the work — coordinate them rather than re-deriving everything inline.
    - **act** — make the edits. Honor the policy: for `ask me before <X>`, ask the user
      before doing X (migrations, pushes, etc.); auto classes you may do directly.
-   - **observe** — run the `done when` command (or named test) and read pass/fail.
+   - **observe** — run the `done when` check and read pass/fail. For a command or named test,
+     run it. For `the skill "<name>" approves` / `scores N or more`, invoke that review skill
+     on the work and read back its verdict (approved/rejected, or a score vs. the threshold) —
+     this is how an abstract goal gets a verifiable check.
    - on **fail** → **reflect** on why (use the failure output), then **plan again** (the
      back-edge). Repeat.
    - **stop** when `done when` passes, or after the thrash guard's N tries (state the
@@ -270,8 +304,41 @@ and honor the policy: if `push when done` is set and the current branch is `main
 
 ---
 
+## Global library — save a loop, reuse it in any project
+
+The user keeps a personal library of loops at **`~/.claude/loopflow/`** — one
+`<name>.loop` per saved loop. It lives beside the installed skill, so a loop saved once is
+runnable from **every** repo. The library is driven entirely from this chat; there is no
+terminal command for it. Create the directory on first save (`mkdir -p ~/.claude/loopflow`).
+
+Four operations — recognize them from `/loopflow <verb>` or from plain language:
+
+- **save** — *"save this as `<name>`"*, *"save it to my library"*, `/loopflow save …`
+  Write the loop's `.loop` source to `~/.claude/loopflow/<name>.loop`. Take `<name>` from
+  the user; if they don't give one, slugify the loop's name (`"fix the auth test"` →
+  `fix-the-auth-test`). **If that file already exists, show the saved version and confirm
+  before overwriting.** Report the path you wrote.
+
+- **list** — `/loopflow list`, *"what loops do I have saved"*
+  List every `*.loop` in `~/.claude/loopflow/`. For each, print `name — <goal>` (add the
+  one-line shape when it helps). An empty or missing dir → say it's empty and how to save one.
+
+- **run** — `/loopflow run <name>`, *"run my security loop here"*
+  Read `~/.claude/loopflow/<name>.loop` and run it **in the current repo**, exactly as in
+  *Running a .loop (in this session)* above. A bare `<name>` means the library; a path or a
+  name ending in `.loop` is a local file, so the library never shadows a loop in the repo.
+  If `<name>` isn't in the library, say so and offer `list`.
+
+- **remove** — `/loopflow remove <name>`, *"delete my `<name>` loop"*
+  Delete `~/.claude/loopflow/<name>.loop` after confirming. If it doesn't exist, say so.
+
+These are plain files — the user may also open or edit them directly. Saving is a copy, so
+removing a library entry never touches the original loop in a repo.
+
+---
+
 ## Reference
 
 The full language reference is in `AGENTS.md` and `docs/MANUAL.md` of the loop-lang repo;
-the CLI (`loop run|viz|export|parse`) and the VSCode extension are alternative ways to run
+the CLI (`loop-run run|viz|parse`) and the VSCode extension are alternative ways to run
 the same `.loop` files.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loop-lang/loop",
-  "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.",
+  "version": "0.3.0",
+  "description": "Install LoopFlow (.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" },
   "type": "module",
@@ -13,6 +13,7 @@
   "scripts": {
     "sync-assets": "node scripts/sync-assets.mjs",
     "prepack": "node scripts/sync-assets.mjs",
+    "postinstall": "node src/postinstall.mjs",
     "test": "node scripts/sync-assets.mjs && node --test test/*.test.mjs"
   }
 }

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
-// /loopflow skill) or headless via the full @loop/runtime CLI.
+// /loopflow skill) or headless via the full @loop-lang/runtime CLI.
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
 import { init } from "./init.mjs";
@@ -17,7 +17,7 @@ usage:
 
 init options:
   --dir <path>     install into <path> (default: current directory)
-  --global         install the /loopflow skill into ~/.claude/skills (not the repo)
+  --global         install the /loopflow skill into ~/.claude/skills (done automatically on \`npm install -g\`)
   --no-skill       don't install the Claude Code /loopflow skill
   --no-example     don't write examples/fix_test.loop
   --no-claude-md   don't write the CLAUDE.md pointer (written by default)
@@ -29,7 +29,7 @@ init options:
 after init:
   • 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>`;
+  • headless:    install @loop-lang/runtime for  loop-run run <file>`;
 
 function flag(argv, name) { return argv.includes(name); }
 function opt(argv, name) { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : undefined; }
@@ -70,8 +70,8 @@ async function main(argv) {
     return;
   }
 
-  if (["run", "parse", "export", "viz", "show", "ls"].includes(cmd)) {
-    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\`.`);
+  if (["run", "parse", "viz", "show", "ls"].includes(cmd)) {
+    console.error(`\`loop ${cmd}\` runs in your agent (the /loopflow skill) or via the full runtime CLI: \`loop-run ${cmd}\` (install @loop-lang/runtime).\nThis package installs Loop — try \`loop init\`. See \`loop help\`.`);
     process.exit(2);
   }
 

package/src/init.mjs

@@ -17,6 +17,7 @@ export function pointer({ skill }) {
     "## Loop (`.loop`)",
     "",
     "This repo uses **Loop** — a small natural-language DSL for self-correcting, human-gated coding workflows.",
+    "**First time you touch Loop in this repo, read [`AGENTS.md`](./AGENTS.md) end to end before authoring or running anything** — it's the full, current grammar that ships with the repo. Don't rely on prior memory of Loop; it may be stale. Read it once per session so your context is up to date.",
     "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");

package/src/postinstall.mjs

@@ -0,0 +1,33 @@
+// Runs after `npm install -g @loop-lang/loop`.
+// On a global install, copies the /loopflow skill to ~/.claude/skills/loopflow
+// so every Claude Code session in every project has access to /loopflow.
+// Skips silently on local installs and when the skill already exists.
+import { cp, mkdir, access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const isGlobal = process.env.npm_config_global === "true";
+if (!isGlobal) process.exit(0);
+
+const here = dirname(fileURLToPath(import.meta.url));
+const src = join(here, "..", "assets", "skill");
+const dst = join(homedir(), ".claude", "skills", "loopflow");
+
+const exists = (p) => access(p).then(() => true, () => false);
+
+try {
+  if (await exists(dst)) {
+    console.log(`  loop: /loopflow skill already at ~/.claude/skills/loopflow — skipped.`);
+    console.log(`  Run \`loop init --global --force\` to overwrite.`);
+  } else {
+    await mkdir(join(homedir(), ".claude", "skills"), { recursive: true });
+    await cp(src, dst, { recursive: true });
+    console.log(`  loop: installed /loopflow skill → ~/.claude/skills/loopflow`);
+    console.log(`  Open any Claude Code session and type /loopflow to start.`);
+  }
+} catch (err) {
+  // Non-fatal — don't break the install.
+  console.warn(`  loop: could not install /loopflow skill: ${err.message}`);
+  console.warn(`  Run \`loop init --global\` manually to install it.`);
+}