jeremylongshore/tons-of-skills-marketplace / plugins/devops/engineer-design-diagram/skills/engineer-design-diagram
engineer-design-diagram
VerifiedGenerate production-grade engineering design diagrams (architecture, sequence, delta, drift) as self-contained dark-themed HTML files with accessible inline SVG. Grounds every diagram in real repo topology via DCI — package manifests, docker-compose, k8s, terraform, import graph. Four modes: generate from a live repo, diff a PR, trace a stack into a sequence diagram, or watch for drift against a fingerprint. Semantic OKLCH palette; Mermaid fallback for large graphs. Use when visualizing system architecture, reviewing a PR for structural change, diagnosing an incident from a trace, onboarding to a codebase, or detecting architectural drift. Trigger with "/design:generate", "/design:diff", "/design:trace", "/design:watch", "draw the architecture", "diagram this PR", "engineer design diagram", or "architecture diagram".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.7 KB |
| evals/evals.json | config | 3.3 KB |
| examples/aws-serverless.html | other | 9.4 KB |
| examples/microservices.html | other | 13.5 KB |
| examples/tiny-monorepo/expected-architecture.html | other | 7.8 KB |
| references/THIRD_PARTY_LICENSES.md | markdown | 2.3 KB |
| references/accessibility.md | markdown | 2.8 KB |
| references/dci-block.md | markdown | 3.3 KB |
| references/docs-layout.md | markdown | 16.6 KB |
| references/drawing-rules.md | markdown | 7.6 KB |
| references/fingerprint-spec.md | markdown | 5.1 KB |
| references/mode-playbooks.md | markdown | 5.4 KB |
| references/troubleshooting.md | markdown | 3.7 KB |
| scripts/collect_dci.shexecutable | script | 2.6 KB |
| scripts/fingerprint.pyexecutable | script | 6.8 KB |
| scripts/open_in_browser.shexecutable | script | 975 B |
| scripts/validate_html.pyexecutable | script | 3.2 KB |
| templates/base.html | other | 12.2 KB |
| templates/docs-layout.html | other | 21.4 KB |
| templates/mermaid-fallback.html | other | 2.2 KB |
| templates/sequence.html | other | 3.2 KB |
references/mode-playbooks.md
View on GitHub# Mode Playbooks
Per-mode workflows for engineer-design-diagram. Each playbook covers input contract, steps, output contract, and failure modes.
## Table of Contents
- [generate](#generate)
- [diff](#diff)
- [trace](#trace)
- [watch](#watch)
## generate
Produce an architecture view of the current repository.
**Input contract:**
- Current working directory is a git repo (or has discoverable manifests)
- Optional: `$ARGUMENTS[1]` = path to scope (default: repo root)
**Steps:**
1. Read DCI block output from SKILL.md activation.
2. Build node set from docker-compose services, k8s Deployments/Services, terraform resources, package manifest names.
3. Build edge set from `depends_on`, exposed ports + HTTP client imports (via Grep), k8s Service selectors, terraform resource references.
4. Classify each node's role per [drawing-rules.md § Role inference](drawing-rules.md#role-inference).
5. Fill `templates/base.html` per [drawing-rules.md](drawing-rules.md). Write to `$CWD/.arch/generate-<timestamp>.html`.
6. Write fingerprint via `scripts/fingerprint.py write`.
7. Run `scripts/validate_html.py` on output. If ARIA or no-externals check fails, re-fill template.
8. Echo Mermaid equivalent to chat.
9. Open HTML via `scripts/open_in_browser.sh`.
**Output contract:**
- `$CWD/.arch/generate-<ISO-timestamp>.html` — single-file HTML, offline-capable
- Mermaid text block in chat
- Updated `${CLAUDE_PLUGIN_DATA}/arch-state.json`
**Failure modes:**
- No manifests detected → ask user to describe system in prose, render prose-only diagram
- >50 nodes → auto-switch to `templates/mermaid-fallback.html`
- Layout collision detected → retry with Mermaid
## diff
Produce a before/after architecture view with delta highlighting, for PR review.
**Input contract:**
- Current branch is NOT the default branch
- Default branch discoverable via `origin/HEAD`, `main`, `master`, or `trunk`
**Steps:**
1. Probe default branch: `git symbolic-ref refs/remotes/origin/HEAD` → fallback chain.
2. Read prior fingerprint from `${CLAUDE_PLUGIN_DATA}/arch-state.json` if it exists, else generate from default branch checkout.
3. Re-run DCI on working tree (current branch).
4. Compute diff: `added_nodes`, `removed_nodes`, `changed_nodes` (role change), `added_edges`, `removed_edges`.
5. Fill `templates/base.html` with all nodes from the NEW state. Apply `class="delta-added"` / `delta-removed` / `delta-changed` per [drawing-rules.md § Delta Markers](drawing-rules.md#delta-markers-diff-mode).
6. Write output to `$CWD/.arch/diff-<timestamp>.html`.
7. Update fingerprint to reflect the new state.
8. Emit summary line: `Added N nodes, M edges. Removed X nodes, Y edges.`
**Output contract:**
- `$CWD/.arch/diff-<ISO-timestamp>.html` with delta classes on changed elements
- Mermaid text block
- One-line delta summary in chat
- Updated fingerprint
**Failure modes:**
- No default branch found → use `HEAD~1` as base, warn user
- Both branches have identical structure → output "No structural changes detected" and exit without writing
## trace
Render a sequence diagram from a stack trace, log span, or incident event.
**Input contract:**
- `$ARGUMENTS[1]` = path to trace file (required)
- Supported formats: Sentry JSON, OpenTelemetry span JSON, raw stack trace text
**Steps:**
1. Detect format by file shape: `.json` → inspect top-level keys; `.txt` or no extension → assume raw stack trace.
2. Parse using appropriate parser:
- **Sentry**: extract `exception.values[].stacktrace.frames[]` + `spans[]`
- **OTel**: parse `resourceSpans[].scopeSpans[].spans[]` by `parentSpanId` for call order
- **Raw**: regex `at ServiceName.methodName(file.ext:line)` lines
3. Collapse frames into lifelines (one per service/module).
4. Build message list with timestamps where available.
5. Fill `templates/sequence.html`. Mark the final/error arrow with `class="error"`.
6. Write to `$CWD/.arch/trace-<timestamp>.html`.
7. **Do not write fingerprint** (trace mode doesn't alter architectural state).
**Output contract:**
- `$CWD/.arch/trace-<ISO-timestamp>.html` with sequence diagram
- Mermaid `sequenceDiagram` text block
- No fingerprint write
**Failure modes:**
- Unknown format → emit Mermaid-only sequence with best-effort parsing, flag for user review
- <2 lifelines parseable → output "Trace too shallow for sequence diagram" with raw trace excerpt
## watch
Detect architectural drift by comparing current repo state against last stored fingerprint.
**Input contract:**
- `${CLAUDE_PLUGIN_DATA}/arch-state.json` exists (from a prior generate/diff run)
**Steps:**
1. Load prior fingerprint.
2. Re-run DCI on current working tree.
3. Build new node/edge graph.
4. Compute structural diff (same algorithm as diff mode, Step 4).
5. For each delta, cite the source file + line that justifies it (from DCI output and Grep).
6. Emit markdown report — **no HTML render** in watch mode.
**Output contract:**
- Markdown report with sections `Added`, `Removed`, `Changed`
- Each bullet cites `source:file:line`
- Final line: `New graph_fingerprint: <sha256>`
- Updated fingerprint (optional — ask user before overwriting if drift is significant)
**Failure modes:**
- No prior fingerprint → output "No baseline found. Run `/design:generate` first to establish a fingerprint."
- Schema version mismatch → output "Fingerprint schema drift. Run `/design:generate` to re-baseline."
- No drift detected → output "No structural drift since <prior timestamp>."
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |