diff --git a/.claude/skills/seo-audit/SKILL.md b/.claude/skills/seo-audit/SKILL.md new file mode 100644 index 0000000..493fd14 --- /dev/null +++ b/.claude/skills/seo-audit/SKILL.md @@ -0,0 +1,119 @@ +--- +name: seo-audit +description: Audit and improve on-page SEO for web pages, docs sites, and marketing pages. Use whenever the user wants an SEO review or audit, wants to check or fix title tags / meta descriptions / Open Graph / Twitter cards / canonical URLs / structured data (JSON-LD) / robots / sitemap / heading structure / image alt text, asks "why isn't this page ranking / showing a preview card", wants to optimize a page for search or social sharing, or mentions SEO, meta tags, OG tags, rich results, or search snippets — even if they don't say the word "audit". Works on local source files (HTML, JSX/TSX, Markdown, Astro/Next/Vite) or a live URL. Not for off-page SEO (backlinks, ad campaigns) or keyword-volume research. +--- + +# On-page SEO audit + +Review a page (or a set of pages) against on-page SEO best practices, report what's +wrong in priority order, and — when the user wants — fix it in the source files. + +The point is not to produce a checklist for its own sake. Search engines and social +platforms read a page's `` and semantic HTML to decide how to index it and how to +render its preview card. When those signals are missing or wrong, the page still "works" +for humans but is invisible or ugly to crawlers. Your job is to find that gap and close it. + +## Decide the target first + +Two modes — pick based on what the user gives you: + +- **Source mode (default when working in a repo):** audit the files that produce the page. + This is what the user usually wants when the pages live in this repo, because the fix + lands in code they can commit. Find where `` / metadata is set — this varies by + stack, so look before assuming: + - Static HTML → the `` in the `.html` file. + - Next.js → `metadata` exports / `` / `generateMetadata` in `app/` or `pages/`. + - Astro → frontmatter + `` in layout `.astro` files. + - Vite/plain SPA → `index.html` plus any runtime `document.title` / meta injection. + - Markdown docs (MkDocs, Docusaurus, VitePress, Jekyll) → frontmatter + the theme's + head template. Per-page `title`/`description` usually live in frontmatter. + Grep for `og:`, `twitter:`, `canonical`, `application/ld+json`, ``. Note in the report that you audited rendered output, not source. + +If the user hasn't said which, infer from context (a repo path → source; a URL → live) and +state which mode you chose in one line. Don't stall on the choice. + +## What to check + +Go through these. For each, report the current value (or "missing"), whether it's OK, and +what to change. Read `references/checklist.md` for the full detail on any item — thresholds, +common mistakes, and exactly what good looks like. The high-signal ones, roughly in order +of how often they matter: + +1. **``** — present, unique per page, ~50–60 chars, front-loads the primary term. +2. **`<meta name="description">`** — present, ~120–160 chars, compelling, not duplicated + across pages. Missing/duplicate descriptions are the single most common real problem. +3. **Open Graph** — `og:title`, `og:description`, `og:image` (absolute URL, ~1200×630), + `og:url`, `og:type`. This is what LinkedIn/Slack/Facebook show. A missing `og:image` + is why a shared link looks blank. +4. **Twitter/X card** — `twitter:card` (usually `summary_large_image`), plus title/desc/image. +5. **Canonical** — `<link rel="canonical">` with an absolute URL, to avoid duplicate-content + splitting between www/non-www, trailing-slash, and query-param variants. +6. **Headings** — exactly one `<h1>`, no skipped levels (h1→h3), headings describe content + not styling. +7. **Image `alt`** — every meaningful `<img>` has descriptive alt text; decorative images + have empty `alt=""`. +8. **Structured data** — JSON-LD (`application/ld+json`) appropriate to the page type + (Article, Product, Organization, BreadcrumbList, FAQPage). Validate the shape. +9. **`robots`** — no accidental `noindex`/`nofollow` on pages that should rank; a sensible + `<meta name="robots">` where needed. +10. **Crawlability** — `robots.txt` and `sitemap.xml` exist and are referenced; internal + links use real `<a href>`; important content isn't hidden behind JS-only rendering. +11. **Technical hygiene** — `<html lang>` set, one viewport meta, HTTPS, no broken canonical + or OG URLs, reasonable page-load weight. + +Don't invent problems to pad the report. If a page is in good shape, say so — a short +"these 9 things are correct, here are the 2 that aren't" is more useful than a wall of green +checkmarks. + +## Report format + +Lead with the fixes that matter. Use this shape: + +``` +# SEO audit — <page or URL> (<source|live> mode) + +## Critical (breaks indexing or sharing) +- <issue> — <why it matters> — <exact fix, with file:line if source mode> + +## Recommended (real improvement, not urgent) +- ... + +## Passing +- <one line each for the checks that are already correct> +``` + +- **Critical** = the page won't be indexed correctly or its share card is broken (missing + title, `noindex` by accident, no og:image, broken canonical). +- **Recommended** = genuine improvements (thin description, missing JSON-LD, h1 issues). +- Every fix must be **specific**: the actual tag to add and where, not "improve your meta + description". In source mode, cite `file:line`. Prefer showing the exact snippet to paste. + +## Applying fixes + +Only edit files when the user asks you to fix things (or approves the audit's fixes). Then: + +- Make the smallest change that resolves each issue; match the file's existing style and the + framework's idiom (e.g. Next's `metadata` export, not a raw `<head>` tag, in an app-router + project). +- Use **absolute** URLs for `og:image`, `og:url`, and `canonical` — relative URLs silently + break when the page is scraped off-domain. If you don't know the production origin, find it + (existing tags, `package.json` homepage, CNAME, config) or ask rather than guessing. +- After editing, re-run the relevant checks so the report reflects reality, and show a diff. + +## Verifying + +Recommend the user confirm share cards with the platform validators (these re-scrape the +live URL, so they only work after deploy): opengraph.xyz, LinkedIn Post Inspector, +X/Twitter Card Validator, and Google's Rich Results Test for structured data. For local +verification, re-read the rendered `<head>` (live mode) or re-grep the source (source mode). +``` +``` + +Keep the audit proportional to the ask: one page → tight focused report; "audit the whole +site" → sample the templates that generate the pages (layout, per-type page components) +since fixing a template fixes every page it renders, and call out which pages inherit each fix. diff --git a/.claude/skills/seo-audit/references/checklist.md b/.claude/skills/seo-audit/references/checklist.md new file mode 100644 index 0000000..d33c687 --- /dev/null +++ b/.claude/skills/seo-audit/references/checklist.md @@ -0,0 +1,140 @@ +# On-page SEO checklist — full detail + +Read this when you need the precise threshold, the common failure mode, or a copy-paste +example for a given item. The SKILL.md has the summary; this has the specifics. + +## Table of contents +1. Title tag +2. Meta description +3. Open Graph +4. Twitter / X card +5. Canonical URL +6. Headings +7. Image alt text +8. Structured data (JSON-LD) +9. Robots directives +10. Crawlability (robots.txt, sitemap, links) +11. Technical hygiene +12. Copy-paste starter block + +--- + +## 1. Title tag +- **Good:** unique per page, ~50–60 characters (Google truncates around 580px ≈ 60 chars), + primary keyword/topic near the front, brand at the end (`Primary Topic — Brand`). +- **Bad:** same title on every page, empty, >70 chars (truncated in results), keyword-stuffed, + or set only via JS so crawlers that don't run JS miss it. +- Only one `<title>` per page. In SPAs, make sure the title is set before first paint or + server-rendered, not just updated on route change. + +## 2. Meta description +- **Good:** 120–160 characters, reads like ad copy, describes what the page delivers, unique + per page, includes the term a searcher would use. +- **Bad:** missing (Google auto-generates a worse one), duplicated across pages (the most + common real SEO defect), truncated mid-word, or just the first sentence of body text. +- Not a ranking factor directly, but drives click-through from the results page, which is. + +## 3. Open Graph (`og:`) +Required for a rich share card on LinkedIn, Facebook, Slack, Discord, iMessage: +- `og:title` — can differ from `<title>`; optimize for the share context. +- `og:description` — 2–4 sentences. +- `og:image` — **absolute** URL, ideally 1200×630 (1.91:1), under ~5MB, PNG/JPG. This is the + single most impactful tag for social — a missing or relative `og:image` is why a shared link + renders as a blank/text-only card. +- `og:url` — the canonical absolute URL of the page. +- `og:type` — `website` for home/landing, `article` for posts. +- Optional but nice: `og:site_name`, `og:image:alt`, `og:locale`. + +## 4. Twitter / X card +- `twitter:card` — `summary_large_image` for a big image, `summary` for a small one. +- `twitter:title`, `twitter:description`, `twitter:image` — X falls back to OG tags for + most fields, so you often only need `twitter:card` if OG is complete. Verify rather than + assuming; add `twitter:image` explicitly if the OG image isn't picked up. +- Optional: `twitter:site` / `twitter:creator` (@handles). + +## 5. Canonical URL +- `<link rel="canonical" href="https://example.com/page">` — absolute, self-referential on + the primary version of the page. +- Prevents duplicate-content dilution across `http/https`, `www/non-www`, trailing slash, + and tracking-param variants (`?utm_...`). +- **Bad:** canonical pointing to the wrong page, to a relative URL, to a `noindex` page, or + every page canonicalizing to the homepage (a classic accidental de-indexing). + +## 6. Headings +- Exactly one `<h1>`, describing the page's main topic. +- Don't skip levels (h1 → h2 → h3, not h1 → h4). Screen readers and crawlers use the outline. +- Headings should describe content, not be chosen for their font size — use CSS for styling. + +## 7. Image alt text +- Every meaningful `<img>` needs `alt` describing the image's content/function. +- Purely decorative images: `alt=""` (empty, not missing) so assistive tech skips them. +- **Bad:** `alt="image"`, `alt="logo logo logo"`, filename dumped as alt, or no alt attribute + at all (fails accessibility and loses image-search traffic). + +## 8. Structured data (JSON-LD) +- Embed as `<script type="application/ld+json">` in the head or body. +- Match the schema.org type to the page: `Article`/`BlogPosting`, `Product` + `Offer`, + `Organization`, `WebSite` (+ `SearchAction` for a sitelinks search box), `BreadcrumbList`, + `FAQPage`, `HowTo`. +- Required fields vary by type — validate the shape (all required properties present, correct + nesting) and confirm it matches visible page content (Google penalizes mismatched markup). +- Verify with Google's Rich Results Test after deploy. + +## 9. Robots directives +- Check no page that should rank carries `<meta name="robots" content="noindex">` or + `nofollow` by accident — a staging default that shipped to prod is a common cause of "my + pages vanished from Google." +- Use `noindex` deliberately on thank-you pages, filtered/faceted URLs, internal search results. +- `X-Robots-Tag` HTTP header can also set this — in live mode check response headers too. + +## 10. Crawlability +- **robots.txt** at the domain root: doesn't accidentally `Disallow: /`, and references the + sitemap (`Sitemap: https://example.com/sitemap.xml`). +- **sitemap.xml**: exists, lists canonical URLs, valid XML, submitted in Search Console. +- **Internal links** use real `<a href>` (crawlers follow those, not `onclick` divs). +- **Content** important for ranking should be in the initial HTML, not injected only after a + client-side fetch — if it's live mode, compare `WebFetch` output (no JS) against the + Chrome-rendered DOM to see what a non-JS crawler misses. + +## 11. Technical hygiene +- `<html lang="en">` (or correct locale) set. +- Exactly one `<meta name="viewport" content="width=device-width, initial-scale=1">`. +- Served over HTTPS; no mixed content. +- No duplicate/conflicting meta tags (two descriptions, two canonicals). +- Reasonable performance — Core Web Vitals (LCP, CLS, INP) influence ranking; flag obviously + heavy pages, but deep perf work is its own task. + +## 12. Copy-paste starter block +A complete, correct head to diff a page against (replace values; keep URLs absolute): + +```html +<title>Primary Topic — Brand + + + + + + + + + + + + + + + + + + + + + +``` diff --git a/docs/game.html b/docs/game.html index fe47b7e..58e1eed 100644 --- a/docs/game.html +++ b/docs/game.html @@ -5,6 +5,18 @@ LoopFlow Lab — learn loops by building them + + + + + + + + + + + + @@ -221,8 +233,10 @@ .startbtn:hover{filter:brightness(1.07);} @media(max-width:640px){ .pblock{min-width:0; flex:1 1 44%;} .brand{font-size:21px;} .card.lvl h2{font-size:23px;} } + +

