Flow Next Visual

Visual — human-first markdown digest

Restate one thing visually, in compact markdown, on one screen. The structure IS the output: the reader scans the shape, spots the wrong thing, and drills into only that file instead of reading everything to find out whether anything is wrong.

Output contract: compact markdown visuals rendered in chat — fenced text/diff/code blocks and tiny tables. Never images, never HTML files, never a written artifact. Everything here renders natively in the terminal, in chat, and on every forge: diff fences color for free, text is monospace everywhere, ```ts gets highlighting for free. There is no rendering machinery — the shapes below are the whole product.

Read-only. This skill reads state and responds. It never writes files, never mutates flow state, never commits, never runs a workflow. (If the user asks to save a digest, that is an ordinary Write with ordinary consent — not a mode of this skill.)

Preamble

flowctl is bundled with the plugin (not on PATH). Define once; subsequent blocks use $FLOWCTL:

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"

Input

Arguments: $ARGUMENTS — optional. One of:

• Spec id (fn-12-add-oauth) → spec digest
• Task id (fn-12-add-oauth.1) → task digest
• Git range (main..HEAD, abc123..def456, or the bare word diff) → diff digest
• Nothing, or free-form text → ad-hoc restate of the current topic (or of the text pointed at)

Digest modes

Spec digest (post-plan) — the primary mode

Read $FLOWCTL show <spec-id> --json, the spec markdown ($FLOWCTL cat <spec-id>), and every task file ($FLOWCTL cat <task-id>). Emit these six elements, in order, on one screen:

1. Thesis — 1-2 sentences: what ships and why.
2. Task tree — indented text tree in dependency order, parallel groups adjacent; one line per task: id, short title, the one thing it produces.
3. Planned file-layout diff — shallow tree with + (new) / ~ (changed) per file or dir, one-line responsibility, owning task id annotated, so the reviewer sees where the change lands and who owns it.
4. Shape sketch — the new/changed types, signatures, config keys, or command surfaces the tasks will create (shape 6), when the plan implies any. Skip when it implies none.
5. R-ID coverage line — one compact line or tiny table from the tasks' declared satisfies arrays, which live in each task file's frontmatter ($FLOWCTL cat <task-id>), not in show --json: R1 -> t1 · R2 -> t2,t3 · R5 -> UNCOVERED. Uncovered and undeclared jump out instead of needing cross-referencing.
6. Boundaries — IS / IS-NOT, one line each side.

Spec digest (pre-plan)

No tasks yet: thesis, proposed shape, edge cases as one-liners, boundaries. No task tree, no coverage line — there is nothing to derive them from, and inventing them is the failure mode this mode exists to avoid.

Task digest

One task: what it produces (shape sketch or file-layout diff), its position in the dependency tree, and its acceptance restated as 1-3 predicates.

Diff digest

Input is a git range; on a branch with no range given, default to the merge base with the default branch (git merge-base origin/HEAD HEAD or the repo's default branch). Emit a file-layout diff with paths from git diff --name-status (rename-aware path identity — --stat prints {old => new} presentation labels, not paths) and churn from git diff --stat, plus a call-tree or component-tree sketch of the load-bearing structural change — when the diff carries one. A docs/config-only range with no real call or component relationship gets the grounded file-layout diff alone; never invent structure to satisfy the shape. For orienting a reader before they read the real diff. Empty range: say so in one line and stop — never fabricate a sketch.

Ad-hoc restate

No flow id: restate the current conversation topic, or the text the user points at, using the vocabulary. This is the "too much text — show me" mode and the natural-language entry point. Needs no flowctl and no git.

Grounding (hallucination guardrails)

• Every path in a file tree comes from a task file, the spec, or git diff --name-status — never invented. (--stat is for churn numbers only; its rename labels {old => new} are presentation strings, not paths.)
• Every edge in a call tree traces to real code read in this session or to a real task dependency. In ad-hoc mode, paths and relationships explicitly present in the supplied topic text also count as grounded — restating them is the job; adding ones the text does not support is not.
• Coverage lines come from the tasks' declared satisfies frontmatter (read with $FLOWCTL cat <task-id>) checked against the spec's R-IDs, not from re-narrated prose.
• No embellishment nodes "for clarity". When in doubt: fewer nodes, more honest.
• Nothing readable → say what was unreadable in one line, digest what is readable. A digest that quietly invents the missing half is worse than a short one.