/reimagine-it

Banks: references/notes.md · references/forms.md · references/webpage-craft.md (only for the webpage form) · references/craft-floor.md (the interaction contract every webpage output must clear; read every run) · references/review.md (§5.d named-object accuracy + clone scan; load on every verify) · references/forms/ (non-webpage form packs: pdf, document, slides, universal) · references/domains/ (only when the user gave a domain token: artistic / dashboard / photography / cinematic (aka 3d, webgl) / ecommerce / landing / portfolio / infographic) · references/modifiers/ (only when the user gave a modifier: glassmorphism / bento / neon / brutalism / neumorphism / handdrawn) · references/locks/ (loaded on --ref <name>) · references/research/web-craft-2025.md (deep source pack — Awwwards SOTY stack scan, Rauno/Emil craft floor, Lupi/Fragapane data humanism, Feixen/Weingart/Troxler print grammar, Apple AIDA cinematic, view-transitions, scroll-driven animations, kinetic type, sound, neubrutalism — read once, cite in reports) · references/research/infographic-craft.md (15-source infographic pack — Cleveland–McGill, Tufte, Bertin, ISOTYPE, Minard/Snow, Cairo, Lupi, FT Visual Vocabulary, USWDS, WCAG charts, InfoAlign layouts — load when the form or domain is infographic) · examples.md

/reimagine-it is a Content-Derived Design engine. The shipped product reads HTML and writes HTML: extract the headings, facts, names, dates, numbers, links, emails, and colors already in the file, then generate a standalone page in one of 17 tokens (or --auto). Default output is offline.

Do not claim the CLI redesigns PDF, PPTX, DOCX, MOBI, or “any file.” If the user pointed at another format, convert or wrap it as HTML first, run the engine, and only then — if they asked and the toolchain exists — export with a host tool. Report that extra step as host conversion, not as an engine feature.

If local.md exists beside this file, Read it after this skill (host chairs, org, paths). Public installs have no local.md.

Say once: "Running /reimagine-it."

Engine — run the CLI; do not invent the page

The shipped product is the CLI. /reimagine-it is orchestration around it, not a license to hand-author HTML.

1. If the source is not HTML, wrap or extract it into HTML first. Do not claim the engine ingested PDF, PPTX, or DOCX.
2. Run the matching command and use the file it writes:

npx reimagine-it --auto -i page.html -o redesign.html
npx reimagine-it -i page.html -t infographic -o poster.html
npx reimagine-it variations -i page.html -n 3 -o review/
npx reimagine-it extract -i page.html
npx reimagine-it audit redesign.html

The CLI enforces the source guard mechanically: an --output path that resolves to the source file exits 2 without writing. Pass --no-clobber to also refuse replacing an existing output file — useful when an agent or CI loop must not clobber a reviewed artifact. Auto mode also holds an advisory run lock next to the artifact, so a second agent targeting the same output fails fast instead of interleaving writes; crashed runs self-heal via stale-lock detection, and --force overrides.

3. Open that artifact. Report from it. If npx reimagine-it cannot run, ship REIMAGINED: partial and name the exact blocker — do not substitute a model-written page.

Categories (you choose · agent decides)

Optional tokens. Combine freely. You pick tokens; the agent picks questions, form (if unset), mutations, and the stretch.