LoopFlow Lab — learn loop engineering by building loops

LoopFlow Studio
diff --git a/docs/index.html b/docs/index.html index 6b132c0..70b2956 100644 --- a/docs/index.html +++ b/docs/index.html @@ -11,10 +11,15 @@ + + + @@ -195,6 +200,7 @@ .heroduo .duo-arrow{transform:rotate(90deg);padding:0} } + after N tries (thrash guard) — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -42,5 +55,5 @@

How it runs

The order is the engine's, not yours: attempts is checked before fail, so the thrash guard always wins once you hit the limit.

Related

when … (transitions)reflect
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/allow.html b/docs/keywords/allow.html index 98adcb0..13f792a 100644 --- a/docs/keywords/allow.html +++ b/docs/keywords/allow.html @@ -1,9 +1,22 @@ allow / ask me before — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -30,5 +43,5 @@

Example

Related

look athuman gatesgit:
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/also.html b/docs/keywords/also.html index 0ac7b07..e9e082a 100644 --- a/docs/keywords/also.html +++ b/docs/keywords/also.html @@ -1,9 +1,22 @@ also — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -30,5 +43,5 @@

Example

Related

each cycledone when
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/done-when.html b/docs/keywords/done-when.html index bfaad2a..89018be 100644 --- a/docs/keywords/done-when.html +++ b/docs/keywords/done-when.html @@ -1,9 +1,22 @@ done when — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -33,5 +46,5 @@

