feat: add skills and cross-run memory to the Loop language

.claude/skills/loopflow/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
@@ -63,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
@@ -183,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

AGENTS.md

@@ -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

README.md

@@ -8,6 +8,8 @@
 
 <p align="center"><i>Stop tuning prompts. Start editing the loop.</i></p>
 
+<p align="center"><img src="docs/assets/loop-demo.svg" alt="A Loop turning a failing test green: plan → act → observe (FAIL) → reflect → plan → act → observe (PASS) → done" width="760"></p>
+
 <p align="center">
   <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/License-Apache_2.0-34e0c4.svg"></a>
   <a href="https://www.npmjs.com/package/@loop-lang/loop"><img alt="npm" src="https://img.shields.io/npm/v/@loop-lang/loop?color=84b6ff&label=%40loop-lang%2Floop"></a>
@@ -104,13 +106,34 @@ pipeline "ship feature":
     a human reviews before stopping
 ```
 
+## Skills and memory
+
+Two knobs make a loop coordinate proven work and learn over time:
+
+```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     # coordinate battle-tested skills
+  remember in "morning-run.memory.md"            # cross-run history + lessons learned
+  each cycle: plan, then act, then observe
+  done when the skill "workout-review" approves   # bridge the abstract to the verifiable
+```
+
+- **`use skills:`** names skills the loop may invoke while planning and acting — compose
+  proven skills instead of one mega-prompt (skill-driven development).
+- **`done when the skill "…" approves`** (or `scores N or more`) lets a review skill verify
+  a goal that isn't a test or command — a good email, a sound design, a sensible call.
+- **`remember in "<file>"`** gives the loop a markdown memory: it reads past lessons into its
+  first plan and appends an outcome entry when it stops. `reflect` is within-run memory;
+  `remember` is its across-run counterpart. See [`examples/skills_memory.loop`](examples/skills_memory.loop).
+
 ## Compose loops
 
 Compose loops into **pipelines** (stages in order, fail-fast), chain whole files with **`flow`**, and fan out over a plan with **`for each`** — humans wired in where judgment lives. Full grammar with worked examples: the [tutorial](https://loopflow.live) and the [manual](docs/MANUAL.md).
 
 ## The vocabulary (~15 words — learn it once)
 
-`pipeline` · `stage` · `loop` · `flow` · `for each … in …` · `run … then …` · `each cycle` · `goal` · `done when` · `look at` · `allow…/ask me before…` · `also` · `when…` · `reflect` · `a human…` · `stop` · `use` · `schedule` · `git`
+`pipeline` · `stage` · `loop` · `flow` · `for each … in …` · `run … then …` · `each cycle` · `goal` · `done when` · `look at` · `allow…/ask me before…` · `also` · `use skills` · `remember in` · `when…` · `reflect` · `a human…` · `stop` · `use` · `schedule` · `git`
 
 Power comes from **composition**, not keyword count.
 

docs/MANUAL.md

@@ -216,6 +216,8 @@ BMAD flow (discover → design → for each story) as one example method.
 | `allow edits automatically, but ask me before <classes>` | Action policy. Auto classes run unattended; confirm classes pause for you. Classes: `edit`, `migrate`, `push`, `deploy`, `delete`. |
 | `each cycle: plan, then act, then observe` | The repeated steps — any subset of `plan` / `act` / `observe`, in order. |
 | `also: <pass>, <pass>` | Extra finishing passes run **after** the goal is met (skipped on failure). |
+| `use skills: <a>, <b>` | Named skills the loop may invoke during `plan`/`act` — coordinate proven skills instead of one mega-prompt. |
+| `remember in "<file.md>"` | Cross-run memory: read the file's lessons into the first plan, append a dated outcome entry on stop. (`keep a memory in "<file>"` also works.) |
 | `when it passes and the goal is met: stop` | Success transition. |
 | `when it fails: reflect on <focus>, then plan again` | The feedback edge — reflect, then re-enter the cycle. |
 | `when blocked: ask a human` | Pause for a person when stuck. |
@@ -237,11 +239,19 @@ done when the test "billing.spec.ts::apostrophe" passes   # a named test
 done when "pnpm test" passes                               # shell command, exit 0 (`succeeds` also works)
 done when "semgrep --severity=high" finds nothing          # shell command, empty stdout
 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 runs in your shell with your privileges (like an npm script). Keep it fast
 and deterministic.
 
+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, a sensible go/no-go call — a review skill
+returns an approved/rejected verdict or a 0–10 score, and the loop treats that as its check.
+Build the review skill manually first and confirm it judges well, then wire it in. See
+`examples/skills_memory.loop` and `examples/email_review.loop`.
+
 ### Config tier (top of file)
 
 ```loop

examples/email_review.loop

@@ -0,0 +1,11 @@
+# Skill-as-verifier with a numeric threshold: an email isn't "done" until a review
+# skill scores it 8 or more out of 10.
+loop "draft the launch announcement email":
+  goal: a launch email that is clear, on-brand, and ready to send
+  use skills: write-email
+  remember in "launch-email.memory.md"
+  each cycle: plan, then act, then observe
+  done when the skill "email-review" scores 8 or more
+  when it fails: reflect on the lowest-scoring dimension, then plan again
+  a human reviews before stopping
+  after 5 tries: stop and warn "review won't reach 8 — needs a human"

examples/morning-run.memory.md

@@ -0,0 +1,8 @@
+# morning-run — memory
+
+Run history and lessons the loop reads on start and appends to on stop.
+
+## 2026-06-18 — done
+- goal: a clear go / no-go call the runner trusts, with a one-line reason
+- outcome: satisfied after 2 tries
+- lesson: light drizzle below 2mm/h is fine for this runner — don't cancel on rain alone, check intensity.

examples/skills_memory.loop

@@ -0,0 +1,10 @@
+# Skills + memory: a non-technical loop that coordinates skills, verifies with a
+# review skill, and remembers what it learns across runs.
+loop "decide whether to cancel the morning run":
+  goal: a clear go / no-go call the runner trusts, with a one-line reason
+  use skills: check-weather, analyze-workout   # battle-tested skills the loop coordinates
+  remember in "morning-run.memory.md"          # cross-run history + lessons learned
+  each cycle: plan, then act, then observe
+  done when the skill "workout-review" approves  # bridge the abstract to the verifiable
+  when it fails: reflect on what the review flagged, then plan again
+  after 4 tries: stop and warn "no call the review would approve"