feat: live dashboard for loop runs — Waze-style route, CLI + in-session

.claude/skills/loopflow/SKILL.md

@@ -82,6 +82,13 @@ it in front of them. Never silently guess the loop; interview first, then author
 one topic at a time, and always offer a default so a confident user can accept it all
 in one reply.
 
+**Check the template library first.** If the repo has a `templates/` directory (see
+`templates/README.md`), and the user's request matches one — a bug fix, a feature, a
+brownfield change, a CI/security/architecture gate, delivering an existing spec, building
+a greenfield app — start from that template instead of a blank file: read it, copy it, and
+fill in its `# TODO` lines with the user's specifics. Still interview them for the goal,
+the real `done when`, and what to gate; the template is the skeleton, not the answer.
+
 ### 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
@@ -103,8 +110,12 @@ into a scoped loop and teaches the three top-level forms at once.
 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 medium/large** → invoke `superpowers:brainstorming` **before** writing any `.loop`. The brainstorming skill explores project context, asks clarifying questions one at a time (offering a browser visual when a design choice benefits from it), proposes 2-3 approaches, gets user approval, and produces a spec doc at `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`. Once the spec is approved and saved:
+  - The approved goal → `goal:` in the loop
+  - The spec file → `look at: docs/superpowers/specs/<name>.md`
+  - Sub-tasks in the spec → `stage`s in a `pipeline`, or `for each <var> in "plan.yaml"`
+
+  This replaces the old "discovery loop" pattern — brainstorming handles the interview natively in-session and produces a richer, visually-validated artifact.
 - **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)
@@ -178,6 +189,81 @@ show the file chain (`a.loop → b.loop → …`). `loop ls` lists every loop in
 
 ---
 
