Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Generate Architecture DSL from requirements or refine existing DSL. Use for layered architectures (Module View) or application landscapes (Landscape View). Triggers on "architecture diagram", "layer diagram", "module view", "landscape view", "draw architecture".
version
4
Architecture DSL Tool
Purpose
AI Agents follow this skill to generate Architecture DSL definitions to:
Create layered architecture diagrams (Module View) from requirements
Create application landscape diagrams (Landscape View) from system descriptions
Refine or update existing Architecture DSL definitions
Important Notes
BLOCKING: Document MUST start with @startuml module-view or @startuml landscape-view and end with @enduml. The view keyword is NOT valid — only @startuml is recognized by the parser.
BLOCKING: Module cols within a layer MUST sum to 12. Violation produces invalid diagrams.
BLOCKING: component is the mandatory smallest unit. Every layer MUST contain at least one component. module is optional — use it only when grouping components adds clarity; otherwise place components directly in the layer.
BLOCKING: After generating or refining DSL, run python3 .github/skills/x-ipe-tool-architecture-dsl/scripts/lint_dsl.py {file} --format json to validate. Fix ALL errors before outputting.
CRITICAL: IPE natively renders Architecture DSL in markdown via architecture-dsl code blocks — no HTML files needed.
CRITICAL: Stereotyped components render at half width (0.5x) and 1.5x height. Use horizontal grid () for stereotype-only modules.
CRITICAL: Do NOT invent keywords. Only use keywords defined in the grammar (, , , , , , , , , , , , , , , ). Unknown keywords like , , are silently ignored by the parser and will cause missing content.
grid N x 1
layer
module
component
cols
rows
grid
align
gap
color
border-color
text-align
title
theme
direction
canvas
side-column
desc
description
note
Quick Syntax Reference
BLOCKING: Use this as a checklist when generating architecture-dsl code blocks.
Module View — Minimal Valid Structure:
@startuml module-view ← MUST start with this (NOT `view: module`)
title "Your Title" ← MUST use double quotes
theme "theme-default"
direction top-to-bottom
grid 12 x {total_rows} ← MUST declare at document level
layer "Layer Name" { ← MUST use double quotes
color "#hex"
border-color "#hex"
rows N
module "Module Name" { ← optional grouping; cols MUST sum to 12 per layer
cols N
rows N
grid CxR ← internal layout (cols x rows >= component count)
align center center
gap 8px
component "Name" { cols 1, rows 1 } ← MANDATORY smallest unit
}
}
@enduml ← MUST end with this
Architecture DSL is a domain-specific language for defining software architecture diagrams using a Bootstrap-inspired 12-column grid system. It supports two view types: Module View (layered decomposition) and Landscape View (application integration).
Key Concepts:
Module View - Layered architecture with layers, modules, and components arranged in a 12-column grid
Landscape View - Application integration diagrams with zones, apps, databases, and action flows
Grid System - 12-column layout where module cols must sum to 12 per layer
Stereotypes - Component decorators (<<file>>, <<folder>>, <<model>>, <<service>>, <<icon>>, <<api>>, <<db>>) that alter rendering size
IPE Markdown Embedding:
```architecture-dsl
@startuml module-view
title "Your Architecture"
...
@enduml
```
When to Use
triggers:-"architecture diagram"-"layer diagram"-"module view"-"landscape view"-"draw architecture"-"system architecture"-"application landscape"not_for:-"flowcharts -> use Mermaid"-"sequence diagrams -> use Mermaid"-"class/ER diagrams -> use Mermaid"
Input Parameters
input:operation:"generate_module_view | generate_landscape_view | refine_dsl"context:requirements:"text description or structured requirements"existing_dsl:"optional - current DSL to refine"options:theme:"theme name (default: theme-default)"canvas:"optional explicit dimensions (e.g., 1200px, 600px)"direction:"top-to-bottom | left-to-right (default: top-to-bottom)"
Definition of Ready
<definition_of_ready><checkpointrequired="true"><name>Requirements Available</name><verification>Text description, idea summary, or existing DSL provided as input</verification></checkpoint><checkpointrequired="true"><name>View Type Determined</name><verification>Either module-view (layered) or landscape-view (integration) identified</verification></checkpoint></definition_of_ready>
Operations
Operation: Generate Module View
When: Creating a layered architecture diagram from requirements.
<operationname="generate_module_view"><action>
1. Identify architectural layers (standard: Presentation, Business, Data)
2. Calculate document grid: cols = 12, rows = sum of all layer rows
3. Allocate module cols per layer (must sum to 12):
- 2 equal: 6 + 6
- 3 equal: 4 + 4 + 4
- 1 wide + 1 narrow: 8 + 4
- 1 wide + 2 narrow: 6 + 3 + 3
4. Plan component grid per module:
- 1-2 components: grid 2 x 1
- 3-4 components: grid 2 x 2
- 5-6 components: grid 3 x 2 or grid 2 x 3
- 7-9 components: grid 3 x 3
5. Apply layer colors (see references/layout-principles.md)
6. Use multi-line names with \n for long labels
7. Run lint: `python3 .github/skills/x-ipe-tool-architecture-dsl/scripts/lint_dsl.py {file} --format json`
8. Fix any errors reported by linter, re-run until valid
</action><constraints>
- BLOCKING: Document MUST start with `@startuml module-view` and end with `@enduml` — the `view` keyword is NOT valid syntax
- BLOCKING: Module cols MUST sum to 12 per layer
- BLOCKING: Every layer MUST have rows declaration
- BLOCKING: Every layer MUST contain at least one `component` (the smallest renderable unit)
- BLOCKING: Stereotype-only modules MUST use horizontal grid (grid N x 1)
- BLOCKING: Only use keywords defined in the grammar — unknown keywords (e.g. `desc`) are silently dropped
- Module is OPTIONAL — use only when grouping components adds clarity
- Document MUST have grid declaration at document level
</constraints><output>Complete Architecture DSL in architecture-dsl code block</output></operation>
Operation: Generate Landscape View
When: Creating an application integration diagram showing how systems connect.
<operationname="generate_landscape_view"><action>
1. Identify application zones/domains from requirements
2. Define apps with tech, platform, and status properties
3. Define databases and data stores
4. Create action flows between components using verb-based labels
5. Validate alias uniqueness and flow target existence
6. Run lint: `python3 .github/skills/x-ipe-tool-architecture-dsl/scripts/lint_dsl.py {file} --format json`
7. Fix any errors reported by linter, re-run until valid
</action><constraints>
- Flow labels MUST be action-focused (e.g., "Submit Order", not "order data")
- All aliases MUST be unique
- Flow sources and targets MUST reference defined aliases
- App status MUST be one of: healthy, warning, critical
</constraints><output>Complete Architecture DSL in architecture-dsl code block</output></operation>
Operation: Refine DSL
When: Updating or correcting an existing Architecture DSL definition.
<operationname="refine_dsl"><action>
1. Parse existing DSL and identify view type
2. Apply requested changes (add/remove/modify elements)
3. Recalculate grid dimensions if layers or modules changed
4. Verify module cols still sum to 12 per layer
5. Run lint: `python3 .github/skills/x-ipe-tool-architecture-dsl/scripts/lint_dsl.py {file} --format json`
6. Fix any errors reported by linter, re-run until valid
</action><constraints>
- BLOCKING: Preserve existing structure unless change is explicitly requested
- Recalculate document grid rows when layer rows change
</constraints><output>Updated Architecture DSL in architecture-dsl code block</output></operation>
Operation: Lint DSL
When: Validating generated or existing Architecture DSL against the grammar specification.
<operationname="lint"><action>
1. Save the DSL content to a temporary file (or pipe via stdin)
2. Run the bundled linter:
python3 .github/skills/x-ipe-tool-architecture-dsl/scripts/lint_dsl.py {file} --format json
3. Parse JSON output — check "valid" field
4. IF valid == false:
- Read errors[] array for specific violations (E001–E009)
- Fix each violation in the DSL
- Re-run linter until valid == true
5. IF valid == true:
- Warnings (W001) may remain — review but not blocking
</action><constraints>
- BLOCKING: Exit code 1 means errors — DSL must not be output until linter passes
- Script requires Python 3.10+ with no external dependencies
- Use --format json for machine-readable output
</constraints><output>Lint report (JSON) and corrected DSL if needed</output></operation>
CRITICAL: After generating or refining DSL, run the bundled linter for deterministic validation, then use a sub-agent for semantic checks the linter cannot cover.
<definition_of_done><lint_validation><tool>python3 .github/skills/x-ipe-tool-architecture-dsl/scripts/lint_dsl.py {file} --format json</tool><instructions>
1. Save generated DSL to a temp file
2. Run lint_dsl.py — if exit code 1, fix ALL errors and re-run
3. Only proceed to sub-agent validation after linter reports valid=true
</instructions></lint_validation><validation_sub_agent><role>architecture-dsl-validator</role><goal>Validate semantic aspects the linter cannot check (component grid capacity, stereotype layout, keyword correctness)</goal><model_hint>sonnet</model_hint><instructions>
1. Read the complete DSL grammar from references/grammar.md
2. Read the layout principles from references/layout-principles.md
3. Verify ONLY the semantic checkpoints below (linter already covers structural checks)
4. For each checkpoint: report PASS or FAIL with specific line references
5. IF any FAIL: return the list of violations with fix suggestions
6. The generating agent MUST fix all violations before output is accepted
</instructions></validation_sub_agent><checkpointrequired="true"><name>Lint Passes</name><verification>scripts/lint_dsl.py exits 0 (no E001–E009 errors). Run BEFORE sub-agent validation.</verification></checkpoint><checkpointrequired="true"><name>Structure Valid</name><verification>Document starts with `@startuml module-view` or `@startuml landscape-view` (NOT `view`), ends with `@enduml`, grid declared at document level</verification></checkpoint><checkpointrequired="true"><name>Grid Rules Satisfied</name><verification>Each layer has rows, each module has cols, module cols sum to 12 per layer</verification></checkpoint><checkpointrequired="true"><name>Components Present</name><verification>Every layer contains at least one `component` — component is the mandatory smallest renderable unit</verification></checkpoint><checkpointrequired="true"><name>Component Grid Valid</name><verification>Each module's internal grid dimensions can contain all declared components (cols x rows >= component count)</verification></checkpoint><checkpointrequired="true"><name>Stereotypes Correct</name><verification>Stereotype-only modules use horizontal grid (grid N x 1)</verification></checkpoint><checkpointrequired="true"><name>Aliases Valid</name><verification>All aliases unique, all flow targets reference defined aliases</verification></checkpoint><checkpointrequired="true"><name>Syntax Conforms to Grammar</name><verification>Only grammar-defined keywords used (no `desc`, `description`, `note`, `view` etc.). Every keyword, property, and nesting level matches references/grammar.md specification</verification></checkpoint><checkpointrequired="true"><name>Output Embedded</name><verification>DSL wrapped in architecture-dsl code block for IPE rendering</verification></checkpoint></definition_of_done>
Error Handling
Error
Cause
Resolution
Module cols sum != 12
Incorrect cols allocation
Adjust module cols to sum to 12
Missing rows in layer
Layer lacks rows declaration
Add rows N to every layer
Missing grid declaration
Document-level grid absent
Add grid 12 x N at document level
Undefined alias in flow
Flow references non-existent alias
Define alias with as keyword before using in flow
Duplicate alias
Same alias used for multiple elements
Use unique alias names
Invalid status value
Status not in allowed set
Use healthy, warning, or critical
Vertical stereotype layout
Stereotype module uses grid 1 x N
Change to horizontal grid N x 1
Templates
Module View Structure
@startuml module-view
title "Title"
theme "theme-default"
direction top-to-bottom
canvas 1200px, 600px
grid 12 x 6
layer "Name" {
color "#hex"
border-color "#hex"
rows 2
module "Name" {
cols 4
rows 2
grid 2 x 3
align center center
gap 8px
component "Name" { cols 1, rows 1 }
}
}
@enduml
Landscape View Structure
@startuml landscape-view
title "Title"
theme "theme-default"
zone "Zone Name" {
app "App" as alias {
tech: Technology
platform: Platform
status: healthy | warning | critical
}
database "DB" as alias
}
alias1 --> alias2 : "Action Description"
@enduml
