seeflow-lookup

name

seeflow-lookup

description

This skill should be used before `/seeflow` whenever the user phrases the request as inspection rather than creation — "show me", "show the", "how does X work", "what does X do", "diagram our system", "explain the flow", "where does X live", "what handles Y", "what depends on Z", or names a flow by slug/title without an explicit "create / scaffold / generate / add" verb. Also use when onboarding to a repo that already has seeflow flows registered. Read-only — never mutates flows; auto-hands off to `/seeflow` only when no matching flow is registered.

seeflow-lookup

Look up registered SeeFlow flows and consult them as architectural ground truth. Read-only counterpart to /seeflow — that skill creates and edits flows; this one queries them while writing code or making decisions.

Routing gate — run before deciding

Inspection phrasing always lands here first, even when no flow is yet registered — the auto-handoff below covers the empty case. The trigger words are: show me, show the, how does, how do, what does, what handles, where does, where is, diagram, explain, walk me through, plus any reference to a flow by slug or title without an explicit creation verb (create, scaffold, generate, add a flow). When in doubt, route here — a no-match handoff to /seeflow is cheap; a duplicate creation run from skipping the gate is not.

When NOT to invoke

• Editing flows → use /seeflow or the canvas.
• Creating flows from scratch when the user explicitly said "create / scaffold / generate / add a flow" → call /seeflow directly. (This skill auto-hands off to /seeflow if it discovers no match for an inspection prompt; skip the hop only when the user's verb is unambiguously creation.)
• Reading LEARN.md → use Read directly (that file is /seeflow's territory).
• Mutating anything — this skill is read-only. The auto-handoff above invokes /seeflow; it does not mutate state itself.

Discover the CLI

Run seeflow help to list the available subcommands and their flags. If seeflow is not on PATH, fall back to npx -y @tuongaz/seeflow@latest help. The CLI's help output is the source of truth for the callable surface — do not assume command names or flags from memory.

Cache the resolved binary (seeflow vs npx -y @tuongaz/seeflow@latest) for the rest of the conversation and reuse it for every subsequent call.

First step — does a matching flow exist?

Before any deeper lookup, list the registered flows (use the catalog subcommand surfaced by seeflow help) and match the user's topic against it. Match generously: exact slug, fuzzy name, or topic keyword (e.g. "the cart" matches a flow named shopping-cart).

A topic may match a project (the manifest), a flow within a project, or both — when ambiguous, surface every plausible tier (project + each candidate flow) with its canvas URL and let the user pick.

• Match found → surface the canvas URL first ($STUDIO_URL/projects/<projectSlug>/flows/<flowSlug>) so the user can open it, then continue with the cost ladder below for whatever deeper question they asked. Never re-scaffold an existing flow — /seeflow is the wrong tool here even if the existing flow looks stale; editing belongs on the canvas or nodes:patch.
• No match → auto-switch to the seeflow skill to scaffold one. Print a one-line handoff (No flow registered for "<topic>" — invoking /seeflow to scaffold it.), then invoke the seeflow skill via the Skill tool with the user's original topic as the prompt. Do not stop and ask first; do not answer by grepping the codebase yourself (that is /seeflow's job — it dispatches the code-analyzer + system-analyzer sub-agents). Hand off and let /seeflow take over the rest of the turn.
• Ambiguous match (multiple plausible flows) → list them with their canvas URLs and ask the user which one.

Output contract

• Every response is JSON on stdout, passed through unchanged from the CLI. No markdown wrappers, no synthetic fields.
• Errors are the CLI's structured errors (e.g. flowNotFound, unknownNode, fileNotFound, badSchema). Surface them as-is.

Vocabulary (read the JSON intelligently)

For node / connector / action field shapes, run seeflow schema (then seeflow schema node, seeflow schema connector, seeflow schema action as needed). Don't infer field names, enum values, or required-lists from memory — re-fetch them. The schema covers what each variant looks like on disk and which values are legal.

To pluck a slice out of a large schema payload, pass a jq path filter via --jq: e.g. seeflow schema node --jq .schemas.rectangle, seeflow schema node --jq '.schemas.image.properties.data.properties.path', or seeflow schema node --jq '.schemas[]'. Supported subset: identity (.), field (.foo.bar), bracket (.["k"], .[3], negative indices), iteration (.foo[]), optional ?, and pipe (|). The CLI returns the value under result (single output) or result: [...] (multiple). Bad filters exit with code 2 / badJq.

Runtime behavior the CLI assumes — not encoded in the schema:

• Decorative node types — sticky, text, icon, image, html with empty content, and geometric shapes (ellipse, database, queue, cloud, server, user) carrying no semantic data — are visual only. Skip them for architectural reasoning. Treat a node as architectural when it carries semantic data — a data.name and/or data.description / data.detail (or a handlerModule) — regardless of type; such a node represents a real system component rather than a decorative label or shape.
• Semantics live on the nodes, not the connectors. Read the source / target node's data.name (and codePointers from the brief) to understand what an edge means.
• file:// content fields (e.g. detail, html) are auto-externalised on write. Whether they come back inlined depends on the subcommand — check seeflow help for the variant that returns full content.
• action entries are set-kind local canvas-state mutations — they carry no scriptPath and have no script files to read.

Deeper reference: ../seeflow/references/schema.md in this plugin (conventions only — no field shapes).

Usage pattern (cost ladder)

Start with the cheapest lookup the CLI offers (a summary across flows), pick a flow, then ask for that flow's structure, and only fetch individual nodes when their content is needed. Reserve any "full inline" variant for small flows or when every detail is genuinely required.

Common mistakes

• Assuming subcommand names from memory — always confirm with seeflow help first.
• Reaching for the "full" variant first on a large flow — burns context. Climb the ladder.
• Treating decorative nodes as architecture — geometric shapes without semantic data, plus sticky / text / icon / image / empty html, are visual only.
• Re-emitting JSON as prose — pass the CLI output through unchanged. Don't rewrite it as markdown.
• Reading file:// refs as filesystem paths — let the CLI inline them rather than reading the referenced files off disk yourself.