What Is the First-Run Style Guide Gate and How Does It Enforce Customization

The first-run style guide gate is a safeguard that blocks diagram generation when the installed style-guide.md has not been customized, forcing users to create a deliberate style profile before any output is produced.

This mechanism ensures that every diagram generated by cathrynlavery/diagram-design reflects intentional design decisions rather than accidental defaults. The gate lives in the project's core definition and acts as a quality checkpoint during the initialization workflow.

How the First-Run Gate Detects Pristine Style Guides

The gate evaluates two specific conditions to determine whether a style guide has been customized. Both must be true for the gate to trigger:

1. No active profile header — the working copy of style-guide.md lacks a leading profile header block that identifies a custom configuration.
2. All semantic-role values and typography tokens match shipped defaults — the file's content is byte-for-byte identical to the pristine version distributed with the plugin.

When these conditions converge, the generation pipeline executes the first-time setup gate documented in skills/diagram-design/SKILL.md. This interrupts normal processing and launches an onboarding flow that requires profile creation.

Where the Gate Logic Is Implemented

The gate's behavior is distributed across three critical files in the repository:

File Path	Purpose
skills/diagram-design/SKILL.md	Contains the first-time setup gate implementation invoked on pristine style guides
skills/diagram-design/references/profiles.md	Defines resolution rules including the "skip the first-run gate" clause for the built-in default profile
skills/diagram-design/references/style-guide.md	The shipped default style guide used as the comparison baseline

The logic operates at the intersection of these definitions. The SKILL.md file houses the actual gate execution, while profiles.md establishes when the gate can be legally bypassed.

Bypassing the Gate with Explicit Profile Selection

Users can skip the first-run style guide gate entirely by creating a project marker file that explicitly selects the built-in default profile. According to the resolution rules in profiles.md (lines 79–82), when <project-root>/.diagram-design contains profile: default, the gate is skipped and generation proceeds with the unmodified default style guide.

# Example: .diagram-design marker file that bypasses the gate

profile: default

This explicit opt-out preserves the gate's enforcement for typical workflows while providing an escape hatch for scenarios requiring rapid prototyping or strict default adherence.

Gate Execution in Practice

The enforcement mechanism follows a straightforward decision tree. Pseudocode illustrating the core logic:

# Core first-run gate logic as implemented in the skill definition

if not style_guide_has_header() and style_guide_is_pristine():
    # Trigger onboarding defined in SKILL.md

    run_first_time_setup_gate()
else:
    # Normal generation path

    generate_diagram()

When the gate triggers, users must either create a new profile or run a structural check. This ensures that subsequent invocations encounter a customized style guide with a valid header block.

What a Customized Style Guide Header Looks Like

Adding a profile header transforms the style guide from pristine to customized, permanently satisfying the gate's conditions. A valid header uses HTML comment syntax with structured metadata:

<!-- diagram-design-profile
name: Acme Corp
slug: acme
source-url: https://acme.example.com
created: 2026-08-14
updated: 2026-08-14
notes: Custom brand colours
-->

# Style Guide

...

Once this header exists, style_guide_has_header() returns true and the gate yields to normal generation regardless of content modifications elsewhere in the file.

Enforcement Guarantees and Design Philosophy

The first-run style guide gate enforces customization through blocking rather than warning. Unlike optional linting or post-hoc validation, this gate operates as a hard dependency in the generation pipeline. No diagram output is produced until the user demonstrates intent by creating or selecting a profile.

This design choice reflects the project's philosophy that visual consistency requires deliberate configuration. The default style guide serves as a template and teaching tool, not a production-ready fallback.

Summary

• The first-run style guide gate runs during initial diagram generation to detect untouched style-guide.md files.
• It triggers when no profile header exists and all values match the shipped defaults.
• The gate is defined in SKILL.md and documented in profiles.md with bypass rules for explicit default profile selection.
• Users bypass enforcement by adding a profile header or creating a .diagram-design marker with profile: default.
• The mechanism ensures every production diagram derives from intentional style configuration rather than unexamined defaults.

Frequently Asked Questions

How do I know if the first-run gate has triggered?

The gate produces an explicit onboarding prompt that interrupts generation. If you see a message requesting profile creation or structural check rather than diagram output, the gate has activated. Successful generation without this interruption indicates either prior customization or explicit default profile selection.

Can I permanently disable the first-run gate?

Not globally. The gate is intrinsic to the skill's initialization logic. You can only bypass it per-project by either customizing the style guide with a profile header or explicitly selecting profile: default in your .diagram-design marker file. These bypasses must be reestablished for each new project root.

What happens if I edit the style guide without adding a profile header?

Partial modifications without a header will satisfy condition 2 (no longer pristine) but fail condition 1 (still no header). In this intermediate state, behavior depends on version-specific implementation details. Best practice is to add the profile header immediately when beginning customization to ensure predictable gate resolution.

Where is the pristine default style guide located?

The comparison baseline lives at skills/diagram-design/references/style-guide.md in the repository. This file ships with the plugin and serves as the reference against which your working copy is evaluated. Never modify this reference file directly; create your customized profile instead.

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