How a Multi-Client Workflow Supports Different Brands for Parallel Workspaces in Diagram Design

A hidden marker file (.diagram-design) lets each project reference an external brand profile, so many workspaces share one installation while each uses its own visual tokens.

Diagram Design implements a profile-based isolation system that separates brand identity from the core skill installation. This architecture enables agencies and freelancers to manage multiple client brands inside parallel project folders without conflicts. The mechanism centers on two components: profiles stored in the user's home directory and project markers that dynamically resolve which profile to load.

How Brand Profiles Work

A profile is a standalone Markdown file containing a complete brand token table plus metadata. Profiles live in ~/.diagram-design/profiles/<slug>.md, outside the installed skill directory. This location ensures that:

• Profile data survives skill updates
• Multiple workspaces reference the same profile without duplication
• No client tokens leak into the default style-guide.md

Profile Structure

Each profile contains the same token categories as [skills/diagram-design/references/style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md): paper (backgrounds), ink (text), accent (highlights), and font stacks. A small YAML header tracks the profile slug and creation date.

The Five-Step Multi-Client Workflow

The workflow defined in [skills/diagram-design/references/profiles.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) connects brand extraction to project-specific rendering:

1. Onboard the Brand

The skill fetches a client website, extracts color palettes and typography, and writes tokens to references/style-guide.md. This process is documented in [skills/diagram-design/references/onboarding.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md).

# Extract brand from website

onboard diagram-design to https://acme.com

2. Save as Named Profile

The save <slug> command copies the current style guide into ~/.diagram-design/profiles/<slug>.md, preserving the token table and adding metadata headers.

# Save current brand under a client slug

/diagram-design:profile save acme

3. Create Project Marker

A hidden file .diagram-design in the project root contains one line: profile: <slug>. The skill reads this marker before every generation to determine which profile to load.

# Add marker inside client project folder

echo "profile: acme" > .diagram-design

4. Generate Client-Branded Diagrams

On each request, the skill resolves the profile from the marker, merges any missing rows from shipped defaults (schema back-filling), and renders with client-specific colors and fonts. The installed style-guide.md remains untouched.

# Diagram automatically uses Acme brand

Make me an architecture diagram of my app

5. Switch or Update Brands

• load <slug> — replaces the marker (or overwrites local style-guide.md if no marker exists)
• update <slug> — rewrites an existing profile with latest tokens

# Switch to different client in same workspace

/diagram-design:profile load beta-corp

# Update profile after style guide tweaks

/diagram-design:profile update acme

How Parallel Workspaces Coexist

The marker-plus-profile design enables true workspace parallelism:

Workspace	Marker Content	Profile Loaded
/projects/acme-web/	profile: acme	~/.diagram-design/profiles/acme.md
/projects/beta-corp-api/	profile: beta-corp	~/.diagram-design/profiles/beta-corp.md
/projects/internal-tool/	(none)	skills/diagram-design/references/style-guide.md (default)

Both client projects share the same skill installation at skills/diagram-design/ but render with completely independent visual identities. Because markers are plain-text files, they travel with the project repository—clone the repo on any machine with Diagram Design installed, and the correct brand loads automatically.

Resolution and Validation Guarantees

The resolution logic in [profiles.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) provides three safety mechanisms:

• Fallback behavior — Missing or malformed markers are ignored; generation continues with default tokens
• Schema validation — Profiles are checked against the skill's current schema on every generation; new token rows added in later releases are back-filled automatically
• Installation integrity — The shipped style-guide.md is only modified when load runs without a marker present

Command Reference for Multi-Client Management

All commands route through [skills/diagram-design/commands/profile.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/commands/profile.md):

# List all saved profiles

/diagram-design:profile list

# Save current style guide as new profile

/diagram-design:profile save <slug>

# Load profile into current project (creates or updates marker)

/diagram-design:profile load <slug>

# Update existing profile from current style guide

/diagram-design:profile update <slug>

# Remove a profile

/diagram-design:profile remove <slug>

These slash-commands function across all supported host agents (Claude Code, Codex, Factory Droid, Pi, etc.).

Key Files in the Multi-Client Architecture

File	Purpose
[skills/diagram-design/references/profiles.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md)	Profile library format, marker resolution, verb definitions
[skills/diagram-design/references/onboarding.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md)	URL-to-tokens extraction flow
[skills/diagram-design/references/style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md)	Default token table and schema reference
[skills/diagram-design/SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)	Agent entry point for command routing
[skills/diagram-design/commands/profile.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/commands/profile.md)	Concrete /profile command implementation

Summary

• Profiles isolate brand tokens in ~/.diagram-design/profiles/<slug>.md, outside the skill installation
• Project markers (.diagram-design files) resolve which profile to load for each workspace
• Parallel workspaces share one Diagram Design installation while each renders with distinct client branding
• Schema validation ensures profiles stay compatible as the skill evolves
• Fallback logic protects against missing markers by defaulting to shipped tokens

Frequently Asked Questions

What happens if a project has no .diagram-design marker?

The skill ignores the missing file and falls back to the installed style-guide.md at skills/diagram-design/references/style-guide.md. Generation proceeds with default tokens.

Can multiple projects use the same profile simultaneously?

Yes. Profiles are read-only during generation. Any number of project markers can point to profile: acme, and all will render with identical branding.

How do I move a branded project to another machine?

Copy the project folder including the hidden .diagram-design marker. On the new machine, ensure the same profile slug exists in ~/.diagram-design/profiles/. If absent, re-run onboard and save to recreate it.

Will updating the Diagram Design skill affect my saved profiles?

No. Profiles live in your home directory, completely outside skills/diagram-design/. Skill updates only modify the installation directory. However, newer skill versions may introduce new token categories—these are automatically back-filled into existing profiles during the next generation.

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