Skip to content

Commit 2dba3ad

Browse files
flemming-n-larsenflemming-n-larsen
committed
Merge branch 'architecture'
2 parents f20c0eb + 28440ed commit 2dba3ad

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

53 files changed

+12679
-1
lines changed

‎.github/skills/structurizr.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Structurizr C4 DSL to SVG Skill
2+
3+
Convert C4 DSL workspace blocks directly into SVG diagrams with zero setup required.
4+
5+
## 🛑 FOR AI AGENTS: MANDATORY INSTRUCTIONS
6+
7+
**STOP! Before doing ANYTHING, read [AI_INSTRUCTIONS.md](structurizr/AI_INSTRUCTIONS.md) completely!**
8+
9+
### Critical Rules:
10+
- ❌ **DO NOT** download Structurizr CLI (already in `tools/structurizr-cli/`)
11+
- ❌ **DO NOT** download PlantUML (already in `tools/plantuml.jar`)
12+
- ❌ **DO NOT** use Docker, wget, curl, or install any packages
13+
- ✅ **DO** use the bundled script: `bash .github/skills/structurizr/generate.sh '<dsl>'`
14+
- ✅ **DO** verify Java 11+ is available (only system requirement)
15+
16+
**If you try to download tools, you are ignoring these instructions!**
17+
18+
See [AI_INSTRUCTIONS.md](structurizr/AI_INSTRUCTIONS.md) for complete usage instructions.
19+
20+
## 🚀 How It Works
21+
22+
1. **Select C4 DSL text** containing a workspace block
23+
2. **Ask GitHub Copilot** to generate diagrams using this skill
24+
3. **Get SVG files** automatically saved to `/architecture/images/`
25+
26+
## ⚡ Features
27+
28+
- ✅ **Zero installation** - All tools bundled (only requires Java 11+)
29+
- ✅ **Multiple diagram types** - SystemContext, SystemLandscape, keys
30+
- ✅ **Smart naming** - Extracts from DSL or generates automatically
31+
- ✅ **Clean output** - SVG files only, no intermediate files
32+
33+
## 📋 Requirements
34+
35+
| Tool | Status |
36+
|------|--------|
37+
| **Java 11+** | Required |
38+
| **Structurizr CLI** | ✅ Bundled |
39+
| **PlantUML** | ✅ Bundled |
40+
41+
## 🎨 Supported Elements
42+
43+
- `person`, `softwareSystem`, `container`, `component`
44+
- Relationships with `->` notation
45+
- Automatic styling and layouts
46+
47+
This skill provides a **complete, zero-setup experience** for C4 diagram generation!

‎.github/skills/structurizr/.ai-context‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# AI Agent Quick Reference - Structurizr Skill
2+
3+
## ⚠️ CRITICAL INFORMATION
4+
5+
**ALL TOOLS ARE ALREADY EMBEDDED - DO NOT DOWNLOAD ANYTHING**
6+
7+
## Tool Locations (Relative to Skill Root)
8+
9+
- Structurizr CLI: `.tools/structurizr-cli/structurizr.sh`
10+
- PlantUML JAR: `.tools/plantuml.jar`
11+
- Generation Script: `generate.sh`
12+
13+
## Usage Pattern
14+
15+
```bash
16+
cd /path/to/project
17+
bash .github/skills/structurizr/generate.sh '<workspace_dsl_content>'
18+
```
19+
20+
## What the Script Does
21+
22+
1. Pre-checks: Verifies Java and bundled tools exist
23+
2. Processes: Uses bundled Structurizr CLI to generate PlantUML
24+
3. Converts: Uses bundled PlantUML JAR to generate SVG
25+
4. Outputs: Saves SVG files to /docs-internal/architecture/c4-views/images/
26+
27+
## What NOT to Do
28+
29+
- ❌ DO NOT download Structurizr CLI
30+
- ❌ DO NOT download PlantUML
31+
- ❌ DO NOT use Docker
32+
- ❌ DO NOT use npm packages
33+
- ❌ DO NOT install system packages
34+
35+
## What TO Do
36+
37+
- ✅ Use the generate.sh script
38+
- ✅ Trust the embedded tools
39+
- ✅ Verify Java is available (only requirement)
40+
41+
## Documentation Files
42+
43+
- README.md - Main skill documentation
44+
- AI_INSTRUCTIONS.md - Detailed AI agent instructions
45+
- tools/README.md - Bundled tools information
46+
- .ai-context (this file) - Quick reference
47+
48+
## Success Indicators
49+
50+
- Script outputs: "✅ All pre-checks passed!"
51+
- Script outputs: "📸 Created SVG: [filename]"
52+
- SVG files appear in /docs-internal/architecture/c4-views/images/

