devstudio

Plugin Dev Studio Workflow

Comprehensive development environment for building, testing, and validating Claude Code plugins with hot-reload support.

When to Use This Skill

Activate this skill when:

• Developing a new plugin and need rapid iteration with live validation
• Debugging plugin manifest or resource file issues
• Visualizing plugin dependency graphs for architecture review
• Building regression test suites for plugin commands
• Preparing a plugin for publication to a registry

Architecture Overview

The Dev Studio consists of four core subsystems:

+------------------+     +---------------+     +-------------------+
|   FileWatcher    | --> |  HotReloader  | --> | Resource Registry |
| (FNV-1a hashing) |     | (Validation)  |     | (Live state)      |
+------------------+     +---------------+     +-------------------+
                                |
                                v
                     +--------------------+
                     | Console Reporter   |
                     | (file:line errors) |
                     +--------------------+

+-------------------+     +---------------------------+
| PluginPlayground  |     | DependencyGraphRenderer   |
| (Record/Replay)   |     | (ASCII + Mermaid output)  |
+-------------------+     +---------------------------+

FileWatcher

Monitors a plugin directory for file changes using filesystem watchers with content-hash-based change detection.

Key design decisions:

• Uses FNV-1a (32-bit) hashing for speed — non-cryptographic, but extremely fast for small files
• Only triggers reload when file content actually changed (ignores timestamp-only updates)
• Debounces rapid changes with a 100ms window to batch editor save operations
• Classifies files by resource type (command, skill, agent, config, source)

HotReloader

Processes file changes and maintains a live resource registry.

On each change:

1. If manifest changed: re-read, re-validate JSON structure and required fields
2. If markdown resource changed: re-lint frontmatter (YAML validity, required fields)
3. Update resource registry: add new resources, update modified ones, remove deleted ones
4. Report validation results with file:line references for inline error display

PluginPlayground

Isolated execution context for testing plugin commands.

Record-replay workflow:

1. Register mock capabilities for external dependencies
2. Execute commands and record full input/output pairs as fixtures
3. Save fixtures to tests/fixtures/ as JSON
4. Replay fixtures in CI to detect regressions

DependencyGraphRenderer

Builds and renders plugin dependency graphs.

Two output formats:

• ASCII tree: Uses Unicode box-drawing characters for terminal display
• Mermaid diagram: Pasteable into GitHub markdown, Notion, or Mermaid Live Editor

Development Workflow

Phase 1: Scaffold and Configure

# Create plugin structure
mkdir -p my-plugin/{commands,skills,agents,config,src,tests/fixtures}
mkdir -p my-plugin/.claude-plugin

# Create minimal manifest
cat > my-plugin/.claude-plugin/plugin.json << 'EOF'
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "My new plugin",
  "contextEntry": "CONTEXT.md",
  "capabilities": {
    "provides": ["my-capability"],
    "requires": []
  }
}
EOF

# Create required operator runbook
cat > my-plugin/CLAUDE.md << 'EOF'
# My Plugin Guide

## Purpose
- Brief description of plugin intent.

## Supported Commands
- command-name (commands/command-name.md)

## Prohibited Actions
- List destructive or out-of-scope operations.

## Required Validation Checks
- npm run check:plugin-context
- npm run check:plugin-schema

## Context Budget
1. CONTEXT_SUMMARY.md
2. commands/index (or commands/)
3. README.md and only task-relevant deep docs

## Escalation Path
- Describe who reviews risky or blocking changes.
EOF

# Create operator context entrypoint (keep concise)
cat > my-plugin/CONTEXT.md << 'EOF'
# my-plugin Context

## Purpose
One-paragraph operator summary.

## Key Commands
- /my:command

## Agent Inventory
- my-agent

## Load Deeper Docs When
- You need implementation details or architecture rationale.
EOF

Phase 2: Develop with Hot-Reload

# Start the dev server with file watching
/mp:dev serve ./my-plugin --watch

The dev server will:

• Validate the manifest on startup
• Discover and register all commands, skills, and agents
• Watch for file changes and re-validate on save
• Show inline errors with file:line references

Phase 3: Test in Playground

# Launch interactive playground
/mp:dev playground ./my-plugin

# In the playground:
# > run /my:command "test input"
# > save my-test-case
# > log

Phase 4: Visualize Dependencies

# Show dependency graph
/mp:dev graph ./my-plugin

Review the ASCII tree to verify:

• All capability declarations are correct
• Inter-resource dependencies are properly linked
• No circular dependencies exist

Phase 5: Validate Before Publish

# Full validation suite
/mp:dev validate ./my-plugin

Fix all errors before publishing. Warnings are advisory but should be addressed.

Phase 6: Regression Testing

# List saved fixtures
/mp:dev fixture list

# Replay a specific fixture
/mp:dev fixture replay my-test-case

Validation Rules

Manifest Validation (plugin.json)

Rule	Severity	Description
Valid JSON	error	File must be parseable JSON
name field	error	Must be a non-empty string
version field	error	Must be a non-empty string
description field	error	Must be a non-empty string
contextEntry field	error	Must reference CONTEXT.md or PLUGIN_CONTEXT.md
CLAUDE.md present	error	Plugin root must include CLAUDE.md runbook
capabilities present	warning	Plugin should declare capabilities
capabilities.provides is array	error	Must be an array of strings
capabilities.requires is array	error	Must be an array of strings

Command/Skill Validation (.md files)

Rule	Severity	Description
Has frontmatter	error	Must start with ---
Frontmatter closed	error	Must have closing ---
name in frontmatter	error	Commands and skills must have a name
description in frontmatter	warning	Should have a description
Top-level heading	info	Should have # Title after frontmatter

File Structure

plugin-root/
  .claude-plugin/
    plugin.json          # Plugin manifest (validated by HotReloader)
  CLAUDE.md              # Required operator runbook and context budget
  CONTEXT.md             # Minimal operator context entrypoint
  commands/
    *.md                 # Slash commands (validated for frontmatter)
  skills/
    */SKILL.md           # Skills (validated for frontmatter)
  agents/
    *.md                 # Agents (validated for frontmatter)
  config/
    *.json               # Configuration files
  src/
    devstudio/
      types.ts           # Type definitions
      server.ts          # FileWatcher, HotReloader, Playground, GraphRenderer
  tests/
    fixtures/
      *.json             # Recorded test fixtures (from playground)

Troubleshooting

Common Issues

"Plugin manifest not found"

• Ensure .claude-plugin/plugin.json exists in the plugin root
• Check that the path passed to /mp:dev is correct

"Missing YAML frontmatter"

• Markdown resource files must start with --- on the first line
• Frontmatter must be closed with a second --- line

"Content hash unchanged but file was modified"

• The FileWatcher uses content hashing, not timestamps
• If only whitespace changed, verify the hash actually differs
• The FNV-1a hash has a very low (but non-zero) collision rate for small changes

"Fixture replay fails with empty output"

• Playground execution is a simulation; real command execution requires the Claude runtime
• Record the actual output using recordOutput() after command execution

Source Files

• Types: src/devstudio/types.ts
• Implementation: src/devstudio/server.ts
• Command: commands/dev.md
• This skill: skills/devstudio/SKILL.md

---

Skill version: 1.0 Module: dev-studio (marketplace-pro plugin)