diagram-renderer
Skill1 starsChanged 55 days agoMITView on GitHub
Author FILE-LEVEL Mermaid overviews for ONE mainframe or IBM i (AS400) source from `facts.json`. Emits call graph, COBOL control flow, IBM i CL command flow, JCL steps, CICS calls, SQL cursor lifecycle, and ER fragments when facts exist. USE FOR: IBM i CL/COBOL or mainframe diagrams. DO NOT USE FOR: per-section diagrams, SVG rendering, or index/complete authoring.
In this repository17 other files it gives its agents.
- chunk-text-extractionSkill
- cobol-chunkingSkill
- cobol-facts-extractionSkill
- facts-slicingSkill
- functional-analysis-finalizerSkill
- functional-analysis-group-finalizerSkill
- functional-analysis-group-writerSkill
- functional-analysis-writerSkill
- group-doc-finalizerSkill
- qa-reviewerSkill
- requirements-finalizerSkill
- requirements-group-finalizerSkill
- requirements-group-writerSkill
- requirements-writerSkill
- section-doc-finalizerSkill
- section-doc-writerSkill
- technical-analysis-writerSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Do not use this skill for:
- Very specific: line 40
Use identifiers that match profile.yaml::identifier_lock_regex (default [A-Z][A-Z0-9-]*(\.[A-Z0-9-]+)?).
- Very specific: line 101
Re-deriving collections: Always use facts.json collections as-is.
- Very specific: line 102
Invented nodes: Every Mermaid node MUST trace back to an identifier present in the corresponding facts.json collection.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Diagram Renderer (per-file, phase C)
LLM-driven phase-C authoring skill. Produces FILE-LEVEL overview .mmd Mermaid sources, one per non-empty collection in docs/_shared/<basename-with-ext>/facts.json. The skill packages the inputs deterministically and defines the kind-to-syntax mapping; the LLM call that fills the templates is invoked by the diagram-renderer agent.
When to Use
- The user asks to "render the overview diagrams", "generate the call graph", "draw the JCL step flow", "author cics-calls.mmd", "produce the ER fragment for DEMO100".
- Phase B has completed:
docs/_shared/<file>/facts.jsonexists and itsmanifest_sha256matches the current chunk-manifest.
Do not use this skill for:
- Per-section
.mmdfiles — those are produced bysection-doc-writerat per-section scope. .svgrendering — owned by phase D.- File-level prose (
index.md/complete.md) — usesection-doc-finalizer.
Output Contract
For file <basename-with-ext> and each non-empty source collection, emit:
| Collection (in facts.json) | Output file | Mermaid kind |
performs | docs/_shared/<file>/diagrams/call-graph.mmd | flowchart LR |
calls + incoming_xref | docs/_shared/<file>/diagrams/inter-program-call-graph.mmd | flowchart LR |
go_tos | docs/_shared/<file>/diagrams/control-flow.mmd | flowchart TD |
jcl_steps | docs/_shared/<file>/diagrams/jcl-steps.mmd | flowchart TD |
cl_commands | docs/_shared/<file>/diagrams/cl-command-flow.mmd | flowchart TD |
exec_cics | docs/_shared/<file>/diagrams/cics-calls.mmd | sequenceDiagram |
exec_sql (cursor stanzas) | docs/_shared/<file>/diagrams/cursor-lifecycle.mmd | stateDiagram-v2 |
data_records | docs/_shared/<file>/diagrams/er-fragment.mmd | erDiagram |
Empty collections produce NO file. Stale .mmd files for collections that emptied between runs are deleted when --prune is passed.
Each .mmd MUST:
- Begin with a Mermaid
%% generated-from: <facts_sha8> %%comment so consumers can detect drift. - Use identifiers that match
profile.yaml::identifier_lock_regex(default[A-Z][A-Z0-9-]*(\.[A-Z0-9-]+)?). - Reference only chunks/identifiers present in
facts.json— no invented nodes. - Render
inter-program-call-graphfrom the bundle's derivedinter_program_callscollection. Each edge label is its call kind; inbound and outbound directions must be preserved. Exclude copybook edges.
Procedure
- Resolve inputs. Required artifact (under
docs/_shared/<basename-with-ext>/):facts.json(whole file — this is the per-file step, slicing does not apply). On any miss: exit4and tell the user to re-run phase B.
- Stale-input check. Re-compute
sha256(facts.json bytes)and compare to the value embedded in any existing.mmdheader. On mismatch, re-author (or delete with--prune). - Assemble the prompt bundle. Invoke scripts/assemble-inputs.py — pure-deterministic packager. It loads
facts.json, derives the non-empty collection set, and prints (or writes via--out) a single JSON object the LLM consumes:
Flags:python .github/skills/diagram-renderer/scripts/assemble-inputs.py ` --source repos/sample1/COBOL/DEMO100.CBL ` --out prompt-bundle.json--source <path>(required).--out <path>— write to file (default: stdout).--profile <path>— override profile.yaml.
- Author. The
diagram-rendereragent reads the bundle and writes one.mmdper non-empty collection. - Validate mechanically. Invoke
qa-reviewer--kind diagramson the produced.mmdset.
Bundle Schema
{
"bundle_version": "1.0",
"source_path": "repos/sample1/COBOL/DEMO100.CBL",
"source_kind": "cobol|cl|jcl|proc|copybook|bms",
"program_id": "DEMO100",
"facts_sha": "<64-hex>",
"manifest_sha": "<64-hex>",
"diagrams": [
{
"kind": "call-graph",
"mermaid": "flowchart LR",
"output_path": "docs/_shared/DEMO100.CBL/diagrams/call-graph.mmd",
"facts_subset": { "performs": [ /* … */ ], "paragraphs": [ /* … */ ] }
},
/* one entry per non-empty collection, in stable order */
],
"profile": { /* loaded profile.yaml */ }
}Determinism Rules
- Bundle packager is fully deterministic: stable iteration order, sha256 over canonical-JSON of every
facts_subset. - LLM authoring is non-deterministic but the shape is fixed: same kind → same Mermaid header, same identifier styling.
- Pruning is opt-in via
--pruneto avoid silently deleting hand-edited.mmdfiles.
Resources
- scripts/assemble-inputs.py — deterministic prompt-bundle packager.
Common Pitfalls
- Authoring per-section
.mmdhere. Those belong tosection-doc-writerper-section scope; mixing breaks the per-section/per-file boundary the DAG enforces. - Re-deriving collections. Always use
facts.jsoncollections as-is; do not re-parse the COBOL/JCL source. - Invented nodes. Every Mermaid node MUST trace back to an identifier present in the corresponding
facts.jsoncollection.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

