Omh Codebase Uml

Codebase Uml

This is a Hermes-native codebase-uml workflow skill.

Why This Exists

codebase-uml exists so 'visualize our codebase' produces one deterministic, readable picture instead of a hand-drawn guess: the interface each unit exposes is ranked by who imports it, the layout is bounded before PlantUML sees it, and every omission the bounding made is printed on the image.

Do Not Use When

• The user wants the local code index refreshed or a task-scoped handoff pack, not a picture; use codegraph-refresh.
• The user wants a narrative first-read tour, reading path, or glossary; use codebase-onboarding.
• The user wants a summary card, thumbnail, or explainer image of a PR, meeting, or release rather than a structural diagram; use img-summary.

Examples

Good example:

• Prompt: Visualize our codebase and drop the picture here so the new teammate can see how the routing package fits.
• Expected behavior: Run omh codegraph uml --focus src/routing --output .omh/uml/routing.puml, render with the plan's command, attach the PNG, and read back the legend (units shown, folded, edges pruned).
• Why: The request is a structural picture of one area for a chat surface, which is exactly the bounded diagram this workflow produces.

Bad example:

• Prompt: Just sketch what you think the architecture looks like from the README.
• Expected behavior: Decline to draw from memory; generate the diagram from the tree with omh codegraph uml or say the renderer is missing and name the install step.
• Why: A diagram not derived from the actual tree misleads more than no diagram.

Completion Checklist

• The view (package, focus, or module) matches the question asked, and only one view was rendered unless more were requested.
• The render command and its observed result are recorded before the image is claimed.
• The legend's omissions were read back to the user in the reply.
• Follow-up exploration used narrower generated views, not recollection of the first picture.

Recovery Notes

• If the render plan is blocked, send the PlantUML source path plus the install hint; do not attach a stale or hand-drawn image.
• If the picture is still unreadable, lower --max-nodes, narrow --focus, or raise --depth by one, and say which knob changed.
• If Graphviz dot is missing, rerun with --layout smetana; the layout differs but the content is identical.

Workflow Lane

• Current lane: Intent -> plan (oh-my-hermes, meta-router, deep-interview, context, plan, ralplan, adversarial-consensus, codebase-onboarding, +8 more) - clarify, plan, ship, or loop goals.
• If intent belongs to another lane, hand back to oh-my-hermes or name the adjacent workflow.
• Shared product, routing, compatibility, and evidence rules: omh-routing/references/skill-common-rail.md.

Use When

Use when the user wants to see the shape of a codebase as one picture - a package, module, or focused-area diagram they can drop into Slack, Discord, a PR, or a doc - rather than a prose tour or a refreshed code index.

Strong routing signals: `codebase-uml`, `codebase uml`, `uml`, `plantuml`, `uml diagram`, `class diagram`, `package diagram`, `module diagram`, `architecture diagram`, `dependency diagram`, `module dependency diagram`, `visualize the codebase`, `visualize this codebase`, `visualize the code`, `visualize the architecture`, `codebase visualization`, `code visualization`, `diagram of the codebase`, `diagram the codebase`, `draw the architecture`, `draw the codebase`, `architecture picture`, `codebase picture`, `picture of the codebase`, `코드베이스 시각화`, `코드베이스 시각화해줘`, `코드베이스를 시각화`, `아키텍처 다이어그램`, `UML 다이어그램`, `패키지 다이어그램`, `클래스 다이어그램`, `코드베이스 다이어그램`, `코드 구조 그림`, `코드베이스 그림으로`, `코드 구조도`

Catalog Metadata

Category: planning Phase: codebase-uml Hermes role: planner Quality tier: codegraph-gated Reasoning demand: standard

Quality bar:

• Scope first: whole-repo package view for 'show me the codebase', --focus <path> for one area, --level module for a subsystem; never render more than one view per request unless asked.
• Generate with omh codegraph uml --repo <root> --output <dir>/codebase.puml and read the printed render plan; when it is blocked, report the exact blocker and install hint instead of improvising a renderer.
• Render with the plan's command verbatim (-DPLANTUML_LIMIT_SIZE=8192 stays on) and attach the PNG; use --layout smetana when Graphviz dot is absent and --format svg only when the user asked for SVG.
• Read the legend back to the user in one line: units shown, units folded, edges pruned, symbols hidden - so nobody mistakes 16 boxes for the whole system.
• Answer follow-up exploration by re-running with a narrower --focus or --level module rather than describing what the first picture omitted from memory.
• Keep the omh theme unless the user asks for --theme mono; the theme exists so every OMH diagram reads as one family.

Handoff policy:

Keep diagram scoping, the omh codegraph uml source generation, and the render command in Hermes; the render runs through Hermes' own terminal tool and the image is attached by the chat surface. A generated .puml is prepared context; the picture exists only when the render command's exit status and output file are observed, and neither is architecture proof, review, CI, or merge evidence.