‎.github/skills/structurizr/AI_INSTRUCTIONS.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# AI Agent Instructions for Structurizr Skill
2+
3+
## 🛑 MANDATORY RULE FOR AI AGENTS
4+
5+
**BEFORE doing ANYTHING, read this entire file!**
6+
7+
### ⚠️ CRITICAL: Tools Are Downloaded On-Demand - DO NOT INSTALL MANUALLY
8+
9+
**STOP! DO NOT manually download, install, or fetch any tools.**
10+
11+
All required tools are **automatically downloaded** via `.tools/download-tools.sh`:
12+
13+
- **Structurizr CLI**: Downloaded to `.tools/structurizr-cli/`
14+
- **PlantUML JAR**: Downloaded to `.tools/plantuml.jar`
15+
- **Structurizr DSL JAR**: Symlinked at `.tools/structurizr-dsl.jar`
16+
17+
The `generate.sh` script will **automatically run the download script** if tools are missing.
18+
19+
**IF YOU TRY TO MANUALLY DOWNLOAD OR INSTALL TOOLS, YOU ARE DOING IT WRONG!**
20+
21+
## How to Generate SVG Diagrams
22+
23+
### Step 1: Use the Bundled Script
24+
25+
Call the generation script with the workspace DSL content:
26+
27+
```bash
28+
bash .github/skills/structurizr/generate.sh '<workspace_dsl_content>'
29+
```
30+
31+
### Step 2: Script Behavior
32+
33+
The `generate.sh` script:
34+
1. Performs pre-checks (Java availability, tool presence)
35+
2. **Automatically downloads tools if missing** using `.tools/download-tools.sh`
36+
3. Uses `.tools/structurizr-cli/structurizr.sh` for DSL processing
37+
4. Uses `.tools/plantuml.jar` for SVG generation
38+
5. Outputs SVG files to `/docs-internal/architecture/c4-views/images/`
39+
40+
### Step 3: Verify Output
41+
42+
The script will output:
43+
- Number of diagrams generated
44+
- SVG file names and locations
45+
- Markdown references for the generated diagrams
46+
47+
## Common Mistakes to Avoid
48+
49+
❌ **DO NOT** try to manually download Structurizr CLI
50+
❌ **DO NOT** try to manually download PlantUML JAR
51+
❌ **DO NOT** use Docker images
52+
❌ **DO NOT** install npm packages
53+
❌ **DO NOT** use `sudo` to install tools
54+
55+
✅ **DO** use the bundled `generate.sh` script (it handles downloads automatically)
56+
✅ **DO** verify Java is available (only system requirement)
57+
✅ **DO** trust the pre-checks in the script
58+
✅ **DO** let the script download tools on first run
59+
60+
## Example Usage
61+
62+
```bash
63+
cd /path/to/project
64+
bash .github/skills/structurizr/generate.sh 'workspace "Example" {
65+
model {
66+
user = person "User"
67+
system = softwareSystem "System"
68+
user -> system "uses"
69+
}
70+
}'
71+
```
72+
73+
## Tool Locations Reference
74+
75+
Tools are downloaded on-demand to `.tools/` at the project root:
76+
77+
- **Download script**: `.tools/download-tools.sh` ⚙️ VERSION CONTROLLED
78+
- **Generation script**: `.github/skills/structurizr/generate.sh` ⚙️ VERSION CONTROLLED
79+
- **Structurizr CLI**: `.tools/structurizr-cli/` 📦 DOWNLOADED (gitignored)
80+
- **PlantUML JAR**: `.tools/plantuml.jar` 📦 DOWNLOADED (gitignored)
81+
- **Structurizr DSL JAR**: `.tools/structurizr-dsl.jar` 🔗 SYMLINK (created by download script)
82+
- **Output directory**: `docs-internal/architecture/c4-views/images/` 📁 VERSION CONTROLLED
83+
84+
See `.tools/README.md` for detailed tool documentation.
85+
86+
## Pre-Check Validation
87+
88+
The script automatically checks:
89+
1. ✅ Java 11+ is installed and available
90+
2. ✅ Structurizr CLI exists (downloads if missing)
91+
3. ✅ PlantUML JAR exists (downloads if missing)
92+
93+
If Java is missing, the script will report the issue and exit. All other tools are downloaded automatically.
94+
95+
## Summary
96+
97+
**The skill is self-contained and ready to use. Just call the generate.sh script with your DSL content - it will automatically download any missing tools on first run.**

‎.github/skills/structurizr/README.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Structurizr C4 DSL Skill for GitHub Copilot
2+
3+
Convert C4 DSL workspace blocks to SVG diagrams automatically.
4+
5+
## 🤖 For AI Agents
6+
7+
**IMPORTANT**: This skill uses tools **bundled at the project root** in the `.tools/` directory:
8+
- **Structurizr CLI**: `.tools/structurizr-cli/structurizr.sh`
9+
- **PlantUML JAR**: `.tools/plantuml.jar`
10+
11+
**DO NOT attempt to download or install these tools** - they are already available and ready to use.
12+
13+
📖 **See [AI_INSTRUCTIONS.md](AI_INSTRUCTIONS.md) for detailed AI agent guidance.**
14+
15+
### How to Use from AI
16+
17+
1. Call the generation script: `bash .github/skills/structurizr/generate.sh '<workspace_dsl_content>'`
18+
2. The script automatically uses the embedded tools in the `.tools/` directory
19+
3. SVG files are generated in `/docs-internal/architecture/c4-views/images/`
20+
21+
The script performs pre-checks to verify Java availability and confirms the embedded tools are present before processing.
22+
23+
## 🚀 Usage
24+
25+
1. **Select C4 DSL text** containing a workspace block:
26+
```
27+
workspace {
28+
name "Tank Royale"
29+
model {
30+
user = person "Bot Developer" "Writes bot AI code"
31+
server = softwareSystem "Game Server" "Hosts battles and enforces rules"
32+
user -> server "connects via WebSocket"
33+
}
34+
}
35+
```
36+
37+
2. **Ask GitHub Copilot**: *"Use the Structurizr skill to generate diagrams"*
38+
39+
3. **Get SVG files** in `/docs-internal/architecture/c4-views/images/` with simplified, predictable names:
40+
- `system-context.svg` - System context diagram
41+
- `container.svg` - Container diagram
42+
- `component-<name>.svg` - Component diagrams (e.g., `component-GameServer.svg`)
43+
- `deployment.svg` - Deployment diagram
44+
- `system-landscape.svg` - System landscape diagram
45+
46+
## ⚡ Features
47+
48+
- ✅ **Zero installation** - All tools bundled (only requires Java 11+)
49+
- ✅ **Multiple views** - SystemContext, SystemLandscape, Container, Component, Deployment
50+
- ✅ **Version control friendly** - Predictable file names without hash-based uniqueness
51+
- ✅ **Clean naming** - Simple names like `system-context.svg`, `container.svg`, `component-<name>.svg`
52+
- ✅ **Clean output** - SVG files only, no intermediate files
53+
- ✅ **User customizable** - Simple names allow users to rename files as needed
54+
55+
## 🎯 Requirements
56+
57+
| Tool | Status | Location |
58+
|------|--------|----------|
59+
| **Java 11+** | Required | System installation |
60+
| **Structurizr CLI** | ✅ Bundled | `.tools/structurizr-cli/` |
61+
| **PlantUML** | ✅ Bundled | `.tools/plantuml.jar` |
62+
63+
## 🎨 Supported C4 Elements
64+
65+
- `person` - People/actors
66+
- `softwareSystem` - Software systems
67+
- `container` - Containers within systems
68+
- `component` - Components within containers
69+
- Relationships with `->` notation
70+
- Automatic styling and layouts
71+
72+
## 📝 Example Test
73+
74+
Test the skill by selecting this workspace block and invoking the skill:
75+
76+
```
77+
workspace {
78+
name "Test System"
79+
model {
80+
user = person "User" "System user"
81+
system = softwareSystem "Test System" "A test system"
82+
user -> system "uses"
83+
}
84+
}
85+
```
86+
87+
**Result**: Clean SVG files ready for documentation! 🎉

0 commit comments

Comments
 (0)