How the Client Profile Marker Resolution System Works in Diagram Design

Diagram Design resolves the effective style guide for every diagram generation by first inspecting a project-root marker file named .diagram-design, which isolates client profiles so that parallel workspaces never clash on a shared style-guide.md.

The cathrynlavery/diagram-design repository implements a robust client profile marker resolution system that keeps client-specific style guides isolated across parallel workspaces. This marker-first architecture ensures that the installed style-guide.md is never overwritten when a marker is present, preserving plugin files across updates while allowing precise control over which profile governs each project.

Marker-First Resolution Flow

Inspecting the Project Marker

When Diagram Design initiates diagram generation, it first checks for the existence of a marker file at <project-root>/.diagram-design. This file acts as a trusted pointer that determines which client profile to load. According to the skill definition in skills/diagram-design/SKILL.md (lines 23-24), the system reads this marker as untrusted data that must match a strict grammar before proceeding.

The marker file must contain exactly:

profile: <slug>

Where <slug> identifies the specific client profile to load.

Validating the Profile Slug

The extracted slug undergoes strict validation against a regular expression defined in skills/diagram-design/references/profiles.md (lines 71-78). The slug must match the pattern:

[a-z0-9][a-z0-9-]{0,63}

This constraint ensures lowercase alphanumeric characters and hyphens only, preventing filesystem conflicts and ensuring cross-platform compatibility. Invalid slugs trigger an immediate fallback to marker-less resolution.

Loading from the Profile Library

Once validated, Diagram Design loads the corresponding profile directly from the user's home-directory library at:

~/.diagram-design/profiles/<slug>.md

This direct read operation bypasses any copy-over of the installed style-guide.md, ensuring that plugin updates never overwrite client-specific customizations. As documented in ADR 0006 (lines 65-84), this approach maintains strict isolation between parallel workspaces by keeping profile resolution external to the plugin installation directory.

Fallback Resolution and Edge Cases

The Default Profile Shortcut

The marker may specify profile: default as a special case. When detected, the system loads the built-in default.md profile and skips the onboarding gate entirely. This provides a fast path for projects that require standard styling without custom overrides.

Marker-Less Resolution

If the .diagram-design marker is absent, malformed, or references a non-existent profile, the system executes marker-less resolution. It reads the installed references/style-guide.md, scans for a leading profile header, and determines whether the guide represents a custom-unsaved configuration or the shipped default. This fallback mechanism ensures backward compatibility for legacy projects while encouraging migration to the marker-based system.

Schema Validation and Back-Fill

After loading any profile—whether via marker or fallback—Diagram Design performs a current-schema structural check as defined in the profiles reference. This validation ensures the profile contains all required semantic-role rows and typography entries defined by the current schema version.

Missing rows are automatically back-filled from the pristine shipped guide. The system then offers the user an update <slug> command to persist the repaired snapshot, ensuring profiles remain forward-compatible as the schema evolves.

CLI Workflow Examples

The following commands demonstrate the complete marker-based workflow:

# 1. Save the current style guide as a new profile

diagram-design profile save acme

# => creates ~/.diagram-design/profiles/acme.md and offers to write the marker

# 2. Add a marker to the project so it always uses the saved profile

echo "profile: acme" > .diagram-design

# (or run the command that writes the marker for you)

diagram-design profile load acme   # writes the marker if you approve

# 3. Generate a diagram – the system will resolve the marker first

diagram-design draw flowchart my-diagram.yml

# → reads ~/.diagram-design/profiles/acme.md directly; no copy-over occurs

Summary

• Marker isolation: The .diagram-design file at the project root acts as the single source of truth for profile selection, preventing workspace collisions.
• Validated slugs: Profile identifiers must match the [a-z0-9][a-z0-9-]{0,63} pattern defined in profiles.md (lines 71-78).
• Direct library reads: Valid markers trigger direct reads from ~/.diagram-design/profiles/<slug>.md, never touching the installed style-guide.md.
• Graceful degradation: Missing or invalid markers fall back to scanning the installed style guide per the logic in SKILL.md (lines 23-24).
• Schema integrity: Automatic back-filling from the shipped guide ensures profiles remain complete and upgrade-safe.

Frequently Asked Questions

What happens if the .diagram-design marker file is missing?

The system falls back to marker-less resolution, reading the installed references/style-guide.md to determine if a custom profile header exists. If no header is found, it treats the guide as either a custom-unsaved configuration or the default shipped version. This ensures existing projects continue to function while encouraging adoption of the marker system.

How does the system validate profile slugs?

Slugs are validated against the regular expression [a-z0-9][a-z0-9-]{0,63} as defined in skills/diagram-design/references/profiles.md (lines 71-78). The pattern requires lowercase alphanumeric starting characters, permits hyphens, and limits length to 64 characters to ensure filesystem safety and parsing reliability.

Where are client profiles stored on disk?

Client profiles reside in the user's home directory at ~/.diagram-design/profiles/<slug>.md. This location separates client customizations from the plugin installation, ensuring that updates to Diagram Design never overwrite saved profiles and that profiles remain available across multiple projects via marker references.

Why does the system use marker-first resolution instead of modifying style-guide.md?

According to ADR 0006 (lines 65-84), marker-first resolution keeps parallel workspaces isolated by externalizing profile selection from the plugin files. This architecture prevents the installed style-guide.md from being overwritten when switching between client contexts, enables version control of profile assignments per project, and allows the plugin to update its default guides without risking client data loss.

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