name	plugin-architecture
description	Expertise in Claude Code plugin structure, semantic versioning, metadata management, and component synchronization. Activate when creating plugins, updating versions, or managing plugin metadata. Guides proper plugin.json configuration, VERSION synchronization, and CHANGELOG maintenance, ensuring plugins remain discoverable and maintain compatibility.

Plugin Architecture Skill

Expert knowledge of Claude Code plugin architecture, covering directory structure, plugin.json configuration, semantic versioning, component tracking, and metadata synchronization for the orchestr8 plugin system.

Documentation Output Locations

This skill generates outputs in the following .orchestr8/docs/ locations:

Plugin architecture documentation: .orchestr8/docs/architecture/design/

Output Naming Convention

All outputs follow the pattern: [type]-[name]-YYYY-MM-DD.md

Example outputs:

.orchestr8/docs/research/assumptions/validation-microservices-2025-01-15.md
.orchestr8/docs/research/poc/poc-event-sourcing-2025-01-15.md
.orchestr8/docs/patterns/library/pattern-factory-2025-01-15.md

When to Use This Skill

Use plugin-architecture for:

✅ Creating new Claude Code plugins from scratch
✅ Configuring plugin.json with proper metadata and discovery patterns
✅ Managing semantic versioning (MAJOR.MINOR.PATCH) across releases
✅ Synchronizing VERSION file with plugin.json and CHANGELOG.md
✅ Organizing plugin directory structure (agents/, commands/, skills/)
✅ Ensuring plugin discoverability and marketplace compatibility

Less critical for:

❌ Creating individual agents or workflows (use those specific skills)
❌ Plugin usage or installation (this is for plugin creation/maintenance)
❌ Non-plugin Claude Code projects

Plugin Directory Structure

Standard Plugin Layout

.claude/
├── VERSION                    # Primary version file (single line)
├── plugin.json                # Plugin metadata manifest
├── CLAUDE.md                  # System instructions for end users
├── CHANGELOG.md               # Release history
├── QUICKSTART.md              # Getting started guide
├── RELEASE.md                 # Release process documentation
├── agents/                    # Agent definitions
│   ├── development/
│   │   ├── languages/         # Python, TypeScript, Java, etc.
│   │   ├── frontend/          # React, Vue, Angular, etc.
│   │   ├── api/               # GraphQL, gRPC, OpenAPI
│   │   ├── ai-ml/             # LangChain, LlamaIndex
│   │   ├── blockchain/        # Solidity, Web3
│   │   ├── game-engines/      # Unity, Unreal, Godot
│   │   ├── mobile/
│   │   └── data/
│   ├── quality/
│   │   ├── testing/
│   │   └── debugging/
│   ├── infrastructure/
│   │   ├── databases/
│   │   ├── messaging/
│   │   ├── search/
│   │   ├── caching/
│   │   ├── monitoring/
│   │   ├── sre/
│   │   └── cloud/
│   ├── devops/
│   │   ├── cloud/
│   │   └── infrastructure/
│   ├── compliance/
│   ├── orchestration/
│   └── meta/                  # Meta-system agents
├── commands/                  # Workflow slash commands
│   ├── add-feature.md
│   ├── fix-bug.md
│   ├── deploy.md
│   └── [other-workflows].md
└── skills/                    # Auto-activated skills
    ├── practices/
    ├── patterns/
    ├── meta/
    └── [other-categories]/

plugin.json Structure

Complete Schema

{
  "name": "plugin-identifier",
  "version": "X.Y.Z",
  "description": "[Comprehensive plugin description]",
  "author": {
    "name": "Author Name",
    "url": "https://github.com/author"
  },
  "license": "MIT",
  "repository": "https://github.com/author/plugin",
  "homepage": "https://github.com/author/plugin",
  "keywords": [
    "keyword1",
    "keyword2"
  ],
  "commands": "commands/**/*.md",
  "agents": "agents/**/*.md"
}

Field Descriptions

Required Fields:

name - Plugin identifier (lowercase, no spaces, kebab-case)
version - Semantic version (MAJOR.MINOR.PATCH)
description - Comprehensive capability summary
commands - Glob pattern for workflow files (typically "commands/**/*.md")
agents - Glob pattern for agent files (typically "agents/**/*.md")

Recommended Fields:

author - Object with name and url
license - License type (e.g., "MIT")
repository - GitHub repository URL
homepage - Project homepage URL
keywords - Array of searchable keywords

Description Formula

"Complete [type] with [N] specialized agents, [M] autonomous workflows,
[key features]. Features [capabilities]. Transform Claude Code into [value]."

Example:

"Complete autonomous software engineering organization with 69 specialized agents,
19 autonomous workflows, enterprise compliance, game development, AI/ML,
blockchain/Web3 support, and meta-orchestration capabilities. Features multi-stage
iterative code review system and self-extending plugin architecture. Transform
Claude Code into a full development team that can create its own agents,
workflows, and skills."

Semantic Versioning

Version Format: MAJOR.MINOR.PATCH

1.4.0
│ │ │
│ │ └─ PATCH: Bug fixes, documentation, minor improvements
│ └─── MINOR: New features, agents, workflows, backward-compatible
└───── MAJOR: Breaking changes, incompatible API changes

When to Bump Versions

MAJOR (e.g., 1.x.x → 2.0.0):

Breaking changes to agent interfaces
Major workflow behavior changes requiring user adaptation
Incompatible API changes
Fundamental architecture redesign
Removal of core features

MINOR (e.g., 1.3.0 → 1.4.0):

