@loop-lang/loop 0.1.0 → 0.3.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

@@ -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 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
+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
@@ -59,7 +71,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`)
@@ -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
@@ -232,18 +282,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
@@ -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
@@ -62,36 +74,89 @@ 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. (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, 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.
+
+> **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
 
@@ -122,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
@@ -223,15 +297,48 @@ 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.
 
 ---
 
+## 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.1.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
-// /loop 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,19 +17,19 @@ 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 (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
-  --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>`;
+  • 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; }
@@ -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\`.`);
+  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

@@ -11,13 +11,14 @@ 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 + ".",
+    "**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");
 }
@@ -66,13 +67,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.

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.`);
+}