PR Lens Skill for Hermes Agent: Animated Architecture Diagrams

PR Lens turns a code change or a system into animated SVG diagrams: architecture, data flow, and the shape of a diff. You describe the picture as a single JSON document, validate it, and the CLI renders it. It is a comprehension layer, not a review bot. There is no field for a bug, a risk, or a security note, and a document that invents one is rejected. Reach for it when a pull request needs a diagram a reviewer can actually follow, or when someone asks you to explain how a change fits together.

What it does

The skill gives you a small authoring format and a CLI. You write lanes, nodes, edges, and ordered flows into .pr-lens/graph.json, run the validator, then render. The output is a set of animated SVGs plus a manifest that names each one by lens and view. Because the document is structured rather than freehand, the same source produces the same diagrams on demand, and the generated files are treated as build artifacts rather than source.

What it is not: a linter, a reviewer, or a place to record findings. If you find yourself wanting to annotate a node with a warning, that is the wrong tool. PR Lens exists so a reader can see the shape of a change, not so a machine can judge it.

Before you start

• Node.js with npx. The CLI runs via npx @coldtea/pr-lens-cli@latest, so there is no install step.
• gh (the GitHub CLI) is optional. You only need it if you plan to attach diagrams to pull requests.
• The optional canvas publishing step calls a third-party service, prlens.dev. Treat that as an opt-in action, not part of the default flow.
• The skill is optional and installed on demand. Its path is optional-skills/software-development/pr-lens, version 1.0.0, MIT licensed, authored by Coldtea AI and adapted by Nous Research. It targets linux and macos.

Run every command with the terminal tool from the repository root.

How to run it

1. Read the diff

When you are representing a code change, start from the diff. The base you compare against is the merge base, not the tip of the base branch. That distinction matters: comparing against the branch tip pulls in unrelated commits and makes the diagram describe work that is not part of the change. If you are not expressing a diff, read the code you intend to visualise instead.

2. Write the document

Write the graph document to .pr-lens/graph.json, following references/graph-document.md. Before you write your first one, read references/example.graph.json. It is a valid reference containing three lanes, all four delta states, a hero edge, a seven-step flow, a nested drill-down tree, and a six-step walkthrough. Reading the example is faster than reading the reference prose, and it shows you the shape the validator expects.

3. Validate, and fix

npx @coldtea/pr-lens-cli@latest validate .pr-lens/graph.json

Fix every failure and run it again. Do not render an invalid document, and do not work around a failure by deleting the element the validator names. If it says an edge points at an id you never declared, the fix is to declare the node or correct the reference, not to remove the edge and lose the connection you were trying to show.

4. Render

npx @coldtea/pr-lens-cli@latest render .pr-lens/graph.json --theme light

Render light by default unless the user asks for another theme. The SVGs, the manifest, and drawn.graph.json land in .pr-lens/, which the CLI adds to the repository's .gitignore. Do not commit any of it. These files are rebuilt from the diff on demand, so committing them creates stale copies that drift from the source. Each SVG is named after its view, theme, and content hash, and manifest.json lists them by lens and view.

4b. Canvas push (optional, opt-in)

Only do this when the user explicitly asks for a shareable link. It publishes .pr-lens/drawn.graph.json to the third-party service prlens.dev:

npx @coldtea/pr-lens-cli@latest canvas push

It prints three links, and they are not interchangeable. Give the user the view link (https://prlens.dev/c/{id}): that is the full-screen diagram with every view on one page, and it needs no login. The edit link ends in #w=… and lets its holder overwrite the canvas. Treat it as a secret: leave it out of the reply unless asked, and never paste it anywhere public. The embed link serves the top view as an SVG, which is what you want for a README.

Pushing the same file again updates the same canvas. That makes a rename cheap: edit, validate, render, push, and the link stays the same. If the push fails, say so plainly and tell the user where the local SVGs are and which one is the top view.

5. Attach to a PR, when there is one

Upstream documents gh pr create/edit/comment --attach, but --attach arrived in GitHub CLI 2.99. Check gh --version first. An older gh, 2.97 for example, does not have the flag.

With gh 2.99 or newer, write the body with a Markdown image reference, then repeat --attach once per referenced diagram:

gh pr create --title "…" --body-file .pr-lens/body.md --attach .pr-lens/overview-light-<hash>.svg

The alt text is the one-line caption a reader without images gets, so write it as a sentence, not a filename. An HTML image tag is left as written and the file is appended at the bottom instead, which is rarely what you want.

Without --attach, use a commit-free path. You have three options:

• Upload the SVGs to a gist with gh gist create .pr-lens/*.svg, then reference the raw gist URL in the PR body or comment.
• Publish via the canvas link from step 4b, with the user's consent, and link the view URL.
• Note the local .pr-lens/ path in the PR body so reviewers can rebuild the diagrams themselves.

Once the diagrams are published somewhere durable, let the CLI compose the comment markdown:

npx @coldtea/pr-lens-cli@latest comment \
  --graph .pr-lens/drawn.graph.json \
  --manifest .pr-lens/manifest.json \
  --asset-base-url <where you published the SVGs>

--graph takes drawn.graph.json, not the document you wrote. The CLI refuses a document its manifest does not describe, so pointing it at graph.json will not work. Leave out --asset-base-url and the markdown points at local paths no reader can fetch. The markdown goes to stdout; posting it is your business.

Attach the views a reviewer needs and leave the rest in .pr-lens/. The top architecture view comes first, then a data flow if the change has a sequence worth following. Two diagrams usually beat four.

6. Optional automation

npx @coldtea/pr-lens-cli@latest analyze --base <ref>

This does steps 1 and 2 by asking a provider (Gemini, OpenAI, or any /chat/completions endpoint) with a key of your own. It is the only path here that needs an API key. Normally you author the document yourself, and that is usually the better result: you know which connection matters and which neighbour is context.

What makes a document worth reading

These are the rules that separate a diagram a reviewer reads from one they scroll past.

• Include what did not change. Unchanged neighbours that a change touches are the context. Mark them delta: "unchanged" so the reader can tell what moved and what stayed put.
• Lanes are the reader's mental model. A runtime, a tier, a boundary. Not the folder tree. If your lanes mirror directories, you have described the repository, not the system.
• One hero edge, two at the outside. That is the connection the change is really about. More than that and nothing stands out.
• Add a flow only when there is a sequence worth animating. One good flow beats three thin ones.
• Attach file refs. They become the permalinks a reviewer clicks.
• Architecture views are a C4-inspired decision tree: system context, then container, then component, each child materially narrower than its parent. Skip empty or repetitive levels. Keep data-flow views as separate roots. Set defaultOpen: true on the highest useful architecture view.
• Walkthroughs run 2 to 12 steps, aim for 3 to 7. Write one for anything non-trivial. Each step is one change (added, removed, or moved), with the headline change first and the overview last. Headings are 48 characters or fewer and built from change words. Bodies are 140 characters or fewer and must describe behaviour. Write for a smart twelve-year-old: no "leverages", no "orchestrates". Keep consecutive steps on the same stage. The walkthrough field needs CLI 0.4.0 or newer (contract 0.1.1).
• Fixing a wrong map: never edit the generated document. Write corrections into .github/pr-lens.yml (see references/config.md), then validate it:

npx @coldtea/pr-lens-cli@latest validate .github/pr-lens.yml

Prefer path globs over id: matches, because globs survive renames and ids do not.

Quick reference

Command	Purpose
npx @coldtea/pr-lens-cli@latest validate .pr-lens/graph.json	validate the document (also validates .github/pr-lens.yml)
npx @coldtea/pr-lens-cli@latest render .pr-lens/graph.json --theme light	render SVGs + manifest into .pr-lens/
npx @coldtea/pr-lens-cli@latest canvas push	OPTIONAL: publish to prlens.dev (opt-in only)
npx @coldtea/pr-lens-cli@latest comment --graph … --manifest … --asset-base-url …	compose PR comment markdown to stdout
npx @coldtea/pr-lens-cli@latest analyze --base <ref>	auto-author document via an LLM provider (needs API key)

Validator failure codes:

Code	What you did
BROKEN_REFERENCE	an edge, flow step, view or walkthrough step names an id you never declared
INVALID_DOCUMENT	an invented field; the schemas are strict, unknown keys are rejected
DUPLICATE_ID	two nodes, edges or views sharing an id
UNSUPPORTED_SCHEMA_VERSION	schemaVersion is not the contract version installed

When not to use it

PR Lens is a comprehension layer, not a review bot. If the task is to find bugs, flag risks, or record a security note, this is the wrong skill: the document format has no field for those, and a document that invents one is rejected by the validator. Use it when the goal is to explain, not to judge.

It is also a poor fit when there is no change and no system worth drawing. A diagram of a trivial diff adds noise to a review. And if the user has not asked for a visual, a text summary is often faster to read.

Limits and gotchas

• Six rules are parser-only and not in the JSON Schema: referential integrity, inverted line ranges, disagreeing self endpoints, identical patch commits, too many views for a manifest, and flow-step focus on the wrong stage. Always run validate. Structured output alone is not enough.
• Do not commit anything in .pr-lens/. It is regenerated and gitignored by the CLI.
• The --attach gh flag needs gh 2.99 or newer. Older gh silently lacks it, so check before you write a body around it.
• The canvas edit link (#w=…) is a write credential. Never share it unprompted or paste it publicly.
• A stored map never carries a walkthrough. A walkthrough tells the story of one change, so it does not belong in a map that outlives that change.
• pr-lens render reports corrections in .github/pr-lens.yml that matched nothing. That is drift worth fixing, not an error.

Verification

A smoke test, live-verified 2026-09-12 with @coldtea/pr-lens-cli via npx, node on Linux:

cp references/example.graph.json ~/.hermes/cache/scratch/prlens-smoke/ && cd ~/.hermes/cache/scratch/prlens-smoke
npx -y @coldtea/pr-lens-cli@latest validate example.graph.json
# ✓ example.graph.json — graph document · 3 lanes, 10 nodes, 13 edges, 1 flow · 6 walkthrough steps
npx -y @coldtea/pr-lens-cli@latest render example.graph.json --theme light
# ✓ .pr-lens/manifest.json — 4 SVGs across 4 diagrams

Expect exit 0 on both, and four *-light-*.svg files plus manifest.json and drawn.graph.json in .pr-lens/. Running this once before you author your first real document tells you the toolchain works and shows you what a valid document produces.

What pairs with it

PR Lens is adapted from coldteadotai/pr-lens (packages/agent-skill, pinned 0993b4d), MIT License, Copyright (c) 2026 Coldtea AI. See LICENSE.txt in the skill directory for the full licence text. The upstream repository is the place to look when you need the authoring reference in more depth than references/graph-document.md provides.