✅ New agents added
✅ New workflows added
✅ New skills added
✅ New categories created
✅ Backward-compatible feature additions
✅ Significant enhancements

PATCH (e.g., 1.3.0 → 1.3.1):

Bug fixes in existing agents/workflows
Documentation improvements
Typo corrections
Minor agent improvements (no interface changes)
Performance optimizations (without API changes)

Version Synchronization

CRITICAL: Two files must ALWAYS have identical versions:

.claude/VERSION - Single line text file: 1.4.0
.claude/plugin.json - JSON field: "version": "1.4.0"

Validation:

# Check synchronization
VERSION_FILE=$(cat .claude/VERSION)
VERSION_JSON=$(grep '"version"' .claude/plugin.json | sed 's/.*: "\(.*\)".*/\1/')

if [ "$VERSION_FILE" != "$VERSION_JSON" ]; then
  echo "ERROR: VERSION mismatch!"
fi

Component Counting

Accurate Component Counts

Count Agents:

find .claude/agents -name "*.md" -type f | wc -l

Count Workflows:

find .claude/commands -name "*.md" | wc -l

Count Skills:

find .claude/skills -type d -mindepth 2 -maxdepth 2 | wc -l

Update Description with Counts

When counts change, update plugin.json description:

Before:

"description": "Complete autonomous software engineering organization with 65 specialized agents, 16 autonomous workflows..."

After adding 4 agents and 3 workflows:

"description": "Complete autonomous software engineering organization with 69 specialized agents, 19 autonomous workflows..."

Keyword Management

Keyword Categories

Core Concepts:

agents, orchestration, automation, multi-agent, workflows

Domains:

enterprise, devops, ci-cd, security, compliance, quality-assurance

Cloud Providers:

aws, azure, gcp, kubernetes, docker, terraform

Languages:

python, typescript, javascript, java, go, rust, kotlin, swift, csharp, php, ruby, cpp

Technologies:

react, nextjs, vue, angular, django, fastapi, spring-boot, graphql, grpc

Specializations:

game-development, unity, unreal, godot, ai, ml, langchain, llamaindex, blockchain, web3, solidity, ethereum

Capabilities:

code-review, pull-request, architecture-review, test-automation, performance-optimization, accessibility

When to Add Keywords

Adding agents for new technologies → Add technology keyword
Adding new categories → Add category keywords
Adding significant features → Add feature keywords
Expanding into new domains → Add domain keywords

Changelog Management

Changelog Structure

# Changelog

All notable changes to the [plugin-name] plugin will be documented in this file.

## [X.Y.Z] - YYYY-MM-DD

### 🎯 [Category Name]

**New [Type] (N items)**

- **Item Name** - Brief description
  - Key capability 1
  - Key capability 2
  - Technical details

### 📝 [Another Category]

[More changes...]

## [Previous Version] - YYYY-MM-DD

[Previous release notes...]

Changelog Entry Pattern

## [1.4.0] - 2025-01-15

### 🎯 Meta-Orchestration

**New Meta Agents (4 agents)**

- **agent-architect** - Expert in designing new Claude Code agents
  - Frontmatter design and validation
  - Tool selection strategy
  - Documentation structure
  - Category placement

- **workflow-architect** - Expert in designing autonomous workflows
  - Multi-phase execution design
  - Quality gate implementation
  - Agent coordination patterns

[... more items ...]

**New Meta Workflows (3 workflows)**

- **/create-agent** - Complete agent creation lifecycle
  - Requirements → Design → Implementation → Validation → Integration

[... more items ...]

**New Meta Skills (3 skills)**

- **agent-design-patterns** - Best practices for agent creation
- **workflow-orchestration-patterns** - Workflow design patterns
- **plugin-architecture** - Plugin structure and conventions

### 📊 Updated Capabilities

- **Total Agents**: 69 (up from 65)
- **Total Workflows**: 19 (up from 16)
- **Total Skills**: 4 (up from 1)

Version Update Workflow

Complete Update Checklist

When releasing a new version:

Update VERSION file
```
echo "1.4.0" > .claude/VERSION
```
Update plugin.json
- Update version field
- Update description with new counts
- Add new keywords if applicable

Count components

echo "Agents: $(find .claude/agents -name "*.md" -type f | wc -l)"
echo "Workflows: $(find .claude/commands -name "*.md" | wc -l)"
echo "Skills: $(find .claude/skills -type d -mindepth 2 -maxdepth 2 | wc -l)"

Update CHANGELOG.md
- Add new ## [X.Y.Z] - YYYY-MM-DD section at top
- Document all changes with categories
- Include detailed feature descriptions
Verify synchronization
- VERSION matches plugin.json version
- Component counts accurate in description
- JSON is valid

Create git commit

git add .claude/VERSION .claude/plugin.json .claude/CHANGELOG.md
git commit -m "release: vX.Y.Z - [Brief description]"

Create git tag

git tag -a vX.Y.Z -m "Release vX.Y.Z - [Description]"
git push origin vX.Y.Z

Best Practices

DO ✅

Version Management:

Always update VERSION and plugin.json together
Use semantic versioning correctly
Count components with find commands (don't guess)
Verify synchronization before committing
Create git tags for releases

Metadata:

Keep description accurate and up-to-date
Add keywords when expanding capabilities
Maintain valid JSON syntax
Update counts when adding components
Document all changes in CHANGELOG

File Organization:

Place agents in correct category directories
Use kebab-case for all filenames
Follow glob patterns (commands//*.md, agents//*.md)
Organize skills by category
Keep directory structure consistent

DON'T ❌