x-ipe-tool-architecture-dsl - SKILL.md Agent Skill

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.0

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.</verification>
  </checkpoint>
  <checkpoint required="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>
  <checkpoint required="true">
    <name>Grid Rules Satisfied</name>
    <verification>Each layer has rows, each module has cols, module cols sum to 12 per layer</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Components Present</name>
    <verification>Every layer contains at least one `component` — component is the mandatory smallest renderable unit</verification>
  </checkpoint>
  <checkpoint required="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>
  <checkpoint required="true">
    <name>Stereotypes Correct</name>
    <verification>Stereotype-only modules use horizontal grid (grid N x 1)</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Aliases Valid</name>
    <verification>All aliases unique, all flow targets reference defined aliases</verification>
  </checkpoint>
  <checkpoint required="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>
  <checkpoint required="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

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

references/grammar.md - Complete DSL grammar specification
references/layout-principles.md - Grid layout guidelines and color suggestions
examples/module-view-v2.dsl - Module View example
examples/landscape-view.dsl - Landscape View example