Example

Related

goalreflectwhen … (transitions)
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/each-cycle.html b/docs/keywords/each-cycle.html index 22b2b2e..dcb386a 100644 --- a/docs/keywords/each-cycle.html +++ b/docs/keywords/each-cycle.html @@ -1,9 +1,22 @@ each cycle — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -43,5 +56,5 @@

How it runs

Every cycle runs plan → act → observe; the done when check decides — pass → stop, fail → reflect into the next plan.

Related

reflectwhen … (transitions)loop
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/flow.html b/docs/keywords/flow.html index 9fe5a9e..23096bc 100644 --- a/docs/keywords/flow.html +++ b/docs/keywords/flow.html @@ -1,9 +1,22 @@ flow — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -44,5 +57,5 @@

How it runs

A flow chains separate .loop files; after each, a short text summary carries into the next as context.

Related

run / then runfor eachpipeline
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/for-each.html b/docs/keywords/for-each.html index 02e20e8..1895cd1 100644 --- a/docs/keywords/for-each.html +++ b/docs/keywords/for-each.html @@ -1,9 +1,22 @@ for each — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -49,5 +62,5 @@

How it runs

for each is dynamic fan-out: a planning step discovers the items, then the same template runs once per item.

Related

flowrun / then runpipeline
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/git.html b/docs/keywords/git.html index df1e3b7..01cd0fe 100644 --- a/docs/keywords/git.html +++ b/docs/keywords/git.html @@ -1,9 +1,22 @@ git: — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -47,5 +60,5 @@

