/dr-plugin

Overview

/dr-plugin is the Datarim plugin-system CLI introduced in v1.23.0 (TUNE-0101). It manages an opt-in set of skills, agents, commands, and templates beyond the built-in datarim-core shipping set. Plugins are opt-in by design: nothing is loaded unless the operator explicitly enables it, keeping the AI context lean and the dependency graph deterministic.

Plugins are local directories (or git URLs in a future phase) shaped as {plugin-id}/{plugin.yaml, skills/, agents/, commands/, templates/}. The CLI symlinks discovered files into ~/.claude/{category}/{plugin-id}/ namespaces, with optional root-position installation via the overrides: field. The active set lives in datarim/enabled-plugins.md — the single source of truth.

Usage

# Show active + bootstrap on first run
/dr-plugin list

# Enable a local plugin source (absolute path)
/dr-plugin enable /path/to/my-plugin

# Disable an active plugin (removes symlinks + manifest entry)
/dr-plugin disable my-plugin

# Reconcile runtime ↔ manifest (idempotent)
/dr-plugin sync

# Run 9 health checks; --fix auto-repairs sync-fixable issues
/dr-plugin doctor
/dr-plugin doctor --fix

Plugin Source Contract

A plugin source directory must contain plugin.yaml with at minimum:

schema_version: 1
id: my-plugin                # kebab-case, [a-z][a-z0-9-]{0,31}
title: My Plugin
version: 0.1.0
author: ...
license: MIT
description: ...
categories:
  - skills
  - commands
overrides:                   # optional — root-position install
  - my-shadow-skill.md
depends_on:                  # optional — other plugin ids
  - some-other-plugin

Doctor Health Checks (9)

1. manifest-syntax — required scalar fields, valid IDs (error)
2. inventory-consistency — declared symlinks present (error, --fix → sync)
3. broken-symlinks — declared symlink target missing (error, --fix → sync)
4. orphan-files — runtime files not in any inventory (warning, --fix → sync)
5. override-integrity — overrides must be in plugin's file_inventory (error, --fix → sync)
6. dependency-graph — cycle/dangling detection via DFS (error)
7. git-state — uncommitted manifest in git workspace (warning)
8. snapshot-cleanup — snapshots older than 30 days (warning, --fix → purge)
9. skill-registry — skill frontmatter name: matches basename (warning) — closes the Skill-tool resolution gap when frontmatter is malformed

Exit Codes

• 0 — clean
• 1 — warnings only
• 2 — errors found
• 3 — concurrent invocation (lock held by another process)
• 64 — usage error

Safety

Every enable takes a tarball snapshot of runtime/ + manifest.md before applying any change. On mid-apply failure, restore_from_snapshot reverts atomically. FIFO cap DR_PLUGIN_SNAPSHOT_MAX=50; age-based purge after DR_PLUGIN_SNAPSHOT_AGE_DAYS=30. Path traversal, embedded credentials in URLs, and CRLF in YAML are rejected at the validation gate. Critical-core overrides (evolution, datarim-system, pre-archive-check) emit a warning to stderr but allow — the operator decides.

When to Use Plugins vs local/ Overlay

• Personal additions for a single workstation → ~/.claude/local/{skills,agents,commands,templates}/ (gitignored overlay; loader policy: local wins on name conflict).
• Shareable extensions versioned as a unit, distributed as a directory or repo → /dr-plugin enable.