just-works: Skill for Claude Code

PlantUML Diagramming

Match the project's existing conventions. Before writing, Glob for *.puml, *.plantuml and *.pu, and read what you find to infer naming, layout direction, theme usage and abstraction level. Check for shared includes (!include) or a project theme file. These defaults apply only when the project has no established convention.

File placement and naming

• Put diagrams in a diagrams/ directory at the project root, unless the project already has a convention.
• Name files <context>_<type>_<title>.puml, lowercase with underscores, for example auth_sequence_login_flow.puml.

Never rules

These are unconditional. They prevent broken or unreadable diagrams regardless of project style.

• Never omit @startuml/@enduml delimiters -- PlantUML silently fails or produces garbage without them. Every .puml file must start with @startuml and end with @enduml (or the equivalent for the diagram type: @startmindmap/@endmindmap, @startgantt/@endgantt, etc.).

• Never use cryptic abbreviations or internal codenames as labels -- use plain English that any team member understands. AuthSvc means nothing to a product manager; Authentication Service does. Labels are for humans, not compilers.

• Never create diagrams with more than ~15 elements without grouping/nesting -- overcrowded diagrams defeat the purpose. Use package, rectangle, node, cloud, or together to group related elements. If you cannot group meaningfully, split into multiple diagrams.

• Never use legacy skinparam when <style> blocks achieve the same result -- skinparam is deprecated. Use CSS-like <style> blocks for all visual customization. The only exception: edge cases where <style> does not yet support a specific property -- activity-diagram stereotype coloring (skinparam activity { BackgroundColor<<x>> ... }, see references/activity-diagrams.md) is the documented one.

• Never hardcode colors inline on individual elements -- use stereotype-based skinparam or <style> blocks for consistency. Inline colors (#FF0000 or #CCFFCC after ;) on individual elements create maintenance nightmares, visual inconsistency, and often cause syntax errors in activity diagrams.