How it runs

Three layers, each refining the one above. The protected-branch rule sits outside all of them: pushing to main/master is always refused.

Related

allow / ask me beforemodels:
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/goal.html b/docs/keywords/goal.html index e954a3a..fecc3fc 100644 --- a/docs/keywords/goal.html +++ b/docs/keywords/goal.html @@ -1,9 +1,22 @@ goal — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -30,5 +43,5 @@

Example

Related

done whenlook at
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/human-gates.html b/docs/keywords/human-gates.html index 4774359..b21b1b2 100644 --- a/docs/keywords/human-gates.html +++ b/docs/keywords/human-gates.html @@ -1,9 +1,22 @@ human gates — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -35,5 +48,5 @@

Example

Related

allow / ask me beforewhen … (transitions)stage
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/index.html b/docs/keywords/index.html index 687c741..d2fcff7 100644 --- a/docs/keywords/index.html +++ b/docs/keywords/index.html @@ -1,9 +1,22 @@ Keywords — LoopFlow reference + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab
-
LoopFlow / Keywords
+
LoopFlow / Keywords

Keywords

Every construct in the LoopFlow language — one page each, with syntax, what it does, examples, and a diagram where it helps.
-

Learning the language top-to-bottom? Read the tutorial. This is the by-keyword reference.

+

Learning the language top-to-bottom? Read the tutorial. This is the by-keyword reference.

Core syntax — the five decisionsThe engine. Objective, context, actions, verification, stopping — plus the cycle that drives them, and where a human steps in.
The five decisions
goalObjective — what "done" means, in plain language.look atContext — scope what the agent reads first.allow / ask me beforeActions — auto vs confirm.done whenVerification — how a loop proves itself.when … (transitions)Stopping — rules evaluated after each observe.after N tries (thrash guard)Stopping — stop & warn if it gets stuck.
@@ -37,5 +50,5 @@

Keywords

use skills:Named skills the loop may invoke.remember inCross-run memory across runs.alsoFinishing passes after the goal is met.plan fromRead the plan from a file you control.
Ops & reuse
git:Branch / commit / push strategy.models:Model tiering by phase.use the <X> methodImport a reusable preset.scheduleWhen to run.targetWhere the runner operates.notifyWhere to send completion.
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/look-at.html b/docs/keywords/look-at.html index e5e2895..efc310b 100644 --- a/docs/keywords/look-at.html +++ b/docs/keywords/look-at.html @@ -1,9 +1,22 @@ look at — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -30,5 +43,5 @@

Example

Related

goalallow / ask me before
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/loop.html b/docs/keywords/loop.html index 7ebb783..8811237 100644 --- a/docs/keywords/loop.html +++ b/docs/keywords/loop.html @@ -1,9 +1,22 @@ loop — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -46,5 +59,5 @@

How it runs

Every cycle runs plan → act → observe; the done when check decides — pass → stop, fail → reflect into the next plan.

Related

goaldone wheneach cyclepipeline
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/models.html b/docs/keywords/models.html index e396c37..409fd4a 100644 --- a/docs/keywords/models.html +++ b/docs/keywords/models.html @@ -1,9 +1,22 @@ models: — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -41,5 +54,5 @@

