| name | x-ipe-tool-architecture-dsl |
| description | 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 (grid N x 1) for stereotype-only modules.
CRITICAL: Do NOT invent keywords. Only use keywords defined in the grammar (layer, module, component, cols, rows, grid, align, gap, color, border-color, text-align, title, theme, direction, canvas, side-column). Unknown keywords like desc, description, note are silently ignored by the parser and will cause missing content.
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
Valid keywords: layer, module, component, cols, rows, grid, align, gap, color, border-color, text-align, title, theme, direction, canvas, side-column
INVALID keywords (silently ignored — NEVER use): view, desc, description, tech, note, [Name]
About
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>
<checkpoint required="true">
<name>Requirements Available</name>
<verification>Text description, idea summary, or existing DSL provided as input</verification>
</checkpoint>
<checkpoint required="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.
<operation name="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.
<operation name="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.
<operation name="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.
<operation name="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>
Output Result
operation_output:
success: true | false
result:
view_type: "module-view | landscape-view"
dsl: "complete DSL content in architecture-dsl code block"
validation: "all checklist items passed"
lint_report: "JSON lint report from scripts/lint_dsl.py (when lint operation used)"
errors: []
Definition of Done
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>
<checkpoint required="true">
<name>Lint Passes</name>
<verification>scripts/lint_dsl.py exits 0 (no E001–E009 errors). Run BEFORE sub-agent validation.
Structure Valid
Document starts with `@startuml module-view` or `@startuml landscape-view` (NOT `view`), ends with `@enduml`, grid declared at document level
Grid Rules Satisfied
Each layer has rows, each module has cols, module cols sum to 12 per layer
Components Present
Every layer contains at least one `component` — component is the mandatory smallest renderable unit
Component Grid Valid
Each module's internal grid dimensions can contain all declared components (cols x rows >= component count)
Stereotypes Correct
Stereotype-only modules use horizontal grid (grid N x 1)
Aliases Valid
All aliases unique, all flow targets reference defined aliases
Syntax Conforms to Grammar
Only grammar-defined keywords used (no `desc`, `description`, `note`, `view` etc.). Every keyword, property, and nesting level matches references/grammar.md specification
Output Embedded
DSL wrapped in architecture-dsl code block for IPE rendering
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
Translation Patterns
| Input | Output |
|---|
| "3 layers: X, Y, Z" | 3 layers with rows 2 each, grid 12 x 6 |
| "split into 3 parts" | 3 modules with cols 4 |
| "one wide, one narrow" | cols 8 + cols 4 |
| "stack vertically" | grid 1 x N |
| "X connects to Y" | x --> y : "Action" |
Examples
