@loop-lang/loop 0.1.0

package/README.md

@@ -0,0 +1,34 @@
+# @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.
+
+```sh
+npx @loop-lang/loop init
+```
+
+That scaffolds, into the current repo:
+
+- **`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).
+- **`examples/fix_test.loop`** — a starter loop to run.
+
+### Options
+
+```
+loop init [--dir <path>] [--global] [--no-skill] [--no-example]
+          [--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`).
+- `--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.
+
+### After install
+
+- **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>`.
+
+Learn the language: the [tutorial](https://github.com/tickets-forge-dev/loop-lang), the keyword reference, and the playable Loop Lab.

package/assets/AGENTS.md

@@ -0,0 +1,255 @@
+# AGENTS.md — authoring Loop (`.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
+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`.
+
+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
+verifies itself, when it stops, and where a human steps in. The five knobs —
+**objective, context, actions, verification, stopping rules** — are first-class instead
+of buried in a prompt.
+
+## When to write a `.loop`
+
+Write one when the work is a *repeatable, verifiable* loop or a sequence of them:
+bug fixes with a test, refactors gated by a check, an epic broken into stories, a
+migration with a verification step. Don't write one for a one-off question or a trivial
+edit — just do those directly.
+
+**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);
+(3) **`look at`** context; (4) the **action policy** (what's risky enough to gate);
+(5) **stopping** (reflect on failure + an `after N tries` guard). Then the
+**human gates** and the **git strategy** (default: branch + commit when done,
+never push to `main`; ask if they want a PR or a worktree). Offer the defaults
+inline so a confident user can accept everything at once.
+
+## Vocabulary (the whole language)
+
+```
+loop "<name>":            a self-correcting loop
+pipeline "<name>":        a sequence of stages (an epic)
+stage "<name>":           one stage of a pipeline (its body is a loop; a story)
+flow "<name>":            a chain of loop files (each step runs a whole .loop file)
+  run "<file>":           first step — runs the file; its text result is passed forward
+  then run "<file>":      subsequent step — receives the previous result as context
+    a human approves first  (optional per-step human gate before the step runs)
+  with the result of <name>  (reference a named step's output instead of auto-carry)
+  for each <var> in "<file>":  iterate items from a .yaml or .md file; run the template once per item
+    run "<template>":     template receives the item text as context; fail → ask continue/stop
+
+goal: <text>              what "done" means, in plain language
+done when <predicate>     how the loop verifies itself (see Predicates)
+look at: <files>, and the last failure   context the agent reads before acting (items are file paths or plain-language descriptions the agent resolves to files)
+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
+reflect                   turn a failure into context for the next plan (the back-edge)
+
+when it passes and the goal is met: stop
+when it fails: reflect on <focus>, then plan again
+when blocked: ask a human
+after <N> tries: stop and warn "<message>"
+
+a human approves the plan first        (human authors/approves the plan before acting)
+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)
+
+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`)
+```
+
+### Predicates (`done when …`)
+
+```
+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
+```
+
+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.
+
+### `flow` — chaining loops across files
+
+A `flow` sequences multiple `.loop` files. Each step runs the whole file (plan→act→observe
+cycle) and passes its text result forward as context for the next step. The chain is
+fail-fast: a step that ends unsatisfied stops the rest.
+
+```loop
+flow "ship":
+  run "build.loop"
+  then run "test.loop"
+  then run "deploy.loop":
+    a human approves first
+```
+
+- `run "<file>"` — first step; the file path is relative to the flow file.
+- `then run "<file>"` — subsequent steps; automatically receive the previous step's text summary.
+- `a human approves first` — optional per-step gate; blocks until approved.
+- `with the result of <name>` — reference a named step's output explicitly instead of auto-carry.
+
+### `for each` — iterate a plan, run a template per item
+
+Inside a `flow`, `for each` reads a list from a YAML or Markdown file and runs a template
+once per entry. The entry's text becomes the template's context (what to build).
+
+```loop
+flow "deliver":
+  for each item in "plan.yaml":
+    run "item-template.loop"
+```
+
+- `for each <var> in "<file>":` — source must be a `.yaml` file (a list or a single-key
+  list like `items:`) or a `.md` file (splits on `## ` sections).
+- `run "<template>"` — the template runs once per item; the item text arrives as context.
+- A failed item pauses the flow and asks whether to continue with the next item or stop.
+- Method-neutral: works with any checklist, not only BMAD. See `examples/foreach/` for a
+  generic bundle and `examples/bmad/atoz/` for BMAD as one example method.
+
+## Rules
+
+- **Indentation matters.** `loop` / `pipeline` / `flow` at column 0; their body indented
+  two spaces; a `stage`'s body indented under the stage.
+- A `loop` needs a `goal`. A `pipeline` needs at least one `stage`.
+- **An epic → a `pipeline`; each story → a `stage`.** Stages run in order; a failing
+  stage halts the rest.
+- **Scope each loop with `look at:`** so the agent follows the existing architecture and
+  makes the smallest change, instead of writing greenfield code. Items can be exact file
+  paths or plain-language descriptions (e.g. `the billing form`) — the agent resolves
+  descriptions to the actual files before planning.
+- **Put human gates on risky work** — payments, migrations, deploys, anything
+  irreversible. Use `ask me before …` for action policy, `a human approves before …`
+  for a hard stage gate.
+- Output only valid `.loop` syntax. Comments start with `#`.
+
+## Example — a single loop
+
+```loop
+loop "fix billing apostrophe bug":
+  goal: settings save when the company name has an apostrophe
+  done when the test "billing.spec.ts::apostrophe" passes
+
+  look at: billing/form.tsx, api/settings.ts, schema/settings.ts, and the last failure
+  allow edits automatically, but ask me before migrations or pushes
+
+  each cycle: plan, then act, then observe
+  when it passes and the goal is met:  stop
+  when it fails:                        reflect on which layer broke, then plan again
+  when blocked:                         ask a human
+  also:                                 polish the code, run a security check
+  after 6 tries:                        stop and warn "thrashing"
+```
+
+## Example — an epic with stories
+
+```loop
+pipeline "epic: checkout v2":
+
+  stage "story: cart totals":
+    goal: cart shows correct totals with tax
+    look at: src/cart/, src/tax/
+    done when "pnpm test cart" passes
+    each cycle: plan, then act, then observe
+    when it fails: reflect, then plan again
+
+  stage "story: checkout submit":
+    goal: order submits and payment is captured
+    a human approves before charging the card
+    done when "pnpm test checkout" passes
+    each cycle: act, then observe
+```
+
+## Git strategy
+
+A `git:` block sets the version-control strategy for the whole file (config tier, before
+any definition) or for a single loop (inside the loop body).
+
+**Built-in default (no `git:` block):** work on a branch, commit when the goal is met,
+no push. This applies whenever no git block is present at any level.
+
+### Line forms
+
+```
+work in place                    # edit the current branch as-is
+work on a branch                 # create / switch to a feature branch (default)
+work on a branch "my-feature"    # explicit branch name
+work in a worktree               # isolated git worktree
+work in a worktree "my-worktree" # named worktree
+
+commit when the goal is met      # one commit on success (default)
+commit each cycle                # commit after every cycle
+commit each story                # commit after each stage
+commit never / do not commit     # no automatic commits
+
+push when done                   # push the branch on completion
+do not push                      # no push (default)
+
+open a pull request              # open a PR after pushing
+```
+
+### Cascade (lowest wins)
+
+1. Built-in default — branch + commit-when-done, no push.
+2. File-level `git:` block — applies to all loops in the file.
+3. Per-loop `git:` block — refines commit cadence for that loop only.
+
+A `use the <method>` preset may carry a `git:` block at file level; the file's own block
+overrides it.
+
+### Always-on safety
+
+- **Never push to `main` or `master`.** This is unconditional — no `git:` block can
+  override it. A `push when done` directive with the current branch being protected is an
+  error that surfaces before the loop runs.
+- **`work in place` + `push when done` on a protected branch** is also an up-front error.
+
+### Example
+
+```loop
+git:
+  work on a branch
+  commit when the goal is met
+  push when done
+  open a pull request
+
+loop "add a healthcheck endpoint":
+  goal: GET /healthz returns 200 with a JSON status
+  done when "pnpm test health" passes
+  look at: the http server and the routes module, and the last failure
+  each cycle: plan, then act, then observe
+  when it fails: reflect, then plan again
+  after 6 tries: stop and warn "healthcheck stuck"
+```
+
+## 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
+(`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.
+
+## Running what you wrote
+
+- `loop 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).
+
+## Authoring checklist
+
+1. One coherent objective per `loop`; one story per `stage`.
+2. A real, fast `done when` predicate — never claim done without a check.
+3. `look at:` the relevant files so the agent stays inside the architecture.
+4. A `when it fails: reflect, then plan again` so the loop self-corrects.
+5. An `after N tries` thrash guard so it can't spin forever.
+6. Human gates on anything irreversible.

package/assets/examples/fix_test.loop

@@ -0,0 +1,6 @@
+loop "fix test":
+  goal: the checkout tax test passes
+  done when the test "checkout.spec.ts::tax" passes
+
+  each cycle: plan, then act, then observe
+  when it fails: reflect, then plan again

package/assets/skill/SKILL.md

@@ -0,0 +1,237 @@
+---
+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".
+---
+
+# Loop
+
+Loop is a small natural-language DSL for **loop engineering**: a `.loop` file describes a
+staged, self-correcting, human-gated coding workflow — its objective, the context it may
+read, the actions it may take, how it verifies itself, when it stops, and where a human
+steps in.
+
+You do two things with this skill: **create** `.loop` files, and **run** them — natively,
+in this conversation, so the user watches every step and answers gates right here.
+
+---
+
+## The language
+
+Vocabulary (the whole DSL):
+
+```
+loop "<name>":            a self-correcting loop
+pipeline "<name>":        a sequence of stages (an epic)
+stage "<name>":           one stage of a pipeline (its body is a loop; a story)
+
+flow "<name>":            a chain of whole .loop files, run in order (handoff is text)
+  run "<file.loop>"         a flow step: run that whole file
+  then run "<file.loop>"    the next step; the prior file's summary carries forward as context
+  ... with the result of <step>   pull the handoff from a named earlier step instead of the previous
+  for each <var> in "<file>":   run the child template once per item in <file>
+    run "<template.loop>"
+
+# `for each` source: .yaml/.yml (a list, or items under a single key) or .md (each `## ` section).
+# Each item's text becomes the template's context for that run.
+
+goal: <text>              what "done" means, in plain language
+done when <predicate>     how the loop verifies itself
+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
+when it fails: reflect on <focus>, then plan again
+when it passes and the goal is met: stop
+when blocked: ask a human
+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)
+```
+
+Predicates:
+```
+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"
+```
+
+Rules: indentation is structural (two spaces); `loop`/`pipeline` at column 0; comments
+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.
+
+## Show the flow — every time it changes
+
+Whenever you **create or edit** a `.loop`, immediately print its flow so the user
+watches the shape evolve. If the `loop` CLI is installed, run `loop show <file>`.
+Otherwise render the same compact ASCII yourself:
+
+```
+loop "fix test"
+   ↻  plan → act → observe        (each cycle)
+   ↺  on fail: reflect → plan     (the back-edge)
+   ✓  done when: test "checkout.spec.ts::tax"
+   ⛔ guard: after 6 tries → stop & warn "stuck"
+   ·  goal: the tax line is correct
+```
+
+For a **pipeline**, list the stages in order and mark 👤 gates; for a **flow**,
+show the file chain (`a.loop → b.loop → …`). `loop ls` lists every loop in the repo.
+
+---
+
+## Running a .loop (in this session)
+
+Prefer running it **yourself, here** — that way the whole loop is visible in the
+conversation and the user answers gates inline. (Only shell out to the `loop run` CLI if
+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:**
+   - **plan** — inspect the `look at:` files; decide the smallest change toward the goal.
+   - **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.
+   - 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
+     warning), or if genuinely blocked (ask the user).
+   - **human gates:** `a human approves the plan first` → present the plan and wait for
+     approval before acting. `a human reviews before stopping` → ask before declaring done.
+     `a human approves before <X>` → ask before that stage runs.
+   - **pipelines:** run stages in order; if a stage can't be satisfied, halt the rest.
+   - **flows:** run each referenced file in order, the *whole* file. After each, carry a
+     short text summary of how it went forward as context for the next file. If a file
+     isn't satisfied, halt the rest (fail-fast). `with the result of <step>` redirects
+     which earlier summary to carry.
+   - **for each `<var>` in `<file>`:** read the source file and split it into items
+     (`.yaml` list entries, or `.md` `## ` sections). Run the template loop once per item,
+     giving the template that item's text as its context. If an item's checklist fails,
+     pause and ask the user: continue to the next item, or stop the whole flow? Continuing
+     accepts that item and proceeds; reaching the end means done.
+   - **`also:`** finishing passes run only after the goal is met (skip them if it failed).
+3. **Report a concise trace** — one line per cycle step (plan / act / observe = PASS|fail /
+   reflect / stop), and the final outcome.
+
+Because you are the one running it, the user sees the real work — file reads, edits,
+command output — as part of this session, and answers any gate right in the chat.
+
+---
+
+## Interactive discovery (the front of an A-to-Z flow)
+
+A discovery/planning step is just a loop whose goal is to produce a planning artifact (a
+spec, PRD, or plan file). Run it as a real conversation:
+
+- Interview the user — ask the questions the method calls for — across as many turns as it
+  takes. You're naturally suspended between their answers, so a long session (even an hour)
+  is fine; there's nothing to "wait" on.
+- The step is **done when its `done when` artifact check passes** — e.g. the plan file
+  exists and has the required sections — NOT when the conversation goes quiet. Re-check the
+  artifact; when it validates, move on. (The questions come from the loop's goal/context —
+  i.e. the method — not from this skill.)
+
+So a full method, end to end, is a `flow`:
+
+    flow "deliver: <feature>":
+      run "discover.loop"          # conversation: interview → write the plan file
+      then run "design.loop"       # design from it; a human approves
+      then for each item in "plan.yaml":
+        run "item-template.loop"    # the per-item checklist, once per item
+
+`discover.loop` ends via e.g. `done when "<validator> plan.yaml"`; each item then runs the
+same checklist. (Name things to taste — a BMAD setup might use `story`/`sprint.yaml`.)
+
+---
+
+## Git strategy
+
+A `git:` block sets the version-control strategy for the whole file (config tier) or for
+a single loop. When there is no `git:` block at all the built-in default applies:
+**work on a branch, commit when the goal is met, no push**.
+
+### Line forms
+
+```
+work in place                    # edit the current branch as-is
+work on a branch                 # create / switch to a feature branch (default)
+work on a branch "my-feature"    # name the branch explicitly
+work in a worktree               # isolated git worktree
+work in a worktree "my-worktree" # named worktree
+
+commit when the goal is met      # one commit when done (default)
+commit each cycle                # commit after every plan→act→observe cycle
+commit each story                # commit after each stage in a pipeline
+commit never / do not commit     # no automatic commits
+
+push when done                   # push the branch when the loop finishes
+do not push                      # no push (default)
+
+open a pull request              # open a PR after pushing (requires push when done)
+```
+
+### Cascade
+
+Settings resolve in three layers, each refining the one above:
+
+1. **Built-in default** — branch + commit-when-done, no push.
+2. **File-level `git:` block** — placed at the top of the `.loop` file, before any loop definition; applies to every loop in the file.
+3. **Per-loop `git:` block** — placed inside a single `loop` body; refines the commit cadence for that loop only.
+
+A `use the <method>` preset may also carry a `git:` block; it applies at the file level and is then overridden by the file's own `git:` block if present.
+
+### Always-on safety
+
+Two protections are unconditional and cannot be overridden by any `git:` block:
+
+- **Never push to `main` or `master`.** If the current branch is `main` or `master` (or a branch whose name matches the protected set), any `push when done` directive is an error that surfaces *before the loop runs*, not after.
+- **`work in place` + `push when done` on a protected branch** is also rejected up front.
+
+### In-chat runner note
+
+When you run a loop *inside this conversation* (the `/loop` 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.
+
+---
+
+## 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 same `.loop` files.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "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.",
+  "license": "Apache-2.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "bin": { "loop": "src/cli.mjs" },
+  "files": ["src", "assets", "README.md"],
+  "engines": { "node": ">=18" },
+  "keywords": ["loop", "agent", "claude", "ai", "workflow", "dsl", "loop-engineering"],
+  "repository": { "type": "git", "url": "https://github.com/tickets-forge-dev/loop-lang.git", "directory": "packages/cli" },
+  "scripts": {
+    "sync-assets": "node scripts/sync-assets.mjs",
+    "prepack": "node scripts/sync-assets.mjs",
+    "test": "node scripts/sync-assets.mjs && node --test test/*.test.mjs"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,84 @@
+#!/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.
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { init } from "./init.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const ASSETS = join(here, "..", "assets");
+
+const HELP = `loop — install Loop into your repo so any agent can author + run .loop files
+
+usage:
+  loop init [options]      scaffold Loop into the current repo
+  loop help                show this
+
+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
+  --no-example     don't write examples/fix_test.loop
+  --claude-md      also write a CLAUDE.md pointer
+  --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
+  • any agent:   it reads AGENTS.md and can author + run .loop files
+  • headless:    install @loop/runtime for  loop 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; }
+
+async function main(argv) {
+  const cmd = argv[0];
+
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    console.log(HELP);
+    return;
+  }
+
+  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");
+    if (flag(argv, "--cursor") && !agents.includes("cursor")) agents.push("cursor");
+    if (flag(argv, "--copilot") && !agents.includes("copilot")) agents.push("copilot");
+
+    const targetDir = resolve(process.cwd(), opt(argv, "--dir") ?? ".");
+    const skill = flag(argv, "--no-skill") ? "none" : flag(argv, "--global") ? "global" : "local";
+
+    const { steps } = await init(targetDir, {
+      skill,
+      agents,
+      example: !flag(argv, "--no-example"),
+      force: flag(argv, "--force"),
+    }, ASSETS);
+
+    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(`    • 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\`.`);
+    process.exit(2);
+  }
+
+  console.error(`unknown command: ${cmd}\n`);
+  console.log(HELP);
+  process.exit(2);
+}
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(String(err?.message ?? err));
+  process.exit(1);
+});