How it runs

Cheap model for the thinking phases, strong model for writing code. The end-of-run summary shows the call mix per tier.

Related

git:each cycleuse the <X> method
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/notify.html b/docs/keywords/notify.html index 876e376..bfc6a25 100644 --- a/docs/keywords/notify.html +++ b/docs/keywords/notify.html @@ -1,9 +1,22 @@ notify — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -31,5 +44,5 @@

Example

Related

scheduletarget
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/pipeline.html b/docs/keywords/pipeline.html index d26ed6d..c2dc47b 100644 --- a/docs/keywords/pipeline.html +++ b/docs/keywords/pipeline.html @@ -1,9 +1,22 @@ pipeline — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -46,5 +59,5 @@

How it runs

An epic → a pipeline, each story → a stage; stages run in order with their own checks and gates.

Related

stageflowloop
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/plan-from.html b/docs/keywords/plan-from.html index 664b3bd..848bc48 100644 --- a/docs/keywords/plan-from.html +++ b/docs/keywords/plan-from.html @@ -1,9 +1,22 @@ plan from — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -34,5 +47,5 @@

Example

Related

each cycleuse the <X> method
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/reflect.html b/docs/keywords/reflect.html index 5eb8f0f..fc49e9b 100644 --- a/docs/keywords/reflect.html +++ b/docs/keywords/reflect.html @@ -1,9 +1,22 @@ reflect — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -42,5 +55,5 @@

How it runs

Every cycle runs plan → act → observe; the done when check decides — pass → stop, fail → reflect into the next plan.

Related

when … (transitions)each cycle
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/remember-in.html b/docs/keywords/remember-in.html index 94f54d3..63e3b2e 100644 --- a/docs/keywords/remember-in.html +++ b/docs/keywords/remember-in.html @@ -1,9 +1,22 @@ remember in — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -35,5 +48,5 @@

Example

Related

reflectuse skillsgoal
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
diff --git a/docs/keywords/run.html b/docs/keywords/run.html index 992ca7c..0cb947e 100644 --- a/docs/keywords/run.html +++ b/docs/keywords/run.html @@ -1,9 +1,22 @@ run / then run — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -43,5 +56,5 @@

How it runs

A flow chains separate .loop files; after each, a short text summary carries into the next as context.

Related

flowfor each
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/schedule.html b/docs/keywords/schedule.html index ac9d1e2..793dd59 100644 --- a/docs/keywords/schedule.html +++ b/docs/keywords/schedule.html @@ -1,9 +1,22 @@ schedule — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -32,5 +45,5 @@

Example

Related

use the <X> methodtargetnotify
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/stage.html b/docs/keywords/stage.html index eadeece..312f567 100644 --- a/docs/keywords/stage.html +++ b/docs/keywords/stage.html @@ -1,9 +1,22 @@ stage — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -35,5 +48,5 @@

Example

Related

pipelineloophuman gates
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/target.html b/docs/keywords/target.html index 93b0912..6154535 100644 --- a/docs/keywords/target.html +++ b/docs/keywords/target.html @@ -1,9 +1,22 @@ target — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -31,5 +44,5 @@

Example

Related

scheduleuse the <X> method
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/use-method.html b/docs/keywords/use-method.html index fdb9e78..7adcc81 100644 --- a/docs/keywords/use-method.html +++ b/docs/keywords/use-method.html @@ -1,9 +1,22 @@ -use the <X> method — LoopFlow keyword +use the <X> method — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -32,5 +45,5 @@

Example

Related

pipelinescheduletarget
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/keywords/use-skills.html b/docs/keywords/use-skills.html index 6364777..280da5f 100644 --- a/docs/keywords/use-skills.html +++ b/docs/keywords/use-skills.html @@ -1,9 +1,22 @@ use skills — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -35,5 +48,5 @@

Example

Related

done whenremember inreflect
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
diff --git a/docs/keywords/when.html b/docs/keywords/when.html index 60fbe55..f582a10 100644 --- a/docs/keywords/when.html +++ b/docs/keywords/when.html @@ -1,9 +1,22 @@ when … (transitions) — LoopFlow keyword + + + + + + + + + + + + - + +
LoopFlow
- Tutorial + Tutorial Workshop Keywords 🎮 LoopFlow Lab @@ -46,5 +59,5 @@

How it runs

The order is the engine's, not yours: attempts is checked before fail, so the thrash guard always wins once you hit the limit.

Related

