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:

bashCopy code
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.

Acceptance on request

Ordinary graph delivery ends with the three commands above. Run the browser checks in acceptance.md only when (a) the user asks to see or check the rendering, (b) the delivery includes Viewer changes, or (c) a receipt reports rendering diagnostics; read that file only then. Otherwise the reply carries Browser acceptance: not performed.

Refresh an existing diagram

Read the supplied graph and collection metadata. Inherit type, scope, granularity, view count and directory. An explicit update approves --force for that directory; audit findings alone do not. Resolve only the requested views; ask if their identity is ambiguous.

Simplification uses verified facts in Author. Expansion returns to Evidence before Author. Preserve stable IDs; report gaps, aggregations, additions and exclusions. These changes authorize --layout auto --force for the requested views only. In a collection add --view <view-id> for each changed view; omit it only when all views need layout. Unselected views must pass preserve; never relayout them to clear a failure. Ordinary refresh preserves geometry:

bashCopy code
node scripts/validate-graph.mjs "<dir>/graph.json" --input-only --fix --repo-root "<root>"
node scripts/generate-viewer.mjs "<dir>/graph.json" "<dir>" --layout preserve --force --repo-root "<root>"

Between the two, fix only anchors still reported: read just their files, edit just those source / site anchors or facts, and report a symbol you cannot place. Then validate the output as above. preserve keeps the user's moved positions and edited text; if it fails the gate, report the nodes and ask before --layout auto. Reply with the changed anchors and every artifact path. If a browser could only download graph.json, put it in <dir> and regenerate the page and SVGs.

Viewer maintenance

For Viewer changes or interaction audits, read viewer-development.md, including its maintained visual/interaction contract. Changes to Viewer source, routing, schema behavior, or validation require the full eleven-view browser matrix described there. Graph-only delivery uses the single-page check in acceptance.md.

Publishing the plugin or creating a remote repository requires separate user authorization.