How the Profile Marker System Works with .diagram-design Files

The .diagram-design profile marker system uses a strict two-step resolution process to validate a profile: <slug> declaration and load the corresponding style guide from ~/.diagram-design/profiles/<slug>.md, ensuring workspace isolation without overwriting installed defaults.

The cathrynlavery/diagram-design repository implements a robust profile marker system that enables project-specific style guide selection through a simple root-level configuration file. This mechanism allows multiple client projects to coexist with distinct visual standards while treating marker content as untrusted data to maintain strict security boundaries.

Marker File Location and Grammar

The .diagram-design file must reside in the project root and follows an exact grammatical specification defined in skills/diagram-design/references/profiles.md (lines 71-78). The engine accepts only content matching the pattern profile: <slug> with optional horizontal whitespace and a trailing newline. Any deviation from this strict syntax causes immediate rejection of the marker as untrusted data.

The Two-Step Resolution Process

According to the source code in skills/diagram-design/references/profiles.md, Diagram Design follows a strict validation pipeline:

Step 1: Grammar Inspection

When generation starts, the engine reads the .diagram-design file as untrusted data. It validates that the entire content matches the exact grammar profile: <slug> (allowing optional horizontal whitespace and a trailing newline) as specified in lines 71-78 of the profiles reference document.

Step 2: Slug Validation and Profile Loading

The extracted <slug> must satisfy the regex [a-z0-9][a-z0-9-]{0,63} defined in lines 17-22 of skills/diagram-design/references/profiles.md. Upon validation, the system directly reads the corresponding profile from ~/.diagram-design/profiles/<slug>.md (lines 9-13), making it the effective style guide without modifying the installed references/style-guide.md.

Profile Resolution Scenarios

The outcome depends on marker content validity and profile existence:

Default Profile Selection

When the marker contains profile: default, the system loads the built-in default profile (default.md) directly. No copy-over of the shipped style guide occurs in this path (profiles.md lines 79-81).

Loading Custom Client Profiles

For a valid slug with an existing profile file, Diagram Design reads the profile and runs a structural check (as detailed in the "Current-schema structural check" section of skills/diagram-design/references/profiles.md). The diagram generation then proceeds using that client-specific style guide.

Handling Missing or Invalid Markers

If the profile file is missing for a valid slug, the user receives a notification listing available profiles, and the marker is ignored for the current run. For invalid grammar or slugs, the engine displays a one-line explanation and falls back to marker-less resolution, reading the installed style-guide.md or a header inside it (profiles.md lines 80-82).

Security and Workspace Isolation

The profile marker system treats the .diagram-design file as untrusted data to prevent security vulnerabilities. Because profiles are selected by reference rather than copied into the repository, several parallel client projects can coexist without clobbering each other's style guides. This design ensures that marker-selected profiles only influence the in-memory guide used for the current generation, leaving the installed style-guide.md intact.

CLI Implementation and Usage

The commands/profile.md file implements CLI commands for manipulating the marker. To set a profile via command line:

# Using the CLI to set a marker

$ diagram-design profile set acme-company

# The command writes the exact line `profile: acme-company` into .diagram-design

The resulting marker file contains only the validated declaration:

# Example .diagram-design marker (project root)

profile: acme-company

The resolution logic follows this pattern (simplified from the source):

def resolve_style_guide(project_root):
    marker_path = os.path.join(project_root, ".diagram-design")
    if os.path.isfile(marker_path):
        content = read_file(marker_path).strip()
        if re.fullmatch(r"profile:\s*([a-z0-9][a-z0-9-]{0,63})", content):
            slug = re.search(r"[a-z0-9][a-z0-9-]{0,63}", content).group(0)
            profile_path = os.path.expanduser(f"~/.diagram-design/profiles/{slug}.md")
            if os.path.isfile(profile_path):
                return read_profile(profile_path)          # → effective guide

    # Fallback to installed style‑guide.md …

Summary

• The .diagram-design file acts as a root-level marker using strict profile: <slug> grammar to reference client-specific style guides.
• Resolution requires validating the grammar against skills/diagram-design/references/profiles.md specifications (lines 71-78) and the slug against regex [a-z0-9][a-z0-9-]{0,63} (lines 17-22).
• Valid profiles load from ~/.diagram-design/profiles/<slug>.md without overwriting the installed style-guide.md.
• Invalid markers or missing profiles trigger fallback behavior to default resolution, treating the marker as untrusted data to ensure security.
• The CLI command diagram-design profile set <slug> writes the exact required syntax to the marker file.

Frequently Asked Questions

What happens if the .diagram-design file contains invalid content?

The engine treats the marker as untrusted data and ignores it entirely. It displays a one-line explanation and falls back to marker-less resolution, reading the installed style-guide.md or header content instead. This strict validation prevents malicious content from executing or being interpreted as filesystem paths.

Where does Diagram Design look for profile files after validating the marker?

After validating the slug, the system reads the profile directly from ~/.diagram-design/profiles/<slug>.md as defined in the profile library specification. This path in the user's home directory contains the actual profile files with full style guide bodies and leading metadata comments.

Can I use the default profile without creating a custom .diagram-design file?

Yes. If you create a marker with profile: default, the system loads the built-in default profile directly without copying over the shipped style guide. However, if no marker exists, the engine automatically falls back to the installed style-guide.md, achieving the same visual result without requiring a marker file.

Why doesn't the marker system copy profiles into my project repository?

The reference-based design isolates workspaces by allowing multiple projects to share profiles from ~/.diagram-design/profiles/ without duplication. This prevents repository bloat and ensures that updates to a client profile immediately affect all projects using that marker, while maintaining strict boundaries between different client style guides.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}