What Is an HCP Chart? Using MakingHCPChartSkill to Turn HCP-DSL into Deterministic SVG

What is an HCP chart?

An HCP chart describes process flow as a hierarchical structure.

• Left side (shallower levels): the goal you want to achieve (What)
• Right side (deeper levels): concrete means and details (How)
• Top (level 0): the overall purpose label

Just by following this rule, the design intent and the implementation details become visible at a glance.

Why HCP charts are useful

Traditional hand-drawn diagrams have a few problems:

• Diagrams drift out of sync with the spec
• Branches and hierarchy become ambiguous
• They are hard to diff and review on Git

An HCP chart auto-generates an SVG image from HCP-DSL (text), so the same input always produces the same diagram. That makes it easy to wire into CI and code review.

Repository layout

Target repository: https://github.com/gomurin0428/MakingHCPChartSkill

10-minute hands-on

1. Clone the repository

git clone https://github.com/gomurin0428/MakingHCPChartSkill.git
cd MakingHCPChartSkill

2. Install the skill into your local Codex

Copy-Item -Recurse -Force .\hcp-chart-svg-v2 "$HOME\.codex\skills\hcp-chart-svg-v2"

3. Generate the SVG response

python .\hcp-chart-svg-v2\scripts\hcp_render_svg.py `
  --input .\hcp-chart-svg-v2\references\example-gcd-request.json `
  --output .\hcp-chart-svg-v2\references\example-gcd-response.json `
  --pretty

4. Extract the SVG

$r = Get-Content -Raw .\hcp-chart-svg-v2\references\example-gcd-response.json | ConvertFrom-Json
$r.svg | Set-Content -NoNewline -Encoding utf8 .\hcp-chart-svg-v2\references\example-gcd.svg

Things to watch out for

• When renderAllModules=true, you cannot specify module
• If diagnostics contains errors, the SVG comes back empty

How to write HCP-DSL (example)

Here is a DSL that computes the GCD (greatest common divisor).

\module main
Receive the request and confirm the preconditions
    Validate the required fields in the input JSON
Parse the DSL and turn it into a structured form
    Interpret modules and hierarchy
    Collect diagnostics
Choose the response path based on the diagnostics
    \fork Are there any errors?
        \true Yes
            Return an empty SVG payload
        \false No
            Decide which module to render
            \fork Is renderAllModules true?
                \true Yes
                    Generate SVG for every module
                \false No
                    Generate SVG for a single module
Return the result to the caller

Summary

• The biggest strength of an HCP chart is that you can manage the diagram as the spec
• The same input yields the same output, so it pairs well with CI/CD and reviews
• Try writing one of your everyday processing specs in HCP-DSL and you will quickly feel the benefit

References

• MakingHCPChartSkill (GitHub)
• SKILL.md
• hcp_render_svg.py