🌱 ZenUML Diagramly Kit

Transform user intentions into visual diagrams automatically.

A toolkit to help transform user requirements and intentions directly into visual diagrams and system representations.

This Project is based on Spec-Kit (https://github.com/github/spec-kit), adapted for ZenUML Diagramly Kit Licensed under MIT License

---

Table of Contents

• 🤔 What is User Intention to Diagram Generation?
• ⚡ Get started
• 🤖 Supported AI Agents
• 🔧 Diagramly CLI Reference
• 📚 Core philosophy
• 🌟 Use cases
• 🎯 Goals
• 🔧 Prerequisites
• 📖 Learn more
• 📋 Detailed process
• 📄 License

🤔 What is User Intention to Diagram Generation?

User Intention to Diagram Generation flips the script on traditional diagram creation. For decades, creating diagrams required manual work - users had to draw boxes, connect lines, and format layouts. User Intention to Diagram Generation changes this: user requirements and intentions become visual representations, automatically generating diagrams that match the user's intent rather than requiring manual creation.

⚡ Get started

1. Install Diagramly

Choose your preferred installation method:

Option 1: Persistent Installation (Recommended)

Install once and use everywhere:

uv tool install diagramly-cli --from git+https://github.com/zenuml/diagramly-kit.git

Then use the tool directly:

diagramly init <PROJECT_NAME>
diagramly check

To upgrade diagramly run:

uv tool install diagramly-cli --force --from git+https://github.com/zenuml/diagramly-kit.git

Option 2: One-time Usage

Run directly without installing:

uvx --from git+https://github.com/zenuml/diagramly-kit.git diagramly init <PROJECT_NAME>

Benefits of persistent installation:

• Tool stays installed and available in PATH
• No need to create shell aliases
• Better tool management with uv tool list, uv tool upgrade, uv tool uninstall
• Cleaner shell configuration

2. Initialize your project

Use the diagramly init command to set up your diagram generation environment:

diagramly init my-diagram-project

3. Generate diagrams from your intentions

Use the /diagramlykit.diagram command to describe what you want to visualize. Focus on the what you want to see.

/diagramlykit.diagram Generate a system architecture diagram showing the relationship between user, web application, database, and external services. The web application should use React with a Node.js backend.

4. Generate other diagrams as needed

Use /diagramlykit.diagram with different types of diagrams:

/diagramlykit.diagram Create a UML class diagram for the user and order management system with classes User, Order, and Product.
/diagramlykit.diagram Generate a flowchart showing the user registration process from sign up to account activation.

For detailed step-by-step instructions, see our comprehensive guide in this README.

🤖 Supported AI Agents

Agent	Support	Notes
Claude Code	✅
GitHub Copilot	✅
Gemini CLI	✅
Cursor	✅
Qwen Code	✅
opencode	✅
Windsurf	✅
Kilo Code	✅
Auggie CLI	✅
CodeBuddy	✅
Roo Code	✅
Codex CLI	✅
Amazon Q Developer CLI	⚠️	Amazon Q Developer CLI does not support custom arguments for slash commands.

🔧 Diagramly CLI Reference

The diagramly command supports the following options:

Commands

Command	Description
init	Initialize a new Diagramly project from the latest template
check	Check for installed tools (git, claude, gemini, code/code-insiders, cursor-agent, windsurf, qwen, opencode, codex)

diagramly init Arguments & Options

Argument/Option	Type	Description
<project-name>	Argument	Name for your new project directory (optional if using --here, or use . for current directory)
--ai	Option	AI assistant to use: claude, gemini, copilot, cursor, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, or q
--script	Option	Script variant to use: sh (bash/zsh) or ps (PowerShell)
--ignore-agent-tools	Flag	Skip checks for AI agent tools like Claude Code
--no-git	Flag	Skip git repository initialization
--here	Flag	Initialize project in the current directory instead of creating a new one
--force	Flag	Force merge/overwrite when initializing in current directory (skip confirmation)
--skip-tls	Flag	Skip SSL/TLS verification (not recommended)
--debug	Flag	Enable detailed debug output for troubleshooting
--github-token	Option	GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable)

Examples

# Basic project initialization
diagramly init my-project

# Initialize with specific AI assistant
diagramly init my-project --ai claude

# Initialize with Cursor support
diagramly init my-project --ai cursor-agent

# Initialize with Windsurf support
diagramly init my-project --ai windsurf

# Initialize with PowerShell scripts (Windows/cross-platform)
diagramly init my-project --ai copilot --script ps

# Initialize in current directory
diagramly init . --ai copilot
# or use the --here flag
diagramly init --here --ai copilot

# Force merge into current (non-empty) directory without confirmation
diagramly init . --force --ai copilot
# or 
diagramly init --here --force --ai copilot

