edsger 0.82.0 → 0.83.0

package/assets/manifest.yaml

@@ -3,7 +3,7 @@
 schemaVersion: 1
 name: edsger-assets
 version: 0.1.0
-description: Industrial-grade benchmark rubrics and PR review standards.
+description: Industrial-grade benchmark rubrics, PR review standards, and diagram catalogs.
 
 # Standard kinds shipped in this repository.
 kinds:
@@ -15,6 +15,10 @@ kinds:
     dir: review
     base: base
     schema: schema/review.schema.json
+  diagrams:
+    dir: diagrams
+    base: base
+    schema: schema/diagrams.schema.json
 
 # Languages with dedicated overlays. `id` matches the detector in languages.yaml.
 # `aliases` are accepted on the CLI (e.g. `--lang ts`).

package/assets/schema/diagrams.schema.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/stevenzg/edsger-assets/schema/diagrams.schema.json",
+  "title": "Edsger Diagram Catalog",
+  "description": "A catalog of professional software diagrams an agent can generate for a repository. A `base` catalog is merged with zero or more language overlays to form the effective catalog. For each project the agent selects the diagrams whose `detect` signals and `appliesWhen` guidance match the repository's characteristics, then emits Mermaid source for each.",
+  "type": "object",
+  "required": ["id", "name", "version", "kind", "groups"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "kind": { "const": "diagrams" },
+    "extends": {
+      "description": "id of a catalog this overlay merges on top of (usually 'base').",
+      "type": ["string", "null"]
+    },
+    "appliesTo": {
+      "description": "Language ids this catalog targets, or ['*'] for any.",
+      "type": "array",
+      "items": { "type": "string" },
+      "default": ["*"]
+    },
+    "groups": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/group" }
+    }
+  },
+  "definitions": {
+    "group": {
+      "type": "object",
+      "required": ["id", "name", "diagrams"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "diagrams": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/definitions/diagram" }
+        }
+      }
+    },
+    "diagram": {
+      "type": "object",
+      "required": ["id", "title", "type", "appliesWhen", "guidance"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+        "title": { "type": "string" },
+        "type": {
+          "description": "The Mermaid diagram type to emit.",
+          "type": "string",
+          "enum": [
+            "flowchart",
+            "sequenceDiagram",
+            "classDiagram",
+            "stateDiagram-v2",
+            "erDiagram",
+            "journey",
+            "gantt",
+            "gitGraph",
+            "mindmap",
+            "timeline",
+            "requirementDiagram",
+            "quadrantChart",
+            "pie",
+            "sankey-beta",
+            "C4Context",
+            "C4Container",
+            "C4Component",
+            "C4Deployment",
+            "block-beta",
+            "architecture-beta"
+          ]
+        },
+        "appliesWhen": {
+          "description": "Prose describing the project characteristics that make this diagram valuable, so the agent can decide whether to include it.",
+          "type": "string"
+        },
+        "detect": {
+          "description": "Coarse signals (file globs, marker filenames, or keywords) that hint this diagram is relevant. '*' means 'almost always useful'. Advisory only — the agent still decides from real evidence.",
+          "type": "array",
+          "items": { "type": "string" },
+          "default": []
+        },
+        "guidance": {
+          "description": "How to construct this diagram from the repository: what to read, what nodes/edges to include, and how to keep it faithful and legible.",
+          "type": "string"
+        },
+        "references": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/assets/skills/diagram/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: diagram
+description: >
+  Generate professional software diagrams (architecture/C4, ER, sequence,
+  flowchart, class, state, data-flow, deployment, and more) tailored to a
+  repository's characteristics, as renderable Mermaid, and write them to a
+  viewable report. Use when the user asks to diagram, visualize, map, or chart a
+  codebase's architecture, database schema, request flow, or structure.
+---
+
+# Diagram a repository
+
+You will inspect the repository in the current working directory, decide which
+professional diagrams genuinely fit **this** project, and emit each as valid
+**Mermaid** so it renders in Markdown/HTML.
+
+## 1. Prefer the CLI if it is installed
+
+If the `edsger` CLI is available, it runs the agent and produces a viewable HTML
+dashboard — use it:
+
+```bash
+command -v edsger >/dev/null 2>&1 && edsger diagram || echo "no-cli"
+```
+
+If it ran, summarise `.edsger/diagrams/diagrams.md` for the user and stop.
+Otherwise continue with the native flow below.
+
+## 2. Detect the language(s)
+
+Look for manifest files to decide which overlays apply: `package.json`/`tsconfig.json`
+→ typescript; `pyproject.toml`/`requirements.txt` → python; `go.mod` → go;
+`*.csproj`/`*.sln` → csharp; `pom.xml`/`build.gradle` → java; `pubspec.yaml` → dart.
+A repo may match several.
+
+## 3. Load the catalog
+
+Read the base catalog and any matching language overlays from this plugin:
+
+- `${CLAUDE_PLUGIN_ROOT}/diagrams/base.yaml` (always)
+- `${CLAUDE_PLUGIN_ROOT}/diagrams/<language>.yaml` (for each detected language)
+
+Merge overlays onto the base **by id** (group ids and diagram ids). If the repo
+has a `.edsger/diagrams/` directory, those files override the bundled catalog.
+
+## 4. Profile the project and select diagrams
+
+Explore the repo (Read/Grep/Glob, read-only) and characterise it: what kind of
+project is it (service, library, CLI, SPA, data pipeline, monorepo…), what does
+it integrate with, does it own a database, does it deploy somewhere?
+
+For each catalog diagram, use its `detect` signals and `appliesWhen` guidance to
+decide whether it adds value **for this repo**. Only include diagrams the
+evidence supports — a library needs different diagrams than a microservice. Never
+invent structure that is not in the code.
+
+## 5. Generate faithful Mermaid
+
+For each selected diagram, follow its `guidance` and produce **valid Mermaid** of
+the specified `type`, grounded in real files (record the files as evidence). Keep
+each diagram to roughly one screen and legible; prefer faithful over exhaustive.
+Validate the Mermaid syntax mentally before emitting it.
+
+## 6. Write the report
+
+Write `.edsger/diagrams/diagrams.md` containing: a short project profile, then one
+section per diagram with a heading, a one-line description of what it shows and
+why it applies, the fenced ` ```mermaid ` block, and the evidence files. Group by
+catalog group (Architecture, Behaviour, Data, Deployment, Process). Then give the
+user a concise summary of which diagrams you produced and why.