package/src/init.mjs

@@ -0,0 +1,100 @@
+// `loop init` — install Loop into a repo so any agent can author + run .loop files.
+// Pure-ish: takes a target dir + options + the assets dir; returns the steps taken.
+// No external deps (node built-ins only) so the published package runs under npx as-is.
+import { readFile, writeFile, mkdir, cp, access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+const MARK_START = "<!-- loop:start (managed by `loop init` — edits between the markers are overwritten) -->";
+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 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 + ".",
+    "Every time you create or change a `.loop`, print its flow so the user can see the shape.",
+  ].join("\n");
+}
+
+const exists = (p) => access(p).then(() => true, () => false);
+
+/** Write `body` into `file`, replacing a prior `loop init` block if present, else appending/creating. */
+async function mergeMarkered(file, body) {
+  const block = `${MARK_START}\n${body}\n${MARK_END}`;
+  if (await exists(file)) {
+    const cur = await readFile(file, "utf8");
+    if (cur.includes(MARK_START) && cur.includes(MARK_END)) {
+      const next = cur.replace(new RegExp(`${esc(MARK_START)}[\\s\\S]*?${esc(MARK_END)}`), block);
+      await writeFile(file, next);
+      return "updated";
+    }
+    await writeFile(file, `${cur.replace(/\s*$/, "")}\n\n${block}\n`);
+    return "appended to";
+  }
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, `${block}\n`);
+  return "wrote";
+}
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+async function copyInto(src, dst, { force }) {
+  if (!force && (await exists(dst))) return "skipped";
+  await mkdir(dirname(dst), { recursive: true });
+  await cp(src, dst, { recursive: true });
+  return "wrote";
+}
+
+/**
+ * @param {string} targetDir  repo to install into (usually process.cwd())
+ * @param {object} opts  { skill:"local"|"global"|"none", agents:string[], example:boolean, force:boolean }
+ * @param {string} assetsDir  this package's assets/ dir (AGENTS.md, skill, examples)
+ * @returns {Promise<{steps:string[]}>}
+ */
+export async function init(targetDir, opts, assetsDir) {
+  const { skill = "local", agents = [], example = true, force = false } = opts;
+  const steps = [];
+  const withSkill = skill !== "none";
+
+  // 1. AGENTS.md — the universal language reference (every agent reads it).
+  const agentsBody = await readFile(join(assetsDir, "AGENTS.md"), "utf8");
+  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.
+  if (withSkill) {
+    const dst = skill === "global"
+      ? join(homedir(), ".claude", "skills", "loop")
+      : join(targetDir, ".claude", "skills", "loop");
+    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)`);
+  }
+
+  // 3. Opt-in per-agent memory pointers.
+  const ptr = pointer({ skill: withSkill });
+  if (agents.includes("claude")) {
+    const v = await mergeMarkered(join(targetDir, "CLAUDE.md"), ptr);
+    steps.push(`${v} CLAUDE.md  (Claude Code memory)`);
+  }
+  if (agents.includes("cursor")) {
+    const v = await mergeMarkered(join(targetDir, ".cursor", "rules", "loop.md"), ptr);
+    steps.push(`${v} .cursor/rules/loop.md  (Cursor)`);
+  }
+  if (agents.includes("copilot")) {
+    const v = await mergeMarkered(join(targetDir, ".github", "copilot-instructions.md"), ptr);
+    steps.push(`${v} .github/copilot-instructions.md  (GitHub Copilot)`);
+  }
+
+  // 4. A starter loop to run.
+  if (example) {
+    const r = await copyInto(join(assetsDir, "examples", "fix_test.loop"), join(targetDir, "examples", "fix_test.loop"), { force });
+    steps.push(`${r === "skipped" ? "skipped (exists)" : "wrote"} examples/fix_test.loop  (a starter loop)`);
+  }
+
+  return { steps };
+}