+## Live browser dashboard
+
+A live animated schematic in the browser — the active cycle node pulses, flow steps
+highlight as they execute, and a for-each (sprint) progress bar fills item by item, so the
+user always sees **where in the loop / where in the plan** the run currently is.
+
+### Gate it on `loop.config` (in-session runs)
+
+The in-session dashboard is **opt-in via repo config** — off by default so a normal
+`/loopflow` run stays entirely in the chat. Before running a loop in this session, read
+`loop.config` at the repo root and look for a `live=` line:
+
+- **`live=false`, or the line/file is absent** → **do not** start the dashboard. Run
+  normally, narrating the trace in chat (the *Running a .loop* section below). Do not ask.
+- **`live=true`** → start the dashboard and drive it as you narrate (mechanism below). You
+  may still mention you're opening it.
+
+(`loop.config` is written by `loop init` with `live=false`; the user flips it to `live=true`
+to turn the dashboard on. The headless `loop-run run <file> --live` flag is independent of
+this config.)
+
+### How the in-session dashboard works
+
+You (the skill) **are** the engine in-session — so you spin up a tiny server, point the
+browser at it, and push an event for each step you narrate. The browser renders in real
+time. Three pieces, all via the `loop-run` CLI:
+
+1. **Start the server (background) and grab its port:**
+   ```bash
+   loop-run live <file.loop>      # opens the browser automatically
+   ```
+   Run it in the **background** (don't block on it). Read its first stdout line —
+   `LOOP_LIVE_PORT=<port>` — and keep `<port>` for the rest of the run. The server renders
+   the loop's schematic and stays up until you stop it (or the user hits Ctrl-C).
+
+2. **Push an event as you reach each step** — one `emit` per narrated step:
+   ```bash
+   loop-run emit <port> '<event-json>'
+   ```
+   `emit` is best-effort (never blocks your narration if the browser is closed). Push the
+   same events the engine would emit; the key ones to keep the view truthful:
+
+   | When you… | Push |
+   |-----------|------|
+   | start a flow | `{"type":"flow-start","name":"<flow>"}` |
+   | enter a flow step | `{"type":"flow-step-start","name":"<step>","ref":"<file>"}` |
+   | finish a flow step | `{"type":"flow-step-end","name":"<step>","satisfied":true}` |
+   | start a `for each` | `{"type":"foreach-start","var":"<var>","source":"<file>","count":<N>,"labels":["<title 1>","<title 2>",…]}` — pass `labels` (one short title per item, e.g. each story's title) so the dashboard lists the real items instead of "story 1..N" |
+   | start item i (0-based) | `{"type":"foreach-item-start","var":"<var>","index":<i>,"total":<N>}` |
+   | finish item i | `{"type":"foreach-item-end","var":"<var>","index":<i>,"satisfied":true}` |
+   | begin a cycle step | `{"type":"node-enter","node":"plan","attempt":<n>}` (then `act`, `observe`) |
+   | finish a cycle step | `{"type":"node-exit","node":"plan","attempt":<n>,"ok":true}` |
+   | run the done-when check | `{"type":"observe","passed":true,"output":"<first line>"}` |
+   | reflect on failure | `{"type":"reflect","text":"<why>"}` then loop-back `{"type":"loop-back","to":"plan"}` |
+   | start a pipeline stage | `{"type":"stage-start","name":"<stage>"}` |
+   | stop | `{"type":"stop","reason":"done"}` then `{"type":"loop-end","name":"<loop>","satisfied":true}` |
+
+3. **At the end**, leave the server running so the user can review the final state. Mention
+   they can Ctrl-C the `loop-run live` process to close it.
+
+The dashboard renders the loop's **actual structure** as a turn-by-turn route (Waze-style):
+the real stages / flow steps / for-each items, with a "you are here", the steps ahead, and
+human gates flagged. So a sprint (`for each story in "sprint.yaml"`) lists each story by title
+with N/total progress, a check on finished stories, and a plan/act/observe tracker on the one
+you're working now — exactly "where are we in the loop / in the plan".
+
+### CLI-only alternative (headless)
+
+If the user would rather run it headless (gates answered in the terminal, not chat):
+```bash
+loop-run run <file.loop> --live
+```
+The engine itself emits every event to the browser — no manual `emit` needed. Use this only
+when the user explicitly wants the headless runner.
+
 ## Running a .loop (in this session)
 
 Prefer running it **yourself, here** — that way the whole loop is visible in the

AGENTS.md

@@ -38,6 +38,23 @@ high-leverage questions and offering defaults for the rest: (1) the **goal**;
 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.
 
+### Start from a template when one fits
+
+This repo ships a library of **best-practice starter loops** in [`templates/`](./templates/)
+(see [`templates/README.md`](./templates/README.md)). When the user's request matches one,
+**reach for it first** — copy it, fill in its `# TODO` lines (test commands, paths), and
+adapt — instead of authoring from a blank file. They cover the everyday jobs:
+
+- **Spec-driven:** `greenfield-app.loop` (whole app, A-to-Z), `load-spec.loop` (deliver an
+  existing `plan.md` + `sprint.yaml` backlog story by story) — with `discover.loop`,
+  `design.loop`, `story-template.loop`, and starter `sprint.yaml`/`plan.md`.
+- **Change:** `feature.loop`, `brownfield-feature.loop`, `bugfix.loop`, `refactor.loop`.
+- **Quality gates:** `cicd-check.loop`, `security.loop`, `clean-architecture.loop`,
+  `test-coverage.loop`, `review-diff.loop`.
+
+Each is heavily commented and verified to parse. Still interview the user for the specifics
+(goal, the real `done when`, what to gate) — the template is the skeleton, not the answer.
+
 ## Vocabulary (the whole language)
 
 ```
@@ -294,6 +311,25 @@ flow, show the file chain. `loop-run ls` lists every loop in the repo.
 - `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.
 
+### Live visual — opt-in via `loop.config`
+
+The in-session dashboard is **off by default**. Before running a loop **in this session**,
+read `loop.config` at the repo root: only if it has `live=true` do you start the dashboard
+and drive it as you narrate. With `live=false` (the default written by `loop init`) or no
+config, run normally in the chat — don't open anything, don't ask. (The headless
+`loop-run run <file> --live` flag below is independent of this config.) When enabled:
+
+- `loop-run live file.loop` — start the dashboard server (opens the browser, prints
+  `LOOP_LIVE_PORT=<port>`), run it in the **background**, keep the port.
+- `loop-run emit <port> '<event-json>'` — push one event per narrated step so the browser
+  animates in real time: the active cycle node pulses, flow steps light up, and a
+  `for each` (sprint) progress bar fills item by item — the user always sees where in the
+  loop and where in the plan the run is.
+- `loop-run run file.loop --live` — headless alternative: the engine itself streams every
+  event to the browser (no manual `emit`), gates answered in the terminal.
+
+The `/loopflow` skill has the full event cheat-sheet for the in-session push protocol.
+
 ## Authoring checklist
 
 1. One coherent objective per `loop`; one story per `stage`.

CHANGELOG.md

@@ -2,33 +2,105 @@
 
 All notable changes to LoopFlow are recorded here. The packages share the `0.x`
 line; the `loop-vscode` extension versions independently (it had an earlier cut).
+Versions track the `@loop-lang/loop` installer package.
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-06-28
+
+> `@loop-lang/loop` 0.5.0 · `@loop-lang/{parser,runtime,stdlib,viz}` 0.2.0
+
+### Added
+- **Live dashboard** — a real-time browser view of a run that renders the loop's
+  *actual* structure (pipeline stages / flow steps / for-each items) as a turn-by-turn
+  route (Waze-style): a "you are here" marker, the steps ahead, human gates flagged, and
+  `for each` sprints listed by item title with live progress and a per-item
+  plan/act/observe tracker.
+  - Headless: `loop-run run <file> --live` opens a browser and the engine streams every
+    event to it over Server-Sent Events.
+  - In-session: running a loop via `/loopflow` opens the dashboard when enabled, pushing
+    one event per narrated step.
+- `loop-run live <file>` (dashboard server, no engine) and
+  `loop-run emit <port> '<json>'` (push one event) commands.
+- `loop init` now writes a `loop.config` file (`live=false` by default) that gates the
+  in-session dashboard; written once and never clobbered unless `--force`. Set
+  `live=true` to have `/loopflow` show the dashboard.
+- `loop version` command (and `--version` / `-v`).
+- `@loop-lang/viz` exports `renderLiveHtml`; `@loop-lang/runtime` adds `startLiveServer`
+  and derives short item labels (`labelOf`) so headless sprints show real story titles.
+- `/loopflow` integrates `superpowers:brainstorming` for the no-plan (medium/large) path.
+- **Template library** — `templates/` ships best-practice, copy-and-edit starter loops for
+  everyday work (bugfix, feature, brownfield-feature, refactor; cicd-check, security,
+  clean-architecture, test-coverage, review-diff; greenfield-app and load-spec with their
+  supporting discover/design/story-template + starter sprint.yaml/plan.md). `loop init`
+  installs them (`--no-templates` to skip), and AGENTS.md + the `/loopflow` skill point the
+  agent at a matching template before authoring from scratch. All validated to parse.
+
+### Changed
+- The dashboard uses a flat, Linear-style dark theme; self-contained (no external assets)
+  and bound to `127.0.0.1` only.
+- SSE stream tags each event with an id and replays buffered events on connect, deduping
+  on reconnect via `Last-Event-ID`, plus a heartbeat so idle connections survive proxy/NAT
+  timeouts — events fired before the browser connects aren't lost and a transient drop
+  doesn't double-deliver.
+- `loop-run run --live` keeps the dashboard alive after the run (Ctrl-C to exit) so a fast
+  loop's result stays viewable; shared run wiring de-duplicated.
+
+### Fixed
+- Dashboard: a failed cycle node no longer throws (and now logs the failure); a standalone
+  single-loop file activates its route leg; the "needs you" gate clears when work resumes;
+  `for each` legs finalize on completion.
+- `labelOf` follows YAML block scalars (`story: |`/`>`) to their body, keeps URLs/times
+  (`https://`, `09:00`) intact, only strips a balanced quote pair, and truncates without
+  splitting a surrogate pair.
+- Cross-platform: Windows browser auto-open (`cmd /c start`), page title via
+  `path.basename`, `version.test` cwd via `fileURLToPath`. HTML-escape the dashboard
+  `<title>`; corrected the `embedJson` `<`-escape.
+
+### Docs
+- Tutorial (`docs/index.html`), `README.md`, `docs/MANUAL.md`, `AGENTS.md`, and the
+  `/loopflow` skill document the live dashboard, the `loop.config` gate, and the
+  `live`/`emit`/`--live` commands.
+- The tutorial now leads with the **Claude Code chat (`/loopflow`)** as the first-class
+  usage path and demotes the VS Code extension to optional hand-authoring; added a
+  "Starter templates" section.
+
+## [0.4.0] — 2026-06-27
+
+### Added
+- **Skills** — `use skills: <a>, <b>` lets a loop invoke named skills during plan/act, and
+  `done when the skill "<name>" approves` / `scores N or more` turns a review skill into a
+  verifiable predicate.
+- **Cross-run memory** — `remember in "<file>"` reads past lessons on start and appends a
+  dated outcome on stop, so a loop improves across runs.
+- `/loopflow` auto-installs globally on `npm install -g @loop-lang/loop`.
+
+## [0.2.0] — 2026-06-22
+
 ### Changed
 - Unified the npm scope: the libraries moved from `@loop/*` to `@loop-lang/*`
-  (`@loop-lang/parser`, `@loop-lang/runtime`, `@loop-lang/stdlib`,
-  `@loop-lang/viz`), matching the installer `@loop-lang/loop`.
-- The runtime CLI binary is now `loop-run` (`loop-run run`, `loop-run show`, …);
-  the installer (`@loop-lang/loop`) keeps the `loop` command (`loop init`), so the
-  two no longer collide on a global install.
-- `plan from` is now a generic file source: `plan from "docs/plan.md"` reads the
-  plan from a file instead of having the agent generate one. Replaces the former
-  `plan from archon`.
+  (`@loop-lang/parser`, `@loop-lang/runtime`, `@loop-lang/stdlib`, `@loop-lang/viz`),
+  matching the installer `@loop-lang/loop`.
+- The runtime CLI binary is now `loop-run` (`loop-run run`, `loop-run show`, …); the
+  installer (`@loop-lang/loop`) keeps the `loop` command (`loop init`), so the two no
+  longer collide on a global install.
+- Renamed the Claude Code skill to `/loopflow` (avoids colliding with the built-in `/loop`
+  scheduler) and rewrote the README.
+- `plan from` is now a generic file source: `plan from "docs/plan.md"` reads the plan from
+  a file instead of having the agent generate one. Replaces the former `plan from archon`.
 
 ### Removed
-- Dropped all Archon coupling: the `@loop-lang/export-archon` package, the
-  `loop export` (Archon workflow YAML) command, the `plan from archon` source,
-  and the `ARCHON_URL`/`ARCHON_TOKEN`/`ARCHON_CODEBASE_ID` env vars. LoopFlow runs
-  natively on Claude Code; the language no longer references any third-party tool.
+- Dropped all Archon coupling: the `@loop-lang/export-archon` package, the `loop export`
+  (Archon workflow YAML) command, the `plan from archon` source, and the
+  `ARCHON_URL`/`ARCHON_TOKEN`/`ARCHON_CODEBASE_ID` env vars. LoopFlow runs natively on
+  Claude Code; the language no longer references any third-party tool.
 
 ### Added
 - CI (`build` + `test` on Node 18/20) and a tag-driven release workflow.
-- `SECURITY.md`, this changelog, and publish metadata (`publishConfig`,
-  `repository`, `homepage`, `bugs`) across the published packages.
+- `SECURITY.md`, this changelog, and publish metadata (`publishConfig`, `repository`,
+  `homepage`, `bugs`) across the published packages.
 
 ## [0.1.0]
 
-- First public release: the LoopFlow (`.loop`) language, parser, runtime, viz,
-  stdlib presets, the `loop` installer CLI, and the `loop-vscode` extension
-  (published as `0.2.0`).
+- First public release: the LoopFlow (`.loop`) language, parser, runtime, viz, stdlib
+  presets, the `loop` installer CLI, and the `loop-vscode` extension (published as `0.2.0`).

README.md

@@ -177,6 +177,21 @@ Describe work and it writes the `.loop`; name a `.loop` file and it runs the loo
 human gates right in the chat. Copy `.claude/skills/loopflow/` to `~/.claude/skills/` to use it
 in any repo (it's already active inside this one).
 
+## Watch it run — live dashboard
+
+A real-time browser view of a run, showing the loop's **actual structure** as a turn-by-turn
+route (Waze-style): where you are, the steps ahead, human gates, and for-each sprints listed
+by item title with live progress.
+
+```
+loop-run run file.loop --live      # headless: engine streams every step to the browser
+/loopflow run file.loop            # in-session: the skill offers the dashboard, then drives it
+```
+
+When you run a loop via `/loopflow`, the skill asks if you want the dashboard and, on yes,
+opens it and updates it as each step happens — pipeline stages, flow steps, and sprint stories
+filling in as the loop progresses.
+
 ## Project layout
 
 | Package | Purpose |
@@ -185,7 +200,7 @@ in any repo (it's already active inside this one).
 | `@loop-lang/runtime` | walks a spec, drives Claude Code, emits a live trace |
 | `@loop-lang/vscode` | highlight, formatter, ▶ Play CodeLens, live gutter trace |
 | `@loop-lang/stdlib` | `BMAD.loop` + starter presets |
-| `@loop-lang/viz` | `loop-run viz file.loop` → self-contained HTML schematic (the cycle + reflect back-edge) |
+| `@loop-lang/viz` | `loop-run viz file.loop` → self-contained HTML schematic; also the live dashboard (`--live`) |
 | `spec/loop-spec.schema.json` | the open IR contract |
 
 ## Is this just another <X>?