Visual Aids

Flow-Next 2.0.0 adds an opt-in HTML artifact mode: when activated, the lifecycle skills also emit beautifully rendered, self-contained HTML pages — render lenses — alongside their markdown output. This page covers the spec lens, the business- and plan-review surface. The PR-side counterpart is the PR review instrument.

Click to zoom

The spec lens for the feature that shipped it (fn-62) — masthead, at-a-glance dials, serif thesis. Generated by a fresh agent session from the disclosure reference alone. Click to zoom.

Render lens, never record

Markdown (and tracker-sync) stays 100% the source of truth. Every HTML output is an additional regenerable artifact — never parsed back as state, always re-derivable from the spec. OFF by default: markdown-only users see zero new steps, zero token overhead, zero behavior change.

Activation

One config key, written by the /flow-next:setup ceremony or set directly:

flowctl config get artifacts.html.enabled --json    # default: false
flowctl config set artifacts.html.enabled true
flowctl config set artifacts.html.enabled false     # turn off again

With the mode off or unset, participating skills load no reference file, write no artifacts, open no Lavish sessions, and add no output — the single config read is the only addition. Setup asks once (only when the key is unset): enable or not, then — on yes — commit-vs-gitignore for .flow/artifacts/ and an optional lavish-axi install offer (never auto-installed).

Generation is agentic, not deterministic: when the mode is active, the skills load one shared disclosure reference carrying all generation rules and an explicit anti-slop design contract (own warm-black instrument-panel house style, local-only font stacks, no CDN fonts, no purple gradients), and the host agent writes the HTML. There is no Python renderer and no new slash command.

One pathway, state-dependent rendering

The spec artifact lives at a fixed, deterministic path — .flow/artifacts/<spec-id>/spec.html, never timestamped — and regenerates at its lifecycle touchpoints. What renders depends on what state exists, not on a config axis:

Lifecycle touchpoint	What renders
/flow-next:capture — fresh spec, no tasks yet	Spec-only view: thesis, acceptance criteria with source-tag provenance chips, architecture panel, edge cases, boundaries, decision context — the business-review surface
/flow-next:plan — tasks now exist	Same file, same path, regenerated with the plan layer: task dependency DAG with critical path, R-ID → task coverage matrix

The plan layer makes the lens a plan-review aid too: a tech lead reads the task graph and coverage matrix as one page instead of walking task files. Generation runs only after plan’s refinement loop exits — the lens never renders a task graph you are still editing.

Click to zoom

The post-plan layer: the task DAG laid out by dependency depth, edges measured from the DOM at load (never hand-typed coordinates), critical path in amber, live task-status chips. Click to zoom.

After writing, the skill updates a single artifact link line in the spec markdown (marked <!-- flow-next:artifact-link -->), replaced in place on every regeneration — repeated capture/plan runs never duplicate it. Every artifact footer carries a staleness stamp (spec updated_at + repo commit at render time) so a reader can tell when the lens lags the markdown. Generation failure is non-fatal everywhere: the markdown is already on disk and is the record.

Self-contained or nothing

Every lens is a single HTML file — inline CSS/JS, zero external requests, fonts included, print-friendly. It opens identically from file://, inside Lavish, in a CI archive, and on paper.

GitHub renders committed .html as raw source and rejects .html PR attachments, so the markdown links carry local-open guidance:

open .flow/artifacts/<spec-id>/spec.html    # macOS; xdg-open on Linux

Artifacts are committed by default (that is what makes the PR lens’s blob links resolve for remote reviewers); the setup ceremony offers gitignoring .flow/artifacts/ instead for clean history — the skills probe ignore status and never emit a link that 404s.

Annotate in the browser — Lavish (optional)

lavish-axi (npm) is an optional companion: it serves the spec artifact in a browser session where humans annotate, and annotations flow back to the agent as edits of the markdown source of truth, followed by lens regeneration. Detected on PATH, never required — absent means a plain static artifact, never an error, never an auto-install.

npm i -g lavish-axi          # or zero-setup per run: npx lavish-axi <artifact.html>
lavish-axi .flow/artifacts/<spec-id>/spec.html

The feedback loop is pull-only and session-spanning: annotations queue in the global ~/.lavish-axi/state.json and survive agent death — annotate tonight, and any later agent session drains the queue via lavish-axi poll, mapping each annotation to a spec edit and regenerating the lens. The local server idle-stops after ~30 minutes; the artifact still renders as a plain static page, and re-running lavish-axi <file> resumes the session.

The annotate loop applies to spec artifacts only — the PR lens never enters it, and autonomous loops never poll (see Going Autonomous).

Regenerating

There is no regeneration command. Auto-regen rides the lifecycle touchpoints (capture, plan, make-pr); everything else is conversational — after hand edits, an interview pass, or drained annotations, just ask the agent:

“regenerate the artifact for fn-12”

It reloads the disclosure reference, re-reads the spec + flowctl state, and regenerates at the same fixed path.