Visual — human-first markdown digest

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.)

Rich HTML render lenses are a different register and stay where they are (artifacts.html.enabled); this skill never produces or replaces them.

Preamble

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

FLOWCTL="${CODEX_HOME:-$HOME/.codex}/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-189-human-first-visual-digest-skill) → spec digest
• Task id (fn-189-human-first-visual-digest-skill.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.