Category	You choose	Agent decides
(none)	Default. No interview.	Infer, lock, form, build.
Auto — auto / --auto	Let the tool manage the normal redesign loop.	Extract evidence → rank coherent forms → generate candidates → verify → return the strongest artifact. Source stays read-only.
interview	Talk before build.	Which questions, recommended answers, when to stop.
Form family — code cli protocol demo prose product architecture experiment	Force that form family.	How the notes land in it.
Visual form — svg 3js infographic canvas html webpage simulation	Force a visual form.	Craft inside that medium. Token infographic also loads references/domains/infographic.md (poster of an argument, not a dashboard). Token svg / 3js ship alive-micro by default (2–4 fact-tied loops that beautify; brief still freezes). Token simulation ships a playable model of facts already in this source — default paused on the first fact; nested short spans are inspectable; type in the gutter. None of these are a Texas skin; leftover words are a lens.
Host conversion (not CLI tokens) — pdf document slides	Only if the user asked and local tools exist.	Convert/wrap as HTML → run the engine → optional export (Weasyprint, python-docx, python-pptx). The CLI does not read or write these formats.
Domain aesthetic — second word after webpage: artistic dashboard photography cinematic (3d, webgl) ecommerce landing portfolio infographic	Force a webpage aesthetic.	Load references/domains/.md and extend the webpage-craft spine. cinematic upgrades the 3D floor to inline WebGL2. infographic is a statistical poster (common-scale encodings + ISOTYPE + data table) — not an ops dashboard.
Modifier — third word or --style <name>: glassmorphism bento neon brutalism neumorphism handdrawn	Layer a UI/UX modifier on top of the domain.	Load references/modifiers/.md; modifiers waive matching cut-list entries and add their own non-negotiables.
Font override — --font "Family, Fallback, generic"	Pin the display / body font family.	Build a full font stack; degrade gracefully when the family is not on the reader's box. Never fetch a webfont at run time unless you also pass --allow-fetch.
Sound — --sound [tier] (ambient / feedback / full, default feedback)	Turn on sound design for this run. Off by default.	Load Howler.js sprite pack; enforce earcon tier hierarchy (§ craft-floor #7); ship visible mute + volume controls; never autoplay; provide visual alternative for every cue. Downgrades to partial if any of those are missing.
Lock / reuse — lock <path> [as <name>] · --ref <name> · --list-refs	Capture a shipped output as a reusable reference, or apply one.	Extract palette + type stack + motifs + motion + 3D signatures into references/locks/.md; on --ref, load that pack as if it were a domain.
--notes	Show the four notes.	Which four.
--plan-only	No files.	Lock + notes + form + stretch.
--full	Extra plus-pass after the hero.	One mutation that serves the idea, then ship.
--variants N	Ask for N distinct outputs from the same brief instead of one.	Pick N distinct make-strange moves; write to .../var-1/, .../var-2/, ...
--seed <n>	Pin the creative variation sample so two runs produce the same draw. Default is fresh every run.	Use the seed to deterministically pick one option per variation axis.
--variant a|b|c|...	Shorthand for a named seed (a = first canonical draw, b = second, …).	Reproduce a specific shipped draw; useful for locks (--variant b --lock).
<brief>	Any leftover words after known tokens. Open vocabulary — not a theme catalog.	Treat as a creative lens on register, ground, motif, pattern, type, motion. Still sniff context; brief does not replace source facts.
Audit — audit	Run deterministic quality checks on an HTML file.	Runs npx reimagine-it audit — 19 checks (src/audit.js) across typography, palette, motion, content, structure, and performance with no LLM and no API key. Python scripts/audit.py is the CI mirror. Zero failures must pass. Supports --verbose and --json.

Combine freely. Known form / domain / modifier tokens load packs. Every other word is kept and followed. There is no list of allowed leftover words.

/reimagine-it auto
/reimagine-it webpage cinematic

/reimagine-it webpage infographic
/reimagine-it infographic
/reimagine-it infographic <any leftover words>
/reimagine-it svg
/reimagine-it audit
/reimagine-it 3js
/reimagine-it simulation
/reimagine-it webpage artistic glassmorphism --font "Playfair Display, serif"
/reimagine-it lock gold/domains/cinematic/after.html as house-cinema
/reimagine-it webpage --ref house-cinema
/reimagine-it webpage bento --variants 3

Interview is off unless they picked interview. Do not grill unprompted. Do not ask "what style do you want?" — not even in interview.

Every mode must ship an artifact (unless --plan-only). A list of vibes is not the deliverable.

Hard contract

1. Read this file. Load references/notes.md and references/forms.md.
2. Sniff context. Interview only if interview was chosen.
3. Name the adjacent possible: spare parts already here + one combination they did not request.
4. Pick four notes in private (device · leap · craft · effect). Answer with mutations, not mood words.
5. Route a hero form. Run the CLI into that form (-t or --auto). Do not hand-author a replacement page.
6. Name one stretch they did not know was in bounds. Build it if cheap; otherwise give the exact next command.
7. Kill list in notes.md. No "wow". No prompt-slop. No TED-over-B-roll.
8. Paid gate: code, SVG, HTML, PDF, docx, pptx, local demos are free. Ask before billed image/video/model APIs.
9. No commit/push unless asked.
10. Report REIMAGINED: shipped | partial | blocked.

Procedure

REIMAGINED Progress:
- [ ] 0. Mode + categories parsed (leftover words kept as brief) + context sniffed
- [ ] 0.5. Interview only if that category was chosen
- [ ] 0.75. Adjacent possible named (private)
- [ ] 0.85. Anchor list — extract 3–5 concrete nouns/proper nouns/dates/verbs from the source; every plate must map back
- [ ] 1. Four notes chosen (private)
- [ ] 2. Hero form routed (unless user forced one)
- [ ] 2.4. Variation sample picked (avoid previous draw; pin if --seed / --variant)
- [ ] 2.5. Modifiers / font override / --ref loaded if present
- [ ] 2.6. Output is standalone HTML (host conversion only if the user asked and the toolchain exists)
- [ ] 2.7. Craft floor loaded (references/craft-floor.md) — every rule enforceable before render
- [ ] 3. Hero artifact written (or N variants if --variants)
- [ ] 4. Stretch named (and built if cheap)
- [ ] 4.5. --full plus-pass if requested
- [ ] 5. Verify with evidence (functional + visual + craft-floor scan)
- [ ] 6. Report REIMAGINED: shipped | partial | blocked

Auto mode — the automatic design loop

auto is the person-like invocation: the user gives context, not a pile of commands. Infer the best form from the source, generate up to three coherent candidate directions, run the craft-floor checks, and return the strongest standalone artifact plus the selected token, seed, evidence, and rejected candidates. Never overwrite the source. Never invent facts. If a host can render previews, show the selected artifact and make the alternatives available for comparison.

Auto is deliberately model-agnostic. An agent host may use the returned plan as structured context, delegate visual review to a subagent, or supply a model-specific renderer. The core engine remains deterministic and safe without an API key. --auto is an explicit CLI equivalent; plain /reimagine-it remains the full inferred workflow.

0. Token parse (open brief — do not drop words)

This skill is a creative engine. The user may type anything after /reimagine-it. Do not require a matching pack. Do not autocorrect unknown words into a listed domain. Do not ask "what style do you want?"

1. Split on whitespace. Consume flags and their arguments (--seed, --style, --font, --ref, --variants, --sound, --notes, --plan-only, --full, --variant, --allow-fetch, --ask-format, --list-refs). Handle lock … as … as its own command.
2. Classify remaining words that exactly match a known form, domain (incl. 3d / webgl), or modifier.
3. Join every leftover word, in order, as the brief. Empty brief is allowed. Multi-word briefs are the point.
4. A known modifier still loads its pack (neon, handdrawn, …). Leftover words around it stay in the brief.

The brief is a lens, not new content and not a closed theme list. Apply it to ground, motif, pattern, type, and motion. Source facts stay source facts. Log it on the report Brief: line (or none).

0. Context sniff (do not skip)

In parallel, cheaply:

• Workspace root, README, GOAL.md if present (read; do not overwrite)
• git status -sb if a repo
• Open / recently viewed files if known
• User text after the slash
• Domain files the repo already points at (CONTRIBUTING, protocol docs, failing tests)
• The target file if the user pointed at one (prefer .html; if they pointed at PDF/PPTX/DOCX, wrap or extract into HTML before calling the engine)

One-sentence lock: what this is, what happens to them.

If context is empty (blank chat, empty folder) and no interview: still ship. Invent from the folder name and any README. Do not stall for a brief.

0.5 Interview category (skip unless chosen)

Only when they passed interview. You choose the category; the agent decides the questions.

• After the sniff, ask only what context cannot answer.
• One question at a time. Wait. Multiple questions at once is bewildering.
• Each question includes a recommended answer. They can take it, replace it, or say just go to skip the rest and build.
• Questions come from the note bank (device / leap / craft / effect) — not "what style" or "any preferences?"
• If the codebase can answer, Read/Grep instead of asking.
• Cap 4 questions, then build. Do not leave the session in interview forever.

0.75 Adjacent possible (private)

From the parts already in this repo or thread, name one unused combination. That is the leap candidate. Do not dump a mood board.

Pick one SCAMPER letter as the mutation (Substitute, Combine, Adapt, Modify, Put to another use, Eliminate, Reverse). Do not run all seven in chat.

0.85 Anchor list (private, but every plate must map to one)

From the source, extract 3–5 concrete anchors: proper nouns (people, places, brands), dates, numbers, verbs of action, physical objects, quoted phrases. These are the units of content the design must serve.

Every plate, tile, section, chart, or hero unit in the output must map back to at least one anchor. If it does not, delete it — do not paint a placeholder tile with the word blank, sample, or an alt-text stand-in (see must-not).

Record the anchor → plate mapping privately (or in the local ledger). Cite it on the report Anchors: line so the user sees the design isn't drifting from the source.

Example — Texas notebook source: anchors = {Jordan Rivers, Big Bend, 1836, Post Office, west Texas sunset}. Draw C's shader-hero → sunset; letterpress-card #01 → 1836; map plate → Big Bend; caption → Rivers; kicker → Post Office. Every unit serves an anchor.

1. Four notes (private)

From references/notes.md: one Device, one Leap (vastness + accommodation, moral beauty, big ideas, small self), one Craft, one Effect. Mutations name a cut, plate, magnet, withheld title, first-run beat, API shape, or demo — not "cinematic."

Do not dump the bank in chat.

2. Form router

Follow references/forms.md unless a category forced the family.

Webpage / HTML / infographic → load references/webpage-craft.md before writing the file. If the user added a domain (second word), also load the matching pack in references/domains/. Token infographic — as a visual form or as a domain — always loads references/domains/infographic.md and references/research/infographic-craft.md. Lock structure (list / sequence / hierarchy / compare / values / relation) from this source before drawing marks. If they added a modifier (third word or --style), also load the matching pack in references/modifiers/. Leftover words are the brief (step 0) — follow them; do not require a pack file. If they passed --ref <name>, load references/locks/.md instead of (or in addition to) a domain — treat locks as domain packs.

SVG → load references/forms/svg.md. Marks in the field, type in the gutter. No label on a path. Alive-micro default: 2–4 loops on marks (weenie-breathe + one fact-loop + hover pairing). Brief still / no-motion / print freezes loops. Leftover words are a lens. Do not clone the Texas gold weenie onto a different source.

3js → load references/forms/3js.md. Reserved HUD strip. Silhouettes from this source. Not a primitive demo. Alive-micro default: idle life on 2–3 meshes (weenie-turn, flow along a source curve, sun-breath) plus camera ease / wide-drift. Brief still pins the camera and freezes meshes. Leftover words are a lens. Do not clone the Texas gold room onto a different source.

simulation → load references/forms/simulation.md. Playable model of this source's sequence (years, days, handshake steps — whatever it times with). Type in the gutter. Marks on the field. Nested short spans are inspectable. Default paused on the first fact. Leftover words are a lens. Do not clone the Texas 1836–1995 clock onto a different source.

PDF / document / slides → host conversion only. Prefer: extract or wrap as HTML, run npx reimagine-it, ship HTML. Load references/forms/ only if the user explicitly asked for that format and Weasyprint / python-docx / python-pptx (etc.) is on the machine. Do not present those packs as CLI tokens.

Any webpage output — with or without a domain / modifier / lock — must land hero-scale inline SVG doing real work, three moving elements at any moment, and 3D that reads in a still (rotation ≥ 12° + shadow blur ≥ 24px, or translateZ ≥ 30px + real shadow, or inline WebGL2). If a screenshot cannot prove all three, the redesign did not earn the form. Exception — infographic: the poster stays orthographic (paper drop-shadow only; no rotateX on the board).

Non-HTML export — optional, never the default claim. If the user asked for PDF/PPTX/DOCX and the toolchain exists, follow the matching form pack. Otherwise ship HTML and name the missing tool.

Form follows the leap:

• Capability in this codebase → implement here (plus a tiny proof: test, CLI, fail-demo).
• Seeing-tool (infographic, weenie, canvas, explainer HTML, one-shot deck/PDF) → <workspace>/reimagined/<yyyy-mm-dd>-<slug>/.
• Never hide a product feature inside reimagined/ as a souvenir.

2.4 Creative variation (never repeat)

/reimagine-it must not return the same output twice for the same source unless the caller pinned a seed with --seed <n> (or picked a named --variant). Every fresh run samples a new combination along the axes below so the same brief produces a real range of draws instead of one canned "official" answer: