crew-diagrams

Files (6)

• SKILL.md
• render.sh · scripts/_test/
• diagram_check.py · scripts/
• diagram_doc.py · scripts/
• render.sh · scripts/
• visio.ps1 · scripts/

SKILL.md (first lines)

# Diagrams

Diagrams live as **Mermaid source in git**, rendered to images on demand. Text is
the artifact; the PNG is a build output.

The reason is maintenance. A PNG someone drew in a tool is unreviewable in a pull
request and un-updatable by anyone who lacks the source file, so it drifts from
the code within about a quarter and then actively misleads. Mermaid diffs, and
the person who changes the code can change the diagram in the same commit.

## Where things go

```
docs/diagrams/
  architecture.mmd        # source, committed
  data-flow-orders.mmd
  process-refund.mmd
  README.md               # generated: every diagram embedded with its purpose (diagram_doc.py)
  index.html              # generated: the same page as HTML
  out/                    # rendered, gitignored unless a doc embeds it
    architecture.svg
```

These are the standard locations, for every diagram crew draws. A topic page
that explains a process (`docs/qa/README.md`, say) embeds its diagrams as
fenced `mermaid` blocks and keeps their sources here, so one directory holds
every diagram the repo has and one page shows them all. The README of the code
a diagram describes gets it too, generated (see "Embedded in the READMEs it
describes").

Every source file starts with a provenance comment and a purpose line:

```
%% Generated from <repo>@<short-sha> on <date>. Verify before trusting.
%% Anchors: src/api/orders.ts, src/domain/refund.ts
%% Purpose: How a refund moves from request to ledger, and where it can be refused.
```

`%% Purpose:` is what the generated page prints above the diagram. One or two
plain sentences: what a reader learns from it.

Anchors are the same idea as the code map: a diagram nobody can re-verify is a
diagram that rots into confident inaccuracy.

**The header is machine-read, so its shape matters.** `crew_state.read_diagrams`
parses the short sha out of that first line to decide whether a diagram is
current, and `/crew:status` and the context hook report the answer. A source file with no parseable
provenance counts as *behind*, not as *unknown* — unknown resolving to stale is
the honest direction, and it is the same call `_read_graph` makes about a graph
with no `built_at_commit`. The cost of being wrong that way is one unnecessary
redraw; the cost of the other way is a diagram that lies and looks fresh.

## The PM refreshes these on its own

Diagrams are the one documentation artifact the crew regenerates without being
asked. That is not a general licence to rewrite documentation — it is specific
to artifacts with a machine-checkable anchor, where "is this still true" has a
real answer rather than a judgement call. Prose docs keep `crew-docs`'s
deliberate *do not touch* default for exactly that reason.

Two triggers drive it, and they mean different things:

- `diagramsStale` — a source's anchor is not HEAD. The picture exists and the
  code under it moved. Re-verify, then update.
- `diagramsMissing` — one of architecture / data-flow / process has no file at
  all, in a repo whose subsystems are already mapped. Draw it. This one stays
  quiet until there is a code map, because a repo that has not decided what its
  subsystems are has nothing to draw from yet.

**Always re-verify before redrawing.** Send `crew:explorer` first and check its
anchors against HEAD. A diagram regenerated from a code map that is itself
behind is stale output wearing a fresh anchor — strictly worse than the stale
diagram it replaced, because that one at least advertised its age. This is why
`graphStale` and `knowledgeBehind` sort above `diagramsStale` in the trigger
order: fix the input before regenerating the output.

## Picking the diagram type

| Need | Mermaid type |
|---|---|
| Components and what talks to what | `flowchart LR` or `graph TD` |
| A request through the system over time | `sequenceDiagram` |
| Business or approval process | `flowchart TD` with decision nodes |
| Data model | `erDiagram` |
| Object or state lifecycle | `stateDiagram-v2` |
| Deployment topology | `flowchart` with `subgraph` per environment |
| Delivery timeline | `gantt` — rarely worth it, prefer a table |

Data-flow diagrams are `flowchart` with edge labels naming **what** moves, not
just that something does: `-->|order id, line items|` beats `-->`.

## The readability standard: measured, not hoped for

A diagram is done when `diagram_check.py` says PASS on its render. It measures
the drawing Mermaid actually produced, so a layout that looked fine in the
source and crossed in the picture is caught:

| Measured | Limit |
|---|---|
| Lines crossing outside a box | 0 |
| A line drawn through a box that is not one of its ends | 0 |
| An edge label covering a box or another label | 0 |
| Boxes | 15 |

```bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/crew-diagrams/scripts/render.sh docs/diagrams
python3 ${CLAUDE_PLUGIN_ROOT}/skills/crew-diagrams/scripts/diagram_check.py docs/diagrams/out
python3 ${CLAUDE_PLUGIN_ROOT}/skills/crew-diagrams/scripts/diagram_doc.py --dir docs/diagrams --write
```

Only flowcharts are measured; a sequence, state or ER diagram is reported NOT
CHECKED, never PASS. Without `mmdc` nothing is rendered, so nothing is
measured: say NOT VERIFIED and give the install line, never "looks fine".
A drawing the checker cannot fully read (no box measured, a line outside the
boxes that is not a recognised edge, a scale/rotate transform, path data it
cannot parse) is UNKNOWN, also never PASS.

The page trusts a render only when it came from the current source:
`render.sh` writes `out/<name>.svg.src`, the sha256 of the `.mmd` it rendered,

From mbadali25/useful-claude-add-ons, GPL-2.0.

More from mbadali25/useful-claude-add-ons