Plugins Manager - Branch of JARVIS-02

Build and improve plugins following the plugins-management policy.

Policy Source

Primary policy: JARVIS-02 → .claude/skills/plugins-management/SKILL.md

This branch executes the policy defined by JARVIS-02. Always sync with Primary before major operations.

Quick Decision Tree

Task Received
    │
    ├── Create new plugin? ─────────────> Which type?
    │   ├── Task routing ────────────────> Use shared Orchestrator
    │   ├── Self-improvement ────────────> Use shared plugin-dev
    │   ├── Data access ─────────────────> Create BigQuery-[cat] from template
    │   └── Domain logic ────────────────> Create Category-[cat] custom
    │
    ├── Adapt marketplace plugin? ───────> Workflow 3: Adapt
    │
    ├── Fix existing plugin? ────────────> Workflow 2: Improve
    │
    └── Validate plugin? ────────────────> Validation Checklist

Plugin Overview

Claude Code plugins follow a standardized directory structure with automatic component discovery.

Key concepts:

• Conventional directory layout for automatic discovery
• Manifest-driven configuration in .claude-plugin/plugin.json
• Component-based organization (commands, agents, skills, hooks)
• Portable path references using ${CLAUDE_PLUGIN_ROOT}

Directory Structure

Every Claude Code plugin follows this organizational pattern:

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin manifest
├── commands/                 # Slash commands (.md files)
├── agents/                   # Subagent definitions (.md files)
├── skills/                   # Agent skills (subdirectories)
│   └── skill-name/
│       └── SKILL.md         # Required for each skill
├── hooks/
│   ├── hooks.json           # Event handler configuration
│   └── scripts/             # Hook scripts
├── .mcp.json                # MCP server definitions
└── scripts/                 # Helper scripts and utilities

Critical rules:

1. Manifest location: The plugin.json MUST be in .claude-plugin/ directory
2. Component locations: All component directories MUST be at plugin root level, NOT nested inside .claude-plugin/
3. Optional components: Only create directories for components the plugin actually uses
4. Naming convention: Use kebab-case for all directory and file names

The 4-Plugin Architecture

Every JARVIS category has exactly 4 plugins:

Plugin Manifest (plugin.json)

Located at .claude-plugin/plugin.json:

Required Fields

{
  "name": "plugin-name"
}

Name requirements:

• Use kebab-case format (lowercase with hyphens)
• Must be unique across installed plugins
• No spaces or special characters

Recommended Fields

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief explanation of plugin purpose",
  "author": {
    "name": "Author Name",
    "email": "author@example.com"
  },
  "repository": "https://github.com/user/plugin-name",
  "license": "MIT",
  "keywords": ["jarvis", "category-name"]
}

Component Path Configuration

Specify custom paths for components:

{
  "name": "plugin-name",
  "commands": "./custom-commands",
  "agents": ["./agents", "./specialized-agents"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./.mcp.json"
}

Path rules:

• Must be relative to plugin root
• Must start with ./
• Cannot use absolute paths
• Custom paths supplement defaults (don't replace)

Portable Path References

${CLAUDE_PLUGIN_ROOT}

Use ${CLAUDE_PLUGIN_ROOT} for all intra-plugin path references:

{
  "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"
}

Where to use it:

• Hook command paths
• MCP server command arguments
• Script execution references
• Resource file paths

Never use:

• Hardcoded absolute paths (/Users/name/plugins/...)
• Relative paths from working directory (./scripts/... in commands)
• Home directory shortcuts (~/plugins/...)

In hook scripts:

#!/bin/bash
# ${CLAUDE_PLUGIN_ROOT} available as environment variable
source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"

Component Organization

Commands

Location: commands/ directory Format: Markdown files with YAML frontmatter Auto-discovery: All .md files in commands/ load automatically

commands/
├── review.md        # /review command
├── test.md          # /test command
└── deploy.md        # /deploy command

Agents

Location: agents/ directory Format: Markdown files with YAML frontmatter Auto-discovery: All .md files in agents/ load automatically

agents/
├── code-reviewer.md
├── test-generator.md
└── refactorer.md

Skills

Location: skills/ directory with subdirectories per skill Format: Each skill in own directory with SKILL.md file Auto-discovery: All SKILL.md files in skill subdirectories load automatically

skills/
├── api-testing/
│   ├── SKILL.md
│   └── references/
└── database-migrations/
    ├── SKILL.md
    └── examples/

Hooks

Location: hooks/hooks.json or inline in plugin.json Format: JSON configuration defining event handlers

hooks/
├── hooks.json           # Hook configuration
└── scripts/
    └── validate.sh      # Hook script

Configuration format:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh",
        "timeout": 30
      }]
    }]
  }
}

MCP Servers

Location: .mcp.json at plugin root Format: JSON configuration for MCP server definitions

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Auto-Discovery Mechanism

Claude Code automatically discovers and loads components:

1. Plugin manifest: Reads .claude-plugin/plugin.json when plugin enables
2. Commands: Scans commands/ directory for .md files
3. Agents: Scans agents/ directory for .md files
4. Skills: Scans skills/ for subdirectories containing SKILL.md
5. Hooks: Loads configuration from hooks/hooks.json or manifest
6. MCP servers: Loads configuration from .mcp.json or manifest

Discovery timing:

• Plugin installation: Components register with Claude Code
• Plugin enable: Components become available for use
• No restart required for file changes (except hooks)

File Naming Conventions

Component Files

Commands: Use kebab-case .md files

• code-review.md → /code-review
• run-tests.md → /run-tests

Agents: Use kebab-case .md files

• test-generator.md
• code-reviewer.md

Skills: Use kebab-case directory names

• api-testing/
• database-migrations/

Supporting Files

Scripts: Use descriptive kebab-case names

• validate-input.sh
• generate-report.py

Configuration: Use standard names

• hooks.json
• .mcp.json
• plugin.json

Plugin Settings Pattern

Plugins can store user-configurable settings in .claude/plugin-name.local.md:

Settings File Structure

---
enabled: true
setting1: value1
setting2: value2
---

# Additional Context

This markdown body can contain:
- Task descriptions
- Additional instructions
- Prompts to feed back to Claude

Reading Settings in Hooks

#!/bin/bash
STATE_FILE=".claude/my-plugin.local.md"

# Quick exit if file doesn't exist
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0  # Plugin not configured
fi

# Parse YAML frontmatter
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")

# Extract field
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')

if [[ "$ENABLED" != "true" ]]; then
  exit 0  # Disabled
fi

Settings Best Practices

