/omh-codebase-uml

name: "omh-codebase-uml"
description: "[omh] Architecture picture of a codebase: turn a repository into one readable, interface-level PlantUML architecture picture - packages or modules, the public symbols other units actually import, bounded import edges - and get it rendered to a single PNG a chat surface can show. Use when the user says: codebase-uml, codebase uml, uml, plantuml, uml diagram, class diagram, package diagram, module diagram."
metadata:
  hermes:
    tags: [workflow, oh-my-hermes, planning]
    category: planning
    phase: codebase-uml
    role: planner
    quality_tier: codegraph-gated

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