Diagram Design profiles.md Contract: Storage, Markers, and Recovery

The profiles.md contract defines the complete specification for profile storage locations, project marker files, and recovery of the built-in default profile within the Diagram Design skill.

The profiles.md file in the cathrynlavery/diagram-design repository serves as the authoritative blueprint for how the skill manages user profiles across projects. This contract governs hard-coded file paths, metadata schema validation, and the deterministic behavior of CLI verbs like save, load, and reset. Understanding these rules ensures safe profile persistence and reliable project-specific style guide resolution.

Profile Storage Locations and File Paths

The contract mandates four distinct storage concepts with immutable paths that are never altered by updates.

Concept	Path (expanded)	Purpose
Profile library	~/.diagram-design/profiles/	Holds one Markdown file per named profile (<slug>.md).
Profile file	~/.diagram-design/profiles/<slug>.md	The persistent copy of a client’s style guide plus a metadata header.
Working copy	<install-dir>/references/style-guide.md	The active file the skill reads/writes when no project marker exists.
Project marker	<project-root>/.diagram-design	A tiny text file that binds a project to a specific profile (profile: <slug>).

The contract insists that profiles must never live inside an installed plugin because the plugin directory may be replaced during an update. This separation protects user data from being overwritten during skill upgrades.

Project Marker Contract and Resolution Logic

When a project contains a .diagram-design file, the skill follows a strict validation protocol before loading any profile.

Marker File Format and Validation Rules

The skill reads the marker file as untrusted data and expects exactly one line matching the pattern profile: <slug>. Whitespace is allowed, and a final newline is optional. The extracted <slug> must validate against the regex [a-z0-9][a-z0-9-]{0,63}.

If validation succeeds, the skill directly reads the corresponding profile file from the library (~/.diagram-design/profiles/<slug>.md) and uses it as the effective style guide. No copy-over to the installed working copy occurs.

Fallback Behavior for Invalid Markers

If the marker is missing, malformed, or contains an invalid slug, the skill ignores the marker with a one-line explanation and falls back to marker-less resolution. This prevents path traversal attacks and ensures deterministic behavior even with corrupted project metadata.

# Example: Creating a valid project marker

echo "profile: acme" > .diagram-design

Profile File Format and Metadata Schema

Each profile file is a standard style-guide.md with a single leading metadata comment that follows a strict strip-then-prepend rule.

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

# Style Guide

…

The Strip-then-Prepend Rule

Before any save or update operation, the skill strips any existing metadata header, then prepends a freshly rendered header containing current timestamps. The body content after the header is copied byte-for-byte; the skill never rewrites token values inside the style guide tables.

Date Formats and Optional Fields

The contract requires dates to use YYYY-MM-DD format. Missing optional fields must be explicitly expressed as none rather than being omitted. This schema consistency ensures that parsing remains deterministic across different versions of the skill.

Default Profile Recovery and Initialization

The built-in default profile serves as a recovery copy of the pristine references/style-guide.md shipped with the package.

Default.md Initialization from Pristine Source

On first-run (or when default.md is absent), the skill performs the following recovery procedure:

1. Reads the pristine shipped file from the installation directory.
2. Creates the profile library directory (mkdir -p ~/.diagram-design/profiles).
3. Writes default.md with a freshly rendered header where slug: default.

Subsequent reset commands simply load this default.md profile. No snapshot of a customized style guide may ever become default, ensuring a clean recovery path.

Corruption Handling and Reset Behavior

If the shipped pristine copy cannot be read (e.g., the install is corrupted), the skill reports that the default snapshot could not be created and disables the reset verb until a clean package is available. This prevents the propagation of corrupted baseline data.

# Example: Resetting to the built-in default

diagram-design profile reset

# The skill ensures ~/.diagram-design/profiles/default.md exists,

# then loads it either via the marker or by copying over the working copy

Structural Validation and Schema Back-filling

Before every generation, the skill runs a current-schema structural check (implemented around lines 96-105 in the contract logic). This validation:

• Ensures required rows exist in the ### Semantic roles table and the ## Typography table.

• Back-fills missing rows from the current pristine defaults, leaving existing values untouched.

• Offers an update <slug> command to persist the repaired snapshot to the profile library.

This mechanism ensures that legacy profiles remain compatible with new skill versions without overwriting user customizations.

CLI Verb Procedures and Contract Compliance

All public verbs defined in the contract obey the storage-marker-recovery rules:

• save <slug>: Strips existing headers, prepends fresh metadata, and writes to ~/.diagram-design/profiles/<slug>.md. Optionally updates the working copy header.
• load <slug> (or switch <slug>): Writes the chosen profile over the working copy only when no marker exists; otherwise updates the project marker file.
• reset: Defined as "load default", following the same marker-aware flow to restore the pristine baseline.
• delete <slug>: Never removes the library directory, only the requested file, after confirming the slug is not default (which is protected).

# Example: Saving the current style guide as a new profile

diagram-design profile save acme

# The skill strips headers, prepends fresh metadata with today's date,

# and writes to ~/.diagram-design/profiles/acme.md

Summary

• The profiles.md contract hard-codes paths to ~/.diagram-design/profiles/ for persistent storage and <project-root>/.diagram-design for project markers.
• Profile files use a metadata header format with mandatory YYYY-MM-DD dates and a strip-then-prepend update rule.
• The project marker binds directories to profiles via a profile: <slug> line validated against [a-z0-9][a-z0-9-]{0,63}.
• Recovery relies on a pristine default.md generated from the shipped style-guide.md, with safeguards against installation corruption.
• Structural checks (lines 96-105) back-fill missing schema rows without overwriting existing values.

Frequently Asked Questions

What happens if the .diagram-design marker file contains an invalid slug?

The skill validates the slug against the regex [a-z0-9][a-z0-9-]{0,63}. If validation fails, the skill ignores the entire marker, outputs a one-line explanation indicating "invalid slug", and falls back to marker-less resolution. This security measure prevents path traversal and ensures the skill never attempts to load files outside the profile library.

How does the skill protect user profiles during plugin updates?

According to the contract, profiles must never reside inside the installed plugin directory. The skill stores all user data in ~/.diagram-design/profiles/, which is external to <install-dir>. Because these paths are hard-coded and never altered by updates, replacing the plugin directory during an upgrade leaves user profiles untouched.

What is the difference between the working copy and the profile library?

The working copy at <install-dir>/references/style-guide.md acts as a scratch pad that the skill reads and writes when no project marker is present. The profile library at ~/.diagram-design/profiles/ contains the canonical named profiles (<slug>.md). When a valid project marker exists, the skill bypasses the working copy entirely and reads style guide data directly from the library file specified by the marker.

How does the skill handle a corrupted installation when creating the default profile?

If the skill cannot read the pristine shipped style-guide.md during initialization, it reports that the default snapshot could not be created and disables the reset command. This prevents the generation of a corrupted default.md file. The skill will continue to operate with existing user profiles, but recovery to the built-in default remains unavailable until a clean package installation restores the pristine reference file.

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