• Use .claude/plugin-name.local.md format
• Add .claude/*.local.md to .gitignore
• Provide sensible defaults when settings file doesn't exist
• Document that changes require Claude Code restart (for hooks)

Workflow 1: Create New Plugin

For Shared Plugins (Orchestrator, plugin-dev)

Do NOT create new ones. Copy from source repository:

# Copy shared plugin
cp -r /path/to/shared/plugin-orchestrator ./plugins/orchestrator
cp -r /path/to/shared/plugin-dev ./plugins/dev

For BigQuery Plugin (Template)

1. Copy template structure

mkdir -p plugins/bigquery-[category]/.claude-plugin
mkdir -p plugins/bigquery-[category]/{agents,skills/bigquery-[category]}

2. Create plugin.json

{
  "name": "plugin-bigquery-[category]",
  "version": "1.0.0",
  "description": "BigQuery data access for JARVIS-XX [Category]"
}

3. Create BigQuery skill with HARDCODED tables

---
name: bigquery-[category]
description: "This skill provides BigQuery access for [Category]. Use when querying data, writing analytics, or accessing tables. Triggers: 'query', 'write data', 'analytics', 'BigQuery'."
---

# BigQuery - [Category]

## Allowed Tables (HARDCODED)

| Table | Access | Purpose |
|-------|--------|---------|
| jarvis_XX_table1 | READ/WRITE | [Purpose] |
| jarvis_XX_table2 | READ | [Purpose] |

## Query Patterns
[Standard patterns for this category]

For Category Plugin (Custom)

1. Create structure

mkdir -p plugins/category-[name]/.claude-plugin
mkdir -p plugins/category-[name]/{agents,skills/[domain],commands,hooks/scripts}

2. Create plugin.json

{
  "name": "plugin-category-[name]",
  "version": "1.0.0",
  "description": "Domain-specific plugin for [Category] operations"
}

3. Add components using appropriate manager skills
   • Agents → agents-manager
   • Skills → skills-manager
   • Commands → commands-manager
   • Hooks → hooks-manager

Workflow 2: Improve Existing Plugin

Step 1: Analyze Current State

# Plugin audit
cat plugins/[name]/.claude-plugin/plugin.json
ls -la plugins/[name]/agents/
ls -la plugins/[name]/skills/
ls -la plugins/[name]/commands/
ls -la plugins/[name]/hooks/

Step 2: Gap Analysis

Step 3: Apply Fixes

Use the appropriate manager skill:

• Agent issues → agents-manager
• Skill issues → skills-manager
• Command issues → commands-manager
• Hook issues → hooks-manager

Step 4: Validate

Run full validation checklist.

Workflow 3: Adapt Marketplace Plugin

When taking a plugin from wshobson-agents, obra-superpowers, or other sources:

Step 1: Analyze Source Plugin

ls -la source-plugin/
cat source-plugin/.claude-plugin/plugin.json
ls source-plugin/agents/
ls source-plugin/skills/

Step 2: Determine Target Plugin Type

Step 3: Adapt Components

For each component:

1. Read original file
2. Adapt for JARVIS (add triggers, context)
3. Use appropriate manager skill
4. Save to target plugin

Step 4: Update plugin.json

{
  "name": "plugin-category-[name]",
  "version": "1.0.0",
  "description": "Adapted from [source] - [purpose] for JARVIS-XX",
  "source": "[original repository]"
}

Step 5: Validate Adaptation

Run full validation checklist.

Validation Checklist

Structure

• .claude-plugin/plugin.json exists (not at root)
• plugin.json has name field
• Name is kebab-case, 3-50 characters
• Component directories at plugin root (not in .claude-plugin/)
• All paths use ${CLAUDE_PLUGIN_ROOT} for portability

Agents (if any)

• Files in agents/ with .md extension
• Each has valid YAML frontmatter
• Each has name, description, model, color
• Description has 2+ <example> blocks

Skills (if any)

• Each skill in own subdirectory under skills/
• Each has SKILL.md with valid frontmatter
• Each has "Triggers:" in description
• Content under 2000 words

Commands (if any)

• Files in commands/ with .md extension
• Each has description in frontmatter
• Written as instructions FOR Claude
• Uses imperative form

Hooks (if any)

• hooks/hooks.json is valid JSON
• Uses {"hooks": {...}} wrapper format
• Scripts in hooks/scripts/ are executable
• Each hook has timeout specified
• Uses ${CLAUDE_PLUGIN_ROOT} for script paths

Type-Specific

• If shared plugin: identical to source
• If BigQuery: only table list differs from template
• If Category: domain-specific only, no generic content

Plugin Templates

Minimal Plugin

plugin-name/
├── .claude-plugin/
│   └── plugin.json     <- {"name": "plugin-name"}
└── skills/
    └── [skill]/
        └── SKILL.md

Full Plugin

plugin-name/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   └── agent.md
├── skills/
│   └── domain/
│       ├── SKILL.md
│       └── references/
├── commands/
│   └── command.md
├── hooks/
│   ├── hooks.json
│   └── scripts/
│       └── validate.sh
├── .mcp.json
└── scripts/
    └── utility.sh

Common Issues & Fixes

Troubleshooting

Component not loading:

• Verify file is in correct directory
• Check YAML frontmatter syntax
• Ensure skill has SKILL.md (not README.md)
• Confirm plugin is enabled

Path resolution errors:

• Replace hardcoded paths with ${CLAUDE_PLUGIN_ROOT}
• Verify paths start with ./ in manifest
• Test with echo $CLAUDE_PLUGIN_ROOT in hook scripts

Auto-discovery not working:

• Confirm directories are at plugin root
• Check file naming (kebab-case, correct extensions)
• Restart Claude Code

When to Use This Skill

• User asks to create a new plugin
• User asks to validate plugin structure
• User asks to adapt a marketplace plugin
• User asks to fix plugin issues
• User asks about plugin.json or CLAUDE_PLUGIN_ROOT
• Setting up 4-plugin architecture for new category
• DEV-Manager detects plugin problems during improvement cycle
• Regular improvement cycle (~6 sessions)

Sync Protocol

Before executing any workflow:

1. Read JARVIS-02's plugins-management SKILL.md
2. Check for policy updates
3. Apply current policy, not cached knowledge