# Skip git initialization
diagramly init my-project --ai gemini --no-git

# Enable debug output for troubleshooting
diagramly init my-project --ai claude --debug

# Use GitHub token for API requests (helpful for corporate environments)
diagramly init my-project --ai claude --github-token ghp_your_token_here

# Check system requirements
diagramly check

Available Slash Commands

After running diagramly init, your AI coding agent will have access to these slash commands for diagram generation:

Core Commands

Essential commands for the User Intention to Diagram Generation workflow:

Command	Description
/diagramlykit.diagram	Generate diagrams from user requirements (Zenuml, Mermaid, PlantUML, Graphviz, etc.)

📚 Core philosophy

User Intention to Diagram Generation is a structured process that emphasizes:

• Intent-driven visualization where user requirements define the "what" before the "how"
• Rich diagram generation using AI to transform natural language into visual representations
• Multi-step refinement rather than one-shot diagram creation from prompts
• Heavy reliance on advanced AI model capabilities for diagram interpretation and generation

🌟 Use cases

Use Case	Focus	Key Activities
System Architecture	Visualize system components	Document system architecture Generate component diagrams Create deployment diagrams Visualize service interactions
Process Documentation	Flow and procedure visualization	Create workflow diagrams Document business processes Generate sequence diagrams
Data Modeling	Data structure visualization	Create entity-relationship diagrams Generate class diagrams from requirements Visualize data flows

🎯 Goals

Our goals focus on:

Visualization simplicity

• Transform user requirements into visual diagrams automatically
• Support diverse diagram types (system architecture, flowcharts, UML, data models)

User experience

• Make diagram creation accessible to non-technical users
• Generate high-quality diagrams from natural language descriptions

AI capabilities

• Leverage advanced AI for diagram interpretation and generation
• Support iterative refinement of generated diagrams

🔧 Prerequisites

• Linux/macOS (or WSL2 on Windows)
• AI coding agent: Claude Code, GitHub Copilot, Gemini CLI, Cursor, Qwen CLI, opencode, Codex CLI, Windsurf, or Amazon Q Developer CLI
• uv for package management
• Python 3.11+
• Git

If you encounter issues with an agent, please open an issue so we can refine the integration.

📖 Learn more

• Complete User Intention to Diagram Generation Methodology - Deep dive into the full process
• Detailed Walkthrough - Step-by-step implementation guide

---

📋 Detailed process

Click to expand the detailed step-by-step walkthrough

You can use the Diagramly CLI to bootstrap your project, which will bring in the required artifacts in your environment. Run:

diagramly init <project_name>

Or initialize in the current directory:

diagramly init .
# or use the --here flag
diagramly init --here
# Skip confirmation when the directory already has files
diagramly init . --force
# or
diagramly init --here --force

Diagramly CLI bootstrapping a new project in the terminal

You will be prompted to select the AI agent you are using. You can also proactively specify it directly in the terminal:

diagramly init <project_name> --ai claude
diagramly init <project_name> --ai gemini
diagramly init <project_name> --ai copilot

# Or in current directory:
diagramly init . --ai claude
diagramly init . --ai codex

# or use --here flag
diagramly init --here --ai claude
diagramly init --here --ai codex

# Force merge into a non-empty current directory
diagramly init . --force --ai claude

# or
diagramly init --here --force --ai claude

The CLI will check if you have Claude Code, Gemini CLI, Cursor CLI, Qwen CLI, opencode, Codex CLI, or Amazon Q Developer CLI installed. If you do not, or you prefer to get the templates without checking for the right tools, use --ignore-agent-tools with your command:

diagramly init <project_name> --ai claude --ignore-agent-tools

STEP 1: Initialize your diagram environment

Go to the project folder and run your AI agent. In our example, we're using claude.

Bootstrapping Claude Code environment

You will know that things are configured correctly if you see the /diagramlykit.diagram command available.

The environment will be set up with the necessary templates and configurations for diagram generation.

STEP 2: Generate your first diagram

With your environment established, you can now generate diagrams. Use the /diagramlykit.diagram command and then provide the description of what you want to visualize.

[!IMPORTANT] Be as explicit as possible about what you want to see in the diagram and why. Do not focus on the diagram format at this point.

An example prompt:

Generate a system architecture diagram showing the relationship between users, web application, database, and external services. The web application should use React with a Node.js backend, and the database should be PostgreSQL. The external services include a payment gateway and email service.

After this prompt is entered, you should see your AI agent generate the appropriate diagram code, visualize it, and provide you with the diagram in multiple formats.

---

📄 License

This project is licensed under the terms of the MIT open source license. Please refer to the LICENSE file for the full terms.