after N tries (thrash guard)reflect
-
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
+
LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
\ No newline at end of file diff --git a/docs/llms.txt b/docs/llms.txt new file mode 100644 index 0000000..34d2ac1 --- /dev/null +++ b/docs/llms.txt @@ -0,0 +1,37 @@ +# LoopFlow + +> LoopFlow is an open, natural-language DSL for **loop engineering**: you describe a +> self-correcting, human-gated AI coding workflow in plain English — its goal, the context +> it may read, the actions it may take, how it verifies itself (`done when`), and where a +> human steps in — then run it until the check is green. A `.loop` file turns "babysitting +> the agent" into a scoped, verifiable, repeatable loop. + +Use LoopFlow when a coding task is **repeatable and verifiable**: a bug fixed by a failing +test, a refactor gated by a check, an epic broken into stories, a migration with a +verification step. A loop plans, acts, observes its own `done when` check, reflects on +failure, and stops only when the goal is met or a thrash guard fires. + +Key concepts (each has a reference page under /keywords/): +- goal — what "done" means, in plain language +- done when — the predicate the loop uses to verify itself (a test, a command, a review skill) +- look at — the context the loop reads before acting +- each cycle — the repeated plan → act → observe steps +- reflect — turning a failure into context for the next plan (the back-edge) +- after N tries — the thrash guard that stops a stuck loop +- pipeline / stage — an epic as a sequence of gated stages +- flow / for each — chaining whole .loop files, or running a template per plan item +- human gates — where a person approves the plan, a stage, or the stop + +## Docs +- [Tutorial (home)](https://loopflow.live/): what LoopFlow is and why loops beat one-shot prompts +- [Playground](https://loopflow.live/playground.html): type a .loop, see its shape live in-browser +- [Workshop](https://loopflow.live/workshop.html): build a loop step by step +- [LoopFlow Lab](https://loopflow.live/game.html): learn loop engineering by playing +- [Keyword reference](https://loopflow.live/keywords/): every word in the DSL, one page each + +## Run it +- In Claude Code: the `/loopflow` skill authors and runs `.loop` files in-session. +- Headless: `loop-run run .loop`. + +## Source +- GitHub: https://github.com/tickets-forge-dev/loop-lang (grammar in AGENTS.md, manual in docs/MANUAL.md) diff --git a/docs/playground.html b/docs/playground.html index 51c9af0..736a620 100644 --- a/docs/playground.html +++ b/docs/playground.html @@ -11,8 +11,15 @@ + + + + + @@ -52,6 +59,7 @@ .hint{color:var(--muted);font-size:12.5px;margin-top:14px;border-top:1px solid var(--line);padding-top:12px} .hint code{font-family:var(--mono);color:var(--ink)} +
diff --git a/docs/robots.txt b/docs/robots.txt new file mode 100644 index 0000000..895dac2 --- /dev/null +++ b/docs/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: / + +Sitemap: https://loopflow.live/sitemap.xml diff --git a/docs/seo.memory.md b/docs/seo.memory.md new file mode 100644 index 0000000..79d8580 --- /dev/null +++ b/docs/seo.memory.md @@ -0,0 +1,28 @@ +# seo.loop — memory + +Cross-run lessons for the on-page SEO loop over the loopflow.live docs site. + +## 2026-07-05 — PASSED (2 cycles) + +- **Goal met:** all 30 docs pages have unique title + description, full OG + Twitter card, + self-referential absolute canonical, one `

`, and valid JSON-LD; `robots.txt`, + `sitemap.xml` (30 URLs), and `llms.txt` added. +- **Starting state:** only `index.html` + `playground.html` had OG/Twitter; nothing had a + canonical; keyword pages were title+desc only; `game.html` had no description and no `

`. +- **What worked:** the 26 keyword pages are structurally uniform, so a Python script + (`scratchpad/inject_seo.py`) injected canonical/OG/Twitter/BreadcrumbList by reusing each + page's own `` + description — far faster than 26 hand edits. Keep this pattern for + any future bulk head-tag change. +- **Gotchas found by the audit:** + - `keywords/use-method.html` had an unescaped `<X>` inside `<title>` (invalid HTML, broke + title parsing). Escaped to `<X>`. Check new keyword pages whose name contains `<…>`. + - Keyword pages linked nav + footer to a non-existent `../tutorial.html` (the homepage is + `index.html`, which top-level pages already link as "Tutorial"). Repointed to + `../index.html`. If a `tutorial.html` is ever added at deploy, revisit. + - `game.html` is a JS game with no natural `<h1>`; added a visually-hidden keyword-rich + `<h1>` after `<body>` rather than disturbing the game UI. +- **Still open (bigger levers, out of this loop's scope):** keyword pages are thin + (one-sentence bodies) — expanding them into real reference content is the biggest ranking + lever. Per-page OG images would lift share CTR. Both are good candidates for their own loop. +- **Next run:** re-audit after any new pages; the script is idempotent (skips pages that + already have a canonical), so re-running is safe. diff --git a/docs/sitemap.xml b/docs/sitemap.xml new file mode 100644 index 0000000..54fcd80 --- /dev/null +++ b/docs/sitemap.xml @@ -0,0 +1,33 @@ +<?xml version="1.0" encoding="UTF-8"?> +<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> + <url><loc>https://loopflow.live/game.html</loc></url> + <url><loc>https://loopflow.live/</loc></url> + <url><loc>https://loopflow.live/playground.html</loc></url> + <url><loc>https://loopflow.live/workshop.html</loc></url> + <url><loc>https://loopflow.live/keywords/after-n-tries.html</loc></url> + <url><loc>https://loopflow.live/keywords/allow.html</loc></url> + <url><loc>https://loopflow.live/keywords/also.html</loc></url> + <url><loc>https://loopflow.live/keywords/done-when.html</loc></url> + <url><loc>https://loopflow.live/keywords/each-cycle.html</loc></url> + <url><loc>https://loopflow.live/keywords/flow.html</loc></url> + <url><loc>https://loopflow.live/keywords/for-each.html</loc></url> + <url><loc>https://loopflow.live/keywords/git.html</loc></url> + <url><loc>https://loopflow.live/keywords/goal.html</loc></url> + <url><loc>https://loopflow.live/keywords/human-gates.html</loc></url> + <url><loc>https://loopflow.live/keywords/</loc></url> + <url><loc>https://loopflow.live/keywords/look-at.html</loc></url> + <url><loc>https://loopflow.live/keywords/loop.html</loc></url> + <url><loc>https://loopflow.live/keywords/models.html</loc></url> + <url><loc>https://loopflow.live/keywords/notify.html</loc></url> + <url><loc>https://loopflow.live/keywords/pipeline.html</loc></url> + <url><loc>https://loopflow.live/keywords/plan-from.html</loc></url> + <url><loc>https://loopflow.live/keywords/reflect.html</loc></url> + <url><loc>https://loopflow.live/keywords/remember-in.html</loc></url> + <url><loc>https://loopflow.live/keywords/run.html</loc></url> + <url><loc>https://loopflow.live/keywords/schedule.html</loc></url> + <url><loc>https://loopflow.live/keywords/stage.html</loc></url> + <url><loc>https://loopflow.live/keywords/target.html</loc></url> + <url><loc>https://loopflow.live/keywords/use-method.html</loc></url> + <url><loc>https://loopflow.live/keywords/use-skills.html</loc></url> + <url><loc>https://loopflow.live/keywords/when.html</loc></url> +</urlset> diff --git a/docs/tools/check_content.py b/docs/tools/check_content.py new file mode 100644 index 0000000..cec3f1a --- /dev/null +++ b/docs/tools/check_content.py @@ -0,0 +1,57 @@ +#!/usr/bin/env python3 +"""Content-depth gate for the loopflow.live keyword reference pages. + +A keyword page is a real reference (not a stub) when its <main> has enough prose, +more than one worked example, a pitfalls/gotchas section, and related links. This +script is the `done when` check for the keyword-content loop: it prints every page +that falls short and exits non-zero, so the loop keeps working until all pass. + +Usage: python3 docs/tools/check_content.py +Exit 0 = every keyword page clears the bar (loop may stop). +Exit 1 = at least one page is still thin (offenders printed). +""" +import glob, os, re, sys + +DOCS = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + +MIN_WORDS = 220 # substantial prose, not a one-liner +MIN_EXAMPLES = 2 # more than a single snippet +PITFALL_RE = re.compile(r"pitfall|common mistake|gotcha|when not|watch out|avoid", re.I) + +def main_html(src): + m = re.search(r"<main>(.*?)</main>", src, re.S) + return m.group(1) if m else src + +def check(path): + src = open(path, encoding="utf-8").read() + body = main_html(src) + words = len(re.sub(r"\s+", " ", re.sub(r"<[^>]+>", " ", body)).split()) + examples = len(re.findall(r"<pre", body)) + headings = " ".join(re.findall(r"<h2[^>]*>(.*?)</h2>", body, re.S)) + has_pitfalls = bool(PITFALL_RE.search(re.sub(r"<[^>]+>", " ", headings))) + has_related = 'class="related"' in body or "Related" in headings + fails = [] + if words < MIN_WORDS: fails.append(f"words {words}<{MIN_WORDS}") + if examples < MIN_EXAMPLES: fails.append(f"examples {examples}<{MIN_EXAMPLES}") + if not has_pitfalls: fails.append("no pitfalls/gotchas section") + if not has_related: fails.append("no Related links") + return fails + +def main(): + pages = sorted(p for p in glob.glob(os.path.join(DOCS, "keywords", "*.html")) + if not p.endswith("index.html")) + offenders = [] + for p in pages: + fails = check(p) + if fails: + offenders.append((os.path.relpath(p, DOCS), fails)) + if offenders: + print(f"{len(offenders)}/{len(pages)} keyword pages below the content bar:\n") + for name, fails in offenders: + print(f" {name}: {', '.join(fails)}") + sys.exit(1) + print(f"All {len(pages)} keyword pages clear the content bar " + f"(>= {MIN_WORDS} words, >= {MIN_EXAMPLES} examples, pitfalls + related).") + +if __name__ == "__main__": + main() diff --git a/docs/workshop.html b/docs/workshop.html index 984dc0a..df85c2d 100644 --- a/docs/workshop.html +++ b/docs/workshop.html @@ -5,6 +5,18 @@ <link rel="icon" type="image/svg+xml" href="/gyro-icon.svg" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>LoopFlow — the workshop + + + + + + + + + + + + @@ -110,6 +122,7 @@ .topbar{flex-wrap:wrap; gap:8px;} } + diff --git a/seo-content.loop b/seo-content.loop new file mode 100644 index 0000000..052fd82 --- /dev/null +++ b/seo-content.loop @@ -0,0 +1,33 @@ +# seo-content.loop — turn the thin keyword reference pages into real, rankable docs. +# The biggest SEO lever left: search engines rank depth, and every keyword page is +# currently a stub (median ~150 words, no "common mistakes" section, one example). +# The loop expands them until the content-depth checker passes AND a human signs off +# on quality — the checker stops it going green while thin; the human stops it padding. + +loop "seo: expand keyword reference pages": + # ── Contract ────────────────────────────────────────────────────────────────── + goal: every keyword page under docs/keywords/ is a substantial, genuinely useful + reference — a clear explanation of what the keyword does AND why it matters, + at least two worked examples, a "Common mistakes" section, and related links — + accurate to the real grammar, never padded filler. + + done when "python3 docs/tools/check_content.py" passes + + # ── Boundaries ──────────────────────────────────────────────────────────────── + look at: docs/keywords/, docs/keywords/style.css, and the last failure + knowledge: AGENTS.md, docs/MANUAL.md # the grammar — read-only source of truth; never edit + examples: templates/, examples/ # real .loop patterns to draw accurate examples from + + allow edits automatically, but ask me before changing page structure or navigation + use skills: seo-audit # keep title/description/OG correct as bodies grow + + # ── Engine ──────────────────────────────────────────────────────────────────── + each cycle: plan, then act, then observe # each pass: expand the thinnest pages, re-check + + remember in "docs/keywords-content.memory.md" + + # ── Safety net ──────────────────────────────────────────────────────────────── + when it fails: reflect on which pages and which checks still fail, then plan again + when blocked: ask a human + a human reviews before stopping # quality gate — no word-count padding + after 10 tries: stop and warn "content still thin — expand the worst pages by hand" diff --git a/seo.loop b/seo.loop new file mode 100644 index 0000000..80cd884 --- /dev/null +++ b/seo.loop @@ -0,0 +1,32 @@ +# seo.loop — self-correcting on-page SEO for the loopflow.live docs site. +# Runs the seo-audit skill to both DO the work and CHECK it: audit → fix → re-audit, +# looping until the audit finds no Critical issues on any page. + +loop "seo: loopflow.live docs": + # ── Contract: the finish line, and how it's verified ────────────────────────── + goal: every public page under docs/ has complete, unique on-page SEO — a unique + and meta description, a full Open Graph + Twitter card with an + absolute og:image, a self-referential canonical URL, exactly one <h1>, + alt text on meaningful images, and valid JSON-LD. + + done when the skill "seo-audit" approves + the bar: zero Critical issues on any audited page; every og:image / og:url / + canonical is an absolute https URL; titles and meta descriptions are + unique per page (no duplicates across the site). + + # ── Boundaries: what it may read, and how much power it has ─────────────────── + look at: docs/index.html, docs/game.html, docs/playground.html, + docs/workshop.html, docs/keywords/, and the last failure + allow edits automatically, but ask me before changing visible page copy or headings + + use skills: seo-audit + remember in "docs/seo.memory.md" + + # ── Engine: the repeated cycle ──────────────────────────────────────────────── + each cycle: plan, then act, then observe + + # ── Safety net: back-edge, escape hatch, hard stop ──────────────────────────── + when it fails: reflect on which pages and which tags still fail, then plan again + when blocked: ask a human + a human reviews before stopping + after 8 tries: stop and warn "SEO still failing after 8 passes — narrow look at: to the worst pages"