hiearch

name	hiearch
description	Generate hierarchical decomposition diagrams and views using the hiearch tool. Use when creating architecture diagrams, package dependency visualizations, state machine diagrams, use case diagrams, or any hierarchical structure visualization. Supports Graphviz output in SVG and other formats.

Hiearch

Overview

Hiearch is a diagram generator that creates hierarchical decomposition visualizations from YAML configuration files. It processes input files to generate structured diagrams showing relationships between entities (nodes and edges) with customizable views and styling.

When to Use This Skill

This skill should be used when:

• Generating architecture diagrams showing package hierarchies
• Creating state machine visualizations
• Building use case diagrams
• Visualizing hierarchical decomposition of systems
• Creating structured views of complex relationships
• Generating documentation diagrams with consistent styling

Core Concepts

Input Files

Hiearch processes YAML files that define:

• Views: Different perspectives on the hierarchy for selective node visualization
• Nodes: Entities in the hierarchy with IDs, labels, and properties
• Edges: Relationships between nodes
• Styles: Visual formatting options for nodes and edges (colors, shapes, fonts)

Views

Views define which nodes are visualized and how they are selected:

• hh_state_machine_view: State machine diagrams
• hh_use_case_view: Use case diagrams
• default: Fallback view

Views are primarily intended for selective visualization of nodes. Visualization style is a secondary feature.

Node Selection

Nodes can be selected using several methods:

Tags

Assign tags to nodes and reference them in views:

nodes:
    - id: mynode
      tags: [important, core]

views:
    - id: core_view
      tags: [core]

Autotagging

Nodes and edges are automatically tagged based on their structural relationships:

• Nodes with a scope get hh:scope:<scope_id> tags for each scope parent, including ancestors up the scope chain
• Nodes with a style reference get hh:style:<style_id> tag, plus tags for all parent styles up the style chain
• Edges with a style reference get hh:style:<style_id> tag, plus tags for all parent styles up the style chain
• Entities with style_notag inherit visual properties but do NOT get hh:style:* tags

Tags propagate through the hierarchy: a node with scope a gets hh:scope:a, and if a itself has scope g, the node also gets hh:scope:g. The same applies to style chains. style_notag entities are excluded from style tag propagation.

These auto-generated tags can be used in views for selection:

nodes:
    - id: ["A", a]
      # gets hh:scope:g
      scope: g
    - id: ["B", b]
      # gets hh:scope:a and hh:scope:g
      scope: a
    - id: ["C", c]
      # gets hh:style:i and hh:style:h
      style: i
    - id: ["D", d]
      # combined: hh:scope:g + hh:style:i + hh:style:h
      scope: g
      style: i
    - id: ["E", e]
      # multiscoping: hh:scope:a + hh:scope:g
      scope: [a, g]
    - id: ["F", f]
      # inherits style but NO hh:style:* tags
      style_notag: i
    - id: ["G", g]
    - id: ["H", h]
      graphviz:
          shape: box
    - id: ["I", i]
      style: h
      graphviz:
          style: filled
          fillcolor: lightblue

edges:
    - link: [a, b]
    - link: [a, c, j]
      graphviz:
          color: red
    - link: [b, c]
      style: j

views:
    - id: scope_parent
      # A, B, D, E
      tags: ["hh:scope:g"]
    - id: scope_child
      # B and E
      tags: ["hh:scope:a"]
    - id: style_base
      # C, D, I (all inherit hh:style:h; F excluded by style_notag)
      tags: ["hh:style:h"]
    - id: style_derived
      # C and D
      tags: ["hh:style:i"]
    - id: style_notag
      # same as style_base -- F excluded from hh:style:* tags
      tags: ["hh:style:h"]
    - id: combined
      # D only (has both hh:scope:g and hh:style:h), with styled edges
      tags: ["hh:scope:g", "hh:style:h"]
      edge_tags: ["hh:style:j"]
      neighbours: direct

Edge Selection

Tags

Edges can be tagged similarly to nodes. Views use edge_tags to select only edges with matching tags. Edges are filtered before neighbour selection, so neighbour discovery only follows tagged edges.

edges:
    - link: [a, b]
      tags: [control]
    - link: [a, c]
      tags: [data]

views:
    - id: control_view
      edge_tags: [control]
      neighbours: direct

When edge_tags is not specified, edges with the default tag are included (matching node tags behavior). Multiple tags use OR/union semantics.

Explicit Node IDs

List specific node IDs in the view:

views:
    - id: specific
      nodes: [node1, node2, node3]

Neighbour Selection

Control which connected nodes are included:

• explicit: Only explicitly listed nodes
• direct: Nodes directly connected to selected nodes
• parent: Parent nodes up the hierarchy
• recursive_in: Recursively select nodes connected inward
• recursive_out: Recursively select nodes connected outward
• recursive_all: Both recursive_in and recursive_out

View Expansion

Automatically generate expanded views for specific nodes:

views:
    - id: packages
      nodes: [root_node]
      expand: [recursive_all]

This generates separate diagrams for each node showing its subtree.

Output Formats

• SVG: Scalable Vector Graphics (default)
• svg:cairo: SVG with embedded images (recommended when nodes include external image files)
• Other Graphviz-supported formats (PNG, PDF, etc.)

Usage

Basic Command

hiearch <input-file.yaml> [options]

Options

• -o OUTPUT, --output OUTPUT: Output directory (default: current directory)
• -f FORMAT, --format FORMAT: Output format (default: svg)
• -t TEMP_DIR, --temp-dir TEMP_DIR: Temporary files output directory (defaults to output directory)
• -r DIR, --resource-dirs DIR: Directories to search for graphical resources (can be specified multiple times)
• -i [DIR], --install-skill [DIR]: Install hiearch skill to coding agent skill directory
• -h, --help: Show help message

Examples

Generate diagram from a YAML configuration:

hiearch config.yaml -o ./diagrams

Generate self-contained SVG with embedded images:

hiearch config.yaml -o ./diagrams -f svg:cairo

Install skill to default directory:

hiearch -i

Install skill to custom directory:

hiearch -i /custom/path/.qwen/skills/hiearch

Generate in PNG format:

hiearch config.yaml -o ./output -f png

Process multiple input files:

hiearch file1.yaml file2.yaml -o ./diagrams

Input File Structure

Basic View Definition

views:
    - id: my_view
      nodes: [root_node]
      neighbours: recursive_all
      expand: [recursive_all]

Node and Edge Definitions

nodes:
    - id: root
      label: Root Node
      tags: [core]
    - id: child1
      label: Child One
      scope: root

edges:
    - in: root
      out: child1
      label: connects to

Node and Edge Styles

Prefer setting style of nodes and edges using node and edge styles instead of styling options provided in the views:

nodes:
    - id: mynode
      label: My Node
      graphviz:
          shape: box
          style: "rounded,filled"
          fillcolor: lightblue

edges:
    - in: node1
      out: node2
      graphviz:
          color: blue
          style: bold

Style Inheritance Without Tags (style_notag)

Both nodes and edges support style_notag, which inherits visual properties from another entity without inheriting its tags. This is useful for referencing style definitions that have specialized tags without pulling those tags into the referencing entity.

edges:
    - link: [a, b, style_edge]
      tags: [control]
      graphviz:
          color: red
    - link: [b, c]
      style_notag: style_edge

The b → c edge inherits color: red from style_edge but does not inherit the control tag. An entity cannot have both style and style_notag.

Installation

Hiearch should be installed with pipx:

pipx install hiearch

Verify installation:

hiearch --help

Installing Coding Agent Skill

To install the hiearch skill for coding agents:

hiearch -i

This will install the skill to the default agent skill directory. Restart the coding agent to activate it.

For custom installation paths:

hiearch -i /path/to/agent/skills/hiearch

Best Practices

1. Define Clear Views: Each view should have a distinct purpose and not be empty
2. Use Node and Edge Styles: Prefer setting style of nodes and edges using node and edge styles instead of styling options provided in the views
3. Organize Input Files: Keep YAML configuration files in a dedicated directory (e.g., diagrams/ or docs/diagrams/)
4. Use Meaningful IDs: Node and view IDs should be descriptive and follow naming conventions
5. Leverage Node Selection Features: Use tags, explicit IDs, neighbour selection, and expansion options to control which nodes appear in each view
6. Output Organization: Use the -o flag to organize generated diagrams in a dedicated directory
7. Use svg:cairo for Embedded Images: When node styles include other image files, use svg:cairo format to embed them in the output

Common Patterns

State Machine Diagram

State machine views are built-in and can be referenced in input files to generate state transition diagrams.

Use Case Diagram

Use case views are built-in and can be referenced to generate use case relationship diagrams.

Troubleshooting

"All views are empty" Error

This occurs when no nodes match the view definitions. Ensure your input files define entities that match the view criteria.

Missing Output Files

Check that the output directory exists and is writable. Use -t to specify a separate temp directory if needed.

Format Issues

Verify the output format is supported by Graphviz. SVG is the most reliable and recommended format. Use svg:cairo when nodes include external image files.