- commit
- 0ef3936c78ab77acd3eb4c3b131eace690db15c2
- parent
- 8eb9305d6e92d5b78c144990407d3981883aec1c
- author
- Dami <dami.etoile@gmail.com>
@@ -1,15 +1,18 @@
11 import { readFile, readdir } from 'node:fs/promises'2-import { join, relative } from 'node:path'2+import { join, relative, resolve } from 'node:path'33 import { fileURLToPath } from 'node:url'44 import { diagramTypeIds, diagramTypes } from '../data/diagram-types.mjs'5+import { diagramSkillIds, diagramSkills, skillGroups, standardsSupport } from '../../skills/catalog.mjs'56 67 const site = join(fileURLToPath(new URL('..', import.meta.url)))78 const docs = join(site, 'docs')8-const publicFiles = [join(site, 'static', 'llms.txt'), join(site, 'static', 'llms-full.txt'), join(site, 'static', 'diagram-types.json')]9+const repo = join(site, '..')10+const publicFiles = [join(site, 'static', 'llms.txt'), join(site, 'static', 'llms-full.txt'), join(site, 'static', 'diagram-types.json'), join(site, 'static', 'diagram-skills.json')]911 const examples = join(site, 'static', 'examples')12+const skills = join(repo, 'skills')13+const publicSkills = join(site, 'static', 'skills')1014 const errors = []1115 const source = (path) => readFile(path, 'utf8')12-const repo = join(site, '..')1316 1417 function assert(condition, message) { if (!condition) errors.push(message) }1518 function idsFromNames(names) { return names.filter((name) => name.endsWith('.md')).map((name) => name.slice(0, -3)).sort() }@@ -22,6 +25,22 @@ async function filesBelow(directory) {
2225 return nested.flat()2326 }2427 28+function skillFrontmatter(content) {29+ const raw = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1]30+ if (!raw) return undefined31+ const value = (key) => {32+ const rawValue = raw.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1]?.trim()33+ return rawValue?.replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/, '$1$2')34+ }35+ return { raw, name: value('name'), description: value('description'), disableModelInvocation: value('disable-model-invocation') }36+}37+38+function relativeMarkdownLinks(content) {39+ return [...content.matchAll(/\[[^\]]*\]\(([^)]+\.md(?:#[^)]*)?)\)/g)]40+ .map((match) => match[1].split('#')[0])41+ .filter((target) => !/^[a-z]+:/i.test(target) && !target.startsWith('/'))42+}43+2544 function proseBlocks(markdown) {2645 const blocks = []2746 let paragraph = []@@ -97,6 +116,63 @@ try { catalog = JSON.parse(catalogRaw) } catch { errors.push('static/diagram-typ
97116 assert(catalog?.diagramTypes?.length === expected.length, 'Machine catalog does not contain all diagram types.')98117 assert(JSON.stringify((catalog?.diagramTypes ?? []).map(({ id }) => id).sort()) === JSON.stringify(expected), 'Machine catalog IDs do not match the diagram type catalog.')99118 119+const expectedSkillIds = [...diagramSkillIds].sort()120+const skillEntries = await readdir(skills, { withFileTypes: true })121+const actualSkillIds = skillEntries.filter((entry) => entry.isDirectory()).map(({ name }) => name).sort()122+const publicSkillIds = (await readdir(publicSkills, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map(({ name }) => name).sort()123+assert(diagramSkillIds.length === 39, `Expected 39 semantic skills, found ${diagramSkillIds.length} in the catalog.`)124+assert(new Set(diagramSkillIds).size === diagramSkillIds.length, 'Semantic skill catalog contains duplicate IDs.')125+assert(JSON.stringify(actualSkillIds) === JSON.stringify(expectedSkillIds), 'Source skill directories do not match the semantic skill catalog.')126+assert(JSON.stringify(publicSkillIds) === JSON.stringify(expectedSkillIds), 'Published skill directories do not match the semantic skill catalog.')127+128+const skillCatalogRaw = await source(join(site, 'static', 'diagram-skills.json'))129+let skillCatalog130+try { skillCatalog = JSON.parse(skillCatalogRaw) } catch { errors.push('static/diagram-skills.json is not valid JSON.') }131+assert(skillCatalog?.version === 1, 'Semantic skill catalog has the wrong version.')132+assert(JSON.stringify(skillCatalog?.groups ?? []) === JSON.stringify(skillGroups), 'Published semantic skill groups do not match the source catalog.')133+assert(JSON.stringify((skillCatalog?.skills ?? []).map(({ id }) => id).sort()) === JSON.stringify(expectedSkillIds), 'Published semantic skill IDs do not match the source catalog.')134+assert(JSON.stringify(skillCatalog?.standards ?? []) === JSON.stringify(standardsSupport), 'Published standards support data does not match the source catalog.')135+for (const standard of standardsSupport) {136+ assert(standard.relatedSkills.every((id) => diagramSkillIds.includes(id)), `Standard ${standard.id} references an unknown semantic skill.`)137+ assert(['source-supported', 'visual-subset', 'visual-conventions', 'unsupported'].includes(standard.status), `Standard ${standard.id} has an unknown support status.`)138+}139+140+for (const entry of diagramSkills) {141+ const skillFile = join(skills, entry.id, 'SKILL.md')142+ const content = await source(skillFile)143+ const metadata = skillFrontmatter(content)144+ assert(metadata, `Skill ${entry.id} has no valid frontmatter.`)145+ assert(metadata?.name === entry.id, `Skill ${entry.id} frontmatter name does not match its directory.`)146+ assert(Boolean(metadata?.description), `Skill ${entry.id} has no description.`)147+ assert((metadata?.description?.length ?? 0) <= 1024, `Skill ${entry.id} description exceeds 1024 characters.`)148+ assert(content.split('\n').length <= 500, `Skill ${entry.id} exceeds 500 lines.`)149+ assert(metadata?.disableModelInvocation !== 'false', `Skill ${entry.id} must omit disable-model-invocation instead of setting it false.`)150+ assert((metadata?.disableModelInvocation === 'true') === (entry.id === 'diagram-workshop'), `Skill ${entry.id} has the wrong invocation policy.`)151+ assert(!/kroki/i.test(content), `Forbidden project name found in skills/${entry.id}/SKILL.md.`)152+153+ const referenceDir = join(skills, entry.id, 'references')154+ const packageFiles = await filesBelow(join(skills, entry.id))155+ const referenceFiles = packageFiles.filter((path) => path.startsWith(`${referenceDir}/`) && path.endsWith('.md'))156+ for (const path of referenceFiles) {157+ assert(content.includes(relative(join(skills, entry.id), path)), `Skill ${entry.id} does not link reference ${relative(referenceDir, path)}.`)158+ }159+ for (const target of relativeMarkdownLinks(content)) {160+ const resolved = resolve(join(skills, entry.id), target)161+ assert(packageFiles.includes(resolved), `Skill ${entry.id} links missing file ${target}.`)162+ }163+ for (const path of packageFiles) {164+ const packageContent = await source(path)165+ assert(!/kroki/i.test(packageContent), `Forbidden project name found in ${relative(repo, path)}.`)166+ }167+168+ const publishedFiles = (await filesBelow(join(publicSkills, entry.id))).map((path) => relative(join(publicSkills, entry.id), path)).sort()169+ const sourceFiles = packageFiles.map((path) => relative(join(skills, entry.id), path)).sort()170+ assert(JSON.stringify(publishedFiles) === JSON.stringify(sourceFiles), `Published package ${entry.id} does not match its source files.`)171+}172+173+const workshopOpenAI = await source(join(skills, 'diagram-workshop', 'agents', 'openai.yaml'))174+assert(/allow_implicit_invocation:\s*false/.test(workshopOpenAI), 'Diagram workshop must disable implicit OpenAI invocation.')175+100176 for (const id of expected) {101177 const type = diagramTypes.find((item) => item.id === id)102178 const create = await source(join(docs, 'create', 'types', `${id}.md`))@@ -123,4 +199,4 @@ for (const path of [...documentationFiles, ...publicFiles]) {
123199 if (/\.mdx?$/.test(path)) checkProse(content, relative(docs, path))124200 }125201 126-if (errors.length) { console.error(errors.map((error) => `ERROR: ${error}`).join('\n')); process.exitCode = 1 } else console.log(`Documentation checks passed for ${expected.length} diagram types.`)202+if (errors.length) { console.error(errors.map((error) => `ERROR: ${error}`).join('\n')); process.exitCode = 1 } else console.log(`Documentation checks passed for ${expected.length} renderer types and ${expectedSkillIds.length} semantic skills.`)@@ -1,7 +1,8 @@
1-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'1+import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'22 import { dirname, join } from 'node:path'33 import { fileURLToPath } from 'node:url'44 import { diagramTypes } from '../data/diagram-types.mjs'5+import { diagramSkills, skillGroups, standardsSupport } from '../../skills/catalog.mjs'56 67 const root = dirname(fileURLToPath(import.meta.url))78 const site = join(root, '..')@@ -10,6 +11,9 @@ const typesDir = join(docs, 'create', 'types')
1011 const styleDir = join(docs, 'style', 'types')1112 const staticDir = join(site, 'static')1213 const examplesDir = join(staticDir, 'examples')14+const repo = join(site, '..')15+const skillsDir = join(repo, 'skills')16+const publicSkillsDir = join(staticDir, 'skills')1317 1418 const completeExampleFixtures = {1519 bpmn: 'example.bpmn',@@ -38,6 +42,34 @@ const syntaxPath = (id) => `/create/types/${id}`
3842 const stylePath = (id) => `/style/types/${id}`3943 const articleFor = (label) => /^[aeiou]/i.test(label) ? 'an' : 'a'4044 45+function frontmatterValue(content, key) {46+ const block = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] ?? ''47+ const value = block.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1]?.trim()48+ if (!value) return undefined49+ if (value.startsWith('"') && value.endsWith('"')) {50+ try { return JSON.parse(value) } catch { return value.slice(1, -1) }51+ }52+ if (value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1).replace(/''/g, "'")53+ return value54+}55+56+const skillSources = Object.fromEntries(await Promise.all(diagramSkills.map(async (entry) => {57+ const content = await readFile(join(skillsDir, entry.id, 'SKILL.md'), 'utf8')58+ return [entry.id, {59+ ...entry,60+ name: frontmatterValue(content, 'name'),61+ description: frontmatterValue(content, 'description'),62+ userInvokableOnly: frontmatterValue(content, 'disable-model-invocation') === 'true',63+ path: `/skills/${entry.id}/SKILL.md`,64+ }]65+})))66+67+const skillCatalog = diagramSkills.map(({ id }) => skillSources[id])68+const skillIndex = () => skillGroups.map((group) => {69+ const entries = skillCatalog.filter((entry) => entry.group === group.id)70+ return `## ${group.label}\n\n${entries.map((entry) => `- [${entry.label}](https://docs.diagram.zip${entry.path}): ${entry.description}${entry.userInvokableOnly ? ' Explicit user invocation only.' : ''}`).join('\n')}`71+}).join('\n\n')72+4173 function frontmatter(type, section, description) {4274 return `---\nid: ${section}-${type.id}\nslug: /${section}/types/${type.id}\ntitle: ${type.label}\ndescription: ${description}\nsidebar_label: ${type.label}\n---\n\n`4375 }@@ -99,18 +131,22 @@ const fullText = () => diagramTypes.map((type) => `${syntaxPage(type, false)}\n$
99131 await rm(join(docs, 'create', 'types'), { recursive: true, force: true })100132 await rm(join(docs, 'style', 'types'), { recursive: true, force: true })101133 await rm(examplesDir, { recursive: true, force: true })134+await rm(publicSkillsDir, { recursive: true, force: true })102135 await mkdir(typesDir, { recursive: true })103136 await mkdir(styleDir, { recursive: true })104137 await mkdir(staticDir, { recursive: true })105138 await mkdir(examplesDir, { recursive: true })139+await mkdir(publicSkillsDir, { recursive: true })106140 107141 await Promise.all(diagramTypes.flatMap((type) => [108142 writeFile(join(typesDir, `${type.id}.md`), syntaxPage(type)),109143 writeFile(join(styleDir, `${type.id}.md`), stylePage(type)),110144 writeFile(join(examplesDir, `${type.id}.json`), `${JSON.stringify(completeExamples[type.id], null, 2)}\n`),111145 ]))146+await Promise.all(diagramSkills.map(({ id }) => cp(join(skillsDir, id), join(publicSkillsDir, id), { recursive: true })))112147 await writeFile(join(staticDir, 'diagram-types.json'), `${JSON.stringify({ version: 1, diagramTypes: catalog }, null, 2)}\n`)113-await writeFile(join(staticDir, 'llms.txt'), `# diagram.zip documentation\n\n> Use these stable pages to create, style, save, and share diagrams.\n\n${diagramTypes.map((type) => `- [${type.label} syntax](https://docs.diagram.zip${syntaxPath(type.id)}/): Create ${articleFor(type.label)} ${type.label} diagram. [Style](https://docs.diagram.zip${stylePath(type.id)}/).`).join('\n')}\n\n## General pages\n\n- [General presentation](https://docs.diagram.zip/style/presentation/)\n- [Share a diagram](https://docs.diagram.zip/collaboration/sharing/)\n- [Password encryption](https://docs.diagram.zip/collaboration/encryption/)\n- [Working state and saved state](https://docs.diagram.zip/collaboration/working-and-saved-state/)\n\n## Structured catalog\n\n- [diagram-types.json](https://docs.diagram.zip/diagram-types.json)\n- [Full text reference](https://docs.diagram.zip/llms-full.txt)\n- [Source repository](https://github.com/FelineStateMachine/diagramzip)\n`)148+await writeFile(join(staticDir, 'diagram-skills.json'), `${JSON.stringify({ version: 1, groups: skillGroups, skills: skillCatalog, standards: standardsSupport }, null, 2)}\n`)149+await writeFile(join(staticDir, 'llms.txt'), `# diagram.zip documentation\n\n> Choose the semantic story first, then choose a renderer and source format.\n\n- [Diagram routing skill](https://docs.diagram.zip/skills/diagramming/SKILL.md): Select a diagram family from the reader's question.\n- [Machine-readable semantic catalog](https://docs.diagram.zip/diagram-skills.json): Inspect every skill, use case, exclusion, role, and invocation constraint.\n\n${skillIndex()}\n\n## Renderer and source formats\n\n${diagramTypes.map((type) => `- [${type.label} syntax](https://docs.diagram.zip${syntaxPath(type.id)}/): Create ${articleFor(type.label)} ${type.label} diagram. [Style](https://docs.diagram.zip${stylePath(type.id)}/).`).join('\n')}\n\n## General pages\n\n- [General presentation](https://docs.diagram.zip/style/presentation/)\n- [Share a diagram](https://docs.diagram.zip/collaboration/sharing/)\n- [Password encryption](https://docs.diagram.zip/collaboration/encryption/)\n- [Working state and saved state](https://docs.diagram.zip/collaboration/working-and-saved-state/)\n\n## Structured catalogs\n\n- [diagram-skills.json](https://docs.diagram.zip/diagram-skills.json)\n- [diagram-types.json](https://docs.diagram.zip/diagram-types.json)\n- [Full renderer text reference](https://docs.diagram.zip/llms-full.txt)\n- [Source repository](https://github.com/FelineStateMachine/diagramzip)\n`)114150 await writeFile(join(staticDir, 'llms-full.txt'), `# diagram.zip documentation\n\n${fullText()}`)115151 116-console.log(`Generated ${diagramTypes.length} creation pages, ${diagramTypes.length} style pages, and machine-readable indexes.`)152+console.log(`Generated ${diagramTypes.length} renderer guides, ${diagramSkills.length} semantic skill packages, and machine-readable indexes.`)@@ -0,0 +1,886 @@
1+{2+ "version": 1,3+ "groups": [4+ {5+ "id": "workflow",6+ "label": "Routing and collaboration"7+ },8+ {9+ "id": "behavior",10+ "label": "Behavior and process"11+ },12+ {13+ "id": "architecture",14+ "label": "Software and system structure"15+ },16+ {17+ "id": "conceptual",18+ "label": "Conceptual and planning"19+ },20+ {21+ "id": "data",22+ "label": "Data visualization"23+ },24+ {25+ "id": "technical",26+ "label": "Technical and hardware"27+ }28+ ],29+ "skills": [30+ {31+ "id": "diagramming",32+ "label": "Choose a diagram",33+ "group": "workflow",34+ "role": "router",35+ "question": "Which visual story best answers the reader's question?",36+ "useCases": [37+ "Route a diagram request by meaning",38+ "Choose a renderer after choosing the story"39+ ],40+ "avoidWhen": [41+ "The user already selected a semantic diagram type"42+ ],43+ "name": "diagramming",44+ "description": "Choose the semantic diagram story first, then select a diagram.zip renderer and produce a clear, reviewable diagram.",45+ "userInvokableOnly": false,46+ "path": "/skills/diagramming/SKILL.md"47+ },48+ {49+ "id": "diagram-workshop",50+ "label": "Diagram workshop",51+ "group": "workflow",52+ "role": "workflow",53+ "question": "What should we discover together before committing to a diagram?",54+ "useCases": [55+ "Facilitate an explicit, user-led diagram design session"56+ ],57+ "avoidWhen": [58+ "A focused request can be handled directly"59+ ],60+ "name": "diagram-workshop",61+ "description": "Work with me to discover the right diagram question, audience, scope, and level of detail before making a diagram.",62+ "userInvokableOnly": true,63+ "path": "/skills/diagram-workshop/SKILL.md"64+ },65+ {66+ "id": "diagram-review",67+ "label": "Review a diagram",68+ "group": "workflow",69+ "role": "Does the diagram tell its intended story accurately and accessibly?",70+ "question": [71+ "Review semantics, readability, fidelity, and accessibility"72+ ],73+ "useCases": [74+ "The request is only to choose a diagram family"75+ ],76+ "name": "diagram-review",77+ "description": "Review a proposed diagram for semantic fit, evidence, readability, accessibility, and renderer or standards limitations; recommend precise revisions.",78+ "userInvokableOnly": false,79+ "path": "/skills/diagram-review/SKILL.md"80+ },81+ {82+ "id": "flowchart",83+ "label": "Flowchart",84+ "group": "behavior",85+ "role": "diagram",86+ "question": "What path does work follow through steps and decisions?",87+ "useCases": [88+ "Procedures",89+ "Algorithms",90+ "Decision-heavy workflows"91+ ],92+ "avoidWhen": [93+ "Time-ordered interactions need lifelines",94+ "Formal business semantics require BPMN"95+ ],96+ "name": "flowchart",97+ "description": "Choose a flowchart when the user needs a readable decision or process path with a clear start, sequence, branch, merge, or end.",98+ "userInvokableOnly": false,99+ "path": "/skills/flowchart/SKILL.md"100+ },101+ {102+ "id": "sequence-diagram",103+ "label": "Sequence diagram",104+ "group": "behavior",105+ "role": "diagram",106+ "question": "Who communicates with whom, and in what order?",107+ "useCases": [108+ "API calls",109+ "Runtime collaborations",110+ "Request and response flows"111+ ],112+ "avoidWhen": [113+ "The main story is static structure"114+ ],115+ "name": "sequence-diagram",116+ "description": "Choose a sequence diagram when the user needs to explain ordered messages, calls, responses, or time-dependent collaboration between participants.",117+ "userInvokableOnly": false,118+ "path": "/skills/sequence-diagram/SKILL.md"119+ },120+ {121+ "id": "state-machine-diagram",122+ "label": "State machine diagram",123+ "group": "behavior",124+ "role": "diagram",125+ "question": "Which events cause an entity to change state?",126+ "useCases": [127+ "Lifecycle rules",128+ "Protocol states",129+ "UI state transitions"130+ ],131+ "avoidWhen": [132+ "The story is a sequence of work rather than persistent state"133+ ],134+ "name": "state-machine-diagram",135+ "description": "Choose a state-machine diagram when an entity's permitted states, event-triggered transitions, guards, and entry or exit behavior are the central story.",136+ "userInvokableOnly": false,137+ "path": "/skills/state-machine-diagram/SKILL.md"138+ },139+ {140+ "id": "activity-diagram",141+ "label": "Activity diagram",142+ "group": "behavior",143+ "role": "diagram",144+ "question": "How does work flow across actions, branches, and owners?",145+ "useCases": [146+ "Concurrent workflows",147+ "Swimlane processes",148+ "UML behavioral modeling"149+ ],150+ "avoidWhen": [151+ "The process requires executable BPMN semantics"152+ ],153+ "name": "activity-diagram",154+ "description": "Choose an activity diagram when the user needs to explain workflow logic, parallel work, decisions, joins, and responsibility across actions.",155+ "userInvokableOnly": false,156+ "path": "/skills/activity-diagram/SKILL.md"157+ },158+ {159+ "id": "bpmn-process",160+ "label": "BPMN process",161+ "group": "behavior",162+ "role": "diagram",163+ "question": "How does a formal business process coordinate work, events, and participants?",164+ "useCases": [165+ "Auditable business processes",166+ "Message flows",167+ "Exception and event handling"168+ ],169+ "avoidWhen": [170+ "A lightweight explanatory flow is sufficient"171+ ],172+ "name": "bpmn-process",173+ "description": "Choose BPMN when the user needs a formal business-process model with events, tasks, gateways, pools, lanes, and message or sequence flows.",174+ "userInvokableOnly": false,175+ "path": "/skills/bpmn-process/SKILL.md"176+ },177+ {178+ "id": "use-case-diagram",179+ "label": "Use-case diagram",180+ "group": "behavior",181+ "role": "diagram",182+ "question": "Which actors pursue which goals through the system?",183+ "useCases": [184+ "Scope conversations",185+ "Actor goals",186+ "System boundary discussions"187+ ],188+ "avoidWhen": [189+ "Detailed interaction order or internal design is required"190+ ],191+ "name": "use-case-diagram",192+ "description": "Use when the user needs to explain who can achieve which externally visible goals with a system, including actors, system boundaries, and goal relationships.",193+ "userInvokableOnly": false,194+ "path": "/skills/use-case-diagram/SKILL.md"195+ },196+ {197+ "id": "data-flow-diagram",198+ "label": "Data-flow diagram",199+ "group": "behavior",200+ "role": "diagram",201+ "question": "Where does data originate, move, transform, and rest?",202+ "useCases": [203+ "Information flows",204+ "Trust-boundary analysis",205+ "Data-processing overviews"206+ ],207+ "avoidWhen": [208+ "Control flow or message timing is the main concern"209+ ],210+ "name": "data-flow-diagram",211+ "description": "Use when the user needs to show where information originates, how processes transform it, where stores retain it, and which external entities exchange it.",212+ "userInvokableOnly": false,213+ "path": "/skills/data-flow-diagram/SKILL.md"214+ },215+ {216+ "id": "timeline",217+ "label": "Timeline",218+ "group": "behavior",219+ "role": "diagram",220+ "question": "What happened, or will happen, in chronological order?",221+ "useCases": [222+ "Milestones",223+ "Historical narratives",224+ "Release evolution"225+ ],226+ "avoidWhen": [227+ "Durations and dependencies drive the story"228+ ],229+ "name": "timeline",230+ "description": "Use when the user needs to communicate events or milestones in chronological order, with dates, intervals, eras, or parallel tracks.",231+ "userInvokableOnly": false,232+ "path": "/skills/timeline/SKILL.md"233+ },234+ {235+ "id": "gantt-chart",236+ "label": "Gantt chart",237+ "group": "behavior",238+ "role": "diagram",239+ "question": "When do tasks occur, overlap, and depend on each other?",240+ "useCases": [241+ "Project schedules",242+ "Critical dependencies",243+ "Delivery planning"244+ ],245+ "avoidWhen": [246+ "Only milestone chronology is needed"247+ ],248+ "name": "gantt-chart",249+ "description": "Use when the user needs a time-scaled schedule showing tasks, durations, dependencies, milestones, and progress across teams or workstreams.",250+ "userInvokableOnly": false,251+ "path": "/skills/gantt-chart/SKILL.md"252+ },253+ {254+ "id": "user-journey-map",255+ "label": "User journey map",256+ "group": "behavior",257+ "role": "diagram",258+ "question": "What does a person experience across stages of a goal?",259+ "useCases": [260+ "Experience mapping",261+ "Touchpoints",262+ "Pain points and opportunities"263+ ],264+ "avoidWhen": [265+ "The request is for system behavior without a user-experience lens"266+ ],267+ "name": "user-journey-map",268+ "description": "Use when the user needs to understand a person’s experience across stages, touchpoints, actions, thoughts, emotions, pain points, and opportunities.",269+ "userInvokableOnly": false,270+ "path": "/skills/user-journey-map/SKILL.md"271+ },272+ {273+ "id": "choose-architecture-diagram",274+ "label": "Choose an architecture diagram",275+ "group": "architecture",276+ "role": "router",277+ "question": "Which abstraction level and viewpoint will answer the architecture question?",278+ "useCases": [279+ "Route among landscape, context, container, component, dynamic, and deployment views"280+ ],281+ "avoidWhen": [282+ "The user already selected an architecture view"283+ ],284+ "name": "choose-architecture-diagram",285+ "description": "Choose the smallest architecture view that answers the stakeholder's question, then route it to a suitable diagram source.",286+ "userInvokableOnly": false,287+ "path": "/skills/choose-architecture-diagram/SKILL.md"288+ },289+ {290+ "id": "system-landscape-diagram",291+ "label": "System landscape diagram",292+ "group": "architecture",293+ "role": "diagram",294+ "question": "How do systems and people relate across an organization or domain?",295+ "useCases": [296+ "Enterprise system portfolios",297+ "Cross-system dependencies",298+ "Ownership context"299+ ],300+ "avoidWhen": [301+ "The focus is one system and its immediate environment"302+ ],303+ "name": "system-landscape-diagram",304+ "description": "Show the systems and people across an organization or domain, emphasizing ownership and meaningful dependencies.",305+ "userInvokableOnly": false,306+ "path": "/skills/system-landscape-diagram/SKILL.md"307+ },308+ {309+ "id": "system-context-diagram",310+ "label": "System context diagram",311+ "group": "architecture",312+ "role": "diagram",313+ "question": "How does one system interact with people and external systems?",314+ "useCases": [315+ "C4 system context",316+ "Scope and boundary communication"317+ ],318+ "avoidWhen": [319+ "Internal applications or deployable units must be shown"320+ ],321+ "name": "system-context-diagram",322+ "description": "Explain one system in its environment by showing its users, external systems, and the relationships that matter.",323+ "userInvokableOnly": false,324+ "path": "/skills/system-context-diagram/SKILL.md"325+ },326+ {327+ "id": "container-diagram",328+ "label": "Container diagram",329+ "group": "architecture",330+ "role": "diagram",331+ "question": "What deployable or runnable units make up the system?",332+ "useCases": [333+ "C4 containers",334+ "Technology responsibilities",335+ "Inter-container communication"336+ ],337+ "avoidWhen": [338+ "Code-level components or infrastructure instances are the focus"339+ ],340+ "name": "container-diagram",341+ "description": "Show the major deployable or runtime containers inside one software system and how they collaborate.",342+ "userInvokableOnly": false,343+ "path": "/skills/container-diagram/SKILL.md"344+ },345+ {346+ "id": "component-diagram",347+ "label": "Component diagram",348+ "group": "architecture",349+ "role": "diagram",350+ "question": "Which components collaborate inside a container or subsystem?",351+ "useCases": [352+ "C4 components",353+ "UML components",354+ "Module responsibility"355+ ],356+ "avoidWhen": [357+ "Only system-level scope is needed"358+ ],359+ "name": "component-diagram",360+ "description": "Create a component-level view of software structure, interfaces, and dependencies when the audience needs implementation boundaries rather than deployment topology.",361+ "userInvokableOnly": false,362+ "path": "/skills/component-diagram/SKILL.md"363+ },364+ {365+ "id": "architecture-dynamic-diagram",366+ "label": "Architecture dynamic diagram",367+ "group": "architecture",368+ "role": "diagram",369+ "question": "How do architecture elements collaborate for one scenario?",370+ "useCases": [371+ "C4 dynamic views",372+ "Cross-boundary runtime stories"373+ ],374+ "avoidWhen": [375+ "A reusable protocol sequence needs detailed lifelines"376+ ],377+ "name": "architecture-dynamic-diagram",378+ "description": "Explain an architecture scenario over time by showing participating components, messages, and state changes for one concrete use case.",379+ "userInvokableOnly": false,380+ "path": "/skills/architecture-dynamic-diagram/SKILL.md"381+ },382+ {383+ "id": "deployment-diagram",384+ "label": "Deployment diagram",385+ "group": "architecture",386+ "role": "diagram",387+ "question": "Where do software instances run, and how are they connected?",388+ "useCases": [389+ "Runtime topology",390+ "Infrastructure mapping",391+ "C4 or UML deployment views"392+ ],393+ "avoidWhen": [394+ "Logical structure without runtime placement is enough"395+ ],396+ "name": "deployment-diagram",397+ "description": "Show where software artifacts run, which infrastructure nodes host them, and how runtime communication crosses environments or trust boundaries.",398+ "userInvokableOnly": false,399+ "path": "/skills/deployment-diagram/SKILL.md"400+ },401+ {402+ "id": "block-diagram",403+ "label": "Block diagram",404+ "group": "architecture",405+ "role": "diagram",406+ "question": "What are the major functional blocks and their interfaces?",407+ "useCases": [408+ "Functional decomposition",409+ "System overviews",410+ "Signal or responsibility boundaries"411+ ],412+ "avoidWhen": [413+ "A stricter domain notation is required"414+ ],415+ "name": "block-diagram",416+ "description": "Arrange labeled blocks and relationships to communicate system decomposition, signal or data paths, and high-level structure without committing to a specialized formal notation.",417+ "userInvokableOnly": false,418+ "path": "/skills/block-diagram/SKILL.md"419+ },420+ {421+ "id": "class-diagram",422+ "label": "Class diagram",423+ "group": "architecture",424+ "role": "diagram",425+ "question": "What types exist and how are their structures related?",426+ "useCases": [427+ "Domain models",428+ "Object-oriented design",429+ "Static type relationships"430+ ],431+ "avoidWhen": [432+ "The main story concerns data persistence tables"433+ ],434+ "name": "class-diagram",435+ "description": "Create or review class diagrams that explain types, responsibilities, contracts, and structural relationships in an object-oriented or domain model.",436+ "userInvokableOnly": false,437+ "path": "/skills/class-diagram/SKILL.md"438+ },439+ {440+ "id": "entity-relationship-diagram",441+ "label": "Entity-relationship diagram",442+ "group": "architecture",443+ "role": "diagram",444+ "question": "Which data entities exist and how are they related?",445+ "useCases": [446+ "Conceptual data models",447+ "Relational schemas",448+ "Cardinality review"449+ ],450+ "avoidWhen": [451+ "Runtime object behavior is the focus"452+ ],453+ "name": "entity-relationship-diagram",454+ "description": "Model persistent data with entities, attributes, keys, relationships, cardinality, optionality, and integrity boundaries using an entity-relationship diagram.",455+ "userInvokableOnly": false,456+ "path": "/skills/entity-relationship-diagram/SKILL.md"457+ },458+ {459+ "id": "dependency-graph",460+ "label": "Dependency graph",461+ "group": "architecture",462+ "role": "diagram",463+ "question": "What depends on what, and where are cycles or critical paths?",464+ "useCases": [465+ "Package dependencies",466+ "Build graphs",467+ "Service dependencies"468+ ],469+ "avoidWhen": [470+ "Ordered interactions or physical topology are central"471+ ],472+ "name": "dependency-graph",473+ "description": "Show dependencies between packages, modules, services, artifacts, or concepts when the important story is coupling, direction, reachability, or change impact.",474+ "userInvokableOnly": false,475+ "path": "/skills/dependency-graph/SKILL.md"476+ },477+ {478+ "id": "network-topology",479+ "label": "Network topology",480+ "group": "architecture",481+ "role": "diagram",482+ "question": "Which network zones, devices, and links connect?",483+ "useCases": [484+ "Logical networks",485+ "Addressed segments",486+ "Connectivity and trust boundaries"487+ ],488+ "avoidWhen": [489+ "Application behavior rather than connectivity is the focus"490+ ],491+ "name": "network-topology",492+ "description": "Document physical or logical networks with nodes, interfaces, links, segments, addressing, trust zones, and traffic boundaries.",493+ "userInvokableOnly": false,494+ "path": "/skills/network-topology/SKILL.md"495+ },496+ {497+ "id": "mind-map",498+ "label": "Mind map",499+ "group": "conceptual",500+ "role": "diagram",501+ "question": "What ideas radiate from one central topic?",502+ "useCases": [503+ "Brainstorming",504+ "Early exploration",505+ "Topic decomposition"506+ ],507+ "avoidWhen": [508+ "Relationships need explicit semantic labels"509+ ],510+ "name": "mind-map",511+ "description": "Use when the user needs to explore one central topic through associative branches, capture brainstorming, or organize an unconstrained idea space before choosing a structure.",512+ "userInvokableOnly": false,513+ "path": "/skills/mind-map/SKILL.md"514+ },515+ {516+ "id": "concept-map",517+ "label": "Concept map",518+ "group": "conceptual",519+ "role": "diagram",520+ "question": "Which concepts relate, and what do those relationships mean?",521+ "useCases": [522+ "Knowledge models",523+ "Explanatory relationship networks"524+ ],525+ "avoidWhen": [526+ "A single-root hierarchy is sufficient"527+ ],528+ "name": "concept-map",529+ "description": "Use when the user needs to explain concepts and the labeled relationships between them, especially definitions, dependencies, evidence, or cross-domain connections.",530+ "userInvokableOnly": false,531+ "path": "/skills/concept-map/SKILL.md"532+ },533+ {534+ "id": "hierarchy-diagram",535+ "label": "Hierarchy diagram",536+ "group": "conceptual",537+ "role": "diagram",538+ "question": "How is a set organized into parent-child levels?",539+ "useCases": [540+ "Trees",541+ "Organization charts",542+ "Work breakdown structures"543+ ],544+ "avoidWhen": [545+ "Many-to-many relationships carry the meaning"546+ ],547+ "name": "hierarchy-diagram",548+ "description": "Use when the user needs a ranked, nested, or reporting structure such as a taxonomy, organization chart, tree, or work breakdown structure.",549+ "userInvokableOnly": false,550+ "path": "/skills/hierarchy-diagram/SKILL.md"551+ },552+ {553+ "id": "decision-tree",554+ "label": "Decision tree",555+ "group": "conceptual",556+ "role": "diagram",557+ "question": "Which choices or tests lead to which outcomes?",558+ "useCases": [559+ "Decision guidance",560+ "Classification logic",561+ "Scenario branching"562+ ],563+ "avoidWhen": [564+ "The goal is to depict an operational process with loops"565+ ],566+ "name": "decision-tree",567+ "description": "Use when the user needs to show a sequence of choices, branching rules, outcomes, or diagnostic paths.",568+ "userInvokableOnly": false,569+ "path": "/skills/decision-tree/SKILL.md"570+ },571+ {572+ "id": "matrix-diagram",573+ "label": "Matrix diagram",574+ "group": "conceptual",575+ "role": "diagram",576+ "question": "How do items compare across two dimensions?",577+ "useCases": [578+ "Quadrants",579+ "Responsibility matrices",580+ "Pairwise relationship grids"581+ ],582+ "avoidWhen": [583+ "Geometric set overlap or time is the main encoding"584+ ],585+ "name": "matrix-diagram",586+ "description": "Use when the user needs to compare two dimensions, expose a portfolio or prioritization space, or show a many-to-many relationship in a grid or quadrant.",587+ "userInvokableOnly": false,588+ "path": "/skills/matrix-diagram/SKILL.md"589+ },590+ {591+ "id": "set-diagram",592+ "label": "Set diagram",593+ "group": "conceptual",594+ "role": "diagram",595+ "question": "How do categories overlap or contain one another?",596+ "useCases": [597+ "Venn diagrams",598+ "Euler diagrams",599+ "Set relationships"600+ ],601+ "avoidWhen": [602+ "Exact quantities or many sets must be compared"603+ ],604+ "name": "set-diagram",605+ "description": "Use when the user needs to show membership, overlap, exclusion, union, intersection, or nested categories with sets.",606+ "userInvokableOnly": false,607+ "path": "/skills/set-diagram/SKILL.md"608+ },609+ {610+ "id": "choose-data-visualization",611+ "label": "Choose a data visualization",612+ "group": "data",613+ "role": "router",614+ "question": "Which visual encoding best supports the analytical task and data?",615+ "useCases": [616+ "Comparison",617+ "Trend",618+ "Distribution",619+ "Relationship",620+ "Composition",621+ "Flow",622+ "Geography"623+ ],624+ "avoidWhen": [625+ "The request is a conceptual diagram rather than a quantitative display"626+ ],627+ "name": "choose-data-visualization",628+ "description": "Choose and design a data visualization when the user has data, a comparison, trend, distribution, relationship, flow, or geographic question but has not yet chosen a chart form. Use the simplest honest encoding, explain the story, and route the result to Vega or Vega-Lite when appropriate.",629+ "userInvokableOnly": false,630+ "path": "/skills/choose-data-visualization/SKILL.md"631+ },632+ {633+ "id": "protocol-layout-diagram",634+ "label": "Protocol layout diagram",635+ "group": "technical",636+ "role": "diagram",637+ "question": "How are bits or bytes allocated within a protocol record?",638+ "useCases": [639+ "Packet headers",640+ "Binary formats",641+ "Byte-field documentation"642+ ],643+ "avoidWhen": [644+ "Message ordering or state transitions are the focus"645+ ],646+ "name": "protocol-layout-diagram",647+ "description": "Use when a diagram must explain the bit, byte, or word layout of a protocol message, file header, register, or binary record.",648+ "userInvokableOnly": false,649+ "path": "/skills/protocol-layout-diagram/SKILL.md"650+ },651+ {652+ "id": "digital-timing-diagram",653+ "label": "Digital timing diagram",654+ "group": "technical",655+ "role": "diagram",656+ "question": "How do digital signals change relative to time and each other?",657+ "useCases": [658+ "Clocked logic",659+ "Bus transactions",660+ "Signal constraints"661+ ],662+ "avoidWhen": [663+ "The request is for an analog waveform plot"664+ ],665+ "name": "digital-timing-diagram",666+ "description": "Use when a diagram must show digital signals changing over time, including clocked interfaces, bus transactions, handshakes, setup/hold relationships, or waveform protocols.",667+ "userInvokableOnly": false,668+ "path": "/skills/digital-timing-diagram/SKILL.md"669+ },670+ {671+ "id": "rack-diagram",672+ "label": "Rack diagram",673+ "group": "technical",674+ "role": "diagram",675+ "question": "Which equipment occupies each rack unit?",676+ "useCases": [677+ "Capacity planning",678+ "Datacenter documentation",679+ "Equipment placement"680+ ],681+ "avoidWhen": [682+ "Logical network connectivity is the primary story"683+ ],684+ "name": "rack-diagram",685+ "description": "Use when documenting equipment placement in a cabinet or rack, including rack units, device identity, power, network uplinks, and physical capacity.",686+ "userInvokableOnly": false,687+ "path": "/skills/rack-diagram/SKILL.md"688+ },689+ {690+ "id": "wiring-harness-diagram",691+ "label": "Wiring harness diagram",692+ "group": "technical",693+ "role": "diagram",694+ "question": "How do connectors, conductors, and terminations map?",695+ "useCases": [696+ "Harness assembly",697+ "Pin-to-pin connectivity",698+ "Cable documentation"699+ ],700+ "avoidWhen": [701+ "Circuit behavior or board-level electronics are the focus"702+ ],703+ "name": "wiring-harness-diagram",704+ "description": "Use when the user needs to document wires, cables, connectors, splices, branches, pin mappings, or harness manufacturing/service information.",705+ "userInvokableOnly": false,706+ "path": "/skills/wiring-harness-diagram/SKILL.md"707+ },708+ {709+ "id": "hdl-component-diagram",710+ "label": "HDL component diagram",711+ "group": "technical",712+ "role": "diagram",713+ "question": "How do HDL modules, ports, and signal paths connect?",714+ "useCases": [715+ "RTL hierarchy",716+ "Module interfaces",717+ "Hardware design review"718+ ],719+ "avoidWhen": [720+ "Gate-level timing or physical wiring is the focus"721+ ],722+ "name": "hdl-component-diagram",723+ "description": "Use when the user needs a hardware-design view of HDL entities, modules, interfaces, ports, parameters, clocks, resets, and hierarchy.",724+ "userInvokableOnly": false,725+ "path": "/skills/hdl-component-diagram/SKILL.md"726+ },727+ {728+ "id": "circuit-diagram",729+ "label": "Circuit diagram",730+ "group": "technical",731+ "role": "diagram",732+ "question": "Which electronic components connect into a circuit?",733+ "useCases": [734+ "Schematic communication",735+ "Electrical connectivity",736+ "Circuit explanation"737+ ],738+ "avoidWhen": [739+ "Physical harness routing or enclosure placement is needed"740+ ],741+ "name": "circuit-diagram",742+ "description": "Use when the user needs an electrical or electronic schematic showing components, nets, reference designators, power, signal flow, and test points.",743+ "userInvokableOnly": false,744+ "path": "/skills/circuit-diagram/SKILL.md"745+ },746+ {747+ "id": "technical-illustration",748+ "label": "Technical illustration",749+ "group": "technical",750+ "role": "diagram",751+ "question": "Which spatial or mechanical relationships must the reader see?",752+ "useCases": [753+ "Exploded views",754+ "Annotated assemblies",755+ "Physical instructions"756+ ],757+ "avoidWhen": [758+ "Abstract relationships can be communicated more precisely with a diagram notation"759+ ],760+ "name": "technical-illustration",761+ "description": "Use when the user needs an explanatory technical figure showing parts, assemblies, operation, dimensions, callouts, or a controlled visual sequence.",762+ "userInvokableOnly": false,763+ "path": "/skills/technical-illustration/SKILL.md"764+ }765+ ],766+ "standards": [767+ {768+ "id": "bpmn-2.0.2",769+ "name": "OMG BPMN 2.0.2",770+ "status": "source-supported",771+ "relatedSkills": [772+ "bpmn-process"773+ ],774+ "note": "The BPMN renderer accepts BPMN 2.0 XML and diagram interchange data. Treat rendering as separate from complete semantic validation.",775+ "source": "https://www.omg.org/spec/BPMN/2.0.2/"776+ },777+ {778+ "id": "uml-2.5.1",779+ "name": "OMG UML 2.5.1",780+ "status": "visual-subset",781+ "relatedSkills": [782+ "use-case-diagram",783+ "sequence-diagram",784+ "state-machine-diagram",785+ "activity-diagram",786+ "class-diagram",787+ "component-diagram",788+ "deployment-diagram"789+ ],790+ "note": "PlantUML and other renderers cover useful UML views, but diagram.zip does not validate the complete metamodel or import and export UML XMI and UMLDI.",791+ "source": "https://www.omg.org/spec/UML/2.5.1/",792+ "integration": {793+ "reward": "medium",794+ "effort": "large",795+ "scope": "UML XMI/UMLDI import, model validation, profile handling, and round-trip fidelity"796+ }797+ },798+ {799+ "id": "iso-5807-1985",800+ "name": "ISO 5807:1985",801+ "status": "visual-conventions",802+ "relatedSkills": [803+ "flowchart"804+ ],805+ "note": "General renderers can apply its flowchart conventions, but diagram.zip does not validate symbol or path conformance.",806+ "source": "https://www.iso.org/standard/11955.html"807+ },808+ {809+ "id": "rfc-2360",810+ "name": "RFC 2360 packet diagram conventions",811+ "status": "visual-conventions",812+ "relatedSkills": [813+ "protocol-layout-diagram"814+ ],815+ "note": "PacketDiag and Bytefield can express layouts that follow the conventions, but protocol-specific validation is not built in.",816+ "source": "https://www.rfc-editor.org/rfc/rfc2360.html#section-3.3"817+ },818+ {819+ "id": "dmn-1.5",820+ "name": "OMG DMN 1.5",821+ "status": "unsupported",822+ "relatedSkills": [823+ "decision-tree"824+ ],825+ "note": "Informal decision trees are supported. Decision requirements diagrams, DMN XML interchange, and FEEL evaluation are not.",826+ "source": "https://www.omg.org/spec/DMN/1.5/",827+ "integration": {828+ "reward": "high",829+ "effort": "medium-to-large",830+ "scope": "DMN XML parser, decision requirements rendering, validation, and optional FEEL evaluation"831+ }832+ },833+ {834+ "id": "archimate-3.2",835+ "name": "The Open Group ArchiMate 3.2",836+ "status": "unsupported",837+ "relatedSkills": [838+ "choose-architecture-diagram",839+ "system-landscape-diagram",840+ "system-context-diagram",841+ "container-diagram"842+ ],843+ "note": "Generic architecture pictures are supported, but ArchiMate viewpoints, notation rules, and model exchange are not.",844+ "source": "https://www.opengroup.org/archimate-licensed-downloads",845+ "integration": {846+ "reward": "high",847+ "effort": "large",848+ "scope": "Licensed notation assets, ArchiMate 3.x model exchange, viewpoint rules, and conformance testing"849+ }850+ },851+ {852+ "id": "sysml-2.0",853+ "name": "OMG SysML 2.0",854+ "status": "unsupported",855+ "relatedSkills": [856+ "choose-architecture-diagram",857+ "block-diagram",858+ "component-diagram",859+ "hierarchy-diagram"860+ ],861+ "note": "Generic blocks and relationships are supported, but SysML language semantics, textual notation, model interchange, and view validation are not.",862+ "source": "https://www.omg.org/spec/SysML/2.0/",863+ "integration": {864+ "reward": "high",865+ "effort": "very-large",866+ "scope": "SysML textual or JSON parsing, KerML/SysML semantics, libraries, view generation, and conformance"867+ }868+ },869+ {870+ "id": "iec-60617-2026-db",871+ "name": "IEC 60617:2026 DB",872+ "status": "unsupported",873+ "relatedSkills": [874+ "circuit-diagram",875+ "wiring-harness-diagram"876+ ],877+ "note": "General renderers can draw circuits and harnesses, but diagram.zip has no licensed IEC symbol library or symbol validation.",878+ "source": "https://webstore.iec.ch/en/publication/2723",879+ "integration": {880+ "reward": "medium",881+ "effort": "large",882+ "scope": "Symbol licensing, searchable assets, semantic ports and nets, document rules, and conformance boundaries"883+ }884+ }885+ ]886+}@@ -1,6 +1,68 @@
11 # diagram.zip documentation22 3-> Use these stable pages to create, style, save, and share diagrams.3+> Choose the semantic story first, then choose a renderer and source format.4+5+- [Diagram routing skill](https://docs.diagram.zip/skills/diagramming/SKILL.md): Select a diagram family from the reader's question.6+- [Machine-readable semantic catalog](https://docs.diagram.zip/diagram-skills.json): Inspect every skill, use case, exclusion, role, and invocation constraint.7+8+## Routing and collaboration9+10+- [Choose a diagram](https://docs.diagram.zip/skills/diagramming/SKILL.md): Choose the semantic diagram story first, then select a diagram.zip renderer and produce a clear, reviewable diagram.11+- [Diagram workshop](https://docs.diagram.zip/skills/diagram-workshop/SKILL.md): Work with me to discover the right diagram question, audience, scope, and level of detail before making a diagram. Explicit user invocation only.12+- [Review a diagram](https://docs.diagram.zip/skills/diagram-review/SKILL.md): Review a proposed diagram for semantic fit, evidence, readability, accessibility, and renderer or standards limitations; recommend precise revisions.13+14+## Behavior and process15+16+- [Flowchart](https://docs.diagram.zip/skills/flowchart/SKILL.md): Choose a flowchart when the user needs a readable decision or process path with a clear start, sequence, branch, merge, or end.17+- [Sequence diagram](https://docs.diagram.zip/skills/sequence-diagram/SKILL.md): Choose a sequence diagram when the user needs to explain ordered messages, calls, responses, or time-dependent collaboration between participants.18+- [State machine diagram](https://docs.diagram.zip/skills/state-machine-diagram/SKILL.md): Choose a state-machine diagram when an entity's permitted states, event-triggered transitions, guards, and entry or exit behavior are the central story.19+- [Activity diagram](https://docs.diagram.zip/skills/activity-diagram/SKILL.md): Choose an activity diagram when the user needs to explain workflow logic, parallel work, decisions, joins, and responsibility across actions.20+- [BPMN process](https://docs.diagram.zip/skills/bpmn-process/SKILL.md): Choose BPMN when the user needs a formal business-process model with events, tasks, gateways, pools, lanes, and message or sequence flows.21+- [Use-case diagram](https://docs.diagram.zip/skills/use-case-diagram/SKILL.md): Use when the user needs to explain who can achieve which externally visible goals with a system, including actors, system boundaries, and goal relationships.22+- [Data-flow diagram](https://docs.diagram.zip/skills/data-flow-diagram/SKILL.md): Use when the user needs to show where information originates, how processes transform it, where stores retain it, and which external entities exchange it.23+- [Timeline](https://docs.diagram.zip/skills/timeline/SKILL.md): Use when the user needs to communicate events or milestones in chronological order, with dates, intervals, eras, or parallel tracks.24+- [Gantt chart](https://docs.diagram.zip/skills/gantt-chart/SKILL.md): Use when the user needs a time-scaled schedule showing tasks, durations, dependencies, milestones, and progress across teams or workstreams.25+- [User journey map](https://docs.diagram.zip/skills/user-journey-map/SKILL.md): Use when the user needs to understand a person’s experience across stages, touchpoints, actions, thoughts, emotions, pain points, and opportunities.26+27+## Software and system structure28+29+- [Choose an architecture diagram](https://docs.diagram.zip/skills/choose-architecture-diagram/SKILL.md): Choose the smallest architecture view that answers the stakeholder's question, then route it to a suitable diagram source.30+- [System landscape diagram](https://docs.diagram.zip/skills/system-landscape-diagram/SKILL.md): Show the systems and people across an organization or domain, emphasizing ownership and meaningful dependencies.31+- [System context diagram](https://docs.diagram.zip/skills/system-context-diagram/SKILL.md): Explain one system in its environment by showing its users, external systems, and the relationships that matter.32+- [Container diagram](https://docs.diagram.zip/skills/container-diagram/SKILL.md): Show the major deployable or runtime containers inside one software system and how they collaborate.33+- [Component diagram](https://docs.diagram.zip/skills/component-diagram/SKILL.md): Create a component-level view of software structure, interfaces, and dependencies when the audience needs implementation boundaries rather than deployment topology.34+- [Architecture dynamic diagram](https://docs.diagram.zip/skills/architecture-dynamic-diagram/SKILL.md): Explain an architecture scenario over time by showing participating components, messages, and state changes for one concrete use case.35+- [Deployment diagram](https://docs.diagram.zip/skills/deployment-diagram/SKILL.md): Show where software artifacts run, which infrastructure nodes host them, and how runtime communication crosses environments or trust boundaries.36+- [Block diagram](https://docs.diagram.zip/skills/block-diagram/SKILL.md): Arrange labeled blocks and relationships to communicate system decomposition, signal or data paths, and high-level structure without committing to a specialized formal notation.37+- [Class diagram](https://docs.diagram.zip/skills/class-diagram/SKILL.md): Create or review class diagrams that explain types, responsibilities, contracts, and structural relationships in an object-oriented or domain model.38+- [Entity-relationship diagram](https://docs.diagram.zip/skills/entity-relationship-diagram/SKILL.md): Model persistent data with entities, attributes, keys, relationships, cardinality, optionality, and integrity boundaries using an entity-relationship diagram.39+- [Dependency graph](https://docs.diagram.zip/skills/dependency-graph/SKILL.md): Show dependencies between packages, modules, services, artifacts, or concepts when the important story is coupling, direction, reachability, or change impact.40+- [Network topology](https://docs.diagram.zip/skills/network-topology/SKILL.md): Document physical or logical networks with nodes, interfaces, links, segments, addressing, trust zones, and traffic boundaries.41+42+## Conceptual and planning43+44+- [Mind map](https://docs.diagram.zip/skills/mind-map/SKILL.md): Use when the user needs to explore one central topic through associative branches, capture brainstorming, or organize an unconstrained idea space before choosing a structure.45+- [Concept map](https://docs.diagram.zip/skills/concept-map/SKILL.md): Use when the user needs to explain concepts and the labeled relationships between them, especially definitions, dependencies, evidence, or cross-domain connections.46+- [Hierarchy diagram](https://docs.diagram.zip/skills/hierarchy-diagram/SKILL.md): Use when the user needs a ranked, nested, or reporting structure such as a taxonomy, organization chart, tree, or work breakdown structure.47+- [Decision tree](https://docs.diagram.zip/skills/decision-tree/SKILL.md): Use when the user needs to show a sequence of choices, branching rules, outcomes, or diagnostic paths.48+- [Matrix diagram](https://docs.diagram.zip/skills/matrix-diagram/SKILL.md): Use when the user needs to compare two dimensions, expose a portfolio or prioritization space, or show a many-to-many relationship in a grid or quadrant.49+- [Set diagram](https://docs.diagram.zip/skills/set-diagram/SKILL.md): Use when the user needs to show membership, overlap, exclusion, union, intersection, or nested categories with sets.50+51+## Data visualization52+53+- [Choose a data visualization](https://docs.diagram.zip/skills/choose-data-visualization/SKILL.md): Choose and design a data visualization when the user has data, a comparison, trend, distribution, relationship, flow, or geographic question but has not yet chosen a chart form. Use the simplest honest encoding, explain the story, and route the result to Vega or Vega-Lite when appropriate.54+55+## Technical and hardware56+57+- [Protocol layout diagram](https://docs.diagram.zip/skills/protocol-layout-diagram/SKILL.md): Use when a diagram must explain the bit, byte, or word layout of a protocol message, file header, register, or binary record.58+- [Digital timing diagram](https://docs.diagram.zip/skills/digital-timing-diagram/SKILL.md): Use when a diagram must show digital signals changing over time, including clocked interfaces, bus transactions, handshakes, setup/hold relationships, or waveform protocols.59+- [Rack diagram](https://docs.diagram.zip/skills/rack-diagram/SKILL.md): Use when documenting equipment placement in a cabinet or rack, including rack units, device identity, power, network uplinks, and physical capacity.60+- [Wiring harness diagram](https://docs.diagram.zip/skills/wiring-harness-diagram/SKILL.md): Use when the user needs to document wires, cables, connectors, splices, branches, pin mappings, or harness manufacturing/service information.61+- [HDL component diagram](https://docs.diagram.zip/skills/hdl-component-diagram/SKILL.md): Use when the user needs a hardware-design view of HDL entities, modules, interfaces, ports, parameters, clocks, resets, and hierarchy.62+- [Circuit diagram](https://docs.diagram.zip/skills/circuit-diagram/SKILL.md): Use when the user needs an electrical or electronic schematic showing components, nets, reference designators, power, signal flow, and test points.63+- [Technical illustration](https://docs.diagram.zip/skills/technical-illustration/SKILL.md): Use when the user needs an explanatory technical figure showing parts, assemblies, operation, dimensions, callouts, or a controlled visual sequence.64+65+## Renderer and source formats466 567 - [PlantUML syntax](https://docs.diagram.zip/create/types/plantuml/): Create a PlantUML diagram. [Style](https://docs.diagram.zip/style/types/plantuml/).668 - [Mermaid syntax](https://docs.diagram.zip/create/types/mermaid/): Create a Mermaid diagram. [Style](https://docs.diagram.zip/style/types/mermaid/).@@ -40,8 +102,9 @@
40102 - [Password encryption](https://docs.diagram.zip/collaboration/encryption/)41103 - [Working state and saved state](https://docs.diagram.zip/collaboration/working-and-saved-state/)42104 43-## Structured catalog105+## Structured catalogs44106 107+- [diagram-skills.json](https://docs.diagram.zip/diagram-skills.json)45108 - [diagram-types.json](https://docs.diagram.zip/diagram-types.json)46-- [Full text reference](https://docs.diagram.zip/llms-full.txt)109+- [Full renderer text reference](https://docs.diagram.zip/llms-full.txt)47110 - [Source repository](https://github.com/FelineStateMachine/diagramzip)@@ -0,0 +1,40 @@
1+---2+name: activity-diagram3+description: Choose an activity diagram when the user needs to explain workflow logic, parallel work, decisions, joins, and responsibility across actions.4+---5+6+# Activity diagram7+8+## What and why9+10+An activity diagram tells how work flows through actions and control nodes, including branching, merging, concurrency, and synchronization. Use it for algorithms, operational workflows, and cross-team procedures. Use BPMN when formal business-process events, messages, compensation, or executable process semantics matter.11+12+## Model it13+14+1. Define the activity boundary, initial condition, and completion criteria.15+2. Name actions with concise verbs and separate control flow from data flow.16+3. Use decision/merge and fork/join deliberately; a fork must have a meaningful synchronization story.17+4. Add swimlanes only to answer ownership questions; keep lane count small.18+5. Show exceptions, cancellation, and parallel completion rules when they affect the outcome.19+20+UML 2.5.1 provides the activity, action, control-node, token-flow, and partition concepts. See [UML activities](references/uml-activities.md).21+22+## Story and styling23+24+Give the happy path a stable reading direction and make concurrency visually parallel. Label guards as business conditions, not code fragments. Use lanes as responsibility bands, and reserve color for ownership or exception emphasis with a textual legend.25+26+## Renderer routing27+28+Prefer `plantuml` for UML activity semantics, `mermaid` for accessible documentation flow, `actdiag` for simple lane-oriented activities, or `d2` for a customized technical workflow. Preserve the user's requested renderer. Use `bpmn` for formal process interchange rather than translating BPMN semantics into a generic activity chart.29+30+## Review31+32+- Are actions, decisions, merges, forks, and joins distinguishable?33+- Does every parallel branch have a clear completion or cancellation rule?34+- Are swimlanes meaningful and consistently assigned?35+- Are data objects shown only when they clarify the workflow?36+- Can a reader follow normal, exception, and concurrent paths?37+38+## Limits and opportunities39+40+diagram.zip does not validate UML token-flow semantics or guarantee that an activity is deadlock-free. A UML activity parser/linter and a first-class swimlane layout profile would be useful future integrations.@@ -0,0 +1,7 @@
1+# UML activities2+3+UML 2.5.1 defines activities, actions, control nodes, object nodes, flows, and activity partitions (often rendered as swimlanes). Use the formal concepts when the workflow is a software or systems design artifact.4+5+Reference: [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1).6+7+Generic flowchart renderers can display the picture but do not validate UML activity semantics. Strict validation remains an integration opportunity.@@ -0,0 +1,38 @@
1+---2+name: architecture-dynamic-diagram3+description: Explain an architecture scenario over time by showing participating components, messages, and state changes for one concrete use case.4+---5+6+# Architecture dynamic diagram7+8+## What and why9+10+Use this skill to tell the story of one runtime scenario: who participates, what crosses boundaries, and where decisions, retries, or asynchronous work occur. It complements a static architecture view; it should not become a generic system map.11+12+## Select or avoid13+14+Select it for request lifecycles, event propagation, failure paths, migrations, and performance-sensitive interactions. Avoid it for an inventory of components, infrastructure placement, or a business process with formal events and gateways. If exact temporal order is the point, choose a sequence diagram; if spatial topology is the point, choose deployment or system landscape.15+16+## Modeling method17+18+1. State the scenario, trigger, success condition, and scope.19+2. Choose participants at one architecture level and order them by responsibility or boundary.20+3. Show the happy path first, then annotate only consequential alternatives, retries, timeouts, and failures.21+4. Distinguish synchronous calls, asynchronous messages, callbacks, and durable events.22+5. Label messages with intent and contract, not implementation trivia. Mark assumptions and omitted internals.23+24+## Styling and customization25+26+Use a clear time direction, visually separate trust or ownership boundaries, and keep alternate paths close to the message that branches. Use line styles consistently for sync/async and a single accent for failure or retry. Add duration or correlation IDs only when they answer the user’s question. Preserve a user-selected renderer; otherwise prefer `structurizr` when the scenario uses an existing C4 workspace, `c4plantuml` for a focused C4 dynamic view, `plantuml` or `mermaid` for sequence-like scenarios, and `d2` for annotated flows.27+28+## Review checklist29+30+- Is this one scenario rather than an architecture inventory?31+- Is ordering unambiguous, including asynchronous behavior?32+- Are retries, timeouts, failure ownership, and idempotency visible where relevant?33+- Are boundaries and participant abstraction levels consistent?34+- Does the diagram state what it intentionally omits?35+36+## Standards and prior art37+38+Use [C4 dynamic diagrams](https://c4model.com/diagrams/dynamic) for scenario-focused architecture narration and [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1/) for sequence/message semantics. diagram.zip can render PlantUML, C4 PlantUML, Mermaid, D2, Graphviz, and SeqDiag, but does not validate a formal UML interaction model or guarantee execution traces. Formal architecture-model interchange and analysis are integration opportunities.@@ -0,0 +1,38 @@
1+---2+name: block-diagram3+description: Arrange labeled blocks and relationships to communicate system decomposition, signal or data paths, and high-level structure without committing to a specialized formal notation.4+---5+6+# Block diagram7+8+## What and why9+10+Use this skill for a deliberately general overview: major blocks, inputs and outputs, and the paths that connect them. It is useful early in design, in technical documentation, and when a domain-specific notation would distract from the main story.11+12+## Select or avoid13+14+Select it when the audience needs a compact structural abstraction and the exact notation is not the decision. Avoid it when semantics are important enough to warrant a flowchart, component, deployment, circuit, protocol-layout, or formal SysML diagram. State whether arrows mean control, data, energy, material, or dependency; an unlabeled generic arrow is ambiguous.15+16+## Modeling method17+18+1. Write the one-sentence story and define the system boundary.19+2. Select blocks that transform, contain, or depend on something relevant to that story.20+3. Arrange blocks in the dominant flow direction and label inputs, outputs, and relationships.21+4. Group blocks only when the grouping changes interpretation; keep hierarchy shallow.22+5. Add assumptions, units, interfaces, and omitted detail as notes or a legend.23+24+## Styling and customization25+26+Use one shape family for blocks, spacing to show hierarchy, and line weight to distinguish boundary from flow. Use color for category or state, never as the only encoding. Prefer orthogonal routing for engineered paths and whitespace over connector crossings. Preserve a user-selected renderer; otherwise use D2 or Graphviz for flexible blocks, BlockDiag for automatic block layouts, Mermaid for lightweight docs, or PlantUML for a familiar architecture notation.27+28+## Review checklist29+30+- Is the meaning of each block and arrow explicit?31+- Is the abstraction level consistent?32+- Can the dominant path be followed without crossing lines?33+- Are boundary, interface, assumptions, and omitted detail visible?34+- Would a specialized diagram type communicate the decision more precisely?35+36+## Standards and prior art37+38+Block diagrams are a family of conventions rather than one universally governing notation. [ISO 5807:1985](https://www.iso.org/standard/11955.html) covers information-processing flowchart and program-network symbols, while [OMG SysML](https://www.omg.org/sysml/) formalizes block-oriented systems modeling beyond a generic sketch. diagram.zip supports generic block rendering through PlantUML, Mermaid, D2, Graphviz, BlockDiag, and diagrams.net, but does not provide SysML validation or interchange. Native SysML 2 support is an integration opportunity if demand justifies it.@@ -0,0 +1,40 @@
1+---2+name: bpmn-process3+description: Choose BPMN when the user needs a formal business-process model with events, tasks, gateways, pools, lanes, and message or sequence flows.4+---5+6+# BPMN process7+8+## What and why9+10+BPMN is a business-process notation and metamodel, not merely a flowchart style. Use it for cross-organization processes, orchestration, choreography, exception events, compensation, and process-engine interchange. Use a generic flowchart or activity diagram for an informal procedure without BPMN semantics.11+12+## Model it13+14+1. Define participants and process boundaries; use pools and lanes for responsibility.15+2. Start with start/end events and the business outcome.16+3. Choose tasks by business meaning, then add gateways only for real control decisions.17+4. Use sequence flow inside a process and message flow between participants; never conflate them.18+5. Model timer, error, escalation, compensation, subprocess, and data semantics only when they affect execution or understanding.19+20+BPMN 2.0.2 is standardized by OMG and ISO 19510. See [BPMN references](references/bpmn-standard.md).21+22+## Story and styling23+24+Make participant boundaries and the normal process path obvious. Use event markers and gateway labels consistently. Keep diagram interchange positions stable when XML is exchanged, and use restrained colors for roles or exceptions. Explain any vendor-specific extensions in a legend or note.25+26+## Renderer routing27+28+Use `bpmn` when BPMN 2.0 XML and formal interchange are required. Use `plantuml` or `mermaid` only for an intentionally BPMN-like explanatory sketch, and state that it is not BPMN interchange. `graphviz` or `d2` can show a business process but cannot preserve BPMN semantics. Preserve an explicitly requested renderer.29+30+## Review31+32+- Are pools, lanes, sequence flows, and message flows used for their intended meanings?33+- Is each gateway type justified by the process behavior?34+- Are event triggers and exception paths explicit?35+- Are start/end events and subprocess boundaries coherent?36+- Does the XML include stable IDs and diagram interchange where exchange requires it?37+38+## Limits and integration opportunities39+40+diagram.zip supports BPMN rendering, but it does not promise full BPMN conformance validation, execution semantics, vendor-extension compatibility, or process-model analysis. A BPMN 2.0.2 validator, lint ruleset, and round-trip interchange tests would be valuable integrations.@@ -0,0 +1,7 @@
1+# BPMN standard2+3+BPMN 2.0.2 defines the notation, metamodel, and interchange concepts for business-process diagrams. ISO 19510 adopts the BPMN specification. Use the specification's distinction between sequence flow, message flow, events, activities, gateways, pools, and lanes when producing a formal model.4+5+References: [OMG BPMN 2.0.2](https://www.omg.org/spec/BPMN/2.0.2/) and [ISO 19510](https://www.iso.org/standard/62652.html).6+7+Rendering BPMN XML is not the same as validating or executing it. Treat validator, conformance profiles, and vendor-extension handling as explicit integration opportunities.@@ -0,0 +1,42 @@
1+---2+name: choose-architecture-diagram3+description: Choose the smallest architecture view that answers the stakeholder's question, then route it to a suitable diagram source.4+---5+6+# Choose an architecture diagram7+8+## What it tells9+10+This skill is a decision aid for selecting an architecture view before drawing. It distinguishes landscape, context, container, component, deployment, dynamic, and block views by audience, scope, and relationship semantics.11+12+## When to use13+14+Use it when a request says “architecture diagram” without naming a view, or when the requested picture risks mixing organizational scope, runtime behavior, and implementation structure. Ask who needs the decision, what boundary they need, and whether the question is static structure, runtime interaction, or physical placement.15+16+Avoid it when the user has already named a precise view and its scope. Use the corresponding architecture skill directly, preserving the user's choice.17+18+## Method19+20+1. Restate the question as a decision or explanation.21+2. Choose one primary view and make its system boundary explicit.22+3. Keep the abstraction level consistent; do not mix components with external organizations or deployment hosts without a deliberate second view.23+4. Name relationships with a verb and, where useful, a protocol or trust boundary.24+5. Offer a companion view only when it answers a separate question.25+26+Use the C4 model as a notation-independent framing aid: landscape for many systems, context for one system and its users/dependencies, container for deployable/runtime units, and component for internals of one container. Use deployment for nodes/environments and dynamic views for a scenario over time. A block diagram is appropriate when the domain is not software or when informal modular decomposition is enough.27+28+## Renderer routing29+30+Preserve an explicitly requested renderer. Otherwise prefer `structurizr` when one C4 model should produce several views, `c4plantuml` for a focused C4 view, `plantuml` for UML-flavoured architecture, `mermaid` or `d2` for lightweight sketches, `graphviz` for graph-heavy dependencies, and `blockdiag` for simple block structure. These are source choices, not diagram types; confirm the renderer can express the chosen semantics before generating.31+32+## Style and customization33+34+Use a restrained palette, a visible legend, directional flow, short labels, and a title stating scope and audience. Use consistent shapes for people, software systems, containers, components, and external dependencies. Prefer line styles or icons for trust, synchronous/asynchronous, and data-flow distinctions; never rely on color alone. Generate a second focused diagram when labels become paragraphs.35+36+## Review37+38+Check that every element is inside or outside the boundary intentionally, every arrow has a readable meaning, the audience can identify the level of abstraction, and no implementation detail is implied by an informal shape. Check that the diagram remains useful in grayscale and at its intended size. If the user needs formal conformance, call out that C4 itself is a model/framing convention rather than an ISO notation standard.39+40+## Prior art and limits41+42+The C4 model is explicitly notation-independent. C4 PlantUML is a practical renderer library, not a formal interchange standard. ArchiMate and SysML offer stronger formal viewpoints/modeling semantics but are not currently represented by a dedicated diagram.zip source skill; integration would require a compatible renderer/import path and a decision on conformance. See [C4 diagrams](https://c4model.com/diagrams), [C4 notation](https://c4model.com/diagrams/notation), [ArchiMate](https://www.opengroup.org/archimate-forum/archimate-overview), and [OMG SysML](https://www.omg.org/sysml/).@@ -0,0 +1,55 @@
1+---2+name: choose-data-visualization3+description: Choose and design a data visualization when the user has data, a comparison, trend, distribution, relationship, flow, or geographic question but has not yet chosen a chart form. Use the simplest honest encoding, explain the story, and route the result to Vega or Vega-Lite when appropriate.4+---5+6+# Choose a data visualization7+8+## What this skill is9+10+This is a semantic chart-selection skill. It decides what the data should say before deciding how the source is written. It covers bar, line and area, scatter and bubble, histogram, box/violin/density, pie/donut, heatmap, treemap, Sankey, geographic, network, beeswarm, and word-cloud forms.11+12+## Ask first13+14+Establish these facts before choosing a mark:15+16+- What decision or question should the reader answer?17+- What is one row: an observation, category, event, relationship, region, or aggregate?18+- Which fields are quantitative, temporal, ordinal, nominal, geographic, or identifiers?19+- Is the task comparison, ranking, change over time, distribution, correlation, part-to-whole, flow, location, hierarchy, or topology?20+- How many observations and categories are there, and will the chart be printed, embedded, or explored interactively?21+- Are zero, uncertainty, missing values, weights, denominators, and units meaningful?22+23+If the user already selected a chart form or renderer, preserve that choice and review it against the question. Do not silently substitute a chart.24+25+## Choose the story26+27+- **Bar**: compare discrete values or rank categories. Use a common zero baseline for magnitudes; sort deliberately. Horizontal bars suit long labels. Avoid bars for dense time series or many categories.28+- **Line / area**: show ordered time or another continuous sequence. Lines imply continuity; do not connect unrelated categories. Use area for cumulative volume or a small number of parts, not for precise comparison of many series.29+- **Scatter / bubble**: show association between two quantitative variables; use size for a third only when area can be read as approximate magnitude. Add trend or reference lines only when they have a stated meaning.30+- **Histogram**: show the distribution of one quantitative field. State bin width or method; compare groups with shared bins. It is not a bar chart of arbitrary categories.31+- **Box / violin / density**: compare distributions across groups. Box plots emphasize robust summaries and outliers; violins/densities show shape but can mislead with small samples or smoothing. Show sample size where it changes interpretation.32+- **Pie / donut**: show a small number of mutually exclusive parts of one whole when the total is meaningful. Prefer bars when exact comparison matters; never use a pie for unrelated values or a changing total.33+- **Heatmap**: show a quantitative value over two categorical/ordered dimensions, often a matrix or calendar. Use a perceptually ordered scale and label the legend; do not imply precision the color cannot carry.34+- **Treemap**: show nested part-to-whole with limited space. Use area for the primary magnitude and hierarchy for grouping; avoid it when adjacent length comparisons are required.35+- **Sankey / flow**: show quantities moving among stages or nodes. Preserve conservation or explain losses/gains, label units, and avoid excessive crossing. It is not a generic relationship graph.36+- **Geographic map**: show spatial distribution or routes only when location changes the decision. Choose a projection and geometry appropriate to the region; normalize rates by population/area where relevant. A map is not automatically more informative than a ranked bar chart.37+- **Network visualization**: show entities and relationships/topology. Define node and edge meaning, direction, and weight; do not use position as an unearned quantitative scale. For dense networks, filter, group, or provide a table/search alternative.38+- **Beeswarm**: show every observation across one or more groups while exposing distribution and sample size. It is useful when overplotting would hide points; preserve a quantitative axis and explain jitter packing.39+- **Word cloud**: show rough prominence of terms in a corpus, not exact ranking or meaning. Prefer a sorted bar chart for measured comparison; remove stopwords and disclose the weighting/tokenization.40+41+## Honest encodings and styling42+43+Use position and length for the most important quantitative comparison, then color, shape, and size. Treat color as a redundant cue, not the sole encoding. Use a zero baseline for bars and areas unless a clearly marked non-zero baseline is the point. Keep comparable panels on shared scales. Label units, denominators, aggregation, date range, missing data, and uncertainty.44+45+Prefer restrained, semantic styling: a neutral field, one accent for the focus, a colorblind-safe categorical palette, direct labels where they reduce lookup, and a legend only when it remains legible. Avoid 3-D effects, decorative gradients, rainbow scales for ordered values, misleading area/volume, excessive gridlines, and truncated axes that exaggerate differences. Provide text or tabular access to values and meaningful titles/annotations.46+47+For Vega-Lite, start with a mark and field encodings, then set explicit types, scales, axes, legends, and configuration. Use Vega when the chart needs custom marks, transforms, signals, projections, force layouts, or precise composition. Both are supported renderer IDs in diagram.zip: `vegalite` and `vega`. Keep data and images inline: diagram.zip does not provide URL-backed data or images for these renderers and returns SVG.48+49+Renderer choice remains the user’s choice. If another supported renderer is requested, route only if it can express the selected story faithfully; otherwise explain the gap and offer a Vega/Vega-Lite source as an option. The current catalog has no dedicated high-level renderer for Sankey, treemap, beeswarm, word cloud, or network charts. Vega can sometimes implement them with custom transforms/marks; Vega-Lite is not a turnkey solution for each. Geographic charts require inline geometry and a deliberate projection. Treat this as an integration opportunity, not permission to invent unsupported syntax.50+51+## Review before delivery52+53+Check that the title states the question, encodings match field types, aggregation and denominators are explicit, scales do not distort the comparison, categories are ordered intentionally, and annotations do not imply causation. Test long labels, missing values, small samples, extreme values, grayscale/low-vision viewing, keyboard or text alternatives, and export at the intended size. For maps check projection, boundary date, privacy, and rate normalization; for flows check conservation; for networks check edge ambiguity; for distributions check binning/smoothing and sample size.54+55+Read [Vega and Vega-Lite guidance](references/vega.md) for renderer-specific decisions and [accessibility guidance](references/accessibility.md) when the output will be published or used for a decision.@@ -0,0 +1,8 @@
1+# Accessible data visualization reference2+3+- [WCAG 2.2 Success Criterion 1.4.1](https://www.w3.org/TR/WCAG22/#use-of-color) requires that color not be the only means of conveying information. Add labels, patterns, shapes, line styles, or text alternatives.4+- [WCAG 2.2 Success Criterion 1.4.3](https://www.w3.org/TR/WCAG22/#contrast-minimum) covers text contrast. Small labels and legends need particular care.5+- [W3C SVG 2 accessibility guidance](https://www.w3.org/TR/SVG2/conform.html#accessibility) describes meaningful titles, descriptions, and accessible naming for SVG graphics.6+- [W3C WAI complex images tutorial](https://www.w3.org/WAI/tutorials/images/complex/) recommends a concise purpose statement plus a longer text alternative for charts and other complex graphics.7+8+For a diagram.zip SVG, provide a meaningful title and description when the chosen source format supports them, and pair the image with a nearby textual summary or data table. Do not rely on color, hover, animation, or spatial position alone. Preserve readable focus/order in interactive variants and state the data source, date, aggregation, and uncertainty in accompanying text.@@ -0,0 +1,17 @@
1+# Vega and Vega-Lite reference2+3+Use the renderer that matches the required control surface:4+5+- [Vega documentation](https://vega.github.io/vega/docs/) defines the lower-level grammar: data, transforms, scales, axes, legends, marks, signals, and projections. It is the supported diagram.zip renderer ID `vega`.6+- [Vega-Lite documentation](https://vega.github.io/vega-lite/docs/) defines concise marks, encodings, typed fields, layering, concatenation, faceting, and repeat views. It is the supported diagram.zip renderer ID `vegalite`.7+- The Vega-Lite paper, [A Grammar of Interactive Graphics](https://idl.uw.edu/papers/vega-lite/), explains why explicit data types and compositional encodings make common charts easier to specify and review.8+9+Practical routing:10+11+- Start with Vega-Lite for bars, lines, areas, scatterplots, histograms, box plots, heatmaps, faceting, and small multiples.12+- Use Vega when you need custom transforms, a geographic projection, a force layout, bespoke marks, signals, or exact layered composition.13+- Put records or geometry inline. External URLs are unavailable in diagram.zip’s Vega and Vega-Lite renderers.14+- Use explicit `type` (`quantitative`, `temporal`, `ordinal`, or `nominal`) and explicit scale domains when comparison across views matters.15+- Verify the actual output at the target size; a valid specification can still produce illegible labels or an ambiguous legend.16+17+The renderer catalog does not currently provide convenience renderers for Sankey, treemap, beeswarm, word cloud, or network diagrams. A future integration could add tested, accessible templates or dedicated renderers for these forms; until then, disclose custom Vega work and do not claim that a generic mark is a semantic implementation.@@ -0,0 +1,38 @@
1+---2+name: circuit-diagram3+description: Use when the user needs an electrical or electronic schematic showing components, nets, reference designators, power, signal flow, and test points.4+---5+6+# Circuit diagram7+8+## Select it when9+10+Choose this skill when the reader must understand or build an electrical circuit: signal paths, power rails, component relationships, or measurement points. Use it for conceptual schematics and documentation. Do not call a general block diagram a schematic, and do not imply PCB layout, simulation, safety approval, or manufacturing release without source data.11+12+## Story and modeling13+14+Choose the level first: functional block schematic, detailed circuit, or power/control subcircuit. Model standard symbols, reference designators, values/ratings, net names, pin numbers, polarity, power and ground, connectors, test points, and signal direction. Keep wires orthogonal where possible; show a junction only where a connection exists. Use net labels and hierarchical connectors to avoid unreadable wire crossings. Include units and a legend.15+16+A rendered image is not necessarily an authoritative electrical document. It does not establish ERC correctness, component availability, creepage/clearance, safe ratings, SPICE behavior, or PCB connectivity unless those are validated by an integrated EDA source.17+18+## Styling and customization19+20+Prefer conventional symbol geometry and a consistent left-to-right signal flow. Use line weight and labels before color; if color marks power domains or warnings, provide a monochrome legend. Keep reference designators visible and values secondary. Use sheet boundaries, title blocks, revision, and source links for engineering audiences. Do not invent a symbol when the standard symbol is unavailable—label the custom graphic and explain it.21+22+## Renderer routing23+24+Preserve a renderer explicitly requested by the user. Use `diagramsnet` for manually positioned schematic-like drawings, `svgbob` for text-native circuit sketches, or `tikz` and `pikchr` for controlled custom geometry. Use `plantuml`, `d2`, or `graphviz` only for functional connectivity abstractions. The catalog does not expose a native SPICE/EDA schematic renderer or IEC symbol-validation pipeline. General renderers cannot guarantee electrical semantics, pin correctness, or standards-compliant symbol libraries.25+26+## Review27+28+Check every net endpoint, junction, pin number, polarity mark, power/ground symbol, reference designator, value, unit, and cross-sheet link. Confirm that crossings are unambiguous and that no hidden net is silently assumed. Review ratings, safety boundaries, and revision/source provenance with an electrical engineer. State whether the output is conceptual, review-ready, or a standards-controlled artifact.29+30+## References31+32+- [IEC 60617:2026 DB](https://webstore.iec.ch/en/publication/2723) — authoritative symbol database; licensing and symbol-library integration may be required.33+- [IEC 61082-1](https://webstore.iec.ch/en/publication/265) — preparation of electrotechnical documents; the renderers do not enforce its conventions.34+- [IEEE Std 315](https://standards.ieee.org/standard/315-1975.html) — graphic symbols for electrical/electronics diagrams; verify applicability and current organizational practice.35+36+## Integration opportunities37+38+Native IEC/IEEE symbol libraries, ERC/netlist checks, SPICE import, EDA interchange, title-block control, and design-rule validation are unsupported integration opportunities. Do not describe a general-renderer output as IEC/IEEE-compliant authoring.@@ -0,0 +1,54 @@
1+---2+name: class-diagram3+description: Create or review class diagrams that explain types, responsibilities, contracts, and structural relationships in an object-oriented or domain model.4+---5+6+# Class diagram7+8+## Select this skill when9+10+Use this skill when the story is about named types and their structural relationships: attributes, operations, inheritance, interfaces, composition, aggregation, or dependencies. Use it for a design contract, domain model, API shape, or a focused explanation of one subsystem.11+12+Avoid it when the main story is runtime order (use a sequence or activity diagram), deployment topology (use deployment or network-topology), relational tables (use entity-relationship-diagram), or a graph whose nodes are not types (use dependency-graph).13+14+## Story and semantic model15+16+Start with the question the reader must answer: “What are the important types, what do they own, and how may they collaborate?” Name the abstraction level in the title. Keep the diagram to one coherent boundary and show only members that support the story.17+18+Use UML semantics deliberately:19+20+- A class has identity and may show attributes and operations; an interface describes a contract.21+- Generalization means “is a”; realization means “implements the contract”; dependency means “uses”.22+- Composition means the part’s lifecycle is owned by the whole; aggregation is weaker and should be used sparingly.23+- Label associations with role names, navigability, and multiplicities when they matter. Do not imply lifecycle or cardinality merely with a line.24+- Prefer explicit relationship labels over relying on arrow glyphs that vary by renderer.25+26+Object diagrams are a useful companion when the reader needs one concrete runtime snapshot. Keep that as a reference view rather than mixing instances and classifiers in the same primary diagram.27+28+## Layout and styling29+30+Use a consistent reading direction, group types by bounded context or package, and place the most important contract near the center. Keep inheritance vertical where possible and route cross-group dependencies around the outside. Show public API members first; omit private implementation details unless they explain a constraint.31+32+Use restrained color for roles or packages, not for every class. Make interface, abstract, external, and deprecated status available through shape, stereotype, or text as well as color. Use high-contrast text and never make a dashed/solid distinction the only encoding.33+34+## Renderer routing35+36+Preserve an explicit renderer choice from the user. Otherwise prefer:37+38+- `plantuml` for expressive UML, relationships, members, and mature styling.39+- `mermaid` for a lightweight Markdown-friendly class view.40+- `c4plantuml` only when the class view is actually a component-level C4 view; it is not a general UML class renderer.41+- `graphviz` or `d2` for a dependency-shaped type graph when UML notation is unnecessary.42+- `diagramsnet` when the user needs hand-positioned, editable shapes.43+44+Check the local renderer catalog before promising syntax or export behavior. Renderer support is not semantic validation: diagram.zip cannot guarantee that a source expresses valid UML merely because it renders.45+46+## Review checklist47+48+Check that every arrow has a sentence meaning, multiplicities are intentional, ownership is not overstated, and the abstraction level is consistent. Remove orphan types, duplicate concepts, and members that do not support the stated question. Test the diagram at its final reading size and verify that a grayscale or non-color reading still works.49+50+## Standards and prior art51+52+The baseline is OMG UML 2.5.1, especially Class, Interface, Generalization, Realization, Dependency, and Association semantics: <https://www.omg.org/spec/UML/2.5.1/>. UML is a vocabulary, not a mandate to show every member or relationship.53+54+The object-diagram companion is also defined by UML, but diagram.zip currently has no dedicated object-diagram skill. A future skill could add instance identity, slots, links, and snapshot review rules. If a user requires machine-valid UML interchange or complete XMI round-tripping, that is an unsupported integration opportunity rather than a promise of this skill.@@ -0,0 +1,40 @@
1+---2+name: component-diagram3+description: Create a component-level view of software structure, interfaces, and dependencies when the audience needs implementation boundaries rather than deployment topology.4+---5+6+# Component diagram7+8+## What and why9+10+Use this skill to tell the story of how a software system is partitioned into replaceable or independently owned components, and how those components collaborate through explicit interfaces. It is a good fit for design reviews, ownership boundaries, integration planning, and explaining an existing codebase. It is not a class diagram, deployment map, or a full system landscape.11+12+## Select or avoid13+14+Select it when the question is “which implementation parts depend on which contracts?” Avoid it when the question is about people and systems (system context), runtime nodes (deployment), message order (sequence), or data ownership (ERD). Ask whether the component means a code/module boundary, a service boundary, or a logical subsystem; do not mix those levels without a boundary legend.15+16+## Modeling method17+18+1. Name the system boundary and audience.19+2. Identify components at one consistent level. Give each a responsibility and owner.20+3. Draw only meaningful dependencies; label each edge with the interface, protocol, or purpose.21+4. Show provided/required interfaces when interface compatibility matters.22+5. Add external dependencies only when they explain a decision. Mark inferred or undocumented relationships.23+24+The primary story should be readable from components and labeled relationships alone. Use notes for risks, technology, or migration state—not as a substitute for missing structure.25+26+## Styling and customization27+28+Use containment to show system/subsystem boundaries, not decorative nesting. Keep component shapes consistent, use a restrained color for ownership or lifecycle, and reserve a second accent for external dependencies. Prefer orthogonal or gently routed connectors, short labels, and a left-to-right direction for dependency flow. Add a legend for every non-obvious color, stereotype, or line style. Preserve a user-selected renderer; otherwise prefer `structurizr` for a reusable C4 workspace, `c4plantuml` for a focused C4 component view, `plantuml` for UML component notation, `mermaid` for quick documentation, or `d2` for a polished sketch.29+30+## Review checklist31+32+- Is the abstraction level explicit and consistent?33+- Does every important edge name a contract or purpose?34+- Can ownership, externality, and lifecycle status be distinguished without guessing?35+- Are cycles, high fan-in, and unstable boundaries visible?36+- Is the diagram still legible when rendered in the requested format?37+38+## Standards and prior art39+40+See [C4 and UML profiles](references/c4-uml.md). C4 component diagrams and UML component diagrams overlap in intent but are not interchangeable notations. UML 2.5.1 is the formal standard; diagram.zip supports text renderers and C4 PlantUML, not a general UML model interchange pipeline. Full UML conformance, executable interface contracts, and SysML component semantics are integration opportunities rather than promises of this skill.@@ -0,0 +1,6 @@
1+# C4 and UML profiles2+3+- [C4 diagrams](https://c4model.com/diagrams) and [C4 notation](https://c4model.com/diagrams/notation): C4 uses context, container, component, and code views to progressively explain software architecture. Treat “component” as a zoom level and state the boundary.4+- [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1/): the UML Component and Composite Structures chapters define components, provided/required interfaces, ports, connectors, and collaborations. Use those concepts when interface semantics matter; do not imply formal UML conformance from a rendered sketch.5+6+The supported renderer choices are syntax-level choices: PlantUML, Mermaid, D2, Graphviz, BlockDiag, and C4 PlantUML are available in diagram.zip. They differ in layout and notation fidelity; preserve the user’s choice and explain any loss of interface/port semantics.@@ -0,0 +1,34 @@
1+---2+name: concept-map3+description: Use when the user needs to explain concepts and the labeled relationships between them, especially definitions, dependencies, evidence, or cross-domain connections.4+---5+6+# Concept map7+8+## What / why9+10+A concept map is a semantic network: concepts are nodes and labeled propositions connect them. It tells the story “how are these ideas related, and what kind of relationship is it?” Choose it over a mind map when cross-links and relationship meaning matter.11+12+## How to model13+14+- State the focus question before modeling.15+- Use noun or noun-phrase concepts; connect them with explicit verbs or relation labels.16+- Make each path read as a proposition: `concept — relation — concept`.17+- Use hierarchy only for real general-to-specific relationships; allow cross-links.18+- Distinguish evidence, examples, and claims from concepts themselves.19+20+## Styling and customization21+22+Use directional links, high-contrast labels, and enough space for relation text. Use color for concept categories, not relationship meaning alone. Add a legend for arrowheads, line styles, and confidence/status. For a dense map, provide a focused subgraph as well as the overview.23+24+## Renderer choices25+26+Preserve the user’s renderer choice. Mermaid, Graphviz, D2, PlantUML, and diagrams.net can represent labeled graphs; Graphviz is useful for automatic layout, while D2 or diagrams.net suit deliberate composition. No diagram.zip renderer enforces concept-map propositions or validates relationship labels; the skill supplies that semantic discipline.27+28+## Review29+30+Read every edge as a sentence. Check labels are specific, arrow direction is meaningful, cycles are intentional, and the focus question is answered. Remove unlabeled edges unless adjacency itself is the claim.31+32+## Prior art and gaps33+34+See [references/prior-art.md](references/prior-art.md). The [ISO 704 terminology principles](https://www.iso.org/standard/59176.html) are useful prior art for clear concepts and relations, but diagram.zip does not implement a terminology interchange format.@@ -0,0 +1,7 @@
1+# Concept-map references2+3+- [IHMC CmapTools concept-map overview](https://cmap.ihmc.us/docs/concept-maps.php) — prior art for concepts, linking phrases, propositions, hierarchy, and cross-links.4+- [ISO 704:2022](https://www.iso.org/standard/59176.html) — terminology principles relevant to concept clarity and definitions.5+- [Graphviz DOT language](https://graphviz.org/documentation/) — supported graph renderer and layout reference.6+7+There is no universally adopted concept-map interchange standard in diagram.zip. A dedicated concept-map data model and validator would be an integration opportunity.@@ -0,0 +1,34 @@
1+---2+name: container-diagram3+description: Show the major deployable or runtime containers inside one software system and how they collaborate.4+---5+6+# Container diagram7+8+## What it tells9+10+A container diagram opens one system boundary by one level. It explains the major applications, services, data stores, and other runtime units, their responsibilities, and their important collaborations.11+12+## Use and boundaries13+14+Use it for solution design, team ownership, technology decisions, integration review, and explaining where data or requests flow. Define “container” as a separately runnable or deployable unit in the chosen context; do not confuse it with an operating-system container. Avoid classes, functions, cloud-product inventories, or host topology unless they are the explicit story; use component or deployment views for those.15+16+## Method17+18+Begin with a system context and retain only its boundary-relevant actors/dependencies. For each container state its responsibility and, when useful, technology. Draw the smallest set of collaborations needed to answer the question, label edges with action/data/protocol, and distinguish synchronous from asynchronous paths. Include data stores as containers when persistence matters. If a service is actually a team boundary or a deployment unit, say which interpretation is being used.19+20+## Renderer routing21+22+Keep the user's renderer choice. Prefer `structurizr` when containers share a reusable C4 workspace model or `c4plantuml` for a focused view. Use `plantuml` for UML component/deployment hybrids, `mermaid` or `d2` for approachable sketches, and `graphviz` when automatic layout is the main need. Renderer syntax can draw the shapes but cannot guarantee that a box is a C4 container—encode that meaning in labels, legend, and review.23+24+## Style and customization25+26+Use nested system boundaries, consistent container shapes, short responsibility labels, and a small technology annotation. Separate data stores visually without implying a technology that was not chosen. Use line patterns for sync/async or trust, and keep color accessible and nonessential. Provide a focused companion deployment view when physical placement matters.27+28+## Review29+30+Check that every container has a responsibility, the system boundary is visible, collaborations are directional and labeled, technology details are not mistaken for responsibilities, and the level does not mix classes or infrastructure resources. Test readability at the delivery size and in grayscale. Confirm that the diagram answers one question rather than becoming an inventory.31+32+## Prior art and limits33+34+This uses the C4 container concept, which is notation-independent. C4 PlantUML provides macros, not a formal model interchange format. UML component/deployment views, ArchiMate, and SysML can provide formal semantics, but diagram.zip currently lacks dedicated profile-enforced ArchiMate/SysML sources; integration would be needed for those standards. See [C4 diagrams](https://c4model.com/diagrams), [C4 notation](https://c4model.com/diagrams/notation), [OMG UML](https://www.omg.org/spec/UML/2.5.1/), [ArchiMate overview](https://www.opengroup.org/archimate-forum/archimate-overview), and [OMG SysML](https://www.omg.org/sysml/).@@ -0,0 +1,40 @@
1+---2+name: data-flow-diagram3+description: Use when the user needs to show where information originates, how processes transform it, where stores retain it, and which external entities exchange it.4+---5+6+# Data-flow diagram7+8+## What and why9+10+A data-flow diagram (DFD) explains movement and transformation of information. Its story is source → process → store/sink, with the data named on each flow. It is useful for system scope, privacy reviews, integration discovery, and requirements conversations.11+12+Choose it for information movement. Avoid it for temporal call order (sequence diagram), network topology (network-topology), business control flow (flowchart/BPMN), or deployment placement.13+14+## How15+16+1. Declare the level: context/level 0 for one process and external entities, or a decomposed level for internal processes.17+2. Use four concepts: external entity, process, data store, and data flow. Give each a stable ID and a meaningful noun/verb label.18+3. Label every arrow with the data being exchanged; distinguish request, response, event, and batch where it matters.19+4. Balance decomposition: flows crossing a parent boundary must remain represented in its child diagram.20+5. Mark trust boundaries, retention, sensitive fields, and ownership as annotations rather than inventing new flow semantics.21+22+## Story and styling23+24+Put external entities at the perimeter, processes in the reading direction, and stores near the processes that use them. Use restrained colors for entity/process/store roles and a single accent for sensitive or cross-boundary flows. Arrow direction and labels must remain legible in monochrome.25+26+If no renderer is specified, `graphviz` is a strong default for explicit nodes and directed edges; `mermaid` or `d2` is convenient for source-controlled sketches. These renderers do not enforce Yourdon/DeMarco or Gane–Sarson symbol semantics, so state the chosen profile in a legend or title. Preserve the user’s renderer choice.27+28+## Review29+30+- Is the diagram level and system boundary explicit?31+- Does every process have at least one input and output, unless it is an intentional source/sink?32+- Are all flows named with data, not vague verbs such as “handles”?33+- Are stores and external entities distinct from processes?34+- Are decomposed diagrams balanced and are sensitive/trust-crossing flows visible?35+36+## Prior art and limitations37+38+Use the [NIST glossary definition of a data-flow diagram](https://csrc.nist.gov/glossary/term/data_flow_diagram) as a government-domain anchor, and document the selected notation profile. DFD notation has multiple historical conventions; there is no single current ISO visual interchange standard implemented by the available renderers.39+40+SVG output should meet [WCAG 2.2](https://www.w3.org/TR/WCAG22/) non-text contrast and text alternatives. A future integration could add a profile-aware DFD renderer or interchange validator for Yourdon–DeMarco and Gane–Sarson symbols.@@ -0,0 +1,34 @@
1+---2+name: decision-tree3+description: Use when the user needs to show a sequence of choices, branching rules, outcomes, or diagnostic paths.4+---5+6+# Decision tree7+8+## What / why9+10+A decision tree tells the story “which question or rule leads to which next branch and outcome?” It is for explicit branching logic, not a general process or arbitrary hierarchy.11+12+## How to model13+14+- Start with one entry condition and make each decision node a question or predicate.15+- Label every outgoing edge with understandable, mutually exclusive conditions; include the default/else branch.16+- Keep outcomes distinct from subsequent decisions and identify terminal nodes.17+- State precedence, probability, owner, or evidence when decisions depend on them.18+- If rules are complex, separate the readable tree from the authoritative decision table.19+20+## Styling and customization21+22+Use diamonds or clearly differentiated decision nodes, rounded/colored terminal outcomes, and directional flow. Keep branch labels near edges and avoid color-only meaning. Use line styles for confidence or exception paths only with a legend.23+24+## Renderer choices25+26+Preserve the user’s renderer. Mermaid flowcharts, Graphviz, D2, PlantUML activity diagrams, and diagrams.net can render decision trees. diagram.zip does not implement DMN decision requirements diagrams or FEEL evaluation; that is an unsupported integration opportunity. Use BPMN when the user needs formal process events/tasks, not merely branching.27+28+## Review29+30+Trace every path from entry to outcome. Check branch completeness, overlap, unreachable nodes, contradictory predicates, and whether visual order matches evaluation order. Call out any informal rule that needs DMN or a decision table.31+32+## Prior art and gaps33+34+See [references/prior-art.md](references/prior-art.md).@@ -0,0 +1,7 @@
1+# Decision-tree references2+3+- [OMG DMN 1.5](https://www.omg.org/spec/DMN/1.5/) — latest formal prior art for decision requirements, decision logic, and FEEL; not a native diagram.zip renderer.4+- [Mermaid flowchart syntax](https://mermaid.js.org/syntax/flowchart.html) — supported renderer for readable informal decision trees.5+- [ISO 5807:1985](https://www.iso.org/standard/11955.html) — flowchart symbol convention relevant to decision/process notation.6+7+DMN support would require XML parsing, decision requirements notation, and likely FEEL-aware validation. Do not imply that a Mermaid diamond is DMN-conformant.@@ -0,0 +1,52 @@
1+---2+name: dependency-graph3+description: Show dependencies between packages, modules, services, artifacts, or concepts when the important story is coupling, direction, reachability, or change impact.4+---5+6+# Dependency graph7+8+## Select this skill when9+10+Use this skill when a reader needs to see “what depends on what,” identify coupling, trace impact, find cycles, or understand a dependency boundary. Nodes may be software packages, services, libraries, documents, datasets, or other artifacts, but declare the node type and edge meaning.11+12+Avoid it for ordered interactions (use sequence-diagram), ownership hierarchies (use hierarchy-diagram), network reachability (use network-topology), or a business process. If edges mean several different things, split the views or use an explicit legend.13+14+## Story and semantic model15+16+Define the direction in a sentence, such as “A imports B” or “Service A calls Service B.” Name the evidence and time scope: declared dependencies, runtime calls, build dependencies, or inferred references. Keep the graph at one level of abstraction.17+18+- Use directed edges by default and label exceptional edge kinds.19+- Distinguish direct from transitive dependencies; do not draw transitive edges unless they are the story.20+- Use clusters for ownership or package boundaries, not as a substitute for missing nodes.21+- Mark external, optional, deprecated, generated, and cyclic dependencies explicitly.22+- For impact analysis, identify the root artifact and highlight reachable downstream nodes without hiding the rest of the graph.23+24+Large graphs should be filtered by boundary, depth, or centrality. A graph that contains every dependency is often a dataset, not a useful diagram.25+26+## Layout and styling27+28+Choose left-to-right for dependency flow and top-to-bottom for layered architecture. Use stable node IDs and short labels; put versions or details in a legend or annotation. Use color for status or ownership, and use line style, labels, or shape for edge semantics so the reading survives grayscale.29+30+Prefer one strong emphasis (for example, a selected package and its callers). Avoid rainbow coloring by node. If the graph has cycles, make them visible and annotate whether the cycle is intentional.31+32+## Renderer routing33+34+Preserve an explicit renderer choice. Otherwise prefer:35+36+- `graphviz` for larger directed/undirected graphs, clusters, rank direction, and automatic layout.37+- `d2` for readable architecture/dependency graphs with containers and local styling.38+- `mermaid` for compact Markdown documentation and moderate-size graphs.39+- `plantuml` when dependency edges are part of a broader UML component or package view.40+- `diagramsnet` when a small dependency map must remain manually editable.41+42+Renderer layout is not graph analysis. diagram.zip does not infer dependencies, calculate reachability, detect cycles, or verify versions unless the input itself supplies those facts. Generate or validate the dependency data upstream, then use this skill to present it.43+44+## Review checklist45+46+Read the edge direction aloud and verify it is consistent. Check that every edge has a defined meaning, direct/transitive scope is clear, external boundaries are visible, and the selected graph is small enough to scan. Verify emphasized paths against source evidence. Remove duplicate nodes and edges, and explain cycles instead of routing them out of view.47+48+## Standards and prior art49+50+Graphviz DOT is the most portable source prior art for directed and undirected graph structure and attributes: <https://graphviz.org/documentation/>. The W3C Web of Things Architecture is useful prior art for describing software/system dependencies alongside boundaries and interactions: <https://www.w3.org/TR/wot-architecture/>.51+52+There is no universal standard that makes a generic dependency graph semantically interchangeable across package managers and runtime systems. If the project needs dependency extraction, provenance, graph queries, or a machine-readable graph interchange profile, that requires integration beyond diagram.zip rendering.@@ -0,0 +1,38 @@
1+---2+name: deployment-diagram3+description: Show where software artifacts run, which infrastructure nodes host them, and how runtime communication crosses environments or trust boundaries.4+---5+6+# Deployment diagram7+8+## What and why9+10+Use this skill to tell the operational placement story: artifacts or services, execution nodes, environments, networks, and the paths between them. It supports capacity, security, release, and incident discussions. It is not a component dependency map or a rack inventory unless that physical detail is the subject.11+12+## Select or avoid13+14+Select it when location, hosting, environment, connectivity, or redundancy matters. Avoid it when only logical ownership matters (component), when the audience needs business systems (landscape/context), or when exact hardware rack units are the question (rack diagram). Clarify whether “node” means cloud service, VM/container, device, or physical host.15+16+## Modeling method17+18+1. Name the deployment environment and observation time.19+2. Define nodes and nested execution environments at a consistent granularity.20+3. Place deployable artifacts or services on their host; distinguish replicated, standby, and ephemeral instances.21+4. Label connections with protocol, port, direction, trust boundary, and important controls.22+5. Show only topology relevant to the decision; add a legend for availability, environment, and security notation.23+24+## Styling and customization25+26+Use nested containers for environments and hosts, and a calm color scheme for production/staging/development. Keep network or trust boundaries visually stronger than ordinary grouping. Use badges for replicas, zones, and managed services; never rely on color alone. Preserve a user-selected renderer; otherwise prefer `structurizr` or `c4plantuml` for C4 deployment views, `plantuml` for UML deployment notation, `mermaid` or `d2` for documentation, and `nwdiag` for network-centric topology.27+28+## Review checklist29+30+- Is the environment/time snapshot explicit?31+- Can a reader identify what runs where and what crosses each boundary?32+- Are replicas, zones, failure domains, and dependencies represented accurately?33+- Are protocols, ports, and trust assumptions labeled when operationally important?34+- Does the diagram avoid implying a physical guarantee from a logical cloud abstraction?35+36+## Standards and prior art37+38+See [deployment profiles](references/deployment-profiles.md). UML 2.5.1 defines deployment nodes, artifacts, communication paths, and deployment relationships; C4’s deployment diagrams provide a pragmatic architecture view. diagram.zip renders PlantUML, C4 PlantUML, Mermaid, D2, Graphviz, BlockDiag, and NwDiag, but does not validate a UML model, cloud-provider topology, or security policy. Cloud-provider-native architecture export and formal deployment-model interchange are integration opportunities.@@ -0,0 +1,7 @@
1+# Deployment profiles2+3+- [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1/): deployment diagrams model nodes, artifacts, deployment specifications, and communication paths. Use those terms when the audience expects UML semantics.4+- [C4 deployment diagrams](https://c4model.com/diagrams/deployment): C4 uses deployment views to show how software is deployed to infrastructure in a particular environment, often with instances and technology details.5+- [NwDiag](http://blockdiag.com/en/nwdiag/): network-focused diagrams can show network segments and hosts, but are not a substitute for application artifact placement.6+7+Choose the least expressive renderer that preserves the story. A renderer’s visual similarity to UML or C4 does not establish standards conformance.@@ -0,0 +1,28 @@
1+---2+name: diagram-review3+description: Review a proposed diagram for semantic fit, evidence, readability, accessibility, and renderer or standards limitations; recommend precise revisions.4+---5+6+# Diagram review7+8+## What this is9+10+Use this model-invokable skill after a diagram is drafted, when a user asks whether it is correct, or when requirements are ambiguous enough that errors would be costly. Review the semantic story separately from the renderer syntax.11+12+## Review sequence13+14+1. State the diagram's apparent question, audience, scope, and main claim.15+2. Check that the selected diagram family makes that claim easy to read. Identify category errors, overloaded symbols, missing actors, hidden assumptions, and relationships that lack direction or labels.16+3. Check evidence: distinguish facts, inferred relationships, proposed architecture, and illustrative examples. Flag claims that need a source or domain-owner confirmation.17+4. Check layout: reading direction, grouping, crossings, hierarchy, density, legend, labels, and print or small-screen behavior.18+5. Check accessibility: meaningful text alternatives, document language and title/description where supported, contrast, non-color encoding, text size, and a linear reading explanation. Use [WCAG 2.2](https://www.w3.org/TR/WCAG22/) and [SVG accessibility guidance](https://www.w3.org/TR/SVG-access/) for delivery decisions.19+6. Check renderer fidelity and export. Name unsupported standard constructs, layout controls, or interchange data rather than silently approximating them.20+7. Return prioritized fixes: blocking semantic errors, reader-confusing issues, then polish. Include a concise corrected story or source fragment when useful.21+22+## Styling and customization23+24+Prefer styles that reinforce meaning: consistent shape roles, restrained color, explicit boundaries, and labels that survive grayscale or color-vision differences. Keep bespoke styling local and documented. Do not let a theme override a formal symbol's meaning or make decorative elements look like data.25+26+## Prior art27+28+For formal diagrams, compare against the relevant [OMG UML](https://www.omg.org/spec/UML), [OMG BPMN](https://www.omg.org/spec/BPMN/2.0.2/), or [C4 notation](https://c4model.com/diagrams/notation) guidance. For flowcharts, consult [ISO 5807](https://www.iso.org/standard/11955.html) where exact symbol conventions matter. Standards are review references; the local renderer catalog determines what diagram.zip can execute.@@ -0,0 +1,34 @@
1+---2+name: diagram-workshop3+description: Work with me to discover the right diagram question, audience, scope, and level of detail before making a diagram.4+disable-model-invocation: true5+---6+7+# Diagram workshop8+9+Use this skill when the user explicitly asks to workshop, explore, compare, or decide what diagram to make. It is intentionally user-invokable only: a router may recommend it, but must not invoke it without the user's direction.10+11+## What to discover12+13+Establish:14+15+- who will read the diagram and what decision or explanation it must support;16+- the subject, boundaries, time direction, and stable versus changing facts;17+- whether the story is flow, interaction, state, structure, data, hierarchy, comparison, physical placement, or a formal process;18+- the required fidelity, output format, renderer preference, and accessibility constraints.19+20+## How to facilitate21+22+Ask only the smallest set of questions that changes the diagram choice. Offer two or three candidate stories, state what each makes easy or hides, and recommend one. Sketch the entities and relationships in plain language before writing renderer syntax. Then hand off to the selected semantic skill and renderer while preserving the user's choices.23+24+## Useful prompts25+26+“What should a reader be able to decide after looking at this?” “Is order or structure more important?” “What is inside the boundary?” “Which facts must be exact?” “Who owns each step or component?” “Will this be read on a slide, in a document, or by assistive technology?”27+28+## Guardrails29+30+Do not manufacture missing facts. Mark assumptions and ask for confirmation when they affect meaning. A single diagram should not silently combine incompatible stories; propose separate views or a deliberate hybrid. If the requested formal notation is not available in diagram.zip, explain the gap and suggest the closest semantic view plus an integration opportunity.31+32+## Prior art33+34+Use the [C4 diagram question framing](https://c4model.com/diagrams), [OMG UML](https://www.omg.org/spec/UML), and [OMG BPMN](https://www.omg.org/spec/BPMN/2.0.2/) as appropriate. These references inform the conversation; they do not replace the selected skill's renderer support check.@@ -0,0 +1,40 @@
1+---2+name: diagramming3+description: Choose the semantic diagram story first, then select a diagram.zip renderer and produce a clear, reviewable diagram.4+---5+6+# Diagramming7+8+## What this is9+10+Use this as the model-invokable router for diagram requests. A renderer is a notation and execution choice; a diagram type is the story the reader needs. Select the story before selecting syntax.11+12+## Why13+14+The same system can be shown as a flow, interaction, boundary, dependency, data model, or physical layout. Choosing by renderer first commonly produces a technically valid diagram that answers the wrong question.15+16+## How to route17+18+1. Ask or infer the audience, decision, scope, time direction, and required level of detail.19+2. Choose the smallest semantic skill that matches the question. Prefer `diagram-workshop` when the user needs help discovering the question; it is user-invokable only and must not be invoked implicitly.20+3. Read that skill, including its references when the subject is formal or safety-sensitive.21+4. Choose a supported renderer from the local renderer catalog. Preserve an explicit renderer request even if another renderer is a better fit; explain any limitation and adapt the source.22+5. Make one main claim visually dominant. Label relationships with verbs, keep a consistent direction, and remove details that do not support the claim.23+6. Review the result for semantic correctness, layout, accessibility, and renderer limitations. Offer a second view when one diagram cannot answer two different questions.24+25+## Renderer routing26+27+Common choices include Mermaid for compact general diagrams, PlantUML for UML-oriented notation, C4 PlantUML for C4 views, Graphviz or D2 for graph structure, BPMN for formal process exchange, DBML for relational schemas, and PacketDiag/Bytefield for protocol fields. The complete supported set and syntax links are in the generated `llms.txt` and `diagramzip-docs/data/diagram-types.mjs`. Do not claim a standard is supported merely because a renderer has a similarly named mode: confirm the renderer's actual output and interchange fidelity.28+29+## Prior art and standards30+31+Use the [OMG UML specification](https://www.omg.org/spec/UML), [OMG BPMN specification](https://www.omg.org/spec/BPMN/2.0.2/), [C4 notation](https://c4model.com/diagrams/notation), and other authoritative references linked by the selected semantic skill when formal conformance matters. Treat these as guidance for meaning and notation, not as permission to invent unsupported renderer features.32+33+## Review checklist34+35+- Can the intended reader state the diagram's question in one sentence?36+- Are nodes, relationships, boundaries, and direction consistent with the selected story?37+- Is every label necessary and unambiguous?38+- Does the chosen renderer actually support the required semantics, layout, and export?39+- Are text, contrast, alternative descriptions, and SVG metadata adequate for the delivery context?40+- Have unsupported standards or fidelity gaps been named as integration opportunities?@@ -0,0 +1,54 @@
1+---2+name: digital-timing-diagram3+description: Use when a diagram must show digital signals changing over time, including clocked interfaces, bus transactions, handshakes, setup/hold relationships, or waveform protocols.4+---5+6+# Digital timing diagram7+8+## What it is9+10+A digital timing diagram is a time-aligned view of signals and events. It tells the reader which edges, levels, delays, and sampling relationships are required—not merely which components are connected.11+12+## Choose it when13+14+- correctness depends on clock edges, signal levels, latency, pulse width, or ordering in time;15+- the reader needs to compare a producer, consumer, clock, enable, reset, or bus on a shared time axis;16+- a protocol's “what happens when” is about electrical/logical timing rather than software call order.17+18+Use a sequence diagram for causal messages between participants. Use a protocol-layout diagram for field positions in a packet. Use an electrical schematic for connectivity and symbols.19+20+## Story and modeling21+22+1. Define the time direction, scale or “not to scale” status, voltage/logic convention, and active edge.23+2. Put the reference clock and reset first. Align every signal to explicit edges or intervals.24+3. Label meaningful transitions: setup window, hold window, valid/ready, request/acknowledge, turnaround, wait state, and sampled value.25+4. Show unknown, high-impedance, don't-care, and invalid states distinctly; never silently draw them as stable 0 or 1.26+5. State assumptions such as synchronous domain, propagation delay, bus ownership, and whether the waveform is normative or an example trace.27+28+## Styling and customization29+30+Use a consistent signal baseline and equal vertical spacing. Use a single accent for the active transaction, neutral clock/grid lines, and explicit hatch or text for unknown/high-impedance states. Annotate intervals with brackets and values, not only color. Keep the time axis readable at the intended output size and split long traces into named phases rather than shrinking everything.31+32+## Renderer routing33+34+- `wavedrom` is the direct diagram.zip fit for clocked waveforms, signal lanes, phase labels, and bus values.35+- `vega` can produce bespoke plotted traces when quantitative time data or custom scales matter, but it needs more explicit grammar and does not itself confer electrical meaning.36+- `tikz` or `pikchr` can handle a custom timing notation when WaveDrom's primitives are insufficient.37+- `plantuml`, `mermaid`, and `seqdiag` show ordered interactions but do not encode waveform-level setup/hold semantics; use them only if that abstraction is intentional.38+39+Preserve the user's renderer choice. If no renderer is requested, prefer `wavedrom` and state any assumptions. diagram.zip does not currently validate timing constraints against an HDL interface standard or simulate a waveform; an integration that imports interface timing tables or checks setup/hold annotations would be valuable. IEEE 1800/SystemVerilog assertions and vendor timing formats remain unsupported as normative inputs unless separately integrated.40+41+## Review checklist42+43+- Is the time axis and scale status clear?44+- Are clock edge, polarity, reset, and sampling point explicit?45+- Are setup/hold, latency, pulse width, and turnaround intervals labeled where relevant?46+- Are X/Z/don't-care states distinguishable from 0/1?47+- Does every transition support the stated protocol story?48+- Is this a normative timing requirement or one illustrative trace?49+50+## References51+52+- [WaveDrom documentation](https://wavedrom.com/) describes the waveform source model supported by diagram.zip.53+- [IEEE 1800-2023](https://standards.ieee.org/ieee/1800/10458/) is the SystemVerilog language standard, including assertions and timing-oriented design constructs; diagram.zip does not parse it as a timing-diagram source.54+- [JEDEC JESD79-5C](https://www.jedec.org/standards-documents/docs/jesd79-5c) is an example of a memory-interface specification where timing diagrams accompany normative setup/hold requirements.@@ -0,0 +1,52 @@
1+---2+name: entity-relationship-diagram3+description: Model persistent data with entities, attributes, keys, relationships, cardinality, optionality, and integrity boundaries using an entity-relationship diagram.4+---5+6+# Entity-relationship diagram7+8+## Select this skill when9+10+Use this skill when the story is how data is stored and related: entities, identifying keys, foreign keys, cardinality, optionality, normalization, or schema ownership. Use it before writing SQL when a team needs to agree on the data model.11+12+Avoid it for service calls and runtime behavior (use data-flow or sequence), software types (use class-diagram), or a generic dependency graph. A physical schema diagram may include indexes and column types, but do not let implementation detail obscure the conceptual model.13+14+## Story and semantic model15+16+State whether the view is conceptual, logical, or physical. Name entities with stable singular nouns, attributes with domain terms, and identifiers explicitly. For each relationship, answer: can each side exist without the other, how many are allowed, and what identifies the relationship?17+18+- Mark primary keys and candidate keys; distinguish a surrogate identifier from a meaningful natural key.19+- Show foreign-key mappings in a logical or physical view, but do not infer them from similarly named columns.20+- Use associative entities for many-to-many relationships when the relationship has attributes or needs independent lifecycle.21+- Represent optionality and cardinality explicitly. “One or more” and “zero or one” are different constraints.22+- Note temporal, tenant, uniqueness, and deletion rules when they change the interpretation of the model.23+24+Keep a conceptual ERD free of storage-engine choices. In a physical view, include types, indexes, and constraints only when they answer the audience’s question.25+26+## Layout and styling27+28+Place the central business entities in the middle, group entities by bounded context or ownership, and route relationship lines to minimize crossings. Use a stable key/attribute order and consistent notation (crow’s foot, Chen, or another declared profile).29+30+Use color to distinguish ownership or lifecycle, never to encode cardinality alone. Show key and constraint symbols in text or shape as well. If the renderer cannot express the chosen notation, add a legend and use labels rather than silently changing semantics.31+32+## Renderer routing33+34+Preserve an explicit renderer choice. Otherwise prefer:35+36+- `dbml` for a compact physical/logical relational schema with tables, fields, indexes, and references.37+- `mermaid` for a shareable ER view in Markdown-oriented workflows.38+- `plantuml` for richer entity notation and explanatory annotations.39+- `graphviz` or `d2` for a custom data relationship graph when strict ER notation is not required.40+- `diagramsnet` for manually arranged, editable database documentation.41+42+`dbml` describes relational structure but does not by itself establish a universal conceptual ER notation. Validate that the selected renderer can show keys, nullability, and cardinality required by the story. diagram.zip renders source; it does not connect to a live database or verify that a schema matches production.43+44+## Review checklist45+46+Check every entity has an identifier or an explicit reason it does not. Check every relationship has both endpoint constraints, no many-to-many relationship is accidental, and optionality is stated. Look for duplicated facts, transitive dependencies, ambiguous names, and ownership rules missing from the model. Review conceptual and physical views separately when both are needed.47+48+## Standards and prior art49+50+Use ISO/IEC 11179 terminology for data-element naming and metadata where a governance context requires it: <https://www.iso.org/standard/35343.html>. For relational implementation, the SQL standard is the authority for constraints, but vendor DDL adds behavior not represented by a generic ERD.51+52+Crow’s-foot notation is common practice rather than one single universally controlling interchange standard. Declare the notation in a legend. If the user requires a formally exchangeable conceptual model (for example, a vendor-specific modeling repository format), diagram.zip has no dedicated interchange validator; that is an integration opportunity.@@ -0,0 +1,40 @@
1+---2+name: flowchart3+description: Choose a flowchart when the user needs a readable decision or process path with a clear start, sequence, branch, merge, or end.4+---5+6+# Flowchart7+8+## What and why9+10+A flowchart is a control-flow story: work moves from an entry point through actions and decisions to one or more outcomes. Choose it for procedures, troubleshooting, algorithms, approvals, and “what happens next?” explanations. It is not a good fit for rich business semantics, timed interactions between participants, or a large dependency network.11+12+## Model it13+14+1. State the scope and one reader question in the title.15+2. Identify start/end outcomes before filling in steps.16+3. Use verb-first action labels and phrase decisions as questions with labeled exits.17+4. Make the normal path visually dominant; keep exception paths explicit.18+5. Merge paths when they become equivalent, and avoid crossing connectors.19+20+Use conventional symbols where the audience expects them: process, decision, terminator, input/output, and connector. ISO 5807 remains the relevant flowchart reference; use its notation when interchange or formal review matters. See [flowchart conventions](references/flowchart-conventions.md).21+22+## Story and styling23+24+The useful story is “how a case gets from here to there.” Keep one direction, consistent spacing, and short labels. Reserve color for semantic emphasis such as risk, exception, or ownership; provide shape or text cues too. Put explanatory detail in notes or adjacent prose rather than turning every node into a paragraph.25+26+## Renderer routing27+28+Prefer `mermaid` for quick Markdown-friendly flowcharts, `graphviz` when automatic graph layout matters, `plantuml` for a source-controlled formal diagram, or `d2` for a polished architecture/process sketch. `blockdiag` is suitable for simple block-oriented paths. Preserve an explicitly requested renderer and adapt the model to its syntax.29+30+## Review31+32+- Is there one clearly stated scope and outcome question?33+- Can every decision exit be followed and understood?34+- Are loops, retries, and failure outcomes visible?35+- Does the layout have a reading direction and minimal line crossings?36+- Are symbols, labels, contrast, and text alternatives usable in the target output?37+38+## Limits and opportunities39+40+The renderers above do not provide a guaranteed ISO 5807 interchange validator. If strict symbol conformance or machine validation becomes a product requirement, add a flowchart semantic linter or an ISO-profile integration.@@ -0,0 +1,7 @@
1+# Flowchart conventions2+3+ISO 5807:1985, confirmed current in 2019, defines documentation symbols and conventions for data, program, and system flowcharts. Use it as a vocabulary and review aid rather than assuming that a renderer's shape names prove conformance.4+5+Reference: [ISO 5807:1985](https://www.iso.org/standard/11955.html).6+7+The standard is not bundled as executable validation in diagram.zip. Treat strict conformance checking as a possible future integration.@@ -0,0 +1,40 @@
1+---2+name: gantt-chart3+description: Use when the user needs a time-scaled schedule showing tasks, durations, dependencies, milestones, and progress across teams or workstreams.4+---5+6+# Gantt chart7+8+## What and why9+10+A Gantt chart tells the scheduling story: work packages occupy intervals on a calendar, and dependencies constrain when work can happen. It is useful for delivery plans, migrations, launches, and maintenance windows.11+12+Choose it for planned work over time. Avoid it for an event history (timeline), a process’s logical steps without dates (flowchart), or a personal experience over stages (user-journey-map).13+14+## How15+16+1. Establish a calendar, timezone, working-day policy, and status date.17+2. Decompose deliverables into tasks with owners, start/finish or duration, and a definition of done.18+3. Add only meaningful dependencies; distinguish finish-to-start from other relationships when supported.19+4. Mark milestones as zero-duration outcomes, not decorative dates. Show progress with a legend and a clear as-of date.20+5. Keep the critical path or key release gates visible; move low-value detail to a linked plan.21+22+## Story and styling23+24+Order rows by deliverable or dependency flow. Use neutral bars for planned work, a distinct overlay for completed work, and one accent for gates or risk. Never use color alone for status. Include weekends/holidays and baseline variance only if they inform the decision.25+26+If no renderer is specified, use `mermaid` for a compact source-controlled schedule. `plantuml` can represent Gantt charts in its supported syntax; `graphviz` and `d2` require modeling a schedule manually and are poor defaults. Preserve an explicit renderer choice. Renderers do not replace a scheduling engine: validate dates, dependencies, and resource constraints before drawing.27+28+## Review29+30+- Is the as-of date, calendar, and timezone visible?31+- Does each task have an owner, outcome, and realistic duration?32+- Are dependencies meaningful and free of cycles?33+- Are milestones outcomes and progress semantics unambiguous?34+- Does the chart distinguish plan, actual, baseline, and uncertainty?35+36+## Prior art and limitations37+38+Use project-scheduling vocabulary from [ISO 21502:2020](https://www.iso.org/standard/74947.html) and dependency concepts from [PMI’s Practice Standard for Scheduling](https://www.pmi.org/pmbok-guide-standards/practice-guides/scheduling). These sources guide the planning model; they do not prescribe one SVG notation.39+40+The available renderers do not calculate critical paths, resource leveling, calendars, or earned value. Integration with a scheduling model/validator would be needed for authoritative planning rather than presentation-only charts.@@ -0,0 +1,38 @@
1+---2+name: hdl-component-diagram3+description: Use when the user needs a hardware-design view of HDL entities, modules, interfaces, ports, parameters, clocks, resets, and hierarchy.4+---5+6+# HDL component diagram7+8+## Select it when9+10+Choose this skill to explain a Verilog/SystemVerilog module hierarchy or VHDL entity/architecture boundary and its interfaces. Use it for design review, onboarding, integration planning, and clock/reset documentation. Do not use it as a substitute for RTL, a timing report, a gate-level netlist, or an electrical schematic.11+12+## Story and modeling13+14+Decide whether the story is hierarchy, interface contract, or clock/reset flow. Show module/entity names, instance boundaries, port direction, width, protocol role, clock domain, reset polarity/synchrony, parameters/generics, and meaningful buses. Distinguish combinational/data paths from clocks, resets, interrupts, and sidebands. Keep implementation detail out unless it answers the review question; link to source paths and generated netlist reports when available.15+16+The picture is an explanatory abstraction. It is not proof that RTL elaborates, synthesizes, meets timing, or matches a pin constraint. Never infer signal widths or clock domains from line styling alone.17+18+## Styling and customization19+20+Use nested containers for hierarchy, consistent port-side placement, and labeled bus widths. Give clocks and resets a clearly documented visual treatment, but provide labels so color is not the only encoding. Use one visual grammar for module interfaces and another for external pins or board connections. Highlight only the path under review and put protocol details in notes or a companion table.21+22+## Renderer routing23+24+Preserve a renderer explicitly requested by the user. Prefer `symbolator` when VHDL or Verilog declarations should produce a component symbol with ports, groups, and widths. Use `plantuml`, `d2`, or `graphviz` for module hierarchy and dependencies, or `diagramsnet` when manual port placement is essential. Symbolator parses a useful declaration subset; diagram.zip does not validate complete Verilog, SystemVerilog, VHDL, SVA, CDC constraints, or synthesis output.25+26+## Review27+28+Check that every shown port has direction and width where relevant, interfaces are not confused with instances, clock/reset domains are explicit, and omitted signals are called out. Verify names against elaborated RTL or a netlist. Check fan-out, bidirectional buses, clock crossings, and reset release assumptions. Mark the source revision and whether the view is pre- or post-elaboration.29+30+## References31+32+- [IEEE 1800-2023 SystemVerilog](https://standards.ieee.org/standard/1800-2023.html) — language standard; diagram.zip does not parse or validate the full language.33+- [IEEE 1076-2019 VHDL](https://standards.ieee.org/standard/1076-2019.html) — VHDL language standard; entity/architecture terminology here follows it at a high level.34+- [IEEE 1801-2024 UPF](https://standards.ieee.org/standard/1801-2024.html) — power intent can affect hardware views but is not represented automatically.35+36+## Integration opportunities37+38+Standards-compliant HDL-aware authoring would require parser/elaborator integration, width and direction checks, clock-domain analysis, source links, and optional synthesis/netlist import. Current renderers only provide depiction.@@ -0,0 +1,34 @@
1+---2+name: hierarchy-diagram3+description: Use when the user needs a ranked, nested, or reporting structure such as a taxonomy, organization chart, tree, or work breakdown structure.4+---5+6+# Hierarchy diagram7+8+## What / why9+10+A hierarchy diagram shows parent-child levels. It tells the story “what contains, reports to, or decomposes into what?” Name the relationship because taxonomy, authority, and work decomposition are not interchangeable.11+12+## How to model13+14+- Declare the hierarchy kind and root before adding nodes.15+- Give each node one parent unless multiple inheritance is explicitly intended.16+- Keep siblings at the same abstraction level; avoid mixing roles, instances, and tasks.17+- For a WBS, use verb-led deliverables and decompose until work is estimable; for an org chart, use roles and reporting lines; for a taxonomy, use concepts and “is-a” relationships.18+- Show cross-links separately from the tree so they cannot be mistaken for parentage.19+20+## Styling and customization21+22+Use top-down or left-to-right levels, aligned siblings, consistent node sizes, and whitespace. Use color to distinguish categories or departments, not depth alone. For org charts, label role and optionally person separately; for WBS, show identifiers and status secondarily.23+24+## Renderer choices25+26+Preserve user choice. Mermaid flowcharts/mindmaps and Graphviz/DOT are good for generated trees; PlantUML can express deployment/component-style hierarchies; D2 and diagrams.net suit bespoke layouts. diagram.zip has no dedicated org-chart or WBS semantic renderer: use supported syntax and document relationship semantics in labels.27+28+## Review29+30+Verify one root (or explain a forest), consistent parent semantics, no accidental cycles, readable levels, and a legend for dashed or secondary links. Check that a WBS is deliverable-oriented rather than merely an org chart.31+32+## Prior art and gaps33+34+See [references/prior-art.md](references/prior-art.md). ArchiMate, SysML, and formal WBS interchange are not rendered as native diagram.zip semantic types; integration would require a parser/profile and conformance checks.@@ -0,0 +1,7 @@
1+# Hierarchy references2+3+- [PMI Work Breakdown Structure practice standard](https://www.pmi.org/standards/work-breakdown-structures) — prior art for deliverable-oriented decomposition and the 100-percent rule.4+- [Graphviz DOT documentation](https://graphviz.org/documentation/) — supported automatic tree layout.5+- [Mermaid flowchart syntax](https://mermaid.js.org/syntax/flowchart.html) — supported hierarchical graph syntax.6+7+Org-chart and taxonomy semantics are conventions rather than one universal interchange standard. Do not claim a generic tree is an ArchiMate or SysML view without implementing that standard.@@ -0,0 +1,34 @@
1+---2+name: matrix-diagram3+description: Use when the user needs to compare two dimensions, expose a portfolio or prioritization space, or show a many-to-many relationship in a grid or quadrant.4+---5+6+# Matrix diagram7+8+## What / why9+10+A matrix places items against two or more declared dimensions. It tells the story “how does each item compare across these axes?” Use it for prioritization, responsibility, compatibility, or traceability; choose a graph when relationships themselves are the focus.11+12+## How to model13+14+- Name each axis, direction, unit, and scale before placing items.15+- Define whether cells mean intersection, score, responsibility, presence, or absence.16+- Use a consistent measure and show missing/unknown values explicitly.17+- Keep quadrant thresholds visible; do not let position imply precision the data does not have.18+- For a responsibility matrix, define roles and accountabilities rather than generic marks.19+20+## Styling and customization21+22+Use a quiet grid, strong headers, ample cell padding, and a colorblind-safe palette. Add values or labels so meaning does not depend on color or position. For a quadrant, annotate thresholds; for traceability, use symbols with a legend and accessible text.23+24+## Renderer choices25+26+Preserve user choice. diagrams.net and custom SVG are best for precise grids; Mermaid, D2, and Graphviz can approximate matrices with tables/subgraphs, and Vega/Vega-Lite suit data-driven matrices or heatmaps. diagram.zip has no dedicated semantic matrix or quadrant type, so renderer styling cannot substitute for axis definitions.27+28+## Review29+30+Check units, axis direction, ordering, thresholds, empty cells, legend, and accessibility. Verify rankings are not inferred from an arbitrary sort. If it is a heatmap, inspect the color scale and provide numeric values.31+32+## Prior art and gaps33+34+See [references/prior-art.md](references/prior-art.md). There is no single matrix interchange standard in diagram.zip; a data-driven matrix/heatmap integration could add schema validation and accessible tabular alternatives.@@ -0,0 +1,7 @@
1+# Matrix references2+3+- [W3C WCAG 2.2](https://www.w3.org/TR/WCAG22/) — accessibility requirements for non-text contrast, use of color, and text alternatives.4+- [Vega-Lite documentation](https://vega.github.io/vega-lite/) — supported declarative data-visualization renderer for quantitative matrices and heatmaps.5+- [RACI model](https://www.pmi.org/learning/library/responsible-accountable-consulted-informed-raci-roles-7382) — established prior art for responsibility matrices.6+7+diagram.zip does not currently expose a matrix schema, automatic color-scale validator, or ARIA/table alternative generator. Those are concrete integration opportunities if matrices become a first-class semantic type.@@ -0,0 +1,33 @@
1+---2+name: mind-map3+description: Use when the user needs to explore one central topic through associative branches, capture brainstorming, or organize an unconstrained idea space before choosing a structure.4+---5+6+# Mind map7+8+## What / why9+10+A mind map radiates from one central subject. It tells the story “what belongs around this idea?” rather than “what causes what?” Use it to externalize a messy topic, reveal themes, and identify next questions. Choose another skill when relationships need to be typed, ordered, causal, or exhaustive.11+12+## How to model13+14+- Put one unambiguous topic at the center; make branch labels nouns or short prompts.15+- Keep one concept per node and use a stable depth (topic → theme → detail).16+- Prefer parent-child containment. Do not imply sequence, ownership, or causality with an ordinary branch.17+- Mark questions, examples, decisions, and unknowns distinctly; do not bury caveats in prose.18+19+## Styling and customization20+21+Use radial or left-to-right layout, short labels, whitespace, and restrained color. Reserve color for branch families or status, and use line weight sparingly. A bespoke style may use icons, but every visual distinction needs a legend or clear label.22+23+## Renderer choices24+25+Ask for the user’s renderer preference first. Mermaid supports mind maps and configurable themes/layouts; D2, Graphviz, PlantUML, and diagrams.net can express tree-like maps but do not guarantee a mind-map grammar. Use native layout where possible; do not force a flowchart and call it a mind map. diagram.zip has no dedicated semantic mind-map validator, so validate hierarchy and labels in the source.26+27+## Review28+29+Check exactly one center, readable branches without color, comparable sibling levels, and no connector implying an unsupported relationship. Confirm whether the map is exploratory or a final taxonomy.30+31+## Prior art32+33+See [references/prior-art.md](references/prior-art.md).@@ -0,0 +1,6 @@
1+# Mind-map references2+3+- [Tony Buzan’s mind map guidance](https://www.tonybuzan.com/about/mind-mapping/) — prior art for a central image, radiating branches, keywords, and visual association.4+- [Mermaid mindmap syntax](https://mermaid.js.org/syntax/mindmap.html) — supported diagram.zip renderer syntax; check current renderer behavior before relying on experimental features.5+6+Mind maps have no single ISO/OMG interchange standard. A standards-based taxonomy or concept map may be a better fit when formal semantics are required.@@ -0,0 +1,52 @@
1+---2+name: network-topology3+description: Document physical or logical networks with nodes, interfaces, links, segments, addressing, trust zones, and traffic boundaries.4+---5+6+# Network topology7+8+## Select this skill when9+10+Use this skill when the story is connectivity: which devices or services attach to which network, how traffic can flow, where trust boundaries sit, or how a physical installation is wired. State whether the view is physical, logical, or both.11+12+Avoid it for application call dependencies (use dependency-graph), packet field layout (use protocol-layout-diagram), rack-unit placement (use rack-diagram), or a general system context. Do not use a topology map to imply that an application call is permitted merely because two nodes share a segment.13+14+## Story and semantic model15+16+Name the scope, observation time, and layer. Identify devices, interfaces, links, network segments, address ranges, VLANs, zones, gateways, and trust boundaries as appropriate. Define link direction and capacity only when known.17+18+- Distinguish physical links from logical adjacencies, tunnels, overlays, and routes.19+- Label interfaces or endpoints when a device has multiple connections.20+- Show layer-3 prefixes and layer-2 segments separately; do not conflate an IP range with a broadcast domain.21+- Mark ingress/egress, filtering devices, and trust boundaries with explicit labels.22+- Treat cloud and external networks as boundaries with ownership and assumptions, not as opaque decorative clouds.23+24+For a change review, highlight the affected path and annotate source-of-truth evidence. For incident response, show observed state and timestamp rather than presenting an intended design as fact.25+26+## Layout and styling27+28+Use nested containers for sites, zones, or segments. Arrange traffic flow consistently (left-to-right or top-to-bottom), keep gateways at boundaries, and attach labels close to interfaces. Use shape for device class and line style for physical/logical/tunnel links. Use color for trust or operational status only with a legend and a text fallback.29+30+Include a legend for abbreviations, link semantics, and address notation. Avoid unlabeled line crossings; if a link crosses a boundary, make the crossing explicit.31+32+## Renderer routing33+34+Preserve an explicit renderer choice. Otherwise prefer:35+36+- `nwdiag` for network blocks, hosts, addresses, and shared segments.37+- `d2` for custom logical/physical topology with containers and annotations.38+- `graphviz` for topology-as-graph or route-focused views.39+- `mermaid` for a small Markdown-friendly network map.40+- `diagramsnet` for manually positioned physical topology documentation.41+42+`nwdiag` is convenient but does not express every routing, security-policy, or vendor-device semantic. diagram.zip does not discover devices, test reachability, or validate IP plans. If the user requires import/export to a network-management or vendor topology format, live inventory integration, or formal path-policy validation, call that an unsupported integration opportunity.43+44+## Review checklist45+46+Check that scope, layer, timestamp, and ownership are stated. Verify every link has endpoints and a defined meaning, every segment has a boundary, and addresses are not invented. Confirm that physical and logical relationships are not visually conflated. Review the highlighted path against current source-of-truth data and test the final diagram at print or incident-room size.47+48+## Standards and prior art49+50+RFC 2360 documents conventions for Internet protocol documentation and packet/network figures: <https://www.rfc-editor.org/rfc/rfc2360>. ISO/IEC 27001 and 27002 provide information-security control context for network zones and access boundaries, but do not prescribe a single topology notation: <https://www.iso.org/isoiec-27001-information-security.html>.51+52+Network topology notation is largely operational prior art rather than one universal exchange standard. Declare the layer and legend. For formal network configuration or topology exchange, diagram.zip currently has no dedicated NETCONF/YANG, vendor NMS, or inventory adapter; that is an integration opportunity.@@ -0,0 +1,56 @@
1+---2+name: protocol-layout-diagram3+description: Use when a diagram must explain the bit, byte, or word layout of a protocol message, file header, register, or binary record.4+---5+6+# Protocol layout diagram7+8+## What it is9+10+A protocol layout diagram maps wire-order positions to named fields. It tells the reader how many bits or bytes each field occupies, where boundaries fall, which values are interpreted together, and which parts are conditional or repeated.11+12+## Choose it when13+14+- the question is “what is at offset N?” or “how is this message encoded?”15+- implementation, interoperability, packet capture, or security review depends on exact widths and ordering;16+- a prose table would hide alignment, reserved bits, endianness, or optional extensions.17+18+Use a sequence or flow diagram for message behavior. Use a data-flow diagram for movement between components. Do not use this diagram to imply that fields are sent in the order they are drawn unless wire order is explicitly stated.19+20+## Story and modeling21+22+1. State the unit and orientation: bits per row, byte order, bit numbering convention, and whether offsets are absolute or relative.23+2. Draw the fixed header first, then conditional, repeated, and payload regions. Mark variable-length fields with their length rule.24+3. Give every field a name, width/range, and interpretation. Show reserved bits and whether they must be zero, ignored, or preserved.25+4. Separate normative wire facts from explanatory annotations. Record the specification version and section beside the title or in a legend.26+5. Check examples against the encoding: widths must sum to the row width, offsets must not overlap, and endianness must agree with the prose.27+28+## Styling and customization29+30+Use a restrained palette: one color for fixed framing, one for payload, one for control/flags, and a visibly distinct treatment for reserved or deprecated fields. Put bit numbers above the row and byte offsets below it. Keep labels short and move long semantics into notes. For accessibility, do not communicate field meaning by color alone; use text, patterns, or a legend.31+32+## Renderer routing33+34+- `packetdiag` is the direct diagram.zip fit for bit-field layouts; preserve its column width and field-range semantics.35+- `bytefield` is useful for byte-oriented headers and payloads when a code-defined, repeatable layout is preferred.36+- `wavedrom` can express registers and bus transactions when timing is part of the story, but it is not a substitute for a normative packet layout.37+- `tikz` or `pikchr` can be a bespoke escape hatch when a standards-specific notation exceeds those renderers.38+39+Keep the user's explicit renderer choice. If no renderer is specified, choose the smallest source that preserves exact widths and explain the choice. diagram.zip does not currently provide a dedicated parser/validator for every protocol standard; a standards-aware packet editor or automatic field-sum validation would be a useful integration opportunity.40+41+## Review checklist42+43+- Is wire order, bit numbering, and unit unambiguous?44+- Do widths, offsets, and alignment add up?45+- Are optional, repeated, reserved, and extension fields explicit?46+- Are byte order and value encoding documented?47+- Is the cited specification/version recoverable?48+- Can a reader distinguish normative fields from commentary without color?49+50+## References51+52+- [RFC 2360, section 3.3](https://www.rfc-editor.org/rfc/rfc2360.html#section-3.3) summarizes conventions for protocol diagrams and field representations.53+- [RFC 791, section 3.1](https://www.rfc-editor.org/rfc/rfc791.html#section-3.1) is a canonical example of an Internet header bit layout and field description.54+- [RFC 8200, section 3](https://www.rfc-editor.org/rfc/rfc8200.html#section-3) shows the IPv6 base-header field layout and extension-header model.55+- [PacketDiag documentation](http://blockdiag.com/en/nwdiag/packetdiag-examples.html) documents the diagram.zip-supported PacketDiag source model.56+- [Bytefield SVG documentation](https://bytefield-svg.deepsymmetry.org/) documents byte-oriented source forms.@@ -0,0 +1,55 @@
1+---2+name: rack-diagram3+description: Use when documenting equipment placement in a cabinet or rack, including rack units, device identity, power, network uplinks, and physical capacity.4+---5+6+# Rack diagram7+8+## What it is9+10+A rack diagram is a vertical physical inventory view. It tells the reader what occupies each rack unit, where blanking panels and shared equipment are, and how to identify or service the installed hardware.11+12+## Choose it when13+14+- operations, facilities, installation, maintenance, or capacity planning depends on physical rack position;15+- a cabinet contains servers, switches, patch panels, PDUs, UPS units, shelves, or reserved space;16+- the reader needs a fast unit-by-unit inventory rather than a logical topology.17+18+Pair it with a network-topology diagram for logical links and a deployment diagram for software placement. Do not infer power, airflow, cable path, or network connectivity from vertical adjacency alone.19+20+## Story and modeling21+22+1. Name the site, room, cabinet, face (front/rear), orientation, and rack-unit numbering direction.23+2. Show total usable U height and every occupied, reserved, and intentionally blank unit. Represent multi-U devices at their actual height.24+3. Label each device with asset/service identity, model or role, and U range. Use a legend for shared devices, patch panels, PDUs, and blanking panels.25+4. Add power feeds, cable management, airflow direction, and rear-view details only when they are in scope; distinguish planned, installed, and decommissioned equipment.26+5. Include revision/date and an authoritative inventory reference. A rack drawing is not an asset database.27+28+## Styling and customization29+30+Use a stable visual grammar: one unit grid, consistent device height, strong cabinet boundaries, and restrained colors by equipment role. Use labels and symbols in addition to color. Keep identifiers legible at print scale, and use callouts for dense front/rear cabling rather than crossing the rack body with wires.31+32+## Renderer routing33+34+- `rackdiag` is the direct diagram.zip fit and preserves rack-unit placement and device height.35+- `diagramsnet` is appropriate when a facilities team needs to edit a native physical-layout document.36+- `diagramsnet` or `tikz` can support bespoke front/rear views, airflow arrows, or detailed cable callouts.37+- `nwdiag` shows network segments, not physical cabinet placement; pair it when logical connectivity matters.38+39+Preserve the user's explicit renderer choice. If no renderer is specified, choose `rackdiag` for an inventory-style rack and explain what it cannot represent. diagram.zip does not currently ingest DCIM/CMDB inventories, validate U conflicts, or model thermal/power budgets. Importing an authoritative inventory and checking occupied-unit, power, and airflow constraints would be a meaningful integration opportunity.40+41+## Review checklist42+43+- Are cabinet identity, face, orientation, and U numbering explicit?44+- Do device heights and U ranges avoid overlap and fit the cabinet?45+- Are blank, reserved, planned, and decommissioned units distinguished?46+- Are asset identity and revision/date present?47+- Are power, airflow, and cabling claims backed by source data?48+- Is logical connectivity kept separate or clearly linked to another view?49+50+## References51+52+- [RackDiag examples](http://blockdiag.com/en/nwdiag/rackdiag-examples.html) documents the diagram.zip-supported rack-unit source model.53+- [ANSI/TIA-606-C](https://www.tiaonline.org/standards/standards-information/) is the telecommunications infrastructure administration and labeling standard; use the licensed standard for authoritative identifier and record requirements.54+- [ASHRAE TC 9.9](https://www.ashrae.org/technical-resources/bookstore/datacom-series) provides data-center thermal guidance; a rack drawing should not claim thermal compliance without the applicable facility analysis.55+- [Uptime Institute data-center standards](https://uptimeinstitute.com/standards) provides facility-resilience context that is outside the scope of a rack-placement renderer.@@ -0,0 +1,40 @@
1+---2+name: sequence-diagram3+description: Choose a sequence diagram when the user needs to explain ordered messages, calls, responses, or time-dependent collaboration between participants.4+---5+6+# Sequence diagram7+8+## What and why9+10+A sequence diagram tells a time-ordered interaction story. It is strongest for an API request, authentication exchange, event flow, incident trace, or one scenario across services and people. It is not a deployment map, class structure, or a complete behavioral specification.11+12+## Model it13+14+1. Name the scenario and trigger, including success or failure scope.15+2. Choose participants that send, receive, or transform a message; omit passive infrastructure.16+3. Order messages top-to-bottom and label intent, not implementation trivia.17+4. Use activation, return, loop, alternative, optional, and parallel fragments only when they clarify behavior.18+5. Mark asynchronous messages, timeouts, retries, and external boundaries explicitly.19+20+UML 2.5.1 defines interaction and combined-fragment semantics. See [UML interaction guidance](references/uml-interactions.md).21+22+## Story and styling23+24+Make the primary path easy to scan, then place alternatives in `alt`/`opt` regions. Use participant types consistently and distinguish synchronous calls from asynchronous signals. Keep lifelines aligned; use restrained color for external systems, errors, or trust boundaries. Never encode meaning by color alone.25+26+## Renderer routing27+28+Prefer `mermaid` for lightweight docs, `plantuml` for expressive UML fragments, `seqdiag` for compact message-focused diagrams, or `d2` when the sequence is part of a broader technical illustration. Preserve the user's renderer choice. `bpmn` is appropriate only when the requested story is a formal business process with BPMN events, tasks, and message flows.29+30+## Review31+32+- Is the scenario boundary and trigger explicit?33+- Does vertical order represent time without implying false duration?34+- Are request/response direction, async behavior, errors, and retries unambiguous?35+- Are fragments labeled with meaningful guards?36+- Is the diagram readable without relying on tiny labels or color alone?37+38+## Limits and opportunities39+40+diagram.zip renders sequence sources but does not execute a UML interaction validator or check trace completeness. A future integration could validate UML fragment nesting and provide conformance diagnostics.@@ -0,0 +1,7 @@
1+# UML interactions2+3+UML 2.5.1 defines interaction diagrams, lifelines, messages, executions, and combined fragments such as alternatives, options, loops, and parallel regions. Use the standard when a sequence diagram is a design artifact rather than an informal sketch.4+5+Reference: [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1).6+7+PlantUML and Mermaid provide useful notations but are not interchange validators for every UML constraint. Strict UML validation is an integration opportunity.@@ -0,0 +1,34 @@
1+---2+name: set-diagram3+description: Use when the user needs to show membership, overlap, exclusion, union, intersection, or nested categories with sets.4+---5+6+# Set diagram7+8+## What / why9+10+A set diagram tells the story “which elements belong to which sets, and where do memberships overlap?” Use Venn diagrams for a small number of sets and Euler diagrams when only meaningful intersections should be shown. Choose a graph for typed relationships or a matrix for exhaustive pairwise comparison.11+12+## How to model13+14+- Define each set and the universe or scope; state whether circles are exhaustive.15+- Put elements in regions only when membership is known; distinguish empty from unknown.16+- Label intersections with the set operation or plain-language meaning.17+- Keep set count small enough for legible regions; use an Euler representation for sparse overlaps.18+- Do not use area or circle size to imply quantity unless it is quantitatively encoded and explained.19+20+## Styling and customization21+22+Use overlapping outlines with high-contrast labels, transparent fills, and patterns or labels in addition to color. Avoid excessive intersections. Provide an accessible list/table of memberships when important, and keep the universe boundary visible when it matters.23+24+## Renderer choices25+26+Preserve user choice. Mermaid, Graphviz, D2, PlantUML, and diagrams.net can approximate set diagrams with shapes and labels; diagrams.net or custom SVG is better for controlled overlap. diagram.zip has no dedicated Venn/Euler semantic renderer or overlap solver, so verify memberships manually and do not claim proportional geometry.27+28+## Review29+30+Check every region against membership data, confirm empty/unknown regions, make labels readable, and test grayscale/colorblind viewing. Ensure the chosen Venn layout can represent stated intersections; otherwise switch to Euler or a table.31+32+## Prior art and gaps33+34+See [references/prior-art.md](references/prior-art.md). A native set renderer would need membership input, Venn/Euler layout validation, and an accessible tabular fallback; this is an integration opportunity rather than current diagram.zip support.@@ -0,0 +1,7 @@
1+# Set-diagram references2+3+- [Euler diagram definition (Encyclopaedia of Mathematics)](https://encyclopediaofmath.org/wiki/Euler_diagram) — prior art distinguishing diagrams that show only existing set intersections.4+- [Venn’s original set diagram paper](https://doi.org/10.1080/14786440508637087) — historical prior art for systematic set intersections.5+- [W3C SVG accessibility guidance](https://www.w3.org/TR/SVG-access/) — relevant when a set diagram is delivered as SVG and needs meaningful text alternatives.6+7+No supported diagram.zip renderer currently guarantees a valid Venn or Euler layout from arbitrary set membership data. Treat overlap geometry as illustrative unless an integration adds validation.@@ -0,0 +1,40 @@
1+---2+name: state-machine-diagram3+description: Choose a state-machine diagram when an entity's permitted states, event-triggered transitions, guards, and entry or exit behavior are the central story.4+---5+6+# State-machine diagram7+8+## What and why9+10+A state-machine diagram explains how one subject changes state in response to events. Use it for lifecycle rules, protocol sessions, order status, device modes, and resilient services. Do not use it when the main question is work order between participants; choose a sequence or activity diagram instead.11+12+## Model it13+14+1. Name the subject and define its initial and terminal conditions.15+2. List stable, externally meaningful states rather than every implementation flag.16+3. Label transitions `event [guard] / effect` where useful.17+4. Add entry, exit, and do behavior only when it changes the reader's interpretation.18+5. Use composite or concurrent states for genuine hierarchy or orthogonal behavior; avoid decorative nesting.19+20+UML 2.5.1 is the prior art for state machines, pseudostates, guards, and regions. See [UML state-machine guidance](references/uml-state-machines.md).21+22+## Story and styling23+24+Make states the visual anchors and transitions the explanation. Use a consistent arrow direction, explicit self-loops, and a legend for event/guard/effect syntax. Style terminal, error, and externally controlled states distinctly, with labels and shapes supporting any color choice.25+26+## Renderer routing27+28+Prefer `mermaid` for compact state diagrams, `plantuml` for UML-rich state machines, `graphviz` for explicit graph layout, or `d2` for annotated technical state views. Preserve a requested renderer. Avoid `c4plantuml`, because C4 is for software architecture structure, not lifecycle behavior.29+30+## Review31+32+- Is there exactly one subject or a clearly defined composite boundary?33+- Are initial, terminal, error, and unreachable states considered?34+- Does every transition have a meaningful trigger and destination?35+- Are guards mutually understandable and effects separated from events?36+- Are concurrency, hierarchy, and history semantics necessary and explained?37+38+## Limits and opportunities39+40+diagram.zip can render state-machine source but does not model-check reachability, determinism, deadlocks, or event completeness. A state-machine lint/verification integration would add material value for protocol and safety-critical use cases.@@ -0,0 +1,7 @@
1+# UML state machines2+3+UML 2.5.1 specifies states, transitions, triggers, guards, effects, pseudostates, composite states, regions, and state-machine ownership. Use those concepts when lifecycle behavior must be reviewed precisely.4+5+Reference: [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1).6+7+The renderers are presentation tools; they do not guarantee semantic validation of a UML state machine. Consider a future parser and model-checking integration.@@ -0,0 +1,30 @@
1+---2+name: system-context-diagram3+description: Explain one system in its environment by showing its users, external systems, and the relationships that matter.4+---5+6+# System context diagram7+8+## What it tells9+10+This view answers “what is this system, who uses it, and what does it depend on?” It shows one named system as the focal boundary plus relevant people, organizations, external systems, and high-level relationships.11+12+## Use and boundaries13+14+Use it for onboarding, product scope, stakeholder alignment, risk review, and early architecture decisions. Keep the focal system as one box. Do not open it into containers or components, and do not turn external systems into infrastructure nodes. Add a system landscape first when the audience needs portfolio context.15+16+## Method17+18+Name the system by purpose, identify actors by role, and list external systems only when they exchange information or impose a meaningful constraint. Label every relationship with a concise verb and optionally direction, protocol, or data. Make system ownership and trust boundaries explicit when they affect the story. Prefer one context diagram per focal system and audience.19+20+## Renderer routing21+22+Preserve a requested renderer. Prefer `structurizr` when the context view belongs to a reusable C4 workspace model, `c4plantuml` for a focused C4 source, `plantuml` for an unconstrained architecture view, or `mermaid`, `d2`, and `graphviz` for lightweight sketches. Use `blockdiag` only for an informal block view; it will not encode C4 roles or semantics for you.23+24+## Style and review25+26+Use a strong visual treatment for the focal system, a consistent actor shape, and a neutral external-system shape. Keep the canvas sparse, route edges clearly, and include a legend for trust or relationship patterns. Ensure the focal boundary is unambiguous, all important actors/dependencies are named, arrows are readable in grayscale, and no internal implementation details slipped in.27+28+## Prior art and limits29+30+The C4 context diagram is a widely used framing convention and is deliberately notation-independent, not a formal interchange standard. ArchiMate and UML can provide formal viewpoints, but diagram.zip does not currently expose a dedicated ArchiMate source or a profile-enforced context renderer. That is an integration opportunity if formal semantics or model exchange becomes a requirement. See [C4 diagrams](https://c4model.com/diagrams), [C4 notation](https://c4model.com/diagrams/notation), [UML](https://www.omg.org/spec/UML/2.5.1/), and [ArchiMate overview](https://www.opengroup.org/archimate-forum/archimate-overview).@@ -0,0 +1,30 @@
1+---2+name: system-landscape-diagram3+description: Show the systems and people across an organization or domain, emphasizing ownership and meaningful dependencies.4+---5+6+# System landscape diagram7+8+## What it tells9+10+A landscape is the broadest software architecture view: which systems, people, teams, or domains exist and how they relate. It tells an audience where a system sits in a wider estate, not how its internals work.11+12+## Use and boundaries13+14+Use it for portfolio orientation, modernization planning, ownership conversations, integration discovery, and explaining a system's neighbors. Choose one organizational or domain scope and state it in the title. Avoid showing classes, containers, deployment hosts, or detailed request sequences; those belong in narrower companion views.15+16+## Method17+18+Start with the audience's question and inventory only systems relevant to it. Group by business domain, ownership, or environment—not arbitrary spatial decoration. Give each node a stable name and concise purpose. Draw only relationships that support a decision, label them with a verb, and distinguish dependency from data movement or responsibility. Mark uncertainty rather than inventing an integration.19+20+## Renderer routing21+22+Honor the user's source choice. For a C4-style landscape, use `structurizr` when the landscape belongs to a reusable workspace model or `c4plantuml` for a focused source file. Use `plantuml` for a custom UML-like view, or `mermaid`, `d2`, and `graphviz` for compact relationship maps. `blockdiag` can express simple blocks but does not supply C4 semantics. Check the selected renderer's supported syntax in diagram.zip docs before writing source.23+24+## Style and review25+26+Use one shape family for systems and another for people or organizations. Cluster sparingly, keep edge crossings low, and provide a legend for colors, line types, ownership, and trust boundaries. Prefer labels and patterns over color-only coding. Review for accidental detail, duplicate nodes, unlabeled arrows, missing external actors, and a scope that is too broad to read.27+28+## Prior art and limits29+30+This follows the C4 landscape/context framing, which is notation-independent; it is not a formal ArchiMate exchange model. ArchiMate viewpoints could add standardized enterprise-architecture semantics, but diagram.zip has no dedicated ArchiMate renderer/skill yet. Consider integration if conformance or model interchange is required. See [C4 diagrams](https://c4model.com/diagrams), [C4 notation](https://c4model.com/diagrams/notation), and [ArchiMate overview](https://www.opengroup.org/archimate-forum/archimate-overview).@@ -0,0 +1,39 @@
1+---2+name: technical-illustration3+description: Use when the user needs an explanatory technical figure showing parts, assemblies, operation, dimensions, callouts, or a controlled visual sequence.4+---5+6+# Technical illustration7+8+## Select it when9+10+Choose this skill for an explanatory figure whose meaning depends on physical appearance, exploded relationships, section views, callouts, or a sequence of operation. Use it for manuals, training, proposals, and engineering communication. Do not use it for a pure graph, formal schematic, manufacturing drawing, or photorealistic product render unless that is explicitly the requested deliverable.11+12+## Story and modeling13+14+State the reader's question and the viewing convention: identify parts, show assembly order, explain motion/flow, expose an internal section, or compare states. Establish a datum/orientation, part IDs, leader-line targets, scale status, and what is intentionally omitted. Separate measured dimensions from illustrative proportions. If geometry or safety depends on exact values, link to the controlled CAD/drawing source.15+16+The output is an explanatory depiction, not automatically a standards-compliant technical product definition. A generic diagram renderer cannot guarantee projection rules, tolerances, datum systems, material hatching, or manufacturing authority.17+18+## Styling and customization19+20+Use a restrained palette, high-contrast labels, consistent line weights, and uncluttered leader lines. Use exploded offsets and transparency sparingly; preserve occlusion cues and assembly order. Number parts consistently and provide a keyed parts list. Use section hatching or dimension marks only when their convention is explained. Avoid decorative perspective that changes the apparent relationship or hides a critical interface.21+22+## Renderer routing23+24+Preserve a renderer explicitly requested by the user. Use `pikchr` or `tikz` for controlled geometry, `diagramsnet` or `excalidraw` for manually composed callouts and assembly views, and `ditaa`, `goat`, or `svgbob` for text-native sketches. Use `d2`, `graphviz`, or `plantuml` when the illustration is really a relationship abstraction. No listed renderer is a CAD, geometric-dimensioning, or photorealistic illustration engine; offer an integration gap rather than faking precision.25+26+## Review27+28+Check callout target accuracy, part numbering, orientation, section/hidden-line conventions, label legibility, contrast, and print behavior. Confirm that dimensions have units and that “not to scale” is visible where applicable. Have a domain reviewer verify the physical interpretation and compare against the controlled source. Record revision and intended audience.29+30+## References31+32+- [ISO 128-1:2020](https://www.iso.org/standard/65296.html) — general principles for technical drawings; consult the applicable part and licensed text for production work.33+- [ISO 5455:1979](https://www.iso.org/standard/11514.html) — scales for technical drawings; a renderer does not enforce scale.34+- [ISO 5457:1999](https://www.iso.org/standard/11522.html) — sizes and layout of drawing sheets; page-layout integration may be needed.35+- [IEC 61082-1](https://webstore.iec.ch/en/publication/265) — electrotechnical documentation conventions where the illustration is part of such a document.36+37+## Integration opportunities38+39+Standards-aware projection, dimensioning, tolerancing, CAD import, vector authoring, material/section conventions, and controlled title-block export are not provided by the current diagram renderers. Treat those as integration opportunities when exact engineering documentation is required.@@ -0,0 +1,40 @@
1+---2+name: timeline3+description: Use when the user needs to communicate events or milestones in chronological order, with dates, intervals, eras, or parallel tracks.4+---5+6+# Timeline7+8+## What and why9+10+A timeline tells a chronological story: what happened, when it happened, and sometimes how parallel strands relate. It is useful for releases, incidents, historical context, migrations, and roadmaps.11+12+Choose it when time is the primary organizing axis. Avoid it for task scheduling with dependencies (gantt-chart), causal process flow (flowchart), or a person’s step-by-step experience (user-journey-map).13+14+## How15+16+1. Choose the time scale and state it: dates, quarters, years, eras, or relative time.17+2. Select only events that advance the story; give each an unambiguous date or interval.18+3. Use a single track for one narrative and parallel tracks for independent streams. Keep labels short and put detail in notes.19+4. Distinguish event, milestone, interval, and uncertainty. Do not imply precision the source does not support.20+5. If the timeline is a roadmap, label commitment status separately from chronology.21+22+## Story and styling23+24+Use a strong axis and consistent date formatting. Encode event categories with shape or small color accents, but also label them for color-independent reading. Use whitespace for eras and avoid crossing annotations. For dense timelines, split into views by track or period.25+26+If no renderer is specified, use `mermaid` for its timeline syntax or `d2`/`graphviz` when custom layout is more important. These renderers do not provide a universal temporal data model; validate dates and uncertainty in the source data. Preserve an explicit renderer choice.27+28+## Review29+30+- Is the time scale and direction explicit?31+- Are dates, intervals, and uncertain dates represented honestly?32+- Can a reader distinguish tracks and event categories without color alone?33+- Does every item earn its space in the narrative?34+- Are roadmap status and chronological position kept separate?35+36+## Prior art and limitations37+38+For milestone and project communication, align terminology with [ISO 21502:2020](https://www.iso.org/standard/74947.html), while recognizing that a timeline is a communication view rather than a project-control model. For historical chronology, use the source domain’s date conventions and cite the source data.39+40+The supported text renderers do not guarantee date-aware scaling, collision avoidance, or semantic uncertainty encoding. A standards-aware timeline data model and date-scale renderer would be a useful integration opportunity.@@ -0,0 +1,40 @@
1+---2+name: use-case-diagram3+description: Use when the user needs to explain who can achieve which externally visible goals with a system, including actors, system boundaries, and goal relationships.4+---5+6+# Use-case diagram7+8+## What and why9+10+Use a use-case diagram to scope a system from the perspective of actors and their goals. It tells the story of who interacts with the system and what value they seek, not how the implementation works.11+12+Choose it when the question is “who needs which capability?” Avoid it for call ordering, internal architecture, data movement, or detailed requirements; use a sequence, context, or data-flow diagram instead.13+14+## How15+16+1. Name the system boundary and write each use case as an observable goal using a verb.17+2. Identify human, organizational, device, or external-system actors; keep actors outside the boundary.18+3. Connect actors to goals they participate in. Use `include` only for required reused behavior and `extend` only for optional behavior at an explicit extension point.19+4. Add generalization only when a specialized actor or goal is substitutable for a more general one.20+5. Keep the diagram at one scope and move scenarios, exceptions, and acceptance criteria into accompanying text.21+22+## Story and styling23+24+The visual hierarchy should make the boundary, actors, and primary goals obvious. Prefer a small set of neutral actor/system colors, strong boundary contrast, and short labels. Group use cases by capability area only when that grouping answers a real scope question; do not turn every subsystem into an actor.25+26+If the user has not chosen a renderer, use `plantuml` for UML notation or `mermaid` for a lightweight, Markdown-friendly version. `c4plantuml` is appropriate for a system-context view, not detailed use-case semantics. Preserve an explicit renderer choice. Mermaid and PlantUML can express the common notation, but neither is a requirements repository or a complete UML interchange format.27+28+## Review29+30+- Is every actor outside the system boundary and named by a role?31+- Does every use case state a user-visible goal rather than an implementation step?32+- Are `include`, `extend`, and generalization used sparingly and in the correct direction?33+- Is scope narrow enough to read without a legend-heavy wall of bubbles?34+- Are assumptions, alternate flows, and non-functional requirements documented elsewhere?35+36+## Prior art and limitations37+38+The notation follows the UML use-case model in [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1/), especially Use Cases and Relationships. For accessibility expectations for the rendered SVG, apply [WCAG 2.2](https://www.w3.org/TR/WCAG22/) and provide a meaningful title/description where the host supports it.39+40+The available renderers do not provide a standards-complete UML model exchange or traceability to requirements tools. Supporting XMI/UML interchange would be a separate integration opportunity.@@ -0,0 +1,40 @@
1+---2+name: user-journey-map3+description: Use when the user needs to understand a person’s experience across stages, touchpoints, actions, thoughts, emotions, pain points, and opportunities.4+---5+6+# User-journey map7+8+## What and why9+10+A user-journey map tells the experience story from a specific persona’s point of view across a goal-driven journey. It makes moments of friction, uncertainty, and opportunity visible to product and service teams.11+12+Choose it for experience discovery and service improvement. Avoid it for a technical request sequence (sequence-diagram), a dated delivery plan (gantt-chart), or a generic process with no user perspective (flowchart).13+14+## How15+16+1. Name the persona, situation, goal, scope, and journey start/end. State whether evidence is observed, reported, or hypothesized.17+2. Choose 4–8 stages that follow the user’s mental model, not internal team ownership.18+3. For each stage capture user actions, touchpoints/channels, questions or thoughts, emotional state, pain points, and opportunities.19+4. Add backstage dependencies only in a separate lane so the user’s experience remains primary.20+5. Rank opportunities by evidence, impact, and feasibility; do not turn an empathy map into unsupported demographic claims.21+22+## Story and styling23+24+Use stages as columns and experience dimensions as rows. Keep the persona and goal prominent, and use a small, labeled emotional curve only when it is evidence-based. Use icons sparingly, ensure labels carry meaning, and encode pain/opportunity with text plus shape or pattern—not color alone.25+26+If no renderer is specified, use `mermaid` for a simple journey/timeline-like layout or `diagramsnet` when the user needs a hand-arranged workshop canvas. `plantuml` can produce a structured activity-style approximation, but no available renderer is a dedicated journey-map model. Preserve an explicit renderer choice and explain any approximation.27+28+## Review29+30+- Is one persona, goal, and journey boundary explicit?31+- Are stages based on user behavior and evidence rather than org-chart phases?32+- Are touchpoints, backstage causes, pain, and opportunities distinguishable?33+- Are emotions framed as evidence or hypotheses?34+- Can a decision-maker see the next opportunity and its rationale?35+36+## Prior art and limitations37+38+Use the journey-mapping practice described by [Nielsen Norman Group](https://www.nngroup.com/articles/journey-mapping-101/) and service-design principles in [ISO 9241-210:2019](https://www.iso.org/standard/77520.html). These are guidance for research and communication, not a machine-readable interchange standard.39+40+The supported renderers do not encode research provenance, accessibility of workshop artifacts, or prioritization semantics. A dedicated journey-map schema with evidence and opportunity fields would be a worthwhile integration opportunity.@@ -0,0 +1,39 @@
1+---2+name: wiring-harness-diagram3+description: Use when the user needs to document wires, cables, connectors, splices, branches, pin mappings, or harness manufacturing/service information.4+---5+6+# Wiring harness diagram7+8+## Select it when9+10+Choose this skill when the important story is physical connectivity: which connector cavity, splice, terminal, shield, or wire reaches which destination. Use it for vehicle, aerospace, industrial, and test harness documentation. Do not use it for only a logical network topology, a circuit schematic, or a software dependency graph.11+12+## Story and modeling13+14+Start with the reader's task: build, inspect, troubleshoot, or modify the harness. Model connector references and cavity numbers, wire identifiers, conductor size, color, shielding, splice points, branch points, destinations, and relevant units. Separate physical route or bundle membership from electrical net identity. Mark unknown, optional, spare, and not-fitted conductors explicitly; never imply that a crossing is a connection.15+16+The diagram is a depiction, not automatically a manufacturing release. Preserve revision, source-of-truth identifiers, pin numbering conventions, and a legend. If a table is more reliable for a complete pin-to-pin netlist, pair the diagram with it.17+18+## Styling and customization19+20+Use a restrained color key for wire function or status, with line labels and a monochrome-safe alternative. Use heavier bundle lines and lighter individual conductors; show connectors as stable, labeled blocks and keep signal direction separate from physical routing. Avoid decorative colors that could be mistaken for conductor color codes. Add callouts for shield termination, splice details, bend/service loops, and cross-sheet references.21+22+## Renderer routing23+24+Preserve a renderer explicitly requested by the user. Prefer `wireviz` for connectors, cables, pins, wire colors, gauges, and connection mappings. Use `diagramsnet` for hand-positioned routes or assembly callouts, or `graphviz` and `d2` for relationship-first maps. Pair `nwdiag` only when logical network segments are a separate part of the story. WireViz models harness data, but diagram.zip does not validate terminal compatibility, bend radius, manufacturing rules, or external source-of-truth netlists.25+26+## Review27+28+Check every endpoint and cavity, connector orientation, branch/splice identity, wire label, shield/ground convention, crossing versus junction, and continuation reference. Check that the legend explains line weight, colors, and omissions, and that the output remains legible when printed in grayscale. State clearly when the result is illustrative rather than standards-compliant release data.29+30+## References31+32+- [SAE AS50881](https://www.sae.org/standards/content/as50881/) — aerospace and military wiring-system guidance; use the current licensed edition for release requirements, not this summary.33+- [IEC 60617:2026 DB](https://webstore.iec.ch/en/publication/2723) — graphical symbols for diagrams; symbol availability and licensing may require integration work.34+- [IEC 61082-1](https://webstore.iec.ch/en/publication/265) — rules for electrotechnical documentation; the renderer does not enforce its document conventions.35+- [IPC/WHMA-A-620E](https://www.ipc.org/news-release/ipc-releases-ipcwhma-620e-requirements-and-acceptance-cable-and-wire-harness) — manufacturing and acceptance requirements; a rendered harness diagram does not establish conformity.36+37+## Integration opportunities38+39+diagram.zip can depict harness structure, but it does not currently provide a standards-aware connector/cavity library, netlist validation, wire-gauge rules, terminal compatibility checks, or IEC, SAE, or IPC/WHMA conformance export. Those would be separate integration opportunities.@@ -0,0 +1,40 @@
1+---2+name: activity-diagram3+description: Choose an activity diagram when the user needs to explain workflow logic, parallel work, decisions, joins, and responsibility across actions.4+---5+6+# Activity diagram7+8+## What and why9+10+An activity diagram tells how work flows through actions and control nodes, including branching, merging, concurrency, and synchronization. Use it for algorithms, operational workflows, and cross-team procedures. Use BPMN when formal business-process events, messages, compensation, or executable process semantics matter.11+12+## Model it13+14+1. Define the activity boundary, initial condition, and completion criteria.15+2. Name actions with concise verbs and separate control flow from data flow.16+3. Use decision/merge and fork/join deliberately; a fork must have a meaningful synchronization story.17+4. Add swimlanes only to answer ownership questions; keep lane count small.18+5. Show exceptions, cancellation, and parallel completion rules when they affect the outcome.19+20+UML 2.5.1 provides the activity, action, control-node, token-flow, and partition concepts. See [UML activities](references/uml-activities.md).21+22+## Story and styling23+24+Give the happy path a stable reading direction and make concurrency visually parallel. Label guards as business conditions, not code fragments. Use lanes as responsibility bands, and reserve color for ownership or exception emphasis with a textual legend.25+26+## Renderer routing27+28+Prefer `plantuml` for UML activity semantics, `mermaid` for accessible documentation flow, `actdiag` for simple lane-oriented activities, or `d2` for a customized technical workflow. Preserve the user's requested renderer. Use `bpmn` for formal process interchange rather than translating BPMN semantics into a generic activity chart.29+30+## Review31+32+- Are actions, decisions, merges, forks, and joins distinguishable?33+- Does every parallel branch have a clear completion or cancellation rule?34+- Are swimlanes meaningful and consistently assigned?35+- Are data objects shown only when they clarify the workflow?36+- Can a reader follow normal, exception, and concurrent paths?37+38+## Limits and opportunities39+40+diagram.zip does not validate UML token-flow semantics or guarantee that an activity is deadlock-free. A UML activity parser/linter and a first-class swimlane layout profile would be useful future integrations.@@ -0,0 +1,7 @@
1+# UML activities2+3+UML 2.5.1 defines activities, actions, control nodes, object nodes, flows, and activity partitions (often rendered as swimlanes). Use the formal concepts when the workflow is a software or systems design artifact.4+5+Reference: [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1).6+7+Generic flowchart renderers can display the picture but do not validate UML activity semantics. Strict validation remains an integration opportunity.@@ -0,0 +1,38 @@
1+---2+name: architecture-dynamic-diagram3+description: Explain an architecture scenario over time by showing participating components, messages, and state changes for one concrete use case.4+---5+6+# Architecture dynamic diagram7+8+## What and why9+10+Use this skill to tell the story of one runtime scenario: who participates, what crosses boundaries, and where decisions, retries, or asynchronous work occur. It complements a static architecture view; it should not become a generic system map.11+12+## Select or avoid13+14+Select it for request lifecycles, event propagation, failure paths, migrations, and performance-sensitive interactions. Avoid it for an inventory of components, infrastructure placement, or a business process with formal events and gateways. If exact temporal order is the point, choose a sequence diagram; if spatial topology is the point, choose deployment or system landscape.15+16+## Modeling method17+18+1. State the scenario, trigger, success condition, and scope.19+2. Choose participants at one architecture level and order them by responsibility or boundary.20+3. Show the happy path first, then annotate only consequential alternatives, retries, timeouts, and failures.21+4. Distinguish synchronous calls, asynchronous messages, callbacks, and durable events.22+5. Label messages with intent and contract, not implementation trivia. Mark assumptions and omitted internals.23+24+## Styling and customization25+26+Use a clear time direction, visually separate trust or ownership boundaries, and keep alternate paths close to the message that branches. Use line styles consistently for sync/async and a single accent for failure or retry. Add duration or correlation IDs only when they answer the user’s question. Preserve a user-selected renderer; otherwise prefer `structurizr` when the scenario uses an existing C4 workspace, `c4plantuml` for a focused C4 dynamic view, `plantuml` or `mermaid` for sequence-like scenarios, and `d2` for annotated flows.27+28+## Review checklist29+30+- Is this one scenario rather than an architecture inventory?31+- Is ordering unambiguous, including asynchronous behavior?32+- Are retries, timeouts, failure ownership, and idempotency visible where relevant?33+- Are boundaries and participant abstraction levels consistent?34+- Does the diagram state what it intentionally omits?35+36+## Standards and prior art37+38+Use [C4 dynamic diagrams](https://c4model.com/diagrams/dynamic) for scenario-focused architecture narration and [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1/) for sequence/message semantics. diagram.zip can render PlantUML, C4 PlantUML, Mermaid, D2, Graphviz, and SeqDiag, but does not validate a formal UML interaction model or guarantee execution traces. Formal architecture-model interchange and analysis are integration opportunities.@@ -0,0 +1,38 @@
1+---2+name: block-diagram3+description: Arrange labeled blocks and relationships to communicate system decomposition, signal or data paths, and high-level structure without committing to a specialized formal notation.4+---5+6+# Block diagram7+8+## What and why9+10+Use this skill for a deliberately general overview: major blocks, inputs and outputs, and the paths that connect them. It is useful early in design, in technical documentation, and when a domain-specific notation would distract from the main story.11+12+## Select or avoid13+14+Select it when the audience needs a compact structural abstraction and the exact notation is not the decision. Avoid it when semantics are important enough to warrant a flowchart, component, deployment, circuit, protocol-layout, or formal SysML diagram. State whether arrows mean control, data, energy, material, or dependency; an unlabeled generic arrow is ambiguous.15+16+## Modeling method17+18+1. Write the one-sentence story and define the system boundary.19+2. Select blocks that transform, contain, or depend on something relevant to that story.20+3. Arrange blocks in the dominant flow direction and label inputs, outputs, and relationships.21+4. Group blocks only when the grouping changes interpretation; keep hierarchy shallow.22+5. Add assumptions, units, interfaces, and omitted detail as notes or a legend.23+24+## Styling and customization25+26+Use one shape family for blocks, spacing to show hierarchy, and line weight to distinguish boundary from flow. Use color for category or state, never as the only encoding. Prefer orthogonal routing for engineered paths and whitespace over connector crossings. Preserve a user-selected renderer; otherwise use D2 or Graphviz for flexible blocks, BlockDiag for automatic block layouts, Mermaid for lightweight docs, or PlantUML for a familiar architecture notation.27+28+## Review checklist29+30+- Is the meaning of each block and arrow explicit?31+- Is the abstraction level consistent?32+- Can the dominant path be followed without crossing lines?33+- Are boundary, interface, assumptions, and omitted detail visible?34+- Would a specialized diagram type communicate the decision more precisely?35+36+## Standards and prior art37+38+Block diagrams are a family of conventions rather than one universally governing notation. [ISO 5807:1985](https://www.iso.org/standard/11955.html) covers information-processing flowchart and program-network symbols, while [OMG SysML](https://www.omg.org/sysml/) formalizes block-oriented systems modeling beyond a generic sketch. diagram.zip supports generic block rendering through PlantUML, Mermaid, D2, Graphviz, BlockDiag, and diagrams.net, but does not provide SysML validation or interchange. Native SysML 2 support is an integration opportunity if demand justifies it.@@ -0,0 +1,40 @@
1+---2+name: bpmn-process3+description: Choose BPMN when the user needs a formal business-process model with events, tasks, gateways, pools, lanes, and message or sequence flows.4+---5+6+# BPMN process7+8+## What and why9+10+BPMN is a business-process notation and metamodel, not merely a flowchart style. Use it for cross-organization processes, orchestration, choreography, exception events, compensation, and process-engine interchange. Use a generic flowchart or activity diagram for an informal procedure without BPMN semantics.11+12+## Model it13+14+1. Define participants and process boundaries; use pools and lanes for responsibility.15+2. Start with start/end events and the business outcome.16+3. Choose tasks by business meaning, then add gateways only for real control decisions.17+4. Use sequence flow inside a process and message flow between participants; never conflate them.18+5. Model timer, error, escalation, compensation, subprocess, and data semantics only when they affect execution or understanding.19+20+BPMN 2.0.2 is standardized by OMG and ISO 19510. See [BPMN references](references/bpmn-standard.md).21+22+## Story and styling23+24+Make participant boundaries and the normal process path obvious. Use event markers and gateway labels consistently. Keep diagram interchange positions stable when XML is exchanged, and use restrained colors for roles or exceptions. Explain any vendor-specific extensions in a legend or note.25+26+## Renderer routing27+28+Use `bpmn` when BPMN 2.0 XML and formal interchange are required. Use `plantuml` or `mermaid` only for an intentionally BPMN-like explanatory sketch, and state that it is not BPMN interchange. `graphviz` or `d2` can show a business process but cannot preserve BPMN semantics. Preserve an explicitly requested renderer.29+30+## Review31+32+- Are pools, lanes, sequence flows, and message flows used for their intended meanings?33+- Is each gateway type justified by the process behavior?34+- Are event triggers and exception paths explicit?35+- Are start/end events and subprocess boundaries coherent?36+- Does the XML include stable IDs and diagram interchange where exchange requires it?37+38+## Limits and integration opportunities39+40+diagram.zip supports BPMN rendering, but it does not promise full BPMN conformance validation, execution semantics, vendor-extension compatibility, or process-model analysis. A BPMN 2.0.2 validator, lint ruleset, and round-trip interchange tests would be valuable integrations.@@ -0,0 +1,7 @@
1+# BPMN standard2+3+BPMN 2.0.2 defines the notation, metamodel, and interchange concepts for business-process diagrams. ISO 19510 adopts the BPMN specification. Use the specification's distinction between sequence flow, message flow, events, activities, gateways, pools, and lanes when producing a formal model.4+5+References: [OMG BPMN 2.0.2](https://www.omg.org/spec/BPMN/2.0.2/) and [ISO 19510](https://www.iso.org/standard/62652.html).6+7+Rendering BPMN XML is not the same as validating or executing it. Treat validator, conformance profiles, and vendor-extension handling as explicit integration opportunities.@@ -0,0 +1,139 @@
1+export const skillGroups = [2+ { id: 'workflow', label: 'Routing and collaboration' },3+ { id: 'behavior', label: 'Behavior and process' },4+ { id: 'architecture', label: 'Software and system structure' },5+ { id: 'conceptual', label: 'Conceptual and planning' },6+ { id: 'data', label: 'Data visualization' },7+ { id: 'technical', label: 'Technical and hardware' },8+]9+10+const skill = (id, label, group, role, question, useCases, avoidWhen) => ({11+ id,12+ label,13+ group,14+ role,15+ question,16+ useCases,17+ avoidWhen,18+})19+20+export const diagramSkills = [21+ skill('diagramming', 'Choose a diagram', 'workflow', 'router', 'Which visual story best answers the reader\'s question?', ['Route a diagram request by meaning', 'Choose a renderer after choosing the story'], ['The user already selected a semantic diagram type']),22+ skill('diagram-workshop', 'Diagram workshop', 'workflow', 'workflow', 'What should we discover together before committing to a diagram?', ['Facilitate an explicit, user-led diagram design session'], ['A focused request can be handled directly']),23+ skill('diagram-review', 'Review a diagram', 'workflow', 'Does the diagram tell its intended story accurately and accessibly?', ['Review semantics, readability, fidelity, and accessibility'], ['The request is only to choose a diagram family']),24+25+ skill('flowchart', 'Flowchart', 'behavior', 'diagram', 'What path does work follow through steps and decisions?', ['Procedures', 'Algorithms', 'Decision-heavy workflows'], ['Time-ordered interactions need lifelines', 'Formal business semantics require BPMN']),26+ skill('sequence-diagram', 'Sequence diagram', 'behavior', 'diagram', 'Who communicates with whom, and in what order?', ['API calls', 'Runtime collaborations', 'Request and response flows'], ['The main story is static structure']),27+ skill('state-machine-diagram', 'State machine diagram', 'behavior', 'diagram', 'Which events cause an entity to change state?', ['Lifecycle rules', 'Protocol states', 'UI state transitions'], ['The story is a sequence of work rather than persistent state']),28+ skill('activity-diagram', 'Activity diagram', 'behavior', 'diagram', 'How does work flow across actions, branches, and owners?', ['Concurrent workflows', 'Swimlane processes', 'UML behavioral modeling'], ['The process requires executable BPMN semantics']),29+ skill('bpmn-process', 'BPMN process', 'behavior', 'diagram', 'How does a formal business process coordinate work, events, and participants?', ['Auditable business processes', 'Message flows', 'Exception and event handling'], ['A lightweight explanatory flow is sufficient']),30+ skill('use-case-diagram', 'Use-case diagram', 'behavior', 'diagram', 'Which actors pursue which goals through the system?', ['Scope conversations', 'Actor goals', 'System boundary discussions'], ['Detailed interaction order or internal design is required']),31+ skill('data-flow-diagram', 'Data-flow diagram', 'behavior', 'diagram', 'Where does data originate, move, transform, and rest?', ['Information flows', 'Trust-boundary analysis', 'Data-processing overviews'], ['Control flow or message timing is the main concern']),32+ skill('timeline', 'Timeline', 'behavior', 'diagram', 'What happened, or will happen, in chronological order?', ['Milestones', 'Historical narratives', 'Release evolution'], ['Durations and dependencies drive the story']),33+ skill('gantt-chart', 'Gantt chart', 'behavior', 'diagram', 'When do tasks occur, overlap, and depend on each other?', ['Project schedules', 'Critical dependencies', 'Delivery planning'], ['Only milestone chronology is needed']),34+ skill('user-journey-map', 'User journey map', 'behavior', 'diagram', 'What does a person experience across stages of a goal?', ['Experience mapping', 'Touchpoints', 'Pain points and opportunities'], ['The request is for system behavior without a user-experience lens']),35+36+ skill('choose-architecture-diagram', 'Choose an architecture diagram', 'architecture', 'router', 'Which abstraction level and viewpoint will answer the architecture question?', ['Route among landscape, context, container, component, dynamic, and deployment views'], ['The user already selected an architecture view']),37+ skill('system-landscape-diagram', 'System landscape diagram', 'architecture', 'diagram', 'How do systems and people relate across an organization or domain?', ['Enterprise system portfolios', 'Cross-system dependencies', 'Ownership context'], ['The focus is one system and its immediate environment']),38+ skill('system-context-diagram', 'System context diagram', 'architecture', 'diagram', 'How does one system interact with people and external systems?', ['C4 system context', 'Scope and boundary communication'], ['Internal applications or deployable units must be shown']),39+ skill('container-diagram', 'Container diagram', 'architecture', 'diagram', 'What deployable or runnable units make up the system?', ['C4 containers', 'Technology responsibilities', 'Inter-container communication'], ['Code-level components or infrastructure instances are the focus']),40+ skill('component-diagram', 'Component diagram', 'architecture', 'diagram', 'Which components collaborate inside a container or subsystem?', ['C4 components', 'UML components', 'Module responsibility'], ['Only system-level scope is needed']),41+ skill('architecture-dynamic-diagram', 'Architecture dynamic diagram', 'architecture', 'diagram', 'How do architecture elements collaborate for one scenario?', ['C4 dynamic views', 'Cross-boundary runtime stories'], ['A reusable protocol sequence needs detailed lifelines']),42+ skill('deployment-diagram', 'Deployment diagram', 'architecture', 'diagram', 'Where do software instances run, and how are they connected?', ['Runtime topology', 'Infrastructure mapping', 'C4 or UML deployment views'], ['Logical structure without runtime placement is enough']),43+ skill('block-diagram', 'Block diagram', 'architecture', 'diagram', 'What are the major functional blocks and their interfaces?', ['Functional decomposition', 'System overviews', 'Signal or responsibility boundaries'], ['A stricter domain notation is required']),44+ skill('class-diagram', 'Class diagram', 'architecture', 'diagram', 'What types exist and how are their structures related?', ['Domain models', 'Object-oriented design', 'Static type relationships'], ['The main story concerns data persistence tables']),45+ skill('entity-relationship-diagram', 'Entity-relationship diagram', 'architecture', 'diagram', 'Which data entities exist and how are they related?', ['Conceptual data models', 'Relational schemas', 'Cardinality review'], ['Runtime object behavior is the focus']),46+ skill('dependency-graph', 'Dependency graph', 'architecture', 'diagram', 'What depends on what, and where are cycles or critical paths?', ['Package dependencies', 'Build graphs', 'Service dependencies'], ['Ordered interactions or physical topology are central']),47+ skill('network-topology', 'Network topology', 'architecture', 'diagram', 'Which network zones, devices, and links connect?', ['Logical networks', 'Addressed segments', 'Connectivity and trust boundaries'], ['Application behavior rather than connectivity is the focus']),48+49+ skill('mind-map', 'Mind map', 'conceptual', 'diagram', 'What ideas radiate from one central topic?', ['Brainstorming', 'Early exploration', 'Topic decomposition'], ['Relationships need explicit semantic labels']),50+ skill('concept-map', 'Concept map', 'conceptual', 'diagram', 'Which concepts relate, and what do those relationships mean?', ['Knowledge models', 'Explanatory relationship networks'], ['A single-root hierarchy is sufficient']),51+ skill('hierarchy-diagram', 'Hierarchy diagram', 'conceptual', 'diagram', 'How is a set organized into parent-child levels?', ['Trees', 'Organization charts', 'Work breakdown structures'], ['Many-to-many relationships carry the meaning']),52+ skill('decision-tree', 'Decision tree', 'conceptual', 'diagram', 'Which choices or tests lead to which outcomes?', ['Decision guidance', 'Classification logic', 'Scenario branching'], ['The goal is to depict an operational process with loops']),53+ skill('matrix-diagram', 'Matrix diagram', 'conceptual', 'diagram', 'How do items compare across two dimensions?', ['Quadrants', 'Responsibility matrices', 'Pairwise relationship grids'], ['Geometric set overlap or time is the main encoding']),54+ skill('set-diagram', 'Set diagram', 'conceptual', 'diagram', 'How do categories overlap or contain one another?', ['Venn diagrams', 'Euler diagrams', 'Set relationships'], ['Exact quantities or many sets must be compared']),55+56+ skill('choose-data-visualization', 'Choose a data visualization', 'data', 'router', 'Which visual encoding best supports the analytical task and data?', ['Comparison', 'Trend', 'Distribution', 'Relationship', 'Composition', 'Flow', 'Geography'], ['The request is a conceptual diagram rather than a quantitative display']),57+58+ skill('protocol-layout-diagram', 'Protocol layout diagram', 'technical', 'diagram', 'How are bits or bytes allocated within a protocol record?', ['Packet headers', 'Binary formats', 'Byte-field documentation'], ['Message ordering or state transitions are the focus']),59+ skill('digital-timing-diagram', 'Digital timing diagram', 'technical', 'diagram', 'How do digital signals change relative to time and each other?', ['Clocked logic', 'Bus transactions', 'Signal constraints'], ['The request is for an analog waveform plot']),60+ skill('rack-diagram', 'Rack diagram', 'technical', 'diagram', 'Which equipment occupies each rack unit?', ['Capacity planning', 'Datacenter documentation', 'Equipment placement'], ['Logical network connectivity is the primary story']),61+ skill('wiring-harness-diagram', 'Wiring harness diagram', 'technical', 'diagram', 'How do connectors, conductors, and terminations map?', ['Harness assembly', 'Pin-to-pin connectivity', 'Cable documentation'], ['Circuit behavior or board-level electronics are the focus']),62+ skill('hdl-component-diagram', 'HDL component diagram', 'technical', 'diagram', 'How do HDL modules, ports, and signal paths connect?', ['RTL hierarchy', 'Module interfaces', 'Hardware design review'], ['Gate-level timing or physical wiring is the focus']),63+ skill('circuit-diagram', 'Circuit diagram', 'technical', 'diagram', 'Which electronic components connect into a circuit?', ['Schematic communication', 'Electrical connectivity', 'Circuit explanation'], ['Physical harness routing or enclosure placement is needed']),64+ skill('technical-illustration', 'Technical illustration', 'technical', 'diagram', 'Which spatial or mechanical relationships must the reader see?', ['Exploded views', 'Annotated assemblies', 'Physical instructions'], ['Abstract relationships can be communicated more precisely with a diagram notation']),65+]66+67+export const diagramSkillIds = diagramSkills.map(({ id }) => id)68+69+export const standardsSupport = [70+ {71+ id: 'bpmn-2.0.2',72+ name: 'OMG BPMN 2.0.2',73+ status: 'source-supported',74+ relatedSkills: ['bpmn-process'],75+ note: 'The BPMN renderer accepts BPMN 2.0 XML and diagram interchange data. Treat rendering as separate from complete semantic validation.',76+ source: 'https://www.omg.org/spec/BPMN/2.0.2/',77+ },78+ {79+ id: 'uml-2.5.1',80+ name: 'OMG UML 2.5.1',81+ status: 'visual-subset',82+ relatedSkills: ['use-case-diagram', 'sequence-diagram', 'state-machine-diagram', 'activity-diagram', 'class-diagram', 'component-diagram', 'deployment-diagram'],83+ note: 'PlantUML and other renderers cover useful UML views, but diagram.zip does not validate the complete metamodel or import and export UML XMI and UMLDI.',84+ source: 'https://www.omg.org/spec/UML/2.5.1/',85+ integration: { reward: 'medium', effort: 'large', scope: 'UML XMI/UMLDI import, model validation, profile handling, and round-trip fidelity' },86+ },87+ {88+ id: 'iso-5807-1985',89+ name: 'ISO 5807:1985',90+ status: 'visual-conventions',91+ relatedSkills: ['flowchart'],92+ note: 'General renderers can apply its flowchart conventions, but diagram.zip does not validate symbol or path conformance.',93+ source: 'https://www.iso.org/standard/11955.html',94+ },95+ {96+ id: 'rfc-2360',97+ name: 'RFC 2360 packet diagram conventions',98+ status: 'visual-conventions',99+ relatedSkills: ['protocol-layout-diagram'],100+ note: 'PacketDiag and Bytefield can express layouts that follow the conventions, but protocol-specific validation is not built in.',101+ source: 'https://www.rfc-editor.org/rfc/rfc2360.html#section-3.3',102+ },103+ {104+ id: 'dmn-1.5',105+ name: 'OMG DMN 1.5',106+ status: 'unsupported',107+ relatedSkills: ['decision-tree'],108+ note: 'Informal decision trees are supported. Decision requirements diagrams, DMN XML interchange, and FEEL evaluation are not.',109+ source: 'https://www.omg.org/spec/DMN/1.5/',110+ integration: { reward: 'high', effort: 'medium-to-large', scope: 'DMN XML parser, decision requirements rendering, validation, and optional FEEL evaluation' },111+ },112+ {113+ id: 'archimate-3.2',114+ name: 'The Open Group ArchiMate 3.2',115+ status: 'unsupported',116+ relatedSkills: ['choose-architecture-diagram', 'system-landscape-diagram', 'system-context-diagram', 'container-diagram'],117+ note: 'Generic architecture pictures are supported, but ArchiMate viewpoints, notation rules, and model exchange are not.',118+ source: 'https://www.opengroup.org/archimate-licensed-downloads',119+ integration: { reward: 'high', effort: 'large', scope: 'Licensed notation assets, ArchiMate 3.x model exchange, viewpoint rules, and conformance testing' },120+ },121+ {122+ id: 'sysml-2.0',123+ name: 'OMG SysML 2.0',124+ status: 'unsupported',125+ relatedSkills: ['choose-architecture-diagram', 'block-diagram', 'component-diagram', 'hierarchy-diagram'],126+ note: 'Generic blocks and relationships are supported, but SysML language semantics, textual notation, model interchange, and view validation are not.',127+ source: 'https://www.omg.org/spec/SysML/2.0/',128+ integration: { reward: 'high', effort: 'very-large', scope: 'SysML textual or JSON parsing, KerML/SysML semantics, libraries, view generation, and conformance' },129+ },130+ {131+ id: 'iec-60617-2026-db',132+ name: 'IEC 60617:2026 DB',133+ status: 'unsupported',134+ relatedSkills: ['circuit-diagram', 'wiring-harness-diagram'],135+ note: 'General renderers can draw circuits and harnesses, but diagram.zip has no licensed IEC symbol library or symbol validation.',136+ source: 'https://webstore.iec.ch/en/publication/2723',137+ integration: { reward: 'medium', effort: 'large', scope: 'Symbol licensing, searchable assets, semantic ports and nets, document rules, and conformance boundaries' },138+ },139+]@@ -0,0 +1,42 @@
1+---2+name: choose-architecture-diagram3+description: Choose the smallest architecture view that answers the stakeholder's question, then route it to a suitable diagram source.4+---5+6+# Choose an architecture diagram7+8+## What it tells9+10+This skill is a decision aid for selecting an architecture view before drawing. It distinguishes landscape, context, container, component, deployment, dynamic, and block views by audience, scope, and relationship semantics.11+12+## When to use13+14+Use it when a request says “architecture diagram” without naming a view, or when the requested picture risks mixing organizational scope, runtime behavior, and implementation structure. Ask who needs the decision, what boundary they need, and whether the question is static structure, runtime interaction, or physical placement.15+16+Avoid it when the user has already named a precise view and its scope. Use the corresponding architecture skill directly, preserving the user's choice.17+18+## Method19+20+1. Restate the question as a decision or explanation.21+2. Choose one primary view and make its system boundary explicit.22+3. Keep the abstraction level consistent; do not mix components with external organizations or deployment hosts without a deliberate second view.23+4. Name relationships with a verb and, where useful, a protocol or trust boundary.24+5. Offer a companion view only when it answers a separate question.25+26+Use the C4 model as a notation-independent framing aid: landscape for many systems, context for one system and its users/dependencies, container for deployable/runtime units, and component for internals of one container. Use deployment for nodes/environments and dynamic views for a scenario over time. A block diagram is appropriate when the domain is not software or when informal modular decomposition is enough.27+28+## Renderer routing29+30+Preserve an explicitly requested renderer. Otherwise prefer `structurizr` when one C4 model should produce several views, `c4plantuml` for a focused C4 view, `plantuml` for UML-flavoured architecture, `mermaid` or `d2` for lightweight sketches, `graphviz` for graph-heavy dependencies, and `blockdiag` for simple block structure. These are source choices, not diagram types; confirm the renderer can express the chosen semantics before generating.31+32+## Style and customization33+34+Use a restrained palette, a visible legend, directional flow, short labels, and a title stating scope and audience. Use consistent shapes for people, software systems, containers, components, and external dependencies. Prefer line styles or icons for trust, synchronous/asynchronous, and data-flow distinctions; never rely on color alone. Generate a second focused diagram when labels become paragraphs.35+36+## Review37+38+Check that every element is inside or outside the boundary intentionally, every arrow has a readable meaning, the audience can identify the level of abstraction, and no implementation detail is implied by an informal shape. Check that the diagram remains useful in grayscale and at its intended size. If the user needs formal conformance, call out that C4 itself is a model/framing convention rather than an ISO notation standard.39+40+## Prior art and limits41+42+The C4 model is explicitly notation-independent. C4 PlantUML is a practical renderer library, not a formal interchange standard. ArchiMate and SysML offer stronger formal viewpoints/modeling semantics but are not currently represented by a dedicated diagram.zip source skill; integration would require a compatible renderer/import path and a decision on conformance. See [C4 diagrams](https://c4model.com/diagrams), [C4 notation](https://c4model.com/diagrams/notation), [ArchiMate](https://www.opengroup.org/archimate-forum/archimate-overview), and [OMG SysML](https://www.omg.org/sysml/).@@ -0,0 +1,55 @@
1+---2+name: choose-data-visualization3+description: Choose and design a data visualization when the user has data, a comparison, trend, distribution, relationship, flow, or geographic question but has not yet chosen a chart form. Use the simplest honest encoding, explain the story, and route the result to Vega or Vega-Lite when appropriate.4+---5+6+# Choose a data visualization7+8+## What this skill is9+10+This is a semantic chart-selection skill. It decides what the data should say before deciding how the source is written. It covers bar, line and area, scatter and bubble, histogram, box/violin/density, pie/donut, heatmap, treemap, Sankey, geographic, network, beeswarm, and word-cloud forms.11+12+## Ask first13+14+Establish these facts before choosing a mark:15+16+- What decision or question should the reader answer?17+- What is one row: an observation, category, event, relationship, region, or aggregate?18+- Which fields are quantitative, temporal, ordinal, nominal, geographic, or identifiers?19+- Is the task comparison, ranking, change over time, distribution, correlation, part-to-whole, flow, location, hierarchy, or topology?20+- How many observations and categories are there, and will the chart be printed, embedded, or explored interactively?21+- Are zero, uncertainty, missing values, weights, denominators, and units meaningful?22+23+If the user already selected a chart form or renderer, preserve that choice and review it against the question. Do not silently substitute a chart.24+25+## Choose the story26+27+- **Bar**: compare discrete values or rank categories. Use a common zero baseline for magnitudes; sort deliberately. Horizontal bars suit long labels. Avoid bars for dense time series or many categories.28+- **Line / area**: show ordered time or another continuous sequence. Lines imply continuity; do not connect unrelated categories. Use area for cumulative volume or a small number of parts, not for precise comparison of many series.29+- **Scatter / bubble**: show association between two quantitative variables; use size for a third only when area can be read as approximate magnitude. Add trend or reference lines only when they have a stated meaning.30+- **Histogram**: show the distribution of one quantitative field. State bin width or method; compare groups with shared bins. It is not a bar chart of arbitrary categories.31+- **Box / violin / density**: compare distributions across groups. Box plots emphasize robust summaries and outliers; violins/densities show shape but can mislead with small samples or smoothing. Show sample size where it changes interpretation.32+- **Pie / donut**: show a small number of mutually exclusive parts of one whole when the total is meaningful. Prefer bars when exact comparison matters; never use a pie for unrelated values or a changing total.33+- **Heatmap**: show a quantitative value over two categorical/ordered dimensions, often a matrix or calendar. Use a perceptually ordered scale and label the legend; do not imply precision the color cannot carry.34+- **Treemap**: show nested part-to-whole with limited space. Use area for the primary magnitude and hierarchy for grouping; avoid it when adjacent length comparisons are required.35+- **Sankey / flow**: show quantities moving among stages or nodes. Preserve conservation or explain losses/gains, label units, and avoid excessive crossing. It is not a generic relationship graph.36+- **Geographic map**: show spatial distribution or routes only when location changes the decision. Choose a projection and geometry appropriate to the region; normalize rates by population/area where relevant. A map is not automatically more informative than a ranked bar chart.37+- **Network visualization**: show entities and relationships/topology. Define node and edge meaning, direction, and weight; do not use position as an unearned quantitative scale. For dense networks, filter, group, or provide a table/search alternative.38+- **Beeswarm**: show every observation across one or more groups while exposing distribution and sample size. It is useful when overplotting would hide points; preserve a quantitative axis and explain jitter packing.39+- **Word cloud**: show rough prominence of terms in a corpus, not exact ranking or meaning. Prefer a sorted bar chart for measured comparison; remove stopwords and disclose the weighting/tokenization.40+41+## Honest encodings and styling42+43+Use position and length for the most important quantitative comparison, then color, shape, and size. Treat color as a redundant cue, not the sole encoding. Use a zero baseline for bars and areas unless a clearly marked non-zero baseline is the point. Keep comparable panels on shared scales. Label units, denominators, aggregation, date range, missing data, and uncertainty.44+45+Prefer restrained, semantic styling: a neutral field, one accent for the focus, a colorblind-safe categorical palette, direct labels where they reduce lookup, and a legend only when it remains legible. Avoid 3-D effects, decorative gradients, rainbow scales for ordered values, misleading area/volume, excessive gridlines, and truncated axes that exaggerate differences. Provide text or tabular access to values and meaningful titles/annotations.46+47+For Vega-Lite, start with a mark and field encodings, then set explicit types, scales, axes, legends, and configuration. Use Vega when the chart needs custom marks, transforms, signals, projections, force layouts, or precise composition. Both are supported renderer IDs in diagram.zip: `vegalite` and `vega`. Keep data and images inline: diagram.zip does not provide URL-backed data or images for these renderers and returns SVG.48+49+Renderer choice remains the user’s choice. If another supported renderer is requested, route only if it can express the selected story faithfully; otherwise explain the gap and offer a Vega/Vega-Lite source as an option. The current catalog has no dedicated high-level renderer for Sankey, treemap, beeswarm, word cloud, or network charts. Vega can sometimes implement them with custom transforms/marks; Vega-Lite is not a turnkey solution for each. Geographic charts require inline geometry and a deliberate projection. Treat this as an integration opportunity, not permission to invent unsupported syntax.50+51+## Review before delivery52+53+Check that the title states the question, encodings match field types, aggregation and denominators are explicit, scales do not distort the comparison, categories are ordered intentionally, and annotations do not imply causation. Test long labels, missing values, small samples, extreme values, grayscale/low-vision viewing, keyboard or text alternatives, and export at the intended size. For maps check projection, boundary date, privacy, and rate normalization; for flows check conservation; for networks check edge ambiguity; for distributions check binning/smoothing and sample size.54+55+Read [Vega and Vega-Lite guidance](references/vega.md) for renderer-specific decisions and [accessibility guidance](references/accessibility.md) when the output will be published or used for a decision.@@ -0,0 +1,8 @@
1+# Accessible data visualization reference2+3+- [WCAG 2.2 Success Criterion 1.4.1](https://www.w3.org/TR/WCAG22/#use-of-color) requires that color not be the only means of conveying information. Add labels, patterns, shapes, line styles, or text alternatives.4+- [WCAG 2.2 Success Criterion 1.4.3](https://www.w3.org/TR/WCAG22/#contrast-minimum) covers text contrast. Small labels and legends need particular care.5+- [W3C SVG 2 accessibility guidance](https://www.w3.org/TR/SVG2/conform.html#accessibility) describes meaningful titles, descriptions, and accessible naming for SVG graphics.6+- [W3C WAI complex images tutorial](https://www.w3.org/WAI/tutorials/images/complex/) recommends a concise purpose statement plus a longer text alternative for charts and other complex graphics.7+8+For a diagram.zip SVG, provide a meaningful title and description when the chosen source format supports them, and pair the image with a nearby textual summary or data table. Do not rely on color, hover, animation, or spatial position alone. Preserve readable focus/order in interactive variants and state the data source, date, aggregation, and uncertainty in accompanying text.@@ -0,0 +1,17 @@
1+# Vega and Vega-Lite reference2+3+Use the renderer that matches the required control surface:4+5+- [Vega documentation](https://vega.github.io/vega/docs/) defines the lower-level grammar: data, transforms, scales, axes, legends, marks, signals, and projections. It is the supported diagram.zip renderer ID `vega`.6+- [Vega-Lite documentation](https://vega.github.io/vega-lite/docs/) defines concise marks, encodings, typed fields, layering, concatenation, faceting, and repeat views. It is the supported diagram.zip renderer ID `vegalite`.7+- The Vega-Lite paper, [A Grammar of Interactive Graphics](https://idl.uw.edu/papers/vega-lite/), explains why explicit data types and compositional encodings make common charts easier to specify and review.8+9+Practical routing:10+11+- Start with Vega-Lite for bars, lines, areas, scatterplots, histograms, box plots, heatmaps, faceting, and small multiples.12+- Use Vega when you need custom transforms, a geographic projection, a force layout, bespoke marks, signals, or exact layered composition.13+- Put records or geometry inline. External URLs are unavailable in diagram.zip’s Vega and Vega-Lite renderers.14+- Use explicit `type` (`quantitative`, `temporal`, `ordinal`, or `nominal`) and explicit scale domains when comparison across views matters.15+- Verify the actual output at the target size; a valid specification can still produce illegible labels or an ambiguous legend.16+17+The renderer catalog does not currently provide convenience renderers for Sankey, treemap, beeswarm, word cloud, or network diagrams. A future integration could add tested, accessible templates or dedicated renderers for these forms; until then, disclose custom Vega work and do not claim that a generic mark is a semantic implementation.@@ -0,0 +1,38 @@
1+---2+name: circuit-diagram3+description: Use when the user needs an electrical or electronic schematic showing components, nets, reference designators, power, signal flow, and test points.4+---5+6+# Circuit diagram7+8+## Select it when9+10+Choose this skill when the reader must understand or build an electrical circuit: signal paths, power rails, component relationships, or measurement points. Use it for conceptual schematics and documentation. Do not call a general block diagram a schematic, and do not imply PCB layout, simulation, safety approval, or manufacturing release without source data.11+12+## Story and modeling13+14+Choose the level first: functional block schematic, detailed circuit, or power/control subcircuit. Model standard symbols, reference designators, values/ratings, net names, pin numbers, polarity, power and ground, connectors, test points, and signal direction. Keep wires orthogonal where possible; show a junction only where a connection exists. Use net labels and hierarchical connectors to avoid unreadable wire crossings. Include units and a legend.15+16+A rendered image is not necessarily an authoritative electrical document. It does not establish ERC correctness, component availability, creepage/clearance, safe ratings, SPICE behavior, or PCB connectivity unless those are validated by an integrated EDA source.17+18+## Styling and customization19+20+Prefer conventional symbol geometry and a consistent left-to-right signal flow. Use line weight and labels before color; if color marks power domains or warnings, provide a monochrome legend. Keep reference designators visible and values secondary. Use sheet boundaries, title blocks, revision, and source links for engineering audiences. Do not invent a symbol when the standard symbol is unavailable—label the custom graphic and explain it.21+22+## Renderer routing23+24+Preserve a renderer explicitly requested by the user. Use `diagramsnet` for manually positioned schematic-like drawings, `svgbob` for text-native circuit sketches, or `tikz` and `pikchr` for controlled custom geometry. Use `plantuml`, `d2`, or `graphviz` only for functional connectivity abstractions. The catalog does not expose a native SPICE/EDA schematic renderer or IEC symbol-validation pipeline. General renderers cannot guarantee electrical semantics, pin correctness, or standards-compliant symbol libraries.25+26+## Review27+28+Check every net endpoint, junction, pin number, polarity mark, power/ground symbol, reference designator, value, unit, and cross-sheet link. Confirm that crossings are unambiguous and that no hidden net is silently assumed. Review ratings, safety boundaries, and revision/source provenance with an electrical engineer. State whether the output is conceptual, review-ready, or a standards-controlled artifact.29+30+## References31+32+- [IEC 60617:2026 DB](https://webstore.iec.ch/en/publication/2723) — authoritative symbol database; licensing and symbol-library integration may be required.33+- [IEC 61082-1](https://webstore.iec.ch/en/publication/265) — preparation of electrotechnical documents; the renderers do not enforce its conventions.34+- [IEEE Std 315](https://standards.ieee.org/standard/315-1975.html) — graphic symbols for electrical/electronics diagrams; verify applicability and current organizational practice.35+36+## Integration opportunities37+38+Native IEC/IEEE symbol libraries, ERC/netlist checks, SPICE import, EDA interchange, title-block control, and design-rule validation are unsupported integration opportunities. Do not describe a general-renderer output as IEC/IEEE-compliant authoring.@@ -0,0 +1,54 @@
1+---2+name: class-diagram3+description: Create or review class diagrams that explain types, responsibilities, contracts, and structural relationships in an object-oriented or domain model.4+---5+6+# Class diagram7+8+## Select this skill when9+10+Use this skill when the story is about named types and their structural relationships: attributes, operations, inheritance, interfaces, composition, aggregation, or dependencies. Use it for a design contract, domain model, API shape, or a focused explanation of one subsystem.11+12+Avoid it when the main story is runtime order (use a sequence or activity diagram), deployment topology (use deployment or network-topology), relational tables (use entity-relationship-diagram), or a graph whose nodes are not types (use dependency-graph).13+14+## Story and semantic model15+16+Start with the question the reader must answer: “What are the important types, what do they own, and how may they collaborate?” Name the abstraction level in the title. Keep the diagram to one coherent boundary and show only members that support the story.17+18+Use UML semantics deliberately:19+20+- A class has identity and may show attributes and operations; an interface describes a contract.21+- Generalization means “is a”; realization means “implements the contract”; dependency means “uses”.22+- Composition means the part’s lifecycle is owned by the whole; aggregation is weaker and should be used sparingly.23+- Label associations with role names, navigability, and multiplicities when they matter. Do not imply lifecycle or cardinality merely with a line.24+- Prefer explicit relationship labels over relying on arrow glyphs that vary by renderer.25+26+Object diagrams are a useful companion when the reader needs one concrete runtime snapshot. Keep that as a reference view rather than mixing instances and classifiers in the same primary diagram.27+28+## Layout and styling29+30+Use a consistent reading direction, group types by bounded context or package, and place the most important contract near the center. Keep inheritance vertical where possible and route cross-group dependencies around the outside. Show public API members first; omit private implementation details unless they explain a constraint.31+32+Use restrained color for roles or packages, not for every class. Make interface, abstract, external, and deprecated status available through shape, stereotype, or text as well as color. Use high-contrast text and never make a dashed/solid distinction the only encoding.33+34+## Renderer routing35+36+Preserve an explicit renderer choice from the user. Otherwise prefer:37+38+- `plantuml` for expressive UML, relationships, members, and mature styling.39+- `mermaid` for a lightweight Markdown-friendly class view.40+- `c4plantuml` only when the class view is actually a component-level C4 view; it is not a general UML class renderer.41+- `graphviz` or `d2` for a dependency-shaped type graph when UML notation is unnecessary.42+- `diagramsnet` when the user needs hand-positioned, editable shapes.43+44+Check the local renderer catalog before promising syntax or export behavior. Renderer support is not semantic validation: diagram.zip cannot guarantee that a source expresses valid UML merely because it renders.45+46+## Review checklist47+48+Check that every arrow has a sentence meaning, multiplicities are intentional, ownership is not overstated, and the abstraction level is consistent. Remove orphan types, duplicate concepts, and members that do not support the stated question. Test the diagram at its final reading size and verify that a grayscale or non-color reading still works.49+50+## Standards and prior art51+52+The baseline is OMG UML 2.5.1, especially Class, Interface, Generalization, Realization, Dependency, and Association semantics: <https://www.omg.org/spec/UML/2.5.1/>. UML is a vocabulary, not a mandate to show every member or relationship.53+54+The object-diagram companion is also defined by UML, but diagram.zip currently has no dedicated object-diagram skill. A future skill could add instance identity, slots, links, and snapshot review rules. If a user requires machine-valid UML interchange or complete XMI round-tripping, that is an unsupported integration opportunity rather than a promise of this skill.@@ -0,0 +1,40 @@
1+---2+name: component-diagram3+description: Create a component-level view of software structure, interfaces, and dependencies when the audience needs implementation boundaries rather than deployment topology.4+---5+6+# Component diagram7+8+## What and why9+10+Use this skill to tell the story of how a software system is partitioned into replaceable or independently owned components, and how those components collaborate through explicit interfaces. It is a good fit for design reviews, ownership boundaries, integration planning, and explaining an existing codebase. It is not a class diagram, deployment map, or a full system landscape.11+12+## Select or avoid13+14+Select it when the question is “which implementation parts depend on which contracts?” Avoid it when the question is about people and systems (system context), runtime nodes (deployment), message order (sequence), or data ownership (ERD). Ask whether the component means a code/module boundary, a service boundary, or a logical subsystem; do not mix those levels without a boundary legend.15+16+## Modeling method17+18+1. Name the system boundary and audience.19+2. Identify components at one consistent level. Give each a responsibility and owner.20+3. Draw only meaningful dependencies; label each edge with the interface, protocol, or purpose.21+4. Show provided/required interfaces when interface compatibility matters.22+5. Add external dependencies only when they explain a decision. Mark inferred or undocumented relationships.23+24+The primary story should be readable from components and labeled relationships alone. Use notes for risks, technology, or migration state—not as a substitute for missing structure.25+26+## Styling and customization27+28+Use containment to show system/subsystem boundaries, not decorative nesting. Keep component shapes consistent, use a restrained color for ownership or lifecycle, and reserve a second accent for external dependencies. Prefer orthogonal or gently routed connectors, short labels, and a left-to-right direction for dependency flow. Add a legend for every non-obvious color, stereotype, or line style. Preserve a user-selected renderer; otherwise prefer `structurizr` for a reusable C4 workspace, `c4plantuml` for a focused C4 component view, `plantuml` for UML component notation, `mermaid` for quick documentation, or `d2` for a polished sketch.29+30+## Review checklist31+32+- Is the abstraction level explicit and consistent?33+- Does every important edge name a contract or purpose?34+- Can ownership, externality, and lifecycle status be distinguished without guessing?35+- Are cycles, high fan-in, and unstable boundaries visible?36+- Is the diagram still legible when rendered in the requested format?37+38+## Standards and prior art39+40+See [C4 and UML profiles](references/c4-uml.md). C4 component diagrams and UML component diagrams overlap in intent but are not interchangeable notations. UML 2.5.1 is the formal standard; diagram.zip supports text renderers and C4 PlantUML, not a general UML model interchange pipeline. Full UML conformance, executable interface contracts, and SysML component semantics are integration opportunities rather than promises of this skill.@@ -0,0 +1,6 @@
1+# C4 and UML profiles2+3+- [C4 diagrams](https://c4model.com/diagrams) and [C4 notation](https://c4model.com/diagrams/notation): C4 uses context, container, component, and code views to progressively explain software architecture. Treat “component” as a zoom level and state the boundary.4+- [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1/): the UML Component and Composite Structures chapters define components, provided/required interfaces, ports, connectors, and collaborations. Use those concepts when interface semantics matter; do not imply formal UML conformance from a rendered sketch.5+6+The supported renderer choices are syntax-level choices: PlantUML, Mermaid, D2, Graphviz, BlockDiag, and C4 PlantUML are available in diagram.zip. They differ in layout and notation fidelity; preserve the user’s choice and explain any loss of interface/port semantics.@@ -0,0 +1,34 @@
1+---2+name: concept-map3+description: Use when the user needs to explain concepts and the labeled relationships between them, especially definitions, dependencies, evidence, or cross-domain connections.4+---5+6+# Concept map7+8+## What / why9+10+A concept map is a semantic network: concepts are nodes and labeled propositions connect them. It tells the story “how are these ideas related, and what kind of relationship is it?” Choose it over a mind map when cross-links and relationship meaning matter.11+12+## How to model13+14+- State the focus question before modeling.15+- Use noun or noun-phrase concepts; connect them with explicit verbs or relation labels.16+- Make each path read as a proposition: `concept — relation — concept`.17+- Use hierarchy only for real general-to-specific relationships; allow cross-links.18+- Distinguish evidence, examples, and claims from concepts themselves.19+20+## Styling and customization21+22+Use directional links, high-contrast labels, and enough space for relation text. Use color for concept categories, not relationship meaning alone. Add a legend for arrowheads, line styles, and confidence/status. For a dense map, provide a focused subgraph as well as the overview.23+24+## Renderer choices25+26+Preserve the user’s renderer choice. Mermaid, Graphviz, D2, PlantUML, and diagrams.net can represent labeled graphs; Graphviz is useful for automatic layout, while D2 or diagrams.net suit deliberate composition. No diagram.zip renderer enforces concept-map propositions or validates relationship labels; the skill supplies that semantic discipline.27+28+## Review29+30+Read every edge as a sentence. Check labels are specific, arrow direction is meaningful, cycles are intentional, and the focus question is answered. Remove unlabeled edges unless adjacency itself is the claim.31+32+## Prior art and gaps33+34+See [references/prior-art.md](references/prior-art.md). The [ISO 704 terminology principles](https://www.iso.org/standard/59176.html) are useful prior art for clear concepts and relations, but diagram.zip does not implement a terminology interchange format.@@ -0,0 +1,7 @@
1+# Concept-map references2+3+- [IHMC CmapTools concept-map overview](https://cmap.ihmc.us/docs/concept-maps.php) — prior art for concepts, linking phrases, propositions, hierarchy, and cross-links.4+- [ISO 704:2022](https://www.iso.org/standard/59176.html) — terminology principles relevant to concept clarity and definitions.5+- [Graphviz DOT language](https://graphviz.org/documentation/) — supported graph renderer and layout reference.6+7+There is no universally adopted concept-map interchange standard in diagram.zip. A dedicated concept-map data model and validator would be an integration opportunity.@@ -0,0 +1,34 @@
1+---2+name: container-diagram3+description: Show the major deployable or runtime containers inside one software system and how they collaborate.4+---5+6+# Container diagram7+8+## What it tells9+10+A container diagram opens one system boundary by one level. It explains the major applications, services, data stores, and other runtime units, their responsibilities, and their important collaborations.11+12+## Use and boundaries13+14+Use it for solution design, team ownership, technology decisions, integration review, and explaining where data or requests flow. Define “container” as a separately runnable or deployable unit in the chosen context; do not confuse it with an operating-system container. Avoid classes, functions, cloud-product inventories, or host topology unless they are the explicit story; use component or deployment views for those.15+16+## Method17+18+Begin with a system context and retain only its boundary-relevant actors/dependencies. For each container state its responsibility and, when useful, technology. Draw the smallest set of collaborations needed to answer the question, label edges with action/data/protocol, and distinguish synchronous from asynchronous paths. Include data stores as containers when persistence matters. If a service is actually a team boundary or a deployment unit, say which interpretation is being used.19+20+## Renderer routing21+22+Keep the user's renderer choice. Prefer `structurizr` when containers share a reusable C4 workspace model or `c4plantuml` for a focused view. Use `plantuml` for UML component/deployment hybrids, `mermaid` or `d2` for approachable sketches, and `graphviz` when automatic layout is the main need. Renderer syntax can draw the shapes but cannot guarantee that a box is a C4 container—encode that meaning in labels, legend, and review.23+24+## Style and customization25+26+Use nested system boundaries, consistent container shapes, short responsibility labels, and a small technology annotation. Separate data stores visually without implying a technology that was not chosen. Use line patterns for sync/async or trust, and keep color accessible and nonessential. Provide a focused companion deployment view when physical placement matters.27+28+## Review29+30+Check that every container has a responsibility, the system boundary is visible, collaborations are directional and labeled, technology details are not mistaken for responsibilities, and the level does not mix classes or infrastructure resources. Test readability at the delivery size and in grayscale. Confirm that the diagram answers one question rather than becoming an inventory.31+32+## Prior art and limits33+34+This uses the C4 container concept, which is notation-independent. C4 PlantUML provides macros, not a formal model interchange format. UML component/deployment views, ArchiMate, and SysML can provide formal semantics, but diagram.zip currently lacks dedicated profile-enforced ArchiMate/SysML sources; integration would be needed for those standards. See [C4 diagrams](https://c4model.com/diagrams), [C4 notation](https://c4model.com/diagrams/notation), [OMG UML](https://www.omg.org/spec/UML/2.5.1/), [ArchiMate overview](https://www.opengroup.org/archimate-forum/archimate-overview), and [OMG SysML](https://www.omg.org/sysml/).@@ -0,0 +1,40 @@
1+---2+name: data-flow-diagram3+description: Use when the user needs to show where information originates, how processes transform it, where stores retain it, and which external entities exchange it.4+---5+6+# Data-flow diagram7+8+## What and why9+10+A data-flow diagram (DFD) explains movement and transformation of information. Its story is source → process → store/sink, with the data named on each flow. It is useful for system scope, privacy reviews, integration discovery, and requirements conversations.11+12+Choose it for information movement. Avoid it for temporal call order (sequence diagram), network topology (network-topology), business control flow (flowchart/BPMN), or deployment placement.13+14+## How15+16+1. Declare the level: context/level 0 for one process and external entities, or a decomposed level for internal processes.17+2. Use four concepts: external entity, process, data store, and data flow. Give each a stable ID and a meaningful noun/verb label.18+3. Label every arrow with the data being exchanged; distinguish request, response, event, and batch where it matters.19+4. Balance decomposition: flows crossing a parent boundary must remain represented in its child diagram.20+5. Mark trust boundaries, retention, sensitive fields, and ownership as annotations rather than inventing new flow semantics.21+22+## Story and styling23+24+Put external entities at the perimeter, processes in the reading direction, and stores near the processes that use them. Use restrained colors for entity/process/store roles and a single accent for sensitive or cross-boundary flows. Arrow direction and labels must remain legible in monochrome.25+26+If no renderer is specified, `graphviz` is a strong default for explicit nodes and directed edges; `mermaid` or `d2` is convenient for source-controlled sketches. These renderers do not enforce Yourdon/DeMarco or Gane–Sarson symbol semantics, so state the chosen profile in a legend or title. Preserve the user’s renderer choice.27+28+## Review29+30+- Is the diagram level and system boundary explicit?31+- Does every process have at least one input and output, unless it is an intentional source/sink?32+- Are all flows named with data, not vague verbs such as “handles”?33+- Are stores and external entities distinct from processes?34+- Are decomposed diagrams balanced and are sensitive/trust-crossing flows visible?35+36+## Prior art and limitations37+38+Use the [NIST glossary definition of a data-flow diagram](https://csrc.nist.gov/glossary/term/data_flow_diagram) as a government-domain anchor, and document the selected notation profile. DFD notation has multiple historical conventions; there is no single current ISO visual interchange standard implemented by the available renderers.39+40+SVG output should meet [WCAG 2.2](https://www.w3.org/TR/WCAG22/) non-text contrast and text alternatives. A future integration could add a profile-aware DFD renderer or interchange validator for Yourdon–DeMarco and Gane–Sarson symbols.@@ -0,0 +1,34 @@
1+---2+name: decision-tree3+description: Use when the user needs to show a sequence of choices, branching rules, outcomes, or diagnostic paths.4+---5+6+# Decision tree7+8+## What / why9+10+A decision tree tells the story “which question or rule leads to which next branch and outcome?” It is for explicit branching logic, not a general process or arbitrary hierarchy.11+12+## How to model13+14+- Start with one entry condition and make each decision node a question or predicate.15+- Label every outgoing edge with understandable, mutually exclusive conditions; include the default/else branch.16+- Keep outcomes distinct from subsequent decisions and identify terminal nodes.17+- State precedence, probability, owner, or evidence when decisions depend on them.18+- If rules are complex, separate the readable tree from the authoritative decision table.19+20+## Styling and customization21+22+Use diamonds or clearly differentiated decision nodes, rounded/colored terminal outcomes, and directional flow. Keep branch labels near edges and avoid color-only meaning. Use line styles for confidence or exception paths only with a legend.23+24+## Renderer choices25+26+Preserve the user’s renderer. Mermaid flowcharts, Graphviz, D2, PlantUML activity diagrams, and diagrams.net can render decision trees. diagram.zip does not implement DMN decision requirements diagrams or FEEL evaluation; that is an unsupported integration opportunity. Use BPMN when the user needs formal process events/tasks, not merely branching.27+28+## Review29+30+Trace every path from entry to outcome. Check branch completeness, overlap, unreachable nodes, contradictory predicates, and whether visual order matches evaluation order. Call out any informal rule that needs DMN or a decision table.31+32+## Prior art and gaps33+34+See [references/prior-art.md](references/prior-art.md).@@ -0,0 +1,7 @@
1+# Decision-tree references2+3+- [OMG DMN 1.5](https://www.omg.org/spec/DMN/1.5/) — latest formal prior art for decision requirements, decision logic, and FEEL; not a native diagram.zip renderer.4+- [Mermaid flowchart syntax](https://mermaid.js.org/syntax/flowchart.html) — supported renderer for readable informal decision trees.5+- [ISO 5807:1985](https://www.iso.org/standard/11955.html) — flowchart symbol convention relevant to decision/process notation.6+7+DMN support would require XML parsing, decision requirements notation, and likely FEEL-aware validation. Do not imply that a Mermaid diamond is DMN-conformant.@@ -0,0 +1,52 @@
1+---2+name: dependency-graph3+description: Show dependencies between packages, modules, services, artifacts, or concepts when the important story is coupling, direction, reachability, or change impact.4+---5+6+# Dependency graph7+8+## Select this skill when9+10+Use this skill when a reader needs to see “what depends on what,” identify coupling, trace impact, find cycles, or understand a dependency boundary. Nodes may be software packages, services, libraries, documents, datasets, or other artifacts, but declare the node type and edge meaning.11+12+Avoid it for ordered interactions (use sequence-diagram), ownership hierarchies (use hierarchy-diagram), network reachability (use network-topology), or a business process. If edges mean several different things, split the views or use an explicit legend.13+14+## Story and semantic model15+16+Define the direction in a sentence, such as “A imports B” or “Service A calls Service B.” Name the evidence and time scope: declared dependencies, runtime calls, build dependencies, or inferred references. Keep the graph at one level of abstraction.17+18+- Use directed edges by default and label exceptional edge kinds.19+- Distinguish direct from transitive dependencies; do not draw transitive edges unless they are the story.20+- Use clusters for ownership or package boundaries, not as a substitute for missing nodes.21+- Mark external, optional, deprecated, generated, and cyclic dependencies explicitly.22+- For impact analysis, identify the root artifact and highlight reachable downstream nodes without hiding the rest of the graph.23+24+Large graphs should be filtered by boundary, depth, or centrality. A graph that contains every dependency is often a dataset, not a useful diagram.25+26+## Layout and styling27+28+Choose left-to-right for dependency flow and top-to-bottom for layered architecture. Use stable node IDs and short labels; put versions or details in a legend or annotation. Use color for status or ownership, and use line style, labels, or shape for edge semantics so the reading survives grayscale.29+30+Prefer one strong emphasis (for example, a selected package and its callers). Avoid rainbow coloring by node. If the graph has cycles, make them visible and annotate whether the cycle is intentional.31+32+## Renderer routing33+34+Preserve an explicit renderer choice. Otherwise prefer:35+36+- `graphviz` for larger directed/undirected graphs, clusters, rank direction, and automatic layout.37+- `d2` for readable architecture/dependency graphs with containers and local styling.38+- `mermaid` for compact Markdown documentation and moderate-size graphs.39+- `plantuml` when dependency edges are part of a broader UML component or package view.40+- `diagramsnet` when a small dependency map must remain manually editable.41+42+Renderer layout is not graph analysis. diagram.zip does not infer dependencies, calculate reachability, detect cycles, or verify versions unless the input itself supplies those facts. Generate or validate the dependency data upstream, then use this skill to present it.43+44+## Review checklist45+46+Read the edge direction aloud and verify it is consistent. Check that every edge has a defined meaning, direct/transitive scope is clear, external boundaries are visible, and the selected graph is small enough to scan. Verify emphasized paths against source evidence. Remove duplicate nodes and edges, and explain cycles instead of routing them out of view.47+48+## Standards and prior art49+50+Graphviz DOT is the most portable source prior art for directed and undirected graph structure and attributes: <https://graphviz.org/documentation/>. The W3C Web of Things Architecture is useful prior art for describing software/system dependencies alongside boundaries and interactions: <https://www.w3.org/TR/wot-architecture/>.51+52+There is no universal standard that makes a generic dependency graph semantically interchangeable across package managers and runtime systems. If the project needs dependency extraction, provenance, graph queries, or a machine-readable graph interchange profile, that requires integration beyond diagram.zip rendering.@@ -0,0 +1,38 @@
1+---2+name: deployment-diagram3+description: Show where software artifacts run, which infrastructure nodes host them, and how runtime communication crosses environments or trust boundaries.4+---5+6+# Deployment diagram7+8+## What and why9+10+Use this skill to tell the operational placement story: artifacts or services, execution nodes, environments, networks, and the paths between them. It supports capacity, security, release, and incident discussions. It is not a component dependency map or a rack inventory unless that physical detail is the subject.11+12+## Select or avoid13+14+Select it when location, hosting, environment, connectivity, or redundancy matters. Avoid it when only logical ownership matters (component), when the audience needs business systems (landscape/context), or when exact hardware rack units are the question (rack diagram). Clarify whether “node” means cloud service, VM/container, device, or physical host.15+16+## Modeling method17+18+1. Name the deployment environment and observation time.19+2. Define nodes and nested execution environments at a consistent granularity.20+3. Place deployable artifacts or services on their host; distinguish replicated, standby, and ephemeral instances.21+4. Label connections with protocol, port, direction, trust boundary, and important controls.22+5. Show only topology relevant to the decision; add a legend for availability, environment, and security notation.23+24+## Styling and customization25+26+Use nested containers for environments and hosts, and a calm color scheme for production/staging/development. Keep network or trust boundaries visually stronger than ordinary grouping. Use badges for replicas, zones, and managed services; never rely on color alone. Preserve a user-selected renderer; otherwise prefer `structurizr` or `c4plantuml` for C4 deployment views, `plantuml` for UML deployment notation, `mermaid` or `d2` for documentation, and `nwdiag` for network-centric topology.27+28+## Review checklist29+30+- Is the environment/time snapshot explicit?31+- Can a reader identify what runs where and what crosses each boundary?32+- Are replicas, zones, failure domains, and dependencies represented accurately?33+- Are protocols, ports, and trust assumptions labeled when operationally important?34+- Does the diagram avoid implying a physical guarantee from a logical cloud abstraction?35+36+## Standards and prior art37+38+See [deployment profiles](references/deployment-profiles.md). UML 2.5.1 defines deployment nodes, artifacts, communication paths, and deployment relationships; C4’s deployment diagrams provide a pragmatic architecture view. diagram.zip renders PlantUML, C4 PlantUML, Mermaid, D2, Graphviz, BlockDiag, and NwDiag, but does not validate a UML model, cloud-provider topology, or security policy. Cloud-provider-native architecture export and formal deployment-model interchange are integration opportunities.@@ -0,0 +1,7 @@
1+# Deployment profiles2+3+- [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1/): deployment diagrams model nodes, artifacts, deployment specifications, and communication paths. Use those terms when the audience expects UML semantics.4+- [C4 deployment diagrams](https://c4model.com/diagrams/deployment): C4 uses deployment views to show how software is deployed to infrastructure in a particular environment, often with instances and technology details.5+- [NwDiag](http://blockdiag.com/en/nwdiag/): network-focused diagrams can show network segments and hosts, but are not a substitute for application artifact placement.6+7+Choose the least expressive renderer that preserves the story. A renderer’s visual similarity to UML or C4 does not establish standards conformance.@@ -0,0 +1,28 @@
1+---2+name: diagram-review3+description: Review a proposed diagram for semantic fit, evidence, readability, accessibility, and renderer or standards limitations; recommend precise revisions.4+---5+6+# Diagram review7+8+## What this is9+10+Use this model-invokable skill after a diagram is drafted, when a user asks whether it is correct, or when requirements are ambiguous enough that errors would be costly. Review the semantic story separately from the renderer syntax.11+12+## Review sequence13+14+1. State the diagram's apparent question, audience, scope, and main claim.15+2. Check that the selected diagram family makes that claim easy to read. Identify category errors, overloaded symbols, missing actors, hidden assumptions, and relationships that lack direction or labels.16+3. Check evidence: distinguish facts, inferred relationships, proposed architecture, and illustrative examples. Flag claims that need a source or domain-owner confirmation.17+4. Check layout: reading direction, grouping, crossings, hierarchy, density, legend, labels, and print or small-screen behavior.18+5. Check accessibility: meaningful text alternatives, document language and title/description where supported, contrast, non-color encoding, text size, and a linear reading explanation. Use [WCAG 2.2](https://www.w3.org/TR/WCAG22/) and [SVG accessibility guidance](https://www.w3.org/TR/SVG-access/) for delivery decisions.19+6. Check renderer fidelity and export. Name unsupported standard constructs, layout controls, or interchange data rather than silently approximating them.20+7. Return prioritized fixes: blocking semantic errors, reader-confusing issues, then polish. Include a concise corrected story or source fragment when useful.21+22+## Styling and customization23+24+Prefer styles that reinforce meaning: consistent shape roles, restrained color, explicit boundaries, and labels that survive grayscale or color-vision differences. Keep bespoke styling local and documented. Do not let a theme override a formal symbol's meaning or make decorative elements look like data.25+26+## Prior art27+28+For formal diagrams, compare against the relevant [OMG UML](https://www.omg.org/spec/UML), [OMG BPMN](https://www.omg.org/spec/BPMN/2.0.2/), or [C4 notation](https://c4model.com/diagrams/notation) guidance. For flowcharts, consult [ISO 5807](https://www.iso.org/standard/11955.html) where exact symbol conventions matter. Standards are review references; the local renderer catalog determines what diagram.zip can execute.@@ -0,0 +1,34 @@
1+---2+name: diagram-workshop3+description: Work with me to discover the right diagram question, audience, scope, and level of detail before making a diagram.4+disable-model-invocation: true5+---6+7+# Diagram workshop8+9+Use this skill when the user explicitly asks to workshop, explore, compare, or decide what diagram to make. It is intentionally user-invokable only: a router may recommend it, but must not invoke it without the user's direction.10+11+## What to discover12+13+Establish:14+15+- who will read the diagram and what decision or explanation it must support;16+- the subject, boundaries, time direction, and stable versus changing facts;17+- whether the story is flow, interaction, state, structure, data, hierarchy, comparison, physical placement, or a formal process;18+- the required fidelity, output format, renderer preference, and accessibility constraints.19+20+## How to facilitate21+22+Ask only the smallest set of questions that changes the diagram choice. Offer two or three candidate stories, state what each makes easy or hides, and recommend one. Sketch the entities and relationships in plain language before writing renderer syntax. Then hand off to the selected semantic skill and renderer while preserving the user's choices.23+24+## Useful prompts25+26+“What should a reader be able to decide after looking at this?” “Is order or structure more important?” “What is inside the boundary?” “Which facts must be exact?” “Who owns each step or component?” “Will this be read on a slide, in a document, or by assistive technology?”27+28+## Guardrails29+30+Do not manufacture missing facts. Mark assumptions and ask for confirmation when they affect meaning. A single diagram should not silently combine incompatible stories; propose separate views or a deliberate hybrid. If the requested formal notation is not available in diagram.zip, explain the gap and suggest the closest semantic view plus an integration opportunity.31+32+## Prior art33+34+Use the [C4 diagram question framing](https://c4model.com/diagrams), [OMG UML](https://www.omg.org/spec/UML), and [OMG BPMN](https://www.omg.org/spec/BPMN/2.0.2/) as appropriate. These references inform the conversation; they do not replace the selected skill's renderer support check.@@ -0,0 +1,40 @@
1+---2+name: diagramming3+description: Choose the semantic diagram story first, then select a diagram.zip renderer and produce a clear, reviewable diagram.4+---5+6+# Diagramming7+8+## What this is9+10+Use this as the model-invokable router for diagram requests. A renderer is a notation and execution choice; a diagram type is the story the reader needs. Select the story before selecting syntax.11+12+## Why13+14+The same system can be shown as a flow, interaction, boundary, dependency, data model, or physical layout. Choosing by renderer first commonly produces a technically valid diagram that answers the wrong question.15+16+## How to route17+18+1. Ask or infer the audience, decision, scope, time direction, and required level of detail.19+2. Choose the smallest semantic skill that matches the question. Prefer `diagram-workshop` when the user needs help discovering the question; it is user-invokable only and must not be invoked implicitly.20+3. Read that skill, including its references when the subject is formal or safety-sensitive.21+4. Choose a supported renderer from the local renderer catalog. Preserve an explicit renderer request even if another renderer is a better fit; explain any limitation and adapt the source.22+5. Make one main claim visually dominant. Label relationships with verbs, keep a consistent direction, and remove details that do not support the claim.23+6. Review the result for semantic correctness, layout, accessibility, and renderer limitations. Offer a second view when one diagram cannot answer two different questions.24+25+## Renderer routing26+27+Common choices include Mermaid for compact general diagrams, PlantUML for UML-oriented notation, C4 PlantUML for C4 views, Graphviz or D2 for graph structure, BPMN for formal process exchange, DBML for relational schemas, and PacketDiag/Bytefield for protocol fields. The complete supported set and syntax links are in the generated `llms.txt` and `diagramzip-docs/data/diagram-types.mjs`. Do not claim a standard is supported merely because a renderer has a similarly named mode: confirm the renderer's actual output and interchange fidelity.28+29+## Prior art and standards30+31+Use the [OMG UML specification](https://www.omg.org/spec/UML), [OMG BPMN specification](https://www.omg.org/spec/BPMN/2.0.2/), [C4 notation](https://c4model.com/diagrams/notation), and other authoritative references linked by the selected semantic skill when formal conformance matters. Treat these as guidance for meaning and notation, not as permission to invent unsupported renderer features.32+33+## Review checklist34+35+- Can the intended reader state the diagram's question in one sentence?36+- Are nodes, relationships, boundaries, and direction consistent with the selected story?37+- Is every label necessary and unambiguous?38+- Does the chosen renderer actually support the required semantics, layout, and export?39+- Are text, contrast, alternative descriptions, and SVG metadata adequate for the delivery context?40+- Have unsupported standards or fidelity gaps been named as integration opportunities?@@ -0,0 +1,54 @@
1+---2+name: digital-timing-diagram3+description: Use when a diagram must show digital signals changing over time, including clocked interfaces, bus transactions, handshakes, setup/hold relationships, or waveform protocols.4+---5+6+# Digital timing diagram7+8+## What it is9+10+A digital timing diagram is a time-aligned view of signals and events. It tells the reader which edges, levels, delays, and sampling relationships are required—not merely which components are connected.11+12+## Choose it when13+14+- correctness depends on clock edges, signal levels, latency, pulse width, or ordering in time;15+- the reader needs to compare a producer, consumer, clock, enable, reset, or bus on a shared time axis;16+- a protocol's “what happens when” is about electrical/logical timing rather than software call order.17+18+Use a sequence diagram for causal messages between participants. Use a protocol-layout diagram for field positions in a packet. Use an electrical schematic for connectivity and symbols.19+20+## Story and modeling21+22+1. Define the time direction, scale or “not to scale” status, voltage/logic convention, and active edge.23+2. Put the reference clock and reset first. Align every signal to explicit edges or intervals.24+3. Label meaningful transitions: setup window, hold window, valid/ready, request/acknowledge, turnaround, wait state, and sampled value.25+4. Show unknown, high-impedance, don't-care, and invalid states distinctly; never silently draw them as stable 0 or 1.26+5. State assumptions such as synchronous domain, propagation delay, bus ownership, and whether the waveform is normative or an example trace.27+28+## Styling and customization29+30+Use a consistent signal baseline and equal vertical spacing. Use a single accent for the active transaction, neutral clock/grid lines, and explicit hatch or text for unknown/high-impedance states. Annotate intervals with brackets and values, not only color. Keep the time axis readable at the intended output size and split long traces into named phases rather than shrinking everything.31+32+## Renderer routing33+34+- `wavedrom` is the direct diagram.zip fit for clocked waveforms, signal lanes, phase labels, and bus values.35+- `vega` can produce bespoke plotted traces when quantitative time data or custom scales matter, but it needs more explicit grammar and does not itself confer electrical meaning.36+- `tikz` or `pikchr` can handle a custom timing notation when WaveDrom's primitives are insufficient.37+- `plantuml`, `mermaid`, and `seqdiag` show ordered interactions but do not encode waveform-level setup/hold semantics; use them only if that abstraction is intentional.38+39+Preserve the user's renderer choice. If no renderer is requested, prefer `wavedrom` and state any assumptions. diagram.zip does not currently validate timing constraints against an HDL interface standard or simulate a waveform; an integration that imports interface timing tables or checks setup/hold annotations would be valuable. IEEE 1800/SystemVerilog assertions and vendor timing formats remain unsupported as normative inputs unless separately integrated.40+41+## Review checklist42+43+- Is the time axis and scale status clear?44+- Are clock edge, polarity, reset, and sampling point explicit?45+- Are setup/hold, latency, pulse width, and turnaround intervals labeled where relevant?46+- Are X/Z/don't-care states distinguishable from 0/1?47+- Does every transition support the stated protocol story?48+- Is this a normative timing requirement or one illustrative trace?49+50+## References51+52+- [WaveDrom documentation](https://wavedrom.com/) describes the waveform source model supported by diagram.zip.53+- [IEEE 1800-2023](https://standards.ieee.org/ieee/1800/10458/) is the SystemVerilog language standard, including assertions and timing-oriented design constructs; diagram.zip does not parse it as a timing-diagram source.54+- [JEDEC JESD79-5C](https://www.jedec.org/standards-documents/docs/jesd79-5c) is an example of a memory-interface specification where timing diagrams accompany normative setup/hold requirements.@@ -0,0 +1,52 @@
1+---2+name: entity-relationship-diagram3+description: Model persistent data with entities, attributes, keys, relationships, cardinality, optionality, and integrity boundaries using an entity-relationship diagram.4+---5+6+# Entity-relationship diagram7+8+## Select this skill when9+10+Use this skill when the story is how data is stored and related: entities, identifying keys, foreign keys, cardinality, optionality, normalization, or schema ownership. Use it before writing SQL when a team needs to agree on the data model.11+12+Avoid it for service calls and runtime behavior (use data-flow or sequence), software types (use class-diagram), or a generic dependency graph. A physical schema diagram may include indexes and column types, but do not let implementation detail obscure the conceptual model.13+14+## Story and semantic model15+16+State whether the view is conceptual, logical, or physical. Name entities with stable singular nouns, attributes with domain terms, and identifiers explicitly. For each relationship, answer: can each side exist without the other, how many are allowed, and what identifies the relationship?17+18+- Mark primary keys and candidate keys; distinguish a surrogate identifier from a meaningful natural key.19+- Show foreign-key mappings in a logical or physical view, but do not infer them from similarly named columns.20+- Use associative entities for many-to-many relationships when the relationship has attributes or needs independent lifecycle.21+- Represent optionality and cardinality explicitly. “One or more” and “zero or one” are different constraints.22+- Note temporal, tenant, uniqueness, and deletion rules when they change the interpretation of the model.23+24+Keep a conceptual ERD free of storage-engine choices. In a physical view, include types, indexes, and constraints only when they answer the audience’s question.25+26+## Layout and styling27+28+Place the central business entities in the middle, group entities by bounded context or ownership, and route relationship lines to minimize crossings. Use a stable key/attribute order and consistent notation (crow’s foot, Chen, or another declared profile).29+30+Use color to distinguish ownership or lifecycle, never to encode cardinality alone. Show key and constraint symbols in text or shape as well. If the renderer cannot express the chosen notation, add a legend and use labels rather than silently changing semantics.31+32+## Renderer routing33+34+Preserve an explicit renderer choice. Otherwise prefer:35+36+- `dbml` for a compact physical/logical relational schema with tables, fields, indexes, and references.37+- `mermaid` for a shareable ER view in Markdown-oriented workflows.38+- `plantuml` for richer entity notation and explanatory annotations.39+- `graphviz` or `d2` for a custom data relationship graph when strict ER notation is not required.40+- `diagramsnet` for manually arranged, editable database documentation.41+42+`dbml` describes relational structure but does not by itself establish a universal conceptual ER notation. Validate that the selected renderer can show keys, nullability, and cardinality required by the story. diagram.zip renders source; it does not connect to a live database or verify that a schema matches production.43+44+## Review checklist45+46+Check every entity has an identifier or an explicit reason it does not. Check every relationship has both endpoint constraints, no many-to-many relationship is accidental, and optionality is stated. Look for duplicated facts, transitive dependencies, ambiguous names, and ownership rules missing from the model. Review conceptual and physical views separately when both are needed.47+48+## Standards and prior art49+50+Use ISO/IEC 11179 terminology for data-element naming and metadata where a governance context requires it: <https://www.iso.org/standard/35343.html>. For relational implementation, the SQL standard is the authority for constraints, but vendor DDL adds behavior not represented by a generic ERD.51+52+Crow’s-foot notation is common practice rather than one single universally controlling interchange standard. Declare the notation in a legend. If the user requires a formally exchangeable conceptual model (for example, a vendor-specific modeling repository format), diagram.zip has no dedicated interchange validator; that is an integration opportunity.@@ -0,0 +1,40 @@
1+---2+name: flowchart3+description: Choose a flowchart when the user needs a readable decision or process path with a clear start, sequence, branch, merge, or end.4+---5+6+# Flowchart7+8+## What and why9+10+A flowchart is a control-flow story: work moves from an entry point through actions and decisions to one or more outcomes. Choose it for procedures, troubleshooting, algorithms, approvals, and “what happens next?” explanations. It is not a good fit for rich business semantics, timed interactions between participants, or a large dependency network.11+12+## Model it13+14+1. State the scope and one reader question in the title.15+2. Identify start/end outcomes before filling in steps.16+3. Use verb-first action labels and phrase decisions as questions with labeled exits.17+4. Make the normal path visually dominant; keep exception paths explicit.18+5. Merge paths when they become equivalent, and avoid crossing connectors.19+20+Use conventional symbols where the audience expects them: process, decision, terminator, input/output, and connector. ISO 5807 remains the relevant flowchart reference; use its notation when interchange or formal review matters. See [flowchart conventions](references/flowchart-conventions.md).21+22+## Story and styling23+24+The useful story is “how a case gets from here to there.” Keep one direction, consistent spacing, and short labels. Reserve color for semantic emphasis such as risk, exception, or ownership; provide shape or text cues too. Put explanatory detail in notes or adjacent prose rather than turning every node into a paragraph.25+26+## Renderer routing27+28+Prefer `mermaid` for quick Markdown-friendly flowcharts, `graphviz` when automatic graph layout matters, `plantuml` for a source-controlled formal diagram, or `d2` for a polished architecture/process sketch. `blockdiag` is suitable for simple block-oriented paths. Preserve an explicitly requested renderer and adapt the model to its syntax.29+30+## Review31+32+- Is there one clearly stated scope and outcome question?33+- Can every decision exit be followed and understood?34+- Are loops, retries, and failure outcomes visible?35+- Does the layout have a reading direction and minimal line crossings?36+- Are symbols, labels, contrast, and text alternatives usable in the target output?37+38+## Limits and opportunities39+40+The renderers above do not provide a guaranteed ISO 5807 interchange validator. If strict symbol conformance or machine validation becomes a product requirement, add a flowchart semantic linter or an ISO-profile integration.@@ -0,0 +1,7 @@
1+# Flowchart conventions2+3+ISO 5807:1985, confirmed current in 2019, defines documentation symbols and conventions for data, program, and system flowcharts. Use it as a vocabulary and review aid rather than assuming that a renderer's shape names prove conformance.4+5+Reference: [ISO 5807:1985](https://www.iso.org/standard/11955.html).6+7+The standard is not bundled as executable validation in diagram.zip. Treat strict conformance checking as a possible future integration.@@ -0,0 +1,40 @@
1+---2+name: gantt-chart3+description: Use when the user needs a time-scaled schedule showing tasks, durations, dependencies, milestones, and progress across teams or workstreams.4+---5+6+# Gantt chart7+8+## What and why9+10+A Gantt chart tells the scheduling story: work packages occupy intervals on a calendar, and dependencies constrain when work can happen. It is useful for delivery plans, migrations, launches, and maintenance windows.11+12+Choose it for planned work over time. Avoid it for an event history (timeline), a process’s logical steps without dates (flowchart), or a personal experience over stages (user-journey-map).13+14+## How15+16+1. Establish a calendar, timezone, working-day policy, and status date.17+2. Decompose deliverables into tasks with owners, start/finish or duration, and a definition of done.18+3. Add only meaningful dependencies; distinguish finish-to-start from other relationships when supported.19+4. Mark milestones as zero-duration outcomes, not decorative dates. Show progress with a legend and a clear as-of date.20+5. Keep the critical path or key release gates visible; move low-value detail to a linked plan.21+22+## Story and styling23+24+Order rows by deliverable or dependency flow. Use neutral bars for planned work, a distinct overlay for completed work, and one accent for gates or risk. Never use color alone for status. Include weekends/holidays and baseline variance only if they inform the decision.25+26+If no renderer is specified, use `mermaid` for a compact source-controlled schedule. `plantuml` can represent Gantt charts in its supported syntax; `graphviz` and `d2` require modeling a schedule manually and are poor defaults. Preserve an explicit renderer choice. Renderers do not replace a scheduling engine: validate dates, dependencies, and resource constraints before drawing.27+28+## Review29+30+- Is the as-of date, calendar, and timezone visible?31+- Does each task have an owner, outcome, and realistic duration?32+- Are dependencies meaningful and free of cycles?33+- Are milestones outcomes and progress semantics unambiguous?34+- Does the chart distinguish plan, actual, baseline, and uncertainty?35+36+## Prior art and limitations37+38+Use project-scheduling vocabulary from [ISO 21502:2020](https://www.iso.org/standard/74947.html) and dependency concepts from [PMI’s Practice Standard for Scheduling](https://www.pmi.org/pmbok-guide-standards/practice-guides/scheduling). These sources guide the planning model; they do not prescribe one SVG notation.39+40+The available renderers do not calculate critical paths, resource leveling, calendars, or earned value. Integration with a scheduling model/validator would be needed for authoritative planning rather than presentation-only charts.@@ -0,0 +1,38 @@
1+---2+name: hdl-component-diagram3+description: Use when the user needs a hardware-design view of HDL entities, modules, interfaces, ports, parameters, clocks, resets, and hierarchy.4+---5+6+# HDL component diagram7+8+## Select it when9+10+Choose this skill to explain a Verilog/SystemVerilog module hierarchy or VHDL entity/architecture boundary and its interfaces. Use it for design review, onboarding, integration planning, and clock/reset documentation. Do not use it as a substitute for RTL, a timing report, a gate-level netlist, or an electrical schematic.11+12+## Story and modeling13+14+Decide whether the story is hierarchy, interface contract, or clock/reset flow. Show module/entity names, instance boundaries, port direction, width, protocol role, clock domain, reset polarity/synchrony, parameters/generics, and meaningful buses. Distinguish combinational/data paths from clocks, resets, interrupts, and sidebands. Keep implementation detail out unless it answers the review question; link to source paths and generated netlist reports when available.15+16+The picture is an explanatory abstraction. It is not proof that RTL elaborates, synthesizes, meets timing, or matches a pin constraint. Never infer signal widths or clock domains from line styling alone.17+18+## Styling and customization19+20+Use nested containers for hierarchy, consistent port-side placement, and labeled bus widths. Give clocks and resets a clearly documented visual treatment, but provide labels so color is not the only encoding. Use one visual grammar for module interfaces and another for external pins or board connections. Highlight only the path under review and put protocol details in notes or a companion table.21+22+## Renderer routing23+24+Preserve a renderer explicitly requested by the user. Prefer `symbolator` when VHDL or Verilog declarations should produce a component symbol with ports, groups, and widths. Use `plantuml`, `d2`, or `graphviz` for module hierarchy and dependencies, or `diagramsnet` when manual port placement is essential. Symbolator parses a useful declaration subset; diagram.zip does not validate complete Verilog, SystemVerilog, VHDL, SVA, CDC constraints, or synthesis output.25+26+## Review27+28+Check that every shown port has direction and width where relevant, interfaces are not confused with instances, clock/reset domains are explicit, and omitted signals are called out. Verify names against elaborated RTL or a netlist. Check fan-out, bidirectional buses, clock crossings, and reset release assumptions. Mark the source revision and whether the view is pre- or post-elaboration.29+30+## References31+32+- [IEEE 1800-2023 SystemVerilog](https://standards.ieee.org/standard/1800-2023.html) — language standard; diagram.zip does not parse or validate the full language.33+- [IEEE 1076-2019 VHDL](https://standards.ieee.org/standard/1076-2019.html) — VHDL language standard; entity/architecture terminology here follows it at a high level.34+- [IEEE 1801-2024 UPF](https://standards.ieee.org/standard/1801-2024.html) — power intent can affect hardware views but is not represented automatically.35+36+## Integration opportunities37+38+Standards-compliant HDL-aware authoring would require parser/elaborator integration, width and direction checks, clock-domain analysis, source links, and optional synthesis/netlist import. Current renderers only provide depiction.@@ -0,0 +1,34 @@
1+---2+name: hierarchy-diagram3+description: Use when the user needs a ranked, nested, or reporting structure such as a taxonomy, organization chart, tree, or work breakdown structure.4+---5+6+# Hierarchy diagram7+8+## What / why9+10+A hierarchy diagram shows parent-child levels. It tells the story “what contains, reports to, or decomposes into what?” Name the relationship because taxonomy, authority, and work decomposition are not interchangeable.11+12+## How to model13+14+- Declare the hierarchy kind and root before adding nodes.15+- Give each node one parent unless multiple inheritance is explicitly intended.16+- Keep siblings at the same abstraction level; avoid mixing roles, instances, and tasks.17+- For a WBS, use verb-led deliverables and decompose until work is estimable; for an org chart, use roles and reporting lines; for a taxonomy, use concepts and “is-a” relationships.18+- Show cross-links separately from the tree so they cannot be mistaken for parentage.19+20+## Styling and customization21+22+Use top-down or left-to-right levels, aligned siblings, consistent node sizes, and whitespace. Use color to distinguish categories or departments, not depth alone. For org charts, label role and optionally person separately; for WBS, show identifiers and status secondarily.23+24+## Renderer choices25+26+Preserve user choice. Mermaid flowcharts/mindmaps and Graphviz/DOT are good for generated trees; PlantUML can express deployment/component-style hierarchies; D2 and diagrams.net suit bespoke layouts. diagram.zip has no dedicated org-chart or WBS semantic renderer: use supported syntax and document relationship semantics in labels.27+28+## Review29+30+Verify one root (or explain a forest), consistent parent semantics, no accidental cycles, readable levels, and a legend for dashed or secondary links. Check that a WBS is deliverable-oriented rather than merely an org chart.31+32+## Prior art and gaps33+34+See [references/prior-art.md](references/prior-art.md). ArchiMate, SysML, and formal WBS interchange are not rendered as native diagram.zip semantic types; integration would require a parser/profile and conformance checks.@@ -0,0 +1,7 @@
1+# Hierarchy references2+3+- [PMI Work Breakdown Structure practice standard](https://www.pmi.org/standards/work-breakdown-structures) — prior art for deliverable-oriented decomposition and the 100-percent rule.4+- [Graphviz DOT documentation](https://graphviz.org/documentation/) — supported automatic tree layout.5+- [Mermaid flowchart syntax](https://mermaid.js.org/syntax/flowchart.html) — supported hierarchical graph syntax.6+7+Org-chart and taxonomy semantics are conventions rather than one universal interchange standard. Do not claim a generic tree is an ArchiMate or SysML view without implementing that standard.@@ -0,0 +1,34 @@
1+---2+name: matrix-diagram3+description: Use when the user needs to compare two dimensions, expose a portfolio or prioritization space, or show a many-to-many relationship in a grid or quadrant.4+---5+6+# Matrix diagram7+8+## What / why9+10+A matrix places items against two or more declared dimensions. It tells the story “how does each item compare across these axes?” Use it for prioritization, responsibility, compatibility, or traceability; choose a graph when relationships themselves are the focus.11+12+## How to model13+14+- Name each axis, direction, unit, and scale before placing items.15+- Define whether cells mean intersection, score, responsibility, presence, or absence.16+- Use a consistent measure and show missing/unknown values explicitly.17+- Keep quadrant thresholds visible; do not let position imply precision the data does not have.18+- For a responsibility matrix, define roles and accountabilities rather than generic marks.19+20+## Styling and customization21+22+Use a quiet grid, strong headers, ample cell padding, and a colorblind-safe palette. Add values or labels so meaning does not depend on color or position. For a quadrant, annotate thresholds; for traceability, use symbols with a legend and accessible text.23+24+## Renderer choices25+26+Preserve user choice. diagrams.net and custom SVG are best for precise grids; Mermaid, D2, and Graphviz can approximate matrices with tables/subgraphs, and Vega/Vega-Lite suit data-driven matrices or heatmaps. diagram.zip has no dedicated semantic matrix or quadrant type, so renderer styling cannot substitute for axis definitions.27+28+## Review29+30+Check units, axis direction, ordering, thresholds, empty cells, legend, and accessibility. Verify rankings are not inferred from an arbitrary sort. If it is a heatmap, inspect the color scale and provide numeric values.31+32+## Prior art and gaps33+34+See [references/prior-art.md](references/prior-art.md). There is no single matrix interchange standard in diagram.zip; a data-driven matrix/heatmap integration could add schema validation and accessible tabular alternatives.@@ -0,0 +1,7 @@
1+# Matrix references2+3+- [W3C WCAG 2.2](https://www.w3.org/TR/WCAG22/) — accessibility requirements for non-text contrast, use of color, and text alternatives.4+- [Vega-Lite documentation](https://vega.github.io/vega-lite/) — supported declarative data-visualization renderer for quantitative matrices and heatmaps.5+- [RACI model](https://www.pmi.org/learning/library/responsible-accountable-consulted-informed-raci-roles-7382) — established prior art for responsibility matrices.6+7+diagram.zip does not currently expose a matrix schema, automatic color-scale validator, or ARIA/table alternative generator. Those are concrete integration opportunities if matrices become a first-class semantic type.@@ -0,0 +1,33 @@
1+---2+name: mind-map3+description: Use when the user needs to explore one central topic through associative branches, capture brainstorming, or organize an unconstrained idea space before choosing a structure.4+---5+6+# Mind map7+8+## What / why9+10+A mind map radiates from one central subject. It tells the story “what belongs around this idea?” rather than “what causes what?” Use it to externalize a messy topic, reveal themes, and identify next questions. Choose another skill when relationships need to be typed, ordered, causal, or exhaustive.11+12+## How to model13+14+- Put one unambiguous topic at the center; make branch labels nouns or short prompts.15+- Keep one concept per node and use a stable depth (topic → theme → detail).16+- Prefer parent-child containment. Do not imply sequence, ownership, or causality with an ordinary branch.17+- Mark questions, examples, decisions, and unknowns distinctly; do not bury caveats in prose.18+19+## Styling and customization20+21+Use radial or left-to-right layout, short labels, whitespace, and restrained color. Reserve color for branch families or status, and use line weight sparingly. A bespoke style may use icons, but every visual distinction needs a legend or clear label.22+23+## Renderer choices24+25+Ask for the user’s renderer preference first. Mermaid supports mind maps and configurable themes/layouts; D2, Graphviz, PlantUML, and diagrams.net can express tree-like maps but do not guarantee a mind-map grammar. Use native layout where possible; do not force a flowchart and call it a mind map. diagram.zip has no dedicated semantic mind-map validator, so validate hierarchy and labels in the source.26+27+## Review28+29+Check exactly one center, readable branches without color, comparable sibling levels, and no connector implying an unsupported relationship. Confirm whether the map is exploratory or a final taxonomy.30+31+## Prior art32+33+See [references/prior-art.md](references/prior-art.md).@@ -0,0 +1,6 @@
1+# Mind-map references2+3+- [Tony Buzan’s mind map guidance](https://www.tonybuzan.com/about/mind-mapping/) — prior art for a central image, radiating branches, keywords, and visual association.4+- [Mermaid mindmap syntax](https://mermaid.js.org/syntax/mindmap.html) — supported diagram.zip renderer syntax; check current renderer behavior before relying on experimental features.5+6+Mind maps have no single ISO/OMG interchange standard. A standards-based taxonomy or concept map may be a better fit when formal semantics are required.@@ -0,0 +1,52 @@
1+---2+name: network-topology3+description: Document physical or logical networks with nodes, interfaces, links, segments, addressing, trust zones, and traffic boundaries.4+---5+6+# Network topology7+8+## Select this skill when9+10+Use this skill when the story is connectivity: which devices or services attach to which network, how traffic can flow, where trust boundaries sit, or how a physical installation is wired. State whether the view is physical, logical, or both.11+12+Avoid it for application call dependencies (use dependency-graph), packet field layout (use protocol-layout-diagram), rack-unit placement (use rack-diagram), or a general system context. Do not use a topology map to imply that an application call is permitted merely because two nodes share a segment.13+14+## Story and semantic model15+16+Name the scope, observation time, and layer. Identify devices, interfaces, links, network segments, address ranges, VLANs, zones, gateways, and trust boundaries as appropriate. Define link direction and capacity only when known.17+18+- Distinguish physical links from logical adjacencies, tunnels, overlays, and routes.19+- Label interfaces or endpoints when a device has multiple connections.20+- Show layer-3 prefixes and layer-2 segments separately; do not conflate an IP range with a broadcast domain.21+- Mark ingress/egress, filtering devices, and trust boundaries with explicit labels.22+- Treat cloud and external networks as boundaries with ownership and assumptions, not as opaque decorative clouds.23+24+For a change review, highlight the affected path and annotate source-of-truth evidence. For incident response, show observed state and timestamp rather than presenting an intended design as fact.25+26+## Layout and styling27+28+Use nested containers for sites, zones, or segments. Arrange traffic flow consistently (left-to-right or top-to-bottom), keep gateways at boundaries, and attach labels close to interfaces. Use shape for device class and line style for physical/logical/tunnel links. Use color for trust or operational status only with a legend and a text fallback.29+30+Include a legend for abbreviations, link semantics, and address notation. Avoid unlabeled line crossings; if a link crosses a boundary, make the crossing explicit.31+32+## Renderer routing33+34+Preserve an explicit renderer choice. Otherwise prefer:35+36+- `nwdiag` for network blocks, hosts, addresses, and shared segments.37+- `d2` for custom logical/physical topology with containers and annotations.38+- `graphviz` for topology-as-graph or route-focused views.39+- `mermaid` for a small Markdown-friendly network map.40+- `diagramsnet` for manually positioned physical topology documentation.41+42+`nwdiag` is convenient but does not express every routing, security-policy, or vendor-device semantic. diagram.zip does not discover devices, test reachability, or validate IP plans. If the user requires import/export to a network-management or vendor topology format, live inventory integration, or formal path-policy validation, call that an unsupported integration opportunity.43+44+## Review checklist45+46+Check that scope, layer, timestamp, and ownership are stated. Verify every link has endpoints and a defined meaning, every segment has a boundary, and addresses are not invented. Confirm that physical and logical relationships are not visually conflated. Review the highlighted path against current source-of-truth data and test the final diagram at print or incident-room size.47+48+## Standards and prior art49+50+RFC 2360 documents conventions for Internet protocol documentation and packet/network figures: <https://www.rfc-editor.org/rfc/rfc2360>. ISO/IEC 27001 and 27002 provide information-security control context for network zones and access boundaries, but do not prescribe a single topology notation: <https://www.iso.org/isoiec-27001-information-security.html>.51+52+Network topology notation is largely operational prior art rather than one universal exchange standard. Declare the layer and legend. For formal network configuration or topology exchange, diagram.zip currently has no dedicated NETCONF/YANG, vendor NMS, or inventory adapter; that is an integration opportunity.@@ -0,0 +1,56 @@
1+---2+name: protocol-layout-diagram3+description: Use when a diagram must explain the bit, byte, or word layout of a protocol message, file header, register, or binary record.4+---5+6+# Protocol layout diagram7+8+## What it is9+10+A protocol layout diagram maps wire-order positions to named fields. It tells the reader how many bits or bytes each field occupies, where boundaries fall, which values are interpreted together, and which parts are conditional or repeated.11+12+## Choose it when13+14+- the question is “what is at offset N?” or “how is this message encoded?”15+- implementation, interoperability, packet capture, or security review depends on exact widths and ordering;16+- a prose table would hide alignment, reserved bits, endianness, or optional extensions.17+18+Use a sequence or flow diagram for message behavior. Use a data-flow diagram for movement between components. Do not use this diagram to imply that fields are sent in the order they are drawn unless wire order is explicitly stated.19+20+## Story and modeling21+22+1. State the unit and orientation: bits per row, byte order, bit numbering convention, and whether offsets are absolute or relative.23+2. Draw the fixed header first, then conditional, repeated, and payload regions. Mark variable-length fields with their length rule.24+3. Give every field a name, width/range, and interpretation. Show reserved bits and whether they must be zero, ignored, or preserved.25+4. Separate normative wire facts from explanatory annotations. Record the specification version and section beside the title or in a legend.26+5. Check examples against the encoding: widths must sum to the row width, offsets must not overlap, and endianness must agree with the prose.27+28+## Styling and customization29+30+Use a restrained palette: one color for fixed framing, one for payload, one for control/flags, and a visibly distinct treatment for reserved or deprecated fields. Put bit numbers above the row and byte offsets below it. Keep labels short and move long semantics into notes. For accessibility, do not communicate field meaning by color alone; use text, patterns, or a legend.31+32+## Renderer routing33+34+- `packetdiag` is the direct diagram.zip fit for bit-field layouts; preserve its column width and field-range semantics.35+- `bytefield` is useful for byte-oriented headers and payloads when a code-defined, repeatable layout is preferred.36+- `wavedrom` can express registers and bus transactions when timing is part of the story, but it is not a substitute for a normative packet layout.37+- `tikz` or `pikchr` can be a bespoke escape hatch when a standards-specific notation exceeds those renderers.38+39+Keep the user's explicit renderer choice. If no renderer is specified, choose the smallest source that preserves exact widths and explain the choice. diagram.zip does not currently provide a dedicated parser/validator for every protocol standard; a standards-aware packet editor or automatic field-sum validation would be a useful integration opportunity.40+41+## Review checklist42+43+- Is wire order, bit numbering, and unit unambiguous?44+- Do widths, offsets, and alignment add up?45+- Are optional, repeated, reserved, and extension fields explicit?46+- Are byte order and value encoding documented?47+- Is the cited specification/version recoverable?48+- Can a reader distinguish normative fields from commentary without color?49+50+## References51+52+- [RFC 2360, section 3.3](https://www.rfc-editor.org/rfc/rfc2360.html#section-3.3) summarizes conventions for protocol diagrams and field representations.53+- [RFC 791, section 3.1](https://www.rfc-editor.org/rfc/rfc791.html#section-3.1) is a canonical example of an Internet header bit layout and field description.54+- [RFC 8200, section 3](https://www.rfc-editor.org/rfc/rfc8200.html#section-3) shows the IPv6 base-header field layout and extension-header model.55+- [PacketDiag documentation](http://blockdiag.com/en/nwdiag/packetdiag-examples.html) documents the diagram.zip-supported PacketDiag source model.56+- [Bytefield SVG documentation](https://bytefield-svg.deepsymmetry.org/) documents byte-oriented source forms.@@ -0,0 +1,55 @@
1+---2+name: rack-diagram3+description: Use when documenting equipment placement in a cabinet or rack, including rack units, device identity, power, network uplinks, and physical capacity.4+---5+6+# Rack diagram7+8+## What it is9+10+A rack diagram is a vertical physical inventory view. It tells the reader what occupies each rack unit, where blanking panels and shared equipment are, and how to identify or service the installed hardware.11+12+## Choose it when13+14+- operations, facilities, installation, maintenance, or capacity planning depends on physical rack position;15+- a cabinet contains servers, switches, patch panels, PDUs, UPS units, shelves, or reserved space;16+- the reader needs a fast unit-by-unit inventory rather than a logical topology.17+18+Pair it with a network-topology diagram for logical links and a deployment diagram for software placement. Do not infer power, airflow, cable path, or network connectivity from vertical adjacency alone.19+20+## Story and modeling21+22+1. Name the site, room, cabinet, face (front/rear), orientation, and rack-unit numbering direction.23+2. Show total usable U height and every occupied, reserved, and intentionally blank unit. Represent multi-U devices at their actual height.24+3. Label each device with asset/service identity, model or role, and U range. Use a legend for shared devices, patch panels, PDUs, and blanking panels.25+4. Add power feeds, cable management, airflow direction, and rear-view details only when they are in scope; distinguish planned, installed, and decommissioned equipment.26+5. Include revision/date and an authoritative inventory reference. A rack drawing is not an asset database.27+28+## Styling and customization29+30+Use a stable visual grammar: one unit grid, consistent device height, strong cabinet boundaries, and restrained colors by equipment role. Use labels and symbols in addition to color. Keep identifiers legible at print scale, and use callouts for dense front/rear cabling rather than crossing the rack body with wires.31+32+## Renderer routing33+34+- `rackdiag` is the direct diagram.zip fit and preserves rack-unit placement and device height.35+- `diagramsnet` is appropriate when a facilities team needs to edit a native physical-layout document.36+- `diagramsnet` or `tikz` can support bespoke front/rear views, airflow arrows, or detailed cable callouts.37+- `nwdiag` shows network segments, not physical cabinet placement; pair it when logical connectivity matters.38+39+Preserve the user's explicit renderer choice. If no renderer is specified, choose `rackdiag` for an inventory-style rack and explain what it cannot represent. diagram.zip does not currently ingest DCIM/CMDB inventories, validate U conflicts, or model thermal/power budgets. Importing an authoritative inventory and checking occupied-unit, power, and airflow constraints would be a meaningful integration opportunity.40+41+## Review checklist42+43+- Are cabinet identity, face, orientation, and U numbering explicit?44+- Do device heights and U ranges avoid overlap and fit the cabinet?45+- Are blank, reserved, planned, and decommissioned units distinguished?46+- Are asset identity and revision/date present?47+- Are power, airflow, and cabling claims backed by source data?48+- Is logical connectivity kept separate or clearly linked to another view?49+50+## References51+52+- [RackDiag examples](http://blockdiag.com/en/nwdiag/rackdiag-examples.html) documents the diagram.zip-supported rack-unit source model.53+- [ANSI/TIA-606-C](https://www.tiaonline.org/standards/standards-information/) is the telecommunications infrastructure administration and labeling standard; use the licensed standard for authoritative identifier and record requirements.54+- [ASHRAE TC 9.9](https://www.ashrae.org/technical-resources/bookstore/datacom-series) provides data-center thermal guidance; a rack drawing should not claim thermal compliance without the applicable facility analysis.55+- [Uptime Institute data-center standards](https://uptimeinstitute.com/standards) provides facility-resilience context that is outside the scope of a rack-placement renderer.@@ -0,0 +1,40 @@
1+---2+name: sequence-diagram3+description: Choose a sequence diagram when the user needs to explain ordered messages, calls, responses, or time-dependent collaboration between participants.4+---5+6+# Sequence diagram7+8+## What and why9+10+A sequence diagram tells a time-ordered interaction story. It is strongest for an API request, authentication exchange, event flow, incident trace, or one scenario across services and people. It is not a deployment map, class structure, or a complete behavioral specification.11+12+## Model it13+14+1. Name the scenario and trigger, including success or failure scope.15+2. Choose participants that send, receive, or transform a message; omit passive infrastructure.16+3. Order messages top-to-bottom and label intent, not implementation trivia.17+4. Use activation, return, loop, alternative, optional, and parallel fragments only when they clarify behavior.18+5. Mark asynchronous messages, timeouts, retries, and external boundaries explicitly.19+20+UML 2.5.1 defines interaction and combined-fragment semantics. See [UML interaction guidance](references/uml-interactions.md).21+22+## Story and styling23+24+Make the primary path easy to scan, then place alternatives in `alt`/`opt` regions. Use participant types consistently and distinguish synchronous calls from asynchronous signals. Keep lifelines aligned; use restrained color for external systems, errors, or trust boundaries. Never encode meaning by color alone.25+26+## Renderer routing27+28+Prefer `mermaid` for lightweight docs, `plantuml` for expressive UML fragments, `seqdiag` for compact message-focused diagrams, or `d2` when the sequence is part of a broader technical illustration. Preserve the user's renderer choice. `bpmn` is appropriate only when the requested story is a formal business process with BPMN events, tasks, and message flows.29+30+## Review31+32+- Is the scenario boundary and trigger explicit?33+- Does vertical order represent time without implying false duration?34+- Are request/response direction, async behavior, errors, and retries unambiguous?35+- Are fragments labeled with meaningful guards?36+- Is the diagram readable without relying on tiny labels or color alone?37+38+## Limits and opportunities39+40+diagram.zip renders sequence sources but does not execute a UML interaction validator or check trace completeness. A future integration could validate UML fragment nesting and provide conformance diagnostics.@@ -0,0 +1,7 @@
1+# UML interactions2+3+UML 2.5.1 defines interaction diagrams, lifelines, messages, executions, and combined fragments such as alternatives, options, loops, and parallel regions. Use the standard when a sequence diagram is a design artifact rather than an informal sketch.4+5+Reference: [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1).6+7+PlantUML and Mermaid provide useful notations but are not interchange validators for every UML constraint. Strict UML validation is an integration opportunity.@@ -0,0 +1,34 @@
1+---2+name: set-diagram3+description: Use when the user needs to show membership, overlap, exclusion, union, intersection, or nested categories with sets.4+---5+6+# Set diagram7+8+## What / why9+10+A set diagram tells the story “which elements belong to which sets, and where do memberships overlap?” Use Venn diagrams for a small number of sets and Euler diagrams when only meaningful intersections should be shown. Choose a graph for typed relationships or a matrix for exhaustive pairwise comparison.11+12+## How to model13+14+- Define each set and the universe or scope; state whether circles are exhaustive.15+- Put elements in regions only when membership is known; distinguish empty from unknown.16+- Label intersections with the set operation or plain-language meaning.17+- Keep set count small enough for legible regions; use an Euler representation for sparse overlaps.18+- Do not use area or circle size to imply quantity unless it is quantitatively encoded and explained.19+20+## Styling and customization21+22+Use overlapping outlines with high-contrast labels, transparent fills, and patterns or labels in addition to color. Avoid excessive intersections. Provide an accessible list/table of memberships when important, and keep the universe boundary visible when it matters.23+24+## Renderer choices25+26+Preserve user choice. Mermaid, Graphviz, D2, PlantUML, and diagrams.net can approximate set diagrams with shapes and labels; diagrams.net or custom SVG is better for controlled overlap. diagram.zip has no dedicated Venn/Euler semantic renderer or overlap solver, so verify memberships manually and do not claim proportional geometry.27+28+## Review29+30+Check every region against membership data, confirm empty/unknown regions, make labels readable, and test grayscale/colorblind viewing. Ensure the chosen Venn layout can represent stated intersections; otherwise switch to Euler or a table.31+32+## Prior art and gaps33+34+See [references/prior-art.md](references/prior-art.md). A native set renderer would need membership input, Venn/Euler layout validation, and an accessible tabular fallback; this is an integration opportunity rather than current diagram.zip support.@@ -0,0 +1,7 @@
1+# Set-diagram references2+3+- [Euler diagram definition (Encyclopaedia of Mathematics)](https://encyclopediaofmath.org/wiki/Euler_diagram) — prior art distinguishing diagrams that show only existing set intersections.4+- [Venn’s original set diagram paper](https://doi.org/10.1080/14786440508637087) — historical prior art for systematic set intersections.5+- [W3C SVG accessibility guidance](https://www.w3.org/TR/SVG-access/) — relevant when a set diagram is delivered as SVG and needs meaningful text alternatives.6+7+No supported diagram.zip renderer currently guarantees a valid Venn or Euler layout from arbitrary set membership data. Treat overlap geometry as illustrative unless an integration adds validation.@@ -0,0 +1,40 @@
1+---2+name: state-machine-diagram3+description: Choose a state-machine diagram when an entity's permitted states, event-triggered transitions, guards, and entry or exit behavior are the central story.4+---5+6+# State-machine diagram7+8+## What and why9+10+A state-machine diagram explains how one subject changes state in response to events. Use it for lifecycle rules, protocol sessions, order status, device modes, and resilient services. Do not use it when the main question is work order between participants; choose a sequence or activity diagram instead.11+12+## Model it13+14+1. Name the subject and define its initial and terminal conditions.15+2. List stable, externally meaningful states rather than every implementation flag.16+3. Label transitions `event [guard] / effect` where useful.17+4. Add entry, exit, and do behavior only when it changes the reader's interpretation.18+5. Use composite or concurrent states for genuine hierarchy or orthogonal behavior; avoid decorative nesting.19+20+UML 2.5.1 is the prior art for state machines, pseudostates, guards, and regions. See [UML state-machine guidance](references/uml-state-machines.md).21+22+## Story and styling23+24+Make states the visual anchors and transitions the explanation. Use a consistent arrow direction, explicit self-loops, and a legend for event/guard/effect syntax. Style terminal, error, and externally controlled states distinctly, with labels and shapes supporting any color choice.25+26+## Renderer routing27+28+Prefer `mermaid` for compact state diagrams, `plantuml` for UML-rich state machines, `graphviz` for explicit graph layout, or `d2` for annotated technical state views. Preserve a requested renderer. Avoid `c4plantuml`, because C4 is for software architecture structure, not lifecycle behavior.29+30+## Review31+32+- Is there exactly one subject or a clearly defined composite boundary?33+- Are initial, terminal, error, and unreachable states considered?34+- Does every transition have a meaningful trigger and destination?35+- Are guards mutually understandable and effects separated from events?36+- Are concurrency, hierarchy, and history semantics necessary and explained?37+38+## Limits and opportunities39+40+diagram.zip can render state-machine source but does not model-check reachability, determinism, deadlocks, or event completeness. A state-machine lint/verification integration would add material value for protocol and safety-critical use cases.@@ -0,0 +1,7 @@
1+# UML state machines2+3+UML 2.5.1 specifies states, transitions, triggers, guards, effects, pseudostates, composite states, regions, and state-machine ownership. Use those concepts when lifecycle behavior must be reviewed precisely.4+5+Reference: [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1).6+7+The renderers are presentation tools; they do not guarantee semantic validation of a UML state machine. Consider a future parser and model-checking integration.@@ -0,0 +1,30 @@
1+---2+name: system-context-diagram3+description: Explain one system in its environment by showing its users, external systems, and the relationships that matter.4+---5+6+# System context diagram7+8+## What it tells9+10+This view answers “what is this system, who uses it, and what does it depend on?” It shows one named system as the focal boundary plus relevant people, organizations, external systems, and high-level relationships.11+12+## Use and boundaries13+14+Use it for onboarding, product scope, stakeholder alignment, risk review, and early architecture decisions. Keep the focal system as one box. Do not open it into containers or components, and do not turn external systems into infrastructure nodes. Add a system landscape first when the audience needs portfolio context.15+16+## Method17+18+Name the system by purpose, identify actors by role, and list external systems only when they exchange information or impose a meaningful constraint. Label every relationship with a concise verb and optionally direction, protocol, or data. Make system ownership and trust boundaries explicit when they affect the story. Prefer one context diagram per focal system and audience.19+20+## Renderer routing21+22+Preserve a requested renderer. Prefer `structurizr` when the context view belongs to a reusable C4 workspace model, `c4plantuml` for a focused C4 source, `plantuml` for an unconstrained architecture view, or `mermaid`, `d2`, and `graphviz` for lightweight sketches. Use `blockdiag` only for an informal block view; it will not encode C4 roles or semantics for you.23+24+## Style and review25+26+Use a strong visual treatment for the focal system, a consistent actor shape, and a neutral external-system shape. Keep the canvas sparse, route edges clearly, and include a legend for trust or relationship patterns. Ensure the focal boundary is unambiguous, all important actors/dependencies are named, arrows are readable in grayscale, and no internal implementation details slipped in.27+28+## Prior art and limits29+30+The C4 context diagram is a widely used framing convention and is deliberately notation-independent, not a formal interchange standard. ArchiMate and UML can provide formal viewpoints, but diagram.zip does not currently expose a dedicated ArchiMate source or a profile-enforced context renderer. That is an integration opportunity if formal semantics or model exchange becomes a requirement. See [C4 diagrams](https://c4model.com/diagrams), [C4 notation](https://c4model.com/diagrams/notation), [UML](https://www.omg.org/spec/UML/2.5.1/), and [ArchiMate overview](https://www.opengroup.org/archimate-forum/archimate-overview).@@ -0,0 +1,30 @@
1+---2+name: system-landscape-diagram3+description: Show the systems and people across an organization or domain, emphasizing ownership and meaningful dependencies.4+---5+6+# System landscape diagram7+8+## What it tells9+10+A landscape is the broadest software architecture view: which systems, people, teams, or domains exist and how they relate. It tells an audience where a system sits in a wider estate, not how its internals work.11+12+## Use and boundaries13+14+Use it for portfolio orientation, modernization planning, ownership conversations, integration discovery, and explaining a system's neighbors. Choose one organizational or domain scope and state it in the title. Avoid showing classes, containers, deployment hosts, or detailed request sequences; those belong in narrower companion views.15+16+## Method17+18+Start with the audience's question and inventory only systems relevant to it. Group by business domain, ownership, or environment—not arbitrary spatial decoration. Give each node a stable name and concise purpose. Draw only relationships that support a decision, label them with a verb, and distinguish dependency from data movement or responsibility. Mark uncertainty rather than inventing an integration.19+20+## Renderer routing21+22+Honor the user's source choice. For a C4-style landscape, use `structurizr` when the landscape belongs to a reusable workspace model or `c4plantuml` for a focused source file. Use `plantuml` for a custom UML-like view, or `mermaid`, `d2`, and `graphviz` for compact relationship maps. `blockdiag` can express simple blocks but does not supply C4 semantics. Check the selected renderer's supported syntax in diagram.zip docs before writing source.23+24+## Style and review25+26+Use one shape family for systems and another for people or organizations. Cluster sparingly, keep edge crossings low, and provide a legend for colors, line types, ownership, and trust boundaries. Prefer labels and patterns over color-only coding. Review for accidental detail, duplicate nodes, unlabeled arrows, missing external actors, and a scope that is too broad to read.27+28+## Prior art and limits29+30+This follows the C4 landscape/context framing, which is notation-independent; it is not a formal ArchiMate exchange model. ArchiMate viewpoints could add standardized enterprise-architecture semantics, but diagram.zip has no dedicated ArchiMate renderer/skill yet. Consider integration if conformance or model interchange is required. See [C4 diagrams](https://c4model.com/diagrams), [C4 notation](https://c4model.com/diagrams/notation), and [ArchiMate overview](https://www.opengroup.org/archimate-forum/archimate-overview).@@ -0,0 +1,39 @@
1+---2+name: technical-illustration3+description: Use when the user needs an explanatory technical figure showing parts, assemblies, operation, dimensions, callouts, or a controlled visual sequence.4+---5+6+# Technical illustration7+8+## Select it when9+10+Choose this skill for an explanatory figure whose meaning depends on physical appearance, exploded relationships, section views, callouts, or a sequence of operation. Use it for manuals, training, proposals, and engineering communication. Do not use it for a pure graph, formal schematic, manufacturing drawing, or photorealistic product render unless that is explicitly the requested deliverable.11+12+## Story and modeling13+14+State the reader's question and the viewing convention: identify parts, show assembly order, explain motion/flow, expose an internal section, or compare states. Establish a datum/orientation, part IDs, leader-line targets, scale status, and what is intentionally omitted. Separate measured dimensions from illustrative proportions. If geometry or safety depends on exact values, link to the controlled CAD/drawing source.15+16+The output is an explanatory depiction, not automatically a standards-compliant technical product definition. A generic diagram renderer cannot guarantee projection rules, tolerances, datum systems, material hatching, or manufacturing authority.17+18+## Styling and customization19+20+Use a restrained palette, high-contrast labels, consistent line weights, and uncluttered leader lines. Use exploded offsets and transparency sparingly; preserve occlusion cues and assembly order. Number parts consistently and provide a keyed parts list. Use section hatching or dimension marks only when their convention is explained. Avoid decorative perspective that changes the apparent relationship or hides a critical interface.21+22+## Renderer routing23+24+Preserve a renderer explicitly requested by the user. Use `pikchr` or `tikz` for controlled geometry, `diagramsnet` or `excalidraw` for manually composed callouts and assembly views, and `ditaa`, `goat`, or `svgbob` for text-native sketches. Use `d2`, `graphviz`, or `plantuml` when the illustration is really a relationship abstraction. No listed renderer is a CAD, geometric-dimensioning, or photorealistic illustration engine; offer an integration gap rather than faking precision.25+26+## Review27+28+Check callout target accuracy, part numbering, orientation, section/hidden-line conventions, label legibility, contrast, and print behavior. Confirm that dimensions have units and that “not to scale” is visible where applicable. Have a domain reviewer verify the physical interpretation and compare against the controlled source. Record revision and intended audience.29+30+## References31+32+- [ISO 128-1:2020](https://www.iso.org/standard/65296.html) — general principles for technical drawings; consult the applicable part and licensed text for production work.33+- [ISO 5455:1979](https://www.iso.org/standard/11514.html) — scales for technical drawings; a renderer does not enforce scale.34+- [ISO 5457:1999](https://www.iso.org/standard/11522.html) — sizes and layout of drawing sheets; page-layout integration may be needed.35+- [IEC 61082-1](https://webstore.iec.ch/en/publication/265) — electrotechnical documentation conventions where the illustration is part of such a document.36+37+## Integration opportunities38+39+Standards-aware projection, dimensioning, tolerancing, CAD import, vector authoring, material/section conventions, and controlled title-block export are not provided by the current diagram renderers. Treat those as integration opportunities when exact engineering documentation is required.@@ -0,0 +1,40 @@
1+---2+name: timeline3+description: Use when the user needs to communicate events or milestones in chronological order, with dates, intervals, eras, or parallel tracks.4+---5+6+# Timeline7+8+## What and why9+10+A timeline tells a chronological story: what happened, when it happened, and sometimes how parallel strands relate. It is useful for releases, incidents, historical context, migrations, and roadmaps.11+12+Choose it when time is the primary organizing axis. Avoid it for task scheduling with dependencies (gantt-chart), causal process flow (flowchart), or a person’s step-by-step experience (user-journey-map).13+14+## How15+16+1. Choose the time scale and state it: dates, quarters, years, eras, or relative time.17+2. Select only events that advance the story; give each an unambiguous date or interval.18+3. Use a single track for one narrative and parallel tracks for independent streams. Keep labels short and put detail in notes.19+4. Distinguish event, milestone, interval, and uncertainty. Do not imply precision the source does not support.20+5. If the timeline is a roadmap, label commitment status separately from chronology.21+22+## Story and styling23+24+Use a strong axis and consistent date formatting. Encode event categories with shape or small color accents, but also label them for color-independent reading. Use whitespace for eras and avoid crossing annotations. For dense timelines, split into views by track or period.25+26+If no renderer is specified, use `mermaid` for its timeline syntax or `d2`/`graphviz` when custom layout is more important. These renderers do not provide a universal temporal data model; validate dates and uncertainty in the source data. Preserve an explicit renderer choice.27+28+## Review29+30+- Is the time scale and direction explicit?31+- Are dates, intervals, and uncertain dates represented honestly?32+- Can a reader distinguish tracks and event categories without color alone?33+- Does every item earn its space in the narrative?34+- Are roadmap status and chronological position kept separate?35+36+## Prior art and limitations37+38+For milestone and project communication, align terminology with [ISO 21502:2020](https://www.iso.org/standard/74947.html), while recognizing that a timeline is a communication view rather than a project-control model. For historical chronology, use the source domain’s date conventions and cite the source data.39+40+The supported text renderers do not guarantee date-aware scaling, collision avoidance, or semantic uncertainty encoding. A standards-aware timeline data model and date-scale renderer would be a useful integration opportunity.@@ -0,0 +1,40 @@
1+---2+name: use-case-diagram3+description: Use when the user needs to explain who can achieve which externally visible goals with a system, including actors, system boundaries, and goal relationships.4+---5+6+# Use-case diagram7+8+## What and why9+10+Use a use-case diagram to scope a system from the perspective of actors and their goals. It tells the story of who interacts with the system and what value they seek, not how the implementation works.11+12+Choose it when the question is “who needs which capability?” Avoid it for call ordering, internal architecture, data movement, or detailed requirements; use a sequence, context, or data-flow diagram instead.13+14+## How15+16+1. Name the system boundary and write each use case as an observable goal using a verb.17+2. Identify human, organizational, device, or external-system actors; keep actors outside the boundary.18+3. Connect actors to goals they participate in. Use `include` only for required reused behavior and `extend` only for optional behavior at an explicit extension point.19+4. Add generalization only when a specialized actor or goal is substitutable for a more general one.20+5. Keep the diagram at one scope and move scenarios, exceptions, and acceptance criteria into accompanying text.21+22+## Story and styling23+24+The visual hierarchy should make the boundary, actors, and primary goals obvious. Prefer a small set of neutral actor/system colors, strong boundary contrast, and short labels. Group use cases by capability area only when that grouping answers a real scope question; do not turn every subsystem into an actor.25+26+If the user has not chosen a renderer, use `plantuml` for UML notation or `mermaid` for a lightweight, Markdown-friendly version. `c4plantuml` is appropriate for a system-context view, not detailed use-case semantics. Preserve an explicit renderer choice. Mermaid and PlantUML can express the common notation, but neither is a requirements repository or a complete UML interchange format.27+28+## Review29+30+- Is every actor outside the system boundary and named by a role?31+- Does every use case state a user-visible goal rather than an implementation step?32+- Are `include`, `extend`, and generalization used sparingly and in the correct direction?33+- Is scope narrow enough to read without a legend-heavy wall of bubbles?34+- Are assumptions, alternate flows, and non-functional requirements documented elsewhere?35+36+## Prior art and limitations37+38+The notation follows the UML use-case model in [OMG UML 2.5.1](https://www.omg.org/spec/UML/2.5.1/), especially Use Cases and Relationships. For accessibility expectations for the rendered SVG, apply [WCAG 2.2](https://www.w3.org/TR/WCAG22/) and provide a meaningful title/description where the host supports it.39+40+The available renderers do not provide a standards-complete UML model exchange or traceability to requirements tools. Supporting XMI/UML interchange would be a separate integration opportunity.@@ -0,0 +1,40 @@
1+---2+name: user-journey-map3+description: Use when the user needs to understand a person’s experience across stages, touchpoints, actions, thoughts, emotions, pain points, and opportunities.4+---5+6+# User-journey map7+8+## What and why9+10+A user-journey map tells the experience story from a specific persona’s point of view across a goal-driven journey. It makes moments of friction, uncertainty, and opportunity visible to product and service teams.11+12+Choose it for experience discovery and service improvement. Avoid it for a technical request sequence (sequence-diagram), a dated delivery plan (gantt-chart), or a generic process with no user perspective (flowchart).13+14+## How15+16+1. Name the persona, situation, goal, scope, and journey start/end. State whether evidence is observed, reported, or hypothesized.17+2. Choose 4–8 stages that follow the user’s mental model, not internal team ownership.18+3. For each stage capture user actions, touchpoints/channels, questions or thoughts, emotional state, pain points, and opportunities.19+4. Add backstage dependencies only in a separate lane so the user’s experience remains primary.20+5. Rank opportunities by evidence, impact, and feasibility; do not turn an empathy map into unsupported demographic claims.21+22+## Story and styling23+24+Use stages as columns and experience dimensions as rows. Keep the persona and goal prominent, and use a small, labeled emotional curve only when it is evidence-based. Use icons sparingly, ensure labels carry meaning, and encode pain/opportunity with text plus shape or pattern—not color alone.25+26+If no renderer is specified, use `mermaid` for a simple journey/timeline-like layout or `diagramsnet` when the user needs a hand-arranged workshop canvas. `plantuml` can produce a structured activity-style approximation, but no available renderer is a dedicated journey-map model. Preserve an explicit renderer choice and explain any approximation.27+28+## Review29+30+- Is one persona, goal, and journey boundary explicit?31+- Are stages based on user behavior and evidence rather than org-chart phases?32+- Are touchpoints, backstage causes, pain, and opportunities distinguishable?33+- Are emotions framed as evidence or hypotheses?34+- Can a decision-maker see the next opportunity and its rationale?35+36+## Prior art and limitations37+38+Use the journey-mapping practice described by [Nielsen Norman Group](https://www.nngroup.com/articles/journey-mapping-101/) and service-design principles in [ISO 9241-210:2019](https://www.iso.org/standard/77520.html). These are guidance for research and communication, not a machine-readable interchange standard.39+40+The supported renderers do not encode research provenance, accessibility of workshop artifacts, or prioritization semantics. A dedicated journey-map schema with evidence and opportunity fields would be a worthwhile integration opportunity.@@ -0,0 +1,39 @@
1+---2+name: wiring-harness-diagram3+description: Use when the user needs to document wires, cables, connectors, splices, branches, pin mappings, or harness manufacturing/service information.4+---5+6+# Wiring harness diagram7+8+## Select it when9+10+Choose this skill when the important story is physical connectivity: which connector cavity, splice, terminal, shield, or wire reaches which destination. Use it for vehicle, aerospace, industrial, and test harness documentation. Do not use it for only a logical network topology, a circuit schematic, or a software dependency graph.11+12+## Story and modeling13+14+Start with the reader's task: build, inspect, troubleshoot, or modify the harness. Model connector references and cavity numbers, wire identifiers, conductor size, color, shielding, splice points, branch points, destinations, and relevant units. Separate physical route or bundle membership from electrical net identity. Mark unknown, optional, spare, and not-fitted conductors explicitly; never imply that a crossing is a connection.15+16+The diagram is a depiction, not automatically a manufacturing release. Preserve revision, source-of-truth identifiers, pin numbering conventions, and a legend. If a table is more reliable for a complete pin-to-pin netlist, pair the diagram with it.17+18+## Styling and customization19+20+Use a restrained color key for wire function or status, with line labels and a monochrome-safe alternative. Use heavier bundle lines and lighter individual conductors; show connectors as stable, labeled blocks and keep signal direction separate from physical routing. Avoid decorative colors that could be mistaken for conductor color codes. Add callouts for shield termination, splice details, bend/service loops, and cross-sheet references.21+22+## Renderer routing23+24+Preserve a renderer explicitly requested by the user. Prefer `wireviz` for connectors, cables, pins, wire colors, gauges, and connection mappings. Use `diagramsnet` for hand-positioned routes or assembly callouts, or `graphviz` and `d2` for relationship-first maps. Pair `nwdiag` only when logical network segments are a separate part of the story. WireViz models harness data, but diagram.zip does not validate terminal compatibility, bend radius, manufacturing rules, or external source-of-truth netlists.25+26+## Review27+28+Check every endpoint and cavity, connector orientation, branch/splice identity, wire label, shield/ground convention, crossing versus junction, and continuation reference. Check that the legend explains line weight, colors, and omissions, and that the output remains legible when printed in grayscale. State clearly when the result is illustrative rather than standards-compliant release data.29+30+## References31+32+- [SAE AS50881](https://www.sae.org/standards/content/as50881/) — aerospace and military wiring-system guidance; use the current licensed edition for release requirements, not this summary.33+- [IEC 60617:2026 DB](https://webstore.iec.ch/en/publication/2723) — graphical symbols for diagrams; symbol availability and licensing may require integration work.34+- [IEC 61082-1](https://webstore.iec.ch/en/publication/265) — rules for electrotechnical documentation; the renderer does not enforce its document conventions.35+- [IPC/WHMA-A-620E](https://www.ipc.org/news-release/ipc-releases-ipcwhma-620e-requirements-and-acceptance-cable-and-wire-harness) — manufacturing and acceptance requirements; a rendered harness diagram does not establish conformity.36+37+## Integration opportunities38+39+diagram.zip can depict harness structure, but it does not currently provide a standards-aware connector/cavity library, netlist validation, wire-gauge rules, terminal compatibility checks, or IEC, SAE, or IPC/WHMA conformance export. Those would be separate integration opportunities.