Q Flow

Q flow

Offline HTML diagrams with SVG/PNG downloads.

Intake

Resolve intent first: an audit is read-only, even if source drift is found. Read and validate without --fix; report findings without generation, edits or --force. Only an explicit update enters Refresh. Read all supplied material, combining source and documents when requested; distinguish implemented facts from documented intent. Existing graphs supply scope, type, granularity, views and directory; inherit these unless changed.

A request is ready when every requested view has a subject and question. Structure accepts a system, module or entity set; behaviour needs a flow or component, including one described in a document. For missing scope or output location, use guided-intake.md. Ask only for missing information, usually in one or two rounds; continue if essential scope remains unclear. Use a structured question tool when available, otherwise numbered options. After asking, end the turn and wait for the reply; never assume an answer. Write no output files before the round completes.

For every ready request, apply Granularity before Evidence, even when intake is skipped. Default unspecified preferences; then start without another confirmation.

Evidence

• For repository evidence, follow evidence-sources.md: verify tool/index availability before reporting CodeGraph, otherwise trace directly. Documents use document evidence.
• Use source/tests for calls, DDL/mappings for ER, manifests for deployment, and accepted requirements plus implementation for business behavior.
• Preserve exact identifiers and file/line anchors. Separate repository facts, framework behavior, documents, and inference; omit unproven critical relationships and label other inference. Never put secrets or token values in graph data.
• Public examples and documentation must use independently authored fictional content or public sources. Never reuse private project names, paths, architecture, rules, versions, status or reference images; renaming them is insufficient. Remove affected generated copies when replacing private-derived examples. This does not restrict private diagrams explicitly requested for the user's own project.

Author

Eleven templates: three architecture views (meta.architectureView: capabilities, engineering, relations) and eight other types below.

1. Choose meta.diagramType by intent: structure → architecture; decisions → flowchart; ordered calls → sequence; stored data → er; runtime placement → deployment; types → class; lifecycle → state; actors/capabilities → usecase; data movement → dataflow. Default to architecture when ambiguous. Architecture: platform capabilities / business integration → capabilities; engineering organization / component layers → engineering; component calls / dependencies → relations. Use one graph unless the user explicitly requests multiple views.
2. Each view uses graph-common.md and its matching page in references/types/ (types/<diagramType>.md); reuse loaded references across views. Do not read graph-schema.md, visual-contract.md, examples/, scripts/, assets/ or tests to learn rules. Use the type skeleton and validator messages for fields.
3. Write the evidenced graph at the chosen granularity, without coordinates. Record level/coverage in meta.scope and check every user requirement before layout. Apply the common rules for names, evidence, ownership, order and business centre. Across views reuse the same non-empty module value for the same business module. Preserve ER keys/cardinalities, class members/multiplicities, sequence pairing/fragments/executions, state guards and architecture/deployment boundaries required at this level. Write once; correct only reported fields.
4. Templates measure text and preserve order; routes use feasible outlines and independent labels. Never remove facts.
5. Default output: <repository-root>/docs/qgraphflow/<scope>-<diagram-type>/. Document-only work uses the current project root instead; without a suitable project or specified directory, ask only for the output location. Honor user-selected directories.

Generate and verify

Resolve the skill directory from the loaded SKILL.md, not the client's working directory or a hard-coded installation path. Quote absolute paths in the target repository; never output into plugin caches.

Run from the skill directory:

node scripts/validate-graph.mjs "<absolute-graph.json>" --input-only --repo-root "<absolute-repository-root>"
node scripts/generate-viewer.mjs "<absolute-graph.json>" "<absolute-output-directory>" --repo-root "<absolute-repository-root>"
node scripts/validate-graph.mjs "<absolute-output-directory>/graph.json" --repo-root "<absolute-repository-root>"

• Execute the scripts; do not read them, the bundled HTML, the Viewer source or tests. --help lists every option. Failures report elements, rule, measurement and remediation; --verbose prints the receipt.
• On failure, run node scripts/validate-graph.mjs "<graph.json>" --input-only --fix --repo-root "<root>" first: it repairs sequence order, operand ids, unambiguous replies/callee bars and unique source/site symbols, prints changes and writes only a valid graph. Then edit only reported fields/elements and rerun. Rewrite the whole file only for a wrong type or view split. Never delete supported facts, shrink text or use --force to pass a check.
• Composition warnings never fail the run; input validation prints them, later commands count them (warnings: n). Fix module.missing, module.inconsistent, flowchart.process-branch (a non-decision branches) and edge.site-missing. For module.single-tone, keep one module if the flow really belongs to it; never rename a module for colour. view.oversized means over 4 screens at readable zoom: apply the common contract's view-splitting rules while preserving requested detail and graph count. A failing collection names every failing view.
• If bounded layout still fails, distinguish a search budget from proven impossibility, report the blocking nodes and relationships and propose separate views with explicit coverage of the original model; never silently reduce the requested detail. Generation defaults to --layout auto; --layout preserve keeps existing geometry under the same gate.
• For repository-backed diagrams, pass the target repository root to both commands: they verify every node source and edge site against local UTF-8 files (existence, line range, symbol, no path escape) and report sourceEvidence with its relations coverage. This checks the working tree, not the commit in sourceRef or whether code proves a relationship. Omitting --repo-root reports skipped, never verified evidence; say so when source files are unavailable. Conceptual diagrams need no root.
• Outputs are index.html, graph.json and one SVG per view (diagram.svg, or diagram-<n>-<type>.svg in a collection), built from the prebuilt viewer; no rebuild or install. Use --force only with approval to replace the named outputs. All collection views must pass before replacing output.
• Reply with artifact paths, types, granularity and coverage (meta.scope), semantic/geometry/source-relation results, meta.notes, unresolved evidence boundaries, and Browser acceptance: not performed unless the next section ran. Never paste full HTML or graph JSON.